scan

type Candidate ¶

type Candidate struct {
	// contains filtered or unexported fields
}

Candidate is one reported occurrence of a closed PatternID inside one active owner's Goldmark AST. Candidate is immutable and can only be constructed by this package's own scanning (see scanFileCandidates); a caller can inspect one but never fabricate one, so a Candidate handed to Classify always names a real, exact source occurrence.

func ScanCandidates(baseDir string, discovered []string, owners OwnerManifest) ([]Candidate, error)

func (c Candidate) ASTNode() string

func (c Candidate) ContentWindow() string

func (c Candidate) IsValid() bool

func (c Candidate) Location() ir.Location

func (c Candidate) Pattern() PatternID

func (c Candidate) Snippet() string

type Classification ¶

type Classification string

Classification is the closed, exhaustive disposition a maintainer assigns to one discovered Candidate through the checked-in ClassificationManifest.

There is deliberately no "unclassified" member of this type: unclassified is not a value a candidate can be classified *as*, it is the absence of a matching classification-manifest entry (see Inventory.UnclassifiedCount and ClassifiedCandidate.Classified). Modeling it as a value would let a zero Classification silently mean "no fallback assigns meaning" one day and "explicitly reviewed, no meaning applies" the next — the two states this package must keep visibly distinct per pasture#47's acceptance criteria ("every candidate is explicitly classified or visibly unclassified; no fallback assigns meaning").

const (
	// ClassificationOrchestration is native team/assignment orchestration
	// syntax (e.g. TeamCreate, SendMessage, Skill invocation) that #38's
	// IR represents as a typed orchestration SemanticOperation.
	ClassificationOrchestration Classification = "orchestration"
	// ClassificationUserDecision is native user-interaction syntax (e.g.
	// AskUserQuestion) that #38's IR represents as RequestUserDecision.
	ClassificationUserDecision Classification = "user_decision"
	// ClassificationTaskEffect is a Beads/task-tracker invocation that #43
	// will represent as a typed task effect.
	ClassificationTaskEffect Classification = "task_effect"
	// ClassificationProcessEffect is a process/Git/filesystem invocation
	// that #46 will represent as a typed process/Git/filesystem effect.
	ClassificationProcessEffect Classification = "process_effect"
	// ClassificationPortableVerbatim is native-looking text that is
	// intentionally preserved exactly (e.g. a documentation example
	// showing legacy syntax on purpose) and maps to #38's Verbatim part.
	ClassificationPortableVerbatim Classification = "portable_verbatim"
	// ClassificationTargetLiteral is a reviewed, harness-bound raw escape
	// that maps to #38's exhaustive TargetLiteral part.
	ClassificationTargetLiteral Classification = "target_literal"
	// ClassificationNeutralFalsePositive is a pattern match that, on
	// review, carries no operational meaning at all (e.g. the construct
	// name mentioned in prose without being invoked).
	ClassificationNeutralFalsePositive Classification = "neutral_false_positive"
)

func Classifications() []Classification

func (c Classification) IsValid() bool

type ClassificationEntry ¶

type ClassificationEntry struct {
	Owner          string
	Pattern        PatternID
	ContentWindow  string
	Section        string
	Ordinal        int
	Classification Classification
	Notes          string
}

ClassificationEntry is one checked-in classification decision for exactly one candidate occurrence.

The key is (Owner, Pattern, ContentWindow, Section, Ordinal) — content, not a bare regex-matched prefix and not raw whole-file encounter order:

• ContentWindow is the enclosing source line around the match (see Candidate.ContentWindow), not the short matched prefix (e.g. "Skill(/") Candidate.Snippet still reports for display/diagnostics. Two occurrences of the same pattern almost always sit on different lines, so ContentWindow alone usually makes the key unique without any ordinal at all: keying by the bare prefix made the key indistinguishable between two differently-classified occurrences, so reordering them in the source silently swapped which physical location received which classification, with zero manifest diff and zero scan error.
• Section additionally scopes Ordinal to the nearest preceding heading (the same Section every Candidate/Location already reports), so Ordinal only disambiguates a genuinely byte-identical ContentWindow within one section, not across the whole file — a section-level reorder (moving a whole subsection, or inserting a new one before an existing group of identical-content duplicates) cannot silently reassign meaning the way whole-file ordinal could.
• Ordinal is a last resort: it disambiguates two truly identical lines (same owner, pattern, ContentWindow, and Section) — a swap between those specific occurrences is classification-harmless by construction (a maintainer reviewing byte-identical content under one heading has no way to tell them apart either).

type ClassificationManifest ¶

type ClassificationManifest struct {
	// contains filtered or unexported fields
}

ClassificationManifest is the immutable, validated, checked-in set of every explicit candidate classification decision. A candidate with no matching entry is not defaulted to any Classification — see Inventory/Classify — it is reported unclassified.

func DecodeClassificationManifest(data []byte) (ClassificationManifest, error)

func NewClassificationManifest(entries []ClassificationEntry) (ClassificationManifest, error)

func (m ClassificationManifest) Len() int

type ClassifiedCandidate ¶

type ClassifiedCandidate struct {
	Candidate      Candidate
	Classification Classification
	Classified     bool
	Notes          string
	Ordinal        int
}

