@ecoma-io/archkeep 0.22.2 → 0.24.0

package/src/commands/coverage-verdict.mjs

@@ -49,7 +49,7 @@ import {
   isWholeFileFailure,
   unresolvableLiteralCount,
 } from "../analysis/source-util.mjs";
-import { EXIT, coverageIncompleteReasons } from "../verdict.mjs";
+import { EXIT, coverageComplete, coverageIncompleteReasons } from "../verdict.mjs";
 import { buildDecision } from "../report/evidence.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatCoverageIncomplete } from "../report/text.mjs";
@@ -96,7 +96,17 @@ export function coverageVerdict(commandContext, { acceptedFiles } = {}) {
     .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;
+  // The conjunction is `../verdict.mjs`'s `coverageComplete` — the same
+  // predicate `verdictFor`'s decision face reads, so `check`'s envelope
+  // cannot carry a `coverage.complete` and a `decision.coverageComplete`
+  // that disagree about one run. The predicate is defined there, not here,
+  // because `verdictFor` needs it and this module already imports from that
+  // one: the reverse import would be a cycle.
+  const complete = coverageComplete({
+    unchecked: notAnalyzed.length,
+    blindSpotCount,
+    analyzed: analysis.analyzed,
+  });
   return {
     notAnalyzed,
     blindSpots,

package/src/commands/delta-snapshot.mjs

@@ -48,6 +48,7 @@
 import { readFileSync } from "node:fs";
 
 import { canonicalJsonReplacer } from "../canonical.mjs";
+import { isPlainObject } from "../values.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 
 /** The only snapshot schemaVersion this module writes and reads. */
@@ -518,11 +519,6 @@ export function providerMismatch(baselineProvider, currentProvider) {
   );
 }
 
-/** Non-empty plain-object guard used across validation. */
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 /** Describes a value for error messages without dumping it. */
 function describe(value) {
   if (value === null) return "null";

package/src/commands/diff.mjs

@@ -41,7 +41,7 @@
 import { readFileSync } from "node:fs";
 
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
-import { computeRuleImpact } from "./edge-constraints.mjs";
+import { computeRuleImpact } from "../rules/edge-constraints.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { SCHEMA_VERSION } from "../report/json.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";

package/src/commands/discover.mjs

@@ -14,9 +14,13 @@
  * - **`--propose`** — computes the candidate architecture over those same
  *   observations (`src/governance/discovery-proposal.mjs`'s
  *   `evaluateDiscovery`) and emits it with `proposed: true` and
- *   `notAuthoritative: true` on every candidate. It never writes
- *   `architecture-intent.json`, never mutates the workspace, and never hands
- *   a candidate the authority of a decision.
+ *   `notAuthoritative: true` on every candidate. This layer performs no
+ *   write: the evaluator is pure, and the one route from a proposal to
+ *   `architecture-intent.json` is the CLI's own `--write-intent <file>` flag
+ *   (`cli.mjs`'s `runDiscover`, serialized through `proposalToIntent`
+ *   below) — explicit, named by the operator, and refused when a file
+ *   already stands at the target. The command never hands a candidate the
+ *   authority of a decision.
  *
  * ## The empty-result invariant
  *

package/src/commands/evaluation-primitives.mjs

@@ -25,8 +25,12 @@ import {
   computeDomainCoverage,
   REQUIRED_DOMAINS,
 } from "./completeness.mjs";
-import { computeImpact } from "./impact.mjs";
-import { computeImpactConstraints } from "./edge-constraints.mjs";
+// The reachability walk comes from `./impact-reachability.mjs`, not from
+// `./impact.mjs`: that module drives `./impact-statement.mjs`, which drives
+// this one, so importing the walk from there closed the engine's only import
+// cycle (#644).
+import { computeImpact } from "./impact-reachability.mjs";
+import { computeImpactConstraints } from "../rules/edge-constraints.mjs";
 // ---------------------------------------------------------------------------
 // Decision resolution
 // ---------------------------------------------------------------------------

package/src/commands/explain.mjs

@@ -79,16 +79,13 @@
  * was: the field, and its rendered lines, exist only when the comparison was
  * requested.
  */
-import {
-  blindSpotRows,
-  isWholeFileFailure,
-  unresolvableLiteralCount,
-} from "../analysis/source-util.mjs";
+import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
 import { evaluate } from "../rules/index.mjs";
 import { findConstraintsFor } from "../rules/tags.mjs";
 import { findProjectForPath, createProjectRootMappings } from "../rules/specifiers.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { coverageVerdict } from "./coverage-verdict.mjs";
 import { formatExplainReport } from "../report/explain-text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { readAdrContext } from "./adr.mjs";
@@ -369,18 +366,18 @@ export function explainCommand(site, commandContext, config, options = {}) {
   // Normalize backslash separators (Windows paths) to forward slashes.
   parsed.sourceFile = sep === "\\" ? normalizedFile.replaceAll("\\", "/") : normalizedFile;
 
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  // 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";
+  // The completeness verdict is the shared constructor's, not this file's —
+  // the same contract `graph`/`discover` run: an unresolvable site was seen
+  // but never judged (#595), the graph is missing whatever edge it 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 restatement
+  // this replaces carried two of the constructor's three axes; the third
+  // (`analyzed > 0`, #599) moves no byte here, because every lane below that
+  // builds an envelope already implies a read file — an import record or a
+  // positioned failure exists only for a file the run analyzed — so the axis
+  // is carried by composition, not changed by it.
+  const { notAnalyzed, blindSpots, complete, status, exitCode } = coverageVerdict(commandContext);
 
   // Find the import record at this site.
   const record = findSite(parsed, commandContext.analysis.imports);
@@ -432,7 +429,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
         analyzedFiles: commandContext.analysis.analyzed,
         imports: commandContext.analysis.imports.length,
         notAnalyzed,
-        blindSpots: blindSpotRows(commandContext.analysis.failures),
+        blindSpots,
         notes: [],
       };
 
@@ -447,7 +444,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
         command: "explain",
         context,
         status,
-        exitCode: complete ? 0 : 3,
+        exitCode,
         coverage,
         result,
       });
