paperlint 3.2.0 → 4.0.0

package/src/adapters/banal/settings.ts

@@ -9,7 +9,7 @@ import {
   type Environment,
   type HostDirs,
 } from "../../domain/host.ts";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath, type AbsolutePath } from "../../domain/paths.ts";
 
 /** An explicit banal to use instead of paperlint's (a path to the script). */
 export const BANAL_ENV = "BANAL";
@@ -29,7 +29,7 @@ export interface BanalSettings {
 
 /** `resolve` with an absolute base never consults the process's cwd. */
 const absolute = (cwd: string, p: string): AbsolutePath =>
-  resolve(cwd, p) as AbsolutePath;
+  absolutePath(resolve(cwd, p));
 
 /** An unset variable and an empty one mean the same: not set. */
 const set = (v: string | undefined): string | null => (v ? v : null);

package/src/adapters/curl/download.test.ts

@@ -15,18 +15,18 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { afterAll as after, test } from "vitest";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath, joinPath } from "../../domain/paths.ts";
 import { curlDownload, curlFailure } from "./download.io.ts";
 import type { ProcessExit } from "../../ports/process.ts";
 import { spawnProcess } from "../node/index.ts";
 
-const root = realpathSync(
-  mkdtempSync(join(tmpdir(), "paperlint-download-test-")),
+const root = absolutePath(
+  realpathSync(mkdtempSync(join(tmpdir(), "paperlint-download-test-"))),
 );
 after(() => {
   rmSync(root, { recursive: true, force: true });
 });
-const at = (...p: string[]) => join(root, ...p) as AbsolutePath;
+const at = (...p: string[]) => joinPath(root, ...p);
 
 const dl = (env: Record<string, string>) => {
   const tmp = at("dl-tmp");

package/src/adapters/memory/index.ts

@@ -2,7 +2,7 @@
  * In-memory adapters for the app layer's tests: every port, no disk, no processes, no network.
  * Each one RECORDS what it was asked, so a test asserts on the calls instead of on side effects.
  */
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import type { Download } from "../../ports/download.ts";
 import type { Files } from "../../ports/files.ts";
 import type { Command, ProcessExit, RunProcess } from "../../ports/process.ts";
@@ -69,11 +69,12 @@ export interface MemoryWorkspace extends Workspace {
 export function memoryWorkspace(dir = "/scratch"): MemoryWorkspace {
   const written: MemoryWorkspace["written"] = [];
   const ended: ("returned" | "threw")[] = [];
+  const at = absolutePath(dir);
   const scratch: Scratch = {
-    dir: dir as AbsolutePath,
+    dir: at,
     write(name, content, mode) {
       written.push({ name, content, mode });
-      return `${dir}/${name}` as AbsolutePath;
+      return absolutePath(`${dir}/${name}`);
     },
   };
   return {

package/src/adapters/node/files.test.ts

@@ -4,14 +4,16 @@ import { existsSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll as after, test } from "vitest";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath, joinPath } from "../../domain/paths.ts";
 import { errorCode, nodeFiles } from "./files.io.ts";
 
-const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-files-test-")));
+const root = absolutePath(
+  realpathSync(mkdtempSync(join(tmpdir(), "paperlint-files-test-"))),
+);
 after(() => {
   rmSync(root, { recursive: true, force: true });
 });
-const at = (...p: string[]) => join(root, ...p) as AbsolutePath;
+const at = (...p: string[]) => joinPath(root, ...p);
 
 test("Files: a missing file reads as null and is not a file", () => {
   assert.equal(nodeFiles.readBytes(at("nope")), null);

package/src/adapters/node/process.io.ts

@@ -11,8 +11,15 @@ import {
 } from "node:child_process";
 import type { Command, ProcessExit, RunProcess } from "../../ports/process.ts";
 
-/** Node's `spawnSync`, or a stand-in with its shape (a harness records the calls through one). */
-export type SpawnSync = typeof spawnSync;
+/**
+ * Node's `spawnSync` — the one overload this file calls, text in and text out — or a stand-in with its
+ * shape (a harness records the calls through one).
+ */
+export type SpawnSync = (
+  file: string,
+  args: readonly string[],
+  options: SpawnSyncOptionsWithStringEncoding,
+) => SpawnSyncReturns<string>;
 
 const errno = (r: SpawnSyncReturns<string>): string | undefined =>
   codeOf(r.error);

package/src/adapters/node/process.test.ts

@@ -5,7 +5,7 @@
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import type { Command } from "../../ports/process.ts";
 import { spawnProcess } from "./process.io.ts";
 
@@ -62,19 +62,19 @@ test("output past maxOutputBytes is a spawn failure, named by Node's own message
 });
 
 test("cwd is the Command's when it names one", () => {
-  const r = run.run({ ...sh("pwd"), cwd: "/" as AbsolutePath });
+  const r = run.run({ ...sh("pwd"), cwd: absolutePath("/") });
   assert.deepEqual(r.kind === "exited" && r.stdout, "/\n");
 });
 
 test("a spawn that reports no status, no signal and no error reads as exit 1, not success", () => {
-  const silent = spawnProcess((() => ({
+  const silent = spawnProcess(() => ({
     pid: 0,
     output: [],
     stdout: "",
     stderr: "",
     status: null,
     signal: null,
-  })) as never);
+  }));
   assert.deepEqual(silent.run(sh("true")), {
     kind: "exited",
     status: 1,

package/src/adapters/node/workspace.io.ts

@@ -10,14 +10,18 @@ import {
   writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import {
+  absolutePath,
+  joinPath,
+  type AbsolutePath,
+} from "../../domain/paths.ts";
 import type { NotAPromise, Scratch, Workspace } from "../../ports/workspace.ts";
 
 function scratchIn(dir: AbsolutePath): Scratch {
   return {
     dir,
     write(name, content, mode): AbsolutePath {
-      const at = join(dir, name) as AbsolutePath;
+      const at = joinPath(dir, name);
       writeFileSync(at, content);
       if (mode === "exec") chmodSync(at, 0o755);
       return at;
@@ -29,9 +33,10 @@ function scratchIn(dir: AbsolutePath): Scratch {
 export function tmpWorkspace(tmpDir: string): Workspace {
   return {
     within<T>(prefix: string, use: (s: Scratch) => NotAPromise<T>): T {
-      const dir = realpathSync(mkdtempSync(join(tmpDir, prefix)));
+      // `realpath` answers with an absolute path, whatever `tmpDir` was.
+      const dir = absolutePath(realpathSync(mkdtempSync(join(tmpDir, prefix))));
       try {
-        return use(scratchIn(dir as AbsolutePath));
+        return use(scratchIn(dir));
       } finally {
         rmSync(dir, { recursive: true, force: true });
       }

package/src/adapters/references/index.ts

@@ -44,6 +44,7 @@ import type {
   BibEntry,
 } from "../../../skills/verify-citations/scripts/bib-authors.mjs";
 import { messageOf } from "../../domain/text.ts";
+import { isRecord } from "../../domain/record.ts";
 
 const describeAuthors = (f: AuthorFinding): string =>
   [
@@ -188,12 +189,16 @@ function grown(
 ): LookupCache {
   const { cache, usable } = loaded;
   const { store, dblp } = run;
-  const fresh = Object.entries(store).filter(([k]) => !usable.citations.has(k));
+  // verify-cites stores each answer as an object; only such a value is a response the cache can hold.
+  const fresh = Object.entries(store).filter(
+    (e): e is [string, Readonly<Record<string, unknown>>] =>
+      !usable.citations.has(e[0]) && isRecord(e[1]),
+  );
   const freshDblp = [...dblp].filter(([k]) => !usable.dblp.has(k));
   if (fresh.length === 0 && freshDblp.length === 0) return cache;
   const dated = fresh.map(([k, response]): [string, CachedResponse] => [
     k,
-    { fetched: today(), response: response as CachedResponse["response"] },
+    { fetched: today(), response },
   ]);
   return {
     citations: new Map([...cache.citations, ...dated]),

package/src/build-engine.test.ts

@@ -9,6 +9,7 @@ import { dirname, join } from "node:path";
 import { test } from "vitest";
 import { useTempDir } from "../test/support.ts";
 import { prepareEngine, refusal } from "./build-engine.ts";
+import type { Runner } from "./engine.ts";
 
 const work = useTempDir("paperlint-build-engine-test-");
 const TEX = { packages: { acmart: ["acmart.cls"] }, tools: {} };
@@ -20,11 +21,12 @@ const texAt = (dir: string): string => {
   return dir;
 };
 /** kpsewhich answers per bin directory. */
-const fakeRun = (found: Record<string, string>) =>
-  ((cmd: string) => ({
+const fakeRun =
+  (found: Record<string, string>): Runner =>
+  (cmd) => ({
     stdout: found[dirname(cmd)] ?? "",
     status: 0,
-  })) as never;
+  });
 
 async function go(o: Parameters<typeof prepareEngine>[0]) {
   const out: string[] = [];
@@ -101,7 +103,10 @@ test("a complete cache is used from an environment with no PATH at all", async (
 
 test("the refusal line for a decision to use a tree names nothing missing", () => {
   assert.equal(
-    refusal({ kind: "use-cache" } as never, { system: null } as never),
+    refusal(
+      { kind: "use-cache", tree: { label: "cache", bin: "/b", missing: [] } },
+      { system: null },
+    ),
     "✗ paperlint build: no TeX Live with every package these papers need — run `npx paperlint toolchain` (missing: 0 package(s): )",
   );
 });
@@ -122,14 +127,14 @@ test("without an ask or an install given: Enter is yes, and the default install
       PAPERLINT_CTAN_MIRROR: "https://mirror.invalid/tlnet",
       PATH: join(work, "nothing"),
     },
-    run: ((cmd: string) => {
+    run: (cmd) => {
       calls.push(cmd.split("/").pop() ?? cmd);
       return {
         status: 22,
         stdout: "",
         stderr: "curl: (6) could not resolve\n",
       };
-    }) as never,
+    },
   });
   assert.deepEqual(r, { ok: false, code: 1 });
   assert.ok(calls.includes("curl"), calls.join(","));

package/src/build-engine.ts

@@ -62,10 +62,12 @@ type Resolved = Required<Omit<EngineOptions, "install">> & {
 };
 
 /** The options a caller actually set — `undefined` must still get its default, so no plain spread. */
-const defined = <T extends object>(o: T): Partial<T> =>
-  Object.fromEntries(
-    Object.entries(o).filter(([, v]) => v !== undefined),
-  ) as Partial<T>;
+function defined<T extends object>(o: T): Partial<T> {
+  const out: Partial<T> = {};
+  // `for…in` hands out `o`'s keys typed as its keys; an options literal has no inherited ones.
+  for (const k in o) if (o[k] !== undefined) out[k] = o[k];
+  return out;
+}
 
 function withDefaults(o: EngineOptions): Resolved {
   const r = {
@@ -133,7 +135,10 @@ const names = (missing: readonly string[]): string =>
   `${String(missing.length)} package(s): ${missing.join(", ")}`;
 
 /** The one line a run without a human gets. It names the command and what is missing. */
-export function refusal(d: EngineDecision, facts: EngineFacts): string {
+export function refusal(
+  d: EngineDecision,
+  facts: Pick<EngineFacts, "system">,
+): string {
   const missing = d.kind === "refuse" || d.kind === "ask" ? d.missing : [];
   const sys =
     facts.system && facts.system.missing.length

package/src/build.test.ts

@@ -8,7 +8,7 @@ import assert from "node:assert/strict";
 import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { test } from "vitest";
-import { useTempDir, writeTree } from "../test/support.ts";
+import { present, useTempDir, writeTree } from "../test/support.ts";
 import {
   bibInput,
   buildPaper,
@@ -64,16 +64,16 @@ function bibtexRun(f: Fake, cwd: string) {
 }
 function fakeRun(f: Fake): NonNullable<BuildOptions["run"]> {
   let pass = 0;
-  return ((bin: string, _args: string[], opts: { cwd: string }) => {
+  return (bin, _args, opts) => {
     if (bin === f.missing)
       return {
         error: Object.assign(new Error("spawn ENOENT"), { code: "ENOENT" }),
         status: null,
       };
-    return bin === "pdflatex"
-      ? latexPass(f, opts.cwd, ++pass)
-      : bibtexRun(f, opts.cwd);
-  }) as never;
+    // The build always runs a pass in the paper's directory.
+    const cwd = present(opts.cwd, "the pass's cwd");
+    return bin === "pdflatex" ? latexPass(f, cwd, ++pass) : bibtexRun(f, cwd);
+  };
 }
 
 const NO_GEOMETRY: Geometry = {
@@ -146,11 +146,10 @@ test("documentclass: an empty name is no class; a macro inside the name contribu
   // `\documentclass` came back bare has no name to read, and is no class.
   assert.equal(
     parseDocumentclass("\\documentclass", {
-      parse: () =>
-        ({
-          type: "root",
-          content: [{ type: "macro", content: "documentclass" }],
-        }) as never,
+      parse: () => ({
+        type: "root",
+        content: [{ type: "macro", content: "documentclass" }],
+      }),
     }),
     null,
   );

package/src/build.ts

@@ -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,7 +77,6 @@ import {
 import {
   nextStep,
   summarize,
-  TRACKED,
   type BibInput,
   type Hashes,
   type Observation,
@@ -128,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 {
@@ -286,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 =>
@@ -387,8 +386,8 @@ function latexPass(
 
 /** The two streams of a finished run, as they really arrive (see `printed`). */
 interface Streams {
-  readonly stdout: string | undefined;
-  readonly stderr: string | undefined;
+  readonly stdout?: string | undefined;
+  readonly stderr?: string | undefined;
 }
 
 /**
@@ -694,7 +693,7 @@ function defaultMeasurer(
   return banalMeasurer(
     nodeAdapters({ tmpDir: dirs.tmp }),
     parseBanalSettings(b.env, dirs),
-    b.projectRoot as AbsolutePath,
+    callerPath(b.projectRoot),
   );
 }
 

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

@@ -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

@@ -10,6 +10,7 @@ import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { test } from "vitest";
 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]) },
@@ -363,7 +376,8 @@ test("a paper's paperlint.json that does not parse stops the lint with its path"
 });
 
 test("silentOptionalRules: a config with no rules turns nothing on", async () => {
-  assert.deepEqual(await silentOptionalRules({} 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 () => {
@@ -538,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"]),
@@ -553,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"],