paperlint 4.2.0 → 6.0.0

package/src/adapters/latex/index.ts

@@ -31,6 +31,7 @@ import { outlineOf } from "./outline.ts";
 import { parseLatex } from "./parse.ts";
 import { bodyProse } from "./prose.ts";
 import { renderedRuns } from "./rendered.ts";
+import { layoutOverridesOf } from "./layout.ts";
 
 export {
   documentClassOf,
@@ -51,6 +52,7 @@ export { outlineOf } from "./outline.ts";
 export { parseLatex, type ParsedTex } from "./parse.ts";
 export { bodyProse } from "./prose.ts";
 export { renderedRuns } from "./rendered.ts";
+export { layoutOverridesOf } from "./layout.ts";
 
 /** The `LatexReader` port over unified-latex: each call parses its source once. */
 export const latexReader: LatexReader = {
@@ -62,4 +64,5 @@ export const latexReader: LatexReader = {
   documentBody: (src) => documentBodyOf(parseLatex(src)),
   template: parseTemplate,
   withDocumentClass: (src, want) => replaceDocumentClass(parseLatex(src), want),
+  layoutOverrides: (src) => layoutOverridesOf(parseLatex(src)),
 };

package/src/adapters/latex/layout.ts

@@ -0,0 +1,106 @@
+/**
+ * Where a source changes the page layout its class sets for the whole document — the input of
+ * `format/layout-override`. Read from the parse tree, never the text: a command in a comment is not
+ * a command.
+ *
+ * What counts, each by its node:
+ *
+ *   \usepackage{geometry} · \RequirePackage{…,geometry}   the package that re-sets the margins
+ *   \geometry{…} · \newgeometry{…}                        its commands
+ *   \setlength / \addtolength on a layout length          \textheight \textwidth \topmargin …
+ *   \linespread{…} · \renewcommand{\baselinestretch}      the line spacing
+ *
+ * Local spacing — a negative `\vspace` or `\vskip` around one float — is not a layout the template
+ * sets, and no venue's call names it; it is not read.
+ *
+ * A comment and a `comment` environment are not read — the parser hands both back as text, not
+ * macros. Everything else is — the bibliography, math, floats — and a macro definition too: a
+ * `\newcommand` whose body sets a layout length does so wherever it is used. Conditionals are not
+ * evaluated.
+ */
+import type { LayoutOverride } from "../../domain/tex-document.ts";
+import {
+  collapse,
+  isList,
+  macroPlace,
+  mandatory,
+  textOf,
+  visited,
+  type Macro,
+} from "./nodes.ts";
+import type { ParsedTex } from "./parse.ts";
+
+/** The lengths the class sets for the page and the line; changing one changes the venue's layout. */
+export const LAYOUT_LENGTHS: ReadonlySet<string> = new Set([
+  "textheight",
+  "textwidth",
+  "topmargin",
+  "oddsidemargin",
+  "evensidemargin",
+  "columnsep",
+  "headsep",
+  "headheight",
+  "footskip",
+  "baselineskip",
+]);
+
+/** The macro a mandatory argument holds first, or undefined: `{\textheight}` → `textheight`. */
+function firstMacro(m: Macro, i: number): string | undefined {
+  const first = mandatory(m)[i]?.content.find((n) => n.type !== "whitespace");
+  return first?.type === "macro" ? first.content : undefined;
+}
+
+const argText = (m: Macro, i: number): string =>
+  collapse(textOf(mandatory(m)[i]?.content));
+
+/** What names a macro that overrides the layout; null: this use of it does not. */
+type Namer = (m: Macro) => string | null;
+
+const usesGeometry: Namer = (m) =>
+  argText(m, 0)
+    .split(",")
+    .map((p) => p.trim())
+    .includes("geometry")
+    ? `\\${m.content}{geometry}`
+    : null;
+
+const setsLayoutLength: Namer = (m) => {
+  const length = firstMacro(m, 0);
+  return length !== undefined && LAYOUT_LENGTHS.has(length)
+    ? `\\${m.content}{\\${length}}`
+    : null;
+};
+
+/** Each macro that may override the layout, and how to tell whether this use of it does. */
+const OVERRIDES: ReadonlyMap<string, Namer> = new Map<string, Namer>([
+  ["usepackage", usesGeometry],
+  ["RequirePackage", usesGeometry],
+  ["geometry", (m) => `\\${m.content}`],
+  ["newgeometry", (m) => `\\${m.content}`],
+  ["linespread", (m) => `\\linespread{${argText(m, 0)}}`],
+  ["setlength", setsLayoutLength],
+  ["addtolength", setsLayoutLength],
+  [
+    "renewcommand",
+    (m) =>
+      firstMacro(m, 0) === "baselinestretch"
+        ? "\\renewcommand{\\baselinestretch}"
+        : null,
+  ],
+]);
+
+/** How a message names a macro that overrides the layout, or null when it does not. */
+const overrideOf: Namer = (m) => OVERRIDES.get(m.content)?.(m) ?? null;
+
+/** Every layout override in the source, in document order. */
+export function layoutOverridesOf(t: ParsedTex): readonly LayoutOverride[] {
+  // Nothing is pruned: a comment, and a `comment` environment, reach the tree as leaves of text.
+  const lists = visited(t.root, () => false).filter(isList);
+  return lists.flatMap((list) =>
+    list.flatMap((n) => {
+      if (n.type !== "macro") return [];
+      const command = overrideOf(n);
+      return command === null ? [] : [{ command, place: macroPlace(n) }];
+    }),
+  );
+}

package/src/adapters/latex/nodes.ts

@@ -63,9 +63,17 @@ const NONE: Shown = { kind: "none" };
  */
 const SHOWN_ARGUMENT: ReadonlyMap<string, Shown> = new Map<string, Shown>([
   ["texorpdfstring", { kind: "argument", at: 0 }],
-  ...["color", "fontsize", "vspace", "hspace", "setlength", "addtolength"].map(
-    (m) => [m, NONE] as const,
-  ),
+  ...[
+    "color",
+    "fontsize",
+    "vspace",
+    "hspace",
+    "setlength",
+    "addtolength",
+    "linespread",
+    "geometry",
+    "newgeometry",
+  ].map((m) => [m, NONE] as const),
 ]);
 
 /** The text a (non-key) macro typesets: see `SHOWN_ARGUMENT`. */

package/src/adapters/latex/parse.ts

@@ -82,7 +82,11 @@ const LINK_SIGNATURES = Object.fromEntries(signed(["href"], "m m"));
  * Declarations unified-latex has no signature for: signed so their arguments (sizes, not text)
  * attach to them instead of standing beside them as groups a reader would seem to see.
  */
-const DECLARATION_SIGNATURES = Object.fromEntries(signed(["fontsize"], "m m"));
+const DECLARATION_SIGNATURES = Object.fromEntries([
+  ...signed(["fontsize"], "m m"),
+  // The layout commands `format/layout-override` reads: a spacing factor, geometry's key list.
+  ...signed(["linespread", "geometry", "newgeometry"], "m"),
+]);
 
 /**
  * Macros that define other macros or environments. A heading in a body is no section where it is

package/src/build.harness.mjs

@@ -264,8 +264,10 @@ try {
     tex.calls.every((c) => c.cwd === clean),
   );
   check(
-    "🔴 pdflatex got paperlint's venues directory on TEXINPUTS, trailing separator kept",
-    tex.calls.every((c) => c.texinputs === `${venues}${delimiter}`),
+    "🔴 pdflatex got the paper's directory, then paperlint's venues directory, on TEXINPUTS, trailing separator kept",
+    tex.calls.every(
+      (c) => c.texinputs === `.${delimiter}${venues}${delimiter}`,
+    ),
   );
 
   // ── the measure step: facts for the lint rules ────────────────────────────────────────
@@ -287,8 +289,8 @@ try {
   if (existsSync(factsFile)) {
     const f = JSON.parse(readFileSync(factsFile, "utf8"));
     check(
-      "measure: the facts are schema 2, about paper.pdf, with the last page's heights",
-      f.schema === 2 &&
+      "measure: the facts are schema 3, about paper.pdf, with the last page's heights",
+      f.schema === 3 &&
         f.pdf === "paper.pdf" &&
         JSON.stringify(f.last_page_cols_pt) === "[400,400]",
     );

package/src/build.test.ts

@@ -6,7 +6,8 @@
  */
 import assert from "node:assert/strict";
 import { existsSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { delimiter, join } from "node:path";
+import { texInputsDir } from "./package-dirs.ts";
 import { test } from "vitest";
 import { present, useTempDir, writeTree } from "../test/support.ts";
 import {
@@ -114,6 +115,11 @@ const reader =
         },
         last,
         layout: [],
+        pageTexts: [],
+        links: [],
+        bibAnchorPage: null,
+        appendixAnchorPage: null,
+        metadata: {},
       },
     });
 const quiet = () => {};
