paperlint 3.1.3 → 4.0.0

package/src/build.ts

@@ -45,7 +45,7 @@ import { delimiter, join, relative } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import { getParser } from "@unified-latex/unified-latex-util-parse";
 import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
-import { CONFIG_FILE } from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "#lib/paper-config";
 import {
   declaredVenue,
   factsPath,
@@ -61,7 +61,8 @@ import { banalMeasurer, parseBanalSettings } from "./adapters/banal/index.ts";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import { hostDirs, nodeAdapters, nodeFiles } from "./adapters/node/index.ts";
 import { whyNoGeometry } from "./domain/geometry.ts";
-import type { AbsolutePath } from "./domain/paths.ts";
+import { callerPath } from "./caller-path.ts";
+import type { Runner } from "./engine.ts";
 import type { Files } from "./ports/files.ts";
 import type { MeasureGeometry } from "./ports/measure-geometry.ts";
 import type { CheckReferences } from "./ports/check-references.ts";
@@ -76,13 +77,16 @@ import {
 import {
   nextStep,
   summarize,
-  TRACKED,
   type BibInput,
   type Hashes,
   type Observation,
   type Step,
 } from "./latex-loop.ts";
 import type { BuildResult, PlanLine } from "./types.ts";
+import { messageOf, printed } from "./domain/text.ts";
+
+/** stdin closed, stdout and stderr captured — the tuple type spawnSync's `stdio` wants. */
+const PIPED: ["ignore", "pipe", "pipe"] = ["ignore", "pipe", "pipe"];
 
 /** A directory counts as a paper by the same markers as `structure.ts` — one shared dictionary. */
 export const PAPER_MARKERS = [
@@ -124,7 +128,7 @@ export interface PaperFacts {
 }
 
 /** A process runner with `spawnSync`'s shape — the port the harness replaces. */
-export type Runner = typeof spawnSync;
+export type { Runner };
 
 /** What a step's `run` receives. `env` is the environment accumulated by the steps before it. */
 export interface BuildContext {
@@ -282,9 +286,8 @@ function hashes(paperDir: string): Hashes {
     const p = join(paperDir, `${JOB}.${ext}`);
     return existsSync(p) ? sha(readFileSync(p)) : null;
   };
-  const out: Record<string, string | null> = {};
-  for (const t of TRACKED) out[t] = h(t);
-  return out as Hashes;
+  // A literal of the mapped type: a new tracked extension without a hash here is a compile error.
+  return { aux: h("aux"), toc: h("toc"), out: h("out"), bbl: h("bbl") };
 }
 
 const readOr = (path: string, enc: BufferEncoding): string | null =>
@@ -337,7 +340,7 @@ function spawnOptions(ctx: BuildContext) {
   return {
     cwd: ctx.paperDir,
     env: ctx.env,
-    stdio: ["ignore", "pipe", "pipe"] as ["ignore", "pipe", "pipe"],
+    stdio: PIPED,
     encoding: "latin1" as const,
     maxBuffer: 64 * 1024 * 1024,
   };
@@ -376,19 +379,23 @@ function latexPass(
       exitCode === 0
         ? []
         : written === null
-          ? printed(r)
+          ? lastPrinted(r)
           : errorExcerpt(log).map(fromLatin1),
   };
 }
 
+/** The two streams of a finished run, as they really arrive (see `printed`). */
+interface Streams {
+  readonly stdout?: string | undefined;
+  readonly stderr?: string | undefined;
+}
+
 /**
  * The last lines pdflatex printed, for the run that wrote no log — it died before opening one (a
  * format it cannot load, a missing TeX Live file). Marked by NO_LOG, which the report keys on.
  */
-function printed(r: { stdout?: unknown; stderr?: unknown }): string[] {
-  const lines = fromLatin1(
-    `${String(r.stdout ?? "")}\n${String(r.stderr ?? "")}`,
-  )
+function lastPrinted(r: Streams): string[] {
+  const lines = fromLatin1(`${printed(r.stdout)}\n${printed(r.stderr)}`)
     .split("\n")
     .filter((l) => l.trim());
   return [NO_LOG, ...lines.slice(-8).map((l) => `  ${l}`)];
@@ -410,7 +417,7 @@ function bibtexPass(ctx: BuildContext, opts: SpawnOptions): Observation | null {
     after: hashes(ctx.paperDir),
     bib,
     errorLines:
-      exitCode === 0 ? [] : bibtexExcerpt(fromLatin1(String(r.stdout ?? ""))),
+      exitCode === 0 ? [] : bibtexExcerpt(fromLatin1(printed(r.stdout))),
   };
 }
 
@@ -443,7 +450,7 @@ export function compile(ctx: BuildContext): {
 const NO_PDF = `pdflatex exited 0 but wrote no ${JOB}.pdf — does the document have any pages?`;
 
 const plural = (n: number, one: string, many: string): string =>
-  `${n} ${n === 1 ? one : many}`;
+  `${String(n)} ${n === 1 ? one : many}`;
 
 export const compileStep: BuildStep = {
   name: "compile",
@@ -467,7 +474,7 @@ export const compileStep: BuildStep = {
       const bin = end.step === "latex" ? "pdflatex" : "bibtex";
       const where =
         end.cause.kind === "exit"
-          ? `${bin} exited with ${end.cause.code}`
+          ? `${bin} exited with ${String(end.cause.code)}`
           : `${bin} did not converge`;
       const log = join(
         ctx.paperDir,
@@ -669,13 +676,14 @@ function baseDefaults({
 }
 
 /** Without a checker the record says so — never a pass. The CLI wires the real one. */
-const notWired: CheckReferences = async (_bib, cache) => ({
-  check: {
-    kind: "not-checked",
-    why: "no reference checker was wired into this build",
-  },
-  cache,
-});
+const notWired: CheckReferences = (_bib, cache) =>
+  Promise.resolve({
+    check: {
+      kind: "not-checked",
+      why: "no reference checker was wired into this build",
+    },
+    cache,
+  });
 
 /** banal as the measurer, wired from the build's environment: the one piece of root work left here (#76). */
 function defaultMeasurer(
@@ -685,7 +693,7 @@ function defaultMeasurer(
   return banalMeasurer(
     nodeAdapters({ tmpDir: dirs.tmp }),
     parseBanalSettings(b.env, dirs),
-    b.projectRoot as AbsolutePath,
+    callerPath(b.projectRoot),
   );
 }
 
@@ -762,7 +770,7 @@ export async function buildPaper(
       dir,
       status: "failed",
       plan: [],
-      failure: { step: "facts", lines: [(e as Error).message] },
+      failure: { step: "facts", lines: [messageOf(e)] },
     };
   }
   for (const s of facts.ignoredScripts)
@@ -853,7 +861,7 @@ export function formatResult(r: BuildResult): string {
 function formatFailure(r: BuildResult): string {
   const [head, ...rest] = r.failure?.lines ?? ["failed"];
   return [
-    `  ✗ ${r.failure?.step ?? "build"}: ${head}`,
+    `  ✗ ${r.failure?.step ?? "build"}: ${String(head)}`,
     ...rest.map((l) => `      ${l}`),
     `      ${PDF_REMOVED}`,
   ].join("\n");

package/src/caller-path.ts

@@ -0,0 +1,13 @@
+/**
+ * A path as a caller gave it, made absolute where it enters a `Files` call.
+ *
+ * The app's use cases take paper directories and files as strings, and some callers pass them as
+ * typed on a command line (`skills/render-paper/extract-pdf-facts.mjs <paper.pdf>`). A relative one
+ * has always meant the process's cwd — `node:fs` resolved it there. Resolving it HERE, the same way,
+ * makes the `AbsolutePath` brand a checked fact rather than an assertion: the value handed to the port
+ * is absolute, and nothing downstream has to wonder.
+ */
+import { resolve } from "node:path";
+import { absolutePath, type AbsolutePath } from "./domain/paths.ts";
+
+export const callerPath = (p: string): AbsolutePath => absolutePath(resolve(p));

package/src/cli.harness.mjs

@@ -28,8 +28,8 @@ import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { PAPERS_DIR_FIELD, findProjectRoot } from "../lib/paper-config.mjs";
-import { createChecker } from "../lib/check.mjs";
+import { PAPERS_DIR_FIELD, findProjectRoot } from "../lib/paper-config.ts";
+import { createChecker } from "../lib/check.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const { run, parseArgs, buildConfig, nextSteps, toPaths, runHook } =
@@ -635,7 +635,7 @@ check(
 
     // ── 7-bis. THE SKILLS: WHAT WAS LINKED, AND WHAT WAS LEFT ALONE, BY NAME ────────────
     //
-    // The links themselves are `link-skills.harness.mjs`'s subject. Here: init REPORTS them, and
+    // The links themselves are `link-skills.harness.ts`'s subject. Here: init REPORTS them, and
     // a name it refused to take does not turn a working install red. The state is handed in so
     // this block does not depend on a package being installed next to the temp project.
     {
@@ -967,7 +967,7 @@ check(
 
 // ── STRUCTURE GETS THROUGH TO THE COMMAND ──────────────────────────────────────────────
 //
-// `structure.mjs` is checked separately and in full (`structure.harness.mjs`). Here — exactly
+// `structure.mjs` is checked separately and in full (`structure.harness.ts`). Here — exactly
 // one fact that harness cannot know: that the module is WIRED IN. A correct module forgotten in
 // `run()` gives zero findings and looks like a clean corpus.
 {
@@ -1148,7 +1148,7 @@ check(
 //     pnpm: node_modules/vigiles/dist/cli.js  DOES NOT
 // The old wiring addressed the runtime from the project root and did not resolve under pnpm,
 // and `|| exit 2` on PreToolUse(Bash) turned that into a block on ANY command. The end-to-end
-// half (both installs, real processes) lives in `test/e2e/install.mjs`; here — the verdicts.
+// half (both installs, real processes) lives in `test/e2e/install.ts`; here — the verdicts.
 {
   const calls = [];
   const fake = (code) => (bin, args, opts) => {
@@ -1258,7 +1258,7 @@ console.log(
 
 // ─────────────────────────────────────────────────────────────────────────────
 // What is left after init is typed in THE SAME TERMINAL. The two `/plugin` lines are gone: the
-// hooks are written into `.claude/settings.json` by init itself (hooks-settings.harness.mjs).
+// hooks are written into `.claude/settings.json` by init itself (hooks-settings.harness.ts).
 
 {
   const steps = nextSteps("papers");
@@ -1711,8 +1711,6 @@ console.log(
         typo.out.includes('paperlint.json: unknown key "typographyDept"'),
     );
     settings({
-      ledger: "x.jsonl",
-      citeChecks: "c",
       timezone: "UTC",
       contactEmail: "a@b.c",
       triggerCases: "t.mjs",

package/src/cli.test.ts

@@ -9,7 +9,8 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { test } from "vitest";
-import { runNode, useTempDir, writeTree } from "../test/support.mjs";
+import { runNode, useTempDir, writeTree } from "../test/support.ts";
+import type { runToolchain } from "./toolchain.ts";
 import {
   chooseVenue,
   initTexLive,
@@ -57,6 +58,18 @@ test("parseArgs: the boolean flags of build and toolchain, and a value flag with
   );
 });
 
+test("🔴 parseSettings refuses a mistyped `structure` instead of letting `lint` crash on it", () => {
+  // Guards: `markers: 5` used to pass the boundary, and `checkStructure` then threw
+  // "rules.markers.some is not a function" from inside `paperlint lint`.
+  for (const structure of [{ markers: 5 }, "yes", { requireOneOf: ["a"] }]) {
+    const r = parseSettings({ structure }, "paperlint.json", "/r");
+    assert.equal(r.ok, false, JSON.stringify(structure));
+    assert.match(r.error, /^paperlint\.json: "structure" must be false/);
+  }
+  const off = parseSettings({ structure: false }, "paperlint.json", "/r");
+  assert.equal(off.ok && off.value.structure, false);
+});
+
 test("parseSettings refuses a non-object, names one unknown key or several, and a mistyped default", () => {
   const error = (json: unknown) => {
     const r = parseSettings(json, "paperlint.json", "/r");
@@ -146,7 +159,7 @@ test("runHook: a runtime with no cli.js beside it, and a hook killed by a signal
   });
   const killed = runHook("paper-edit-guard", {
     err: (m: string) => messages.push(m),
-    run: (() => ({ status: null, signal: "SIGKILL" })) as never,
+    run: () => ({ status: null, signal: "SIGKILL" }),
   });
   assert.deepEqual(
     { noCli, killed, messages: messages.map((m) => m.split(" from ")[0]) },
@@ -169,7 +182,12 @@ test("chooseVenue: a preset by path (inside and outside the paper), by prefixed
   const choose = (venue: string) =>
     chooseVenue(
       { venue, kind: null },
-      { paperDir, cwd: dir, interactive: false, ask: async () => "" },
+      {
+        paperDir,
+        cwd: dir,
+        interactive: false,
+        ask: () => Promise.resolve(""),
+      },
     );
   const results = await Promise.all([
     choose("./papers/p/mine.jsonc"),
@@ -354,11 +372,12 @@ test("a paper's paperlint.json that does not parse stops the lint with its path"
   });
   const r = paperRuleBlocks([join(dir, "p")]);
   assert.equal(r.ok, false);
-  assert.match(!r.ok ? r.error : "", /^.*rules-broken\/p\/paperlint\.json: /);
+  assert.match(r.error, /^.*rules-broken\/p\/paperlint\.json: /);
 });
 
 test("silentOptionalRules: a config with no rules turns nothing on", async () => {
-  assert.deepEqual(await silentOptionalRules({} as never, [], {} as never), []);
+  const eslint = { calculateConfigForFile: () => Promise.resolve(undefined) };
+  assert.deepEqual(await silentOptionalRules(eslint, [], {}), []);
 });
 
 test("init with no path and --format md sets up the current directory", async () => {
@@ -493,7 +512,9 @@ function newAtTerminal(cwd: string, answers: Record<string, string>) {
         child.stdin.write(answer);
       }
     });
-    child.on("close", (status) => done({ status, out }));
+    child.on("close", (status) => {
+      done({ status, out });
+    });
   });
 }
 
@@ -531,8 +552,8 @@ test("ownVersion: the manifest's version; an unreadable manifest or a non-string
 
 test("init's TeX Live install runs the toolchain over the project's papers, never a check", () => {
   const dir = writeTree(join(root, "init-tex"), { "package.json": "{}" });
-  const calls: unknown[] = [];
-  const fake = ((o: unknown) => (calls.push(o), 0)) as never;
+  const calls: Parameters<typeof runToolchain>[0][] = [];
+  const fake: typeof runToolchain = (o) => (calls.push(o), 0);
   const log = () => {};
   const here = initTexLive(
     parseArgs(["init"]),
@@ -546,10 +567,7 @@ test("init's TeX Live install runs the toolchain over the project's papers, neve
   );
   assert.deepEqual([here.install(), there.install()], [0, 0]);
   assert.deepEqual(
-    calls.map((c) => {
-      const o = c as { check: boolean; tex: unknown; banal: unknown };
-      return [o.check, o.tex, typeof o.banal];
-    }),
+    calls.map((c) => [c.check, c.tex, typeof c.banal]),
     [
       [false, toolchainTex(dir), "object"],
       [false, toolchainTex(join(dir, "sub")), "object"],
@@ -563,7 +581,7 @@ test("lint with its LaTeX language missing from the install still lints the mark
     "papers/p/paper.md": "# P\n\nSome prose.\n",
     "no-latex.mjs":
       "import { register } from 'node:module';\n" +
-      "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s.endsWith('latex-language.mjs')) throw Object.assign(new Error('gone'), { code: 'ERR_MODULE_NOT_FOUND' }); return next(s, c); }\"));\n",
+      "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s === '#eslint-rules/latex-language') throw Object.assign(new Error('gone'), { code: 'ERR_MODULE_NOT_FOUND' }); return next(s, c); }\"));\n",
   });
   const without = runNode(BIN, ["lint", "papers"], {
     cwd: dir,