paperlint 3.1.3 → 4.0.0

package/src/cli.ts

@@ -30,7 +30,8 @@ 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.
+import { z } from "zod";
+// Types come from consumer.d.mts beside it.
 import {
   isMain,
   packageVenuesDir,
@@ -96,43 +97,39 @@ 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,
   shippedRuleIds,
   unknownKeys,
   type Parsed,
+  type ConfigBlock,
   type RuleBlock,
   type RuleEntry,
 } from "./rules-config.ts";
 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";
+import { isRecord } from "./domain/record.ts";
 
 /** The shipped venue presets, read from the package's venues directory — the one list. */
 const SHIPPED_VENUES = (): string[] => shippedPresets(packageVenuesDir());
@@ -226,7 +223,7 @@ settings — paperlint.json, at two levels, one schema. Both are optional.
 export function buildConfig(
   opts: PaperlintConfig = {},
   texLanguage: unknown,
-): unknown[] {
+): ConfigBlock[] {
   const paperRules = { ...researchQuestion.rules, ...typography.rules };
   // The reference rules judge `_build/references.json`, and only on `paper.tex`.
   const texPaperRules = {
@@ -244,8 +241,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: ConfigBlock[] = [
     // 🔴 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
@@ -336,6 +332,21 @@ export function buildConfig(
   return cfg;
 }
 
+/**
+ * paperlint's blocks as ESLint's config type — the one place the two meet. ESLint types a plugin's
+ * rule as one that runs on ANY language; paperlint's run on the language they were written for, so
+ * no static proof that a block fits exists (`ConfigBlock`, rules-config.ts). ESLint checks every block
+ * when it loads the config and throws on one it cannot use; what is left to check here is that each
+ * is an object.
+ */
+const isEslintBlock = (b: unknown): b is Linter.Config =>
+  typeof b === "object" && b !== null;
+
+export function eslintConfig(blocks: readonly ConfigBlock[]): Linter.Config[] {
+  const loose: readonly unknown[] = blocks;
+  return loose.filter(isEslintBlock);
+}
+
 /**
  * The rule ids a consumer may name in `rules`: every rule paperlint's own config defines, read off that
  * config rather than listed again. `@eslint/markdown` is a dependency's plugin, not paperlint's.
@@ -364,9 +375,7 @@ export interface RulePlugin {
 export function rulePlugins(texLanguage?: unknown): Record<string, RulePlugin> {
   const out: Record<string, { rules: Record<string, unknown> }> = {};
   for (const block of buildConfig({}, texLanguage ?? { sentinel: "tex" }))
-    for (const [name, plugin] of Object.entries(
-      (block as { plugins?: Record<string, RulePlugin> }).plugins ?? {},
-    ))
+    for (const [name, plugin] of Object.entries(block.plugins ?? {}))
       if (plugin !== markdown)
         out[name] = { rules: { ...out[name]?.rules, ...plugin.rules } };
   if (out["tex"] && texLanguage !== undefined)
@@ -389,10 +398,10 @@ export function rulePlugins(texLanguage?: unknown): Record<string, RulePlugin> {
  * switched off in THIS run — `paperlint lint` still reports a directive that silences nothing.
  */
 export function rulesOff(texLanguage?: unknown): Linter.Config[] {
-  return [
+  return eslintConfig([
     {
       name: "paperlint/rules-off",
-      plugins: rulePlugins(texLanguage) as Linter.Config["plugins"],
+      plugins: rulePlugins(texLanguage),
       rules: Object.fromEntries([...SHIPPED_RULES].map((id) => [id, "off"])),
     },
     {
@@ -400,12 +409,12 @@ export function rulesOff(texLanguage?: unknown): Linter.Config[] {
       files: PAPER_FILE_PATTERNS,
       linterOptions: { reportUnusedDisableDirectives: "off" },
     },
-  ];
+  ]);
 }
 
 /** 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;
 };
 
@@ -417,7 +426,7 @@ export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
   [...SHIPPED_RULES].filter(
     (id) =>
       !buildConfig({}, { sentinel: "tex language" }).some((b) =>
-        isOn((b as { rules?: Record<string, unknown> }).rules?.[id]),
+        isOn(b.rules?.[id]),
       ),
   ),
 );
@@ -434,8 +443,13 @@ export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
  * papers a and b (#103) — a block that reaches a paper outside this run is not dead. A glob that
  * reaches no paper of the project at all still fails, from a subset as from the whole.
  */
+/** What `calculateConfigForFile` answers, read for its rules: undefined for a file outside ESLint's cwd or scope. */
+const ComputedConfig = z
+  .object({ rules: z.record(z.string(), z.unknown()).optional() })
+  .optional();
+
 export async function silentOptionalRules(
-  eslint: ESLint,
+  eslint: Pick<ESLint, "calculateConfigForFile">,
   files: readonly string[],
   opts: PaperlintConfig,
 ): Promise<string[]> {
@@ -449,8 +463,7 @@ export async function silentOptionalRules(
   const reached = new Set<string>();
   for (const f of new Set(files.filter((p) => basename(p) === MAIN))) {
     // Undefined for a file outside ESLint's cwd or scope: it reaches nothing.
-    const cfg = (await eslint.calculateConfigForFile(f)) as
-      { rules?: Record<string, unknown> } | undefined;
+    const cfg = ComputedConfig.parse(await eslint.calculateConfigForFile(f));
     for (const id of turnedOn) if (isOn(cfg?.rules?.[id])) reached.add(id);
   }
   return [...turnedOn].filter((id) => !reached.has(id));
@@ -470,7 +483,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")
@@ -545,6 +561,20 @@ const PAPER_FILE_PATTERNS: string[] = ownedPatterns(
   buildConfig({}, { sentinel: "tex language" }),
 );
 
+/** `structure` as `checkStructure` reads it: off, or lists of file names over the defaults. */
+const Names = z.array(z.string()).exactOptional();
+const Structure = z
+  .union([
+    z.literal(false),
+    z.object({
+      markers: Names,
+      require: Names,
+      requireOneOf: z.array(z.array(z.string())).exactOptional(),
+      ignore: Names,
+    }),
+  ])
+  .optional();
+
 /**
  * The root `paperlint.json` after the boundary: an unknown key is refused by name, the paper
  * defaults (`extends`, `kind`, `pdf`) are checked the way a paper's own are, and `rules` becomes
@@ -555,10 +585,9 @@ export function parseSettings(
   where: string,
   baseDir: string,
 ): Parsed<PaperlintConfig> {
-  if (typeof json !== "object" || json === null || Array.isArray(json))
+  if (!isRecord(json))
     return { ok: false, error: `${where}: must be a JSON object` };
-  const raw = json as Record<string, unknown>;
-  const opts = raw as PaperlintConfig;
+  const raw = json;
   const unknown = unknownKeys(raw);
   if (unknown.length > 0)
     return {
@@ -569,9 +598,22 @@ export function parseSettings(
     };
   const defaults = stringFields(raw);
   if (!defaults.ok) return { ok: false, error: `${where}: ${defaults.error}` };
+  const structure = Structure.safeParse(raw["structure"]);
+  if (!structure.success)
+    return {
+      ok: false,
+      error: `${where}: "structure" must be false, or an object whose markers, require and ignore are lists of file names and requireOneOf a list of such lists`,
+    };
   const rules = parseRuleBlocks(raw["rules"], where, SHIPPED_RULES, baseDir);
   if (!rules.ok) return rules;
-  return { ok: true, value: { ...opts, rules: rules.value } };
+  return {
+    ok: true,
+    value: {
+      papersDir: raw[PAPERS_DIR_FIELD],
+      structure: structure.data,
+      rules: rules.value,
+    },
+  };
 }
 
 /**
@@ -701,8 +743,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 +794,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
@@ -767,7 +814,7 @@ export function readConfig(
 
 /** The papers directory field of the settings, read by its one declared name; the default when absent. */
 export function papersDirOf(opts: PaperlintConfig): unknown {
-  const declared = (opts as Record<string, unknown>)[PAPERS_DIR_FIELD];
+  const declared = opts.papersDir;
   return declared === undefined ? DEFAULT_PAPERS_ROOT : declared;
 }
 
@@ -787,7 +834,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 [];
 }
 
@@ -834,7 +883,12 @@ export function runHook(
       createRequire(import.meta.url).resolve(spec),
   }: {
     err?: typeof console.error;
-    run?: typeof spawnSync;
+    /** Runs the hook with the terminal's streams: `spawnSync` is one, and only its status is read. */
+    run?: (
+      file: string,
+      args: readonly string[],
+      options: { readonly stdio: "inherit" },
+    ) => { readonly status: number | null };
     resolve?: (spec: string) => string;
   } = {},
 ): number {
@@ -1453,8 +1507,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;
   }
@@ -1462,7 +1515,7 @@ export async function run(
   const eslint = new ESLint({
     cwd: lintRoot(root, paths),
     overrideConfigFile: true,
-    overrideConfig: buildConfig(withPapers, texLanguage) as Linter.Config[],
+    overrideConfig: eslintConfig(buildConfig(withPapers, texLanguage)),
     fix: a.fix,
   });
 
@@ -1478,8 +1531,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) {
@@ -1540,12 +1592,20 @@ async function firstUnownedFile(
  * is outside paperlint's scope (`all-matched-files-ignored` — a papers directory holding only
  * vendored scripts). Both mean "nothing was linted", which the caller reports itself.
  */
+/** What a thrown ESLint error says about itself; anything else thrown says nothing. */
+const EslintFailure = z
+  .object({
+    messageTemplate: z.string().optional(),
+    message: z.string().optional(),
+  })
+  .catch({});
+
 const isEmptySet = (e: unknown): boolean => {
-  const fail = e as { messageTemplate?: string; message?: string } | null;
+  const fail = EslintFailure.parse(e);
   return (
-    fail?.messageTemplate === "file-not-found" ||
-    fail?.messageTemplate === "all-matched-files-ignored" ||
-    /No files matching/i.test(String(fail?.message))
+    fail.messageTemplate === "file-not-found" ||
+    fail.messageTemplate === "all-matched-files-ignored" ||
+    /No files matching/i.test(String(fail.message))
   );
 };
 
@@ -1555,8 +1615,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 +1657,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 +1667,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.test.ts

@@ -44,7 +44,7 @@ test("doctor: a settings file silent on papersDir, an occupied entry, an unreada
   const code = doctor({
     cwd: root,
     log: (s: string) => lines.push(s),
-    run: (() => ({ status: 0 })) as never,
+    run: () => ({ status: 0 }),
     cliPapers: join(root, "papers"),
     skillLinks: () => ({
       ok: true,

package/src/doctor.ts

@@ -36,6 +36,8 @@ 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";
+import { fieldOf } from "./domain/record.ts";
 
 export interface Program {
   readonly bin: string;
@@ -98,7 +100,17 @@ export const PROGRAMS: readonly Program[] = [
   },
 ];
 
-export const found = (bin: string, run = spawnSync): boolean =>
+/**
+ * Asks the shell whether a program is on PATH. `spawnSync` is one; a fake answers with a status
+ * alone, because a status is all `found` reads.
+ */
+export type ProgramProbe = (
+  file: string,
+  args: readonly string[],
+  options: { readonly shell: true; readonly stdio: "ignore" },
+) => { readonly status: number | null };
+
+export const found = (bin: string, run: ProgramProbe = spawnSync): boolean =>
   run("command", ["-v", bin], { shell: true, stdio: "ignore" }).status === 0;
 
 /** Lists a directory's entries; the disk by default, a test stages an unreadable child. */
@@ -169,15 +181,13 @@ 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,
     };
   }
-  const declared = (settings as Record<string, unknown> | null)?.[
-    PAPERS_DIR_FIELD
-  ];
+  const declared = fieldOf(settings, PAPERS_DIR_FIELD);
   return {
     lines: [
       declared === undefined
@@ -233,7 +243,7 @@ export interface DoctorOptions {
   cwd?: string;
   /** The project root the hooks are anchored to. Claude Code sets this; it defaults to `cwd`. */
   projectDir?: string;
-  run?: typeof spawnSync;
+  run?: ProgramProbe;
   /** The directory the CLI resolved from its own config, so both sides can be compared. */
   cliPapers?: string | null;
   /** Reads the skill links without writing any. Injected only so a test can fake the install. */
@@ -334,7 +344,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/paths.test.ts

@@ -0,0 +1,15 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { absolutePath, joinPath } from "./paths.ts";
+
+test("absolutePath keeps an absolute path as it is", () => {
+  assert.equal(absolutePath("/a/b"), "/a/b");
+});
+
+test("absolutePath refuses a relative path instead of letting the process's cwd decide it", () => {
+  assert.throws(() => absolutePath("a/b"), /not an absolute path: a\/b/);
+});
+
+test("joinPath stays under its absolute base", () => {
+  assert.equal(joinPath(absolutePath("/a"), "b", "c"), "/a/b/c");
+});

package/src/domain/paths.ts

@@ -1,5 +1,24 @@
 /** Paths as the domain holds them. */
+import { isAbsolute, join } from "node:path";
 import type { Opaque } from "ts-essentials";
 
-/** An absolute path. Minted at the composition root (`abs`), so nothing inside resolves a cwd. */
+/**
+ * An absolute path. Minted by `absolutePath` (a checked string) or `joinPath` (an absolute base and
+ * segments) only, so nothing holding one has to ask whether it is relative.
+ */
 export type AbsolutePath = Opaque<string, "AbsolutePath">;
+
+// The brand's one owner: the predicate IS the check, so no assertion is needed to mint the type.
+const isAbsolutePath = (p: string): p is AbsolutePath => isAbsolute(p);
+
+/** A path the caller holds as text, checked where it becomes a value. A relative one throws. */
+export function absolutePath(p: string): AbsolutePath {
+  if (!isAbsolutePath(p)) throw new Error(`not an absolute path: ${p}`);
+  return p;
+}
+
+/** `segments` under `base`: absolute because `base` is. */
+export const joinPath = (
+  base: AbsolutePath,
+  ...segments: string[]
+): AbsolutePath => absolutePath(join(base, ...segments));

package/src/domain/ready.ts

@@ -0,0 +1,31 @@
+/** A program `paperlint toolchain` installed or found: present, verified, running. */
+
+// Not exported: a `Ready` carries this property, and the one way to write it is `ready` below.
+const READY = Symbol("Ready");
+
+/**
+ * Present, verified, running. BRANDED: a literal `{ where, fresh, verified }` is not a `Ready`, so
+ * only an installer's adapter — one minting call each (banal's is `ready` in
+ * `adapters/banal/index.ts`) — can make one, and a ready line cannot be printed without it.
+ */
+export interface Ready {
+  /** Where it is: the program's path or its bin directory. */
+  readonly where: string;
+  /** This run installed it. */
+  readonly fresh: boolean;
+  /** What was checked before calling it ready, as a person reads it. */
+  readonly verified: string;
+  readonly [READY]: true;
+}
+
+/** An installer's verdict that its program is ready. Called by an installer adapter, after its checks. */
+export const ready = (r: {
+  readonly where: string;
+  readonly fresh: boolean;
+  readonly verified: string;
+}): Ready => ({
+  where: r.where,
+  fresh: r.fresh,
+  verified: r.verified,
+  [READY]: true,
+});

package/src/domain/record.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { fieldOf, isRecord, numbersOf } from "./record.ts";
+
+test("isRecord: an object, and not null, an array or a string", () => {
+  assert.deepEqual(
+    [isRecord({}), isRecord(null), isRecord([]), isRecord("x")],
+    [true, false, false, false],
+  );
+});
+
+test("fieldOf reads an own or inherited field of a record, and nothing of anything else", () => {
+  assert.equal(fieldOf({ a: 1 }, "a"), 1);
+  assert.equal(fieldOf(new TypeError("x"), "name"), "TypeError");
+  assert.equal(fieldOf("text", "length"), undefined);
+});
+
+test("numbersOf keeps numbers as they are", () => {
+  assert.deepEqual(numbersOf([1, -0.5, 0]), [1, -0.5, 0]);
+});