@ecoma-io/archkeep 0.20.1 → 0.22.0

package/src/commands/scenario.mjs

@@ -11,7 +11,7 @@
  */
 import { resolveProvenance } from "./provenance.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { evaluateScenario, parseScenarioInput } from "./scenario-evaluation.mjs";
 export { parseScenarioInput } from "./scenario-evaluation.mjs";
 
@@ -23,7 +23,10 @@ export { parseScenarioInput } from "./scenario-evaluation.mjs";
  * @param {string} scenarioJson The scenario description as JSON.
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {object} [config] The loaded boundary config.
- * @returns {{status: string, scenario: object, coverage: object, report: {text: string, json: string}}}
+ * @returns {{status: "ok"|"no-verdict", scenario?: object, coverage: object,
+ *   report: {text: string, json: string}}} `scenario` is absent under
+ *   `status: "no-verdict"` — the coverage refusal (#608) withholds the
+ *   evaluation, and the envelope's `coverage` block is the whole answer.
  */
 export function scenarioCommand(projectName, scenarioJson, commandContext, config = null) {
   const { root, provider, marker, graph, pluginGap } = commandContext;
@@ -44,31 +47,24 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
   // Parse the scenario input
   const scenarioInput = parseScenarioInput(scenarioJson);
 
-  // Check coverage
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: the graph has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so the scenario may ` +
-        `under-represent the real architecture. Fix the unanalyzed files and re-run.`,
-    );
+  // Check coverage — refused through the one structured contract
+  // `./coverage-verdict.mjs` builds (#608): the evaluation is withheld
+  // in-band, where a parser and `--output` can read it.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "scenario", commandContext, what: "evaluating a scenario" });
   }
 
   // Evaluate
   const scenario = evaluateScenario(projectName, commandContext, scenarioInput, config);
 
   const coverage = {
-    complete: scenario.complete,
+    complete: true,
     projects: Object.keys(graph.nodes).length,
     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: [
       "scenario evaluation is virtual and not authoritative — run `check` for the real verdict",
       "per-edge verdicts cover only depConstraints (3 of 15 violation types)",
@@ -81,6 +77,7 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
     virtual: scenario.virtual,
     notAuthoritative: scenario.notAuthoritative,
     complete: scenario.complete,
+    completeness: scenario.completeness,
     project: scenario.project,
     base: scenario.base,
     changes: scenario.changes,
@@ -102,7 +99,7 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
     result,
   });
 
-  const text = formatScenarioReport(scenario);
+  const text = formatScenarioReport(scenario, coverage);
 
   return {
     status: "ok",
@@ -118,15 +115,29 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
 /**
  * Formats a scenario evaluation as terminal text.
  *
+ * The coverage line rides the same `coverageIncompleteReasons` clauses every
+ * other text face uses (`../verdict.mjs`), so a terminal reader is told how
+ * much of the tree the comparison inspected, in the one wording the JSON
+ * envelope's status also speaks (#609).
+ *
  * @param {object} scenario The scenario evaluation result.
+ * @param {object} coverage The run's coverage block.
  * @returns {string}
  */
-function formatScenarioReport(scenario) {
+function formatScenarioReport(scenario, coverage) {
   const lines = [];
 
   lines.push(`Scenario evaluation for "${scenario.project}"`);
   lines.push(`${"=".repeat(50)}`);
   lines.push(`Virtual: ${scenario.virtual}  |  Not authoritative: ${scenario.notAuthoritative}`);
+  // The "how much was inspected" line, derived from the same coverage block
+  // the envelope carries — never re-counted here.
+  lines.push(
+    `Coverage: ${coverage.imports} import${coverage.imports === 1 ? "" : "s"} in ` +
+      `${coverage.analyzedFiles} file${coverage.analyzedFiles === 1 ? "" : "s"} across ` +
+      `${coverage.projects} project${coverage.projects === 1 ? "" : "s"}` +
+      (coverage.complete ? "" : " — coverage incomplete"),
+  );
   lines.push("");
 
   if (scenario.changes.length > 0) {
@@ -167,10 +178,10 @@ function formatScenarioReport(scenario) {
   if (delta.dependentsAdded.length === 0 && delta.dependentsRemoved.length === 0) {
     lines.push("  No change to dependent set");
   }
-  if (delta.constraintsChanged) {
+  if (delta.constraintsChanged && delta.constraintsChanged.status === "changed") {
     lines.push("  Constraint impact: CHANGED");
   }
-  if (delta.decisionsChanged) {
+  if (delta.decisionsChanged && delta.decisionsChanged.status === "changed") {
     lines.push("  Decision impact: CHANGED");
   }
   lines.push("");

package/src/commands/waivers.mjs

@@ -37,10 +37,11 @@
  * `now` and the output is reproducible byte-for-byte. Defaults to the wall
  * clock, the same injection `evaluate` uses for waiver expiry.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { blindSpotRows } from "../analysis/source-util.mjs";
 import { suppressionCovers } from "../config.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import { isWaiver, remainingMs, waiverStatus } from "../governance/waiver.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatWaiversReport } from "../report/waivers-text.mjs";
 import { partitionUnownedCoverage } from "./coverage-acceptance.mjs";
@@ -150,10 +151,13 @@ export function computeWaivers(suppressions, rawViolations, now = referenceTime(
  *   clock, and — from `cli.mjs`'s `runWaivers` — the workspace-relative path
  *   the run's law actually resolved from, so the `coverage.unowned` matching
  *   below subtracts the same configuration files `check` subtracts.
- * @returns {Promise<{status: "ok", waivers: object, report: {text: string, json: string}}>}
- * @throws {Error} whenever the run's law is malformed, or the tree has
- *   whole-file analysis failures — exit-3 class, the same posture `check` takes
- *   on a malformed config and `impact`/`drift` take on incomplete coverage.
+ * @returns {Promise<{status: "ok"|"no-verdict", waivers?: object, coverage: object,
+ *   report: {text: string, json: string}}>}
+ *   `status: "no-verdict"` carries no `waivers` payload — the verdict was
+ *   withheld, and the envelope's `coverage` block is the whole answer (#608).
+ * @throws {Error} whenever the run's law is malformed — exit-3 class, the same
+ *   posture `check` takes on a malformed config. Incomplete coverage returns
+ *   the structured no-verdict envelope instead of throwing (#608).
  */
 export async function waiversCommand(commandContext, boundaryConfig, io = {}) {
   const { root, provider, marker, analysis, graph } = commandContext;
@@ -180,25 +184,23 @@ export async function waiversCommand(commandContext, boundaryConfig, io = {}) {
   // A waiver surface over a tree it could not fully read is a lottery ticket,
   // not a surface: a file the analyzer never judged contributes no raw
   // violation, so every waiver that names it reads as stale and the report
-  // says "covers nothing" about a finding the run never looked at. Refuse
-  // loudly on whole-file failures, the same posture `impact`, `drift`, and
-  // `history` take — "could not look" must never read as "looked and found
-  // nothing" (`./impact.mjs`'s refusal names the same silence). A whole-file
-  // failure whose file a `coverage.unowned` row accepts is withdrawn first,
-  // exactly as `check` withdraws it (`./check.mjs`'s `acceptedUnclaimed`):
-  // its state is a recorded acceptance this very report is about to name,
-  // not a hole the run failed to look at.
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .filter(({ sourceFile }) => !unownedCoverage.acceptedFiles.has(sourceFile))
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: waivers has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every waiver naming one ` +
-        `would read as covering nothing it never saw. Fix the unanalyzed files and re-run.`,
-    );
+  // says "covers nothing" about a finding the run never looked at. Refused
+  // through the one structured contract `./coverage-verdict.mjs` builds
+  // (#608) — "could not look" must never read as "looked and found nothing".
+  // A whole-file failure whose file a `coverage.unowned` row accepts is
+  // withdrawn first, exactly as `check` withdraws it (`./check.mjs`'s
+  // `acceptedUnclaimed`): its state is a recorded acceptance this very report
+  // is about to name, not a hole the run failed to look at.
+  const completeness = coverageVerdict(commandContext, {
+    acceptedFiles: unownedCoverage.acceptedFiles,
+  });
+  if (!completeness.complete) {
+    return coverageRefusal({
+      command: "waivers",
+      commandContext,
+      what: "measuring the waiver surface",
+      acceptedFiles: unownedCoverage.acceptedFiles,
+    });
   }
 
   // F07: a waiver surface measured against a graph that cannot see the
@@ -226,10 +228,13 @@ export async function waiversCommand(commandContext, boundaryConfig, io = {}) {
     projects: Object.keys(graph.nodes).length,
     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 })),