ClassifiedCandidate pairs one scanned Candidate with its manifest classification decision. Classified is false exactly when no ClassificationManifest entry matched — pasture#47's "no fallback assigns meaning": Classification is the zero value in that case and must not be read as ClassificationOrchestration or any other member. Ordinal is the zero-based occurrence index Classify assigned this candidate within its (owner, pattern, ContentWindow, section) scope — the same value looked up against (and, once classified, matched to) a ClassificationEntry.

type Diagnostic ¶

type Diagnostic struct {
	What   string
	Why    string
	Where  string
	Phase  string
	Impact string
	Fix    string
	Cause  error
}

Diagnostic is this package's actionable error contract. Every field is required so a caller can act on a failure without reading scanner source: what went wrong, why, where it failed, during which phase, what it means for the caller, and how to fix it. This mirrors internal/codegen/ir's Diagnostic shape (see ir/diagnostic.go) without importing it: scan is an independent consumer-facing package and must not fork or re-export #38's exported Diagnostic type, but the same actionable-error contract applies to every error this package returns.

func (d *Diagnostic) Error() string

func (d *Diagnostic) Unwrap() error

type Inventory ¶

type Inventory struct {
	// contains filtered or unexported fields
}

Inventory is the classified candidate set #46, #43, and #40 consume before freezing their own closed sets, and #42 consumes through RequireZeroUnclassified before enabling strict rejection.

func Classify(candidates []Candidate, manifest ClassificationManifest) Inventory

func ScanCanonical(baseDir string) (Inventory, error)

func ScanWithManifests(baseDir string, roots []string, owners OwnerManifest, classifications ClassificationManifest) (Inventory, error)

func (inv Inventory) Candidates() []ClassifiedCandidate

func (inv Inventory) CountByClassification(c Classification) int

func (inv Inventory) Len() int

func (inv Inventory) OrphanedClassifications() []ClassificationEntry

func (inv Inventory) Unclassified() []ClassifiedCandidate

func (inv Inventory) UnclassifiedCount() int

type OwnerDisposition ¶

type OwnerDisposition string

OwnerDisposition is the closed, exhaustive whole-file disposition recorded in the checked-in OwnerManifest.

const (
	// OwnerActive means the owner is parsed and scanned for candidates.
	OwnerActive OwnerDisposition = "active"
	// OwnerDead means the owner is discovered and reconciled (it still
	// must be byte-for-byte hashed and present in the manifest) but is
	// explicitly disposed as historically inactive, so it is not parsed
	// for candidates. A dead disposition always requires a non-empty
	// Reason (see OwnerEntry) — pasture#47 requires "explicit dead-owner
	// dispositions", not a silent skip.
	OwnerDead OwnerDisposition = "dead"
)

func OwnerDispositions() []OwnerDisposition

func (d OwnerDisposition) IsValid() bool

type OwnerEntry ¶

type OwnerEntry struct {
	// Path is the owner's path relative to the scan base directory,
	// slash-separated (e.g. "skills/worker/SKILL.md").
	Path string
	// Disposition is the owner's closed active/dead disposition.
	Disposition OwnerDisposition
	// Reason is required (non-empty) when Disposition is OwnerDead and
	// otherwise ignored — pasture#47 requires "explicit dead-owner
	// dispositions", not a silent skip.
	Reason string
}

OwnerEntry is one checked-in disposition for a canonical owner path.

type OwnerManifest ¶

type OwnerManifest struct {
	// contains filtered or unexported fields
}

OwnerManifest is the immutable, validated, checked-in set of every canonical owner's disposition. It is reconciliation input only — see ReconcileOwners — never the discovery source: Discover walks the filesystem independently, and OwnerManifest is compared against what Discover actually found.

func DecodeOwnerManifest(data []byte) (OwnerManifest, error)

func NewOwnerManifest(entries []OwnerEntry) (OwnerManifest, error)

func (m OwnerManifest) Len() int

func (m OwnerManifest) Lookup(path string) (OwnerEntry, bool)

func (m OwnerManifest) Paths() []string

type PatternID ¶

type PatternID string

PatternID identifies one closed, code-owned lexical pattern the scanner looks for inside every active owner's Goldmark AST. The registry is intentionally small and precise (exact call-like syntax, not every prose mention of a construct's name) — see patternRegistry in pattern.go for the exact regular expressions and internal/codegen/scan/manifest for the real classification of every match this registry currently produces against this repository's canonical roots.

const (
	// PatternTeamCreate matches a literal TeamCreate( call prefix — native
	// parallel-team spawning syntax (orchestration).
	PatternTeamCreate PatternID = "team_create"
	// PatternSendMessage matches a literal SendMessage( call prefix —
	// native assignment-messaging syntax (orchestration).
	PatternSendMessage PatternID = "send_message"
	// PatternSkillInvocation matches a literal Skill(/ call prefix —
	// native skill-invocation syntax (orchestration).
	PatternSkillInvocation PatternID = "skill_invocation"
	// PatternAskUserQuestion matches a literal AskUserQuestion( call
	// prefix — native user-decision syntax (user decision).
	PatternAskUserQuestion PatternID = "ask_user_question"
)

func PatternIDs() []PatternID

func (id PatternID) IsValid() bool

type ReconcileError ¶

type ReconcileError struct{ Problems []string }

ReconcileError aggregates every owner-manifest drift problem found by ReconcileOwners into one actionable error, so a caller sees every problem in one report instead of fixing them one failed run at a time.

func (e *ReconcileError) Error() string