topic

package
v0.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 24, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package topic parses and validates current-state topic inputs.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ClaimBudgetNotes added in v0.22.0 

func ClaimBudgetNotes(c Corpus, maxClaimsPerTopic int) []string

ClaimBudgetNotes returns one deterministic advisory for each topic whose claim count is strictly above maxClaimsPerTopic.

func ParseMetadata 

func ParseMetadata(metadataRoot, path string, data []byte) (TopicID, Metadata, error)

func ParseSelector 

func ParseSelector(selector string) (topicID, claimID string, err error)

func RenderIndex 

func RenderIndex(model IndexRenderModel) (string, error)

func RenderTopic 

func RenderTopic(model TopicRenderModel) (string, error)

Types

type ADRHistory 

type ADRHistory struct {
	Number        string `json:"number"`
	Title         string `json:"title"`
	Status        string `json:"status"`
	StateSequence int    `json:"stateSequence,omitempty"`
}

type Backing 

type Backing string
const (
	NoBacking         Backing = ""
	ExplicitNoBacking Backing = "none"
	TestBacking       Backing = "test"
	Unbacked          Backing = "unbacked"
)

type Claim 

type Claim struct {
	ID, Slug              string
	Type                  ClaimType
	Prose                 string
	Origin                string
	RevisedBy, References []string
	Backing               Backing
	Verify                string
}

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 ClaimReferences struct {
	ClaimID  string   `json:"claimId"`
	Incoming []string `json:"incoming"`
	Outgoing []string `json:"outgoing"`
}

type ClaimType 

type ClaimType string
const (
	Rule      ClaimType = "rule"
	Invariant ClaimType = "invariant"
)

type Corpus 

type Corpus struct {
	DomainPaths map[string][]string
	Markers     MarkerIndex
	// contains filtered or unexported fields
}

func LoadCorpus 

func LoadCorpus(root string, cfg *config.Config, adrs adr.Corpus) (Corpus, error)

LoadCorpus parses the on-disk .awf/topics tree into a Corpus, reading domain ownership from cfg and scanning marker sources under root. It reads every input into memory and delegates the identity, provenance, reference, and marker assembly to assembleCorpus, the byte-fed core the snapshot loader shares.

func LoadCorpusFromTree added in v0.22.0 

func LoadCorpusFromTree(tree *snapshot.Tree, cfg *config.Config, adrs adr.Corpus) (Corpus, error)

LoadCorpusFromTree parses the current-state topic corpus from an immutable snapshot instead of the live filesystem, so a working-tree, index, or commit universe yields exactly the corpus that tree encodes. Topic metadata, parts, domain ownership, and marker sources are all read from tree; cfg supplies the configured domains and marker-source families (parse it from the same tree for a single-universe load). It shares assembleCorpus and the marker scan/validate core with the filesystem LoadCorpus, so both loaders enforce identical rules over identically shaped bytes.

func (Corpus) All 

func (c Corpus) All() []Topic

func (Corpus) ByClaimID 

func (c Corpus) ByClaimID(id string) (Claim, bool)

func (Corpus) ByTopicID 

func (c Corpus) ByTopicID(id string) (Topic, bool)

func (Corpus) ForDomain 

func (c Corpus) ForDomain(domain string) []Topic

func (Corpus) Incoming 

func (c Corpus) Incoming(id string) []string

func (Corpus) Outgoing 

func (c Corpus) Outgoing(id string) []string

type CoverageFinding added in v0.22.0 

