conceptcatalog

package
v0.44.0 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	GeneratedReadme = "docs/concept-disambiguation-scorecard/README.md"
	// GeneratedIndex is the reverse lookup: every NAME a reader can meet in the tree
	// mapped back to the concept it denotes, plus the twins that name is mistakable
	// for. It is generated from the same catalog as the scorecard and must age with
	// it - a fresh scorecard beside a stale index would answer "what is this concept"
	// correctly while answering "which concept is this name" from a retired catalog.
	GeneratedIndex = "docs/concept-disambiguation-scorecard/INDEX.md"
	// RegenerateCommand is the WORKTREE-mode cure, and it answers CheckFresh only.
	// The generator derives its numbers by walking the whole workspace, so run from
	// the repo root it scores every peer's unsaved edit too - a different tree from
	// the one CheckGitTree scores, and therefore a different answer.
	RegenerateCommand = "fak concept generate"
	// RegenerateStagedCommand is the TREE-mode cure, and it is the only one that can
	// clear a CheckGitTree refusal: it regenerates inside the same clean-room export
	// of the staged tree that CheckGitTree scored, then writes the artifacts back to
	// the worktree for the operator to stage (#5829).
	//
	// Bare, it resolves the CALLER's index. That is not good enough for a refusal to
	// quote: a pre-commit hook runs against git's temporary partial-commit index (HEAD
	// plus the pathspec), while the operator who reads the refusal runs the cure in a
	// plain shell, where the same words resolve the SHARED .git/index - HEAD plus
	// whatever every peer left staged. Measured on this trunk, those two trees give
	// different artifacts and the retry refuses again. Refusals must therefore print
	// RegenerateStagedCommandFor, never this constant alone.
	RegenerateStagedCommand = "fak concept generate --staged"
)
View Source 
const DataRel = "tools/concept_disambiguation_scorecard.data"

Variables

This section is empty.

Functions

func Apply 

func Apply(plan Plan) error

func ProductionCorpus 

func ProductionCorpus(root, raw string) (bool, error)

ProductionCorpus reports whether a token is grounded outside tests and build-tag-only files.

func ProductionCorpusMany 

func ProductionCorpusMany(root string, raw []string) (map[string]bool, error)

ProductionCorpusMany resolves many grounding tokens with one bounded tree walk. A per-row walk made current-catalog validation scale as rows times corpus size.

The walk holds one file's tokenized text at a time and stops as soon as every token is grounded. Concatenating the whole tree into a single buffer instead made `fak concept position` peak at 20.79GB RSS over 112s on this repo, because ~98% of the bytes it matched came from in-tree run artifacts rather than source. Matching per file is exactly equivalent to matching the concatenation: token() keeps only [a-z0-9], so no want can span the "\n" that separates two tokenized lines.

func Regenerate added in v0.44.0 

func Regenerate(root string) ([]string, error)

Regenerate runs the canonical concept writer and returns every artifact it refreshed. Classifications live in the input catalog, so generation reads and preserves the same source that concept classify updates.

func RegenerateFromGitTree added in v0.44.0 

func RegenerateFromGitTree(root, treeish, dest string) ([]string, error)

RegenerateFromGitTree runs the generator against the same clean-room export of treeish that CheckGitTree scores, and writes every tracked artifact under dest (the repo root when empty). It returns the tracked paths written, for the caller to name in its own pathspec - staging is the operator's call on a shared trunk.

This is the cure CheckGitTree's refusal prints. The extraction is shared with the check by construction, so the bytes written here are the bytes the check compared against; regenerating from the worktree instead answers a different tree and leaves the refusal standing.

func RegenerateStagedCommandFor added in v0.44.0 

func RegenerateStagedCommandFor(treeish string) string

RegenerateStagedCommandFor pins the tree-mode cure to the exact tree that was scored, so the printed command means the same thing in the operator's shell as it did inside the hook (#5829).

Safe to hand out because git write-tree does not merely hash the index, it WRITES the tree object into the repository - so the SHA still resolves after the hook's temporary index is gone. An empty treeish degrades to the bare command rather than emitting a dangling `--tree`, which would be worse than imprecise.

func RelevantPath 

func RelevantPath(path string) bool

RelevantPath reports whether a change can affect the disambiguation snapshot.

func RenderFreshness added in v0.44.0 

func RenderFreshness(stdout, stderr io.Writer, label, treeNote string, res FreshnessResult, err error, asJSON bool) int

