@geonosis/ratchet 0.1.0 → 0.1.2

package/README.md

@@ -54,7 +54,52 @@ code, and its baseline survives a rewrite another counter earned: printing OK fo
 took is how a red main goes unnoticed for three commits.
 
 A counter whose command cannot run is a hard error, never a silent zero. A gate that cannot measure
-has not passed.
+has not passed. Nor is a number believed on its own: `oxlintErrors` reads the finding lines AND the
+summary oxlint printed, and raises when they disagree.
+
+### The warnings-only window, and `expectFormat`
+
+The last-resort backstop under the oxlint counters — output in no shape we know *and* a non-zero
+exit means the format moved, so refuse — has one gap, and it is worth naming rather than pretending
+otherwise. **oxlint exits 0 when a run found only warnings.** On such a run the backstop cannot
+fire: an unrecognised format reads as zero warnings, and a zero that only shrinks is a zero the
+ratchet banks by rewriting the baseline down.
+
+`--deny-warnings` is **not** the fix. It makes warnings exit non-zero by making them errors, which
+moves every warning into `oxlintErrors` and changes what both numbers mean — a bigger lie than the
+one it patches, told to the whole baseline.
+
+The fix is to say which shape you asked for:
+
+```jsonc
+{ "counter": "oxlintWarnings", "command": "npx oxlint --format=unix .", "expectFormat": "unix" }
+```
+
+With `expectFormat` set, output that matches none of the three shapes and is not empty once npm's
+own chatter is stripped (`> …` script echoes, `npm warn …`, `npm notice …` update nags, blank
+lines) is refused **even on a clean exit**. `npm ERR!` is not stripped — that is npm saying the
+command never ran, and it must never read as zero. Unset is the default and changes nothing, so a repo that never opts in keeps exactly
+the behaviour it had. Valid values: `unix`, `agent`, `default`.
+
+When a number **grew**, the last ten lines of that counter's command output print under the
+`<-- REGRESSED` line, indented — so the report says what grew, not only that something did. A
+counter that reads a file rather than running a command (`lawLineCount`) prints nothing extra.
+
+## Running it where it will actually run
+
+- **Counters run in the caller's environment.** They inherit the shell the ratchet was started in,
+  nothing more. If a child command needs `NODE_OPTIONS` — a TypeScript shim, a loader — put it on
+  the script that invokes `geonosis-ratchet`, not on the counter's own line, and not only in your
+  interactive shell.
+- **A `typecheckErrors` counter needs the same precondition CI gives it: build the workspace
+  packages first.** In a fresh worktree the `dist/*.d.ts` files do not exist yet, and `tsc` reports
+  a false +N of missing-module errors that has nothing to do with the change under test. `pnpm build
+  && geonosis-ratchet` is the shape; a bare `geonosis-ratchet` in a clean checkout is not.
+- **A release-age cooldown will refuse a package published minutes ago.** If pnpm's
+  `minimumReleaseAge` blocks `@geonosis/*`, exclude the scope for that project — pnpm writes
+  `minimumReleaseAgeExclude` into `pnpm-workspace.yaml` — rather than lowering the cooldown. The
+  cooldown is protecting every other dependency in the tree; the exclusion is scoped to the one you
+  chose to trust.
 
 ## Counters
 
@@ -62,8 +107,8 @@ Every counter takes its `command` from the config, so the toolchain stays the re
 
 | id | counts | params |
 | --- | --- | --- |
-| `oxlintErrors` / `oxlintWarnings` | `: error ` / `: warning ` lines | `command` |
-| `oxlintRule` | one named rule's findings; with `config`, after forcing it to `error` in a temp copy, so debt cannot grow behind a downgrade | `rule`, `config`, `command` |
+| `oxlintErrors` / `oxlintWarnings` | findings under any shape oxlint prints — `--format=unix`, the compact `agent` format, the graphical `default` — cross-checked against the tool's own summary | `command`, `expectFormat` |
+| `oxlintRule` | one named rule's findings, counted only on lines the run reported as findings and refused when none of them attributes itself readably; with `config`, after forcing the rule to `error` in a temp copy — `"warn"`, `"off"` and the `["off", { … }]` array form alike — so debt cannot grow behind a downgrade | `rule`, `config`, `command`, `expectFormat` |
 | `typecheckErrors` | `error TS` occurrences | `command` |
 | `testFailures` | the runner's own failure summary; throws when neither a pass nor a fail count is readable | `command` |
 | `unformattedFiles` | paths `--list-different` names that exist on disk | `command` |

package/dist/{chunk-VX2PL7QG.js → chunk-BTWIR7DK.js}

