paperlint 4.2.0 → 6.0.0

package/src/facts-file.ts

@@ -26,6 +26,14 @@
  * fonts are all named `Type3`; `embedded` means a usable program is present, so a corrupted one is
  * false. `pdf` is now relative to the PAPER directory, not to wherever the command ran.
  *
+ * ── SCHEMA 3 (2026-09-29) ───────────────────────────────────────────────────────
+ * Adds what the PDF SAYS, for the rules that judge text rather than geometry: `pages_text` (each
+ * page's text, in content order), `metadata` (the Info dictionary and the XMP packet, flat),
+ * `links` (every link annotation's target and page), `bib_anchor_page` and `appendix_anchor_page`
+ * (the pages hyperref anchored the bibliography's first entry and the appendix on, or null). Every schema-2 field keeps its name and meaning. The number moves anyway: `anonymity/identity` and `format/page-limit` read these fields,
+ * and schema-2 facts without them would be judged as a PDF that says nothing — a clean pass over no
+ * input. A schema-2 file is refused by `pdf/fresh` with "rebuild", which is one `paperlint build`.
+ *
  * 🔴 STALENESS. The PDF is not committed, so neither are these facts: they live in `_build/` and
  * carry `pdf_sha256`. A rule compares it with the PDF on disk and refuses facts about another build.
  */
@@ -52,7 +60,7 @@ import { paperPreset, paperPresetProblem } from "./presets.ts";
 import { presetsDir } from "./package-dirs.ts";
 import { messageOf } from "./domain/text.ts";
 
-export const FACTS_SCHEMA = 2;
+export const FACTS_SCHEMA = 3;
 export const FACTS_DIR = "_build";
 export const FACTS_FILE = "paper.facts.json";
 
@@ -123,7 +131,17 @@ export type FactsDocument = {
   readonly last_page: LastPageEntry;
   /** Schema 1's field, kept: the two heights, or null when the last page is a stub or a review build. */
   readonly last_page_cols_pt: readonly [number, number] | null;
-} & FactsGeometryFields;
+} & FactsTextFields &
+  FactsGeometryFields;
+
+/** Schema 3's fields: what the PDF says (see the module header). */
+export interface FactsTextFields {
+  readonly pages_text: readonly string[];
+  readonly metadata: Readonly<Record<string, string>>;
+  readonly links: readonly { readonly page: number; readonly uri: string }[];
+  readonly bib_anchor_page: number | null;
+  readonly appendix_anchor_page: number | null;
+}
 
 export function fontEntry(f: FontFact): FontEntry {
   return {
@@ -170,6 +188,11 @@ export function factsDocument(i: FactsInput): FactsDocument {
       i.read.fonts.kind === "drawn" ? i.read.fonts.list.map(fontEntry) : [],
     last_page: last,
     last_page_cols_pt: last.kind === "measured" ? last.columns_pt : null,
+    pages_text: i.read.pageTexts,
+    metadata: i.read.metadata,
+    links: i.read.links,
+    bib_anchor_page: i.read.bibAnchorPage,
+    appendix_anchor_page: i.read.appendixAnchorPage,
     ...flatGeometry(i.geometry),
   };
 }
@@ -249,6 +272,19 @@ export interface ReadFacts {
   readonly fonts: readonly FontEntry[];
   /** The geometry columns, or null when no measurer ran (`geometry_source` is null). */
   readonly geometry: FlatGeometry | null;
+  /** What the PDF says: schema 3's fields, parsed. */
+  readonly text: TextFacts;
+}
+
+/** Schema 3's fields as a rule reads them. */
+export interface TextFacts {
+  readonly pages: readonly string[];
+  readonly metadata: Readonly<Record<string, string>>;
+  readonly links: readonly { readonly page: number; readonly uri: string }[];
+  /** The page of the first bibliography entry hyperref anchored, or null. */
+  readonly bibAnchorPage: number | null;
+  /** The page hyperref anchored the appendix on, or null. */
+  readonly appendixAnchorPage: number | null;
 }
 
 /** Why a facts file cannot be judged. */
@@ -331,6 +367,56 @@ function geometryOf(
   });
 }
 
+const isPage = (v: unknown): v is number =>
+  typeof v === "number" && Number.isInteger(v) && v > 0;
+const isPageOrNull = (v: unknown): v is number | null =>
+  v === null || isPage(v);
+const isStrings = (v: unknown): v is readonly string[] =>
+  Array.isArray(v) && v.every((x) => typeof x === "string");
+const isStringRecord = (v: unknown): v is Readonly<Record<string, string>> =>
+  isRecord(v) && Object.values(v).every((x) => typeof x === "string");
+const isLinks = (
+  v: unknown,
+): v is readonly { readonly page: number; readonly uri: string }[] =>
+  Array.isArray(v) &&
+  v.every(
+    (l) => isRecord(l) && isPage(l["page"]) && typeof l["uri"] === "string",
+  );
+
+/** Schema 3's fields, or which one is wrong. */
+function textOf(
+  d: Readonly<Record<string, unknown>>,
+): Result<TextFacts, string> {
+  const { pages_text, metadata, links } = d;
+  const { bib_anchor_page, appendix_anchor_page } = d;
+  if (!isStrings(pages_text))
+    return err("`pages_text` is not a list of strings");
+  if (!isStringRecord(metadata))
+    return err("`metadata` is not an object of strings");
+  if (!isLinks(links)) return err("`links` is not a list of { page, uri }");
+  if (!isPageOrNull(bib_anchor_page))
+    return err("`bib_anchor_page` is neither a page number nor null");
+  if (!isPageOrNull(appendix_anchor_page))
+    return err("`appendix_anchor_page` is neither a page number nor null");
+  return ok({
+    pages: pages_text,
+    metadata,
+    links,
+    bibAnchorPage: bib_anchor_page,
+    appendixAnchorPage: appendix_anchor_page,
+  });
+}
+
+/** What the PDF measures and what it says: the geometry columns and schema 3's fields. */
+function contentOf(
+  d: Readonly<Record<string, unknown>>,
+): Result<Pick<ReadFacts, "geometry" | "text">, string> {
+  const geometry = geometryOf(d);
+  if (!geometry.ok) return geometry;
+  const text = textOf(d);
+  return text.ok ? ok({ geometry: geometry.value, text: text.value }) : text;
+}
+
 /** The PDF the facts describe: its path and its sha256. */
 function artifactOf(
   d: Readonly<Record<string, unknown>>,
@@ -368,11 +454,7 @@ export function parseFactsText(text: string): Result<ReadFacts, FactsProblem> {
       kind: "broken",
       why: "`fonts` is not a list of { name, type, embedded, program }",
     });
-  const geometry = geometryOf(d);
-  if (!geometry.ok) return err({ kind: "broken", why: geometry.error });
-  return ok({
-    ...artifact.value,
-    fonts,
-    geometry: geometry.value,
-  });
+  const content = contentOf(d);
+  if (!content.ok) return err({ kind: "broken", why: content.error });
+  return ok({ ...artifact.value, fonts, ...content.value });
 }

