@ecoma-io/archkeep 0.20.1 → 0.22.0

package/src/commands/change.mjs

@@ -71,16 +71,20 @@
  * change lives in `./change-intent.mjs`'s validation (`parseChangeIntent`),
  * the same loud lane as every other malformed declaration.
  *
- * Refusals (each a throw → exit 3 upstream): a manifest that fails shape or
- * reference validation, an unreadable/malformed/foreign-schema baseline,
- * incomplete baseline coverage, a provider mismatch, incomplete head
- * coverage, an unregistered-plugin graph over polyglot manifests, and a run
- * with no boundary law (constraints and the law fingerprint need one).
+ * Refusals: incomplete head coverage returns the structured no-verdict
+ * envelope `./coverage-verdict.mjs` builds (#608) — 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 rest are throws →
+ * exit 3 upstream: a manifest that fails shape or reference validation, an
+ * unreadable/malformed/foreign-schema baseline, incomplete baseline coverage,
+ * a provider mismatch, an unregistered-plugin graph over polyglot manifests,
+ * and a run with no boundary law (constraints and the law fingerprint need
+ * one).
  *
  * This module computes and returns; `../../cli.mjs`'s `runChange` owns argv,
  * output destination and the process exit code (`./README.md`).
  */
-import { classifyDelta } from "./delta-classify.mjs";
+import { classifyDelta, edgeEvolutionIdentity } from "./delta-classify.mjs";
 import { computeDiff } from "./diff.mjs";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
 import {
@@ -91,10 +95,12 @@ import {
 } from "./change-intent.mjs";
 import {
   evidenceGraphToProjectGraph,
-  refuseUnjudgeableHead,
+  refusePluginGapHead,
   sourceProjectAttributor,
 } from "./delta.mjs";
 import { providerMismatch, readEvidenceSnapshot } from "./delta-snapshot.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
+import { blindSpotRows } from "../analysis/source-util.mjs";
 import { cyclicProjects } from "../governance/fitness-rules.mjs";
 import { fitnessVerdict } from "../governance/verdict.mjs";
 import { buildDecision } from "../report/evidence.mjs";
@@ -154,25 +160,16 @@ function violationFindingId(entry) {
   return `${entry.messageId}:${entry.sourceProject ?? "-"}:${entry.target}`;
 }
 
-/**
- * The identity string an observed edge carries into the event's `observed`
- * and `affected` — `(source, target, type)`, the triple `./diff.mjs`'s
- * `edgeIdentityKey` owns, spelled for a human reader (`>` separator, optional
- * type suffix). Two spellings of one triple never diverge because the triple
- * itself is the input.
- *
- * @param {{source: string, target: string, type?: string}} edge
- * @returns {string}
- */
-function edgeIdentityString(edge) {
-  return `${edge.source}>${edge.target}${edge.type === undefined || edge.type === "" ? "" : `:${edge.type}`}`;
-}
-
 /**
  * The structural-diff facts in the event's `observed` shape (design §1),
  * mapped from `computeDiff`'s output and the metadata comparison — the same
  * lists the reconciliation already consumed, never recomputed.
  *
+ * The edges' identity strings come from `edgeEvolutionIdentity`
+ * (`./delta-classify.mjs`) — the ONE spelling the evolution events'
+ * `observed.edges`/`affected.boundaries` use. A local spelling here would be
+ * a second definition of "same edge", and two definitions drift.
+ *
  * @param {{addedProjects: object[], removedProjects: object[],
  *   changedProjects: object[], addedEdges: object[], removedEdges: object[]}} structural
  * @param {{policyChanged: boolean|null, policyOneSided: boolean,
@@ -189,8 +186,8 @@ function observedFrom(structural, meta) {
     changed: structural.changedProjects.map((project) => project.name),
   };
   const edges = {
-    added: structural.addedEdges.map(edgeIdentityString),
-    removed: structural.removedEdges.map(edgeIdentityString),
+    added: structural.addedEdges.map(edgeEvolutionIdentity),
+    removed: structural.removedEdges.map(edgeEvolutionIdentity),
   };
   return {
     architectureChanged:
@@ -490,8 +487,14 @@ function judgeDeclaredConstraints(intent, io) {
  *   change event's `debt` diff judges the intent over this run's base and
  *   head graphs and would be untestable without it.
  * @returns {Promise<{status: "ok"|"findings"|"no-verdict",
- *   changeIntent: object, coverage: object, report: {text: string, json: string}}>}
- * @throws {Error} on every refusal the module header lists.
+ *   changeIntent?: object, coverage: object, report: {text: string, json: string}}>}
+ *   `status: "no-verdict"` from the coverage refusal (#608) carries no
+ *   `changeIntent` payload — the reconciliation was withheld, and the
+ *   envelope's `coverage` block plus its `decision.reason` are the whole
+ *   answer.
+ * @throws {Error} on every refusal the module header lists. Incomplete head
+ *   coverage returns the structured no-verdict envelope instead of throwing
+ *   (#608); the unregistered-plugin graph keeps its throw.
  */
 export async function changeCommand(
   baselinePath,
@@ -530,7 +533,23 @@ export async function changeCommand(
     );
   }
 
-  refuseUnjudgeableHead(commandContext, "reconcile a change intent");
+  // The plugin-gap refusal stays a throw; the coverage refusal returns the one
+  // structured envelope `./coverage-verdict.mjs` builds (#608) — status
+  // "no-verdict", exit 3, a `coverage` block naming every file and site the
+  // run could not judge — instead of the throw `refuseUnjudgeableHead` used to
+  // carry here. Reconciling a declaration over a half-read tree would answer
+  // "undeclared" about architecture the run never observed, and that refusal
+  // belongs in-band, where a parser and `--output` can read it.
+  refusePluginGapHead(commandContext, "reconcile a change intent");
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({
+      command: "change",
+      commandContext,
+      what: "reconciling a change intent",
+      decision: true,
+    });
+  }
 
   const intent = await (readIntent ? readIntent(intentPath) : readChangeIntent(intentPath));
 
@@ -718,7 +737,12 @@ export async function changeCommand(
     analyzedFiles: analysis.analyzed,
     imports: analysis.imports.length,
     notAnalyzed: [],
-    blindSpots: [],
+    // The positioned failures the run SAW — including the dynamic and external
+    // sites that never withhold a verdict. This used to be hardcoded `[]`
+    // (#609): a declared limit named nowhere is a disclosure gap, and
+    // `blindSpotRows` is the one mapping every other command's coverage block
+    // carries.
+    blindSpots: blindSpotRows(analysis.failures),
     notes,
   };
 
@@ -745,7 +769,14 @@ export async function changeCommand(
     reason: entry.reason,
   }));
   const evolution = classifyEvolution({
-    observed,
+    // The raw triples, not the mapped strings `observed` carries (that object
+    // is the event's stored record): `classifyEvolution` owns the identity
+    // spelling and takes the triples, so `affected.boundaries` is mapped
+    // inside it under the one spelling rather than trusted from the caller.
+    observed: {
+      ...observed,
+      edges: { added: structural.addedEdges, removed: structural.removedEdges },
+    },
     ...(classification === null
       ? {}
       : {

package/src/commands/check.mjs

@@ -12,7 +12,12 @@
 import { statSync } from "node:fs";
 import { join } from "node:path";
 
-import { fileFailure, isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  fileFailure,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { tsconfigPathsFacts } from "../analysis/typescript.mjs";
 import { stripTrailingSlashes } from "../path-util.mjs";
 import { suppressionCovers } from "../config.mjs";
@@ -188,7 +193,7 @@ function declaredEdgeManifest({ provider, graph }, sourceProject) {
  *   intentUnresolved: number, intentUnresolvedDecisionRefs: number, fitnessFail: number,
  *   fitnessUnknown: number, customRuleFail: number, customRuleUnknown: number,
  *   customRuleEvidence: {rule: string, bytes: Uint8Array}[], customRulesDeclared: boolean,
- *   analyzed: number, unchecked: number, waived?: number}>}
+ *   analyzed: number, unchecked: number, blindSpots: number, waived?: number}>}
  */
 export async function check(options, { cwd, readGraph, listFiles = listTrackedFiles }) {
   const commandContext = resolveCommandContext(
@@ -196,7 +201,7 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     { readGraph, listFiles },
   );
   const { root, graph, workspace, tracked } = commandContext;
-  const { imports, exemptedFiles } = commandContext.analysis;
+  const { imports, exemptedFiles, unsupportedLanguageFiles } = commandContext.analysis;
   const failures = [...commandContext.analysis.failures];
   const analyzed = commandContext.analysis.analyzed;
 
@@ -622,6 +627,18 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     failures.filter(isWholeFileFailure).map((failure) => failure.sourceFile),
   ).size;
 
+  // Sites the run saw but never judged (#595): the file was analyzed, this
+  // site was not, and a pass over it would claim a verdict the run does not
+  // hold. Counted beside `unchecked` from one classifier
+  // (`unresolvableLiteralCount`) so the exit, the report and the envelope all
+  // agree from one number. The two classes that withholds nothing are
+  // excluded from the count: the declared dynamic limit — a non-literal
+  // `import()` argument, unknowable in principle — and the external
+  // bare-package site, whose resolvability depends on an installed dependency
+  // tree a workspace legitimately may not have (`isDynamicSiteFailure` and
+  // `isExternalSiteFailure` in source-util.mjs own the class line).
+  const blindSpotCount = unresolvableLiteralCount(failures);
+
   // A row of the boundary law that covers nothing is a boundary that stopped
   // being enforced, and — unlike a missing `reason`, which only a human can
   // judge — it is machine-detectable. Two tables can be dead, and both are
@@ -838,8 +855,38 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
           },
         ]
       : []),
