paperlint 8.0.0 → 9.0.1

package/src/CLAUDE.md.spec.ts

@@ -0,0 +1,72 @@
+// Compiled to src/CLAUDE.md by `npx vigiles compile`. Edit THIS file, never the markdown.
+import { enforce, file, instructionFile, prose } from "vigiles/spec";
+
+export default instructionFile({
+  sections: {
+    "`src/`": prose`The package's TypeScript: the CLI, the build, the toolchain installer, and the measuring that feeds
+the facts file. Loaded when working under \`src/\`; the repository-wide rules are in the root
+\`CLAUDE.md\`.`,
+
+    "The two layer axes": prose`**\`src/\` is hexagonal on two axes, and the linter enforces both** (\`eslint.config.mjs\`; fixtures in
+\`test/fixtures/layers/\`, run by ${file("test/eslint-layers.test.ts")}; issue #76).
+
+**Axis A — knowledge. Core means the DOMAIN, not "no I/O".** A file belongs to an adapter when it
+exists because of one external program or format: _if banal / pdf.js / TeX Live / ESLint / Claude
+Code disappeared tomorrow, which files would change? Those are its adapter, wherever they sit
+today._ The domain is what would not change if every one of them were swapped. Purity is not the
+test — a parser for banal's JSON is pure and is still banal's.
+
+| element   | where                  | holds                                                                                                                                                              | may import                                                                                                              |
+| --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| \`domain\`  | \`src/domain/\`          | values and decisions in the paper's vocabulary                                                                                                                     | \`domain\`; \`ts-essentials\`, \`node:path\`, \`node:crypto\`                                                                   |
+| \`port\`    | \`src/ports/\`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | \`domain\`, \`port\`; the same three externals                                                                              |
+| \`app\`     | \`src/*.ts\`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | \`domain\`, \`port\`, \`app\`, the package's \`.mjs\`; Node's \`util\`/\`url\`/\`module\`                                             |
+| \`adapter\` | \`src/adapters/<tool>/\` | everything that knows \`<tool>\` exists, pure parsers included; used through its \`index.ts\`                                                                          | \`domain\`, \`port\`, its own folder, its tool's packages, the package's \`.mjs\`. **Never** \`app\`, **never** another adapter |
+| \`root\`    | \`src/cli.ts\`           | reads \`process.*\`, builds adapters, wires ports                                                                                                                    | anything                                                                                                                |
+
+Folders are ELEMENTS of \`eslint-plugin-boundaries\`, single files are CATEGORIES (\`root\`, \`app\`,
+\`test\`, \`io\`): v7 matches element patterns as folders. Everyone — tests included — reaches an
+adapter through its \`index.ts\`; the files inside one adapter import each other freely.
+
+**Axis B — purity.** An effect (disk, process, network, env, clock, TTY) may be written only in
+\`src/adapters/<tool>/<x>.io.ts\` and \`src/cli.ts\`. Every other file, adapters' parsers included,
+takes a port. Test: _can a call here fail for a reason not in its arguments?_ Imports are checked
+through the \`io\` file category in \`boundaries/dependencies\`; the \`process\` and \`fetch\` globals by
+\`no-restricted-globals\`.
+
+**The legacy app files are held by a ratchet, not exempted.** A site that still breaks either axis
+carries \`// eslint-disable-next-line <rule> -- legacy <I/O|layer>, moves behind a port in #76\`.
+Unused directives are errors (\`reportUnusedDisableDirectives\`), so a fixed site must drop its
+comment; the per-file counts are frozen in \`scripts/layer-legacy.frozen.json\` and checked by
+${file("scripts/layer-legacy-frozen.ts")} (\`npm run check\`, CI), which counts ESLint's own
+\`suppressedMessages\` and fails when a file's count grows, a file not in the list carries one, or
+anything under \`src/domain/\`, \`src/ports/\` or \`src/adapters/\` does. A NEW module that needs the
+world is a new \`*.io.ts\` in the adapter of the program it talks to — never a new directive.
+
+Parse at the boundary, into types that cannot hold an invalid state (a banal path that exists only
+after its sha256 and probe passed; a \`Ready\` only an installer mints; an outcome as a discriminated
+union, not a string); the inside never re-validates.
+
+⚠️ **Two settings are load-bearing.** \`boundaries/root-path\`: without it the plugin matches paths
+against \`process.cwd()\`, so lint started from any other directory classifies nothing and passes.
+\`checkAllOrigins: true\`: without it no \`module:\` policy is evaluated, so axis B and the library bans
+report nothing — dropping it turns the fixtures \`src/domain/reads-disk.ts\` and
+\`src/adapters/one/disk.ts\` clean (measured).`,
+
+    "Readers and commands": prose`\`@retorquere/bibtex-parser\` is the one \`.bib\` reader, behind ${file("src/ports/bib-reader.ts")}.
+Rejected on 2026-09-27, so not proposed again: a separate \`paperlint refs\` command; the slowness it
+would have moved was a cache thrown away after every build (${file("docs/references.md")}).`,
+  },
+  rules: {
+    layers: enforce(
+      "eslint/boundaries/dependencies",
+      "Both axes: what a layer may import, and where an effect may be written.",
+      { render: "id" },
+    ),
+    "effect-globals": enforce(
+      "eslint/no-restricted-globals",
+      "The process and fetch globals only where an effect may be written.",
+      { render: "id" },
+    ),
+  },
+});

