Documentation
¶
Overview ¶
Package invariant extracts policy-bearing statements from Go source files in a three-tier confidence ladder:
Tier 1: existing markers — // CRITICAL, // IMPORTANT, // WARNING,
// Deprecated:
Tier 2: new convention markers — // INVARIANT:, // CONSENSUS:,
// SECURITY:
Tier 3: heuristics — panic(...) / fmt.Errorf("...") with policy
keywords (must, cannot, consensus, validator, byzantine).
The extractor parses Go via the standard go/parser package; it returns each detected invariant as a types.Chunk with ChunkKind = ChunkInvariant. The caller pairs invariants back to source chunks by file + line overlap.
False-positive control:
- Tier 3 is suppressed in *_test.go files.
- A per-file cap (MaxTier3PerFile, default 10) prevents a single test fixture or builder from saturating the index.
Index ¶
Constants ¶
const MaxTier3PerFile = 10
MaxTier3PerFile caps heuristic invariants per file. Bounded to prevent test fixtures or boilerplate panic chains from flooding the index. Override via Options for special-case files.
Variables ¶
This section is empty.
Functions ¶
func AttachRefs ¶
func AttachRefs(chunks []types.Chunk, results []Result, refs []types.InvariantRef)
AttachRefs decorates each source chunk with InvariantRefs whose line range overlaps the chunk's [StartLine, EndLine]. Mutates chunks in place. The chunk slice and refs slice come from the same file; chunk IDs in refs must already be present in the emitted invariant chunks.
All-line invariants (Marker == "CRITICAL" at top of file, etc.) that fall outside every source chunk's span attach to no one — they are still indexed as ChunkInvariant on their own row.
func EmitChunks ¶
EmitChunks converts a slice of Results into ChunkInvariant chunks plus a list of back-pointer InvariantRefs the caller should staple onto matching source chunks. file is the chunk's File field; commit is propagated for citation parity.
Each invariant chunk's ID is deterministic over (file, line range, SHA256 of text), so re-running the extractor on unchanged source produces the same chunk IDs (Upsert behaves correctly).
Types ¶
type Options ¶
type Options struct {
// MaxTier3PerFile bounds heuristic detections. 0 → MaxTier3PerFile.
MaxTier3PerFile int
// SkipTier3InTests omits heuristic detection in *_test.go.
// Defaults true; set false only for fixture inspection.
SkipTier3InTests bool
}
Options tune extraction behavior.
type Result ¶
type Result struct {
Tier types.InvariantTier
Marker string // "CRITICAL", "INVARIANT", "panic", "Errorf", ...
StartLine int // 1-based, inclusive
EndLine int // 1-based, inclusive
Text string // the comment / call source text
}
Result is one extracted invariant.
Source Files