paperlint 4.1.0 → 4.2.0

package/src/domain/paper-source.test.ts

@@ -0,0 +1,156 @@
+/**
+ * The paper as one text: includes spliced where they stand, every character mapped back to its
+ * file, a missing file reported, a subfile's body only, and a file that includes itself entered once.
+ * The reader is a stand-in that finds `\input{…}` by position, so these tests are about assembling,
+ * not about parsing LaTeX (the LaTeX adapter's own tests cover `includes`).
+ */
+import { describe, expect, it } from "vitest";
+import {
+  assemblePaper,
+  originOf,
+  type AssembleDeps,
+  type Include,
+} from "./paper-source.ts";
+
+/** `\input{x}` / `\include{x}` / `\subfile{x}` in `src`, by a scan good enough for these inputs. */
+const includes = (src: string): readonly Include[] =>
+  [...src.matchAll(/\\(input|include|subfile)\{([^}]*)\}/gu)].map((m) => ({
+    macro:
+      m[1] === "subfile" ? "subfile" : m[1] === "include" ? "include" : "input",
+    target: m[2] ?? "",
+    span: { start: m.index, end: m.index + m[0].length },
+  }));
+
+const deps = (files: Record<string, string>): AssembleDeps => ({
+  includes,
+  documentBody: (src) => {
+    const a = src.indexOf("\\begin{document}");
+    const b = src.indexOf("\\end{document}");
+    return a < 0 || b < 0
+      ? null
+      : { start: a + "\\begin{document}".length, end: b };
+  },
+  read: (p) => files[p] ?? null,
+});
+
+describe("assemblePaper — the text TeX reads", () => {
+  it("splices each file where its include stands; `.tex` is tried first", () => {
+    const main = "A\\input{s/one}B\\include{two.tex}C";
+    const p = assemblePaper(
+      "paper.tex",
+      main,
+      deps({ "s/one.tex": "one", "two.tex": "two" }),
+    );
+    expect(p.text).toBe("AoneBtwoC");
+    expect(p.missing).toEqual([]);
+    expect([...new Set(p.segments.map((g) => g.file))]).toEqual([
+      "paper.tex",
+      "s/one.tex",
+      "two.tex",
+    ]);
+  });
+
+  it("nested includes resolve from the paper directory, and map back through the outermost include", () => {
+    const main = "x\\input{a}y";
+    const p = assemblePaper(
+      "paper.tex",
+      main,
+      deps({ "a.tex": "[\\input{s/b}]", "s/b.tex": "BB" }),
+    );
+    expect(p.text).toBe("x[BB]y");
+    expect(originOf(p, { start: 2, end: 4 })).toEqual({
+      file: "s/b.tex",
+      source: "BB",
+      span: { start: 0, end: 2 },
+      via: { start: 1, end: 10 },
+    });
+  });
+
+  it("🔴 a missing file is reported where it stands, and left out", () => {
+    const main = "a\\input{gone}b";
+    const p = assemblePaper("paper.tex", main, deps({}));
+    expect(p.text).toBe("ab");
+    expect(p.missing).toEqual([
+      {
+        file: "paper.tex",
+        target: "gone",
+        span: { start: 1, end: 13 },
+        via: { start: 1, end: 13 },
+      },
+    ]);
+  });
+});
+
+describe("assemblePaper — subfiles and a file that includes itself", () => {
+  it("a subfile contributes its document body, not its preamble", () => {
+    const sub =
+      "\\documentclass[paper]{subfiles}\\begin{document}BODY\\end{document}";
+    const p = assemblePaper(
+      "paper.tex",
+      "<\\subfile{s}>",
+      deps({ "s.tex": sub }),
+    );
+    expect(p.text).toBe("<BODY>");
+  });
+
+  it("a subfile with no document environment is read whole", () => {
+    const p = assemblePaper(
+      "paper.tex",
+      "<\\subfile{s}>",
+      deps({ "s.tex": "ALL" }),
+    );
+    expect(p.text).toBe("<ALL>");
+  });
+
+  it("a file that includes itself is entered once", () => {
+    const p = assemblePaper(
+      "paper.tex",
+      "m\\input{a}",
+      deps({ "a.tex": "a\\input{a}\\input{paper.tex}" }),
+    );
+    expect(p.text).toBe("ma");
+  });
+});
+
+describe("originOf — where a span of the assembled text comes from", () => {
+  const p = assemblePaper(
+    "paper.tex",
+    "ab\\input{x}cd",
+    deps({ "x.tex": "XYZ" }),
+  );
+
+  it("in the main file: its own offsets, via nothing", () => {
+    expect(originOf(p, { start: 0, end: 2 })).toEqual({
+      file: "paper.tex",
+      source: "ab\\input{x}cd",
+      span: { start: 0, end: 2 },
+      via: null,
+    });
+  });
+
+  it("after the include: offsets in the main file past the macro", () => {
+    expect(originOf(p, { start: 5, end: 7 })).toEqual({
+      file: "paper.tex",
+      source: "ab\\input{x}cd",
+      span: { start: 11, end: 13 },
+      via: null,
+    });
+  });
+
+  it("a span running out of an included file is cut at its end", () => {
+    expect(originOf(p, { start: 3, end: 7 })).toEqual({
+      file: "x.tex",
+      source: "XYZ",
+      span: { start: 1, end: 3 },
+      via: { start: 2, end: 11 },
+    });
+  });
+
+  it("an empty span at the very end belongs to the last stretch; outside the text there is none", () => {
+    expect(originOf(p, { start: 7, end: 7 })?.span).toEqual({
+      start: 13,
+      end: 13,
+    });
+    expect(originOf(p, { start: 9, end: 9 })).toBe(null);
+  });
+});

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 reported and left out; 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/ports/latex.ts

@@ -2,10 +2,13 @@
  * What paperlint needs from a LaTeX source, shaped by its rules and `paperlint new` — not by the
  * parser. The one implementation is `src/adapters/latex/` (unified-latex); `src/cli.ts` wires it.
  */
+import type { Include } from "../domain/paper-source.ts";
 import type {
   ClassLine,
   DocumentClass,
   Outline,
+  Passage,
+  Span,
   TextRun,
 } from "../domain/tex-document.ts";
 
@@ -16,6 +19,16 @@ export interface LatexReader {
   readonly outline: (src: string) => Outline;
   /** The text a reader sees: prose, the author block, footnotes — not comments, keys, math, code. */
   readonly renderedRuns: (src: string) => readonly TextRun[];
+  /**
+   * The body's prose, as passages a sentence cannot cross: from the start of the document (the
+   * abstract included) to the appendix or the bibliography, without headings, captions, floats,
+   * code or the title block. Citations, links and cross-references stay in place as marks.
+   */
+  readonly bodyProse: (src: string) => readonly Passage[];
+  /** Every `\input`, `\include` and `\subfile`, in source order: the path as written, where it stands. */
+  readonly includes: (src: string) => readonly Include[];
+  /** The span of the `document` environment's body, or null when the source has none. */
+  readonly documentBody: (src: string) => Span | null;
   /**
    * A preset's `template` → the class it names: a whole `\documentclass[…]{…}` line, or a bare
    * class name (no option). Null for anything else.