@geonosis/lint-parity 2.1.0 → 2.3.0

package/README.md

@@ -1,5 +1,8 @@
 # @geonosis/lint-parity
 
+Through the front door: `geonosis lint-parity` — the metapackage pins this and every other kit tool
+at ONE version, and passes the exit code through unchanged.
+
 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

package/dist/{chunk-D7OGKQ2C.js → chunk-JPGZG2HA.js}

@@ -1,6 +1,6 @@
 // src/envelope.ts
 import { mkdirSync, readFileSync, writeFileSync } from "fs";
-import { dirname, join } from "path";
+import { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 var ENVELOPES_DIR = ".geonosis/envelopes";
 var envelopePath = (root, tool) => join(root, ENVELOPES_DIR, `${tool}.json`);
@@ -12,6 +12,14 @@ var UnbalancedEnvelope = class extends Error {
 };
 var isCount = (value) => Number.isSafeInteger(value) && value >= 0;
 var unbalancedMessage = (envelope, next) => `${envelope.tool}: considered ${envelope.considered} but accounts for ${envelope.read + envelope.refused.length + envelope.excused.length} \u2014 ${envelope.read} read + ${envelope.refused.length} refused + ${envelope.excused.length} excused. A run that has lost count of its own inputs cannot say what it measured, so no verdict was rendered and no envelope was written. Next: ${next}`;
+var FORBIDDEN_ROOT = "GEONOSIS_ENVELOPES_FORBIDDEN_ROOT";
+var refuseForbiddenRoot = (root) => {
+  const forbidden = process.env[FORBIDDEN_ROOT];
+  if (forbidden === void 0 || resolve(forbidden) !== resolve(root)) return;
+  throw new UnbalancedEnvelope(
+    `${root} is off limits to envelope writers in this process (${FORBIDDEN_ROOT}) \u2014 a run that writes one into a shared root races every other run reading it, and leaves a file the next one takes for real. Point this at a scratch root of its own: tooling/scratch-dir.ts.`
+  );
+};
 var writeEnvelope = ({
   envelope,
   next,
@@ -35,6 +43,7 @@ var writeEnvelope = ({
   if (envelope.considered !== envelope.read + envelope.refused.length + envelope.excused.length) {
     throw new UnbalancedEnvelope(unbalancedMessage(envelope, next));
   }
+  refuseForbiddenRoot(root);
   const at = envelopePath(root, envelope.tool);
   mkdirSync(dirname(at), { recursive: true });
   writeFileSync(at, `${JSON.stringify(envelope, void 0, 2)}
@@ -94,7 +103,7 @@ import {
   writeFileSync as writeFileSync2
 } from "fs";
 import { tmpdir } from "os";
-import { dirname as dirname2, join as join2, resolve } from "path";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 var ANSI = /\[[0-9;]*m/g;
 var SUMMARY_COUNT = /^(\d+) problems?$/m;
 var RULE_IN_LINE = /\[(?:Error|Warning)\/([^\]]+)\]$/;
@@ -103,7 +112,7 @@ 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");
+    const bin = resolve2(dir, "node_modules/.bin/oxlint");
     if (existsSync(bin)) return bin;
     const parent = dirname2(dir);
     if (parent === dir) return "oxlint";
@@ -117,6 +126,8 @@ var ParityError = class extends Error {
   }
 };
 var normaliseFindings = (output, cwd) => output.replaceAll(ANSI, "").split("\n").map((line) => line.trim().replace(`${cwd}/`, "").replace(/^\.\//, "")).filter((line) => UNIX_FINDING.test(line)).toSorted();
+var REFUSED_CONFIG = /Failed to parse oxlint configuration file|Failed to setup JS plugin options/;
+var refusalIn = (output) => (/^\s*(?:x|Error:)\s*(.+)$/m.exec(output)?.[1] ?? output.trim().split("\n")[0] ?? "").trim();
 var readRun = ({ code, output }, cwd, side) => {
   const findings = normaliseFindings(output, cwd);
   const summary = SUMMARY_COUNT.exec(output);
@@ -127,6 +138,11 @@ ${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 (REFUSED_CONFIG.test(output)) {
+    return refuse(
+      `oxlint refused to parse this config and linted nothing \u2014 ${refusalIn(output)}. That is not a run with no findings. For a corpus comparison, config A is the BASE COMMIT's own corpus config against the BASE build, never HEAD's config against an older build: see docs/releasing.md.`
+    );
+  }
   if (findings.length === 0 && code !== 0) {
     return refuse(`oxlint exited ${code} without reporting a single finding`);
   }
@@ -239,15 +255,22 @@ var formatSummary = (parity) => {
     changed
   ].join("\n");
 };
-var rulesNamedBy = (config) => {
+var OFF = /* @__PURE__ */ new Set(["off", 0]);
+var severityOf = (level) => Array.isArray(level) ? level[0] : level;
+var layersOf = (config) => {
   const parsed = JSON.parse(readFileSync2(config, "utf8"));
-  return [
-    .../* @__PURE__ */ new Set([
-      ...Object.keys(parsed.rules ?? {}),
-      ...(parsed.overrides ?? []).flatMap((one) => Object.keys(one.rules ?? {}))
-    ])
-  ];
+  return [parsed.rules ?? {}, ...(parsed.overrides ?? []).map((one) => one.rules ?? {})];
+};
+var namedBy = (config) => {
+  const layers = layersOf(config);
+  const named = [...new Set(layers.flatMap((one) => Object.keys(one)))];
+  const enabled = named.filter(
+    (rule) => layers.some((one) => rule in one && !OFF.has(severityOf(one[rule])))
+  );
+  return { enabled, off: named.filter((rule) => !enabled.includes(rule)) };
 };
+var rulesNamedBy = (config) => namedBy(config).enabled;
+var rulesTurnedOffBy = (config) => namedBy(config).off;
 var ruleIdOf = (line) => {
   const token = RULE_IN_LINE.exec(line)?.[1];
   if (token === void 0) return UNATTRIBUTED;
@@ -333,6 +356,7 @@ var corpusOf = ({
     rmSync(root, { force: true, recursive: true });
   }
   const configured = [.../* @__PURE__ */ new Set([...rulesNamedBy(configA), ...rulesNamedBy(configB)])].toSorted();
+  const off = [.../* @__PURE__ */ new Set([...rulesTurnedOffBy(configA), ...rulesTurnedOffBy(configB)])].filter((rule) => !configured.includes(rule)).toSorted();
   const reach = configured.filter((rule) => exercised.has(rule)).map((rule) => {
     const foundInA = inA.get(rule) ?? 0;
     const foundInB = inB.get(rule) ?? 0;
@@ -350,6 +374,7 @@ var corpusOf = ({
     claims,
     claimsHeld: claims.every((one) => one.verdict === "held"),
     neither: reach.filter((one) => !one.firedInA && !one.firedInB).map((one) => one.rule),
+    off,
     outside: configured.filter((rule) => !exercised.has(rule)),
     plugin: manifest.plugin,
     reach
@@ -387,6 +412,7 @@ var formatCorpus = (report) => {
     `- rules in scope of this corpus: **${report.reach.length}**`,
     `- fired under neither config: **${report.neither.length}**`,
     `- outside this corpus: **${report.outside.length}**`,
+    `- turned off by a config, so out of scope: **${report.off.length}**${report.off.length === 0 ? "" : ` (${report.off.map((rule) => `\`${rule}\``).join(", ")})`}`,
     "",
     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")}`,
@@ -416,9 +442,14 @@ var parseParityArgs = (argv) => {
   const read = {};
   let corpus;
   let expectChanged;
+  let json = false;
   for (let index = 0; index < flags.length; index += 1) {
     const flag = flags[index];
     const value = flags[index + 1];
+    if (flag === "--json") {
+      json = true;
+      continue;
+    }
     if (flag === CORPUS_FLAG) {
       if (value === void 0 || value.startsWith("--")) {
         throw new Error(
@@ -457,6 +488,7 @@ var parseParityArgs = (argv) => {
     configB: read.configB,
     ...corpus === void 0 ? {} : { corpus },
     ...expectChanged === void 0 ? {} : { expectChanged },
+    json,
     ...read.out === void 0 ? {} : { out: read.out },
     ...read.oxlint === void 0 ? {} : { oxlint: read.oxlint },
     paths: paths.length === 0 ? ["."] : paths
@@ -552,6 +584,7 @@ export {
   compareFindings,
   formatSummary,
   rulesNamedBy,
+  rulesTurnedOffBy,
   ruleIdOf,
   MANIFEST_FILE,
   manifestOf,

package/dist/index.d.ts

@@ -47,13 +47,6 @@ type Parity = {
  * 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;
@@ -100,20 +93,31 @@ type CorpusReport = {
      * about anybody else's rule, and a verdict on one would be a guess.
      */
     outside: string[];
+    /**
+     * Rules a config names and turns off. Out of scope — a rule that does not run cannot be shown to
+     * reach anything — and counted, so "in scope" is never a number with a silent subtraction in it.
+     */
+    off: 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, and
+ * The rule ids an oxlint config ENABLES, exactly as it wrote them — plugin prefix included, and
  * from `overrides[]` as well as from `rules`.
  *
  * A config's base block is only its first layer: an overrides entry may name a rule the base block
  * never mentions, and oxlint runs it on every file that entry's globs claim. Reading `rules` alone
  * left such a rule out of the reach scope entirely — it fired, and the report about which rules
  * reach anything did not have a row for it.
+ *
+ * Severity is read (#16). A rule set to `"off"` does not run, so a corpus that never fires it has
+ * shown nothing about it: three rules read as "fire nowhere" under a consumer's config where the
+ * doctor, which does read severity, said one.
  */
 declare const rulesNamedBy: (config: string) => string[];
+/** The rules a config names and turns off — out of the reach scope, and counted rather than hidden. */
+declare const rulesTurnedOffBy: (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
@@ -176,6 +180,8 @@ type ParityArgs = {
      * an empty list is not expressible, because a claim about no rules is not a claim.
      */
     expectChanged?: string[];
+    /** Print the report as a document rather than as a summary a caller has to read by regex. */
+    json: boolean;
     out?: string;
     oxlint?: string;
     paths: string[];
@@ -219,4 +225,4 @@ declare const parityOf: ({ configA, configB, cwd, out, oxlint, paths, }: {
     paths: string[];
 }) => Parity;
 
-export { type CorpusClaim, type CorpusManifest, type CorpusReport, type FileCensus, MANIFEST_FILE, type MessageChange, type Parity, type ParityArgs, ParityError, type RuleReach, type RuleTally, compareFindings, corpusOf, fileCensus, filesLintedBy, formatCorpus, formatSummary, manifestOf, normaliseFindings, parityOf, parseParityArgs, readManifest, readRun, resolveOxlint, ruleIdOf, rulesNamedBy };
+export { type CorpusClaim, type CorpusManifest, type CorpusReport, type FileCensus, MANIFEST_FILE, type MessageChange, type Parity, type ParityArgs, ParityError, type RuleReach, type RuleTally, compareFindings, corpusOf, fileCensus, filesLintedBy, formatCorpus, formatSummary, manifestOf, normaliseFindings, parityOf, parseParityArgs, readManifest, readRun, resolveOxlint, ruleIdOf, rulesNamedBy, rulesTurnedOffBy };

package/dist/index.js

@@ -15,8 +15,9 @@ import {
   readRun,
   resolveOxlint,
   ruleIdOf,
-  rulesNamedBy
-} from "./chunk-D7OGKQ2C.js";
+  rulesNamedBy,
+  rulesTurnedOffBy
+} from "./chunk-JPGZG2HA.js";
 export {
   MANIFEST_FILE,
   ParityError,
@@ -34,5 +35,6 @@ export {
   readRun,
   resolveOxlint,
   ruleIdOf,
-  rulesNamedBy
+  rulesNamedBy,
+  rulesTurnedOffBy
 };

package/dist/parity-cli.js

@@ -9,13 +9,13 @@ import {
   parseParityArgs,
   resolveOxlint,
   writeEnvelope
-} from "./chunk-D7OGKQ2C.js";
+} from "./chunk-JPGZG2HA.js";
 
 // src/parity-cli.ts
 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>]
+var USAGE = `geonosis-lint-parity --a <config-a.json> --b <config-b.json> [--oxlint <path>] [--out <dir>] [--json] -- <paths\u2026>
+geonosis-lint-parity --corpus <dir> --a <config-a.json> --b <config-b.json> [--out <dir>] [--json]
                      [--expect-changed <rule,rule,\u2026>]
 
 Runs oxlint twice over the same paths under two configs and diffs the findings. Exits 1 when a
@@ -71,7 +71,8 @@ and it reads them as oxlint does rather than interpreting them itself.
       oxlint
     });
     const text = formatCorpus(report);
-    process.stdout.write(`${text}
+    process.stdout.write(args.json ? `${JSON.stringify(report, void 0, 2)}
+` : `${text}
 `);
     if (args.out !== void 0) {
       const out = resolve(cwd, args.out);
@@ -89,7 +90,7 @@ and it reads them as oxlint does rather than interpreting them itself.
     oxlint,
     paths: args.paths
   });
-  process.stdout.write(`${formatSummary(parity)}
+  if (!args.json) process.stdout.write(`${formatSummary(parity)}
 `);
   const at = writeEnvelope({
     envelope: parityEnvelope(
@@ -100,8 +101,11 @@ and it reads them as oxlint does rather than interpreting them itself.
     next: PARITY_NEXT,
     root: cwd
   });
-  process.stdout.write(`envelope: ${at}
-`);
+  process.stdout.write(
+    args.json ? `${JSON.stringify(parity, void 0, 2)}
+` : `envelope: ${at}
+`
+  );
   return parity.lost ? 1 : 0;
 };
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/lint-parity",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "types": "./dist/index.d.ts",
   "description": "Findings parity and rule reach over any two oxlint configs — the diff a fork is deleted on.",
   "keywords": [
@@ -44,7 +44,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@geonosis/ratchet": "2.1.0"
+    "@geonosis/ratchet": "2.3.0"
   },
   "scripts": {
     "build": "tsup",