Add script and github workflow to ratchet coverage to 100%

.claude/CLAUDE.md

@@ -89,6 +89,24 @@ Server-managed collections use `new_collection`/`collection_more`/`collection_re
 
 For enums, it also creates `<Enum><Variant>Generator` for each data variant. Implementation is split across `struct_gen.rs`, `enum_gen.rs`, and `utils.rs`.
 
+### Coverage Annotations and Ratchet
+
+**CRITICAL: You MUST NOT increase the numbers in `.github/coverage-ratchet.json` without first asking for and then receiving explicit human permission to do so.** This applies even if you believe the annotation is justified. The ratchet numbers can only decrease; any increase requires human approval. Do not work around this by restructuring code to avoid coverage instead of writing tests. Do NOT blindly add `// nocov` -- each annotation must be justified, and your first instinct should be to write a test instead.
+
+This project enforces 100% code coverage. When code is genuinely untestable, use these annotations:
+
+- `// nocov` at the end of a line -- excludes that line from line coverage.
+- `// nocov start` / `// nocov end` on their own lines -- excludes a block from line coverage.
+
+The coverage check script (`scripts/check-coverage.py`) automatically removes `// nocov` annotations from lines that turn out to be covered. The ratchet file tracks the total count of excluded lines and prevents the count from increasing.
+
+The following patterns are **automatically excluded** and do NOT need `// nocov`:
+- Structural syntax (closing braces, punctuation-only lines)
+- `#[cfg(test)]` modules
+- `todo!()` and `unreachable!()` calls
+- Continuation lines inside multi-line `unreachable!()`/`todo!()` calls
+- `#[ignore]`d test bodies
+
 ### Testing Conventions
 
 - Place tests in `tests/` as integration tests, not as inline `#[cfg(test)] mod tests` in source files.

.github/coverage-ratchet.json

@@ -0,0 +1,3 @@
+{
+  "nocov": 564
+}

.github/workflows/ci.yml

@@ -157,11 +157,13 @@ jobs:
     name: coverage
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: write  # needed for ratchet auto-update
+      pull-requests: write  # needed for creating PRs on main
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      # persist-credentials needed for git push in the auto-update step below
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 # zizmor: ignore[artipacked]
         with:
-          persist-credentials: false
+          ref: ${{ github.head_ref || github.ref }}
 
       - name: Install Rust
         run: rustup toolchain install stable --profile minimal -c llvm-tools-preview
@@ -177,6 +179,40 @@ jobs:
       - name: Run coverage
         run: just check-coverage
 
+      - name: Auto-update coverage annotations and ratchet
+        if: success()
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if git diff --quiet; then
+            echo "No coverage annotation changes needed"
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -u
+          git add .github/coverage-ratchet.json
+
+          if git diff --cached --quiet; then
+            exit 0
+          fi
+
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            git commit -m "Auto-update coverage annotations and ratchet"
+            git push
+          else
+            BRANCH="auto/coverage-ratchet-update"
+            git checkout -b "$BRANCH"
+            git commit -m "Auto-update coverage annotations and ratchet"
+            git push -f origin "$BRANCH"
+            gh pr create \
+              --title "Auto-update coverage ratchet" \
+              --body "The coverage ratchet has tightened on main. This PR updates the ratchet file and removes unnecessary annotations." \
+              --base main \
+              --head "$BRANCH" || true
+          fi
+
   conformance:
     name: conformance
     runs-on: ubuntu-latest

justfile

@@ -38,11 +38,14 @@ check-docs:
 docs:
     cargo +nightly docs-rs --open
 
-check-lint: check-format check-clippy
+check-nocov-style:
+    scripts/check-nocov-style.py
+
+check-lint: check-format check-clippy check-nocov-style
 
 check-coverage:
     # requires cargo-llvm-cov and llvm-tools-preview
-    RUST_BACKTRACE=1 cargo llvm-cov --all-features --fail-under-lines 30 --show-missing-lines
+    scripts/check-coverage.py
 
 check-conformance:
     cargo build --release --manifest-path tests/conformance/rust/Cargo.toml