paperlint 4.1.0 → 5.0.0

package/src/domain/paper-source.ts

@@ -0,0 +1,233 @@
+/**
+ * A paper as one text: `paper.tex` with every `\input`, `\include` and `\subfile` replaced by the
+ * file it names — what TeX itself does — and a map from every character of that text back to the
+ * file and offset it came from. The rules read the whole paper; a finding still points at its file.
+ *
+ * ── WHY SPLICE THE TEXT ──────────────────────────────────────────────────────────
+ * `\input` is textual inclusion: TeX reads the named file where the macro stands. Replacing the
+ * macro by the file's text gives the parser exactly what TeX reads, so every question the reader
+ * answers about one file (the class, the outline, the rendered text, the body's passages) is
+ * answered about the paper, unchanged. A subfile is a document of its own; only its body is spliced.
+ *
+ * ── WHAT IS NOT DONE ─────────────────────────────────────────────────────────────
+ * No macro is expanded, so a path built from a macro (`\input{\dir/intro}`) is read as written. A
+ * file that cannot be found is left out and named in `missing`; a file that includes itself,
+ * directly or through others, is spliced once.
+ */
+import { extname, normalize } from "node:path";
+import type { Span } from "./tex-document.ts";
+
+/** One `\input`, `\include` or `\subfile` in a source: the path as written and where the macro stands. */
+export interface Include {
+  readonly macro: "input" | "include" | "subfile";
+  readonly target: string;
+  readonly span: Span;
+}
+
+/** What assembling needs from the LaTeX reader and from the disk, relative to the paper directory. */
+export interface AssembleDeps {
+  /** The includes of a source, in source order. */
+  readonly includes: (src: string) => readonly Include[];
+  /** The span of a source's `document` environment body, or null when it has none. */
+  readonly documentBody: (src: string) => Span | null;
+  /** A file's text by its path relative to the paper directory, or null when there is none. */
+  readonly read: (path: string) => string | null;
+}
+
+/** A stretch of the assembled text copied from one file: `[start, end)` here is `from…` there. */
+export interface Segment {
+  readonly start: number;
+  readonly end: number;
+  readonly file: string;
+  /** The whole text of `file`, so a place in it can be told as a line and a column. */
+  readonly source: string;
+  readonly from: number;
+  /** Where, in the main file, the outermost include that brought this text in stands. */
+  readonly via: Span | null;
+}
+
+/** An include whose file was not found, where it stands. */
+export interface MissingInclude {
+  readonly file: string;
+  readonly target: string;
+  readonly span: Span;
+  /** Where it stands in the main file (the include itself, or the one that brought its file in). */
+  readonly via: Span;
+}
+
+/** The paper as one text, the map back to its files, and the includes that were not found. */
+export interface PaperSource {
+  readonly main: string;
+  readonly text: string;
+  readonly segments: readonly Segment[];
+  readonly missing: readonly MissingInclude[];
+}
+
+/** The paths TeX tries for a target: `name.tex`, then `name` — or the name alone if it has one. */
+const candidates = (target: string): readonly string[] => {
+  const t = normalize(target.trim());
+  return extname(t) === "" ? [`${t}.tex`, t] : [t];
+};
+
+/** The first candidate path that exists, with its text. */
+function found(
+  target: string,
+  read: AssembleDeps["read"],
+): { readonly path: string; readonly text: string } | null {
+  const hits = candidates(target).flatMap((path) => {
+    const text = read(path);
+    return text === null ? [] : [{ path, text }];
+  });
+  return hits[0] ?? null;
+}
+
+/** An assembled piece of text: the text, its segments from 0, and the includes not found. */
+interface Piece {
+  readonly text: string;
+  readonly segments: readonly Segment[];
+  readonly missing: readonly MissingInclude[];
+}
+
+/** `segments` moved by `by` characters. */
+const shifted = (
+  segments: readonly Segment[],
+  by: number,
+): readonly Segment[] =>
+  segments.map((s) => ({ ...s, start: s.start + by, end: s.end + by }));
+
+/** `[from, to)` of `file`'s text, copied as it is, brought in via `via`. */
+interface Stretch {
+  readonly file: string;
+  readonly text: string;
+  readonly from: number;
+  readonly to: number;
+  readonly via: Span | null;
+}
+
+/** A stretch as a piece: its text, and one segment mapping it back. */
+const copied = ({ file, text, from, to, via }: Stretch): Piece => ({
+  text: text.slice(from, to),
+  segments:
+    to > from
+      ? [{ start: 0, end: to - from, file, source: text, from, via }]
+      : [],
+  missing: [],
+});
+
+/** Nothing: an include left out. */
+const NOTHING: Piece = { text: "", segments: [], missing: [] };
+
+/** Pieces joined in order. */
+const joined = (pieces: readonly Piece[]): Piece =>
+  pieces.reduce<Piece>(
+    (acc, p) => ({
+      text: acc.text + p.text,
+      segments: [...acc.segments, ...shifted(p.segments, acc.text.length)],
+      missing: [...acc.missing, ...p.missing],
+    }),
+    NOTHING,
+  );
+
+/**
+ * `[from, to)` of `file`, its includes spliced. `stack` is the chain of files being spliced, so a
+ * file that includes itself is not entered again; `via` is where the chain began in the main file.
+ */
+/** What splicing carries down the chain of files. */
+interface Context {
+  readonly deps: AssembleDeps;
+  readonly stack: readonly string[];
+  readonly via: Span | null;
+}
+
+function spliced(file: string, text: string, range: Span, ctx: Context): Piece {
+  const incs = ctx.deps
+    .includes(text)
+    .filter((i) => i.span.start >= range.start && i.span.end <= range.end);
+  const at = (from: number, to: number): Piece =>
+    copied({ file, text, from, to, via: ctx.via });
+  const { pieces, cursor } = incs.reduce<{
+    readonly pieces: readonly Piece[];
+    readonly cursor: number;
+  }>(
+    (acc, inc) => ({
+      pieces: [
+        ...acc.pieces,
+        at(acc.cursor, inc.span.start),
+        included(file, inc, ctx),
+      ],
+      cursor: inc.span.end,
+    }),
+    { pieces: [], cursor: range.start },
+  );
+  return joined([...pieces, at(cursor, range.end)]);
+}
+
+/** One include: the file it names, spliced, or — when not found — nothing, and a report. */
+function included(file: string, inc: Include, ctx: Context): Piece {
+  const via = ctx.via ?? inc.span;
+  const hit = found(inc.target, ctx.deps.read);
+  if (hit === null)
+    return {
+      ...NOTHING,
+      missing: [{ file, target: inc.target, span: inc.span, via }],
+    };
+  if (ctx.stack.includes(hit.path)) return NOTHING;
+  const body = inc.macro === "subfile" ? ctx.deps.documentBody(hit.text) : null;
+  return spliced(
+    hit.path,
+    hit.text,
+    body ?? { start: 0, end: hit.text.length },
+    { deps: ctx.deps, stack: [...ctx.stack, hit.path], via },
+  );
+}
+
+/** The paper whose main file is `main` (a path relative to the paper directory) with `text`. */
+export function assemblePaper(
+  main: string,
+  text: string,
+  deps: AssembleDeps,
+): PaperSource {
+  const p = spliced(
+    main,
+    text,
+    { start: 0, end: text.length },
+    { deps, stack: [main], via: null },
+  );
+  return {
+    main,
+    text: p.text,
+    segments: p.segments,
+    missing: p.missing,
+  };
+}
+
+/** Where a span of the assembled text stands: in which file, at which offsets, and via which include. */
+export interface Origin {
+  readonly file: string;
+  /** The whole text of `file`. */
+  readonly source: string;
+  readonly span: Span;
+  readonly via: Span | null;
+}
+
+/**
+ * The origin of `span` of the assembled text: the file of its first character. A span that runs
+ * past that file's stretch is cut at its end — a sentence cannot point into two files.
+ */
+export function originOf(p: PaperSource, span: Span): Origin | null {
+  // The character at `start`; an empty span at the very end belongs to the last stretch.
+  const seg =
+    p.segments.find((s) => span.start >= s.start && span.start < s.end) ??
+    p.segments.find((s) => span.start === s.end);
+  if (seg === undefined) return null;
+  const end = Math.min(span.end, seg.end);
+  return {
+    file: seg.file,
+    source: seg.source,
+    span: {
+      start: seg.from + span.start - seg.start,
+      end: seg.from + end - seg.start,
+    },
+    via: seg.via,
+  };
+}

