paperlint 3.1.3 → 4.0.0

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.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { loadTypescript } from "./tex-requirements.ts";
+
+test("loadTypescript refuses a module without the two functions a profile is read with", () => {
+  assert.throws(
+    () => loadTypescript(() => ({})),
+    /loaded without parseConfigFileTextToJson/,
+  );
+});
+
+test("loadTypescript hands back what `require` loaded when it has them", () => {
+  const ts = {
+    parseConfigFileTextToJson: () => ({ config: {} }),
+    flattenDiagnosticMessageText: () => "",
+  };
+  assert.equal(
+    loadTypescript(() => ts),
+    ts,
+  );
+});

package/src/tex-requirements.ts

@@ -26,7 +26,8 @@ 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";
+import { fieldOf } from "./domain/record.ts";
 
 /** CTAN package name → the names that prove it is installed. */
 export type PackageProofs = Readonly<Record<string, readonly string[]>>;
@@ -51,22 +52,45 @@ const PROFILE_EXT = ".jsonc";
 
 export const NO_REQUIREMENTS: TexRequirements = { packages: {}, tools: {} };
 
-type Ts = typeof import("typescript");
-let ts: Ts | null = null;
+/** The two functions of `typescript` a profile is read with. */
+type TsJsonc = Pick<
+  typeof import("typescript"),
+  "parseConfigFileTextToJson" | "flattenDiagnosticMessageText"
+>;
+
+const isTsJsonc = (m: unknown): m is TsJsonc =>
+  typeof fieldOf(m, "parseConfigFileTextToJson") === "function" &&
+  typeof fieldOf(m, "flattenDiagnosticMessageText") === "function";
+
+/** `typescript` as `load` returns it — `require` answers `any` — checked for the two functions used. */
+export function loadTypescript(load: (id: string) => unknown): TsJsonc {
+  const m = load("typescript");
+  if (!isTsJsonc(m))
+    throw new Error(
+      "`typescript` loaded without parseConfigFileTextToJson — reinstall this package",
+    );
+  return m;
+}
+
+let ts: TsJsonc | null = null;
 /** TypeScript is loaded only when a profile is read: `paperlint lint` never pays for it. */
-function typescript(): Ts {
-  ts ??= createRequire(import.meta.url)("typescript") as Ts;
+function typescript(): TsJsonc {
+  ts ??= loadTypescript(createRequire(import.meta.url));
   return ts;
 }
 
 type Validate = ReturnType<Ajv.Ajv["compile"]>;
+/** `PresetJson` is the TypeScript side of the profile schema: a document the schema accepts is one. */
+const matchesSchema = (v: unknown, validate: Validate): v is PresetJson =>
+  validate(v) === true;
 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,17 +238,19 @@ 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, " ")}`,
     );
   const validate = validatorFor(dir);
-  if (!validate(config))
+  if (!matchesSchema(config, validate))
     throw new Error(
       `${file} does not match ${SCHEMA_FILE}:\n  ${violations(file, validate).join("\n  ")}`,
     );
-  const j = config as PresetJson;
+  const j = config;
   return {
     extends: orNull(j.extends),
     name: orNull(j.name),

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,
@@ -34,19 +34,19 @@ type Answer = {
 };
 /** A runner answering by program name (the last path segment); `onRun` may write files first. */
 function io(
-  answers: Record<string, (args: string[]) => Answer>,
+  answers: Record<string, (args: readonly string[]) => Answer>,
 ): ToolchainIO & { lines: string[] } {
   const lines: string[] = [];
   return {
     lines,
     log: (l) => lines.push(l),
     env: {},
-    run: ((cmd: string, args: string[]) => {
+    run: (cmd, args) => {
       const name = cmd.split("/").pop() ?? cmd;
       const answer = answers[`${name} ${args[0] ?? ""}`] ?? answers[name];
       if (!answer) throw new Error(`unexpected ${name} ${args.join(" ")}`);
       return answer(args);
-    }) as never,
+    },
   };
 }
 const ok = (stdout = ""): Answer => ({ status: 0, stdout, stderr: "" });
@@ -194,7 +194,7 @@ function cacheWith(name: string, year: string): string {
 const ACMART = { packages: { acmart: ["acmart.cls"] }, tools: {} };
 function ensure(
   cache: string,
-  answers: Record<string, (args: string[]) => Answer>,
+  answers: Record<string, (args: readonly string[]) => Answer>,
 ) {
   const t = io(answers);
   const errs: string[] = [];
@@ -272,7 +272,11 @@ test("runToolchain with only its installer: the console is the default output",
   const saved = console.error;
   console.error = (...a: unknown[]) => void seen.push(a.join(" "));
   try {
-    assert.equal(runToolchain({ platform: "win32", banal: {} as never }), 1);
+    const unused = (): never => {
+      throw new Error("an unsupported platform installs nothing");
+    };
+    const banal = { label: "banal", ensure: unused, check: unused };
+    assert.equal(runToolchain({ platform: "win32", banal }), 1);
   } finally {
     console.error = saved;
   }

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;
 }

package/src/types.ts

@@ -12,10 +12,12 @@ import type { RuleBlock } from "./rules-config.ts";
  */
 export interface PaperlintConfig {
   /** The paper director(ies), relative to the project root. Default `papers`. The field name is
-   * `PAPERS_DIR_FIELD` in lib/paper-config.mjs; code reads it through `papersDirOf()` in cli.ts. */
-  papersDir?: string | string[];
+   * `PAPERS_DIR_FIELD` in lib/paper-config.mjs; code reads it through `papersDirOf()` in cli.ts.
+   * As written in the file: `toPaths` turns a string or a list of strings into directories, and
+   * reads anything else as none. */
+  papersDir?: unknown;
   /** Which files a paper directory must carry; `false` turns the check off entirely. */
-  structure?: StructureConfig | false;
+  structure?: StructureConfig | false | undefined;
   /** ESLint config blocks appended after paperlint's own — PARSED by `parseSettings` in cli.ts. */
   rules?: readonly RuleBlock[];
   /** The default venue preset of every paper that names none (`src/paper-settings.ts`). */