paperlint 3.1.2 → 3.2.0

package/src/{structure.harness.mjs → structure.harness.ts}

@@ -15,18 +15,27 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { z } from "zod";
+import { createChecker } from "../lib/check.ts";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
+/** `asEslintResults` promises only `unknown[]`; these are the fields the checks read. */
+const EslintResults = z.array(
+  z.object({
+    errorCount: z.number(),
+    warningCount: z.number(),
+    messages: z.array(
+      z.object({ ruleId: z.string().nullable(), severity: z.number() }),
+    ),
+  }),
+);
 const { checkStructure, formatStructure, asEslintResults, STRUCTURE_DEFAULTS } =
-  await import(join(HERE, "structure.ts"));
+  await import("./structure.ts");
 
 const check = createChecker();
 
 const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-struct-")));
 const papers = join(root, "papers");
-const paper = (name, files) => {
+const paper = (name: string, files: readonly string[]) => {
   const dir = join(papers, name);
   mkdirSync(dir, { recursive: true });
   for (const f of files) {
@@ -50,7 +59,7 @@ try {
   writeFileSync(join(papers, ".hidden", "paper.tex"), "x");
 
   const f = checkStructure([papers], undefined, { cwd: root });
-  const at = (name) => f.filter((x) => x.file.endsWith(name));
+  const at = (name: string) => f.filter((x) => x.file.endsWith(name));
 
   check(
     "a complete paper directory — NOT A SINGLE finding",
@@ -63,24 +72,26 @@ try {
   check(
     "a missing scorecard — a finding",
     at("no-scorecard").length === 1 &&
-      /missing `PIPELINE-STATUS\.md`/.test(at("no-scorecard")[0].message),
+      /missing `PIPELINE-STATUS\.md`/.test(
+        at("no-scorecard")[0]?.message ?? "",
+      ),
   );
   check(
     "and the message names the CONSEQUENCE, not a restatement of the condition",
-    /are skipped/.test(at("no-scorecard")[0].message) &&
+    /are skipped/.test(at("no-scorecard")[0]?.message ?? "") &&
       /stage, source and research-question checks/.test(
-        at("no-scorecard")[0].message,
+        at("no-scorecard")[0]?.message ?? "",
       ),
   );
   check(
     "and the consequence names THIS directory by name",
-    /no-scorecard/.test(at("no-scorecard")[0].message),
+    /no-scorecard/.test(at("no-scorecard")[0]?.message ?? ""),
   );
   check(
     "a directory with no source — a finding, and BOTH accepted forms are listed",
     at("no-source").length === 1 &&
-      /`paper\.tex`/.test(at("no-source")[0].message) &&
-      /`paper\.md`/.test(at("no-source")[0].message),
+      /`paper\.tex`/.test(at("no-source")[0]?.message ?? "") &&
+      /`paper\.md`/.test(at("no-source")[0]?.message ?? ""),
   );
 
   // 🔴 THE PAIRED HALF: detection is GENEROUS. Without this the check would scream about every
@@ -136,7 +147,7 @@ try {
   );
 
   // ── one schema for both halves ────────────────────────────────────────────────────────
-  const asResults = asEslintResults(f);
+  const asResults = EslintResults.parse(asEslintResults(f));
   check(
     "findings come back shaped like an ESLint result — `--json` stays one array",
     asResults.length === 2 &&
@@ -144,7 +155,7 @@ try {
         (r) =>
           r.errorCount === 1 &&
           r.warningCount === 0 &&
-          r.messages[0].ruleId === "structure/required-file" &&
+          r.messages[0]?.ruleId === "structure/required-file" &&
           r.messages[0].severity === 2,
       ),
   );
@@ -156,7 +167,7 @@ try {
         { require: ["PIPELINE-STATUS.md", "refs.bib"] },
         { cwd: root },
       ).filter((x) => x.file.endsWith("no-source"));
-      return asEslintResults(two)[0].errorCount === 2;
+      return EslintResults.parse(asEslintResults(two))[0]?.errorCount === 2;
     })(),
   );
   check(

package/src/structure.ts

@@ -25,7 +25,7 @@
 import { readdirSync, existsSync } from "node:fs";
 import { join, relative, basename, isAbsolute, sep } from "node:path";
 import type { StructureConfig, StructureFinding } from "./types.ts";
-import { CONFIG_FILE } from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "#lib/paper-config";
 
 /** The requirements after the consumer's config is laid over the defaults. */
 type Rules = Required<StructureConfig>;

package/src/{tex-requirements.harness.mjs → tex-requirements.harness.ts}

@@ -13,12 +13,14 @@ import {
   readFileSync,
   realpathSync,
   rmSync,
+  writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import ts from "typescript";
-import { createChecker } from "../lib/check.mjs";
+import { z } from "zod";
+import { createChecker } from "../lib/check.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const VENUES = join(
@@ -29,18 +31,18 @@ const VENUES = join(
   "references",
   "venues",
 );
-const R = await import(join(HERE, "tex-requirements.ts"));
+const R = await import("./tex-requirements.ts");
 
 const check = createChecker();
-const throws = (fn) => {
+const throws = (fn: () => unknown): string => {
   try {
     fn();
     return "";
   } catch (e) {
-    return e.message;
+    return e instanceof Error ? e.message : String(e);
   }
 };
-const read = (f) =>
+const read = (f: string) =>
   R.parseProfile(readFileSync(join(VENUES, f), "utf8"), f, VENUES);
 
 // ── 1. the shipped data ─────────────────────────────────────────────────────────────────
@@ -69,11 +71,14 @@ check(
 );
 
 // The whole profile, parsed the way the other harnesses read these files — never a line of text.
-const templateOf = (v) =>
-  ts.parseConfigFileTextToJson(
-    v,
-    readFileSync(join(VENUES, `${v}.jsonc`), "utf8"),
-  ).config.template;
+const TemplateField = z.object({ template: z.unknown().optional() });
+const templateOf = (v: string): unknown =>
+  TemplateField.parse(
+    ts.parseConfigFileTextToJson(
+      v,
+      readFileSync(join(VENUES, `${v}.jsonc`), "utf8"),
+    ).config,
+  ).template;
 const acm = venues.filter((v) => templateOf(v) === "acmart");
 check(
   "at least one acmart venue is shipped (else the next checks see nothing)",
@@ -92,7 +97,7 @@ for (const v of acm) {
     // minimal one.
     ["fancyhdr", "fancyhdr.sty"],
     ["acmart", "acmart.cls"],
-  ])
+  ] satisfies [string, string][])
     check(
       `🔴 ${v}: declares ${pkg}, proved by ${file}`,
       tex.packages[pkg]?.includes(file),
@@ -102,22 +107,39 @@ for (const v of acm) {
 // dictionaries diverged. Since the ACM venues extend the `acm-sigconf` family, only the family
 // declares the template's packages, so this holds by construction; the check stays for any two
 // standalone presets that name the same template.
-const byTemplate = new Map();
+const byTemplate = new Map<unknown, string[]>();
 for (const v of venues) {
   const t = templateOf(v);
   byTemplate.set(t, [...(byTemplate.get(t) ?? []), v]);
 }
 for (const [t, vs] of byTemplate)
   check(
-    `venues on template ${t} declare the SAME packages (${vs.join(", ")})`,
+    `venues on template ${String(t)} declare the SAME packages (${vs.join(", ")})`,
     new Set(vs.map((v) => JSON.stringify(read(`${v}.jsonc`)))).size === 1,
   );
 
+// A venues directory whose schema file is JSON but not a schema: refused where it is read, with
+// the file's name — not deep inside Ajv as "schema should be object or boolean".
+{
+  const odd = realpathSync(
+    mkdtempSync(join(tmpdir(), "paperlint-texreq-schema-")),
+  );
+  writeFileSync(join(odd, R.SCHEMA_FILE), "3\n");
+  check(
+    "a schema file that is not a JSON object is refused, naming the file",
+    new RegExp(
+      `${R.SCHEMA_FILE.replace(/\./g, "\\.")}: not a JSON Schema object`,
+    ).test(throws(() => R.parsePreset("{}", "odd.jsonc", odd))),
+    throws(() => R.parsePreset("{}", "odd.jsonc", odd)),
+  );
+}
+
 // ── 2. the schema rejects ───────────────────────────────────────────────────────────────
 const tmp = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-texreq-h-")));
 copyFileSync(join(VENUES, R.SCHEMA_FILE), join(tmp, R.SCHEMA_FILE));
-const bad = (text) => throws(() => R.parseProfile(text, "bad.jsonc", tmp));
-const BAD = [
+const bad = (text: string) =>
+  throws(() => R.parseProfile(text, "bad.jsonc", tmp));
+const BAD: [string, string, string][] = [
   ["no `tex` block at all", `{ "template": "acmart" }`, "tex"],
   // Guards: typo detection — `templat` would be accepted and the field silently unread.
   [
@@ -181,13 +203,12 @@ rmSync(tmp, { recursive: true, force: true });
 // Which preset a paper resolves to — a typo, the base file, a missing one — is src/presets.ts's
 // question now, tested in src/presets.test.ts; this function only adds a resolved preset's packages.
 {
-  const r = R.requirementsFor(
-    { label: acm[0], tex: read(`${acm[0]}.jsonc`) },
-    VENUES,
-  );
+  // `acm` is non-empty: the check above it throws otherwise.
+  const [label = ""] = acm;
+  const r = R.requirementsFor({ label, tex: read(`${label}.jsonc`) }, VENUES);
   check(
     "a resolved preset → its packages ON TOP OF the base set, and the source names its label",
-    r.source === `venue ${acm[0]}` &&
+    r.source === `venue ${label}` &&
       "acmart" in r.tex.packages &&
       "hyperref" in r.tex.packages &&
       "texcount" in r.tex.tools,
@@ -251,9 +272,16 @@ rmSync(tmp, { recursive: true, force: true });
     "violations: Ajv's null `errors` is no violation; a message Ajv left out is an empty one",
     R.violations("f.jsonc", { errors: null }).length === 0 &&
       R.violations("f.jsonc", {
-        errors: [{ dataPath: "", message: undefined }],
+        errors: [
+          {
+            keyword: "required",
+            dataPath: "",
+            schemaPath: "#/required",
+            params: {},
+          },
+        ],
       })[0] === "f.jsonc: (top level) ",
   );
 }
 
-console.log(`tex-requirements: ${check.count} checks passed`);
+console.log(`tex-requirements: ${String(check.count)} checks passed`);

package/src/tex-requirements.ts

@@ -26,7 +26,7 @@ import { join } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import Ajv from "ajv";
 import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
-import { CONFIG_FILE } from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "#lib/paper-config";
 
 /** CTAN package name → the names that prove it is installed. */
 export type PackageProofs = Readonly<Record<string, readonly string[]>>;
@@ -64,9 +64,10 @@ const validators = new Map<string, Validate>();
 function validatorFor(dir: string): Validate {
   const known = validators.get(dir);
   if (known) return known;
-  const schema: object = JSON.parse(
-    readFileSync(join(dir, SCHEMA_FILE), "utf8"),
-  );
+  const path = join(dir, SCHEMA_FILE);
+  const schema: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (typeof schema !== "object" || schema === null)
+    throw new Error(`${path}: not a JSON Schema object`);
   const v = new Ajv({ allErrors: true }).compile(schema);
   validators.set(dir, v);
   return v;
@@ -214,7 +215,9 @@ export function parsePreset(
   file: string,
   dir: string = packageVenuesDir(),
 ): PresetFile {
-  const { config, error } = typescript().parseConfigFileTextToJson(file, text);
+  const parsed = typescript().parseConfigFileTextToJson(file, text);
+  const config: unknown = parsed.config;
+  const error = parsed.error;
   if (error)
     throw new Error(
       `${file}: not valid JSONC — ${typescript().flattenDiagnosticMessageText(error.messageText, " ")}`,

package/src/toolchain.harness.mjs

@@ -6,7 +6,7 @@
  * inside is `fixtures/toolchain-mirror/install-tl`, which lays out a tree whose `kpsewhich` and
  * `tlmgr` answer from two text files. So what runs is paperlint's own download, fallback, unpack,
  * install and verify logic — the part that decides success — and what is faked is only TeX.
- * The real TeX Live half is `test/e2e/toolchain.mjs`.
+ * The real TeX Live half is `test/e2e/toolchain.ts`.
  *
  * Tables, in order:
  *   1. the pure pieces (year, profile, tlmgr's unknown names, cache location);
@@ -32,7 +32,7 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { createChecker } from "../lib/check.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const FIXTURE = join(HERE, "..", "fixtures", "toolchain-mirror");

package/src/toolchain.test.ts

@@ -9,7 +9,7 @@ import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { join } from "node:path";
 import { test } from "vitest";
-import { useTempDir, writeTree } from "../test/support.mjs";
+import { useTempDir, writeTree } from "../test/support.ts";
 import {
   cachedTrees,
   CACHE_ENV,

package/src/toolchain.ts

@@ -56,6 +56,10 @@ import {
   packageNames,
   type TexRequirements,
 } from "./tex-requirements.ts";
+import { 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"];
 
 export const CACHE_ENV = "PAPERLINT_TEXLIVE_DIR";
 export const MIRROR_ENV = "PAPERLINT_CTAN_MIRROR";
@@ -274,23 +278,29 @@ export function describeGaps(g: Gaps, tex: TexRequirements): string {
 export function formatDuration(ms: number): string {
   const s = Math.round(ms / 1000);
   return s < 60
-    ? `${s}s`
-    : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
+    ? `${String(s)}s`
+    : `${String(Math.floor(s / 60))}m${String(s % 60).padStart(2, "0")}s`;
 }
 
 // ── processes ────────────────────────────────────────────────────────────────────────
 
 const quiet = (io: ToolchainIO, timeout?: number) => ({
   encoding: "utf8" as const,
-  stdio: ["ignore", "pipe", "pipe"] as ["ignore", "pipe", "pipe"],
+  stdio: PIPED,
   env: io.env,
   maxBuffer: 64 * 1024 * 1024,
   ...(timeout ? { timeout } : {}),
 });
 
 /** The last lines a process printed — what a failure shows. */
-function tail(r: ReturnType<Runner>, n = 12): string[] {
-  const text = `${String(r.stdout ?? "")}\n${String(r.stderr ?? "")}`;
+function tail(
+  r: {
+    readonly stdout: string | undefined;
+    readonly stderr: string | undefined;
+  },
+  n = 12,
+): string[] {
+  const text = `${printed(r.stdout)}\n${printed(r.stderr)}`;
   return text
     .split("\n")
     .filter((l) => l.trim())
@@ -475,13 +485,15 @@ export function installPackages(
     if (noGaps(gaps)) break;
     const want = [...gaps.packages, ...gaps.tools, ...gaps.dependencies];
     const repairsBase = gaps.dependencies.length > 0;
-    io.log(`  tlmgr: installing ${want.length} package(s) from ${mirror}…`);
+    io.log(
+      `  tlmgr: installing ${String(want.length)} package(s) from ${mirror}…`,
+    );
     const r = io.run(
       join(tree.bin, "tlmgr"),
       ["--repository", mirror, "install", ...want],
       quiet(io, TLMGR_MS),
     );
-    const output = `${String(r.stdout ?? "")}\n${String(r.stderr ?? "")}`;
+    const output = `${printed(r.stdout)}\n${printed(r.stderr)}`;
     // A new release: every mirror serves it, so trying the next one only repeats the refusal.
     const newer = releaseGap(output);
     if (newer) return { ok: false, newer };
@@ -567,7 +579,7 @@ export function ensureTexLive(
   if (!verified.ok) return fail(o.err, verified.lines);
   o.log(
     `✓ TeX Live ${used.year} is ready in ${used.dir}: ${verified.value} ` +
-      `${sizeMB(used.dir)} MB, ${formatDuration(o.now() - started)}`,
+      `${String(sizeMB(used.dir))} MB, ${formatDuration(o.now() - started)}`,
   );
   o.log(binLine(used));
   if (used !== tree.value) o.log(leftInPlace(tree.value));
@@ -638,14 +650,14 @@ function verify(
   return {
     ok: true,
     value:
-      `${packageNames(tex).length} packages verified ` +
-      `(${files} files found by kpsewhich, ${Object.keys(tex.tools).length} tools),`,
+      `${String(packageNames(tex).length)} packages verified ` +
+      `(${String(files)} files found by kpsewhich, ${String(Object.keys(tex.tools).length)} tools),`,
   };
 }
 
 /** The superseded tree is named, with the space it holds — and left alone. */
 export const leftInPlace = (old: CachedTree): string =>
-  `  TeX Live ${old.year} in ${old.dir} is left in place and no longer used (${sizeMB(old.dir)} MB); ` +
+  `  TeX Live ${old.year} in ${old.dir} is left in place and no longer used (${String(sizeMB(old.dir))} MB); ` +
   `delete that directory to free the space`;
 
 /**
@@ -693,14 +705,14 @@ function report(o: Resolved, tree: CachedTree | null): number {
   const n = packageNames(o.tex).length;
   if (!tree) {
     o.log(
-      `✗ no TeX Live in ${cacheRoot(o.env, o.home)} — \`npx paperlint toolchain\` installs ${n} packages (~230 MB, ~2 min)`,
+      `✗ no TeX Live in ${cacheRoot(o.env, o.home)} — \`npx paperlint toolchain\` installs ${String(n)} packages (~230 MB, ~2 min)`,
     );
     return 1;
   }
   const gaps = gapsOf(tree, o.tex, o.run);
   if (noGaps(gaps)) {
     o.log(
-      `✓ TeX Live ${tree.year} in ${tree.dir} has all ${n} declared packages`,
+      `✓ TeX Live ${tree.year} in ${tree.dir} has all ${String(n)} declared packages`,
     );
     o.log(binLine(tree));
     return 0;
@@ -709,9 +721,11 @@ function report(o: Resolved, tree: CachedTree | null): number {
   // A dependency the install left out is not one of the venue's declared packages: counted apart,
   // so the line never reads "lacks 0 of 51" followed by a name.
   const what = [
-    ...(declared ? [`${declared} of ${n} declared packages`] : []),
+    ...(declared
+      ? [`${String(declared)} of ${String(n)} declared packages`]
+      : []),
     ...(gaps.dependencies.length
-      ? [`${gaps.dependencies.length} TeX Live base package(s)`]
+      ? [`${String(gaps.dependencies.length)} TeX Live base package(s)`]
       : []),
   ].join(" and ");
   o.log(
@@ -759,13 +773,13 @@ function texPart(o: Resolved): number {
   // reason to install only when tlmgr refuses to add a newly declared package to the old tree.
   if (tree && complete(tree)) {
     o.log(
-      `✓ TeX Live ${tree.year} in ${tree.dir} already has all ${n} declared packages — nothing to do`,
+      `✓ TeX Live ${tree.year} in ${tree.dir} already has all ${String(n)} declared packages — nothing to do`,
     );
     o.log(binLine(tree));
     return 0;
   }
   o.log(
-    `paperlint toolchain: TeX Live with ${n} packages into ${cacheRoot(o.env, o.home)}`,
+    `paperlint toolchain: TeX Live with ${String(n)} packages into ${cacheRoot(o.env, o.home)}`,
   );
   return ensureTexLive(o.tex, o).ok ? 0 : 1;
 }