paperlint 3.1.3 → 3.2.0

package/src/cli.ts

@@ -30,7 +30,7 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { join, dirname, resolve, relative, basename, sep } from "node:path";
 import markdown from "@eslint/markdown";
-// Types come from consumer.d.mts beside it, the same arrangement as lib/paper-config.d.mts.
+// Types come from consumer.d.mts beside it.
 import {
   isMain,
   packageVenuesDir,
@@ -96,15 +96,16 @@ import {
   type PaperFormat,
   type VenueSetting,
 } from "./new-paper.ts";
-// The one source for the consumer's config key lives in the .mjs half of the package (the ESLint
-// rules and the skill scripts import it too); its types are in lib/paper-config.d.mts.
+// The one source for the consumer's config key lives in lib/ (the ESLint rules and the skill scripts
+// import it too). It is imported compiled, from dist/, the one path that resolves the same from src/
+// and from dist/ — see CONTRIBUTING.md.
 import {
   CONFIG_FILE,
   DEFAULT_PAPERS_ROOT,
   PAPERS_DIR_FIELD,
   SETTINGS_KEYS,
   findProjectRoot,
-} from "../lib/paper-config.mjs";
+} from "#lib/paper-config";
 import {
   parseRuleBlocks,
   parseRuleEntries,
@@ -117,22 +118,15 @@ import {
 export { init };
 export { nextSteps } from "./init.ts";
 
-// @ts-expect-error — an ESLint rule in .mjs, it has no types
-import paperStages from "../eslint-rules/paper-stages.mjs";
-// @ts-expect-error — an ESLint rule in .mjs, it has no types
-import researchQuestion from "../eslint-rules/paper-research-question.mjs";
-// @ts-expect-error — an ESLint rule in .mjs, it has no types
-import typography from "../eslint-rules/paper-typography.mjs";
-// @ts-expect-error — an ESLint rule in .mjs, it has no types
-import texBuild from "../eslint-rules/tex-build.mjs";
-// @ts-expect-error — an ESLint rule in .mjs, it has no types
-import bibReachable from "../eslint-rules/bib-reachable-entry.mjs";
-// @ts-expect-error — an ESLint rule in .mjs, it has no types
-import reviewFrontmatter from "../eslint-rules/review-frontmatter.mjs";
-// @ts-expect-error — an ESLint rule in .mjs, it has no types
-import siblingFrontmatter from "../eslint-rules/sibling-frontmatter.mjs";
-// @ts-expect-error — an ESLint rule in .mjs, it has no types
-import pdfRules from "../eslint-rules/pdf-last-page-balance.mjs";
+import paperStages from "#eslint-rules/paper-stages";
+import researchQuestion from "#eslint-rules/paper-research-question";
+import typography from "#eslint-rules/paper-typography";
+import texBuild from "#eslint-rules/tex-build";
+import bibReachable from "#eslint-rules/bib-reachable-entry";
+import reviewFrontmatter from "#eslint-rules/review-frontmatter";
+import siblingFrontmatter from "#eslint-rules/sibling-frontmatter";
+import pdfRules from "#eslint-rules/pdf-last-page-balance";
+import { messageOf } from "./domain/text.ts";
 
 /** The shipped venue presets, read from the package's venues directory — the one list. */
 const SHIPPED_VENUES = (): string[] => shippedPresets(packageVenuesDir());
@@ -244,8 +238,7 @@ export function buildConfig(
     languageOptions: { frontmatter: "yaml" },
   };
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #49: replace with a real type
-  const cfg: any[] = [
+  const cfg: unknown[] = [
     // 🔴 THE PROJECT'S PAPER TEMPLATE IS NOT A PAPER. `paperlint new` reads `<papers>/.template/`, and
     // its files carry every marker a paper does. Flat config does NOT ignore dot-directories by
     // default (only `node_modules/` and `.git/`), so without this block `paperlint lint` would lint the
@@ -392,7 +385,9 @@ export function rulesOff(texLanguage?: unknown): Linter.Config[] {
   return [
     {
       name: "paperlint/rules-off",
-      plugins: rulePlugins(texLanguage) as Linter.Config["plugins"],
+      plugins: rulePlugins(texLanguage) as NonNullable<
+        Linter.Config["plugins"]
+      >,
       rules: Object.fromEntries([...SHIPPED_RULES].map((id) => [id, "off"])),
     },
     {
@@ -405,7 +400,7 @@ export function rulesOff(texLanguage?: unknown): Linter.Config[] {
 
 /** Whether a rule entry (`"error"`, `2`, `["warn", {…}]`) turns the rule on. */
 const isOn = (entry: unknown): boolean => {
-  const sev = Array.isArray(entry) ? entry[0] : entry;
+  const sev: unknown = Array.isArray(entry) ? entry[0] : entry;
   return sev !== undefined && sev !== "off" && sev !== 0;
 };
 
@@ -470,7 +465,10 @@ export function paperRuleBlocks(
     existsSync(p) && statSync(p).isFile() ? dirname(p) : p,
   );
   const papers = [...new Set(dirs.flatMap((p) => [p, ...papersIn(p)]))];
-  const out = { preset: [] as RuleBlock[], own: [] as RuleBlock[] };
+  const out: { preset: RuleBlock[]; own: RuleBlock[] } = {
+    preset: [],
+    own: [],
+  };
   for (const dir of papers) {
     const p = paperPreset(dir, PRESET_DEPS);
     if (p.kind === "settings-problem")
@@ -701,8 +699,13 @@ export function ownVersion(
     readFileSync(new URL("../package.json", import.meta.url), "utf8"),
 ): string | undefined {
   try {
-    const v = JSON.parse(readManifest())?.version;
-    return typeof v === "string" ? v : undefined;
+    const manifest: unknown = JSON.parse(readManifest());
+    return typeof manifest === "object" &&
+      manifest !== null &&
+      "version" in manifest &&
+      typeof manifest.version === "string"
+      ? manifest.version
+      : undefined;
   } catch {
     return undefined;
   }
@@ -747,7 +750,7 @@ export function readConfig(
   try {
     parsed = JSON.parse(readFileSync(configPath, "utf8"));
   } catch (e) {
-    err(`${configPath} is not valid JSON: ${(e as Error).message}`);
+    err(`${configPath} is not valid JSON: ${messageOf(e)}`);
     return { code: 2 };
   }
   // The discovered config is NAMED out loud. Otherwise a run from someone else's directory picks
@@ -787,7 +790,9 @@ export const papersRoots = (cfg: {
 export function toPaths(papers: unknown): string[] {
   if (typeof papers === "string") return papers.trim() ? [papers.trim()] : [];
   if (Array.isArray(papers))
-    return papers.filter((x) => typeof x === "string" && x.trim());
+    return papers.filter(
+      (x): x is string => typeof x === "string" && x.trim() !== "",
+    );
   return [];
 }
 
@@ -1453,8 +1458,7 @@ export async function run(
   // failing outright — the LaTeX rules simply have no language to run in.
   let texLanguage: unknown = null;
   try {
-    // @ts-expect-error — the module is .mjs and has no types
-    ({ texLanguage } = await import("../eslint-rules/latex-language.mjs"));
+    ({ texLanguage } = await import("#eslint-rules/latex-language"));
   } catch {
     texLanguage = null;
   }
@@ -1478,8 +1482,7 @@ export async function run(
   // reached, which is what the very first run over an empty directory showed: instead of a clear
   // message a stack from the depths of eslint-helpers.js flew out. A failure stays a failure, but
   // an explicable one.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #49: replace with a real type
-  let results: any[];
+  let results: ESLint.LintResult[];
   try {
     results = await eslint.lintFiles(paths);
   } catch (e) {
@@ -1555,8 +1558,7 @@ const isEmptySet = (e: unknown): boolean => {
  */
 async function reportLint(
   eslint: ESLint,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #49: replace with a real type
-  results: any[],
+  results: ESLint.LintResult[],
   structure: ReturnType<typeof checkStructure>,
   {
     a,
@@ -1598,7 +1600,7 @@ async function reportLint(
       out.trim() ||
         (structure.length > 0
           ? ""
-          : `✓ ${results.length} file(s) checked, no findings`),
+          : `✓ ${String(results.length)} file(s) checked, no findings`),
     );
   }
   if (structure.length > 0 || results.some((r) => r.errorCount > 0)) return 1;
@@ -1608,7 +1610,7 @@ async function reportLint(
     const warnings = results.reduce((n, r) => n + r.warningCount, 0);
     if (warnings > a.maxWarnings) {
       err(
-        `${warnings} warning(s) exceed the --max-warnings limit of ${a.maxWarnings}`,
+        `${String(warnings)} warning(s) exceed the --max-warnings limit of ${String(a.maxWarnings)}`,
       );
       return 1;
     }

package/src/doctor.harness.mjs

@@ -10,7 +10,7 @@
  *
  * Run:    npx vigiles test src/doctor.harness.mjs
  */
-import { PAPERS_DIR_FIELD } from "../lib/paper-config.mjs";
+import { PAPERS_DIR_FIELD } from "../lib/paper-config.ts";
 import {
   mkdtempSync,
   mkdirSync,
@@ -21,7 +21,7 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { createChecker } from "../lib/check.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const { doctor, detectPapers, PROGRAMS, found } = await import(
@@ -279,7 +279,7 @@ const runDoctor = (
 
 // ── VII-bis. SKILLS THAT ARE NOT LINKED ARE NAMED — AND DO NOT FAIL THE RUN ─────────────────
 // Before this section a consumer without `.claude/skills/` links had no `/paper-pipeline`, and
-// nothing anywhere said so. The link state itself is `link-skills.harness.mjs`'s subject; here
+// nothing anywhere said so. The link state itself is `link-skills.harness.ts`'s subject; here
 // only doctor's REPORTING of it is judged, so the state is handed in rather than built on disk.
 {
   const dir = consumer({ papersDir: "papers", declared: "papers" });

package/src/doctor.ts

@@ -36,6 +36,7 @@ import {
 import { PAPER_MARKERS } from "./build.ts";
 import { linkSkills, SKILLS_HOME, type LinkReport } from "./link-skills.ts";
 import { doctorHooks } from "./hooks-settings.ts";
+import { messageOf } from "./domain/text.ts";
 
 export interface Program {
   readonly bin: string;
@@ -169,7 +170,7 @@ function declarationVerdict(raw: string | null): {
   } catch (e) {
     return {
       lines: [
-        `  ✗ ${CONFIG_FILE} is not valid JSON: ${(e as Error).message}`,
+        `  ✗ ${CONFIG_FILE} is not valid JSON: ${messageOf(e)}`,
         `      the edit guard refuses every Bash command until it parses — fix it with Edit or Write`,
       ],
       bad: 1,
@@ -334,7 +335,7 @@ export function doctor({
   try {
     out.push(...doctorHooks(root));
   } catch (e) {
-    out.push(`hooks`, `  ⚠ not checked — ${(e as Error).message}`);
+    out.push(`hooks`, `  ⚠ not checked — ${messageOf(e)}`);
   }
   out.push("");
   log(out.join("\n"));

package/src/domain/lookup-cache.ts

@@ -31,6 +31,7 @@
  * never read as empty.
  */
 import { err, ok, type Result } from "./result.ts";
+import { messageOf } from "./text.ts";
 
 export const LOOKUP_CACHE_SCHEMA = 1;
 
@@ -106,7 +107,7 @@ function sectionOf<T>(
   name: string,
   section: unknown,
   known: readonly string[],
-  one: (o: Json, at: string) => Result<T, string>,
+  one: (o: Json, fetched: string, at: string) => Result<T, string>,
 ): Result<Map<string, T>, string> {
   if (!isObject(section)) return err(`\`${name}\`: expected an object`);
   const out = new Map<string, T>();
@@ -115,18 +116,23 @@ function sectionOf<T>(
     if (!isObject(v)) return err(`${at}\`: expected an object`);
     const extra = unknownField(v, known);
     if (extra !== undefined) return err(`${at}\`: unknown field \`${extra}\``);
-    if (!isDate(v["fetched"]))
+    const fetched = v["fetched"];
+    if (!isDate(fetched))
       return err(`${at}.fetched\`: expected a date, YYYY-MM-DD`);
-    const r = one(v, at);
+    const r = one(v, fetched, at);
     if (!r.ok) return r;
     out.set(key, r.value);
   }
   return ok(out);
 }
 
-const cachedResponse = (o: Json, at: string): Result<CachedResponse, string> =>
+const cachedResponse = (
+  o: Json,
+  fetched: string,
+  at: string,
+): Result<CachedResponse, string> =>
   isObject(o["response"]) && o["response"]["transport"] === "ok"
-    ? ok({ fetched: o["fetched"] as string, response: o["response"] })
+    ? ok({ fetched, response: o["response"] })
     : err(
         `${at}.response\`: expected a successful response ({"transport": "ok", …})`,
       );
@@ -137,7 +143,11 @@ const isHit = (h: unknown): h is DblpHit =>
   Array.isArray(h["authors"]) &&
   h["authors"].every((a) => typeof a === "string");
 
-function cachedDblp(o: Json, at: string): Result<CachedDblp, string> {
+function cachedDblp(
+  o: Json,
+  fetched: string,
+  at: string,
+): Result<CachedDblp, string> {
   const { title, hits } = o;
   if (typeof title !== "string") return err(`${at}.title\`: expected a string`);
   if (!Array.isArray(hits)) return err(`${at}.hits\`: expected an array`);
@@ -147,9 +157,9 @@ function cachedDblp(o: Json, at: string): Result<CachedDblp, string> {
       `${at}.hits[${String(bad)}]\`: expected {venue, year, type, title: string; authors: string[]}`,
     );
   return ok({
-    fetched: o["fetched"] as string,
+    fetched,
     title,
-    hits: hits as DblpHit[],
+    hits: hits.filter(isHit),
   });
 }
 
@@ -159,7 +169,7 @@ export function parseLookupCache(text: string): Result<LookupCache, string> {
   try {
     json = JSON.parse(text);
   } catch (e) {
-    return err(`not JSON: ${(e as Error).message}`);
+    return err(`not JSON: ${messageOf(e)}`);
   }
   if (!isObject(json))
     return err("expected an object with `schema`, `citations` and `dblp`");
@@ -186,8 +196,8 @@ export function parseLookupCache(text: string): Result<LookupCache, string> {
   return ok({ citations: citations.value, dblp: dblp.value });
 }
 
-const sorted = <T>(m: ReadonlyMap<string, T>): Record<string, T> =>
-  Object.fromEntries([...m.keys()].sort().map((k) => [k, m.get(k) as T]));
+const sorted = <T>(m: ReadonlyMap<string, T>): Record<string, T | undefined> =>
+  Object.fromEntries([...m.keys()].sort().map((k) => [k, m.get(k)]));
 
 /** The cache as the file holds it: keys sorted, so one new answer is a small diff. */
 export const serializeLookupCache = (c: LookupCache): string =>

package/src/domain/result.test.ts

@@ -3,7 +3,7 @@ import { test } from "vitest";
 import { andThen, err, map, match, ok, type Result } from "./result.ts";
 
 const half = (n: number): Result<number, string> =>
-  n % 2 === 0 ? ok(n / 2) : err(`${n} is odd`);
+  n % 2 === 0 ? ok(n / 2) : err(`${String(n)} is odd`);
 
 test("map and andThen run on ok and pass an error through untouched", () => {
   assert.deepEqual(
@@ -24,7 +24,7 @@ test("map and andThen run on ok and pass an error through untouched", () => {
 
 test("match picks the branch by `ok`", () => {
   const say = (r: Result<number, string>) =>
-    match(r, { ok: (n) => `got ${n}`, err: (e) => `no: ${e}` });
+    match(r, { ok: (n) => `got ${String(n)}`, err: (e) => `no: ${e}` });
   assert.equal(say(half(4)), "got 2");
   assert.equal(say(half(5)), "no: 5 is odd");
 });

package/src/domain/text.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { codeOf, firstLine, messageOf, printed } from "./text.ts";
+
+test("messageOf: an Error's message, and anything else thrown as its text", () => {
+  assert.equal(messageOf(new Error("boom")), "boom");
+  // `throw "x"` and `throw 3` are legal JavaScript; `(e as Error).message` read them as undefined.
+  assert.equal(messageOf("plain string"), "plain string");
+  assert.equal(messageOf(3), "3");
+});
+
+test("codeOf: a string `code` only", () => {
+  assert.equal(
+    codeOf(Object.assign(new Error("x"), { code: "ENOENT" })),
+    "ENOENT",
+  );
+  assert.equal(codeOf(new Error("no code")), undefined);
+  assert.equal(codeOf({ code: 3 }), undefined);
+  assert.equal(codeOf(null), undefined);
+  assert.equal(codeOf("ENOENT"), undefined);
+});
+
+test("printed: a stream a failed spawn left undefined reads as empty text", () => {
+  assert.equal(printed(undefined), "");
+  assert.equal(printed(null), "");
+  assert.equal(printed("out"), "out");
+});
+
+test("firstLine: the first non-blank line, trimmed", () => {
+  assert.equal(firstLine("\n  \n  first \nsecond"), "first");
+  assert.equal(firstLine(""), "");
+});

package/src/domain/text.ts

@@ -9,3 +9,26 @@ export const firstLine = (s: string): string =>
     .split("\n")
     .map((l) => l.trim())
     .find(Boolean) ?? "";
+
+/**
+ * What a process printed on one stream, as text. Node types `spawnSync(…, { encoding })`'s
+ * `stdout`/`stderr` as `string`, but both are `undefined` when the spawn itself failed (measured:
+ * `spawnSync("no-such-program", [], { encoding: "utf8" }).stdout` is `undefined`). The parameter
+ * takes the stream as it really arrives, so the fallback guards a real case instead of reading
+ * as dead code against a type that lies.
+ */
+export const printed = (stream: string | null | undefined): string =>
+  stream ?? "";
+
+/** What a caught value says: an `Error`'s message, anything else as text (`catch` gets `unknown`). */
+export const messageOf = (e: unknown): string =>
+  e instanceof Error ? e.message : String(e);
+
+/** The `code` a Node error carries (`ENOENT`, `EACCES`, …), when it carries a string one. */
+export const codeOf = (e: unknown): string | undefined =>
+  typeof e === "object" &&
+  e !== null &&
+  "code" in e &&
+  typeof e.code === "string"
+    ? e.code
+    : undefined;

package/src/engine.harness.mjs

@@ -5,7 +5,7 @@
  *   1. `resolveEngine` over `EngineFacts` — one row per branch of the order;
  *   2. the fact readers: `missingPackages` over kpsewhich output, `missingTools`, `whichOnPath`,
  *      `probeTree` through a fake runner.
- * All pure or port-driven: no TeX needed. The real-TeX half is `test/e2e/build.mjs`.
+ * All pure or port-driven: no TeX needed. The real-TeX half is `test/e2e/build.ts`.
  */
 import {
   chmodSync,
@@ -18,7 +18,7 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { createChecker } from "../lib/check.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const {

package/src/engine.ts

@@ -24,6 +24,7 @@ import { spawnSync } from "node:child_process";
 import { accessSync, constants, statSync } from "node:fs";
 import { basename, delimiter, join } from "node:path";
 import type { TexRequirements } from "./tex-requirements.ts";
+import { printed } from "./domain/text.ts";
 
 /** A process runner with `spawnSync`'s shape — the port the harness replaces. */
 export type Runner = typeof spawnSync;
@@ -161,7 +162,7 @@ export function probeTree(
     stdio: ["ignore", "pipe", "pipe"],
   });
   if (r.error) return Object.keys(packages).sort();
-  return missingPackages(packages, String(r.stdout ?? ""));
+  return missingPackages(packages, printed(r.stdout));
 }
 
 /**
@@ -181,7 +182,7 @@ export function missingDependencies(
     stdio: ["ignore", "pipe", "pipe"],
   });
   if (r.error) return [];
-  const lines = String(r.stdout ?? "").split("\n");
+  const lines = printed(r.stdout).split("\n");
   const start = lines.findIndex(
     (l) => l.trim() === "DEPENDS WITHOUT PACKAGES:",
   );
@@ -193,7 +194,7 @@ export function missingDependencies(
   return [
     ...new Set(
       (end < 0 ? section : section.slice(0, end)).map((l) =>
-        l.split(" in: ")[0]!.trim(),
+        l.replace(/ in: [\s\S]*/, "").trim(),
       ),
     ),
   ].sort();

package/src/facts-file.test.ts

@@ -4,8 +4,8 @@
  * The document is assembled from hand-made measurements (pure), and `measurePaper` runs on
  * in-memory files with a FAKE pdf.js reader and a FAKE measurer, so each outcome — read failed, not
  * measured, measured — is chosen rather than hoped for. Reading real PDFs is
- * `pdf-facts.harness.mjs`'s job; banal as the measurer is `adapters/banal/index.test.ts`, and the
- * real banal is `test/e2e/banal.mjs`.
+ * `pdf-facts.harness.ts`'s job; banal as the measurer is `adapters/banal/index.test.ts`, and the
+ * real banal is `test/e2e/banal.ts`.
  */
 import assert from "node:assert/strict";
 import { readdirSync, readFileSync } from "node:fs";
@@ -147,10 +147,11 @@ test("🔴 geometry_source and the nine columns come from ONE branch", () => {
 const PAPER = "/r/papers/p";
 const PDF = `${PAPER}/paper.pdf`;
 const PDF_BYTES = "%PDF-pretend";
-const good: PdfReader = async () => ({
-  ok: true,
-  facts: { pages: 2, fonts: FONTS, last: lastPage(60, 60), layout: [] },
-});
+const good: PdfReader = () =>
+  Promise.resolve({
+    ok: true,
+    facts: { pages: 2, fonts: FONTS, last: lastPage(60, 60), layout: [] },
+  });
 /** The shipped presets at their real paths: `extends` resolves through the same Files port. */
 const SHIPPED_PRESETS = Object.fromEntries(
   readdirSync(packageVenuesDir())
@@ -232,7 +233,8 @@ test("a failed read is the one error line, and nothing is written", async () =>
   const before = files.map.size;
   const m = await measurePaper(PAPER, PDF, {
     ...o,
-    readPdf: async () => ({ ok: false, reason: "unreadable", detail: "boom" }),
+    readPdf: () =>
+      Promise.resolve({ ok: false, reason: "unreadable", detail: "boom" }),
   });
   assert.match(!m.ok ? m.error : "", /pdf\.js \(unreadable\): boom/);
   assert.equal(files.map.size, before);

package/src/facts-file.ts

@@ -50,6 +50,7 @@ import type { Files } from "./ports/files.ts";
 import { err, ok, type Result } from "./domain/result.ts";
 import { paperPreset, paperPresetProblem } from "./presets.ts";
 import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { messageOf } from "./domain/text.ts";
 
 export const FACTS_SCHEMA = 2;
 export const FACTS_DIR = "_build";
@@ -338,7 +339,7 @@ export function parseFactsText(text: string): Result<ReadFacts, FactsProblem> {
   try {
     d = JSON.parse(text);
   } catch (e) {
-    return err({ kind: "broken", why: `not JSON (${(e as Error).message})` });
+    return err({ kind: "broken", why: `not JSON (${messageOf(e)})` });
   }
   if (!isRecord(d)) return err({ kind: "broken", why: "not a JSON object" });
   if (d["schema"] !== FACTS_SCHEMA)