+    // Files a project owns that no analyzer claims (#601): skipped before
+    // reading, so they land in no failure list — without this row the run
+    // would present the judged surface as the whole story. Disclosure, not
+    // failure: the row names them and their extensions, and leaves
+    // `complete` to the surface that WAS judged. Sorted, because the row's
+    // bytes must not vary with `git ls-files`' order (E-F10).
+    ...(unsupportedLanguageFiles.length > 0
+      ? [{ kind: "unsupported-language", files: [...unsupportedLanguageFiles].sort() }]
+      : []),
   ];
 
+  // One verdict computation for both faces: the JSON envelope spreads it and
+  // the text report renders its `reasons` beside the headline — a second call
+  // here would let the two faces disagree about a run neither re-derives from
+  // the other (`../verdict.mjs`'s header owns that argument).
+  const verdict = verdictFor({
+    violations: violations.length,
+    declaredEdgeFindings,
+    goWorkDrift,
+    tsconfigPathsDead,
+    intentFindings,
+    intentUnresolved,
+    intentUnresolvedDecisionRefs: intentUnresolvedDecisionRefRows.length,
+    unchecked,
+    analyzed,
+    blindSpots: blindSpotCount,
+    fitnessFail,
+    fitnessUnknown,
+    customRuleFail,
+    customRuleUnknown,
+  });
+
   const report =
     options.format === "json"
       ? renderJson(
@@ -861,36 +908,20 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
             // `decision` — the four-state verb of the same counts — so the
             // envelope's `decision.verdict` and its `status` are built from
             // exactly one computation and can never disagree.
-            ...verdictFor({
-              violations: violations.length,
-              declaredEdgeFindings,
-              goWorkDrift,
-              tsconfigPathsDead,
-              intentFindings,
-              intentUnresolved,
-              intentUnresolvedDecisionRefs: intentUnresolvedDecisionRefRows.length,
-              unchecked,
-              fitnessFail,
-              fitnessUnknown,
-              customRuleFail,
-              customRuleUnknown,
-            }),
+            ...verdict,
             coverage: {
-              complete: unchecked === 0,
+              // Complete means the run judged everything in scope: no
+              // whole-file failure (unchecked), no unresolvable site (#595),
+              // and at least one file analyzed (#599 — a run that judged
+              // nothing has no verdict to claim).
+              complete: unchecked === 0 && blindSpotCount === 0 && analyzed > 0,
               projects: Object.keys(graph.nodes).length,
               analyzedFiles: analyzed,
               imports: imports.length,
               notAnalyzed: failures
                 .filter(isWholeFileFailure)
                 .map(({ sourceFile, reason }) => ({ file: sourceFile, reason })),
-              blindSpots: failures
-                .filter((failure) => !isWholeFileFailure(failure))
-                .map(({ sourceFile, line, column, reason }) => ({
-                  file: sourceFile,
-                  line,
-                  column,
-                  reason,
-                })),
+              blindSpots: blindSpotRows(failures),
               notes,
               coverageGaps,
             },
@@ -1020,6 +1051,10 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
           // inspected" fact does (`../report/text.mjs`'s `formatReport`).
           notes,
           coverageGaps,
+          // `formatReport` (text) renders these beside the headline; the SARIF
+          // face files the same facts as warning notifications. Both faces of
+          // one run name the same clauses, in the same order.
+          coverageIncomplete: verdict.reasons,
           // `formatReport` (text) reads this to annotate an unresolved
           // decisionRef inline; `formatSarif` files each one as a warning
           // notification. Both faces of one run name the same citations, in
@@ -1052,5 +1087,9 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     customRulesDeclared: customRules !== null,
     analyzed,
     unchecked,
+    // The site-level count `verdictFor` needs: `cli.mjs` passes this whole
+    // return through `verdictFor` for the process's exit code, so a count the
+    // envelope saw but the exit code did not would let the two disagree.
+    blindSpots: blindSpotCount,
   };
 }