@geonosis/lint-parity 0.4.0 → 1.0.0

package/README.md

@@ -18,6 +18,7 @@ pnpm add -D @geonosis/lint-parity oxlint
 ```bash
 geonosis-lint-parity --a <config-a.json> --b <config-b.json> [--oxlint <path>] [--out <dir>] -- <paths…>
 geonosis-lint-parity --corpus <dir> --a <config-a.json> --b <config-b.json> [--out <dir>]
+                     [--expect-changed <rule,rule,…>]
 ```
 
 **Write both configs inside the workspace being linted** — `<ws>/.oxlintrc.parity-a.json`, deleted
@@ -63,6 +64,33 @@ import { manifestOf, MANIFEST_FILE } from '@geonosis/lint-parity'
 writeFileSync(join(corpus, MANIFEST_FILE), `${JSON.stringify(manifestOf(plugin), null, 2)}\n`)
 ```
 
+## And a release's claims, checked
+
+A changelog line that names a rule is a claim. `--expect-changed` makes it data the corpus judges:
+
+```bash
+geonosis-lint-parity --corpus node_modules/<plugin>/corpus \
+  --a oxlintrc.old.json --b oxlintrc.new.json \
+  --expect-changed some-rule,another-rule
+```
+
+It exits 1 unless the corpus shows **exactly** those rules behaving differently under the two
+configs — different reach, or a different number of findings:
+
+| verdict | means |
+| --- | --- |
+| `HELD` | claimed, and the corpus shows it changing |
+| `UNPROVEN` | claimed, and the corpus shows nothing — including a rule the corpus does not exercise |
+| `UNCLAIMED` | the corpus shows it changing and the release never said so |
+
+The report prints the claims table beside the reach table. Without the flag no claim is made and none
+is judged, which is what a corpus run has always done.
+
+Why it exists: a release once announced a behaviour widening for **ten** rules while its corpus
+carried evidence for **two**, and the parity run offered as proof went over a consumer tree that had
+no such violation in it — so every number matched. The claim is the thing to check, and the corpus is
+what checks it.
+
 ## Then parity
 
 It runs oxlint twice with `--format=unix` over the same paths, strips the working-directory prefix,

package/dist/{chunk-OLCJQ6JC.js → chunk-3PCNMLVE.js}

@@ -1,13 +1,31 @@
 // src/parity.ts
 import { spawnSync } from "child_process";
-import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync
+} from "fs";
 import { tmpdir } from "os";
-import { join } from "path";
+import { dirname, join, resolve } from "path";
 var ANSI = /\[[0-9;]*m/g;
 var SUMMARY_COUNT = /^(\d+) problems?$/m;
 var RULE_IN_LINE = /\[(?:Error|Warning)\/([^\]]+)\]$/;
 var UNIX_FINDING = /^\S[^\n]*:\d+:\d+: .*\[(?:Error|Warning)\/[^\]\n]+\]$/;
 var FINDING_PLACE = /^(\S[^\n]*?:\d+:\d+): .*\[(?:Error|Warning)\/([^\]\n]+)\]$/;
+var resolveOxlint = (from) => {
+  let dir = from;
+  for (; ; ) {
+    const bin = resolve(dir, "node_modules/.bin/oxlint");
+    if (existsSync(bin)) return bin;
+    const parent = dirname(dir);
+    if (parent === dir) return "oxlint";
+    dir = parent;
+  }
+};
 var ParityError = class extends Error {
   constructor(message) {
     super(message);
@@ -152,6 +170,27 @@ var manifestOf = (plugin) => ({
   plugin: plugin.meta.name,
   rules: Object.keys(plugin.rules).map((rule) => `${plugin.meta.name}/${rule}`).toSorted()
 });
+var namesRule = (claim, rule) => {
+  if (claim === rule) return true;
+  const at = rule.indexOf("/");
+  return at !== -1 && rule.slice(at + 1) === claim;
+};
+var claimsOver = (reach, expectChanged) => {
+  if (expectChanged === void 0) return [];
+  const claimed = (rule) => expectChanged.some((one) => namesRule(one, rule));
+  const judged = reach.filter((one) => one.changed || claimed(one.rule)).map((one) => ({
+    changed: one.changed,
+    claimed: claimed(one.rule),
+    rule: one.rule,
+    verdict: verdictOf(one.changed, claimed(one.rule))
+  }));
+  const outsideReach = expectChanged.filter((claim) => !reach.some((one) => namesRule(claim, one.rule))).map((rule) => ({ changed: false, claimed: true, rule, verdict: "unproven" }));
+  return [...judged, ...outsideReach];
+};
+var verdictOf = (changed, claimed) => {
+  if (changed && claimed) return "held";
+  return claimed ? "unproven" : "unclaimed";
+};
 var readManifest = (corpus) => {
   const path = join(corpus, MANIFEST_FILE);
   let parsed;
@@ -170,14 +209,16 @@ var corpusOf = ({
   configA,
   configB,
   corpus,
+  expectChanged,
   oxlint
 }) => {
   const manifest = readManifest(corpus);
   const exercised = new Set(manifest.rules);
   const root = mkdtempSync(join(tmpdir(), "geonosis-corpus-"));
   const here = join(root, "corpus");
-  const firedIn = (config, side) => new Set(
-    readRun(
+  const foundIn = (config, side) => {
+    const counts = /* @__PURE__ */ new Map();
+    for (const finding of readRun(
       lint({
         config,
         cwd: root,
@@ -187,29 +228,67 @@ var corpusOf = ({
       }),
       root,
       side
-    ).map(ruleIdOf)
-  );
-  let inA = /* @__PURE__ */ new Set();
-  let inB = /* @__PURE__ */ new Set();
+    )) {
+      const rule = ruleIdOf(finding);
+      counts.set(rule, (counts.get(rule) ?? 0) + 1);
+    }
+    return counts;
+  };
+  let inA = /* @__PURE__ */ new Map();
+  let inB = /* @__PURE__ */ new Map();
   try {
     cpSync(corpus, here, { recursive: true });
-    inA = firedIn(configA, "A");
-    inB = firedIn(configB, "B");
+    inA = foundIn(configA, "A");
+    inB = foundIn(configB, "B");
   } finally {
     rmSync(root, { force: true, recursive: true });
   }
   const configured = [.../* @__PURE__ */ new Set([...rulesNamedBy(configA), ...rulesNamedBy(configB)])].toSorted();
-  const reach = configured.filter((rule) => exercised.has(rule)).map((rule) => ({ firedInA: inA.has(rule), firedInB: inB.has(rule), rule }));
+  const reach = configured.filter((rule) => exercised.has(rule)).map((rule) => {
+    const foundInA = inA.get(rule) ?? 0;
+    const foundInB = inB.get(rule) ?? 0;
+    return {
+      changed: foundInA !== foundInB,
+      firedInA: foundInA > 0,
+      firedInB: foundInB > 0,
+      foundInA,
+      foundInB,
+      rule
+    };
+  });
+  const claims = claimsOver(reach, expectChanged);
   return {
+    claims,
+    claimsHeld: claims.every((one) => one.verdict === "held"),
     neither: reach.filter((one) => !one.firedInA && !one.firedInB).map((one) => one.rule),
     outside: configured.filter((rule) => !exercised.has(rule)),
     plugin: manifest.plugin,
     reach
   };
 };
+var VERDICTS = {
+  held: "HELD",
+  unclaimed: "UNCLAIMED \u2014 the corpus shows this changing and the release did not say so",
+  unproven: "UNPROVEN \u2014 claimed, and the corpus shows no change"
+};
+var claimsSection = (report) => {
+  if (report.claims.length === 0) return [];
+  return [
+    "## claims",
+    "",
+    report.claimsHeld ? "**HELD** \u2014 every rule the release claims is a rule this corpus shows changing, and no other." : "**BROKEN** \u2014 a claim this corpus does not show, or a change the release did not claim.",
+    "",
+    "| rule | claimed | observed | verdict |",
+    "|---|---|---|---|",
+    ...report.claims.map(
+      (one) => `| \`${one.rule}\` | ${one.claimed ? "changed" : "\u2014"} | ${one.changed ? "changed" : "unchanged"} | ${VERDICTS[one.verdict]} |`
+    ),
+    ""
+  ];
+};
 var formatCorpus = (report) => {
   const rows = report.reach.map(
-    (one) => `| \`${one.rule}\` | ${one.firedInA ? "yes" : "NO"} | ${one.firedInB ? "yes" : "NO"} |`
+    (one) => `| \`${one.rule}\` | ${one.firedInA ? "yes" : "NO"} (${one.foundInA}) | ${one.firedInB ? "yes" : "NO"} (${one.foundInB}) |`
   );
   const outside = report.outside.length === 0 ? "None \u2014 this corpus speaks for every rule the configs enable.\n" : `${report.outside.map((rule) => `- \`${rule}\``).join("\n")}
 `;
@@ -223,9 +302,10 @@ var formatCorpus = (report) => {
     report.neither.length === 0 ? "**PASS** \u2014 every in-scope rule has at least one corpus file that fires it." : `**FAIL** \u2014 these rules fire nowhere in the corpus, so nothing shows they reach anything:
 ${report.neither.map((rule) => `- \`${rule}\``).join("\n")}`,
     "",
+    ...claimsSection(report),
     "## per rule",
     "",
-    "| rule | fired under A | fired under B |",
+    "| rule | fired under A (findings) | fired under B (findings) |",
     "|---|---|---|",
     ...rows,
     "",
@@ -239,12 +319,14 @@ ${report.neither.map((rule) => `- \`${rule}\``).join("\n")}`,
 };
 var FLAGS = { "--a": "configA", "--b": "configB", "--out": "out", "--oxlint": "oxlint" };
 var CORPUS_FLAG = "--corpus";
+var CLAIM_FLAG = "--expect-changed";
 var parseParityArgs = (argv) => {
   const at = argv.indexOf("--");
   const flags = at === -1 ? argv : argv.slice(0, at);
   const paths = at === -1 ? [] : argv.slice(at + 1);
   const read = {};
   let corpus;
+  let expectChanged;
   for (let index = 0; index < flags.length; index += 1) {
     const flag = flags[index];
     const value = flags[index + 1];
@@ -258,6 +340,16 @@ var parseParityArgs = (argv) => {
       index += 1;
       continue;
     }
+    if (flag === CLAIM_FLAG) {
+      if (value === void 0 || value.startsWith("--")) {
+        throw new Error(
+          `geonosis-lint-parity: ${CLAIM_FLAG} needs the rules the release claims it changes, comma separated \u2014 a claim about no rules is not a claim`
+        );
+      }
+      expectChanged = value.split(",").map((one) => one.trim()).filter((one) => one !== "");
+      index += 1;
+      continue;
+    }
     const name = FLAGS[flag];
     if (name === void 0) throw new Error(`geonosis-lint-parity: unknown argument "${flag}"`);
     if (value === void 0 || value.startsWith("--")) {
@@ -275,6 +367,7 @@ var parseParityArgs = (argv) => {
     configA: read.configA,
     configB: read.configB,
     ...corpus === void 0 ? {} : { corpus },
+    ...expectChanged === void 0 ? {} : { expectChanged },
     ...read.out === void 0 ? {} : { out: read.out },
     ...read.oxlint === void 0 ? {} : { oxlint: read.oxlint },
     paths: paths.length === 0 ? ["."] : paths
@@ -322,6 +415,7 @@ var parityOf = ({
 };
 
 export {
+  resolveOxlint,
   ParityError,
   normaliseFindings,
   readRun,

package/dist/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * The consumer's own oxlint, walking up from a directory, not one `npx` might fetch: a run under a
+ * different binary from the one the repo gates with compares two things nobody ships. Exported
+ * because every tool that spawns oxlint has to answer this, and a second copy of the answer is a
+ * second answer.
+ */
+declare const resolveOxlint: (from: string) => string;
 /** A run that could not be read. Never a number — 0 findings against 0 findings is a PASS. */
 declare class ParityError extends Error {
     constructor(message: string);
@@ -50,11 +57,34 @@ declare const compareFindings: ({ a, b }: {
 }) => Parity;
 declare const formatSummary: (parity: Parity) => string;
 type RuleReach = {
+    /**
+     * The corpus saw this rule behave differently under the two configs — it started firing, stopped
+     * firing, or fired a different number of times. What a release CLAIMS about a rule is checked
+     * against this, and nothing else.
+     */
+    changed: boolean;
     firedInA: boolean;
     firedInB: boolean;
+    /** How many findings each side made, so a rule that gained a case is a change and not a shrug. */
+    foundInA: number;
+    foundInB: number;
+    rule: string;
+};
+/**
+ * One line of a release's claim, judged. `held` — claimed and shown; `unproven` — claimed and the
+ * corpus shows nothing; `unclaimed` — the corpus shows a change nobody named.
+ */
+type CorpusClaim = {
+    changed: boolean;
+    claimed: boolean;
     rule: string;
+    verdict: 'held' | 'unclaimed' | 'unproven';
 };
 type CorpusReport = {
+    /** Empty when the run claimed nothing — a corpus run without a claim judges no claim. */
+    claims: CorpusClaim[];
+    /** False as soon as one claim is unproven or one change went unclaimed. */
+    claimsHeld: boolean;
     /** Rules no file in the corpus fires under either config — rules shipping with no evidence. */
     neither: string[];
     /**
@@ -105,10 +135,15 @@ declare const readManifest: (corpus: string) => CorpusManifest;
  * consumer inherits every one of those as a claim it cannot check. The corpus is the evidence, and
  * `neither` is the list that has to stay empty.
  */
-declare const corpusOf: ({ configA, configB, corpus, oxlint, }: {
+declare const corpusOf: ({ configA, configB, corpus, expectChanged, oxlint, }: {
     configA: string;
     configB: string;
     corpus: string;
+    /**
+     * The rules a release SAYS it changes. Absent means no claim, and no claim is judged; present
+     * means the corpus must show exactly these rules changing and no others.
+     */
+    expectChanged?: string[];
     oxlint: string;
 }) => CorpusReport;
 declare const formatCorpus: (report: CorpusReport) => string;
@@ -121,6 +156,11 @@ type ParityArgs = {
      * default would weld this tool to whichever plugin happened to be beside it.
      */
     corpus?: string;
+    /**
+     * The rules a release claims it changes. Absent means the run claims nothing and judges nothing;
+     * an empty list is not expressible, because a claim about no rules is not a claim.
+     */
+    expectChanged?: string[];
     out?: string;
     oxlint?: string;
     paths: string[];
@@ -135,4 +175,4 @@ declare const parityOf: ({ configA, configB, cwd, out, oxlint, paths, }: {
     paths: string[];
 }) => Parity;
 
-export { type CorpusManifest, type CorpusReport, MANIFEST_FILE, type MessageChange, type Parity, type ParityArgs, ParityError, type RuleReach, type RuleTally, compareFindings, corpusOf, formatCorpus, formatSummary, manifestOf, normaliseFindings, parityOf, parseParityArgs, readManifest, readRun, ruleIdOf, rulesNamedBy };
+export { type CorpusClaim, type CorpusManifest, type CorpusReport, MANIFEST_FILE, type MessageChange, type Parity, type ParityArgs, ParityError, type RuleReach, type RuleTally, compareFindings, corpusOf, formatCorpus, formatSummary, manifestOf, normaliseFindings, parityOf, parseParityArgs, readManifest, readRun, resolveOxlint, ruleIdOf, rulesNamedBy };

package/dist/index.js

@@ -11,9 +11,10 @@ import {
   parseParityArgs,
   readManifest,
   readRun,
+  resolveOxlint,
   ruleIdOf,
   rulesNamedBy
-} from "./chunk-OLCJQ6JC.js";
+} from "./chunk-3PCNMLVE.js";
 export {
   MANIFEST_FILE,
   ParityError,
@@ -27,6 +28,7 @@ export {
   parseParityArgs,
   readManifest,
   readRun,
+  resolveOxlint,
   ruleIdOf,
   rulesNamedBy
 };

package/dist/parity-cli.js

@@ -3,14 +3,16 @@ import {
   formatCorpus,
   formatSummary,
   parityOf,
-  parseParityArgs
-} from "./chunk-OLCJQ6JC.js";
+  parseParityArgs,
+  resolveOxlint
+} from "./chunk-3PCNMLVE.js";
 
 // src/parity-cli.ts
-import { existsSync, mkdirSync, writeFileSync } from "fs";
-import { dirname, join, resolve } from "path";
+import { mkdirSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
 var USAGE = `geonosis-lint-parity --a <config-a.json> --b <config-b.json> [--oxlint <path>] [--out <dir>] -- <paths\u2026>
 geonosis-lint-parity --corpus <dir> --a <config-a.json> --b <config-b.json> [--out <dir>]
