@geonosis/lint-parity 1.2.0 → 1.4.0

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

@@ -1,16 +1,100 @@
+// src/envelope.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var ENVELOPES_DIR = ".geonosis/envelopes";
+var envelopePath = (root, tool) => join(root, ENVELOPES_DIR, `${tool}.json`);
+var UnbalancedEnvelope = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnbalancedEnvelope";
+  }
+};
+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 writeEnvelope = ({
+  envelope,
+  next,
+  root
+}) => {
+  if (envelope.tool.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `an envelope with no tool name cannot be filed or reported against. Next: ${next}`
+    );
+  }
+  if (envelope.version.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: an envelope that cannot name the build that wrote it dates nothing, and a stale one reads exactly like a fresh one. Next: ${next}`
+    );
+  }
+  if (!isCount(envelope.considered) || !isCount(envelope.read)) {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: considered ${envelope.considered} and read ${envelope.read} \u2014 a census is a whole number of things, and arithmetic over anything else balances by accident. Next: ${next}`
+    );
+  }
+  if (envelope.considered !== envelope.read + envelope.refused.length + envelope.excused.length) {
+    throw new UnbalancedEnvelope(unbalancedMessage(envelope, next));
+  }
+  const at = envelopePath(root, envelope.tool);
+  mkdirSync(dirname(at), { recursive: true });
+  writeFileSync(at, `${JSON.stringify(envelope, void 0, 2)}
+`);
+  return at;
+};
+var UNKNOWN = "unknown";
+var versionIn = (dir) => {
+  try {
+    const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var versionOf = (moduleUrl) => {
+  let dir = dirname(fileURLToPath(moduleUrl));
+  for (; ; ) {
+    const found = versionIn(dir);
+    if (found !== void 0) return found;
+    const up = dirname(dir);
+    if (up === dir) return UNKNOWN;
+    dir = up;
+  }
+};
+var PARITY_TOOL = "lint-parity";
+var PARITY_NEXT = "oxlint --debug=files --config <each config> <paths> and diff the two lists \u2014 a parity run only compares the files BOTH configs opened, and the ones only one of them opened are the silence this refuses over";
+var parityEnvelope = (census, findings, durationMs) => ({
+  considered: census.both.length + census.onlyInA.length + census.onlyInB.length,
+  durationMs,
+  excused: [
+    ...census.onlyInA.map((path) => ({
+      path,
+      reason: "config B would not lint this file, so the two runs cannot be compared over it"
+    })),
+    ...census.onlyInB.map((path) => ({
+      path,
+      reason: "config A would not lint this file, so the two runs cannot be compared over it"
+    }))
+  ],
+  findings,
+  read: census.both.length,
+  refused: [],
+  tool: PARITY_TOOL,
+  version: versionOf(import.meta.url)
+});
+
 // src/parity.ts
 import { spawnSync } from "child_process";
 import {
   cpSync,
   existsSync,
-  mkdirSync,
+  mkdirSync as mkdirSync2,
   mkdtempSync,
-  readFileSync,
+  readFileSync as readFileSync2,
   rmSync,
-  writeFileSync
+  writeFileSync as writeFileSync2
 } from "fs";
 import { tmpdir } from "os";
-import { dirname, join, resolve } from "path";
+import { dirname as dirname2, join as join2, resolve } from "path";
 var ANSI = /\[[0-9;]*m/g;
 var SUMMARY_COUNT = /^(\d+) problems?$/m;
 var RULE_IN_LINE = /\[(?:Error|Warning)\/([^\]]+)\]$/;
@@ -21,7 +105,7 @@ var resolveOxlint = (from) => {
   for (; ; ) {
     const bin = resolve(dir, "node_modules/.bin/oxlint");
     if (existsSync(bin)) return bin;
-    const parent = dirname(dir);
+    const parent = dirname2(dir);
     if (parent === dir) return "oxlint";
     dir = parent;
   }
@@ -156,8 +240,13 @@ var formatSummary = (parity) => {
   ].join("\n");
 };
 var rulesNamedBy = (config) => {
-  const parsed = JSON.parse(readFileSync(config, "utf8"));
-  return Object.keys(parsed.rules ?? {});
+  const parsed = JSON.parse(readFileSync2(config, "utf8"));
+  return [
+    .../* @__PURE__ */ new Set([
+      ...Object.keys(parsed.rules ?? {}),
+      ...(parsed.overrides ?? []).flatMap((one) => Object.keys(one.rules ?? {}))
+    ])
+  ];
 };
 var ruleIdOf = (line) => {
   const token = RULE_IN_LINE.exec(line)?.[1];
@@ -192,10 +281,10 @@ var verdictOf = (changed, claimed) => {
   return claimed ? "unproven" : "unclaimed";
 };
 var readManifest = (corpus) => {
-  const path = join(corpus, MANIFEST_FILE);
+  const path = join2(corpus, MANIFEST_FILE);
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync(path, "utf8"));
+    parsed = JSON.parse(readFileSync2(path, "utf8"));
   } catch (error) {
     throw new ParityError(`could not read ${path}: ${error.message}`);
   }
@@ -214,8 +303,8 @@ var corpusOf = ({
 }) => {
   const manifest = readManifest(corpus);
   const exercised = new Set(manifest.rules);
-  const root = mkdtempSync(join(tmpdir(), "geonosis-corpus-"));
-  const here = join(root, "corpus");
+  const root = mkdtempSync(join2(tmpdir(), "geonosis-corpus-"));
+  const here = join2(root, "corpus");
   const foundIn = (config, side) => {
     const counts = /* @__PURE__ */ new Map();
     for (const finding of readRun(
@@ -390,6 +479,44 @@ var lint = ({
     throw new ParityError(`could not run ${oxlint}: ${run.error.message}`);
   return { code: run.status ?? -1, output: `${run.stdout ?? ""}${run.stderr ?? ""}` };
 };
+var filesLintedBy = ({
+  config,
+  cwd,
+  oxlint,
+  paths
+}) => {
+  const run = spawnSync(oxlint, ["--debug=files", "--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}`);
+  }
+  if (run.status !== 0) {
+    throw new ParityError(
+      `oxlint --debug=files exited ${String(run.status)} under ${config}, so which files it would read is not known:
+${`${run.stdout ?? ""}${run.stderr ?? ""}`.trim()}`
+    );
+  }
+  return (run.stdout ?? "").split("\n").map((line) => line.trim().replace(`${cwd}/`, "").replace(/^\.\//, "")).filter((line) => line !== "").toSorted();
+};
+var fileCensus = ({
+  configA,
+  configB,
+  cwd,
+  oxlint,
+  paths
+}) => {
+  const inA = filesLintedBy({ config: configA, cwd, oxlint, paths });
+  const inB = new Set(filesLintedBy({ config: configB, cwd, oxlint, paths }));
+  return {
+    both: inA.filter((file) => inB.has(file)),
+    onlyInA: inA.filter((file) => !inB.has(file)),
+    onlyInB: [...inB].filter((file) => !inA.includes(file)).toSorted()
+  };
+};
 var parityOf = ({
   configA,
   configB,
@@ -403,18 +530,21 @@ var parityOf = ({
     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));
+    mkdirSync2(out, { recursive: true });
+    writeFileSync2(join2(out, "a.txt"), asFile(parity.a));
+    writeFileSync2(join2(out, "b.txt"), asFile(parity.b));
+    writeFileSync2(join2(out, "only-in-a.txt"), asFile(parity.onlyInA));
+    writeFileSync2(join2(out, "only-in-b.txt"), asFile(parity.onlyInB));
+    writeFileSync2(join2(out, "changed.txt"), asFile(changedLines(parity.messageChanged)));
+    writeFileSync2(join2(out, "SUMMARY.md"), formatSummary(parity));
   }
   return parity;
 };
 
 export {
+  writeEnvelope,
+  PARITY_NEXT,
+  parityEnvelope,
   resolveOxlint,
   ParityError,
   normaliseFindings,
@@ -429,5 +559,7 @@ export {
   corpusOf,
   formatCorpus,
   parseParityArgs,
+  filesLintedBy,
+  fileCensus,
   parityOf
 };

package/dist/index.d.ts

@@ -1,3 +1,10 @@
+/** The files each config would actually read, split three ways. */
+type FileCensus = {
+    both: string[];
+    onlyInA: string[];
+    onlyInB: string[];
+};
+
 /**
  * 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
@@ -97,7 +104,15 @@ type CorpusReport = {
     plugin: string;
     reach: RuleReach[];
 };
-/** The rule ids an oxlint config enables, exactly as it wrote them — plugin prefix included. */
+/**
+ * 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.
+ */
 declare const rulesNamedBy: (config: string) => string[];
 /**
  * The plugin-qualified id behind a finding's `plugin(rule)` token, in the `plugin/rule` shape a
@@ -166,6 +181,35 @@ type ParityArgs = {
     paths: string[];
 };
 declare const parseParityArgs: (argv: string[]) => ParityArgs;
+/**
+ * The files a config would actually lint, asked of oxlint itself.
+ *
+ * `--debug=files` prints one path per line and exits 0 without linting anything: measured here,
+ * `--config narrow.json` (whose `ignorePatterns` name `b.ts`) printed one file where
+ * `--config wide.json` printed two. Nothing else in a `--format=unix` run carries this — that
+ * output is findings and only findings, which is why a parity run could report agreement over a
+ * tree the second config never opened.
+ *
+ * The argv is deliberately the same SHAPE `lint` uses, config and paths passed through exactly as
+ * they arrived. It has to be: oxlint's ignore resolution is sensitive to that shape — an absolute
+ * `--config` with a relative path argument applies no `ignorePatterns` at all, where the same
+ * config named relatively does. A census taken under different arguments would describe a run
+ * nobody made, which is the failure this whole envelope is about.
+ */
+declare const filesLintedBy: ({ config, cwd, oxlint, paths, }: {
+    config: string;
+    cwd: string;
+    oxlint: string;
+    paths: string[];
+}) => string[];
+/** Which files both configs would read, and which each would read alone. */
+declare const fileCensus: ({ configA, configB, cwd, oxlint, paths, }: {
+    configA: string;
+    configB: string;
+    cwd: string;
+    oxlint: string;
+    paths: string[];
+}) => FileCensus;
 declare const parityOf: ({ configA, configB, cwd, out, oxlint, paths, }: {
     configA: string;
     configB: string;
@@ -175,4 +219,4 @@ declare const parityOf: ({ configA, configB, cwd, out, oxlint, paths, }: {
     paths: string[];
 }) => Parity;
 
-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 };
+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 };

package/dist/index.js

@@ -3,6 +3,8 @@ import {
   ParityError,
   compareFindings,
   corpusOf,
+  fileCensus,
+  filesLintedBy,
   formatCorpus,
   formatSummary,
   manifestOf,
@@ -14,12 +16,14 @@ import {
   resolveOxlint,
   ruleIdOf,
   rulesNamedBy
-} from "./chunk-3PCNMLVE.js";
+} from "./chunk-D7OGKQ2C.js";
 export {
   MANIFEST_FILE,
   ParityError,
   compareFindings,
   corpusOf,
+  fileCensus,
+  filesLintedBy,
   formatCorpus,
   formatSummary,
   manifestOf,

package/dist/parity-cli.js

@@ -1,11 +1,15 @@
 import {
+  PARITY_NEXT,
   corpusOf,
+  fileCensus,
   formatCorpus,
   formatSummary,
+  parityEnvelope,
   parityOf,
   parseParityArgs,
-  resolveOxlint
-} from "./chunk-3PCNMLVE.js";
+  resolveOxlint,
+  writeEnvelope
+} from "./chunk-D7OGKQ2C.js";
 
 // src/parity-cli.ts
 import { mkdirSync, writeFileSync } from "fs";
@@ -37,6 +41,16 @@ path \u2014 a config in a temp dir cannot find a plugin installed in the workspa
 refused rather than counted as zero findings.`;
 var main = () => {
   const argv = process.argv.slice(2);
+  if (argv.includes("--print-config-shape")) {
+    process.stdout.write(
+      `geonosis-lint-parity reads no configuration file.
+
+The two configs it compares are .oxlintrc.json files named on the command line with --a and --b,
+and it reads them as oxlint does rather than interpreting them itself.
+`
+    );
+    return 0;
+  }
   if (argv.includes("--help") || argv.includes("-h") || argv.length === 0) {
     process.stdout.write(`${USAGE}
 `);
@@ -66,6 +80,7 @@ var main = () => {
     }
     return report.neither.length > 0 || !report.claimsHeld ? 1 : 0;
   }
+  const startedAt = Date.now();
   const parity = parityOf({
     configA,
     configB,
@@ -75,6 +90,17 @@ var main = () => {
     paths: args.paths
   });
   process.stdout.write(`${formatSummary(parity)}
+`);
+  const at = writeEnvelope({
+    envelope: parityEnvelope(
+      fileCensus({ configA, configB, cwd, oxlint, paths: args.paths }),
+      parity.onlyInA,
+      Date.now() - startedAt
+    ),
+    next: PARITY_NEXT,
+    root: cwd
+  });
+  process.stdout.write(`envelope: ${at}
 `);
   return parity.lost ? 1 : 0;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/lint-parity",
-  "version": "1.2.0",
+  "version": "1.4.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": [
@@ -43,6 +43,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "devDependencies": {
+    "@geonosis/ratchet": "1.4.0"
+  },
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit"