paperlint 7.1.0 → 8.0.0

package/src/cli.harness.mjs

@@ -42,6 +42,10 @@ const { PROGRAMS } = await import(join(HERE, "doctor.ts"));
 // loads vigiles without recording a check is reported as having verified nothing.
 const check = createChecker();
 
+/** A paper.tex whose whole body is `body`. */
+const tex = (body) =>
+  `\\documentclass{article}\n\\begin{document}\n${body}\n\\end{document}\n`;
+
 /** Runs the utility with output captured — quieter and faster than spawning a process. */
 async function cli(args, cwd) {
   // 🔴 THE STREAMS ARE SPLIT, AND THAT IS LOAD-BEARING. As long as the harness dumped log and
@@ -129,11 +133,11 @@ check(
   const ruleBlocks = (c) => c.filter((b) => Array.isArray(b.files));
   check(
     "without a LaTeX language the config still gets built — a corpus with no .tex is not a reason to refuse",
-    Array.isArray(cfg) && ruleBlocks(cfg).length === 4,
+    Array.isArray(cfg) && ruleBlocks(cfg).length === 3,
   );
   check(
     "with a LaTeX language two blocks are added: paper.tex, and the files it includes",
-    ruleBlocks(buildConfig({}, {})).length === 6,
+    ruleBlocks(buildConfig({}, {})).length === 5,
   );
   check(
     "🔴 the project's paper TEMPLATE directory is ignored — flat config does not skip dot-directories",
@@ -178,7 +182,7 @@ check(
       join(paper, "versions", "2026-07-22-submitted.pdf"),
       "x".repeat(100),
     );
-    writeFileSync(join(paper, "paper.md"), "# Intro\n\nRQ1: does it hold?\n");
+    writeFileSync(join(paper, "paper.tex"), tex("RQ1: does it hold?"));
     writeFileSync(
       join(paper, "PIPELINE-STATUS.md"),
       `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: 100\n    source: versions/s.tex\n    sourceBytes: 4\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`,
@@ -703,7 +707,7 @@ check(
     const status = (bytes) =>
       `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: ${bytes}\n    source: versions/s.tex\n    sourceBytes: 4\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`;
     writeFileSync(join(paper, "versions", "s.tex"), "abcd");
-    writeFileSync(join(paper, "paper.md"), "# Intro\n\nRQ1: does it hold?\n");
+    writeFileSync(join(paper, "paper.tex"), tex("RQ1: does it hold?"));
 
     writeFileSync(join(paper, "PIPELINE-STATUS.md"), status(100));
     const clean = await cli(["lint", "papers"], root);
@@ -788,7 +792,7 @@ check(
       join(paper, "versions", "2026-07-22-submitted.pdf"),
       "x".repeat(100),
     );
-    writeFileSync(join(paper, "paper.md"), "# Intro\n\nRQ1: does it hold?\n");
+    writeFileSync(join(paper, "paper.tex"), tex("RQ1: does it hold?"));
     const status = (bytes) =>
       `---\nstages:\n  - stage: submitted\n    date: 2026-07-22\n    pdf: versions/2026-07-22-submitted.pdf\n    bytes: ${bytes}\n    source: versions/s.tex\n    sourceBytes: 4\n---\n# S\n\n| id | note |\n|---|---|\n| cites | bib-authors run |\n`;
     writeFileSync(join(paper, "PIPELINE-STATUS.md"), status(100));
@@ -897,8 +901,8 @@ check(
     );
     // Three § signs — `paper/section-word`, warn level and only warn.
     writeFileSync(
-      join(paper, "paper.md"),
-      "# Intro\n\nRQ1: does it hold?\n\nSee \u00a7 5 and \u00a7 6 and \u00a7 7.\n",
+      join(paper, "paper.tex"),
+      tex("RQ1: does it hold?\n\nSee \u00a7 5 and \u00a7 6 and \u00a7 7."),
     );
     writeFileSync(
       join(paper, "PIPELINE-STATUS.md"),
@@ -1040,7 +1044,7 @@ check(
     const paper = join(tree, "papers", "p");
     mkdirSync(paper, { recursive: true });
     // Two findings of different kinds: a structural one (no scorecard) and a rule one (`§`).
-    writeFileSync(join(paper, "paper.md"), "# T\n\nSee § 3 and §4.\n");
+    writeFileSync(join(paper, "paper.tex"), tex("See § 3 and §4."));
 
     const inside = await cli(["lint", "--json", "papers"], tree);
     const outside = await cli(
@@ -1273,22 +1277,10 @@ console.log(
 
 // ── the new flags parse, and none of them becomes the directory argument ─────────────────
 {
-  const a = parseArgs([
-    "init",
-    "--yes",
-    "--no-hooks",
-    "--paper",
-    "demo",
-    "--format",
-    "md",
-  ]);
+  const a = parseArgs(["init", "--yes", "--no-hooks", "--paper", "demo"]);
   check(
     "init flags parse into fields, not into paths",
-    a.yes &&
-      a.noHooks &&
-      a.paper === "demo" &&
-      a.format === "md" &&
-      a.paths.length === 0,
+    a.yes && a.noHooks && a.paper === "demo" && a.paths.length === 0,
   );
   check("-y is --yes", parseArgs(["init", "-y"]).yes === true);
   check(
@@ -1300,11 +1292,6 @@ console.log(
     "🔴 --hooks=local is NOT implemented, and it is refused by name rather than read as a path",
     r.code === 2 && /--hooks=local is not implemented/.test(r.out),
   );
-  const f = await cli(["init", "--format", "pdf"]);
-  check(
-    "an unknown --format is refused before anything is written",
-    f.code === 2 && /--format must be one of tex, md/.test(f.out),
-  );
 }
 
 // ── init wires the hooks, and a human can say no ─────────────────────────────────────────
@@ -1315,7 +1302,7 @@ console.log(
   const mk = (name) => {
     const dir = join(root, name);
     mkdirSync(join(dir, "papers", "p1"), { recursive: true });
-    writeFileSync(join(dir, "papers", "p1", "paper.md"), "# P\n");
+    writeFileSync(join(dir, "papers", "p1", "paper.tex"), "% P\n");
     writeFileSync(
       join(dir, "papers", "p1", "PIPELINE-STATUS.md"),
       "---\n---\n",
@@ -1426,19 +1413,17 @@ console.log(
         ask: async (q) => {
           asked.push(q);
           if (/create a first paper/.test(q)) return "first";
-          if (/format:/.test(q)) return "md";
           return "";
         },
-        createPaper: async (papersRoot, name, format) => {
-          made.push({ papersRoot, name, format });
+        createPaper: async (papersRoot, name) => {
+          made.push({ papersRoot, name });
           return 0;
         },
       });
       check(
-        "a human with no paper is offered one, and the answer and format reach `paperlint new`'s routine",
+        "a human with no paper is offered one, and the answer reaches `paperlint new`'s routine",
         made.length === 1 &&
           made[0].name === "first" &&
-          made[0].format === "md" &&
           made[0].papersRoot === join(dir, "papers"),
       );
     }
@@ -1466,22 +1451,17 @@ console.log(
         log: () => {},
         interactive: false,
         paper: "given",
-        createPaper: async (papersRoot, name, format) => (
-          made.push({ name, format }),
-          0
-        ),
+        createPaper: async (papersRoot, name) => (made.push({ name }), 0),
       });
       check(
-        "--paper creates it without a human, in the default format",
-        made.length === 1 &&
-          made[0].name === "given" &&
-          made[0].format === "tex",
+        "--paper creates it without a human",
+        made.length === 1 && made[0].name === "given",
       );
     }
     {
       const dir = bare("has-one");
       mkdirSync(join(dir, "papers", "p1"), { recursive: true });
-      writeFileSync(join(dir, "papers", "p1", "paper.md"), "# P\n");
+      writeFileSync(join(dir, "papers", "p1", "paper.tex"), "% P\n");
       const asked = [];
       await init(dir, {
         ...base,
@@ -1569,7 +1549,7 @@ console.log(
       `{"${PAPERS_DIR_FIELD}":"papers"}\n`,
     );
     mkdirSync(join(root, "papers", "p1"), { recursive: true });
-    writeFileSync(join(root, "papers", "p1", "paper.md"), "# P\n");
+    writeFileSync(join(root, "papers", "p1", "paper.tex"), "% P\n");
     writeFileSync(
       join(root, "papers", "p1", "PIPELINE-STATUS.md"),
       "---\n---\n",
@@ -1591,7 +1571,7 @@ console.log(
       join(root, "papers", "p2", "PIPELINE-STATUS.md"),
       readFileSync(join(root, "papers", ".template", "PIPELINE-STATUS.md")),
     );
-    writeFileSync(join(root, "papers", "p2", "paper.md"), "# P\n");
+    writeFileSync(join(root, "papers", "p2", "paper.tex"), "% P\n");
     const r2 = await cli(["lint"], root);
     check(
       "and the same scorecard in a real paper folder fails — the ignore is scoped, not a blind spot",
@@ -1625,11 +1605,11 @@ console.log(
         /names no venue preset yet/.test(r.out) &&
         /\(0 errors, 1 warning\)/.test(r.out),
     );
-    const again = await cli(["new", "demo", "--format", "md"], root);
+    const again = await cli(["new", "demo"], root);
     check(
       "a second run on the same folder adds nothing — the tex source already stands",
       again.code === 0 &&
-        !existsSync(join(root, "writing", "demo", "paper.md")) &&
+        !/\+ /.test(again.out) &&
         /kept — never overwritten/.test(again.out),
     );
     const bad = await cli(["new", "Demo"], root);

package/src/cli.test.ts

@@ -6,7 +6,7 @@
  */
 import assert from "node:assert/strict";
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { createServer } from "node:http";
 import { dirname, join } from "node:path";
 import { test } from "vitest";
@@ -50,14 +50,14 @@ test("parseArgs: the boolean flags of build and toolchain, and a value flag with
     [
       parseArgs(["build", "--all", "--dry-run", "papers/p"]),
       parseArgs(["toolchain", "--check"]),
-      parseArgs(["new", "x", "--format"]),
+      parseArgs(["new", "x", "--paper"]),
       parseArgs(["new", "x", "--venue="]),
       parseArgs(["new", "x", "--kind", "short", "--max-warnings=3"]),
     ],
     [
       { ...base, cmd: "build", all: true, dryRun: true, paths: ["papers/p"] },
       { ...base, cmd: "toolchain", check: true },
-      { ...base, cmd: "new", paths: ["x"], missingValue: "--format" },
+      { ...base, cmd: "new", paths: ["x"], missingValue: "--paper" },
       { ...base, cmd: "new", paths: ["x"], missingValue: "--venue" },
       { ...base, cmd: "new", paths: ["x"], kind: "short", maxWarnings: 3 },
     ],
@@ -142,20 +142,18 @@ test("build refuses with no target, and --all over no papers", async () => {
   );
 });
 
-test("new refuses an unknown format, a broken config, and a config that names no papers directory", async () => {
+test("new refuses a broken config, and a config that names no papers directory", async () => {
   const broken = join(root, "new-broken");
   writeTree(broken, { "paperlint.json": "{ not json" });
   const none = join(root, "new-none");
   writeTree(none, { "paperlint.json": JSON.stringify({ papersDir: [] }) });
   const results = [
-    await cli(["new", "p", "--format", "docx"], root),
-    await cli(["new", "p", "--format", "md"], broken),
-    await cli(["new", "p", "--format", "md"], none),
+    await cli(["new", "p"], broken),
+    await cli(["new", "p"], none),
   ];
   assert.deepEqual(
     results.map((r) => ({ code: r.code, err: r.err.split(":")[0] })),
     [
-      { code: 2, err: "--format must be one of tex, md — got `docx`" },
       { code: 2, err: join(broken, "paperlint.json is not valid JSON") },
       {
         code: 2,
@@ -170,7 +168,7 @@ test("new with several papers directories says which one it used", async () => {
   writeTree(dir, {
     "paperlint.json": JSON.stringify({ papersDir: ["a", "b"] }),
   });
-  const r = await cli(["new", "p", "--format", "md", "--yes"], dir);
+  const r = await cli(["new", "p", "--yes"], dir);
   assert.equal(
     r.out.split("\n")[0],
     "several papers directories are declared — using the first: a",
@@ -274,20 +272,20 @@ async function withoutTex<T>(dir: string, fn: () => Promise<T>): Promise<T> {
 const noTexDir = join(root, "build-notex");
 writeTree(noTexDir, {
   "package.json": "{}",
-  "papers/md/paper.md": "# P\n\nx\n",
+  "papers/nosource/notes.txt": "x\n",
   "papers/tex/paper.tex":
     "\\documentclass{article}\\begin{document}x\\end{document}\n",
 });
 const venues = texInputsDir();
 
-test("build: a markdown-only paper is refused", async () => {
-  const md = await withoutTex(noTexDir, () =>
-    cli(["build", "papers/md"], noTexDir),
+test("build: a paper with no paper.tex is refused, naming paper.tex", async () => {
+  const none = await withoutTex(noTexDir, () =>
+    cli(["build", "papers/nosource"], noTexDir),
   );
-  assert.deepEqual(md, {
+  assert.deepEqual(none, {
     code: 1,
     out: [
-      "papers/md",
+      "papers/nosource",
       `  inputs: TEXINPUTS += the paper's directory, then ${venues}`,
       "  compile: refused — no paper.tex; paperlint compiles LaTeX, and this paper has none",
       "  measure: skipped — nothing is compiled",
@@ -295,7 +293,7 @@ test("build: a markdown-only paper is refused", async () => {
       "  ✗ nothing to compile: no paper.tex",
     ].join("\n"),
     err:
-      "\nNo paper.tex in: papers/md.\n" +
+      "\nNo paper.tex in: papers/nosource.\n" +
       'This is NOT "nothing to build" — paperlint compiles LaTeX, and these papers have no LaTeX source.\n' +
       "Write the paper in paper.tex; `paperlint new <name>` creates one.",
   });
@@ -344,6 +342,15 @@ test("no command prints the usage and exits 2; --kind with no value is refused",
   assert.equal(parseArgs(["new", "x", "--kind"]).missingValue, "--kind");
 });
 
+test("--help names the cycles and where a deadline comes from — the only place a newcomer looks first", async () => {
+  const r = await cli(["--help"], root);
+  assert.equal(r.code, 0);
+  assert.match(r.out, /"cycles": \[ \{ "id"/);
+  assert.match(r.out, /A venue preset carries the portal's deadlines/);
+  assert.match(r.out, /"override": \{ "at", "reason", "evidence" \}/);
+  assert.match(r.out, /the earlier reading binds/);
+});
+
 test("src/cli.ts run as the program itself answers like the bin", () => {
   const r = runNode(join(import.meta.dirname, "cli.ts"), ["--help"]);
   assert.equal(r.status, 0);
@@ -390,7 +397,7 @@ test("build --dry-run on a paper with a venue plans for the preset's packages",
 
 test("a paper's paperlint.json that does not parse stops the lint with its path", () => {
   const dir = writeTree(join(root, "rules-broken"), {
-    "p/paper.md": "# P\n",
+    "p/paper.tex": "% P\n",
     "p/paperlint.json": "{ nope",
   });
   const r = paperRuleBlocks([join(dir, "p")]);
@@ -435,15 +442,12 @@ test("silentOptionalRules: a rule no block names for any paper is silent — a g
   );
 });
 
-test("init with no path and --format md sets up the current directory", async () => {
+test("init with no path sets up the current directory, and its first paper is paper.tex", async () => {
   const dir = writeTree(join(root, "init-here"), { "package.json": "{}" });
-  const r = await cli(
-    ["init", "--yes", "--no-hooks", "--paper", "first", "--format", "md"],
-    dir,
-  );
-  assert.equal(
-    existsSync(join(dir, "papers", "first", "paper.md")),
-    true,
+  const r = await cli(["init", "--yes", "--no-hooks", "--paper", "first"], dir);
+  assert.deepEqual(
+    readdirSync(join(dir, "papers", "first")).sort(),
+    ["PIPELINE-STATUS.md", "paper.tex", "paperlint.json"],
     r.out + r.err,
   );
 });
@@ -479,12 +483,9 @@ test("lint: a named directory with nothing paperlint lints is named in full when
 test("new from inside the paper it names adds the missing files and names the paper in full", async () => {
   const dir = writeTree(join(root, "new-inside"), {
     "paperlint.json": JSON.stringify({ papersDir: "papers" }),
-    "papers/p/paper.md": "# P\n",
+    "papers/p/paper.tex": "% P\n",
   });
-  const r = await cli(
-    ["new", "p", "--format", "md", "--yes"],
-    join(dir, "papers", "p"),
-  );
+  const r = await cli(["new", "p", "--yes"], join(dir, "papers", "p"));
   assert.match(
     r.out,
     new RegExp(
@@ -498,7 +499,7 @@ test("new with several directories, run from the first, names it in full", async
     "paperlint.json": JSON.stringify({ papersDir: ["a", "b"] }),
     "a/.keep": "",
   });
-  const r = await cli(["new", "p", "--format", "md", "--yes"], join(dir, "a"));
+  const r = await cli(["new", "p", "--yes"], join(dir, "a"));
   assert.equal(
     r.out.split("\n")[0],
     `several papers directories are declared — using the first: ${join(dir, "a")}`,
@@ -510,7 +511,7 @@ test("lint: an ESLint failure that is not an empty set is not swallowed", async
     "paperlint.json": JSON.stringify({
       rules: { "paper/stages": ["error", { x: 1 }] },
     }),
-    "papers/p/paper.md": "# P\n",
+    "papers/p/paper.tex": "% P\n",
     "papers/p/PIPELINE-STATUS.md": "---\nstages: []\n---\n# S\n",
   });
   await assert.rejects(cli(["lint"], dir), {
@@ -573,11 +574,11 @@ function newAtTerminal(cwd: string, answers: Record<string, string>) {
   });
 }
 
-test("new at a terminal asks for the format and the venue; the answers pick them", async () => {
-  const md = writeTree(join(root, "new-tty-md"), { "package.json": "{}" });
-  const r = await newAtTerminal(md, { "format:": "md\n", "venue:": "none\n" });
+test("new at a terminal asks for the venue; the answer picks it", async () => {
+  const dir = writeTree(join(root, "new-tty"), { "package.json": "{}" });
+  const r = await newAtTerminal(dir, { "venue:": "none\n" });
   assert.equal(r.status, 0, r.out);
-  assert.equal(existsSync(join(md, "papers", "first", "paper.md")), true);
+  assert.equal(existsSync(join(dir, "papers", "first", "paper.tex")), true);
 });
 
 test("chooseVenue: a question that fails (the stream ended) takes the default, no venue", async () => {
@@ -616,9 +617,9 @@ test("init's TeX Live install runs the toolchain over the project's papers, neve
   assert.equal(typeof here.installed(), "boolean");
 });
 
-test("lint with its LaTeX language missing from the install still lints the markdown papers", () => {
+test("lint with its LaTeX language missing from the install still lints the scorecards", () => {
   const dir = writeTree(join(root, "lint-no-tex-language"), {
-    "papers/p/paper.md": "# P\n\nSome prose.\n",
+    "papers/p/PIPELINE-STATUS.md": "---\nstages: []\n---\n# S\n",
     "no-latex.mjs":
       "import { register } from 'node:module';\n" +
       "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s === '#eslint-rules/latex-language') throw Object.assign(new Error('gone'), { code: 'ERR_MODULE_NOT_FOUND' }); return next(s, c); }\"));\n",
@@ -628,9 +629,9 @@ test("lint with its LaTeX language missing from the install still lints the mark
     nodeArgs: ["--import", join(dir, "no-latex.mjs")],
   });
   const whole = runNode(BIN, ["lint", "papers"], { cwd: dir });
-  // A markdown paper needs no LaTeX language: the same report, the same code.
+  // A scorecard needs no LaTeX language: the same report, the same code.
   assert.deepEqual(without, whole);
-  assert.match(whole.stdout, /missing `PIPELINE-STATUS\.md`/);
+  assert.match(whole.stdout, /missing all of `paper\.tex`/);
 });
 
 test("`paperlint hook` with no name: exit 2, and the usage names an example", async () => {