@ecoma-io/archkeep 0.22.0 → 0.22.2

package/src/commands/delta-snapshot.mjs

@@ -47,6 +47,7 @@
  */
 import { readFileSync } from "node:fs";
 
+import { canonicalJsonReplacer } from "../canonical.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 
 /** The only snapshot schemaVersion this module writes and reads. */
@@ -262,16 +263,23 @@ export function buildEvidenceSnapshot({
 /**
  * Renders the snapshot as deterministic JSON text.
  *
- * Deterministic because `buildEvidenceSnapshot` constructs every key in a
- * fixed order and sorts every array whose source does not guarantee order;
- * two captures over one unchanged tree produce byte-identical files, which is
- * what makes a plain `diff` of two baselines meaningful.
+ * Deterministic by mechanism, not by constructor discipline: the text is
+ * produced through `../canonical.mjs`'s `canonicalJsonReplacer`, which sorts
+ * plain-object keys at every depth — the same canonicalizer the graph-snapshot
+ * family's `snapshotIdentity` hashes with. That is load-bearing because two of
+ * the stored inputs (`records`, `graph.workspaceLayout`) arrive verbatim from
+ * upstream code that owns their nested key order; sorting at serialize time is
+ * what makes the bytes a function of what the snapshot MEANS. Array element
+ * order is the only order the format keeps, and `buildEvidenceSnapshot` sorts
+ * every array whose source does not guarantee it. Two captures over one
+ * unchanged tree produce byte-identical files, which is what makes a plain
+ * `diff` of two baselines meaningful.
  *
  * @param {object} snapshot From `buildEvidenceSnapshot`.
  * @returns {string} The JSON text, newline-terminated.
  */
 export function serializeEvidenceSnapshot(snapshot) {
-  return `${JSON.stringify(snapshot, null, 2)}\n`;
+  return `${JSON.stringify(snapshot, canonicalJsonReplacer, 2)}\n`;
 }
 
 /**

package/src/commands/discover.mjs

@@ -20,18 +20,23 @@
  *
  * ## The empty-result invariant
  *
- * A workspace the run could not fully read (`notAnalyzed` non-empty) returns
- * `status: "no-verdict"` → exit 3, the same refusal `graph`/`drift` make:
- * every missing edge would be ambiguous between "gone" and "never seen".
- * An Nx workspace with polyglot manifests and no plugin registration is
- * refused the same way `graph` refuses it — the graph would silently
- * under-represent the real architecture, and a candidate derived from it
- * would be a fabrication wearing a proposal's name.
+ * Completeness comes from `./coverage-verdict.mjs`'s shared constructor —
+ * the same three-axis law (no whole-file failure, no unjudged blind spot,
+ * at least one file analyzed) that `graph` and `check` judge completeness
+ * over. The graph-family restatement this replaces is how the zero-analysis
+ * axis went missing here (#619).
  *
  * A workspace with zero projects is NOT a refusal: it is the empty proposal
  * with `unknown: true` (`evaluateDiscovery`'s contract), because zero observed
  * projects is a complete observation — the honest answer is "nothing to
- * propose", not a fabricated candidate set.
+ * propose", not a fabricated candidate set. The constructor's zero-analysis
+ * clause is overridden for this case: if there is nothing to observe, the
+ * observation is complete.
+ *
+ * An Nx workspace with polyglot manifests and no plugin registration is
+ * refused the same way `graph` refuses it — the graph would silently
+ * under-represent the real architecture, and a candidate derived from it
+ * would be a fabrication wearing a proposal's name.
  *
  * ## Determinism
  *
@@ -40,14 +45,11 @@
  * byte-identical text and JSON — the same promise `graph`'s snapshots make,
  * which is what lets a consumer `diff` two proposals meaningfully.
  */
-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";
+import { coverageIncompleteReasons } from "../verdict.mjs";
+import { coverageVerdict } from "./coverage-verdict.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { refuseIncompleteGraph } from "./drift.mjs";
@@ -131,32 +133,49 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
 
   refuseIncompleteGraph(commandContext);
 
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  const blindSpotCount = unresolvableLiteralCount(analysis.failures);
-
   const observed = buildObserved(commandContext);
 
   const proposal = propose ? evaluateDiscovery(observed) : null;
 
+  // The completeness verdict is the shared constructor's, not this file's:
+  // restating the axes here is how the `analyzed > 0` term went missing from
+  // this face (#619 — a run that judged no file at all used to report `ok` /
+  // `complete: true` / exit 0, byte-for-byte the envelope a clean workspace
+  // gets). `coverageVerdict` owns the one law — no whole-file failure, no
+  // unjudged site, at least one file analyzed — and the same return shape
+  // the envelope and the text face both read.
+  //
+  // One override: a workspace with zero projects is a complete observation
+  // (there is nothing to observe), so the zero-analysis clause does not
+  // withhold from it. `evaluateDiscovery`'s contract returns `unknown: true`
+  // over an empty project list, and that answer is honest — it does not
+  // claim completeness over nothing.
+  const verdict = coverageVerdict(commandContext);
+  const hasProjects = observed.projects.length > 0;
+  const { complete, status, exitCode } = verdict;
+  // When there are no projects, override the zero-analysis withdrawal: an
+  // empty observation is a complete observation, and the `unknown` proposal
+  // is the honest answer.
+  const effectiveComplete = hasProjects ? complete : true;
+  const effectiveStatus = hasProjects ? status : "ok";
+  const effectiveExitCode = hasProjects ? exitCode : 0;
+
   // A proposal over an unread tree would be a fabrication wearing a
   // 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.
   // 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)) {
+  // still a guess. Use the shared verdict's counts rather than re-deriving.
+  if (propose && (verdict.notAnalyzed.length > 0 || verdict.blindSpotCount > 0)) {
     throw new Error(
       `archkeep: discover --propose has incomplete coverage — ` +
         [
-          notAnalyzed.length > 0
-            ? `${notAnalyzed.length} file${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed`
+          verdict.notAnalyzed.length > 0
+            ? `${verdict.notAnalyzed.length} file${verdict.notAnalyzed.length === 1 ? "" : "s"} could not be analyzed`
             : null,
-          blindSpotCount > 0
-            ? `${blindSpotCount} import site${blindSpotCount === 1 ? "" : "s"} could not be resolved`
+          verdict.blindSpotCount > 0
+            ? `${verdict.blindSpotCount} import site${verdict.blindSpotCount === 1 ? "" : "s"} could not be resolved`
             : null,
         ]
           .filter(Boolean)
@@ -166,21 +185,22 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
     );
   }
 
-  // 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;
+  // The clauses the text face renders over an incomplete run, worded by the
+  // same function `verdictFor` joins into `decision.reason` — one wording,
+  // two renderings, and neither can drift from the other.
+  const coverageIncomplete = coverageIncompleteReasons({
+    unchecked: verdict.notAnalyzed.length,
+    blindSpots: verdict.blindSpotCount,
+    analyzed: analysis.analyzed,
+  });
 
   const coverage = {
-    complete,
+    complete: effectiveComplete,
     projects: observed.projects.length,
     analyzedFiles: analysis.analyzed,
     imports: analysis.imports.length,
-    notAnalyzed,
-    blindSpots: blindSpotRows(analysis.failures),
+    notAnalyzed: verdict.notAnalyzed,
+    blindSpots: verdict.blindSpots,
     notes: [],
   };
 
@@ -196,14 +216,14 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
   const envelope = jsonEnvelope({
     command: "discover",
     context,
-    status,
-    exitCode,
+    status: effectiveStatus,
+    exitCode: effectiveExitCode,
     coverage,
     result: { discovery, ...(proposal ? { proposal } : {}) },
   });
 
   return {
-    status,
+    status: effectiveStatus,
     discovery,
     proposal,
     coverage,
@@ -212,6 +232,7 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
         discovery,
         proposal,
         coverage,
+        coverageIncomplete: hasProjects ? coverageIncomplete : undefined,
       }),
       json: renderJson(envelope),
     },

