paperlint 3.0.0 → 3.1.1

package/.github/workflows/ci.yml

@@ -3,7 +3,7 @@
 # ── WHY ONE JOB ─────────────────────────────────────────────────────────────
 # Parallelism does not save billable minutes, it ADDS them: every job pays for its own
 # setup + checkout + install (~20-30 s). Splitting is worth it for signal isolation on a big
-# matrix; here the whole suite is 84 seconds, so a second job would cost more than it isolates.
+# matrix; here the whole suite is ~96 seconds, so a second job would cost more than it isolates.
 #
 # ⛽ THIS REPOSITORY IS PUBLIC, so its minutes are FREE — they do not touch the account's
 # 3000/month quota (verified against the API 2026-09-12: `"private": false`). The header said
@@ -11,23 +11,24 @@
 # rather than guessed. Keep measuring them anyway: the bond exists to stop a HANG, and a hang
 # costs wall-clock and a red check whether or not anyone is billed.
 #
-# ── THE MEASUREMENT THE BONDS COME FROM (local, 2026-09-12) ─────────────────
-#   npm test (12 harnesses)              11 s
-#   npm run lint (eslint over fixtures)   1 s
-#   rules-see-files.mjs                   1 s
-#   vigiles lint                          3 s   ← added 2026-09-12 with the first ten skills
-#   run-mutations.mjs (12 batteries)    242 s   ← 130 mutations, the expensive and load-bearing part
+# ── THE MEASUREMENT THE BONDS COME FROM (local, 4 cores, 2026-09-26) ─────────
+#   npm run build                         2 s
+#   npm test -- --no-skip (69 harnesses) 41 s   ← vitest + every harness
+#   npm run lint                          6 s
+#   npm run fmt:check                     5 s
+#   vigiles lint . README.md              6 s
+#   rules-see-files.mjs                   5 s
+#   layer-legacy-frozen.mjs               3 s
+#   install e2e --strict (npm + pnpm)    28 s
 #   ───────────────────────────────────────────
-#   total work                          ~255 s, plus checkout + install
+#   total work                          ~96 s, plus checkout + install + the claude binary
 #
-# 🔴 THE PREVIOUS NUMBERS ARE KEPT NOWHERE BUT THIS SENTENCE, ON PURPOSE: they said ~84 s total
-# with `timeout-minutes: 8`, i.e. a ~2.7× bond. The pipeline's checkers arrived on 2026-09-12 and
-# tripled every count — 4 harnesses became 12, 45 mutations became 130 — which would have left an
-# 8-minute bond at ~1.3× of a ~6-minute run. A bond that tight fails on a slow runner and reads
-# as a broken suite rather than as a bond. Re-measure when the counts move again; do not cite the
-# table above without re-running it.
+# 🔴 THE PREVIOUS TABLE (2026-09-12) had one more row, `run-mutations.mjs`, at 242 s of ~255 s, and
+# by 2026-09-23 it was 8m39s of a 10m02s job (#52). The batteries were removed in #52, which is
+# what took the job from `timeout-minutes: 20` to 10. Re-measure when the counts move again; do not
+# cite the table above without re-running it.
 #
-# Expect ~6 minutes warm. `timeout-minutes: 20` is ~3.3×, and `npm ci` carries its OWN bond
+# Expect ~3 minutes warm. `timeout-minutes: 10` is ~3×, and `npm ci` carries its OWN bond
 # because a job-level bond cannot tell "the registry hung" from "the suite is slow" and so hands
 # a hang the whole job.
 name: ci
@@ -62,7 +63,7 @@ jobs:
     # there is no pull_request object, and a bare `.draft` would be missing and kill every check there.
     if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v7
 
@@ -88,14 +89,10 @@ jobs:
       # i.e., claimed a protection that does not exist. Protection against this case comes from `--no-skip` below.
       # 🔴 THE `claude` CLI IS A TEST DEPENDENCY HERE, and its absence was NOT harmless.
       # `plan-paper-timeline.effects.harness.mjs` spawns the real agent binary; without it the
