paperlint 4.0.0 → 4.1.0

package/src/adapters/latex/document-class.ts

@@ -0,0 +1,147 @@
+/** The paper's `\documentclass`, a preset's template, and setting a class in a source. */
+import {
+  documentClassLine,
+  venueClass,
+  type ClassLine,
+  type DocumentClass,
+} from "../../domain/tex-document.ts";
+import {
+  collapse,
+  macroPlace,
+  mandatory,
+  optional,
+  textOf,
+  type Node,
+  type Macro,
+} from "./nodes.ts";
+import { parseLatex, type ParsedTex } from "./parse.ts";
+
+const isDocumentClass = (n: Node): n is Macro =>
+  n.type === "macro" && n.content === "documentclass";
+
+const isComma = (n: Node): boolean => n.type === "string" && n.content === ",";
+
+/** Nodes split wherever `at` holds, the separators dropped: a comma inside braces is its group's. */
+function splitWhere(
+  nodes: readonly Node[],
+  at: (n: Node) => boolean,
+): readonly (readonly Node[])[] {
+  const cuts = nodes.flatMap((n, i) => (at(n) ? [i] : []));
+  return [-1, ...cuts].map((from, k) =>
+    nodes.slice(from + 1, cuts[k] ?? nodes.length),
+  );
+}
+
+/** The source text a run of nodes spans; its markup-free text if unplaced. */
+function sourceOf(src: string, nodes: readonly Node[]): string {
+  const start = nodes[0]?.position?.start.offset;
+  const end = nodes.at(-1)?.position?.end.offset;
+  return start === undefined || end === undefined
+    ? textOf(nodes)
+    : src.slice(start, end);
+}
+
+/**
+ * One option as TeX reads it, whitespace collapsed. A line comment is not part of it, and it joins
+ * its two sides with no space: `foo=bar% note⏎baz` is `foo=barbaz`.
+ */
+const optionText = (src: string, part: readonly Node[]): string =>
+  collapse(
+    splitWhere(part, (n) => n.type === "comment")
+      .map((run) => sourceOf(src, run))
+      .join(""),
+  );
+
+const classNode = (t: ParsedTex): Macro | undefined =>
+  t.root.content.find(isDocumentClass);
+
+/** A `\documentclass` node as a class line: empty, or the class with its options as read. */
+function classLine(src: string, node: Macro): ClassLine {
+  const place = macroPlace(node);
+  const cls = collapse(textOf(mandatory(node)[0]?.content));
+  if (cls === "") return { kind: "empty", place };
+  const options = splitWhere(optional(node)?.content ?? [], isComma)
+    .map((part) => optionText(src, part))
+    .filter(Boolean);
+  return { kind: "class", cls, options, place };
+}
+
+/**
+ * The first `\documentclass` at the top of the tree: missing; empty (`\documentclass{}`); or the
+ * class with each of its options as written (`foo={a,b}` stays one option, braces kept), whitespace
+ * collapsed. Its place spans the macro and its arguments.
+ */
+export function documentClassOf(t: ParsedTex): ClassLine {
+  const node = classNode(t);
+  return node === undefined ? { kind: "missing" } : classLine(t.src, node);
+}
+
+/**
+ * A preset's `template` → the class it names: a whole `\documentclass[…]{…}` line, or a bare class
+ * name (`article`), which names no option. Anything else is null.
+ */
+export function parseTemplate(text: string): DocumentClass | null {
+  const t = parseLatex(text);
+  const [only, ...rest] = t.root.content.filter(
+    (n) => n.type !== "whitespace" && n.type !== "comment",
+  );
+  if (only === undefined || rest.length > 0) return null;
+  const line = documentClassOf(t);
+  if (line.kind === "class") return { cls: line.cls, options: line.options };
+  return only.type === "string" ? { cls: only.content, options: [] } : null;
+}
+
+/** `src` with `text` in place of `[from, to)`. */
+const splice = (src: string, from: number, to: number, text: string): string =>
+  src.slice(0, from) + text + src.slice(to);
+
+/**
+ * `options` written into the class line's own source: before the `]` of its `[…]` — right after the
+ * last node inside, or right after the `[` when there is none — or as a new `[…]` after the name.
+ * The bytes between `[` and `]` stay as the author wrote them, comments and braces included.
+ */
+function addOptions(
+  src: string,
+  node: Macro,
+  line: { readonly start: number; readonly empty: boolean },
+  options: readonly string[],
+): string {
+  const list = options.join(",");
+  const nameEnd = line.start + 1 + node.content.length; // `\` and the macro's name
+  const opt = optional(node);
+  if (opt === undefined) return splice(src, nameEnd, nameEnd, `[${list}]`);
+  const close =
+    opt.content.at(-1)?.position?.end.offset ?? src.indexOf("[", nameEnd) + 1;
+  return splice(src, close, close, line.empty ? list : `,${list}`);
+}
+
+/**
+ * The source with its `\documentclass` line changed to satisfy `want` (see `venueClass`): another
+ * class is replaced by the template's line; the same class gains the options it lacks in place. A
+ * source whose class already satisfies `want`, or that has no class line the parser could place, is
+ * returned as it is.
+ */
+export function replaceDocumentClass(
+  t: ParsedTex,
+  want: DocumentClass,
+): string {
+  const node = classNode(t);
+  if (node === undefined) return t.src;
+  const line = classLine(t.src, node);
+  if (line.kind !== "class" || line.place.kind === "unplaced") return t.src;
+  const { start, end } = line.place.span;
+  const change = venueClass(line, want);
+  switch (change.kind) {
+    case "keep":
+      return t.src;
+    case "replace":
+      return splice(t.src, start, end, documentClassLine(change.by));
+    case "add":
+      return addOptions(
+        t.src,
+        node,
+        { start, empty: line.options.length === 0 },
+        change.options,
+      );
+  }
+}

