feat: git locks doctor, a read-only invariant check of the store (0.5.0)

[flyingrobots]

Roadmap item 3 (#19).

git locks doctor reads one snapshot and checks it, writing nothing. One finding line per broken invariant as it is found, then one doctor line with the store, the reading basis (refs and records in that snapshot, and the clock), the checks run, the count and the verdict. Exit 0 healthy, 1 with findings, 2 when the store cannot be read, which is never reported healthy.

The invariants, each with a test that corrupts a store by hand (direct update-ref and hash-object -w on the store) and counts the finding:

• every job record decodes (record-decodes) and names its own job (job-ref-name)
• every path a record lists has a path ref pointing at that record (path-ref-missing, path-ref-elsewhere)
• every path ref points at a record some job ref points at (path-ref-orphan), and that record lists the path (path-ref-stray)
• every child's parent exists (parent-missing), is live (parent-expired) and has the same holder (parent-holder); no parent chain cycles (family-cycle)
• every semaphore has meta and gen (sem-meta, sem-gen), its records decode (sem-record), and its live slots fit its capacity (sem-capacity)
• nothing else lives in the namespace (unknown-ref)

Paths are hashed in one hash-object process (each path becomes a temp file, one call hashes them all with --no-filters, the same bytes path_ref hashes from stdin), so the suite asserts the git process count is the same for 3 locks and 33. An unreadable store exits 2 with a store-read error and no doctor line. Findings come in ref order, so output is stable.

Schema: finding_line and doctor_line added; every line the tests provoke validates. README: a commands row and a contract paragraph ("What the invariants are, and how to see them hold"). Repair is deliberately not a mode of this command.

Also fixes a shadowing bug found on the way: field_v and json_paths_v declared locals a caller could name (rest, line), the same trap CONTRIBUTING records for write_blob.

Version 0.5.0. 366 checks green, lint clean. Branched from #28 so the diff against main is the doctor only.

Closes #19

[coderabbitai]

Warning

Review limit reached

Next included review available in 20 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 2833fe9c-9a7b-428f-8c70-dd8896a1a5b7

📥 Commits

Reviewing files that changed from the base of the PR and between b918f82 and f383944.

📒 Files selected for processing (9)

• CHANGELOG.md
• README.md
• bin/git-locks
• lib/000-prelude.sh
• lib/010-json.sh
• lib/175-doctor.sh
• lib/990-main.sh
• schema/git-locks.schema.json
• test/test.sh

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}