Documentation
¶
Overview ¶
Package check implements the six record-layer checks behind nova-check. 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 ParseDenyList(spec string) ([]string, error)
- func ParseLedger(raw []byte) ([]Anchor, []Failure, error)
- func ResolveRoot(root string) (abs, resolved string, err error)
- 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 NoCodeOptions
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 and the two want different things. In a finding's REASON they are free text -- `code extension .py (floor list)` -- and keep their spaces, because the tail of a line is prose. On the `deny-list=` and `source=` FIELDS of nova-check's summary lines they are a field, and SPEC.md's rule is that a field is ONE token, so the caller there renders them through oneline.Field and `floor list` prints as `floor\x20list`. The spelling is not shortened to fit the field: a label a reader has seen in a finding should read the same on the summary line, and the escape is how one token is reached without changing what it says.
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 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 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.
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.
func Links ¶
func Links(dir string) (mdFiles, checked int, broken []BrokenLink, err error)
Links 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. It returns the number of markdown files seen, the number of relative links checked, and every broken link found.
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 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.
Source Files