Documentation
¶
Overview ¶
Package check implements the four 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)
- type Attestation
- type BrokenLink
- type Failure
- 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.
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.
Types ¶
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 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.
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