package/src/adapters/latex/hidden.ts

@@ -0,0 +1,70 @@
+/**
+ * What a reader of the PDF never sees, as a walk over the tree prunes it: comments, math and code,
+ * the bibliography's body, and the arguments that are keys, labels, files or URLs. The rendered
+ * text and the outline both prune with it.
+ *
+ * A macro definition's body is NOT pruned here. It is text once the macro is used, and nothing here
+ * expands macros, so the rendered text reads the body where it is written — a definition naming
+ * another venue is a leftover whether it is used or not. The outline prunes it on top
+ * (`isDefinition`): a heading in a definition body is not a section where it is written.
+ */
+import {
+  isArgument,
+  isNode,
+  type Argument,
+  type Node,
+  type Visited,
+} from "./nodes.ts";
+import { DEFINITION_MACROS, KEY_ARGUMENT, KEY_SIGNATURES } from "./parse.ts";
+
+/** Environments whose body is not text a reader sees as prose: code, the bibliography, comments. */
+const HIDDEN_ENVS: ReadonlySet<string> = new Set([
+  "thebibliography",
+  "verbatim",
+  "Verbatim",
+  "lstlisting",
+  "minted",
+  "comment",
+]);
+
+/** Node types a reader does not see as prose: comments, code, math. */
+const HIDDEN_TYPES: ReadonlySet<Node["type"]> = new Set<Node["type"]>([
+  "comment",
+  "verbatim",
+  "verb",
+  "inlinemath",
+  "displaymath",
+  "mathenv",
+]);
+
+const KEY_MACROS: ReadonlySet<string> = new Set(Object.keys(KEY_SIGNATURES));
+
+/** A key macro that prints none of its arguments (`\label`, `\url`, …). */
+const isHiddenMacro = (name: string): boolean =>
+  KEY_MACROS.has(name) && !KEY_ARGUMENT.has(name);
+
+const isHiddenNode = (n: Node): boolean =>
+  HIDDEN_TYPES.has(n.type) ||
+  (n.type === "environment" && HIDDEN_ENVS.has(n.env)) ||
+  (n.type === "macro" && isHiddenMacro(n.content));
+
+/**
+ * The one argument of a partly printed macro (`KEY_ARGUMENT`) that is a key or a URL. What holds an
+ * argument is a macro or an environment; the first three tests only narrow the type.
+ */
+const isKeyArgument = (a: Argument, parent: Visited | undefined): boolean =>
+  parent !== undefined &&
+  isNode(parent) &&
+  parent.type === "macro" &&
+  parent.args?.indexOf(a) === KEY_ARGUMENT.get(parent.content);
+
+/** Whether the walk prunes `v` (given the node that holds it): see the module comment. */
+export const isUnrendered = (
+  v: Visited,
+  parent: Visited | undefined,
+): boolean =>
+  isArgument(v) ? isKeyArgument(v, parent) : isNode(v) && isHiddenNode(v);
+
+/** A macro that defines another macro or an environment (`\newcommand`, `\def`, …). */
+export const isDefinition = (v: Visited): boolean =>
+  isNode(v) && v.type === "macro" && DEFINITION_MACROS.has(v.content);

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

