@geonosis/lint-parity 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,118 @@
+# @geonosis/lint-parity
+
+A repo does not delete its vendored copy of a lint plugin because the version numbers match. It
+deletes it when the **findings** match: same tree, same rule ids, two configs, and a diff.
+`geonosis-lint-parity` is that diff — and, before it, the answer to whether either config's rules
+reach anything at all.
+
+It knows no rule names and no plugin. Two oxlint configs and a tree are the whole input; a corpus,
+when there is one, arrives as a directory whose own `manifest.json` says which rules it can speak
+for. So it checks any plugin's adoption, including plugins it was never shipped beside.
+
+## Install
+
+```bash
+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>]
+```
+
+**Write both configs inside the workspace being linted** — `<ws>/.oxlintrc.parity-a.json`, deleted
+afterwards — or name the plugin by absolute path in `jsPlugins`. oxlint resolves a `jsPlugins`
+specifier relative to the **config file's** directory, not the working directory, so a config
+written to a temp dir cannot find a plugin installed in the workspace: it fails with
+`Cannot find module '@…/plugin'`, and the tool correctly refuses with
+`config A: oxlint exited 1 without reporting a single finding`.
+
+`--oxlint` overrides the binary; by default it walks up from the working directory for
+`node_modules/.bin/oxlint`, so the comparison runs under the consumer's own linter rather than one
+`npx` might fetch.
+
+## Step 0 — reach, before parity
+
+Parity between two configs that both do nothing is perfect parity. In one repo 34 of 51 configured
+rules fired nowhere in any corpus it had: 34 rules a consumer would inherit as claims nothing could
+check. `--corpus` answers that directly.
+
+```bash
+geonosis-lint-parity \
+  --corpus node_modules/@geonosis/oxlint-plugin-biological-architecture/corpus \
+  --a oxlintrc.fork.json --b oxlintrc.published.json --out proofs/reach
+```
+
+Both configs run over the corpus — copied to a temp root first, so neither a `.gitignore` nor
+oxlint's `node_modules` skip can quietly turn "every rule fired nowhere" into the answer. It prints
+a fired-under-A / fired-under-B row per in-scope rule and **exits 1 when one fires under neither**.
+`--out` writes `CORPUS.md`.
+
+**The directory is required.** This package ships no corpus, because a corpus is one plugin's
+evidence: one deliberately broken file per rule, and a `manifest.json` naming the rules it therefore
+speaks for. A rule the manifest does not name — another plugin's, one of oxlint's built-ins — is
+listed under **outside this corpus** and gets no verdict. Judging those would fail every real config
+for saying nothing.
+
+A plugin generates its manifest from its own rules export, so a rule cannot be added and forgotten
+in the list of what the corpus is evidence about:
+
+```ts
+import { manifestOf, MANIFEST_FILE } from '@geonosis/lint-parity'
+
+writeFileSync(join(corpus, MANIFEST_FILE), `${JSON.stringify(manifestOf(plugin), null, 2)}\n`)
+```
+
+## Then parity
+
+It runs oxlint twice with `--format=unix` over the same paths, strips the working-directory prefix,
+sorts, and prints the two counts, `only in A`, `only in B` and a per-rule tally. **It exits 1 when
+`only in A` is non-empty** — a finding the old config caught and the new one does not. New findings
+are what an upgrade is for; lost ones stop the adoption. `--out` writes `a.txt`, `b.txt`,
+`only-in-a.txt`, `only-in-b.txt`, `changed.txt` and `SUMMARY.md` for the proof file.
+
+**A finding is identified by where it is and which rule found it — `path:line:col` plus
+`plugin(rule)`.** The message is not part of it, and neither is the severity. A release that only
+rewords a rule's message would otherwise show as one finding lost and one gained, and stop an
+adoption over a sentence. Those pair up instead under **changed**, reported in full and never
+reaching the exit code; a severity change lands there too, because that is a fact about the config
+rather than a rule that stopped firing.
+
+**A run it cannot read is an error, never a number.** oxlint exits 1 both when it reported findings
+and when it never linted a file at all — a rule name it does not know, options a rule has no schema
+for, a plugin it could not load. All three print a paragraph and no findings, and "0 findings" on
+one side reads as agreement with the other. A summary counting findings no line accounts for, or a
+non-zero exit with nothing readable on it, stops the run.
+
+**Fork vs published**, before deleting a vendored copy — two configs identical but for `jsPlugins`:
+
+```bash
+geonosis-lint-parity \
+  --a oxlintrc.fork.json --b oxlintrc.published.json \
+  --out proofs/adoption-parity \
+  -- apps packages
+```
+
+**Version vs version**, as a release check — the same config, pointing first at the installed
+version and then at a local build, by absolute path:
+
+```bash
+geonosis-lint-parity \
+  --a oxlintrc.old.json --b oxlintrc.new.json \
+  --out proofs/parity-old-vs-new \
+  -- apps packages
+```
+
+## Programmatic use
+
+```ts
+import { compareFindings, corpusOf, normaliseFindings, parityOf, readRun } from '@geonosis/lint-parity'
+
+const parity = parityOf({ configA, configB, cwd, oxlint, paths: ['apps', 'packages'] })
+process.exit(parity.lost ? 1 : 0)
+```
+
+`parityOf` and `corpusOf` spawn the binary; `normaliseFindings`, `readRun` and `compareFindings` are
+pure and take output a run already produced.
+
+Apache-2.0.

