Documentation
¶
Overview ¶
Package bounded is the one shape every listing in this repo prints, and the reason it exists is an incident: a line running on a 260K-context model died reading a single 674-line return from a verb that lists its state. Nothing was wrong with the state and nothing was wrong with the reader. The tool printed all of it, every time, because no verb here had ever been given a ceiling.
SPEC.md promises one machine-scannable line per event. It does not promise that the number of events is small, and at a large state it is not: 10,000 unresolved wikilinks, 800 broken links, 1,200 self-talk claims, 300 quarantines. A listing whose length is the state's length is not a report, it is the state, copied -- and a reader who has to hold all of it to learn "there are 10,000" learned one number for 197,000 tokens.
So every listing here is a cap and a count:
at most Max item lines, in the order the tool produced them
then ONE line naming what was not shown and how to see it:
<TOKEN> MORE kind=<kind> shown=<n> total=<t> <remedy>
The remedy is never advice. It is the flag that widens the cap or the file that holds the whole list, written so it can be typed. A cap with no remedy is censorship; a cap with one is an index.
Two rules the caps do not cover, and the callers keep:
THE COUNT LINE PRINTS ON FAILURE TOO. Every verb in this repo used to print its summary -- files=, links=, gating= -- only when it passed, so a failing run gave N lines and never N. Shown and Total are exported for exactly that line. MAX 0 MEANS ALL. A cap a caller cannot turn off is a tool deciding what its user may see. Every --*-max flag here takes 0, and 0 prints everything.
Grouped is the same shape per kind, for a verb that runs several checks into one stream: 20 findings of one kind must not bury the single finding of another, which is what a flat cap over a concatenated list does.
Nothing here is a substitute for the escape. Every item line is rendered through oneline.Escape on its way out -- which is a no-op over text the caller already escaped, because Escape does not escape a backslash -- so a listing cannot break its own line count, whatever the state holds.
Receipt — the compact failure receipt for one nova-test run. deprecated/docs/SPEC-TEST.md names four outcomes — a generic failure, a timeout, a missing-job, and a superseded cancellation — but each is the same shape: identity, equivalence key, bounded failing steps and excerpts, latency, and at most one MORE line naming the log that holds the whole list.
The cap, the count, and the escape are the three things a receipt cannot get wrong without becoming the state it was meant to be a window into, and those are exactly the three jobs the rest of this package already does. Defining Receipt here, beside List and Group, means the verb in deprecated/cmd/nova-test will reuse the same machinery its listings already use, and a reader who parses one RECEIPT line parses every RECEIPT line.
A receipt printed with zero failing steps — the run never reached one because it timed out, the job never existed, or it was superseded — is one header line plus zero or one MORE line: the same bound as a receipt with a hundred failures. The bound is "at most the failing steps, plus excerpts, plus a single remedy line", and it is checked on every receipt whether the list was filled or never started.
Index ¶
Constants ¶
const ( ReceiptKindFail = "fail" ReceiptKindTimeout = "timeout" ReceiptKindMissing = "missing" ReceiptKindSuperseded = "superseded" )
Receipt kinds. deprecated/docs/SPEC-TEST.md names the three non-fail outcomes: a timeout, a missing job and a superseded cancellation each read as their own receipt rather than as one shared "fail". These strings are what appears after kind= in the receipt header, and they are what the "failures" verb greps for when a reader wants to count, say, timeouts across a week of runs without dragging the failed runs along.
const Default = 20
Default is the ceiling every --*-max flag in this repo starts at. Twenty is a screen: enough to see the shape of what failed and to recognise a pattern, few enough that a reader who wanted the number rather than the list has not paid for the list. It is a default and not a law -- every flag that carries it can be widened, and 0 lifts it.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Capture ¶ added in v0.15.0
type Capture struct {
// contains filtered or unexported fields
}
Capture retains at most limit bytes and cancels a producer as soon as that limit is reached. Writes still consume their full input, so cancellation cannot turn a capped prefix into an apparently complete response.
func NewCapture ¶ added in v0.15.0
func NewCapture(limit int, cancel context.CancelFunc) *Capture
type Group ¶
type Group struct {
// contains filtered or unexported fields
}
Group is one cap per kind over a single stream, for a verb that runs several checks and prints their findings together.
A flat cap over a concatenated list is the wrong shape there: 10,000 wikilink findings ahead of one frontmatter finding means the frontmatter finding is never printed, and the one line that would have told the reader something they did not already know is the line the cap ate. Each kind gets its own ceiling and its own MORE line, and the kinds print in the order they were first seen, so the output is deterministic without being alphabetised into a shape the verb did not choose.
func Grouped ¶
Grouped returns a Group whose every kind is capped at max. See Capped for the arguments.
func (*Group) Line ¶
Line offers one item line under its kind, opening that kind's list the first time it is seen.
func (*Group) List ¶ added in v0.11.0
List is one kind's list, or nil when this group has not seen that kind. It is here for a verb whose MORE line carries a field this package does not print -- nova-wake's carries n=<elided>, which its spec requires -- so that such a verb can reuse the per-kind capping and still write its own summary, rather than hand-rolling a second map of lists beside this one.
func (*Group) More ¶
func (g *Group) More()
More prints one MORE line per kind that elided anything, in the order the kinds were first seen.
type List ¶
type List struct {
// contains filtered or unexported fields
}
List prints at most max item lines and then one line standing for the rest.
The zero value is not usable; build one with Capped. A nil *List is, deliberately, not usable either: a listing that silently printed nothing would be the same silence this package exists to end.
func Capped ¶
Capped returns a List that writes to w, prints at most max lines, and stands the rest behind one MORE line.
token is the event token the verb already prints (VERIFY, LINKS, SCAN), so the MORE line sorts and greps with the lines it caps. kind names what is being counted, and is what makes a per-kind cap readable. remedy is the flag or the file that shows the rest, written the way it would be typed. max <= 0 prints everything: a caller who asked for all of it gets all of it, and gets no MORE line, because there is no more.
func (*List) Elided ¶
Elided is Total minus Shown: what the reader would have to widen the cap to see.
func (*List) Err ¶ added in v0.11.0
Err is the first write error this listing hit, or nil. A caller that records what it has delivered asks this before it writes that record down.
func (*List) Line ¶
Line offers one already-rendered item line to the listing. It is counted always and printed only while the ceiling allows, so Total is the truth about the state even when the output is not.
The line arrives WITHOUT its newline; one trailing newline is tolerated and removed rather than escaped into a visible \x0a, because a caller converting an existing fmt.Fprintf site is copying a format string that ends in one, and a tool that punished that with mangled output would be teaching its authors to be careful instead of being robust.
func (*List) More ¶
func (l *List) More()
More prints the one line that stands for everything Line counted and did not print, and prints nothing at all when nothing was elided -- a MORE line saying total equals shown is a line that carries no information, and this package is about not printing those.
type Receipt ¶
type Receipt struct {
// contains filtered or unexported fields
}
Receipt is the compact failure receipt for one nova-test run. Build one with NewReceipt; never copy a zero value and print it — a receipt that says nothing is what this package exists to refuse.
The failing-step list is capped by the same Default this package uses for listings, and an over-cap run leaves a single MORE line naming the log that holds the un-bounded list. The reader types that path the same way the verb types it: an improvement on redisplaying a thousand-step failure into a single screen-sized receipt.
func NewReceipt ¶
func NewReceipt(w io.Writer, kind, identity, equivalence string, latency time.Duration, log string) *Receipt
NewReceipt builds a receipt printing to w. kind names the outcome and is one of ReceiptKindFail, ReceiptKindTimeout, ReceiptKindMissing or ReceiptKindSuperseded: those four names are how a timeout, a missing job, and a superseded cancellation read as their own receipt rather than as a shared "fail" header.
identity, equivalence, and latency are the fields the run record carried; the verb passes them through oneline.Field so a stored identity, an equality-sign in the equivalence key, or a path holding whitespace does not pose as a token.
log is the path to the file holding the un-bounded list and is the remedy line the spec demands. It is the way a reader would type it from the receipt:
nova-test receipt <identity> --log <log>
func (*Receipt) Failure ¶
Failure offers one failing step and its source-backed excerpt to the receipt's bounded list. Each call counts toward the cap, and the cap is why a timeout or a missing-job receipt without an item still prints a header rather than the whole list. The pair renders as one line, so an excerpt cannot add an item line the cap did not account for.
func (*Receipt) Print ¶
func (r *Receipt) Print()
Print writes the receipt: a single header line carrying the identity, the kind, the equivalence key, and the latency; then the failing steps with their excerpts (buffered through r.failing.Line as Failure was called, and written only now, after the header); and at most one MORE line naming the log that holds the un-bounded list. The MORE line is written only when the call sequence elided at least one failure; an empty receipt prints just the header and nothing else.
Source Files