paperlint 8.0.0 → 9.0.0

package/src/build.test.ts

@@ -22,7 +22,14 @@ import {
   type PaperFacts,
 } from "./build.ts";
 import type { Geometry } from "./domain/geometry.ts";
+import { bibReader } from "./adapters/bibtex/index.ts";
+import { nodeFiles } from "./adapters/node/index.ts";
+import { sourcesCodec } from "./adapters/sources-record/index.ts";
+import { sha256Hex } from "./domain/sha256.ts";
+import { serializeSourcesRecord } from "./domain/sources-record.ts";
+import { bibliographyReader } from "./references.ts";
 import type { PdfReader } from "./pdf-facts.ts";
+import type { Recorded, TexRun } from "./sources-record.ts";
 
 const root = useTempDir("paperlint-build-test-");
 const TEX = "\\documentclass{article}\\begin{document}x\\end{document}";
@@ -44,6 +51,8 @@ interface Fake {
   noLog?: boolean;
   /** Each pass writes a different .aux, so the loop never settles. */
   churn?: boolean;
+  /** What pdflatex's `-recorder` file holds after pass `n`; without it, pdflatex records nothing. */
+  fls?: (pass: number) => string;
 }
 /** A pdflatex pass: writes the .aux, the log unless it dies first, and a PDF when it exits 0. */
 function latexPass(f: Fake, cwd: string, pass: number) {
@@ -51,6 +60,7 @@ function latexPass(f: Fake, cwd: string, pass: number) {
   const aux = f.churn ? `\\relax % ${String(pass)}\n` : (f.aux ?? "\\relax\n");
   writeFileSync(join(cwd, "paper.aux"), aux);
   if (!f.noLog) writeFileSync(join(cwd, "paper.log"), f.log ?? "");
+  if (f.fls) writeFileSync(join(cwd, "paper.fls"), f.fls(pass));
   if (status === 0) writeFileSync(join(cwd, "paper.pdf"), "%PDF-fake");
   return f.noLog ? { status } : { status, stdout: "", stderr: "" };
 }
@@ -263,6 +273,55 @@ test("compile: warnings the final log still reports are named in the note", asyn
   assert.match(r.notes?.[0] ?? "", /— ⚠️ the final log still reports /);
 });
 
