@ecoma-io/archkeep 0.16.1 → 0.17.0

package/README.md

@@ -225,7 +225,7 @@ Ten minutes end to end, most of it spent deciding what your tags mean:
 Ten minutes end to end, most of it spent deciding what your tags mean:
 [**Getting started →**](https://github.com/ecoma-io/archkeep/blob/main/docs/getting-started/installation.md). `graph`, `diff`,
 `history`, `trajectory`, `evolution`, `drift`, `impact`, `explain`,
-`context` and the rest of the 22-command surface are in the
+`context` and the rest of the 23-command surface are in the
 [CLI reference](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/cli.md).
 
 ## Documentation map

package/cli.mjs

@@ -107,6 +107,7 @@ import {
 import { contextCommand } from "./src/commands/context-command.mjs";
 import { planContextCommand } from "./src/commands/plan-context-command.mjs";
 import { adrCommand } from "./src/commands/adr.mjs";
+import { decisionsCommand } from "./src/commands/decisions.mjs";
 import { diffCommand } from "./src/commands/diff.mjs";
 import { captureDelta, deltaCommand } from "./src/commands/delta.mjs";
 import { discoverCommand } from "./src/commands/discover.mjs";
@@ -1712,6 +1713,73 @@ async function runAdr(options, { cwd, env }) {
   // Descriptive: 0 for answered, 3 for incomplete coverage.
   return result.status === "ok" ? EXIT.ok : EXIT.error;
 }
+/**
+ * `decisions`'s run: the deterministic chain behind one recorded decision —
+ * decision → governed rows → projects → current findings, with the
+ * per-decision verification level. Exactly one positional: the ADR id.
+ *
+ * The law is resolved the way `report` resolves it (`resolvePolicy`) because
+ * the chain's Fitness leg reads the workspace's declared gates, and `--config`
+ * wins the same way. Fitness verdicts are derived inside the command from the
+ * declared list; a declared gate that fails to evaluate THROWS (exit 3), it
+ * never silently walks clean. `0` when every hop of the chain resolved, `3`
+ * when any did not — never `1`.
+ *
+ * @param {{format: string, output: string|null, config: string|null, paths: string[]}} options
+ * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
+ * @returns {Promise<number>}
+ */
+async function runDecisions(options, { cwd, env }) {
+  if (options.paths.length !== 1) {
+    env.err(
+      `archkeep: decisions takes exactly one positional argument (an ADR id); ` +
+        `got ${options.paths.length}`,
+    );
+    return EXIT.usage;
+  }
+
+  let result;
+  try {
+    const commandContext = resolveCommandContext(
+      { cwd },
+      { readGraph: env.readGraph, listFiles: env.listFiles },
+    );
+
+    // ONE law for the chain, resolved exactly like `report` — the Fitness leg
+    // reads this law's declared gates, so a `--config` override must reach it.
+    const { config } = await resolvePolicy(options, commandContext, cwd);
+
+    const intent = commandContext.tracked.includes(INTENT_FILE)
+      ? await loadIntent(commandContext.root, { tracked: commandContext.tracked })
+      : null;
+
+    result = decisionsCommand(options.paths[0], commandContext, config, { intent });
+  } catch (error) {
+    const usageError = error instanceof UsageError;
+    env.err(String(error?.message ?? error));
+    return usageError ? EXIT.usage : EXIT.error;
+  }
+
+  const report = options.format === "json" ? result.report.json : result.report.text;
+
+  if (options.output) {
+    // Atomic, symlink-safe write — `writeOutputReport`'s own docstring owns
+    // the mechanism and the threat it closes.
+    const reportText = report.endsWith("\n") ? report : `${report}\n`;
+    if (!writeOutputReport(options.output, reportText, env, cwd, options.config)) return EXIT.error;
+    // The confirmation names the no-verdict case, so a reader who only
+    // glances at stderr cannot mistake a written chain for a resolved one.
+    env.err(
+      `archkeep: decision chain for ${options.paths[0]} ` +
+        `${result.status === "ok" ? "resolved" : "did NOT fully resolve"} → ${options.output}`,
+    );
+  } else {
+    env.out(report);
+  }
+
+  // Descriptive: 0 when every hop resolved, 3 when any could not. Never 1.
+  return result.status === "ok" ? EXIT.ok : EXIT.error;
+}
 
 /**
  * `rules`'s `run`: dispatches to the appropriate subcommand (list/info/verify/add),
@@ -2985,6 +3053,42 @@ const EXPLAIN_FLAG_HELP = Object.freeze([
   }),
 ]);
 
+/**
+ * `decisions`'s flags: text or JSON envelope, optional file output, and the
+ * same `--config` override `report` takes — the chain's Fitness leg reads the
+ * declared gates of one boundary law, and a caller must be able to say which.
+ *
+ * @type {readonly FlagHelp[]}
+ */
+const DECISIONS_FLAG_HELP = Object.freeze([
+  Object.freeze({
+    flag: "--format",
+    key: "format",
+    arg: "text|json",
+    describe: Object.freeze([
+      "Terminal report (default) or the versioned JSON envelope",
+      "docs/reference/json-output.md documents",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--output",
+    key: "output",
+    arg: "<file>",
+    describe: Object.freeze(["Write the report to a file instead of stdout"]),
+  }),
+  Object.freeze({
+    flag: "--config",
+    key: "config",
+    arg: "<file>",
+    describe: ({ boundaryConfig, inline }) =>
+      Object.freeze([
+        "Read the boundary law from here instead of",
+        inline
+          ? "the inline boundaryConfig in archkeep.json"
+          : `<workspace root>/${boundaryConfig}`,
+      ]),
+  }),
+]);
 /**
  * `context`'s flags: text or JSON envelope, optional file output.
  * The project name is a positional argument. `--config` overrides the boundary
@@ -3317,6 +3421,17 @@ const COMMANDS = Object.freeze({
     formats: DESCRIBABLE_FORMATS,
     run: runProvenance,
   }),
+  decisions: Object.freeze({
+    name: "decisions",
+    args: "<id>",
+    summary:
+      "Walk the full chain behind one recorded decision — decision to bound rows, projects, findings, and its verification level",
+    flagHelp: DECISIONS_FLAG_HELP,
+    flags: Object.freeze(Object.fromEntries(DECISIONS_FLAG_HELP.map((f) => [f.flag, f.key]))),
+    defaults: Object.freeze({ format: "text", output: null, config: null }),
+    formats: DESCRIBABLE_FORMATS,
+    run: runDecisions,
+  }),
   adr: Object.freeze({
     name: "adr",
     args: "[<id>]",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript, Vue, Java and Kotlin",
   "keywords": [
     "architecture",

package/src/commands/adr.mjs

@@ -55,6 +55,20 @@
  * `bindings` beside `knownFitness`, at exit 0. Naming a limit is not a
  * verdict; leaving it unnamed would be the silent direction
  * (`../../../../AGENTS.md`).
+ * ## What it can say about fitness
+ *
+ * Wave 2's fitness derivation (`../governance/decision-fitness.mjs`) folds a
+ * decision's bound constraints and their verdicts into one per-decision
+ * level. It is NOT wired into this command's own read: `adr` stays the
+ * registry-only surface it was. The caller may hand verdicts in through
+ * `io.fitnessVerdicts` (the same `{name, verdict}` shape `fitness` produces)
+ * and every record then renders its level — `verified` only when a bound
+ * constraint passes. Without verdicts the derivation still runs, and its
+ * honest answer is echoed: a decision with authority but nothing verifiable
+ * is `unverifiable` — never healthy — while a status without authority is
+ * `not_applicable`. An empty verdict set is not silence; it is the registry
+ * alone asserting nothing. Levels never change the exit code: `adr` remains
+ * 0/2/3, a description of what is recorded, not a gate.
  */
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import {
@@ -65,6 +79,8 @@ import {
 } from "../report/adr-text.mjs";
 import { ADR_DIR, stripAdrPrefix } from "../governance/adr-registry.mjs";
 import { adrsBinding, boundFitnessIds, loadAdrRegistry } from "../governance/adr-registry.mjs";
+import { computeDecisionFitness } from "../governance/decision-fitness.mjs";
+import { stripRuleFitnessPrefix } from "../governance/adr-registry.mjs";
 
 /**
  * The other half of the id name space the positional argument answers
@@ -124,8 +140,11 @@ export function readAdrContext(root, io = {}) {
  * @param {{id?: string}} options
  * @param {{loadAdrRegistryOverride?: typeof loadAdrRegistry, tracked?: string[],
  *   lstatSync?: (path: string) => {isSymbolicLink: () => boolean},
- *   realpathSync?: (path: string) => string}} [io] Forwarded to
- *   `readAdrContext` unchanged.
+ *   realpathSync?: (path: string) => string, fitnessVerdicts?:
+ *   Array<{name: string, verdict: string}>}} [io] `tracked`, `lstatSync` and
+ *   `realpathSync` are forwarded to `readAdrContext` unchanged; `fitnessVerdicts`
+ *   feeds the per-decision fitness derivation ("What it can say about fitness"
+ *   in the module header owns what an absent array means).
  * @returns {{status: "ok"|"no-verdict", result: object, coverage: object,
  *   report: {text: string, json: string}}}
  * @throws {Error} on an unreadable registry (exit-3 class).
@@ -135,6 +154,21 @@ export function adrCommand(root, options, io = {}) {
 
   const { records, byId, knownFitness } = ctx;
 
+  // Per-decision fitness: the wave-2 derivation, fed a lookup built from
+  // whatever verdicts the caller can supply (`io.fitnessVerdicts`, the same
+  // `{name, verdict}` shape the `fitness` command emits). A binding's prefix
+  // (`rule:`/`fitness:`) is stripped before the lookup — a verdict names a
+  // declared fitness id, and `fitness:hotspot` and `hotspot` are the same id.
+  // An empty verdict set is a legitimate input: every authority decision then
+  // derives `unverifiable`, which is the registry alone asserting nothing —
+  // the module header's "What it can say about fitness" owns the wording.
+  const verdictByName = new Map((io.fitnessVerdicts ?? []).map((v) => [v.name, v]));
+  const fitnessLookup = (bindingId) => verdictByName.get(stripRuleFitnessPrefix(bindingId));
+  const fitnessById = new Map(
+    computeDecisionFitness(records, null, fitnessLookup).map((entry) => [entry.id, entry]),
+  );
+  const fitness = [...fitnessById.values()];
+
   // An id the caller asked about that the registry does not know is a named
   // unknown, not a clean result — the invariant. Two cases, told apart by the
   // id's shape: a `rule:x`/`fitness:x` ref (`FITNESS_REF_PATTERN`, above) is a
@@ -194,15 +228,22 @@ export function adrCommand(root, options, io = {}) {
     supersedes: records.flatMap((record) =>
       record.supersedes.map((ref) => ({ adr: record.id, supersedes: ref })),
     ),
+    // The derived reverse link — the records whose `supersedes` names this
+    // one — so a machine reader of the envelope sees the same lineage the
+    // text face shows.
+    supersededBy: records.flatMap((record) =>
+      record.supersededBy.map((id) => ({ adr: record.id, supersededBy: id })),
+    ),
+    fitness,
     unresolved,
     knownFitness: [...knownFitness].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
   };
 
   const text =
     requestedId === undefined
-      ? formatAdrDump({ records, knownFitness })
+      ? formatAdrDump({ records, knownFitness, fitnessById })
       : byId.has(resolvedAdrId)
-        ? formatAdrRecord(byId.get(resolvedAdrId), knownFitness)
+        ? formatAdrRecord(byId.get(resolvedAdrId), knownFitness, fitnessById)
         : isFitnessRef
           ? formatAdrReverse({ fitnessId: requestedId, adrIds: adrsBinding(records, requestedId) })
           : formatAdrMissing({ adrId: requestedId });

package/src/commands/decisions.mjs

@@ -0,0 +1,291 @@
+/**
+ * The `decisions` command: the deterministic chain behind one recorded
+ * architecture decision — decision → the governed rows that stand on it
+ * (intent + constraint + fitness) → the projects they govern → the current
+ * evidence/findings, and the decision's verification level.
+ *
+ * It composes the wave-2 modules without owning any of them:
+ *
+ * - `../governance/adr-registry.mjs` — the read of `docs/adr/` and the
+ *   record index (`readAdrContext` below is this module's thin wrapper);
+ * - `../governance/decision-graph.mjs` — `forwardDecision`, the walk that
+ *   attaches governed rows, projects and evidence, and reports every hop it
+ *   cannot resolve in `walk.unresolved`;
+ * - `../governance/decision-fitness.mjs` — `computeDecisionFitness`, the
+ *   per-decision verification level;
+ * - `./provenance-command.mjs` — `intentRows`/`configRows`, the same row
+ *   walk `provenance` uses, so this command never holds a second copy of
+ *   which rows exist.
+ *
+ * It is descriptive, like `adr`/`report`: it never exits 1. The chain is a
+ * description of what is recorded and whether it is currently satisfied, not
+ * a finding. What it DOES refuse, loudly (exit 3, never clean):
+ *
+ * - an unreadable registry — a read that throws propagates to the caller;
+ * - a reference that does not resolve — either the positional `<id>` naming
+ *   no ADR record, or any hop of the walk (`walk.unresolved`), including a
+ *   binding that names no governed row. A chain that could not walk every hop
+ *   is rendered as an unresolved block, never as a clean chain (the
+ *   invariant, `../../../../AGENTS.md`).
+ *
+ * ## What the chain's Fitness leg verifies
+ *
+ * A decision's `bindings` name rule/fitness ids. This command walks the
+ * workspace's declared `fitness` list (like `report` does) and evaluates
+ * those functions against the same snapshot the `fitness` command builds, so
+ * a binding that names a declared gate derives its real verdict. A binding
+ * naming no declared gate derives `unverifiable` — the registry alone asserts
+ * nothing, never a clean pass. The whole derivation is deterministic: the
+ * same tree, the same law, the same chain.
+ */
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatDecisionChain } from "../report/decisions-text.mjs";
+import { readAdrContext } from "./adr.mjs";
+import { forwardDecision } from "../governance/decision-graph.mjs";
+import { computeDecisionFitness } from "../governance/decision-fitness.mjs";
+import { stripAdrPrefix, stripRuleFitnessPrefix } from "../governance/adr-registry.mjs";
+import { intentRows, configRows, rowLabel } from "./provenance-command.mjs";
+import { evaluateFitness, fitnessSnapshot } from "../governance/fitness-registry.mjs";
+import { hasTag, isComboDepConstraint } from "../rules/tags.mjs";
+import { resolveMembers } from "../architecture-intent/selectors.mjs";
+import { evaluate } from "../rules/index.mjs";
+
+/**
+ * The projects whose tags satisfy a constraint row's source selector — the
+ * same match `findConstraintsFor` (`../rules/tags.mjs`) makes, so the row's
+ * `governs` never disagrees with the row a rule actually applies to.
+ *
+ * @param {object} row A `depConstraints` row.
+ * @param {object} graph The project graph.
+ * @returns {string[]}
+ */
+function constraintGoverns(row, graph) {
+  return Object.entries(graph.nodes)
+    .filter(([, project]) =>
+      isComboDepConstraint(row)
+        ? row.allSourceTags.every((tag) => hasTag(project, tag))
+        : hasTag(project, row.sourceTag),
+    )
+    .map(([name]) => name)
+    .sort();
+}
+
+/**
+ * Resolves one intent side (`from`/`to`/`name`/`source`/`target`) to the
+ * projects it names: a declared boundary wins, else the side is an inline
+ * selector. Mirrors `sidePatterns` (`../architecture-intent/judge.mjs`).
+ *
+ * @param {object} intent The normalized intent model.
+ * @param {object} graph The project graph.
+ * @param {string} side A boundary name or inline selector.
+ * @returns {string[]}
+ */
+function sideProjects(intent, graph, side) {
+  const declared = (intent.boundaries ?? []).find((b) => b.name === side);
+  const patterns = declared ? declared.match : [side];
+  return resolveMembers(patterns, graph.nodes);
+}
+
+/**
+ * The projects one intent row governs, by row family — the "who does this
+ * row bind" answer. A row with no resolvable side governs nothing, which is
+ * itself a fact the walk reports (a governed project list is never assumed).
+ *
+ * @param {object} intent The normalized intent model.
+ * @param {object} graph The project graph.
+ * @param {object} row An intent row.
+ * @returns {string[]}
+ */
+function intentRowGoverns(intent, graph, row) {
+  if (typeof row.name === "string") return [row.name];
+  if (typeof row.from === "string") {
+    // `forbiddenTags` and the dependency rows claim the FROM side's edges;
+    // `allowed`/`forbidden` claim the boundary between both sides.
+    const from = sideProjects(intent, graph, row.from);
+    if (typeof row.to === "string") {
+      const to = sideProjects(intent, graph, row.to);
+      return Array.from(new Set([...from, ...to])).sort();
+    }
+    return from;
+  }
+  return [];
+}
+
+/**
+ * The verdicts of the workspace's declared fitness functions, folded into a
+ * `{name, verdict}` list — the same `{name, verdict}` shape `fitness` emits,
+ * so `computeDecisionFitness` can verify a decision's bound gates against
+ * this run's real judgements. Deterministic: same tree, same law, same list.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {object} config The resolved boundary law.
+ * @param {object|null} intent The normalized intent model, or null when the
+ *   workspace declares none.
+ * @returns {object[]} `[{name, verdict}, ...]`.
+ */
+function fitnessVerdictsFor(commandContext, config, intent) {
+  if (!Array.isArray(config?.fitness) || config.fitness.length === 0) return [];
+  const snapshot = fitnessSnapshot(commandContext, {
+    intent,
+    suppressions: config.suppressions ?? [],
+  });
+  return evaluateFitness(config.fitness, snapshot).map((decision) => ({
+    name: decision.name,
+    verdict: decision.verdict,
+  }));
+}
+
+/**
+ * The verdict for one `decisions` run: the payload for both renderers, the
+ * status, and the coverage that decides exit 0 against 3.
+ *
+ * @param {string} decisionId The ADR id to walk (`NNN-slug` or `adr:NNN-slug`).
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {object} config The resolved boundary law.
+ * @param {{intent?: object|null, fitnessVerdicts?: object[]}} [io]
+ *   `intent` is the normalized intent model (or null); `fitnessVerdicts`
+ *   overrides the run's own evaluation — a test supplies a fixed list.
+ * @returns {{status: "ok"|"no-verdict", result: object, coverage: object,
+ *   report: {text: string, json: string}}}
+ * @throws {Error} on an unreadable registry, a malformed law, or a config
+ *   declaring fitness that fails to evaluate — exit-3 class.
+ */
+export function decisionsCommand(decisionId, commandContext, config, io = {}) {
+  const intent = io.intent ?? null;
+
+  // The registry read — throws on an unreadable `docs/adr/`, which the caller
+  // maps to exit 3. Never a clean result.
+  const { records, byId, knownFitness } = readAdrContext(commandContext.root, {
+    tracked: commandContext.tracked,
+  });
+
+  // The governed rows the walk attaches: intent rows and config constraint
+  // rows, each carrying the governance block and the projects it governs.
+  // `governs` is derived deterministically from the graph, so the walk never
+  // has to re-resolve a selector.
+  const rowsFromIntent = intent === null ? [] : intentRows(intent);
+  /** @type {import("../governance/decision-graph.mjs").GovernedRow[]} */
+  const rows = [
+    ...rowsFromIntent.map(
+      ({ kind, row }) =>
+        /** @type {import("../governance/decision-graph.mjs").GovernedRow} */ ({
+          id: rowLabel(kind, row),
+          kind: "intent",
+          decisionRef: row.decisionRef,
+          governs: intentRowGoverns(intent, commandContext.graph, row),
+        }),
+    ),
+    ...configRows(config).map(
+      ({ kind, row }) =>
+        /** @type {import("../governance/decision-graph.mjs").GovernedRow} */ ({
+          id: rowLabel(kind, row),
+          kind: "constraint",
+          decisionRef: row.decisionRef,
+          governs: constraintGoverns(row, commandContext.graph),
+        }),
+    ),
+    // The declared fitness gates themselves, keyed by their name — the same
+    // id space `declaredFitnessNames`/`stripRuleFitnessPrefix` use, so a
+    // decision binding `fitness:cycle-free` resolves to the gate that exists.
+    ...(Array.isArray(config?.fitness) ? config.fitness : []).map(
+      (gate) =>
+        /** @type {import("../governance/decision-graph.mjs").GovernedRow} */ ({
+          id: gate.name,
+          kind: "fitness",
+          governs: resolveMembers(gate.match ?? ["*"], commandContext.graph.nodes),
+        }),
+    ),
+  ];
+
+  // The evidence leg: findings for the projects the rows govern, built from
+  // the same evaluation `check` runs. A path-scoped or graph-less context
+  // would leave this lookup undefined and `attachRowLeg` reports it as an
+  // unresolved walk — never a quiet "no findings" claim.
+  const violations = evaluate(commandContext.analysis.imports, commandContext.graph, config);
+  const findingsByProject = new Map();
+  for (const violation of violations) {
+    const list = findingsByProject.get(violation.sourceProject) ?? [];
+    list.push({
+      id: `${violation.sourceFile}:${violation.line}:${violation.column}`,
+      project: violation.sourceProject,
+      ruleId: violation.messageId,
+    });
+    findingsByProject.set(violation.sourceProject, list);
+  }
+
+  const walk = forwardDecision(decisionId, {
+    records,
+    byId,
+    knownFitness,
+    rows,
+    findingsByProject: (project) => findingsByProject.get(project) ?? [],
+  });
+
+  // The per-decision fitness derivation, folded with THIS run's verdicts —
+  // the `{name, verdict}` list from the declared fitness gates above (or the
+  // caller's override). `computeDecisionFitness`'s second argument carries
+  // verdicts but is unused; the lookup is the single door, so it is null.
+  const verdicts = io.fitnessVerdicts ?? fitnessVerdictsFor(commandContext, config, intent);
+  const verdictByName = new Map(verdicts.map((v) => [v.name, v]));
+  const fitnessLookup = (bindingId) => verdictByName.get(stripRuleFitnessPrefix(bindingId));
+  const fitnessById = new Map(
+    computeDecisionFitness(records, null, fitnessLookup).map((entry) => [entry.id, entry]),
+  );
+
+  const record = byId.get(stripAdrPrefix(decisionId)) ?? null;
+  const result = {
+    decisionId,
+    record,
+    walk,
+    fitness: record === null ? undefined : fitnessById.get(record.id),
+    knownFitness: [...knownFitness].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+  };
+
+  const unresolved = walk.unresolved;
+  const status = walk.ok ? "ok" : "no-verdict";
+  const exitCode = status === "ok" ? 0 : 3;
+
+  const coverage = {
+    complete: walk.ok,
+    projects: Object.keys(commandContext.graph?.nodes ?? {}).length,
+    analyzedFiles: commandContext.analysis?.analyzed ?? 0,
+    imports: (commandContext.analysis?.imports ?? []).length,
+    notAnalyzed: unresolved.map(({ ref, kind: ukind, reason }) => ({
+      file: ukind === "decision" ? `${ref}.md` : ref,
+      reason,
+    })),
+    blindSpots: [],
+    notes: [],
+  };
+
+  const envelope = jsonEnvelope({
+    command: "decisions",
+    context: {
+      root: commandContext.root,
+      provider: commandContext.provider ?? "native",
+      marker: "docs/adr",
+      provenance: null,
+    },
+    status,
+    exitCode,
+    coverage,
+    result,
+  });
+
+  const text = formatDecisionChain({
+    decisionId,
+    record,
+    walk,
+    fitness: result.fitness,
+  });
+
+  return {
+    status,
+    result,
+    coverage,
+    report: {
+      text: `${text}\n`,
+      json: renderJson(envelope),
+    },
+  };
+}