@@ -579,7 +576,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
     analyzedFiles: commandContext.analysis.analyzed,
     imports: commandContext.analysis.imports.length,
     notAnalyzed,
-    blindSpots: blindSpotRows(commandContext.analysis.failures),
+    blindSpots,
     notes: [],
   };
 

package/src/commands/graph.mjs

@@ -180,6 +180,13 @@ export function computePolicyFingerprint(config) {
     suppressions: config.suppressions ?? [],
     ...(config.fitness === undefined ? {} : { fitness: config.fitness }),
     ...(config.customRules === undefined ? {} : { customRules: config.customRules }),
+    // The document track is law the same way the two blocks above are: it
+    // decides what this run judges, so a policy that adds or edits a
+    // `markdown` block must not share a fingerprint with one that does not —
+    // `diff`'s policy-changed warning reads this hash. Conditional, like the
+    // two above, so a policy declaring no block hashes exactly as it did
+    // before this key existed.
+    ...(config.markdown === undefined ? {} : { markdown: config.markdown }),
   };
   // Canonicalise: sort object keys at every depth so insertion order does not
   // affect the hash. Semantic equality, not construction order, is the claim —

package/src/commands/health.mjs

@@ -112,10 +112,14 @@ export function healthCommand(commandContext, io = {}) {
   const edges = buildDependencies(graph.dependencies);
 
   // The run's coverage facts, the same shape every command's envelope carries.
+  // A run that analyzed nothing judged nothing (#599, #694): judging nothing
+  // is not finding nothing, so it defeats completeness the way a whole-file
+  // failure does.
   // 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.analyzed > 0 &&
     analysis.failures.filter(isWholeFileFailure).length === 0 &&
     unresolvableLiteralCount(analysis.failures) === 0;
   // The graph is complete only when the files are AND the graph actually sees

package/src/commands/impact-reachability.mjs

@@ -0,0 +1,104 @@
+/**
+ * Reverse reachability over the project graph — the impact *computation*.
+ *
+ * Given a project name, `computeImpact` lists every project that transitively
+ * depends on it — the set a developer needs to consider before changing that
+ * project. It is descriptive: it never exits anything, because a description
+ * of what depends on a project is never a finding.
+ *
+ * The result separates **direct** dependents (projects whose edges point
+ * straight at the target) from **transitive** ones (reachable only through
+ * another project), and the union of both is `dependents`. An empty
+ * `dependents` list is a claim — "nothing depends on this project" — not a
+ * shrug, and the reports built on it are worded that way so a reader never
+ * mistakes it for silence.
+ *
+ * This is a plain module rather than part of `./impact.mjs` on purpose: the
+ * canonical evaluator (`./evaluation-primitives.mjs`) needs the same
+ * reachability walk the `impact` command reports, and `./impact.mjs` drives
+ * `./impact-statement.mjs`, which drives that evaluator. Holding the walk in
+ * `./impact.mjs` made `evaluation-primitives → impact → impact-statement →
+ * evaluation-primitives` the engine's only import cycle (#644) — three
+ * modules forced to load together, with no dependency order left to reason
+ * about. Both sides import the walk from here instead:
+ * `impact → impact-reachability`, `evaluation-primitives →
+ * impact-reachability`, and the trio's remaining direction stays one-way.
+ * `./impact.mjs` re-exports `computeImpact` so its existing importers keep
+ * resolving.
+ *
+ * Like `./edge-constraints.mjs`, this is a shared computation layer: it holds
+ * no argv, prints nothing, and decides no exit code (`./README.md`).
+ */
+import { UsageError } from "../errors.mjs";
+
+/**
+ * Computes the impact set: every project that transitively depends on
+ * `projectName`.
+ *
+ * Builds a reverse adjacency map from the graph's `dependencies`, then walks
+ * it breadth-first starting from the target project. The walk does NOT include
+ * the target project itself in the dependent set — a project does not depend
+ * on itself — but the returned `dependents` array is the union of `direct`
+ * and `transitive`, and the report header names the target separately.
+ *
+ * @param {string} projectName The project whose impact is being queried.
+ * @param {object} graph The project graph: `{nodes, dependencies}`.
+ * @returns {{project: string, direct: string[], transitive: string[], dependents: string[]}}
+ * @throws {UsageError} when `projectName` is not in the graph.
+ */
+export function computeImpact(projectName, graph) {
+  const nodes = graph.nodes;
+  const deps = graph.dependencies;
+
+  if (!Object.hasOwn(nodes, projectName)) {
+    throw new UsageError(
+      `archkeep: no project named '${projectName}' in the graph — ` +
+        `available projects: ${Object.keys(nodes)
+          .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+          .join(", ")}`,
+    );
+  }
+
+  // Build reverse adjacency: target → [sources that depend on it]
+  const reverseAdj = Object.create(null);
+  for (const source of Object.keys(deps)) {
+    if (!Object.hasOwn(deps, source)) continue;
+    const targets = deps[source];
+    for (const edge of targets) {
+      if (!Object.hasOwn(reverseAdj, edge.target)) {
+        reverseAdj[edge.target] = [];
+      }
+      reverseAdj[edge.target].push(source);
+    }
+  }
+
+  // Direct dependents: projects whose edges point straight at the target.
+  // Deduplicate (multiple edges between same pair are possible) and sort.
+  const directSet = new Set(reverseAdj[projectName] ?? []);
+  const direct = [...directSet].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+  // BFS through reverse edges to find transitive dependents.
+  const visited = new Set(directSet);
+  const queue = [...directSet];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const parents = reverseAdj[current];
+    if (parents === undefined) continue;
+    for (const parent of parents) {
+      if (!visited.has(parent)) {
+        visited.add(parent);
+        queue.push(parent);
+      }
+    }
+  }
+
+  // Transitive dependents: reachable through another project, but not direct.
+  const transitive = [...visited]
+    .filter((name) => !directSet.has(name))
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+  // All dependents: direct + transitive, sorted.
+  const dependents = [...visited].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+  return { project: projectName, direct, transitive, dependents };
+}

