@ecoma-io/archkeep 0.27.0 → 0.28.0

package/README.md

@@ -3,7 +3,7 @@
 **Architecture governance for polyglot repositories** — a deterministic
 authority that keeps the architecture your team declared aligned with the code
 your team keeps changing. Dependency graphs and module boundaries for Go, Rust,
-Python, TypeScript, JavaScript, Vue, Java, Kotlin and C#, with Nx and Moon as first-class
+Python, TypeScript and JavaScript, Vue, Java, Kotlin and C#, with Nx and Moon as first-class
 integrations. Coding agents read the same verdicts, machine-readably, through
 the `arch-*` skills. The system boundary — what Archkeep is and what it is not —
 is owned by [architecture-authority.md](https://github.com/ecoma-io/archkeep/blob/main/docs/doctrine/architecture-authority.md).
@@ -166,8 +166,10 @@ a file it cannot edit ([overview.md](https://github.com/ecoma-io/archkeep/blob/m
   mismatch, undeclared imports) refuses the run — never a silent skip
   ([custom-rules.md](https://github.com/ecoma-io/archkeep/blob/main/docs/concepts/custom-rules.md),
   [writing one](https://github.com/ecoma-io/archkeep/blob/main/docs/usage/custom-rules.md)).
-- **Shipped policy packs** — Clean Architecture, hexagonal, layered modular
-  monolith and DDD bounded contexts, as ready-made profile registries under
+- **Shipped policy packs** — six shipped packs: Clean Architecture, hexagonal,
+  traditional layering, layered modular monolith, vertical slices and DDD
+  bounded contexts, as
+  ready-made profile registries under
   this package's `presets/` directory. Copy one into your workspace, or point
   the `profiles` option straight at it; either way it is enforced by the same
   path a registry you wrote yourself is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Architecture authority for human and agentic software development — deterministic, evidence-backed enforcement of declared architecture.",
   "keywords": [
     "architecture",
@@ -73,6 +73,7 @@
     "!src/custom-rules/wasm-fixture.mjs",
     "!src/report/envelope-shape.json",
     "!src/custom-rules/evidence-golden.json",
+    "!src/fixtures/",
     "presets/",
     "LICENSE",
     "README.md"

package/src/analysis/jvm/gradle.mjs

@@ -69,6 +69,12 @@
  * below THROWS on the same list (#364's posture, `../source-util.mjs`'s
  * `refuseUnreadTree`), so `nx affected` fails loudly instead of
  * under-selecting on it.
+ *
+ * A settings file that cannot be READ at all — one `readFile` throws on, an
+ * unreadable include file — is refused with a thrown Error naming the file
+ * path, not an empty include list (#847): a missing settings file is fine
+ * (a root may have no reactor), but a settings file whose read fails must
+ * not collapse the reactor to "no includes" silently.
  */
 
 import { normalizePath } from "../manifest-util.mjs";
@@ -380,12 +386,27 @@ function buildGradleModel(workspace) {
   for (const dir of candidateDirs) {
     for (const name of SETTINGS_FILENAMES) {
       const path = normalizePath(dir, name);
-      if (readFile(path) !== null && readFile(path) !== undefined) settingsFiles.push(path);
+      try {
+        if (readFile(path) !== null && readFile(path) !== undefined) settingsFiles.push(path);
+      } catch (cause) {
+        throw new Error(
+          `Gradle settings file '${path}' could not be read: ${cause?.message ?? cause}`,
+          { cause },
+        );
+      }
     }
   }
   for (const settingsPath of settingsFiles) {
     const settingsDir = dirnameOf(settingsPath);
-    const settingsText = readFile(settingsPath);
+    let settingsText;
+    try {
+      settingsText = readFile(settingsPath);
+    } catch (cause) {
+      throw new Error(
+        `Gradle settings file '${settingsPath}' could not be read: ${cause?.message ?? cause}`,
+        { cause },
+      );
+    }
     const settingsParsed = parseGradleSettings(settingsText ?? "");
     if (settingsParsed.reason !== undefined) {
       failures.push({

package/src/commands/README.md

@@ -54,8 +54,10 @@ the resolution order.
   introduced/resolved/unchanged/unknown (`./delta-classify.mjs`), with
   unresolvable import sites carried as their own category, never counted as
   violations. Refuses an unreadable, malformed, foreign-schema, or
-  incomplete-coverage baseline, a provider mismatch (stricter than `diff`'s
-  note — violation identity across two project models is not evidence),
+  incomplete-coverage baseline, a `command`-carrying report envelope (a graph
+  snapshot is `diff`'s input, not delta evidence), a provider mismatch
+  (stricter than `diff`'s note — violation identity across two project models
+  is not evidence),
   incomplete head coverage, and an Nx workspace with polyglot manifests but no
   plugin registration; a policy-fingerprint change is a loud coverage note, not
   a refusal. A verdict, not a description: a non-waived introduced violation is
@@ -84,8 +86,9 @@ the resolution order.
   pins); an unproven base identity or an undeterminable
   constraint is exit 3, and constraints are left unevaluated over a base the
   run cannot vouch for. Refuses a manifest that fails shape or reference
-  validation, an unreadable/malformed/incomplete baseline, a provider
-  mismatch, incomplete head coverage, and the unregistered-plugin graph.
+  validation, an unreadable/malformed/incomplete baseline, a `command`-carrying
+  report envelope in its place, a provider mismatch, incomplete head coverage,
+  and the unregistered-plugin graph.
 
 - **`impact`** (`./impact.mjs`'s `impactCommand`) — reverse reachability from
   the project graph: given a project name, lists every project that transitively

package/src/commands/change.mjs

@@ -76,8 +76,9 @@
  * 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,
+ * unreadable/malformed/foreign-schema baseline, a `command`-carrying report
+ * envelope in its place, 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).
  *

package/src/commands/delta-snapshot.mjs

@@ -320,6 +320,10 @@ export function readEvidenceSnapshot(path, io = {}) {
  *
  * Refusals, each loud:
  * - unreadable/malformed JSON — named with the path and the parse error;
+ * - a `command` field — that marker belongs to a report envelope (the graph
+ *   family), so the document is not delta evidence at all; the family is
+ *   decided before the schemaVersion refusals, whose "newer version" advice
+ *   would be false for a file this binary itself wrote;
  * - a `schemaVersion` that is not the integer this format uses — a FUTURE
  *   version refuses too: a reader that half-understood a newer format would
  *   classify over evidence it misread;
@@ -360,6 +364,19 @@ export function parseEvidenceSnapshot(text, path) {
     );
   }
 
+  // A `command` field marks a report envelope — the graph family's document,
+  // not delta evidence. The family decides before the schemaVersion refusals
+  // below: that number is the OTHER format's version, so its "newer version;
+  // upgrade" advice would be false for a file this binary itself wrote (#810).
+  if (typeof parsed.command === "string") {
+    const pointer = parsed.command === "graph" ? " For graph snapshots use 'diff <baseline>'." : "";
+    throw new Error(
+      `archkeep: the evidence snapshot '${path}' has a 'command' field — it is not a delta ` +
+        `evidence snapshot, it is a '${parsed.command}' envelope. delta requires an evidence ` +
+        `snapshot (from 'delta --capture').${pointer}`,
+    );
+  }
+
   const problems = [];
   if (!Number.isInteger(parsed.schemaVersion)) {
     problems.push(

package/src/commands/delta.mjs

@@ -29,8 +29,10 @@
  * 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 baseline that cannot be read, parsed, or holds a foreign schemaVersion
- *   (`./delta-snapshot.mjs`'s loader owns those);
+ * - a baseline that cannot be read, parsed, or holds a foreign schemaVersion,
+ *   or a report envelope — a document carrying a `command` field (a graph
+ *   snapshot is `diff`'s input), refused as the wrong family before any
+ *   schemaVersion reading (`./delta-snapshot.mjs`'s loader owns those);
  * - a provider mismatch between baseline and this run (`providerMismatch`) —
  *   a THROW here where `diff` settles for a note, because violation IDENTITY
  *   across two different project models is not trustworthy: the same tree

package/src/commands/scenario-evaluation.mjs

@@ -152,11 +152,13 @@ function cloneGraph(graph) {
  *
  * @param {object} graph The base graph to apply changes to.
  * @param {DependencyChange[]} changes The hypothetical changes.
- * @returns {{graph: object, applied: string[], refused: string[]}}
+ * @returns {{graph: object, applied: string[],
+ *   mutations: {type: string, source: string, target: string}[], refused: string[]}}
  */
 function applyChanges(graph, changes) {
   const cloned = cloneGraph(graph);
   const applied = [];
+  const mutations = [];
   const refused = [];
 
   for (const change of changes) {
@@ -203,6 +205,7 @@ function applyChanges(graph, changes) {
         source: change.source,
       });
       applied.push(`added dependency: ${change.source} → ${change.target} (${change.edgeType})`);
+      mutations.push({ type: "dependency_added", source: change.source, target: change.target });
     }
 
     if (change.type === "dependency_removed") {
@@ -238,6 +241,7 @@ function applyChanges(graph, changes) {
       existing.splice(idx, 1);
       const typeLabel = change.edgeType ? ` (${change.edgeType})` : "";
       applied.push(`removed dependency: ${change.source} → ${change.target}${typeLabel}`);
+      mutations.push({ type: "dependency_removed", source: change.source, target: change.target });
     }
   }
   // Clean up empty dependency arrays
@@ -247,7 +251,7 @@ function applyChanges(graph, changes) {
     }
   }
 
-  return { graph: cloned, applied, refused };
+  return { graph: cloned, applied, mutations, refused };
 }
 
 /**
@@ -410,6 +414,50 @@ function resolveBaseRevision(root, userBase) {
   };
 }
 
+/**
+ * Merges constraint-impact rows for the named project's own changed edges
+ * into one side's rows (#809), preserving the row shape the primitive
+ * returns — no new fields, no second judgment.
+ *
+ * One row per project: when the side already carries a row for the project,
+ * the edge, constraint-row and violation lists union without duplicates
+ * (constraint rows match by identity — they are the config's own row
+ * objects; violations by value, since `judgeEdge` builds fresh objects);
+ * otherwise the row is appended. Appending keeps every pre-existing row
+ * byte-identical and the order deterministic, because it follows the
+ * input changes' order.
+ *
+ * @param {{project: string, edges: object[], constraintRows: object[],
+ *   violations: object[]}[]} rows The side's constraint impact, mutated in place.
+ * @param {{project: string, edges: object[], constraintRows: object[],
+ *   violations: object[]}[]} merged Rows computed for the changed edge.
+ */
+function mergeConstraintImpact(rows, merged) {
+  for (const row of merged) {
+    const existing = rows.find((r) => r.project === row.project);
+    if (!existing) {
+      rows.push(row);
+      continue;
+    }
+    for (const edge of row.edges) {
+      if (!existing.edges.some((e) => e.target === edge.target && e.type === edge.type)) {
+        existing.edges.push(edge);
+      }
+    }
+    for (const constraintRow of row.constraintRows) {
+      if (!existing.constraintRows.includes(constraintRow)) {
+        existing.constraintRows.push(constraintRow);
+      }
+    }
+    for (const violation of row.violations) {
+      const identity = JSON.stringify(violation);
+      if (!existing.violations.some((v) => JSON.stringify(v) === identity)) {
+        existing.violations.push(violation);
+      }
+    }
+  }
+}
+
 /**
  * Evaluates a scenario against the current workspace.
  *
@@ -452,7 +500,12 @@ export function evaluateScenario(
   }
 
   // Step 3: Apply scenario changes to the graph
-  const { graph: scenarioGraph, applied, refused } = applyChanges(graph, scenarioInput.changes);
+  const {
+    graph: scenarioGraph,
+    applied,
+    mutations,
+    refused,
+  } = applyChanges(graph, scenarioInput.changes);
 
   // Step 4: Compute scenario impact
   const scenarioImpact = computeImpact(projectName, scenarioGraph);
@@ -468,6 +521,47 @@ export function evaluateScenario(
     );
   }
 
+  // Step 4b: the named project's own changed edges (#809).
+  //
+  // `computeImpactConstraints` judges edges INTO the target from its
+  // dependents, so a change whose SOURCE is the named project never enters
+  // that frame — an edge pointing out of the target is invisible to it, and
+  // the source-named run reported `unchanged` where the target-named run of
+  // the same change reported the violation. The rows for the changed edge
+  // are computed here by the same primitive — never a second judgment — and
+  // merged into the frame the edge actually belongs to: additions into the
+  // scenario side (the edge exists only there), removals into the current
+  // side (it exists only there).
+  if (config && config.depConstraints) {
+    for (const mutation of mutations) {
+      if (mutation.source !== projectName) continue;
+      if (mutation.type === "dependency_added") {
+        mergeConstraintImpact(
+          scenarioConstraintImpact,
+          computeImpactConstraints(
+            mutation.target,
+            [mutation.source],
+            scenarioGraph.nodes,
+            scenarioGraph.dependencies,
+            config.depConstraints,
+          ),
+        );
+      }
+      if (mutation.type === "dependency_removed") {
+        mergeConstraintImpact(
+          currentConstraintImpact,
+          computeImpactConstraints(
+            mutation.target,
+            [mutation.source],
+            graph.nodes,
+            graph.dependencies,
+            config.depConstraints,
+          ),
+        );
+      }
+    }
+  }
+
   // Step 5: Build decision impact for both sides
   const currentDecisionImpact = buildDecisionImpact(root, currentConstraintImpact, config);
   const scenarioDecisionImpact = buildDecisionImpact(root, scenarioConstraintImpact, config);

package/src/corpus/goldens/adr.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "adr",
   "workspace": {

package/src/corpus/goldens/change.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "change",
   "workspace": {
@@ -45,7 +45,7 @@
       "path": "<fixture-root>/.archkeep-delta.json",
       "tool": {
         "name": "@ecoma-io/archkeep",
-        "version": "0.27.0"
+        "version": "0.28.0"
       },
       "provider": "native",
       "provenance": {

package/src/corpus/goldens/check.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "check",
   "workspace": {

package/src/corpus/goldens/context.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "context",
   "workspace": {

package/src/corpus/goldens/debt.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "debt",
   "workspace": {

package/src/corpus/goldens/decisions.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "decisions",
   "workspace": {

package/src/corpus/goldens/delta.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "delta",
   "workspace": {
@@ -31,7 +31,7 @@
       "path": "<fixture-root>/.archkeep-delta.json",
       "tool": {
         "name": "@ecoma-io/archkeep",
-        "version": "0.27.0"
+        "version": "0.28.0"
       },
       "provider": "native",
       "provenance": {

package/src/corpus/goldens/diff.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "diff",
   "workspace": {
@@ -33,7 +33,7 @@
       "path": "<fixture-root>/.archkeep-graph.json",
       "projects": 3,
       "edges": 2,
-      "toolVersion": "0.27.0",
+      "toolVersion": "0.28.0",
       "provenance": {
         "commit": "1fd51709c377d99a6139891e1200291cf08aede9",
         "remote": null,

package/src/corpus/goldens/discover.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "discover",
   "workspace": {

package/src/corpus/goldens/drift.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "drift",
   "workspace": {

package/src/corpus/goldens/evolution.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "evolution",
   "workspace": {

package/src/corpus/goldens/explain.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "explain",
   "workspace": {

package/src/corpus/goldens/fitness.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "fitness",
   "workspace": {

package/src/corpus/goldens/graph.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "graph",
   "workspace": {

package/src/corpus/goldens/health.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "health",
   "workspace": {

package/src/corpus/goldens/history.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "history",
   "workspace": {

package/src/corpus/goldens/impact.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "impact",
   "workspace": {

package/src/corpus/goldens/provenance.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "provenance",
   "workspace": {

package/src/corpus/goldens/reconcile.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "reconcile",
   "workspace": {

package/src/corpus/goldens/report.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "report",
   "workspace": {

package/src/corpus/goldens/scenario.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "scenario",
   "workspace": {

package/src/corpus/goldens/trajectory.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "trajectory",
   "workspace": {

package/src/corpus/goldens/waivers.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "tool": {
     "name": "@ecoma-io/archkeep",
-    "version": "0.27.0"
+    "version": "0.28.0"
   },
   "command": "waivers",
   "workspace": {

package/src/governance/provenance-graph.mjs

@@ -5,9 +5,10 @@
  * to `{attested, attribution}`. When `fileAttribution` cannot answer (returns
  * null), every decision is unattested.
  *
- * This is the shared helper both `buildProvenanceGraph` and the impact/scenario
- * evaluation callers use, so decision provenance is computed identically
- * everywhere — "via the same graph helper, never re-derived" (PR4).
+ * This is the shared helper the impact and scenario evaluation callers use, so
+ * decision provenance is computed identically everywhere — "via the same graph
+ * helper, never re-derived" (PR4). `buildProvenanceGraph` is not a caller: it
+ * reads attestation from its `decisionLifecycle` input directly (#882).
  *
  * @param {{id: string}[]} records ADR records
  * @param {(path: string) => {createdBy: object|null,
@@ -92,9 +93,6 @@ import { resolveDecisionRef, stripRuleFitnessPrefix, stripAdrPrefix } from "./ad
  *   Decision record lookup map.
  * @property {Set<string>} knownFitness
  *   Fitness record names for resolution.
- * @property {(path: string) => object|null} [fileAttribution]
- *   Resolves git attribution for a decision record file. Passed through to
- *   `computeDecisionProvenance`. Defaults to a function that always returns null.
  * @property {{id: string, attested: boolean, attribution: object|null}[]}
  *   decisionLifecycle
  * @typedef {object} ProvenanceGraphNode
@@ -172,7 +170,6 @@ export function buildProvenanceGraph({
   records = [],
   byId = new Map(),
   knownFitness = new Set(),
-  fileAttribution: _fileAttribution = () => null,
   decisionLifecycle = [],
 }) {
   const nodes = [];
@@ -408,7 +405,12 @@ export function buildProvenanceGraph({
       for (const nextId of sortedArray(record.supersedes)) {
         if (!visited.has(nextId)) {
           queue.push(nextId);
-          parentMap.set(nextId, currentId);
+          // First queued parent wins: when a second supersession path reaches
+          // a decision already queued, overwriting its parent would drop the
+          // first path's hop from the chain while `edges` keeps both relations.
+          if (!parentMap.has(nextId)) {
+            parentMap.set(nextId, currentId);
+          }
         }
       }
 
@@ -457,7 +459,9 @@ export function buildProvenanceGraph({
       causalChains.push({
         id: chainId,
         startNode: rowId,
-        endNode: `decision:${chainNodes[chainNodes.length - 1]}`,
+        // `chainNodes` entries are node ids already (`decision:<id>`); wrapping
+        // them a second time emitted the dangling `decision:decision:<id>`.
+        endNode: chainNodes[chainNodes.length - 1],
         hops: chainEdges,
       });
     }