paperlint 3.1.3 → 4.0.0

package/docs/testing.md

@@ -18,9 +18,10 @@ When in doubt between unit and integration: if the function takes a port (`Files
 ## Unit — vitest, pure functions
 
 - **Answers:** does this function return the right value for this input?
-- **Lives:** beside the module, `<module>.test.ts` for a `.ts` module, `<module>.test.mjs` for a
-  `.mjs` one (TypeScript has no types to check a JS module against, and `allowJs` was measured to
-  break a dozen existing `@ts-expect-error` imports).
+- **Lives:** beside the module, `<module>.test.ts`. A test that IMPORTS a `.mjs` module stays
+  `<module>.test.mjs` until that module moves to TypeScript (#78): TypeScript has no types to check
+  it against, and `allowJs` was measured to break a dozen existing `@ts-expect-error` imports. A
+  test that only runs a `.mjs` script as a process has nothing to import and is `.test.ts` already.
 - **May touch:** nothing. No disk, no network, no process, no clock.
 - **Example:** `src/domain/lookup-cache.test.ts` — the reference cache's parse, serialize and key
   functions, each refusal compared as a whole value.
@@ -29,7 +30,7 @@ When in doubt between unit and integration: if the function takes a port (`Files
 
 - **Answers:** does this use case or adapter do the right thing with the world it talks to?
 - **Lives:** beside the module, named like a unit test.
-- **May touch:** a temp directory (`useTempDir` and `writeTree` in `test/support.mjs`), a child
+- **May touch:** a temp directory (`useTempDir` and `writeTree` in `test/support.ts`), a child
   process of this repository's own scripts (`runNode`). Never the real network.
 - **How fakes get in:** through the seams the code already has.
   - a port the use case takes: `memoryFiles` and `scriptedProcess` in `src/adapters/memory/`, a
@@ -51,16 +52,18 @@ When in doubt between unit and integration: if the function takes a port (`Files
 - **Asserts through** `lib/check.mjs`: `const check = createChecker();` then
   `check(label, cond, detail)`. A failure prints the label and the detail, every call is counted.
   Do not define a local `check`.
-- **Example:** `hooks/hooks.harness.mjs`.
+- **Example:** `hooks/hooks.harness.ts`.
 - **Skills are tested through vigiles**, not a bespoke runner: a home-grown runner here once printed
   byte-identical "clean" verdicts for three skills that had never loaded.
 
-## End-to-end — `test/e2e/*.mjs`
+## End-to-end — `test/e2e/*.ts`
 
 - **Answers:** does the package work once it is somewhere else? The tarball installed into another
   tree, a real `pdflatex` build, the PDF's fonts measured.
 - **May touch:** everything a user's machine has, except the network: a citation service is a
-  counting fake `fetch` even here (`test/e2e/build.mjs`).
+  counting fake `fetch` even here (`test/e2e/build.ts`).
+- **Types:** the runs import the built modules from `dist/` (the shipped path is the point), so
+  their types are the declarations `tsc` emits — `npm run build` before type-checking them.
 - **What each run proves, and when a change owes one:** [`e2e.md`](e2e.md).
 
 ## Running
@@ -108,7 +111,7 @@ file matches, and it transpiles without type-checking, so `npm run check` runs
 5. **Coverage is 100% on lines, statements, functions and branches**, enforced by `npm run coverage`
    in `npm run check` and CI. c8 reads `NODE_V8_COVERAGE`, so a CLI a test spawns is measured too,
    unless the test hands the child a fresh `env` without it. vitest runs in the `threads` pool with
-   native `import` (`vitest.config.ts` says why), and the run preloads `test/coverage-src.mjs`, which
+   native `import` (`vitest.config.ts` says why), and the run preloads `test/coverage-src.ts`, which
    answers every import of `dist/*.js` with `src/*.ts`, so no module is measured twice.
 6. **No `c8 ignore`, and no guard deleted to reach 100%.** An effect a test cannot reach — a race, a
    permission root is never denied, a broken install, a 270 MB download — is made injectable and the

package/docs/toolchain.md

@@ -97,7 +97,7 @@ accepts as input. Measured on 50 PDFs / 598 pages (2026-09-25): banal on paperli
 real `pdftohtml` agree on every field the facts file keeps, with no venue verdict changed. They
 agree only because paperlint leaves out rotated and invisible text (as `pdftohtml` does), writes each
 text's colour so banal drops light text by its own rule, and writes sizes and coordinates at the
-zoom and precision banal expects. `test/e2e/banal.mjs` checks each of those against the real banal
+zoom and precision banal expects. `test/e2e/banal.ts` checks each of those against the real banal
 on the committed fixtures.
 
 **How it is installed — and the licence boundary.** banal is **GPL-2.0-or-later**; paperlint is MIT. paperlint

package/eslint-rules/{bib-reachable-entry.mjs → bib-reachable-entry.ts}

@@ -21,7 +21,8 @@
  * a field name followed by `=` — BibTeX's own lexical shape, one lexeme at a time, not a parse:
  * the parser (`@retorquere/bibtex-parser`) is an OPTIONAL peer of this package.
  */
-import { bibRange } from "./paper-typography.mjs";
+import { bibRange } from "./paper-typography.ts";
+import type { RuleContext } from "./rule-context.ts";
 
 /** Entry types that are not references. */
 const NOT_AN_ENTRY = /^@(comment|string|preamble)\b/i;
@@ -32,7 +33,7 @@ export default {
   rules: {
     "reachable-entry": {
       meta: {
-        type: "suggestion",
+        type: "suggestion" as const,
         docs: {
           description:
             "a bibliography entry carries a doi, a url or an arXiv id — something a reader can follow",
@@ -43,7 +44,7 @@ export default {
             "`{{key}}` has no doi, url or arXiv id — a reader has nothing to follow. If none exists, keep the exception with `% eslint-disable-next-line bib/reachable-entry -- <why>` above the entry",
         },
       },
-      create(context) {
+      create(context: RuleContext) {
         return {
           "root:exit"() {
             const sc = context.sourceCode;
@@ -55,7 +56,7 @@ export default {
               const entry = bib.body.slice(s, starts[i + 1] ?? bib.body.length);
               if (NOT_AN_ENTRY.test(entry)) return;
               if (HAS_LINK.test(entry) || HAS_ARXIV.test(entry)) return;
-              const head = entry.split("\n")[0];
+              const [head = ""] = entry.split("\n");
               const key = /\{\s*([^,\s]+)/.exec(head)?.[1] ?? "?";
               const from = bib.bodyStart + s;
               context.report({

package/eslint-rules/install-path-literals.harness.mjs

@@ -17,7 +17,7 @@ import { fileURLToPath } from "node:url";
 import { ESLint } from "eslint";
 import markdown from "@eslint/markdown";
 import { recordCheck } from "vigiles";
-import port, { PORT } from "./install-path-literals.mjs";
+import port, { PORT } from "./install-path-literals.ts";
 
 // Resolved from THIS file, never from the caller's cwd — rule 6, and the mistake this very
 // class of bug is about.

package/eslint-rules/{install-path-literals.mjs → install-path-literals.ts}

@@ -22,6 +22,8 @@
  * The parser can: this rule sees nodes, and it is pointed only at skills.
  */
 
+import type { RuleContext } from "./rule-context.ts";
+
 // Each entry is a prefix that only makes sense in ONE install channel.
 const CHANNEL_PREFIXES = [
   ".claude/skills/", // the consumer symlinks the package's skills to here
@@ -31,7 +33,7 @@ const CHANNEL_PREFIXES = [
 ];
 
 /** The first channel prefix appearing in `s`, or null. Plain substring: a path IS a string. */
-function channelPrefixIn(s) {
+function channelPrefixIn(s: unknown): string | null {
   if (typeof s !== "string") return null;
   for (const p of CHANNEL_PREFIXES) if (s.includes(p)) return p;
   return null;
@@ -42,7 +44,7 @@ function channelPrefixIn(s) {
 // that never existed (#67) and read fine for a week: the harness now requires it on disk.
 const PORT = "skills/paper-pipeline/scripts/consumer.mjs";
 
-const MESSAGES = {
+const MESSAGES: Readonly<Record<string, string>> = {
   installPath:
     "This names a file by where it is INSTALLED ('{{prefix}}'), so it resolves in one " +
     "delivery channel and does not exist in another. Rule 10: every answer to *where* comes " +
@@ -53,7 +55,7 @@ const MESSAGES = {
 /** Markdown: a skill's own prose, its fenced commands, and its YAML frontmatter. */
 const mdInstallPath = {
   meta: {
-    type: "problem",
+    type: "problem" as const,
     docs: {
       description:
         "a skill must not name its scripts by an install-specific path — rule 10, the port owns where",
@@ -61,8 +63,8 @@ const mdInstallPath = {
     schema: [],
     messages: MESSAGES,
   },
-  create(context) {
-    const check = (node) => {
+  create(context: RuleContext) {
+    const check = (node: { readonly value?: unknown }) => {
       const prefix = channelPrefixIn(node.value);
       if (prefix)
         context.report({ node, messageId: "installPath", data: { prefix } });
@@ -76,7 +78,7 @@ const mdInstallPath = {
 /** JavaScript: the modules this package ships. */
 const jsInstallPath = {
   meta: {
-    type: "problem",
+    type: "problem" as const,
     docs: {
       description:
         "a shipped module must not carry an install-specific path literal — rule 10, the port owns where",
@@ -84,17 +86,23 @@ const jsInstallPath = {
     schema: [],
     messages: MESSAGES,
   },
-  create(context) {
-    const report = (node, prefix) =>
+  create(context: RuleContext) {
+    const report = (node: object, prefix: string) => {
       context.report({ node, messageId: "installPath", data: { prefix } });
+    };
     return {
-      Literal(node) {
+      Literal(node: { readonly value: unknown }) {
         const prefix = channelPrefixIn(node.value);
         if (prefix) report(node, prefix);
       },
       // A template literal's static parts are just as much a path as a plain string; its
       // interpolations are not our business, which is why the quasis are read one by one.
-      TemplateElement(node) {
+      TemplateElement(node: {
+        readonly value?: {
+          readonly cooked?: string | null;
+          readonly raw: string;
+        };
+      }) {
         const prefix = channelPrefixIn(node.value?.cooked ?? node.value?.raw);
         if (prefix) report(node, prefix);
       },

package/eslint-rules/latex-language.harness.mjs

@@ -57,7 +57,7 @@ import { fileURLToPath } from "node:url";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(HERE, ".."); // eslint-rules → repository root
-const LANG = join(HERE, "latex-language.mjs");
+const LANG = join(HERE, "latex-language.ts");
 assert.ok(existsSync(LANG), `no entry point for the test: ${LANG}`);
 
 const { texLanguage, texToMdast } = await import(LANG);
@@ -507,7 +507,7 @@ const headings = (root) => root.children.filter((c) => c.type === "heading");
   // the file has to exist on disk (the rule reads it from disk, and a missing path makes it
   // silent for the wrong reason), and a `.tex` file written inside the repository would also
   // be picked up by the glob assertions in part V.
-  const texBuild = (await import(join(HERE, "tex-build.mjs"))).default;
+  const texBuild = (await import(join(HERE, "tex-build.ts"))).default;
   const local = new ESLint({
     cwd: TMP,
     overrideConfigFile: true,

package/eslint-rules/latex-language.test.mjs

@@ -5,7 +5,7 @@
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";
-import { texLanguage, texToMdast } from "./latex-language.mjs";
+import { texLanguage, texToMdast } from "./latex-language.ts";
 
 /** The projection plus each node's type, lang/title and start–end offsets. */
 const project = (src) => {
@@ -66,6 +66,12 @@ test("a body the parser cannot take (nesting deep enough to exhaust its stack) i
     [r.ok, r.errors.map((e) => e.constructor.name)],
     [false, ["RangeError"]],
   );
+  // ESLint prints a parse failure at its `line` and `column`; a failure of the whole parse has no
+  // position of its own, so it sits at the start of the file rather than at `undefined:undefined`.
+  assert.deepEqual(
+    r.errors.map((e) => [e.line, e.column]),
+    [[1, 1]],
+  );
 });
 
 /** A node position on line 1, from offset `a` to offset `b`. */