paperlint 4.0.0 → 4.2.0

package/src/adapters/latex/nodes.ts

@@ -0,0 +1,150 @@
+/** What the three readers share about unified-latex nodes: places, text, and the walk. */
+import type * as Ast from "@unified-latex/unified-latex-types";
+import { CONTINUE, SKIP, visit } from "@unified-latex/unified-latex-util-visit";
+import type { Place, Span } from "../../domain/tex-document.ts";
+import { KEY_SIGNATURES } from "./parse.ts";
+
+export { collapse } from "../../domain/tex-document.ts";
+
+/** unified-latex's node types, read-only: nothing here writes to a tree. */
+export type Node = Readonly<Ast.Node>;
+export type Macro = Readonly<Ast.Macro>;
+export type Argument = Readonly<Ast.Argument>;
+
+/** Anything the parser may have given a position: offsets of its first and past its last character. */
+interface Positioned {
+  readonly position?: {
+    readonly start: { readonly offset: number };
+    readonly end: { readonly offset: number };
+  };
+}
+
+/** Where a node stands, or that it has no position. */
+export const placeOf = (n: Positioned): Place =>
+  n.position === undefined
+    ? { kind: "unplaced" }
+    : {
+        kind: "at",
+        span: { start: n.position.start.offset, end: n.position.end.offset },
+      };
+
+/** What `f` makes of a place's span, or nothing for a node the parser gave no position. */
+export const inPlace = <T>(
+  p: Place,
+  f: (span: Span) => readonly T[],
+): readonly T[] => (p.kind === "at" ? f(p.span) : []);
+
+/** A macro's arguments, in order: none when the parser attached none. */
+export const argumentsOf = (m: Macro): readonly Argument[] => m.args ?? [];
+
+/** The first mandatory (`{…}`) and optional (`[…]`) arguments' contents, and the last mandatory one's. */
+export const mandatory = (m: Macro): readonly Argument[] =>
+  argumentsOf(m).filter((a) => a.openMark === "{");
+export const optional = (m: Macro): Argument | undefined =>
+  argumentsOf(m).find((a) => a.openMark === "[");
+
+/** What a string node reads as: itself, except a tie (`~`), which is a space the reader sees. */
+export const stringText = (content: string): string =>
+  content === "~" ? " " : content;
+
+/** Which of a macro's mandatory arguments it typesets: one of them, or none at all. */
+type Shown =
+  | { readonly kind: "argument"; readonly at: number }
+  | { readonly kind: "none" };
+
+const LAST: Shown = { kind: "argument", at: -1 };
+const NONE: Shown = { kind: "none" };
+
+/**
+ * Macros that do not typeset their last mandatory argument, as data. `\texorpdfstring{shown}{bookmark}`
+ * typesets the first; a declaration (`\color{red}`, `\fontsize{10}{12}`, `\vspace{1em}`,
+ * `\setlength{\x}{0pt}`) typesets none. Every other macro typesets its last (`\textcolor{red}{x}`,
+ * `\colorbox{yellow}{x}`, `\href{url}{x}`).
+ */
+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,
+  ),
+]);
+
+/** The text a (non-key) macro typesets: see `SHOWN_ARGUMENT`. */
+function shownText(m: Macro): string {
+  const shown = SHOWN_ARGUMENT.get(m.content) ?? LAST;
+  return shown.kind === "none"
+    ? ""
+    : textOf(mandatory(m).at(shown.at)?.content);
+}
+
+/**
+ * The text of a node list with markup dropped: strings, spaces, what groups hold, and the argument a
+ * formatting macro typesets — its last mandatory one (`\textbf{Usage}`, `\textcolor{red}{Usage}`,
+ * `\href{url}{Usage}` → `Usage`) unless `SHOWN_ARGUMENT` says otherwise. A key macro's arguments
+ * (`\label{…}`, `\cite{…}`) are not text.
+ */
+export const textOf = (nodes: readonly Node[] | undefined): string =>
+  (nodes ?? [])
+    .map((n) => {
+      if (n.type === "string") return stringText(n.content);
+      if (n.type === "whitespace" || n.type === "parbreak") return " ";
+      if (n.type === "group") return textOf(n.content);
+      return n.type === "macro" && !(n.content in KEY_SIGNATURES)
+        ? shownText(n)
+        : "";
+    })
+    .join("");
+
+/**
+ * A macro's place with its arguments: from its name to past the closing mark of the last argument
+ * that holds text. unified-latex positions the name and the arguments' contents, never the
+ * arguments themselves, so an empty trailing argument is not covered.
+ */
+export function macroPlace(m: Macro): Place {
+  const name = placeOf(m);
+  if (name.kind === "unplaced") return name;
+  const end = (m.args ?? []).reduce((e, a) => {
+    const last = a.content.at(-1)?.position?.end.offset;
+    return last === undefined ? e : last + a.closeMark.length;
+  }, name.span.end);
+  const span: Span = { start: name.span.start, end };
+  return { kind: "at", span };
+}
+
+/** What visit reaches: a node, an argument, or a node list (a content array, an argument list). */
+export type Visited = Readonly<Ast.Ast> | readonly (Node | Argument)[];
+
+/**
+ * Everything visit reaches under `tree`, in document order, node lists included; `skip` prunes what
+ * it is given (a node or an argument, with the node that holds it) and everything under it. visit
+ * reports through a callback and returns nothing, so the one collection point of this adapter is here.
+ */
+export function visited(
+  // eslint-disable-next-line functional/prefer-immutable-types -- visit's own parameter type is mutable
+  tree: Ast.Ast,
+  skip: (v: Visited, parent: Visited | undefined) => boolean,
+): readonly Visited[] {
+  // eslint-disable-next-line functional/prefer-immutable-types -- the one accumulator, see above
+  const seen: Visited[] = [];
+  visit(
+    tree,
+    (node, info) => {
+      // eslint-disable-next-line functional/immutable-data -- visit is callback-only; see above
+      seen.push(node);
+      return skip(node, info.parents[0]) ? SKIP : CONTINUE;
+    },
+    { includeArrays: true },
+  );
+  return seen;
+}
+
+/** A node list visit reached. `Array.isArray` alone does not narrow a readonly array. */
+export const isList = (v: Visited): v is readonly (Node | Argument)[] =>
+  Array.isArray(v);
+
+/** A macro's argument, as visit reports it. */
+export const isArgument = (v: Visited): v is Argument =>
+  !isList(v) && v.type === "argument";
+
+/** A node, as opposed to a node list or an argument (which visit also reports). */
+export const isNode = (v: Visited): v is Node =>
+  !isList(v) && v.type !== "argument" && v.type !== "root";

