paperlint 4.2.0 → 5.0.0

package/eslint-rules/paper-research-question.ts

@@ -1,199 +0,0 @@
-/**
- * `paper/research-question` — a shipped paper states its research question EXPLICITLY.
- *
- * Reviewer A's verbatim point on agenticdev (#20), as it was parsed: "State the goal as a
- * research question." This is a venue expectation, not taste: an empirical paper that never
- * names the question it answers forces the reviewer to reconstruct it — and they say so.
- *
- * ── WHY THE SCOPE IS SHIPPED PAPERS ONLY ─────────────────────────────────────────────────
- * A draft never asked anyone to read it. The scope deliberately matches `paper/author-list`:
- * both are about the DEBT of a shipped paper, and an unshipped one has no debt. Measured on the
- * live corpus before the move:
- *     agenticdev-2026   has RQ,   shipped        -> silent  (added because of this very review)
- *     aisec-2026        no RQ,    shipped        -> a finding
- *     compile-rules     no RQ,    shipped        -> a finding
- *     scored-2026       no RQ,    NOT shipped    -> silent
- *
- * ── WHAT THE MOVE CHANGED ─────────────────────────────────────────────────────────────────
- * The predecessor read the stage with a REGEX OVER THE SCORECARD'S PROSE. Remeasured 2026-09-17:
- * for `agenticdev-2026` the prose reads `submitted`, while the `stages` field declares
- * `submitted, camera-ready`. Here the stage comes from the FIELD — the same one `paper/stages`
- * checks against the bytes in both directions.
- *
- * ⚠️ WHAT THE MOVE DOES NOT FIX, AND THIS IS MEASURED, NOT ASSUMED. The rule reads RAW text, not
- * the parsed tree, so a mention of RQ inside a LaTeX comment (`% add an RQ`) will put it to
- * sleep. Measured 2026-09-17 across all four papers: ZERO such cases — not a single match inside
- * a comment. So the hole is LATENT, not observed, and closing it with a tree walk would
- * complicate the rule without a measured difference. The neighboring `paper/typography` is built
- * the same way and for the same reason. Once a real case shows up, there will be something to
- * cite here.
- *
- * The rule is ADVISORY by decision, not by coincidence: a position paper may legitimately have
- * no question. Then its absence is the author's decision, and the rule says exactly that,
- * rather than declaring the absence a defect on its own.
- */
-import { existsSync, readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { load } from "js-yaml";
-import { z } from "zod";
-import type { RuleContext } from "./rule-context.ts";
-
-/**
- * The two scorecard fields this rule reads, parsed rather than trusted: a field of the wrong shape
- * reads as absent, the way `data?.stages` on a string or a number always did.
- */
-const Scorecard = z
-  .looseObject({
-    stages: z.array(z.unknown()).catch([]),
-    researchQuestion: z.string().catch(""),
-  })
-  .catch({ stages: [], researchQuestion: "" });
-const StageEntry = z.looseObject({ stage: z.unknown().optional() }).catch({});
-const RuleOptions = z
-  .object({ statusFile: z.string().default("PIPELINE-STATUS.md") })
-  .default({ statusFile: "PIPELINE-STATUS.md" });
-
-/**
- * 🔴 THE REGEX IS GONE, AND THE REASON IS NOT "regexes are bad" — IT IS THAT IT ANSWERED THE
- * WRONG QUESTION (2026-09-19).
- *
- * What stood here was `/\\textbf\{RQ|\bRQ[0-9]?\b|research question/i`, defended in this very
- * file with: "a regex is LEGITIMATE here: the subject is human prose, which has no structure by
- * definition, and no parser can tell a question's statement apart from a paragraph about it."
- *
- * The premise is true. The conclusion does not follow. From "the text cannot decide this" the
- * answer is not "so pattern-match harder" — it is "so the HUMAN declares it, and the check
- * compares the declaration against the text." The three spellings were an undeclared schema
- * field: someone added a fact and invented a convention for how it would look in prose, which is
- * the design running backwards.
- *
- * What the pattern actually decided, in both directions:
- *   • a paper that says "we leave the research question to future work" — MATCHED, and the rule
- *     went silent on a paper that states no question at all;
- *   • a paper whose question is written plainly ("Does pruning reduce review cost?") with no
- *     "RQ" anywhere — NOT matched, and the rule reported a paper that does exactly what is asked.
- * An open list of spellings cannot be completed, so both failures are structural, not bugs.
- *
- * ── WHAT REPLACES IT: ONE UNDECIDABLE QUESTION BECOMES TWO DECIDABLE ONES ──────────────────
- *   1. Is the question WRITTEN DOWN? — `researchQuestion` in the scorecard's front matter. A
- *      field, parsed by js-yaml, not a phrase hunted for in prose.
- *   2. Does the paper CONTAIN what was written down? — the declared sentence, whitespace
- *      collapsed, compared against the source. Bytes, not spelling.
- *
- * This is the shape this package already uses twice, and for the same reason: `bytes`/
- * `sourceBytes` (a recorded number compared against the file on disk) and `paper/author-list`
- * (a recorded marker, because whether a cross-check ran is not visible in the paper). Neither
- * asks the prose a question the prose cannot answer.
- *
- * ⚠️ WHAT THIS STILL CANNOT DO, said plainly rather than implied: nothing here decides that the
- * declared sentence IS a research question. A declaration of "banana" passes step 1 and, if the
- * word appears in the paper, step 2. The rule guarantees that the author wrote a question down
- * and that the paper carries it — it does not grade the question. That is a human's job, and
- * pretending otherwise is what the regex was doing.
- */
-
-/** Whitespace is the only thing normalised: a sentence wrapped across lines is the same sentence. */
-const flatten = (t: string) => t.replace(/\s+/g, " ").trim().toLowerCase();
-
-/**
- * Both facts come out of ONE parse of the scorecard's front matter: the stages (has this paper
- * shipped?) and the declared question. Reading them separately would invite the two to be taken
- * from different revisions of the same file.
- */
-function scorecard(
-  dir: string,
-  statusName: string,
-): { stages: unknown[]; question: string } {
-  const p = join(dir, statusName);
-  const none = { stages: [], question: "" };
-  if (!existsSync(p)) return none;
-  let text: string;
-  try {
-    text = readFileSync(p, "utf-8");
-  } catch {
-    return none;
-  }
-  const m = /^---\n([\s\S]*?)\n---/.exec(text);
-  if (!m) return none;
-  const [, front = ""] = m;
-  let data: unknown;
-  try {
-    data = load(front);
-  } catch {
-    return none; // the unreadable YAML is already reported by `paper/stages`, on its own file
-  }
-  const { stages: raw, researchQuestion: question } = Scorecard.parse(data);
-  const stages = raw.map((r) => StageEntry.parse(r).stage).filter(Boolean);
-  return { stages, question };
-}
-
-export default {
-  rules: {
-    "research-question": {
-      meta: {
-        type: "suggestion" as const,
-        docs: {
-          description:
-            "a paper that declares a stage states its research question explicitly — otherwise the reviewer reconstructs it themselves, and says so",
-        },
-        schema: [
-          {
-            type: "object",
-            properties: {
-              // The scorecard's name is a CONSUMER convention. The rule is declared on the
-              // paper's source, so it has to name its neighbor itself rather than get it via a
-              // config glob.
-              statusFile: { type: "string" },
-            },
-            additionalProperties: false,
-          },
-        ],
-        messages: {
-          notDeclared:
-            "the paper shipped (stage «{{stages}}») and its scorecard declares no `researchQuestion`. This is reviewer A's verbatim point on agenticdev (#20), not the linter's taste. Write the question down as a field, in your own words — the check cannot infer it from the prose, and the pattern that used to try matched «we leave the research question to future work» while missing a question stated plainly. Advisory: a position paper may legitimately have none, and then leaving the field out is a DECISION — record it as one",
-          notInPaper:
-            "the scorecard declares a research question the paper does not contain. Looked for «{{needle}}» with whitespace collapsed, and the source has no such run of text. Either the paper dropped it or the declaration drifted from what was written — and which of the two it is, only you know",
-        },
-      },
-      create(context: RuleContext) {
-        const { statusFile: statusName } = RuleOptions.parse(
-          context.options[0],
-        );
-        return {
-          // `root:exit` exists for both markdown and the `tex/latex` language — the same place
-          // `paper/typography` lives, and for the same reason: a paper in this corpus can be
-          // either.
-          "root:exit"(node: object) {
-            const raw = context.sourceCode.raw ?? context.sourceCode.text;
-            if (typeof raw !== "string") return;
-            const { stages, question } = scorecard(
-              dirname(context.filename),
-              statusName,
-            );
-            if (stages.length === 0) return; // not shipped — owes nothing
-
-            // Step 1 — is it written down? A field, not a phrase hunted for in prose.
-            if (question.trim() === "") {
-              context.report({
-                node,
-                messageId: "notDeclared",
-                data: { stages: stages.join("/") },
-              });
-              return;
-            }
-
-            // Step 2 — does the paper carry what was written down? Bytes, not spelling. Only
-            // whitespace is normalised, because a sentence wrapped across source lines is the
-            // same sentence; everything else stays the author's.
-            if (flatten(raw).includes(flatten(question))) return;
-            context.report({
-              node,
-              messageId: "notInPaper",
-              data: { needle: flatten(question) },
-            });
-          },
-        };
-      },
-    },
-  },
-};

package/fixtures/paper-research-question/comment-only/PIPELINE-STATUS.md

@@ -1,9 +0,0 @@
----
-stages:
-  - stage: submitted
-    date: 2026-07-22
-    venue: A Venue 2026
-    pdf: versions/2026-07-22-submitted.pdf
-    bytes: 100
----
-# PIPELINE-STATUS

package/fixtures/paper-research-question/comment-only/paper.tex

@@ -1,7 +0,0 @@
-\section{Introduction}
-% TODO: state the research question — this is a LaTeX COMMENT.
-% The rule reads RAW text and today does not tell it apart from the paper, so here it STAYS
-% SILENT. The hole is named in the rule's header and measured: on the live corpus there are
-% zero such cases, so it is latent. The fixture keeps it visible — the first real case turns
-% up and the assertion below has to be rewritten deliberately, not discovered after the fact.
-Body text of the paper, in which no question is stated.

package/fixtures/paper-research-question/declared-not-in-paper/PIPELINE-STATUS.md

@@ -1,10 +0,0 @@
----
-stages:
-  - stage: submitted
-    date: 2026-07-22
-    venue: A Venue 2026
-    pdf: versions/2026-07-22-submitted.pdf
-    bytes: 100
-researchQuestion: "Does pruning reduce review cost?"
----
-# PIPELINE-STATUS

package/fixtures/paper-research-question/declared-not-in-paper/paper.tex

@@ -1,6 +0,0 @@
-\section{Introduction}
-% This fixture is the one the predecessor could not express. The scorecard declares a question;
-% the paper does not carry it. And the words "research question" DO appear below — so the old
-% pattern `/\textbf{RQ|\bRQ[0-9]?\b|research question/i` matched and went silent on a paper that
-% states no question at all. Matching a phrase ABOUT the thing is not finding the thing.
-We leave the research question to future work.

package/fixtures/paper-research-question/draft/PIPELINE-STATUS.md

@@ -1,6 +0,0 @@
----
-stages: []
----
-# PIPELINE-STATUS
-
-A draft, never submitted anywhere.

package/fixtures/paper-research-question/draft/paper.tex

@@ -1,2 +0,0 @@
-\section{Introduction}
-A draft with no question. Nobody was asked to read it.

package/fixtures/paper-research-question/markdown-no-rq/PIPELINE-STATUS.md

@@ -1,9 +0,0 @@
----
-stages:
-  - stage: submitted
-    date: 2026-07-22
-    venue: A Venue 2026
-    pdf: versions/2026-07-22-submitted.pdf
-    bytes: 100
----
-# PIPELINE-STATUS

package/fixtures/paper-research-question/markdown-no-rq/paper.md

@@ -1,4 +0,0 @@
-# Introduction
-
-The paper is written in markdown, not LaTeX — that happens in this corpus, and the rule must
-see it the same way. No question is stated here.

package/fixtures/paper-research-question/shipped-no-rq/PIPELINE-STATUS.md

@@ -1,12 +0,0 @@
----
-stages:
-  - stage: submitted
-    date: 2026-07-22
-    pdf: versions/a.pdf
-    bytes: 1
-  - stage: camera-ready
-    date: 2026-08-29
-    pdf: versions/b.pdf
-    bytes: 2
----
-# PIPELINE-STATUS

package/fixtures/paper-research-question/shipped-no-rq/paper.tex

@@ -1,3 +0,0 @@
-\section{Introduction}
-We study how agents behave and measure how many rules survive to the run.
-The question is named nowhere — neither by a macro nor in words.

package/fixtures/paper-research-question/shipped-with-rq/PIPELINE-STATUS.md

@@ -1,10 +0,0 @@
----
-stages:
-  - stage: submitted
-    date: 2026-07-22
-    venue: A Venue 2026
-    pdf: versions/2026-07-22-submitted.pdf
-    bytes: 100
-researchQuestion: "does a rule written in prose survive to the run?"
----
-# PIPELINE-STATUS

package/fixtures/paper-research-question/shipped-with-rq/paper.tex

@@ -1,2 +0,0 @@
-\section{Introduction}
-\textbf{RQ1:} does a rule written in prose survive to the run?

package/src/action-ref.test.ts

@@ -1,26 +0,0 @@
-import assert from "node:assert/strict";
-import { test } from "vitest";
-import { actionRef } from "./action-ref.ts";
-
-/** [the running package's version, the ref `paperlint init` may pin the action to]. */
-const TABLE: readonly (readonly [string | undefined, string | null])[] = [
-  ["1.2.3", "v1.2.3"],
-  ["1.0.0", "v1.0.0"],
-  ["10.20.30", "v10.20.30"],
-  // Guards: a git checkout / `npm link` carries the unreleased placeholder — there is no tag for it.
-  ["0.0.0-semantically-released", null],
-  // Guards: only a plain release is known to have a tag; anything else stays the placeholder.
-  ["1.2.3-beta.1", null],
-  ["v1.2.3", null],
-  ["1.2", null],
-  ["", null],
-  ["latest", null],
-  [" 1.2.3", null],
-  // Guards: the CLI could not read its own manifest — no version, no pin.
-  [undefined, null],
-];
-
-for (const [version, ref] of TABLE)
-  test(`actionRef(${JSON.stringify(version)})`, () => {
-    assert.equal(actionRef(version), ref);
-  });

package/src/action-ref.ts

@@ -1,15 +0,0 @@
-/**
- * The ref `paperlint init` pins the GitHub Action to, decided from the version of the package that is
- * running. semantic-release tags every release `v<version>` on the commit it publishes, so the
- * action at that tag is the same code as the installed package.
- *
- * Only a plain `X.Y.Z` has such a tag. A git checkout or `npm link` carries the unreleased
- * placeholder `0.0.0-semantically-released`, a version that could not be read is `undefined`, and
- * anything else is not known to be tagged: those return `null` ("no pin known"), and the caller
- * keeps the placeholder. A wrong tag written confidently is worse than an obvious placeholder.
- */
-export function actionRef(version: string | undefined): string | null {
-  return version !== undefined && /^\d+\.\d+\.\d+$/.test(version)
-    ? `v${version}`
-    : null;
-}