RenderFreshness writes one freshness answer and returns the process exit code.

label names the command for its diagnostics ("fak concept freshness"); treeNote is the noun phrase for the tree that was checked (" in the staged tree", or empty for the worktree). The JSON envelope is written from the PROBE, never from the raw result, so the unknown verdict reaches stdout instead of a stale `"fresh":true`. Unknown exits 1 like stale does — a check that could not run is not a pass — but it says so in different words, because the cure for "regenerate the artifacts" and the cure for "the checker itself is broken" are not the same cure.

Types

type Catalog 

type Catalog struct {
	Meta Metadata
	Rows []Row
	Dir  string
}

func Load 

func Load(root string) (Catalog, error)

func LoadDir 

func LoadDir(dir string) (Catalog, error)

type Change 

type Change struct {
	Path        string `json:"path"`
	BeforeCount int    `json:"before_count,omitempty"`
	AfterCount  int    `json:"after_count,omitempty"`
	Content     []byte `json:"-"`
}

type ClassifyRequest 

type ClassifyRequest struct{ Family, Token, Category, Reason string }

type Diagnostic 

type Diagnostic struct {
	File   string `json:"file"`
	RowID  string `json:"row_id,omitempty"`
	Field  string `json:"field"`
	Value  string `json:"value,omitempty"`
	Repair string `json:"repair"`
	Code   string `json:"code"`
}

func Validate 

func Validate(c Catalog) []Diagnostic

func ValidateStrict 

func ValidateStrict(c Catalog) []Diagnostic

ValidateStrict adds the authoring-time invariant that distinct_from references use stable IDs. Validate remains compatible with the inherited catalog while new writes are held to the stricter contract.

func ValidateTree 

func ValidateTree(c Catalog, root string) []Diagnostic

ValidateTree adds the cross-tree grounding invariant: a row cannot be grounded exclusively by tests or build-tag-only source. It is separate from ValidateStrict because in-memory fixture catalogs do not necessarily have a repository root.

func (Diagnostic) Error 

func (d Diagnostic) Error() string

type Family 

type Family struct {
	ID      string   `json:"id"`
	Name    string   `json:"name"`
	Roots   []string `json:"roots"`
	Ignore  []string `json:"ignore"`
	Exclude []string `json:"exclude"`
}

type FreshnessProbe added in v0.44.0 

type FreshnessProbe struct {
	Verdict    FreshnessVerdict `json:"verdict"`
	Fresh      bool             `json:"fresh"`
	StalePaths []string         `json:"stale_paths,omitempty"`
	Regenerate string           `json:"regenerate"`
	// Unchecked carries the reason the probe could not run, in the words the error
	// used, so a --json consumer sees the cause rather than only the absence.
	Unchecked string `json:"unchecked,omitempty"`
}

FreshnessProbe is the JSON envelope every freshness surface emits. Fresh and StalePaths are kept for the consumers that already read them, and Fresh is false under VerdictUnknown, so a reader that only greps `"fresh":true` still cannot be told a check succeeded when it did not.

func ProbeFreshness added in v0.44.0 

func ProbeFreshness(res FreshnessResult, err error) FreshnessProbe

ProbeFreshness folds a check's (result, error) pair into a verdict. An error always outranks the result's own Fresh flag: a check that failed reports what it knows, which is nothing. This is a constructor rather than a struct literal at each call site precisely because the defect it fixes was call sites reading the two halves of the pair in the wrong order.

func (FreshnessProbe) JSON added in v0.44.0 

func (p FreshnessProbe) JSON() []byte

JSON encodes the probe envelope.

type FreshnessResult 

type FreshnessResult struct {
	Fresh      bool     `json:"fresh"`
	StalePaths []string `json:"stale_paths,omitempty"`
	Regenerate string   `json:"regenerate"`
}

FreshnessResult describes deterministic generated-artifact freshness.

func CheckFresh 

func CheckFresh(root string) (FreshnessResult, error)

CheckFresh regenerates in scratch space and compares every tracked generated artifact.

func CheckGitTree 

func CheckGitTree(root, treeish string) (FreshnessResult, error)

CheckGitTree checks a committed or staged git tree, immune to peer working-tree files. An empty treeish means the current index (git write-tree).

The result's Regenerate names the tree-scoped cure, never RegenerateCommand: a refusal produced by scoring a git tree can only be cleared by regenerating from that same tree, and the worktree command answers a tree this check never looked at (#5829).