package/bin/geonosis-lint-parity.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Committed, so `pnpm install` can link the bin on a fresh clone — before `pnpm build` has
+// produced dist/. A bin that only exists after a build is a bin that is missing when you need it.
+import '../dist/parity-cli.js'

package/dist/chunk-OLCJQ6JC.js

@@ -0,0 +1,339 @@
+// src/parity.ts
+import { spawnSync } from "child_process";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } 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 ParityError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ParityError";
+  }
+};
+var normaliseFindings = (output, cwd) => output.replaceAll(ANSI, "").split("\n").map((line) => line.trim().replace(`${cwd}/`, "").replace(/^\.\//, "")).filter((line) => UNIX_FINDING.test(line)).toSorted();
+var readRun = ({ code, output }, cwd, side) => {
+  const findings = normaliseFindings(output, cwd);
+  const summary = SUMMARY_COUNT.exec(output);
+  const refuse = (why) => {
+    throw new ParityError(`config ${side}: ${why}
+${output.trim()}`);
+  };
+  if (summary?.[1] !== void 0 && Number(summary[1]) !== findings.length) {
+    return refuse(`oxlint says ${summary[1]} problems, ${findings.length} lines parsed as findings`);
+  }
+  if (findings.length === 0 && code !== 0) {
+    return refuse(`oxlint exited ${code} without reporting a single finding`);
+  }
+  return findings;
+};
+var UNATTRIBUTED = "(unattributed)";
+var ruleOf = (line) => RULE_IN_LINE.exec(line)?.[1] ?? UNATTRIBUTED;
+var asFile = (lines) => lines.length === 0 ? "" : `${lines.join("\n")}
+`;
+var changedLines = (changes) => changes.flatMap((one) => [`- A: ${one.a}`, `+ B: ${one.b}`]);
+var countByRule = (lines) => {
+  const counts = /* @__PURE__ */ new Map();
+  for (const line of lines) counts.set(ruleOf(line), (counts.get(ruleOf(line)) ?? 0) + 1);
+  return counts;
+};
+var missingFrom = (lines, other) => {
+  const remaining = /* @__PURE__ */ new Map();
+  for (const line of other) remaining.set(line, (remaining.get(line) ?? 0) + 1);
+  return lines.filter((line) => {
+    const left = remaining.get(line) ?? 0;
+    if (left === 0) return true;
+    remaining.set(line, left - 1);
+    return false;
+  });
+};
+var identityOf = (line) => {
+  const found = FINDING_PLACE.exec(line);
+  return found === null ? line : `${found[1]} [${found[2]}]`;
+};
+var byIdentity = (lines) => {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const line of lines) {
+    const identity = identityOf(line);
+    grouped.set(identity, [...grouped.get(identity) ?? [], line]);
+  }
+  return grouped;
+};
+var compareFindings = ({ a, b }) => {
+  const inA = countByRule(a);
+  const inB = countByRule(b);
+  const groupedA = byIdentity(a);
+  const groupedB = byIdentity(b);
+  const onlyInA = [];
+  const onlyInB = [];
+  const messageChanged = [];
+  for (const identity of [.../* @__PURE__ */ new Set([...groupedA.keys(), ...groupedB.keys()])].toSorted()) {
+    const here = groupedA.get(identity) ?? [];
+    const there = groupedB.get(identity) ?? [];
+    const leftA = missingFrom(here, there);
+    const leftB = missingFrom(there, here);
+    for (const [index, line] of leftA.entries()) {
+      const other = leftB[index];
+      if (other === void 0) onlyInA.push(line);
+      else messageChanged.push({ a: line, b: other });
+    }
+    onlyInB.push(...leftB.slice(leftA.length));
+  }
+  return {
+    a,
+    b,
+    lost: onlyInA.length > 0,
+    messageChanged,
+    onlyInA,
+    onlyInB,
+    tally: [.../* @__PURE__ */ new Set([...inA.keys(), ...inB.keys()])].toSorted().map((rule) => ({
+      a: inA.get(rule) ?? 0,
+      b: inB.get(rule) ?? 0,
+      rule
+    }))
+  };
+};
+var formatSummary = (parity) => {
+  const rows = parity.tally.map(
+    (one) => `| \`${one.rule}\` | ${one.a} | ${one.b} | ${one.b - one.a >= 0 ? "+" : ""}${one.b - one.a} |`
+  );
+  const lost = parity.onlyInA.length === 0 ? "None. Every finding A reported, B reported too.\n" : `${parity.onlyInA.map((line) => `- \`${line}\``).join("\n")}
+`;
+  const gained = parity.onlyInB.length === 0 ? "None.\n" : `${parity.onlyInB.map((line) => `- \`${line}\``).join("\n")}
+`;
+  const changed = parity.messageChanged.length === 0 ? "None. Every finding both runs made is worded and graded the same.\n" : `${changedLines(parity.messageChanged).map((line) => `- \`${line}\``).join("\n")}
+`;
+  return [
+    "# findings parity",
+    "",
+    `- findings A: **${parity.a.length}**`,
+    `- findings B: **${parity.b.length}**`,
+    `- only in A (lost): **${parity.onlyInA.length}**`,
+    `- only in B (gained): **${parity.onlyInB.length}**`,
+    `- same finding, changed message or severity: **${parity.messageChanged.length}**`,
+    "",
+    `**${parity.lost ? "FAIL" : "PASS"}** \u2014 ${parity.lost ? "B lost findings A reported. A rule that fired under A and fires nowhere under B stops the adoption." : "B reported everything A did."}`,
+    "",
+    "## per rule",
+    "",
+    "| rule | A | B | delta |",
+    "|---|---:|---:|---:|",
+    ...rows,
+    "",
+    "## only in A (lost)",
+    "",
+    lost,
+    "## only in B (gained)",
+    "",
+    gained,
+    "## changed (same place, same rule, different message or severity)",
+    "",
+    "Reported, never counted against B: a reworded message is the same finding, and a rule graded",
+    "differently is a fact about the config. Neither reaches the exit code.",
+    "",
+    changed
+  ].join("\n");
+};
+var rulesNamedBy = (config) => {
+  const parsed = JSON.parse(readFileSync(config, "utf8"));
+  return Object.keys(parsed.rules ?? {});
+};
+var ruleIdOf = (line) => {
+  const token = RULE_IN_LINE.exec(line)?.[1];
+  if (token === void 0) return UNATTRIBUTED;
+  const at = token.indexOf("(");
+  return at === -1 ? token : `${token.slice(0, at)}/${token.slice(at + 1, -1)}`;
+};
+var MANIFEST_FILE = "manifest.json";
+var manifestOf = (plugin) => ({
+  plugin: plugin.meta.name,
+  rules: Object.keys(plugin.rules).map((rule) => `${plugin.meta.name}/${rule}`).toSorted()
+});
+var readManifest = (corpus) => {
+  const path = join(corpus, MANIFEST_FILE);
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new ParityError(`could not read ${path}: ${error.message}`);
+  }
+  const manifest = parsed;
+  if (typeof manifest.plugin !== "string" || !Array.isArray(manifest.rules)) {
+    throw new ParityError(`${path} names no plugin and no rules \u2014 it cannot scope a reach run`);
+  }
+  return { plugin: manifest.plugin, rules: manifest.rules };
+};
+var corpusOf = ({
+  configA,
+  configB,
+  corpus,
+  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(
+      lint({
+        config,
+        cwd: root,
+        extra: ["--no-ignore", "--disable-nested-config"],
+        oxlint,
+        paths: [here]
+      }),
+      root,
+      side
+    ).map(ruleIdOf)
+  );
+  let inA = /* @__PURE__ */ new Set();
+  let inB = /* @__PURE__ */ new Set();
+  try {
+    cpSync(corpus, here, { recursive: true });
+    inA = firedIn(configA, "A");
+    inB = firedIn(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 }));
+  return {
+    neither: reach.filter((one) => !one.firedInA && !one.firedInB).map((one) => one.rule),
+    outside: configured.filter((rule) => !exercised.has(rule)),
+    plugin: manifest.plugin,
+    reach
+  };
+};
+var formatCorpus = (report) => {
+  const rows = report.reach.map(
+    (one) => `| \`${one.rule}\` | ${one.firedInA ? "yes" : "NO"} | ${one.firedInB ? "yes" : "NO"} |`
+  );
+  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")}
+`;
+  return [
+    "# corpus reach",
+    "",
+    `- rules in scope of this corpus: **${report.reach.length}**`,
+    `- fired under neither config: **${report.neither.length}**`,
+    `- outside this corpus: **${report.outside.length}**`,
+    "",
+    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")}`,
+    "",
+    "## per rule",
+    "",
+    "| rule | fired under A | fired under B |",
+    "|---|---|---|",
+    ...rows,
+    "",
+    "## outside this corpus",
+    "",
+    `Configured rules this corpus never claimed to exercise. It speaks for \`${report.plugin}\` only,`,
+    "so it is no evidence either way about these and passes no verdict on them.",
+    "",
+    outside
+  ].join("\n");
+};
+var FLAGS = { "--a": "configA", "--b": "configB", "--out": "out", "--oxlint": "oxlint" };
+var CORPUS_FLAG = "--corpus";
+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;
+  for (let index = 0; index < flags.length; index += 1) {
+    const flag = flags[index];
+    const value = flags[index + 1];
+    if (flag === CORPUS_FLAG) {
+      if (value === void 0 || value.startsWith("--")) {
+        throw new Error(
+          `geonosis-lint-parity: ${CORPUS_FLAG} needs a directory \u2014 this tool ships no corpus of its own, so name the one a plugin ships`
+        );
+      }
+      corpus = value;
+      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("--")) {
+      throw new Error(`geonosis-lint-parity: ${flag} needs a value`);
+    }
+    read[name] = value;
+    index += 1;
+  }
+  if (read.configA === void 0 || read.configB === void 0) {
+    throw new Error(
+      "geonosis-lint-parity: both --a and --b are required \u2014 one config compares to nothing"
+    );
+  }
+  return {
+    configA: read.configA,
+    configB: read.configB,
+    ...corpus === void 0 ? {} : { corpus },
+    ...read.out === void 0 ? {} : { out: read.out },
+    ...read.oxlint === void 0 ? {} : { oxlint: read.oxlint },
+    paths: paths.length === 0 ? ["."] : paths
+  };
+};
+var lint = ({
+  config,
+  cwd,
+  extra = [],
+  oxlint,
+  paths
+}) => {
+  const run = spawnSync(oxlint, ["--format=unix", ...extra, "--config", config, ...paths], {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, NO_COLOR: "1" },
+    maxBuffer: 64 * 1024 * 1024
+  });
+  if (run.error !== void 0)
+    throw new ParityError(`could not run ${oxlint}: ${run.error.message}`);
+  return { code: run.status ?? -1, output: `${run.stdout ?? ""}${run.stderr ?? ""}` };
+};
+var parityOf = ({
+  configA,
+  configB,
+  cwd,
+  out,
+  oxlint,
+  paths
+}) => {
+  const parity = compareFindings({
+    a: readRun(lint({ config: configA, cwd, oxlint, paths }), cwd, "A"),
+    b: readRun(lint({ config: configB, cwd, oxlint, paths }), cwd, "B")
+  });
+  if (out !== void 0) {
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, "a.txt"), asFile(parity.a));
+    writeFileSync(join(out, "b.txt"), asFile(parity.b));
+    writeFileSync(join(out, "only-in-a.txt"), asFile(parity.onlyInA));
+    writeFileSync(join(out, "only-in-b.txt"), asFile(parity.onlyInB));
+    writeFileSync(join(out, "changed.txt"), asFile(changedLines(parity.messageChanged)));
+    writeFileSync(join(out, "SUMMARY.md"), formatSummary(parity));
+  }
+  return parity;
+};
+
+export {
+  ParityError,
+  normaliseFindings,
+  readRun,
+  compareFindings,
+  formatSummary,
+  rulesNamedBy,
+  ruleIdOf,
+  MANIFEST_FILE,
+  manifestOf,
+  readManifest,
+  corpusOf,
+  formatCorpus,
+  parseParityArgs,
+  parityOf
+};

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+/** 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);
+}
+type RuleTally = {
+    a: number;
+    b: number;
+    rule: string;
+};
+/** One finding both runs made in the same place, worded — or graded — differently. */
+type MessageChange = {
+    a: string;
+    b: string;
+};
+type Parity = {
+    a: string[];
+    b: string[];
+    /** True when A found something B did not — the only failure this tool has. */
+    lost: boolean;
+    /**
+     * Same place, same rule, different message or severity. Reported, never counted as loss: every
+     * release copy-edits a rule's wording, and a diff of whole lines called each one a finding lost
+     * AND a finding gained — a stopped adoption over a sentence.
+     */
+    messageChanged: MessageChange[];
+    onlyInA: string[];
+    onlyInB: string[];
+    tally: RuleTally[];
+};
+/**
+ * One run's finding lines, with the root they were linted from removed and sorted. Both are what
+ * make two runs comparable: absolute paths differ between checkouts, and oxlint's file order is a
+ * thread-scheduling detail, not a finding.
+ */
+declare const normaliseFindings: (output: string, cwd: string) => string[];
+/**
+ * The findings of one run, or a refusal to guess. oxlint exits 1 both when it reported errors and
+ * when it never linted a file at all — a rule name it does not know, options a rule has no schema
+ * for, a plugin it could not load. All three print a paragraph and no findings, and "0 findings" on
+ * one side of a parity run reads as agreement with the other. So: a summary counting findings no
+ * line accounts for, or a non-zero exit with nothing readable on it, is an error, not a count.
+ */
+declare const readRun: ({ code, output }: {
+    code: number;
+    output: string;
+}, cwd: string, side: string) => string[];
+declare const compareFindings: ({ a, b }: {
+    a: string[];
+    b: string[];
+}) => Parity;
+declare const formatSummary: (parity: Parity) => string;
+type RuleReach = {
+    firedInA: boolean;
+    firedInB: boolean;
+    rule: string;
+};
+type CorpusReport = {
+    /** Rules no file in the corpus fires under either config — rules shipping with no evidence. */
+    neither: string[];
+    /**
+     * Configured rules the corpus never claimed to exercise — other plugins, the built-ins. Reported,
+     * never judged: a tree of one deliberately broken file per rule of ONE plugin is not evidence
+     * about anybody else's rule, and a verdict on one would be a guess.
+     */
+    outside: string[];
+    /** The plugin the corpus declared itself to speak for. */
+    plugin: string;
+    reach: RuleReach[];
+};
+/** The rule ids an oxlint config enables, exactly as it wrote them — plugin prefix included. */
+declare const rulesNamedBy: (config: string) => string[];
+/**
+ * The plugin-qualified id behind a finding's `plugin(rule)` token, in the `plugin/rule` shape a
+ * config names it by. Prefix included on purpose: `typescript(no-unused-vars)` is a different rule
+ * from `biological-architecture(no-unused-vars)`, and matching on the bare name would let either
+ * one stand as evidence for the other.
+ */
+declare const ruleIdOf: (line: string) => string;
+declare const MANIFEST_FILE = "manifest.json";
+/** What a corpus declares about itself: whose rules it exercises, and which ones. */
+type CorpusManifest = {
+    plugin: string;
+    rules: string[];
+};
+/**
+ * The manifest for a plugin, off the plugin itself. A plugin's corpus build writes what this
+ * returns beside its copied fixture tree — derived, never hand-maintained, so a rule cannot be
+ * added to the plugin and forgotten in the list of what the corpus is evidence about.
+ */
+declare const manifestOf: (plugin: {
+    meta: {
+        name: string;
+    };
+    rules: Record<string, unknown>;
+}) => CorpusManifest;
+/**
+ * A corpus says which rules it can speak for; nothing here infers it. That is what keeps the tool
+ * general: point `--corpus` at another plugin's tree and the scope moves with it, rather than a
+ * prefix welded into this file deciding what counts.
+ */
+declare const readManifest: (corpus: string) => CorpusManifest;
+/**
+ * Reach, not parity: which of the configured rules any file in the corpus actually fires. A rule
+ * that fires nowhere is a rule nobody has evidence for — during.day shipped 34 of them, and a
+ * 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, }: {
+    configA: string;
+    configB: string;
+    corpus: string;
+    oxlint: string;
+}) => CorpusReport;
+declare const formatCorpus: (report: CorpusReport) => string;
+type ParityArgs = {
+    configA: string;
+    configB: string;
+    /**
+     * The reach corpus to run over instead of a tree, reporting reach instead of parity. Absent means
+     * no corpus run: this tool ships none of its own, because a corpus is one plugin's evidence and a
+     * default would weld this tool to whichever plugin happened to be beside it.
+     */
+    corpus?: string;
+    out?: string;
+    oxlint?: string;
+    paths: string[];
+};
+declare const parseParityArgs: (argv: string[]) => ParityArgs;
+declare const parityOf: ({ configA, configB, cwd, out, oxlint, paths, }: {
+    configA: string;
+    configB: string;
+    cwd: string;
+    out?: string;
+    oxlint: string;
+    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 };

package/dist/index.js

@@ -0,0 +1,32 @@
+import {
+  MANIFEST_FILE,
+  ParityError,
+  compareFindings,
+  corpusOf,
+  formatCorpus,
+  formatSummary,
+  manifestOf,
+  normaliseFindings,
+  parityOf,
+  parseParityArgs,
+  readManifest,
+  readRun,
+  ruleIdOf,
+  rulesNamedBy
+} from "./chunk-OLCJQ6JC.js";
+export {
+  MANIFEST_FILE,
+  ParityError,
+  compareFindings,
+  corpusOf,
+  formatCorpus,
+  formatSummary,
+  manifestOf,
+  normaliseFindings,
+  parityOf,
+  parseParityArgs,
+  readManifest,
+  readRun,
+  ruleIdOf,
+  rulesNamedBy
+};

package/dist/parity-cli.js

@@ -0,0 +1,83 @@
+import {
+  corpusOf,
+  formatCorpus,
+  formatSummary,
+  parityOf,
+  parseParityArgs
+} from "./chunk-OLCJQ6JC.js";
+
+// src/parity-cli.ts
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { dirname, 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>]
+
+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
+now is the adoption stopping, whatever the version numbers say.
+
+--corpus runs both configs over a reach corpus \u2014 one file per rule that the rule must fire on \u2014
+and exits 1 when a rule the corpus claims to exercise fires under NEITHER. Run it first: a rule
+with no reach evidence reports parity with every other rule that also does nothing. The directory
+is required: this tool ships no corpus, because a corpus is one plugin's evidence. Point it at the
+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.
+
+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) {
+    process.stdout.write(`${USAGE}
+`);
+    return 0;
+  }
+  const args = parseParityArgs(argv);
+  const cwd = process.cwd();
+  const configA = resolve(cwd, args.configA);
+  const configB = resolve(cwd, args.configB);
+  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 text = formatCorpus(report);
+    process.stdout.write(`${text}
+`);
+    if (args.out !== void 0) {
+      const out = resolve(cwd, args.out);
+      mkdirSync(out, { recursive: true });
+      writeFileSync(join(out, "CORPUS.md"), text);
+    }
+    return report.neither.length > 0 ? 1 : 0;
+  }
+  const parity = parityOf({
+    configA,
+    configB,
+    cwd,
+    ...args.out === void 0 ? {} : { out: resolve(cwd, args.out) },
+    oxlint,
+    paths: args.paths
+  });
+  process.stdout.write(`${formatSummary(parity)}
+`);
+  return parity.lost ? 1 : 0;
+};
+try {
+  process.exit(main());
+} catch (error) {
+  process.stderr.write(`${error.message}
+`);
+  process.exit(2);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@geonosis/lint-parity",
+  "version": "0.2.0",
+  "description": "Findings parity and rule reach over any two oxlint configs — the diff a fork is deleted on.",
+  "keywords": [
+    "oxlint",
+    "lint",
+    "parity",
+    "migration",
+    "adoption",
+    "corpus",
+    "ci"
+  ],
+  "homepage": "https://github.com/microcompanies/geonosis/tree/main/packages/lint-parity",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microcompanies/geonosis.git",
+    "directory": "packages/lint-parity"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "geonosis-lint-parity": "bin/geonosis-lint-parity.mjs"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "peerDependencies": {
+    "oxlint": ">=1.77"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}