paperlint 2.0.0

package/action.harness.mjs

@@ -0,0 +1,287 @@
+/**
+ * Harness over `action.yml` and the guard it calls.
+ * Run: `npx vigiles test action.harness.mjs`
+ *
+ * 🔴 WHAT IT REFUSES TO BE. A harness that greps `action.yml` for `--no-config-lookup` would pass
+ * on a file where the flag sits inside a comment, and would say nothing about whether the action
+ * BEHAVES. So: the YAML is read with a PARSER (`js-yaml`) and addressed as nodes, and the
+ * green-zero guard is exercised by CALLING it on fixtures — the same entry point the action calls.
+ *
+ * BOTH HALVES for every property: it fires on a planted defect AND stays quiet on a clean input.
+ * A guard only ever observed silent is indistinguishable from a dead one.
+ */
+import assert from "node:assert/strict";
+import {
+  readFileSync,
+  writeFileSync,
+  mkdtempSync,
+  realpathSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import * as yaml from "js-yaml";
+import { guard } from "./scripts/eslint-report-guard.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TMP = realpathSync(mkdtempSync(join(tmpdir(), "rpp-action-")));
+const action = yaml.load(readFileSync(join(HERE, "action.yml"), "utf8"));
+
+// ── I. SHAPE, read as nodes ───────────────────────────────────────────────────────────────────
+assert.equal(action.runs.using, "composite", "the action must be composite");
+const names = action.runs.steps.map((s) => s.name);
+assert.equal(
+  action.runs.steps.length,
+  4,
+  `expected 4 steps, got ${action.runs.steps.length}: ${names}`,
+);
+
+const eslintStep = action.runs.steps.find((s) => s.name === "paperlint lint");
+assert.ok(eslintStep, `no step named "paperlint lint" among: ${names}`);
+
+// 🔴 THE ACTION MUST CALL THE PACKAGE'S OWN CLI, NOT ESLINT. This is not tidiness: while the step
+// invoked `npx eslint` directly it was a SECOND implementation of the same job, and it had already
+// drifted — the directory-structure check (a paper directory with no PIPELINE-STATUS.md gets zero
+// rules and reports clean) lives in `bin/rpp.mjs`, so in CI it did not run at all. Any future edit
+// that reaches past the CLI reintroduces exactly that gap, silently and greenly.
+assert.match(
+  eslintStep.run,
+  /npx paperlint lint/,
+  "the lint step must call this package's own CLI — invoking eslint directly bypasses rpp.json and the structure check",
+);
+assert.doesNotMatch(
+  eslintStep.run,
+  /npx eslint/,
+  "the lint step must not invoke eslint directly — that is the bypass this step was fixed to remove",
+);
+// `--no-config-lookup` is deliberately absent and is NOT missing: the CLI builds its config with
+// `overrideConfigFile: true`, so a consumer's nested config cannot reach the run. The guarantee
+// moved from a flag into the code — assert the code, not the flag.
+//
+// 🔴 AND ASSERT IT IN THE FILE THAT HOLDS IT. This read said `bin/rpp.mjs` until the CLI moved to
+// TypeScript; `bin/rpp.mjs` is now a loader shim and contains no such call, so the assertion went
+// red on a move that changed no behaviour. That redness is the point — the same assertion written
+// as a grep over "the CLI" would have kept passing against whichever file still matched, which is
+// how a check quietly stops watching its subject.
+assert.match(
+  readFileSync(new URL("./src/cli.ts", import.meta.url), "utf8"),
+  /overrideConfigFile:\s*true/,
+  "the CLI must pin its own config, or a consumer's nested config silently changes the rule set",
+);
+// The redirect into a report file is only sound while `--json` keeps stdout clean.
+assert.match(
+  eslintStep.run,
+  /--json > "\$RUNNER_TEMP\/rpp\.json"/,
+  "the machine-readable report must be redirected whole — it is what the guard reads",
+);
+// The guard must be CALLED, and by file — an inline blob would be untestable.
+assert.match(
+  eslintStep.run,
+  /eslint-report-guard\.mjs/,
+  "the lint step must hand its report to scripts/eslint-report-guard.mjs",
+);
+// ── I-b. THE STEP'S SHELL SEMANTICS, EXECUTED — not grepped ───────────────────────────────────
+//
+// 🔴 THE ASSERTION THAT STOOD HERE READ THE TEXT (`/RC=\$\?/`) AND WAS GREEN OVER A DEAD ERROR
+// PATH. GitHub runs composite `shell: bash` as `bash --noprofile --norc -eo pipefail`. Under `-e`
+// a bare `npx eslint` that exits non-zero ABORTS THE SCRIPT, so the guard on the next line never
+// ran — and the file contained the characters `RC=$?` either way, so the text assertion could not
+// tell the two apart. Every failure this action exists to explain (bad config, unreadable report,
+// non-zero ESLint) lives on exactly that dead path.
+//
+// So: execute the REAL `run:` block under the REAL flags, with a stub standing in for `npx`, and
+// require that the guard was reached and that ESLint's code came through it.
+const stubbedStepRun = (stubRc) => {
+  const bin = realpathSync(mkdtempSync(join(tmpdir(), "rpp-bin-")));
+  writeFileSync(
+    join(bin, "npx"),
+    // Stub prints the report TO STDOUT, not to a file by the `-o` flag: the step no longer passes
+    // `-o`, it REDIRECTS output. So the stub also checks the redirect itself — if it disappears
+    // from the step, the file stays empty and the guard says "nothing was measured".
+    `#!/usr/bin/env bash\n` +
+      `printf '%s' "$REPORT_JSON"\n` +
+      `exit "$STUB_RC"\n`,
+    { mode: 0o755 },
+  );
+  return spawnSync(
+    "bash",
+    ["--noprofile", "--norc", "-eo", "pipefail", "-c", eslintStep.run],
+    {
+      cwd: TMP,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        PATH: `${bin}:${process.env.PATH}`,
+        RUNNER_TEMP: TMP,
+        GITHUB_ACTION_PATH: HERE,
+        RPP_CONFIG: "eslint.config.mjs",
+        RPP_PATHS: ".",
+        RPP_MAXWARN: "-1",
+        STUB_RC: String(stubRc),
+        REPORT_JSON: JSON.stringify([{ filePath: "/x/a.md", messages: [] }]),
+      },
+    },
+  );
+};
+
+// FIRES-THROUGH: ESLint failed. This is the case the old text assertion could not see.
+{
+  const r = stubbedStepRun(2);
+  assert.match(
+    r.stdout,
+    /linted 1 file\(s\)/,
+    "the guard must still run when ESLint exits non-zero — under `bash -e` a bare command aborts the step",
+  );
+  assert.equal(
+    r.status,
+    2,
+    "ESLint's failure code must come through the guard, not be masked to 1",
+  );
+}
+// QUIET HALF: ESLint succeeded — the guard runs and passes 0 through.
+{
+  const r = stubbedStepRun(0);
+  assert.match(
+    r.stdout,
+    /linted 1 file\(s\)/,
+    "the guard must run on success too",
+  );
+  assert.equal(r.status, 0, "a clean run must stay green");
+}
+
+// texcount is checked for EXISTENCE, not by the installer's exit code: an installer can put nothing
+// in place and report success (measured in this corpus, 2026-09-01).
+const pathStep = action.runs.steps.find((s) => /on PATH/i.test(s.name ?? ""));
+assert.ok(pathStep, `no step verifying texcount is on PATH among: ${names}`);
+assert.match(
+  pathStep.run,
+  /command -v texcount/,
+  "the PATH step must probe the binary itself",
+);
+
+for (const key of [
+  "config",
+  "paths",
+  "max-warnings",
+  "texcount",
+  "working-directory",
+])
+  assert.ok(action.inputs[key], `input \`${key}\` is missing`);
+
+// ── `paths` is REQUIRED, and the requirement is ENFORCED, not merely declared ─────────────────
+// 🔴 GitHub does not enforce `required: true` for COMPOSITE actions. A caller who omits the
+// input reaches the first step with an empty string and no error at all. So two separate things
+// are asserted here, and neither implies the other: that the contract is DECLARED, and that a
+// step exists which can actually fail on it.
+assert.equal(
+  action.inputs.paths.required,
+  true,
+  "`paths` must be declared required",
+);
+assert.ok(
+  !("default" in action.inputs.paths),
+  "`paths` must have NO default — the old default `.` linted the whole checkout, so a caller " +
+    "who never chose a scope still got a green job over one",
+);
+const pathsGuard = action.runs.steps.find((s) =>
+  /paths was actually given/i.test(s.name ?? ""),
+);
+assert.ok(
+  pathsGuard,
+  `no step enforcing the \`paths\` contract among: ${names}`,
+);
+assert.match(
+  pathsGuard.run,
+  /exit 1/,
+  "the `paths` guard must FAIL, not warn — a declaration nobody checks is documentation",
+);
+// And it must come FIRST: checking scope after texlive setup would burn apt minutes
+// for a call already wrong.
+assert.equal(
+  action.runs.steps[0].name,
+  pathsGuard.name,
+  "the `paths` guard must run FIRST — checking scope after an apt install burns minutes on a " +
+    "call that was already wrong",
+);
+
+// ── II. BEHAVIOUR of the guard — both halves, on fixtures ─────────────────────────────────────
+const fixture = (name, body) => {
+  const p = join(TMP, name);
+  writeFileSync(p, body);
+  return p;
+};
+
+// FIRES: zero files linted. The whole reason the guard exists.
+{
+  const { code, lines } = guard(fixture("empty.json", "[]"), 0, {
+    paths: ".",
+    config: "c.mjs",
+  });
+  assert.equal(
+    code,
+    1,
+    "a report of zero linted files must FAIL, not pass as clean",
+  );
+  assert.match(lines.join("\n"), /linted ZERO files/);
+}
+// FIRES: the report is absent or unparsable — nothing was measured either way.
+assert.equal(
+  guard(join(TMP, "absent.json"), 0).code,
+  1,
+  "an unreadable report must FAIL",
+);
+assert.equal(
+  guard(fixture("garbage.json", "{oops"), 0).code,
+  1,
+  "an unparsable report must FAIL",
+);
+assert.equal(
+  guard(fixture("object.json", '{"not":"an array"}'), 0).code,
+  1,
+  "a report that is not a result array must FAIL",
+);
+
+// QUIET: files were linted and ESLint was happy → ESLint's code passes through untouched.
+{
+  const one = fixture(
+    "one.json",
+    JSON.stringify([
+      {
+        filePath: "/x/a.md",
+        messages: [
+          { severity: 1, line: 3, column: 1, ruleId: "paper/x", message: "m" },
+        ],
+      },
+    ]),
+  );
+  assert.equal(
+    guard(one, 0).code,
+    0,
+    "a real run with findings must pass ESLint's own 0 through",
+  );
+  assert.equal(
+    guard(one, 2).code,
+    2,
+    "a real run must pass ESLint's failure code through, not mask it",
+  );
+}
+// QUIET: a file linted with NO findings is a legitimate clean run — the guard must not fire on it.
+{
+  const clean = fixture(
+    "clean.json",
+    JSON.stringify([{ filePath: "/x/a.md", messages: [] }]),
+  );
+  const { code, lines } = guard(clean, 0);
+  assert.equal(
+    code,
+    0,
+    "one file linted with zero findings is CLEAN, not empty — the guard must be quiet",
+  );
+  assert.doesNotMatch(lines.join("\n"), /linted ZERO files/);
+  assert.match(lines.join("\n"), /linted 1 file\(s\) · 0 finding\(s\)/);
+}
+
+console.log(
+  "✓ action.yml shape (parsed, not grepped) + guard behaviour, both halves — 20 assertions",
+);

