paperlint 3.1.3 → 4.0.0

package/eslint-rules/{paper-research-question.mjs → paper-research-question.ts}

@@ -35,6 +35,23 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { load } from "js-yaml";
+import { z } from "zod";
+import type { RuleContext } from "./rule-context.ts";
+
+/**
+ * The two scorecard fields this rule reads, parsed rather than trusted: a field of the wrong shape
+ * reads as absent, the way `data?.stages` on a string or a number always did.
+ */
+const Scorecard = z
+  .looseObject({
+    stages: z.array(z.unknown()).catch([]),
+    researchQuestion: z.string().catch(""),
+  })
+  .catch({ stages: [], researchQuestion: "" });
+const StageEntry = z.looseObject({ stage: z.unknown().optional() }).catch({});
+const RuleOptions = z
+  .object({ statusFile: z.string().default("PIPELINE-STATUS.md") })
+  .default({ statusFile: "PIPELINE-STATUS.md" });
 
 /**
  * 🔴 THE REGEX IS GONE, AND THE REASON IS NOT "regexes are bad" — IT IS THAT IT ANSWERED THE
@@ -76,18 +93,21 @@ import { load } from "js-yaml";
  */
 
 /** Whitespace is the only thing normalised: a sentence wrapped across lines is the same sentence. */
-const flatten = (t) => t.replace(/\s+/g, " ").trim().toLowerCase();
+const flatten = (t: string) => t.replace(/\s+/g, " ").trim().toLowerCase();
 
 /**
  * Both facts come out of ONE parse of the scorecard's front matter: the stages (has this paper
  * shipped?) and the declared question. Reading them separately would invite the two to be taken
  * from different revisions of the same file.
  */