+test("references: without a reader the step says it was not wired; with one and no checker, the record says not checked", async () => {
+  const text = {
+    "paper.tex":
+      "\\documentclass{article}\\begin{document}x\\bibliography{refs}\\end{document}",
+    "refs.bib": "@misc{a, url = {https://example.org}}\n",
+  };
+  // What a build of this paper records: TeX read paper.tex, bibtex opened refs.bib and typeset `a`.
+  const digest = (s: string) => sha256Hex(new TextEncoder().encode(s));
+  const bib = {
+    ...text,
+    "_build/sources.json": serializeSourcesRecord({
+      schema: 1,
+      inputs: [{ path: "paper.tex", role: "body" }],
+      written: [],
+      bibdata: ["refs"],
+      bibtex: {
+        ran: true,
+        databases: ["refs.bib"],
+        keys: ["a"],
+        exit: 0,
+        errors: [],
+      },
+      sha256: {
+        "paper.tex": digest(text["paper.tex"]),
+        "refs.bib": digest(text["refs.bib"]),
+      },
+    }),
+  };
+  const unwired = await build(paper(bib));
+  assert.ok(
+    unwired.r.notes?.includes(
+      "references NOT checked — no bibliography reader was wired into this build; lint will say so",
+    ),
+    JSON.stringify(unwired.r.notes),
+  );
+  const readBibliography = bibliographyReader({
+    files: nodeFiles,
+    codec: sourcesCodec,
+    bib: bibReader,
+  });
+  const wired = await build(paper(bib), {}, { readBibliography });
+  assert.ok(
+    wired.r.notes?.includes(
+      "references NOT checked — no reference checker was wired into this build; lint will say so",
+    ),
+    JSON.stringify(wired.r.notes),
+  );
+});
+
 test("measure: a review build and a stub last page are named; a measured geometry adds nothing", async () => {
   const review = await build(paper(), {}, { readPdf: reader(page(20, 60)) });
   assert.match(
@@ -382,3 +441,154 @@ test("a failed result without its lines still says what failed", () => {
     ].join("\n"),
   );
 });
+
+// ── the record of the build's sources ────────────────────────────────────────────────────────
+
+/** What a recorder was handed, for each paper it was asked about. */
+function spyRecorder(answer: Recorded) {
+  const asked: { dir: string; run: TexRun }[] = [];
+  return {
+    asked,
+    recordSources: (dir: string, run: TexRun): Recorded => {
+      asked.push({ dir, run });
+      return answer;
+    },
+  };
+}
+const RECORDED: Recorded = {
+  kind: "recorded",
+  path: "/p/_build/sources.json",
+  record: {
+    schema: 1,
+    inputs: [{ path: "paper.tex", role: "body" }],
+    written: [],
+    bibdata: [],
+    bibtex: { ran: false },
+    sha256: {},
+  },
+};
+
+test("sources: every pdflatex pass runs with -recorder, so TeX itself says which files it read", async () => {
+  const args: (readonly string[])[] = [];
+  const run = fakeRun({});
+  await build(
+    paper(),
+    {},
+    {
+      run: (bin, a, opts) => {
+        if (bin === "pdflatex") args.push(a);
+        return run(bin, a, opts);
+      },
+    },
+  );
+  assert.ok(args.length >= 2);
+  assert.ok(
+    args.every((a) => a.includes("-recorder")),
+    JSON.stringify(args),
+  );
+});
+
+test("sources: the recorder is handed the .fls of every pass, in order, and bibtex's exit when it ran", async () => {
+  const spy = spyRecorder(RECORDED);
+  const { r } = await build(
+    paper({ "paper.tex": TEX, "refs.bib": "@misc{k}\n" }),
+    {
+      aux: "\\citation{k}\n\\bibstyle{plain}\n\\bibdata{refs}\n",
+      fls: (pass) => `pass ${String(pass)}`,
+    },
+    { recordSources: spy.recordSources },
+  );
+  assert.equal(r.status, "built");
+  const [only] = spy.asked;
+  assert.equal(spy.asked.length, 1);
+  assert.match(only?.dir ?? "", /\/p\d+$/);
+  const passes = only?.run.fls ?? [];
+  assert.ok(passes.length >= 2);
+  assert.deepEqual(
+    passes,
+    passes.map((_, i) => `pass ${String(i + 1)}`),
+  );
+  assert.equal(only?.run.bibtexExit, 0);
+  assert.match(
+    r.notes?.[0] ?? "",
+    /bibtex runs?; sources: 1 file read → _build\/sources\.json$/,
+  );
+});
+
+test("sources: a build that ran no bibtex says so to the recorder", async () => {
+  const spy = spyRecorder(RECORDED);
+  await build(
+    paper(),
+    { fls: () => "x" },
+    { recordSources: spy.recordSources },
+  );
+  assert.equal(spy.asked[0]?.run.bibtexExit, null);
+});
+
+test("sources: a paper.fls an earlier build left is not this build's: pdflatex that wrote none hands the recorder none", async () => {
+  const spy = spyRecorder(RECORDED);
+  const dir = paper({ "paper.tex": TEX, "paper.fls": "INPUT stale.tex\n" });
+  await build(dir, {}, { recordSources: spy.recordSources });
+  assert.deepEqual(spy.asked[0]?.run.fls, []);
+});
+
+test("sources: without a recorder, or when it records nothing, the build still builds and the note says it did not record", async () => {
+  const unwired = await build(paper());
+  assert.equal(unwired.r.status, "built");
+  assert.ok(
+    unwired.r.notes?.[0]?.endsWith(
+      "; sources NOT recorded — no recorder was wired into this build; lint will say so",
+    ),
+    JSON.stringify(unwired.r.notes),
+  );
+  const empty = await build(
+    paper(),
+    {},
+    {
+      recordSources: spyRecorder({
+        kind: "not-recorded",
+        why: "pdflatex wrote no paper.fls — nothing to record",
+      }).recordSources,
+    },
+  );
+  assert.equal(empty.r.status, "built");
+  assert.ok(
+    empty.r.notes?.[0]?.endsWith(
+      "; sources NOT recorded — pdflatex wrote no paper.fls — nothing to record; lint will say so",
+    ),
+    JSON.stringify(empty.r.notes),
+  );
+});
+
+test("sources: the note counts the files the record lists", async () => {
+  const two: Recorded = {
+    ...RECORDED,
+    record: {
+      ...RECORDED.record,
+      inputs: [
+        { path: "paper.tex", role: "body" },
+        { path: "sections/intro.tex", role: "body" },
+      ],
+    },
+  };
+  const { r } = await build(
+    paper(),
+    {},
+    { recordSources: spyRecorder(two).recordSources },
+  );
+  assert.ok(
+    r.notes?.[0]?.endsWith("; sources: 2 files read → _build/sources.json"),
+    JSON.stringify(r.notes),
+  );
+});
+
+test("sources: a build that fails records nothing", async () => {
+  const spy = spyRecorder(RECORDED);
+  const { r } = await build(
+    paper(),
+    { latex: 1 },
+    { recordSources: spy.recordSources },
+  );
+  assert.equal(r.status, "failed");
+  assert.deepEqual(spy.asked, []);
+});

package/src/build.ts

@@ -66,7 +66,19 @@ import type { Runner } from "./engine.ts";
 import type { Files } from "./ports/files.ts";
 import type { MeasureGeometry } from "./ports/measure-geometry.ts";
 import type { CheckReferences } from "./ports/check-references.ts";
-import { recordReferences, REFERENCES_FILE } from "./references.ts";
+import {
+  notWiredRecord,
+  recordingNote,
+  type RecordSources,
+  type TexRun,
+} from "./sources-record.ts";
+import { JOBNAME } from "./domain/sources-record.ts";
+import {
+  notWiredBibliography,
+  recordReferences,
+  REFERENCES_FILE,
+  type ReadBibliography,
+} from "./references.ts";
 import {
   auxBib,
   bibtexExcerpt,
@@ -93,7 +105,7 @@ export const PAPER_MARKERS = ["PIPELINE-STATUS.md", "paper.tex", CONFIG_FILE];
 
 /** The source paperlint compiles, and the job name every output file carries. */
 export const MAIN = "paper.tex";
-export const JOB = "paper";
+export const JOB = JOBNAME;
 
 /**
  * Scripts that `paperlint build` USED to run. Their presence is reported and nothing more: running a
@@ -101,11 +113,16 @@ export const JOB = "paper";
  */
 export const IGNORED_SCRIPTS = ["build.sh", "repro/build-submission.sh"];
 
-/** The pdflatex flags: never stop for input, stop at the first error, and say file:line. */
+/**
+ * The pdflatex flags: never stop for input, stop at the first error, say file:line, and write
+ * `paper.fls` — every file the pass opened, which is how the build learns what the paper is made of
+ * (`sources-record.ts`) without reading its TeX.
+ */
 export const PDFLATEX_FLAGS = [
   "-interaction=nonstopmode",
   "-halt-on-error",
   "-file-line-error",
+  "-recorder",
 ];
 
 /** Everything the steps may know about a paper — parsed from it, not configured. */
@@ -138,6 +155,16 @@ export interface BuildContext {
   readonly files: Files;
   /** The online reference checks; the CLI wires the real ones, a test passes a function. */
   readonly checkReferences: CheckReferences;
+  /**
+   * The databases the build's bibtex opened (`readBibliography`, from `_build/sources.json`); the CLI
+   * wires the real reader.
+   */
+  readonly readBibliography: ReadBibliography;
+  /**
+   * Writes `_build/sources.json` from TeX's own files after a compile; the CLI wires the real one.
+   * `buildPapers` hands the step `notWiredRecord` when it is given none: it records nothing and says so.
+   */
+  readonly recordSources: RecordSources;
 }
 
 export type StepOutcome =
@@ -265,7 +292,6 @@ export const inputsStep: BuildStep = {
     yes: true,
     why: `TEXINPUTS += the paper's directory, then ${texInputsDir()}`,
   }),
-  // The same search path the lint rules read includes through: one answer to which file is meant.
   // A pass runs IN the paper's directory, so that directory is `.` here. TeX names a file it finds
   // through an absolute entry by that absolute path: with the directory itself on TEXINPUTS, the
   // `broken` build fixture's log said `/tmp/…/paper.tex:6:` instead of `./paper.tex:6:` (measured).
@@ -374,6 +400,7 @@ function latexPass(
     after: hashes(ctx.paperDir),
     markers: logMarkers(log),
     bib: bibInput(ctx.paperDir),
+    fls: readOr(join(ctx.paperDir, `${JOB}.fls`), "utf8"),
     errorLines:
       exitCode === 0
         ? []
@@ -420,28 +447,47 @@ function bibtexPass(ctx: BuildContext, opts: SpawnOptions): Observation | null {
   };
 }
 
+/** What the loop's passes left for the record of the build's sources (`sources-record.ts`). */
+function runOf(history: readonly Observation[]): TexRun {
+  const bibtexRuns = history.flatMap((o) =>
+    o.step === "bibtex" ? [o.exitCode] : [],
+  );
+  return {
+    fls: history.flatMap((o) =>
+      o.step === "latex" && o.fls !== null ? [o.fls] : [],
+    ),
+    bibtexExit: bibtexRuns.at(-1) ?? null,
+  };
+}
+
 /** Run the loop until `nextStep` says done or fail. */
 export function compile(ctx: BuildContext): {
   end: Terminal;
   latex: number;
   bibtex: number;
+  run: TexRun;
 } {
   const history: Observation[] = [];
   const opts = spawnOptions(ctx);
-  // Every log this loop reads is one its own pdflatex wrote. A pdflatex that dies before opening
-  // paper.log would otherwise have an earlier build's error quoted as this one's.
-  rmSync(join(ctx.paperDir, `${JOB}.log`), { force: true });
+  // Every file this loop reads is one its own pdflatex wrote. A pdflatex that dies before opening
+  // paper.log would otherwise have an earlier build's error quoted as this one's, and one that wrote
+  // no paper.fls would hand the record the files an earlier build read.
+  const remove = (ext: string): void => {
+    rmSync(join(ctx.paperDir, `${JOB}.${ext}`), { force: true });
+  };
+  remove("log");
+  remove("fls");
   const runs = { latex: 0, bibtex: 0 };
+  const finish = (end: Terminal) => ({ end, ...runs, run: runOf(history) });
   for (;;) {
     const step = nextStep(summarize(history));
-    if (step.kind === "done" || step.kind === "fail")
-      return { end: step, ...runs };
+    if (step.kind === "done" || step.kind === "fail") return finish(step);
     runs[step.kind]++;
     const seen =
       step.kind === "latex"
         ? latexPass(ctx, step.final, opts)
         : bibtexPass(ctx, opts);
-    if (seen === null) return { end: cannotStart(step.kind), ...runs };
+    if (seen === null) return finish(cannotStart(step.kind));
     history.push(seen);
   }
 }
@@ -468,7 +514,7 @@ export const compileStep: BuildStep = {
     return { yes: true, why: `${facts.main} (${cls}${venue})` };
   },
   run: (ctx) => {
-    const { end, latex, bibtex } = compile(ctx);
+    const { end, latex, bibtex, run } = compile(ctx);
     if (end.kind === "fail") {
       const bin = end.step === "latex" ? "pdflatex" : "bibtex";
       const where =
@@ -504,7 +550,7 @@ export const compileStep: BuildStep = {
       : "";
     return {
       ok: true,
-      note: `${plural(latex, "pdflatex pass", "pdflatex passes")}, ${plural(bibtex, "bibtex run", "bibtex runs")}${warn}`,
+      note: `${plural(latex, "pdflatex pass", "pdflatex passes")}, ${plural(bibtex, "bibtex run", "bibtex runs")}${warn}; ${recordingNote(ctx.recordSources(ctx.paperDir, run))}`,
     };
   },
 };
@@ -585,7 +631,12 @@ export const referencesStep: BuildStep = {
       : { yes: false, why: "nothing is compiled" },
   run: async (ctx) => ({
     ok: true,
-    note: await recordReferences(ctx.files, ctx.paperDir, ctx.checkReferences),
+    note: await recordReferences(
+      ctx.files,
+      ctx.paperDir,
+      ctx.readBibliography(ctx.paperDir),
+      ctx.checkReferences,
+    ),
   }),
 };
 
@@ -648,6 +699,17 @@ export interface BuildOptions {
    * warns. The CLI passes the real ones (`adapters/references`).
    */
   checkReferences?: CheckReferences;
+  /**
+   * The databases the build's bibtex opened, for the references step. Default: none — the step says
+   * it was not wired and records nothing, and lint warns. The CLI passes `bibliographyReader` over the
+   * real ports.
+   */
+  readBibliography?: ReadBibliography;
+  /**
+   * Writes `_build/sources.json` after a compile. Default: none — the build says it recorded nothing,
+   * and lint reports the paper as not built. The CLI passes `recordSources` over the real ports.
+   */
+  recordSources?: RecordSources;
 }
 
 /**
@@ -669,7 +731,14 @@ function baseDefaults({
   readPdf = pdfjsReader,
   projectRoot = env["CLAUDE_PROJECT_DIR"] || cwd,
 }: BuildOptions): Required<
-  Omit<BuildOptions, "measure" | "files" | "checkReferences">
+  Omit<
+    BuildOptions,
+    | "measure"
+    | "files"
+    | "checkReferences"
+    | "readBibliography"
+    | "recordSources"
+  >
 > {
   return { run, cwd, env, steps, log, dryRun, readPdf, projectRoot };
 }
@@ -686,7 +755,16 @@ const notWired: CheckReferences = (_bib, cache) =>
 
 /** banal as the measurer, wired from the build's environment: the one piece of root work left here (#76). */
 function defaultMeasurer(
-  b: Required<Omit<BuildOptions, "measure" | "files" | "checkReferences">>,
+  b: Required<
+    Omit<
+      BuildOptions,
+      | "measure"
+      | "files"
+      | "checkReferences"
+      | "readBibliography"
+      | "recordSources"
+    >
+  >,
 ): MeasureGeometry {
   const dirs = hostDirs({ cwd: b.cwd });
   return banalMeasurer(
@@ -705,6 +783,8 @@ function withDefaults(o: BuildOptions): Required<BuildOptions> {
     measure,
     files: o.files ?? nodeFiles,
     checkReferences: o.checkReferences ?? notWired,
+    readBibliography: o.readBibliography ?? notWiredBibliography,
+    recordSources: o.recordSources ?? notWiredRecord,
   };
 }
 
@@ -713,29 +793,14 @@ async function runSteps(
   paperDir: string,
   dir: string,
   plan: PlanLine[],
-  {
-    run,
-    env,
-    steps,
-    readPdf,
-    measure,
-    files,
-    checkReferences,
-  }: Required<BuildOptions>,
+  o: Required<BuildOptions>,
 ): Promise<BuildResult> {
-  let stepEnv = env;
+  let stepEnv = o.env;
   const notes: string[] = [];
-  for (const [i, step] of steps.entries()) {
+  for (const [i, step] of o.steps.entries()) {
     if (!plan[i]?.applies) continue;
-    const out = await step.run({
-      paperDir,
-      env: stepEnv,
-      run,
-      readPdf,
-      measure,
-      files,
-      checkReferences,
-    });
+    // Every port the options hold, the paper, and the environment so far.
+    const out = await step.run({ ...o, paperDir, env: stepEnv });
     if (!out.ok) {
       // The PDF THIS run wrote and the step then rejected (a partial pass).
       // A PDF from an earlier run is already gone — `buildPapers` removed it before anything ran.

package/src/claim-provenance.test.ts

@@ -7,10 +7,12 @@
 import { describe, expect, it } from "vitest";
 import { latexReader } from "./adapters/latex/index.ts";
 import { memoryFiles } from "./adapters/memory/index.ts";
+import { sourcesCodec } from "./adapters/sources-record/index.ts";
 import {
   claimProvenanceRule,
   judgeClaimProvenance,
 } from "./claim-provenance.ts";
+import { builtPaper } from "../test/recorded-fixture.ts";
 
 const doc = (body: string): string =>
   `\\documentclass{article}\n\\begin{document}\n${body}\n\\end{document}\n`;
@@ -317,7 +319,11 @@ function run(
 }
 
 const onDisk = (files: Record<string, string> = {}) =>
-  claimProvenanceRule({ files: memoryFiles(files), latex: latexReader });
+  claimProvenanceRule({
+    files: memoryFiles(files),
+    latex: latexReader,
+    codec: sourcesCodec,
+  });
 
 describe("the rule, as ESLint runs it", () => {
   it("reports each finding at its lines, with the message naming the owners that would do", () => {
@@ -337,16 +343,36 @@ describe("the rule, as ESLint runs it", () => {
     ]);
   });
 
-  it("🔴 reads the files the paper \\inputs: a finding there is reported at the \\input, naming its file and line", () => {
-    const rule = onDisk({
-      "/p/sections/results.tex":
-        "\\section{Results}\nIt holds.\nAgents ignore 42\\% of rules.\n",
-    });
-    expect(run(rule, doc("Intro.\n\\input{sections/results}"))).toEqual([
+  it("🔴 reads the files the build recorded TeX reading: a finding there is reported at the \\input, naming its file and line", () => {
+    const main = doc("Intro.\n\\input{sections/results}");
+    const rule = onDisk(
+      builtPaper(
+        "/p",
+        {
+          "paper.tex": main,
+          "sections/results.tex":
+            "\\section{Results}\nIt holds.\nAgents ignore 42\\% of rules.\n",
+        },
+        [
+          { path: "paper.tex", role: "body" },
+          { path: "sections/results.tex", role: "body" },
+        ],
+      ),
+    );
+    expect(run(rule, main)).toEqual([
       {
         line: 4,
         message: `sections/results.tex:3:1: ${String(rule.meta.messages["noOwner"]).replace("{{number}}", "42%")}`,
       },
     ]);
   });
+
+  it("🔴 without a record the paper is paper.tex: the file it \\inputs is not read", () => {
+    const main = doc("Intro.\n\\input{sections/results}");
+    const rule = onDisk({
+      "/p/paper.tex": main,
+      "/p/sections/results.tex": "Agents ignore 42\\% of rules.\n",
+    });
+    expect(run(rule, main)).toEqual([]);
+  });
 });

package/src/claim-provenance.ts

@@ -37,7 +37,7 @@ import {
   segmentOf,
   sentences,
 } from "./domain/sentences.ts";
-import { readPaper, reportInPaper, type PaperDeps } from "./tex-paper.ts";
+import { readPaper, reportInPaper, type ProseDeps } from "./tex-paper.ts";
 import {
   ruleDocsUrl,
   type Located,
@@ -198,7 +198,7 @@ const META: TexRuleModule["meta"] = {
 };
 
 /** The rule, over the body's prose of the whole paper, its includes spliced (`readPaper`). */
-export const claimProvenanceRule = (deps: PaperDeps): TexRuleModule => ({
+export const claimProvenanceRule = (deps: ProseDeps): TexRuleModule => ({
   meta: META,
   create(context) {
     return {

package/src/cli.harness.mjs

@@ -46,6 +46,15 @@ const check = createChecker();
 const tex = (body) =>
   `\\documentclass{article}\n\\begin{document}\n${body}\n\\end{document}\n`;
 
+/**
+ * A run that linted a paper nobody built clean: exit 0, and the one finding is the warning that no
+ * build recorded what TeX read (`paper/sources-fresh`) — what "no findings" meant before that rule.
+ */
+const cleanButUnbuilt = (r) =>
+  r.code === 0 &&
+  /paper\/sources-fresh/.test(r.out) &&
+  /1 problem \(0 errors, 1 warning\)/.test(r.out);
+
 /** Runs the utility with output captured — quieter and faster than spawning a process. */
 async function cli(args, cwd) {
   // 🔴 THE STREAMS ARE SPLIT, AND THAT IS LOAD-BEARING. As long as the harness dumped log and
@@ -196,7 +205,7 @@ check(
     const bare = await cli(["lint"], root);
     check(
       "🔴 NO paperlint.json IS A VALID PROJECT — the default papers directory is linted",
-      bare.code === 0 && /no findings/.test(bare.out),
+      cleanButUnbuilt(bare),
     );
     check(
       "and no config line is printed when there is no file to name",
@@ -208,7 +217,7 @@ check(
     const empty = await cli(["lint"], root);
     check(
       `an empty paperlint.json — no \`${PAPERS_DIR_FIELD}\`, so the default`,
-      empty.code === 0 && /no findings/.test(empty.out),
+      cleanButUnbuilt(empty),
     );
 
     // 🔴 THE DECLARED DIRECTORY IS NOT THE DEFAULT: with `papers` declared, a CLI that ignored
@@ -221,7 +230,7 @@ check(
     const r = await cli(["lint"], root);
     check(
       "🔴 THE UTILITY READS THE DECLARATION FROM paperlint.json — the file `paperlint init` writes and the hooks read",
-      r.code === 0 && /no findings/.test(r.out),
+      cleanButUnbuilt(r),
     );
     check(
       "and NAMES the carrier out loud — swapping settings is never silent",
@@ -713,7 +722,7 @@ check(
     const clean = await cli(["lint", "papers"], root);
     check(
       "on a clean corpus — zero and a legible report",
-      clean.code === 0 && /no findings/.test(clean.out),
+      cleanButUnbuilt(clean),
     );
 
     writeFileSync(join(paper, "PIPELINE-STATUS.md"), status(999));
@@ -822,7 +831,7 @@ check(
     const found = await cli(["lint"], root);
     check(
       "the config is FOUND on its own: `lint` with no argument at all runs",
-      found.code === 0 && /no findings/.test(found.out),
+      cleanButUnbuilt(found),
     );
     check(
       "and the found file is NAMED out loud — swapping settings silently is not acceptable",
@@ -836,7 +845,7 @@ check(
     const fromSub = await cli(["lint"], paper);
     check(
       "the path from the config resolves relative to the CONFIG'S DIRECTORY, not the current one",
-      fromSub.code === 0 && /no findings/.test(fromSub.out),
+      cleanButUnbuilt(fromSub),
     );
 
     // Consumer data from the found config actually reaches the rules, not just gets read.
@@ -865,7 +874,7 @@ check(
     const noPapers = await cli(["lint"], root);
     check(
       "a config WITHOUT the papers-directory field lints the default `papers/`",
-      noPapers.code === 0 && /no findings/.test(noPapers.out),
+      cleanButUnbuilt(noPapers),
     );
     check(
       'an empty string as the papers directory is refused, not read as the directory ""',
@@ -925,7 +934,7 @@ check(
     );
     check(
       'and the failure names the NUMBER and the THRESHOLD, not just "too many"',
-      /3 warning\(s\) exceed the --max-warnings limit of 0/.test(strict.out),
+      /4 warning\(s\) exceed the --max-warnings limit of 0/.test(strict.out),
     );
     const generous = await cli(["lint", "--max-warnings", "5"], root);
     check(
@@ -1597,13 +1606,14 @@ console.log(
     );
     const r = await cli(["new", "demo"], root);
     check(
-      "🔴 `paperlint new demo` creates writing/demo/ and its lint is the verdict — exit 0, and only the warning that no venue is chosen yet",
+      "🔴 `paperlint new demo` creates writing/demo/ and its lint is the verdict — exit 0, and only two warnings: no venue is chosen yet, the paper is not built",
       r.code === 0 &&
         existsSync(join(root, "writing", "demo", "PIPELINE-STATUS.md")) &&
         existsSync(join(root, "writing", "demo", "paper.tex")) &&
         existsSync(join(root, "writing", "demo", "paperlint.json")) &&
         /names no venue preset yet/.test(r.out) &&
-        /\(0 errors, 1 warning\)/.test(r.out),
+        /paper\/sources-fresh/.test(r.out) &&
+        /\(0 errors, 2 warnings\)/.test(r.out),
     );
     const again = await cli(["new", "demo"], root);
     check(