perf(docm): size the docs cache from recorded checkout sizes

[AbysmalBiscuit]

TL;DR (human written)

---

Closes #102
Refs #31

---

Agent summary

Every devkit doctor run re-walked every file under every materialized checkout to recompute a number that barely moves. devkit_docs::doctor_summary called dir_size on the whole cache root, and that was the only place the number came from.

Most of what it walked is stable. A library directory is one shared repo.git plus a detached worktree per resolved version; the worktrees sit at fixed commits and are verified clean, and only the object store actually grows as new versions are materialized. On a blobless clone of tokio with two version trees, repo.git was 9.0 MB of a 19.1 MB total, so roughly half the walked bytes were identical on every run.

What changed

cache::WorktreeMeta gains an optional bytes, recorded in resolve::resolve right after ensure_at writes the tree and assert_clean verifies it, while the library lock is already held and the tree is still hot in page cache. upgrade::attend back-fills it once for a cache written before this, under the lock it already takes, and needs_attention matches exactly what the back-fill will do, so a cache it cannot finish does not ask for the lock again on every command.

doctor_summary substitutes the records into the walk through a new disk::dir_size_with_known, rather than composing a total out of parts. The cache is still walked whole, so the shared object stores, sidecars, lock files and whatever a broken cache has left lying around all still land in the total. A record that outlived its checkout adds nothing, because the substitution happens where the walk meets the entry.

docm list now shows size per version in both the table and --json. That is the number that says which version is the fat one, which is what #31 needs in order to decide where to point its filters.

The staleness trade

A record is a snapshot of a tree pinned at a fixed commit, so it goes stale when a checkout grows, and the growth most likely to matter escapes the cleanliness sweep as well: git status --porcelain does not report ignored files, so a target/ or node_modules/ landing in a checkout shows up in neither the record nor the local-modifications check. That gap is not new, but nothing here pretends otherwise.

docm list --refresh re-measures every checkout under its library lock and writes the numbers back, and doctor names the flag in its docs-cache row so a reader who doubts the number knows where to go. Refreshing lives on list rather than on doctor because doctor diagnoses and does not mutate the cache, and its sweep deliberately takes no library lock.

Also

inspect spawned two git processes per checkout, git status --porcelain then git rev-parse HEAD. git status --porcelain=v2 --branch answers both in one: its header carries the full HEAD oid, so the recorded-commit comparison reads off the same output as the dirty check. Entry lines are reduced to the status letters and the path the way v1 rendered them, unrecognized record types yield nothing so a format git grows later cannot become a phantom modification, and (initial) is reported as a missing commit rather than compared against a sha. assert_clean only needs dirtiness and stays on v1.

Measured on this box that saves about 1 ms per checkout, which is the spawn cost of rev-parse itself. The case for it is Windows, where process creation is far more expensive, and where CI runs.

Verification

devrun task test (2262 tests, 2259 passing), test-doc, lint clean, fmt applied.

Three failures are pre-existing on main in this container and unrelated to the diff, confirmed by running the suite on a clean tree: devkit::install_links a_failed_pass_is_partial_and_retries_once_the_cooldown_elapses and two devkit-common git::tests permission fixtures, all of which need a non-root user for anything to be denied.

---

🤖 Generated with Claude Opus 5 via Claude Code

https://claude.ai/code/session_01TXnj77YPcNHmatshb47AJN

---

Generated by Claude Code