type CoverageFinding struct {
	Path     string           `json:"path"`
	Domain   string           `json:"domain,omitempty"`
	Kind     CoverageKind     `json:"kind"`
	Severity CoverageSeverity `json:"severity"`
	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.

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, path-scoped topic covering the path yields one Uncovered finding at the coverage severity, so a topic from one owner never satisfies another owner's gap. Global and claimless topics never satisfy scoped coverage. Across all owners the distinct path-scoped topics matching a path are counted once; exceeding the budget yields a single Fanout finding at the fan-out severity. Globals are excluded from the count, and a CoverageOff severity suppresses its findings. Unowned paths are the context ownership concern and produce no finding here.

type CoverageKind added in v0.22.0 

type CoverageKind string

CoverageKind distinguishes a missing-scoped-topic finding from a fan-out one. 

const (
	// Uncovered marks a domain-owned path with no claim-bearing scoped topic.
	Uncovered CoverageKind = "uncovered"
	// Fanout marks a path matched by more path-scoped topics than the budget.
	Fanout CoverageKind = "fanout"
)

type CoveragePolicy added in v0.22.0 

type CoveragePolicy struct {
	Coverage, Fanout CoverageSeverity
	MaxTopicsPerPath int
}

CoveragePolicy carries the configured coverage/fan-out severities and the per-path fan-out budget.

type CoverageSeverity added in v0.22.0 

type CoverageSeverity string

CoverageSeverity is the configured strictness for a coverage or fan-out finding: CoverageError fails a gated command, CoverageWarn reports without failing, and CoverageOff suppresses the finding entirely (ADR-0134 item 11). 

const (
	// CoverageError makes a consuming command exit nonzero.
	CoverageError CoverageSeverity = "error"
	// CoverageWarn reports the finding without changing the exit code.
	CoverageWarn CoverageSeverity = "warn"
	// CoverageOff suppresses the finding so the evaluator never emits it.
	CoverageOff CoverageSeverity = "off"
)

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 BuildMarkerIndex 

func BuildMarkerIndex(root string, corpus Corpus, cfg *config.CurrentStateConfig) (MarkerIndex, error)

func (MarkerIndex) All 

func (m MarkerIndex) All() []MarkerSite

func (MarkerIndex) ForClaim 

func (m MarkerIndex) ForClaim(id string) []MarkerSite

type MarkerKind 

type MarkerKind string
const (
	StateMarker   MarkerKind = "state"
	ProofMarker   MarkerKind = "invariant"
	TouchesMarker MarkerKind = "touches-state"
)

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 Metadata 

type Metadata struct {
	Title, Summary string
	Paths          []string
	Applies        string
}
type NavigationModel struct {
	IndexLink string
	Topics    []TopicListItem
}

func BuildNavigationModel 

func BuildNavigationModel(domain string, topics []Topic) NavigationModel

type QueryClaim 

type QueryClaim struct {
	ID      string    `json:"id"`
	Type    ClaimType `json:"type"`
	Prose   string    `json:"prose"`
	Backing Backing   `json:"backing"`
	Verify  string    `json:"verify,omitempty"`
}

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.

type ScaffoldFile 

type ScaffoldFile struct {
	Path    string
	Content []byte
}

ScaffoldFile is one repository-relative authored input produced for a topic.

func ScaffoldFiles 

func ScaffoldFiles(root string, cfg *config.Config, domain, title string) ([]ScaffoldFile, error)

ScaffoldFiles validates and allocates the paired authored inputs for a topic. It inspects both trees but performs no writes.

type Topic 

type Topic struct {
	ID                     TopicID
	Metadata               Metadata
	Intro, Part            string
	Claims                 []Claim
	MetadataPath, PartPath string
}

func ParsePart 

func ParsePart(id TopicID, path string, data []byte) (Topic, error)

func TopicsForPath added in v0.22.0 

func TopicsForPath(c Corpus, path string) []Topic

TopicsForPath returns the topics applicable to a repo-relative path: every global topic plus every path-scoped topic whose effective scope (its owning domain's paths intersected with the topic's own selectors) covers the path. A topic never applies outside its domain ownership by construction. Results are sorted by topic ID, so a caller's per-file selection is deterministic.

type TopicApplicability added in v0.22.0 

type TopicApplicability struct {
	DeclaredGlobal bool         `json:"declaredGlobal"`
	DomainPaths    []string     `json:"domainPaths"`
	TopicPaths     []string     `json:"topicPaths"`
	MatchedPaths   []string     `json:"matchedPaths"`
	MarkerSites    []MarkerSite `json:"markerSites"`
}

TopicApplicability is honest, concrete applicability evidence. DomainPaths and TopicPaths are separate selectors and both must match for a scoped topic; MatchedPaths are witnesses from the caller's selected universe, not a symbolic glob-intersection proof.

func ApplicabilityForTopic added in v0.22.0 

func ApplicabilityForTopic(t Topic, domainPaths []string, markers MarkerIndex, currentPaths []string) TopicApplicability

type TopicID 

type TopicID struct{ Domain, Slug string }

func (TopicID) String 

func (id TopicID) String() string

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.