devindex

package
v0.53.0 Latest Latest
Warning

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

 Go to latest Published: Sep 8, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package devindex is queryable self-index over fak's own dev facts (lanes/leaves + doc map): query, don't survey.

Tier: foundation (1) — see internal/architest. This package may import only packages whose tier is <= 1; an upward import fails the architest gate. See AGENTS.md and internal/architest for the layering contract.

Index

Constants

View Source 
const (
	// ExecAuditSchema versions the emitted witness.
	ExecAuditSchema = "fak.devindex.exec-audit.v1"
	// ExecDomainNotEstablished is the fail-closed status: the audit could not resolve
	// the executable domain, so it reports THAT rather than a green run over nothing.
	ExecDomainNotEstablished = "could-not-establish-domain"
)
View Source 
const DevHandoffManifestPath = "internal/devhandoff/commands_gen.go"
View Source 
const DiscoveryBenchmarkSchema = "fak-devindex-discovery-benchmark/1"
View Source 
const VerbSynopsisMaxRunes = 110

VerbSynopsisMaxRunes is the width ceiling for a curated verb synopsis, counted in runes (not bytes) so a multi-byte character costs one column, matching the usage wall's own rendering width.

Variables

View Source 
var DevOnlyPackages = []PackageOwnership{
	{Path: moduleInternalPrefix + "amdgpu", Owner: OwnerShared, Rationale: "shares AMD GPU hardware probe and counters between runtime and fak-dev commands"},
	{Path: moduleInternalPrefix + "commitsubject", Owner: OwnerDev, Rationale: "audits repository commit-subject grammar coverage"},
	{Path: moduleInternalPrefix + "codexmemory", Owner: OwnerDev, Rationale: "diagnoses development-agent Codex memory posture"},
	{Path: moduleInternalPrefix + "devcmd", Owner: OwnerDev, Rationale: "hosts repository-development command implementations for fak-dev"},
	{Path: moduleInternalPrefix + "devindex", Owner: OwnerDev, Rationale: "indexes repository development metadata for fak-dev"},
	{Path: moduleInternalPrefix + "readmevisualaudit", Owner: OwnerDev, Rationale: "audits repository README visual and asset health"},
	{Path: moduleInternalPrefix + "refactorverify", Owner: OwnerDev, Rationale: "verifies repository code-motion refactors preserve declarations"},
	{Path: moduleInternalPrefix + "toolcoverage", Owner: OwnerDev, Rationale: "audits repository tool test coverage and load-bearing references"},
	{Path: moduleInternalPrefix + "workflowaudit", Owner: OwnerDev, Rationale: "audits repository CI workflow refs and generated documentation"},
	{Path: moduleInternalPrefix + "planaudit", Owner: OwnerDev, Rationale: "audits repository plan documents for drift"},
	{Path: moduleInternalPrefix + "issuesync", Owner: OwnerDev, Rationale: "synchronizes fak repository GitHub issues"},
	{Path: moduleInternalPrefix + "wiki", Owner: OwnerDev, Rationale: "audits repository documentation structure, citations, freshness, and coverage"},
	{Path: moduleInternalPrefix + "sweep", Owner: OwnerDev, Rationale: "groups and commits shared-checkout development work"},
	{Path: moduleInternalPrefix + "worktreeworker", Owner: OwnerDev, Rationale: "manages isolated repository worker worktrees"},
	{Path: moduleInternalPrefix + "borrowprovenance", Owner: OwnerShared, Rationale: "shares provenance records with runtime SWE-bench SOTA verification while fak-dev owns the CLI"},
	{Path: moduleInternalPrefix + "customizationindex", Owner: OwnerDev, Rationale: "indexes agent-customization research for maintainers"},
	{Path: moduleInternalPrefix + "ideascout", Owner: OwnerDev, Rationale: "plans research-derived repository issue intake"},
	{Path: moduleInternalPrefix + "studyadjacency", Owner: OwnerDev, Rationale: "audits related-runtime research adjacency"},
	{Path: moduleInternalPrefix + "studyclass", Owner: OwnerDev, Rationale: "classifies repository study evidence"},
	{Path: moduleInternalPrefix + "studyforge", Owner: OwnerDev, Rationale: "captures forge-history research evidence"},
	{Path: moduleInternalPrefix + "studylink", Owner: OwnerShared, Rationale: "shares the deterministic study-evidence join with the runtime learning-mesh compiler while fak-dev owns repository study-link orchestration"},
	{Path: moduleInternalPrefix + "studymonitor", Owner: OwnerShared, Rationale: "shares study registry types and verification with runtime studydrift while fak-dev owns study monitor CLI"},
	{Path: moduleInternalPrefix + "studyprio", Owner: OwnerDev, Rationale: "prioritizes uncovered repository study joins"},
	{Path: moduleInternalPrefix + "studytickets", Owner: OwnerDev, Rationale: "constructs repository ticket closure from study evidence"},
}

DevOnlyPackages starts the package boundary with leaves whose contracts are intrinsically repository-development control-plane work. The list expands as command families move; every entry is enforced immediately by GraphLeaks.

View Source 
var ExecAuditPins = []ExecPin{}

