paperlint 2.0.1 → 3.0.0

package/src/doctor.harness.mjs

@@ -12,10 +12,7 @@
  * Killed by: src/doctor.mutations.mjs
  */
 import assert from "node:assert/strict";
-import {
-  OLD_PAPERS_DIR_FIELD,
-  PAPERS_DIR_FIELD,
-} from "../lib/paper-config.mjs";
+import { PAPERS_DIR_FIELD } from "../lib/paper-config.mjs";
 import {
   mkdtempSync,
   mkdirSync,
@@ -41,8 +38,8 @@ const check = (label, cond) => {
   assert.ok(cond, label);
 };
 
-/** A consumer on disk: a papers directory, and maybe a declaration in package.json. */
-function consumer({ papersDir, pkgKey, makeDir = true }) {
+/** A consumer on disk: a papers directory, and maybe a declaration in the root paperlint.json. */
+function consumer({ papersDir, declared, makeDir = true }) {
   const dir = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-doctor-")));
   if (makeDir && papersDir) {
     mkdirSync(join(dir, papersDir, "some-paper"), { recursive: true });
@@ -51,9 +48,15 @@ function consumer({ papersDir, pkgKey, makeDir = true }) {
       "# s\n",
     );
   }
-  const pkg = { name: "consumer", version: "1.0.0" };
-  if (pkgKey !== undefined) pkg["paperlint"] = { [PAPERS_DIR_FIELD]: pkgKey };
-  writeFileSync(join(dir, "package.json"), JSON.stringify(pkg, null, 2));
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name: "consumer", version: "1.0.0" }, null, 2),
+  );
+  if (declared !== undefined)
+    writeFileSync(
+      join(dir, "paperlint.json"),
+      JSON.stringify({ [PAPERS_DIR_FIELD]: declared }, null, 2),
+    );
   return dir;
 }
 
