Documentation
¶
Overview ¶
Package check compares the functions in a source file against the mined conventions of the subsystem the file belongs to and reports the ones they break. It enforces only pattern types whose evidence is crisp — who calls what, what a file imports, how a file begins — at rule confidence with meaningful support, and stays silent whenever the evidence is not clear-cut: a false positive costs far more than a missed violation, because the first one teaches people to turn the check off.
Index ¶
Constants ¶
const ( DefaultMinConfidence = 0.98 DefaultMinSupport = 10 // MinPairingLift is how much more often the paired helper must be called // by functions that call the first than by functions that do not, for a // helper_pairing claim to count as a convention rather than an artifact // of a ubiquitous helper: when everything here calls Errorf, everything // that calls Close "pairs" with it too. MinPairingLift = 0.30 // MinExpectedCallers is how many functions (or files) a scope would be // expected to have calling a helper (importing a module) at the // repo-wide rate before its absence from the scope counts as a // convention rather than a small sample: ten functions none of which // call something that a tenth of the repository calls is one expected // caller, not a rule. MinExpectedCallers = 5 )
Defaults for Options. At the miner's rule tier of 0.95 one in twenty of the scope's own functions is a counter-example by definition, so the check holds new code to 0.98 — at most one exception per fifty — and the miner's subsystem support floor. The two gates below tighten what counts as evidence.
const ConfigFile = ".opentuple.json"
ConfigFile is the repository-level configuration file, read from the repository root. Every field is optional. Command-line flags override it.
Variables ¶
This section is empty.
Functions ¶
func Enforces ¶
Enforces reports whether check, configured by opts, holds new code to the stored pattern: it clears the confidence and support floors, its type is not disabled, and it passes the per-type evidence gates. A pattern whose claim does not decode is never enforced.
func Format ¶
Format renders violations as the plain-text report an agent reads: one block per violation with the file and line, the rule, its evidence, and an example that follows it, then a one-line summary telling the reader what to do. Paths are spelled relative to repoRoot. No violations renders "".
func Locate ¶
Locate returns the root of the indexed repository containing path, spelled as the index spells it: the nearest ancestor directory with an index under ~/.opentuple, tried with path as given and again with symlinks resolved (macOS spells /tmp as /private/tmp). It wraps store.ErrNoIndex when no ancestor is indexed.
func ResolveInRepo ¶
ResolveInRepo returns path as an absolute path spelled under repoRoot the way the index spells it. A path outside repoRoot is retried with symlinks resolved on both sides and respelled under repoRoot on a match (the path's parent is resolved when the path itself does not exist yet); otherwise it is an error, never a silent fall-through.
Types ¶
type Config ¶
type Config struct {
MinConfidence float64 `json:"min_confidence"`
MinSupport int `json:"min_support"`
Disable []string `json:"disable"` // rule types never enforced
Enable []string `json:"enable"` // opt-in rule types: io_boundary, duplicate, helper_absence, import_absence
IgnorePaths []string `json:"ignore_paths"` // repo-relative glob patterns check skips
}
Config is what a repository may tune about the check. Rule types are the claim type names a violation report uses (helper_pairing, doc_comment, ...) plus "duplicate" and "io_boundary". Enabling helper_absence or import_absence enforces every mined absence, not only banned builtins.
func LoadConfig ¶
LoadConfig reads repoRoot's configuration file. A missing file yields the zero Config; a malformed one is an error, so a typo never silently disables everything or nothing.
type Options ¶
type Options struct {
MinConfidence float64
MinSupport int
Disabled map[string]bool
IOBoundary bool
Duplicates bool
Absences bool
IgnorePaths []string
}
Options tunes which mined patterns check enforces. Zero values take the defaults above. Disabled names rule types never enforced; IOBoundary and Duplicates opt into the I/O boundary and clone rules, which are off by default because repositories copy functions on purpose (API versions, per-binary copies, compatibility shims) more often than by accident; Absences opts into every mined absence, where by default only the builtins repositories ban (panic, print, eval, console.log, ...) are enforced, because a package that never called httptest.NewRecorder or imported fmt usually never needed to; IgnorePaths are repo-relative globs of files never checked.
type Violation ¶
type Violation struct {
File string // absolute path, spelled as the index spells it
Line int // first line of the function, or of the offending import
Function string // "" for a file-level violation
Type string // rule type, as an ignore directive or config disable names it
Headline string // "<function> calls Lock but never Unlock"
Rule string // the convention in one sentence
Evidence string // the counts behind it
Example string // one indexed function or file that follows it; "" when none was located
}
Violation is one function (or, for file-level rules, one file) breaking one rule, carrying everything an agent needs to fix it without further context.
func File ¶
func File(ctx context.Context, s *store.Store, repoRoot, filePath string, source []byte, opts Options) ([]Violation, error)
File checks every function in source — the content of filePath, which must be absolute and spelled as the index spells paths under repoRoot — against the patterns mined for its scope, and the file itself against the file- level patterns. A scope with no mined patterns yields nothing: silence, not a guess. Generated files are never checked.
func Repository ¶
func Repository(ctx context.Context, s *store.Store, repoRoot string, opts Options) ([]Violation, int, error)
Repository checks every indexed, still-present file of the repository against its rules, as a self-audit: what it reports is the repository's own code disagreeing with the conventions mined from it.
Source Files