package/src/adapters/bibtex/index.test.ts

@@ -0,0 +1,163 @@
+/**
+ * The bibtex reader over @retorquere/bibtex-parser: where each entry stands, its fields as text, its
+ * name lists as names, the `@string` and `@preamble` a copy is compared on, and an entry it cannot
+ * finish. What bibtex reads beyond it is the post-build check's (src/references.ts), measured on the
+ * planted papers in src/paper-sources.test.ts.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { absolutePath } from "../../domain/paths.ts";
+import { bibReader } from "./index.ts";
+
+const PATH = absolutePath("/p/refs.bib");
+const read = (text: string) => bibReader.readFile(PATH, text);
+
+describe("the bibtex reader", () => {
+  it("places each entry in the text, a block's within the file that holds it", () => {
+    const tex =
+      "\\begin{filecontents*}{refs.bib}\n@misc{a, title={A}}\n@Article(b, title={B})\n\\end{filecontents*}\n";
+    const body = { start: tex.indexOf("@misc"), end: tex.indexOf("\\end") };
+    const bib = bibReader.read(absolutePath("/p/paper.tex"), tex, body);
+    expect(
+      bib.entries.map((e) => [
+        e.type,
+        e.key,
+        tex.slice(e.span.start, e.span.end),
+      ]),
+    ).toEqual([
+      ["misc", "a", "@misc{a, title={A}}"],
+      ["article", "b", "@Article(b, title={B})"],
+    ]);
+  });
+
+  it("reads fields as text: LaTeX accents, a link, a list field joined", () => {
+    const [e] = read(
+      '@book{k, title={M{\\"u}ller}, howpublished={\\url{https://x.org}}, publisher={A and B}}',
+    ).entries;
+    // The parser writes `{\"u}` as u and a combining diaeresis: compared composed.
+    expect(
+      Object.fromEntries(
+        Object.entries(e?.fields ?? {}).map(([k, v]) => [
+          k,
+          v.normalize("NFC"),
+        ]),
+      ),
+    ).toEqual({
+      title: "Müller",
+      howpublished: '<a href="https://x.org">https://x.org</a>',
+      publisher: "A and B",
+    });
+  });
+
+  it("reads a name list as names: family part, particle, suffix, a literal kept whole", () => {
+    const [e] = read(
+      "@misc{k, author={Lovelace, Ada and von Neumann, Jr., John and {World Health Organization} and others}}",
+    ).entries;
+    expect(e?.names).toEqual({
+      author: [
+        { lastName: "Lovelace", firstName: "Ada" },
+        {
+          lastName: "Neumann",
+          firstName: "John",
+          prefix: "von",
+          suffix: "Jr.",
+        },
+        { name: "World Health Organization" },
+        { lastName: "others" },
+      ],
+    });
+  });
+});
+
+describe("the bibtex reader — what a copy is compared on, and what it leaves to bibtex", () => {
+  it("reads @preamble commands, and expands each @string where an entry uses it", () => {
+    const bib = read(
+      '@string{v = "Venue"}\n@preamble{"\\x"}\n@misc{k, note = v}\n@string{v = "Later"}',
+    );
+    expect([bib.preamble, bib.entries[0]?.fields]).toEqual([
+      ['"\\x"'],
+      { note: "Venue" },
+    ]);
+  });
+
+  it("keeps each entry as bibtex takes it: the value it used, LaTeX and braces as written, whitespace folded", () => {
+    const bib = read(
+      '@string{v = "Venue"}\n@Misc{k, note = v # " 2", author = {G{\\"o}del,   Kurt}, title = {{X}}, keywords = {b, a}}\n@string{v = "Later"}',
+    );
+    expect(bib.written).toEqual([
+      {
+        type: "misc",
+        key: "k",
+        fields: {
+          note: "Venue 2",
+          author: 'G{\\"o}del, Kurt',
+          title: "{X}",
+          keywords: "a, b",
+        },
+      },
+    ]);
+  });
+
+  it("an entry it cannot finish is no entry — bibtex reports that file (v6, exit 2)", () => {
+    const text = readFileSync(
+      join(
+        dirname(fileURLToPath(import.meta.url)),
+        "../../../fixtures/paper-sources/v6-unclosed/refs.bib",
+      ),
+      "utf8",
+    );
+    expect(read(text).entries.map((e) => e.key)).toEqual(["a1", "a3"]);
+  });
+});
+
+describe("the bibtex reader — databases in sequence, as bibtex reads them", () => {
+  // bibtex reads the databases of `\\bibliography{abbreviations,references}` one after the other, and an
+  // `@string` the first defines is in force in the second (fixtures/paper-sources/v27-shared-string:
+  // its .bbl typesets the expanded author and booktitle).
+  const ABBR =
+    '@string{venue = "Proceedings of the {\\"O}ld Venue"}\n@string{who = "Lovelace, Ada"}\n';
+  const REFS =
+    "@inproceedings{late, author = who, booktitle = venue # {, Main}}\n";
+  const SECOND = absolutePath("/p/references.bib");
+
+  it("🔴 an @string an earlier database defined is in force in a later one: read as one file holding both", () => {
+    const first = read(ABBR);
+    const second = bibReader.readFile(SECOND, REFS, first.strings);
+    const whole = read(ABBR + REFS);
+    expect([
+      second.entries.map((e) => [e.fields, e.names]),
+      second.written,
+    ]).toEqual([whole.entries.map((e) => [e.fields, e.names]), whole.written]);
+    expect(second.written[0]?.fields).toEqual({
+      author: "Lovelace, Ada",
+      booktitle: 'Proceedings of the {\\"O}ld Venue, Main',
+    });
+  });
+
+  it("the @strings in force after a database are those before it and its own, a redefinition winning; a block reads with them too", () => {
+    const first = read(ABBR);
+    const second = bibReader.readFile(
+      SECOND,
+      '@string{venue = "Newer"}\n',
+      first.strings,
+    );
+    expect([second.inherited, second.strings]).toEqual([
+      first.strings,
+      { VENUE: "Newer", WHO: "Lovelace, Ada" },
+    ]);
+    const tex = `\\begin{filecontents*}{refs.bib}\n${REFS}\\end{filecontents*}\n`;
+    const body = { start: tex.indexOf("@"), end: tex.indexOf("\\end") };
+    expect(
+      bibReader.read(absolutePath("/p/paper.tex"), tex, body, second.strings)
+        .written[0]?.fields.booktitle,
+    ).toBe("Newer, Main");
+  });
+
+  it("read alone, a database has nothing inherited: a name no @string defines stays unresolved", () => {
+    const alone = bibReader.readFile(SECOND, REFS);
+    expect([alone.inherited, alone.strings]).toEqual([{}, {}]);
+    expect(alone.written[0]?.fields.author).not.toBe("Lovelace, Ada");
+  });
+});

package/src/adapters/bibtex/index.ts

@@ -0,0 +1,155 @@
+/**
+ * The bibtex reader over `@retorquere/bibtex-parser` — the one `.bib` reader of paperlint
+ * (`src/ports/bib-reader.ts`).
+ *
+ * It reads a well-formed database as bibtex does: entries, fields (LaTeX read into text, so `{\"u}`
+ * is `ü` and `\url{x}` a link), name lists split into names, `@string`s expanded, `@preamble`. A
+ * second reading keeps each field as bibtex takes it, LaTeX as written: what two databases are
+ * compared by (`sameDatabase`), where `{\"u}` and `ü` must stay different. A malformed
+ * database is bibtex's to report: the build runs bibtex and fails with bibtex's own lines. The two
+ * readers also differ on one well-formed shape: bibtex has no comment syntax, so an entry behind
+ * `%` or inside `@comment{…}` is one bibtex reads and this reader does not. The build records what
+ * bibtex read, and `paper/refs-checked` names such an entry (`src/references.ts`).
+ *
+ * The parser gives each entry's text (`input`), not its place: each is found in the body in order.
+ *
+ * A database read after others starts with the `@string`s they left in force (`inherited`), as bibtex
+ * reads a paper's databases in sequence with one table of them: the parser takes them as its table of
+ * predefined `@string`s, which the database's own definitions override from where they stand. Each
+ * database is still parsed as its own text, so every entry keeps its place in the file that holds it.
+ */
+import {
+  parse,
+  type Creator,
+  type Entry,
+  type Library,
+  type Options,
+} from "@retorquere/bibtex-parser";
+import type {
+  BibEntry,
+  BibName,
+  BibStrings,
+  BibText,
+  WrittenEntry,
+} from "../../domain/paper-sources.ts";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import type { Span } from "../../domain/tex-document.ts";
+import type { BibReader } from "../../ports/bib-reader.ts";
+
+/** A title as written, not sentence-cased; no field kept as raw LaTeX. */
+const OPTIONS: Readonly<Options> = { sentenceCase: false, verbatimFields: [] };
+
+/**
+ * Every field as bibtex takes it: `@string`s expanded where they are used, LaTeX left as written (no
+ * conversion, no name split, no outer braces dropped).
+ */
+const AS_WRITTEN: Readonly<Options> = {
+  raw: true,
+  sentenceCase: false,
+  verbatimFields: [/.*/],
+  removeOuterBraces: [],
+};
+
+/** A name's parts, those it has: the parser leaves the others out. */
+const nameOf = (c: Readonly<Creator>): BibName =>
+  Object.fromEntries(
+    Object.entries({
+      lastName: c.lastName,
+      firstName: c.firstName,
+      prefix: c.prefix,
+      suffix: c.suffix,
+      name: c.name,
+    }).filter((kv): kv is [string, string] => kv[1] !== undefined),
+  );
+
+const isText = (x: unknown): x is string => typeof x === "string";
+const isName = (x: unknown): x is Readonly<Creator> =>
+  typeof x === "object" && x !== null;
+
+/** An entry's fields and name lists, from the parser's one record of both. */
+function fieldsOf(e: Readonly<Entry>): Pick<BibEntry, "fields" | "names"> {
+  const pairs = Object.entries(e.fields);
+  const isNames = (k: string): boolean => e.mode[k] === "creatorlist";
+  return {
+    // A list field (`keywords`, `publisher`) is joined as BibTeX writes it.
+    fields: Object.fromEntries(
+      pairs
+        .filter(([k]) => !isNames(k))
+        .map(([k, v]) => [k, [v].flat().filter(isText).join(" and ")]),
+    ),
+    names: Object.fromEntries(
+      pairs
+        .filter(([k]) => isNames(k))
+        .map(([k, v]) => [k, [v].flat().filter(isName).map(nameOf)]),
+    ),
+  };
+}
+
+/** Each entry the parser read, placed in the text: found in `source` in order, `source` at `offset`. */
+function placed(
+  parsed: readonly Readonly<Entry>[],
+  source: string,
+  offset: number,
+): readonly BibEntry[] {
+  return parsed.reduce<{
+    readonly from: number;
+    readonly found: readonly BibEntry[];
+  }>(
+    (acc, e) => {
+      const at = source.indexOf(e.input, acc.from);
+      const end = at + e.input.length;
+      const span = { start: offset + at, end: offset + end };
+      const entry = { type: e.type.toLowerCase(), key: e.key, span };
+      return { from: end, found: [...acc.found, { ...entry, ...fieldsOf(e) }] };
+    },
+    { from: 0, found: [] },
+  ).found;
+}
+
+/** The entries the parser finished: one it could not keeps no text — it is malformed, and bibtex reports it. */
+const finished = (lib: Readonly<Library>): readonly Readonly<Entry>[] =>
+  lib.entries.filter((e) => e.input !== "");
+
+/** An entry as bibtex takes it; a list field (`keywords`) as one value. */
+const writtenOf = (e: Readonly<Entry>): WrittenEntry => ({
+  type: e.type.toLowerCase(),
+  key: e.key,
+  fields: Object.fromEntries(
+    Object.entries(e.fields).map(([k, v]) => [
+      k,
+      [v].flat().filter(isText).join(", "),
+    ]),
+  ),
+});
+
+/**
+ * The database in `body` of `text`, the text of the file at `path`, read with the `@string`s
+ * `inherited` in force. The parser is handed a copy of them: it writes into its own.
+ */
+function read(
+  path: AbsolutePath,
+  text: string,
+  body: Span,
+  inherited: BibStrings = {},
+): BibText {
+  const source = text.slice(body.start, body.end);
+  const lib = parse(source, { ...OPTIONS, strings: { ...inherited } });
+  const asWritten = parse(source, { ...AS_WRITTEN, strings: { ...inherited } });
+  return {
+    path,
+    text,
+    body,
+    entries: placed(finished(lib), source, body.start),
+    written: finished(asWritten).map(writtenOf),
+    preamble: lib.preamble,
+    inherited,
+    // Its own as bibtex takes them: the reading that keeps LaTeX as written.
+    strings: { ...inherited, ...asWritten.strings },
+  };
+}
+
+export const bibReader: BibReader = {
+  read,
+  readFile: (path, text, inherited) =>
+    read(path, text, { start: 0, end: text.length }, inherited),
+};

