paperlint 4.0.0 → 4.2.0

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

@@ -0,0 +1,155 @@
+/** The paper's `\documentclass`, a preset's template, and setting a class in a source. */
+import {
+  documentClassLine,
+  venueClass,
+  type ClassCandidate,
+  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(""),
+  );
+
+/** Every `\documentclass` at the top of the tree, in source order. */
+const classNodes = (t: ParsedTex): readonly Macro[] =>
+  t.root.content.filter(isDocumentClass);
+
+/** A `\documentclass` node as a class line: empty, or the class with its options as read. */
+function classLine(src: string, node: Macro): ClassCandidate {
+  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 `\documentclass` at the top of the tree: missing; empty (`\documentclass{}`); the class with
+ * each of its options as written (`foo={a,b}` stays one option, braces kept), whitespace collapsed,
+ * its place spanning the macro and its arguments; or, when there are several (behind a TeX switch),
+ * each of them as a candidate.
+ */
+export function documentClassOf(t: ParsedTex): ClassLine {
+  const lines = classNodes(t).map((n) => classLine(t.src, n));
+  const [first, second, ...rest] = lines;
+  if (first === undefined) return { kind: "missing" };
+  return second === undefined
+    ? first
+    : { kind: "ambiguous", candidates: [first, second, ...rest] };
+}
+
+/**
+ * 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`, that has no class line the parser could place, or
+ * that has several, is returned as it is.
+ */
+export function replaceDocumentClass(
+  t: ParsedTex,
+  want: DocumentClass,
+): string {
+  // Several lines behind a switch: which one builds is not known, so none is rewritten.
+  const [node, ...others] = classNodes(t);
+  if (node === undefined || others.length > 0) 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/includes.ts

@@ -0,0 +1,66 @@
+/** The files a source pulls in, and the body of a source that is a document of its own. */
+import type * as Ast from "@unified-latex/unified-latex-types";
+import type { Include } from "../../domain/paper-source.ts";
+import type { Span } from "../../domain/tex-document.ts";
+import { isDefinition } from "./hidden.ts";
+import {
+  inPlace,
+  isNode,
+  macroPlace,
+  mandatory,
+  placeOf,
+  visited,
+  type Macro,
+  type Node,
+} from "./nodes.ts";
+import type { ParsedTex } from "./parse.ts";
+
+const INCLUDE_MACROS: ReadonlyMap<string, Include["macro"]> = new Map([
+  ["input", "input"],
+  ["include", "include"],
+  ["subfile", "subfile"],
+]);
+
+/**
+ * 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.
+ */
+function argumentText(src: string, m: Macro): string | null {
+  const start = mandatory(m)[0]?.content[0]?.position?.start.offset;
+  if (start === undefined) return null;
+  const rest = src.slice(start);
+  const stop = rest.search(src[start - 1] === "{" ? /\}/u : /[\s{}%]/u);
+  return stop < 0 ? rest : rest.slice(0, stop);
+}
+
+/** One include macro as an `Include`, or nothing when it names no file or has no place. */
+function includeOf(src: string, m: Macro): readonly Include[] {
+  const macro = INCLUDE_MACROS.get(m.content);
+  const target = argumentText(src, m);
+  if (macro === undefined || target === null || target.trim() === "") return [];
+  return inPlace(macroPlace(m), (span) => [{ macro, target, span }]);
+}
+
+/**
+ * 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.
+ */
+export const includesOf = (t: ParsedTex): readonly Include[] =>
+  visited(t.root, isDefinition)
+    .filter(isNode)
+    .flatMap((n) => (n.type === "macro" ? includeOf(t.src, n) : []));
+
+const isDocument = (n: Node): n is Readonly<Ast.Environment> =>
+  n.type === "environment" && n.env === "document";
+
+/** The span of the `document` environment's body, or null when the source has none. */
+export const documentBodyOf = (t: ParsedTex): Span | null =>
+  (t.root.content.find(isDocument)?.content ?? [])
+    .flatMap((n) => inPlace(placeOf(n), (span) => [span]))
+    .reduce<Span | null>(
+      (body, span) =>
+        body === null ? span : { start: body.start, end: span.end },
+      null,
+    );