paperlint 2.0.1 → 2.1.0

package/src/facts-file.ts

@@ -40,13 +40,16 @@ import { describeFailure, type PdfFacts, type PdfReader } from "./pdf-facts.ts";
 import {
   flatGeometry,
   type FactsGeometryFields,
+  type FlatGeometry,
   type Geometry,
 } from "./domain/geometry.ts";
-import { sha256Hex } from "./domain/sha256.ts";
+import { parseSha256, sha256Hex, type Sha256 } from "./domain/sha256.ts";
 import type { MeasureGeometry } from "./ports/measure-geometry.ts";
 import type { AbsolutePath } from "./domain/paths.ts";
 import type { Files } from "./ports/files.ts";
 import { err, ok, type Result } from "./domain/result.ts";
+import { paperPreset, paperPresetProblem } from "./presets.ts";
+import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
 
 export const FACTS_SCHEMA = 2;
 export const FACTS_DIR = "_build";
@@ -56,41 +59,42 @@ export const FACTS_FILE = "paper.facts.json";
 export const factsPath = (paperDir: string): string =>
   join(paperDir, FACTS_DIR, FACTS_FILE);
 
-/** The `venue.json` a paper declares: where it is submitted, as which kind, and where its PDF is. */
-export interface VenueDecl {
-  readonly venue: string;
-  readonly kind: string | null;
-  readonly pdf: string | null;
-}
-
 /**
  * A path as the caller gave it. The `Files` adapter resolves a relative one against the process's
  * cwd, which is what these callers have always meant; the brand is not a claim this code checked it.
  */
 const at = (p: string): AbsolutePath => p as AbsolutePath;
 
