@ecoma-io/archkeep 0.20.1 → 0.22.0

package/src/commands/evolution.mjs

@@ -80,6 +80,7 @@ import { debtChangeDiff, debtFactId, driftFactOf } from "../governance/debt-ledg
 import { computeAffectedDecisions } from "../governance/decision-lineage.mjs";
 import {
   classifyEvolution,
+  edgeEvolutionIdentity,
   eventDedupeKey,
   eventId,
   EVOLUTION_EVENT_SCHEMA_VERSION,
@@ -939,23 +940,24 @@ function buildEvolutionSummary(comparisons) {
         comparisons.flatMap((c) => c.observed.projects.changed.map((p) => p.name ?? p)),
       ),
     },
+    // The identity string is the ONE spelling `edgeEvolutionIdentity` owns —
+    // the same spelling `affected.boundaries` and every stored event carry.
+    // An edge without a complete triple has no identity to name, so it is
+    // dropped from the union and counted into `unnamedEdges` rather than
+    // leaking an object serialization into a field of identity strings.
     edges: {
       added: unique(
         comparisons.flatMap((c) =>
-          c.observed.edges.added.map((e) =>
-            e.source && e.target && e.type
-              ? `${e.source}→${e.target}:${e.type}`
-              : JSON.stringify(e),
-          ),
+          c.observed.edges.added
+            .filter((e) => e.source && e.target && e.type)
+            .map((e) => edgeEvolutionIdentity(e)),
         ),
       ),
       removed: unique(
         comparisons.flatMap((c) =>
-          c.observed.edges.removed.map((e) =>
-            e.source && e.target && e.type
-              ? `${e.source}→${e.target}:${e.type}`
-              : JSON.stringify(e),
-          ),
+          c.observed.edges.removed
+            .filter((e) => e.source && e.target && e.type)
+            .map((e) => edgeEvolutionIdentity(e)),
         ),
       ),
     },
@@ -983,6 +985,21 @@ function buildEvolutionSummary(comparisons) {
   };
 
   const notes = unique(comparisons.flatMap((c) => c.notes ?? []));
+  const unnamedEdges = comparisons.reduce(
+    (count, c) =>
+      count +
+      [...c.observed.edges.added, ...c.observed.edges.removed].filter(
+        (e) => !(e.source && e.target && e.type),
+      ).length,
+    0,
+  );
+  if (unnamedEdges > 0) {
+    // The house shape for "we could not name it": a note naming the gap,
+    // never a silent drop dressed as a clean union.
+    notes.push(
+      `${unnamedEdges} changed edge(s) carry no complete identity and are not named in observed.edges`,
+    );
+  }
   return {
     transitions: comparisons.length,
     disposition,

package/src/commands/explain.mjs

@@ -79,7 +79,11 @@
  * was: the field, and its rendered lines, exist only when the comparison was
  * requested.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
 import { evaluate } from "../rules/index.mjs";
 import { findConstraintsFor } from "../rules/tags.mjs";
@@ -369,7 +373,13 @@ export function explainCommand(site, commandContext, config, options = {}) {
     .filter(isWholeFileFailure)
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
 
-  const complete = notAnalyzed.length === 0;
+  // An unresolvable site was seen but never judged (#595): the graph is
+  // missing whatever edge that site would have drawn, and rules that judge
+  // the whole graph (circularity, lazy loading) would answer over a gap. The
+  // explanation still reports — status no-verdict — naming the site in
+  // `coverage.blindSpots`, the same contract `graph`/`discover` run.
+  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+  const complete = notAnalyzed.length === 0 && blindSpotCount === 0;
   const status = complete ? "ok" : "no-verdict";
 
   // Find the import record at this site.
@@ -422,14 +432,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
         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: blindSpotRows(commandContext.analysis.failures),
         notes: [],
       };
 
@@ -576,9 +579,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
     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: blindSpotRows(commandContext.analysis.failures),
     notes: [],
   };
 

package/src/commands/fitness.mjs

@@ -45,10 +45,11 @@
  * sorted; JSON rides `canonicalizeJson`. Two runs over an unchanged tree and
  * policy produce byte-identical text and JSON.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { blindSpotRows } from "../analysis/source-util.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatFitnessSection } from "../report/text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { driftForCheck } from "./drift.mjs";
 import {
   evaluateFitness,
@@ -114,9 +115,13 @@ export function declaresFitness(config) {
  *
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {{config?: object|null}} [io] The loaded policy, injectable for tests.
- * @returns {Promise<{status: "ok"|"findings"|"no-verdict", fitness: object, coverage: object,
- *   report: {text: string, json: string}}>}
- * @throws {Error} on every condition the header lists, all exit-3 class.
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict", fitness?: object,
+ *   coverage: object, report: {text: string, json: string}}>}
+ *   `status: "no-verdict"` from the coverage refusal carries no `fitness`
+ *   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.
  */
 export async function fitnessCommand(commandContext, io = {}) {
   const { root, provider, marker, analysis } = commandContext;
@@ -129,18 +134,16 @@ export async function fitnessCommand(commandContext, io = {}) {
     );
   }
 