package/src/init.test.ts

@@ -21,8 +21,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { FRESH_CLONE_NOTE } from "./hooks-settings.ts";
+import { load as yamlLoad } from "js-yaml";
+import { z } from "zod";
 import {
-  UNPINNED_REF,
   WORKFLOW_PATH,
   choosePapers,
   declarePapers,
@@ -33,6 +34,7 @@ import {
   reportSkillLinks,
   reportTexLive,
   reportWorkflow,
+  workflowYaml,
 } from "./init.ts";
 import { runNode } from "../test/support.ts";
 
@@ -353,30 +355,48 @@ describe("paperlint init — how several candidate directories were decided, sai
 const here = (p: string) => `<${p}>`;
 
 describe("paperlint init — the workflow section, whole", () => {
-  it("the workflow: written unpinned, kept, declined, not asked", () => {
-    const ctx = { papersDir: "papers", why: "stdin is not a terminal" };
-    expect(reportWorkflow("written", ctx)).toEqual([
-      `  ✓ wrote ${WORKFLOW_PATH} — pin ${UNPINNED_REF} before pushing it`,
+  it("the written workflow installs the package, then runs the action from node_modules", () => {
+    // Guards: one revision. The action comes from the lockfile-pinned install, so there is no
+    // `zernie/paperlint@<ref>` to drift from package.json, and no `paths` to repeat papersDir.
+    const Workflow = z.object({
+      jobs: z.object({
+        papers: z.object({
+          steps: z.array(z.record(z.string(), z.unknown())),
+        }),
+      }),
+    });
+    expect(Workflow.parse(yamlLoad(workflowYaml())).jobs.papers.steps).toEqual([
+      { uses: "actions/checkout@v4" },
+      { uses: "actions/setup-node@v4", with: { "node-version": 22 } },
+      { run: "npm ci" },
+      { uses: "./node_modules/paperlint" },
     ]);
-    expect(reportWorkflow("written", { ...ctx, version: "1.2.3" })).toEqual([
-      `  ✓ wrote ${WORKFLOW_PATH}, pinned to v1.2.3`,
+  });
+
+  it("the workflow report: written, kept, declined, not asked", () => {
+    const ctx = { why: "stdin is not a terminal" };
+    expect(reportWorkflow("written", ctx)).toEqual([
+      `  ✓ wrote ${WORKFLOW_PATH}`,
     ]);
     expect(reportWorkflow("kept", ctx)).toEqual([
       `  ✓ ${WORKFLOW_PATH} is already there — kept, nothing overwritten`,
     ]);
-    const step = [
-      "      to run the same checks in CI, add this step to a workflow:",
-      `        - uses: zernie/paperlint@${UNPINNED_REF}`,
+    const steps = [
+      "      to run the same checks in CI, add these steps to a workflow:",
+      "        - uses: actions/checkout@v4",
+      "        - uses: actions/setup-node@v4",
       "          with:",
-      "            paths: papers",
+      "            node-version: 22",
+      "        - run: npm ci",
+      "        - uses: ./node_modules/paperlint",
     ];
     expect(reportWorkflow("declined", ctx)).toEqual([
       "  · declined — nothing written",
-      ...step,
+      ...steps,
     ]);
     expect(reportWorkflow("not-asked", ctx)).toEqual([
       "  · stdin is not a terminal, so nothing was asked. Default taken: NO file written.",
-      ...step,
+      ...steps,
     ]);
   });
 });

package/src/init.ts

@@ -55,7 +55,6 @@ import {
 } from "./doctor.ts";
 import { PAPER_MARKERS, papersIn } from "./build.ts";
 import { linkSkills, SKILLS_HOME, type LinkReport } from "./link-skills.ts";
-import { actionRef } from "./action-ref.ts";
 import {
   FRESH_CLONE_NOTE,
   SETTINGS_PATH,
@@ -270,29 +269,33 @@ export async function declarePapers(
 
 export const WORKFLOW_PATH = join(".github", "workflows", "papers.yml");
 
-/** Where the action is pinned when no release tag is known — obviously a placeholder. */
-export const UNPINNED_REF = "<commit-sha>";
-
 /**
- * The CI step, as a whole workflow, pinned to `ref` — the release tag of the running package
- * (`actionRef`). With no tag known (`null`: a git checkout, `npm link`) it keeps the placeholder
- * and says so: a wrong tag written confidently is worse than a placeholder that is obviously one.
+ * The CI steps, one list for the file `init` writes and for the steps it prints. The action is
+ * called from the installed package, after `npm ci`: it and the CLI it runs are then one revision,
+ * set by the lockfile, and the action finds papersDir in paperlint.json itself.
  */
-export function workflowYaml(papers: string, ref: string | null): string {
+const CI_STEPS = [
+  "- uses: actions/checkout@v4",
+  "- uses: actions/setup-node@v4",
+  "  with:",
+  "    node-version: 22",
+  "- run: npm ci",
+  "- uses: ./node_modules/paperlint",
+] as const;
+
+const indent = (by: number) => (line: string) => `${" ".repeat(by)}${line}`;
+
+/** The CI workflow `init` offers to write. */
+export function workflowYaml(): string {
   return [
-    ref === null
-      ? `# Written by \`paperlint init\`. Replace ${UNPINNED_REF} with a commit or release tag of the action.`
-      : `# Written by \`paperlint init\`, pinned to ${ref} — the release you installed.`,
+    `# Written by \`paperlint init\`.`,
     `name: papers`,
     `on: [push, pull_request]`,
     `jobs:`,
     `  papers:`,
     `    runs-on: ubuntu-latest`,
     `    steps:`,
-    `      - uses: actions/checkout@v4`,
-    `      - uses: zernie/paperlint@${ref ?? UNPINNED_REF}`,
-    `        with:`,
-    `          paths: ${papers}`,
+    ...CI_STEPS.map(indent(6)),
     ``,
   ].join("\n");
 }
@@ -301,16 +304,12 @@ export type WorkflowResult = "written" | "kept" | "declined" | "not-asked";
 
 export async function offerWorkflow(
   root: string,
-  papers: string,
   {
     ask,
     interactive,
-    version,
   }: {
     ask?: (q: string) => Promise<string>;
     interactive: boolean;
-    /** The running package's version; see `InitOptions.version`. */
-    version?: string | undefined;
   },
 ): Promise<WorkflowResult> {
   const path = join(root, WORKFLOW_PATH);
@@ -327,27 +326,17 @@ export async function offerWorkflow(
   // No answer — an empty line, or a stream that ended — is the safe default, which is "no file".
   if (answer !== "y" && answer !== "yes") return "declined";
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, workflowYaml(papers, actionRef(version)), "utf8");
+  writeFileSync(path, workflowYaml(), "utf8");
   return "written";
 }
 
 /** What `init` says about the CI workflow — and, when none was written, the step to paste. */
 export function reportWorkflow(
   wf: WorkflowResult,
-  {
-    version,
-    papersDir,
-    why,
-  }: { version?: string | undefined; papersDir: string; why: string },
+  { why }: { why: string },
 ): string[] {
-  const ref = actionRef(version);
   const out: string[] = [];
-  if (wf === "written")
-    out.push(
-      ref === null
-        ? `  ✓ wrote ${WORKFLOW_PATH} — pin ${UNPINNED_REF} before pushing it`
-        : `  ✓ wrote ${WORKFLOW_PATH}, pinned to ${ref}`,
-    );
+  if (wf === "written") out.push(`  ✓ wrote ${WORKFLOW_PATH}`);
   else if (wf === "kept")
     out.push(
       `  ✓ ${WORKFLOW_PATH} is already there — kept, nothing overwritten`,
@@ -359,10 +348,8 @@ export function reportWorkflow(
     );
   if (wf !== "written" && wf !== "kept")
     out.push(
-      `      to run the same checks in CI, add this step to a workflow:`,
-      `        - uses: zernie/paperlint@${ref ?? UNPINNED_REF}`,
-      `          with:`,
-      `            paths: ${papersDir}`,
+      `      to run the same checks in CI, add these steps to a workflow:`,
+      ...CI_STEPS.map(indent(8)),
     );
   return out;
 }
@@ -603,11 +590,6 @@ export interface InitOptions {
   resolveCliPapers?: (root: string) => string | null;
   /** Links the skills. Injected only so a test can stand in for the installed package. */
   link?: (root: string) => LinkReport;
-  /**
-   * The version of the running package, read by the CLI from its own `package.json`. The CI
-   * workflow is pinned to its release tag (`actionRef`); absent or unreleased, the placeholder.
-   */
-  version?: string | undefined;
   /**
    * TeX Live for `paperlint build`: whether paperlint's own tree is installed, and how to install
    * it (`paperlint toolchain`). Passed in by the CLI; without them the step only names the command.
@@ -734,7 +716,6 @@ export async function init(
     run = spawnSync,
     resolveCliPapers,
     link = (r: string) => linkSkills(r),
-    version,
   } = opts;
   // An injected `interactive` is a test standing in for a terminal; its reason is the classic one.
   const { interactive, why } =
@@ -816,12 +797,8 @@ export async function init(
   // ── 5. the one expensive, unguessable thing ───────────────────────────────────────────
   log(``);
   log(`CI`);
-  const wf = await offerWorkflow(root, papersDir, {
-    ask,
-    interactive,
-    version,
-  });
-  for (const line of reportWorkflow(wf, { version, papersDir, why })) log(line);
+  const wf = await offerWorkflow(root, { ask, interactive });
+  for (const line of reportWorkflow(wf, { why })) log(line);
 
   // ── 6. a first paper — offered only where there is none, and only to a human ──────────
   log(``);

package/src/linted-set.test.ts

@@ -26,7 +26,11 @@ afterEach(() => {
   for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
 });
 
-const TEX = "\\documentclass{article}\n\\begin{document}x\\end{document}\n";
+// The body is partly in `sections/intro.tex`, brought in by `\input` in the document; the preamble
+// `\input`s a macro file and paperlint's own `paper-guards`. Only the body file is the paper.
+const TEX =
+  "\\documentclass{article}\n\\input{macros}\n\\input{paper-guards}\n" +
+  "\\begin{document}x\n\\input{sections/intro}\n\\end{document}\n";
 const JS = "export const x = 1;\n";
 
 /** The files paperlint owns in the fixture paper. */
@@ -35,6 +39,7 @@ const OWNED = [
   "papers/a/PIPELINE-STATUS.md",
   "papers/a/reviews/r1.md",
   "papers/a/siblings/smith2025.md",
+  "papers/a/sections/intro.tex",
 ];
 
 /** Everything else a real paper folder and project carry. None of it may be linted. */
@@ -46,6 +51,10 @@ const NEIGHBOURS = {
   "papers/a/repro/lib/y.mjs": JS,
   "papers/a/repro/z.cjs": "module.exports = 1;\n",
   "papers/a/repro/t.ts": "const t: number = 1;\n",
+  // A preamble include, a frozen version and a .tex nothing includes: none is the paper's body.
+  "papers/a/macros.tex": "\\newcommand{\\x}{y}\n",
+  "papers/a/versions/2026-01-01-submitted.tex": TEX,
+  "papers/a/notes/scratch.tex": "Scratch.\n",
   "script.js": JS,
   "node_modules/pkg/index.js": JS,
 };
@@ -75,6 +84,7 @@ function project(): string {
     "papers/a/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
     "papers/a/reviews/r1.md": "# review\n",
     "papers/a/siblings/smith2025.md": "---\nread: full\n---\n# Smith 2025\n",
+    "papers/a/sections/intro.tex": "Intro.\n",
     ...NEIGHBOURS,
   };
   for (const [p, text] of Object.entries(all)) {

package/src/new-paper.harness.mjs

@@ -5,7 +5,7 @@
  *   - the scaffold is what `paperlint lint` ACCEPTS: the old first run opened with "missing
  *     PIPELINE-STATUS.md", and a scaffold that still produced a finding would move that error
  *     from a missing file into a created one;
- *   - the scorecard carries `researchQuestion` and NO `stages` — a new paper has shipped nothing,
+ *   - the scorecard carries NO `stages` — a new paper has shipped nothing,
  *     and a placeholder stage would be a red `paper/stages` on the very first run;
  *   - the scorecard carries the `**Readiness verdict:**` line the status hook surfaces on every
  *     paper edit — without it the hook reports that the paper cannot say whether it is ready;
@@ -104,10 +104,6 @@ try {
     "🔴 the scorecard has NO `stages` — a new paper has shipped nothing and owes nothing",
     !("stages" in fm),
   );
-  check(
-    "and carries `researchQuestion`, present and empty",
-    "researchQuestion" in fm && fm.researchQuestion === "",
-  );
   check(
     "the name is filled in, and no placeholder survives in any file",
     /PIPELINE-STATUS — demo/.test(status) &&

package/src/new-paper.test.ts

@@ -51,7 +51,13 @@ describe("paperlint new — paperlint.json", () => {
     expect(String(s["$comment"])).toMatch(/paperlint:agenticdev/);
     expect(parsePaperSettings(s)).toEqual({
       ok: true,
-      value: { extends: null, kind: null, pdf: null, rules: null },
+      value: {
+        extends: null,
+        kind: null,
+        pdf: null,
+        rules: null,
+        identity: null,
+      },
     });
   });
 

package/src/package-dirs.ts

@@ -5,6 +5,9 @@
  *
  *   presets/       the venue presets (`paperlint:<name>`) and their JSON Schema
  *   presets/tex/   the LaTeX inputs `paperlint build` puts on TEXINPUTS
+ *
+ * `texSearchPath` is where an `\input` is looked for, in order. The build hands it to TeX and the
+ * lint rules read includes through it, so the two cannot disagree about which file a paper means.
  */
 import { fileURLToPath } from "node:url";
 
@@ -15,3 +18,9 @@ export const presetsDir = (): string =>
 /** The LaTeX inputs a paper `\input`s by name (`paper-guards`, a venue's numbers). */
 export const texInputsDir = (): string =>
   fileURLToPath(new URL("../presets/tex", import.meta.url));
+
+/** Where an `\input` in the paper in `paperDir` is looked for, first to last. */
+export const texSearchPath = (paperDir: string): readonly string[] => [
+  paperDir,
+  texInputsDir(),
+];

package/src/paper-files.ts

@@ -16,8 +16,8 @@
  *
  * 2. **Each rule scoped to the files it was written for** (`ruleOwners` + `narrowToOwners`).
  *    One plugin NAME is bound to different plugin objects in different blocks: `paper` holds
- *    `stages`/`source`/`author-list` beside `PIPELINE-STATUS.md` and `research-question`/
- *    `typography` beside `paper.md`/`paper.tex`. So a consumer block that named `paper/source`
+ *    `stages`/`source`/`author-list` beside `PIPELINE-STATUS.md` and `typography` beside
+ *    `paper.md`/`paper.tex`. So a consumer block that named `paper/source`
  *    for every file under the papers directory reached `paper.tex`, where `paper` has no `source`
  *    — and ESLint threw `Could not find "source" in plugin "paper"` from inside `lintFiles`,
  *    after paperlint's own validation had (correctly) accepted the id. A block is therefore split

package/src/paper-includes.test.ts

@@ -0,0 +1,161 @@
+/**
+ * `paperlint lint` over a paper whose body is in other files: the rules over ESLint's LaTeX text read
+ * every file `paper.tex` includes from its document body, report at that file's own path and line,
+ * and fix that file. What a rule decides for the whole paper — the majority reference form and
+ * whether the build is in review mode — it decides over all of the paper's files, not over the one
+ * it is reporting in.
+ */
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { run } from "./cli.ts";
+import { lintReport } from "../test/lint-report.ts";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+const doc = (cls: string, preamble: string, body: string): string =>
+  `\\documentclass${cls}\n${preamble}\n\\begin{document}\n${body}\n\\end{document}\n`;
+
+const INTRO = "See §3 and p < .05.\nAs Fig.~\\ref{f3} shows.\n";
+
+function project(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-inc-")));
+  dirs.push(root);
+  const all: Record<string, string> = {
+    "package.json": JSON.stringify({ name: "c", private: true }),
+    "papers/a/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
+    "papers/a/paper.tex": doc(
+      "{article}",
+      "\\input{macros}",
+      "Figure~\\ref{f1} and Figure~\\ref{f2}.\n\\input{sections/intro}",
+    ),
+    // Prose in a preamble include is not the body: were it linted, `§2` would be reported.
+    "papers/a/macros.tex": "% See §2.\n\\newcommand{\\half}{0.5}\nSee §2.\n",
+    "papers/a/sections/intro.tex": INTRO,
+    // A frozen version beside the paper is not the paper.
+    "papers/a/versions/2026-01-01-submitted.tex": doc(
+      "{article}",
+      "",
+      "See §9.",
+    ),
+    ...files,
+  };
+  for (const [p, text] of Object.entries(all)) {
+    mkdirSync(join(root, p, ".."), { recursive: true });
+    writeFileSync(join(root, p), text);
+  }
+  return root;
+}
+
+/** `paperlint lint --json` → rule ids per linted file (relative to the project), and stderr. */
+async function lint(
+  root: string,
+  args: string[] = [],
+): Promise<{ byFile: Record<string, string[]>; err: string }> {
+  const out: string[] = [];
+  const err: string[] = [];
+  await run(["lint", "--json", ...args], {
+    cwd: root,
+    log: (s: string) => out.push(s),
+    err: (s: string) => err.push(s),
+  });
+  const byFile = Object.fromEntries(
+    lintReport(out.join("\n")).map((r) => [
+      relative(root, r.filePath),
+      r.messages.map((m) => m.ruleId ?? "(fatal)").sort(),
+    ]),
+  );
+  return { byFile, err: err.join("\n") };
+}
+
+describe("lint reads the files paper.tex includes from its body", () => {
+  it("🔴 findings in an included file land at that file; the majority form is the paper's", async () => {
+    const { byFile } = await lint(project({}));
+    expect(byFile["papers/a/sections/intro.tex"]).toEqual([
+      "paper/figure-ref-style",
+      "paper/leading-zero",
+      "paper/section-word",
+    ]);
+    // Two `Figure` in paper.tex against one `Fig.` in the section: the section holds the minority.
+    expect(byFile["papers/a/paper.tex"]).not.toContain(
+      "paper/figure-ref-style",
+    );
+  });
+
+  it("a preamble include and a frozen version beside the paper are not linted", async () => {
+    const { byFile } = await lint(project({}));
+    expect(Object.keys(byFile).sort()).toEqual([
+      "papers/a/PIPELINE-STATUS.md",
+      "papers/a/paper.tex",
+      "papers/a/sections/intro.tex",
+    ]);
+  });
+
+  it("--fix rewrites the included file, to the paper's majority form", async () => {
+    const root = project({});
+    const before = readFileSync(join(root, "papers/a/paper.tex"), "utf8");
+    const { byFile } = await lint(root, ["--fix"]);
+    expect(byFile["papers/a/sections/intro.tex"]).toEqual([]);
+    expect(
+      readFileSync(join(root, "papers/a/sections/intro.tex"), "utf8"),
+    ).toBe("See Section 3 and p < 0.05.\nAs Figure~\\ref{f3} shows.\n");
+    expect(readFileSync(join(root, "papers/a/paper.tex"), "utf8")).toBe(before);
+  });
+});
+
+describe("what lint decides for the whole paper, it decides over every file of it", () => {
+  it("tex/future-promise in an included file follows the build mode paper.tex declares", async () => {
+    const promise = {
+      "papers/a/sections/intro.tex":
+        "The harness will be released at camera-ready.\n",
+    };
+    const final = await lint(project(promise));
+    expect(final.byFile["papers/a/sections/intro.tex"]).toEqual([
+      "tex/future-promise",
+    ]);
+    const review = await lint(
+      project({
+        ...promise,
+        "papers/a/paper.tex": doc(
+          "[review]{article}",
+          "",
+          "Text.\n\\input{sections/intro}",
+        ),
+      }),
+    );
+    expect(review.byFile["papers/a/sections/intro.tex"]).toEqual([]);
+  });
+
+  it("an include that resolves nowhere is named as a file lint did not read", async () => {
+    const { err } = await lint(
+      project({
+        "papers/a/paper.tex": doc("{article}", "", "\\input{sections/gone}"),
+      }),
+    );
+    expect(err).toMatch(
+      /papers\/a\/paper\.tex: lint did not read `sections\/gone`/,
+    );
+  });
+
+  it("the note is about the papers this run lints, not another paper of the project", async () => {
+    const root = project({
+      "papers/b/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
+      "papers/b/paper.tex": doc("{article}", "", "\\input{gone}"),
+    });
+    expect((await lint(root, ["papers/a"])).err).not.toMatch(/did not read/);
+    expect((await lint(root)).err).toMatch(
+      /papers\/b\/paper\.tex: lint did not read `gone`/,
+    );
+  });
+});