paperlint 3.1.0 → 3.1.1

package/src/link-skills.ts

@@ -60,13 +60,18 @@ export type Located =
  *
  * @returns `dir` — the real directory; `spelled` — the same directory as the project names it.
  */
-export function locatePackage(project: string): Located {
+export function locatePackage(
+  project: string,
+  {
+    resolveManifest = (from: string): string =>
+      createRequire(
+        pathToFileURL(join(from, "__paperlint_locate__.js")).href,
+      ).resolve(`${PACKAGE_NAME}/package.json`),
+  }: { resolveManifest?: (project: string) => string } = {},
+): Located {
   let manifest: string;
   try {
-    const req = createRequire(
-      pathToFileURL(join(project, "__paperlint_locate__.js")).href,
-    );
-    manifest = req.resolve(`${PACKAGE_NAME}/package.json`);
+    manifest = resolveManifest(project);
   } catch (e) {
     return {
       error: `${(e as NodeJS.ErrnoException).code ?? "error"}: ${(e as Error).message.split("\n")[0]}`,
@@ -126,10 +131,28 @@ export type LinkReport =
     }
   | { readonly ok: false; readonly error: string };
 
+/** The filesystem calls linking makes — the disk by default; a test stages a race or a refusal. */
+export interface LinkFs {
+  readonly lstatSync: (p: string) => {
+    isSymbolicLink(): boolean;
+    isDirectory(): boolean;
+  };
+  readonly realpathSync: (p: string) => string;
+  readonly readlinkSync: (p: string) => string;
+  readonly symlinkSync: (target: string, path: string, type: "dir") => void;
+}
+const nodeLinkFs: LinkFs = {
+  lstatSync,
+  realpathSync,
+  readlinkSync,
+  symlinkSync,
+};
+
 /** What occupies `entry`, judged against the directory it should lead to. */
 function inspect(
   entry: string,
   want: string,
+  { lstatSync, realpathSync, readlinkSync }: LinkFs,
 ): { status: "present" | "missing" | "foreign"; reason?: string } {
   let st;
   try {
@@ -163,15 +186,22 @@ function linkOne(
     target,
     want,
     write,
-  }: { entry: string; target: string; want: string; write: boolean },
+    fs,
+  }: {
+    entry: string;
+    target: string;
+    want: string;
+    write: boolean;
+    fs: LinkFs;
+  },
 ): SkillLink {
-  const seen = inspect(entry, want);
+  const seen = inspect(entry, want, fs);
   if (!write || seen.status !== "missing")
     return seen.reason
       ? { name, status: seen.status, reason: seen.reason }
       : { name, status: seen.status };
   try {
-    symlinkSync(target, entry, "dir");
+    fs.symlinkSync(target, entry, "dir");
     return { name, status: "created" };
   } catch (e) {
     return {
@@ -182,6 +212,16 @@ function linkOne(
   }
 }
 
+/** Create the skills home; the reason it could not be, or null. */
+function makeHome(home: string): string | null {
+  try {
+    mkdirSync(home, { recursive: true });
+    return null;
+  } catch (e) {
+    return `cannot create ${home}: ${(e as Error).message}`;
+  }
+}
+
 /**
  * Link every shipped skill into `<project>/.claude/skills/`, or — with `write: false` — only
  * report which ones are missing (that is what `paperlint doctor` asks).
@@ -191,7 +231,12 @@ export function linkSkills(
   {
     write = true,
     locate = locatePackage,
-  }: { write?: boolean; locate?: (p: string) => Located } = {},
+    fs = nodeLinkFs,
+  }: {
+    write?: boolean;
+    locate?: (p: string) => Located;
+    fs?: LinkFs;
+  } = {},
 ): LinkReport {
   const pkg = locate(project);
   if ("error" in pkg)
@@ -205,20 +250,28 @@ export function linkSkills(
   const spelledSkills = join(pkg.spelled, relative(pkg.dir, shipped.skillsDir));
 
   const home = join(project, SKILLS_HOME);
-  if (write && shipped.names.length > 0) {
-    try {
-      mkdirSync(home, { recursive: true });
-    } catch (e) {
-      return {
-        ok: false,
-        error: `cannot create ${home}: ${(e as Error).message}`,
-      };
-    }
-  }
+  const made = write && shipped.names.length > 0 ? makeHome(home) : null;
+  if (made !== null) return { ok: false, error: made };
+  return {
+    ok: true,
+    home,
+    ...linkAll(shipped, { spelledSkills, home, write, fs }),
+  };
+}
+
+/** Every shipped skill's link, and the first one's target as the report's example. */
+function linkAll(
+  shipped: { readonly skillsDir: string; readonly names: readonly string[] },
+  {
+    spelledSkills,
+    home,
+    write,
+    fs,
+  }: { spelledSkills: string; home: string; write: boolean; fs: LinkFs },
+): { example: string | null; links: SkillLink[] } {
   // A relative target resolves against the directory that PHYSICALLY holds the link, so it is
   // computed from the real one — `.claude` may itself be a symlink.
   const physicalHome = existsSync(home) ? realpathSync(home) : resolve(home);
-
   let example: string | null = null;
   const links = shipped.names.map((name): SkillLink => {
     const target = relative(physicalHome, join(spelledSkills, name));
@@ -228,7 +281,8 @@ export function linkSkills(
       target,
       want: realpathSync(join(shipped.skillsDir, name)),
       write,
+      fs,
     });
   });
-  return { ok: true, home, example, links };
+  return { example, links };
 }

package/src/new-paper.harness.mjs

@@ -16,7 +16,6 @@
  * ⚠️ Assertions at the TOP LEVEL: `vigiles test` imports the file and counts "did not throw"
  * as a pass.
  */
-import assert from "node:assert/strict";
 import {
   existsSync,
   mkdirSync,
@@ -32,6 +31,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { load } from "js-yaml";
 import { frontmatterBlock } from "../lib/markdown.mjs";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = dirname(HERE);
@@ -46,11 +46,7 @@ const {
 } = await import(join(HERE, "new-paper.ts"));
 const { run } = await import(join(HERE, "cli.ts"));
 
-let n = 0;
-const check = (label, cond) => {
-  n++;
-  assert.ok(cond, label);
-};
+const check = createChecker();
 
 const work = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-new-")));
 const read = (...p) => readFileSync(join(...p), "utf8");
@@ -217,5 +213,5 @@ try {
 }
 
 console.log(
-  `✓ ${String(n)} assertions passed — paperlint new scaffolds what paperlint lint accepts`,
+  `✓ ${String(check.count)} assertions passed — paperlint new scaffolds what paperlint lint accepts`,
 );

package/src/new-paper.test.ts

@@ -15,7 +15,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { existsSync } from "node:fs";
-import { newPaper, OVERRIDE_DIR } from "./new-paper.ts";
+import { newPaper, OVERRIDE_DIR, reportNewPaper } from "./new-paper.ts";
 import { parsePaperSettings } from "./paper-settings.ts";
 import { chooseVenue, run } from "./cli.ts";
 import { shippedPresets } from "./presets.ts";
@@ -302,3 +302,33 @@ describe("chooseVenue — on a terminal", () => {
     expect(t.asked).toEqual([]);
   });
 });
+
+describe("a project's own template", () => {
+  it("🔴 a template paperlint.json with comments refuses --venue by name, and nothing is made", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, OVERRIDE_DIR), { recursive: true });
+    const src = join(papers, OVERRIDE_DIR, "paperlint.json");
+    writeFileSync(src, '{\n  // our house venue\n  "extends": null\n}\n');
+    const r = newPaper(papers, "p", "tex", {
+      venue: { extends: "paperlint:aisec", kind: null },
+    });
+    expect(r).toEqual({
+      ok: false,
+      reason: `--venue cannot be written into ${src}: it is not plain JSON — set "extends" by hand`,
+    });
+    expect(existsSync(join(papers, "p"))).toBe(false);
+  });
+
+  it("the report names where each created file came from", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, OVERRIDE_DIR), { recursive: true });
+    writeFileSync(join(papers, OVERRIDE_DIR, "paperlint.json"), "{}\n");
+    const lines = reportNewPaper(newPaper(papers, "p", "tex"), (p) => p);
+    expect(lines).toContain(
+      "      + paperlint.json  (from the project's .template/ template)",
+    );
+    expect(
+      lines.filter((l) => l.endsWith("(from the package template)")).length,
+    ).toBeGreaterThan(0);
+  });
+});

