paperlint 12.0.0 → 13.0.0

package/src/version-rules.ts

@@ -0,0 +1,282 @@
+/**
+ * THE RULES OVER A PAPER'S FROZEN VERSIONS — the convention `versions/<cycle>/<stage>.{pdf,tex}` and
+ * its lock (src/domain/versions.ts):
+ *
+ *   versions/layout              error  on PIPELINE-STATUS.md: every entry of versions/ is a cycle's
+ *                                       folder or the lock, every file in a folder a stage's .pdf or
+ *                                       .tex, every PDF with its source, nothing sent from a cycle still
+ *                                       porting, every file as the lock recorded it
+ *   cycle/submitted-frozen       error  on PIPELINE-STATUS.md: a cycle with a submission on the portal
+ *                                       has `versions/<id>/submitted.pdf` (#308)
+ *   cycle/draft-drift            warn   on paper.tex: the draft has moved on from the open cycle's
+ *                                       frozen source, by so many lines
+ *   cycle/camera-ready-source    error  on paper.tex: the last cycle is accepted and its camera-ready is
+ *                                       frozen, and that camera-ready keeps less than half of the
+ *                                       accepted source's lines — silent until the camera-ready is frozen
+ *
+ * ── WHY THE FOLDER IS LISTED AND NOT LINTED ─────────────────────────────────────────────────
+ * A frozen PDF is never handed to ESLint, and a frozen `.tex` is kept out of the linted set on purpose
+ * (src/paper-includes.ts): a rule fired per file could not see either. The folder is listed once per
+ * paper, from the scorecard every paper has, as `paper/allowed-files-only` lists the paper's root.
+ *
+ * ── WHO SPEAKS WHEN THERE IS NOTHING TO JUDGE ───────────────────────────────────────────────
+ * A paper that keeps no `cycles` (the flat form) has no attempt to name a folder after: all four are
+ * silent, and `paper/stages` with `paper/source` judge its `stages:` list as before. A `cycles` record
+ * that does not read is refused by `paperlint lint` before any rule runs.
+ *
+ * ── WHY THE DRIFT IS A WARNING, AND THE CAMERA-READY AN ERROR ───────────────────────────────
+ * Between venues the draft is SUPPOSED to move on from what is under review: the warning says how far,
+ * so an author answering a reviewer knows the line numbers point into the frozen file. Once the venue
+ * accepts, the camera-ready has to be what was accepted plus the changes asked for — building it from
+ * a draft that moved on sends the venue a paper its reviewers never read.
+ *
+ * ── WHY THE CAMERA-READY IS JUDGED ONLY ONCE IT IS FROZEN ───────────────────────────────────
+ * While the camera-ready is being edited, paper.tex differs from what was accepted BY DESIGN: the
+ * reviewers' changes go in. A check on the draft in those weeks fires on correct work, so the rule waits
+ * for `submission update --save` to freeze `camera-ready.{pdf,tex}`, then judges the frozen source:
+ * it must keep at least half of the accepted source's lines (`derivesFrom`, src/domain/versions.ts).
+ * After the freeze the draft is not judged at all — what the venue holds is fixed, and the draft is
+ * free to head for the next paper.
+ */
+import { basename, dirname } from "node:path";
+import type { Files } from "./ports/files.ts";
+import {
+  derivesFrom,
+  driftText,
+  frozenKey,
+  judgeVersions,
+  lineage,
+  unfrozenSubmissions,
+  venueName,
+  type VersionFinding,
+} from "./domain/versions.ts";
+import type {
+  FolderRuleContext,
+  FolderRuleModule,
+} from "./folder-venue-rule.ts";
+import type { TexRuleModule } from "./tex-venue-rules.ts";
+import { readPaper, type ProseDeps } from "./tex-paper.ts";
+import { rulePageUrl } from "./venue-rules.ts";
+import {
+  cyclesIn,
+  draftDrift,
+  entriesIn,
+  factsOfFrozen,
+  frozenText,
+  hasFrozen,
+  readLock,
+  versionsDir,
+  type VersionsDeps,
+} from "./versions.ts";
+
+const STATUS_FILE = "PIPELINE-STATUS.md";
+
+const LOCK_COMMAND = "`npx paperlint versions lock <paper>`";
+
+const LAYOUT_META: FolderRuleModule["meta"] = {
+  type: "suggestion",
+  docs: {
+    description:
+      "versions/ holds a folder per cycle and a file per stage, every PDF with its source, each file as versions/lock.json recorded it",
+    url: rulePageUrl("versions/layout"),
+  },
+  schema: [],
+  messages: {
+    stray: "`versions/{{path}}` is not part of the layout — {{hint}}",
+    unknownCycle:
+      "`versions/{{folder}}/` names no cycle in paperlint.json — a folder in versions/ is one attempt, named by its cycle's id ({{known}}): rename it to the attempt it holds, or move it to extra/",
+    noSource: `\`versions/{{pdf}}\` is frozen without its source: freeze the .tex it was built from as \`versions/{{tex}}\` and run ${LOCK_COMMAND} — a reviewer's line numbers point into that source, and squash merges and \`git gc\` destroy the commit that held it`,
+    porting:
+      "`versions/{{file}}` was sent in the cycle «{{id}}», whose phase is still `porting`: a PDF went to the venue while the record says the source is in the previous venue's template — finish the port and drop the phase, or the file is in the wrong folder",
+    noLock: `versions/ holds frozen files and no lock.json — ${LOCK_COMMAND} records their bytes and digests; paperlint writes the lock, nobody edits it`,
+    badLock: `versions/lock.json: {{why}} — paperlint writes this file: restore it from git, or write it anew with ${LOCK_COMMAND}`,
+    notLocked: `\`versions/{{file}}\` is not in versions/lock.json — ${LOCK_COMMAND} records it (a file \`submission … --save\` froze is locked already)`,
+    changed: `\`versions/{{file}}\` is not the file the lock recorded on {{frozen}} ({{want}} bytes then, {{got}} now, and another digest) — a frozen file does not change: restore it from git; if it was replaced on purpose, ${LOCK_COMMAND} records it anew`,
+    lockedGone: `versions/lock.json records \`{{file}}\`, and the file is not there — a frozen version was deleted: restore it from git; if it went on purpose, ${LOCK_COMMAND} drops the entry`,
+  },
+};
+
+const FROZEN_META: FolderRuleModule["meta"] = {
+  type: "suggestion",
+  docs: {
+    description:
+      "a cycle with a submission on the venue's portal has the PDF it sent frozen as versions/<cycle>/submitted.pdf",
+    url: rulePageUrl("cycle/submitted-frozen"),
+  },
+  schema: [],
+  messages: {
+    unfrozen: `cycle «{{id}}» has submission {{submission}} on the portal, and \`versions/{{pdf}}\` is not there: what the reviewers read is not frozen. \`npx paperlint submission update <paper> --save\` freezes what it sends; for an upload made before, put that PDF there (\`submission show\` gives its size and sha256) with the source it was built from beside it as submitted.tex, then run ${LOCK_COMMAND}`,
+  },
+};
+
+/** What the rules on the scorecard read with: the disk and its listings. */
+export type VersionStatusDeps = VersionsDeps;
+
+/** The findings of one scorecard rule for the paper folder `dir`; none for a paper without cycles. */
+function statusFindings(
+  name: "layout" | "submitted-frozen",
+  dir: string,
+  deps: VersionStatusDeps,
+): readonly VersionFinding[] {
+  const cycles = cyclesIn(dir, deps.files);
+  if (cycles === null) return [];
+  const root = versionsDir(dir);
+  return name === "layout"
+    ? judgeVersions({
+        cycles: cycles.list,
+        root: entriesIn(root, deps),
+        inFolder: (folder) => entriesIn(`${root}/${folder}`, deps),
+        lock: readLock(dir, deps.files),
+        factsOf: factsOfFrozen(dir, deps.files),
+      })
+    : unfrozenSubmissions(cycles.list, hasFrozen(dir, deps.files));
+}
+
+const statusRule = (
+  meta: FolderRuleModule["meta"],
+  name: "layout" | "submitted-frozen",
+  deps: VersionStatusDeps,
+): FolderRuleModule => ({
+  meta,
+  create(context: FolderRuleContext) {
+    if (basename(context.filename) !== STATUS_FILE) return {};
+    return {
+      root() {
+        const at = context.sourceCode.getLocFromIndex(0);
+        statusFindings(name, dirname(context.filename), deps).forEach((f) => {
+          context.report({ loc: { start: at, end: at }, ...f });
+        });
+      },
+    };
+  },
+});
+
+/** The `versions` plugin's rule, on every `PIPELINE-STATUS.md`. */
+export const versionLayoutRules = (
+  deps: VersionStatusDeps,
+): Readonly<Record<"layout", FolderRuleModule>> => ({
+  layout: statusRule(LAYOUT_META, "layout", deps),
+});
+
+/** The `cycle` plugin's rule over the frozen folder, on every `PIPELINE-STATUS.md`. */
+export const submittedFrozenRules = (
+  deps: VersionStatusDeps,
+): Readonly<Record<"submitted-frozen", FolderRuleModule>> => ({
+  "submitted-frozen": statusRule(FROZEN_META, "submitted-frozen", deps),
+});
+
+// ── on paper.tex: the draft against the frozen source ────────────────────────────────────
+
+const DRIFT_META: TexRuleModule["meta"] = {
+  type: "suggestion",
+  docs: {
+    description:
+      "paper.tex has moved on from the source frozen when the open cycle's PDF was sent — said with how many lines",
+    url: rulePageUrl("cycle/draft-drift"),
+  },
+  schema: [],
+  messages: {
+    drift:
+      "paper.tex has moved on from `versions/{{key}}`, the version under review at {{venue}}: {{drift}} — expected while the draft heads for its next venue; a reviewer's line numbers point into the frozen file, not this one",
+  },
+};
+
+const CAMERA_META: TexRuleModule["meta"] = {
+  type: "problem",
+  docs: {
+    description:
+      "once the last cycle is accepted and its camera-ready frozen, the camera-ready started from the source that was accepted",
+    url: rulePageUrl("cycle/camera-ready-source"),
+  },
+  schema: [],
+  messages: {
+    base: "cycle «{{id}}» is accepted, and its frozen camera-ready, `versions/{{id}}/camera-ready.tex`, keeps {{kept}} of the {{total}} lines of what was accepted, `versions/{{id}}/submitted.tex` — under half, so it was not built from the accepted source. The camera-ready is what was accepted plus the changes the reviewers asked for: copy submitted.tex over paper.tex, carry over those changes, build, and send it again with `npx paperlint submission update <paper> --save`, which replaces the frozen one",
+  },
+};
+
+/** The draft against the open cycle's frozen source, or none. */
+function driftFinding(
+  dir: string,
+  draft: string,
+  deps: ProseDeps,
+): VersionFinding | null {
+  const cycles = cyclesIn(dir, deps.files);
+  if (cycles === null || cycles.current.kind !== "cycle") return null;
+  const c = cycles.current.cycle;
+  const d = draftDrift(dir, cycles, draft, deps.files);
+  return d.kind === "drift"
+    ? {
+        messageId: "drift",
+        data: { key: d.key, venue: venueName(c), drift: driftText(d.drift) },
+      }
+    : null;
+}
+
+/**
+ * The accepted cycle's frozen camera-ready against its frozen `submitted.tex`, or none: nothing to judge
+ * before the camera-ready is frozen (or without either source), and nothing wrong when it derives.
+ */
+function cameraFinding(dir: string, files: Files): VersionFinding | null {
+  const cycles = cyclesIn(dir, files);
+  if (cycles === null || cycles.current.kind !== "accepted") return null;
+  const id = cycles.current.cycle.id;
+  const camera = frozenText(dir, frozenKey(id, "camera-ready", "tex"), files);
+  const accepted = frozenText(dir, frozenKey(id, "submitted", "tex"), files);
+  if (camera === null || accepted === null) return null;
+  const l = lineage(accepted, camera);
+  return derivesFrom(l)
+    ? null
+    : {
+        messageId: "base",
+        data: { id, kept: String(l.kept), total: String(l.total) },
+      };
+}
+
+/** A rule on paper.tex: its one finding, reported on the first line. */
+const paperRule = (
+  meta: TexRuleModule["meta"],
+  finding: (dir: string, draft: () => string) => VersionFinding | null,
+  deps: ProseDeps,
+): TexRuleModule => ({
+  meta,
+  create(context) {
+    if (basename(context.filename) !== "paper.tex") return {};
+    return {
+      root() {
+        const sc = context.sourceCode;
+        const f = finding(
+          dirname(context.filename),
+          () => readPaper(context.filename, sc.raw ?? sc.text, deps).text,
+        );
+        if (f === null) return;
+        const at = sc.getLocFromIndex(0);
+        context.report({ loc: { start: at, end: at }, ...f });
+      },
+    };
+  },
+});
+
+/** The `cycle` plugin's rules over the draft, for every `paper.tex`. */
+export const draftRules = (
+  deps: ProseDeps,
+): Readonly<Record<"draft-drift" | "camera-ready-source", TexRuleModule>> => ({
+  "draft-drift": paperRule(
+    DRIFT_META,
+    (dir, draft) => driftFinding(dir, draft(), deps),
+    deps,
+  ),
+  "camera-ready-source": paperRule(
+    CAMERA_META,
+    (dir) => cameraFinding(dir, deps.files),
+    deps,
+  ),
+});
+
+/** The levels they are on at in paperlint's own config. */
+export const VERSION_STATUS_RULE_LEVELS: Readonly<
+  Record<"versions/layout" | "cycle/submitted-frozen", "error">
+> = { "versions/layout": "error", "cycle/submitted-frozen": "error" };
+
+export const DRAFT_RULE_LEVELS: Readonly<
+  Record<"cycle/draft-drift" | "cycle/camera-ready-source", "warn" | "error">
+> = { "cycle/draft-drift": "warn", "cycle/camera-ready-source": "error" };