@@ -76,7 +79,7 @@ const runDoctor = (
 
 // ── I. A CONSISTENT INSTALL IS SILENT ───────────────────────────────────────────────────────
 {
-  const dir = consumer({ papersDir: "papers", pkgKey: "papers" });
+  const dir = consumer({ papersDir: "papers", declared: "papers" });
   const r = runDoctor(dir, { cliPapers: "papers" });
   check("a consistent install — exit ZERO", r.code === 0);
   check(
@@ -86,30 +89,9 @@ const runDoctor = (
   rmSync(dir, { recursive: true, force: true });
 }
 
-// ── I½. THE OLD FIELD NAME IS A FAILURE, NAMED ─────────────────────────────────────────────
-{
-  const dir = consumer({ papersDir: "papers", pkgKey: "papers" });
-  writeFileSync(
-    join(dir, "package.json"),
-    JSON.stringify({
-      name: "consumer",
-      paperlint: { [OLD_PAPERS_DIR_FIELD]: "papers" },
-    }),
-  );
-  const r = runDoctor(dir, { cliPapers: null });
-  check("the old field name — exit NON-zero", r.code !== 0);
-  check(
-    "and doctor says what the field was renamed to",
-    r.out.includes(
-      `"${OLD_PAPERS_DIR_FIELD}" was renamed to "${PAPERS_DIR_FIELD}" in package.json → "paperlint"`,
-    ),
-  );
-  rmSync(dir, { recursive: true, force: true });
-}
-
 // ── II. THE VERY DEFECT: AN INSTALL FOLLOWING THE DOCS ─────────────────────────────────────
-// The old `init` wrote its own config file and did not touch package.json; the hook reads package.json.
-// Measured 09-18.
+// The CLI lints one directory and the hook guards another: the install that motivated doctor
+// (issue #33). Here the CLI was pointed elsewhere while the hook took the default.
 {
   const dir = consumer({ papersDir: "writing/drafts" });
   const r = runDoctor(dir, { cliPapers: "writing/drafts" });
@@ -137,21 +119,31 @@ const runDoctor = (
   rmSync(dir, { recursive: true, force: true });
 }
 
-// ── II-bis. A MISSING DECLARATION THAT DOES NO HARM YET ────────────────────────────────────
-// The papers live exactly where the hook's default points. The install WORKS — by coincidence.
-// It must not fail here (an error-level false positive costs more than a miss), but it must
-// not stay silent either.
+// ── II-bis. NO paperlint.json — EVERY DEFAULT, AND THAT IS A VALID PROJECT ─────────────────
+// The CLI and the hooks both take `papers` when nothing is declared, so they cannot disagree.
 {
   const dir = consumer({ papersDir: "papers" });
   const r = runDoctor(dir, { cliPapers: "papers" });
-  check("an install that works by coincidence does NOT crash", r.code === 0);
+  check("no paperlint.json — exit ZERO", r.code === 0);
   check(
-    "but the missing declaration is NAMED, not skipped",
-    /⚠ package\.json has no "paperlint"/.test(r.out),
+    "and it says the defaults are in play, naming the directory",
+    /✓ no paperlint\.json — every setting has its default; papers are in "papers"/.test(
+      r.out,
+    ),
   );
+  rmSync(dir, { recursive: true, force: true });
+}
+
+// ── II-quater. A paperlint.json THAT DOES NOT PARSE — the guard refuses every command ─────
+{
+  const dir = consumer({ papersDir: "papers" });
+  writeFileSync(join(dir, "paperlint.json"), '{ "papersDir": <<<<<<< HEAD\n');
+  const r = runDoctor(dir, { cliPapers: "papers" });
+  check("an unparsable paperlint.json — a FAILURE", r.code === 2);
   check(
-    "and it says exactly why that is risky — it works only until the directory moves",
-    /works only while your papers happen to live there/.test(r.out),
+    "named, with the way out (a file edit, not a command)",
+    /✗ paperlint\.json is not valid JSON/.test(r.out) &&
+      /Edit or Write/.test(r.out),
   );
   rmSync(dir, { recursive: true, force: true });
 }
@@ -163,7 +155,7 @@ const runDoctor = (
 {
   const dir = consumer({
     papersDir: "papers",
-    pkgKey: "papers",
+    declared: "papers",
     makeDir: false,
   });
   const r = runDoctor(dir, { cliPapers: "papers" });
@@ -177,42 +169,9 @@ const runDoctor = (
   rmSync(dir, { recursive: true, force: true });
 }
 
-// ── II-quater. THE KEY'S OLD NAME IS READ AND NAMED; TWO DIFFERENT KEYS ARE A FAILURE ──────
-{
-  const dir = consumer({ papersDir: "papers" });
-  writeFileSync(
-    join(dir, "package.json"),
-    JSON.stringify({
-      "research-paper-pipeline": { [PAPERS_DIR_FIELD]: "papers" },
-    }),
-  );
-  const r = runDoctor(dir, { cliPapers: "papers" });
-  check(
-    "the old key — read (not a failure), and named with the new one",
-    r.code === 0 &&
-      /⚠ "research-paper-pipeline" in package\.json is the old name/.test(
-        r.out,
-      ) &&
-      /the hooks will guard papers/.test(r.out),
-  );
-  writeFileSync(
-    join(dir, "package.json"),
-    JSON.stringify({
-      paperlint: { [PAPERS_DIR_FIELD]: "papers" },
-      "research-paper-pipeline": { [PAPERS_DIR_FIELD]: "elsewhere" },
-    }),
-  );
-  const both = runDoctor(dir, { cliPapers: "papers" });
-  check(
-    "both keys with different contents — a failure",
-    both.code === 2 && /✗ package\.json has both/.test(both.out),
-  );
-  rmSync(dir, { recursive: true, force: true });
-}
-
 // ── III. TWO DECLARATIONS HAVE DRIFTED APART ────────────────────────────────────────────────
 {
-  const dir = consumer({ papersDir: "writing/drafts", pkgKey: "papers" });
+  const dir = consumer({ papersDir: "writing/drafts", declared: "papers" });
   mkdirSync(join(dir, "papers"), { recursive: true });
   const r = runDoctor(dir, { cliPapers: "writing/drafts" });
   check("both declarations exist, but differ — a FAILURE", r.code === 2);
@@ -223,12 +182,10 @@ const runDoctor = (
 // This is load-bearing: a copy of the logic would drift silently and print a confident wrong
 // answer.
 {
-  const dir = consumer({ papersDir: "docs/papers", pkgKey: "docs/papers/" });
+  const dir = consumer({ papersDir: "docs/papers", declared: "docs/papers/" });
   const r = runDoctor(dir, { cliPapers: "docs/papers" });
   const fromHook = papersRoot(
-    JSON.stringify({
-      paperlint: { [PAPERS_DIR_FIELD]: "docs/papers/" },
-    }),
+    JSON.stringify({ [PAPERS_DIR_FIELD]: "docs/papers/" }),
   );
   check("the hook itself trims the trailing slash", fromHook === "docs/papers");
   check(
@@ -244,7 +201,7 @@ const runDoctor = (
 
 // ── V. THE HOOK'S REFUSAL IS PASSED ALONG, NOT TURNED INTO A DIRECTORY ─────────────────────
 {
-  const dir = consumer({ papersDir: "papers", pkgKey: "" });
+  const dir = consumer({ papersDir: "papers", declared: "" });
   const r = runDoctor(dir, { cliPapers: "papers" });
   check(
     "an empty string in the declaration — the hook refuses, and doctor NAMES it",
@@ -255,7 +212,7 @@ const runDoctor = (
 
 // ── VI. EXTERNAL PROGRAMS ARE A FACT, NOT A VERDICT ─────────────────────────────────────────
 {
-  const dir = consumer({ papersDir: "papers", pkgKey: "papers" });
+  const dir = consumer({ papersDir: "papers", declared: "papers" });
   const none = runDoctor(dir, { cliPapers: "papers", have: () => 1 });
   check(
     "🔴 a missing tex install does NOT fail the run — a gate on advice would mute the whole thing",
@@ -330,7 +287,7 @@ const runDoctor = (
 // nothing anywhere said so. The link state itself is `link-skills.harness.mjs`'s subject; here
 // only doctor's REPORTING of it is judged, so the state is handed in rather than built on disk.
 {
-  const dir = consumer({ papersDir: "papers", pkgKey: "papers" });
+  const dir = consumer({ papersDir: "papers", declared: "papers" });
   const state = {
     ok: true,
     home: join(dir, ".claude", "skills"),

package/src/doctor.mutations.mjs

@@ -46,8 +46,8 @@ process.exit(
         edits: [
           [
             SRC,
-            "  const hookRoot = rawPkg ? papersRoot(rawPkg) : null;",
-            '  const hookRoot = rawPkg ? (JSON.parse(rawPkg)?.["research-paper-pipeline"]?.papersDir ?? "papers") : null;',
+            '  const hookRoot = papersRoot(raw ?? "{}");',
+            '  const hookRoot = raw === null ? "papers" : (() => { try { return JSON.parse(raw)?.papersDir ?? "papers"; } catch { return "papers"; } })();',
           ],
         ],
       },
@@ -115,18 +115,18 @@ process.exit(
         ],
       },
       {
-        name: "a missing declaration is reported as all-clear",
+        name: "an unparsable paperlint.json is reported as all-clear",
         harness: HARNESS,
-        expect: "the missing declaration is NAMED, not skipped",
+        expect: "an unparsable paperlint.json — a FAILURE",
         disables:
-          "the only trace of issue #33 left on an install that STILL works: `paperlint init` writes " +
-          "one file, the hook reads another, and the directories matching up rests on the " +
-          "default. A cheerful checkmark instead of a warning turns a coincidence into a confirmation",
+          "the one failure left in the settings file: while it does not parse, the edit guard " +
+          "refuses every Bash command. A doctor that counts it as fine sends the reader looking " +
+          "everywhere but the file",
         edits: [
           [
             SRC,
-            '      `  ⚠ package.json has no "${CONFIG_KEY}": { "${PAPERS_DIR_FIELD}": … } — the hooks fall back to "${DEFAULT_PAPERS_ROOT}"`,',
-            "      `  ✓ package.json`,",
+            "        `      the edit guard refuses every Bash command until it parses — fix it with Edit or Write`,\n      ],\n      bad: 1,",
+            "        `      the edit guard refuses every Bash command until it parses — fix it with Edit or Write`,\n      ],\n      bad: 0,",
           ],
         ],
       },

package/src/doctor.ts

@@ -29,16 +29,10 @@ import { spawnSync } from "node:child_process";
 // the hook itself rather than at a shared module.
 import {
   papersRoot,
-  CONFIG_KEY,
   DEFAULT_PAPERS_ROOT,
   PAPERS_DIR_FIELD,
-  OLD_PAPERS_DIR_FIELD,
+  CONFIG_FILE,
 } from "../hooks/paper-edit-guard.hook.mjs";
-import {
-  LEGACY_CONFIG_KEY,
-  LEGACY_KEY_MESSAGE,
-  declaredSettings,
-} from "../lib/paper-config.mjs";
 import { PAPER_MARKERS } from "./build.ts";
 import { linkSkills, SKILLS_HOME, type LinkReport } from "./link-skills.ts";
 import { doctorHooks } from "./hooks-settings.ts";
@@ -146,51 +140,44 @@ export function detectPapers(cwd: string, depth = 2): string[] {
 }
 
 /**
- * The declaration's verdict. The old field name and two differing keys are failures (every reader
- * refuses them); the old KEY is read and named; a missing declaration is a warning.
+ * The root `paperlint.json`'s verdict. Absent, or silent on `papersDir`, is fine: the default is
+ * `papers`, and the CLI and the hooks take it alike. Only a file that does not parse is a failure —
+ * the edit guard refuses every Bash command while it cannot read it.
  */
-function declarationVerdict(rawPkg: string): { lines: string[]; bad: number } {
-  const out: string[] = [];
-  const found = (() => {
-    try {
-      return declaredSettings(JSON.parse(rawPkg));
-    } catch {
-      return declaredSettings(undefined);
-    }
-  })();
-  if (found.conflict !== null)
-    return { lines: [`  ✗ ${found.conflict}`], bad: 1 };
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #49: replace with a real type
-  const settings = found.settings as Record<string, any> | undefined;
-  const key = found.legacy ? LEGACY_CONFIG_KEY : CONFIG_KEY;
-  const declared = settings?.[PAPERS_DIR_FIELD];
-  if (found.legacy) out.push(`  ⚠ ${LEGACY_KEY_MESSAGE}`);
-  // The old field name is a failure, not a warning: every reader refuses it.
-  if (settings && Object.hasOwn(settings, OLD_PAPERS_DIR_FIELD))
+function declarationVerdict(raw: string | null): {
+  lines: string[];
+  bad: number;
+} {
+  if (raw === null)
+    return {
+      lines: [
+        `  ✓ no ${CONFIG_FILE} — every setting has its default; papers are in "${DEFAULT_PAPERS_ROOT}"`,
+      ],
+      bad: 0,
+    };
+  let settings: unknown;
+  try {
+    settings = JSON.parse(raw);
+  } catch (e) {
     return {
       lines: [
-        ...out,
-        `  ✗ "${OLD_PAPERS_DIR_FIELD}" was renamed to "${PAPERS_DIR_FIELD}" in package.json → "${key}"`,
+        `  ✗ ${CONFIG_FILE} is not valid JSON: ${(e as Error).message}`,
+        `      the edit guard refuses every Bash command until it parses — fix it with Edit or Write`,
       ],
       bad: 1,
     };
-  // 🔴 A MISSING DECLARATION IS A WARNING, NOT A REFUSAL, and that is a decision, not an
-  // oversight. Without it the hook takes the `papers` default; if the papers do live there, the
-  // install WORKS — just by coincidence, and it will break silently on the day the directory
-  // moves. Failing on a working install is not allowed here: for an `error`-level check a false
-  // positive costs more than a miss, because people do not fix it, they switch it off — together
-  // with the binary findings below, which the command was written for. A real breakage (the roots
-  // drifted apart, the directory does not exist) is caught where it is binary.
-  if (declared === undefined)
-    out.push(
-      `  ⚠ package.json has no "${CONFIG_KEY}": { "${PAPERS_DIR_FIELD}": … } — the hooks fall back to "${DEFAULT_PAPERS_ROOT}"`,
-      `      it works only while your papers happen to live there; declare it and it keeps working`,
-    );
-  else
-    out.push(
-      `  ✓ package.json → ${key}.${PAPERS_DIR_FIELD} = ${JSON.stringify(declared)}`,
-    );
-  return { lines: out, bad: 0 };
+  }
+  const declared = (settings as Record<string, unknown> | null)?.[
+    PAPERS_DIR_FIELD
+  ];
+  return {
+    lines: [
+      declared === undefined
+        ? `  ✓ ${CONFIG_FILE} names no ${PAPERS_DIR_FIELD} — the default "${DEFAULT_PAPERS_ROOT}"`
+        : `  ✓ ${CONFIG_FILE} → ${PAPERS_DIR_FIELD} = ${JSON.stringify(declared)}`,
+    ],
+    bad: 0,
+  };
 }
 
 /**
@@ -261,7 +248,7 @@ export function doctor({
   skillLinks = (r: string) => linkSkills(r, { write: false }),
 }: DoctorOptions = {}): number {
   const root = projectDir ?? cwd;
-  const pkgPath = join(root, "package.json");
+  const configPath = join(root, CONFIG_FILE);
   const out: string[] = [
     "",
     "paperlint doctor — what is wired, and what only looks wired",
@@ -269,22 +256,15 @@ export function doctor({
   ];
   let bad = 0;
 
-  out.push("declaration");
-  const rawPkg = existsSync(pkgPath) ? readFileSync(pkgPath, "utf8") : "";
-  if (!rawPkg) {
-    out.push(`  ✗ no package.json at ${root}`);
-    out.push(
-      `      the hooks read their papers directory from there and refuse without it`,
-    );
-    bad++;
-  } else {
-    const declaration = declarationVerdict(rawPkg);
-    out.push(...declaration.lines);
-    bad += declaration.bad;
-  }
+  out.push("settings");
+  const raw = existsSync(configPath) ? readFileSync(configPath, "utf8") : null;
+  const declaration = declarationVerdict(raw);
+  out.push(...declaration.lines);
+  bad += declaration.bad;
 
   out.push("", "papers directory");
-  const hookRoot = rawPkg ? papersRoot(rawPkg) : null;
+  // The hook is given what its provider gives it: the file, or `{}` when there is none.
+  const hookRoot = papersRoot(raw ?? "{}");
   const hookSays = typeof hookRoot === "string" ? hookRoot : null;
   out.push(
     `  the CLI will lint    ${cliPapers ?? "(nothing — no declaration found)"}`,

package/src/facts-file.test.ts

@@ -8,6 +8,9 @@
  * real banal is `test/e2e/banal.mjs`.
  */
 import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
 import { test } from "vitest";
 import { memoryFiles } from "./adapters/memory/index.ts";
 import {
@@ -147,12 +150,23 @@ const good: PdfReader = async () => ({
   ok: true,
   facts: { pages: 2, fonts: FONTS, last: lastPage(60, 60), layout: [] },
 });
-/** Options over in-memory files: the PDF and venue.json on "disk", a measurer answering `geometry`. */
+/** The shipped presets at their real paths: `extends` resolves through the same Files port. */
+const SHIPPED_PRESETS = Object.fromEntries(
+  readdirSync(packageVenuesDir())
+    .filter((f) => /\.jsonc?$/.test(f))
+    .map((f) => [
+      join(packageVenuesDir(), f),
+      readFileSync(join(packageVenuesDir(), f)),
+    ]),
+);
+
+/** Options over in-memory files: the PDF and paperlint.json on "disk", a measurer answering `geometry`. */
 function setup(geometry: Geometry = NONE) {
   const files = memoryFiles({
     [PDF]: PDF_BYTES,
-    [`${PAPER}/venue.json`]: JSON.stringify({
-      venue: "agenticdev",
+    ...SHIPPED_PRESETS,
+    [`${PAPER}/paperlint.json`]: JSON.stringify({
+      extends: "paperlint:agenticdev",
       kind: "short",
     }),
   });
@@ -170,7 +184,7 @@ function setup(geometry: Geometry = NONE) {
   return { files, measured, o };
 }
 
-test("measure: venue and kind from venue.json, pdf relative to the paper, the file's sha256", async () => {
+test("measure: venue and kind from paperlint.json, pdf relative to the paper, the file's sha256", async () => {
   const { o } = setup();
   const m = await measurePaper(PAPER, PDF, o);
   assert.ok(m.ok);
@@ -233,8 +247,34 @@ test("writeFactsFile: <paper>/_build/paper.facts.json holds exactly the document
   assert.deepEqual(JSON.parse(text), m.value.facts);
 });
 
-test("declaredVenue: none without venue.json, none when it names no venue", () => {
+test("declaredVenue: none without paperlint.json; no label when it extends no preset", () => {
   assert.equal(declaredVenue(memoryFiles(), PAPER), null);
-  const files = memoryFiles({ [`${PAPER}/venue.json`]: '{"kind":"x"}' });
-  assert.equal(declaredVenue(files, PAPER), null);
+  const files = memoryFiles({
+    [`${PAPER}/paperlint.json`]: '{"kind":"x","pdf":"b/p.pdf"}',
+  });
+  assert.deepEqual(declaredVenue(files, PAPER), {
+    label: null,
+    kind: "x",
+    pdf: "b/p.pdf",
+  });
+});
+
+test("declaredVenue: the label is the preset's, and an extends that resolves nowhere is refused", () => {
+  const ok = memoryFiles({
+    ...SHIPPED_PRESETS,
+    [`${PAPER}/paperlint.json`]: '{"extends":"paperlint:aisec"}',
+  });
+  assert.equal(declaredVenue(ok, PAPER)?.label, "aisec");
+  const typo = memoryFiles({
+    ...SHIPPED_PRESETS,
+    [`${PAPER}/paperlint.json`]: '{"extends":"paperlint:aisek"}',
+  });
+  assert.throws(() => declaredVenue(typo, PAPER), /shipped presets/);
+});
+
+test("declaredVenue: a paperlint.json with an unknown key is refused, naming the key", () => {
+  const files = memoryFiles({
+    [`${PAPER}/paperlint.json`]: '{"venu":"agenticdev"}',
+  });
+  assert.throws(() => declaredVenue(files, PAPER), /unknown key "venu"/);
 });