@ecoma-io/archkeep 0.20.1 → 0.22.0

package/src/commands/diff.mjs

@@ -40,9 +40,9 @@
  */
 import { readFileSync } from "node:fs";
 
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
 import { computeRuleImpact } from "./edge-constraints.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { SCHEMA_VERSION } from "../report/json.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatDiffReport } from "../report/diff-text.mjs";
@@ -349,11 +349,14 @@ export function computeDiff(baseline, head) {
  *   When omitted, reads from the real filesystem. `config` is the loaded
  *   boundary config; when provided, rule-impact analysis is computed alongside
  *   the structural diff.
- * @returns {{status: "ok"|"no-verdict", diff: object, coverage: object,
- *   report: {text: string, json: string}}}
- * @throws {Error} when the baseline cannot be read or is incomplete, when
- *   the head is incomplete, or when an Nx workspace has polyglot manifests
- *   but the plugin is not registered.
+ * @returns {{status: "ok"|"no-verdict", diff?: object, coverage: object,
+ *   report: {text: string, json: string}}} `diff` is absent under
+ *   `status: "no-verdict"` — the coverage refusal (#608) withholds the
+ *   comparison, and the envelope's `coverage` block is the whole answer.
+ * @throws {Error} when the baseline cannot be read or is incomplete, or when
+ *   an Nx workspace has polyglot manifests but the plugin is not registered
+ *   (the inline throw in the body). An incomplete head returns the
+ *   structured no-verdict envelope instead of throwing (#608).
  */
 export function diffCommand(
   baselinePath,
@@ -379,19 +382,18 @@ export function diffCommand(
   // is a caller error, not a workspace fact, and it should name the file.
   const baseline = readBaseline(baselinePath);
 
-  // Refuse an incomplete head — same reasoning as the incomplete baseline
-  // refusal: every "added" or "removed" entry would be ambiguous.
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: the head graph has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every "added" or ` +
-        `"removed" entry in the diff would be ambiguous between a real change and a coverage ` +
-        `gap. Fix the unanalyzed files and re-run.`,
-    );
+  // Refuse an incomplete head through the one structured contract
+  // `./coverage-verdict.mjs` builds (#608): the diff is withheld in-band —
+  // status "no-verdict", exit 3, a `coverage` block naming every file and
+  // site the run could not judge — where a parser and `--output` can read it.
+  // The reasoning is the incomplete-baseline refusal's: every "added" or
+  // "removed" entry would be ambiguous. That baseline refusal stays a throw —
+  // `parseBaseline` above throws it through the default reader — because a
+  // baseline nobody captured correctly is a caller error about a file, not a
+  // coverage fact about THIS tree.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "diff", commandContext, what: "diffing the head graph" });
   }
 
   const head = buildHeadSnapshot(commandContext);
@@ -404,9 +406,7 @@ export function diffCommand(
     analyzedFiles: commandContext.analysis.analyzed,
     imports: commandContext.analysis.imports.length,
     notAnalyzed: [],
-    blindSpots: commandContext.analysis.failures
-      .filter((f) => !isWholeFileFailure(f))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: completeness.blindSpots,
     notes: [],
   };
 
@@ -417,6 +417,12 @@ export function diffCommand(
       projects: baseline.projects.length,
       edges: baseline.dependencies.length,
       toolVersion: baseline.toolVersion,
+      // The provenance the baseline itself recorded — which commit, remote,
+      // and dirtiness the captured side names (#609). The head side's own
+      // provenance rides the envelope's `workspace.provenance`; without the
+      // baseline's, a consumer could not tell WHICH revision the empty or
+      // non-empty diff is measured against.
+      provenance: baseline.provenance ?? null,
     },
     head: { projects: head.projects.length, edges: head.dependencies.length },
     addedProjects: diff.addedProjects,
@@ -525,8 +531,9 @@ export function diffCommand(
     // no depConstraints violations were introduced or resolved on the changed
     // edges. Run `check` for the complete verdict.
     coverage.notes.push(
-      "per-edge rule-impact covers only depConstraints (3 of 15 violation types). " +
-        "A dependency with no rule-impact may still violate npm-ban, circular-dependency, " +
+      "per-edge rule-impact covers only depConstraints (3 of 15 violation types; standing " +
+        "edges adjacent to a tags-changed project are re-judged under both sides' tags). A " +
+        "dependency with no rule-impact may still violate npm-ban, circular-dependency, " +
         "lazy-load, or other rules that require import-site details. Run check for the " +
         "complete verdict.",
     );

package/src/commands/discover.mjs

@@ -40,7 +40,11 @@
  * byte-identical text and JSON — the same promise `graph`'s snapshots make,
  * which is what lets a consumer `diff` two proposals meaningfully.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { evaluateDiscovery } from "../governance/discovery-proposal.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatDiscoverReport } from "../report/discover-text.mjs";
@@ -131,6 +135,8 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
     .filter(isWholeFileFailure)
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
 
+  const blindSpotCount = unresolvableLiteralCount(analysis.failures);
+
   const observed = buildObserved(commandContext);
 
   const proposal = propose ? evaluateDiscovery(observed) : null;
@@ -139,16 +145,32 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
   // proposal's name: every candidate edge would be ambiguous between "gone"
   // and "never seen". Refuse loudly — the same reasoning `drift`'s refusal
   // gives — rather than print a proposal and a warning that it may be lying.
-  if (propose && notAnalyzed.length > 0) {
+  // An unresolvable site is the same fabrication at site granularity (#595):
+  // the edge out of it may be missing, and a candidate built over a gap is
+  // still a guess.
+  if (propose && (notAnalyzed.length > 0 || blindSpotCount > 0)) {
     throw new Error(
-      `archkeep: discover --propose has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every candidate ` +
-        `would be ambiguous between "gone" and "never seen". Fix the unanalyzed files and ` +
-        `re-run.`,
+      `archkeep: discover --propose has incomplete coverage — ` +
+        [
+          notAnalyzed.length > 0
+            ? `${notAnalyzed.length} file${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed`
+            : null,
+          blindSpotCount > 0
+            ? `${blindSpotCount} import site${blindSpotCount === 1 ? "" : "s"} could not be resolved`
+            : null,
+        ]
+          .filter(Boolean)
+          .join(", ") +
+        `, so every candidate would be ambiguous between "gone" and "never seen". ` +
+        `Fix the unresolved files and sites and re-run.`,
     );
   }
 
-  const complete = notAnalyzed.length === 0;
+  // An unresolvable site was seen but never judged (#595): the snapshot's
+  // edge list under-represents the tree wherever that site would have drawn
+  // one, so `complete` cannot be claimed over it. It still reports — status
+  // no-verdict, exit 3 — naming the site in `coverage.blindSpots`.
+  const complete = notAnalyzed.length === 0 && blindSpotCount === 0;
   const status = complete ? "ok" : "no-verdict";
   const exitCode = complete ? 0 : 3;
 
@@ -158,9 +180,7 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
     analyzedFiles: analysis.analyzed,
     imports: analysis.imports.length,
     notAnalyzed,
-    blindSpots: analysis.failures
-      .filter((failure) => !isWholeFileFailure(failure))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: blindSpotRows(analysis.failures),
     notes: [],
   };
 

package/src/commands/drift.mjs

@@ -31,9 +31,11 @@
  *
  * - the intent file cannot be read or parsed (strict JSON, validated) → throw
  *   → exit 3;
- * - the observed side is incomplete (`notAnalyzed` non-empty) → exit 3, the
- *   same reasoning as `diff` — every "project missing" would be ambiguous
- *   between "gone" and "never seen";
+ * - the observed side is incomplete → the structured no-verdict refusal
+ *   (`./coverage-verdict.mjs`), exit 3, the same reasoning as `diff` — every
+ *   "project missing" would be ambiguous between "gone" and "never seen" —
+ *   but in the envelope, not on stderr: the same status/coverage contract
+ *   `graph`/`context` return over the same condition (#608);
  * - an Nx workspace has polyglot manifests but the plugin is not registered →
  *   exit 3, the same refusal `graph`/`diff` make;
  * - a boundary or row side matched no observed project → exit 3, the same
@@ -74,8 +76,9 @@
  * everywhere, never `localeCompare` — so two runs over an unchanged tree and
  * intent produce byte-identical text and JSON.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { blindSpotRows } from "../analysis/source-util.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { judgeIntent } from "../architecture-intent/judge.mjs";
@@ -290,11 +293,13 @@ function intentRows(intent) {
  *   row's `decisionRef`. `configError` carries a boundary-policy load failure
  *   the caller chose not to throw at the load site — rethrown here, unchanged,
  *   only if an intent row actually cites something.
- * @returns {Promise<{status: "ok", drift: object, coverage: object,
+ * @returns {Promise<{status: "ok"|"no-verdict", drift?: object, coverage: object,
  *   report: {text: string, json: string}}>}
- * @throws {Error} on every condition the header lists, all exit-3 class, plus
- *   a malformed ADR registry — the same loud refusal `provenance` makes for
- *   the identical read.
+ *   `status: "no-verdict"` carries no `drift` payload — the verdict was
+ *   withheld, and the envelope's `coverage` block is the whole answer (#608).
+ * @throws {Error} on every condition the header lists except the coverage one,
+ *   which returns instead of throwing, plus a malformed ADR registry — the
+ *   same loud refusal `provenance` makes for the identical read.
  */
 export async function driftCommand(commandContext, io = {}) {
   const { root, provider, marker, analysis } = commandContext;
@@ -302,16 +307,13 @@ export async function driftCommand(commandContext, io = {}) {
   refuseIncompleteGraph(commandContext);
 
   // A drift verdict cannot be established over a tree it could not fully read.
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: drift has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every "project missing" ` +
-        `would be ambiguous between "gone" and "never seen". Fix the unanalyzed files and re-run.`,
-    );
+  // The refusal is the structured one the graph family speaks (#608): the
+  // verdict is withheld in-band — status "no-verdict", exit 3, a `coverage`
+  // block naming every file and site the run could not judge — where a parser
+  // and `--output` can read it, not on stderr where only a human can.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "drift", commandContext, what: "judging drift" });
   }
 
   const intent = await (io.loadIntentOverride ?? loadIntent)(root, {
@@ -398,9 +400,7 @@ export async function driftCommand(commandContext, io = {}) {
     notAnalyzed: [],
     // Drift reads only the graph — provider failures are the same blind spots
     // every other command reports, and a blind spot never prevents a verdict.
-    blindSpots: analysis.failures
-      .filter((failure) => !isWholeFileFailure(failure))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: blindSpotRows(analysis.failures),
     // Coverage notes (e.g. an `optional: true` allowed row the team has not
     // built yet) ride here so "optional and absent" never reads as "never
     // checked".

package/src/commands/edge-constraints.mjs

@@ -42,6 +42,7 @@
  * enough that merging them would blur the layer boundary the AGENTS.md guards.
  */
 
+import { edgeEvolutionIdentity } from "../governance/evolution-event.mjs";
 import { renderMessage } from "../rules/messages.mjs";
 import { buildReachability } from "../rules/reachability.mjs";
 import {
@@ -212,7 +213,9 @@ export function declaredEdgeViolationsForCheck(graph, depConstraints) {
  * constraint table. The constraint table is the current one — it is what `check`
  * would judge from today, not what some past version judged from.
  *
- * @param {{addedEdges: object[], removedEdges: object[]}} diff From `computeDiff`.
+ * @param {{addedEdges: object[], removedEdges: object[],
+ *   changedProjects?: {name: string, changes: {field: string, baseline?: unknown,
+ *   head?: unknown}[]}[]}} diff From `computeDiff`.
  * @param {object} headNodes The head graph's `nodes` map (for tag lookups).
  * @param {object} headDependencies The head graph's `dependencies` map (for reachability).
  * @param {object[]} baselineProjects The baseline snapshot's project list (each
@@ -285,6 +288,49 @@ export function computeRuleImpact(
     }
   }
 
+  // Standing edges whose legality a tags-only change can flip (#600): the
+  // edge moved in neither direction, so the loops above never see it, but
+  // the tags its judgment reads did. An edge adjacent to a project whose
+  // tags changed is judged under BOTH sides' tags — violating under head
+  // where it was legal under baseline is an introduced violation, the
+  // inverse is a resolved one, and a violation under both is pre-existing
+  // (unchanged legality is `check`'s finding, not this diff's). Edges the
+  // loops above already judged are skipped by identity, so no edge is ever
+  // reported twice.
+  const tagChangedNames = new Set(
+    (diff.changedProjects ?? [])
+      .filter((project) => (project.changes ?? []).some((change) => change.field === "tags"))
+      .map((project) => project.name),
+  );
+  if (tagChangedNames.size > 0) {
+    const judged = new Set(
+      [...diff.addedEdges, ...diff.removedEdges].map((edge) => edgeEvolutionIdentity(edge)),
+    );
+    for (const edge of baselineDependencies) {
+      if (!(tagChangedNames.has(edge.source) || tagChangedNames.has(edge.target))) continue;
+      if (judged.has(edgeEvolutionIdentity(edge))) continue;
+      const headViolations = judgeEdge(
+        edge,
+        headNodes,
+        headDependencies,
+        depConstraints,
+        headReachability,
+      );
+      const baselineViolations = judgeEdge(
+        edge,
+        baselineNodes,
+        baselineDepsMap,
+        depConstraints,
+        baselineReachability,
+      );
+      if (headViolations.length > 0 && baselineViolations.length === 0) {
+        introduced.push(...headViolations);
+      } else if (baselineViolations.length > 0 && headViolations.length === 0) {
+        resolved.push(...baselineViolations);
+      }
+    }
+  }
+
   return { introduced, resolved };
 }