package/src/commands/graph.mjs

@@ -10,6 +10,13 @@
  * `entryPoints`, or `declaredPackages`). It is descriptive: it never exits 1,
  * because a snapshot of what is is never a finding.
  *
+ * Its completeness verdict is not computed here: `graphCommand` composes
+ * `./coverage-verdict.mjs`'s `coverageVerdict`, the one constructor every
+ * refusal-contract face reads, so this snapshot's `status`/`exitCode` cannot
+ * drift from the axes `check` judges completeness over. The graph-family
+ * restatement this replaces is how the zero-analysis axis went missing here
+ * while every other face carried it (#612).
+ *
  * What it needs from its caller is a `CommandContext` — the preamble every
  * command shares (`./context.mjs`). What it gives back is a `status`, the
  * payload for both the text and the JSON renderers, and enough coverage
@@ -29,15 +36,12 @@
  */
 import { createHash } from "node:crypto";
 
-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";
 import { formatGraphReport } from "../report/graph-text.mjs";
+import { coverageIncompleteReasons } from "../verdict.mjs";
+import { coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 
 /**
@@ -222,20 +226,24 @@ export function graphCommand(commandContext, { config = null } = {}) {
     );
   }
 
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  // 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);
+  // The completeness verdict is the shared constructor's, not this file's:
+  // restating the axes here is how the `analyzed > 0` term went missing from
+  // this face while `check` carried it (#612 — a run that judged no file at
+  // all used to report `ok` / `complete: true` / exit 0, byte-for-byte the
+  // envelope a clean workspace gets). `coverageVerdict` owns the one law —
+  // no whole-file failure, no unjudged site, at least one file analyzed —
+  // and the same return shape the envelope and the text face both read.
+  const verdict = coverageVerdict(commandContext);
+  const { complete, status, exitCode } = verdict;
 
-  const complete = notAnalyzed.length === 0 && blindSpotCount === 0;
-  const status = complete ? "ok" : "no-verdict";
-  const exitCode = complete ? 0 : 3;
+  // The clauses the text face renders over an incomplete run, worded by the
+  // same function `verdictFor` joins into `decision.reason` — one wording,
+  // two renderings, and neither can drift from the other.
+  const coverageIncomplete = coverageIncompleteReasons({
+    unchecked: verdict.notAnalyzed.length,
+    blindSpots: verdict.blindSpotCount,
+    analyzed: commandContext.analysis.analyzed,
+  });
 
   const projects = buildProjects(graph.nodes);
   const dependencies = buildDependencies(graph.dependencies);
@@ -255,8 +263,8 @@ export function graphCommand(commandContext, { config = null } = {}) {
     projects: projects.length,
     analyzedFiles: commandContext.analysis.analyzed,
     imports: commandContext.analysis.imports.length,
-    notAnalyzed,
-    blindSpots,
+    notAnalyzed: verdict.notAnalyzed,
+    blindSpots: verdict.blindSpots,
     notes: [],
   };
 
@@ -299,6 +307,7 @@ export function graphCommand(commandContext, { config = null } = {}) {
         workspaceLayout,
         workspaceLayoutSource,
         coverage,
+        coverageIncomplete,
       }),
       json: renderJson(envelope),
     },

package/src/commands/history.mjs

@@ -79,6 +79,7 @@ import {
   isWholeFileFailure,
   unresolvableLiteralCount,
 } from "../analysis/source-util.mjs";
+import { canonicalizeJson } from "../canonical.mjs";
 import { containmentViolation } from "../containment.mjs";
 import { classifyEvolution } from "../governance/evolution-event.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
@@ -121,17 +122,17 @@ export function snapshotIdentity({ projects, dependencies, policy }) {
     type,
     tags,
   }));
-  const canonical = JSON.stringify(
-    { projects: identityProjects, dependencies, policy: policy?.fingerprint ?? null },
-    (_, value) =>
-      value !== null && typeof value === "object" && !Array.isArray(value)
-        ? Object.fromEntries(
-            Object.keys(value)
-              .sort()
-              .map((key) => [key, value[key]]),
-          )
-        : value,
-  );
+  // The canonical string comes from `../canonical.mjs` — the one canonicalizer
+  // ("one canonicalizer, in one place, so two serializations cannot drift").
+  // This digest's private inline replacer was the last serialization site
+  // beside it (#613); `history.test.mjs` pins the digest byte-identical to the
+  // retired spelling on every snapshot shape, so composing it moved no byte an
+  // unchanged workspace ever saw.
+  const canonical = canonicalizeJson({
+    projects: identityProjects,
+    dependencies,
+    policy: policy?.fingerprint ?? null,
+  });
   return createHash("sha256").update(canonical).digest("hex");
 }
 

package/src/governance/evolution-event.mjs

@@ -107,19 +107,53 @@ export function declarationDigest(intent) {
   });
 }
 
+/**
+ * The escape character every identity spelling below uses, and the one
+ * function that applies it. A field that carries none of `\`, `>` or `:` and
+ * is not exactly `-` is returned byte-identical — the overwhelmingly common
+ * case, which is what keeps this escaping from rewriting the stored events of
+ * workspaces whose names never carried a delimiter (#627's fix is
+ * conditional by design; a wholesale re-encode on the `boundaryKey`
+ * pattern would change the persisted bytes of every workspace). A field that
+ * does carry one is escaped, so the delimiters that remain unescaped in an
+ * identity string are exactly the separators, and distinct field tuples can
+ * no longer join to the same string (#627). The sentinel `-` (`#628` writes
+ * it for an absent source project) escapes to `\-`, so a field that literally
+ * is `-` can no longer read as "absent" — `\-` in an identity string can only
+ * ever have come from field data.
+ *
+ * @param {string} value One field of an identity string.
+ * @returns {string} The field, escaped iff escaping is needed.
+ */
+export function escapeIdentityField(value) {
+  if (!value.includes("\\") && !value.includes(">") && !value.includes(":") && value !== "-") {
+    return value;
+  }
+  // Backslash first, so it never escapes an escape this pass itself wrote.
+  return value
+    .replaceAll("\\", "\\\\")
+    .replaceAll(">", "\\>")
+    .replaceAll(":", "\\:")
+    .replace(/^-$/u, "\\-");
+}
+
 /**
  * The identity string of one graph edge, in the canonical spelling
  * `source>target:type` — the `(source, target, type)` identity design §1
  * names. The ONE spelling the evolution events' `observed.edges` and
  * `affected.boundaries` use: this module owns it, and `classifyEvolution`
  * maps every edge it is handed through this function, so there is exactly
- * one definition of "same edge" and no second spelling to drift.
+ * one definition of "same edge" and no second spelling to drift. Fields are
+ * escaped through `escapeIdentityField`, so the unescaped `>` and `:` in the
+ * result are the separators and two distinct triples never join to one
+ * string (#627) — while a triple with no delimiter in any field spells
+ * exactly what earlier versions spelled, byte for byte.
  *
  * @param {{source: string, target: string, type: string}} edge
  * @returns {string}
  */
 export function edgeEvolutionIdentity({ source, target, type }) {
-  return `${source}>${target}:${type}`;
+  return `${escapeIdentityField(source)}>${escapeIdentityField(target)}:${escapeIdentityField(type)}`;
 }
 
 /**

package/src/intent/intent-manifest.json

@@ -45,8 +45,8 @@
         {
           "type": "source-evidence",
           "path": "src/lsp/diagnose.mjs",
-          "assertion": "analyzed:false on every non-verdict path; empty diagnostic list only from two named places",
-          "sha256": "4eea19bf245c33963cd292e02f676eb9c5238a5783a3a960976f53afc7cf8b27"
+          "assertion": "analyzed:false on every non-verdict path; empty diagnostic list only from two named places — plus a document whose only positioned failure is an external disclosure, which was judged and so is not published (#603)",
+          "sha256": "72196def14055475ccb23284a3c5d34167535a506985b26fb95af097545cc740"
         },
         {
           "type": "source-evidence",
@@ -104,13 +104,13 @@
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped; SCHEMA_VERSION = 2",
-          "sha256": "cce9730e33e83e0a183c0139afcc9a0845f2f95f67b07875f9c583f3ca95d046"
+          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "computePolicyFingerprint produces SHA-256 of canonicalized policy",
-          "sha256": "cce9730e33e83e0a183c0139afcc9a0845f2f95f67b07875f9c583f3ca95d046"
+          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
         }
       ],
       "status": "proven"
@@ -286,7 +286,7 @@
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "Plain string comparison throughout; never localeCompare",
-          "sha256": "cce9730e33e83e0a183c0139afcc9a0845f2f95f67b07875f9c583f3ca95d046"
+          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
         }
       ],
       "status": "proven"

package/src/lsp/diagnose.mjs

@@ -42,7 +42,7 @@
  * places outside the boundary system entirely.
  */
 import { analyzeFile } from "../analysis/analyze.mjs";
-import { projectOwning } from "../analysis/source-util.mjs";
+import { isExternalSiteFailure, projectOwning } from "../analysis/source-util.mjs";
 import { declaredEdgeViolationsForCheck } from "../commands/edge-constraints.mjs";
 import { evaluate } from "../rules/index.mjs";
 
@@ -97,10 +97,19 @@ export function diagnoseDocument({ sourceFile, text, index, config }) {
 
   // Recorded failures come next, and they are published whether or not the
   // rule pass below succeeds: they are the part of the file that was NOT
-  // judged, and a reader needs that before they read what was.
+  // judged, and a reader needs that before they read what was. The external
+  // class is not that part (`isExternalSiteFailure`): a bare coordinate that
+  // resolves to the dependency universe was judged — resolved external,
+  // disclosed in the run's blind-spot rows, excluded from the withholding
+  // count — so a warning on it would say "not checked" about a site the
+  // verdict below covers, and one per third-party import would be a wall of
+  // warnings a reader rightly learns to ignore (#603). The workspace-surface
+  // and whole-file classes keep publishing.
   const diagnostics = [
     ...prelude,
-    ...analysis.failures.map((failure) => failureDiagnostic(failure, lines)),
+    ...analysis.failures
+      .filter((failure) => !isExternalSiteFailure(failure))
+      .map((failure) => failureDiagnostic(failure, lines)),
   ];
 
   // The engine derives its evidence index from exactly the records it is

package/src/report/discover-text.mjs

@@ -4,15 +4,27 @@
  *
  * The coverage claim sits ABOVE everything — the reader knows whether the
  * observations are complete before reading any entry, exactly like
- * `./graph-text.mjs`'s report. The proposal, when present, is rendered below
- * the observations with the proposal-only banner (`proposed`, `not
- * authoritative`) repeated on every line of every candidate, so a reader who
- * scans the report cannot mistake a candidate for a decision.
+ * `./graph-text.mjs`'s report. Under an incomplete claim sit the reason
+ * clauses the run withheld the verdict over, worded by
+ * `../verdict.mjs`'s `coverageIncompleteReasons` and rendered through
+ * `./text.mjs`'s `formatCoverageIncomplete` — the same clauses, in the
+ * same `⚠` rendering, `check`'s text report prints, so a terminal reader is
+ * told why the verdict is withheld whichever face ran. A zero-analysis run
+ * is the case that needs this: its `notAnalyzed` list is empty, so a
+ * count-bearing headline would blame zero failures for an incomplete
+ * discovery (#619).
+ *
+ * The proposal, when present, is rendered below the observations with the
+ * proposal-only banner (`proposed`, `not authoritative`) repeated on every
+ * line of every candidate, so a reader who scans the report cannot mistake a
+ * candidate for a decision.
  *
  * This module decides nothing. A formatter that filtered would be a rule
  * wearing a formatter's name (`../README.md`).
  */
 
+import { formatCoverageIncomplete } from "./text.mjs";
+
 /** The three confidence markers, in the order the legend prints them. */
 const CONFIDENCE_ORDER = ["high", "medium", "low"];
 
@@ -96,10 +108,16 @@ function formatRule(item) {
  *
  * @param {{discovery: {projects: object[], edges: object[], tags: string[]},
  *   proposal: object|null,
- *   coverage: object}} input
+ *   coverage: object,
+ *   coverageIncomplete?: string[]}} input
+ *   `coverageIncomplete` is the withheld-verdict clause list
+ *   (`../verdict.mjs`'s `coverageIncompleteReasons`, handed through
+ *   `../commands/discover.mjs`) — rendered below the incomplete headline,
+ *   empty exactly when the discovery is complete, and optional because a
+ *   complete discovery carries no clauses to render.
  * @returns {string}
  */
-export function formatDiscoverReport({ discovery, proposal, coverage }) {
+export function formatDiscoverReport({ discovery, proposal, coverage, coverageIncomplete }) {
   const sections = [];
 
   const inspected =
@@ -110,11 +128,15 @@ export function formatDiscoverReport({ discovery, proposal, coverage }) {
   if (coverage.complete) {
     sections.push(`✔ discovery complete (${inspected})`);
   } else {
-    const notAnalyzedCount = coverage.notAnalyzed.length;
+    // The headline states the incompleteness and its consequence; the clauses
+    // below state WHY, one per failed coverage axis. Blaming the whole-file
+    // count in the headline alone would read "0 files could not be analyzed"
+    // over a zero-analysis run (#619) — incomplete, with a reason of nothing.
     sections.push(
-      `✖ discovery incomplete — ${notAnalyzedCount} file${notAnalyzedCount === 1 ? "" : "s"} ` +
-        `could not be analyzed, so these observations may under-represent the workspace (${inspected})`,
+      `✖ discovery incomplete — these observations may under-represent the workspace (${inspected})`,
     );
+    const clauses = formatCoverageIncomplete(coverageIncomplete ?? []);
+    if (clauses !== "") sections.push(clauses);
   }
 
   const projectWord = discovery.projects.length === 1 ? "project" : "projects";

package/src/report/graph-text.mjs

@@ -12,12 +12,21 @@
  * The coverage claim sits ABOVE the listing, not below it, so the reader knows
  * whether the snapshot is complete before reading any entry — an incomplete
  * snapshot printed in full would have the "this may under-represent" warning
- * buried at the bottom.
+ * buried at the bottom. Under an incomplete claim sit the reason clauses the
+ * run withheld the verdict over, worded by `../verdict.mjs`'s
+ * `coverageIncompleteReasons` and rendered through `./text.mjs`'s
+ * `formatCoverageIncomplete` — the same clauses, in the same `⚠` rendering,
+ * `check`'s text report prints, so a terminal reader is told why the verdict
+ * is withheld whichever face ran. A zero-analysis run is the case that needs
+ * this: its `notAnalyzed` list is empty, so a count-bearing headline would
+ * blame zero failures for an incomplete snapshot.
  *
  * This module decides nothing. A formatter that filtered would be a rule
  * wearing a formatter's name (`../README.md`).
  */
 
+import { formatCoverageIncomplete } from "./text.mjs";
+
 /**
  * One project as a line: name, root, type, and tags.
  *
@@ -44,7 +53,13 @@ function formatEdge(edge) {
  * The whole graph report.
  *
  * @param {{projects: object[], dependencies: object[], workspaceLayout: object,
- *   workspaceLayoutSource: string, coverage: object}} input
+ *   workspaceLayoutSource: string, coverage: object,
+ *   coverageIncomplete?: string[]}} input
+ *   `coverageIncomplete` is the withheld-verdict clause list
+ *   (`../verdict.mjs`'s `coverageIncompleteReasons`, handed through
+ *   `../../commands/graph.mjs`) — rendered below the incomplete headline,
+ *   empty exactly when the snapshot is complete, and optional because a
+ *   complete snapshot carries no clauses to render.
  * @returns {string}
  */
 export function formatGraphReport({
@@ -53,6 +68,7 @@ export function formatGraphReport({
   workspaceLayout,
   workspaceLayoutSource,
   coverage,
+  coverageIncomplete,
 }) {
   const sections = [];
 
@@ -66,11 +82,15 @@ export function formatGraphReport({
   if (coverage.complete) {
     sections.push(`✔ graph snapshot complete (${inspected})`);
   } else {
-    const notAnalyzedCount = coverage.notAnalyzed.length;
+    // The headline states the incompleteness and its consequence; the clauses
+    // below state WHY, one per failed coverage axis. Blaming the whole-file
+    // count in the headline alone would read "0 files could not be analyzed"
+    // over a zero-analysis run (#612) — incomplete, with a reason of nothing.
     sections.push(
-      `✖ graph snapshot incomplete — ${notAnalyzedCount} file${notAnalyzedCount === 1 ? "" : "s"} ` +
-        `could not be analyzed, so this snapshot may under-represent the architecture (${inspected})`,
+      `✖ graph snapshot incomplete — this snapshot may under-represent the architecture (${inspected})`,
     );
+    const clauses = formatCoverageIncomplete(coverageIncomplete ?? []);
+    if (clauses !== "") sections.push(clauses);
   }
 
   // Layout line