paperlint 3.1.0 → 3.1.2

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 ([`docs/testing.md`](docs/testing.md)).
 
 **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
@@ -189,6 +188,12 @@ the instruction and never the evidence — the same split as rules 9 and 10 and
 🔴 The argument "we need another command for X" is, in every tool examined, an argument that
 the CONFIG is not declaring something. Check that before adding a verb.
 
+Rejected on 2026-09-27, so it is not proposed again: a separate `paperlint refs` command for the
+reference check. The slowness it would have moved (#107) was a cache thrown away after every build,
+not a missing verb. The fix keeps the check in `build` and commits what the services answered in
+`<paper>/repro/references-cache.json` — **raw responses, never verdicts**: verdicts are derived
+again on every build, so a checker fix reaches every paper ([`docs/references.md`](docs/references.md)).
+
 ## Distribution — one install path: npm, then `paperlint init`
 
 `npm i -D paperlint` brings all the code — rules, skills, hooks, scripts. `paperlint init`
@@ -461,26 +466,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
 
@@ -506,88 +493,17 @@ justified two hundred lines above precisely by these minutes being free.
 
 ## Testing
 
-```bash
-npm test                    # vitest over *.test.ts, then the vigiles harnesses
-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
-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).
-
-⚠️ **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.
-
-Skills are tested **through vigiles** — a colocated `<skill>.harness.mjs` beside the skill.
-(This read «Skills, if and when they arrive» until 2026-09-17; there are 24 of them under
-`skills/` carrying a `SKILL.md`, and the README's opening line claimed the repository was
-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.
-
-## `npm test` — `--min=1` stays, and here is what it is for
-
-The script is `vigiles test --min=1`. It went green on 2026-09-11 when the first harnesses
-landed; before that it correctly exited 1:
-
-```
-✗ vigiles test: --min=1 but only 0 test file(s) matched — evals never executed
-  (check the paths/globs, or that the run was reached).
-```
-
-Do **not** "fix" a future red by dropping `--min` — the flag is the only thing standing
-between "every test passed" and "no test ran", which is rule 4 applied to the test runner
-itself.
-
-🔴 **Two ways this command lies if written differently, both measured 2026-09-11:**
-
-| form                   | what happens                                                                | exit  |
-| ---------------------- | --------------------------------------------------------------------------- | ----- |
-| `vigiles test .`       | `.` is read as a FILE — `ERR_UNSUPPORTED_DIR_IMPORT`, uncaught, runner dies | **0** |
-| `vigiles test`         | `No **/*.harness.{mjs,cjs,js,mts,cts,ts} files found.`                      | **0** |
-| `vigiles test --min=1` | names the empty match and fails                                             | **1** |
-
-The first row is the worse one: the runner crashed with a stack trace and still reported
-success. `package.json` shipped `vigiles test .` from the initial scaffold until this was
-measured — so the repo's own test command had never once executed a test, and said nothing.
+| you are testing                                                            | kind                                          |
+| -------------------------------------------------------------------------- | --------------------------------------------- |
+| a pure function                                                            | unit — vitest, `<module>.test.ts` beside it   |
+| a use case or adapter that reaches disk, a process, the network, the clock | integration — vitest, fakes through the ports |
+| a hook's decision, a skill's contract                                      | harness — vigiles, `<surface>.harness.mjs`    |
+| the installed package, a real TeX build                                    | e2e — `test/e2e/*.mjs`                        |
+
+Red first · assert the whole value · test what the code does, never what its source says · no test
+touches the real network · 100% coverage, no `c8 ignore`. **Before every push: `npm run check`,
+exit code read without a pipe.** Everything else — where files live, how fakes are injected, the
+`--min=1` trap: [`docs/testing.md`](docs/testing.md).
 
 ## Commits
 

package/CONTRIBUTING.md

@@ -10,20 +10,10 @@ it is below.
 
 ## How this is tested
 
-Every rule ships with a **harness**: a test that runs the rule twice. Once on a file with a defect
-planted in it, where the rule must find it. Once on a clean file, where the rule must say nothing.
-
-The second run is the one people skip, and it is the one that matters. A rule that is broken and
-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.
+Unit and integration tests run under vitest beside the module they test; harnesses run under
+vigiles and cover what an agent sees; end-to-end runs install the package and build real PDFs.
+Every test is seen red first, asserts the whole value, and tests what the code does rather than
+what a file says. [`docs/testing.md`](docs/testing.md) says which kind to write and how.
 
 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 +21,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 +31,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 +55,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
@@ -78,6 +68,7 @@ docs/           evidence that would otherwise bloat CLAUDE.md:
                   incidents.md  what broke, measured
                   install.md  the install contract
                   e2e.md  the end-to-end runs, and when a change owes one
+                  testing.md  which kind of test to write, and the rules for all of them
 ```
 
 Most of the package's rules run on users' papers and are described for users in
@@ -94,6 +85,8 @@ The README links only what a user needs. These are for people changing the packa
   `init` writes, supported package managers, troubleshooting, and why it is shaped this way
 - [`docs/e2e.md`](docs/e2e.md) — the end-to-end runs: what each proves, what they do not cover,
   and when a change owes one
+- [`docs/testing.md`](docs/testing.md) — the kinds of test, which one a change needs, and the rules
+  for every one
 - [`docs/incidents.md`](docs/incidents.md) — what broke, measured
 - [`docs/package-shape-options.md`](docs/package-shape-options.md) — the options for the
   package's shape, and the ranking
@@ -102,13 +95,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 +165,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
 

package/README.md

@@ -27,7 +27,7 @@ before you submit.** It comes in two parts:
 
   Smaller slips too: `§` for "Section", `.05` for `0.05` — fixed for you.
 
-- 🧠 **Skills for [Claude Code](https://claude.com/claude-code)** — optional, 24 of them, covering the
+- 🧠 **Skills for [Claude Code](https://claude.com/claude-code)** — optional, covering the
   whole pipeline: the idea, the venue, the study, the draft, the reviews, submission.
 
 ## Contents
@@ -173,17 +173,20 @@ what it does — "is this idea worth a paper?", "find me a venue for this". `ini
 - **A ready / not ready verdict before you submit**, worst problem first. `harden-paper`
 - **Where your paper stands**, measured from the real build. `paper-status`
 
-All 24, by stage: [`docs/skills.md`](docs/skills.md).
+Every skill, by stage: [`docs/skills.md`](docs/skills.md).
 
 ## 🔍 Lint and build
 
-|        | `paperlint build`                                                                            | `paperlint lint`                                                                                      |
-| ------ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| needs  | Node, TeX Live, the network                                                                  | Node                                                                                                  |
-| does   | compiles `paper.tex`, measures the PDF, checks each reference online (exists, right authors) | checks the source, and judges what build recorded: page limit, fonts, the reference results — offline |
-| writes | `paper.pdf`, and in `_build/` the measurements and the reference results                     | nothing (`--fix`: the three fixable slips)                                                            |
+|        | `paperlint build`                                                                                       | `paperlint lint`                                                                                      |
+| ------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| needs  | Node, TeX Live, the network                                                                             | Node                                                                                                  |
+| does   | compiles `paper.tex`, measures the PDF, checks each reference online (exists, right authors)            | checks the source, and judges what build recorded: page limit, fonts, the reference results — offline |
+| writes | `paper.pdf`, in `_build/` the measurements and the reference results, and `repro/references-cache.json` | nothing (`--fix`: the three fixable slips)                                                            |
 
 - If `paper.pdf` or the bibliography changed since the last build, lint fails and tells you to rebuild.
+- Commit `repro/references-cache.json`: it keeps what the citation services answered, so a build
+  asks only about new or edited entries (and answers older than 30 days), so an unchanged
+  bibliography usually builds without the network ([`docs/references.md`](docs/references.md)).
 - Lint also checks the pipeline's own records: `PIPELINE-STATUS.md`, reviews, notes on related
   papers ([`docs/rules.md`](docs/rules.md)).
 - The rules run on ESLint, so a deliberate exception is a comment on the line above:
@@ -295,6 +298,7 @@ Only `paperlint lint --fix`, and only three rules: `paper/section-word` (`§`
 - [`docs/install.md`](docs/install.md) — what `init` does, the hooks, package managers, troubleshooting
 - [`docs/configuration.md`](docs/configuration.md) — every setting, how `build` compiles, using your own ESLint
 - [`docs/rules.md`](docs/rules.md) — every check, venue presets, recording a submitted PDF
+- [`docs/references.md`](docs/references.md) — the reference check, and the cache file to commit
 - [`docs/optional-rules.md`](docs/optional-rules.md) — checks only some venues need
 - [`docs/toolchain.md`](docs/toolchain.md) — TeX Live, and Banal (HotCRP's page-geometry checker, GPL)
 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — how the package is tested and released, and adding a venue to it

package/bin/paperlint.test.mjs

@@ -0,0 +1,45 @@
+/**
+ * `bin/paperlint.mjs` — the shim's one decision of its own: with no `dist/` beside it (a clone
+ * before `npm run build`, a git dependency installed with `--ignore-scripts`) it refuses loudly,
+ * naming the missing file and both remedies, instead of an ERR_MODULE_NOT_FOUND from the loader.
+ *
+ * The missing build is staged with a preload that makes `existsSync` answer "no" for exactly
+ * `dist/cli.js` — the shim reads the real file, so the real shim is what is measured.
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { test } from "vitest";
+
+const BIN = fileURLToPath(new URL("./paperlint.mjs", import.meta.url));
+const DIST = fileURLToPath(new URL("../dist/cli.js", import.meta.url));
+
+const HIDE_DIST = [
+  'import fs from "node:fs";',
+  'import { syncBuiltinESMExports } from "node:module";',
+  "const real = fs.existsSync;",
+  'fs.existsSync = (p) => (String(p).endsWith("/dist/cli.js") ? false : real(p));',
+  "syncBuiltinESMExports();",
+].join("\n");
+
+test("no dist/: exit 2, the missing path, and both remedies — nothing from the loader", () => {
+  const r = spawnSync(
+    process.execPath,
+    [
+      "--import",
+      `data:text/javascript,${encodeURIComponent(HIDE_DIST)}`,
+      BIN,
+      "--version",
+    ],
+    { encoding: "utf8" },
+  );
+  assert.equal(r.status, 2);
+  assert.equal(r.stdout, "");
+  const [first, ...rest] = r.stderr.split("\n");
+  assert.equal(first, `paperlint: not built — ${DIST} missing.`);
+  assert.match(
+    rest.join("\n"),
+    /In a clone: `npm run build`\. For a git dependency: reinstall without `--ignore-scripts`\./,
+  );
+  assert.doesNotMatch(r.stderr, /ERR_MODULE_NOT_FOUND/);
+});

package/dist/adapters/node/files.io.d.ts

@@ -1,3 +1,5 @@
 import type { Files } from "../../ports/files.ts";
+/** An error's errno code; anything thrown that is not an Error has none. */
+export declare const errorCode: (e: unknown) => unknown;
 export declare const nodeFiles: Files;
 //# sourceMappingURL=files.io.d.ts.map

package/dist/adapters/node/files.io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.io.d.ts","sourceRoot":"","sources":["../../../src/adapters/node/files.io.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAKlD,eAAO,MAAM,SAAS,EAAE,KAsBvB,CAAC"}
+{"version":3,"file":"files.io.d.ts","sourceRoot":"","sources":["../../../src/adapters/node/files.io.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,4EAA4E;AAC5E,eAAO,MAAM,SAAS,GAAI,GAAG,OAAO,KAAG,OAC6B,CAAC;AAErE,eAAO,MAAM,SAAS,EAAE,KAsBvB,CAAC"}

package/dist/adapters/node/files.io.js

@@ -1,7 +1,8 @@
 /** `Files` over `node:fs`. */
 import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
-const code = (e) => e instanceof Error ? e.code : undefined;
+/** An error's errno code; anything thrown that is not an Error has none. */
+export const errorCode = (e) => e instanceof Error ? e.code : undefined;
 export const nodeFiles = {
     isFile(p) {
         return statSync(p, { throwIfNoEntry: false })?.isFile() ?? false;
@@ -11,7 +12,7 @@ export const nodeFiles = {
             return readFileSync(p);
         }
         catch (e) {
-            if (code(e) === "ENOENT")
+            if (errorCode(e) === "ENOENT")
                 return null;
             throw e;
         }

package/dist/adapters/node/files.io.js.map

@@ -1 +1 @@
-{"version":3,"file":"files.io.js","sourceRoot":"","sources":["../../../src/adapters/node/files.io.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,OAAO,EACL,SAAS,EACT,YAAY,EACZ,UAAU,EACV,MAAM,EACN,QAAQ,EACR,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,MAAM,IAAI,GAAG,CAAC,CAAU,EAAW,EAAE,CACnC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAE,CAA2B,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAErE,MAAM,CAAC,MAAM,SAAS,GAAU;IAC9B,MAAM,CAAC,CAAe;QACpB,OAAO,QAAQ,CAAC,CAAC,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,KAAK,CAAC;IACnE,CAAC;IACD,SAAS,CAAC,CAAe;QACvB,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACtC,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IACD,WAAW,CAAC,CAAe,EAAE,KAAiB;QAC5C,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC;QACzB,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC;YACH,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC3B,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;CACF,CAAC"}
+{"version":3,"file":"files.io.js","sourceRoot":"","sources":["../../../src/adapters/node/files.io.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,OAAO,EACL,SAAS,EACT,YAAY,EACZ,UAAU,EACV,MAAM,EACN,QAAQ,EACR,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAU,EAAW,EAAE,CAC/C,CAAC,YAAY,KAAK,CAAC,CAAC,CAAE,CAA2B,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAErE,MAAM,CAAC,MAAM,SAAS,GAAU;IAC9B,MAAM,CAAC,CAAe;QACpB,OAAO,QAAQ,CAAC,CAAC,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,KAAK,CAAC;IACnE,CAAC;IACD,SAAS,CAAC,CAAe;QACvB,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,SAAS,CAAC,CAAC,CAAC,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAC3C,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IACD,WAAW,CAAC,CAAe,EAAE,KAAiB;QAC5C,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC;QACzB,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC;YACH,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC3B,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/adapters/pdfjs/fill.d.ts

@@ -25,11 +25,13 @@ export interface OperatorList {
 }
 /** `setFillRGBColor`'s argument: a `#rrggbb` string in current pdf.js, three 0-255 numbers in older ones. */
 export declare function hexOf(args: unknown): string;
+/** One drawn character and the fill it was drawn in. */
+interface Drawn {
+    readonly ch: string;
+    readonly fill: Fill;
+}
 /** Every drawn character, in content order, with the fill it was drawn in. */
-export declare function drawnCharacters(ops: ColourOps, list: OperatorList): {
-    chars: string[];
-    fills: Fill[];
-};
+export declare function drawnCharacters(ops: ColourOps, list: OperatorList): Drawn[];
 /** How far ahead the walk looks for an item it cannot find where it expects it. */
 export declare const LOOKAHEAD = 4000;
 /**
@@ -39,4 +41,13 @@ export declare const LOOKAHEAD = 4000;
  * a missed match can keep light text, never drop dark text.
  */
 export declare function fillsOf(ops: ColourOps, list: OperatorList, items: readonly string[]): Fill[];
+/**
+ * Each item paired with its fill — `fillsOf` for items that are not bare strings, so a caller never
+ * matches the two lists up by index.
+ */
+export declare function fillsFor<T>(ops: ColourOps, list: OperatorList, items: readonly T[], textOf: (item: T) => string): {
+    readonly item: T;
+    readonly fill: Fill;
+}[];
+export {};
 //# sourceMappingURL=fill.d.ts.map

package/dist/adapters/pdfjs/fill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fill.d.ts","sourceRoot":"","sources":["../../../src/adapters/pdfjs/fill.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAExD,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAGvD;AAED,0FAA0F;AAC1F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,OAAO,EAAE,CAAC;CACxC;AAKD,6GAA6G;AAC7G,wBAAgB,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAQ3C;AAuCD,8EAA8E;AAC9E,wBAAgB,eAAe,CAC7B,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,YAAY,GACjB;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,IAAI,EAAE,CAAA;CAAE,CAepC;AAED,mFAAmF;AACnF,eAAO,MAAM,SAAS,OAAO,CAAC;AAc9B;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,IAAI,EAAE,CAWR"}
+{"version":3,"file":"fill.d.ts","sourceRoot":"","sources":["../../../src/adapters/pdfjs/fill.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAExD,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAGvD;AAED,0FAA0F;AAC1F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,OAAO,EAAE,CAAC;CACxC;AAKD,6GAA6G;AAC7G,wBAAgB,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAQ3C;AAuCD,wDAAwD;AACxD,UAAU,KAAK;IACb,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,KAAK,EAAE,CAW3E;AAED,mFAAmF;AACnF,eAAO,MAAM,SAAS,OAAO,CAAC;AAoB9B;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,IAAI,EAAE,CAER;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAE,EAAE,CAY7C"}