-  // A verdict over a tree it could not fully read is a guess. Same refusal
-  // `drift`/`graph`/`diff` make for the same condition.
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: fitness has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every coverage ` +
-        `and graph claim would be ambiguous between "clean" and "never seen". Fix the ` +
-        `unanalyzed files and re-run.`,
-    );
+  // A verdict over a tree it could not fully read is a guess. Refused through
+  // the one structured contract `./coverage-verdict.mjs` builds (#608) — this
+  // gate used to check whole-file failures only and then claim
+  // `coverage.complete: true` beside `blindSpots` that could carry an unjudged
+  // site, which the envelope law refuses as a programming error. The unified
+  // completeness returns the no-verdict envelope instead, for every axis the
+  // envelope law already withholds over.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "fitness", commandContext, what: "judging fitness" });
   }
 
   // `drift-free` judges the SAME verdict-shaped intent `check`'s fold builds —
@@ -192,9 +195,7 @@ export async function fitnessCommand(commandContext, io = {}) {
     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/graph.mjs

@@ -29,7 +29,11 @@
  */
 import { createHash } from "node:crypto";
 
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { canonicalizeJson } from "../canonical.mjs";
 import { DEFAULT_WORKSPACE_LAYOUT } from "../rules/specifiers.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
@@ -222,7 +226,14 @@ export function graphCommand(commandContext, { config = null } = {}) {
     .filter(isWholeFileFailure)
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
 
-  const complete = notAnalyzed.length === 0;
+  // An unresolvable import site was seen but never judged (#595): the edges
+  // out of it may be missing from this snapshot, so the snapshot must not
+  // claim `complete` over it. It still reports — status no-verdict, exit 3 —
+  // naming the site in `coverage.blindSpots`, the same contract `check` runs.
+  const blindSpots = blindSpotRows(commandContext.analysis.failures);
+  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+
+  const complete = notAnalyzed.length === 0 && blindSpotCount === 0;
   const status = complete ? "ok" : "no-verdict";
   const exitCode = complete ? 0 : 3;
 
@@ -245,9 +256,7 @@ export function graphCommand(commandContext, { config = null } = {}) {
     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,
     notes: [],
   };
 

package/src/commands/health.mjs

@@ -43,7 +43,11 @@
  * It does not print, and it does not decide the process's exit code —
  * `../../cli.mjs` owns those (`./README.md`).
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatHealthReport } from "../report/health-text.mjs";
@@ -108,7 +112,12 @@ export function healthCommand(commandContext, io = {}) {
   const edges = buildDependencies(graph.dependencies);
 
   // The run's coverage facts, the same shape every command's envelope carries.
-  const fileComplete = analysis.failures.filter(isWholeFileFailure).length === 0;
+  // An unresolvable site is a fact the run saw but never judged (#595) —
+  // metrics measured over it would read precision the run does not have,
+  // so it defeats file completeness the way a whole-file failure does.
+  const fileComplete =
+    analysis.failures.filter(isWholeFileFailure).length === 0 &&
+    unresolvableLiteralCount(analysis.failures) === 0;
   // The graph is complete only when the files are AND the graph actually sees
   // every polyglot edge — an Nx workspace with an unregistered plugin carries
   // a graph with no Go/Rust/Python edges, which `graph`/`impact` refuse and
@@ -123,9 +132,7 @@ export function healthCommand(commandContext, io = {}) {
     notAnalyzed: analysis.failures
       .filter(isWholeFileFailure)
       .map(({ sourceFile, reason }) => ({ file: sourceFile, reason })),
-    blindSpots: analysis.failures
-      .filter((f) => !isWholeFileFailure(f))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: blindSpotRows(analysis.failures),
     notes: graphComplete
       ? []
       : [

package/src/commands/history.mjs

@@ -74,12 +74,16 @@ import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { containmentViolation } from "../containment.mjs";
 import { classifyEvolution } from "../governance/evolution-event.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatHistoryReport } from "../report/history-text.mjs";
-import { computeDiff, edgeIdentityKey, parseBaseline } from "./diff.mjs";
+import { computeDiff, parseBaseline } from "./diff.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
@@ -397,8 +401,12 @@ export function classifyTransition(from, to) {
         changed: diff.changedProjects.map((project) => project.name),
       },
       edges: {
-        added: diff.addedEdges.map(edgeIdentityKey),
-        removed: diff.removedEdges.map(edgeIdentityKey),
+        // The raw triples — `classifyEvolution` maps them through its own
+        // identity spelling (`edgeEvolutionIdentity`), so `affected.boundaries`
+        // carries the canonical strings every other event surface uses, not
+        // this module's diff-internal key spelling.
+        added: diff.addedEdges,
+        removed: diff.removedEdges,
       },
       policyChanged: meta.policyChanged,
       policyOneSided: meta.policyOneSided,
@@ -554,10 +562,23 @@ export function historyCommand(
     const notAnalyzed = commandContext.analysis.failures
       .filter(isWholeFileFailure)
       .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-    if (notAnalyzed.length > 0) {
+
+    const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+    if (notAnalyzed.length > 0 || blindSpotCount > 0) {
       throw new Error(
-        `archkeep: the head graph has incomplete coverage — ${notAnalyzed.length} file` +
-          `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so a captured snapshot ` +
+        `archkeep: the head graph 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 
+a captured snapshot ` +
           `would under-represent the real architecture. Fix the unanalyzed files and re-run.`,
       );
     }
@@ -608,14 +629,7 @@ export function historyCommand(
           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: blindSpotRows(commandContext.analysis.failures),
           notes: [],
         },
         result: { ...head, policy: headPolicy ?? undefined },