Documentation
¶
Overview ¶
Package check implements seven of the ten record-layer checks behind nova-check; the other three live elsewhere because none is about one self repo. dogfood is pkg/dogfood, because its records are receipts about the family's tools; hygiene is pkg/hygiene, because its subject is a branch's range and the accept gate and the merge lane run the same function over it; convergence is internal/converge, because its records are readings of the work itself rather than of a self repo. Each function returns (result, failures, error): failures mean the check ran and said NO (exit 1 at the CLI); a non-nil error means the check could not run at all (exit 2). See SPEC.md for what each check asserts and, as importantly, what it deliberately does not.
Index ¶
- Constants
- func Attest(home, manifest string) (Attestation, []Failure, error)
- func FloorDenyExts() ([]string, error)
- func FloorDenyNames() (names map[string]bool, prefixes []string, err error)
- func IsMarkdown(filename string) bool
- func LoadAllowlistFile(path string) ([]string, error)
- func ParseAllowlist(content string) []string
- func ParseDenyList(spec string) ([]string, error)
- func ParseIgnoreSpec(specs []string) ([]string, error)
- func ParseLedger(raw []byte) ([]Anchor, []Failure, error)
- func ResolveRoot(root string) (abs, resolved string, err error)
- func StripCode(text string) string
- type Anchor
- type Attestation
- type BrokenLink
- type Failure
- func Corpus(root, ledgerPath string, minAnchors int, as []Anchor) ([]Failure, error)
- func Floors(core, source string) (floors int, failures []Failure, err error)
- func Kernel(file string, maxBytes int64) (measured int64, failures []Failure, err error)
- func KernelTokens(file string, maxTokens int64, bytesPerToken float64) (measured, tokens int64, failures []Failure, err error)
- func NoCode(opts NoCodeOptions) (scanned int, findings []Failure, err error)
- type LinksResult
- type NoCodeOptions
- type SpellingChecker
- type SpellingFinding
- type SpellingOptions
- type SpellingResult
Constants ¶
const ( DenyFloor = "floor-list" DenyReplaced = "--deny-ext" DenyExtended = "floor-list+--deny-ext-add" )
Deny-list provenance, reported with every finding so that neither a red nor a green hides the basis it was reached on.
These labels are read in two places: in a finding's REASON -- `code extension .py (floor-list)` -- and on the `deny-list=` and `source=` FIELDS of nova-check's summary lines. SPEC.md's rule is that a field is ONE token, so each label IS one token, with no whitespace and no "=": the same spelling reads the same in both places, and the field needs no escape to be one (a label with a blank printed as `floor\x20list`, which a scanner could count and a reader had to decode). The caller still renders them through oneline.Field, which leaves a token like these unchanged.
Variables ¶
This section is empty.
Functions ¶
func Attest ¶
func Attest(home, manifest string) (Attestation, []Failure, error)
Attest verifies that every file listed in the manifest exists under home, is a regular file, and is non-empty, and computes the boot attestation: file count, total bytes, and a SHA-256 binding paths, order, and contents. Any failure leaves the attestation zero-valued; a partial self must not produce a pasteable line.
func FloorDenyExts ¶ added in v0.5.0
FloorDenyExts returns the embedded floor deny-list, sorted.
It returns an error rather than an empty list if the data is unreadable or empty: a guard that cannot determine what it forbids must refuse, not pass.
func FloorDenyNames ¶ added in v0.6.0
FloorDenyNames returns the embedded floor name list as an exact-basename set and an ordered list of path prefixes.
It returns an error rather than empty results if the data is unreadable or empty, for the same reason FloorDenyExts does: a guard that cannot determine what it forbids must refuse, not pass.
func IsMarkdown ¶ added in v1.2.3
IsMarkdown reports whether the filename has a markdown extension.
func LoadAllowlistFile ¶ added in v1.2.3
LoadAllowlistFile loads an allowlist from a file.
func ParseAllowlist ¶ added in v1.2.3
ParseAllowlist parses allowlist content: one word per line, ignoring blank lines and # comments.
func ParseDenyList ¶ added in v0.5.0
ParseDenyList reads a deny-list specification: either a comma-separated list of extensions, or "@path" naming a file with one extension per line.
func ParseIgnoreSpec ¶ added in v1.2.3
ParseIgnoreSpec parses ignore specifications, which may contain comma-separated words or "@path" referencing a file with one word per line. Words are lowercased and trimmed.
func ParseLedger ¶ added in v0.7.0
ParseLedger reads the anchor rows out of a ledger's markdown.
THE TABLE DECLARES ITS OWN SHAPE; THIS DOES NOT GUESS AT ONE. That is the whole parsing rule, and it replaced two earlier attempts that each failed in one direction: requiring outer pipes silently dropped rows a renderer accepts, and then accepting any pipe-bearing line read ordinary prose and unrelated tables as anchors. Both are the same mistake — a heuristic about what a table looks like — so the heuristic is gone.
A run is a block of consecutive non-blank lines outside any fence, at least one of which bears pipes. A run is an ANCHOR TABLE only when its second line is a separator whose cell count matches its first line's, and that count is four. Everything else is somebody else's table — a two-column glossary, a prose line that happens to contain pipes — and is left alone, because a protection check that reddens on a glossary is one people learn to silence.
Header and separator are recognized by SHAPE and POSITION, never by the words in them: no column title is special to this tool, and a line may title its columns in its own language. A ledger may hold any number of tables.
What IS reported, because each would otherwise be a silent loss inside the ledger's own anchor table: a separator in the body, a row whose column count is not four, a table whose separator disagrees with its header, a pipe-led block with no separator at all (markdown will not render it as a table, so none of its rows would ever be checked), a lone four-column row adrift outside any table, and an unterminated fence.
AN EMPTY LEDGER IS AN ERROR, NEVER A GREEN. A ledger with no rows guards nothing, and "everything present" and "nothing checked" must never print the same line.
func ResolveRoot ¶ added in v0.7.0
ResolveRoot validates --root and resolves it once. Exported so a caller can refuse a bad root BEFORE printing any finding: a FAIL line emitted by a run that then exits 2 tells a scanner about findings from a run that did not happen. It returns the root twice: made absolute, and additionally symlink-resolved. BOTH are needed and mixing them is a real defect — every path this check builds must be joined onto the ABSOLUTE root, while the containment comparison happens against the RESOLVED one. Joining onto the caller's raw spelling and comparing against a resolved root made every anchor under a relative --root report as reached through a symlink.
func StripCode ¶ added in v1.2.3
StripCode blanks fenced code blocks (```...``` or ~~~...~~~) and inline code spans (`...`) with spaces, preserving all newlines, byte lengths, and column positions. CommonMark 0.31.2 container boundaries (block quotes, list items) are tracked so fences inside containers are recognized and close when their container ends. Inline code spans can span multiple lines without resetting at newline (CommonMark 0.31.2). Code spans cannot cross blank lines or fenced code block boundaries. Backtick characters escaped by an odd number of preceding backslashes outside a code span do not start or end a code span.
Types ¶
type Anchor ¶ added in v0.7.0
type Anchor struct {
Fragment string
Home string // slash-separated, relative to --root
Given string
By string
Line int // 1-based line in the ledger, so a finding can be found
}
Anchor is one ledger row: a verbatim fragment, the file it lives in, and the provenance columns that make the ledger readable as prose.
type Attestation ¶
Attestation is the successful result of Attest: what a full boot read.
type BrokenLink ¶
type BrokenLink struct {
File string // path of the containing .md file, relative to the scanned dir
Line int // 1-based line number; 0 when the whole file is the finding
Target string // the link target as written; empty when the whole file is the finding
Reason string
}
BrokenLink is one relative markdown link that does not resolve — or, when Line is 0 and Target is empty, one whole .md file that could not be read.
type Failure ¶
Failure is one named NO from a check: the subject that failed and why.
func Corpus ¶ added in v0.7.0
Corpus verifies every anchor is present in its home file under root, and that the ledger still holds at least minAnchors rows.
It returns every failure rather than the first: the losses this exists to catch arrive in batches — a move, a restore, a consolidation pass — and a one-at-a-time report would take as many runs as there were losses.
err is reserved for the check being unable to run at all: a --root that is absent or is not a directory. That distinction is not pedantry here. A typo'd root would otherwise fire this tool's loudest alarm — "the words were lost in place" — once per anchor, for an invocation mistake, which is the fastest way to teach a caller to ignore the alarm.
func Floors ¶ added in v0.2.0
Floors asserts that the door (SEED-CORE.md) and the source (SEED.md) declare the same floor set — the one pinned in floorTable. floors is the registry size, for the OK line. Every divergence is a Failure (exit 1 at the CLI); err is reserved for the check being unable to run at all.
func Kernel ¶
Kernel enforces a BYTE budget on the kernel file. maxBytes must be positive; there is no default budget and zero does not mean unlimited. A missing kernel and an empty kernel are both failures, not errors: the check ran, and the answer is NO.
Bytes are a proxy. What a context window actually spends is tokens, and the bytes-per-token ratio is a property of the writing, not of the format — see KernelTokens for the honest denomination.
func KernelTokens ¶ added in v0.3.0
func KernelTokens(file string, maxTokens int64, bytesPerToken float64) (measured, tokens int64, failures []Failure, err error)
KernelTokens enforces a TOKEN budget, derived from the measured bytes and a divisor the caller states.
The divisor is not a constant this tool can know: bytes per token varies by tokenizer, by language, and by how a given writer writes. It is a MEASUREMENT the caller makes on their own text — count the tokens of a representative sample with the tokenizer that will actually read the kernel, divide by its bytes, and pass that number. There is deliberately no default: a guessed divisor would make the whole answer a guess while looking like an instrument.
The derivation rounds UP (ceiling). A size check must never report fewer tokens than its own estimate, and rounding down would let a kernel sit one token over budget and read as exactly at it.
AND IT MUST NOT REPORT A NUMBER THE CONVERSION INVENTED. The estimate is a float64 and the count is an int64, and Go leaves an out-of-range conversion between them to the hardware: arm64 saturates to MaxInt64, amd64 yields the integer-indefinite value MinInt64 -- which is less than every budget, so a divisor of 1e-20 printed `KERNEL OK tokens=-9223372036854775808 budget=400` and exited 0 on three of the five shipped targets while the other two failed on the same file. The divisor is a hand-typed measurement and `1e-20` is a scientific-notation typo away from `1e20`, so the range is checked BEFORE the conversion and an estimate that cannot be counted is over budget, said in those words. The gate now gives the same verdict on every GOARCH.
func NoCode ¶
func NoCode(opts NoCodeOptions) (scanned int, findings []Failure, err error)
NoCode reports every file that is machinery living inside a prose-only tree.
A file is flagged when its extension is on the effective deny-list, when it carries an executable bit, or when it begins with a shebang. The three catch different things: the extension is the auditable common case, the mode bit catches a chmod +x on anything at all, and the shebang is the tell that survives renaming — a script with no extension is still a script.
A symlink is never dereferenced — a gate that can be walked out of the tree it guards is not a gate — but its own NAME is still classified, because a link called run.sh is machinery by the same argument that catches a file called run.sh, and reading its name requires no dereference.
A file that cannot be read produces a finding rather than a pass. Making a file less readable must not make this gate greener.
type LinksResult ¶ added in v1.2.3
type LinksResult struct {
MDFiles int
Checked int
Excluded int
Broken []BrokenLink
}
LinksResult is the full accounting of a links walk: the markdown files scanned, the relative links checked, the whole files skipped under an explicit --exclude prefix, and every broken link found.
func LinksExcluding ¶ added in v1.2.3
func LinksExcluding(dir string, exclude []string) (res LinksResult, err error)
LinksExcluding walks dir for .md files (skipping .git) and verifies that every relative inline link target resolves to an existing file or directory inside the tree, with an explicit set of path prefixes to leave unscanned: a file under an excluded prefix is not opened, and a link that resolves into an excluded prefix is skipped rather than checked or reported. The Excluded count is the number of .md files under those prefixes.
func LinksFiles ¶ added in v1.2.3
func LinksFiles(dir string, files []string, exclude []string) (res LinksResult, err error)
LinksFiles is the single-/few-file form of the walk: it checks exactly the listed markdown files and nothing else, so a two-file review does not expand to the whole tree. dir is still the resolution root — root-relative targets and the "escapes the tree" judgement resolve against it — and the reported paths stay repo-relative, exactly as the full walk reports them. A relative path is joined to dir; an absolute one is used as-is.
type NoCodeOptions ¶ added in v0.5.0
type NoCodeOptions struct {
Dir string // root of the tree being guarded (required)
Allow []string // path prefixes where machinery may live; empty by default
DenyExt []string // effective deny-list; empty means the floor list
DenySource string // provenance; required when DenyExt is set
}
NoCodeOptions configures the self/machinery separation check.
Allow starts EMPTY and stays empty unless the caller narrows scope. Every scope narrowing is the caller's, stated per run — the same law the skip and exempt lists elsewhere in this repo obey. The deny-list runs the other way: it is a floor that ships with the tool, because a narrowing that goes missing fails open and a floor that ships cannot.
type SpellingChecker ¶ added in v1.2.3
type SpellingChecker struct {
// contains filtered or unexported fields
}
SpellingChecker wraps misspell.Replacer with allowlist and code-stripping rules.
func NewSpellingChecker ¶ added in v1.2.3
func NewSpellingChecker(ignore []string) *SpellingChecker
NewSpellingChecker compiles a misspell Replacer with DictAmerican and removes ignored words. It caches compiled checkers so repetitive compilation across tests and files is avoided.
func (*SpellingChecker) CheckText ¶ added in v1.2.3
func (c *SpellingChecker) CheckText(filename, text string, isMarkdown bool) ([]SpellingFinding, string)
CheckText checks text content for misspellings. If isMarkdown is true, fenced code blocks and inline code spans are blanked before checking. It returns the findings and the corrected text.
type SpellingFinding ¶ added in v1.2.3
type SpellingFinding struct {
File string `json:"file"`
Line int `json:"line"`
Column int `json:"column"`
Original string `json:"original"`
Replacement string `json:"replacement"`
}
SpellingFinding is one misspelling finding in an input file or text.
type SpellingOptions ¶ added in v1.2.3
type SpellingOptions struct {
Ignore []string // words to ignore/allowlist, or @file paths
Write bool // rewrite files with corrections applied
Plan bool // with Write: make every check each rewrite makes, and write nothing
Markdown bool // force markdown mode (blanking code blocks/spans)
Exclude []string // path prefixes to exclude
Dir string // root directory for relative paths and exclusions
}
SpellingOptions controls spelling check behavior.
type SpellingResult ¶ added in v1.2.3
type SpellingResult struct {
FilesScanned int
Findings []SpellingFinding
Corrected int // number of files corrected if write mode was enabled
Excluded int
}
SpellingResult accounts for a spelling check pass.
func CheckSpelling ¶ added in v1.2.3
func CheckSpelling(targets []string, opts SpellingOptions) (res SpellingResult, err error)
CheckSpelling checks paths or glob patterns, expanding patterns as needed.
func CheckSpellingDir ¶ added in v1.2.3
func CheckSpellingDir(dir string, opts SpellingOptions) (res SpellingResult, err error)
CheckSpellingDir checks all markdown files in dir (and its subdirectories), skipping .git and paths matching opts.Exclude.
func CheckSpellingFiles ¶ added in v1.2.3
func CheckSpellingFiles(dir string, files []string, opts SpellingOptions) (res SpellingResult, err error)
CheckSpellingFiles checks the listed files relative to dir (or opts.Dir, or cwd if both empty).
Source Files