+    // The withdrawn list — whole-file failures a `coverage.unowned` row
+    // accepts are already named in `result.unownedAcceptances` below, so
+    // repeating them here would double-count the same acceptance. On this
+    // path the list is empty by construction: anything unwithdrawn refused
+    // above.
+    notAnalyzed: completeness.notAnalyzed,
+    blindSpots: blindSpotRows(analysis.failures),
     // `remainingMs` reflects the wall clock at the moment of THIS run, not the
     // workspace — it is expected to differ between two runs of an unchanged
     // tree, by design (`../governance/clock.mjs`). Disclosed here, in-band,
@@ -282,6 +287,9 @@ export async function waiversCommand(commandContext, boundaryConfig, io = {}) {
   return {
     status: "ok",
     waivers: result,
+    // The same `coverage` block the envelope carries, so both return shapes —
+    // this one and the no-verdict refusal's (#608) — expose it under one key.
+    coverage,
     report: {
       text: formatWaiversReport(result),
       json: renderJson(envelope),

package/src/governance/evolution-event.mjs

@@ -107,15 +107,68 @@ export function declarationDigest(intent) {
   });
 }
 
+/**
+ * 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.
+ *
+ * @param {{source: string, target: string, type: string}} edge
+ * @returns {string}
+ */
+export function edgeEvolutionIdentity({ source, target, type }) {
+  return `${source}>${target}:${type}`;
+}
+
+/**
+ * The one accepted input shape for an `observed.edges` entry: the raw
+ * `{source, target, type}` triple. A caller handing over a ready-made string
+ * would be choosing a second spelling of "same edge", so a string is refused
+ * loudly rather than accepted as one shape more — the identity string is this
+ * module's output, never its input.
+ *
+ * @param {unknown} entry
+ * @returns {string}
+ */
+function evolutionBoundary(entry) {
+  if (
+    typeof entry !== "object" ||
+    entry === null ||
+    !("source" in entry) ||
+    typeof entry.source !== "string" ||
+    entry.source === "" ||
+    !("target" in entry) ||
+    typeof entry.target !== "string" ||
+    entry.target === "" ||
+    !("type" in entry) ||
+    typeof entry.type !== "string"
+  ) {
+    throw new TypeError(
+      "classifyEvolution: observed.edges entries must be {source, target, type} triples — " +
+        "the identity string is classifyEvolution's own output spelling, never an input",
+    );
+  }
+  // The guard above has verified every property; the annotation only states
+  // what it proved.
+  return edgeEvolutionIdentity(
+    /** @type {{source: string, target: string, type: string}} */ (entry),
+  );
+}
+
 /**
  * @typedef {object} EvolutionEvidence
  * @property {{projects?: {added: string[], removed: string[], changed: string[]},
- *   edges?: {added: string[], removed: string[]},
+ *   edges?: {added: {source: string, target: string, type: string}[],
+ *   removed: {source: string, target: string, type: string}[]},
  *   policyChanged?: boolean|null, policyOneSided?: boolean,
  *   provenanceChanged?: boolean|null}} [observed]
- *   The structural diff between base and head: project names and edge identity
- *   strings (source,target,type) that were added, removed, or changed. Empty
- *   by default. `policyChanged` — whether the policy fingerprint changed
+ *   The structural diff between base and head: project names and raw edge
+ *   triples that were added, removed, or changed. The triples are mapped
+ *   through `edgeEvolutionIdentity` here — the identity spelling is this
+ *   module's own, so `affected.boundaries` comes out as identity strings
+ *   whichever shape the caller held. Empty by default. `policyChanged` — whether the policy fingerprint changed
  *   between base and head; `null` is "could not be compared": exactly one side
  *   records the policy (`policyOneSided: true`) or neither does
  *   (both-absent). `true` is a disclosure, never a refusal. `policyOneSided`
@@ -197,9 +250,9 @@ export function declarationDigest(intent) {
  *   absent (`null`) ⇒ NOT asserted, note added |
  *
  * The `affected` identities are derived from the same signals, never from a
- * second opinion: changed project names, changed edge identity strings, the
- * constraint/intent rows whose verdict was not `pass`/`matched`, and the ADR
- * ids whose lineage moved.
+ * second opinion: changed project names, the changed edges under the one
+ * identity spelling (`edgeEvolutionIdentity`), the constraint/intent rows
+ * whose verdict was not `pass`/`matched`, and the ADR ids whose lineage moved.
  *
  * @param {EvolutionEvidence} [input]
  * @returns {EvolutionClassification}
@@ -211,8 +264,8 @@ export function classifyEvolution(input = {}) {
   const addedProjects = projects.added ?? [];
   const removedProjects = projects.removed ?? [];
   const changedProjects = projects.changed ?? [];
-  const addedEdges = edges.added ?? [];
-  const removedEdges = edges.removed ?? [];
+  const addedEdges = (edges.added ?? []).map(evolutionBoundary);
+  const removedEdges = (edges.removed ?? []).map(evolutionBoundary);
   const structureChanged =
     addedProjects.length +
       removedProjects.length +