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.
Index ¶
Constants ¶
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 ¶
Types ¶
type Capture ¶
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 ¶
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) 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) 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 Tally ¶
type Tally struct {
// contains filtered or unexported fields
}
Tally counts a capped listing without printing it, for a caller that keeps the listing as a value (pkg/tool): Add reports whether an item of a kind is listed under a ceiling of max per kind (0 lists all), in the order added.
Source Files