-      # harness SKIPS, the skip exits 0 through `vigiles test`, and the mutation driver interprets
-      # that as "the mutation survived". Measured 2026-09-15 on run 34966606186: two survivors in CI,
-      # zero locally, the difference being this binary and nothing about the code.
-      #
-      # The driver now REFUSES a battery whose harness skips (lib/mutation-driver.mjs), so the
-      # wrong diagnosis is gone either way. This step is the other half: it restores the evidence
-      # instead of settling for an honest "no evidence". No API key — the tier drives a scripted
-      # stand-in, which is why it costs seconds and $0.
+      # harness SKIPS, and a skip is not evidence. (Measured 2026-09-15 on run 34966606186, when the
+      # since-removed mutation batteries read that skip as two "survivors" in CI and none locally.)
+      # This step restores the evidence instead of settling for an honest "no evidence". No API
+      # key — the tier drives a scripted stand-in, which is why it costs seconds and $0.
       # 🔴 DELIBERATELY UNPINNED, and since issue #7 that is finally honest. The tier exists to
       # notice upstream moving, so a pin would defeat it — but until the version was OBSERVED
       # rather than probed for, an unpinned install meant the assertions characterized whatever
@@ -110,14 +107,16 @@ jobs:
       # that failed to LOAD. In other words, one flag closes both doors at once.
       #
       # ⚠️ The step order was incorrect and made the install above nearly pointless: `npm test`
-      # ran BEFORE it, so the effects tier in this job was always skipped, and the binary
-      # reached only the mutation batteries. The comment about "its absence was NOT harmless"
+      # ran BEFORE it, so the effects tier in this job was always skipped. The comment about "its absence was NOT harmless"
       # described exactly this harm yet did not protect against it itself.
       #
       # ⚠️ And the flag belongs IN THE STEP, not in `package.json`: the macOS cell of build-e2e runs the same `npm test`
       # WITHOUT installing the binary, where skips are legitimate, and a global flag would falsely color it.
-      - name: npm test
-        run: npm test -- --no-skip
+      #
+      # `npm run coverage` is `npm test` under c8 with the thresholds in .c8rc.json: the same tests,
+      # one run, and a drop below the coverage floor fails this step by name.
+      - name: npm test, under coverage
+        run: npm run coverage -- --no-skip
 
       # The rules themselves, over this repository's own fixtures. Two of the four fixtures are
       # DEFECTIVE ON PURPOSE, so a healthy checkout reports warnings here and still exits 0 —
@@ -161,22 +160,11 @@ jobs:
       - name: every rule sees a file
         run: node scripts/rules-see-files.mjs
 
-      # Hand-written mutation batteries are being removed (#52): the frozen list may only
-      # shrink — no new battery, no new case in an existing one.
-      - name: mutation batteries are frozen
-        run: node scripts/mutation-batteries-frozen.mjs
-
       # The legacy exemptions from src/'s layer rules (#76) may only shrink: counted from ESLint's
       # own suppressedMessages, so a new `-- legacy …` directive anywhere fails here.
       - name: legacy layer exemptions are frozen
         run: node scripts/layer-legacy-frozen.mjs
 
-      # The batteries that remain still run until #52 replaces or removes them. The runner
-      # DISCOVERS batteries rather than listing them and errors on finding zero — see
-      # scripts/run-mutations.mjs for why (the hand list it replaced had gone stale, silently).
-      - name: mutation batteries
-        run: node scripts/run-mutations.mjs
-
       # pnpm is INSTALLED here rather than hoped for. The runner image may or may not carry it,
       # and the npm/pnpm difference is the entire reason the install e2e exists — so leaving it
       # to the image means the half that matters most is covered by luck. `corepack` ships with
@@ -244,8 +232,7 @@ jobs:
                                               : "DIVERGE — this is the platform this job exists for");
           '
 
-      # Issue #9: `npm test` was red ONLY on macOS. Only `npm test`, not the mutation batteries:
-      # they would verify on macOS exactly what the gates job verifies on Linux.
+      # Issue #9: `npm test` was red ONLY on macOS.
       - name: npm test (macOS)
         if: runner.os == 'macOS'
         run: npm test

package/.github/workflows/dependabot-automerge.yml

