paperlint 4.0.0 → 4.2.0

package/src/tex-paper.test.ts

@@ -0,0 +1,131 @@
+/**
+ * `tex/missing-input` and the reading every parse-tree rule shares (`readPaper`): an include that
+ * names no file is reported where it stands in `paper.tex`, once, whether `paper.tex` wrote it or a
+ * file it includes did; an include that resolves says nothing.
+ */
+import { describe, expect, it } from "vitest";
+import { latexReader } from "./adapters/latex/index.ts";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import { missingInputRule, readPaper, reportInPaper } from "./tex-paper.ts";
+
+const doc = (body: string): string =>
+  `\\documentclass{article}\n\\begin{document}\n${body}\n\\end{document}\n`;
+
+/** What the rule reports over `/p/paper.tex` holding `src`, with `files` on disk. */
+function run(src: string, files: Record<string, string> = {}) {
+  const out: { line: number; messageId: string; data: unknown }[] = [];
+  const rule = missingInputRule({
+    files: memoryFiles(files),
+    latex: latexReader,
+  });
+  rule
+    .create({
+      filename: "/p/paper.tex",
+      sourceCode: {
+        text: src,
+        getLocFromIndex: (i) => ({
+          line: src.slice(0, i).split("\n").length,
+          column: 0,
+        }),
+      },
+      report: (d) => {
+        if ("messageId" in d)
+          out.push({
+            line: d.loc.start.line,
+            messageId: d.messageId,
+            data: d.data,
+          });
+      },
+    })
+    .root?.();
+  return out;
+}
+
+describe("tex/missing-input", () => {
+  it("an \\input naming no file is reported at its line, naming the target", () => {
+    expect(run(doc("Text.\n\\input{sections/gone}"))).toEqual([
+      {
+        line: 4,
+        messageId: "missing",
+        data: { target: "sections/gone", file: "paper.tex" },
+      },
+    ]);
+  });
+
+  it("one missing in an included file is reported at the include that brought that file in", () => {
+    expect(run(doc("\\input{a}"), { "/p/a.tex": "A\n\\input{b}\n" })).toEqual([
+      { line: 3, messageId: "missingIn", data: { target: "b", file: "a.tex" } },
+    ]);
+  });
+
+  it("silent when every include resolves, with `.tex` added or not", () => {
+    expect(
+      run(doc("\\input{a}\\include{b.tex}"), {
+        "/p/a.tex": "A",
+        "/p/b.tex": "B",
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("readPaper — the paper as the rules read it", () => {
+  it("reads includes from the paper's own directory", () => {
+    const p = readPaper("/p/paper.tex", "x\\input{s/a}y", {
+      files: memoryFiles({ "/p/s/a.tex": "AAA" }),
+      latex: latexReader,
+    });
+    expect(p.text).toBe("xAAAy");
+    expect(p.main).toBe("paper.tex");
+  });
+});
+
+describe("reportInPaper — where a finding of the assembled text is reported", () => {
+  const paper = readPaper("/p/paper.tex", "x\n\\input{a}\ny", {
+    files: memoryFiles({ "/p/a.tex": "one\ntwo" }),
+    latex: latexReader,
+  });
+  const report = (
+    at: { start: number; end: number } | null,
+    messageId = "m",
+  ) => {
+    const out: unknown[] = [];
+    reportInPaper(
+      {
+        filename: "/p/paper.tex",
+        sourceCode: {
+          text: "",
+          getLocFromIndex: (i) => ({ line: i, column: 0 }),
+        },
+        report: (d) =>
+          out.push(
+            "messageId" in d
+              ? { at: d.loc.start.line, id: d.messageId }
+              : { at: d.loc.start.line, message: d.message },
+          ),
+      },
+      { m: "said {{w}}" },
+      paper,
+      [{ messageId, data: { w: "so" }, at }],
+    );
+    return out;
+  };
+
+  it("in the main file: at its own place, by its id", () => {
+    expect(report({ start: 0, end: 1 })).toEqual([{ at: 0, id: "m" }]);
+  });
+
+  it("in an included file: at the include, the file, line and column in front of the filled message", () => {
+    // "x\n" then "one\ntwo": offset 6 is the `t` of `two`, line 2 column 1 of a.tex.
+    expect(report({ start: 6, end: 9 })).toEqual([
+      { at: 2, message: "a.tex:2:1: said so" },
+    ]);
+  });
+
+  it("no place, or a place outside the text: the top of the file; an unknown id is printed as itself", () => {
+    expect(report(null)).toEqual([{ at: 0, id: "m" }]);
+    expect(report({ start: 99, end: 99 })).toEqual([{ at: 0, id: "m" }]);
+    expect(report({ start: 6, end: 9 }, "unknown")).toEqual([
+      { at: 2, message: "a.tex:2:1: unknown" },
+    ]);
+  });
+});

package/src/tex-paper.ts

@@ -0,0 +1,152 @@
+/**
+ * THE PAPER, NOT ITS MAIN FILE — what every rule over the LaTeX parse tree reads, and how it reports.
+ *
+ * `readPaper` gives a rule `paper.tex` with every `\input`, `\include` and `\subfile` spliced in, the
+ * way TeX reads it (`assemblePaper`, src/domain/paper-source.ts). `reportInPaper` puts each finding
+ * back where its text came from: a finding in `paper.tex` at its own place; a finding in an included
+ * file at the include in `paper.tex` that brought it in — the one place ESLint can point to in this
+ * file — with the included file, line and column at the front of the message.
+ *
+ *   tex/missing-input  warn  an `\input`, `\include` or `\subfile` names a file that is not there
+ *
+ * A missing file is a finding, not a silent skip: the rules would otherwise report a clean body for
+ * text they never read, and TeX stops on it too. Warn, not error: a file a build step writes (a
+ * table of generated numbers) is legitimately absent before that step has run.
+ */
+import { basename, dirname, join } from "node:path";
+import {
+  assemblePaper,
+  originOf,
+  type PaperSource,
+} from "./domain/paper-source.ts";
+import type { Span } from "./domain/tex-document.ts";
+import type { LatexReader } from "./ports/latex.ts";
+import type { Files } from "./ports/files.ts";
+import { callerPath } from "./caller-path.ts";
+import type {
+  Located,
+  TexRuleContext,
+  TexRuleModule,
+} from "./tex-venue-rules.ts";
+
+/** What reading a paper needs: the disk, and the LaTeX reader. */
+export interface PaperDeps {
+  readonly files: Files;
+  readonly latex: LatexReader;
+}
+
+/** The paper whose main file is `filename` with the text `src`, its includes spliced. */
+export function readPaper(
+  filename: string,
+  src: string,
+  deps: PaperDeps,
+): PaperSource {
+  const dir = dirname(filename);
+  return assemblePaper(basename(filename), src, {
+    includes: deps.latex.includes,
+    documentBody: deps.latex.documentBody,
+    read: (rel) => {
+      const b = deps.files.readBytes(callerPath(join(dir, rel)));
+      return b === null ? null : new TextDecoder().decode(b);
+    },
+  });
+}
+
+/** Line and column (1-based) of an offset in a text. */
+function lineColumn(text: string, at: number): string {
+  const line = text.slice(0, at).split("\n").length;
+  const column = at - text.lastIndexOf("\n", at - 1);
+  return `${String(line)}:${String(column)}`;
+}
+
+/** A message template with its data filled in, the way ESLint fills it. */
+const filled = (
+  template: string,
+  data: Readonly<Record<string, string | number>> = {},
+): string =>
+  Object.entries(data).reduce(
+    (m, [k, v]) => m.replaceAll(`{{${k}}}`, String(v)),
+    template,
+  );
+
+/** Where a finding stands in the main file, and — when its text came from another file — which. */
+interface Placed {
+  readonly at: Span | null;
+  readonly from: string | null;
+}
+
+/** A finding's span of the assembled text, as a place in the main file. */
+function placed(paper: PaperSource, at: Span | null): Placed {
+  const origin = at === null ? null : originOf(paper, at);
+  if (origin === null) return { at: null, from: null };
+  if (origin.file === paper.main) return { at: origin.span, from: null };
+  return {
+    at: origin.via,
+    from: `${origin.file}:${lineColumn(origin.source, origin.span.start)}`,
+  };
+}
+
+/**
+ * Each finding reported in the main file: at its own place, or at the include that brought its text
+ * in, named in the message (`sections/results.tex:12:3: …`). Offsets are the assembled text's.
+ */
+export function reportInPaper(
+  context: TexRuleContext,
+  messages: Readonly<Record<string, string>>,
+  paper: PaperSource,
+  findings: readonly Located[],
+): void {
+  const loc = (i: number) => context.sourceCode.getLocFromIndex(i);
+  findings.forEach((f) => {
+    const p = placed(paper, f.at);
+    const where = {
+      start: loc(p.at?.start ?? 0),
+      end: loc(p.at?.end ?? 0),
+    };
+    if (p.from === null)
+      context.report({ loc: where, messageId: f.messageId, data: f.data });
+    else
+      context.report({
+        loc: where,
+        // A message id the rule does not define is printed as itself rather than dropped.
+        message: `${p.from}: ${filled(messages[f.messageId] ?? f.messageId, f.data)}`,
+      });
+  });
+}
+
+const MISSING_META: TexRuleModule["meta"] = {
+  type: "problem",
+  docs: {
+    description:
+      "an \\input, \\include or \\subfile names a file that is not there, so no rule read its text",
+    url: "https://github.com/zernie/paperlint/blob/main/docs/rules/tex/missing-input.md",
+  },
+  schema: [],
+  messages: {
+    missing:
+      "`{{target}}` is not there (tried `{{target}}.tex` and `{{target}}`, from the paper's directory): TeX stops on it, and no rule read what it should hold",
+    missingIn:
+      "`{{target}}`, which {{file}} includes, is not there (tried `{{target}}.tex` and `{{target}}`, from the paper's directory): TeX stops on it, and no rule read what it should hold",
+  },
+};
+
+/** The includes that name no file, each reported where it stands in the main file. */
+export const missingInputRule = (deps: PaperDeps): TexRuleModule => ({
+  meta: MISSING_META,
+  create(context) {
+    return {
+      root() {
+        const sc = context.sourceCode;
+        const paper = readPaper(context.filename, sc.raw ?? sc.text, deps);
+        const loc = (i: number) => sc.getLocFromIndex(i);
+        paper.missing.forEach((m) => {
+          context.report({
+            loc: { start: loc(m.via.start), end: loc(m.via.end) },
+            messageId: m.file === paper.main ? "missing" : "missingIn",
+            data: { target: m.target, file: m.file },
+          });
+        });
+      },
+    };
+  },
+});

package/src/tex-requirements.harness.ts

@@ -16,22 +16,12 @@ import {
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import ts from "typescript";
-import { z } from "zod";
+import { join } from "node:path";
 import { createChecker } from "../lib/check.ts";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
-const VENUES = join(
-  HERE,
-  "..",
-  "skills",
-  "submit-paper",
-  "references",
-  "venues",
-);
 const R = await import("./tex-requirements.ts");
+const { parseTemplate } = await import("./adapters/latex/index.ts");
+const VENUES = (await import("./package-dirs.ts")).presetsDir();
 
 const check = createChecker();
 const throws = (fn: () => unknown): string => {
@@ -70,15 +60,15 @@ check(
   "cm-super" in base.packages,
 );
 
-// The whole profile, parsed the way the other harnesses read these files — never a line of text.
-const TemplateField = z.object({ template: z.unknown().optional() });
-const templateOf = (v: string): unknown =>
-  TemplateField.parse(
-    ts.parseConfigFileTextToJson(
-      v,
-      readFileSync(join(VENUES, `${v}.jsonc`), "utf8"),
-    ).config,
-  ).template;
+// The class each profile's template names, as the parser reads it — never a line of text.
+const presetOf = (v: string) =>
+  R.parsePreset(
+    readFileSync(join(VENUES, `${v}.jsonc`), "utf8"),
+    `${v}.jsonc`,
+    VENUES,
+  );
+const templateOf = (v: string): string | undefined =>
+  parseTemplate(presetOf(v).template ?? "")?.cls;
 const acm = venues.filter((v) => templateOf(v) === "acmart");
 check(
   "at least one acmart venue is shipped (else the next checks see nothing)",
@@ -108,7 +98,7 @@ for (const v of acm) {
 // declares the template's packages, so this holds by construction; the check stays for any two
 // standalone presets that name the same template.
 const byTemplate = new Map<unknown, string[]>();
-for (const v of venues) {
+for (const v of venues.filter((x) => presetOf(x).extends === null)) {
   const t = templateOf(v);
   byTemplate.set(t, [...(byTemplate.get(t) ?? []), v]);
 }

package/src/tex-requirements.ts

@@ -16,8 +16,8 @@
  * `TexRequirements` and never looks at the text again; a malformed profile throws with the path
  * of every violation, it is never read as "no packages".
  *
- * Where the profiles live is answered by `packageVenuesDir()` in consumer.mjs — the one module
- * allowed to know where this package is installed (rule 10).
+ * Where the profiles live is answered by `presetsDir()` in `package-dirs.ts` — the one module
+ * allowed to know where this package's data is installed (rule 10).
  */
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { readFileSync, readdirSync } from "node:fs";
@@ -25,7 +25,7 @@ import { createRequire } from "node:module";
 import { join } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import Ajv from "ajv";
-import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { presetsDir } from "./package-dirs.ts";
 import { CONFIG_FILE } from "#lib/paper-config";
 import { fieldOf } from "./domain/record.ts";
 
@@ -148,6 +148,13 @@ export const NO_FORMAT: VenueFormat = {
   kinds: new Map(),
 };
 
+/** A section a venue requires: its exact title, and whether it must close the paper. */
+export interface RequiredSection {
+  readonly title: string;
+  /** "last": after every section of the body; null: anywhere. */
+  readonly position: "last" | null;
+}
+
 /**
  * One preset FILE, parsed — before its `extends` chain is resolved (`src/presets.ts` does that).
  * A preset is a venue or a template family: `{ extends?, name?, template?, format?, tex?, rules? }`.
@@ -157,7 +164,12 @@ export interface PresetFile {
   readonly extends: string | null;
   /** A display name for messages; the file name otherwise. */
   readonly name: string | null;
+  /** The `\\documentclass` the venue's template uses, as the file spells it; null when it names none. */
   readonly template: string | null;
+  /** Other names the venue goes by in a paper's text; empty when the file names none. */
+  readonly aliases: readonly string[];
+  /** Sections the venue requires; null when the file names none (a child's list replaces its parent's). */
+  readonly requiredSections: readonly RequiredSection[] | null;
   /** Null when the file declares no `tex` block (allowed only with `extends`). */
   readonly tex: TexRequirements | null;
   readonly format: VenueFormat;
@@ -188,6 +200,11 @@ interface PresetJson {
   readonly extends?: string;
   readonly name?: string;
   readonly template?: string;
+  readonly aliases?: readonly string[];
+  readonly required_sections?: readonly {
+    readonly title: string;
+    readonly position?: "last";
+  }[];
   /** The schema requires `packages` in a `tex` block; `tools` is optional. */
   readonly tex?: Pick<TexRequirements, "packages"> &
     Partial<Pick<TexRequirements, "tools">>;
@@ -225,6 +242,14 @@ function formatOf(j: FormatJson = {}): VenueFormat {
   };
 }
 
+/** A preset's `required_sections`, or null when it names none. */
+const sectionsOf = (
+  r: PresetJson["required_sections"],
+): readonly RequiredSection[] | null =>
+  r === undefined
+    ? null
+    : r.map((x) => ({ title: x.title, position: orNull(x.position) }));
+
 /**
  * The text of one preset file → the typed file, or an Error naming every problem. The ONE parser
  * of a preset: the toolchain reads its `tex`, the venue rules its `format`, the config its `rules`.
@@ -236,7 +261,7 @@ function formatOf(j: FormatJson = {}): VenueFormat {
 export function parsePreset(
   text: string,
   file: string,
-  dir: string = packageVenuesDir(),
+  dir: string = presetsDir(),
 ): PresetFile {
   const parsed = typescript().parseConfigFileTextToJson(file, text);
   const config: unknown = parsed.config;
@@ -255,6 +280,8 @@ export function parsePreset(
     extends: orNull(j.extends),
     name: orNull(j.name),
     template: orNull(j.template),
+    aliases: j.aliases ?? [],
+    requiredSections: sectionsOf(j.required_sections),
     tex: j.tex ? { packages: j.tex.packages, tools: j.tex.tools ?? {} } : null,
     format: formatOf(j.format),
     rules: j.rules ?? {},
@@ -265,7 +292,7 @@ export function parsePreset(
 export function parseProfile(
   text: string,
   file: string,
-  dir: string = packageVenuesDir(),
+  dir: string = presetsDir(),
 ): TexRequirements {
   return parsePreset(text, file, dir).tex ?? NO_REQUIREMENTS;
 }
@@ -287,7 +314,7 @@ function readProfile(dir: string, file: string): TexRequirements {
 }
 
 /** The venues that have a profile — every `.jsonc` in the directory except the base set. */
-export function venueNames(dir: string = packageVenuesDir()): string[] {
+export function venueNames(dir: string = presetsDir()): string[] {
   return readdirSync(dir)
     .filter((f) => f.endsWith(PROFILE_EXT) && f !== BASE_PROFILE)
     .map((f) => f.slice(0, -PROFILE_EXT.length))
@@ -325,7 +352,7 @@ export function packageNames(tex: TexRequirements): string[] {
  */
 export function requirementsFor(
   preset: { readonly label: string; readonly tex: TexRequirements } | null,
-  dir: string = packageVenuesDir(),
+  dir: string = presetsDir(),
 ): PaperRequirements {
   const base = readProfile(dir, BASE_PROFILE);
   return preset === null
@@ -345,7 +372,7 @@ export function requirementsFor(
  * builds any paper.
  */
 export function declaredUnion(
-  dir: string = packageVenuesDir(),
+  dir: string = presetsDir(),
   extra: readonly TexRequirements[] = [],
 ): {
   readonly tex: TexRequirements;