-const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
-
-/** A parsed `venue.json`, or null when it names no venue. */
-export function parseVenueDecl(json: unknown): VenueDecl | null {
-  const d = typeof json === "object" && json !== null ? json : {};
-  const field = (k: string) => str((d as Record<string, unknown>)[k]);
-  const venue = field("venue");
-  return venue ? { venue, kind: field("kind"), pdf: field("pdf") } : null;
+/** What the facts need from a paper's `paperlint.json`: its venue's label, its kind, where its PDF is. */
+export interface VenueDecl {
+  /** The venue preset's display label (`agenticdev`), or null when the paper extends none. */
+  readonly label: string | null;
+  readonly kind: string | null;
+  readonly pdf: string | null;
 }
 
 /**
- * The paper's `venue.json`, or null when there is none or it names no venue. The one reader of
- * that file: the build, the facts writer and the shim all read it here.
+ * What a paper's `paperlint.json` declares, or null when it has none. THROWS with a one-line reason
+ * when the file does not parse, its `extends` does not resolve, or only the pre-2.1.0 `venue.json`
+ * is there: the build reports that as its `facts` failure rather than building against no venue.
  */
 export function declaredVenue(
   files: Files,
   paperDir: string,
+  venuesDir: string = packageVenuesDir(),
 ): VenueDecl | null {
-  const bytes = files.readBytes(at(join(paperDir, "venue.json")));
-  return bytes === null
-    ? null
-    : parseVenueDecl(JSON.parse(new TextDecoder().decode(bytes)));
+  const p = paperPreset(paperDir, { files, venuesDir });
+  const problem = paperPresetProblem(paperDir, p);
+  if (problem !== null) throw new Error(problem);
+  if (p.kind === "resolved")
+    return {
+      label: p.preset.label,
+      kind: p.settings.kind,
+      pdf: p.settings.pdf,
+    };
+  return p.kind === "none" && p.settings
+    ? { label: null, kind: p.settings.kind, pdf: p.settings.pdf }
+    : null;
 }
 
 // ── the document ────────────────────────────────────────────────────────────────────────
@@ -184,7 +188,7 @@ export interface MeasureOptions {
   readonly kind?: string | null;
   /** The page-geometry measurer (banal, as the composition root wired it). */
   readonly measure: MeasureGeometry;
-  /** Where the PDF and `venue.json` are read from. */
+  /** Where the PDF and `paperlint.json` are read from. */
   readonly files: Files;
 }
 
@@ -215,7 +219,7 @@ export async function measurePaper(
   const facts = factsDocument({
     pdf: posix(relative(paperDir, pdf)),
     sha: sha256Hex(bytes),
-    venue: o.venue ?? decl?.venue ?? null,
+    venue: o.venue ?? decl?.label ?? null,
     kind: o.kind ?? decl?.kind ?? null,
     read: r.facts,
     geometry,
@@ -239,3 +243,120 @@ export function writeFactsFile(
   );
   return out;
 }
+
+// ── reading ─────────────────────────────────────────────────────────────────────────────
+
+/** What a rule judges, read back from the facts file and typed once. */
+export interface ReadFacts {
+  /** As the file spells it: relative to the paper directory, or absolute. */
+  readonly pdf: string;
+  readonly sha: Sha256;
+  readonly fonts: readonly FontEntry[];
+  /** The geometry columns, or null when no measurer ran (`geometry_source` is null). */
+  readonly geometry: FlatGeometry | null;
+}
+
+/** Why a facts file cannot be judged. */
+export type FactsProblem =
+  | { readonly kind: "schema"; readonly got: string }
+  | { readonly kind: "broken"; readonly why: string };
+
+const isRecord = (v: unknown): v is Readonly<Record<string, unknown>> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+const isNum = (v: unknown): v is number =>
+  typeof v === "number" && Number.isFinite(v);
+const numOrNull = (v: unknown): v is number | null => v === null || isNum(v);
+
+function fontOf(v: unknown): FontEntry | null {
+  if (!isRecord(v)) return null;
+  const { name, type, embedded, program } = v;
+  return typeof name === "string" &&
+    typeof type === "string" &&
+    typeof embedded === "boolean" &&
+    typeof program === "string"
+    ? { name, type, embedded, program }
+    : null;
+}
+
+const MAYBE_NUMBERS = [
+  "page_w_in",
+  "page_h_in",
+  "columns",
+  "body_pt",
+  "ref_pt",
+] as const;
+const NUMBERS = ["body_pages", "ref_pages", "appendix_pages"] as const;
+
+/** The geometry columns when a measurer ran; the shape error otherwise. */
+function geometryOf(
+  d: Readonly<Record<string, unknown>>,
+): Result<FlatGeometry | null, string> {
+  if (d["geometry_source"] === null) return ok(null);
+  if (typeof d["geometry_source"] !== "string")
+    return err("`geometry_source` is neither a measurer's name nor null");
+  const bad =
+    MAYBE_NUMBERS.find((k) => !numOrNull(d[k])) ??
+    NUMBERS.find((k) => !isNum(d[k]));
+  if (bad) return err(`\`${bad}\` is not a number`);
+  const pagesByType = d["pages_by_type"];
+  if (!isRecord(pagesByType) || !Object.values(pagesByType).every(isNum))
+    return err("`pages_by_type` is not an object of page counts");
+  const n = (k: (typeof MAYBE_NUMBERS)[number]) => d[k] as number | null;
+  return ok({
+    page_w_in: n("page_w_in"),
+    page_h_in: n("page_h_in"),
+    columns: n("columns"),
+    body_pt: n("body_pt"),
+    ref_pt: n("ref_pt"),
+    body_pages: d["body_pages"] as number,
+    ref_pages: d["ref_pages"] as number,
+    appendix_pages: d["appendix_pages"] as number,
+    pages_by_type: pagesByType as Readonly<Record<string, number>>,
+  });
+}
+
+/** The PDF the facts describe: its path and its sha256. */
+function artifactOf(
+  d: Readonly<Record<string, unknown>>,
+): Result<{ pdf: string; sha: Sha256 }, string> {
+  const pdf = d["pdf"];
+  if (typeof pdf !== "string" || pdf === "") return err("no `pdf` path");
+  try {
+    return ok({ pdf, sha: parseSha256(String(d["pdf_sha256"])) });
+  } catch {
+    return err("no `pdf_sha256` of 64 hex digits");
+  }
+}
+
+/**
+ * The facts file's text → what a rule judges, or why it cannot be judged. The one reader of the
+ * file in `src/`, beside its one writer: a field renamed here and not there is a compile error in
+ * this module, not a rule that silently reads `undefined`. Pure.
+ */
+export function parseFactsText(text: string): Result<ReadFacts, FactsProblem> {
+  let d: unknown;
+  try {
+    d = JSON.parse(text);
+  } catch (e) {
+    return err({ kind: "broken", why: `not JSON (${(e as Error).message})` });
+  }
+  if (!isRecord(d)) return err({ kind: "broken", why: "not a JSON object" });
+  if (d["schema"] !== FACTS_SCHEMA)
+    return err({ kind: "schema", got: JSON.stringify(d["schema"] ?? null) });
+  const artifact = artifactOf(d);
+  if (!artifact.ok) return err({ kind: "broken", why: artifact.error });
+  const rawFonts = d["fonts"];
+  const fonts = Array.isArray(rawFonts) ? rawFonts.map(fontOf) : null;
+  if (fonts === null || fonts.some((f) => f === null))
+    return err({
+      kind: "broken",
+      why: "`fonts` is not a list of { name, type, embedded, program }",
+    });
+  const geometry = geometryOf(d);
+  if (!geometry.ok) return err({ kind: "broken", why: geometry.error });
+  return ok({
+    ...artifact.value,
+    fonts: fonts as FontEntry[],
+    geometry: geometry.value,
+  });
+}

package/src/init.ts

@@ -35,8 +35,14 @@
  * an answer nobody gave. So the non-interactive path takes the stated default and SAYS which
  * default it took and why nothing was asked, rather than pretending it asked.
  */
-// eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+  // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
+} from "node:fs";
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { spawnSync } from "node:child_process";
 import { dirname, join, relative, resolve } from "node:path";
@@ -66,10 +72,13 @@ import {
   CONFIG_KEY,
   DEFAULT_PAPERS_ROOT,
   LEGACY_CONFIG_KEY,
+  LEGACY_PAPER_SETTINGS_FILE,
   PAPERS_DIR_FIELD,
+  PAPER_SETTINGS_FILE,
   declaredSettings,
   renamedFieldMessage,
 } from "../lib/paper-config.mjs";
+import { migrationOf } from "./paper-settings.ts";
 
 /** How the papers directory was arrived at. Printed, because a guess must not read as a fact. */
 export type PapersHow =
@@ -609,6 +618,73 @@ export interface InitOptions {
 }
 
 /** Reads one line from a real terminal. Kept out of `init` so the command stays testable. */
+/**
+ * Move every paper's pre-2.1.0 `venue.json` to `paperlint.json`, the way the old package.json key
+ * is moved, and in the same step `"venue": "aisec"` becomes `"extends": "paperlint:aisec"`: written
+ * as `paperlint.json` when it is alone, removed when `paperlint.json` already says the same, and
+ * REFUSED — both files left as they are — when they differ, since there is no way to know which
+ * one the author means. `code` is 2 when anything was refused.
+ */
+export function migratePaperSettings(papersAbs: string): {
+  readonly code: number;
+  readonly lines: readonly string[];
+} {
+  const lines: string[] = [];
+  let code = 0;
+  for (const dir of papersIn(papersAbs, [
+    ...PAPER_MARKERS,
+    LEGACY_PAPER_SETTINGS_FILE,
+  ])) {
+    const r = migrateOne(dir, (p) => relative(papersAbs, p));
+    if (r === null) continue;
+    lines.push(r.line);
+    if (r.refused) code = 2;
+  }
+  return {
+    code,
+    lines: lines.length ? ["", "paper settings", ...lines] : [],
+  };
+}
+
+/** One paper's move: done, and the line that says so — or null when there is nothing to move. */
+function migrateOne(
+  dir: string,
+  shown: (p: string) => string,
+): { readonly line: string; readonly refused: boolean } | null {
+  const [from, to] = [LEGACY_PAPER_SETTINGS_FILE, PAPER_SETTINGS_FILE].map(
+    (f) => join(dir, f),
+  ) as [string, string];
+  const read = (p: string) => (existsSync(p) ? readFileSync(p) : null);
+  const plan = migrationOf(read(from), read(to));
+  switch (plan.kind) {
+    case "none":
+      return null;
+    case "move":
+      writeFileSync(to, plan.text);
+      unlinkSync(from);
+      return {
+        line: `  ✓ ${shown(from)} → ${shown(to)} ("venue" is now "extends": "paperlint:<name>"; renamed in paperlint 2.1.0)`,
+        refused: false,
+      };
+    case "drop-legacy":
+      unlinkSync(from);
+      return {
+        line: `  ✓ ${shown(from)} removed — ${shown(to)} already says the same`,
+        refused: false,
+      };
+    case "conflict":
+      return {
+        line: `  ✗ ${shown(from)} and ${shown(to)} both exist and differ — nothing was moved. Keep ${PAPER_SETTINGS_FILE}, copy what you need from ${LEGACY_PAPER_SETTINGS_FILE} into it (its "venue": "x" is "extends": "paperlint:x"), delete ${LEGACY_PAPER_SETTINGS_FILE}, then run init again`,
+        refused: true,
+      };
+    case "broken":
+      return {
+        line: `  ✗ ${shown(from)} was not moved: ${plan.why}`,
+        refused: true,
+      };
+  }
+}
+
 export async function askOnTerminal(question: string): Promise<string> {
   // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
   const { createInterface } = await import("node:readline/promises");
@@ -747,6 +823,8 @@ export async function init(
   // guessed directory while lint and the hooks keep reading the declared one.
   const papersDir =
     decl.status === "kept" ? (decl.papers as string) : choice.papers;
+  const moved = migratePaperSettings(resolve(root, papersDir));
+  for (const line of moved.lines) (moved.code ? err : log)(line);
 
   // ── 3. the skills, linked where Claude Code looks for them ─────────────────────────────
   for (const line of reportSkillLinks(link(root), here)) log(line);
@@ -854,5 +932,5 @@ export async function init(
       `doctor exits ${String(code)} — the install is NOT finished. The lines marked ✗ above say what is\n` +
         `left; re-run \`npx paperlint doctor\` once you have done them.`,
     );
-  return paperCode !== 0 ? paperCode : code;
+  return paperCode || moved.code || code;
 }

package/src/new-paper.harness.mjs

@@ -98,11 +98,11 @@ try {
   const papers = join(work, "papers");
   const r = newPaper(papers, "demo", "tex");
   check(
-    "a fresh folder gets the scorecard and a .tex source, both from the package",
+    "a fresh folder gets the scorecard, a .tex source and paperlint.json, all from the package",
     r.ok &&
       r.fresh &&
       r.files.map((f) => `${f.file}:${f.status}:${f.from}`).join(" ") ===
-        "PIPELINE-STATUS.md:created:package paper.tex:created:package",
+        "PIPELINE-STATUS.md:created:package paper.tex:created:package paperlint.json:created:package",
   );
   const status = read(papers, "demo", STATUS_FILE);
   const fm = front(status);
@@ -122,8 +122,10 @@ try {
   );
   const l = await lint(join(papers, "demo"));
   check(
-    "🔴 `paperlint lint` passes the scaffold clean — the first run is green, not a missing-file error",
-    l.code === 0 && /no findings/.test(l.text),
+    "🔴 `paperlint lint` passes the scaffold — exit 0, not a missing-file error — with the one warning that no venue is chosen yet",
+    l.code === 0 &&
+      /names no venue preset yet/.test(l.text) &&
+      /1 problem \(0 errors, 1 warning\)/.test(l.text),
   );
 
   // The format contract of the skills' checker: four sections, parsed.
@@ -171,9 +173,10 @@ try {
   );
   check(
     "wantedFiles asks for a source only when neither format is there",
-    wantedFiles(join(papers, "old"), "tex").join() === STATUS_FILE &&
+    wantedFiles(join(papers, "old"), "tex").join() ===
+      `${STATUS_FILE},paperlint.json` &&
       wantedFiles(join(papers, "nowhere"), "md").join() ===
-        `${STATUS_FILE},paper.md`,
+        `${STATUS_FILE},paper.md,paperlint.json`,
   );
   writeFileSync(join(papers, "afile"), "x");
   check(

package/src/new-paper.test.ts

@@ -0,0 +1,145 @@
+/**
+ * `paperlint new` writes `<paper>/paperlint.json` — from the package's template, or from the
+ * project's `<papers>/.template/` when it has one — with no venue chosen yet, which lint then names
+ * in one warning instead of staying silent.
+ */
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { newPaper, OVERRIDE_DIR } from "./new-paper.ts";
+import { parsePaperSettings } from "./paper-settings.ts";
+import { run } from "./cli.ts";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+const tmp = () => {
+  const d = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-new-")));
+  dirs.push(d);
+  return d;
+};
+const settingsOf = (dir: string) =>
+  JSON.parse(readFileSync(join(dir, "paperlint.json"), "utf8")) as Record<
+    string,
+    unknown
+  >;
+
+describe("paperlint new — paperlint.json", () => {
+  it("is always written, from the package template: no venue chosen yet, and valid", () => {
+    const papers = join(tmp(), "papers");
+    const r = newPaper(papers, "demo", "tex");
+    expect(r.ok && r.files.find((f) => f.file === "paperlint.json")).toEqual({
+      file: "paperlint.json",
+      status: "created",
+      from: "package",
+    });
+    const s = settingsOf(join(papers, "demo"));
+    expect(s["extends"]).toBeNull();
+    expect(String(s["$comment"])).toMatch(/paperlint:agenticdev/);
+    expect(parsePaperSettings(s)).toEqual({
+      ok: true,
+      value: { extends: null, kind: null, pdf: null, rules: null },
+    });
+  });
+
+  it("comes from the project's <papers>/.template/ when it has one", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, OVERRIDE_DIR), { recursive: true });
+    writeFileSync(
+      join(papers, OVERRIDE_DIR, "paperlint.json"),
+      '{ "extends": "paperlint:aisec", "kind": "research" }\n',
+    );
+    const r = newPaper(papers, "house", "tex");
+    expect(r.ok && r.files.find((f) => f.file === "paperlint.json")?.from).toBe(
+      "project",
+    );
+    expect(settingsOf(join(papers, "house"))).toEqual({
+      extends: "paperlint:aisec",
+      kind: "research",
+    });
+  });
+
+  it("is never overwritten", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, "p"), { recursive: true });
+    writeFileSync(
+      join(papers, "p", "paperlint.json"),
+      '{"extends":"paperlint:aisec"}',
+    );
+    const r = newPaper(papers, "p", "tex");
+    expect(
+      r.ok && r.files.find((f) => f.file === "paperlint.json")?.status,
+    ).toBe("kept");
+    expect(settingsOf(join(papers, "p"))).toEqual({
+      extends: "paperlint:aisec",
+    });
+  });
+
+  it("is not added beside a pre-2.1.0 venue.json — `paperlint init` moves that one", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, "old"), { recursive: true });
+    writeFileSync(join(papers, "old", "venue.json"), '{"venue":"aisec"}');
+    const r = newPaper(papers, "old", "tex");
+    expect(r.ok && r.files.map((f) => f.file)).not.toContain("paperlint.json");
+  });
+});
+
+describe("paperlint lint — a paper with no venue preset chosen", () => {
+  async function lintNew(extendsValue: string | null) {
+    const root = tmp();
+    writeFileSync(
+      join(root, "package.json"),
+      JSON.stringify({
+        name: "c",
+        private: true,
+        paperlint: { papersDir: "papers" },
+      }),
+    );
+    newPaper(join(root, "papers"), "demo", "tex");
+    if (extendsValue !== null)
+      writeFileSync(
+        join(root, "papers", "demo", "paperlint.json"),
+        JSON.stringify({ extends: extendsValue, kind: "short" }),
+      );
+    const out: string[] = [];
+    const code = await run(["lint", "--json"], {
+      cwd: root,
+      log: (s: string) => out.push(s),
+      err: () => {},
+    });
+    const messages = (
+      JSON.parse(out.join("\n")) as {
+        messages: { ruleId: string; severity: number; message: string }[];
+      }[]
+    ).flatMap((r) => r.messages);
+    return { code, messages };
+  }
+
+  it("gets exactly one warning naming the file to set, and exits 0", async () => {
+    const { code, messages } = await lintNew(null);
+    expect(code).toBe(0);
+    expect(messages).toHaveLength(1);
+    expect(messages[0]?.ruleId).toBe("pdf/measured");
+    expect(messages[0]?.severity).toBe(1);
+    expect(messages[0]?.message).toMatch(/names no venue preset yet/);
+    expect(messages[0]?.message).toMatch(
+      /set "extends" in .*papers\/demo\/paperlint\.json/,
+    );
+  });
+
+  it("a paper with a real extends does not get it", async () => {
+    const { messages } = await lintNew("paperlint:agenticdev");
+    expect(messages.map((m) => m.message).join("\n")).not.toMatch(
+      /names no venue preset yet/,
+    );
+  });
+});