package/src/adapters/latex/outline.ts

@@ -0,0 +1,64 @@
+/** The document's sections, where its back matter starts, and where it ends. */
+import type * as Ast from "@unified-latex/unified-latex-types";
+import { isDefined } from "remeda";
+import type { Heading, Outline } from "../../domain/tex-document.ts";
+import {
+  collapse,
+  isNode,
+  macroPlace,
+  mandatory,
+  textOf,
+  visited,
+  type Macro,
+  type Node,
+} from "./nodes.ts";
+import { isDefinition, isUnrendered } from "./hidden.ts";
+import type { ParsedTex } from "./parse.ts";
+
+/** Macros and the environment that start the back matter: the appendix and the bibliography. */
+const BACK_MATTER_MACROS: ReadonlySet<string> = new Set([
+  "appendix",
+  "bibliography",
+  "printbibliography",
+]);
+
+const isBackMatter = (n: Node): boolean =>
+  (n.type === "macro" && BACK_MATTER_MACROS.has(n.content)) ||
+  (n.type === "environment" && n.env === "thebibliography");
+
+const isSection = (n: Node): n is Macro =>
+  n.type === "macro" && n.content === "section";
+
+const isDocument = (n: Node): n is Readonly<Ast.Environment> =>
+  n.type === "environment" && n.env === "document";
+
+/** One `\section`/`\section*`: the last mandatory argument is its title. */
+const headingOf = (m: Macro): Heading => ({
+  title: collapse(textOf(mandatory(m).at(-1)?.content)),
+  place: macroPlace(m),
+});
+
+/**
+ * The body's `\section`s (starred or not) in document order, the first back-matter node, and the
+ * end of the document. A source with no `document` environment is read whole, as a fragment. What
+ * the PDF never shows is pruned (`isUnrendered`), and so is a macro definition's body
+ * (`isDefinition`): a heading in a comment environment or in a definition is not a section.
+ */
+export function outlineOf(t: ParsedTex): Outline {
+  const doc = t.root.content.find(isDocument);
+  const nodes = visited(
+    doc?.content ?? t.root.content,
+    (v, parent) => isUnrendered(v, parent) || isDefinition(v),
+  ).filter(isNode);
+  const backMatter =
+    nodes
+      .filter(isBackMatter)
+      .map((n) => n.position?.start.offset)
+      .filter(isDefined)[0] ?? null;
+  const docEnd = doc?.position?.end.offset;
+  return {
+    sections: nodes.filter(isSection).map(headingOf),
+    backMatter,
+    end: docEnd === undefined ? null : docEnd - 1,
+  };
+}

