Repository navigation
Commit a real example report, regenerated by CI so it cannot go stale #16
Description
examples/ holds basic.mjs and basic.sh, which show how to call the tool. What is missing is the thing a visitor actually wants in the first ten seconds: a real report to look at, without installing anything or pointing the tool at their own history.
That gap matters more here than in most tools, because the output is the product. The README describes the figures; a committed report shows what a reader is being asked to trust.
Done when
- A report generated from a public repository is committed, along with the exact command that produced it and the commit it was taken at, so anyone can reproduce it.
- The Markdown rendering is committed next to the JSON, since most readers will only look at the Markdown.
- CI regenerates it and fails when the committed copy no longer matches a fresh run, the way
bench/PRECISION.mdis kept honest in a sibling repository. A committed artefact that nothing checks is a stale artefact waiting to happen, and this project has been bitten by hand-typed numbers before. - The chosen repository is one whose history is stable and public, and the pull request says why you picked it.
Out of scope. Anything involving a private repository, and any report about a real person who has not agreed to it. Pick a repository where the authorship figures are about the project's own public contributors and say so, or use a repository you own.
A wrinkle to think about. A report pinned to a moving branch changes as the project does, so CI will fail for reasons that are nobody's fault. Pinning to a tag or a fixed commit is the obvious answer; if you find a better one, say so.
Taking this on: comment and it is yours, so two people do not write the same patch. No design document needed unless the issue asks for one.
What gets a pull request rejected here: a change with no test; a new runtime dependency; or a number written into a README or a document that did not come from a run somebody else can repeat. CONTRIBUTING.md has the rest.
Activity
Bubblegunn commentedon Sep 6, 2026
This happened, before anyone took the issue.
The README's report block was generated on 5 September. Running the stated command against the stated commit today, with the current build, gives different numbers:
Nothing compared the two, so it drifted quietly across the 0.4.0 and 0.4.1 releases. It is fixed in
3f08876, in both languages, but fixing it by hand is exactly what this issue says should not be necessary.Two things this adds to the issue, both learned the hard way:
The command matters as much as the commit. The first regeneration used
--authorwith two email addresses; the README's block was made with--author "Colin Francis". Those give different denominators, because they resolve to different identity sets. Whatever gets committed has to record the exact flags, not just the repository and the ref.The fingerprint changes every run by design, since its key is random unless
--fingerprint-keyis passed. A checker that diffs the whole block will fail on every run for that one line. Either pin the key in the committed command or exclude that field from the comparison, and say which in the pull request.The sibling repository now has
scripts/readme-demo.mjsdoing this for a much simpler case, including a check that it actually catches injected drift. It is worth reading before starting, though the hard part here is different: this one needs an external repository at a pinned commit, and a CI job that clones it is a network dependency the other one does not have. If that turns out to be the wrong trade, a committed report from a repository we control is a perfectly good answer and the issue should say so.