@ecoma-io/archkeep 0.13.0 → 0.15.0

package/src/commands/check.mjs

@@ -14,10 +14,12 @@ import { join } from "node:path";
 
 import { fileFailure, isWholeFileFailure } from "../analysis/source-util.mjs";
 import { tsconfigPathsFacts } from "../analysis/typescript.mjs";
+import { stripTrailingSlashes } from "../path-util.mjs";
 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";
@@ -154,7 +156,7 @@ function declaredEdgeManifest({ provider, graph }, sourceProject) {
   // spelling) — and `./project.json` is a different string from
   // `project.json` to every consumer that compares paths, this file's own
   // SARIF `uri` included.
-  const scoped = typeof root === "string" ? root.replace(/\/+$/u, "") : "";
+  const scoped = typeof root === "string" ? stripTrailingSlashes(root) : "";
   return scoped === "" || scoped === "." ? site.file : `${scoped}/${site.file}`;
 }
 /**
@@ -248,6 +250,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 +669,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 +799,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 +817,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 = [];
@@ -765,8 +802,7 @@ export function resolveCommandContext(
   // can name it correctly.
   return {
     root,
-    provider: hasMoon ? "moon" : hasNative ? "native" : "nx",
-    marker: hasMoon ? moonMarker : hasNative ? ARCHKEEP_MODEL_FILE : NX_CONFIG_FILE,
+    ...workspaceNames(hasMoon, hasNative, moonMarker),
     graph,
     workspace,
     tracked,
@@ -774,6 +810,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
@@ -783,6 +820,45 @@ export function resolveCommandContext(
   };
 }
 
+/**
+ * The provider/marker pair a workspace root carries, derived from marker
+ * presence through the one mapping every envelope header must agree on.
+ * `resolveCommandContext` reads it for its own context; a caller that needs
+ * the identity WITHOUT judging the tree — an envelope header over a run whose
+ * analyzed revisions each carry their own contexts (`./evolution.mjs`) —
+ * calls `describeWorkspaceRoot`, so the vocabulary ("nx"/"native"/"moon" and
+ * the marker that decided it) has exactly one home.
+ *
+ * @param {boolean} hasMoon Whether a Moon directory marks the root.
+ * @param {boolean} hasNative Whether `archkeep.json` marks the root.
+ * @param {string|null} moonMarker Which Moon directory is present.
+ * @returns {{provider: "nx" | "moon" | "native", marker: string}}
+ */
+function workspaceNames(hasMoon, hasNative, moonMarker) {
+  return {
+    provider: hasMoon ? "moon" : hasNative ? "native" : "nx",
+    marker: hasMoon ? moonMarker : hasNative ? ARCHKEEP_MODEL_FILE : NX_CONFIG_FILE,
+  };
+}
+
+/**
+ * The workspace identity of `root` — which project model governs it and which
+ * marker decided that — without reading one source file or building one graph.
+ * The single-project-model gate runs here exactly as it does in
+ * `resolveCommandContext`: both markers present is refused here for the same
+ * reason it is refused there, because a caller about to describe this
+ * workspace must not name a model the full read would have refused.
+ *
+ * @param {string} root Absolute path to the workspace root.
+ * @returns {{provider: "nx" | "moon" | "native", marker: string}}
+ * @throws {Error} when more than one project-model marker is present
+ *   (`requireSingleProjectModel`).
+ */
+export function describeWorkspaceRoot(root) {
+  const { hasNative, moonMarker } = requireSingleProjectModel(root);
+  return workspaceNames(moonMarker !== null, hasNative, moonMarker);
+}
+
 // Re-exported so a caller that only needs "does this tree look like a
 // workspace at all" (`../../cli.mjs`'s `optionsForUsage`) is not forced to
 // duplicate the marker check a second time; `DEFAULT_OPTIONS` rides along for

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),
+    },
+  };
+}