package/src/domain/sentences.ts

@@ -0,0 +1,67 @@
+/**
+ * The sentences of body prose — one splitter, so every rule that counts or judges sentences cuts
+ * them the same way (`tex/claim-provenance` judges each; `tex/register` counts them).
+ *
+ * A passage becomes one text: its prose as itself, and each mark (a citation, a cross-reference) or
+ * math as one character no prose contains, where it stands. `Intl.Segmenter` cuts that text; a break
+ * after an abbreviation is undone, and marks set right after a full stop belong to the sentence the
+ * full stop ends.
+ */
+import type { Passage, ProsePiece, Segment, TextRun } from "./tex-document.ts";
+
+/** What stands in a sentence's text for a mark: characters no prose contains (private use). */
+export const CITATION = "";
+export const REFERENCE = "";
+export const MATH = "";
+
+/** A piece as the text of its sentence sees it: text as itself, a mark or math as one character. */
+export function segmentOf(p: ProsePiece): Segment {
+  switch (p.kind) {
+    case "text":
+      return p.segment;
+    case "owner":
+      return {
+        text: p.owner === "citation" ? CITATION : REFERENCE,
+        at: p.span.start,
+      };
+    case "math":
+      return { text: MATH, at: p.span.start };
+  }
+}
+
+/** A passage as one run of text, each mark a character where it stands. */
+export const runOf = (p: Passage): TextRun => {
+  const [first, ...rest] = p.pieces;
+  return { segments: [segmentOf(first), ...rest.map(segmentOf)] };
+};
+
+/** An abbreviation whose full stop does not end a sentence, at the end of a segment. */
+const ABBREVIATION =
+  /(?:^|[^\p{L}])(?:e\.g|i\.e|cf|vs|et al|Figs?|Secs?|Tab|Eqs?|No|App|approx|resp)\.\s*$/u;
+
+const SEGMENTER = new Intl.Segmenter("en", { granularity: "sentence" });
+
+/** Marks, and the spaces among them, that open a segment: a `\cite` or a footnote set after the full stop. */
+const LEADING_MARKS = /^[\s]*[]/u;
+
+/** `[from, to)` of a text. */
+export type Range = readonly [number, number];
+
+/**
+ * The sentences of `text`, as `[from, to)` ranges. A break after an abbreviation is undone, and
+ * marks standing right after a full stop belong to the sentence the full stop ends.
+ */
+export function sentences(text: string): readonly Range[] {
+  return [...SEGMENTER.segment(text)].reduce<readonly Range[]>((acc, s) => {
+    const prev = acc.at(-1);
+    const end = s.index + s.segment.length;
+    if (prev === undefined) return [[s.index, end]];
+    const before = acc.slice(0, -1);
+    if (ABBREVIATION.test(text.slice(...prev)))
+      return [...before, [prev[0], end]];
+    const split = s.index + (LEADING_MARKS.exec(s.segment)?.[0].length ?? 0);
+    return split < end
+      ? [...before, [prev[0], split], [split, end]]
+      : [...before, [prev[0], end]];
+  }, []);
+}