package/src/adapters/latex/filecontents.ts

@@ -0,0 +1,114 @@
+/**
+ * THE `filecontents` BLOCKS OF A SOURCE — where a `.bib` TeX wrote stands in the text that wrote it.
+ * Read from the parse tree, never decided: which file a block writes, and whether TeX ran it, is
+ * TeX's answer (`written` in `_build/sources.json`); this reader only says where each block's text
+ * is, so a finding about an entry TeX read can be shown at the block that holds it
+ * (docs/design/paper-sources.md §1).
+ *
+ * unified-latex reads a `filecontents` environment as verbatim; its option and file name are the
+ * first things in that node, white space between them — a line break too: `\begin{filecontents*}` with
+ * `{refs.bib}` on the next line writes `refs.bib` (measured with pdflatex) — and its body starts on the
+ * line after the name, as LaTeX's own reader starts it.
+ * A block is live when the tree keeps it: a comment is a node of its own, `\iffalse … \fi` is cut at
+ * parse (`conditionals.ts`), and nothing after `\end{document}` is read (`liveRoot`).
+ */
+import type * as Ast from "@unified-latex/unified-latex-types";
+import type { Filecontents } from "../../ports/latex.ts";
+import {
+  argumentPieces,
+  inPlace,
+  isNode,
+  placeOf,
+  visited,
+  type ArgumentPiece,
+  type Node,
+} from "./nodes.ts";
+import { liveRoot, parseLatex, type ParsedTex } from "./parse.ts";
+
+const FILECONTENTS: ReadonlySet<string> = new Set([
+  "filecontents",
+  "filecontents*",
+]);
+
+/** Names and options as TeX reads them: off the tree, a comma between two names. */
+type Name = readonly ArgumentPiece[];
+
+/** What a name or an option is written as: its pieces joined, white space trimmed off. */
+export const written = (name: Name): string =>
+  name
+    .map((p) => p.text)
+    .join("")
+    .trim();
+
+/** What may stand before the name: nothing, or one `[options]` — anything else is a block with no name. */
+const OPTION = /^(?:\[[^\]]*\])?$/;
+
+/** A block's head: its name's group, and its options. */
+interface Head {
+  readonly name: Node;
+  readonly options: readonly string[];
+}
+
+/** The head of a block whose text is `text`: the first group, with only white space and an option before it. */
+function headOf(text: string): Head | null {
+  const nodes = parseLatex(text).root.content;
+  const at = nodes.findIndex((x) => x.type === "group");
+  const option = written(argumentPieces(nodes.slice(0, Math.max(at, 0)), null));
+  const name = nodes[at];
+  if (name === undefined || !OPTION.test(option)) return null;
+  return {
+    name,
+    options: option
+      .replace(/^\[|\]$/g, "")
+      .split(",")
+      .map((o) => o.trim()),
+  };
+}
+
+/**
+ * One verbatim `filecontents` node as a block: its name, option, and body. unified-latex reads the
+ * whole environment as verbatim, so its text is parsed on its own and the name read off that tree like
+ * a declaration's (`headOf`). The body starts on the line after the one the name ends on; what TeX
+ * ignores after the name on that line is no body.
+ */
+export function blockOf(
+  src: string,
+  n: Readonly<Ast.VerbatimEnvironment>,
+  jobname: string,
+): readonly Filecontents[] {
+  return inPlace(placeOf(n), (span) => {
+    // The node runs from `\begin{env}` to past `\end{env}`.
+    const headAt = span.start + `\\begin{${n.env}}`.length;
+    const end = span.end - `\\end{${n.env}}`.length;
+    const head = headOf(src.slice(headAt, end));
+    if (head === null) return [];
+    return inPlace(placeOf(head.name), (named) => {
+      const after = headAt + named.end;
+      // What TeX ignores after the name, up to the end of its line.
+      const rest = src.slice(after, end).split("\n", 1).join("");
+      return [
+        {
+          writes: written(argumentPieces([head.name], jobname)),
+          overwrite: head.options.some(
+            (o) => o === "overwrite" || o === "force",
+          ),
+          span,
+          body: { start: Math.min(after + rest.length + 1, end), end },
+        },
+      ];
+    });
+  });
+}
+
+const isBlock = (n: Node): n is Readonly<Ast.VerbatimEnvironment> =>
+  n.type === "verbatim" && FILECONTENTS.has(n.env);
+
+/** Every live `filecontents` block of a source whose main file's name is `jobname`, in source order. */
+export const filecontentsOf = (
+  t: ParsedTex,
+  jobname: string,
+): readonly Filecontents[] =>
+  visited(liveRoot(t), () => false)
+    .filter(isNode)
+    .filter(isBlock)
+    .flatMap((n) => blockOf(t.src, n, jobname));

