paperlint 3.1.3 → 4.0.0

package/lib/{check.mjs → check.ts}

@@ -1,5 +1,5 @@
 /**
- * The one assertion helper every `*.harness.mjs` uses.
+ * The one assertion helper every harness uses.
  *
  * Until #52 each harness defined its own `check()`, and the copies had drifted: some printed a
  * detail on failure and some dropped it, some joined it with " — " and some with a newline, and two
@@ -17,15 +17,27 @@ import assert from "node:assert/strict";
 import { inspect } from "node:util";
 import { recordCheck } from "vigiles";
 
+/** A failure detail: text, any value (rendered with `util.inspect`), or a thunk producing one. */
+export type Detail = unknown;
+
+/** `check(label, cond, detail?)`, and how many times it has been called. */
+export interface Check {
+  (label: string, cond: unknown, detail?: Detail): void;
+  readonly count: number;
+}
+
+/** A detail given as a function, so it is only built on failure. */
+const isThunk = (d: Detail): d is () => unknown => typeof d === "function";
+
 /** A failure detail as text: strings verbatim, other values through `util.inspect`, a thunk called. */
-export function renderDetail(detail) {
-  const value = typeof detail === "function" ? detail() : detail;
+export function renderDetail(detail: Detail): string {
+  const value: unknown = isThunk(detail) ? detail() : detail;
   if (value === undefined || value === null || value === "") return "";
   return typeof value === "string" ? value : inspect(value, { depth: 6 });
 }
 
 /** The label, then the detail: on the same line when it is one line, below it when it is many. */
-export function failureMessage(label, detail) {
+export function failureMessage(label: string, detail: Detail): string {
   const shown = renderDetail(detail);
   if (!shown) return label;
   return shown.includes("\n") ? `${label}\n${shown}` : `${label} — ${shown}`;
@@ -35,16 +47,17 @@ export function failureMessage(label, detail) {
  * A fresh `check(label, cond, detail?)`. `check.count` is how many times it has been called.
  * `log` is where a failure is printed — stderr unless this module's own test injects one.
  */
-export function createChecker({ log = console.error } = {}) {
-  let count = 0;
-  const check = (label, cond, detail) => {
-    count++;
+export function createChecker({
+  log = console.error,
+}: { log?: (line: string) => void } = {}): Check {
+  const check = (label: string, cond: unknown, detail?: Detail): void => {
+    check.count++;
     recordCheck();
     if (cond) return;
     const message = failureMessage(label, detail);
     log(`✗ ${message}`);
     assert.fail(message);
   };
-  Object.defineProperty(check, "count", { get: () => count });
+  check.count = 0;
   return check;
 }

package/lib/markdown.test.mjs

@@ -10,7 +10,7 @@ import { copyFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { test } from "vitest";
-import { runNode, useTempDir, writeTree } from "../test/support.mjs";
+import { runNode, useTempDir, writeTree } from "../test/support.ts";
 import {
   blankFrontmatter,
   fences,
@@ -22,7 +22,7 @@ import {
   stripFences,
   stripFrontmatter,
   tables,
-} from "./markdown.mjs";
+} from "./markdown.ts";
 
 const DOC = [
   "---", // 0
@@ -157,13 +157,13 @@ writeTree(root, {
     "import { register } from 'node:module';\n" +
     "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s === 'markdown-it') throw Object.assign(new Error('gone'), { code: 'ERR_MODULE_NOT_FOUND' }); return next(s, c); }\"));\n",
   "probe.mjs":
-    `const m = await import(${JSON.stringify(join(dirname(fileURLToPath(import.meta.url)), "markdown.mjs"))});\n` +
+    `const m = await import(${JSON.stringify(join(dirname(fileURLToPath(import.meta.url)), "markdown.ts"))});\n` +
     "const t = '# H\\n\\n```\\nx\\n```\\n';\n" +
     "console.log(JSON.stringify([m.MD_AVAILABLE(), m.headings(t), m.fences(t), m.stripFences(t), m.paragraphs(t), m.tables(t)]));\n" +
     "m.requireMarkdown();\n" +
     "console.log('not reached');\n",
   "probe-plugin.mjs":
-    `const m = await import(${JSON.stringify(join(dirname(fileURLToPath(import.meta.url)), "markdown.mjs"))});\n` +
+    `const m = await import(${JSON.stringify(join(dirname(fileURLToPath(import.meta.url)), "markdown.ts"))});\n` +
     'm.requireMarkdown({ from: "file:///home/u/.claude/plugins/cache/paperlint/lib/markdown.mjs" });\n',
 });
 
@@ -223,12 +223,12 @@ test("a copy running from a plugin cache without markdown-it is told to install
   const lib = join(root, ".claude", "plugins", "paperlint", "lib");
   mkdirSync(lib, { recursive: true });
   copyFileSync(
-    join(dirname(fileURLToPath(import.meta.url)), "markdown.mjs"),
-    join(lib, "markdown.mjs"),
+    join(dirname(fileURLToPath(import.meta.url)), "markdown.ts"),
+    join(lib, "markdown.ts"),
   );
   writeTree(lib, {
     "probe.mjs":
-      'const m = await import("./markdown.mjs");\nm.requireMarkdown();\n',
+      'const m = await import("./markdown.ts");\nm.requireMarkdown();\n',
   });
   const r = runNode(join(lib, "probe.mjs"), []);
   assert.deepEqual(

package/lib/{markdown.mjs → markdown.ts}

@@ -32,7 +32,28 @@
 // a bare top-level `import` changed the shape of the failure: no `node_modules` → exit 1
 // → **the blocking `pre` gate in paper-lint stops blocking silently**, because
 // PreToolUse counts only exit code 2 as a block. Measured: `ERR_MODULE_NOT_FOUND`, exit 1.
-let md = null;
+import type MarkdownIt from "markdown-it";
+import type { Token } from "markdown-it";
+
+/** One ATX heading: its level, its text without the hashes, its 0-based line and line offset. */
+export interface Heading {
+  readonly depth: number;
+  readonly text: string;
+  readonly line: number;
+  readonly offset: number;
+}
+
+/** A chunk of the document: the heading it starts with (`null` for the preamble), with and without it. */
+export interface Section {
+  readonly heading: Heading | null;
+  readonly raw: string;
+  readonly body: string;
+}
+
+/** A block tokenizer with markdown-it's shape — the default, or one a test passes. */
+export type Parse = (text: string) => readonly Token[];
+
+let md: MarkdownIt | null = null;
 try {
   const { default: MarkdownIt } = await import("markdown-it");
   md = new MarkdownIt();
@@ -50,7 +71,10 @@ try {
 export const MD_AVAILABLE = () => md !== null;
 
 /** markdown-it's block tokens for `text`, or null when it did not resolve. A test passes its own. */
-const defaultParse = () => (md === null ? null : (text) => md.parse(text, {}));
+const defaultParse = (): Parse | null => {
+  const parser = md;
+  return parser === null ? null : (text) => parser.parse(text, {});
+};
 
 /**
  * The frontmatter is BLANKED with spaces, not cut out: the offsets must stay the
@@ -60,7 +84,7 @@ const defaultParse = () => (md === null ? null : (text) => md.parse(text, {}));
  * sections.
  */
 const FRONTMATTER_RE = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?=\r?\n|$)/;
-export function blankFrontmatter(text) {
+export function blankFrontmatter(text: string): string {
   const m = FRONTMATTER_RE.exec(text);
   return m ? m[0].replace(/[^\n]/g, " ") + text.slice(m[0].length) : text;
 }
@@ -78,7 +102,7 @@ export function blankFrontmatter(text) {
  * and rejected: gray-matter"). The value here is one fence instead of eight, and the
  * parsing of VALUES is done by `js-yaml` at the caller.
  */
-export function frontmatterBlock(text) {
+export function frontmatterBlock(text: string): string | null {
   const m = FRONTMATTER_RE.exec(text);
   if (!m) return null;
   const inner = m[0]
@@ -96,13 +120,13 @@ export function frontmatterBlock(text) {
  * later shown to the user; cutting — where the text is merely counted. Choose by what
  * the caller does, not by taste.
  */
-export function stripFrontmatter(text) {
+export function stripFrontmatter(text: string): string {
   const m = FRONTMATTER_RE.exec(text);
   return m ? text.slice(m[0].length).replace(/^\r?\n/, "") : text;
 }
 
 /** Line-start offsets — so that `token.map` becomes a position in the source string. */
-function lineStarts(text) {
+function lineStarts(text: string): number[] {
   const out = [0];
   for (let i = 0; i < text.length; i++) if (text[i] === "\n") out.push(i + 1);
   return out;
@@ -121,13 +145,15 @@ function lineStarts(text) {
  * under without a blank line would become a level-2 heading per CommonMark. The former
  * regexps knew only ATX, so this preserves the contract rather than narrowing it.
  */
-export function headings(text, { parse = defaultParse() } = {}) {
+export function headings(
+  text: string,
+  { parse = defaultParse() }: { parse?: Parse | null } = {},
+): Heading[] {
   if (parse === null) return [];
   const toks = parse(blankFrontmatter(text));
   const starts = lineStarts(text);
-  const out = [];
-  for (let i = 0; i < toks.length; i++) {
-    const t = toks[i];
+  const out: Heading[] = [];
+  for (const [i, t] of toks.entries()) {
     if (t.type !== "heading_open" || !t.map) continue;
     if (!t.markup || !t.markup.startsWith("#")) continue; // setext — see the caveat above
     // markdown-it follows `heading_open` with its `inline` token and maps blocks to lines of the
@@ -166,18 +192,22 @@ export function headings(text, { parse = defaultParse() } = {}) {
  * happened (`recordBlock` in `skill-corpus.mjs` returned a single "#" character for all
  * 21 skills).
  */
-export function splitSections(text, { min = 2, max = 6 } = {}) {
+export function splitSections(
+  text: string,
+  { min = 2, max = 6 }: { min?: number; max?: number } = {},
+): Section[] {
   const hs = headings(text).filter((h) => h.depth >= min && h.depth <= max);
-  const out = [];
-  const preEnd = hs.length ? hs[0].offset : text.length;
+  const out: Section[] = [];
+  const [first] = hs;
+  const preEnd = first ? first.offset : text.length;
   out.push({
     heading: null,
     raw: text.slice(0, preEnd),
     body: text.slice(0, preEnd),
   });
-  for (let i = 0; i < hs.length; i++) {
-    const h = hs[i];
-    const end = i + 1 < hs.length ? hs[i + 1].offset : text.length;
+  for (const [i, h] of hs.entries()) {
+    const next = hs[i + 1];
+    const end = next ? next.offset : text.length;
     const nl = text.indexOf("\n", h.offset);
     const bodyStart = nl === -1 || nl + 1 > end ? end : nl + 1;
     out.push({
@@ -221,18 +251,21 @@ export function splitSections(text, { min = 2, max = 6 } = {}) {
  * degradation is acceptable (see the module comment), while a silent fallback to a
  * regex would mean a working degraded version that nobody notices.
  */
-export function fences(text) {
+export function fences(text: string): string[] {
   if (md === null) return [];
-  const out = [];
+  const out: string[] = [];
   for (const t of md.parse(blankFrontmatter(text), {}))
     if (t.type === "fence" || t.type === "code_block") out.push(t.content);
   return out;
 }
 
-export function stripFences(text, { blank = false } = {}) {
+export function stripFences(
+  text: string,
+  { blank = false }: { blank?: boolean } = {},
+): string {
   if (md === null) return text;
   const lines = text.split("\n");
-  const drop = new Set();
+  const drop = new Set<number>();
   for (const t of md.parse(blankFrontmatter(text), {}))
     if ((t.type === "fence" || t.type === "code_block") && t.map)
       for (let i = t.map[0]; i < t.map[1]; i++) drop.add(i);
@@ -249,7 +282,9 @@ export function stripFences(text, { blank = false } = {}) {
  * indistinguishable from "the paper has no sections". A confident zero has already been
  * read as a finding four times in this repo; here it is inexpressible.
  */
-export function requireMarkdown({ from = import.meta.url } = {}) {
+export function requireMarkdown({
+  from = import.meta.url,
+}: { from?: string } = {}): void {
   if (MD_AVAILABLE()) return;
   // 🔴 THE CURE DEPENDS ON WHERE THIS COPY RUNS FROM. Measured 2026-09-19: a Claude Code plugin
   // copy is installed without dependencies (`npm pack` strips `package-lock.json`, and the plugin
@@ -301,23 +336,27 @@ export function requireMarkdown({ from = import.meta.url } = {}) {
  * automatically, by the construction of the parser, and not by a separate line-type
  * check.
  */
-export function paragraphs(text) {
+export function paragraphs(text: string): { line: number; endLine: number }[] {
   if (md === null) return [];
   return md
     .parse(blankFrontmatter(text), {})
-    .filter((t) => t.type === "paragraph_open" && t.map)
-    .map((t) => ({ line: t.map[0], endLine: t.map[1] }));
+    .flatMap((t) =>
+      t.type === "paragraph_open" && t.map
+        ? [{ line: t.map[0], endLine: t.map[1] }]
+        : [],
+    );
 }
 
-export function tables(text) {
+export function tables(
+  text: string,
+): { line: number; endLine: number; rows: string[][] }[] {
   if (md === null) return [];
   const lines = blankFrontmatter(text).split("\n");
-  const out = [];
+  const out: { line: number; endLine: number; rows: string[][] }[] = [];
   for (const t of md.parse(blankFrontmatter(text), {})) {
     if (t.type !== "table_open" || !t.map) continue;
-    const rows = [];
-    for (let i = t.map[0]; i < t.map[1]; i++) {
-      const raw = lines[i];
+    const rows: string[][] = [];
+    for (const raw of lines.slice(t.map[0], t.map[1])) {
       if (/^\s*\|?[\s:|-]+\|?\s*$/.test(raw) && raw.includes("-")) continue; // alignment
       rows.push(
         raw

package/lib/paper-config.harness.mjs

@@ -2,7 +2,7 @@
  * Both halves for `lib/paper-config.mjs` — and, more broadly, for the SET of places that
  * publish these two constants.
  *
- * 🔴 WHY THIS CHECK MOVED HERE FROM `hooks/hooks.harness.mjs`. There it compared three hooks
+ * 🔴 WHY THIS CHECK MOVED HERE FROM `hooks/hooks.harness.ts`. There it compared three hooks
  * against each other — and was right only as far as its COVERAGE was right. Measured
  * 2026-09-18: there were eight declarations across five files, four per constant, and for each
  * constant exactly one copy sat OUTSIDE the comparison (`eslint-rules/papers.mjs`,
@@ -27,7 +27,7 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { createChecker } from "./check.mjs";
+import { createChecker } from "./check.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(HERE, "..");
@@ -37,15 +37,15 @@ const check = createChecker();
 /**
  * Every place that publishes at least one of the two constants. The three hooks duplicate them
  * out of necessity (a compiled hook is forbidden to import anything but `vigiles/hook`); the
- * rest re-export from `lib/paper-config.mjs` and are kept in this list for exactly one reason:
+ * rest re-export from `lib/paper-config.ts` and are kept in this list for exactly one reason:
  * so a re-export that is one day swapped back for its own declaration gets caught.
  */
 const CARRIERS = [
-  "lib/paper-config.mjs",
+  "lib/paper-config.ts",
   "hooks/paper-edit-guard.hook.mjs",
   "hooks/paper-skills-nudge.hook.mjs",
   "hooks/paper-status-gates.hook.mjs",
-  "eslint-rules/papers.mjs",
+  "eslint-rules/papers.ts",
   "skills/paper-pipeline/scripts/consumer.mjs",
 ];
 
@@ -167,7 +167,7 @@ const loaded = await Promise.all(
     "repro",
   ]);
   const declares =
-    /^(?:export )?const (?:CONFIG_KEY|CONFIG_FILE|DEFAULT_PAPERS_ROOT|PAPERS_DIR_FIELD)\s*=/m;
+    /^(?:export )?const (?:CONFIG_KEY|CONFIG_FILE|DEFAULT_PAPERS_ROOT|PAPERS_DIR_FIELD)\s*(?::[^=]*)?=/m;
   const found = [];
   const walk = (dir) => {
     for (const e of readdirSync(dir, { withFileTypes: true })) {
@@ -202,7 +202,7 @@ const loaded = await Promise.all(
 // every `settingsOf(root)?.<key>` (and the older `[CONFIG_KEY]?.<key>` shape), plus every field of
 // `PaperlintConfig`, the CLI's typed view of the same object.
 {
-  const { SETTINGS_KEYS } = await import(join(HERE, "paper-config.mjs"));
+  const { SETTINGS_KEYS } = await import(join(HERE, "paper-config.ts"));
   const ts = (await import("typescript")).default;
   const readKeys = new Set();
   const isConfigKey = (e) =>
@@ -253,7 +253,7 @@ const loaded = await Promise.all(
   );
   check(
     "and the scan found the readers it must find — the skill scripts' keys and PaperlintConfig's",
-    ["ledger", "citeChecks", "triggerCases", "papersDir", "rules"].every((k) =>
+    ["scripts", "timezone", "triggerCases", "papersDir", "rules"].every((k) =>
       readKeys.has(k),
     ),
   );
@@ -262,7 +262,7 @@ const loaded = await Promise.all(
 // ── the two readers' fallbacks: no marker anywhere up the tree, and JSON that is not an object ──
 {
   const { findProjectRoot, settingsOf } = await import(
-    join(HERE, "paper-config.mjs")
+    join(HERE, "paper-config.ts")
   );
   check(
     "findProjectRoot: no paperlint.json and no package.json up to / — the start directory itself",

package/lib/{paper-config.mjs → paper-config.ts}

@@ -9,7 +9,7 @@
  * allowing a reach into `child_process`. The restriction is wider than strictly necessary
  * (importing plain constants adds no capability), and that is discussed in zernie/vigiles#245,
  * but until it is relaxed the hooks duplicate, and drift is caught by the cross-check in
- * `hooks/hooks.harness.mjs`.
+ * `hooks/hooks.harness.ts`.
  *
  * 🔴 BUT THE REST WERE DUPLICATING FOR NO REASON AT ALL. `eslint-rules/papers.mjs` and
  * `skills/paper-pipeline/scripts/consumer.mjs` are not hooks, carry no import restriction, and
@@ -28,7 +28,7 @@ import { dirname, join, resolve } from "node:path";
  * and the hooks resolve their scripts through it. It equals the package name, and
  * `lib/paper-config.harness.mjs` checks that.
  */
-export const CONFIG_KEY = "paperlint";
+export const CONFIG_KEY: string = "paperlint";
 
 /**
  * THE SETTINGS FILE, ONE NAME AT TWO LEVELS, ONE SCHEMA (`SETTINGS_KEYS`):
@@ -41,13 +41,13 @@ export const CONFIG_KEY = "paperlint";
  * applied after the root's. A venue preset (`paperlint:<name>`, or the project's own `./x.jsonc`)
  * is the third level, below both.
  */
-export const CONFIG_FILE = "paperlint.json";
+export const CONFIG_FILE: string = "paperlint.json";
 
 /**
  * The files that make a directory a PAPER. A `paperlint.json` beside one of them is that paper's,
  * never the project's — so walking up from inside a paper does not stop at the paper's own file.
  */
-export const PAPER_MARKERS = Object.freeze([
+export const PAPER_MARKERS: readonly string[] = Object.freeze([
   "paper.tex",
   "paper.md",
   "draft.md",
@@ -61,13 +61,16 @@ export const PAPER_MARKERS = Object.freeze([
  *
  * @param isFile  whether a path exists — `existsSync` by default; `src/` passes its Files port.
  */
-export function findProjectRoot(startDir, isFile = existsSync) {
+export function findProjectRoot(
+  startDir: string,
+  isFile: (path: string) => boolean = existsSync,
+): string {
   const start = resolve(startDir);
-  const isPaper = (d) => PAPER_MARKERS.some((m) => isFile(join(d, m)));
+  const isPaper = (d: string) => PAPER_MARKERS.some((m) => isFile(join(d, m)));
   // Up from `start` to the first directory `found` accepts; null past the filesystem root. A
   // loop with an exit condition rather than `for (;;)`: the code after an endless loop is a block
   // that can never run, and coverage counts it as one that did not.
-  const walk = (found) => {
+  const walk = (found: (dir: string) => boolean): string | null => {
     let d = start;
     while (!found(d)) {
       if (dirname(d) === d) return null;
@@ -82,7 +85,7 @@ export function findProjectRoot(startDir, isFile = existsSync) {
   );
 }
 
-const isObject = (v) =>
+const isObject = (v: unknown): v is Readonly<Record<string, unknown>> =>
   v !== null && typeof v === "object" && !Array.isArray(v);
 
 /**
@@ -90,8 +93,10 @@ const isObject = (v) =>
  * such file, or it does not parse, or it is not an object. For readers that only need one key and
  * fall back to its default; `paperlint lint` parses the file strictly and names what is wrong.
  */
-export function settingsOf(root) {
-  let v;
+export function settingsOf(
+  root: string,
+): Readonly<Record<string, unknown>> | undefined {
+  let v: unknown;
   try {
     v = JSON.parse(readFileSync(join(root, CONFIG_FILE), "utf8"));
   } catch {
@@ -101,7 +106,7 @@ export function settingsOf(root) {
 }
 
 /** The default papers directory, used when the root `paperlint.json` declares none (or there is none). */
-export const DEFAULT_PAPERS_ROOT = "papers";
+export const DEFAULT_PAPERS_ROOT: string = "papers";
 
 /**
  * The field that names the papers directory: `{ "papersDir": "papers" }` in the root
@@ -112,7 +117,7 @@ export const DEFAULT_PAPERS_ROOT = "papers";
  * here. The three hooks cannot import this module, so they keep their own copy, and
  * `lib/paper-config.harness.mjs` checks that every copy matches this one.
  */
-export const PAPERS_DIR_FIELD = "papersDir";
+export const PAPERS_DIR_FIELD: string = "papersDir";
 
 /**
  * Every key a `paperlint.json` may hold — the root's and a paper's, ONE schema — with who reads it.
@@ -124,7 +129,7 @@ export const PAPERS_DIR_FIELD = "papersDir";
  * `PaperlintConfig`, and requires each to be here — so a new reader that forgets this list turns
  * the harness red before a consumer's config does.
  */
-export const SETTINGS_KEYS = Object.freeze({
+export const SETTINGS_KEYS: Readonly<Record<string, string>> = Object.freeze({
   papersDir: `the papers directory, default "papers" — every command, the hooks`,
   structure: "which files a paper directory must hold — paperlint lint",
   rules:
@@ -133,24 +138,20 @@ export const SETTINGS_KEYS = Object.freeze({
     "the venue preset: paperlint:<name> or ./path.jsonc — the pdf/ venue rules, paperlint build",
   kind: "the kind of paper, whose page limit applies — pdf/limits",
   pdf: "where the built PDF is, relative to the paper, when it is not paper.pdf — the facts",
-  ledger: "the run ledger — skills/paper-pipeline/scripts/consumer.mjs",
   scripts: "how skill prose names the scripts — consumer.mjs",
-  timezone: "dates in the ledger — consumer.mjs",
+  timezone: "the zone deadline anchors are written in — consumer.mjs",
   contactEmail: "the polite-pool address for citation lookups — consumer.mjs",
-  citeChecks: "the consumer's citation checkers — run-mechanical.mjs",
   triggerCases:
     "the consumer's own skill trigger cases — lib/skill-trigger-cases.mjs",
   $comment: "a note for humans (JSON Schema's own comment keyword); ignored",
 });
 
 /** The keys that only mean something for the whole project: refused in a paper's `paperlint.json`. */
-export const ROOT_ONLY_KEYS = Object.freeze([
+export const ROOT_ONLY_KEYS: readonly string[] = Object.freeze([
   "papersDir",
   "structure",
-  "ledger",
   "scripts",
   "timezone",
   "contactEmail",
-  "citeChecks",
   "triggerCases",
 ]);