package/src/commands/impact.mjs

@@ -35,85 +35,23 @@
  * under project roots, `impact` refuses loudly rather than returning a result
  * whose dependents silently under-represent the real architecture.
  */
-import { UsageError } from "../errors.mjs";
-import { computeImpactConstraints } from "./edge-constraints.mjs";
+import { computeImpactConstraints } from "../rules/edge-constraints.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatImpactReport } from "../report/impact-text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { composeImpactStatement } from "./impact-statement.mjs";
+import { computeImpact } from "./impact-reachability.mjs";
 
 /**
- * Computes the impact set: every project that transitively depends on
- * `projectName`.
- *
- * Builds a reverse adjacency map from the graph's `dependencies`, then walks
- * it breadth-first starting from the target project. The walk does NOT include
- * the target project itself in the dependent set — a project does not depend
- * on itself — but the returned `dependents` array is the union of `direct`
- * and `transitive`, and the report header names the target separately.
- *
- * @param {string} projectName The project whose impact is being queried.
- * @param {object} graph The project graph: `{nodes, dependencies}`.
- * @returns {{project: string, direct: string[], transitive: string[], dependents: string[]}}
- * @throws {UsageError} when `projectName` is not in the graph.
+ * The reachability walk this command reports, shared with the canonical
+ * evaluator through `./impact-reachability.mjs` — held there, not here,
+ * because this module also drives `./impact-statement.mjs`, which drives that
+ * evaluator, and keeping the walk here is what closed the engine's only
+ * import cycle (#644). Re-exported so every importer of this module keeps
+ * resolving `computeImpact` from where it always has.
  */