package/src/adapters/latex/includes.ts

@@ -4,6 +4,7 @@ import type { Include } from "../../domain/paper-source.ts";
 import type { Span } from "../../domain/tex-document.ts";
 import { isDefinition } from "./hidden.ts";
 import {
+  argumentPieces,
   inPlace,
   isNode,
   macroPlace,
@@ -13,7 +14,7 @@ import {
   type Macro,
   type Node,
 } from "./nodes.ts";
-import type { ParsedTex } from "./parse.ts";
+import { liveRoot, type ParsedTex } from "./parse.ts";
 
 const INCLUDE_MACROS: ReadonlyMap<string, Include["macro"]> = new Map([
   ["input", "input"],
@@ -22,15 +23,22 @@ const INCLUDE_MACROS: ReadonlyMap<string, Include["macro"]> = new Map([
 ]);
 
 /**
- * The path an include names, as written: its braced argument, or — TeX's own form, `\input name` —
- * the name up to the next space. unified-latex gives the unbraced form an argument of the first
- * token only (`sections` of `sections/a`), so the source is read for it.
+ * The path an include names: its braced argument read off the tree as TeX reads it (a comment is no
+ * part of it; a macro stays as written: nothing here expands one), or — TeX's own form, `\\input name`
+ * — the name up to the next space. unified-latex gives the unbraced form an argument of the first
+ * token only (`sections` of `sections/a`), so the source is read for that one.
  */
 function argumentText(src: string, m: Macro): string | null {
-  const start = mandatory(m)[0]?.content[0]?.position?.start.offset;
-  if (start === undefined) return null;
+  const arg = mandatory(m)[0];
+  const start = arg?.content[0]?.position?.start.offset;
+  if (arg === undefined || start === undefined) return null;
+  // The parser gives both forms `{` as their open mark; the source says which one was written.
+  if (src[start - 1] === "{")
+    return argumentPieces(arg.content, null)
+      .map((p) => p.text)
+      .join("");
   const rest = src.slice(start);
-  const stop = rest.search(src[start - 1] === "{" ? /\}/u : /[\s{}%]/u);
+  const stop = rest.search(/[\s{}%]/u);
   return stop < 0 ? rest : rest.slice(0, stop);
 }
 
@@ -44,11 +52,11 @@ function includeOf(src: string, m: Macro): readonly Include[] {
 
 /**
  * Every `\input`, `\include` and `\subfile` of the source, in source order — not in a comment (a
- * comment is a node of its own) and not in a macro definition's body, which is read where the macro
- * is used, and nothing here expands macros.
+ * comment is a node of its own), not in a macro definition's body, which is read where the macro
+ * is used, and nothing here expands macros; not after `\end{document}`, which TeX never reads.
  */
 export const includesOf = (t: ParsedTex): readonly Include[] =>
-  visited(t.root, isDefinition)
+  visited(liveRoot(t), isDefinition)
     .filter(isNode)
     .flatMap((n) => (n.type === "macro" ? includeOf(t.src, n) : []));
 

package/src/adapters/latex/index.test.ts

@@ -697,3 +697,76 @@ describe("bodyEmphasis — each style, and edge cases", () => {
     expect(e && src.slice(e.span.start, e.span.end)).toBe("\\textbf{see it}");
   });
 });
+
+describe("latexReader.filecontents — the blocks that write a file, where they stand", () => {
+  const SRC =
+    "\\documentclass{x}\n" +
+    "\\begin{filecontents*}[overwrite]{refs.bib}\n@misc{a, title={A}}\n\\end{filecontents*}\n" +
+    "\\begin{document}\n" +
+    "\\begin{filecontents}{\\jobname.bib}\n@misc{b, title={B}}\n\\end{filecontents}\n" +
+    "\\end{document}\n" +
+    "\\begin{filecontents}{late.bib}\n@misc{c}\n\\end{filecontents}\n";
+
+  it("each live block, in order: the file it writes (\\jobname expanded), [overwrite], its span and body", () => {
+    const blocks = latexReader.filecontents(SRC, "paper");
+    expect(
+      blocks.map((b) => [
+        b.writes,
+        b.overwrite,
+        SRC.slice(b.body.start, b.body.end),
+      ]),
+    ).toEqual([
+      ["refs.bib", true, "@misc{a, title={A}}\n"],
+      ["paper.bib", false, "@misc{b, title={B}}\n"],
+    ]);
+    expect(SRC.slice(blocks[0]?.span.start, blocks[0]?.span.end)).toMatch(
+      /^\\begin\{filecontents\*\}.*\\end\{filecontents\*\}$/s,
+    );
+  });
+
+  it("a block inside a comment, or after \\end{document}, is not one TeX runs", () => {
+    expect(
+      latexReader.filecontents(
+        "% \\begin{filecontents}{x.bib}\n% @misc{z}\n% \\end{filecontents}\n\\begin{document}\n\\end{document}\n",
+        "paper",
+      ),
+    ).toEqual([]);
+  });
+
+  it("a block that names no file writes none: a group after its body's first text is no name, and a body may hold none", () => {
+    expect(
+      [
+        "\\begin{filecontents}\n@misc{z}\n\\end{filecontents}\n",
+        "\\begin{filecontents}\nplain text\n\\end{filecontents}\n",
+      ].flatMap((block) =>
+        latexReader.filecontents(
+          `${block}\\begin{document}\n\\end{document}\n`,
+          "paper",
+        ),
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe("latexReader.filecontents — a file name on a line of its own", () => {
+  it("🔴 a name on the line after \\begin, the option before it or not: TeX takes it, and the body starts on the line after the name", () => {
+    // Measured with pdflatex: `\\begin{filecontents*}` then `{refs.bib}` on the next line writes
+    // refs.bib from the lines after the name (fixtures/paper-sources/v30-name-next-line).
+    const src =
+      "\\begin{filecontents*}\n{refs.bib}\n@misc{a, title={A}}\n\\end{filecontents*}\n" +
+      "\\begin{filecontents}[overwrite]\n  {two.bib}\n@misc{b}\n\\end{filecontents}\n" +
+      "\\begin{document}\n\\end{document}\n";
+    expect(
+      latexReader
+        .filecontents(src, "paper")
+        .map((b) => [
+          b.writes,
+          b.overwrite,
+          src.slice(b.body.start, b.body.end),
+        ]),
+    ).toEqual([
+      ["refs.bib", false, "@misc{a, title={A}}\n"],
+      ["two.bib", true, "@misc{b}\n"],
+    ]);
+  });
+});

package/src/adapters/latex/index.ts

@@ -33,6 +33,7 @@ import { parseLatex } from "./parse.ts";
 import { bodyEmphasis, bodyProse } from "./prose.ts";
 import { renderedRuns } from "./rendered.ts";
 import { layoutOverridesOf } from "./layout.ts";
+import { filecontentsOf } from "./filecontents.ts";
 
 export {
   documentClassOf,
@@ -69,4 +70,5 @@ export const latexReader: LatexReader = {
   template: parseTemplate,
   withDocumentClass: (src, want) => replaceDocumentClass(parseLatex(src), want),
   layoutOverrides: (src) => layoutOverridesOf(parseLatex(src)),
+  filecontents: (src, jobname) => filecontentsOf(parseLatex(src), jobname),
 };