@ecoma-io/archkeep 0.21.0 → 0.22.1

package/src/commands/context-command.mjs

@@ -32,7 +32,11 @@
  * than explaining constraints from a graph whose edges silently under-represent
  * the real architecture.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
 import { judgeEdge } from "./edge-constraints.mjs";
 import { findConstraintsFor } from "../rules/tags.mjs";
@@ -150,7 +154,13 @@ export function contextCommand(projectName, commandContext, config) {
     .filter(isWholeFileFailure)
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
 
-  const complete = notAnalyzed.length === 0;
+  // The same completeness `check` claims (#595, #599): unjudged sites and
+  // a zero-analyzed run defeat it here exactly as they do there, so a
+  // context report cannot look complete over a tree the run could not
+  // fully read.
+  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+  const complete =
+    notAnalyzed.length === 0 && blindSpotCount === 0 && commandContext.analysis.analyzed > 0;
   const status = complete ? "ok" : "no-verdict";
   const exitCode = complete ? 0 : 3;
 
@@ -160,9 +170,7 @@ export function contextCommand(projectName, commandContext, config) {
     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: [
       "per-edge violations cover only depConstraints (3 of 15 violation types). " +
         "A dependency with no violations here may still violate npm-ban, circular-dependency, " +

package/src/commands/context.mjs

@@ -214,11 +214,14 @@ export const WORKSPACE_MARKERS = [
  *   `createWorkspace` returns.
  * @property {string[]} tracked Every tracked file, from `listFiles(root)`.
  * @property {{imports: object[], failures: object[], analyzed: number,
- *   analyzedFiles: string[], exemptedFiles: string[]}} analysis The
+ *   analyzedFiles: string[], exemptedFiles: string[],
+ *   unsupportedLanguageFiles: string[]}} analysis The
  *   whole-tree-then-scoped (native) or scoped-then-analyzed (nx/moon) result —
  *   see the branches below for why the order is not the same on all three.
  *   `exemptedFiles` is always `[]` on nx/moon: `coverage.exempt` is a
- *   native-only `archkeep.json` key.
+ *   native-only `archkeep.json` key. `unsupportedLanguageFiles` is scoped to
+ *   the selected files on every branch (#601): a gap row names only files the
+ *   selected scope could have judged.
  * @property {{boundaryConfig: string|object, tsConfig: object|undefined,
  *   boundaryConfigDeclared: boolean, profiles?: string, inline?: boolean}} options
  *   What this workspace names its boundary law, its shared tsconfig, and —
@@ -549,6 +552,7 @@ export function resolveCommandContext(
   let failures;
   let analyzed;
   let analyzedFiles;
+  let unsupportedLanguageFiles;
   let pluginGap;
   let unownedGap;
   let unclaimedGap;
@@ -664,6 +668,12 @@ export function resolveCommandContext(
       ...jvmIndexFailures(workspace),
     ]);
     analyzedFiles = wholeTreeAnalysis.analyzedFiles.filter((file) => selectedFiles.has(file));
+    // Scoped exactly like `analyzedFiles` above (#601): a gap row must name
+    // only files the selected scope could have judged, and leaving this
+    // undefined here would crash `check`'s gap assembly instead of reporting.
+    unsupportedLanguageFiles = wholeTreeAnalysis.unsupportedLanguageFiles.filter((file) =>
+      selectedFiles.has(file),
+    );
     analyzed = analyzedFiles.length;
     // Unaffected by `paths`: an exempted file is by definition unowned by any
     // project, so it was never a candidate for `owned`/`selected` in the
@@ -787,6 +797,13 @@ export function resolveCommandContext(
     ]);
     unclaimedGap = { files: unclaimedFiles };
     analyzedFiles = wholeTreeAnalysis.analyzedFiles.filter((file) => selectedFiles.has(file));
+    // Scoped exactly like the native branch's own filter above (#601): a gap
+    // row must name only files the selected scope could have judged, and
+    // leaving this undefined here would crash `check`'s gap assembly instead
+    // of reporting.
+    unsupportedLanguageFiles = wholeTreeAnalysis.unsupportedLanguageFiles.filter((file) =>
+      selectedFiles.has(file),
+    );
     analyzed = analyzedFiles.length;
     // `coverage.exempt` is a native-only key (`../providers/native/coverage.mjs`'s
     // header: "Nx has no equivalent question") — Moon carries no such list.
@@ -835,7 +852,10 @@ export function resolveCommandContext(
       paths,
       { root, cwd, tracked },
     );
-    ({ imports, failures, analyzed, analyzedFiles } = analyzeWorkspace(workspace, selected));
+    ({ imports, failures, analyzed, analyzedFiles, unsupportedLanguageFiles } = analyzeWorkspace(
+      workspace,
+      selected,
+    ));
     // Unclaimed analyzable files — `unclaimedFileFailures` above — join
     // unconditionally, the same workspace-wide posture native's own
     // `discovered.failures` has, so a scoped `check <path>` cannot hide an
@@ -876,7 +896,14 @@ export function resolveCommandContext(
     graph,
     workspace,
     tracked,
-    analysis: { imports, failures, analyzed, analyzedFiles, exemptedFiles },
+    analysis: {
+      imports,
+      failures,
+      analyzed,
+      analyzedFiles,
+      exemptedFiles,
+      unsupportedLanguageFiles,
+    },
     options,
     pluginGap,
     unownedGap,

package/src/commands/coverage-verdict.mjs

@@ -0,0 +1,191 @@
+/**
+ * The ONE incomplete-coverage refusal contract, and the one completeness
+ * every command's verdict is a claim about (#608).
+ *
+ * #602 gave the graph family (`check`, `graph`, `discover`, `explain`,
+ * `context`) a structured refusal: `status: "no-verdict"`, exit 3, a
+ * `coverage` block naming what the run could not read — in the envelope,
+ * where a parser and `--output` can read it. Every command here that refuses
+ * the same condition refused it by throwing: a stderr sentence, an empty
+ * stdout, no envelope, nothing under `--output`. Same refusal class, two
+ * machine contracts — while `docs/reference/exit-codes.md` already documents
+ * the structured one for every descriptive command. The functions here are
+ * the shared construction the throw family now goes through, so the two
+ * families cannot drift again:
+ *
+ * - `coverageVerdict` computes the one completeness over three axes — no
+ *   whole-file failure, no unjudged blind spot, at least one file analyzed —
+ *   and the status/exit pair that completeness implies. The first two axes
+ *   ride the envelope law (`../report/json.mjs`), and there only in ONE
+ *   direction: the envelope refuses `complete: true` over a non-empty
+ *   `notAnalyzed` list or an unjudged blind-spot row, and deliberately
+ *   allows `complete: false` with both lists empty, so a run that judged
+ *   nothing is able to say so. The third axis — `analyzed > 0` — is the one
+ *   this constructor adds on top (#599, #612, #619): the envelope has no
+ *   zero-analysis refusal by design, which is WHY this constructor exists.
+ *   The failure classes are read through
+ *   `../analysis/source-util.mjs`'s classifiers, never an inline filter: the
+ *   class line is theirs alone to own.
+ * - `coverageRefusal` builds the refusal result itself: the envelope through
+ *   `jsonEnvelope` (so the envelope invariants hold by construction, and a
+ *   refusal cannot accidentally claim `complete: true`), and a text face
+ *   whose coverage lines come from `coverageIncompleteReasons` — the same
+ *   clauses `check`'s text report renders — so a terminal reader is told the
+ *   same thing the envelope tells a parser.
+ *
+ * What still throws: the plugin-gap refusal (a graph that under-represents
+ * the workspace is a different refusal, kept loud in every command that has
+ * one — `drift.mjs`'s `refuseIncompleteGraph` and `delta.mjs`'s
+ * `refusePluginGapHead` are the two shared guards), input refusals (a
+ * malformed baseline file, a missing intent), and the capture modes
+ * (`delta --capture`, `history --capture`) whose product is a snapshot file
+ * with no envelope contract to refuse through.
+ *
+ * @module
+ */
+
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
+import { EXIT, coverageIncompleteReasons } from "../verdict.mjs";
+import { buildDecision } from "../report/evidence.mjs";
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatCoverageIncomplete } from "../report/text.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+
+/**
+ * @typedef {object} CoverageVerdict
+ * @property {{file: string, reason: string}[]} notAnalyzed One row per
+ *   whole-file failure — the files the run never read.
+ * @property {object[]} blindSpots Every positioned failure, all permanent
+ *   classes — the run's disclosure of every site it saw and did not judge.
+ * @property {number} blindSpotCount The count of sites that WITHHOLD the
+ *   verdict (unresolvable literals referencing the workspace; dynamic and
+ *   external sites disclosed but exit-neutral).
+ * @property {boolean} complete Whether the run judged everything in scope.
+ * @property {"ok"|"no-verdict"} status The verdict the completeness implies.
+ * @property {0|3} exitCode The exit code the status implies.
+ */
+
+/**
+ * The one completeness verdict over a command context's analysis.
+ *
+ * The three completeness axes are exactly the envelope law's: a whole-file
+ * failure is a file no verdict was reached on; an unresolvable literal site
+ * is a question the resolver was asked and could not answer; a zero-analyzed
+ * run judged nothing (#599). Dynamic and external sites are declared limits —
+ * disclosed in `blindSpots`, never withholding — because
+ * `unresolvableLiteralCount` draws that class line once, and this function
+ * reads the count rather than re-deriving it.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {{acceptedFiles?: Set<string>}} [io] `acceptedFiles` names whole-
+ *   file failures a `coverage.unowned` row already accepts (`waivers` and
+ *   `check` withdraw those first): the state is a recorded acceptance the
+ *   report itself names, not a hole the run failed to look at. Absent ⇒ no
+ *   withdrawal, which is every command but `waivers`.
+ * @returns {CoverageVerdict}
+ */
+export function coverageVerdict(commandContext, { acceptedFiles } = {}) {
+  const { analysis } = commandContext;
+  const notAnalyzed = analysis.failures
+    .filter(isWholeFileFailure)
+    .filter(({ sourceFile }) => !(acceptedFiles?.has(sourceFile) ?? false))
+    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
+  const blindSpots = blindSpotRows(analysis.failures);
+  const blindSpotCount = unresolvableLiteralCount(analysis.failures);
+  const complete = notAnalyzed.length === 0 && blindSpotCount === 0 && analysis.analyzed > 0;
+  return {
+    notAnalyzed,
+    blindSpots,
+    blindSpotCount,
+    complete,
+    status: complete ? "ok" : "no-verdict",
+    exitCode: complete ? EXIT.ok : EXIT.error,
+  };
+}
+
+/**
+ * The structured refusal itself: what a command returns over an analysis it
+ * could not fully read, instead of throwing.
+ *
+ * The envelope carries no `result`: the verdict was withheld, so there is no
+ * verdict payload to ride beside the refusal — the `coverage` block IS the
+ * payload, and `jsonEnvelope`'s law would refuse any `ok`-shaped claim this
+ * object might otherwise smuggle through. `decision` is accepted for the two
+ * commands whose envelopes already carry one (`delta`, `change`); an
+ * "unknown" decision must name its reason (I3), so callers pass `true` and
+ * the reason is joined from the same clause list the text face renders.
+ *
+ * @param {{command: string, commandContext: object, what: string,
+ *   acceptedFiles?: Set<string>, decision?: boolean}} input
+ *   `command` is the envelope's command name, `what` names the question the
+ *   command was asking (the text face's one free clause), `acceptedFiles`
+ *   forwards to `coverageVerdict` (see above), and `decision: true` attaches
+ *   the canonical `unknown` decision.
+ * @returns {{status: "no-verdict", coverage: object,
+ *   report: {text: string, json: string}}}
+ */
+export function coverageRefusal({ command, commandContext, what, acceptedFiles, decision }) {
+  const verdict = coverageVerdict(commandContext, { acceptedFiles });
+  // A refusal over a complete coverage would be a `no-verdict` claim about a
+  // run that looked at everything — the silent direction in the other dress.
+  // Every caller gates on `coverageVerdict(...).complete` first; this is the
+  // one place that refuses to build the lie if a caller stops gating.
+  if (verdict.complete) {
+    throw new Error(
+      `coverageRefusal: ${command}'s coverage is complete — there is nothing to refuse`,
+    );
+  }
+  /** @type {"no-verdict"} The completeness is false, so this is the status. */
+  const status = "no-verdict";
+  const reasons = coverageIncompleteReasons({
+    unchecked: verdict.notAnalyzed.length,
+    blindSpots: verdict.blindSpotCount,
+    analyzed: commandContext.analysis.analyzed,
+  });
+  const coverage = {
+    complete: false,
+    projects: Object.keys(commandContext.graph.nodes).length,
+    analyzedFiles: commandContext.analysis.analyzed,
+    imports: commandContext.analysis.imports.length,
+    notAnalyzed: verdict.notAnalyzed,
+    blindSpots: verdict.blindSpots,
+    notes: [],
+  };
+  const envelope = jsonEnvelope({
+    command,
+    context: {
+      root: commandContext.root,
+      provider: commandContext.provider,
+      marker: commandContext.marker,
+      provenance: resolveProvenance(commandContext.root),
+    },
+    status,
+    exitCode: verdict.exitCode,
+    coverage,
+    result: undefined,
+    ...(decision === true
+      ? {
+          decision: buildDecision({
+            status,
+            coverageComplete: false,
+            findings: 0,
+            reason: reasons.join("; "),
+          }),
+        }
+      : {}),
+  });
+  return {
+    status,
+    coverage,
+    report: {
+      text:
+        `${command}: no verdict — ${what} needs a workspace this run could fully read\n` +
+        formatCoverageIncomplete(reasons),
+      json: renderJson(envelope),
+    },
+  };
+}

package/src/commands/debt.mjs

@@ -45,12 +45,13 @@
  * when the ledger was taken; the aging itself is snapshot-relative
  * (`../governance/debt-ledger.mjs`).
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { blindSpotRows } from "../analysis/source-util.mjs";
 import { judgeIntent } from "../architecture-intent/judge.mjs";
 import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
 import { computeDebtLedger } from "../governance/debt-ledger.mjs";
 import { readEvents } from "../governance/evolution-store.mjs";
 import { formatDebtReport } from "../report/debt-text.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { buildObserved, refuseIncompleteGraph } from "./drift.mjs";
@@ -75,9 +76,12 @@ import { readSnapshots } from "./history.mjs";
  *   the `history`/`drift` pattern. `events` is the event-store directory the
  *   `--events <dir>` CLI flag resolves; absent ⇒ no lifecycle refs (the
  *   ledger says so in `lifecycle.note`), never guessed.
- * @returns {Promise<{status: "ok", ledger: object, coverage: object,
+ * @returns {Promise<{status: "ok"|"no-verdict", ledger?: object, coverage: object,
  *   report: {text: string, json: string}}>}
- * @throws {Error} on every condition the header lists, all exit-3 class.
+ *   `status: "no-verdict"` carries no `ledger` 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 debtCommand(dir, commandContext, options = {}) {
   const { root, provider, marker, analysis } = commandContext;
@@ -86,15 +90,16 @@ export async function debtCommand(dir, commandContext, options = {}) {
 
   refuseIncompleteGraph(commandContext);
 
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: debt 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 ledger is a claim about the tree the run read, 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, so a blind-spot-only tree crashed
+  // here. The unified completeness refuses it as the verdict-withholding state
+  // it is, before the snapshot directory is read.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "debt", commandContext, what: "aging the debt ledger" });
   }
 
   // The snapshot directory is the sole source of truth for aging; a directory
@@ -173,9 +178,7 @@ export async function debtCommand(dir, commandContext, options = {}) {
     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),
     // The ledger names what it could not age — a reader can tell "aged" from
     // "observed, not yet aged". The second note discloses `sampleTime`'s own
     // nature: it reflects the wall clock at the moment of THIS run, not the

package/src/commands/delta-classify.mjs

@@ -593,20 +593,11 @@ export function deltaFindings(delta) {
   };
 }
 
-/**
- * The identity string of one graph edge, in the design's canonical spelling
- * `source>target:type` (the `(source, target, type)` identity the design
- * §1 names, printed the way `docs/concepts/evolution.md`'s example shows).
- * The ONE spelling the delta's event `observed.edges`/`affected.boundaries`
- * use — a second spelling somewhere would be a second definition of "same
- * edge", and two definitions drift.
- *
- * @param {{source: string, target: string, type: string}} edge
- * @returns {string}
- */
-export function edgeEvolutionIdentity({ source, target, type }) {
-  return `${source}>${target}:${type}`;
-}
+// The identity spelling's ONE home is `../governance/evolution-event.mjs` —
+// `classifyEvolution` owns it and maps every `observed.edges` entry through
+// it. This re-export keeps delta's importers on the same name; it defines
+// nothing.
+export { edgeEvolutionIdentity } from "../governance/evolution-event.mjs";
 
 /**
  * The delta event's per-constraint verdict deltas (design §1 `fitness`),
@@ -675,12 +666,16 @@ export function deltaVerdictDeltas(delta) {
  *
  * @param {object} delta The `deltaCommand` result payload.
  * @param {{projects?: {added: string[], removed: string[], changed: string[]},
- *   edges?: {added: string[], removed: string[]}, codeDrift?: boolean}} [signals]
+ *   edges?: {added: {source: string, target: string, type: string}[],
+ *   removed: {source: string, target: string, type: string}[]},
+ *   codeDrift?: boolean}} [signals]
  *   The structural-change and drift signals a delta run derives from the two
  *   graphs it holds (the graph diff is `diff`'s vocabulary, shared here, never
- *   re-derived) — `projects`/`edges` carry identity strings (`edgeEvolutionIdentity`
- *   for edges), and `codeDrift` is the delta's computed "provenance advanced,
- *   no arch/policy change" fact. Absent signals are empty, so a delta that
+ *   re-derived) — `edges` carries the raw `{source, target, type}` triples,
+ *   which `classifyEvolution` maps through `edgeEvolutionIdentity` itself (the
+ *   identity string is its output spelling, never an input), and `codeDrift`
+ *   is the delta's computed "provenance advanced, no arch/policy change" fact.
+ *   Absent signals are empty, so a delta that
  *   computed none reads as a violation-only mapping.
  * @returns {{classifications: string[], disposition: "accepted"|"rejected"|"no-verdict",
  *   notes: string[], affected: {projects: string[], boundaries: string[],

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`;
 }
 
 /**