@@ -0,0 +1,361 @@
+/**
+ * The LaTeX adapter on real parses: the class line in each of its states, a preset's template, the
+ * class `paperlint new` writes, the outline, and the rendered text. Trees come only from
+ * `parseLatex`; the one helper that reads a node's position is tested on the shapes a position can
+ * take.
+ */
+import type * as Ast from "@unified-latex/unified-latex-types";
+import { describe, expect, it } from "vitest";
+import { runText, spanIn } from "../../domain/tex-document.ts";
+import {
+  documentClassOf,
+  latexReader,
+  macroPlace,
+  mandatory,
+  optional,
+  outlineOf,
+  parseLatex,
+  parseTemplate,
+  placeOf,
+  renderedRuns,
+  replaceDocumentClass,
+  textOf,
+} from "./index.ts";
+
+const IEEE = { cls: "IEEEtran", options: ["conference", "compsoc"] };
+
+describe("documentClassOf — the class line's three states", () => {
+  it("a class: each option whitespace-collapsed, and the span of the whole macro, arguments included", () => {
+    const src = "% x\n\\documentclass[ conference ,\n compsoc]{IEEEtran}\n";
+    expect(documentClassOf(parseLatex(src))).toEqual({
+      kind: "class",
+      cls: "IEEEtran",
+      options: ["conference", "compsoc"],
+      place: {
+        kind: "at",
+        span: { start: 4, end: src.indexOf("}") + 1 },
+      },
+    });
+  });
+
+  it("🔴 empty: \\documentclass{} names no class, and stands where it stands — not missing", () => {
+    expect(documentClassOf(parseLatex("%\n\\documentclass{}\n"))).toEqual({
+      kind: "empty",
+      place: { kind: "at", span: { start: 2, end: 16 } },
+    });
+  });
+
+  it("missing: no \\documentclass at the top of the tree", () => {
+    expect(
+      documentClassOf(parseLatex("\\begin{document}\\end{document}")),
+    ).toEqual({ kind: "missing" });
+  });
+
+  it("a group in the class name and a paragraph break are read as text", () => {
+    const line = documentClassOf(parseLatex("\\documentclass{{IEEE}\n\ntran}"));
+    expect(line.kind === "class" && line.cls).toBe("IEEE tran");
+  });
+});
+
+describe("placeOf / macroPlace — a node the parser gave no position is unplaced, never offset 0", () => {
+  const at = (start: number, end: number) => ({
+    start: { offset: start, line: 1, column: start + 1 },
+    end: { offset: end, line: 1, column: end + 1 },
+  });
+  it("placeOf: a position is a span; none is unplaced", () => {
+    expect(placeOf({ position: at(3, 7) })).toEqual({
+      kind: "at",
+      span: { start: 3, end: 7 },
+    });
+    expect(placeOf({})).toEqual({ kind: "unplaced" });
+  });
+
+  it("macroPlace: unplaced without a position; with one, to past the last argument that holds text", () => {
+    const bare: Ast.Macro = { type: "macro", content: "documentclass" };
+    expect(macroPlace(bare)).toEqual({ kind: "unplaced" });
+    const withArgs: Ast.Macro = {
+      type: "macro",
+      content: "section",
+      position: at(0, 8),
+      args: [
+        { type: "argument", content: [], openMark: "", closeMark: "" },
+        {
+          type: "argument",
+          content: [{ type: "string", content: "A", position: at(9, 10) }],
+          openMark: "{",
+          closeMark: "}",
+        },
+        { type: "argument", content: [], openMark: "[", closeMark: "]" },
+      ],
+    };
+    expect(macroPlace(withArgs)).toEqual({
+      kind: "at",
+      span: { start: 0, end: 11 },
+    });
+  });
+});
+
+describe("a macro with no arguments, and markup in a name", () => {
+  const bare: Ast.Macro = { type: "macro", content: "foo" };
+  it("has no mandatory or optional arguments, and its place is its name", () => {
+    expect(mandatory(bare)).toEqual([]);
+    expect(optional(bare)).toBe(undefined);
+    expect(
+      macroPlace({
+        ...bare,
+        position: {
+          start: { offset: 2, line: 1, column: 3 },
+          end: { offset: 6, line: 1, column: 7 },
+        },
+      }),
+    ).toEqual({ kind: "at", span: { start: 2, end: 6 } });
+  });
+
+  it("textOf drops markup it cannot read as text, and reads nothing as empty", () => {
+    expect(textOf([bare, { type: "string", content: "x" }])).toBe("x");
+    expect(textOf(undefined)).toBe("");
+  });
+});
+
+describe("parseTemplate — a preset's template", () => {
+  it.each<[string, { cls: string; options: string[] } | null]>([
+    ["\\documentclass[conference,compsoc]{IEEEtran}", IEEE],
+    ["article", { cls: "article", options: [] }],
+    [" acmart\n", { cls: "acmart", options: [] }],
+    ["two words", null],
+    ["% c\n\\documentclass{article}\n", { cls: "article", options: [] }],
+    ["\\documentclass{article} trailing", null],
+    ["\\documentclass[a]{}", null],
+    ["", null],
+  ])("%j → %j", (text, want) => {
+    expect(parseTemplate(text)).toEqual(want);
+  });
+});
+
+const replaced = (src: string) => replaceDocumentClass(parseLatex(src), IEEE);
+
+describe("replaceDocumentClass — the class `paperlint new` writes", () => {
+  it("replaces the whole line, arguments included, and keeps everything around it", () => {
+    expect(replaced("% c\n\\documentclass[11pt]{article}\n\\title{x}\n")).toBe(
+      "% c\n\\documentclass[conference,compsoc]{IEEEtran}\n\\title{x}\n",
+    );
+  });
+
+  it("a class that already satisfies the template keeps the author's own options", () => {
+    const src = "\\documentclass[compsoc,conference,a4paper]{IEEEtran}\nx";
+    expect(replaced(src)).toBe(src);
+  });
+
+  it("the right class missing a required option keeps the author's options and adds the missing ones", () => {
+    expect(
+      replaced("\\documentclass[review,anonymous,conference]{IEEEtran}\nx"),
+    ).toBe("\\documentclass[review,anonymous,conference,compsoc]{IEEEtran}\nx");
+  });
+
+  it("an option with a braced value keeps its braces, its commas and its spacing", () => {
+    expect(replaced("\\documentclass[review, foo={a,b}]{IEEEtran}\nx")).toBe(
+      "\\documentclass[review, foo={a,b},conference,compsoc]{IEEEtran}\nx",
+    );
+  });
+
+  it("no class, or an empty one, is returned as it is", () => {
+    expect(replaced("just text")).toBe("just text");
+    expect(replaced("\\documentclass{}\nx")).toBe("\\documentclass{}\nx");
+  });
+
+  it("the port does the same over a source", () => {
+    expect(
+      latexReader.withDocumentClass("\\documentclass{article}", IEEE),
+    ).toBe("\\documentclass[conference,compsoc]{IEEEtran}");
+  });
+});
+
+describe("replaceDocumentClass — missing options are added in place, the author's bytes kept", () => {
+  it("🔴 the missing options go before the `]`: the author's bytes, a comment included, stay as written", () => {
+    expect(replaced("\\documentclass[foo=bar% note\nbaz]{IEEEtran}\nx")).toBe(
+      "\\documentclass[foo=bar% note\nbaz,conference,compsoc]{IEEEtran}\nx",
+    );
+    const acm = "\\documentclass[review,% reason\nanonymous]{acmart}\nx";
+    expect(
+      replaceDocumentClass(parseLatex(acm), {
+        cls: "acmart",
+        options: ["sigconf"],
+      }),
+    ).toBe("\\documentclass[review,% reason\nanonymous,sigconf]{acmart}\nx");
+  });
+
+  it("a trailing comment in the options: the missing ones go on the next line, before the `]`", () => {
+    expect(replaced("\\documentclass[review% c\n]{IEEEtran}")).toBe(
+      "\\documentclass[review% c\n,conference,compsoc]{IEEEtran}",
+    );
+  });
+
+  it("no options, an empty `[]`, a blank `[ ]`: the options are written without a stray comma", () => {
+    expect(replaced("\\documentclass{IEEEtran}\nx")).toBe(
+      "\\documentclass[conference,compsoc]{IEEEtran}\nx",
+    );
+    expect(replaced("\\documentclass[]{IEEEtran}")).toBe(
+      "\\documentclass[conference,compsoc]{IEEEtran}",
+    );
+    expect(replaced("\\documentclass[ ]{IEEEtran}")).toBe(
+      "\\documentclass[ conference,compsoc]{IEEEtran}",
+    );
+  });
+
+  it("reading the options: a line comment joins its two sides with no space, as TeX does", () => {
+    const read = (src: string) => {
+      const line = documentClassOf(parseLatex(src));
+      return line.kind === "class" && line.options;
+    };
+    expect(read("\\documentclass[review,% reason\nanonymous]{acmart}")).toEqual(
+      ["review", "anonymous"],
+    );
+    expect(read("\\documentclass[foo=bar% note\nbaz]{IEEEtran}")).toEqual([
+      "foo=barbaz",
+    ]);
+  });
+});
+
+describe("outlineOf — a heading's title", () => {
+  it("keeps the text of formatting macros and drops keys such as a label", () => {
+    const o = outlineOf(
+      parseLatex("\\section*{LLM \\textbf{Usage} Statement\\label{s:llm}}"),
+    );
+    expect(o.sections.map((h) => h.title)).toEqual(["LLM Usage Statement"]);
+  });
+});
+
+describe("outlineOf — a formatting macro's text is its last mandatory argument", () => {
+  it.each<[string, string]>([
+    [
+      "\\section*{\\textcolor{red}{LLM Usage Statement}}",
+      "LLM Usage Statement",
+    ],
+    [
+      "\\section*{LLM \\emph{Usage} \\textbf{Statement}}",
+      "LLM Usage Statement",
+    ],
+    ["\\section*{See \\href{https://x.org}{the site}}", "See the site"],
+    [
+      "\\section*{\\texorpdfstring{LLM Usage Statement}{Short}}",
+      "LLM Usage Statement",
+    ],
+    ["\\section*{\\color{red}LLM Usage Statement}", "LLM Usage Statement"],
+    ["\\section*{LLM~Usage~Statement}", "LLM Usage Statement"],
+    [
+      "\\section*{\\colorbox{yellow}{LLM Usage} Statement}",
+      "LLM Usage Statement",
+    ],
+    [
+      "\\section*{\\fontsize{10}{12}\\selectfont LLM \\vspace{1em}Usage\\hspace{2pt} Statement}",
+      "LLM Usage Statement",
+    ],
+    [
+      "\\section*{\\setlength{\\parskip}{0pt}\\addtolength{\\parskip}{1pt}LLM Usage Statement}",
+      "LLM Usage Statement",
+    ],
+  ])("%s → %s", (src, title) => {
+    expect(outlineOf(parseLatex(src)).sections.map((h) => h.title)).toEqual([
+      title,
+    ]);
+  });
+});
+
+describe("outlineOf", () => {
+  it("sections in order with titles collapsed, the first back matter, and the document's end", () => {
+    const src =
+      "\\documentclass{article}\\section{Pre}\n\\begin{document}\n\\section{A  B}\n" +
+      "\\section*{C}\n\\appendix\n\\section{D}\n\\bibliography{r}\n\\end{document}";
+    const o = outlineOf(parseLatex(src));
+    expect(o.sections.map((h) => h.title)).toEqual(["A B", "C", "D"]);
+    expect(o.backMatter).toBe(src.indexOf("\\appendix"));
+    expect(o.end).toBe(src.length - 1);
+    const [a] = o.sections;
+    expect(
+      a?.place.kind === "at" && src.slice(a.place.span.start, a.place.span.end),
+    ).toBe("\\section{A  B}");
+  });
+
+  it("a bibliography environment is back matter too; a fragment has no end; no back matter is null", () => {
+    const src = "\\section{A}\\begin{thebibliography}{1}\\end{thebibliography}";
+    expect(latexReader.outline(src)).toMatchObject({
+      backMatter: src.indexOf("\\begin"),
+      end: null,
+    });
+    expect(latexReader.outline("\\section{A}").backMatter).toBe(null);
+  });
+});
+
+describe("outlineOf — a heading that is never rendered is not in the outline", () => {
+  it.each<[string, string]>([
+    [
+      "a comment environment",
+      "\\begin{comment}\\section{Hidden}\\end{comment}",
+    ],
+    ["a \\newcommand body", "\\newcommand{\\x}{\\section{Hidden}}"],
+    ["a \\def body", "\\def\\y{\\section{Hidden}}"],
+    ["a \\newenvironment body", "\\newenvironment{e}{\\section{Hidden}}{}"],
+  ])("%s", (_, hidden) => {
+    const src = `\\begin{document}${hidden}\\section{Real}\\end{document}`;
+    expect(outlineOf(parseLatex(src)).sections.map((h) => h.title)).toEqual([
+      "Real",
+    ]);
+  });
+});
+
+describe("renderedRuns", () => {
+  it("runs of strings and spaces, each character mapped to its source offset", () => {
+    const src = "A~B \\emph{C D}\n\n E";
+    const runs = renderedRuns(parseLatex(src));
+    expect(runs.map(runText)).toEqual(["A B ", "C D", " E"]);
+    const [first] = runs;
+    expect(first && spanIn(first, 2, 3)).toEqual({ start: 2, end: 3 });
+  });
+
+  it("comments, math, code, keys and the bibliography are not text a reader sees", () => {
+    const src =
+      "x % AISec\n$AISec$ \\cite{AISec} \\label{AISec} \\url{https://AISec.cc}\n" +
+      "\\begin{verbatim}AISec\\end{verbatim}\\begin{thebibliography}{1}\\bibitem{a} AISec\\end{thebibliography}";
+    expect(
+      latexReader
+        .renderedRuns(src)
+        .map(runText)
+        .some((t) => t.includes("AISec")),
+    ).toBe(false);
+  });
+
+  it("a citation's key is hidden, its notes in square brackets are text", () => {
+    const runs = latexReader
+      .renderedRuns("x \\citep[Presented at AISec][p.~3]{zzkey} y")
+      .map(runText);
+    expect(runs.some((t) => t.includes("Presented at AISec"))).toBe(true);
+    expect(runs.some((t) => t.includes("zzkey"))).toBe(false);
+  });
+
+  it("\\href: its URL is hidden, its link text is text", () => {
+    const runs = latexReader
+      .renderedRuns("x \\href{https://example.org/AISec}{the zzlink text} y")
+      .map(runText);
+    expect(runs.some((t) => t.includes("AISec"))).toBe(false);
+    expect(runs.some((t) => t.includes("the zzlink text"))).toBe(true);
+  });
+
+  it("a macro definition's body is read like prose: the rule does not expand macros", () => {
+    const src =
+      "\\newcommand{\\oldvenue}{AISec} \\renewcommand\\b{BISec} \\def\\c{CISec} x";
+    const text = latexReader.renderedRuns(src).map(runText).join("|");
+    expect(
+      ["AISec", "BISec", "CISec", "x"].filter((w) => text.includes(w)),
+    ).toEqual(["AISec", "BISec", "CISec", "x"]);
+  });
+
+  it("the options of other key macros stay hidden: they are settings, not prose", () => {
+    const src = "\\includegraphics[AISec]{f} \\usepackage[AISec]{p}";
+    expect(
+      latexReader
+        .renderedRuns(src)
+        .map(runText)
+        .some((t) => t.includes("AISec")),
+    ).toBe(false);
+  });
+});

