paperlint 3.1.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
 

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"}

package/dist/adapters/pdfjs/fill.js

@@ -42,8 +42,7 @@ function applyState(ops, fn, args, s) {
 /** Every drawn character, in content order, with the fill it was drawn in. */
 export function drawnCharacters(ops, list) {
     const s = { cur: { fill: { kind: "unknown" }, mode: 0 }, stack: [] };
-    const chars = [];
-    const fills = [];
+    const drawn = [];
     list.fnArray.forEach((fn, i) => {
         const args = list.argsArray[i];
         if (applyState(ops, fn, args, s))
@@ -51,22 +50,25 @@ export function drawnCharacters(ops, list) {
         if (fn !== ops.showText && fn !== ops.showSpacedText)
             return;
         const fill = s.cur.mode === 3 ? { kind: "invisible" } : s.cur.fill;
-        for (const ch of squeeze(glyphText(args))) {
-            chars.push(ch);
-            fills.push(fill);
-        }
+        for (const ch of squeeze(glyphText(args)))
+            drawn.push({ ch, fill });
     });
-    return { chars, fills };
+    return drawn;
 }
 /** How far ahead the walk looks for an item it cannot find where it expects it. */
 export const LOOKAHEAD = 4000;
-/** The position at or after `from` where `want` starts in `chars`, or -1 within the look-ahead. */
-function findRun(chars, want, from) {
-    const limit = Math.min(chars.length, from + LOOKAHEAD);
-    for (let q = from; q < limit; q++)
-        if (want.every((ch, k) => chars[q + k] === ch))
-            return q;
-    return -1;
+/**
+ * Where `want` starts in `drawn`, at or after `from` within the look-ahead, and the fill it was
+ * drawn in — or null. The fill comes from the matched element itself, not a second lookup.
+ */
+function findRun(drawn, want, from) {
+    const window = drawn.slice(from, from + LOOKAHEAD);
+    for (const [i, d] of window.entries()) {
+        const at = from + i;
+        if (want.every((ch, k) => drawn[at + k]?.ch === ch))
+            return { at, fill: d.fill };
+    }
+    return null;
 }
 /**
  * The fill of each text item. pdf.js's text content carries no colour, so the operator list is
@@ -75,17 +77,25 @@ function findRun(chars, want, from) {
  * a missed match can keep light text, never drop dark text.
  */
 export function fillsOf(ops, list, items) {
-    const { chars, fills } = drawnCharacters(ops, list);
+    return fillsFor(ops, list, items, (text) => text).map((p) => p.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 function fillsFor(ops, list, items, textOf) {
+    const drawn = drawnCharacters(ops, list);
     let at = 0;
-    return items.map((text) => {
+    const fillOf = (text) => {
         const want = [...squeeze(text)];
         if (want.length === 0)
             return { kind: "unknown" };
-        const q = findRun(chars, want, at);
-        if (q < 0)
+        const hit = findRun(drawn, want, at);
+        if (hit === null)
             return { kind: "unknown" };
-        at = q + want.length;
-        return fills[q] ?? { kind: "unknown" };
-    });
+        at = hit.at + want.length;
+        return hit.fill;
+    };
+    return items.map((item) => ({ item, fill: fillOf(textOf(item)) }));
 }
 //# sourceMappingURL=fill.js.map