@@ -344,6 +350,22 @@ test("paths: a paper that IS the working directory is named by its full path", a
   assert.equal(existsSync(join(dir, "paper.pdf")), false);
 });
 
+test("🔴 pdflatex looks for an \\input in the paper's directory, then paperlint's inputs, then the system tree", async () => {
+  const dir = paper();
+  const f: Fake = {};
+  const inner = fakeRun(f);
+  const seen: (string | undefined)[] = [];
+  await build(dir, f, {
+    run: (bin, args, opts) => {
+      if (bin === "pdflatex") seen.push(opts.env?.["TEXINPUTS"]);
+      return inner(bin, args, opts);
+    },
+  });
+  // The same search path the lint rules read includes through (`texSearchPath`).
+  // A pass runs in the paper's directory, where `.` is that directory.
+  assert.equal(seen[0], [".", texInputsDir(), ""].join(delimiter));
+});
+
 test("facts that cannot be read fail the build at `facts`", async () => {
   const { line } = await build(
     paper({ "paper.tex": TEX, "paperlint.json": "{ nope" }),

package/src/build.ts

@@ -44,7 +44,7 @@ import { createHash } from "node:crypto";
 import { delimiter, join, relative } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import { getParser } from "@unified-latex/unified-latex-util-parse";
-import { texInputsDir } from "./package-dirs.ts";
+import { texInputsDir, texSearchPath } from "./package-dirs.ts";
 import { CONFIG_FILE } from "#lib/paper-config";
 import {
   declaredVenue,
@@ -268,11 +268,15 @@ export const inputsStep: BuildStep = {
   required: false,
   applies: () => ({
     yes: true,
-    why: `TEXINPUTS += ${texInputsDir()}`,
+    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).
   run: (ctx) => ({
     ok: true,
-    env: withTexInputs(ctx.env, [texInputsDir()]),
+    env: withTexInputs(ctx.env, texSearchPath(".")),
   }),
 };
 

package/src/cli.harness.mjs

@@ -132,8 +132,8 @@ check(
     Array.isArray(cfg) && ruleBlocks(cfg).length === 4,
   );
   check(
-    "with a LaTeX language a fifth block is added",
-    ruleBlocks(buildConfig({}, {})).length === 5,
+    "with a LaTeX language two blocks are added: paper.tex, and the files it includes",
+    ruleBlocks(buildConfig({}, {})).length === 6,
   );
   check(
     "🔴 the project's paper TEMPLATE directory is ignored — flat config does not skip dot-directories",
@@ -181,7 +181,7 @@ check(
     writeFileSync(join(paper, "paper.md"), "# Intro\n\nRQ1: does it hold?\n");
     writeFileSync(
       join(paper, "PIPELINE-STATUS.md"),
-      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: 100\n    source: versions/s.tex\n    sourceBytes: 4\nresearchQuestion: "does it hold?"\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`,
+      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: 100\n    source: versions/s.tex\n    sourceBytes: 4\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`,
     );
     writeFileSync(
       join(root, "package.json"),
@@ -441,32 +441,14 @@ check(
         !existsSync(join(dir, WORKFLOW_PATH)),
       );
       check(
-        "and the CI step is still printed — it just gets pasted in by hand",
-        /uses: zernie\/paperlint@/.test(out.text()) &&
-          /paths: writing/.test(out.text()),
-      );
-    }
-    {
-      // Guards: the printed step carries the tag of the running release, not a placeholder.
-      const dir = project("ci-printed-pin", { papers: ["writing"] });
-      const out = say();
-      await init(dir, {
-        log: out.log,
-        err: out.log,
-        interactive: false,
-        run: haveAll,
-        version: "1.2.3",
-      });
-      check(
-        "🔴 a released version — the printed step is pinned to its tag, no <commit-sha>",
-        /uses: zernie\/paperlint@v1\.2\.3\b/.test(out.text()) &&
-          !/<commit-sha>/.test(out.text()),
+        "and the CI steps are still printed — they just get pasted in by hand",
+        out.text().includes("- uses: ./node_modules/paperlint"),
       );
     }
     {
       const dir = project("ci-yes", { papers: ["writing"] });
       const asked = [];
-      const wf = await offerWorkflow(dir, "writing", {
+      const wf = await offerWorkflow(dir, {
         interactive: true,
         ask: async (q) => {
           asked.push(q);
@@ -477,16 +459,22 @@ check(
         "saying yes WRITES the workflow",
         wf === "written" && existsSync(join(dir, WORKFLOW_PATH)),
       );
+      const steps =
+        yamlLoad(readFileSync(join(dir, WORKFLOW_PATH), "utf8"))?.jobs?.papers
+          ?.steps ?? [];
       check(
-        "and the workflow carries THE directory that was actually discussed",
-        /paths: writing/.test(readFileSync(join(dir, WORKFLOW_PATH), "utf8")),
+        "🔴 the workflow runs the action from the installed package — one revision, set by the lockfile",
+        steps.some((st) => st.uses === "./node_modules/paperlint") &&
+          !steps.some((st) =>
+            String(st.uses ?? "").startsWith("zernie/paperlint"),
+          ),
       );
       check(
-        "without a known release the action keeps the obvious placeholder, never a guessed tag",
-        /@<commit-sha>/.test(readFileSync(join(dir, WORKFLOW_PATH), "utf8")),
+        "and it repeats no papers directory — the action reads papersDir from paperlint.json",
+        steps.every((st) => st.with?.paths === undefined),
       );
       check("the question is asked exactly once", asked.length === 1);
-      const again = await offerWorkflow(dir, "writing", {
+      const again = await offerWorkflow(dir, {
         interactive: true,
         ask: async () => "y",
       });
@@ -495,29 +483,9 @@ check(
         again === "kept",
       );
     }
-    {
-      const dir = project("ci-pinned", { papers: ["writing"] });
-      const wf = await offerWorkflow(dir, "writing", {
-        interactive: true,
-        ask: async () => "y",
-        version: "1.2.3",
-      });
-      const yaml = existsSync(join(dir, WORKFLOW_PATH))
-        ? readFileSync(join(dir, WORKFLOW_PATH), "utf8")
-        : "";
-      const uses = (yamlLoad(yaml)?.jobs?.papers?.steps ?? []).map(
-        (s) => s.uses,
-      );
-      check(
-        "🔴 a released version — the written workflow is pinned to its tag, no <commit-sha> left",
-        wf === "written" &&
-          uses.includes("zernie/paperlint@v1.2.3") &&
-          !yaml.includes("<commit-sha>"),
-      );
-    }
     {
       const dir = project("ci-no", { papers: ["writing"] });
-      const no = await offerWorkflow(dir, "writing", {
+      const no = await offerWorkflow(dir, {
         interactive: true,
         ask: async () => "",
       });
@@ -532,7 +500,7 @@ check(
       // 🔴 THE `.catch` HERE IS LOAD-BEARING, NOT CAUTION. A leaked exception is a PROPERTY that
       // gets asserted; without it, the harness crashes instead of failing a named assertion,
       // i.e. the real defect would look like a hole in the test rather than a caught one.
-      const aborted = await offerWorkflow(dir, "writing", {
+      const aborted = await offerWorkflow(dir, {
         interactive: true,
         ask: async () => {
           throw new Error("Aborted with Ctrl+D");
@@ -733,7 +701,7 @@ check(
       "x".repeat(100),
     );
     const status = (bytes) =>
-      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: ${bytes}\n    source: versions/s.tex\n    sourceBytes: 4\nresearchQuestion: "does it hold?"\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`;
+      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: ${bytes}\n    source: versions/s.tex\n    sourceBytes: 4\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`;
     writeFileSync(join(paper, "versions", "s.tex"), "abcd");
     writeFileSync(join(paper, "paper.md"), "# Intro\n\nRQ1: does it hold?\n");
 
@@ -822,7 +790,7 @@ check(
     );
     writeFileSync(join(paper, "paper.md"), "# Intro\n\nRQ1: does it hold?\n");
     const status = (bytes) =>
-      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: ${bytes}\n    source: versions/s.tex\n    sourceBytes: 4\nresearchQuestion: "does it hold?"\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`;
+      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: ${bytes}\n    source: versions/s.tex\n    sourceBytes: 4\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`;
     writeFileSync(join(paper, "PIPELINE-STATUS.md"), status(100));
 
     // findProjectRoot — kept separate from the run so the failure is distinguishable
@@ -934,7 +902,7 @@ check(
     );
     writeFileSync(
       join(paper, "PIPELINE-STATUS.md"),
-      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: 100\n    source: versions/s.tex\n    sourceBytes: 4\nresearchQuestion: "does it hold?"\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`,
+      `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: 100\n    source: versions/s.tex\n    sourceBytes: 4\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`,
     );
     writeFileSync(
       join(root, "paperlint.json"),

package/src/cli.test.ts

@@ -14,7 +14,6 @@ import type { runToolchain } from "./toolchain.ts";
 import {
   chooseVenue,
   initTexLive,
-  ownVersion,
   paperRuleBlocks,
   parseArgs,
   parseSettings,
@@ -259,7 +258,7 @@ test("build: a markdown-only paper is refused", async () => {
     code: 1,
     out: [
       "papers/md",
-      `  inputs: TEXINPUTS += ${venues}`,
+      `  inputs: TEXINPUTS += the paper's directory, then ${venues}`,
       "  compile: refused — no paper.tex; paperlint compiles LaTeX, and this paper has none",
       "  measure: skipped — nothing is compiled",
       "  references: skipped — nothing is compiled",
@@ -288,7 +287,7 @@ test("build: with no TeX Live a dry run says where a real run stops, and a real
         out: [
           `engine: none — a real run would stop here: paperlint build: no TeX Live with every package these papers need — run \`npx paperlint toolchain\` (${missing})`,
           "papers/tex",
-          `  inputs: TEXINPUTS += ${venues}`,
+          `  inputs: TEXINPUTS += the paper's directory, then ${venues}`,
           "  compile: paper.tex (\\documentclass{article})",
           "  measure: pdf.js → _build/paper.facts.json (facts for the lint rules; nothing is judged here)",
           "  references: online: citations exist, titles and authors match → _build/references.json (never fails the build)",
@@ -529,21 +528,6 @@ test("chooseVenue: a question that fails (the stream ended) takes the default, n
   assert.deepEqual(r, { ok: true, value: null });
 });
 
-test("ownVersion: the manifest's version; an unreadable manifest or a non-string version is undefined", () => {
-  assert.deepEqual(
-    [
-      ownVersion(() => '{"version": "1.2.3"}'),
-      ownVersion(() => "{ nope"),
-      ownVersion(() => '{"version": 3}'),
-      ownVersion(() => {
-        throw new Error("ENOENT");
-      }),
-      typeof ownVersion(),
-    ],
-    ["1.2.3", undefined, undefined, undefined, "string"],
-  );
-});
-
 test("init's TeX Live install runs the toolchain over the project's papers, never a check", () => {
   const dir = writeTree(join(root, "init-tex"), { "package.json": "{}" });
   const calls: Parameters<typeof runToolchain>[0][] = [];
@@ -594,3 +578,16 @@ test("`paperlint hook` with no name: exit 2, and the usage names an example", as
     err: "`hook` needs a name, e.g. `paperlint hook paper-edit-guard`",
   });
 });
+
+test("parseSettings refuses a root `identity` that is not a list of words, and takes one that is", () => {
+  const bad = parseSettings({ identity: "Ada" }, "paperlint.json", "/r");
+  assert.deepEqual(bad, {
+    ok: false,
+    error:
+      'paperlint.json: "identity" must be a list of strings, each with a letter or digit, got "Ada"',
+  });
+  assert.equal(
+    parseSettings({ identity: ["Ada Example"] }, "paperlint.json", "/r").ok,
+    true,
+  );
+});