package/src/new-paper.ts

@@ -25,6 +25,10 @@ import {
 /* eslint-enable boundaries/dependencies */
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  LEGACY_PAPER_SETTINGS_FILE,
+  PAPER_SETTINGS_FILE,
+} from "../lib/paper-config.mjs";
 
 export type PaperFormat = "tex" | "md";
 export const FORMATS: readonly PaperFormat[] = ["tex", "md"];
@@ -83,16 +87,32 @@ export type NewPaperResult =
   | { readonly ok: false; readonly reason: string };
 
 /**
- * The files a paper folder must end up with: the scorecard, plus a source in `format` — unless
- * it already has a source in EITHER format, in which case that one stands and nothing is added.
+ * The files a paper folder must end up with: the scorecard, a source in `format` — unless it
+ * already has a source in EITHER format, in which case that one stands — and `paperlint.json`.
  */
 export function wantedFiles(dir: string, format: PaperFormat): string[] {
+  return [...scorecardAndSource(dir, format), ...settingsFile(dir)];
+}
+
+function scorecardAndSource(dir: string, format: PaperFormat): string[] {
   const hasSource = Object.values(SOURCE_FILE).some((f) =>
     existsSync(join(dir, f)),
   );
   return hasSource ? [STATUS_FILE] : [STATUS_FILE, SOURCE_FILE[format]];
 }
 
+/**
+ * `paperlint.json`, so that nobody has to know the file exists: its template says what to put in
+ * it, and until a venue preset is named lint says so in one warning. Not beside a pre-2.1.0
+ * `venue.json`: `paperlint init` moves that file, and a second, different one would make the move
+ * refuse.
+ */
+function settingsFile(dir: string): string[] {
+  return existsSync(join(dir, LEGACY_PAPER_SETTINGS_FILE))
+    ? []
+    : [PAPER_SETTINGS_FILE];
+}
+
 // Documented in README.md#starting-a-paper — update it when this changes.
 export function newPaper(
   papersRoot: string,