paperlint 3.0.0 → 3.1.1

package/docs/prior-art/test-tooling.md

@@ -1,12 +1,12 @@
-# What we test with, and why there is no test framework here
+# What we test with
 
-**Question this file answers:** this package has 57 `*.harness.mjs` files of plain
-`node:assert/strict`, three bespoke e2e scripts, and no jest, vitest, mocha, ava or `node:test`.
-Is that a gap? Should an npm package's install be tested through a local registry?
+**Question this file answers:** should an npm package's install be tested through a local
+registry, and which tests belong to which tool?
 
-**Verdict: change nothing.** A general-purpose runner would buy a reporter and a second answer to
-"do the tests pass". A local registry is what MULTI-package repositories reach for; a single-package
-CLI packs a tarball and installs it. Both conclusions have named triggers for revisiting, below.
+**Verdict.** Unit tests run on vitest (`*.test.ts` / `*.test.mjs`); agent-facing checks are vigiles
+harnesses; the install and build are end-to-end scripts. The install is tested by packing a
+tarball and installing it by path, not through a local registry: a registry is what
+MULTI-package repositories reach for. That conclusion has named triggers for revisiting, below.
 
 ---
 
@@ -27,10 +27,6 @@ So the genuinely agent-facing harnesses are three: `hooks/hooks.harness.mjs` (`r
 (`runHarnessTest`, which spawns the real `claude` binary against a scripted model), and the skill
 contract checks. Everything else is ordinary Node testing that happens to carry the suffix.
 
-⚠️ **The suffix is a CONTRACT, not a style choice.** `lib/mutation-driver.mjs` pairs batteries to
-harnesses by it. Renaming files for a new runner would break that, which has nothing to do with
-running tests.
-
 ## Why the install e2e stays a script
 
 `test/e2e/install.mjs` is one linear scenario per package manager with strictly dependent steps
@@ -81,25 +77,6 @@ answering. Recording this so the question "would it even run here" never has to
 documented install becoming a cold `npx <name>`. Then: verdaccio as a devDependency spawned by the
 script, Angular-style — not a Docker service in CI.
 
-## Why no vitest, and no `node:test` either
-
-vitest's value is its Vite transform pipeline, jsdom, module mocking and a watch UI. The tests here
-are plain `.mjs`, the sources are compiled by `tsc`, there is no DOM, and the design deliberately
-does not mock — it spawns real processes into temp directories, which is the right shape for a CLI.
-So vitest would add vite and a native esbuild binary to a package whose install weight is itself
-under scrutiny, and nothing breaks without it.
-
-`node:test` costs no dependency but creates the two-answers problem verbatim: a second discovery
-mechanism (`--test` globs against the `.harness.mjs` suffix) and a second exit code.
-
-**What staying honestly costs:** a top-level `assert` stops at the FIRST failure, so a table-driven
-test over many fixtures reports one row per run. Also no name-level filtering (file-level exists:
-`vigiles test <file>`).
-
-**Trigger to revisit:** when continue-after-failure is measurably costing iteration time on a
-table-driven test. The answer then is `node:test`, never vitest, and it must run under the same
-`npm test` line rather than beside it.
-
 ## One known limit, recorded so it is not claimed
 
 **Yarn Berry (PnP) cannot be supported as things stand.** `plugin/hooks/hooks.json` addresses

package/docs/rules.md

@@ -3,30 +3,30 @@
 The README lists what each check catches in one line. This page says exactly which file each one
 reads and when it fails. Errors fail `paperlint lint`; warnings print and do not.
 
-| Rule                           | Level | Reads                                         | Fails when                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------ | ----- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `paper/stages`                 | error | `PIPELINE-STATUS.md`                          | a declared stage's PDF is missing, or the `bytes:` it names does not match the file's real size, or a frozen PDF exists that no stage declares                                                                                                                                                                                  |
-| `paper/source`                 | error | `PIPELINE-STATUS.md`                          | a declared stage has no frozen `.tex` beside its PDF (a commit hash does not count — squash and gc destroy it)                                                                                                                                                                                                                  |
-| `paper/author-list`            | error | `paper.tex` → `_build/references.json`        | an entry's authors are not those of the version it cites — typically the arXiv preprint's list under a published venue. Checked online by `paperlint build` (DBLP), reported on the entry's own line                                                                                                                            |
-| `paper/research-question`      | warn  | `paper.tex`, `paper.md`, `PIPELINE-STATUS.md` | a stage is declared and either the scorecard has no `researchQuestion` field, or it has one the paper does not contain. The declared sentence is compared against the source with whitespace collapsed — your words, not a pattern. Advisory, because nothing here can judge whether what you declared _is_ a research question |
-| `paper/section-word`           | warn  | `paper.tex`, `paper.md`                       | `§` or `\S\ref` instead of the word Section. **Fixable:** `--fix` writes `Section~\ref{…}` / `Section 5`                                                                                                                                                                                                                        |
-| `paper/leading-zero`           | warn  | `paper.tex`, `paper.md`                       | a decimal below 1 without its leading zero (`.05` instead of `0.05`, IEEE / ISO 80000-1 style), counted only where the reader sees it — prose, math and table cells, not macro options, column specs, comments, code or tikz. **Fixable**                                                                                       |
-| `paper/figure-ref-style`       | warn  | `paper.tex`                                   | `Fig.~\ref` and `Figure~\ref` mixed in one document; each minority occurrence is reported. **Fixable:** `--fix` writes the majority form                                                                                                                                                                                        |
-| `bib/reachable-entry`          | warn  | `paper.tex` (its `filecontents` bibliography) | an entry has no doi, url or arXiv id — a reader has nothing to follow. Reported on the entry; no fix, the link has to be looked up                                                                                                                                                                                              |
-| `paper/cite-exists`            | error | `paper.tex` → `_build/references.json`        | an entry's doi or arXiv id resolves to nothing, or to a different work. Checked online by `paperlint build`; a work that was merely not found is not a finding                                                                                                                                                                  |
-| `paper/refs-fresh`             | error | `paper.tex` → `_build/references.json`        | the bibliography changed since the build checked it (its SHA-256 differs) — run `npx paperlint build`                                                                                                                                                                                                                           |
-| `paper/refs-checked`           | warn  | `paper.tex` → `_build/references.json`        | the paper has a bibliography and no build has checked it, or the last build could not (no network) — so the two rules above did not run                                                                                                                                                                                         |
-| `tex/future-promise`           | warn  | `paper.tex`                                   | a camera-ready build still says "will be released" about something already handed over                                                                                                                                                                                                                                          |
-| `tex/acm-frontmatter-override` | error | `paper.tex`                                   | an `acmart` build overrides ACM's front-matter commands and drops template elements from page 1                                                                                                                                                                                                                                 |
-| `review/frontmatter`           | error | `reviews/*.md`                                | the review's frontmatter fails paperlint's JSON Schema — a `findings` record without `id`/`status`, an unknown field, or an **open** finding with no `cause` (`skill-defect` · `missing-skill` · `hook` · `rule`). A review with no `findings` key is not checked for findings                                                  |
-| `sibling/frontmatter`          | warn  | `siblings/*.md` (not `README.md`)             | a sibling card's frontmatter has no `read:` saying how much of the competing paper was read (`full` · `abstract` · `none`)                                                                                                                                                                                                      |
-| `pdf/fresh`                    | error | `paper.tex` → `_build/paper.facts.json`       | the paper names a venue and the facts cannot be judged: not JSON, a schema other than 2, or they describe a PDF that is gone or differs from the one on disk (its SHA-256)                                                                                                                                                      |
-| `pdf/profile`                  | error | `paper.tex` → `paperlint.json`                | `paperlint.json` is not JSON or has an unknown key, its `extends` does not resolve (not found, a cycle, a chain longer than four, a preset that fails the schema, an npm name), it names no `kind` while the preset has kinds, or names a kind the preset does not have                                                         |
-| `pdf/fonts`                    | error | `paper.tex` → `_build/paper.facts.json`       | a font the pages draw is Type 3 or not embedded, or no font starts with the family the venue preset names for body text (`fonts_text`) or headings (`fonts_title`)                                                                                                                                                              |
-| `pdf/geometry`                 | error | `paper.tex` → `_build/paper.facts.json`       | the page width or height is more than `dimTol` (default 0.05 in) off the preset's, or the column count differs                                                                                                                                                                                                                  |
-| `pdf/limits`                   | error | `paper.tex` → `_build/paper.facts.json`       | body or reference pages exceed the limit of the paper's kind, or the reference font size is outside the preset's range widened by `body_pt_tol`                                                                                                                                                                                 |
-| `pdf/body-size`                | warn  | `paper.tex` → `_build/paper.facts.json`       | the body font size is more than `body_pt_tol` off the preset's. A warning: banal measures the mode of the rendered text, not the declared size (9.30 pt measured at a declared 9)                                                                                                                                               |
-| `pdf/measured`                 | warn  | `paper.tex` → `_build/paper.facts.json`       | the paper's `paperlint.json` names no venue preset yet; or it names one and there are no facts (it was not built), or the facts carry no page geometry (banal was not found) — so the checks above did not run                                                                                                                  |
+| Rule                           | Level | Reads                                         | Fails when                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------ | ----- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `paper/stages`                 | error | `PIPELINE-STATUS.md`                          | a declared stage's PDF is missing, or the `bytes:` it names does not match the file's real size, or a frozen PDF exists that no stage declares                                                                                                                                                                                                                                                                                                                |
+| `paper/source`                 | error | `PIPELINE-STATUS.md`                          | a declared stage has no frozen `.tex` beside its PDF (a commit hash does not count — squash and gc destroy it)                                                                                                                                                                                                                                                                                                                                                |
+| `paper/author-list`            | error | `paper.tex` → `_build/references.json`        | an entry's authors are not those of the version it cites — typically the arXiv preprint's list under a published venue. Checked online by `paperlint build` (DBLP), reported on the entry's own line                                                                                                                                                                                                                                                          |
+| `paper/research-question`      | warn  | `paper.tex`, `paper.md`, `PIPELINE-STATUS.md` | a stage is declared and either the scorecard has no `researchQuestion` field, or it has one the paper does not contain. The declared sentence is compared against the source with whitespace collapsed — your words, not a pattern. Advisory, because nothing here can judge whether what you declared _is_ a research question                                                                                                                               |
+| `paper/section-word`           | warn  | `paper.tex`, `paper.md`                       | `§` or `\S\ref` instead of the word Section. **Fixable:** `--fix` writes `Section~\ref{…}` / `Section 5`                                                                                                                                                                                                                                                                                                                                                      |
+| `paper/leading-zero`           | warn  | `paper.tex`, `paper.md`                       | a decimal below 1 without its leading zero (`.05` instead of `0.05`, IEEE / ISO 80000-1 style), counted only where the reader sees it — prose, math and table cells, not macro options, column specs, comments, code or tikz. A number right after `¶` or `§` (`¶¶.42`) is a paragraph designator and is not reported; in a paragraph that cites numbers that way, another bare decimal is reported without a fix, with the zero as a suggestion. **Fixable** |
+| `paper/figure-ref-style`       | warn  | `paper.tex`                                   | `Fig.~\ref` and `Figure~\ref` mixed in one document; each minority occurrence is reported. **Fixable:** `--fix` writes the majority form                                                                                                                                                                                                                                                                                                                      |
+| `bib/reachable-entry`          | warn  | `paper.tex` (its `filecontents` bibliography) | an entry has no doi, url or arXiv id — a reader has nothing to follow. Reported on the entry; no fix, the link has to be looked up                                                                                                                                                                                                                                                                                                                            |
+| `paper/cite-exists`            | error | `paper.tex` → `_build/references.json`        | an entry's doi or arXiv id resolves to nothing, or to a different work. Checked online by `paperlint build`; a work that was merely not found is not a finding                                                                                                                                                                                                                                                                                                |
+| `paper/refs-fresh`             | error | `paper.tex` → `_build/references.json`        | the bibliography changed since the build checked it (its SHA-256 differs) — run `npx paperlint build`                                                                                                                                                                                                                                                                                                                                                         |
+| `paper/refs-checked`           | warn  | `paper.tex` → `_build/references.json`        | the paper has a bibliography and no build has checked it, or the last build could not (no network) — so the two rules above did not run                                                                                                                                                                                                                                                                                                                       |
+| `tex/future-promise`           | warn  | `paper.tex`                                   | a camera-ready build still says "will be released" about something already handed over                                                                                                                                                                                                                                                                                                                                                                        |
+| `tex/acm-frontmatter-override` | error | `paper.tex`                                   | an `acmart` build overrides ACM's front-matter commands and drops template elements from page 1                                                                                                                                                                                                                                                                                                                                                               |
+| `review/frontmatter`           | error | `reviews/*.md`                                | the review's frontmatter fails paperlint's JSON Schema — a `findings` record without `id`/`status`, an unknown field, or an **open** finding with no `cause` (`skill-defect` · `missing-skill` · `hook` · `rule`). A review with no `findings` key is not checked for findings                                                                                                                                                                                |
+| `sibling/frontmatter`          | warn  | `siblings/*.md` (not `README.md`)             | a sibling card's frontmatter has no `read:` saying how much of the competing paper was read (`full` · `abstract` · `none`)                                                                                                                                                                                                                                                                                                                                    |
+| `pdf/fresh`                    | error | `paper.tex` → `_build/paper.facts.json`       | the paper names a venue and the facts cannot be judged: not JSON, a schema other than 2, or they describe a PDF that is gone or differs from the one on disk (its SHA-256)                                                                                                                                                                                                                                                                                    |
+| `pdf/profile`                  | error | `paper.tex` → `paperlint.json`                | `paperlint.json` is not JSON or has an unknown key, its `extends` does not resolve (not found, a cycle, a chain longer than four, a preset that fails the schema, an npm name), it names no `kind` while the preset has kinds, or names a kind the preset does not have                                                                                                                                                                                       |
+| `pdf/fonts`                    | error | `paper.tex` → `_build/paper.facts.json`       | a font the pages draw is Type 3 or not embedded, or no font starts with the family the venue preset names for body text (`fonts_text`) or headings (`fonts_title`)                                                                                                                                                                                                                                                                                            |
+| `pdf/geometry`                 | error | `paper.tex` → `_build/paper.facts.json`       | the page width or height is more than `dimTol` (default 0.05 in) off the preset's, or the column count differs                                                                                                                                                                                                                                                                                                                                                |
+| `pdf/limits`                   | error | `paper.tex` → `_build/paper.facts.json`       | body or reference pages exceed the limit of the paper's kind, or the reference font size is outside the preset's range widened by `body_pt_tol`                                                                                                                                                                                                                                                                                                               |
+| `pdf/body-size`                | warn  | `paper.tex` → `_build/paper.facts.json`       | the body font size is more than `body_pt_tol` off the preset's. A warning: banal measures the mode of the rendered text, not the declared size (9.30 pt measured at a declared 9)                                                                                                                                                                                                                                                                             |
+| `pdf/measured`                 | warn  | `paper.tex` → `_build/paper.facts.json`       | the paper's `paperlint.json` names no venue preset yet; or it names one and there are no facts (it was not built), or the facts carry no page geometry (banal was not found) — so the checks above did not run                                                                                                                                                                                                                                                |
 
 Optional rules — off unless you turn them on in the `rules` setting, because only some venues need
 them — are on their own page: [`optional-rules.md`](optional-rules.md). Today there is one,
@@ -200,7 +200,11 @@ rules, which is why they list it above. Markdown papers are deprecated and being
 
 ## The scorecard's `bytes:` and `sourceBytes:`
 
-A stage in `PIPELINE-STATUS.md` looks like this:
+**When you submit,** copy the PDF and `paper.tex` you sent into the paper's `versions/` folder and
+record the stage in the front matter of `PIPELINE-STATUS.md` (the paper's scorecard). From then on
+`paper/stages` fails if that PDF goes missing or changes size, and `paper/source` if its source was
+not kept. Today you record it by hand; a command for it is planned
+([#100](https://github.com/zernie/paperlint/issues/100)). A stage looks like this:
 
 ```yaml
 ---

package/docs/skills.md

@@ -0,0 +1,80 @@
+# Skills
+
+Every skill paperlint ships, by the stages of [the pipeline](../README.md#-the-pipeline). Each line
+says what you get; the skill's name is the second column.
+
+You do not call them by name: you ask Claude Code for the thing ("is this idea worth a paper?"), and
+the skill whose description matches starts. `paperlint init` installs them into
+`.claude/skills/` ([`install.md`](install.md)). Each one's full instructions are its
+`skills/<name>/SKILL.md`.
+
+`test/skills-catalog.test.ts` fails when this list and the shipped `skills/` directory disagree.
+
+## Across every stage
+
+| you get                                                                                   | skill            |
+| ----------------------------------------------------------------------------------------- | ---------------- |
+| a guided path through the stages: what to do now, and which skill does it                 | `paper-pipeline` |
+| where the paper stands, measured: pages from the real build, what is checked, what blocks | `paper-status`   |
+
+## 1 · Idea
+
+| you get                                                                                 | skill                   |
+| --------------------------------------------------------------------------------------- | ----------------------- |
+| a go / no-go on the idea, with the reason and the smallest result that makes a paper    | `research-ideate`       |
+| who already works on it, dated against your deadline, and what you can still claim      | `map-prior-work`        |
+| one close competitor read in full: is yours "just X?", and the sentence that answers it | `analyze-sibling-paper` |
+| candidate mechanisms from other fields, when the work needs a design, not a measurement | `sweep-design-space`    |
+
+## 2 · Venue
+
+| you get                                                                        | skill                   |
+| ------------------------------------------------------------------------------ | ----------------------- |
+| a ranked list of venues that fit: deadline, page limit, indexing, remote talks | `find-venue`            |
+| what papers accepted at that venue do well, and what would make yours stronger | `study-accepted-papers` |
+| the deadlines worked backwards, as events in your calendar                     | `plan-paper-timeline`   |
+
+## 3 · Study
+
+| you get                                                                                    | skill             |
+| ------------------------------------------------------------------------------------------ | ----------------- |
+| a study design with honest statistics, and a reproduction artifact that checks its numbers | `build-benchmark` |
+
+## 4 · Draft
+
+| you get                                                                            | skill            |
+| ---------------------------------------------------------------------------------- | ---------------- |
+| a first draft from your results: claims sized, threats to validity written         | `draft-paper`    |
+| an outline where each section follows from the one before                          | `argument-arc`   |
+| a cut plan: what to cut, merge or move to the appendix                             | `tighten-paper`  |
+| what a reader with no context understood from your last edit, sentence by sentence | `cold-read-diff` |
+| the compiled pages as images, to read on a screen or a phone                       | `render-paper`   |
+
+## 5 · Review
+
+| you get                                                                       | skill                      |
+| ----------------------------------------------------------------------------- | -------------------------- |
+| a writing grade, with the sentence to fix for each point                      | `grade-paper-writing`      |
+| every cited work confirmed to exist, with the right authors, title and year   | `verify-citations`         |
+| one hostile review: overclaims, missing baselines, holes in the method        | `paper-adversarial-review` |
+| a simulated program committee: several reviews, a decision and the must-fixes | `pc-panel-review`          |
+| ready or not ready to submit, worst problem first                             | `harden-paper`             |
+
+## 6 · Submit
+
+| you get                                                             | skill                 |
+| ------------------------------------------------------------------- | --------------------- |
+| the submission, step by step: anonymization, the form, the artifact | `submit-paper`        |
+| the reproduction artifact uploaded to OSF for anonymous review      | `osf-artifact-upload` |
+
+## 7 · Camera-ready
+
+| you get                                                                                    | skill          |
+| ------------------------------------------------------------------------------------------ | -------------- |
+| the final version: authors back, the artifact public with a DOI, any disclosure done first | `camera-ready` |
+
+## 8 · Extend
+
+| you get                                                       | skill          |
+| ------------------------------------------------------------- | -------------- |
+| a plan for the next, stronger paper built on the accepted one | `extend-paper` |

package/eslint-rules/install-path-literals.harness.mjs

@@ -118,4 +118,20 @@ const cases = [];
   cases.push("js quiet on a module that asks the port");
 }
 
-for (const c of cases) recordCheck(c);
+// ── 5. A TAGGED TEMPLATE WITH AN INVALID ESCAPE has no cooked value, only the raw one — and the
+//      path in it is still a path. (`String.raw` is exactly where such a template is legal.)
+{
+  const [res] = await jsLinter.lintText(
+    "export const p = String.raw`node_modules/paperlint/\\unicode`;\n",
+    { filePath: join(ROOT, "tagged.probe.mjs") },
+  );
+  const m = res.messages.filter((x) => x.ruleId === RULE_JS);
+  assert.equal(
+    m.length,
+    1,
+    `a raw-only template quasi must be read, got ${JSON.stringify(res.messages)}`,
+  );
+  cases.push("js fires on a tagged template whose quasi has no cooked value");
+}
+
+recordCheck(cases.length);

package/eslint-rules/latex-language.harness.mjs

@@ -11,9 +11,9 @@
  *       clean.tex` goes through the repository's real `eslint.config.mjs` and must be silent.
  *   II. THE PROJECTION ACTUALLY DID ITS WORK — headings (including SYNTHESISED ones), caption
  *       and footnote prose kept, float markup blanked, opaque macros blanked, math blanked,
- *       comments recognised. This is the half that a mutation battery can kill; without it the
- *       language could be gutted and part I would stay green, because a projection that blanks
- *       everything is also silent.
+ *       comments recognised. This is the half a gutted projection could still hide behind;
+ *       without it the language could be gutted and part I would stay green, because a
+ *       projection that blanks everything is also silent.
  *  III. FIRES ON A PLANTED DEFECT — `fixtures/latex-language/defect.tex`, through the real
  *       config, must produce findings, and at the right addresses.
  *   IV. THE LANGUAGE'S BOUNDARIES AS ASSERTIONS. A known limitation recorded only in prose

package/eslint-rules/latex-language.mjs

@@ -33,7 +33,7 @@
  * arguments of those two macros.
  * 🔴 Removing `table` / `figure` from `CODEISH` was NOT an option — rules would then receive
  * `&`, `\\`, the column specification and tikz nodes, i.e. findings on markup. That is pinned
- * by the harness and by a "naive fix" mutation which that part kills.
+ * by the harness.
  * Measured after the fix: nine new findings across three papers, all of them captions and
  * footnotes, reviewed one by one; zero false positives on markup.
  *
@@ -143,8 +143,13 @@ const argEnd = (node) => {
   return end;
 };
 
-export function texToMdast(src) {
-  const ast = getParser().parse(src);
+/**
+ * The projection of `src`. `parse` is unified-latex by default; a test passes one returning the
+ * node shapes today's parser never emits (a macro without `args`, an argument without `content`, an
+ * `env` given as nodes), which the fallbacks below keep reading instead of throwing on.
+ */
+export function texToMdast(src, { parse = (s) => getParser().parse(s) } = {}) {
+  const ast = parse(src);
   const chars = src.split("");
   const blank = (from, to) => {
     for (let i = from; i < to && i < chars.length; i++)
@@ -264,15 +269,13 @@ export function texToMdast(src) {
         return;
       }
       if (env === "thebibliography" && pos) {
-        const h = synthHeading(
+        // `\begin{thebibliography}` (23 characters) always holds `## References` (13).
+        synthHeading(
           pos.start.offset,
           pos.start.offset + "\\begin{thebibliography}".length,
           "References",
         );
-        blank(
-          pos.start.offset + (h ? "## References".length : 0),
-          pos.end.offset,
-        );
+        blank(pos.start.offset + "## References".length, pos.end.offset);
         children.push({
           type: "code",
           lang: env,
@@ -282,7 +285,7 @@ export function texToMdast(src) {
         return;
       }
       if (CODEISH.test(env) && pos) {
-        // 🔴 THERE WERE TWO LOCKS, AND LIFTING ONE DID NOT HELP (proved by mutation): a
+        // 🔴 THERE WERE TWO LOCKS, AND LIFTING ONE DID NOT HELP: a
         // caption was blanked by `OPAQUE` as a macro, and inside `table` / `figure` it was
         // blanked AGAIN by the whole environment. So what is blanked here is not the float's
         // borders but the float MINUS the arguments of `\caption{}` / `\footnote{}`.

package/eslint-rules/latex-language.test.mjs

@@ -0,0 +1,200 @@
+/**
+ * texToMdast / texLanguage on the shapes the harness does not carry: a `thebibliography`
+ * environment, a float on the file's last line with no newline after it, a heading whose title
+ * holds a macro, an unknown macro in prose, and a parse that fails (nesting deep enough to exhaust the parser).
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { texLanguage, texToMdast } from "./latex-language.mjs";
+
+/** The projection plus each node's type, lang/title and start–end offsets. */
+const project = (src) => {
+  const { root, text } = texToMdast(src);
+  return {
+    text,
+    nodes: root.children.map((c) => [
+      c.type,
+      c.lang ?? c.title,
+      c.position.start.offset,
+      c.position.end.offset,
+    ]),
+  };
+};
+
+test("thebibliography: a References heading over `\\begin`, the rest one blanked code node", () => {
+  assert.deepEqual(
+    project(
+      "\\begin{thebibliography}{9}\n\\bibitem{a} A.\n\\end{thebibliography}\n",
+    ),
+    {
+      text: "## References             \n              \n                     \n",
+      nodes: [
+        ["heading", "References", 0, 13],
+        ["code", "thebibliography", 14, 63],
+      ],
+    },
+  );
+});
+
+test("a float on the last line with no newline after it ends at the end of the file", () => {
+  assert.deepEqual(project("x\n\\begin{table}y\\end{table}"), {
+    text: "x\n                         ",
+    nodes: [["code", "table", 2, 27]],
+  });
+});
+
+test("a heading's title drops an argument-less macro inside it; an unknown macro in prose loses only its name", () => {
+  assert.deepEqual(
+    project("\\section{A \\LaTeX{} b}\nsome \\foo{bar} text\n"),
+    {
+      text: "##               A  b \nsome     {bar} text\n",
+      nodes: [["heading", "A  b", 0, 22]],
+    },
+  );
+});
+
+test("a heading's title keeps the text of a macro with an argument", () => {
+  assert.deepEqual(project("\\section{A \\emph{b} c}\n"), {
+    text: "##              A b c \n",
+    nodes: [["heading", "A b c", 0, 22]],
+  });
+});
+
+test("a body the parser cannot take (nesting deep enough to exhaust its stack) is a parse failure, not a throw", () => {
+  const r = texLanguage.parse({ body: "{".repeat(20_000) });
+  assert.deepEqual(
+    [r.ok, r.errors.map((e) => e.constructor.name)],
+    [false, ["RangeError"]],
+  );
+});
+
+/** A node position on line 1, from offset `a` to offset `b`. */
+const at = (a, b) => ({
+  start: { offset: a, line: 1, column: a + 1 },
+  end: { offset: b, line: 1, column: b + 1 },
+});
+
+test("node shapes today's parser never emits are read, not thrown on", () => {
+  // Each node lacks what unified-latex always gives: `args`, an argument's `content`, a string `env`.
+  const src = " ".repeat(200);
+  const ast = {
+    type: "root",
+    content: [
+      // a heading macro with no args at all: an empty title
+      { type: "macro", content: "section", position: at(0, 8) },
+      // a heading whose title holds a macro whose argument has no content
+      {
+        type: "macro",
+        content: "subsection",
+        position: at(10, 40),
+        args: [
+          {
+            type: "argument",
+            openMark: "{",
+            closeMark: "}",
+            content: [
+              { type: "string", content: "T", position: at(22, 23) },
+              { type: "macro", content: "emph", args: [{ type: "argument" }] },
+            ],
+          },
+        ],
+      },
+      // an environment named by nodes rather than a string
+      {
+        type: "environment",
+        env: [{ type: "string", content: "abstract" }],
+        content: [],
+        position: at(50, 80),
+      },
+      // a float whose caption has no args, and whose footnote's argument has no content
+      {
+        type: "environment",
+        env: "table",
+        position: at(90, 120),
+        content: [
+          { type: "macro", content: "caption", position: at(95, 100) },
+          {
+            type: "macro",
+            content: "footnote",
+            position: at(101, 110),
+            args: [{ type: "argument" }],
+          },
+        ],
+      },
+      // texttt and a first-column textbf with no args; an ordinary macro whose argument is empty
+      { type: "macro", content: "texttt", position: at(125, 132) },
+      {
+        type: "macro",
+        content: "textbf",
+        position: {
+          start: { offset: 133, line: 2, column: 1 },
+          end: { offset: 140, line: 2, column: 8 },
+        },
+      },
+      {
+        type: "macro",
+        content: "foo",
+        position: at(141, 150),
+        args: [{ type: "argument" }],
+      },
+      // the same macros with an argument that has no content
+      {
+        type: "macro",
+        content: "subsubsection",
+        position: at(170, 180),
+        args: [{ type: "argument", openMark: "{", closeMark: "}" }],
+      },
+      {
+        type: "macro",
+        content: "texttt",
+        position: at(181, 185),
+        args: [{ type: "argument" }],
+      },
+      {
+        type: "macro",
+        content: "emph",
+        position: {
+          start: { offset: 186, line: 3, column: 1 },
+          end: { offset: 190, line: 3, column: 5 },
+        },
+        args: [{ type: "argument" }],
+      },
+      // `\bibliography` squeezed into one character: too short for `## References`, so no heading
+      { type: "macro", content: "bibliography", position: at(160, 160) },
+      // a node the walk meets without a position
+      { type: "environment", env: "abstract", content: [] },
+    ],
+  };
+  const { root } = texToMdast(src, { parse: () => ast });
+  assert.deepEqual(
+    root.children.map((c) => [c.type, c.title ?? c.lang ?? ""]),
+    // Sorted by offset: the float's code node starts at its (single) line's start.
+    [
+      ["heading", ""],
+      ["code", "table"],
+      ["heading", "T"],
+      ["heading", "Abstract"],
+      ["strong", ""],
+      ["heading", ""],
+      ["strong", ""],
+    ],
+  );
+});
+
+test("a source code made from a parse result without the raw text reads the projection; parents are recorded", () => {
+  const body = "\\section{A}\n";
+  const parsed = texLanguage.parse({ body });
+  const code = texLanguage.createSourceCode(
+    { body },
+    { ast: parsed.ast, projected: parsed.projected },
+  );
+  const [heading] = parsed.ast.children;
+  assert.deepEqual(
+    [
+      code.raw === parsed.projected,
+      code.getParent(parsed.ast),
+      code.getParent(heading) === parsed.ast,
+    ],
+    [true, undefined, true],
+  );
+});

package/eslint-rules/paper-research-question.harness.mjs

@@ -13,10 +13,19 @@
  */
 import assert from "node:assert/strict";
 import { join, dirname } from "node:path";
-import { readFileSync } from "node:fs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { Linter } from "eslint";
 import markdown from "@eslint/markdown";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const FIX = join(HERE, "..", "fixtures", "paper-research-question");
@@ -24,11 +33,7 @@ const FIX = join(HERE, "..", "fixtures", "paper-research-question");
 const { texLanguage } = await import(join(HERE, "latex-language.mjs"));
 const rq = (await import(join(HERE, "paper-research-question.mjs"))).default;
 
-let n = 0;
-const check = (label, cond) => {
-  assert.ok(cond, label);
-  n++;
-};
+const check = createChecker();
 
 const linter = new Linter();
 
@@ -141,6 +146,67 @@ check(
     .length === 1,
 );
 
+// ── a scorecard that cannot be read is no scorecard: silence, never a crash ────────────
+// A directory where the file should be (EISDIR), and front matter that is not YAML — which
+// `paper/stages` reports on the scorecard itself, so this rule does not report it twice.
+{
+  const work = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-rq-")));
+  try {
+    const paperIn = (name, status) => {
+      const dir = join(work, name);
+      mkdirSync(dir);
+      status(join(dir, "PIPELINE-STATUS.md"));
+      const path = join(dir, "paper.md");
+      writeFileSync(path, "# A paper\n");
+      // A linter rooted at the scratch directory: files outside `cwd` match no config.
+      return new Linter({ cwd: work }).verify(
+        "# A paper\n",
+        [
+          {
+            files: ["**/*.md"],
+            plugins: { markdown, paper: rq },
+            language: "markdown/gfm",
+            rules: { "paper/research-question": "error" },
+          },
+        ],
+        path,
+      );
+    };
+    check(
+      "a scorecard path that is a directory: no finding, no crash",
+      JSON.stringify(paperIn("dir", (p) => mkdirSync(p))) === "[]",
+      () => paperIn("dir2", (p) => mkdirSync(p)),
+    );
+    check(
+      "a scorecard whose front matter is not YAML: no finding, no crash",
+      JSON.stringify(
+        paperIn("yaml", (p) =>
+          writeFileSync(p, "---\nstages: [submitted\n---\n"),
+        ),
+      ) === "[]",
+    );
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+// ── a language whose source code carries no text at all: nothing to compare, silence ───
+{
+  const reports = [];
+  rq.rules["research-question"]
+    .create({
+      options: [],
+      filename: join(FIX, "shipped-no-rq", "paper.tex"),
+      sourceCode: {},
+      report: (r) => reports.push(r),
+    })
+    ["root:exit"]({});
+  check(
+    "a source code with neither `raw` nor `text` is skipped, even for a shipped paper",
+    reports.length === 0,
+  );
+}
+
 console.log(
-  `✓ ${String(n)} assertions passed — paper/research-question, the debt of a shipped paper`,
+  `✓ ${String(check.count)} assertions passed — paper/research-question, the debt of a shipped paper`,
 );