paperlint 3.1.3 → 3.2.0

package/eslint-rules/{review-frontmatter.mjs → review-frontmatter.ts}

@@ -38,23 +38,44 @@
  * author wrote correctly.
  */
 import Ajv from "ajv";
+import type { ErrorObject } from "ajv";
 import { CORE_SCHEMA, load } from "js-yaml";
+import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
+import { z } from "zod";
+import type { RuleContext } from "./rule-context.ts";
+
+/** A compiled schema, as far as `errorsOf` uses one. Ajv's `ValidateFunction` is one. */
+export interface Validate {
+  (data: unknown): unknown;
+  readonly errors?: readonly ErrorObject[] | null;
+}
+
+/**
+ * What a parser failure says about itself. js-yaml's `YAMLException` carries a `reason`; anything
+ * else thrown may carry a `message`, or be a bare value that says nothing.
+ */
+const Thrown = z
+  .object({
+    reason: z.string().optional().catch(undefined),
+    message: z.string().optional().catch(undefined),
+  })
+  .catch({});
 
 /** One ajv error as a line a person can act on. `if` errors only repeat their `then`. */
-function describe(e) {
+function describe(e: ErrorObject): string {
   const where = e.dataPath
     ? `\`${e.dataPath.replace(/^\./, "")}\``
     : "the frontmatter";
-  if (e.keyword === "enum")
+  if (e.keyword === "enum" && "allowedValues" in e.params)
     return `${where} must be one of: ${e.params.allowedValues.join(", ")}`;
-  if (e.keyword === "additionalProperties")
+  if (e.keyword === "additionalProperties" && "additionalProperty" in e.params)
     return `${where} has an unknown field \`${e.params.additionalProperty}\``;
-  return `${where} ${e.message}`;
+  return `${where} ${String(e.message)}`;
 }
 
 /** The schema's verdict on `data` as messages. Ajv types `errors` as possibly null; that is tolerated. */
-export const errorsOf = (validate, data) =>
+export const errorsOf = (validate: Validate, data: unknown): string[] =>
   validate(data)
     ? []
     : (validate.errors ?? []).filter((e) => e.keyword !== "if").map(describe);
@@ -63,10 +84,10 @@ export const errorsOf = (validate, data) =>
  * A rule that validates a markdown file's YAML frontmatter against the JSON Schema in `schemaUrl`
  * (a file shipped beside the rule). A file with no frontmatter is validated as `{}`.
  */
-export function frontmatterRule(schemaUrl, description) {
-  const validate = new Ajv({ allErrors: true }).compile(
-    JSON.parse(readFileSync(schemaUrl, "utf8")),
-  );
+export function frontmatterRule(schemaUrl: URL | string, description: string) {
+  const schema: unknown = JSON.parse(readFileSync(schemaUrl, "utf8"));
+  assert.ok(typeof schema === "object" && schema !== null, "not a schema");
+  const validate = new Ajv({ allErrors: true }).compile(schema);
   return {
     meta: {
       type: "problem",
@@ -78,24 +99,25 @@ export function frontmatterRule(schemaUrl, description) {
         invalid: "{{problem}}",
       },
     },
-    create(context) {
-      let frontmatter = null;
-      let data = {};
+    create(context: RuleContext) {
+      let frontmatter: object | null = null;
+      let data: unknown = {};
       return {
-        yaml(node) {
+        yaml(node: { readonly value?: string }) {
           frontmatter = node;
           try {
             data = load(node.value ?? "", { schema: CORE_SCHEMA }) ?? {};
           } catch (e) {
             data = null;
+            const { reason, message } = Thrown.parse(e);
             context.report({
               node,
               messageId: "malformed",
-              data: { why: e.reason ?? e.message ?? "unparseable" },
+              data: { why: reason ?? message ?? "unparseable" },
             });
           }
         },
-        "root:exit"(root) {
+        "root:exit"(root: object) {
           if (data === null) return;
           for (const problem of errorsOf(validate, data))
             context.report({

package/eslint-rules/rule-context.ts

@@ -0,0 +1,62 @@
+/**
+ * The slice of ESLint's rule API the rules in this directory use.
+ *
+ * These rules run on three languages (JavaScript, markdown and the `.tex` language next door),
+ * and ESLint's own `Rule.RuleContext` is the JavaScript one. So the rules are typed against what
+ * they actually touch, the way `src/venue-rules.ts` and `src/reference-rules.ts` already are.
+ */
+
+/** A line and a 1-based column, as ESLint reports them. */
+export interface Loc {
+  readonly line: number;
+  readonly column: number;
+}
+
+import type { Root } from "mdast";
+
+/** The source code a rule reads. `raw` exists on the `.tex` language's source code only. */
+export interface RuleSourceCode {
+  readonly text: string;
+  readonly raw?: string;
+  /** mdast: the markdown language's tree, or the `.tex` language's projection of one. */
+  readonly ast?: Root;
+  getLocFromIndex(index: number): Loc;
+  getText(node?: object): string;
+}
+
+/** What a fix produces: replace `range` of the file with `text`. */
+export interface RuleFix {
+  readonly range: readonly [number, number];
+  readonly text: string;
+}
+
+export interface RuleFixer {
+  replaceTextRange(range: readonly [number, number], text: string): RuleFix;
+  insertTextBeforeRange(
+    range: readonly [number, number],
+    text: string,
+  ): RuleFix;
+}
+
+export interface RuleSuggestion {
+  readonly messageId: string;
+  readonly data?: Readonly<Record<string, string | number>>;
+  fix(fixer: RuleFixer): RuleFix;
+}
+
+export interface RuleReport {
+  readonly node?: object;
+  readonly loc?: { readonly start: Loc; readonly end: Loc };
+  readonly messageId: string;
+  readonly data?: Readonly<Record<string, string | number>>;
+  readonly fix?: (fixer: RuleFixer) => RuleFix;
+  readonly suggest?: readonly RuleSuggestion[];
+}
+
+export interface RuleContext {
+  readonly filename: string;
+  readonly options: readonly unknown[];
+  readonly settings: Readonly<Record<string, unknown>>;
+  readonly sourceCode: RuleSourceCode;
+  report(descriptor: RuleReport): void;
+}

package/eslint-rules/{sibling-frontmatter.mjs → sibling-frontmatter.ts}

@@ -7,7 +7,7 @@
  * The package writes the cards, so it ships the schema: `sibling-frontmatter.schema.json`. Same
  * mechanism as `review/frontmatter`.
  */
-import { frontmatterRule } from "./review-frontmatter.mjs";
+import { frontmatterRule } from "./review-frontmatter.ts";
 
 export default {
   rules: {

package/eslint-rules/temp-root-realpath.harness.mjs

@@ -20,7 +20,7 @@
 import assert from "node:assert/strict";
 import { ESLint } from "eslint";
 import { recordCheck } from "vigiles";
-import localRules from "./temp-root-realpath.mjs";
+import localRules from "./temp-root-realpath.ts";
 
 const eslint = new ESLint({
   overrideConfigFile: true,

package/eslint-rules/{temp-root-realpath.mjs → temp-root-realpath.ts}

@@ -45,8 +45,18 @@
  * assertion was about their sum.
  */
 
+import type { CallExpression, Node } from "estree";
+import type { RuleContext } from "./rule-context.ts";
+
+/**
+ * Whether `value` is an ESTree node: an object whose `type` is a string. The walk below reaches
+ * every property of a node, and most of them (`regex`, `value`, arrays of flags) are not nodes.
+ */
+const isNode = (value: object): value is Node =>
+  "type" in value && typeof value.type === "string";
+
 /** The called function's name: `f()` and `mod.f()` count as the same name for our purposes. */
-const calleeName = (node) => {
+const calleeName = (node: Node | null | undefined): string => {
   if (node?.type !== "CallExpression") return "";
   const c = node.callee;
   if (c.type === "Identifier") return c.name;
@@ -65,10 +75,10 @@ const calleeName = (node) => {
  * text-based guard would be forced to exclude itself — exactly the class of check string-based
  * checks are banned for in this repository.
  */
-const mentionsTmpdir = (node) => {
+const mentionsTmpdir = (node: unknown): boolean => {
   if (node === null || typeof node !== "object") return false;
   if (Array.isArray(node)) return node.some(mentionsTmpdir);
-  if (typeof node.type !== "string") return false;
+  if (!isNode(node)) return false;
   if (calleeName(node) === "tmpdir") return true;
   for (const [key, value] of Object.entries(node)) {
     if (key === "parent" || key === "loc" || key === "range") continue;
@@ -79,7 +89,9 @@ const mentionsTmpdir = (node) => {
 };
 
 /** `realpathSync(x)` and `realpathSync.native(x)` — both resolve the path, both count. */
-const isRealpathCall = (node) => {
+const isRealpathCall = (
+  node: Node | null | undefined,
+): node is CallExpression => {
   if (node?.type !== "CallExpression") return false;
   const name = calleeName(node);
   if (name === "realpathSync") return true;
@@ -91,6 +103,7 @@ const isRealpathCall = (node) => {
   return (
     obj?.type === "MemberExpression" &&
     !obj.computed &&
+    "name" in obj.property &&
     obj.property.name === "realpathSync"
   );
 };
@@ -113,9 +126,9 @@ export default {
             "directory under two names, and every path comparison built on it silently compares the two.",
         },
       },
-      create(context) {
+      create(context: RuleContext) {
         return {
-          CallExpression(node) {
+          CallExpression(node: CallExpression & { readonly parent?: Node }) {
             if (calleeName(node) !== "mkdtempSync") return;
             if (!mentionsTmpdir(node.arguments)) return;
             const parent = node.parent;

package/eslint-rules/tex-build.harness.mjs

@@ -70,7 +70,7 @@ import { fileURLToPath } from "node:url";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(HERE, ".."); // eslint-rules → repository root
-const RULES = join(HERE, "tex-build.mjs");
+const RULES = join(HERE, "tex-build.ts");
 assert.ok(existsSync(RULES), `no entry point for the test: ${RULES}`);
 
 const TMP = realpathSync(mkdtempSync(join(tmpdir(), "tex-build-")));
@@ -78,7 +78,7 @@ const TMP = realpathSync(mkdtempSync(join(tmpdir(), "tex-build-")));
 // `rmSync` at the bottom never runs in exactly the runs that are red.
 process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
 
-const { texLanguage } = await import(join(HERE, "latex-language.mjs"));
+const { texLanguage } = await import(join(HERE, "latex-language.ts"));
 const texBuild = (await import(RULES)).default;
 
 // A new rule with no declared severity must not slip through unnoticed.

package/eslint-rules/{tex-build.mjs → tex-build.ts}

@@ -50,6 +50,7 @@
  * on `readdirSync` order and on how many drafts happen to lie next to the paper.
  */
 import { readFileSync } from "node:fs";
+import type { RuleContext } from "./rule-context.ts";
 
 /**
  * A copy rather than an import, for the same reason the prose lexicons are copies: a rule may
@@ -152,7 +153,7 @@ const futurePromise = {
         "through paper.tex",
     },
   },
-  create(context) {
+  create(context: RuleContext) {
     return {
       root() {
         // 🔴 ONE GUARD, NOT THREE. The first draft had `if (!file || !existsSync(file))`
@@ -177,7 +178,7 @@ const futurePromise = {
           .split("\n")
           .map((l) => l.replace(/(^|[^\\])%.*$/, "$1"));
         lines.forEach((line, i) => {
-          const m = line.match(FUTURE_PROMISE_RE);
+          const m = FUTURE_PROMISE_RE.exec(line);
           if (!m) return;
           const column = m.index + 1;
           context.report({
@@ -259,7 +260,7 @@ const acmFrontmatterOverride = {
         "on its own",
     },
   },
-  create(context) {
+  create(context: RuleContext) {
     return {
       root() {
         // Same single guard as the sibling rule, and for the same measured reason: a separate

package/eslint.config.mjs

@@ -11,11 +11,11 @@
  * is why `scripts/rules-see-files.mjs` exists and why it runs as part of the test suite:
  * every rule declared below must be enabled for at least one file that is actually on disk.
  */
-import { texLanguage } from "./eslint-rules/latex-language.mjs";
-import texBuild from "./eslint-rules/tex-build.mjs";
+import { texLanguage } from "#eslint-rules/latex-language";
+import texBuild from "#eslint-rules/tex-build";
 import markdown from "@eslint/markdown";
-import localRules from "./eslint-rules/temp-root-realpath.mjs";
-import portRules from "./eslint-rules/install-path-literals.mjs";
+import localRules from "#eslint-rules/temp-root-realpath";
+import portRules from "#eslint-rules/install-path-literals";
 import n from "eslint-plugin-n";
 import tseslint from "typescript-eslint";
 import boundaries from "eslint-plugin-boundaries";
@@ -25,6 +25,35 @@ import { fileURLToPath } from "node:url";
 // The complexity set, shared by the TypeScript block and the ratchet below. Every function
 // measured over these limits on 2026-09-24 was either refactored under them (the #59 build code)
 // or pinned at its current maximum in RATCHET.
+const TS_FILES = ["**/*.ts", "**/*.mts"];
+
+/** `x as unknown as T` tells the checker to look away (#76). Shared: a block REPLACES a rule's options. */
+const AS_UNKNOWN_AS = {
+  selector:
+    "TSAsExpression > TSAsExpression[typeAnnotation.type='TSUnknownKeyword']",
+  message:
+    "`as unknown as` switches the type checker off. Convert with a function, or fix the type.",
+};
+
+/**
+ * A RULE MAY NOT ASK GIT. `paper/source` once bound a paper's stage to a commit sha and checked it
+ * with `git cat-file -e`; of four recorded shas, one still resolved ninety minutes later, because
+ * squash-merge and `gc` delete commits as routine. And `actions/checkout` fetches one commit, so
+ * under CI even a live sha does not resolve: the rule is red where it must hold and green locally.
+ * A rule reads the files ESLint gives it. Matched on the AST: a spawner called with the program
+ * `git` (or a shell line starting with `git `). Two things pass, deliberately: opening `.git/` with
+ * `fs`, and a program name assembled at runtime.
+ */
+const SPAWNERS = "exec|execSync|execFile|execFileSync|spawn|spawnSync|fork";
+const GIT_IN_A_RULE = [
+  `CallExpression[callee.name=/^(${SPAWNERS})$/][arguments.0.value=/^git( |$)/]`,
+  `CallExpression[callee.property.name=/^(${SPAWNERS})$/][arguments.0.value=/^git( |$)/]`,
+].map((selector) => ({
+  selector,
+  message:
+    "A rule may not run git: a sha is deleted by routine maintenance and absent from a shallow CI checkout. Read the file content ESLint passes the rule.",
+}));
+
 const MAX_LINES = { max: 60, skipComments: true, skipBlankLines: true };
 
 // 🔴 A CEILING, NOT A PERMISSION: each number is the file's measured maximum on 2026-09-24, so a
@@ -38,6 +67,20 @@ const RATCHET = {
   "src/hooks-settings.ts": { complexity: 12, "max-depth": 4 },
   "src/structure.ts": { complexity: 12, "max-depth": 4 },
   "src/new-paper.ts": { complexity: 11 },
+  // Moved from JavaScript on 2026-09-27 (#78) and measured that day: the move changed their
+  // language, not their shape, so their debt is pinned here like the rest rather than paid in it.
+  "eslint-rules/latex-language.ts": {
+    complexity: 68,
+    "max-lines-per-function": 314,
+    "max-depth": 4,
+  },
+  "eslint-rules/paper-typography.ts": { complexity: 29, "max-depth": 5 },
+  "eslint-rules/paper-stages.ts": {
+    complexity: 15,
+    "max-lines-per-function": 105,
+  },
+  "eslint-rules/temp-root-realpath.ts": { complexity: 13 },
+  "lib/markdown.ts": { complexity: 12 },
 };
 
 // ── Hexagonal layers (src/CLAUDE.md, issue #76) ─────────────────────────────────────────
@@ -121,6 +164,15 @@ export const layerBoundaries = (root) => ({
   plugins: { boundaries },
   settings: {
     "boundaries/root-path": root,
+    // `#lib/*` and `#eslint-rules/*` are package.json subpath imports; the Node resolver the plugin
+    // defaults to does not read that map and leaves them unresolved, i.e. unknown. The TypeScript
+    // resolver reads it, and with the repository's source condition lands on the `.ts` file, which
+    // is classified as the js-module element it is.
+    "import/resolver": {
+      typescript: {
+        conditionNames: ["paperlint-source", "types", "import", "node"],
+      },
+    },
     "boundaries/elements": [
       { type: "port", pattern: "src/ports", partialMatch: false },
       { type: "domain", pattern: "src/domain", partialMatch: false },
@@ -138,7 +190,7 @@ export const layerBoundaries = (root) => ({
         partialMatch: false,
         capture: ["kind"],
       },
-      // test/support.mjs — shared helpers for tests. Only the `test` category may import it: the
+      // test/support.ts — shared helpers for tests. Only the `test` category may import it: the
       // policies below allow tests any element, and allow no other file this one.
       { type: "test-support", pattern: "test", partialMatch: false },
     ],
@@ -147,7 +199,8 @@ export const layerBoundaries = (root) => ({
       { category: "root", pattern: "src/cli.ts", exclusive: true },
       // Every other file at the top of src/ is app. A new one gets the full app rules.
       { category: "app", pattern: "src/*.ts" },
-      { category: "test", pattern: "src/**/*.test.ts" },
+      // A harness is a test too: it drives the code through vigiles instead of vitest.
+      { category: "test", pattern: "src/**/*.{test,harness}.ts" },
       // AXIS B: purity is a category, orthogonal to the element.
       { category: "io", pattern: "src/adapters/*/*.io.ts" },
     ],
@@ -243,12 +296,17 @@ export const layerBoundaries = (root) => ({
  * Files that did I/O before the layers existed carry an `eslint-disable-next-line` naming #76 above
  * each such import or use; `reportUnusedDisableDirectives: "error"` turns a disable that suppresses
  * nothing into a finding, so an exemption leaves the moment its I/O does, and
- * `scripts/layer-legacy-frozen.mjs` freezes how many each file may carry. A NEW module that needs
+ * `scripts/layer-legacy-frozen.ts` freezes how many each file may carry. A NEW module that needs
  * the outside world is a new `*.io.ts` in the adapter of the program it talks to — not a disable.
  */
 export const IO_GLOBALS = {
   files: ["src/**/*.ts"],
-  ignores: ["src/cli.ts", "src/adapters/*/*.io.ts", "src/**/*.test.ts"],
+  ignores: [
+    "src/cli.ts",
+    "src/adapters/*/*.io.ts",
+    "src/**/*.test.ts",
+    "src/**/*.harness.ts",
+  ],
   linterOptions: { reportUnusedDisableDirectives: "error" },
   rules: {
     "no-restricted-globals": [
@@ -271,6 +329,27 @@ const ceiling = (rule, n) =>
     ? ["error", { ...MAX_LINES, max: n }]
     : ["error", n];
 
+/**
+ * New code is TypeScript (#78). A JavaScript file (`.js`, `.mjs`, `.cjs`) under any of these
+ * directories is an error, whatever its name — the check is on the file's AST root, so a name with
+ * any number of dots and an empty file are both caught. The directories are the ones already moved
+ * to TypeScript; each later step of #78 adds the directories it converts, and the last one replaces
+ * the list with every JavaScript file in the repository.
+ */
+const TYPESCRIPT_ONLY = [
+  "src/adapters/**/*.{js,mjs,cjs}",
+  "src/domain/**/*.{js,mjs,cjs}",
+  "src/ports/**/*.{js,mjs,cjs}",
+  // test/ itself and test/e2e — not test/fixtures/layers/eslint-rules, whose `rule.mjs` stands for
+  // the JavaScript module it is linted as.
+  "test/*.{js,mjs,cjs}",
+  "test/e2e/**/*.{js,mjs,cjs}",
+  "test/fixtures/layers/src/**/*.{js,mjs,cjs}",
+  "fixtures/real-markdown-paper/**/*.{js,mjs,cjs}",
+  "skills/paper-pipeline/scripts/fixtures/**/*.{js,mjs,cjs}",
+  "skills/plan-paper-timeline/fixtures/**/*.{js,mjs,cjs}",
+];
+
 export default [
   // 🔴 TRANSIENT DIRECTORIES ARE NOT THE CORPUS, and leaving them in is a RACE, not sloppiness.
   // `paper-stages.harness.mjs` creates a temp tree under fixtures and removes it when done,
@@ -297,37 +376,51 @@ export default [
   // 🔴 THE PACKAGE'S TYPESCRIPT, and before 2026-09-24 no block matched it — the same silent
   // ignore the `.mjs` block below was written against, recurring for `.ts` (#49). `src/` is the
   // CLI and the build; the skill specs compile into the SKILL.md files the package ships; the
-  // three hand-written `.d.mts` type the `.mjs` modules `src/` imports. All tracked TypeScript.
+  // hand-written `.d.mts` files type the `.mjs` modules `src/` imports. All tracked TypeScript.
   //
   // Measured on the first run (41727cd): 44 findings in 9 of 39 files, all in `src/`, plus one
   // `no-useless-escape` in a spec that had dropped a backslash from its compiled SKILL.md. The
   // #59 build files were refactored clean; the older CLI files sit in RATCHET, one block below.
   //
-  // NOT TYPE-AWARE, deliberately: no rule here needs type information, and `npm run build`
-  // (tsc, strict) already type-checks `src/` as the first gate of `npm run check`.
+  // TYPE-AWARE since 2026-09-27: typescript-eslint's `strictTypeChecked` preset, fed by
+  // `tsconfig.test.json`, which now includes EVERY tracked `.ts`/`.mts` (the 24 skill specs and
+  // `vitest.config.ts` had been in no tsconfig, so neither tsc nor this block type-checked them).
+  // `parserOptions.project` rather than `projectService`: the service looks for the nearest
+  // `tsconfig.json`, and the root one covers only the shipped `src/`, so every test, script and
+  // spec would fall back to a default project. First run: 374 findings in 64 files, all fixed in
+  // the same PR, none suppressed.
   //
   // NOT HERE: `port/js-install-path` (43 findings, 41 of them the specs' `.claude/skills/`
   // literals — issue #19's debt, `warn` for `.mjs` for the same reason; 2 in hooks-settings.ts,
   // which writes the consumer's settings and must name the install) and `n/no-missing-import`
-  // (tsc already fails on an unresolved import in `src/`).
+  // (tsc already fails on an unresolved import).
+  ...tseslint.configs.strictTypeChecked.map((config) => ({
+    ...config,
+    files: TS_FILES,
+  })),
   {
-    files: ["**/*.ts", "**/*.mts"],
-    languageOptions: { parser: tseslint.parser },
+    files: TS_FILES,
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        project: "./tsconfig.test.json",
+        tsconfigRootDir: dirname(fileURLToPath(import.meta.url)),
+      },
+    },
     plugins: { "@typescript-eslint": tseslint.plugin, local: localRules },
     rules: {
       // The same macOS-only defect as in the `.mjs` block; clean here, so it opens at `error`.
       "local/temp-root-realpath": "error",
-      // A dead import is a sign of an incomplete edit. The TypeScript variant, because the core
-      // rule does not understand type-only positions.
-      "@typescript-eslint/no-unused-vars": "error",
-      // `any` switches the checker off for everything it flows into — the gate that makes `src/`
-      // TypeScript at all. Five older sites are pinned inline and named in #49.
+      // `any` switches the checker off for everything it flows into. The preset has it too; named
+      // here so that dropping the preset cannot drop it.
       "@typescript-eslint/no-explicit-any": "error",
       // The behaviour rules of the `.mjs` block, for the same reasons: each changes what the code
       // DOES, not how it looks, and a regex that escapes the wrong thing searches for the wrong thing.
       "no-empty": "error",
       "no-constant-condition": "error",
-      "no-dupe-keys": "error",
+      // `no-unreachable` is switched off by the preset's `eslint-recommended` layer on the claim
+      // that tsc reports it; tsc only greys unreachable code unless `allowUnreachableCode` is
+      // false, so it is switched back on. (`no-dupe-keys` is dropped: tsc does fail on it.)
       "no-unreachable": "error",
       "no-fallthrough": "error",
       "no-useless-escape": "error",
@@ -339,15 +432,7 @@ export default [
       complexity: ["error", 10],
       // `x as unknown as T` tells the checker to look away: two spellings of one port were once
       // reconciled that way (#76). A real conversion is a function; a real subset needs no cast.
-      "no-restricted-syntax": [
-        "error",
-        {
-          selector:
-            "TSAsExpression > TSAsExpression[typeAnnotation.type='TSUnknownKeyword']",
-          message:
-            "`as unknown as` switches the type checker off. Convert with a function, or fix the type.",
-        },
-      ],
+      "no-restricted-syntax": ["error", AS_UNKNOWN_AS],
       // Nesting beyond three blocks is where a step belongs in its own named function.
       "max-depth": ["error", 3],
       // Five positional parameters are a record without field names; pass an object instead.
@@ -423,7 +508,9 @@ export default [
       // unreachable code, fallthrough in `case`.
       "no-empty": "error",
       "no-constant-condition": "error",
-      "no-dupe-keys": "error",
+      // `no-unreachable` is switched off by the preset's `eslint-recommended` layer on the claim
+      // that tsc reports it; tsc only greys unreachable code unless `allowUnreachableCode` is
+      // false, so it is switched back on. (`no-dupe-keys` is dropped: tsc does fail on it.)
       "no-unreachable": "error",
       "no-fallthrough": "error",
       // Regexes: unnecessary escaping slash and control character in class — both findings about
@@ -507,4 +594,26 @@ export default [
     // one whose firing path nothing exercises, which is rule 4 wearing a different hat. The
     // pass/fail signal lives in `npm test`, not in the warning count of `npm run lint`.
   },
+  // Rule sources, whatever their extension; tests and harnesses plant git calls on purpose.
+  {
+    files: ["eslint-rules/*.ts", "eslint-rules/*.mjs"],
+    ignores: ["eslint-rules/*.test.*", "eslint-rules/*.harness.*"],
+    rules: {
+      "no-restricted-syntax": ["error", AS_UNKNOWN_AS, ...GIT_IN_A_RULE],
+    },
+  },
+  // LAST, so no block above can replace its `no-restricted-syntax` options for these files (none
+  // sets that rule for JavaScript today; being last keeps it that way).
+  {
+    files: TYPESCRIPT_ONLY,
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector: "Program",
+          message: "New code is TypeScript (#78): write this file as .ts.",
+        },
+      ],
+    },
+  },
 ];

package/fixtures/pdf-facts/README.md

@@ -1,6 +1,6 @@
 # PDF fixtures for the pdf.js reader
 
-Real PDFs that `src/pdf-facts.harness.mjs` and `skills/render-paper/extract-pdf-facts.harness.mjs`
+Real PDFs that `src/pdf-facts.harness.ts` and `skills/render-paper/extract-pdf-facts.harness.ts`
 read. They were measured with poppler and with pdf.js on 2026-09-24 (issue #61); the harnesses pin
 poppler's numbers, so a pass means agreement with the tool pdf.js replaced.
 
@@ -13,7 +13,7 @@ poppler's numbers, so a pass means agreement with the tool pdf.js replaced.
 | `encrypted.pdf`    | `t3-all.pdf` saved with an AES-256 user password (PyMuPDF)          | pdf.js refuses it with `PasswordException`; the reader reports `encrypted`                                                        |
 | `hidden-text.pdf`  | `hidden-text.tex`, pdflatex                                         | two-column body text beside near-white, rotated and render-mode-3 text; page 2 holds only hidden text, so banal calls it blank    |
 
-`test/e2e/banal.mjs` also reads these files, with the real banal: it pins what banal 1.2 printed for
+`test/e2e/banal.ts` also reads these files, with the real banal: it pins what banal 1.2 printed for
 each one on poppler's `pdftohtml` 24.02.0 (2026-09-25), so a pass there means paperlint's pdf.js-written
 XML measures the same as poppler's. `hidden-text.pdf` exists for that test: each kind of hidden text
 changes banal's answer if it is counted.

package/fixtures/real-markdown-paper/{baseline.mjs → baseline.ts}

@@ -1,18 +1,31 @@
 /**
  * ONE reader of `baseline.json`, shared by the two runs that compare against it: the harness
- * beside this file (the repository's own `bin/paperlint.mjs`) and `test/e2e/install.mjs` (the binary
+ * beside this file (the repository's own `bin/paperlint.mjs`) and `test/e2e/install.ts` (the binary
  * a consumer actually got). Two copies of "growth fails, a drop never does" would drift the first
  * time one of them is tightened, and the two runs would then disagree about the same article.
  */
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+/** Findings per rule id. */
+export type Counts = Record<string, number>;
+
+const Baseline = z.object({ findings: z.record(z.string(), z.number()) });
+const LintOutput = z.array(
+  z.object({
+    messages: z.array(z.object({ ruleId: z.string().nullable() })).nullish(),
+  }),
+);
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
 /** The recorded counts, `{ruleId: n}`. */
-export function recordedFindings() {
-  return JSON.parse(readFileSync(join(HERE, "baseline.json"), "utf8")).findings;
+export function recordedFindings(): Counts {
+  return Baseline.parse(
+    JSON.parse(readFileSync(join(HERE, "baseline.json"), "utf8")),
+  ).findings;
 }
 
 /**
@@ -20,11 +33,13 @@ export function recordedFindings() {
  * 🔴 Output that does not parse THROWS. An empty set read as "clean" is how this repository's
  * checks have gone hollow before.
  */
-export function countByRule(stdout) {
-  const out = {};
-  for (const file of JSON.parse(stdout))
-    for (const m of file.messages ?? [])
-      out[m.ruleId] = (out[m.ruleId] ?? 0) + 1;
+export function countByRule(stdout: string): Counts {
+  const out: Counts = {};
+  for (const file of LintOutput.parse(JSON.parse(stdout)))
+    for (const m of file.messages ?? []) {
+      const rule = String(m.ruleId);
+      out[rule] = (out[rule] ?? 0) + 1;
+    }
   return out;
 }
 
@@ -37,12 +52,18 @@ export function countByRule(stdout) {
  * A partial drop is neither: it is what a fix looks like (paperlint#44 is expected to take typography
  * to zero, and then the recording is updated in the same change).
  */
-export function compareToBaseline(found, recorded = recordedFindings()) {
+export function compareToBaseline(
+  found: Readonly<Counts>,
+  recorded: Readonly<Counts> = recordedFindings(),
+): {
+  grew: { rule: string; now: number; recorded: number }[];
+  vanished: string[];
+} {
   const grew = Object.entries(found)
     .filter(([rule, n]) => n > (recorded[rule] ?? 0))
     .map(([rule, n]) => ({ rule, now: n, recorded: recorded[rule] ?? 0 }));
   const vanished = Object.keys(recorded).filter(
-    (r) => recorded[r] > 0 && !(r in found),
+    (r) => (recorded[r] ?? 0) > 0 && !(r in found),
   );
   return { grew, vanished };
 }