+                     [--expect-changed <rule,rule,\u2026>]
 
 Runs oxlint twice over the same paths under two configs and diffs the findings. Exits 1 when a
 finding config A reported is missing under config B \u2014 a rule that fired before and fires nowhere
@@ -23,20 +25,16 @@ is required: this tool ships no corpus, because a corpus is one plugin's evidenc
 one a plugin ships, e.g. node_modules/<plugin>/corpus. A corpus names the rules it speaks for in
 its own manifest.json, and rules outside that list are reported unjudged.
 
+--expect-changed names the rules a release CLAIMS it changes, and exits 1 unless the corpus shows
+exactly those rules behaving differently under the two configs \u2014 no claim the corpus is silent
+about, no change the release never mentioned. Run it for every changelog line that names a rule: a
+release once claimed a widening for ten rules with corpus evidence for two, and the parity run that
+"proved" it went over a tree with no such violation in it.
+
 oxlint resolves a jsPlugins specifier relative to the CONFIG FILE's directory, not the working
 directory. Write both configs INSIDE the workspace being linted, or name the plugin by absolute
 path \u2014 a config in a temp dir cannot find a plugin installed in the workspace, and the run is
 refused rather than counted as zero findings.`;
-var resolveOxlint = (from) => {
-  let dir = from;
-  for (; ; ) {
-    const bin = resolve(dir, "node_modules/.bin/oxlint");
-    if (existsSync(bin)) return bin;
-    const parent = dirname(dir);
-    if (parent === dir) return "oxlint";
-    dir = parent;
-  }
-};
 var main = () => {
   const argv = process.argv.slice(2);
   if (argv.includes("--help") || argv.includes("-h") || argv.length === 0) {
@@ -51,7 +49,13 @@ var main = () => {
   const oxlint = args.oxlint ?? resolveOxlint(cwd);
   if (args.corpus !== void 0) {
     const corpus = resolve(cwd, args.corpus);
-    const report = corpusOf({ configA, configB, corpus, oxlint });
+    const report = corpusOf({
+      configA,
+      configB,
+      corpus,
+      ...args.expectChanged === void 0 ? {} : { expectChanged: args.expectChanged },
+      oxlint
+    });
     const text = formatCorpus(report);
     process.stdout.write(`${text}
 `);
@@ -60,7 +64,7 @@ var main = () => {
       mkdirSync(out, { recursive: true });
       writeFileSync(join(out, "CORPUS.md"), text);
     }
-    return report.neither.length > 0 ? 1 : 0;
+    return report.neither.length > 0 || !report.claimsHeld ? 1 : 0;
   }
   const parity = parityOf({
     configA,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/lint-parity",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "description": "Findings parity and rule reach over any two oxlint configs — the diff a fork is deleted on.",
   "keywords": [
     "oxlint",