Documentation
¶
Overview ¶
Package topic parses and validates current-state topic inputs.
Index ¶
- func CreatedDocument(files []ScaffoldFile) (presentation.Document, error)
- func ParseMetadata(metadataRoot, path string, data []byte) (TopicID, Metadata, error)
- func ParseSelector(selector string) (topicID, claimID string, err error)
- func PathAuthority(c Corpus, path string) ([]string, []string)
- func RenderIndex(tid string, template []byte, model IndexRenderModel) (string, error)
- func RenderTopic(tid string, template []byte, model TopicRenderModel) (string, error)
- func StaticReferenceDetail() presentation.Detail
- type ADRHistory
- type Backing
- type Claim
- type ClaimHistory
- type ClaimReferences
- type ClaimType
- type Corpus
- func LoadAuthorityCorpusFromFiles(files []snapshot.File, cfg *config.Config, adrs adr.Corpus) (Corpus, error)
- func LoadCorpusFromReader(read TreeReader, cfg *config.Config, adrs adr.Corpus) (Corpus, error)
- func LoadCorpusFromTree(tree *snapshot.Tree, cfg *config.Config, adrs adr.Corpus) (Corpus, error)
- func (c Corpus) All() []Topic
- func (c Corpus) ByClaimID(id string) (Claim, bool)
- func (c Corpus) ByTopicID(id string) (Topic, bool)
- func (c Corpus) Clone() Corpus
- func (c Corpus) ForDomain(domain string) []Topic
- func (c Corpus) Incoming(id string) []string
- func (c Corpus) Outgoing(id string) []string
- type CoverageFinding
- type CoverageKind
- type CoveragePolicy
- type IndexRenderModel
- type MarkerIndex
- type MarkerKind
- type MarkerSite
- type Metadata
- type NavigationModel
- type PartialProvenanceError
- type ProvenanceResult
- type QueryClaim
- type QueryCoverage
- type QueryOptions
- type QueryResult
- type ScaffoldFile
- type Topic
- type TopicApplicability
- type TopicID
- type TopicListItem
- type TopicRenderModel
- type TreeReader
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreatedDocument ¶ added in v0.30.0
func CreatedDocument(files []ScaffoldFile) (presentation.Document, error)
CreatedDocument maps successfully created topic files into one path per line.
func ParseMetadata ¶
func ParseSelector ¶
func PathAuthority ¶ added in v0.43.0
topicMatchesPath answers repository-wide applicability. A global topic is authoritative everywhere, including outside the bounded paths it may own. PathAuthority returns deterministic owning domains and applicable topics for a lexical repository path. Global topics are applicable outside bounded domain ownership but do not create a domain owner.
func RenderIndex ¶
func RenderIndex(tid string, template []byte, model IndexRenderModel) (string, error)
RenderIndex renders one domain's topic index from caller-supplied template identity and content, on the same contract as RenderTopic.
func RenderTopic ¶
func RenderTopic(tid string, template []byte, model TopicRenderModel) (string, error)
RenderTopic renders one topic doc. Template identity and content are the caller's: the render pipeline already holds both (it hashes the same bytes into the drift signal), so this package never re-reads the embedded tree and template identity keeps its single derivation there.
func StaticReferenceDetail ¶ added in v0.30.0
func StaticReferenceDetail() presentation.Detail
StaticReferenceDetail maps the unadopted-project topic reference into the same presentation tree as ordinary topic output.
Types ¶
type ADRHistory ¶
type ClaimHistory ¶
type ClaimHistory struct {
ClaimID string `json:"claimId"`
Origin *ADRHistory `json:"origin,omitempty"`
LegacyBaseline bool `json:"legacyBaseline,omitempty"`
RevisedBy []ADRHistory `json:"revisedBy"`
RemovedBy *ADRHistory `json:"removedBy,omitempty"`
}
type ClaimReferences ¶
type Corpus ¶
type Corpus struct {
DomainPaths map[string][]string
Markers MarkerIndex
// contains filtered or unexported fields
}
func LoadAuthorityCorpusFromFiles ¶ added in v0.30.0
func LoadAuthorityCorpusFromFiles(files []snapshot.File, cfg *config.Config, adrs adr.Corpus) (Corpus, error)
LoadAuthorityCorpusFromFiles parses the reduced topic authority from the supplied snapshot files. Historical selections use this exact byte-fed core without materializing a complete Tree.
func LoadCorpusFromReader ¶ added in v0.40.0
LoadCorpusFromReader loads retained topic authority first, then streams each selected marker source through the scanner so aggregate source bytes never become part of one materialized snapshot.
func LoadCorpusFromTree ¶ added in v0.22.0
LoadCorpusFromTree parses the complete current-state topic corpus from an immutable snapshot. It retains domain ownership and marker validation for callers that need the complete repository projection.
type CoverageFinding ¶ added in v0.22.0
type CoverageFinding struct {
Path string `json:"path"`
Domain string `json:"domain,omitempty"`
Kind CoverageKind `json:"kind"`
CandidateTopics []string `json:"candidateTopics,omitempty"`
// The rank is not part of this struct's wire form. Stated rather than left
// implicit: an untagged exported field still marshals, as a bare 0 or 1.
Severity severity.Rank `json:"-"`
Topics int `json:"topics,omitempty"`
}
CoverageFinding is one deterministic coverage result. Domain names the owning domain of an Uncovered finding and is empty for a Fanout finding, which is emitted once per path across owners; Topics carries a Fanout finding's matching count. CandidateTopics names claim-bearing global topics in the uncovered domain whose ownership selector can be extended as one recovery.
func EvaluateCoverage ¶ added in v0.22.0
func EvaluateCoverage(c Corpus, paths []string, policy CoveragePolicy) []CoverageFinding
EvaluateCoverage returns the sorted coverage and fan-out findings for the eligible paths (ADR-0134 item 11). Every domain owning a path is evaluated independently: a domain with no claim-bearing topic owning the path yields one Uncovered finding at error, so a topic from one owner never satisfies another owner's gap. A global topic owns only its declared paths bounded by its parent domain. Across all owners the distinct owning topics matching a path are counted once; exceeding the budget yields a single Fanout finding at warn. The caller selects which checks run through the policy, and no value suppresses a requested check. Unowned paths are the context ownership concern and produce no finding here.
func (CoverageFinding) Message ¶ added in v0.34.0
func (c CoverageFinding) Message() string
Message renders the finding's semantic diagnostic. The model owner retains both the finding vocabulary and its actionable recovery mapping.
type CoverageKind ¶ added in v0.22.0
type CoverageKind string
CoverageKind distinguishes a missing topic-owner finding from a fan-out one.
const ( // Uncovered marks a domain-owned path with no claim-bearing topic owner. Uncovered CoverageKind = "uncovered" // Fanout marks a path owned by more topics than the budget. Fanout CoverageKind = "fanout" )
type CoveragePolicy ¶ added in v0.22.0
type CoveragePolicy struct {
Coverage, Fanout bool
}
CoveragePolicy carries which coverage checks a caller wants evaluated. A caller that does not want a finding class does not request it; no value suppresses a requested check (ADR-0183 items 2 and 8).
type IndexRenderModel ¶
type IndexRenderModel struct {
Domain string
Topics []TopicListItem
}
func BuildIndexModel ¶
func BuildIndexModel(domain string, topics []Topic) IndexRenderModel
type MarkerIndex ¶
type MarkerIndex struct {
// contains filtered or unexported fields
}
func (MarkerIndex) All ¶
func (m MarkerIndex) All() []MarkerSite
func (MarkerIndex) ForClaim ¶
func (m MarkerIndex) ForClaim(id string) []MarkerSite
type MarkerSite ¶
type MarkerSite struct {
Path string `json:"path"`
Line int `json:"line"`
Kind MarkerKind `json:"kind"`
ClaimID string `json:"claimId"`
Note string `json:"note,omitempty"`
}
type NavigationModel ¶
type NavigationModel struct {
}
func BuildNavigationModel ¶
func BuildNavigationModel(domain string, topics []Topic) NavigationModel
type PartialProvenanceError ¶ added in v0.41.0
type PartialProvenanceError struct {
Result ProvenanceResult
Cause error
}
PartialProvenanceError retains the exact committed part paths when a later provenance observation or replacement fails.
func (*PartialProvenanceError) Error ¶ added in v0.41.0
func (e *PartialProvenanceError) Error() string
func (*PartialProvenanceError) Unwrap ¶ added in v0.41.0
func (e *PartialProvenanceError) Unwrap() error
type ProvenanceResult ¶ added in v0.41.0
type ProvenanceResult struct {
Paths []string
}
ProvenanceResult identifies every authored topic part whose replacement committed, in walk order.
func SubstituteProvenanceConfined ¶ added in v0.41.0
func SubstituteProvenanceConfined(files *filesystem.Handle, renames map[string]string) (ProvenanceResult, error)
SubstituteProvenanceConfined rewrites authored claim parts through the caller-held selected-root handle. It touches only Origin and Revised-by values under .awf/topics/parts and canonicalizes touched lists. Numbering owns the transaction lease; topic retains metadata grammar and replacement policy.
type QueryClaim ¶
type QueryCoverage ¶
type QueryCoverage struct {
Applicability TopicApplicability `json:"applicability"`
}
type QueryOptions ¶
type QueryOptions struct {
History, References, Coverage bool
}
QueryOptions selects independent detail projections for a current-state query.
type QueryResult ¶
type QueryResult struct {
Kind string `json:"kind"`
ID string `json:"id"`
Title string `json:"title,omitempty"`
Summary string `json:"summary,omitempty"`
Claims []QueryClaim `json:"claims"`
History []ClaimHistory `json:"history,omitempty"`
References []ClaimReferences `json:"references,omitempty"`
Coverage *QueryCoverage `json:"coverage,omitempty"`
HistoricalOnly bool `json:"historicalOnly,omitempty"`
}
QueryResult is the single deterministic semantic model used by human and JSON presentation. Optional detail blocks are nil unless their corresponding flag was requested.
func Query ¶
func Query(c Corpus, adrs adr.Corpus, selector string, opts QueryOptions, currentPaths []string) (QueryResult, error)
Query resolves one active topic or claim and assembles only the requested direct detail. A qualified removed claim resolves only when History is set; it never traverses references or constructs tombstone state.
func (QueryResult) Detail ¶ added in v0.30.0
func (result QueryResult) Detail() presentation.Detail
Detail maps every selected topic query result field into the shared presentation tree. Topic owns this semantic mapping; presentation owns validation and text rendering.
type ScaffoldFile ¶
ScaffoldFile is one repository-relative authored input produced for a topic.
func ScaffoldFilesWithExists ¶ added in v0.41.0
func ScaffoldFilesWithExists(cfg *config.Config, domain, title string, exists func(string) (bool, error)) ([]ScaffoldFile, error)
ScaffoldFilesWithExists plans paired authored inputs using the caller's selected-root observation capability. Topic owns allocation and source shape; its operation owner chooses the confined observation mechanism.
type Topic ¶
type TopicApplicability ¶ added in v0.22.0
type TopicApplicability struct {
DeclaredGlobal bool `json:"declaredGlobal"`
DomainPaths []string `json:"domainPaths"`
TopicPaths []string `json:"topicPaths"`
ApplicablePaths []string `json:"applicablePaths"`
OwnedPaths []string `json:"ownedPaths"`
MarkerSites []MarkerSite `json:"markerSites"`
}
TopicApplicability preserves separate witnesses for repository-wide authority and domain-bounded path ownership. ApplicablePaths and OwnedPaths are from the caller's selected universe, not symbolic glob-intersection proofs.
func ApplicabilityForTopic ¶ added in v0.22.0
func ApplicabilityForTopic(t Topic, domainPaths []string, markers MarkerIndex, currentPaths []string) TopicApplicability
type TopicListItem ¶
type TopicListItem struct{ Slug, Title, Summary, Link string }
type TopicRenderModel ¶
type TopicRenderModel struct{ Title, Summary, Applicability, Part string }
func BuildTopicModel ¶
func BuildTopicModel(t Topic, domainPaths []string, markers MarkerIndex, currentPaths []string) TopicRenderModel