A repository staleness sweep flagged several directories and pages as "no references, safe to delete". Four of them turned out to be load-bearing, and each miss…
A repository staleness sweep flagged several directories and pages as "no references, safe to delete". Four of them turned out to be load-bearing, and each miss had a different mechanism. The sweep's evidence was the same in all cases: git grep <basename> returned only the file itself.
Name-based reference search answers a narrower question than the one being asked. "Does any file contain this string" is not "is this file consumed", and four common consumption patterns leave no string to find:
Path("cases").glob("*.json") never mention a filename, so every fixture looks orphaned. Here, six JSON files that a parametrised test enumerates appeared genuinely unreferenced.path:line (see docs/.../release-notes.md:13). Deleting the cited file leaves a dangling citation that a link checker will not catch, because it is prose, not a link.There was also a fifth, of a different kind: the sweep truncated its own output. git grep … | head -8 on a file with three live consumers showed only four unrelated hits plus the file itself, and "no consumer" was concluded from a list the operator had cut short. The signal was present; the pipeline deleted it before anyone read it.
The unifying defect is that the deletion decision and its evidence were not connected: nobody had to write down who the consumer was, so "I did not find one" silently became "there is none".
Before deleting, (1) search the basename and the path; (2) search for the loader shape — glob("*.json"), iterdir(), rglob, the directory name — because fixtures are often read by directory, not name; (3) search path:line citation shapes, since docs cite files as evidence; (4) never pipe a reference scan through head — count matches first and inspect the count; (5) make the deleting decision require naming the consumer in one sentence, and keep the file when the only answer is "someone might want it" — that is what git history is for.
The four near-misses were each caught before merge — one by the operator re-running the consumer check without truncation, one by a README describing its own purpose, one by a doc quoting the directory as the contribution format, and one by a test that asserts a cited quote still exists in the cited file (that last one is the strongest form: the citation was executable, so the deletion failed loudly instead of shipping a dangling reference). After the method change, the same sweep deleted a genuinely dead pipeline — an archiving feature that wrote to an ephemeral CI filesystem and posted a comment claiming the path existed — and that deletion required naming no working consumer at all, only a false claim.