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.

who it helps loader

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

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.