The committed exception set for the executable audit (#5648).

A pin admits ONE executable package that fails an axis, for ONE named reason. It is deliberately not an ignore list: foldExecPins reds the audit the moment a pin stops doing work — when its package leaves the domain, when the package starts passing on its own, when the declared expiry passes, or when the reason is blank. That is the only property that keeps an exception honest, because an exception nobody is forced to revisit is just undocumented debt with a nicer name.

Empty is the correct default. The audit over the current tree reports its failures by name rather than hiding them behind a bulk baseline: which of fak's executables are unwired is a real, currently-true finding, and the committed witness (docs/exec-audit.witness.json) is where that denominator is preserved. Add an entry here only when a specific package has a specific reason to be exempt, with a date.

Functions

func DispatchVerbs added in v0.42.0 

func DispatchVerbs(b []byte) []string

DispatchVerbs is the exported form of mainDispatchVerbs: the lowercased dispatch tokens parsed out of cmd/fak/main.go bytes (sorted, deduped). It exists so the pre-push VERB_UNTIERED hygiene gate (internal/hooks/gate_verbtier.go) reads the verb set through the SAME parser TestVerbTierCoverageIsTotal uses, rather than a second copy — the gate can then never disagree with the CI ratchet it fronts about which tokens the switch actually dispatches (epic #2653).

func FindRoot 

func FindRoot(start string) string

FindRoot walks up from start looking for the dos.toml that marks the repo root, so `fak index` works from any subdirectory. It returns the first ancestor that contains dos.toml, or start unchanged if none is found.

func MarshalOwnershipReport added in v0.44.0 

func MarshalOwnershipReport(report OwnershipReport) ([]byte, error)

MarshalOwnershipReport emits a stable indented JSON artifact.

func RenderDevHandoffManifest added in v0.45.0 

func RenderDevHandoffManifest(root string) ([]byte, error)

RenderDevHandoffManifest renders the one checked-in command authority consumed by runtime fak. The rows come from the fak-dev AST; editing the dispatcher without regenerating this file is a deterministic test failure.

func TierName added in v0.37.0 

func TierName(tier int) string

TierName renders architest's numeric layer into its review vocabulary.

func ValidateCommandOwnership added in v0.44.0 

func ValidateCommandOwnership(verbs []Verb, inventory []CommandOwnership) []string

ValidateCommandOwnership proves that inventory is a one-to-one, total map of catalog command names. It returns deterministic diagnostics for tests and CLI callers rather than failing on the first defect.

func ValidateDevReuseRegistry added in v0.44.0 

func ValidateDevReuseRegistry() []string

ValidateDevReuseRegistry proves that a spelling is declared exactly once. It runs as part of ownership validation so adding a TierDev command without making the reuse decision reds the same exhaustive gate.

func WriteDevHandoffManifest added in v0.45.0 

func WriteDevHandoffManifest(root string) error

Types

type BlastRadiusPackage added in v0.37.0 

type BlastRadiusPackage struct {
	ImportPath string `json:"import_path"`
	Distance   int    `json:"distance"`
	Direct     bool   `json:"direct,omitempty"`
}

BlastRadiusPackage is one dependent package ranked by shortest import distance to a direct symbol reference. Distance 1 means the package directly references the target symbol; larger distances are transitive importers of a direct user.

type BlastRadiusResult added in v0.37.0 

type BlastRadiusResult struct {
	Target   SymbolID             `json:"target"`
	Packages []BlastRadiusPackage `json:"packages"`
}

BlastRadiusResult is the complete answer for one symbol query. Packages excludes the defining package itself and contains direct plus transitive dependents.

func BlastRadius added in v0.37.0 

func BlastRadius(packages []PackageImports, refs []SymbolReference, target SymbolID) BlastRadiusResult

BlastRadius is a convenience wrapper for querying a one-shot package/ref set.

type Catalog 

type Catalog struct {
	Root        string       `json:"root"`
	Leaves      []Leaf       `json:"leaves"`
	Docs        []Doc        `json:"docs"`
	Claims      []Claim      `json:"claims,omitempty"`
	Generations []Generation `json:"generations,omitempty"`
	// contains filtered or unexported fields
}

Catalog is the loaded self-index: the leaf taxonomy and the doc map, plus the path-prefix maps the lane resolver needs. Build it with Load.

func Load 

func Load(root string) (*Catalog, error)

Load reads the catalog from root (the repo root holding dos.toml and INDEX.md). A missing INDEX.md degrades to an empty doc map rather than an error — the leaf taxonomy is the load-bearing half. Load only errors when dos.toml is unreadable, because without it there is no taxonomy to serve.

func (*Catalog) CheckFreshness 

func (c *Catalog) CheckFreshness() []Drift

CheckFreshness returns the drift findings only, sorted (by kind, then subject) for a stable gate message. An empty slice means NO DRIFT WAS PROVEN — which is not the same as "the index agrees with reality", because a detector whose source could not be read proves nothing at all. Callers that need that distinction (anything that reports a verdict to a human or a machine) must use CheckFreshnessReport and its Verdict; callers that only count proven drift, such as a catch-up score, are right to use this projection. It reads only the tree under c.Root; no network.

func (*Catalog) CheckFreshnessAgainstHEAD added in v0.42.0 

func (c *Catalog) CheckFreshnessAgainstHEAD() ([]Drift, error)

CheckFreshnessAgainstHEAD resolves the INDEX.md doc-map bullets and llms.txt local .md links AS COMMITTED AT HEAD against HEAD's committed tree, and returns a Drift for every link whose target a fresh checkout would not have — the HEAD-only dead links the tier-1 working-tree pass is structurally blind to (#5107). Findings are sorted (kind, then subject) like CheckFreshness. A file absent from HEAD (no committed INDEX.md / llms.txt) contributes no finding — no committed map, no committed claim. It returns an error only when git itself cannot answer (no repo, no HEAD): the caller opted into the HEAD view, so a failure to read it must never masquerade as clean. Tier-1 CheckFreshness never calls this; it stays git-free.

func (*Catalog) CheckFreshnessReport added in v0.44.0 

func (c *Catalog) CheckFreshnessReport() FreshnessReport

CheckFreshnessReport compares the loaded catalog against its live sources on disk.

It folds five detectors: undeclared leaves, dead INDEX.md doc links, main.go verb cases missing from the C3 manifest, orphaned dated notes, and dead llms.txt links. A source it cannot read still contributes no DRIFT finding — a missing source is the absence of a claim, not a disagreement — but it is now recorded as an Unchecked, so the detector that skipped it can never be mistaken for one that ran and found the tree clean (#5962). The detail accessors below back each fold and are exported so a gate can report just the category it cares about; they keep their drift-only signatures, so a caller that wants the unchecked half asks here.

func (*Catalog) ClaimsForLeaf 

func (c *Catalog) ClaimsForLeaf(name string) []Claim

ClaimsForLeaf returns the ledger claims that bind to the named (case-insensitive) leaf, in ledger order — the detail behind a leaf's Status rollup. 

func (c *Catalog) DeadDocLinks() []Doc

DeadDocLinks returns the doc-map entries whose path is a LOCAL repo path (not an http(s) URL) that no longer resolves under c.Root. An external URL is left unchecked — tier 1 does no network — and an in-page anchor ("#foo") is skipped. 

func (c *Catalog) DeadLLMSLinks() []string

DeadLLMSLinks returns the local .md link targets in llms.txt (the answer-engine index) that no longer resolve on disk — the dangling half of the reciprocal sync gate applied to the LLM-facing map, which DeadDocLinks (INDEX.md only) does not cover. It mirrors tools/check_index_sync.py's link filter exactly: an http(s) / mailto / in-page anchor / absolute-path target is skipped, a trailing #anchor or ?query is stripped, and only a .md target is checked. Deduped (by cleaned path), sorted. A missing llms.txt yields nothing — no map to check. Reads only c.Root; no network (tier 1: an external URL is never fetched, only skipped).

func (*Catalog) ExplicitTreeLaneForPath added in v0.45.0 

func (c *Catalog) ExplicitTreeLaneForPath(path string) string

ExplicitTreeLaneForPath resolves only authored [lanes.trees] exact paths and prefixes. Unlike LaneForPath it deliberately has no internal/<package> convention fallback, so a live-census parity test can prove that ownership is present in the taxonomy rather than merely infer the package name. This is the strict read used by the #9326 current-package reconciliation witness.

func (*Catalog) GenerationByStream added in v0.37.0 

func (c *Catalog) GenerationByStream(stream string) (Generation, bool)

GenerationByStream returns the generation row matching a stream name or gen/* label, case-insensitive.

func (*Catalog) IssueViews added in v0.37.0 

func (c *Catalog) IssueViews() (IssueViews, error)

IssueViews reads .github/issue-views.json from the catalog root. A missing or unparseable file is returned as an error the caller surfaces — unlike the doc map (which degrades to empty), the selection surface has no taxonomy to invent, and an absent file is a real "this repo declares no views" answer, not a silent empty.

func (*Catalog) LaneForPath 

func (c *Catalog) LaneForPath(path string) string

LaneForPath maps one repo-relative path to its lane: the exact-file map first, then the longest matching [lanes.trees] subtree prefix (authoritative), then the directory convention (internal/<X> -> X, cmd/** -> cmd, a top-level lane dir -> itself). It mirrors internal/hooks.laneForPath so `fak index lane` and the commit-stamp lint reach the SAME answer. "" when no lane can be inferred.

func (*Catalog) LeafByName 

func (c *Catalog) LeafByName(name string) (Leaf, bool)

LeafByName returns the leaf with the given (case-insensitive) name, or false.

func (*Catalog) Orient added in v0.37.0 

func (c *Catalog) Orient(paths []string, leases []OrientationLease) []Orientation

Orient resolves each requested path/glob to its local development conventions.

func (*Catalog) OrphanNotes added in v0.37.0 

func (c *Catalog) OrphanNotes() []string

OrphanNotes returns the repo-relative paths of dated notes under docs/notes/ whose basename INDEX.md never mentions — the tree->index converse of DeadDocLinks. INDEX.md's own contract is "if a doc exists, it is reachable from here", so an unlisted dated note breaks it. The check is a raw-basename substring test against INDEX.md's bytes (a note may be reached via prose, not only a link), matching tools/check_index_sync.py exactly so the Go view and the Python gate can never disagree on an orphan. A missing INDEX.md yields nothing (no map to reconcile against). Sorted, deduped; reads only the tree under c.Root — no git, no network (tier 1).

func (*Catalog) RunDiscoveryBenchmark added in v0.45.0 

func (c *Catalog) RunDiscoveryBenchmark(questions []DiscoveryQuestion) DiscoveryBenchmarkReport

func (*Catalog) SearchClaims 

func (c *Catalog) SearchClaims(query string) []Claim

SearchClaims returns the ledger claims matching the query, lexically scored (a lane match weighs most, then the section, then the prose) and ranked best-first. An empty query returns nothing — a ledger search with no terms is a usage error the caller surfaces. This is the "what's shipped vs simulated vs stub for X" ask. When exact scoring yields NO hit, it falls back to a trigram fuzzy pass over the same fields (#3925), returning the best near-misses flagged Approx.

func (*Catalog) SearchDocs 

func (c *Catalog) SearchDocs(query string) []Doc

SearchDocs returns the doc-map entries matching the query, lexically scored (a title hit weighs most, then the path, then the blurb) and ranked best-first. Multi-term searches rank token coverage first and prefer reference docs over historical notes at equal coverage. A doc must match at least one query token. An empty query returns nothing — a doc search with no terms is a usage error the caller surfaces. When exact scoring yields NO hit, it falls back to a trigram fuzzy pass over the same fields (#3925), returning the best near-misses flagged Approx rather than an empty result.

func (*Catalog) SearchGenerations added in v0.37.0 

func (c *Catalog) SearchGenerations(query string) []Generation

SearchGenerations returns generation rows matching the query. Empty query lists all horizons in now -> future order so `fak index generation` is a compact self-index overview.

func (*Catalog) SearchLeaves 

func (c *Catalog) SearchLeaves(query string) []Leaf

SearchLeaves returns the leaves whose name, tree, or description matches every whitespace-separated query token (case-insensitive), ranked by where the match landed (a name hit outranks a description hit). An empty query returns every leaf in name order. When exact substring scoring yields NO hit, it falls back to a trigram fuzzy pass over the same fields (#3925), returning the best near-misses flagged Approx rather than an empty result.

func (*Catalog) SearchVerbs 

func (c *Catalog) SearchVerbs(query string) []Verb

SearchVerbs returns the catalog verbs matching the query, lexically scored (a name or alias hit weighs most, then the lane, then the synopsis) and ranked best-first. An empty query returns the full catalog in name order — `fak index verbs` with no term lists every verb, matching the leaf-search convention. It searches the live derived catalog (Verbs()), so a dispatched-but-uncurated verb is still found.

func (*Catalog) SuggestStamp 

func (c *Catalog) SuggestStamp(path string) string

SuggestStamp renders the `(fak <leaf>)` ship-stamp trailer the path implies, or "" when no lane can be inferred — the answer an agent otherwise greps dos.toml for before every commit.

func (*Catalog) TierForPath added in v0.37.0 

func (c *Catalog) TierForPath(path string) (tier int, ok bool)

TierForPath returns the architest tier for internal/<leaf> paths. Non-internal paths have no arch tier and return ok=false.

func (*Catalog) UndeclaredLeaves 

func (c *Catalog) UndeclaredLeaves() []string

UndeclaredLeaves returns the names of internal/<X> directories that hold at least one .go file but have no declared dos.toml lane. It mirrors internal/hooks.UndeclaredLeaves, recomputed from this catalog's already-parsed lane set (c.declared — every name in [lanes] AND every [lanes.trees] key, the SAME set the authoritative gate builds) plus the explicit tree resolver, so the tier-1 package need not import the hooks gate yet reaches the identical verdict (pinned by a live parity test). A leaf is owned when its package name is declared or an authored tree maps its files to a differently named composite lane. Sorted, deduped.

A tree it cannot read yields no gaps. That is the drift-only view; ask CheckFreshnessReport if you need to tell "no gaps" apart from "never looked".

func (*Catalog) UndeclaredVerbs 

func (c *Catalog) UndeclaredVerbs() []string

UndeclaredVerbs returns the cmd/fak/main.go top-level switch cases that have no entry in the C3 verb manifest — the "a verb in main.go with no manifest entry" drift (#1293). It parses the dispatch switch out of main.go on disk (read-only); a missing main.go yields no findings (absence of a claim, not a drift). Sorted, deduped, lowercased.

func (*Catalog) VerbByName 

func (c *Catalog) VerbByName(name string) (Verb, bool)

VerbByName returns the manifest entry matching the given (case-insensitive) token against the verb's canonical name OR any alias, and ok=false when nothing routes. The freshness gate uses this to ask "does main.go's case <tok> have a manifest entry?" without re-deriving the alias set at the call site.

func (*Catalog) Verbs 

func (c *Catalog) Verbs() []Verb

Verbs returns the structured CLI-verb catalog, sorted by name. It is a live VIEW, not a frozen list: COVERAGE comes from the cmd/fak/main.go dispatch switch (every verb the binary actually routes), and the curated verbManifest supplies QUALITY (synopsis / owning lane / alias grouping / doc) for the verbs it names. A dispatched verb with no curated entry still appears, carrying a fallback synopsis that points at its own --help — so the catalog can never silently fall behind the binary the way a hand-maintained list does. When main.go cannot be read (an installed binary outside a repo), it falls back to the curated overlay alone. The cmd/ usage generator and `fak index verbs` (CLI + MCP) consume it.

type Claim 

type Claim struct {
	Tag     string   `json:"tag"`               // SHIPPED | SIMULATED | STUB
	Section string   `json:"section,omitempty"` // the nearest `##`/`###` header above it
	Lanes   []string `json:"lanes,omitempty"`   // leaves the claim's path refs bind to
	Text    string   `json:"text"`              // the claim prose, tag prefix removed
	// Approx marks a claim returned by the trigram fuzzy fallback (#3925) — a near-miss
	// on the lanes/section/text rather than an exact substring hit. Omitted on exact hits.
	Approx bool `json:"approx,omitempty"`
}

Claim is one line of the CLAIMS.md honesty ledger: its maturity tag, the `##` section it sits under, the lanes its in-line package-path references resolve to (via LaneForPath — the SAME taxonomy the commit-stamp lint binds to), and the claim prose (the `- [TAG] ` prefix stripped). fak index reads it so an agent asks the ledger instead of grepping it.

type CommandOwner added in v0.44.0 

type CommandOwner string

CommandOwner names the independently buildable artifact that owns a command. Shared is reserved for a command whose executable contract genuinely belongs on both surfaces; it is not a synonym for a shared implementation package. 

const (
	OwnerRuntime CommandOwner = "runtime"
	OwnerDev     CommandOwner = "dev"
	OwnerShared  CommandOwner = "shared"
)

type CommandOwnership added in v0.44.0 

type CommandOwnership struct {
	Name              string       `json:"name"`
	Owner             CommandOwner `json:"owner"`
	Rationale         string       `json:"rationale"`
	CompatibilityName string       `json:"compatibility_name"`
	DispatchTarget    string       `json:"dispatch_target"`
	DevReuse          DevReuse     `json:"dev_reuse"`
	DevReuseRationale string       `json:"dev_reuse_rationale"`
}

CommandOwnership is the machine-readable product boundary for one top-level command spelling. CompatibilityName is the spelling retained at a legacy entry point while DispatchTarget names the artifact that owns execution.

func CommandOwnerships added in v0.44.0 

func CommandOwnerships(verbs []Verb) []CommandOwnership

CommandOwnerships derives a total ownership inventory from the authoritative catalog. The existing tier decision is the migration input: front-door and internal product verbs stay in the runtime artifact; repository-development verbs move to fak-dev. Exceptions must be represented explicitly here rather than inferred from filenames.

type DevReuse added in v0.44.0 

type DevReuse string

DevReuse is independent of binary ownership. It distinguishes reusable development patterns from machinery specific to fak or its private lab. 

const (
	DevReuseNA           DevReuse = "not-applicable"
	DevReusePortable     DevReuse = "portable-pattern"
	DevReuseMaintainer   DevReuse = "fak-maintainer"
	DevReuseLab          DevReuse = "lab-operations"
	DevReuseUnclassified DevReuse = "unclassified"
)

func ClassifyDevReuse added in v0.44.0 

func ClassifyDevReuse(name string, owner CommandOwner) (DevReuse, string)

ClassifyDevReuse returns a total reuse classification. Portable means that the concept is suitable for examples and dogfood; it does not make the current repository-bound command a stable adopter API.

type DiscoveryBenchmarkReport added in v0.45.0 

type DiscoveryBenchmarkReport struct {
	Schema        string                `json:"schema"`
	Source        string                `json:"source"`
	Coverage      string                `json:"coverage"`
	Questions     int                   `json:"questions"`
	Successes     int                   `json:"successes"`
	TopKRate      float64               `json:"top_k_rate"`
	TotalResults  int                   `json:"total_results"`
	RenderedBytes int                   `json:"rendered_bytes"`
	Cases         []DiscoveryCaseResult `json:"cases"`
}

func (DiscoveryBenchmarkReport) Summary added in v0.45.0 

func (r DiscoveryBenchmarkReport) Summary() string

type DiscoveryCaseResult added in v0.45.0 

type DiscoveryCaseResult struct {
	DiscoveryQuestion
	Success       bool     `json:"success"`
	Rank          int      `json:"rank,omitempty"`
	ResultCount   int      `json:"result_count"`
	RenderedBytes int      `json:"rendered_bytes"`
	Approximate   bool     `json:"approximate,omitempty"`
	TopPaths      []string `json:"top_paths,omitempty"`
}

type DiscoveryQuestion added in v0.45.0 

type DiscoveryQuestion struct {
	ID       string   `json:"id"`
	Category string   `json:"category"`
	Query    string   `json:"query"`
	Owners   []string `json:"owners"`
	TopK     int      `json:"top_k"`
}

func DefaultDiscoveryQuestions added in v0.45.0 

func DefaultDiscoveryQuestions() []DiscoveryQuestion

type Doc 

type Doc = docsearch.Doc

Doc remains the development index's public documentation row while the shared loader/search authority lives in docsearch, outside the runtime-forbidden package.

type Drift 

type Drift struct {
	Kind    DriftKind `json:"kind"`
	Subject string    `json:"subject"`
	Reason  string    `json:"reason"`
}

Drift is one freshness finding: the kind, the offending token (a leaf name, a doc path, or a verb), and a one-line human reason. A non-empty Drift slice from CheckFreshness is the signal the (out-of-lane) gate test turns into a red build.

type DriftKind 

type DriftKind string

DriftKind classifies a freshness finding so a caller (a gate test, a scorecard) can route or count by category. 

const (
	// DriftUndeclaredLeaf: an internal/<X> Go package with no dos.toml lane entry.
	DriftUndeclaredLeaf DriftKind = "undeclared-leaf"
	// DriftDeadDocLink: an INDEX.md doc-map entry whose local path is missing.
	DriftDeadDocLink DriftKind = "dead-doc-link"
	// DriftUnknownVerb: a main.go switch case with no C3 verb-manifest entry.
	DriftUnknownVerb DriftKind = "unknown-verb"
	// DriftOrphanNote: a dated docs/notes/ note not listed in INDEX.md.
	DriftOrphanNote DriftKind = "orphan-note"
	// DriftDeadLLMSLink: an llms.txt local .md link that no longer resolves on disk.
	DriftDeadLLMSLink DriftKind = "dead-llms-link"
)
const (
	// DriftDeadDocLinkHEAD: an INDEX.md doc-map entry committed at HEAD whose target
	// path is absent from HEAD's tree (even when an untracked working-tree file of
	// that name exists — the blind spot the working-tree DriftDeadDocLink cannot see).
	DriftDeadDocLinkHEAD DriftKind = "dead-doc-link-head"
	// DriftDeadLLMSLinkHEAD: an llms.txt local .md link committed at HEAD whose
	// target is absent from HEAD's tree — the same HEAD-resolution applied to the
	// LLM-facing map.
	DriftDeadLLMSLinkHEAD DriftKind = "dead-llms-link-head"
)

type ExecAuditOptions added in v0.44.0 

type ExecAuditOptions struct {
	// Root is the module root to audit.
	Root string
	// Pins are the admitted exceptions. Nil means "no exception is admitted".
	Pins []ExecPin
	// Now dates pin expiry. Zero means time.Now().
	Now time.Time
}

ExecAuditOptions parameterizes one audit run.

type ExecAuditResult added in v0.44.0 

type ExecAuditResult struct {
	Schema string `json:"schema"`
	// Established is false when the executable domain could not be resolved at all.
	Established bool   `json:"established"`
	Status      string `json:"status"` // "ok" | "fail" | ExecDomainNotEstablished
	Reason      string `json:"reason,omitempty"`
	// Domain is the TOTAL number of executable packages discovered — the denominator.
	Domain     int            `json:"domain"`
	Tested     int            `json:"tested"`
	Reached    int            `json:"reached"`
	Packages   []ExecPackage  `json:"packages"`
	Exceptions []ExecPinState `json:"exceptions"`
	Failures   []string       `json:"failures"`
	StalePins  []string       `json:"stale_pins"`
}

ExecAuditResult is the whole answer, JSON-shaped so the DENOMINATOR is auditable rather than asserted: the total domain size, every row, every admitted exception, and the named failures.

func AuditExecutables added in v0.44.0 

func AuditExecutables(opts ExecAuditOptions) (*ExecAuditResult, error)

AuditExecutables derives every `main` package in the module at Root, joins each against an adjacent-test probe and a reachability sweep over the tree outside the package, folds the admitted pins, and returns the typed result.

It FAILS CLOSED: if `go list` cannot run, or resolves no executable at all, the returned result carries Established=false and Status=ExecDomainNotEstablished alongside a non-nil error. Callers must never read that as a clean audit.

type ExecEvidence added in v0.44.0 

type ExecEvidence struct {
	Class ExecEvidenceClass `json:"class"`
	File  string            `json:"file"`
	Line  int               `json:"line"`
	Text  string            `json:"text"`
}

ExecEvidence is one reachability edge: the class, the repo-relative file and line that carry it, and the matched text. The locator is kept so a reader can check the claim instead of trusting the audit's own summary.

type ExecEvidenceClass added in v0.44.0 

type ExecEvidenceClass string

ExecEvidenceClass names HOW an executable is reached from outside itself. The classes stay DISTINGUISHED rather than collapsed to a bool: a build target, a dispatcher registration, an installer line, a script and a documented runnable example are not interchangeable, and which one holds is exactly what a fixer needs. 

const (
	// ExecEvidenceBuildTarget: a Makefile / *.mk / CI-workflow line that builds it.
	ExecEvidenceBuildTarget ExecEvidenceClass = "build-target"
	// ExecEvidenceDispatch: Go code outside the package naming its path in a string
	// literal — the spawn/registration edge (a main package cannot be imported).
	ExecEvidenceDispatch ExecEvidenceClass = "dispatcher-registration"
	// ExecEvidenceInstaller: a `go install` line — the "how a user gets the binary" edge.
	ExecEvidenceInstaller ExecEvidenceClass = "installer"
	// ExecEvidenceScript: a shell/PowerShell/Python script that builds or runs it.
	ExecEvidenceScript ExecEvidenceClass = "script"
	// ExecEvidenceDocExample: a documented RUNNABLE example (a command line in prose),
	// as distinct from an inventory row that merely names the package.
	ExecEvidenceDocExample ExecEvidenceClass = "documented-example"
)

type ExecPackage added in v0.44.0 

type ExecPackage struct {
	ImportPath string         `json:"import_path"`
	Dir        string         `json:"dir"` // repo-relative, slash-separated (host-independent)
	Binary     string         `json:"binary"`
	HasTest    bool           `json:"has_test"`
	TestFiles  int            `json:"test_files"`
	Evidence   []ExecEvidence `json:"evidence,omitempty"`
	Status     ExecStatus     `json:"status"`
	// PinReason is set only when a live pin admits an otherwise-failing package.
	PinReason string `json:"pin_reason,omitempty"`
}

ExecPackage is one row of the audit: an executable package, its two independent axes, the evidence that established reachability, and whether a pin admits it.

func (ExecPackage) Reachable added in v0.44.0 

func (p ExecPackage) Reachable() bool

Reachable reports whether anything outside the package invokes it.

type ExecPin added in v0.44.0 

type ExecPin struct {
	Package string `json:"package"` // full import path
	Reason  string `json:"reason"`
	// Until is an optional YYYY-MM-DD expiry. Empty means the pin is bounded only by
	// its own justification (it goes stale when the package leaves the domain or the
	// condition it excuses no longer holds).
	Until string `json:"until,omitempty"`
}

ExecPin is a temporary, REASONED exception: a package allowed to fail an axis while a named condition holds. Following internal/architest's tier map, the reason is mandatory — a bare ignore list converts a measured exception into invisible permanent debt, and the whole value of a pin is that it fails once stale.

type ExecPinState added in v0.44.0 

type ExecPinState struct {
	ExecPin
	Stale bool   `json:"stale"`
	Why   string `json:"why"`
}

ExecPinState is a pin folded against the live tree: whether it is still doing work, or has gone stale and must be removed.

type ExecStatus added in v0.44.0 

type ExecStatus string

ExecStatus is the closed per-package verdict vocabulary, derived from the two independent axes (HasTest, Evidence) plus pin state. It is a LABEL over the axes, never a replacement for them. 

const (
	// ExecStatusOK: an adjacent test AND at least one outside invocation edge.
	ExecStatusOK ExecStatus = "ok"
	// ExecStatusUntested: wired up, but no adjacent test (the "wired-but-untested" state).
	ExecStatusUntested ExecStatus = "untested"
	// ExecStatusUnreachable: tested, but nothing outside the package invokes it.
	ExecStatusUnreachable ExecStatus = "unreachable"
	// ExecStatusOrphan: neither tested nor reached — the "buildable-but-unwired" state.
	ExecStatusOrphan ExecStatus = "orphan"
	// ExecStatusPinned: failing an axis, but covered by a live reasoned exception.
	ExecStatusPinned ExecStatus = "pinned"
)

type ExtractionCandidate added in v0.45.0 

type ExtractionCandidate struct {
	Commands []string           `json:"commands"`
	Handlers []string           `json:"handlers"`
	Files    []string           `json:"files"`
	Imports  []string           `json:"imports,omitempty"`
	Delta    ExtractionDelta    `json:"projected_delta"`
	Reasons  []ExtractionReason `json:"reasons,omitempty"`
}

ExtractionCandidate is one whole same-package component. Multiple commands share a row when their declaration closures overlap and therefore must move together. Reasons is empty exactly for rows in safe.

type ExtractionDelta added in v0.45.0 

type ExtractionDelta struct {
	Commands         int   `json:"commands"`
	Files            int   `json:"files"`
	SourceBytes      int64 `json:"source_bytes"`
	DirectImports    int   `json:"direct_imports"`
	Packages         int   `json:"packages"`
	InternalPackages int   `json:"internal_packages"`
}

ExtractionDelta is a non-mutating projection of source and import-graph removal. Package counts are the packages that become unreachable from cmd/fak, not a build-time claim.

type ExtractionReason added in v0.45.0 

type ExtractionReason struct {
	Code          ExtractionReasonCode `json:"code"`
	Source        string               `json:"source"`
	Symbol        string               `json:"symbol,omitempty"`
	EvidenceCount int                  `json:"evidence_count"`
}

ExtractionReason attributes one closed refusal reason to the source that caused it. Source is always repository-relative; Symbol is present when a declaration, rather than a file-wide mechanism, owns the edge.

type ExtractionReasonCode added in v0.45.0 

type ExtractionReasonCode string

ExtractionReasonCode is the closed vocabulary for refusing source motion. Callers must be able to distinguish a safety decision without parsing prose. 

const (
	ReasonUnresolvedHandler  ExtractionReasonCode = "unresolved-handler"
	ReasonRuntimeOverlap     ExtractionReasonCode = "runtime-tier-overlap"
	ReasonUnknownTierOverlap ExtractionReasonCode = "unknown-tier-overlap"
	ReasonSharedDeclaration  ExtractionReasonCode = "shared-declaration"
	ReasonCgo                ExtractionReasonCode = "hazard-cgo"
	ReasonReflect            ExtractionReasonCode = "hazard-reflect"
	ReasonInit               ExtractionReasonCode = "hazard-init"
	ReasonLinkname           ExtractionReasonCode = "hazard-linkname"
	ReasonEmbed              ExtractionReasonCode = "hazard-embed"
	ReasonSelfExec           ExtractionReasonCode = "hazard-self-exec"
)

type ExtractionReport added in v0.45.0 

type ExtractionReport struct {
	Schema    string                 `json:"schema"`
	Safe      []ExtractionCandidate  `json:"safe"`
	Excluded  []ExtractionCandidate  `json:"excluded"`
	Counts    ExtractionReportCounts `json:"counts"`
	SafeDelta ExtractionDelta        `json:"safe_projected_delta"`
}

ExtractionReport is the checked-in, fail-closed answer to "what TierDev source can leave cmd/fak next?" Every remaining runtime TierDev root appears exactly once in Safe or Excluded.

func BuildRemainingExtractionReport added in v0.45.0 

func BuildRemainingExtractionReport(root string, nodes []ImportNode) (ExtractionReport, error)

BuildRemainingExtractionReport derives the remaining runtime-owned TierDev source plan and projects the safe union against the current runtime graph.

type ExtractionReportCounts added in v0.45.0 

type ExtractionReportCounts struct {
	Commands   int `json:"commands"`
	Safe       int `json:"safe"`
	Excluded   int `json:"excluded"`
	Components int `json:"components"`
}

type FreshnessReport added in v0.44.0 

type FreshnessReport struct {
	Drifts    []Drift     `json:"drifts,omitempty"`
	Unchecked []Unchecked `json:"unchecked,omitempty"`
}

FreshnessReport is the honest form of the freshness fold: the drift findings AND the detectors that never got to look. CheckFreshness's []Drift cannot express the second, so an empty slice from it means only "no drift was PROVEN" — reading that as "the index agrees with reality" is exactly the confusion this report removes.

func (FreshnessReport) Fresh added in v0.44.0 

func (r FreshnessReport) Fresh() bool

Fresh reports whether every detector ran and none found drift — the one state a caller may read as "the index is current". It is a method, not a field, so no caller can hand out a report claiming a freshness it did not earn.

func (FreshnessReport) Verdict added in v0.44.0 

func (r FreshnessReport) Verdict() Verdict

Verdict folds the report to one word. Stale outranks unknown (proven drift is the actionable answer even when some other detector also failed to run) and unknown outranks fresh (an unrun detector may be hiding drift nobody looked for).

type Generation added in v0.37.0 

type Generation struct {
	Stream                 string   `json:"stream"`
	Label                  string   `json:"label"`
	Milestone              string   `json:"milestone"`
	Meaning                string   `json:"meaning"`
	IssueBodySignals       []string `json:"issue_body_signals,omitempty"`
	PromotionEvidence      string   `json:"promotion_evidence,omitempty"`
	DemotionEvidence       string   `json:"demotion_evidence,omitempty"`
	InvalidatingAssumption string   `json:"invalidating_assumption,omitempty"`
}

Generation is one horizon row in the generation-aware development contract. The stream/label/milestone/meaning fields are parsed from docs/generation.md when available; the operational query fields below are the stable issue-intake contract agents need when they ask the self-index instead of re-reading the whole epic.

type GraphLeak added in v0.44.0 

type GraphLeak struct {
	Root      string   `json:"root"`
	Forbidden string   `json:"forbidden"`
	Path      []string `json:"path"`
}

GraphLeak is one shortest witnessed path from a runtime root to a dev-only package. Path includes both the root and forbidden package.

type GraphReport added in v0.44.0 

type GraphReport struct {
	Root          string      `json:"root"`
	PackageCount  int         `json:"package_count"`
	InternalCount int         `json:"internal_count"`
	Leaks         []GraphLeak `json:"leaks"`
}

GraphReport is deterministic machine-readable evidence for an artifact's dependency closure.

func BuildGraphReport added in v0.44.0 

func BuildGraphReport(root string, nodes []ImportNode, packages []PackageOwnership) GraphReport

BuildGraphReport finds shortest runtime-to-dev paths. It deliberately tests reachability, not package-name substrings, so transitive leaks are visible.

type ImportNode added in v0.44.0 

type ImportNode struct {
	ImportPath string   `json:"ImportPath"`
	Imports    []string `json:"Imports"`
}

ImportNode is the stable subset of `go list -deps -json` used by the boundary witness. Tests can construct synthetic graphs without invoking the toolchain.

func LoadImportGraph added in v0.44.0 

func LoadImportGraph(dir, pattern string) ([]ImportNode, error)

LoadImportGraph asks the Go toolchain for the complete dependency graph of a package pattern. The caller controls Dir so this can run in a clean archive.

type IssueView added in v0.37.0 

type IssueView struct {
	Slug  string `json:"slug"`
	Title string `json:"title"`
	Query string `json:"query"`
	Note  string `json:"note,omitempty"`
}

IssueView is one named issue-search view from .github/issue-views.json. Query is GitHub issue-search syntax fed verbatim to `gh issue list --search`; Note explains when to reach for it.

type IssueViews added in v0.37.0 

type IssueViews struct {
	Default string      `json:"default"`
	Limit   int         `json:"limit"`
	Views   []IssueView `json:"views"`
}

IssueViews is the parsed selection surface: the Default view slug, the gh page Limit every query should be paired with (gh defaults to 30, so the file pins an explicit cap), and the named Views in file order (the default view sits first by convention).

func (IssueViews) DefaultView added in v0.37.0 

func (v IssueViews) DefaultView() (IssueView, bool)

DefaultView returns the view named by the Default slug, or false when the file declares no default or the slug names no view.

func (IssueViews) PageLimit added in v0.37.0 

func (v IssueViews) PageLimit() int

PageLimit returns the gh page --limit to pair every query with: the file's declared Limit, or a safe default when it declares none (gh's own default of 30 silently truncates a real backlog).

func (IssueViews) SearchViews added in v0.37.0 

func (v IssueViews) SearchViews(query string) []IssueView

SearchViews returns the views matching the query — by slug (an exact slug match dominates), title, or note — best-first. An empty query returns every view in file order (the default view first by convention), mirroring `fak index leaf`/`verbs`.

type Leaf 

type Leaf struct {
	Name   string `json:"name"`
	Tree   string `json:"tree"`
	Dir    string `json:"dir,omitempty"`
	Exists bool   `json:"exists"`
	Desc   string `json:"desc,omitempty"`
	// Version is the leaf's current module version — "r<rev>+g<sha>", the SAME string
	// `fak version modules` prints — read from the last fak-module-versions/1 ledger
	// row whose module equals this leaf's Dir (#2465). It lets an agent reason about a
	// leaf's staleness from the index payload without shelling out. Empty when the
	// ledger names no version for this Dir, or the ledger is absent: a staleness hint,
	// never load-bearing, so it degrades quietly.
	Version string `json:"version,omitempty"`
	// Status is the CLAIMS.md maturity rollup for this leaf (C2 #1289): how many of
	// the ledger claims that name a path under this leaf are SHIPPED / SIMULATED /
	// STUB. The zero value means the honesty ledger names no capability here.
	Status Status `json:"status"`
	// Approx marks a leaf returned by the trigram fuzzy fallback (#3925) rather than an
	// exact substring hit: the query only NEAR-matched this leaf's name/tree/desc, so a
	// caller can flag it as approximate. False (and omitted) on every exact hit — the
	// fallback engages only when exact scoring found nothing, so exact and approximate
	// results never mix in one response.
	Approx bool `json:"approx,omitempty"`
}

Leaf is one entry of fak's lane taxonomy: a lane/leaf name, the tree glob(s) it owns, the package directory that tree resolves to, whether that directory exists on disk, the one-line description maintained as the inline dos.toml comment, and the module's current derived version (the version-everything spine, #2465).

type Orientation added in v0.37.0 

type Orientation struct {
	Path       string             `json:"path"`
	Lane       string             `json:"lane,omitempty"`
	LaneTree   []string           `json:"lane_tree,omitempty"`
	Tier       *int               `json:"tier,omitempty"`
	TierName   string             `json:"tier_name,omitempty"`
	TestTarget string             `json:"owning_test_target,omitempty"`
	Stamp      string             `json:"stamp,omitempty"`
	LiveLeases []OrientationLease `json:"live_leases,omitempty"`
}

Orientation is the task-scoped convention bundle for one requested path or glob. It answers the facts an agent normally has to infer before editing: lane, arch tier, owning test target, commit stamp, and any live lease that overlaps the tree.

type OrientationLease added in v0.37.0 

type OrientationLease struct {
	ID         string   `json:"id"`
	Holder     string   `json:"holder,omitempty"`
	Tree       []string `json:"tree,omitempty"`
	TTLSeconds int64    `json:"ttl_seconds,omitempty"`
}

OrientationLease is the live-lease projection devindex needs. The CLI fills it from internal/leaseref; tests can inject rows without reaching git.

type OwnershipReport added in v0.44.0 

type OwnershipReport struct {
	Schema     string             `json:"schema"`
	Commands   []CommandOwnership `json:"commands"`
	Packages   []PackageOwnership `json:"packages"`
	Graph      GraphReport        `json:"graph"`
	Extraction ExtractionReport   `json:"remaining_tier_dev_extraction"`
}

OwnershipReport is the complete machine-readable #6020 boundary witness.

func BuildOwnershipReport added in v0.44.0 

func BuildOwnershipReport(root, pattern, importRoot string) (OwnershipReport, error)

BuildOwnershipReport loads the authoritative command catalog and Go import graph from root. It reports current leaks rather than treating them as an error; the migration ratchet decides when the required leak count becomes 0.

type PackageImports added in v0.37.0 

type PackageImports struct {
	ImportPath   string   `json:"import_path"`
	Imports      []string `json:"imports,omitempty"`
	TestImports  []string `json:"test_imports,omitempty"`
	XTestImports []string `json:"xtest_imports,omitempty"`
}

PackageImports is one node from the already-built import graph. Imports, TestImports, and XTestImports are all dependency edges; callers should pass the same folded go-list shape that fak affected uses.

type PackageOwnership added in v0.44.0 

type PackageOwnership struct {
	Path      string       `json:"path"`
	Owner     CommandOwner `json:"owner"`
	Rationale string       `json:"rationale"`
}

PackageOwnership declares an implementation package that belongs only to the development artifact. Runtime must have no direct or transitive path to it.

type PreState added in v0.44.0 

type PreState uint8
const (
	PreUnverified PreState = iota
	PreNone
	PreStructural
	PreRuntime
	PreNotApplicable
)

func (PreState) String added in v0.44.0 

func (p PreState) String() string

type ReasonLexicon added in v0.44.0 

type ReasonLexicon struct {
	Codes map[string]struct{}
}

func BuildReasonLexicon added in v0.44.0 

func BuildReasonLexicon(root string) (*ReasonLexicon, error)

BuildReasonLexicon derives fak's refusal vocabulary from Go source. It deliberately does not use runtime help or a hand-maintained table: reason constants and typed string literals are the source of truth.

type ReferenceIndex added in v0.37.0 

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

ReferenceIndex is the pure, deterministic index behind the blast-radius query. It owns no IO: the CLI/gateway layer gathers go-list packages and symbol refs, then asks this index "what depends on this symbol?" before editing.

func NewReferenceIndex added in v0.37.0 

func NewReferenceIndex(packages []PackageImports, refs []SymbolReference) ReferenceIndex

NewReferenceIndex returns an immutable-by-convention copy of the supplied graph and references. The query methods never mutate caller-owned slices.

func (ReferenceIndex) BlastRadius added in v0.37.0 

func (idx ReferenceIndex) BlastRadius(target SymbolID) BlastRadiusResult

BlastRadius returns direct and transitive packages that depend on target, ranked by shortest distance and then import path. Test imports participate in the graph, matching fak affected's import-edge semantics without running a build.

type SourceClass added in v0.45.0 

type SourceClass string

SourceClass is the fail-closed classification of one executable source component. New motion out of runtime is admitted only from DevOnly; already dev-owned commands remain inventoryable even when they use dev-only mechanisms. 

const (
	SourceRuntime   SourceClass = "runtime"
	SourceDevOnly   SourceClass = "dev-only"
	SourceMixed     SourceClass = "mixed"
	SourceHazardous SourceClass = "hazardous"
)

type SourceOwnership added in v0.45.0 

type SourceOwnership struct {
	Name           string
	Aliases        []string
	Owner          CommandOwner
	Handler        string
	SourceOrigin   string
	DispatchTarget string
	Class          SourceClass
}

SourceOwnership is the generated authority shared by fak-dev dispatch and runtime's refusal/handoff boundary.

func ExtractDevSourceOwnership added in v0.45.0 

func ExtractDevSourceOwnership(root string) ([]SourceOwnership, error)

ExtractDevSourceOwnership derives ownership from the real fak-dev switch and resolves each handler back to its declaration using the same AST package model as verb-surface extraction. Non-dev cases are ignored; ambiguous or hazardous dev cases fail closed instead of entering the generated runtime boundary.

type Status 

type Status struct {
	Shipped   int `json:"shipped"`
	Simulated int `json:"simulated"`
	Stub      int `json:"stub"`
}

Status is a per-leaf rollup of the CLAIMS.md maturity tags that bind to a leaf. It answers the recurring "what's shipped vs simulated vs stub for X" without reading the ledger prose.

func (Status) Total 

func (s Status) Total() int

Total is the number of ledger claims bound to the leaf (across all three tags).

type SurfaceLeaf added in v0.44.0 

type SurfaceLeaf struct {
	Words    []string `json:"words"`
	Aliases  []string `json:"aliases,omitempty"`
	Synopsis string   `json:"synopsis,omitempty"`
	Fn       string   `json:"fn,omitempty"`
	Origin   string   `json:"origin"`
	Planned  bool     `json:"planned,omitempty"`
	Tier     VerbTier `json:"tier,omitempty"`
	Packages []string `json:"packages,omitempty"`
	// InHelp is whether fak's own help wall mentions this path. It is derived from
	// the help SOURCE, never from running the binary, so the comparison is between
	// two readings of the same tree rather than between a tree and a build.
	InHelp bool       `json:"in_help"`
	Pre    SurfacePre `json:"pre"`
}

SurfaceLeaf is one invocable command path — `fak commit`, `fak accounts add`, `fak worktree worker prepare`. The leaf, not the verb, is the unit this page has to be complete over: a doc that lists verbs and is silent about sub-verbs is exactly the state that sends a reader to a bespoke script when the verb they needed already existed one word deeper.

func (SurfaceLeaf) Depth added in v0.44.0 

func (l SurfaceLeaf) Depth() int

Depth is the word count: 1 for a verb, 2+ for a sub-verb.

func (SurfaceLeaf) IsVerb added in v0.44.0 

func (l SurfaceLeaf) IsVerb() bool

IsVerb reports whether this leaf is a top-level verb.

func (SurfaceLeaf) Key added in v0.44.0 

func (l SurfaceLeaf) Key() string

Key is the path without the binary name — the map key the curated tables use.

func (SurfaceLeaf) Path added in v0.44.0 

func (l SurfaceLeaf) Path() string

Path is what an operator types.

func (SurfaceLeaf) Verb added in v0.44.0 

func (l SurfaceLeaf) Verb() string

Verb is the top-level verb this leaf hangs off.

type SurfacePre added in v0.44.0 

type SurfacePre struct {
	State PreState
	Codes []string
	Notes []string
}

type SymbolID added in v0.37.0 

type SymbolID struct {
	Package string `json:"package"`
	Symbol  string `json:"symbol"`
}

SymbolID names a Go symbol by import path plus symbol name. The package path is the full import path known to the import graph, not only the local package name.

func ParseSymbolID added in v0.37.0 

func ParseSymbolID(query string) (SymbolID, error)

ParseSymbolID parses <pkg>.<Symbol>. It splits at the last dot so module hosts such as github.com stay part of the package path.

func (SymbolID) String added in v0.37.0 

func (s SymbolID) String() string

String renders the CLI/query spelling: <pkg>.<Symbol>.

type SymbolReference added in v0.37.0 

type SymbolReference struct {
	FromPackage string   `json:"from_package"`
	Target      SymbolID `json:"target"`
	Test        bool     `json:"test,omitempty"`
}

SymbolReference says FromPackage directly references Target. Test marks a reference seen only in test files; the blast-radius closure treats it as a real dependency seed because test-only callers still need re-verification.

type Unchecked added in v0.44.0 

type Unchecked struct {
	Detector DriftKind `json:"detector"`
	Source   string    `json:"source"`
	Reason   string    `json:"reason"`
}

Unchecked is one detector that could not run: which detector, the repo-relative source it needed, and the read error that stopped it. It is deliberately NOT a Drift — an unread source is not evidence that the index disagrees with the tree, and folding it into the drift slice would red a build over a check that never happened. It is what lets a report be non-stale without being fresh.

type Verb 

type Verb struct {
	Name     string   `json:"name"`
	Synopsis string   `json:"synopsis"`
	Aliases  []string `json:"aliases,omitempty"`
	Lane     string   `json:"lane,omitempty"`
	Doc      string   `json:"doc,omitempty"`
	// Tier is the epic-#2228 CLI concept tier (frontdoor|dev|hidden), stamped
	// from the verbTiers table (tiers.go) — never authored per manifest entry,
	// so the classification keeps its one home. Empty only for a curated entry
	// whose verb is not (yet) dispatched.
	Tier VerbTier `json:"tier,omitempty"`
}

Verb is one entry of the structured CLI-verb catalog: the verb name as typed (`fak <Name>`), the one-line synopsis shown in usage, optional command aliases that route to the same handler (the extra strings in a `case "leaf", "leaves":`), the owning lane/leaf the handler's code lives under, and an optional doc-map path for the deeper reference. It is the parseable replacement for a raw usage string.

func OwnershipVerbs added in v0.44.0 

func OwnershipVerbs(verbs []Verb) []Verb

OwnershipVerbs returns the complete command set, including pre-switch namespace-only commands, sorted by canonical spelling.

func SupplementalDevVerbs added in v0.44.0 

func SupplementalDevVerbs() []Verb

SupplementalDevVerbs are pre-switch namespace commands that are intentionally absent from main.go's top-level switch. Keeping them beside the ownership contract prevents that implementation detail from making the inventory incomplete.

func (Verb) Spellings 

func (v Verb) Spellings() []string

Spellings returns the verb's canonical name plus every alias — the full set of argv[1] tokens that route to this verb. The freshness gate joins on this set so a main.go `case "a", "b":` with one manifest entry covering both does not red.

type VerbStyleKind added in v0.38.0 

type VerbStyleKind string

VerbStyleKind classifies a verb-catalog style defect. The tokens are stable so a baseline entry keyed on one survives a synopsis reword that keeps the same defect. 

const (
	// VerbStyleUncataloged marks a dispatched verb carrying the derived fallback
	// synopsis (verbs.go's "not yet cataloged — …") — no curated verbManifest entry.
	VerbStyleUncataloged VerbStyleKind = "uncataloged"
	// VerbStyleSynopsisWidth marks a curated synopsis wider than VerbSynopsisMaxRunes.
	VerbStyleSynopsisWidth VerbStyleKind = "synopsis-width"
	// VerbStyleSynopsisLead marks a sentence-case leading capital (a single leading
	// upper-case letter) — the house voice is a lowercase lead; a proper noun or
	// acronym (two or more upper-case letters in the first token) is allowed.
	VerbStyleSynopsisLead VerbStyleKind = "synopsis-lead"
	// VerbStyleTrailingPeriod marks a synopsis that ends with a period (the manifest
	// voice is a bare clause, no terminal punctuation).
	VerbStyleTrailingPeriod VerbStyleKind = "trailing-period"
	// VerbStyleNotation marks unbalanced () or [] notation delimiters in a synopsis.
	VerbStyleNotation VerbStyleKind = "notation"
)

type VerbStyleViolation added in v0.38.0 

type VerbStyleViolation struct {
	Verb   string        `json:"verb"`
	Kind   VerbStyleKind `json:"kind"`
	Detail string        `json:"detail"`
}

VerbStyleViolation is one style defect found on a catalog verb.

func CheckVerbCatalogStyle added in v0.38.0 

func CheckVerbCatalogStyle(verbs []Verb) []VerbStyleViolation

CheckVerbCatalogStyle returns every style violation across the given catalog verbs (from Catalog.Verbs()) EXCLUDING the frozen grandfathered baseline. A nil result is the green state the gate enforces: no style debt has entered since the baseline was pinned. Findings are sorted by verb then kind for a stable diff.

type VerbSurface added in v0.44.0 

type VerbSurface struct {
	Leaves []SurfaceLeaf `json:"leaves"`
	// Lexicon is the closed refusal vocabulary the REFUSES column is resolved
	// against, with each code's declaring site. It is derived, never hand-listed.
	Lexicon *ReasonLexicon `json:"-"`
	// Files is the count of cmd/fak non-test files parsed — printed on the page so
	// a shrunken surface is attributable to a shrunken input rather than mysterious.
	Files int `json:"files"`
}

VerbSurface is the whole derived command tree plus the provenance of the refusal vocabulary it was graded against.

func ExtractVerbSurface added in v0.44.0 

func ExtractVerbSurface(root string) (*VerbSurface, error)

ExtractVerbSurface walks cmd/fak's own dispatch switches and returns the complete command surface with its refusal column resolved.

root is the repository root. The refusal lexicon is derived from the same tree (dos.toml's closed [reasons.*] registry plus every reason-shaped constant declared under internal/ and cmd/fak), so the page never asserts a code the tree does not declare.

func (*VerbSurface) Markdown added in v0.44.0 

func (s *VerbSurface) Markdown() []byte

Markdown renders the generated operator page. Coverage counts are in the artifact itself so a reader can distinguish known preconditions from gaps.

type VerbTier added in v0.37.0 

type VerbTier string

VerbTier is one of the three CLI concept tiers of epic #2228. 

const (
	// TierFrontdoor — the product surface: what an adopter or operator of the
	// kernel touches. Stays small (the gate test holds the ceiling); listed by
	// the compact `fak help`.
	TierFrontdoor VerbTier = "frontdoor"
	// TierDev — internal dev/fleet tooling: repo-workflow verbs, scorecards,
	// Slack surfaces, benches, loop/dispatch plumbing. The `fak dev <verb>`
	// namespace (C2) is its canonical spelling.
	TierDev VerbTier = "dev"
	// TierHidden — internal re-exec/hook seams spawned by fak itself, never
	// typed by a person and never listed.
	TierHidden VerbTier = "hidden"
)

func TierOf added in v0.37.0 

func TierOf(name string) (VerbTier, bool)

TierOf resolves a verb token (canonical name OR any alias spelling, any case) to its tier. Alias spellings canonicalize through the curated verb manifest first (`-h` -> help, `benchloop` -> bench-loop); an uncataloged token falls back to a direct table lookup under its own spelling. ok=false means the token is not a classified verb — for a LIVE dispatch token that is exactly the drift tiers_test.go reds on, so callers may treat it as "unknown verb", not "dev by default". Package-level (no Catalog) because the answer must not require a readable repo.

type Verdict added in v0.44.0 

type Verdict string

Verdict is a freshness probe's answer, and it carries THREE values rather than two (#5962). "I checked and found no drift" and "I could not check" are both non-stale, yet only the first may be reported as fresh: a probe that hands back the reassuring answer for a detector that never ran is the tool lying to its own operator. Only VerdictStale is evidence of drift, so only it may drive a gate or a self-heal. 

const (
	// VerdictFresh: every detector ran and none of them found drift.
	VerdictFresh Verdict = "fresh"
	// VerdictStale: at least one detector PROVED drift. The only actionable verdict.
	VerdictStale Verdict = "stale"
	// VerdictUnknown: nothing proved drift, but at least one detector could not run,
	// so the tree may disagree with the index in a way nothing looked at.
	VerdictUnknown Verdict = "unknown"
)

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.