@ecoma-io/archkeep 0.20.0 → 0.21.0

package/src/commands/impact-statement.mjs

@@ -39,12 +39,7 @@
  *
  * @module
  */
-import { readAdrContext } from "./adr.mjs";
-import { computeImpactConstraints } from "./edge-constraints.mjs";
-import { computeImpact } from "./impact.mjs";
-import { hasAuthority, resolveDecisionRef, stripAdrPrefix } from "../governance/adr-registry.mjs";
-import { isComboDepConstraint } from "../rules/tags.mjs";
-
+import { evaluateArchitectureState } from "./evaluation-primitives.mjs";
 /**
  * @typedef {object} ImpactStatement
  * @property {string} project The target project name.
@@ -60,365 +55,23 @@ import { isComboDepConstraint } from "../rules/tags.mjs";
  * @property {{projects: string[], boundaries: string[], constraints: string[],
  *   decisions: string[]}} [evolutionAlignment] The `affected` shape matching
  *   `EvolutionEvent.affected` vocabulary.
- * @property {{evaluated: boolean, entries: object[], note: string|null}} findingsImpact
+ * @property {{evaluated: boolean, findings: object[], count: number}} findingsImpact
  *   Findings that affect the impacted projects. `evaluated: false` when no
  *   findings data was provided — reported as a gap, never as "no findings".
- * @property {{evaluated: boolean, entries: object[], note: string|null}} debtImpact
+ * @property {{evaluated: boolean, debt: object[], count: number}} debtImpact
  *   Debt entries that affect the impacted projects. `evaluated: false` when no
  *   debt data was provided — reported as a gap, never as "no debt".
  * @property {{boundaries: object[], evaluated: boolean}} boundaryImpact
  *   Boundary-crossing analysis for each affected edge. `evaluated: false` when
  *   no constraint impact was available.
+ * @property {{domains: {structural: {status: string, note?: string}, constraint: {status: string, note?: string}, boundary: {status: string, note?: string}, decision: {status: string, note?: string}, governance: {status: string, note?: string}}, overallComplete: boolean, overallStatus: string}} completeness
+ *   Completeness of each evaluation domain and the overall assessment.
  * @property {boolean} complete Whether the statement could be fully composed.
+ *   Backward-compat alias for `completeness.overallComplete`.
  * @property {string[]} notes Caveats about statement completeness and
  *   governance gaps.
  */
 
