paperlint 7.2.0 → 9.0.0

package/src/adapters/sources-record/index.test.ts

@@ -0,0 +1,87 @@
+/**
+ * The schema of `_build/sources.json`: the one text it is parsed from, and every way a file can fail to
+ * be a record of this schema — refused by name, never read as a record.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  serializeSourcesRecord,
+  type SourcesRecord,
+} from "../../domain/sources-record.ts";
+import { sourcesCodec } from "./index.ts";
+
+const parseSourcesRecord = sourcesCodec.parse;
+const A = "a".repeat(64);
+
+const RECORD: SourcesRecord = {
+  schema: 1,
+  inputs: [
+    { path: "paper.tex", role: "body" },
+    { path: "macros.tex", role: "preamble" },
+  ],
+  written: ["refs.bib"],
+  bibdata: ["refs"],
+  bibtex: {
+    ran: true,
+    databases: ["refs.bib"],
+    keys: ["k1"],
+    exit: 2,
+    errors: [{ message: "bad", file: "refs.bib", line: 4 }],
+  },
+  sha256: { "paper.tex": A, "macros.tex": null },
+};
+
+describe("parsing a sources.json", () => {
+  it("what serialize wrote parses back to the same record, and the text ends with a newline", () => {
+    const text = serializeSourcesRecord(RECORD);
+    expect(text.endsWith("}\n")).toBe(true);
+    expect(parseSourcesRecord(text)).toEqual({ ok: true, record: RECORD });
+  });
+
+  it("a build that ran no bibtex parses too", () => {
+    const record: SourcesRecord = { ...RECORD, bibtex: { ran: false } };
+    expect(parseSourcesRecord(serializeSourcesRecord(record))).toEqual({
+      ok: true,
+      record,
+    });
+  });
+
+  it("text that is not JSON is refused by name", () => {
+    expect(parseSourcesRecord("{")).toEqual({
+      ok: false,
+      why: "sources.json is not JSON",
+    });
+  });
+
+  it("another schema number is refused by name, not read as this one", () => {
+    expect(parseSourcesRecord('{"schema":2}')).toEqual({
+      ok: false,
+      why: "sources.json is schema 2, this paperlint reads schema 1",
+    });
+    expect(parseSourcesRecord("[]")).toEqual({
+      ok: false,
+      why: "sources.json is schema unknown, this paperlint reads schema 1",
+    });
+    expect(parseSourcesRecord('{"schema":"1"}')).toEqual({
+      ok: false,
+      why: "sources.json is schema unknown, this paperlint reads schema 1",
+    });
+  });
+
+  it("a record of this schema that is not shaped like one names where", () => {
+    const bad = (patch: object): string => {
+      const r = parseSourcesRecord(JSON.stringify({ ...RECORD, ...patch }));
+      return r.ok ? "accepted" : r.why;
+    };
+    expect(bad({ inputs: "paper.tex" })).toContain("inputs");
+    expect(bad({ sha256: { "paper.tex": "not a digest" } })).toContain(
+      "sha256.paper.tex",
+    );
+    expect(bad({ bibtex: { ran: "yes" } })).toContain("bibtex");
+    expect(bad({ inputs: [{ path: "a.tex", role: "main" }] })).toContain(
+      "inputs.0.role",
+    );
+    expect(parseSourcesRecord(JSON.stringify({ schema: 1 }))).toMatchObject({
+      ok: false,
+    });
+  });
+});

package/src/adapters/sources-record/index.ts

@@ -0,0 +1,82 @@
+/**
+ * The schema of `_build/sources.json` — the one place its shape is checked (docs/design/paper-sources.md
+ * §1). The text is parsed once, here, into the domain's `SourcesRecord`; whatever reads a record after
+ * it never re-validates. A record of another schema number is refused by name, not read as this one.
+ */
+import { z } from "zod";
+import {
+  SOURCES_FILE,
+  SOURCES_SCHEMA,
+  type ParsedRecord,
+} from "../../domain/sources-record.ts";
+import type { SourcesCodec } from "../../ports/sources-codec.ts";
+
+const SHA256 = /^[0-9a-f]{64}$/;
+
+const bibtexError = z.object({
+  message: z.string(),
+  file: z.string(),
+  line: z.number().int().nullable(),
+});
+
+const recordSchema = z.object({
+  schema: z.literal(SOURCES_SCHEMA),
+  inputs: z.array(
+    z.object({ path: z.string(), role: z.enum(["preamble", "body"]) }),
+  ),
+  written: z.array(z.string()),
+  bibdata: z.array(z.string()),
+  bibtex: z.discriminatedUnion("ran", [
+    z.object({ ran: z.literal(false) }),
+    z.object({
+      ran: z.literal(true),
+      databases: z.array(z.string()),
+      keys: z.array(z.string()),
+      exit: z.number().int(),
+      errors: z.array(bibtexError),
+    }),
+  ]),
+  sha256: z.record(z.string(), z.string().regex(SHA256).nullable()),
+});
+
+/** The JSON `text` holds, or undefined when it is not JSON. */
+function jsonOf(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/** The `schema` field of a parsed file, whatever it holds, or undefined when there is none. */
+const schemaOf = (json: unknown): unknown =>
+  typeof json === "object" && json !== null && "schema" in json
+    ? json.schema
+    : undefined;
+
+/**
+ * A `sources.json`'s text, parsed once at the boundary: the record, or the one reason it is not one.
+ * A record of another schema number is refused by name, not read as this one.
+ */
+export function parseSourcesRecord(text: string): ParsedRecord {
+  const json = jsonOf(text);
+  if (json === undefined)
+    return { ok: false, why: `${SOURCES_FILE} is not JSON` };
+  const schema = schemaOf(json);
+  if (schema !== SOURCES_SCHEMA)
+    return {
+      ok: false,
+      why: `${SOURCES_FILE} is schema ${typeof schema === "number" ? String(schema) : "unknown"}, this paperlint reads schema ${String(SOURCES_SCHEMA)}`,
+    };
+  const parsed = recordSchema.safeParse(json);
+  if (parsed.success) return { ok: true, record: parsed.data };
+  const issues = parsed.error.issues.map(
+    (i) => `${i.path.join(".")} ${i.message}`,
+  );
+  return {
+    ok: false,
+    why: `${SOURCES_FILE} does not match schema ${String(SOURCES_SCHEMA)}: ${issues.join("; ")}`,
+  };
+}
+
+export const sourcesCodec: SourcesCodec = { parse: parseSourcesRecord };

package/src/adapters/tex-output/blg.ts

@@ -0,0 +1,27 @@
+/**
+ * The errors in bibtex's log (`paper.blg`). bibtex ends an error with the place it was reading —
+ * `---line 4 of file refs.bib`, or `---while reading file paper.aux` when it names no line — and a
+ * warning with a single dash (`--line 1 of file x.bib`), so the three dashes are the whole grammar.
+ * The message is what stands before them on the line, or, when they start the line, the line before.
+ */
+import type { BibtexError } from "../../domain/sources-record.ts";
+
+const PLACE = /^(.*?)---(?:line (\d+) of file|while reading file) (.+)$/;
+const LINE_NUMBER = /---line (\d+) of file/;
+
+export function parseBlgErrors(blg: string): readonly BibtexError[] {
+  const rows = blg.split(/\r?\n/);
+  return rows.flatMap((row, i): readonly BibtexError[] => {
+    const m = PLACE.exec(row);
+    if (m === null) return [];
+    const [, before = "", , file = ""] = m;
+    const line = LINE_NUMBER.exec(row)?.[1];
+    return [
+      {
+        message: (before === "" ? (rows[i - 1] ?? "") : before).trim(),
+        file: file.trim(),
+        line: line === undefined ? null : Number(line),
+      },
+    ];
+  });
+}

package/src/adapters/tex-output/fls.ts

@@ -0,0 +1,24 @@
+/**
+ * pdflatex's `-recorder` file (`paper.fls`): one line per file TeX opened — `INPUT <path>` to read
+ * it, `OUTPUT <path>` to write it — in the order TeX opened them, and a `PWD <dir>` line first. The
+ * format has no quoting: a path is the rest of its line.
+ */
+import type { Fls, FlsLine } from "../../domain/tex-run.ts";
+
+const OPS = ["INPUT", "OUTPUT"] as const;
+
+/** `INPUT a.tex` → the line; anything else (`PWD …`, a blank, a word with no path) → none. */
+function lineOf(raw: string): readonly FlsLine[] {
+  const op = OPS.find((o) => raw.startsWith(`${o} `));
+  const path = op === undefined ? "" : raw.slice(op.length + 1).trimEnd();
+  return op === undefined || path === "" ? [] : [{ op, path }];
+}
+
+export function parseFls(text: string): Fls {
+  const rows = text.split(/\r?\n/);
+  const pwd = rows.find((r) => r.startsWith("PWD "));
+  return {
+    pwd: pwd === undefined ? null : pwd.slice("PWD ".length).trimEnd(),
+    lines: rows.flatMap(lineOf),
+  };
+}

package/src/adapters/tex-output/index.test.ts

@@ -0,0 +1,171 @@
+/**
+ * The readers of what TeX writes beside a paper — `.fls` (pdflatex `-recorder`) and the errors in
+ * bibtex's `.blg` — on files captured whole from real runs of the planted papers in
+ * `fixtures/paper-sources/` (test/fixtures/tex-output/README.md), not on text written for the test.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { texOutput } from "./index.ts";
+
+const CAPTURES = join(
+  dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url))))),
+  "test",
+  "fixtures",
+  "tex-output",
+);
+const capture = (paper: string, file: string): string =>
+  readFileSync(join(CAPTURES, paper, file), "utf8");
+
+/** The lines that name a file of the paper: not the TeX tree's (absolute) files. */
+const ofPaper = (text: string) =>
+  texOutput.fls(text).lines.filter((l) => !l.path.startsWith("/"));
+
+describe("the .fls reader", () => {
+  it("reads every INPUT and OUTPUT line in order, and the directory pdflatex ran in", () => {
+    const fls = texOutput.fls(capture("v8-jobname", "paper.fls"));
+    expect(fls.pwd).toBe("/work/paper");
+    expect(fls.lines.filter((l) => !l.path.startsWith("/"))).toEqual([
+      { op: "INPUT", path: "paper.tex" },
+      { op: "OUTPUT", path: "paper.log" },
+      { op: "INPUT", path: "./paper.bib" },
+      { op: "INPUT", path: "paper.bib" },
+      { op: "OUTPUT", path: "paper.bib" },
+      { op: "INPUT", path: "./paper.aux" },
+      { op: "INPUT", path: "./paper.aux" },
+      { op: "INPUT", path: "paper.aux" },
+      { op: "OUTPUT", path: "paper.aux" },
+      { op: "INPUT", path: "./paper.bbl" },
+      { op: "INPUT", path: "./paper.bbl" },
+      { op: "INPUT", path: "paper.bbl" },
+      { op: "OUTPUT", path: "paper.pdf" },
+      { op: "INPUT", path: "paper.aux" },
+    ]);
+  });
+
+  it("keeps the TeX tree's files too, as the absolute paths TeX opened", () => {
+    const fls = texOutput.fls(capture("v3-declared", "paper.fls"));
+    expect(fls.lines.slice(0, 4)).toEqual([
+      { op: "INPUT", path: "/usr/share/texlive/texmf.cnf" },
+      { op: "INPUT", path: "/usr/share/texlive/texmf-dist/web2c/texmf.cnf" },
+      {
+        op: "INPUT",
+        path: "/usr/share/texlive/texmf-var/web2c/pdftex/pdflatex.fmt",
+      },
+      { op: "INPUT", path: "paper.tex" },
+    ]);
+  });
+});
+
+describe("the .fls reader, on the shapes of a real run", () => {
+  it("a file in a folder keeps its folder; a first pass has no .aux to read yet; a block over a .bib that is already there writes nothing", () => {
+    expect(ofPaper(capture("p1", "first-pass.fls"))).toEqual([
+      { op: "INPUT", path: "paper.tex" },
+      { op: "OUTPUT", path: "paper.log" },
+      { op: "INPUT", path: "./refs.bib" },
+      { op: "INPUT", path: "refs.bib" },
+      { op: "OUTPUT", path: "paper.aux" },
+      { op: "INPUT", path: "./sections/intro.tex" },
+      { op: "INPUT", path: "./sections/intro.tex" },
+      { op: "INPUT", path: "./sections/intro.tex" },
+      { op: "INPUT", path: "./sections/intro.tex" },
+      { op: "INPUT", path: "sections/intro.tex" },
+      { op: "OUTPUT", path: "paper.pdf" },
+      { op: "INPUT", path: "paper.aux" },
+    ]);
+  });
+
+  it("a path with a space is the whole rest of the line; text that is not a line of the format is skipped", () => {
+    expect(
+      texOutput.fls(
+        "PWD /a b/p\nINPUT my file.tex\nOUTPUT out dir/x.aux\nsomething else\nINPUT\n",
+      ),
+    ).toEqual({
+      pwd: "/a b/p",
+      lines: [
+        { op: "INPUT", path: "my file.tex" },
+        { op: "OUTPUT", path: "out dir/x.aux" },
+      ],
+    });
+  });
+
+  it("an .fls with no PWD line has no directory", () => {
+    expect(texOutput.fls("INPUT paper.tex\n")).toEqual({
+      pwd: null,
+      lines: [{ op: "INPUT", path: "paper.tex" }],
+    });
+  });
+});
+
+describe("the .blg error reader", () => {
+  it("a run that ends well reports none, warnings included", () => {
+    expect(texOutput.blgErrors(capture("v3-declared", "paper.blg"))).toEqual(
+      [],
+    );
+    expect(
+      texOutput.blgErrors(
+        "Database file #1: x.bib\nWarning--I'm ignoring a's extra \"year\" field\n--line 1 of file x.bib\n",
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe("the .blg error reader, on what real runs reported", () => {
+  it("an entry never closed: the message before the dashes, the file and the line after", () => {
+    expect(texOutput.blgErrors(capture("v6-unclosed", "paper.blg"))).toEqual([
+      {
+        message: "I was expecting a `,' or a `}'",
+        file: "refs.bib",
+        line: 4,
+      },
+    ]);
+  });
+
+  it("a second \\bibdata command is an error in the .aux", () => {
+    expect(
+      texOutput.blgErrors(capture("v9-two-bibliographies", "paper.blg")),
+    ).toEqual([
+      {
+        message: "Illegal, another \\bibdata command",
+        file: "paper.aux",
+        line: 5,
+      },
+    ]);
+  });
+
+  it("dashes on the first line of the log have no message before them", () => {
+    expect(texOutput.blgErrors("---line 1 of file paper.aux\n")).toEqual([
+      { message: "", file: "paper.aux", line: 1 },
+    ]);
+  });
+
+  it("a message on the line before its dashes, and an error with no line", () => {
+    expect(
+      texOutput.blgErrors(
+        [
+          "The style file: plain.bst",
+          "I couldn't open database file paper.bib",
+          "---line 4 of file paper.aux",
+          " : \\bibdata{paper",
+          " :               }",
+          "I'm skipping whatever remains of this command",
+          "I found no database files---while reading file paper.aux",
+          'Warning--I didn\'t find a database entry for "declared2023"',
+          "(There were 2 error messages)",
+        ].join("\n"),
+      ),
+    ).toEqual([
+      {
+        message: "I couldn't open database file paper.bib",
+        file: "paper.aux",
+        line: 4,
+      },
+      {
+        message: "I found no database files",
+        file: "paper.aux",
+        line: null,
+      },
+    ]);
+  });
+});

package/src/adapters/tex-output/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The readers of what TeX writes beside a paper: pdflatex's `-recorder` file and bibtex's errors.
+ * One implementation of `TexOutput` (`src/ports/tex-output.ts`).
+ */
+import type { TexOutput } from "../../ports/tex-output.ts";
+import { parseBlgErrors } from "./blg.ts";
+import { parseFls } from "./fls.ts";
+
+export const texOutput: TexOutput = {
+  fls: parseFls,
+  blgErrors: parseBlgErrors,
+};