package/src/adapters/latex/parse.ts

@@ -0,0 +1,137 @@
+/**
+ * A LaTeX source → its unified-latex tree, as one `ParsedTex` that keeps the two together.
+ *
+ * ── CITATION KEYS ARE ARGUMENTS, NOT TEXT ────────────────────────────────────────
+ * unified-latex attaches arguments only to macros it has a signature for. natbib's and biblatex's
+ * citation commands have none, so `\citep{aisec2025}` came back with its key as a separate group —
+ * readable as prose. `KEY_SIGNATURES` declares them, and the other macros whose arguments name a
+ * file, a label or a URL rather than say something, so their arguments are attached and the
+ * rendered text skips them structurally. `\href` says something in one argument and names a URL in
+ * the other, so it is signed too, and `KEY_ARGUMENT` says which of its arguments is not text.
+ */
+import type * as Ast from "@unified-latex/unified-latex-types";
+import { getParser } from "@unified-latex/unified-latex-util-parse";
+import { once } from "remeda";
+
+const signed = (
+  names: readonly string[],
+  signature: string,
+): readonly (readonly [string, { readonly signature: string }])[] =>
+  names.map((m) => [m, { signature }] as const);
+
+/** Citation commands: their `{…}` argument is a key, their `[…]` ones are notes the reader sees. */
+export const CITATION_MACROS: ReadonlySet<string> = new Set([
+  "cite",
+  "citep",
+  "citet",
+  "citealp",
+  "citealt",
+  "citeauthor",
+  "citeyear",
+  "citeyearpar",
+  "Citep",
+  "Citet",
+  "nocite",
+  "parencite",
+  "textcite",
+  "autocite",
+  "footcite",
+]);
+
+/** Macros whose arguments are keys, labels, files or URLs — never text a reader sees. */
+export const KEY_SIGNATURES: Readonly<
+  Record<string, { readonly signature: string }>
+> = Object.fromEntries([
+  ...signed([...CITATION_MACROS], "o o m"),
+  ...signed(
+    [
+      "label",
+      "ref",
+      "eqref",
+      "pageref",
+      "autoref",
+      "cref",
+      "Cref",
+      "url",
+      "input",
+      "include",
+      "subfile",
+      "bibliography",
+      "bibliographystyle",
+      "addbibresource",
+    ],
+    "m",
+  ),
+  ...signed(["includegraphics"], "s o o m"),
+  ...signed(["usepackage", "RequirePackage", "documentclass"], "o m o"),
+]);
+
+/**
+ * Macros that print some arguments and not others: the index of the one argument that is a key or
+ * a URL. A citation (`o o m`) prints its `[…]` notes, not its `{…}` key; `\href` (`m m`) prints its
+ * link text, not its URL.
+ */
+export const KEY_ARGUMENT: ReadonlyMap<string, number> = new Map([
+  ...[...CITATION_MACROS].map((m) => [m, 2] as const),
+  ["href", 0],
+]);
+
+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"));
+
+/**
+ * Macros that define other macros or environments. A heading in a body is no section where it is
+ * written, so the outline skips these; the rendered text reads a body as written, since nothing here
+ * expands macros. `\def` and its kin get a signature so the name and the body attach to them; a
+ * parameter text (`\def\x#1{…}`) is not modelled.
+ */
+export const DEFINITION_MACROS: ReadonlySet<string> = new Set([
+  "newcommand",
+  "renewcommand",
+  "providecommand",
+  "DeclareRobustCommand",
+  "newenvironment",
+  "renewenvironment",
+  "def",
+  "gdef",
+  "edef",
+  "xdef",
+]);
+
+const DEF_SIGNATURES = Object.fromEntries(
+  signed(["def", "gdef", "edef", "xdef"], "m m"),
+);
+
+// Not exported: a `ParsedTex` carries this property, and the one way to write it is `parseLatex`.
+const PARSED = Symbol("ParsedTex");
+
+/** A source and ITS tree: only `parseLatex` makes one, so a tree cannot be paired with another source. */
+export interface ParsedTex {
+  readonly src: string;
+  readonly root: Ast.Root;
+  readonly [PARSED]: true;
+}
+
+/** One parser for the process, made on first use: building one compiles its grammar. */
+const parser = once(() =>
+  getParser({
+    macros: {
+      ...KEY_SIGNATURES,
+      ...LINK_SIGNATURES,
+      ...DECLARATION_SIGNATURES,
+      ...DEF_SIGNATURES,
+    },
+  }),
+);
+
+/** A LaTeX source → its tree. */
+export const parseLatex = (src: string): ParsedTex => ({
+  src,
+  root: parser().parse(src),
+  [PARSED]: true,
+});