-/**
- * Resolve a decisionRef to its record details.
- *
- * @param {string} ref The decision reference (bare, `adr:`, or `rule:`/`fitness:`-prefixed).
- * @param {Map<string, object>} byId The ADR registry index.
- * @param {Set<string>} knownFitness Declared fitness names.
- * @returns {{resolution: "adr"|"fitness"|"unknown", record?: object}}
- */
-function resolveDecision(ref, byId, knownFitness) {
-  const resolution = resolveDecisionRef(byId, knownFitness, ref);
-  if (resolution === "adr") {
-    const record = byId.get(stripAdrPrefix(ref));
-    return { resolution, record };
-  }
-  if (resolution === "fitness") {
-    // A fitness ref resolves but has no ADR record entry — it's a
-    // rule/fitness id, not an ADR. We report the resolution but have
-    // no record details for it.
-    return { resolution };
-  }
-  return { resolution };
-}
-
-/**
- * Builds the decision impact section: which recorded decisions bind the
- * affected constraint rows.
- *
- * @param {string} root Workspace root path.
- * @param {object[]} constraintImpact Per-dependent constraint analysis.
- * @param {object} config The loaded boundary config (with `depConstraints`).
- * @returns {{decisions: object[], unresolvedDecisionRefs: string[]}|null}
- *   null when the ADR registry is unreadable.
- */
-function buildDecisionImpact(root, constraintImpact, config) {
-  // Collect unique decisionRefs ONLY from constraint rows that are actually
-  // AFFECTED by the change — rows that govern edges from impacted dependents.
-  // A decisionRef in the config is not enough: the decision must be causally
-  // bound to a governance entity the change touches.
-  const seenRefs = new Set();
-  const affectedRefs = [];
-
-  // Build evidence map: decisionRef -> { constraintRows, dependentProjects }
-  /** @type {Map<string, {constraintRows: number[], dependentProjects: string[]}>} */
-  const evidenceByRef = new Map();
-
-  if (constraintImpact && config && config.depConstraints) {
-    // Use identity matching: constraintImpact.constraintRows are the actual
-    // config row objects returned by findConstraintsFor — check by reference,
-    // not by string label, for exact causal binding.
-    for (const entry of constraintImpact) {
-      const activeRows = new Set(entry.constraintRows);
-      const sourceProject = entry.project;
-
-      for (let i = 0; i < config.depConstraints.length; i++) {
-        const row = config.depConstraints[i];
-        if (!row.decisionRef) continue;
-        if (!activeRows.has(row)) continue;
-
-        if (!evidenceByRef.has(row.decisionRef)) {
-          evidenceByRef.set(row.decisionRef, {
-            constraintRows: [],
-            dependentProjects: [],
-          });
-        }
-        const evidence = evidenceByRef.get(row.decisionRef);
-        if (!evidence.constraintRows.includes(i)) {
-          evidence.constraintRows.push(i);
-        }
-        if (!evidence.dependentProjects.includes(sourceProject)) {
-          evidence.dependentProjects.push(sourceProject);
-        }
-
-        if (!seenRefs.has(row.decisionRef)) {
-          seenRefs.add(row.decisionRef);
-          affectedRefs.push(row.decisionRef);
-        }
-      }
-    }
-  }
-
-  if (affectedRefs.length === 0) {
-    return { decisions: [], unresolvedDecisionRefs: [] };
-  }
-
-  // Try to read the ADR registry — if it fails, all refs are unresolved
-  let adrContext;
-  try {
-    adrContext = readAdrContext(root);
-  } catch {
-    return {
-      decisions: [],
-      unresolvedDecisionRefs: [...affectedRefs],
-    };
-  }
-
-  const { byId, knownFitness } = adrContext;
-  const unresolvedDecisionRefs = [];
-  const decisions = [];
-
-  for (const ref of affectedRefs) {
-    const resolved = resolveDecision(ref, byId, knownFitness);
-    const evidence = evidenceByRef.get(ref);
-
-    if (resolved.resolution === "unknown") {
-      unresolvedDecisionRefs.push(ref);
-      continue;
-    }
-
-    if (resolved.resolution === "fitness") {
-      // Fitness refs are not ADR records — report them as resolved
-      // but with no record-level details
-      decisions.push({
-        id: ref,
-        kind: "fitness",
-        resolution: "known",
-        evidence,
-      });
-      continue;
-    }
-
-    // ADR record
-    const record = resolved.record;
-    decisions.push({
-      id: record.id,
-      kind: "adr",
-      status: record.status,
-      hasAuthority: hasAuthority(record.status),
-      supersedes: record.supersedes.length > 0 ? record.supersedes : undefined,
-      supersededBy: (record.supersededBy ?? []).length > 0 ? record.supersededBy : undefined,
-      evidence,
-    });
-  }
-
-  return {
-    decisions: decisions.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
-    unresolvedDecisionRefs: [...new Set(unresolvedDecisionRefs)].sort(),
-  };
-}
-
-/**
- * Builds the evolution alignment section: the `affected` shape matching
- * `EvolutionEvent.affected` vocabulary.
- *
- *
- * @param {{direct: string[], transitive: string[], dependents: string[]}} impact
- * @param {object[]} [constraintImpact] Per-dependent constraint rows.
- * @param {string[]} [resolvedDecisions] Decision IDs that bind affected rows.
- * @returns {{projects: string[], boundaries: string[], constraints: string[],
- *   decisions: string[]}}
- */
-function buildEvolutionAlignment(projectName, impact, constraintImpact, resolvedDecisions) {
-  const affectedProjects = [projectName, ...impact.dependents];
-  const affectedConstraints = [];
-  const affectedBoundaries = [];
-
-  if (constraintImpact) {
-    for (const entry of constraintImpact) {
-      // Collect edge identities for each affected boundary
-      for (const edge of entry.edges) {
-        const edgeId = `${entry.project}>${edge.target}:${edge.type}`;
-        if (!affectedBoundaries.includes(edgeId)) {
-          affectedBoundaries.push(edgeId);
-        }
-      }
-      // Collect constraint row labels
-      for (const row of entry.constraintRows) {
-        const label = isComboDepConstraint(row)
-          ? `allSourceTags:${row.allSourceTags.join(",")}`
-          : `sourceTag:${row.sourceTag}`;
-        if (!affectedConstraints.includes(label)) {
-          affectedConstraints.push(label);
-        }
-      }
-    }
-  }
-
-  return {
-    projects: [...new Set(affectedProjects)].sort(),
-    boundaries: affectedBoundaries.sort(),
-    constraints: affectedConstraints.sort(),
-    decisions: resolvedDecisions ? [...new Set(resolvedDecisions)].sort() : [],
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Findings and Debt impact (governance integration)
-// ---------------------------------------------------------------------------
-
-/**
- * Evaluates findings impact for the affected projects.
- *
- * When no findings data is provided, reports the gap explicitly rather than
- * claiming no findings exist.
- *
- * @param {string[]} affectedProjects The projects affected by the change.
- * @param {object[]|null} [availableFindings] Optional pre-computed findings
- *   from the check pipeline.
- * @returns {{evaluated: boolean, entries: object[], note: string|null}}
- *   `evaluated: true` when findings data was available and filtered.
- *   `evaluated: false` when findings were not provided.
- */
-function evaluateFindingsImpact(affectedProjects, availableFindings = null) {
-  if (!availableFindings) {
-    return {
-      evaluated: false,
-      entries: [],
-      note: "findings impact not evaluated — no findings data provided to impact statement",
-    };
-  }
-
-  // Filter findings by affected projects
-  const affectedSet = new Set(affectedProjects);
-  const entries = availableFindings.filter((f) => {
-    const source = f.source ?? f.project ?? "";
-    const target = f.target ?? "";
-    return affectedSet.has(source) || affectedSet.has(target);
-  });
-
-  return {
-    evaluated: true,
-    entries,
-    note:
-      entries.length > 0
-        ? `${entries.length} finding(s) affect impacted projects`
-        : "no findings affect impacted projects",
-  };
-}
-
-/**
- * Evaluates debt impact for the affected projects.
- *
- *
- * Debt entries have `source` as either a project name (for drift entries) or
- * a file path (for waiver entries). When a `resolveProject` function is
- * provided, file-path sources are resolved to project names for matching.
- * When no debt data is provided, reports the gap explicitly rather than
- * claiming no debt exists.
- *
- * @param {string[]} affectedProjects The projects affected by the change.
- * @param {object[]|null} [availableDebt] Optional pre-computed debt entries
- *   from the debt ledger (`computeDebtLedger().entries`).
- * @param {function(string): string|null} [resolveProject] Optional function
- *   to resolve a file path to its owning project name. Used for waiver entries
- *   whose `source` is a file path, not a project name.
- * @returns {{evaluated: boolean, entries: object[], note: string|null}}
- *   `evaluated: true` when debt data was available and filtering was attempted.
- *   `evaluated: false` when debt was not provided.
- */
-function evaluateDebtImpact(affectedProjects, availableDebt = null, resolveProject = null) {
-  if (!availableDebt) {
-    return {
-      evaluated: false,
-      entries: [],
-      note: "debt impact not evaluated — no debt data provided to impact statement",
-    };
-  }
-
-  // Filter debt entries by affected projects.
-  // Debt entries use `source` as either a project name (drift, unresolved) or
-  // a file path (waiver, expired-waiver). For path-based sources, use the
-  // resolveProject function when available.
-  const affectedSet = new Set(affectedProjects);
-  const entries = availableDebt.filter((d) => {
-    // Drift and unresolved entries have source = project name directly
-    if (d.kind === "drift" || d.kind === "unresolved") {
-      return affectedSet.has(d.source ?? "");
-    }
-    // Waiver entries have source = file path; resolve via owning project
-    if (d.kind === "waiver" || d.kind === "expired-waiver") {
-      if (typeof resolveProject === "function") {
-        const project = resolveProject(d.source ?? "");
-        return project !== null && affectedSet.has(project);
-      }
-      // Without resolveProject, we cannot match path-based sources
-      return false;
-    }
-    // Aspirational-gap entries have source = note text — no project match
-    return false;
-  });
-
-  return {
-    evaluated: true,
-    entries,
-    note:
-      entries.length > 0
-        ? `${entries.length} debt entry(ies) affect impacted projects`
-        : "no debt entries affect impacted projects",
-  };
-}
-
-/**
- * Evaluates boundary impact: which boundary tags/layers are crossed by the
- * affected edges.
- *
- * Unlike `evolutionAlignment.boundaries` which collects edge identities, this
- * evaluates whether the change crosses meaningful governance boundaries (e.g.
- * layer transitions, scope crossings).
- *
- * @param {object} graph The project graph.
- * @param {object[]} constraintImpact Per-dependent constraint analysis.
- * @param {string} targetProject The target of the impact analysis.
- * @returns {{boundaries: object[], evaluated: boolean}}
- */
-function evaluateBoundaryImpact(graph, constraintImpact, targetProject) {
-  if (!constraintImpact || constraintImpact.length === 0) {
-    return { boundaries: [], evaluated: false };
-  }
-
-  const targetNode = graph.nodes[targetProject];
-  const targetTags = targetNode?.data?.tags ?? [];
-  const boundaries = [];
-
-  for (const entry of constraintImpact) {
-    const sourceTags = graph.nodes[entry.project]?.data?.tags ?? [];
-
-    for (const edge of entry.edges) {
-      // Determine if this edge crosses a layer boundary
-      const sourceLayer = sourceTags.find((t) => t.startsWith("layer:"));
-      const targetLayer = targetTags.find((t) => t.startsWith("layer:"));
-      const crossesLayer = sourceLayer && targetLayer && sourceLayer !== targetLayer;
-
-      // Determine if this edge crosses a scope boundary
-      const sourceScope = sourceTags.find((t) => t.startsWith("scope:"));
-      const targetScope = targetTags.find((t) => t.startsWith("scope:"));
-      const crossesScope = sourceScope && targetScope && sourceScope !== targetScope;
-
-      // Determine if any constraint row governs this edge
-      const violated = entry.violations?.length > 0;
-      const governingRowCount = entry.constraintRows?.length ?? 0;
-
-      boundaries.push({
-        source: entry.project,
-        target: edge.target,
-        type: edge.type,
-        crossesLayer,
-        crossesScope,
-        violated,
-        governingConstraintRows: governingRowCount,
-      });
-    }
-  }
-
-  return { boundaries, evaluated: true };
-}
-
 /**
  * Composes the full Impact Statement for a project.
  *
@@ -439,45 +92,17 @@ export function composeImpactStatement(projectName, commandContext, config = nul
   const { root, graph } = commandContext;
   const { findings: availableFindings = null, debt: availableDebt = null } = options;
 
-  // Step 1: Reverse reachability (existing primitive)
-  const impact = computeImpact(projectName, graph);
-
-  // Step 2: Edge and constraint impact (existing primitive)
-  let constraintImpact = null;
-  if (config && config.depConstraints) {
-    constraintImpact = computeImpactConstraints(
-      projectName,
-      impact.dependents,
-      graph.nodes,
-      graph.dependencies,
-      config.depConstraints,
-    );
-  }
-
-  // Step 3: Decision impact (with evidence)
-  let decisionImpact = null;
-  if (constraintImpact) {
-    decisionImpact = buildDecisionImpact(root, constraintImpact, config);
-  }
-
-  // Step 4: Evolution alignment
-  const resolvedDecisions = decisionImpact ? decisionImpact.decisions.map((d) => d.id) : [];
-  const evolutionAlignment = buildEvolutionAlignment(
+  // Delegate to the canonical evaluator — one semantic evaluator, many views
+  const evaluation = evaluateArchitectureState({
+    graph,
+    config,
     projectName,
-    impact,
-    constraintImpact,
-    resolvedDecisions,
-  );
-
-  // Step 5: Boundary impact evaluation
-  const boundaryImpact = evaluateBoundaryImpact(graph, constraintImpact, projectName);
-
-  // Step 6: Findings and Debt impact evaluation
-  const affectedProjects = [projectName, ...impact.dependents];
-  const findingsImpact = evaluateFindingsImpact(affectedProjects, availableFindings);
-  const debtImpact = evaluateDebtImpact(affectedProjects, availableDebt);
+    root,
+    findings: availableFindings,
+    debt: availableDebt,
+  });
 
-  // Step 7: Assemble the statement with evidence and coverage notes
+  // Build impact-statement-specific notes
   const notes = [];
 
   if (config && config.depConstraints) {
@@ -488,14 +113,14 @@ export function composeImpactStatement(projectName, commandContext, config = nul
     );
   }
 
-  if (!findingsImpact.evaluated) {
+  if (!evaluation.findingsImpact.evaluated) {
     notes.push(
       "finding impact not evaluated — no findings data provided to impact statement. " +
         "Pass findings data for complete governance evaluation.",
     );
   }
 
-  if (!debtImpact.evaluated) {
+  if (!evaluation.debtImpact.evaluated) {
     notes.push(
       "debt impact not evaluated — no debt data provided to impact statement. " +
         "Pass debt data for complete governance evaluation.",
@@ -503,29 +128,26 @@ export function composeImpactStatement(projectName, commandContext, config = nul
   }
 
   const statement = {
-    project: impact.project,
-    impact: {
-      direct: impact.direct,
-      transitive: impact.transitive,
-      dependents: impact.dependents,
-    },
-    evolutionAlignment,
-    findingsImpact,
-    debtImpact,
-    boundaryImpact,
-    complete: true,
+    project: evaluation.project,
+    impact: evaluation.impact,
+    evolutionAlignment: evaluation.evolutionAlignment,
+    findingsImpact: evaluation.findingsImpact,
+    debtImpact: evaluation.debtImpact,
+    boundaryImpact: evaluation.boundaryImpact,
+    completeness: evaluation.completeness,
+    complete: evaluation.completeness.overallComplete,
     notes,
   };
 
-  if (constraintImpact) {
-    statement.constraintImpact = constraintImpact;
+  if (evaluation.constraintImpact) {
+    statement.constraintImpact = evaluation.constraintImpact;
   }
 
-  if (decisionImpact) {
-    statement.decisionImpact = decisionImpact;
-    if (decisionImpact.unresolvedDecisionRefs.length > 0) {
+  if (evaluation.decisionImpact) {
+    statement.decisionImpact = evaluation.decisionImpact;
+    if (evaluation.decisionImpact.unresolvedDecisionRefs.length > 0) {
       statement.notes.push(
-        `unresolved decision references: ${decisionImpact.unresolvedDecisionRefs.join(", ")}`,
+        `unresolved decision references: ${evaluation.decisionImpact.unresolvedDecisionRefs.join(", ")}`,
       );
     }
   }

package/src/commands/impact.mjs

@@ -161,8 +161,11 @@ export function impactCommand(projectName, commandContext, config = null) {
         `under-represent the real architecture. Fix the unanalyzed files and re-run.`,
     );
   }
+  const blindSpots = commandContext.analysis.failures
+    .filter((f) => !isWholeFileFailure(f))
+    .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason }));
 
-  const complete = true;
+  const complete = true; // whole-file failures already threw above
   const status = "ok";
   const exitCode = 0;
 
@@ -172,9 +175,7 @@ export function impactCommand(projectName, commandContext, config = null) {
     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,
     notes: [
       "per-edge violations cover only depConstraints (3 of 15 violation types). " +
         "A dependent with no violations here may still violate npm-ban, circular-dependency, " +

package/src/commands/provenance-command.mjs

@@ -82,6 +82,7 @@ import {
   hasAuthority,
   unresolvedDecisionRefRows,
 } from "../governance/adr-registry.mjs";
+import { buildProvenanceGraph } from "../governance/provenance-graph.mjs";
 
 /**
  * Whether a row declares a governance origin (`origin.by`/`origin.tool`).
@@ -224,6 +225,10 @@ export function unresolvedDecisionRefNote(decisionRef) {
  *     supersededBy: string[], bindings: string[],
  *     attribution: {createdBy: object|null, lastChangedBy: object|null},
  *     attested: boolean, note: string|null}[],
+ *   provenanceGraph: {nodes: object[], edges: object[], claims: object[],
+ *     causalChains: object[]},
+ *   claims: {id: string, kind: string, verdict: string,
+ *     evidence: {kind: string, detail: string}[]}[],
  *   report: {text: string, json: string}}>}
  * @throws {Error} on a malformed intent, boundary config, or ADR registry —
  *   exit 3, the loud refusal every command that reads them makes.
@@ -339,6 +344,24 @@ export async function provenanceCommand(commandContext, io = {}) {
     });
   }
 
+  // PR4 — provenance graph: compose nodes, edges, claims, and causal chains
+  // from the already-resolved repo, rows, and decision lifecycle.
+  const graphRows = governanceRows.map(({ kind, row }) => ({
+    kind,
+    attested: hasOrigin(row),
+    origin: hasOrigin(row) ? row.origin : null,
+    decisionRef: row?.decisionRef ?? undefined,
+    label: rowLabel(kind, row),
+  }));
+  const provenanceGraph = buildProvenanceGraph({
+    repo,
+    rows: graphRows,
+    records: adrContext.records,
+    byId: adrContext.byId,
+    knownFitness: declaredFitnessNames(loadedConfig),
+    decisionLifecycle,
+  });
+
   const establishment = repo !== null;
   const repoResult = establishment ? repo : { commit: null, remote: null, dirty: null };
   const rowsTotal = rowList.length;
@@ -358,6 +381,7 @@ export async function provenanceCommand(commandContext, io = {}) {
     decisionRefTotal: decisionRefRows.length,
     unresolvedDecisionRefs,
     decisionLifecycle,
+    provenanceGraph,
   });
 
   const context = {
@@ -397,14 +421,19 @@ export async function provenanceCommand(commandContext, io = {}) {
       unattested: unattested.map(({ kind, label, note }) => ({ kind, label, note })),
       unresolvedDecisionRefs,
       decisionLifecycle,
+      provenanceGraph: {
+        nodes: provenanceGraph.nodes,
+        edges: provenanceGraph.edges,
+        claims: provenanceGraph.claims,
+        causalChains: provenanceGraph.causalChains,
+      },
+      claims: provenanceGraph.claims,
     },
   });
 
   return {
     status: "ok",
     repo: { ...repoResult, established: establishment },
-    // The four answer surfaces, also available readably (not only inside the
-    // envelope) so `cli.mjs` can drive the text report from the same facts.
     rows: rowList.map(({ kind, attested, origin }) => ({
       kind,
       attested,
@@ -413,6 +442,8 @@ export async function provenanceCommand(commandContext, io = {}) {
     unattested: unattested.map(({ kind, label, note }) => ({ kind, label, note })),
     unresolvedDecisionRefs,
     decisionLifecycle,
+    provenanceGraph,
+    claims: provenanceGraph.claims,
     report: {
       text: reportText,
       json: renderJson(envelope),