-function scorecard(dir, statusName) {
+function scorecard(
+  dir: string,
+  statusName: string,
+): { stages: unknown[]; question: string } {
   const p = join(dir, statusName);
   const none = { stages: [], question: "" };
   if (!existsSync(p)) return none;
-  let text;
+  let text: string;
   try {
     text = readFileSync(p, "utf-8");
   } catch {
@@ -95,25 +115,23 @@ function scorecard(dir, statusName) {
   }
   const m = /^---\n([\s\S]*?)\n---/.exec(text);
   if (!m) return none;
-  let data;
+  const [, front = ""] = m;
+  let data: unknown;
   try {
-    data = load(m[1]);
+    data = load(front);
   } catch {
     return none; // the unreadable YAML is already reported by `paper/stages`, on its own file
   }
-  const raw = data?.stages;
-  const stages = Array.isArray(raw)
-    ? raw.map((r) => r?.stage).filter(Boolean)
-    : [];
-  const q = data?.researchQuestion;
-  return { stages, question: typeof q === "string" ? q : "" };
+  const { stages: raw, researchQuestion: question } = Scorecard.parse(data);
+  const stages = raw.map((r) => StageEntry.parse(r).stage).filter(Boolean);
+  return { stages, question };
 }
 
 export default {
   rules: {
     "research-question": {
       meta: {
-        type: "suggestion",
+        type: "suggestion" as const,
         docs: {
           description:
             "a paper that declares a stage states its research question explicitly — otherwise the reviewer reconstructs it themselves, and says so",
@@ -137,14 +155,15 @@ export default {
             "the scorecard declares a research question the paper does not contain. Looked for «{{needle}}» with whitespace collapsed, and the source has no such run of text. Either the paper dropped it or the declaration drifted from what was written — and which of the two it is, only you know",
         },
       },
-      create(context) {
-        const statusName =
-          context.options?.[0]?.statusFile ?? "PIPELINE-STATUS.md";
+      create(context: RuleContext) {
+        const { statusFile: statusName } = RuleOptions.parse(
+          context.options[0],
+        );
         return {
           // `root:exit` exists for both markdown and the `tex/latex` language — the same place
           // `paper/typography` lives, and for the same reason: a paper in this corpus can be
           // either.
-          "root:exit"(node) {
+          "root:exit"(node: object) {
             const raw = context.sourceCode.raw ?? context.sourceCode.text;
             if (typeof raw !== "string") return;
             const { stages, question } = scorecard(

package/eslint-rules/paper-stages.harness.mjs

@@ -15,8 +15,8 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Linter } from "eslint";
 import markdown from "@eslint/markdown";
-import stages from "./paper-stages.mjs";
-import { createChecker } from "../lib/check.mjs";
+import stages from "./paper-stages.ts";
+import { createChecker } from "../lib/check.ts";
 
 const FIX = join(
   dirname(fileURLToPath(import.meta.url)),

package/eslint-rules/paper-stages.test.mjs

@@ -8,8 +8,8 @@ import { join } from "node:path";
 import markdown from "@eslint/markdown";
 import { Linter } from "eslint";
 import { test } from "vitest";
-import { useTempDir, writeTree } from "../test/support.mjs";
-import stages from "./paper-stages.mjs";
+import { useTempDir, writeTree } from "../test/support.ts";
+import stages from "./paper-stages.ts";
 
 const root = useTempDir("paper-stages-");
 // Flat config matches `files` against paths under the linter's cwd; the temp papers live outside
@@ -93,6 +93,12 @@ test("each entry: an unknown or missing stage, missing fields, a date that is no
   );
 });
 
+test("a stage written as a mapping is named as written, not as [object Object]", () => {
+  assert.deepEqual(lint("mapping", "stages:\n  - stage: {name: submitted}"), [
+    'unknown stage «{"name":"submitted"}» — the vocabulary is: submitted · camera-ready · arxiv',
+  ]);
+});
+
 test("paper/source skips a `stages` that is not a list, and entries whose stage is unknown or missing", () => {
   assert.deepEqual(
     lint("src-scalar", "stages: submitted", { rule: "source" }),

package/eslint-rules/{paper-stages.mjs → paper-stages.ts}

@@ -48,30 +48,69 @@
  */
 import { existsSync, statSync, readdirSync } from "node:fs";
 import { join, dirname } from "node:path";
+import assert from "node:assert/strict";
 import { load } from "js-yaml";
+import { z } from "zod";
+import type { RuleContext } from "./rule-context.ts";
 
-const STAGES = ["submitted", "camera-ready", "arxiv"];
+/** The frontmatter's `stages` field, whatever it holds; anything that is not a mapping has none. */
+const Frontmatter = z.looseObject({ stages: z.unknown().optional() }).catch({});
+const StageList = z.array(z.unknown());
+/** One `stages` entry. A field of the wrong shape is read as it is written, then judged below. */
+const StageRecord = z
+  .looseObject({
+    stage: z.unknown().optional(),
+    date: z.unknown().optional(),
+    pdf: z.unknown().optional(),
+    bytes: z.unknown().optional(),
+    source: z.unknown().optional(),
+    sourceBytes: z.unknown().optional(),
+    sourceLost: z.unknown().optional(),
+  })
+  .catch({});
+const REQUIRED = ["date", "pdf", "bytes"] satisfies readonly (
+  "date" | "pdf" | "bytes"
+)[];
+
+/** A stage the frontmatter declares, with the fields every check below needs. */
+interface Declared {
+  readonly stage: string;
+  readonly date: string;
+  readonly pdf: string;
+  readonly bytes: number;
+}
+
+const STAGES: readonly string[] = ["submitted", "camera-ready", "arxiv"];
 
 /**
  * A YAML date without quotes parses to a `Date`, not a string — js-yaml honours YAML 1.1
  * timestamps. Comparing `Date === "2026-08-29"` is silently false, so every date is
  * normalised before it is compared with one taken from a filename.
  */
-function isoDate(v) {
+/**
+ * A YAML value as the text a message shows: a scalar as written, nothing as "", and a mapping or
+ * list as its JSON (as a number is) — `String()` would print `[object Object]` for a mapping.
+ */
+const scalarText = (v: unknown): string =>
+  typeof v === "string" ? v : v === undefined ? "" : JSON.stringify(v);
+
+function isoDate(v: unknown): string {
   if (v instanceof Date) return v.toISOString().slice(0, 10);
   if (typeof v === "string") return /^\d{4}-\d{2}-\d{2}/.exec(v)?.[0] ?? "";
   return "";
 }
 
 /** Frozen versions on disk, as `{name, date, stage}`. */
-function frozenPdfs(versionsDir) {
-  let names;
+function frozenPdfs(
+  versionsDir: string,
+): { name: string; date: string; stage: string }[] {
+  let names: string[];
   try {
     names = readdirSync(versionsDir);
   } catch {
     return [];
   }
-  const out = [];
+  const out: { name: string; date: string; stage: string }[] = [];
   for (const name of names) {
     if (!name.endsWith(".pdf")) continue;
     // ⚠️ A name carrying `STALE` is a version WITHDRAWN on purpose — one such file records
@@ -80,8 +119,9 @@ function frozenPdfs(versionsDir) {
     if (name.includes("STALE")) continue;
     const m = /^(\d{4}-\d{2}-\d{2})-(.+)\.pdf$/.exec(name);
     if (!m) continue;
-    if (!STAGES.includes(m[2])) continue;
-    out.push({ name, date: m[1], stage: m[2] });
+    const [, date = "", stage = ""] = m;
+    if (!STAGES.includes(stage)) continue;
+    out.push({ name, date, stage });
   }
   return out;
 }
@@ -90,7 +130,7 @@ export default {
   rules: {
     stages: {
       meta: {
-        type: "problem",
+        type: "problem" as const,
         docs: {
           description:
             "a paper's stage is declared as a FIELD, and every declaration is checked against the bytes on disk in both directions",
@@ -112,26 +152,29 @@ export default {
             "`versions/{{file}}` is frozen, but no «{{stage}}» stage on {{date}} is declared in `stages` — the artefact ran ahead of the declaration",
         },
       },
-      create(context) {
+      create(context: RuleContext) {
         const dir = dirname(context.filename);
-        let declared = null; // null = there was no frontmatter at all
+        let declared: Declared[] | null = null; // null = there was no frontmatter at all
 
         return {
-          yaml(node) {
-            let data;
+          yaml(node: { readonly value?: string }) {
+            let data: unknown;
             try {
               data = load(node.value ?? "");
             } catch (e) {
+              // js-yaml throws its own `YAMLException`, an `Error`, and nothing else.
+              assert.ok(e instanceof Error);
               context.report({
                 node,
                 messageId: "badYaml",
-                data: { reason: String(e.message) },
+                data: { reason: e.message },
               });
               return;
             }
-            const raw = data?.stages;
+            const { stages: raw } = Frontmatter.parse(data);
             if (raw === undefined) return;
-            if (!Array.isArray(raw)) {
+            const list = StageList.safeParse(raw);
+            if (!list.success) {
               context.report({
                 node,
                 messageId: "notAList",
@@ -140,8 +183,9 @@ export default {
               return;
             }
             declared = [];
-            for (const rec of raw) {
-              const stage = String(rec?.stage ?? "");
+            for (const entry of list.data) {
+              const rec = StageRecord.parse(entry);
+              const stage = scalarText(rec.stage);
               if (!STAGES.includes(stage)) {
                 context.report({
                   node,
@@ -151,7 +195,7 @@ export default {
                 continue;
               }
               let complete = true;
-              for (const key of ["date", "pdf", "bytes"]) {
+              for (const key of REQUIRED) {
                 if (rec[key] === undefined) {
                   context.report({
                     node,
@@ -207,7 +251,7 @@ export default {
           // ── direction two: bytes owe their declaration ────────────────────────────────
           // 🔴 On `root:exit` rather than inside `yaml`, because the case worth catching is
           // precisely the one with NO frontmatter at all — where the `yaml` visitor never runs.
-          "root:exit"(node) {
+          "root:exit"(node: object) {
             const records = declared ?? [];
             for (const f of frozenPdfs(join(dir, "versions"))) {
               if (records.some((r) => r.stage === f.stage && r.date === f.date))
@@ -256,7 +300,7 @@ export default {
      */
     source: {
       meta: {
-        type: "problem",
+        type: "problem" as const,
         docs: {
           description:
             "a declared stage freezes its source beside the pdf and is checked by bytes — not by a commit reference",
@@ -273,26 +317,27 @@ export default {
             "stage «{{stage}}» ({{date}}): the source is declared LOST. There is nothing left to match a build against a reviewer's line — if a copy turns up, put it in versions/ and clear the flag",
         },
       },
-      create(context) {
+      create(context: RuleContext) {
         const dir = dirname(context.filename);
         return {
-          yaml(node) {
-            let data;
+          yaml(node: { readonly value?: string }) {
+            let data: unknown;
             try {
               data = load(node.value ?? "");
             } catch {
               return; // `paper/stages` has already reported the unreadable YAML
             }
-            const raw = data?.stages;
-            if (!Array.isArray(raw)) return;
-            for (const rec of raw) {
-              const stage = String(rec?.stage ?? "");
+            const list = StageList.safeParse(Frontmatter.parse(data).stages);
+            if (!list.success) return;
+            for (const entry of list.data) {
+              const rec = StageRecord.parse(entry);
+              const stage = scalarText(rec.stage);
               if (!STAGES.includes(stage)) continue;
-              const date = isoDate(rec?.date);
+              const date = isoDate(rec.date);
 
               // Acknowledging the loss is a RECORD, not an exemption: the rule keeps speaking,
               // because the state stays defective, just unfixable today.
-              if (rec?.sourceLost === true) {
+              if (rec.sourceLost === true) {
                 context.report({
                   node,
                   messageId: "lostAcknowledged",
@@ -300,7 +345,7 @@ export default {
                 });
                 continue;
               }
-              const src = rec?.source === undefined ? "" : String(rec.source);
+              const src = scalarText(rec.source);
               if (src === "") {
                 context.report({
                   node,
@@ -319,7 +364,7 @@ export default {
                 continue;
               }
               const got = statSync(abs).size;
-              const want = Number(rec?.sourceBytes);
+              const want = Number(rec.sourceBytes);
               if (Number.isFinite(want) && got !== want)
                 context.report({
                   node,

package/eslint-rules/paper-typography.test.mjs

@@ -15,9 +15,9 @@ import markdown from "@eslint/markdown";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { texLanguage } from "./latex-language.mjs";
-import typography, { texVisibleRuns } from "./paper-typography.mjs";
-import bib from "./bib-reachable-entry.mjs";
+import { texLanguage } from "./latex-language.ts";
+import typography, { texVisibleRuns } from "./paper-typography.ts";
+import bib from "./bib-reachable-entry.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const FIX = join(HERE, "..", "fixtures", "paper-typography");