@ecoma-io/archkeep 0.13.0 → 0.14.0

package/README.md

@@ -220,7 +220,7 @@ Exit codes: 0 clean — and every selected file was analyzed; 1 findings;
 Ten minutes end to end, most of it spent deciding what your tags mean:
 [**Getting started →**](https://github.com/ecoma-io/archkeep/blob/main/docs/getting-started/installation.md). `graph`, `diff`,
 `history`, `drift`, `impact`, `explain`, `context` and the rest of the
-seventeen-command surface are in the [CLI reference](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/cli.md).
+eighteen-command surface are in the [CLI reference](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/cli.md).
 
 ## Documentation map
 

package/cli.mjs

@@ -104,6 +104,7 @@ import { contextCommand } from "./src/commands/context-command.mjs";
 import { planContextCommand } from "./src/commands/plan-context-command.mjs";
 import { adrCommand } from "./src/commands/adr.mjs";
 import { diffCommand } from "./src/commands/diff.mjs";
+import { captureDelta, deltaCommand } from "./src/commands/delta.mjs";
 import { discoverCommand } from "./src/commands/discover.mjs";
 import { driftCommand } from "./src/commands/drift.mjs";
 import { fitnessCommand } from "./src/commands/fitness.mjs";
@@ -941,6 +942,93 @@ async function runDiff(options, { cwd, env }) {
   return EXIT.ok;
 }
 
+/**
+ * `delta`'s `run`: two modes behind one verb.
+ *
+ * `--capture` writes the evidence snapshot a later run compares against;
+ * `delta <baseline>` loads one, re-judges both sides under the current law,
+ * and folds the classification into the exit code — the one descriptive-family
+ * verb beside `check` and `fitness` whose verdict carries exit 1
+ * (`./src/commands/delta.mjs` owns the fold).
+ *
+ * @param {{format: string, output: string|null, config: string|null, capture: boolean,
+ *   paths: string[]}} options
+ * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
+ * @returns {Promise<number>}
+ */
+async function runDelta(options, { cwd, env }) {
+  if (options.capture) {
+    if (options.paths.length !== 0) {
+      env.err(
+        `archkeep: delta --capture takes no positional arguments; got ${options.paths.join(", ")}`,
+      );
+      return EXIT.usage;
+    }
+  } else if (options.paths.length !== 1) {
+    env.err(
+      `archkeep: delta takes exactly one positional argument (the baseline evidence snapshot), ` +
+        `or --capture to write one; got ${options.paths.length}`,
+    );
+    return EXIT.usage;
+  }
+
+  let result;
+  try {
+    const commandContext = resolveCommandContext(
+      { cwd },
+      { readGraph: env.readGraph, listFiles: env.listFiles },
+    );
+
+    // Both modes need the boundary law: capture fingerprints it, compare
+    // re-judges both sides under it — the same ladder every judging command
+    // resolves through (`resolvePolicy`).
+    const { config } = await resolvePolicy(options, commandContext, cwd);
+
+    if (options.capture) {
+      const { text } = captureDelta(commandContext, { config });
+      if (options.output) {
+        // Atomic, symlink-safe write — `writeOutputReport`'s own docstring
+        // owns the mechanism and the threat it closes.
+        if (!writeOutputReport(options.output, text, env, cwd, options.config)) return EXIT.error;
+        env.err(`archkeep: delta baseline captured → ${options.output}`);
+      } else {
+        env.out(text);
+      }
+      // Capture is descriptive: 0 on success, 3 on any failure, never 1.
+      return EXIT.ok;
+    }
+
+    const baselinePath = isAbsolute(options.paths[0])
+      ? resolve(options.paths[0])
+      : resolve(cwd, options.paths[0]);
+    result = deltaCommand(baselinePath, commandContext, { config });
+  } catch (error) {
+    const usageError = error instanceof UsageError;
+    env.err(String(error?.message ?? error));
+    return usageError ? EXIT.usage : EXIT.error;
+  }
+
+  const report = options.format === "json" ? result.report.json : result.report.text;
+
+  if (options.output) {
+    // Atomic, symlink-safe write — `writeOutputReport`'s own docstring owns
+    // the mechanism and the threat it closes.
+    const reportText = report.endsWith("\n") ? report : `${report}\n`;
+    if (!writeOutputReport(options.output, reportText, env, cwd, options.config)) return EXIT.error;
+    env.err(`archkeep: delta complete → ${options.output}`);
+  } else {
+    env.out(report);
+  }
+
+  // The exit fold `deltaCommand` computed: a non-waived introduced violation
+  // is a finding, an unclassifiable item is a no-verdict, anything else is
+  // clean — mapped here the same way `fitness`'s status is.
+  return (
+    { ok: EXIT.ok, findings: EXIT.violations, "no-verdict": EXIT.error }[result.status] ??
+    EXIT.error
+  );
+}
+
 /**
  * `drift`'s `run`: resolves the command context, drives `driftCommand`, writes
  * the report where it belongs, and returns the process's exit code.
@@ -1156,9 +1244,14 @@ async function runWaivers(options, { cwd, env }) {
     // against this tool's own location, and a `profiles` registry resolves
     // `--config`/`boundaryConfig` as a profile NAME the same way `check`
     // does. A malformed law throws here, exit 3, exactly as in `check`.
-    const { config } = await resolvePolicy(options, commandContext, cwd);
+    const { config, source } = await resolvePolicy(options, commandContext, cwd);
 
-    result = await waiversCommand(commandContext, config);
+    // `source` rides along for one job: `waiversCommand` subtracts the law's
+    // own file from the unowned-file set the `coverage.unowned` acceptances
+    // are matched against, exactly as `check` does — the law is not source
+    // judged by the law (`../src/commands/context.mjs`'s
+    // `unownedGapWithoutRunConfiguration`).
+    result = await waiversCommand(commandContext, config, { policySource: source });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -2011,6 +2104,58 @@ const DIFF_FLAG_HELP = Object.freeze([
   }),
 ]);
 
+/**
+ * `delta`'s flags: `--capture` writes the evidence snapshot a later run
+ * compares against; without it the baseline file is the single positional
+ * argument. `--config` overrides the boundary law the same way `check`'s
+ * does, because both sides are re-judged under whichever law this run
+ * resolves.
+ *
+ * @type {readonly FlagHelp[]}
+ */
+const DELTA_FLAG_HELP = Object.freeze([
+  Object.freeze({
+    flag: "--capture",
+    key: "capture",
+    arg: "",
+    describe: Object.freeze([
+      "Write an evidence snapshot of the current tree",
+      "(raw import records, graph, coverage, policy",
+      "fingerprint) for a later delta run to compare against",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--format",
+    key: "format",
+    arg: "text|json",
+    describe: Object.freeze([
+      "Terminal report (default) or the versioned JSON envelope",
+      "docs/reference/json-output.md documents",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--output",
+    key: "output",
+    arg: "<file>",
+    describe: Object.freeze([
+      "Write the report — or, with --capture, the snapshot —",
+      "to a file instead of stdout",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--config",
+    key: "config",
+    arg: "<file>",
+    describe: ({ boundaryConfig, inline }) =>
+      Object.freeze([
+        "Read the boundary law from here instead of",
+        inline
+          ? "the inline boundaryConfig in archkeep.json"
+          : `<workspace root>/${boundaryConfig}`,
+      ]),
+  }),
+]);
+
 /**
  * `drift`'s flags: text or JSON envelope, optional file output. The intent is
  * always read from the tracked root `architecture-intent.json` — the same one
@@ -2527,6 +2672,17 @@ const COMMANDS = Object.freeze({
     formats: DESCRIBABLE_FORMATS,
     run: runDiff,
   }),
+  delta: Object.freeze({
+    name: "delta",
+    args: "<baseline> | --capture",
+    summary: "Classify how boundary violations moved between a captured baseline and head",
+    flagHelp: DELTA_FLAG_HELP,
+    flags: Object.freeze(Object.fromEntries(DELTA_FLAG_HELP.map((f) => [f.flag, f.key]))),
+    defaults: Object.freeze({ format: "text", output: null, config: null, capture: false }),
+    formats: DESCRIBABLE_FORMATS,
+    booleans: Object.freeze(["capture"]),
+    run: runDelta,
+  }),
   discover: Object.freeze({
     name: "discover",
     args: "[--propose]",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript and Vue",
   "keywords": [
     "architecture",

package/src/commands/README.md

@@ -23,7 +23,7 @@ the resolution order.
   (`./custom-rules.mjs`). Exits 1 on any of them, and it is the only
   command holding all four exit codes
   ([which verbs carry exit 1 is settled in `docs/concepts/architecture.md`](../../../../docs/concepts/architecture.md)
-  — `fitness` is the other one).
+  — `fitness` and `delta` are the other two).
 
 - **`graph`** (`./graph.mjs`'s `graphCommand`) — the project graph as a
   deterministic, serialisable snapshot: projects (with `targets` and `tags`) and
@@ -42,6 +42,24 @@ the resolution order.
   Refuses an Nx workspace with polyglot manifests but no plugin registration.
   Descriptive: never exits 1.
 
+- **`delta`** (`./delta.mjs`'s `captureDelta` and `deltaCommand`) — two modes
+  behind one verb. `--capture` writes the evidence snapshot
+  `./delta-snapshot.mjs` defines — raw import-site records, the graph, coverage,
+  provenance, the policy fingerprint; evidence, never verdicts. Compare loads a
+  baseline, re-judges BOTH sides through `../rules/index.mjs` under the CURRENT
+  config and one shared instant, and classifies each violation
+  introduced/resolved/unchanged/unknown (`./delta-classify.mjs`), with
+  unresolvable import sites carried as their own category, never counted as
+  violations. Refuses an unreadable, malformed, foreign-schema, or
+  incomplete-coverage baseline, a provider mismatch (stricter than `diff`'s
+  note — violation identity across two project models is not evidence),
+  incomplete head coverage, and an Nx workspace with polyglot manifests but no
+  plugin registration; a policy-fingerprint change is a loud coverage note, not
+  a refusal. A verdict, not a description: a non-waived introduced violation is
+  a finding (exit 1 — the third verb beside `check` and `fitness`), an
+  unclassifiable item is a no-verdict (exit 3), and a waived-introduced entry
+  is reported without gating. Capture stays descriptive: never exits 1.
+
 - **`impact`** (`./impact.mjs`'s `impactCommand`) — reverse reachability from
   the project graph: given a project name, lists every project that transitively
   depends on it. Separates direct from transitive dependents. When a boundary

package/src/commands/check.mjs

@@ -18,6 +18,7 @@ import { suppressionCovers } from "../config.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import { suppressionFate } from "../governance/waiver.mjs";
 import { resolveCommandContext, unownedGapWithoutRunConfiguration } from "./context.mjs";
+import { partitionUnownedCoverage } from "./coverage-acceptance.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
 import { declaredEdgeViolationsForCheck } from "./edge-constraints.mjs";
@@ -248,6 +249,51 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
       }
     : null;
 
+  // The unowned-file question, answered once and BEFORE any verdict below
+  // reads `failures`: the tolerated TS/JS/Vue gap (`./context.mjs`'s
+  // `unownedGap`), minus the files this run read as its own configuration —
+  // the law that actually governed THIS run, which `policySource` names
+  // (`--config` override and resolved profile included), never the declared
+  // name alone. Subtracting here rather than inside `resolveCommandContext`
+  // is forced: `resolvePolicy` takes the context as an argument, so it cannot
+  // run before it, and until it has run nothing knows which law governed.
+  // `tsConfig` joins it because it is configuration by the same test, though
+  // every spelling of it is `.json` today and so never reaches the list.
+  const unownedGap = unownedGapWithoutRunConfiguration(commandContext.unownedGap, [
+    policySource,
+    commandContext.options.tsConfig,
+  ]);
+  // Then the acceptance channel: the policy's `coverage.unowned` rows,
+  // matched against BOTH unowned sets — this gap and the Go/Rust/Python
+  // unclaimed list — and nothing else (`./coverage-acceptance.mjs` owns the
+  // guarantee that an owned file is unreachable). Unowned-ness is decided
+  // exactly as before this channel existed; the rows only partition the
+  // result into accepted and uncovered.
+  const coverageRows = config?.coverage?.unowned ?? [];
+  const unownedCoverage = partitionUnownedCoverage({
+    rows: coverageRows,
+    unownedGap,
+    unclaimedFiles: commandContext.unclaimedGap.files,
+    tracked,
+  });
+  // A covered unclaimed file's whole-file failure is withdrawn here: the file
+  // is still unowned and still unanalyzed, but its state is a RECORDED
+  // acceptance now — stated below as the `"accepted-unowned-files"` coverage
+  // gap, never silently — rather than the exit-3 refusal an unanswered
+  // orphan earns. Uncovered unclaimed files keep their failures, and with
+  // them the exit code, byte-identical to before the channel existed. An
+  // unclaimed file carries exactly one failure (it is unowned, so no
+  // analyzer ever read it), so filtering by file cannot drop an unrelated
+  // read failure.
+  const acceptedUnclaimed = new Set(
+    commandContext.unclaimedGap.files.filter((file) => unownedCoverage.acceptedFiles.has(file)),
+  );
+  if (acceptedUnclaimed.size > 0) {
+    for (let at = failures.length - 1; at >= 0; at -= 1) {
+      if (acceptedUnclaimed.has(failures[at].sourceFile)) failures.splice(at, 1);
+    }
+  }
+
   // The go.work drift check, keyed off the manifest's presence the way every
   // resolver keys off its language's manifest: no tracked root go.work, no
   // check and no mention. It ignores `options.paths` on purpose — two
@@ -622,9 +668,22 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     config !== null &&
     options.paths.length === 0 &&
     failures.length === 0 &&
-    (config.suppressions.length > 0 || config.depConstraints.length > 0)
+    (config.suppressions.length > 0 || config.depConstraints.length > 0 || coverageRows.length > 0)
   ) {
     const deadRows = [];
+    // The third dead table: a `coverage.unowned` row matching no unowned file
+    // across BOTH sets (`./coverage-acceptance.mjs`) accepts nothing — the
+    // files it covered are owned now, or the path was never right — and it is
+    // refused in the same sentence shape the native provider's stale
+    // `coverage.exempt` row has always gotten
+    // (`../providers/native/index.mjs`), under the same gate as its two
+    // siblings above this comment's block.
+    for (const { path, index } of unownedCoverage.dead) {
+      deadRows.push(
+        `coverage.unowned[${index}]: '${path}' matches no unowned file this run judged — either ` +
+          `the files it accepted are owned by a project now, or the path was never right`,
+      );
+    }
     config.suppressions.forEach((row, index) => {
       const fate = suppressionFate(row, now);
       if (fate === "waive") return;
@@ -739,25 +798,16 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
   // `coverage.complete` untouched — those belong to `unchecked`, and moving
   // this state into them would turn `check` red on trees whose only sin is a
   // root-level tooling script.
-  // The law that actually governed THIS run, not the one the workspace
-  // declared: `policySource` already carries the `--config` override and the
-  // resolved profile, workspace-relative. Subtracting it here rather than
-  // inside `resolveCommandContext` is forced — `resolvePolicy` takes the
-  // context as an argument, so it cannot run before it. `tsConfig` joins it
-  // because it is configuration by the same test, though every spelling of it
-  // is `.json` today and so never reaches the list.
-  const unownedGap = unownedGapWithoutRunConfiguration(commandContext.unownedGap, [
-    policySource,
-    commandContext.options.tsConfig,
-  ]);
-
+  // The subtraction of the run's own configuration, and the acceptance
+  // partition, both happened beside the policy above — `unownedCoverage` is
+  // that one computation's result, read here rather than recomputed.
   const coverageGaps = [
     ...(commandContext.provider === "nx" &&
     !commandContext.pluginGap.registered &&
     commandContext.pluginGap.manifests.length > 0
       ? [{ kind: "unregistered-plugin", manifests: commandContext.pluginGap.manifests }]
       : []),
-    ...(unownedGap.files.length > 0
+    ...(unownedCoverage.uncoveredUnowned.files.length > 0
       ? [
           {
             kind: "unowned-files",
@@ -766,8 +816,24 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
             // `moon.yml`), and the faces that render this carry no other way
             // to know which tree they are describing.
             provider: commandContext.provider,
-            languages: unownedGap.languages,
-            files: unownedGap.files,
+            languages: unownedCoverage.uncoveredUnowned.languages,
+            files: unownedCoverage.uncoveredUnowned.files,
+          },
+        ]
+      : []),
+    // The accepted half of both unowned sets, stated every run the
+    // acceptance is in force: an accepted hole is loud, never invisible —
+    // the report keeps naming the files, and `archkeep waivers` names each
+    // accepting row with its reason. Only the permanent unanswerable
+    // question (the warning above) and the unclaimed exit 3 are gone for
+    // these files.
+    ...(unownedCoverage.accepted.files.length > 0
+      ? [
+          {
+            kind: "accepted-unowned-files",
+            provider: commandContext.provider,
+            languages: unownedCoverage.accepted.languages,
+            files: unownedCoverage.accepted.files,
           },
         ]
       : []),

package/src/commands/context.mjs

@@ -228,6 +228,15 @@ export const WORKSPACE_MARKERS = [NX_CONFIG_FILE, ARCHKEEP_MODEL_FILE, MOON_DIR,
  *   failure (`../providers/native/coverage.mjs`'s `judgeCoverage`) and so
  *   already refuses the run with exit 3 — a gap beside it would be a second,
  *   quieter voice for a state that is answered loudly.
+ * @property {{files: string[]}} unclaimedGap The tracked Go, Rust or Python
+ *   files no project owns — the SAME files whose whole-file failures
+ *   `unclaimedFileFailures` already put in `analysis.failures`, listed a
+ *   second time as data so `./check.mjs` and `./waivers.mjs` can match the
+ *   policy's `coverage.unowned` acceptance rows against them
+ *   (`./coverage-acceptance.mjs`) without parsing a failure's sentence back
+ *   into a file list. Always `{files: []}` on a native workspace, whose own
+ *   `coverage.exempt` channel makes the policy key unreachable there
+ *   (`./policy.mjs`'s `resolvePolicy`).
  * @property {{file: string, project: string}[]} owned Every tracked file that
  *   belongs to a project, paired with its owning project — the ownership map
  *   `createWorkspace` already built. A command that needs to know WHICH project
@@ -305,20 +314,37 @@ const UNCLAIMED_CHECK_LANGUAGES = new Set(["go", "rust", "python"]);
  * tool reads — inventing one is out of scope here; this only detects and
  * reports.
  *
- * @param {{tracked: string[], owned: {file: string, project: string}[], providerLabel: string}} args
- * @returns {object[]}
+ * The file list and the failures it becomes are two exports on purpose:
+ * `./check.mjs` and `./waivers.mjs` need the LIST a second time — the
+ * `coverage.unowned` acceptance channel (`./coverage-acceptance.mjs`) matches
+ * its rows against exactly this set, and deriving the set from the failures'
+ * wording would bind an acceptance decision to a sentence.
+ *
+ * @param {{tracked: string[], owned: {file: string, project: string}[]}} args
+ * @returns {string[]}
  */
-function unclaimedFileFailures({ tracked, owned, providerLabel }) {
+function unclaimedAnalyzableFiles({ tracked, owned }) {
   const ownedFiles = new Set(owned.map(({ file }) => file));
-  return tracked
-    .filter((file) => UNCLAIMED_CHECK_LANGUAGES.has(languageOf(file)) && !ownedFiles.has(file))
-    .map((file) =>
-      fileFailure(
-        file,
-        `is not owned by any project in ${providerLabel} — every tracked Go, Rust or Python file ` +
-          `must belong to exactly one declared project, so its cross-project imports can be checked`,
-      ),
-    );
+  return tracked.filter(
+    (file) => UNCLAIMED_CHECK_LANGUAGES.has(languageOf(file)) && !ownedFiles.has(file),
+  );
+}
+
+/**
+ * The whole-file failures for `unclaimedAnalyzableFiles`' list — the shape
+ * argued in the comment above the two functions.
+ *
+ * @param {{files: string[], providerLabel: string}} args
+ * @returns {object[]}
+ */
+function unclaimedFileFailures({ files, providerLabel }) {
+  return files.map((file) =>
+    fileFailure(
+      file,
+      `is not owned by any project in ${providerLabel} — every tracked Go, Rust or Python file ` +
+        `must belong to exactly one declared project, so its cross-project imports can be checked`,
+    ),
+  );
 }
 
 /**
@@ -498,6 +524,7 @@ export function resolveCommandContext(
   let analyzedFiles;
   let pluginGap;
   let unownedGap;
+  let unclaimedGap;
   let exemptedFiles;
 
   if (hasNative) {
@@ -607,6 +634,12 @@ export function resolveCommandContext(
     // the reason `pluginGap` is: a reader must not have to tell "false" from
     // "this branch forgot".
     unownedGap = { files: [], languages: [] };
+    // Same statement one list over: native's unclaimed files are already
+    // whole-file failures in `discovered.failures` above, and the policy's
+    // `coverage.unowned` channel is refused outright on this provider
+    // (`./policy.mjs`'s `resolvePolicy`), so there is nothing here for that
+    // channel to match against.
+    unclaimedGap = { files: [] };
   } else if (hasMoon) {
     // Moon provider — reads graph from `moon project-graph --json`, the same
     // one-call contract as the Nx path: Moon already resolved projects, tags
@@ -683,11 +716,13 @@ export function resolveCommandContext(
     // native's own `discovered.failures` has (this branch's header already
     // analyzes the whole tree before `paths` narrows anything, for the same
     // reason).
+    const unclaimedFiles = unclaimedAnalyzableFiles({ tracked, owned });
     failures = [
       ...wholeTreeAnalysis.failures.filter((failure) => selectedFiles.has(failure.sourceFile)),
-      ...unclaimedFileFailures({ tracked, owned, providerLabel: "the Moon project graph" }),
+      ...unclaimedFileFailures({ files: unclaimedFiles, providerLabel: "the Moon project graph" }),
       ...pythonUnmodelledFailures(workspace),
     ];
+    unclaimedGap = { files: unclaimedFiles };
     analyzedFiles = wholeTreeAnalysis.analyzedFiles.filter((file) => selectedFiles.has(file));
     analyzed = analyzedFiles.length;
     // `coverage.exempt` is a native-only key (`../providers/native/coverage.mjs`'s
@@ -742,11 +777,13 @@ export function resolveCommandContext(
     // unconditionally, the same workspace-wide posture native's own
     // `discovered.failures` has, so a scoped `check <path>` cannot hide an
     // orphan file elsewhere in the tree by naming a path that excludes it.
+    const unclaimedFiles = unclaimedAnalyzableFiles({ tracked, owned });
     failures = [
       ...failures,
-      ...unclaimedFileFailures({ tracked, owned, providerLabel: "the Nx project graph" }),
+      ...unclaimedFileFailures({ files: unclaimedFiles, providerLabel: "the Nx project graph" }),
       ...pythonUnmodelledFailures(workspace),
     ];
+    unclaimedGap = { files: unclaimedFiles };
     // Same reason as the Moon branch above: `coverage.exempt` is a native-only
     // concept, so an Nx workspace has nothing to report here.
     exemptedFiles = [];
@@ -774,6 +811,7 @@ export function resolveCommandContext(
     options,
     pluginGap,
     unownedGap,
+    unclaimedGap,
     // Every tracked file that belongs to a project, paired with its project —
     // the ownership map `createWorkspace` already built (`own ./workspace.mjs`).
     // A command that needs to know WHICH project owns a file (the planning

package/src/commands/coverage-acceptance.mjs

@@ -0,0 +1,113 @@
+/**
+ * The policy's `coverage.unowned` acceptance channel, matched in ONE place
+ * against the two unowned-file sets a run establishes — so `check` and
+ * `waivers` cannot disagree about which files a row accepts.
+ *
+ * The channel exists for the Nx and Moon providers, whose project model has
+ * no home of its own for "this file is owned by no project, and we accept
+ * that, for this reason" — the decision `archkeep.json`'s `coverage.exempt`
+ * records on a native tree (`../providers/native/coverage.mjs`). Without it,
+ * the two unowned states those providers report are both permanent: the
+ * TS/JS/Vue gap (`./context.mjs`'s `unownedAnalyzableFiles`) warns on every
+ * run with no way to answer it, and a Go/Rust/Python unclaimed file
+ * (`unclaimedFileFailures` there) is a hard exit 3 with no accepted middle
+ * ground.
+ *
+ * A covered file is a RECORDED acceptance, never an invisible one: `check`
+ * still states every accepted file, as the `"accepted-unowned-files"`
+ * coverage-gap entry (`./check.mjs`), and `archkeep waivers` names each row
+ * with its reason and current coverage. What changes is only the permanent
+ * half — the warning stops re-asking a question someone answered, and the
+ * unclaimed exit 3 stops firing for a file whose acceptance is on record.
+ *
+ * ## Matching starts AFTER unowned-ness is decided
+ *
+ * The inputs here are lists something else already judged: `unownedGap` is
+ * the tolerated TS/JS/Vue list with the run's own configuration files
+ * subtracted (`./context.mjs`'s `unownedGapWithoutRunConfiguration`, applied
+ * by the caller), and `unclaimedFiles` is the Go/Rust/Python unclaimed list
+ * the same module computes. A row is matched against those lists ONLY —
+ * never against the tracked tree — so even a `**` row can never accept, or
+ * silence anything about, a file a project owns. That is the same guarantee
+ * the native provider's `coverage.exempt` states, kept by the same
+ * construction (`../providers/native/coverage.mjs`'s `judgeCoverage` filters
+ * `unowned` first and matches second).
+ *
+ * A row matching NOTHING across both sets is dead — the files it accepted
+ * are owned now, or the path was never right — and dead is a verdict the
+ * caller must refuse loudly, not a state to skip: `./check.mjs`'s dead-row
+ * block does, in the same sentence shape as the native stale-row refusal
+ * (`../providers/native/index.mjs`).
+ */
+import { languageOf } from "../analysis/registry.mjs";
+import { safeMatchesGlob } from "../rules/match.mjs";
+
+/**
+ * The languages a file list spans — sorted and distinct, derived beside the
+ * list it describes so no face can name a language the list does not contain
+ * (the same rule `./context.mjs`'s `unownedAnalyzableFiles` states).
+ *
+ * @param {string[]} files
+ * @returns {string[]}
+ */
+function languagesOf(files) {
+  return [...new Set(files.map((file) => languageOf(file)))].sort();
+}
+
+/**
+ * Partitions a run's unowned files into accepted and uncovered under the
+ * policy's `coverage.unowned` rows.
+ *
+ * Everything is derived from the arguments — no filesystem, no policy load —
+ * so a test drives it directly and the two callers (`./check.mjs`,
+ * `./waivers.mjs`) provably run the identical judgment.
+ *
+ * @param {{
+ *   rows: {path: string, reason: string}[],
+ *   unownedGap: {files: string[], languages: string[]},
+ *   unclaimedFiles: string[],
+ *   tracked: string[],
+ * }} args `rows` is `config.coverage?.unowned ?? []` — the validated table
+ *   (`../config.mjs`'s `findCoverageViolations`). `tracked` fixes the order
+ *   accepted files are reported in: `git ls-files` order, the same order
+ *   every other file list in a report keeps.
+ * @returns {{
+ *   rows: {path: string, reason: string, index: number, files: string[]}[],
+ *   dead: {path: string, reason: string, index: number}[],
+ *   accepted: {files: string[], languages: string[]},
+ *   acceptedFiles: Set<string>,
+ *   uncoveredUnowned: {files: string[], languages: string[]},
+ * }} `rows` is every declared row with the unowned files it currently
+ *   accepts; `dead` the subset accepting none. `accepted` is the union of
+ *   both sets' covered files in tracked order; `uncoveredUnowned` is
+ *   `unownedGap` minus the accepted files — the warning that survives.
+ *   Uncovered UNCLAIMED files need no list of their own: their whole-file
+ *   failures are already in the caller's hands, untouched.
+ */
+export function partitionUnownedCoverage({ rows, unownedGap, unclaimedFiles, tracked }) {
+  const candidates = [...unownedGap.files, ...unclaimedFiles];
+  const matched = rows.map((row, index) => ({
+    path: row.path,
+    reason: row.reason,
+    index,
+    files: candidates.filter((file) => safeMatchesGlob(file, row.path)),
+  }));
+  const acceptedFiles = new Set(matched.flatMap((entry) => entry.files));
+  const acceptedInTrackedOrder = tracked.filter((file) => acceptedFiles.has(file));
+  const uncoveredFiles = unownedGap.files.filter((file) => !acceptedFiles.has(file));
+  return {
+    rows: matched,
+    dead: matched
+      .filter((entry) => entry.files.length === 0)
+      .map(({ path, reason, index }) => ({ path, reason, index })),
+    accepted: {
+      files: acceptedInTrackedOrder,
+      languages: languagesOf(acceptedInTrackedOrder),
+    },
+    acceptedFiles,
+    uncoveredUnowned: {
+      files: uncoveredFiles,
+      languages: languagesOf(uncoveredFiles),
+    },
+  };
+}