@@ -16,7 +16,7 @@
 #
 # 🔴 WHY WE MERGE ANY BUMP, INCLUDING MAJOR, not just patch/minor.
 # Semver is a PUBLISHER'S CLAIM about their release; `ci` is a MEASUREMENT on our corpus (full harness suite,
-# mutations, gates for "rules see their files" and "rules don't touch git"). A major bump that breaks us
+# gates for "rules see their files" and "rules don't touch git"). A major bump that breaks us
 # reds the run and does not merge; a minor one that breaks us does the same.
 # A version-number filter adds a manual step where measurement already exists, and would miss
 # exactly the class for which version filters are typically used.

package/CLAUDE.md

@@ -35,7 +35,6 @@ assumed. Two things that sound like limits and are not:
 | ----------------------- | -----------------------------------------------------------------------------------------: |
 | ESLint rules            | **5** — `latex-language` · `tex-build` · `papers` · `review-findings-cause` · `doc-fields` |
 | harnesses               |                                                                                     **57** |
-| mutation batteries      |                                                                                     **34** |
 | skills                  |                                                                                     **24** |
 | hooks (runnable `.mjs`) |                                                                                      **5** |
 | repo-wide scripts       |                                                                                          5 |
@@ -75,8 +74,8 @@ nodes.
 
 **3. Every check needs BOTH halves, or it is not tested.** It must FIRE on a planted defect
 and stay QUIET on a clean fixture. A check that has only been seen quiet is
-indistinguishable from a dead one — silence is its success state. Prove the fire half with a
-mutation, and assert the patch actually landed before trusting a green run.
+indistinguishable from a dead one — silence is its success state. Prove the fire half by
+seeing the test go RED before the fix lands (§ Testing — how a test is written here).
 
 **4. `exit 0` with empty output is NOT "clean".** A rule whose glob matched no files reports
 exactly like a rule that passed. Any rule shipped here must be loud when its input set is
@@ -461,26 +460,8 @@ node scripts/rules-see-files.mjs   # also part of npm run check
 It is per RULE, not per glob, and that distinction is the point: a rule can be enabled in one
 block whose glob is empty while a different block is busy, so "some glob matched something" is
 not evidence about the rule you care about. Both halves are tested
-(`scripts/rules-see-files.harness.mjs`) and both directions are mutated
-(`scripts/rules-see-files.mutations.mjs` — under-reporting and over-reporting must die on
-_different_ assertions, or only one half of the guard is really tested).
-
-## Mutations — hand-written batteries are deprecated (#52)
-
-The `*.mutations.mjs` batteries (string replacements of source lines, run through
-`lib/mutation-driver.mjs`) are being removed. The idea stays — a test must be seen going red
-when the code breaks — but the vehicle is not this one.
-
-- **Do not create a new `*.mutations.mjs`**, and **do not add cases to an existing one.**
-- **Record what a test guards as a comment directly above its assertion** (`// Guards: …`).
-- The rule is enforced, not asked for: `scripts/mutation-batteries-frozen.mjs` (part of
-  `npm run check` and CI) fails on a battery missing from `scripts/mutation-batteries.frozen.json`,
-  on a listed battery with more or fewer cases than recorded, and on a listed file that is gone.
-  The list may only shrink — delete a battery or a case, then delete or lower its entry.
-- The intended replacement is a real mutation-testing tool (StrykerJS) or nothing; that is
-  decided in #52, not in a pull request that happens to touch a battery.
-
-The batteries that remain still run (`node scripts/run-mutations.mjs`) until #52 retires them.
+(`scripts/rules-see-files.harness.mjs`), under-reporting and over-reporting each by an
+assertion of its own.
 
 ## Cost
 
@@ -508,22 +489,26 @@ justified two hundred lines above precisely by these minutes being free.
 
 ```bash
 npm test                    # vitest over *.test.ts, then the vigiles harnesses
+npm run coverage            # the same run under c8; fails below the thresholds in .c8rc.json
 npx vitest run <file>       # one unit test
 npx vigiles test <file>     # one harness
 ```
 
 **Two kinds of test, told apart by what the file imports.** A `*.harness.*` file tests the agent
 surface and imports `runHook`, `runHarnessTest` or `runEval` from vigiles; everything else is a plain
-unit test, `*.test.ts`, run by vitest — and new tests are TypeScript. Older harnesses that
+unit test run by vitest, beside the module it tests: `<module>.test.ts` for a `.ts` module, and
+`<module>.test.mjs` for a `.mjs` one (TypeScript has no types to check a JS module against, and
+`allowJs` was measured to break a dozen existing `@ts-expect-error` imports). Older harnesses that
 import none of the three are frozen in `scripts/harness-api.frozen.json`, which only shrinks;
 `scripts/harness-api.test.ts` parses every harness's imports and holds both halves (#77). vitest
 exits 1 when no file matches, and it transpiles without type-checking, so `npm run check` runs
 `tsc -p tsconfig.test.json` as its own gate.
 
-**Local = the fast gates on what you touched; the full `npm run check` = CI.** Locally run vitest on
-the touched test files, `npx tsc --noEmit`, `npx eslint <touched files>` and `npm run fmt:check`, then
-push and read CI by job name. The repo is public, so CI is free, and it also runs the TeX e2e that
-cannot run locally; a local full run takes 10-15 min, most of it the mutation batteries (#52).
+**While working: the fast gates on what you touched. Before every push: `npm run check`.** While
+editing, run vitest on the touched test files (`npx vitest run <file or folder>`), `npx tsc --noEmit`,
+`npx eslint <touched files>` and `npm run fmt:check`. Before pushing, run the full `npm run check`
+(about three minutes) and read its exit code: it includes the 100% coverage gate, which a
+single-file run cannot judge. CI runs the same command plus the TeX e2e that cannot run locally.
 
 ⚠️ **Not `vigiles test .`** — the `.` is read as a FILE, the runner dies with
 `ERR_UNSUPPORTED_DIR_IMPORT`, and it still exits 0. See the measured table below.
@@ -534,34 +519,44 @@ Skills are tested **through vigiles** — a colocated `<skill>.harness.mjs` besi
 empty — issue #6.) Not through a bespoke script: a home-grown runner here once printed
 confident, byte-identical "clean" verdicts for three different skills that had never loaded.
 
-### Every npm script takes an exclusive lock, and that is not ceremony
-
-`npm run *` in this repository goes through `scripts/exclusive.mjs`, which holds
-`.vigiles/exclusive.lock` for the duration. A second gate started while one is running does not
-queue and does not race — it **refuses**, names the holder, and exits 3.
-
-🔴 **The reason is that the mutation batteries edit the working tree in place.** That strategy is
-deliberate (see `lib/mutation-driver.mjs` — copying the repo per mutation costs minutes instead
-of seconds), and its one cost is that any parallel reader sees a source file mid-mutation. The
-resulting failure is **false, non-deterministic, and blames the wrong file**: it reports a broken
-assertion, not a mutation, and it reads as "the suite is flaky". That has already cost a wrong
-conclusion here — two runs in a row produced _different_ error messages and the diagnosis "I broke
-round-diff" was incorrect.
-
-A prose instruction "don't run them at the same time" existed and did not work: prose does not
-execute, so it does not apply to the person in the other terminal, the agent, or the editor with
-tests on save. Measured live, with the batteries running:
-
-```
-$ npm test
-🔴 refused: this repository is busy with a run that EDITS FILES IN PLACE.
-   held by: pid 6645, "node scripts/run-mutations.mjs", since 2026-09-17T05:22:28.757Z
-RC=3
-```
-
-⚠️ A lock left behind by a process that no longer exists is **taken over** with a message, not
-respected. Otherwise one interrupted run would block the repository forever, and the first cure
-anybody reaches for would be "delete the lock by hand" — i.e. switching the mechanism off.
+### How a test is written here
+
+1. **Red first.** A new test is seen FAILING before the change that makes it pass — run it on
+   the unfixed code, watch it go red at its own assertion, then fix. A test that has only ever
+   been green is indistinguishable from one that cannot fail. Never add a file that patches
+   source to prove a test can fail — seeing it red once, here, is that proof.
+2. **Assert the whole value.** Compare the entire returned value (`assert.deepEqual`,
+   `expect(x).toEqual(…)`), not a substring of it or one field. A substring assertion passes on
+   output that is wrong everywhere else — a defect found here over and over
+   (`"that is the"` matching two different messages, a bare word the usage block always prints).
+   A substring is right only when the value is prose whose wording is not the subject; then say
+   so in a comment.
+3. **Test what the code DOES, never what its source SAYS.** A test that reads a source file (a
+   `.mjs`, a `SKILL.md`, a config) and asserts it contains some text restates the file: rewording
+   turns it red while a real regression stays green. Assert behaviour instead: a return value, the
+   output and exit code of a run, what landed on disk, what a parser reports. Text is a legitimate
+   subject only when it IS the output (a message the program prints, a file it generates).
+4. **One assertion helper for harnesses: `lib/check.mjs`.** `const check = createChecker();` then
+   `check(label, cond, detail)`. A failure prints the label and the detail (a value is rendered
+   with `util.inspect`, a function is called only on failure), every call is counted
+   (`check.count`, for the summary line) and reported to vigiles. Do not define a local `check`.
+5. **Coverage is a gate.** `npm run check` and CI run `npm run coverage` — `npm test` under c8,
+   `--check-coverage` against `.c8rc.json`. c8 reads `NODE_V8_COVERAGE`, so a CLI a harness
+   spawns is measured too — unless the harness hands the child a fresh `env` without it. vitest
+   runs in the `threads` pool with native `import` (`vitest.config.ts` says why): under its
+   defaults c8 saw nothing vitest ran. The run preloads `test/coverage-src.mjs`, which answers
+   every import of `dist/*.js` with `src/*.ts`: otherwise a module the tests import directly AND
+   the spawned CLI loads compiled is measured twice, and its branches and functions stay red in
+   whichever copy did not run them. `npm test` without coverage still runs `dist/`.
+6. **No `c8 ignore`, and no guard deleted to reach 100%.** An effect a test cannot reach — a
+   race, a permission root is never denied, a broken install, a 270 MB download — is made
+   INJECTABLE (a `readdir`, an fs object, a manifest reader, a toolchain function) and the test
+   passes a fake. A precondition about an argument becomes the signature: the function takes the
+   value it needs, so a call without it cannot be written. A guard whose input can really occur
+   stays, with the test that reaches it. `scripts/coverage-config.test.ts` fails on any
+   coverage-ignore comment in a measured file (it reads comments off the parsed tree), and pins
+   `.c8rc.json`'s `exclude` list: a new exclusion fails there until it is added on purpose, with
+   its reason. Thresholds are 100 for lines, statements, functions and branches.
 
 ## `npm test` — `--min=1` stays, and here is what it is for
 

package/CONTRIBUTING.md

@@ -17,13 +17,20 @@ The second run is the one people skip, and it is the one that matters. A rule th
 finds nothing passes the first kind of test by accident — from outside, "there is nothing wrong
 here" and "this check never ran" look exactly the same.
 
-Older rules also have a **battery** (`*.mutations.mjs`): it deletes one thing the rule depends on
-and then demands the harness go red, at the specific assertion that thing belongs to. **These
-hand-written batteries are deprecated and being removed (#52).** Do not write a new one and do
-not add cases to an existing one; instead, say what an assertion guards in a comment directly
-above it (`// Guards: …`). `npm run check` fails on a new or grown battery — the frozen list in
-`scripts/mutation-batteries.frozen.json` may only shrink. Whether a real mutation-testing tool
-replaces them is decided in #52.
+Three rules for writing the test itself:
+
+1. **Red first.** Run a new test on the code BEFORE the fix and watch it fail at its own
+   assertion. A test that has only ever been green is indistinguishable from one that cannot fail.
+2. **Assert the whole value** — `assert.deepEqual` / `toEqual` on the entire result, not a
+   substring or one field. A substring passes on output that is wrong everywhere else. The
+   exception is prose whose wording is not the subject; say so in a comment.
+3. **Test what the code does, not what its source says.** A test that reads a source file and
+   asserts it contains some text restates the file: rewording turns it red, a real regression
+   stays green. Assert a return value, a run's output and exit code, or what landed on disk.
+
+Say what an assertion guards in a comment directly above it (`// Guards: …`). A harness asserts
+through the shared `lib/check.mjs` (`const check = createChecker()`), which prints the label and
+the detail on failure and counts every call; a new harness does not define its own `check`.
 
 A harness runs in this tree, against this working copy. That is the wrong shape for a defect that
 only exists once somebody else has installed the package — a path written inside a skill, a file
@@ -31,9 +38,9 @@ that never made it into the tarball, a PDF whose content is wrong while the exit
 Those are covered by the end-to-end runs, and [`docs/e2e.md`](docs/e2e.md) says which question
 belongs to which tier, and **when a change owes a new e2e rather than a harness**.
 
-It caught a real one on the way in: `js-yaml` 5 stopped parsing an unquoted date as a `Date`.
-Every harness stayed green under both majors, and only the battery noticed that the rule's
-date coercion had become dead code.
+An example of why asserting the value matters: `js-yaml` 5 stopped parsing an unquoted date as a
+`Date`, every harness stayed green under both majors, and the rule's date coercion had quietly
+become dead code — no test asserted the coerced value.
 
 ## Running the checks: one command
 
@@ -41,8 +48,8 @@ date coercion had become dead code.
 npm run check
 ```
 
-That is the whole instruction. It runs every gate in order — build, lint, every harness, every
-mutation battery, the install e2e under npm and pnpm, and a real `pdflatex` build — and ends
+That is the whole instruction. It runs every gate in order — build, lint, every harness, the
+install e2e under npm and pnpm, and a real `pdflatex` build — and ends
 
 by printing **which CI jobs it does not reproduce, and why**.
 
@@ -65,8 +72,8 @@ nobody covered — verified by adding a `windows` job and watching it fail.
 ## Layout
 
 ```
-eslint-rules/   the rules, each with its .harness.mjs beside it (older ones also a .mutations.mjs)
-lib/            shared readers — markdown, skill corpus, the mutation driver
+eslint-rules/   the rules, each with its .harness.mjs beside it
+lib/            shared readers — markdown, skill corpus
 hooks/          three hooks for vigiles — the code
 plugin/         the Claude Code plugin: wiring for those hooks, no code, no package.json
 skills/         24 stage skills
@@ -102,13 +109,19 @@ The README links only what a user needs. These are for people changing the packa
 
 ```bash
 npm install
-npm test                 # every harness, the tests' type-check, every *.test.ts (Node >= 22.18)
-node scripts/run-mutations.mjs   # run the remaining batteries (deprecated, #52 — do not add to them)
+npm test                 # every *.test.ts, then every harness (Node >= 22.18)
+npm run coverage         # the same, under c8, failing below the thresholds in .c8rc.json
 ```
 
 None of these are needed to USE the tool — they are here because the gates are part of the
 argument, not decoration.
 
+Coverage is 100% for lines, statements, functions and branches, and there is no `c8 ignore`:
+code a test cannot reach directly — a race, a permission, a broken install, a real download — takes
+the effect as a parameter (the ports in `src/ports`, an injected `readdir` or runner), and the test
+passes a fake. `scripts/coverage-config.test.ts` fails on a coverage-ignore comment and on any
+change to `.c8rc.json`'s exclude list that was not made there on purpose.
+
 ## Adding a venue
 
 A venue is a **preset**, a JSONC file in `skills/submit-paper/references/venues/`, validated by
@@ -166,8 +179,7 @@ Licensing differs too: that suite is CC BY-NC 4.0, this is MIT.
 - **scorecard** — `PIPELINE-STATUS.md`, the file above. One per paper.
 - **frozen** — a copy of the exact PDF or `.tex` that was sent, kept in `versions/`. Bytes, not a
   commit reference: squash and `gc` destroy commit references, and did.
-- **harness** — the test beside a rule. **battery** — a set of edits that try to break a harness
-  (deprecated, being removed in #52).
+- **harness** — the test beside a rule.
 
 ## Also in the box