computedwhat to computeHow it worksGitHub
Forty things you decided not to document.
Not a feature list. Every entry below is a fact about a repository that would obviously help somebody, that almost no project writes down, and that rots the moment it is written. The reason is never that nobody wants it. It is that a hand-maintained inventory costs forever, and a wrong one is worse than nothing.
A region changes the arithmetic. The marginal cost of the thirty-first is one line and a script; the cost of keeping it is a hash comparison. Each marker below is real grammar — paste it, write the script it names, run computed run. Every entry carries a collapsed example of what it renders, marked according to whether that output is live in this repository, produced from it, or only illustrative.
Two rules that shape every entry
inputs= reads the full bytes of every matched file. inputs=src/** on a large repository makes check cost the size of the repository. Point it at the smallest set of files that determines the output.
run skips a fresh region's loader entirely. So a command whose output is not byte-stable between runs — a timing, a size, a coverage percentage — does not churn, because it is only re-run when its declared inputs move. That makes a whole class of region viable that a rerun-to-check tool cannot hold still. The cache is the feature, not the optimisation.
A command long enough to need quoting belongs in a script under scripts/, named in cmd= and listed in inputs= beside what it reads — so editing the script makes the region stale too.
Every entry is grounded in docs/research/landing-page-and-site-craft.md, which names the project, issue or document behind each claim.
What does not work, so nobody re-derives it
- gitHistory beyond commits, tags and authors has no honest
inputs=. Thegitloader covers the three it names:git log,git tagsandgit contributorssnapshot the history itself, sochecksees a new commit. Anything else from history, such as a changelog built bygit cliff, lives in.git, which a glob cannot snapshot, and must bevolatile, whichcheckalways passes. - volatile
volatileis a convenience, not a guarantee. It re-renders on everyrunand is never checked. Wherever an entry below is marked volatile, that is the trade being made. - timings
cargo build --timingsemits HTML only. There is no text mode, so a build-timing region needs scraping rather than one line.size(1)'s column spacing is not identical across platforms either;duis the portable option. - stabilitySome generators have no documented output stability.
cargo public-api's ordering is not documented as stable and needs a nightly toolchain present;cargo license's column layout is undocumented — prefercargo deny list. A region over an unstable generator churns for no reason. - formattersA formatter and a region will fight. Prettier or markdownlint running over
CLAUDE.mdwill reformat a region body and turn itedited. all-contributors solves this by nesting its region insideprettier-ignore-startandmarkdownlint-disablefences. Do the same untilcomputedemits them itself.
What not to compute
Anything a person decided. The reason a module is structured the way it is, what a convention is for, which of two approaches was rejected and why. Computing those takes the decision away from the person making it, and a decision has no input to hash. The rule that separates the two: if you could write a script that produces it, it belongs in a region; if you would have to think, it belongs in prose.
Roughly a fifth of a real context file is mechanically derivable, and it clusters at the top. That fifth is the part that rots. The rest is what you are actually paid for.