The treeish is resolved HERE rather than inside materializeGitTree so the resolved SHA can be baked into that cure. Naming the tree is what makes the printed command portable out of the hook's environment: "the current index" denotes git's temporary partial-commit index to the hook and the shared .git/index to the operator reading the refusal, and on a multi-session trunk those are different trees with different artifacts.

func (FreshnessResult) JSON 

func (r FreshnessResult) JSON() []byte

type FreshnessVerdict added in v0.44.0 

type FreshnessVerdict string

FreshnessVerdict is a freshness answer in one word. Three values, not two: "I compared the bytes and they match" and "I never got to compare" are both non-stale, and only the first may be reported as fresh. 

const (
	// VerdictFresh: the check ran and every tracked artifact matched a regeneration.
	VerdictFresh FreshnessVerdict = "fresh"
	// VerdictStale: the check ran and named the artifacts that drifted. The only
	// verdict that may drive a refusal or a regeneration.
	VerdictStale FreshnessVerdict = "stale"
	// VerdictUnknown: the check could not run, so it proved neither freshness nor
	// drift. Non-stale, and emphatically not fresh.
	VerdictUnknown FreshnessVerdict = "unknown"
)

type InvariantResult 

type InvariantResult struct {
	Freshness      FreshnessResult    `json:"freshness"`
	SemanticValid  bool               `json:"semantic_valid"`
	CriticalClean  bool               `json:"critical_clean"`
	ClarityDebt    int                `json:"clarity_debt"`
	Coverage       float64            `json:"coverage"`
	CoverageDebt   int                `json:"coverage_debt"`
	FamilyCoverage map[string]float64 `json:"family_coverage,omitempty"`
	Detail         string             `json:"detail,omitempty"`
}

func CheckInvariant 

func CheckInvariant(root string) (InvariantResult, error)

CheckInvariant validates freshness, semantic catalog structure and scorecard critical state.

type Metadata 

type Metadata struct {
	Families []Family `json:"families"`
}

type Plan 

type Plan struct {
	Mode              string   `json:"mode"`
	Family            string   `json:"family"`
	BeforeFamilyCount int      `json:"before_family_count"`
	AfterFamilyCount  int      `json:"after_family_count"`
	Files             []string `json:"files"`
	Changes           []Change `json:"-"`
}

func AddGeneratedArtifacts 

func AddGeneratedArtifacts(c Catalog, plan Plan) (Plan, error)

AddGeneratedArtifacts runs the canonical generator against a shadow data directory containing the planned mutations. It never alters the workspace.

func PlanClassify 

func PlanClassify(c Catalog, req ClassifyRequest) (Plan, error)

func PlanPosition 

func PlanPosition(c Catalog, req PositionRequest) (Plan, error)

type PositionRequest 

type PositionRequest struct {
	ID, Canonical, Family, Definition, Distinction, Kind, Grounding, GroundingKind, Glossary string
	DistinctFrom, Aliases                                                                    []string
	RowFile                                                                                  string
}

type Row 

type Row struct {
	ID             string   `json:"id"`
	Canonical      string   `json:"canonical"`
	Family         string   `json:"family"`
	Kind           string   `json:"kind"`
	Definition     string   `json:"definition"`
	Distinction    string   `json:"distinction"`
	DistinctFrom   []string `json:"distinct_from"`
	Aliases        []string `json:"aliases"`
	Grounding      string   `json:"grounding"`
	GroundingKind  string   `json:"grounding_kind"`
	GlossaryAnchor string   `json:"glossary_anchor"`
	Parent         string   `json:"parent"`
	Verdict        string   `json:"verdict"`
	Gaps           []string `json:"gaps"`
	Source         string   `json:"-"`
	Index          int      `json:"-"`
}

type UnseparatedPair 

type UnseparatedPair struct {
	A     string `json:"a"`
	B     string `json:"b"`
	Kind  string `json:"kind"`
	Why   string `json:"why"`
	State string `json:"state"`
}

UnseparatedPair is one pair of concepts a reader can confuse whose boundary is not drawn from both sides. The pairs are DISCOVERED by the scorecard from the catalog's own names - the rule lives there once, so the authoring gate and the grader cannot drift into two different definitions of confusable.

func (UnseparatedPair) Other 

func (p UnseparatedPair) Other(id string) (string, bool)

Other returns the id at the far end of the pair from id, and whether id is in it.

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.