package/action.mutations.mjs

@@ -0,0 +1,162 @@
+/**
+ * Mutation battery over `action.yml` and `scripts/eslint-report-guard.mjs`.
+ * Run: `node action.mutations.mjs` (not `vigiles test` — this is not a harness).
+ *
+ * 🔴 EVERY MUTATION CARRIES A "THE PATCH LANDED" ASSERTION: the target must occur EXACTLY ONCE,
+ * the mutant must be present in the file re-read from disk, the original text must be GONE, and
+ * after the rollback the contents must return byte for byte. In this corpus a green mutation has
+ * three times meant not "the defence holds" but "the patch never applied".
+ *
+ * A GREEN HARNESS UNDER A MUTATION is a finding about the TEST, not a conclusion about the defence.
+ * Rank the causes: the wrong test · the patch did not land · the set is too narrow · THE RUN WAS
+ * ALREADY RED BEFORE THE MUTATION. The last is why the baseline runs FIRST and its failure stops
+ * the battery.
+ *
+ * ⚠️ Mutation 1 is the load-bearing one and it is deliberately asymmetric: it sends the step back
+ * to calling `npx eslint` directly while LEAVING the words `paperlint lint` in the comments above. A
+ * harness that grepped the file would stay green; this one parses the YAML and addresses the step
+ * as a node, so it dies. That is the whole argument for the parser, made executable.
+ *
+ * It replaced a mutation over `--no-config-lookup`, which stopped having a target on 2026-09-18:
+ * the flag went away with the eslint call, and the guarantee it carried moved INTO the CLI
+ * (`overrideConfigFile: true`). The bypass it protected against is the same one — a consumer's
+ * nested config deciding the rule set — so the case moved rather than disappeared.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+const HARNESS = "action.harness.mjs";
+
+if (process.env.MUTATIONS_REPORT_COVERAGE) {
+  console.log(`MUTATION-COVERS\t${HARNESS}`);
+  process.exit(0);
+}
+
+const ACTION = "action.yml";
+const GUARD = "scripts/eslint-report-guard.mjs";
+const PRISTINE = new Map(
+  [ACTION, GUARD].map((f) => [f, readFileSync(f, "utf8")]),
+);
+const restoreAll = () => {
+  for (const [f, body] of PRISTINE) writeFileSync(f, body);
+};
+
+const M = [
+  [
+    ACTION,
+    "the step goes back around the CLI to eslint (the words `paperlint lint` left in the comments)",
+    "reinstate the bypass: rpp.json unread, the directory-structure check absent in CI, and a " +
+      "consumer's nested config free to decide the rule set — while a grep still finds `paperlint lint`",
+    "npx paperlint lint $RPP_PATHS",
+    'npx eslint --config "$RPP_CONFIG" $RPP_PATHS',
+  ],
+  [
+    ACTION,
+    "the guard is no longer called",
+    "keep the lint run and drop the green-zero check — the job passes loudest when it measured nothing",
+    'node "$GITHUB_ACTION_PATH/scripts/eslint-report-guard.mjs" \\',
+    "true # MUT \\",
+  ],
+  [
+    ACTION,
+    "texcount probed by the installer's exit code instead of by the binary",
+    "trust an installer that can put nothing in place and report success",
+    "command -v texcount >/dev/null || {",
+    "true || {",
+  ],
+  [
+    GUARD,
+    "a report of ZERO linted files treated as clean",
+    "reinstate the exact indistinguishability the guard exists to break",
+    "  if (res.length === 0) {",
+    "  if (false) { /* MUT */",
+  ],
+  [
+    GUARD,
+    "ESLint's return code masked",
+    "swallow a real ESLint failure and report success",
+    "  return { code: eslintRc, lines };",
+    "  return { code: 0, lines }; /* MUT */",
+  ],
+  [
+    GUARD,
+    "an unparsable report treated as clean",
+    "let a missing or corrupt report pass — nothing was measured either way",
+    "    lines.push(\n      `::error::ESLint wrote no parsable report to ${reportPath} (rc=${eslintRc}). Nothing was measured.`,\n    );\n    return { code: 1, lines };",
+    "    return { code: 0, lines }; /* MUT */",
+  ],
+];
+
+const run = () => {
+  try {
+    return {
+      ok: true,
+      out: execFileSync("npx", ["vigiles", "test", HARNESS], {
+        encoding: "utf8",
+        stdio: "pipe",
+      }),
+    };
+  } catch (e) {
+    return { ok: false, out: `${e.stdout ?? ""}${e.stderr ?? ""}` };
+  }
+};
+
+const base = run();
+if (!base.ok) {
+  console.log(
+    "❌ THE HARNESS IS RED BEFORE ANY MUTATION — the battery cannot tell a killed mutation from that:\n" +
+      base.out.slice(-1200),
+  );
+  process.exit(1);
+}
+
+let ok = 0;
+let bad = 0;
+const rows = [];
+
+for (const [file, label, what, from, to] of M) {
+  const pristine = PRISTINE.get(file);
+  const hits = pristine.split(from).length - 1;
+  if (hits !== 1) {
+    console.log(
+      `❌ ${label}: TARGET ${hits === 0 ? "NOT FOUND" : `NOT UNIQUE (${hits})`} in ${file}`,
+    );
+    bad++;
+    continue;
+  }
+  writeFileSync(file, pristine.replace(from, to));
+  const on = readFileSync(file, "utf8");
+  if (!on.includes(to) || on.includes(from)) {
+    console.log(
+      `❌ ${label}: THE MUTATION DID NOT LAND (checked by re-reading ${file})`,
+    );
+    bad++;
+    restoreAll();
+    continue;
+  }
+  const res = run();
+  restoreAll();
+  if (readFileSync(file, "utf8") !== pristine) {
+    console.log(`❌ ${label}: THE ROLLBACK FAILED on ${file}`);
+    bad++;
+    continue;
+  }
+  if (!res.ok) {
+    ok++;
+    const why =
+      (res.out.match(/AssertionError[^\n]*?: ([^\n]*)/) ?? [])[1] ??
+      "(the harness died)";
+    rows.push([label, what, why.trim().slice(0, 100)]);
+  } else {
+    console.log(
+      `🔴 ${label}: THE HARNESS IS GREEN UNDER THE MUTATION — a finding about the TEST, not a conclusion about the defence`,
+    );
+    bad++;
+  }
+}
+
+console.log("\n| property | mutation | what the harness died on |");
+console.log("|---|---|---|");
+for (const r of rows) console.log(`| ${r[0]} | ${r[1]} | ${r[2]} |`);
+console.log(`\n${ok} mutation(s) killed, ${bad} problem(s)`);
+process.exit(bad === 0 ? 0 : 1);