@@ -108,19 +108,101 @@ var lawLineCount = {
 import { existsSync as existsSync3, readFileSync as readFileSync2, rmSync, writeFileSync } from "fs";
 import { resolve as resolve3 } from "path";
 var DEFAULT_COMMAND = "npx oxlint --format=unix --config .oxlintrc.json .";
+var UNIX_FINDING = /^\S[^\n]*:\d+:\d+: .*\[(Error|Warning)\/[^\]\n]+\]$/gm;
+var UNIX_SUMMARY = /^(\d+) problems?$/m;
+var AGENT_FINDING = /^\S[^\n]*:\d+:\d+: (error|warning) /gm;
+var DEFAULT_SUMMARY = /^Found (\d+) warnings? and (\d+) errors?\.$/m;
+var DEFAULT_FINDING = /^\s*[x!] [^\s(]+\([^)\n]+\): /m;
+var FINDING_SHAPES = [UNIX_FINDING, AGENT_FINDING, DEFAULT_FINDING].map(
+  (shape) => new RegExp(shape.source)
+);
+var RULE_TOKEN = /\([^()\n]+\)/;
+var findingLinesOf = (output) => output.split("\n").filter((line) => FINDING_SHAPES.some((shape) => shape.test(line)));
+var FORMATS = ["agent", "default", "unix"];
+var isFormat = (value) => typeof value === "string" && FORMATS.some((one) => one === value);
+var expectedFormat = (counter, params) => {
+  const value = params.expectFormat;
+  if (value === void 0) return void 0;
+  if (isFormat(value)) return value;
+  throw new CounterError(
+    counter,
+    `expectFormat must be one of ${FORMATS.join(", ")} \u2014 got ${JSON.stringify(value)}`
+  );
+};
+var NOISE = /^(> .*|npm warn .*|npm notice.*|\s*)$/;
+var spokenByTheTool = (output) => output.split("\n").filter((line) => !NOISE.test(line)).join("\n");
+var total = (reading) => reading.errors + reading.warnings;
+var countFindings = (output, pattern, errorToken) => {
+  let errors = 0;
+  let warnings = 0;
+  for (const match of output.matchAll(new RegExp(pattern.source, pattern.flags))) {
+    if (match[1] === errorToken) errors += 1;
+    else warnings += 1;
+  }
+  return { errors, warnings };
+};
+var readFindings = (counter, { code, output }, expect) => {
+  const unix = countFindings(output, UNIX_FINDING, "Error");
+  const agent = countFindings(output, AGENT_FINDING, "error");
+  const problems = UNIX_SUMMARY.exec(output);
+  const found = DEFAULT_SUMMARY.exec(output);
+  const refuse = (why) => {
+    throw new CounterError(counter, `${why} \u2014 oxlint's output changed:
+${output.trim()}`);
+  };
+  if (total(unix) > 0 || problems !== null) {
+    if (problems?.[1] === void 0) return refuse('unix findings with no "N problems" summary');
+    if (Number(problems[1]) !== total(unix)) {
+      return refuse(`the summary says ${problems[1]} problems, the lines say ${total(unix)}`);
+    }
+    return unix;
+  }
+  if (found?.[1] !== void 0 && found[2] !== void 0) {
+    const summary = { errors: Number(found[2]), warnings: Number(found[1]) };
+    if (total(agent) > 0 && (agent.errors !== summary.errors || agent.warnings !== summary.warnings)) {
+      return refuse(
+        `the summary says ${summary.errors} errors and ${summary.warnings} warnings, the lines say ${agent.errors} and ${agent.warnings}`
+      );
+    }
+    return summary;
+  }
+  if (total(agent) > 0) return agent;
+  if (code === 0) {
+    if (expect !== void 0 && spokenByTheTool(output) !== "") {
+      return refuse(`asked for --format=${expect} and got output in no shape this counter reads`);
+    }
+    return { errors: 0, warnings: 0 };
+  }
+  return refuse(`the tool exited ${code} and printed no findings and no summary`);
+};
 var oxlintErrors = {
   id: "oxlintErrors",
   run: async ({ params, run }) => {
     const command = stringParam("oxlintErrors", params, "command", DEFAULT_COMMAND);
-    return countMatches(run(command).output, /: error /);
+    const expect = expectedFormat("oxlintErrors", params);
+    return readFindings("oxlintErrors", run(command), expect).errors;
   }
 };
 var oxlintWarnings = {
   id: "oxlintWarnings",
   run: async ({ params, run }) => {
     const command = stringParam("oxlintWarnings", params, "command", DEFAULT_COMMAND);
-    return countMatches(run(command).output, /: warning /);
+    const expect = expectedFormat("oxlintWarnings", params);
+    return readFindings("oxlintWarnings", run(command), expect).warnings;
+  }
+};
+var countRule = (result, rule, expect) => {
+  const reading = readFindings("oxlintRule", result, expect);
+  const lines = findingLinesOf(result.output);
+  if (total(reading) > 0 && !lines.some((line) => RULE_TOKEN.test(line))) {
+    throw new CounterError(
+      "oxlintRule",
+      `${total(reading)} findings, not one of them attributed to a "plugin(rule)" this counter can read \u2014 oxlint's output changed:
+${result.output.trim()}`
+    );
   }
+  const named = new RegExp(`\\(${escapeForRegex(rule)}\\)`);
+  return lines.filter((line) => named.test(line)).length;
 };
 var oxlintRule = {
   id: "oxlintRule",
@@ -128,19 +210,18 @@ var oxlintRule = {
     const rule = stringParam("oxlintRule", params, "rule");
     const command = stringParam("oxlintRule", params, "command", DEFAULT_COMMAND);
     const config = typeof params.config === "string" ? params.config : "";
-    if (config === "")
-      return countMatches(run(command).output, new RegExp(`\\(${escapeForRegex(rule)}\\)`));
+    const expect = expectedFormat("oxlintRule", params);
+    if (config === "") return countRule(run(command), rule, expect);
     const source = resolve3(cwd, config);
     if (!existsSync3(source)) throw new CounterError("oxlintRule", `no config at ${config}`);
     const strictName = `.oxlintrc.ratchet-${key}.json`;
     const strict = readFileSync2(source, "utf8").replace(
-      new RegExp(`("[^"]*${escapeForRegex(rule)}"\\s*:\\s*)"(warn|off)"`),
+      new RegExp(`("[^"]*${escapeForRegex(rule)}"\\s*:\\s*\\[?\\s*)"(warn|off)"`),
       '$1"error"'
     );
     writeFileSync(resolve3(cwd, strictName), strict);
     try {
-      const output = run(command.replace("{config}", strictName)).output;
-      return countMatches(output, new RegExp(`\\(${escapeForRegex(rule)}\\)`));
+      return countRule(run(command.replace("{config}", strictName)), rule, expect);
     } finally {
       rmSync(resolve3(cwd, strictName), { force: true });
     }
@@ -298,6 +379,18 @@ ${output.trim()}`
 // src/ratchet.ts
 import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
 import { resolve as resolve5 } from "path";
+var EVIDENCE_LINES = 10;
+var recorded = (run) => {
+  let output = "";
+  return {
+    last: () => output.split("\n").map((line) => line.trimEnd()).filter((line) => line !== "").slice(-EVIDENCE_LINES),
+    run: (command) => {
+      const result = run(command);
+      output = result.output;
+      return result;
+    }
+  };
+};
 var verdictOf = (now, baseline) => {
   if (now > baseline) return "grew";
   if (now < baseline) return "shrank";
@@ -335,13 +428,16 @@ var runRatchet = async ({
         `${config.baseline} has no number for "${key}" \u2014 add it before enabling the counter`
       );
     }
-    const now = await counter.run({
-      cwd,
+    const recorder = recorded(runCommand(cwd, entry.counter));
+    const now = await counter.run({ cwd, key, params: entry, run: recorder.run });
+    const verdict = verdictOf(now, limit);
+    measurements.push({
+      baseline: limit,
+      evidence: verdict === "grew" ? recorder.last() : [],
       key,
-      params: entry,
-      run: runCommand(cwd, entry.counter)
+      now,
+      verdict
     });
-    measurements.push({ baseline: limit, key, now, verdict: verdictOf(now, limit) });
   }
   const grew = measurements.some((one) => one.verdict === "grew");
   const shrank = measurements.some((one) => one.verdict === "shrank");
@@ -363,7 +459,10 @@ var formatReport = ({ measurements, rewritten }) => {
       return `  SKIP ${one.key}: not measured by --tier ${one.tier}`;
     }
     const head = `  ${one.key.padEnd(WIDTH)} ${String(one.now).padStart(5)}  (baseline ${one.baseline})`;
-    if (one.verdict === "grew") return `${head}  <-- REGRESSED +${one.now - one.baseline}`;
+    if (one.verdict === "grew") {
+      const regressed = `${head}  <-- REGRESSED +${one.now - one.baseline}`;
+      return [regressed, ...one.evidence.map((line) => `      ${line}`)].join("\n");
+    }
     if (one.verdict === "shrank") return `${head}  <-- improved -${one.baseline - one.now}`;
     return head;
   });

package/dist/cli.js

@@ -2,7 +2,7 @@ import {
   COUNTERS,
   formatReport,
   runRatchet
-} from "./chunk-VX2PL7QG.js";
+} from "./chunk-BTWIR7DK.js";
 
 // src/cli.ts
 var cwdFlag = process.argv.indexOf("--cwd");

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   loadConfig,
   runCommand,
   runRatchet
-} from "./chunk-VX2PL7QG.js";
+} from "./chunk-BTWIR7DK.js";
 export {
   CONFIG_FILE,
   COUNTERS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/ratchet",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Debt as a number that may only shrink — one ratchet, pluggable counters.",
   "keywords": [
     "ratchet",
@@ -21,7 +21,7 @@
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "geonosis-ratchet": "./bin/geonosis-ratchet.mjs"
+    "geonosis-ratchet": "bin/geonosis-ratchet.mjs"
   },
   "exports": {
     ".": "./dist/index.js"
@@ -30,14 +30,14 @@
     "bin",
     "dist"
   ],
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit"
-  },
   "engines": {
     "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
   }
-}
+}