paperlint 3.1.2 → 3.2.0

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) =>
@@ -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:
@@ -144,7 +149,7 @@ export const SETTINGS_KEYS = Object.freeze({
 });
 
 /** 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",

package/lib/skill-checks.mjs

@@ -28,7 +28,7 @@ import { recordCheck } from "vigiles";
 // Markup is parsed with a parser (`CLAUDE.md`, 2026-08-11). `requireMarkdown()` is called by
 // `skill-corpus.mjs` on the import below, so by the time anything is parsed here the parser
 // either exists or the process does not.
-import { headings as mdHeadings } from "./markdown.mjs";
+import { headings as mdHeadings } from "#lib/markdown";
 
 // 🔴 2026-08-28: nine names were removed from this list, and that is NOT a style cleanup — they
 // had drifted apart from what the file does. `EXCLUDED PIPELINE_MARKER GATE_SKILLS EXPECTED_GATES

package/lib/skill-checks.test.mjs

@@ -12,7 +12,7 @@ import { cpSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { test } from "vitest";
-import { useTempDir, writeTree } from "../test/support.mjs";
+import { useTempDir, writeTree } from "../test/support.ts";
 
 const SHIPPED = join(dirname(fileURLToPath(import.meta.url)), "..", "skills");
 const consumer = useTempDir("skill-checks-");

package/lib/skill-corpus.mjs

@@ -38,7 +38,7 @@ import {
   headings as mdHeadings,
   requireMarkdown,
   frontmatterBlock,
-} from "./markdown.mjs";
+} from "#lib/markdown";
 
 // Markup is parsed with a real parser (`CLAUDE.md`, 2026-08-11). Here we THROW rather than
 // degrade: this module answers the question "what does the skill corpus contain", and an empty

package/lib/skill-eval-kit.mjs

@@ -54,7 +54,7 @@ import { resolve } from "node:path";
 import { consumerRoot } from "../skills/paper-pipeline/scripts/consumer.mjs";
 
 import { BY_SKILL, irrelevantFor } from "./skill-trigger-cases.mjs";
-import { FIXTURE } from "./skill-eval-fixture.mjs";
+import { FIXTURE } from "#lib/skill-eval-fixture";
 
 // The CONSUMER's root — the live harness being measured is the consumer's, not this package's.
 const REPO = consumerRoot();

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "paperlint",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",
   "scripts": {
-    "build": "tsc",
-    "prepare": "tsc",
-    "test": "node scripts/test.mjs",
-    "coverage": "NODE_OPTIONS=\"--import=./test/coverage-src.mjs $NODE_OPTIONS\" c8 --check-coverage npm test --",
+    "build": "tsc -p tsconfig.pkg.json && tsc",
+    "prepare": "tsc -p tsconfig.pkg.json && tsc",
+    "test": "node scripts/test.ts",
+    "coverage": "NODE_OPTIONS=\"--import=./test/coverage-src.ts $NODE_OPTIONS\" c8 --check-coverage npm test --",
     "lint": "eslint .",
-    "check": "node scripts/check.mjs",
-    "test:e2e": "node test/e2e/install.mjs && node test/e2e/build.mjs",
+    "check": "node scripts/check.ts",
+    "test:e2e": "node test/e2e/install.ts && node test/e2e/build.ts",
     "fmt": "prettier --write .",
     "fmt:check": "prettier --check ."
   },
@@ -24,7 +24,7 @@
     "js-yaml": "^4.1.0",
     "markdown-it": "^14.3.0",
     "ts-essentials": "^10.2.1",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "unpdf": "^1.8.1",
     "vigiles": "^31.0.1",
     "zod": "^4.6.5"
@@ -33,9 +33,12 @@
     "@retorquere/bibtex-parser": "^10.0.1",
     "@semantic-release/commit-analyzer": "13.0.1",
     "@semantic-release/release-notes-generator": "14.1.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/markdown-it": "^14.2.0",
     "@types/node": "^26.6.1",
     "c8": "^12.0.0",
     "conventional-changelog-conventionalcommits": "9.3.1",
+    "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-boundaries": "^7.2.0",
     "eslint-plugin-n": "^18.3.0",
     "prettier": "^3.8.1",
@@ -72,6 +75,22 @@
   "bin": {
     "paperlint": "bin/paperlint.mjs"
   },
+  "exports": {
+    "./eslint-rules/*.mjs": {
+      "types": "./dist/eslint-rules/*.d.ts",
+      "default": "./dist/eslint-rules/*.js"
+    },
+    "./lib/skill-checks.mjs": "./lib/skill-checks.mjs",
+    "./lib/skill-corpus.mjs": "./lib/skill-corpus.mjs",
+    "./lib/skill-eval-kit.mjs": "./lib/skill-eval-kit.mjs",
+    "./lib/skill-trigger-cases.mjs": "./lib/skill-trigger-cases.mjs",
+    "./lib/trigger-ledger.mjs": "./lib/trigger-ledger.mjs",
+    "./lib/*.mjs": {
+      "types": "./dist/lib/*.d.ts",
+      "default": "./dist/lib/*.js"
+    },
+    "./*": "./*"
+  },
   "files": [
     ".github",
     "CLAUDE.md",
@@ -93,6 +112,19 @@
     "skills",
     "src",
     "templates",
-    "tsconfig.json"
-  ]
+    "tsconfig.json",
+    "tsconfig.pkg.json"
+  ],
+  "imports": {
+    "#lib/*": {
+      "paperlint-source": "./lib/*.ts",
+      "types": "./dist/lib/*.d.ts",
+      "default": "./dist/lib/*.js"
+    },
+    "#eslint-rules/*": {
+      "paperlint-source": "./eslint-rules/*.ts",
+      "types": "./dist/eslint-rules/*.d.ts",
+      "default": "./dist/eslint-rules/*.js"
+    }
+  }
 }