package/src/paper-files.test.ts

@@ -319,6 +319,18 @@ describe("paper-files — the pieces", () => {
   });
 });
 
+describe("paper-files — blocks that carry no rules", () => {
+  it("a plugin with only a language registers no rule; a block with no files owns no pattern of its own", () => {
+    const own = [
+      { plugins: { tex: { languages: {} } } },
+      { ignores: ["**/x.md"], plugins: { tex: { languages: {} } } },
+      { files: ["**/a.md"], plugins: { p: { rules: { one: {} } } } },
+    ];
+    expect([...ruleOwners(own).keys()]).toEqual(["p/one"]);
+    expect(ownedPatterns(own)).toEqual(["**/a.md"]);
+  });
+});
+
 describe("paper-files — narrowing a block", () => {
   const own = [
     { plugins: { g: { rules: { any: {} } } } },

package/src/paper-files.ts

@@ -71,8 +71,9 @@ export interface ScopedBlock {
   readonly rules: Readonly<Record<string, RuleEntry>>;
 }
 
-const globsOf = (b: Block): string[] =>
-  (b.files ?? []).filter((f): f is string => typeof f === "string");
+/** A block's `files`, the string globs only. */
+const globsOf = (files: readonly unknown[]): string[] =>
+  files.filter((f): f is string => typeof f === "string");
 
 const stringsOf = (xs: readonly unknown[] | undefined): string[] =>
   (xs ?? []).filter((x): x is string => typeof x === "string");
@@ -102,8 +103,11 @@ export function ownedScopes(own: readonly unknown[]): OwnedScope[] {
   return merged(
     own
       .map((raw) => raw as Block)
-      .filter((b) => b.files !== undefined)
-      .map((b) => ({ files: globsOf(b), ignores: stringsOf(b.ignores) })),
+      .flatMap((b) =>
+        b.files === undefined
+          ? []
+          : [{ files: globsOf(b.files), ignores: stringsOf(b.ignores) }],
+      ),
   );
 }
 
@@ -150,7 +154,7 @@ export function ruleOwners(
     const scopes =
       b.files === undefined
         ? all
-        : [{ files: globsOf(b), ignores: stringsOf(b.ignores) }];
+        : [{ files: globsOf(b.files), ignores: stringsOf(b.ignores) }];
     for (const id of ruleIdsOf(b))
       found.set(id, [...(found.get(id) ?? []), ...scopes]);
   }

package/src/paper-settings.test.ts

@@ -118,6 +118,26 @@ describe("readPaperSettings", () => {
   });
 });
 
+describe("readPaperSettings — a root paperlint.json that cannot be used", () => {
+  const ROOT = "/work";
+  const withFiles = (f: Record<string, string>) =>
+    memoryFiles({ [`${ROOT}/package.json`]: "{}", ...f });
+
+  it("a root file that does not parse, or names a field of the wrong type, is the paper's problem too", () => {
+    const broken = (root: string) =>
+      readPaperSettings(withFiles({ [`${ROOT}/paperlint.json`]: root }), PAPER);
+    const notJson = broken("{ nope");
+    expect(!notJson.ok && notJson.error.kind).toBe("broken");
+    expect(broken('{"kind":3}')).toEqual({
+      ok: false,
+      error: {
+        kind: "broken",
+        why: expect.stringMatching(/^the root paperlint\.json: .*kind/),
+      },
+    });
+  });
+});
+
 describe("readPaperSettings — the root paperlint.json's defaults, the paper's file over them", () => {
   const ROOT = "/work";
   const withFiles = (f: Record<string, string>) =>

package/src/pdf-facts.harness.mjs

@@ -11,17 +11,14 @@ import { writeFileSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const FIX = resolve(HERE, "..", "fixtures", "pdf-facts");
 const { readPdf } = await import(join(HERE, "pdf-facts.ts"));
 const { classifyLastPage } = await import(join(HERE, "pdf-geometry.ts"));
 
-let n = 0;
-const check = (label, cond, detail = "") => {
-  assert.ok(cond, detail ? `${label} — ${detail}` : label);
-  n++;
-};
+const check = createChecker();
 
 const read = async (name) => {
   const r = await readPdf(join(FIX, name));
@@ -184,5 +181,5 @@ try {
 }
 
 console.log(
-  `✓ ${String(n)} assertions passed — pdf-facts: pdf.js on real PDFs agrees with poppler, and says what it cannot read`,
+  `✓ ${String(check.count)} assertions passed — pdf-facts: pdf.js on real PDFs agrees with poppler, and says what it cannot read`,
 );

package/src/pdf-facts.test.ts

@@ -0,0 +1,144 @@
+/**
+ * pdf-facts.ts on document shapes real test PDFs do not carry, through a fake pdf.js document
+ * (the real pdf.js library for its transforms and operator codes): a font object that is not one,
+ * a font without a name or metrics, an item whose font never resolved, zero-scale transforms, a
+ * document with no pages, text with no font, and a failure that is not an Error.
+ */
+import assert from "node:assert/strict";
+import { getResolvedPDFJS } from "unpdf";
+import { test } from "vitest";
+import { factsOf, failureOf, rawFontOf } from "./pdf-facts.ts";
+
+const lib = await getResolvedPDFJS();
+const H = 792;
+
+interface FakeItem {
+  str: string;
+  fontName: string;
+  transform: number[];
+  width: number;
+  height: number;
+}
+/** A page whose text items and loaded fonts are given; its viewport flips y like pdf.js's. */
+function page(items: FakeItem[], fonts: Record<string, unknown>) {
+  const objs = new Map(Object.entries(fonts));
+  return {
+    getOperatorList: async () => ({ fnArray: [], argsArray: [] }),
+    getTextContent: async () => ({ items }),
+    // Iterable like pdf.js's `commonObjs`, with its `has`/`get`.
+    commonObjs: {
+      has: (id: string) => objs.has(id),
+      get: (id: string) => objs.get(id),
+      [Symbol.iterator]: () => objs[Symbol.iterator](),
+    },
+    getViewport: () => ({
+      width: 612,
+      height: H,
+      transform: [1, 0, 0, -1, 0, H],
+      convertToViewportPoint: (x: number, y: number) => [x, H - y],
+    }),
+  };
+}
+const doc = (pages: ReturnType<typeof page>[]) =>
+  ({
+    numPages: pages.length,
+    getPage: async (i: number) => pages[i - 1],
+  }) as never;
+const item = (
+  fontName: string,
+  transform: number[],
+  height = 10,
+): FakeItem => ({
+  str: "word",
+  fontName,
+  transform,
+  width: 20,
+  height,
+});
+
+test("rawFontOf: not an object, not a font, and a font without a name", () => {
+  assert.deepEqual(
+    [
+      rawFontOf("a", null),
+      rawFontOf("b", { x: 1 }),
+      rawFontOf("c", { loadedName: "L" }),
+    ],
+    [
+      null,
+      null,
+      {
+        id: "c",
+        name: "",
+        type: undefined,
+        subtype: undefined,
+        isType3Font: false,
+        missingFile: false,
+      },
+    ],
+  );
+});
+
+test("a document with no pages is `empty`; text drawn with no font is refused", async () => {
+  assert.deepEqual(await factsOf(doc([]), lib), {
+    ok: false,
+    reason: "empty",
+    detail: "the PDF has no pages",
+  });
+  const r = await factsOf(
+    doc([page([item("f0", [10, 0, 0, 10, 50, 700])], {})]),
+    lib,
+  );
+  assert.equal(r.ok, false);
+  assert.equal(!r.ok && r.reason, "zero-fonts-on-text");
+});
+
+test("metrics, sizes and names fall back when pdf.js gives none", async () => {
+  const fonts = {
+    // a font with a name and an ascent but no descent
+    f1: { loadedName: "f1", name: "Named", ascent: 0.8 },
+    // a font with no name and no metrics at all
+    f2: { loadedName: "f2" },
+  };
+  const r = await factsOf(
+    doc([
+      page(
+        [
+          item("f1", [10, 0, 0, 10, 50, 700]),
+          // zero horizontal scale: the size comes from the item's height…
+          item("f2", [0, 0, 0, 0, 100, 700], 12),
+          // …or, with no height either, from the vertical scale
+          item("f2", [0, 0, 0, 9, 150, 700], 0),
+          // an item whose font pdf.js never resolved
+          item("gone", [10, 0, 0, 10, 200, 700]),
+        ],
+        fonts,
+      ),
+    ]),
+    lib,
+  );
+  assert.equal(r.ok, true);
+  const boxes = r.ok ? r.facts.layout[0]!.boxes : [];
+  assert.deepEqual(
+    boxes.map((b) => [b.font, b.size, b.fill]),
+    [
+      ["Named", 10, { kind: "unknown" }],
+      ["f2", 12, { kind: "unknown" }],
+      ["f2", 9, { kind: "unknown" }],
+      ["gone", 10, { kind: "unknown" }],
+    ],
+  );
+  assert.deepEqual(r.ok ? r.facts.last.words.map((w) => w.text) : [], [
+    "word",
+    "word",
+    "word",
+    "word",
+  ]);
+});
+
+test("a failure that is not an Error is named `Error` with its text", () => {
+  assert.deepEqual(failureOf("boom"), {
+    ok: false,
+    reason: "unreadable",
+    detail: "Error: boom",
+  });
+});

package/src/pdf-facts.ts

@@ -33,7 +33,7 @@ import {
 } from "./pdf-geometry.ts";
 import type { PageLayout, TextBox } from "./domain/page-layout.ts";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
-import { fillsOf, isUpright } from "./adapters/pdfjs/fill.ts";
+import { fillsFor, isUpright } from "./adapters/pdfjs/fill.ts";
 
 type PdfJs = Awaited<ReturnType<typeof import("unpdf").getResolvedPDFJS>>;
 type Doc = Awaited<ReturnType<PdfJs["getDocument"]>["promise"]>;
@@ -241,20 +241,18 @@ function layoutOf(
   lib: PdfJs,
 ): PageLayout {
   const vp = page.getViewport({ scale: 1 });
-  const fills = fillsOf(
-    lib.OPS,
-    ops,
-    items.map((it) => it.str),
+  const boxes = fillsFor(lib.OPS, ops, items, (it) => it.str).map(
+    ({ item, fill }): TextBox => ({ ...boxOf(page, vp, item, lib), fill }),
   );
-  const boxes = items.map((it, k): TextBox => ({
-    ...boxOf(page, vp, it, lib),
-    fill: fills[k] ?? { kind: "unknown" },
-  }));
   return { widthPt: vp.width, heightPt: vp.height, boxes };
 }
 
-/** Every page's fonts, and the last page's words. */
-async function factsOf(doc: Doc, lib: PdfJs): Promise<PdfRead> {
+/**
+ * Every page's fonts, and the last page's words. Exported with `failureOf` so a test can hand it a
+ * document whose objects pdf.js shapes only in rare files (a font without metrics, a zero-scale
+ * transform, no pages) — `readPdf` below is the one production caller.
+ */
+export async function factsOf(doc: Doc, lib: PdfJs): Promise<PdfRead> {
   const read: {
     page: Page;
     raw: RawPage;
@@ -290,7 +288,7 @@ async function factsOf(doc: Doc, lib: PdfJs): Promise<PdfRead> {
 }
 
 /** pdf.js's own exception names for the two conditions a caller can act on. */
-function failureOf(e: unknown): PdfRead {
+export function failureOf(e: unknown): PdfRead {
   const err = e as { name?: string; message?: string };
   const detail = `${err.name ?? "Error"}: ${err.message ?? String(e)}`;
   return fail(
@@ -309,13 +307,13 @@ export const readPdf: PdfReader = async (path) => {
   }
   const lib = await loadPdfJs();
   const task = lib.getDocument({ data, ...PDFJS_OPTIONS });
-  try {
-    return await factsOf(await task.promise, lib);
-  } catch (e) {
-    return failureOf(e);
-  } finally {
-    await task.destroy();
-  }
+  // A promise chain rather than try/catch/finally: every path returns a value here, and the code
+  // after such a statement is a block that can never run — which coverage reports as unrun.
+  const read = await task.promise
+    .then((doc) => factsOf(doc, lib))
+    .catch(failureOf);
+  await task.destroy();
+  return read;
 };
 
 /** The one wording of a failed read, as a build step or a CLI prints it. */

package/src/pdf-geometry.harness.mjs

@@ -6,9 +6,9 @@
  * on 2026-08-29 (the midpoint cut, the review build, years mistaken for line numbers), ported from
  * the harness of the function this replaces.
  */
-import assert from "node:assert/strict";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const {
@@ -21,11 +21,7 @@ const {
   STUB_WORDS,
 } = await import(join(HERE, "pdf-geometry.ts"));
 
-let n = 0;
-const check = (label, cond) => {
-  assert.ok(cond, label);
-  n++;
-};
+const check = createChecker();
 
 const W = 612; // US letter, points
 
@@ -250,5 +246,5 @@ check(
 );
 
 console.log(
-  `✓ ${String(n)} assertions passed — pdf-geometry: columns, stub/review, words from runs, fonts`,
+  `✓ ${String(check.count)} assertions passed — pdf-geometry: columns, stub/review, words from runs, fonts`,
 );

package/src/pdf-geometry.ts

@@ -136,7 +136,7 @@ export function wordsOf(run: TextRun): Word[] {
   const y0 = run.baseline - run.ascent * run.size;
   const y1 = run.baseline - run.descent * run.size;
   return [...run.text.matchAll(/\S+/g)].map((m) => {
-    const x0 = run.x + (m.index ?? 0) * perChar;
+    const x0 = run.x + m.index * perChar;
     return { x0, y0, x1: x0 + m[0].length * perChar, y1, text: m[0] };
   });
 }

package/src/presets.test.ts

@@ -230,6 +230,8 @@ describe("labelOf — display only, never used to resolve", () => {
     ["paperlint:agenticdev", "agenticdev"],
     ["./venues/usenix-sec.jsonc", "usenix-sec"],
     ["../shared/acl.json", "acl"],
+    ["./.hidden", ".hidden"],
+    ["paperlint:", ""],
   ])("%s → %s", (spec, label) => {
     expect(labelOf(spec)).toBe(label);
   });

package/src/presets.ts

@@ -293,5 +293,11 @@ export function paperPresetProblem(
   if (p.kind === "preset-problem")
     return `${join(paperDir, CONFIG_FILE)}: ${presetProblemText(p.problem)}`;
   if (p.kind !== "settings-problem") return null;
-  return `${join(paperDir, CONFIG_FILE)}: ${p.problem.why}`;
+  return settingsProblemLine(paperDir, p.problem);
 }
+
+/** The one line naming a paper's `paperlint.json` that does not parse, and why. */
+export const settingsProblemLine = (
+  paperDir: string,
+  problem: SettingsProblem,
+): string => `${join(paperDir, CONFIG_FILE)}: ${problem.why}`;