paperlint 2.1.0 → 3.0.0

package/src/venue-rules.ts

@@ -24,7 +24,7 @@
  * One rule per reason, and the others are silent — so a paper gets one finding that says what to
  * do, not six that say the same thing:
  *
- *   no paperlint.json       every rule silent — a paper from before 2.1.0 (`paperlint new` writes one)
+ *   no paperlint.json       every rule silent (`paperlint new` writes one)
  *   extends null / absent   pdf/measured (warn) — no venue chosen yet; it names the file to set
  *   preset does not resolve pdf/profile (error) — a typo would otherwise switch every check off
  *   not built / no facts    pdf/measured (warn) — lint often runs before or without a build (the
@@ -48,10 +48,7 @@ import type { FlatGeometry } from "./domain/geometry.ts";
 import type { AbsolutePath } from "./domain/paths.ts";
 import { sha256Hex } from "./domain/sha256.ts";
 import type { Files } from "./ports/files.ts";
-import {
-  LEGACY_PAPER_SETTINGS_MESSAGE,
-  PAPER_SETTINGS_FILE,
-} from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 
 // ── the verdict's vocabulary ─────────────────────────────────────────────────────────
 
@@ -109,6 +106,11 @@ function kindOf(
   kind: string | null,
 ): Pick<Resolved, "kind" | "kindProblem"> {
   const known = [...format.kinds.keys()].join(", ") || "(none)";
+  // A preset with no kinds (`acm-sigconf`, a family a paper for an unprofiled venue extends
+  // directly) has no page limit to pick, so naming no kind is the only valid declaration. A kind
+  // named against it is still `kindUnknown`, whose "its kinds: (none)" says why.
+  if (kind === null && format.kinds.size === 0)
+    return { kind: null, kindProblem: null };
   if (kind === null)
     return {
       kind: null,
@@ -150,14 +152,11 @@ export function assessPaper(paperDir: string, deps: VenueRuleDeps): Assessment {
   if (p.kind === "none")
     return p.settings === null
       ? { kind: "no-venue" }
-      : { kind: "no-preset", file: join(paperDir, PAPER_SETTINGS_FILE) };
+      : { kind: "no-preset", file: join(paperDir, CONFIG_FILE) };
   if (p.kind === "settings-problem")
     return {
       kind: "unresolved",
-      finding:
-        p.problem.kind === "legacy"
-          ? finding("legacySettings")
-          : finding("settingsBroken", { why: p.problem.why }),
+      finding: finding("settingsBroken", { why: p.problem.why }),
     };
   if (p.kind === "preset-problem")
     return {
@@ -415,11 +414,10 @@ const META: Readonly<Record<VenueRuleName, Meta>> = {
         "the venue preset a paper's paperlint.json extends resolves, and the kind it names exists",
     },
     messages: {
-      settingsBroken: `${PAPER_SETTINGS_FILE} cannot be read: {{why}}`,
-      legacySettings: `this paper's venue checks do not run — ${LEGACY_PAPER_SETTINGS_MESSAGE}`,
+      settingsBroken: `${CONFIG_FILE} cannot be read: {{why}}`,
       preset:
         "{{why}} — so this paper's page limit, fonts and format are not checked. Fix `extends` in its paperlint.json, or turn pdf/profile off for this paper",
-      kindMissing: `${PAPER_SETTINGS_FILE} names no \`kind\`, so the page limit of \`{{venue}}\` is not checked; its kinds: {{known}}`,
+      kindMissing: `${CONFIG_FILE} names no \`kind\`, so the page limit of \`{{venue}}\` is not checked; its kinds: {{known}}`,
       kindUnknown:
         "`{{venue}}` has no kind `{{kind}}`, so the page limit is not checked; its kinds: {{known}}",
     },

package/eslint-rules/doc-fields.harness.mjs

@@ -1,336 +0,0 @@
-/**
- * Harness for `doc/fields`. Both halves for every case: fires on a planted defect AND
- * stays silent on a correct neighbor — otherwise "silent" is indistinguishable from "dead".
- *
- * The mutation battery sits alongside it: `doc-fields.mutations.mjs`.
- */
-import assert from "node:assert/strict";
-import { Linter } from "eslint";
-import markdown from "@eslint/markdown";
-import docFields from "./doc-fields.mjs";
-import { recordCheck } from "vigiles";
-
-const linter = new Linter();
-
-const OPTS = {
-  fields: {
-    read: {
-      values: ["full", "abstract", "none"],
-      hint: "what exactly was read",
-    },
-  },
-  sinceCreated: "2026-07-29",
-};
-
-/** Run the rule against one document. Returns the findings. */
-function run(src, options = OPTS) {
-  return linter.verify(src, {
-    plugins: { markdown, doc: docFields },
-    language: "markdown/gfm",
-    languageOptions: { frontmatter: "yaml" },
-    rules: { "doc/fields": ["error", options] },
-  });
-}
-
-const fm = (body, extra = "") =>
-  ["---", "title: neighbor", 'created: "2026-08-01"', extra, "---", "", body]
-    .filter(Boolean)
-    .join("\n");
-
-// ── 1. STAYS SILENT when the field is declared and the value is allowed ────────────────
-{
-  for (const v of ["full", "abstract", "none"]) {
-    const m = run(fm("Analysis.", `read: ${v}`));
-    assert.deepEqual(
-      m,
-      [],
-      `read: ${v} — an allowed value, silence was expected: ${JSON.stringify(m)}`,
-    );
-  }
-  recordCheck("the three allowed field values produce no findings");
-}
-
-// ── 2. FIRES when the field is missing ──────────────────────────────────────────
-{
-  const m = run(fm("Analysis with no field declared."));
-  assert.equal(
-    m.length,
-    1,
-    `case 2: a missing field must produce EXACTLY one finding, got ${m.length}`,
-  );
-  assert.match(
-    m[0].message,
-    /no `read` field/,
-    `case 2: the finding must name "no field", got: ${m[0].message}`,
-  );
-  assert.match(
-    m[0].message,
-    /what exactly was read/,
-    "the hint from the option must reach the text",
-  );
-  recordCheck("a missing field is a finding, with the hint from the option");
-}
-
-// ── 3. FIRES on a value outside the list ─────────────────────────────────────
-{
-  const m = run(fm("Analysis.", "read: fully"));
-  assert.equal(
-    m.length,
-    1,
-    `case 3: a value outside the vocabulary must produce one finding, got ${m.length}`,
-  );
-  assert.match(
-    m[0].message,
-    /`read: fully` — value is not in the list/,
-    `a value outside the vocabulary must be NAMED as the value outside the vocabulary — got: ${m[0].message}`,
-  );
-  recordCheck(
-    "a value outside the vocabulary is a finding, and it names the value that arrived",
-  );
-}
-
-// ── 4. 🔴 THE MAIN CASE: PROSE WITH THE SAME WORD IS NOT A FIELD ───────────────
-// The predecessor searched for the substring `**Read:**` and counted ANY occurrence of
-// it — including an admission of incompleteness. Here the text has no effect on the verdict at all.
-{
-  const confession = fm(
-    "⚠️ **Read only at the abstract level.** The full text is required before submission.",
-  );
-  const m = run(confession);
-  assert.equal(
-    m.length,
-    1,
-    "bold prose containing the word 'Read' does not declare a field — a finding was expected",
-  );
-  assert.match(
-    m[0].message,
-    /no `read` field/,
-    `a missing field must be NAMED (case 1) — got: ${m[0].message}`,
-  );
-
-  // and the reverse half: the same admission, declared as a FIELD, is legitimate and silent
-  const declared = fm(
-    "The full text is required before submission.",
-    "read: abstract",
-  );
-  assert.deepEqual(
-    run(declared),
-    [],
-    "read: abstract — a legitimate state, not a failure",
-  );
-  recordCheck(
-    "prose with the word 'Read' does not count; the same state as a field does",
-  );
-}
-
-// ── 5. A MARKER INSIDE A CODE FENCE AND IN A QUOTE — has no effect ─────────────────
-// A substring search counted both. To the rule this is just document text.
-{
-  const fenced = fm(
-    ["```", "**Read:** an example from someone else's card", "```"].join("\n"),
-  );
-  assert.equal(
-    run(fenced).length,
-    1,
-    "a marker inside a ``` fence does not declare a field",
-  );
-  const quoted = fm("> **Read:** a quote from someone else's card");
-  assert.equal(
-    run(quoted).length,
-    1,
-    "a marker in a quote does not declare a field",
-  );
-  recordCheck("a code fence and a quote do not create a field");
-}
-
-// ── 6. "Rule from a date" — consumer data ───────────────────────────────────
-{
-  // Dates are quoted HERE on purpose: this case is about the GATE, not about type parsing.
-  // Unquoted dates live only in case 8, otherwise the "don't normalize Date" mutation would
-  // kill this case first.
-  const old = [
-    "---",
-    "title: an old card",
-    'created: "2026-07-01"',
-    "---",
-    "",
-    "Analysis with no field.",
-  ].join("\n");
-  assert.deepEqual(
-    run(old),
-    [],
-    "a card older than the rule's date — known debt, not a finding",
-  );
-
-  const onTheDay = [
-    "---",
-    "title: on the rule's day",
-    'created: "2026-07-29"',
-    "---",
-    "",
-    "Analysis with no field.",
-  ].join("\n");
-  assert.equal(
-    run(onTheDay).length,
-    1,
-    "the boundary is inclusive: `created == sinceCreated` is checked",
-  );
-  recordCheck("the rule's date exempts the past and includes its own day");
-}
-
-// ── 7. 🔴 A MISSING FRONTMATTER IS A FINDING, NOT AN EXEMPTION ──────────────────
-// This family's predecessor let a file with no `created` fall out of the check entirely,
-// meaning the gate was bypassed by deleting the header. Here that hole is closed.
-{
-  const bare = "# Neighbor\n\nAnalysis with no header at all.\n";
-  const m = run(bare);
-  assert.equal(
-    m.length,
-    1,
-    `case 7: a document with no frontmatter must produce a finding, got ${m.length}`,
-  );
-  assert.match(
-    m[0].message,
-    /no frontmatter/,
-    `a missing header must have ITS OWN verdict — got: ${m[0].message}`,
-  );
-  recordCheck(
-    "a document with no frontmatter is not exempted — otherwise the gate is bypassed by deleting the header",
-  );
-}
-
-// ── 8. 🔴 AN UNQUOTED `created` ARRIVES AS A Date OBJECT ─────────────────────────
-// js-yaml recognizes YAML 1.1 timestamps. Comparing `Date < "2026-07-29"` SILENTLY gives
-// false, meaning the date gate would stop working and it would look like silence.
-// This case checks both sides of the boundary on an unquoted date.
-{
-  const oldUnquoted = [
-    "---",
-    "created: 2026-07-01",
-    "---",
-    "",
-    "No field.",
-  ].join("\n");
-  assert.deepEqual(
-    run(oldUnquoted),
-    [],
-    "case 8: an unquoted OLD date must exempt",
-  );
-
-  const newUnquoted = [
-    "---",
-    "created: 2026-08-01",
-    "---",
-    "",
-    "No field.",
-  ].join("\n");
-  assert.equal(
-    run(newUnquoted).length,
-    1,
-    "case 8: an unquoted NEW date must TURN ON the check",
-  );
-
-  const quoted = ["---", 'created: "2026-08-01"', "---", "", "No field."].join(
-    "\n",
-  );
-  assert.equal(
-    run(quoted).length,
-    1,
-    "a quoted date behaves the same as an unquoted one",
-  );
-  recordCheck(
-    "a date as a Date and a date as a string give the same verdict on both sides of the boundary",
-  );
-}
-
-// ── 9. Broken YAML — its own separate verdict, not silence ─────────────────────
-{
-  const broken = [
-    "---",
-    "title: [no closing",
-    "created: 2026-08-01",
-    "---",
-    "",
-    "Body.",
-  ].join("\n");
-  const m = run(broken);
-  assert.equal(
-    m.length,
-    1,
-    `case 9: broken YAML must produce one finding, got ${m.length}`,
-  );
-  assert.match(
-    m[0].message,
-    /does not parse as YAML/,
-    `a broken header must have ITS OWN verdict — got: ${m[0].message}`,
-  );
-  recordCheck(
-    "an unparseable header is its own message, not silence and not 'no field'",
-  );
-}
-
-// ── 10. An empty value counts as missing ────────────────────────────────
-// The consumer's `frontmatterField` returned the CLOSING FENCE `---` on an empty value, and
-// that would pass as a value. Here empty means absent.
-{
-  const empty = [
-    "---",
-    "created: 2026-08-01",
-    "read:",
-    "---",
-    "",
-    "Body.",
-  ].join("\n");
-  const m = run(empty);
-  assert.equal(
-    m.length,
-    1,
-    `case 10: an empty value must read as absent, got ${m.length}`,
-  );
-  assert.match(
-    m[0].message,
-    /no `read` field/,
-    `a missing field must be NAMED (case 2) — got: ${m[0].message}`,
-  );
-  recordCheck("an empty field value = absent, not 'the value ---'");
-}
-
-// ── 11. The finding sits ON THE FRONTMATTER, not on the first line of the body ──────────
-{
-  const m = run(fm("The body starts here."));
-  assert.equal(
-    m[0].line,
-    1,
-    `the finding must point at the header, got line ${m[0].line}`,
-  );
-  recordCheck("the finding's address is the frontmatter");
-}
-
-// ── 12. Two fields at once — one finding per field, not one per document ───────────
-{
-  const two = {
-    fields: {
-      read: { values: ["full", "abstract", "none"] },
-      venue_checked: { values: ["yes", "no"] },
-    },
-    sinceCreated: "2026-07-29",
-  };
-  const m = run(fm("Body."), two);
-  assert.equal(
-    m.length,
-    2,
-    `two missing fields — two findings, got ${m.length}`,
-  );
-  assert.deepEqual(
-    m.map((x) => /no `(\w+)` field/.exec(x.message)?.[1]).sort(),
-    ["read", "venue_checked"],
-    "both findings must name THEIR OWN field",
-  );
-  recordCheck("each missing field gets its own finding");
-}
-
-console.log(
-  "✓ doc/fields: a declared field is silent, a missing or bad one is a finding; prose with the " +
-    "same word does not count; the date gate, a missing header, broken YAML, a js-yaml Date, and " +
-    "an empty value — each with its own verdict",
-);

package/eslint-rules/doc-fields.mjs

@@ -1,186 +0,0 @@
-/**
- * `doc/fields` — a document must declare its FIELDS, not hint at them through markup.
- *
- * ── WHY ──────────────────────────────────────────────────────────────────────
- * A convention like "a card must carry the mark `**Read:**`" describes not data
- * but PRESENTATION. Bold text in markdown means "bold text"; that the author meant
- * a field is our guess. The rule requires a real frontmatter field and checks its
- * value against a list of allowed ones.
- *
- * ── WHAT THIS FILE IS ────────────────────────────────────────────────────────────
- * Unit 3 of step 9 of the extraction, and the first one that is NOT a port of the
- * predecessor. The previous two (`review/findings-cause`, `review/cold-read-cause`)
- * carried the mechanism over as-is; here the mechanism is replaced, because the
- * predecessor searched for the substring `**Read:**` in the raw text, and a
- * measurement showed misses in both directions:
- *
- *   | input                                        | substring |
- *   |-----------------------------------------------|-----------|
- *   | `**Read**: everything` (colon outside)         | ❌ rejected|
- *   | `__Read:__ everything` (underscores)            | ❌ rejected|
- *   | a ```-fence with an example inside              | ✅ counted |
- *   | `missing **Read:** — I have not read it`        | ✅ counted |
- *
- * The last row is the heart of the matter: a completeness check counted a direct
- * admission of incompleteness, because it looked at characters, not at the claim.
- *
- * 🔴 AND THE OBVIOUS FIX WOULD HAVE MADE IT WORSE. A naive port to the AST — "there
- * is a `strong` node whose text starts with 'Read'" — would have counted a live
- * card reading `**Read only at the abstract level.** Full text required before
- * submission`, i.e. it would have accepted known debt as completed work. The regex
- * rejected that card BY ACCIDENT — it required a colon right after the word. A
- * field removes the argument entirely: `read: abstract` is a legitimate value, not
- * a bad spelling.
- *
- * ── WHAT THIS RULE DOES NOT DO, AND THIS IS A DECISION ──────────────────────────
- * It does not replace CONTENT checks. A field is the author's claim about
- * themselves, and it cannot be verified: `refs_diffed: true` gets ticked without
- * the work being done. So the requirement "the card has a section analyzing the
- * bibliography" stays a separate heading-level check at the consumer. Only what
- * is already a claim (exactly what was read) becomes a field — not an artefact.
- *
- * ── BOUNDARIES ────────────────────────────────────────────────────────────────────
- * · A missing frontmatter is a FINDING, not an exemption. Otherwise the gate is
- *   bypassed by deleting the header; this family's predecessor already had that
- *   hole (a file with no `created` fell out of the check entirely).
- * · `sinceCreated` compares ISO strings — this is legitimate because the format is
- *   fixed and lexicographic order matches chronological order.
- */
-import { load } from "js-yaml";
-
-/**
- * `created` from YAML arrives either as a string or as a DATE — js-yaml recognizes
- * YAML 1.1 timestamps by default, and `created: 2026-07-29` without quotes becomes
- * a `Date` object. Comparing `Date < "2026-07-29"` silently gives `false`, meaning
- * the date gate would stop working and nobody would notice. Normalize to `YYYY-MM-DD`.
- */
-function isoDate(v) {
-  if (v instanceof Date) return v.toISOString().slice(0, 10);
-  if (typeof v === "string") return /^\d{4}-\d{2}-\d{2}/.exec(v)?.[0] ?? "";
-  return "";
-}
-
-export default {
-  rules: {
-    fields: {
-      meta: {
-        type: "problem",
-        docs: {
-          description:
-            "a document declares its required frontmatter fields and their allowed values, instead of hinting at them with markup",
-        },
-        schema: [
-          {
-            type: "object",
-            properties: {
-              fields: {
-                type: "object",
-                additionalProperties: {
-                  type: "object",
-                  properties: {
-                    values: {
-                      type: "array",
-                      items: { type: "string" },
-                      minItems: 1,
-                    },
-                    hint: { type: "string" },
-                  },
-                  additionalProperties: false,
-                },
-                minProperties: 1,
-              },
-              sinceCreated: {
-                type: "string",
-                pattern: "^\\d{4}-\\d{2}-\\d{2}$",
-              },
-            },
-            required: ["fields"],
-            additionalProperties: false,
-          },
-        ],
-        messages: {
-          noFrontmatter:
-            "no frontmatter — a document of this class must declare the fields {{names}}. A missing header is not an exemption: otherwise the check is bypassed by deleting it.",
-          malformed:
-            "the frontmatter does not parse as YAML ({{why}}) — there is nothing to read the fields {{names}} from.",
-          missing:
-            "the frontmatter has no `{{name}}` field{{hint}}. Allowed values: {{values}}. A note in the body is not a field: markup describes presentation, not data.",
-          badValue:
-            "`{{name}}: {{actual}}` — value is not in the list. Allowed: {{values}}.",
-        },
-      },
-      create(context) {
-        const { fields, sinceCreated } = context.options[0] ?? {};
-        const names = Object.keys(fields);
-        let seenFrontmatter = false;
-
-        return {
-          yaml(node) {
-            seenFrontmatter = true;
-            let data;
-            try {
-              data = load(node.value ?? "");
-            } catch (e) {
-              context.report({
-                node,
-                messageId: "malformed",
-                data: {
-                  why: e.reason ?? e.message ?? "unparseable",
-                  names: names.join(", "),
-                },
-              });
-              return;
-            }
-            if (
-              data === null ||
-              typeof data !== "object" ||
-              Array.isArray(data)
-            ) {
-              context.report({
-                node,
-                messageId: "malformed",
-                data: {
-                  why: "the header is not a key-value mapping",
-                  names: names.join(", "),
-                },
-              });
-              return;
-            }
-            // The date gate stands HERE, not in `root:exit`: a document with no header has no
-            // `created`, so it does not fall under the gate and must be a finding (see BOUNDARIES).
-            const created = isoDate(data.created);
-            if (sinceCreated && (!created || created < sinceCreated)) return;
-
-            for (const [name, spec] of Object.entries(fields)) {
-              const values = spec.values;
-              const hint = spec.hint ? ` (${spec.hint})` : "";
-              if (!(name in data) || data[name] === null || data[name] === "") {
-                context.report({
-                  node,
-                  messageId: "missing",
-                  data: { name, hint, values: values.join(" · ") },
-                });
-                continue;
-              }
-              const actual = String(data[name]);
-              if (!values.includes(actual))
-                context.report({
-                  node,
-                  messageId: "badValue",
-                  data: { name, actual, values: values.join(" · ") },
-                });
-            }
-          },
-          "root:exit"(node) {
-            if (seenFrontmatter) return;
-            context.report({
-              node,
-              messageId: "noFrontmatter",
-              data: { names: names.join(", ") },
-            });
-          },
-        };
-      },
-    },
-  },
-};

package/eslint-rules/doc-fields.mutations.mjs

@@ -1,96 +0,0 @@
-/**
- * Battery for `doc/fields`: six mutations, each removes its own load-bearing property.
- *
- * The last two are about wounds the predecessor would not have shown at all:
- * normalizing js-yaml's `Date` (otherwise the date gate silently stops working) and
- * failing closed on a missing header (otherwise the check is bypassed by deleting it).
- */
-import { fileURLToPath } from "node:url";
-import { dirname, join, resolve } from "node:path";
-import { runMutations } from "../lib/mutation-driver.mjs";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const ROOT = resolve(HERE, "..");
-const RULE = join(HERE, "doc-fields.mjs");
-const HARNESS = join(HERE, "doc-fields.harness.mjs");
-
-process.exit(
-  runMutations({
-    root: ROOT,
-    runner: "node",
-    cases: [
-      {
-        name: "a missing field stops being a finding",
-        harness: HARNESS,
-        expect: 'case 2: the finding must name "no field"',
-        disables:
-          "the verdict itself — a card with no field declared passes silently",
-        edits: [
-          [
-            RULE,
-            'if (!(name in data) || data[name] === null || data[name] === "") {',
-            "if (false) {",
-          ],
-        ],
-      },
-      {
-        name: "the value stops being checked against the vocabulary",
-        harness: HARNESS,
-        expect:
-          "case 3: a value outside the vocabulary must produce one finding",
-        disables: "the value check — `read: fully` becomes allowed",
-        edits: [[RULE, "if (!values.includes(actual))", "if (false)"]],
-      },
-      {
-        name: "'rule from a date' stops exempting",
-        harness: HARNESS,
-        expect: "known debt, not a finding",
-        disables:
-          "the exemption of the historical corpus — 22 old cards go red at once",
-        edits: [
-          [
-            RULE,
-            "if (sinceCreated && (!created || created < sinceCreated)) return;",
-            "if (false) return;",
-          ],
-        ],
-      },
-      {
-        name: "🔴 a missing frontmatter exempts again",
-        harness: HARNESS,
-        expect: "case 7: a document with no frontmatter must produce a finding",
-        disables:
-          "fail-closed — the gate is bypassed again by deleting the header, like the predecessor",
-        edits: [[RULE, "if (seenFrontmatter) return;", "if (true) return;"]],
-      },
-      {
-        name: "🔴 js-yaml's `Date` stops being normalized to a string",
-        harness: HARNESS,
-        expect: "case 8: an unquoted NEW date must TURN ON the check",
-        disables:
-          "normalizing the YAML 1.1 timestamp — comparing a Date to a string SILENTLY gives false, and the date gate dies unnoticed",
-        edits: [
-          [
-            RULE,
-            "if (v instanceof Date) return v.toISOString().slice(0, 10);",
-            "",
-          ],
-        ],
-      },
-      {
-        name: "broken YAML stops having its own verdict",
-        harness: HARNESS,
-        expect: "a broken header must have ITS OWN verdict",
-        disables:
-          "the separation of causes — an unparseable header becomes indistinguishable from silence",
-        edits: [
-          [
-            RULE,
-            'messageId: "malformed",\n                data: {\n                  why: e.reason',
-            'messageId: "missing",\n                data: {\n                  why: e.reason',
-          ],
-        ],
-      },
-    ],
-  }),
-);