@ecoma-io/archkeep 0.17.0 → 0.18.1

package/cli.mjs

@@ -93,6 +93,11 @@
  */
 import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+/*** @type {{name: string, version: string}} */
+const { name: TOOL_NAME, version: TOOL_VERSION } = require("./package.json");
 
 import { containmentViolation } from "./src/containment.mjs";
 import { UsageError } from "./src/errors.mjs";
@@ -931,12 +936,8 @@ async function runDiff(options, { cwd, env }) {
  *
  * `--capture` writes the evidence snapshot a later run compares against;
  * `delta <baseline>` loads one, re-judges both sides under the current law,
- * and folds the classification into the exit code — the one descriptive-family
- * verb beside `check` and `fitness` whose verdict carries exit 1
- * (`./src/commands/delta.mjs` owns the fold).
- *
  * @param {{format: string, output: string|null, config: string|null, capture: boolean,
- *   paths: string[]}} options
+ *   eventOut: string|null, paths: string[]}} options
  * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
  * @returns {Promise<number>}
  */
@@ -948,6 +949,13 @@ async function runDelta(options, { cwd, env }) {
       );
       return EXIT.usage;
     }
+    if (options.eventOut !== null) {
+      env.err(
+        `archkeep: delta --capture does not take --event-out — an event records a transition, ` +
+          `and a capture is one side of it`,
+      );
+      return EXIT.usage;
+    }
   } else if (options.paths.length !== 1) {
     env.err(
       `archkeep: delta takes exactly one positional argument (the baseline evidence snapshot), ` +
@@ -972,7 +980,6 @@ async function runDelta(options, { cwd, env }) {
       const { text } = captureDelta(commandContext, { config });
       if (options.output) {
         // Atomic, symlink-safe write — `writeOutputReport`'s own docstring
-        // owns the mechanism and the threat it closes.
         if (!writeOutputReport(options.output, text, env, cwd, options.config)) return EXIT.error;
         env.err(`archkeep: delta baseline captured → ${options.output}`);
       } else {
@@ -985,7 +992,10 @@ async function runDelta(options, { cwd, env }) {
     const baselinePath = isAbsolute(options.paths[0])
       ? resolve(options.paths[0])
       : resolve(cwd, options.paths[0]);
-    result = await deltaCommand(baselinePath, commandContext, { config });
+    result = await deltaCommand(baselinePath, commandContext, {
+      config,
+      eventOut: options.eventOut,
+    });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1009,6 +1019,18 @@ async function runDelta(options, { cwd, env }) {
     env.out(report);
   }
 
+  // The event the run recorded, when `--event-out` was given — the store's
+  // own `duplicate` answer, so a rerun over the same transition says so
+  // instead of implying a second event was appended. Capture mode refuses the
+  // flag upstream; this line runs only for a compare.
+  if (result.eventWrite !== null) {
+    env.err(
+      `archkeep: evolution event ${
+        result.eventWrite.duplicate ? "duplicate, already recorded" : "recorded"
+      } → ${options.eventOut}`,
+    );
+  }
+
   // The exit fold `deltaCommand` computed: a non-waived introduced violation
   // is a finding, an unclassifiable item is a no-verdict, anything else is
   // clean — mapped here the same way `fitness`'s status is.
@@ -1214,7 +1236,7 @@ async function runReconcile(options, { cwd, env }) {
  * `check` remains the authority on the law.
  *
  * @param {{format: string, output: string|null, config: string|null,
- *   intent: string|null, paths: string[]}} options
+ *   intent: string|null, eventOut?: string|null, paths: string[]}} options
  * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function,
  *   listFiles?: Function}}} runContext
  * @returns {Promise<number>}
@@ -1271,7 +1293,19 @@ async function runChange(options, { cwd, env }) {
     // profile-aware the same way `check` is.
     const { config } = await resolvePolicy(options, commandContext, cwd);
 
-    result = await changeCommand(baselinePath, intentPath, commandContext, { config });
+    // `--event-out` names the reconcile event store directory, resolved from
+    // cwd like the other path flags; `undefined` when absent, so a run
+    // without the flag writes no event and stays byte-identical.
+    const eventOut =
+      typeof options.eventOut === "string" && options.eventOut !== ""
+        ? isAbsolute(options.eventOut)
+          ? options.eventOut
+          : resolve(cwd, options.eventOut)
+        : undefined;
+    result = await changeCommand(baselinePath, intentPath, commandContext, {
+      config,
+      ...(eventOut === undefined ? {} : { eventOut }),
+    });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1581,7 +1615,7 @@ async function runExplain(options, { cwd, env }) {
  * same as `check` and `explain`, because the answer depends on which boundary
  * law is in effect.
  *
- * @param {{format: string, output: string|null, config: string|null, plan: boolean, paths: string[]}} options
+ * @param {{format: string, output: string|null, config: string|null, plan: boolean, paths: string[], historyDir: string|null}} options
  * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
  * @returns {Promise<number>}
  */
@@ -1622,8 +1656,14 @@ async function runContextCommand(options, { cwd, env }) {
     // profile-aware the same way `check` is.
     const { config } = await resolvePolicy(options, commandContext, cwd);
 
+    const historyDir = options.historyDir
+      ? isAbsolute(options.historyDir)
+        ? options.historyDir
+        : resolve(cwd, options.historyDir)
+      : null;
+
     result = options.plan
-      ? await planContextCommand(projectName, scopePaths, commandContext, config)
+      ? await planContextCommand(projectName, scopePaths, commandContext, config, historyDir)
       : contextCommand(projectName, commandContext, config);
   } catch (error) {
     const usageError = error instanceof UsageError;
@@ -2026,7 +2066,7 @@ async function runTrajectory(options, { cwd, env }) {
  * production both are undefined and every revision is read for real.
  *
  * @param {{format: string, output: string|null, base: string|null, head: string|null,
- *   paths: string[]}} options
+ *   eventOut: string|null, paths: string[]}} options
  * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
  * @returns {Promise<number>}
  */
@@ -2057,9 +2097,18 @@ async function runEvolution(options, { cwd, env }) {
 
   let result;
   try {
+    // `--event-out` names the transition event store directory, resolved from
+    // cwd like the other path flags; `null` when absent, so a run without the
+    // flag writes no event and stays byte-identical.
+    const eventOut =
+      typeof options.eventOut === "string" && options.eventOut !== ""
+        ? isAbsolute(options.eventOut)
+          ? options.eventOut
+          : resolve(cwd, options.eventOut)
+        : null;
     result = await evolutionCommand(
       root,
-      { base: options.base, head: options.head },
+      { base: options.base, head: options.head, eventOut },
       {
         readGraph: env.readGraph,
         listFiles: env.listFiles,
@@ -2098,7 +2147,7 @@ async function runEvolution(options, { cwd, env }) {
  * consumer-managed directory `history` reads, so a ledger ages across the
  * same snapshots the evolution record is built from.
  *
- * @param {{format: string, output: string|null, config: string|null, paths: string[]}} options
+ * @param {{format: string, output: string|null, config: string|null, events: string|null, paths: string[]}} options
  * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
  * @returns {Promise<number>}
  */
@@ -2126,7 +2175,10 @@ async function runDebt(options, { cwd, env }) {
     // profile-selected workspace resolves the same way `check` does.
     const { config } = await resolvePolicy(options, commandContext, cwd);
 
-    result = await debtCommand(dir, commandContext, { config });
+    result = await debtCommand(dir, commandContext, {
+      config,
+      events: options.events,
+    });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -2494,9 +2546,10 @@ const DELTA_FLAG_HELP = Object.freeze([
     key: "capture",
     arg: "",
     describe: Object.freeze([
-      "Write an evidence snapshot of the current tree",
+      "Print an evidence snapshot of the current tree",
       "(raw import records, graph, coverage, policy",
-      "fingerprint) for a later delta run to compare against",
+      "fingerprint) for a later delta run to compare against.",
+      "Without --output, the snapshot goes to stdout.",
     ]),
   }),
   Object.freeze({
@@ -2530,6 +2583,17 @@ const DELTA_FLAG_HELP = Object.freeze([
           : `<workspace root>/${boundaryConfig}`,
       ]),
   }),
+  Object.freeze({
+    flag: "--event-out",
+    key: "eventOut",
+    arg: "<dir>",
+    describe: Object.freeze([
+      "Append the delta's evolution event to this directory",
+      "(one canonical record per transition; idempotent — a",
+      "rerun over the same transition writes nothing new).",
+      "Absent: no event file is written",
+    ]),
+  }),
 ]);
 
 /**
@@ -2566,6 +2630,16 @@ const CHANGE_FLAG_HELP = Object.freeze([
     arg: "<file>",
     describe: Object.freeze(["Write the report to a file instead of stdout"]),
   }),
+  Object.freeze({
+    flag: "--event-out",
+    key: "eventOut",
+    arg: "<dir>",
+    describe: Object.freeze([
+      "Also write the reconcile EvolutionEvent to this directory",
+      "(one file per run, idempotent; the classification always",
+      "rides the envelope result — see docs/concepts/evolution.md)",
+    ]),
+  }),
   Object.freeze({
     flag: "--config",
     key: "config",
@@ -2839,6 +2913,16 @@ const EVOLUTION_FLAG_HELP = Object.freeze([
       "linear descendant of --base with no merges between",
     ]),
   }),
+  Object.freeze({
+    flag: "--event-out",
+    key: "eventOut",
+    arg: "<dir>",
+    describe: Object.freeze([
+      "Append one EvolutionEvent per revision pair to this directory",
+      "(idempotent — a re-run over the same pair records a duplicate, never",
+      "a second event). docs/concepts/evolution.md owns the event model.",
+    ]),
+  }),
 ]);
 
 /**
@@ -2981,6 +3065,15 @@ const DEBT_FLAG_HELP = Object.freeze([
           : `<workspace root>/${boundaryConfig}`,
       ]),
   }),
+  Object.freeze({
+    flag: "--events",
+    key: "events",
+    arg: "<dir>",
+    describe: Object.freeze([
+      "Link the evolution event store in <dir> so debt entries carry",
+      "introducedBy/resolvedBy refs and a resolved list",
+    ]),
+  }),
 ]);
 
 /**
@@ -3139,6 +3232,18 @@ const CONTEXT_FLAG_HELP = Object.freeze([
           : `<workspace root>/${boundaryConfig}`,
       ]),
   }),
+  Object.freeze({
+    flag: "--history-dir",
+    key: "historyDir",
+    arg: "<dir>",
+    describe: Object.freeze([
+      "Path to the workspace's history directory. When given and",
+      "the directory holds archived snapshots, the planning context",
+      "includes the architecture-debt snapshot: current violations,",
+      "exemptions, and gaps aged across the history. Used only with",
+      "`--plan`; ignored otherwise.",
+    ]),
+  }),
 ]);
 
 /**
@@ -3252,7 +3357,13 @@ const COMMANDS = Object.freeze({
     summary: "Classify how boundary violations moved between a captured baseline and head",
     flagHelp: DELTA_FLAG_HELP,
     flags: Object.freeze(Object.fromEntries(DELTA_FLAG_HELP.map((f) => [f.flag, f.key]))),
-    defaults: Object.freeze({ format: "text", output: null, config: null, capture: false }),
+    defaults: Object.freeze({
+      format: "text",
+      output: null,
+      config: null,
+      capture: false,
+      eventOut: null,
+    }),
     formats: DELTA_FORMATS,
     booleans: Object.freeze(["capture"]),
     run: runDelta,
@@ -3263,7 +3374,13 @@ const COMMANDS = Object.freeze({
     summary: "Reconcile a declared change intent against the architectural delta",
     flagHelp: CHANGE_FLAG_HELP,
     flags: Object.freeze(Object.fromEntries(CHANGE_FLAG_HELP.map((f) => [f.flag, f.key]))),
-    defaults: Object.freeze({ format: "text", output: null, config: null, intent: null }),
+    defaults: Object.freeze({
+      format: "text",
+      output: null,
+      config: null,
+      intent: null,
+      eventOut: null,
+    }),
     formats: DESCRIBABLE_FORMATS,
     run: runChange,
   }),
@@ -3346,7 +3463,13 @@ const COMMANDS = Object.freeze({
     summary: "Describe how the architecture evolved across a Git revision range",
     flagHelp: EVOLUTION_FLAG_HELP,
     flags: Object.freeze(Object.fromEntries(EVOLUTION_FLAG_HELP.map((f) => [f.flag, f.key]))),
-    defaults: Object.freeze({ format: "text", output: null, base: null, head: null }),
+    defaults: Object.freeze({
+      format: "text",
+      output: null,
+      base: null,
+      head: null,
+      eventOut: null,
+    }),
     formats: DESCRIBABLE_FORMATS,
     run: runEvolution,
   }),
@@ -3376,7 +3499,7 @@ const COMMANDS = Object.freeze({
     summary: "Print the architecture-debt ledger across snapshots",
     flagHelp: DEBT_FLAG_HELP,
     flags: Object.freeze(Object.fromEntries(DEBT_FLAG_HELP.map((f) => [f.flag, f.key]))),
-    defaults: Object.freeze({ format: "text", output: null, config: null }),
+    defaults: Object.freeze({ format: "text", output: null, config: null, events: null }),
     formats: DESCRIBABLE_FORMATS,
     run: runDebt,
   }),
@@ -3406,7 +3529,13 @@ const COMMANDS = Object.freeze({
     summary: "Show the architecture constraints that apply to a project",
     flagHelp: CONTEXT_FLAG_HELP,
     flags: Object.freeze(Object.fromEntries(CONTEXT_FLAG_HELP.map((f) => [f.flag, f.key]))),
-    defaults: Object.freeze({ format: "text", output: null, config: null, plan: false }),
+    defaults: Object.freeze({
+      format: "text",
+      output: null,
+      config: null,
+      plan: false,
+      historyDir: null,
+    }),
     formats: DESCRIBABLE_FORMATS,
     booleans: Object.freeze(["plan"]),
     run: runContextCommand,
@@ -3498,10 +3627,15 @@ export async function runCli(argv, env) {
   // one root-marker read and a clean run pays none.
   const help = () => usage(optionsForUsage(cwd));
 
+  // --help and --version are universal flags, handled before command dispatch.
   if (argv[0] === "--help" || argv[0] === "-h") {
     env.out(help());
     return EXIT.ok;
   }
+  if (argv[0] === "--version" || argv[0] === "-v") {
+    env.out(`${TOOL_NAME} ${TOOL_VERSION}`);
+    return EXIT.ok;
+  }
 
   const [maybeCommand, ...maybeRest] = argv;
   let commandName;
@@ -3512,6 +3646,11 @@ export async function runCli(argv, env) {
   } else if (Object.hasOwn(COMMANDS, maybeCommand)) {
     commandName = maybeCommand;
     rest = maybeRest;
+    // Subcommand --help: show the main help without "unknown option" error.
+    if (rest.includes("--help") || rest.includes("-h")) {
+      env.out(help());
+      return EXIT.ok;
+    }
   } else if (
     maybeCommand !== "" &&
     existsSync(isAbsolute(maybeCommand) ? maybeCommand : join(cwd, maybeCommand))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript, Vue, Java and Kotlin",
   "keywords": [
     "architecture",
@@ -53,7 +53,7 @@
   },
   "peerDependencies": {
     "@nx/eslint-plugin": ">=21",
-    "fast-xml-parser": "5.11.0",
+    "fast-xml-parser": "5.11.1",
     "nx": ">=21",
     "typescript": ">=5 <7",
     "vue": ">=3"

package/src/architecture-intent/judge.mjs

@@ -168,12 +168,15 @@ function codeDependencies(graph) {
  * @param {object} intent The normalized model from `./model.mjs`.
  * @param {{nodes: object, dependencies?: object}} graph
  * @returns {{verdict: "ok"|"findings"|"no-verdict",
- *   findings: object[], unresolved: object[], boundaries: object[], notes: string[]}}
+ *   findings: object[], unresolved: object[], boundaries: object[], notes: string[],
+ *   gaps: {from: string, to: string, note: string}[]}}
  *   `findings` are `{source, target, rule, boundaryFrom, boundaryTo, message}`;
  *   `unresolved` are `{boundary, issue}` for every empty side or empty
  *   boundary; `boundaries` are `{name, projects[]}` (sorted members); `notes`
  *   are coverage notes that change no verdict — today only an
- *   `"optional": true` `allowed` row whose statement is not yet built.
+ *   `"optional": true` `allowed` row whose statement is not yet built; `gaps`
+ *   carry the same rows' structured `{from, to}` identities (F-DEB-8), the
+ *   stable key the debt ledger hashes an aspirational-gap entry by.
  */
 export function judgeIntent(intent, graph) {
   const nodes = graph.nodes ?? {};
@@ -191,6 +194,7 @@ export function judgeIntent(intent, graph) {
   const findings = [];
   const unresolved = [];
   const notes = [];
+  const gaps = [];
 
   for (const boundary of boundaries) {
     if (boundary.projects.length === 0) {
@@ -291,9 +295,18 @@ export function judgeIntent(intent, graph) {
       // Absence tolerated — aspirational, not drift — but it is still a
       // coverage note and the caller threads it into the report's coverage
       // notes, so a reader can tell "optional and absent" from "never checked".
-      notes.push(
-        `optional allowed intent "${row.from}" → "${row.to}" is not yet observed — aspirational, not drift`,
-      );
+      const note = `optional allowed intent "${row.from}" → "${row.to}" is not yet observed — aspirational, not drift`;
+      notes.push(note);
+      // The structured `{from, to}` is the STABLE identity of the gap — the
+      // debt ledger keys an aspirational-gap entry by it (F-DEB-8), never by
+      // the prose note, so a reworded note does not re-key the fact.
+      gaps.push({
+        from: row.from,
+        to: row.to,
+        note,
+        boundaryFrom: from.boundaryName ?? row.from,
+        boundaryTo: to.boundaryName ?? row.to,
+      });
       return;
     }
     const pairs = [];
@@ -535,5 +548,5 @@ export function judgeIntent(intent, graph) {
 
   const verdict = findings.length > 0 ? "findings" : unresolved.length > 0 ? "no-verdict" : "ok";
 
-  return { verdict, findings, unresolved, boundaries, notes };
+  return { verdict, findings, unresolved, boundaries, notes, gaps };
 }

package/src/commands/change-intent.mjs

@@ -313,6 +313,43 @@ export function findChangeIntentViolations(raw) {
 
   return violations;
 }
+/**
+ * The breadth guard (wave 3, design §5): everything wrong with a NORMALIZED
+ * intent whose declaration is empty while its own prose asserts a change.
+ *
+ * An intent with zero declared rows — no project rows, no edge rows, no
+ * declared constraints — declares that NOTHING material will change. Its
+ * `summary`, if present, is the author's own statement of what the change
+ * does; when the rows are empty that statement is a claim nothing in the
+ * declaration can be verified against, and the reconciliation would read
+ * `matched` over an unchanged tree while the author's prose says the tree
+ * moved. Prose cannot assert what rows must state: this is the one bypass
+ * around the grammar's reject-by-name discipline, and it is refused loudly
+ * (`parseChangeIntent` throws, exit 3 upstream) instead of reconciling.
+ *
+ * The rule is deliberately stricter than "empty projects/edges": it also
+ * requires the constraints section empty. A declared constraint IS a row —
+ * `noNewViolations: true` states a verifiable promise, and an intent that
+ * declares one is not a catch-all no matter what its summary says.
+ *
+ * @param {object} intent A `parseChangeIntent` result — the normalized shape,
+ *   with absent raw sections already normalized to empty arrays.
+ * @returns {string[]} Messages; empty when the intent is not a catch-all.
+ */
+export function findChangeIntentBreadthViolations(intent) {
+  const declaredRows =
+    intent.projects.add.length +
+    intent.projects.remove.length +
+    intent.edges.add.length +
+    intent.edges.remove.length +
+    Object.keys(intent.constraints).length;
+  if (declaredRows > 0 || intent.summary === undefined) return [];
+  return [
+    "summary: the intent declares no rows (no projects, no edges, no constraints) while its " +
+      "summary asserts a material change — prose cannot assert what rows must state; declare " +
+      "the material consequences in the rows, or drop the summary",
+  ];
+}
 
 /**
  * Parses and validates change-intent text into the normalized shape the
@@ -346,16 +383,18 @@ export function parseChangeIntent(text, path) {
       { cause },
     );
   }
+  // Shape validation first, then the breadth guard over the NORMALIZED
+  // intent — the guard's subject is the intent as the command will consume
+  // it, with absent sections already normalized to empty expectations. Both
+  // name every violation at once in the one throw below, so a malformed
+  // catch-all is reported whole rather than piecemeal.
   const violations = findChangeIntentViolations(parsed);
-  if (violations.length > 0) {
-    throw new Error(
-      `archkeep: the change intent '${path}' is not a usable contract:\n  ` +
-        violations.join("\n  "),
-    );
-  }
-  return {
+  const intent = {
     version: parsed.version,
-    base: { commit: parsed.base.commit },
+    // Defensive access: an invalid `base` is caught by the shape violations
+    // below and thrown before this object is ever returned, so a missing
+    // section must not crash the normalization itself.
+    base: { commit: parsed.base?.commit },
     ...(parsed.summary === undefined ? {} : { summary: parsed.summary }),
     projects: {
       add: parsed.projects?.add ?? [],
@@ -367,6 +406,14 @@ export function parseChangeIntent(text, path) {
     },
     constraints: { ...(parsed.constraints ?? {}) },
   };
+  violations.push(...findChangeIntentBreadthViolations(intent));
+  if (violations.length > 0) {
+    throw new Error(
+      `archkeep: the change intent '${path}' is not a usable contract:\n  ` +
+        violations.join("\n  "),
+    );
+  }
+  return intent;
 }
 
 /**