package/src/domain/tex-document.ts

@@ -24,12 +24,28 @@ export interface DocumentClass {
   readonly options: readonly string[];
 }
 
-/** A paper's `\documentclass`: none, one that names no class, or a class with its options. */
-export type ClassLine =
-  | { readonly kind: "missing" }
+/** One `\documentclass` line: one that names no class, or a class with its options. */
+export type ClassCandidate =
   | { readonly kind: "empty"; readonly place: Place }
   | ({ readonly kind: "class"; readonly place: Place } & DocumentClass);
 
+/**
+ * A paper's `\documentclass`: none, exactly one, or several — a source that picks its class behind
+ * a TeX switch (`\if\venue1 \documentclass{article} \fi …`). Which branch builds is not
+ * evaluated, so several lines are candidates, in source order, and none of them is THE class.
+ */
+export type ClassLine =
+  | { readonly kind: "missing" }
+  | ClassCandidate
+  | {
+      readonly kind: "ambiguous";
+      readonly candidates: readonly [
+        ClassCandidate,
+        ClassCandidate,
+        ...ClassCandidate[],
+      ];
+    };
+
 /** The options of `want` that `got` does not carry — every one, in `want`'s order. */
 export const missingOptions = (
   got: DocumentClass,
@@ -108,3 +124,20 @@ export function spanIn(run: TextRun, from: number, to: number): Span | null {
   const last = to > from ? offsetIn(run.segments, to - 1) : null;
   return start === null || last === null ? null : { start, end: last + 1 };
 }
+
+/** What a mark in prose says about where a claim comes from: a work outside the paper, or a place in it. */
+export type Owner = "citation" | "reference";
+
+/**
+ * One piece of body prose, in source order: text a reader sees, a mark the markup leaves in the
+ * sentence (a `\cite`, a link, a `\ref`), or math, with its source.
+ */
+export type ProsePiece =
+  | { readonly kind: "text"; readonly segment: Segment }
+  | { readonly kind: "owner"; readonly owner: Owner; readonly span: Span }
+  | { readonly kind: "math"; readonly tex: string; readonly span: Span };
+
+/** A stretch of body prose no sentence crosses — a paragraph, a list item, a footnote. Never empty. */
+export interface Passage {
+  readonly pieces: readonly [ProsePiece, ...ProsePiece[]];
+}

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/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