package/src/adapters/latex/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Reads a paper.tex and answers three questions — checks nothing itself: `documentClassOf` (which
+ * class, with which options, and where), `outlineOf` (the sections in order, where the back matter
+ * starts, where the document ends) and `renderedRuns` (the text a reader sees, each character with
+ * its source offset). Used by `tex/template`, `tex/required-section`, `tex/venue-leftover` and
+ * `paperlint new`, through the `LatexReader` port (`src/ports/latex.ts`); `src/cli.ts` wires it.
+ *
+ * ── WHY THE PARSE TREE AND NOT THE `tex/latex` PROJECTION ────────────────────────
+ * The ESLint language's projection (`eslint-rules/latex-language.ts`) blanks the preamble,
+ * `\documentclass`, `\author` and every other macro in its OPAQUE list, because prose rules must
+ * not see markup. These questions are about exactly that markup: the class line, a `\section*`
+ * title, an `\institution{…}` in the author block. So the source is parsed here with unified-latex,
+ * the parser the language already uses.
+ *
+ * ── STATES, NOT NULL ─────────────────────────────────────────────────────────────
+ * A class line is missing, empty or a class; a node the parser gave no position is `unplaced`, not
+ * offset 0; a run of text is a non-empty list of contiguous segments, and a range outside it has
+ * no span (`spanIn` in `src/domain/tex-document.ts`). A tree travels only with its own source
+ * (`ParsedTex`, minted by `parseLatex` alone).
+ */
+import type { LatexReader } from "../../ports/latex.ts";
+import {
+  documentClassOf,
+  parseTemplate,
+  replaceDocumentClass,
+} from "./document-class.ts";
+import { outlineOf } from "./outline.ts";
+import { parseLatex } from "./parse.ts";
+import { renderedRuns } from "./rendered.ts";
+
+export {
+  documentClassOf,
+  parseTemplate,
+  replaceDocumentClass,
+} from "./document-class.ts";
+export {
+  collapse,
+  macroPlace,
+  mandatory,
+  optional,
+  placeOf,
+  textOf,
+} from "./nodes.ts";
+export { outlineOf } from "./outline.ts";
+export { parseLatex, type ParsedTex } from "./parse.ts";
+export { renderedRuns } from "./rendered.ts";
+
+/** The `LatexReader` port over unified-latex: each call parses its source once. */
+export const latexReader: LatexReader = {
+  documentClass: (src) => documentClassOf(parseLatex(src)),
+  outline: (src) => outlineOf(parseLatex(src)),
+  renderedRuns: (src) => renderedRuns(parseLatex(src)),
+  template: parseTemplate,
+  withDocumentClass: (src, want) => replaceDocumentClass(parseLatex(src), want),
+};