-export function computeImpact(projectName, graph) {
-  const nodes = graph.nodes;
-  const deps = graph.dependencies;
-
-  if (!Object.hasOwn(nodes, projectName)) {
-    throw new UsageError(
-      `archkeep: no project named '${projectName}' in the graph — ` +
-        `available projects: ${Object.keys(nodes)
-          .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
-          .join(", ")}`,
-    );
-  }
-
-  // Build reverse adjacency: target → [sources that depend on it]
-  const reverseAdj = Object.create(null);
-  for (const source of Object.keys(deps)) {
-    if (!Object.hasOwn(deps, source)) continue;
-    const targets = deps[source];
-    for (const edge of targets) {
-      if (!Object.hasOwn(reverseAdj, edge.target)) {
-        reverseAdj[edge.target] = [];
-      }
-      reverseAdj[edge.target].push(source);
-    }
-  }
-
-  // Direct dependents: projects whose edges point straight at the target.
-  // Deduplicate (multiple edges between same pair are possible) and sort.
-  const directSet = new Set(reverseAdj[projectName] ?? []);
-  const direct = [...directSet].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-
-  // BFS through reverse edges to find transitive dependents.
-  const visited = new Set(directSet);
-  const queue = [...directSet];
-  while (queue.length > 0) {
-    const current = queue.shift();
-    const parents = reverseAdj[current];
-    if (parents === undefined) continue;
-    for (const parent of parents) {
-      if (!visited.has(parent)) {
-        visited.add(parent);
-        queue.push(parent);
-      }
-    }
-  }
-
-  // Transitive dependents: reachable through another project, but not direct.
-  const transitive = [...visited]
-    .filter((name) => !directSet.has(name))
-    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-
-  // All dependents: direct + transitive, sorted.
-  const dependents = [...visited].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-
-  return { project: projectName, direct, transitive, dependents };
-}
+export { computeImpact };
 
 /**
  * Runs the `impact` command: resolves the command context, checks the

package/src/commands/plan-context-command.mjs

@@ -501,10 +501,14 @@ export async function planContextCommand(
         (a.messageId < b.messageId ? -1 : a.messageId > b.messageId ? 1 : 0),
     );
 
+  // A run that analyzed nothing judged nothing (#599, #694): judging nothing
+  // is not finding nothing, so it defeats completeness the way a whole-file
+  // failure does.
   // An unresolvable literal site is work the run saw but never judged
   // (#595, narrowed): a plan over it would present edges the run does not
   // hold, so it defeats completeness the way a whole-file failure does.
-  const complete = notAnalyzed.length === 0 && unresolvableLiteralCount(failures) === 0;
+  const complete =
+    wholeTree.analyzed > 0 && notAnalyzed.length === 0 && unresolvableLiteralCount(failures) === 0;
   const status = complete ? "ok" : "no-verdict";
   const exitCode = complete ? 0 : 3;
 

package/src/commands/policy.mjs

@@ -86,10 +86,10 @@ export function hasProfiles(options) {
  * @param {string} cwd The process's working directory a relative `--config`
  *   resolves against — kept separate from the workspace root for the reason
  *   above.
- * @returns {Promise<{config: {depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, notes?: string[]}|null, profile: string|null, source: string|null}>}
- *   `fitness` and `customRules` are present only when the resolved policy
- *   declares them — an absent key is the workspace's decision not to declare
- *   that law, never an empty one (`../config.mjs`'s `policyFrom`).
+ * @returns {Promise<{config: {depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, markdown?: {include: string[], markers: {pattern: string, edge: string}[]}, notes?: string[]}|null, profile: string|null, source: string|null}>}
+ *   `fitness`, `customRules` and `markdown` are present only when the resolved
+ *   policy declares them — an absent key is the workspace's decision not to
+ *   declare that law, never an empty one (`../config.mjs`'s `policyFrom`).
  * @throws {Error} when a named profile, a `--config` file, or an inline
  *   policy cannot be resolved or is malformed — every arm's existing failure
  *   mode, unchanged by the extraction.

package/src/commands/provenance.mjs

@@ -114,8 +114,14 @@ export function resolveProvenance(root) {
 
   // Dirty: any uncommitted change to tracked files means the working tree
   // does not match the commit. A baseline from a dirty tree is not a
-  // reproducible claim about that commit.
-  const status = runProcess("git", ["status", "--porcelain"], root).trim();
+  // reproducible claim about that commit. `--untracked-files=no` is what
+  // makes the code agree with that sentence: bare `--porcelain` includes
+  // untracked paths, and an untracked file is not an uncommitted change to a
+  // tracked file — the analysis reads `git ls-files`-tracked files only, so a
+  // tree whose only dirt is an editor swap, a scratch file, or an unignored
+  // build output has an unchanged analyzed input and must produce an
+  // unchanged envelope (#683).
+  const status = runProcess("git", ["status", "--porcelain", "--untracked-files=no"], root).trim();
   const dirty = status.length > 0;
 
   return { commit, remote, dirty };

package/src/commands/scenario-evaluation.mjs

@@ -32,7 +32,7 @@
  * @module
  */
 import { computeImpact } from "./impact.mjs";
-import { computeImpactConstraints } from "./edge-constraints.mjs";
+import { computeImpactConstraints } from "../rules/edge-constraints.mjs";
 import {
   buildDecisionImpact,
   buildEvolutionAlignment,