Documentation
¶
Overview ¶
Package allowlist is the one reader and the one writer of the exception lists the class tests in internal/ci keep under internal/ci/testdata (nova-tools#4339).
A list is a text file: `#` comment lines, blank lines, and rows. Each row has a key (by default its first field) and whatever reason follows it for a reader. A class test Loads its list, walks the tree, and hands Check the set of keys it measured: every offender it found, listed or not. Check returns the rows nobody needs any more (stale) and the keys the list does not hold (unlisted); the test prints both with its own remedy.
Under NOVA_CI_UPDATE=1, Check rewrites the file to the measured set instead: the stale rows go, every comment and every kept row stays byte for byte, and the test fails once with "updated, rerun". A ceiling-only list -- one whose count only falls, which is every list in internal/ci today -- refuses to grow under the update and says so for each key it will not add: an update never writes a reason on anyone's behalf. A `# ceiling: N` line caps a list's row count; the update lowers N to the new count and never raises it.
No script edits a list file: a removal regenerates every list with one env var.
Index ¶
Constants ¶
const UpdateEnv = "NOVA_CI_UPDATE"
UpdateEnv is the variable that turns Check into a rewrite. Only the value "1" does.
const UpdatedRerun = "updated, rerun"
UpdatedRerun is the sentence the one failure of an update run carries.
Variables ¶
This section is empty.
Functions ¶
func Fields ¶
Fields returns a key of the row's first n fields joined by one space, for a list whose identity is more than one field (`file:line kind`, `file spell`).
func FirstField ¶
FirstField is the default key: the row's first whitespace-separated field.
Types ¶
type List ¶
type List struct {
Path string
// contains filtered or unexported fields
}
List is a loaded allowlist.
type Options ¶
type Options struct {
// Key derives a row's key from its trimmed text. Nil is FirstField.
Key func(row string) string
// Ceiling marks a list whose count only falls: an update drops stale rows and
// refuses to add a row for an unlisted key.
Ceiling bool
// NewRow is the text an update appends for an unlisted key on a list that may
// grow. Nil appends the key alone. Unused on a ceiling list.
NewRow func(key string) string
// MissingIsEmpty loads a missing file as an empty list instead of an error: a
// tree with nothing parked in it is the goal.
MissingIsEmpty bool
}
Options says how a list's rows are keyed and whether it may grow.
type Reporter ¶
Reporter is the part of testing.TB Check writes to. It is an interface here so the package does not link the testing package into a binary that imports internal/ci.
type Result ¶
type Result struct {
// Stale are the rows whose key was not measured. Each is a red run; an update
// drops them and returns none.
Stale []Row
// Unlisted are the measured keys no row carries, sorted. Each is a red run; an
// update on a list that may grow adds them and returns none, and a ceiling list
// keeps them (it refuses to grow).
Unlisted []string
// Updated is true when this run rewrote the file.
Updated bool
}
Result is what Check found.
func Check ¶
Check compares the measured keys with the list. Outside an update it only reports: a list over its ceiling is refused here, and the stale rows and unlisted keys come back for the caller to print with its own remedy. Under NOVA_CI_UPDATE=1 it rewrites the file to the measured set and fails once with "updated, rerun"; a ceiling list refuses each key it would have to add, one line per key.
Source Files