package/action.yml

@@ -0,0 +1,138 @@
+# Composite action: set up what the LaTeX rules need, then run `paperlint lint` over a consumer's corpus.
+#
+# 🔴 THIS ACTION CALLS THE PACKAGE'S OWN CLI. It used to invoke `npx eslint` directly, and that was
+# not a style question — it was a second implementation of the same job, and it had already drifted:
+# the CLI's directory-structure check (a paper directory missing PIPELINE-STATUS.md gets ZERO rules
+# and reports clean) lived only in `bin/rpp.mjs`, so the gate existed locally and was ABSENT in CI,
+# which is the one place it has to hold. The same bypass also meant `rpp.json` was never read and
+# the caller still had to keep an ESLint flat config — the exact thing the CLI exists to remove.
+#
+# WHY AN ACTION AND NOT A DOCUMENTED `run:` BLOCK. Two steps have to happen in this order and
+# neither is guessable from the outside: `texcount` must exist on PATH before linting starts, and
+# the scope has to be checked before any install spends minutes on a call that was already wrong.
+# A consumer who copies only the last step gets a green job over rules that silently degraded —
+# see the `texcount` note below.
+#
+# 🔴 THE GREEN-ZERO GUARD IS PART OF THIS ACTION, NOT AN OPTIONAL EXTRA. `eslint` prints findings
+# and exits 0 when there are none — and "no findings" is byte-identical to "not one rule was handed
+# a single file". A rule whose glob matched nothing is never invoked, and a rule that is never
+# invoked physically cannot report that. So this action asserts that ESLint linted at least one
+# file and fails loudly when it did not. This does NOT replace a per-rule glob audit (the package's
+# own `scripts/rules-see-files.mjs` does that, and it reads the package's config, not yours) — it closes the
+# one failure mode that needs no config knowledge: nothing was linted at all.
+name: paperlint — LaTeX prose gate
+description: Install the toolchain the texcount/* rules need, run ESLint, and refuse to pass on an empty run.
+
+inputs:
+  config:
+    description: >-
+      Path to `rpp.json`. Optional: `paperlint lint` finds it by walking up from the working directory,
+      the way eslint and tsc find theirs, so most callers never set this. Pass it only when the
+      file is somewhere the walk cannot reach. ⚠️ Until 2026-09-18 this input took a path to an
+      ESLint FLAT CONFIG and defaulted to `eslint.config.mjs`; a caller still passing one will
+      fail loudly on the first run rather than lint against it.
+    required: false
+    default: ""
+  paths:
+    description: >-
+      What to lint, as ESLint would take it on the command line. REQUIRED, and deliberately
+      without a default: the previous default was "." — the whole checkout — so a caller who
+      never thought about scope still got a green job, over whatever happened to be in the
+      repository. Scope is the one thing this action cannot guess.
+    required: true
+  max-warnings:
+    description: >-
+      Passed through to ESLint. The default -1 means warnings never fail the job: in this rule set
+      most findings are advisory by design, and a gate that fails on advice gets muted.
+    required: false
+    default: "-1"
+  texcount:
+    description: >-
+      Install the `texcount` binary before linting. 🔴 THIS PACKAGE SHIPS NO RULE THAT USES IT —
+      measured 2026-09-17, zero rules named `texcount/*` here. It is on by default for CONSUMERS
+      whose own config carries such rules (the author's does: `texcount/walls`,
+      `texcount/appendix-ratio`), because without the binary those rules DO NOT FAIL — they
+      quietly fall back to a weaker word count and the job stays green. If your config has no
+      such rule, set this to "false" and save the apt fetch.
+    required: false
+    default: "true"
+  working-directory:
+    description: Directory to run in.
+    required: false
+    default: "."
+
+runs:
+  using: composite
+  steps:
+    # 🔴 `required: true` ABOVE IS A DECLARATION, NOT AN ENFORCEMENT. GitHub does not enforce
+    # required inputs for COMPOSITE actions — a caller who omits `paths` reaches this step with
+    # an empty string and no error of any kind. So the contract is checked here, where it can
+    # actually fail, rather than trusted where it is merely written down. Same reasoning as the
+    # green-zero guard below: the declaration and the check are different things.
+    - name: paths was actually given
+      shell: bash
+      env:
+        RPP_PATHS: ${{ inputs.paths }}
+      run: |
+        if [ -z "${RPP_PATHS// /}" ]; then
+          echo "::error::input \`paths\` is required and was empty. Name what to lint, e.g." \
+               "\`paths: papers\`. There is no default on purpose: linting the whole checkout" \
+               "by accident produces a green job over a scope nobody chose."
+          exit 1
+        fi
+
+    # texlive-extra-utils is what carries /usr/bin/texcount. Cached, because the apt fetch is the
+    # only network hop in this action and a slow mirror once cost a caller 14 minutes.
+    - name: texcount (for a CONSUMER's texcount/* rules — this package ships none)
+      if: inputs.texcount == 'true'
+      uses: awalsh128/cache-apt-pkgs-action@v1
+      with:
+        packages: texlive-extra-utils
+        version: "1.0"
+
+    # 🔴 EXIT=0 AND EMPTY OUTPUT IS NOT "CLEAN" — an installer can put nothing in place and report
+    # success. So the binary is checked for existence, not the installer's return code.
+    - name: texcount is actually on PATH
+      if: inputs.texcount == 'true'
+      shell: bash
+      run: |
+        command -v texcount >/dev/null || {
+          echo "::error::texcount is not on PATH after the install step. The texcount/* rules would" \
+               "silently fall back to a weaker word count, and this job would still be green."
+          exit 1
+        }
+        texcount -version | head -1
+
+    # ONE invocation, JSON to disk, exit code preserved and then handed to the guard. Linting twice
+    # (once for humans, once for the machine) would read the corpus twice and could disagree with
+    # itself. The guard lives in `scripts/eslint-report-guard.mjs` rather than inline here, because
+    # an inline `node -e` blob cannot be reached by a test.
+    #
+    # 🔴 THE REDIRECT IS ONLY SAFE BECAUSE `--json` KEEPS stdout CLEAN. `paperlint lint` prints the name
+    # of the config it discovered; in `--json` mode that line goes to stderr, precisely so a pipe
+    # or a redirect receives one parsable document. That was a real defect for an hour on 18-09 —
+    # the line sat on stdout in front of the array — and it was found by wiring this step up, not
+    # by a test, because the harness had been WORKING AROUND it (slicing the first line off).
+    #
+    # `--no-config-lookup` is gone with the eslint call and is not missing: the CLI builds its
+    # config with `overrideConfigFile: true`, so a consumer's nested config cannot reach the run
+    # at all. The guarantee moved from a flag into the code.
+    - name: paperlint lint
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        RPP_CONFIG: ${{ inputs.config }}
+        RPP_PATHS: ${{ inputs.paths }}
+        RPP_MAXWARN: ${{ inputs.max-warnings }}
+      run: |
+        # 🔴 `|| RC=$?` IS LOAD-BEARING, NOT STYLE. GitHub runs composite `shell: bash` as
+        # `bash --noprofile --norc -eo pipefail`, so a bare `npx paperlint lint` that exits non-zero
+        # ABORTS THE SCRIPT and the guard below never runs — measured, not reasoned: the line
+        # after a failing command did not print. That is the whole error path of this action
+        # (a bad config, an unreadable report, findings), so under `-e` the guard was reachable
+        # ONLY on success, which is the one case it was not written for.
+        RC=0
+        npx paperlint lint $RPP_PATHS ${RPP_CONFIG:+--config "$RPP_CONFIG"} \
+          --max-warnings="$RPP_MAXWARN" --json > "$RUNNER_TEMP/rpp.json" || RC=$?
+        node "$GITHUB_ACTION_PATH/scripts/eslint-report-guard.mjs" \
+          "$RUNNER_TEMP/rpp.json" "$RC" "$RPP_PATHS" "${RPP_CONFIG:-rpp.json}"

package/bin/rpp.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * SHIM. The real CLI lives in `src/*.ts` and builds to `dist/`; this file stays put and
+ * remains JavaScript deliberately.
+ *
+ * 🔴 WHY NOT MOVE `bin` TO `dist/cli.js`. This path is a PUBLIC CONTRACT, and it already has
+ * two consumers outside the package:
+ *   1. `plugin/hooks/hooks.json` calls
+ *        node "${CLAUDE_PROJECT_DIR}/node_modules/paperlint/bin/rpp.mjs" hook <name>
+ *      — the hook wiring was fixed exactly because it addressed a file the consumer did not have;
+ *      changing it the next day would be the same class of error;
+ *   2. docs/configuration.md documents `import { buildConfig } from "paperlint/bin/rpp.mjs"`.
+ * A move would cost both, and yield zero: a file name says nothing about what language it is in.
+ *
+ * 🔴 AND WHY THE FAILURE HERE IS LOUD. A consumer who installed the package from the registry
+ * has `dist/` in the tarball ready — this IS MEASURED (`npm pack --dry-run`: 16 files `dist/*`), and
+ * it is kept by the `files` allowlist in the manifest. The list is not for show: without the `files` field,
+ * npm used `.gitignore` as the exclusion list, and `dist/` in it would eject the build from the package —
+ * 376 files became 360, and the consumer got exactly this refusal. The check stays for two cases where
+ * `dist/` can genuinely be missing: a clone before `npm run build` and installing the package as a git
+ * dependency with `--ignore-scripts` (so `prepare` does not run). Without it, both would yield `ERR_MODULE_NOT_FOUND`
+ * from deep in the loader: a message about a file the consumer did not write, and no hint what to do.
+ */
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const dist = new URL("../dist/cli.js", import.meta.url);
+if (!existsSync(fileURLToPath(dist))) {
+  process.stderr.write(
+    `paperlint: not built — ${fileURLToPath(dist)} missing.\n` +
+      `The package is written in TypeScript; in the registry tarball \`dist/\` already lies built, so\n` +
+      `you reach here from a repository clone or a git dependency installed with\n` +
+      `\`--ignore-scripts\` (so the \`prepare\` step is skipped).\n` +
+      `In a clone: \`npm run build\`. For a git dependency: reinstall without \`--ignore-scripts\`.\n`,
+  );
+  process.exit(2);
+}
+export * from "../dist/cli.js";
+const { run, isMain } = await import("../dist/cli.js");
+// The question is about THIS file, not `dist/cli.js`: `bin` is the target of a symlink from
+// `node_modules/.bin`, and `isMain` can compare it to the real path. For `cli.js` itself
+// the answer is now always "no" — it is imported, not invoked.
+if (isMain(import.meta.url)) process.exit(await run(process.argv.slice(2)));

package/dist/action-ref.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function actionRef(version: string | undefined): string | null;
+//# sourceMappingURL=action-ref.d.ts.map

package/dist/action-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-ref.d.ts","sourceRoot":"","sources":["../src/action-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAIpE"}

package/dist/action-ref.js

@@ -0,0 +1,16 @@
+/**
+ * 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) {
+    return version !== undefined && /^\d+\.\d+\.\d+$/.test(version)
+        ? `v${version}`
+        : null;
+}
+//# sourceMappingURL=action-ref.js.map

package/dist/action-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-ref.js","sourceRoot":"","sources":["../src/action-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,OAA2B;IACnD,OAAO,OAAO,KAAK,SAAS,IAAI,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC;QAC7D,CAAC,CAAC,IAAI,OAAO,EAAE;QACf,CAAC,CAAC,IAAI,CAAC;AACX,CAAC"}