@ecoma-io/archkeep 0.16.1 → 0.18.0

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),
+    },
+  };
+}

package/src/commands/delta-classify.mjs

@@ -65,6 +65,7 @@
 import { canonicalizeJson } from "../canonical.mjs";
 import { suppressionCovers } from "../config.mjs";
 import { referenceTime } from "../governance/clock.mjs";
+import { classifyEvolution } from "../governance/evolution-event.mjs";
 import { suppressionFate } from "../governance/waiver.mjs";
 import { namespacedId } from "./custom-rules.mjs";
 
@@ -491,6 +492,262 @@ export function classifyDelta(input) {
   };
 }
 
+/**
+ * The stable identity string of one classified delta violation entry, for an
+ * evolution event's `findings` (`../governance/evolution-event.mjs`) — the
+ * delta's own identity facts, never a second spelling: `messageId`,
+ * `sourceProject`, the target (project or specifier, with the marker saying
+ * which), and the canonical constraint row that fired. `baseCount`/`headCount`
+ * and the sites are attached evidence, exactly as they are outside identity in
+ * `violationIdentity` — a growth or shrink changes counts, not what the
+ * violation IS.
+ *
+ * @param {object} entry One classified entry from `classifyViolations` or
+ *   `classifyDelta`'s `violations` buckets.
+ * @returns {string} The canonical identity string.
+ */
+function deltaEntryIdentity(entry) {
+  return canonicalizeJson({
+    messageId: entry.messageId,
+    sourceProject: entry.sourceProject ?? null,
+    target: entry.target ?? null,
+    targetIsSpecifier: entry.targetIsSpecifier === true,
+    constraint: entry.constraint ?? null,
+  });
+}
+
+/**
+ * The best name an UNCLASSIFIABLE delta entry can honestly carry into an
+ * event's `unknown` list — the identity it has, or an honest absence. The
+ * reason is the load-bearing half (`classifyEvolution` discloses each with
+ * it); the id exists so the note can name the entry.
+ *
+ * @param {{violation?: object}} entry A violation-classification unknown.
+ * @returns {string}
+ */
+function unknownViolationIdentity(entry) {
+  const violation = entry?.violation;
+  if (violation !== null && typeof violation === "object") {
+    const messageId = typeof violation.messageId === "string" ? violation.messageId : null;
+    const target =
+      typeof violation.targetProject === "string" && violation.targetProject !== ""
+        ? violation.targetProject
+        : typeof violation.specifier === "string" && violation.specifier !== ""
+          ? violation.specifier
+          : null;
+    if (messageId !== null || target !== null) {
+      return `violation ${messageId ?? "?"}${target === null ? "" : ` → ${target}`}`;
+    }
+  }
+  return "unidentifiable violation";
+}
+
+/** The same best-name discipline for an unresolvable-record unknown. */
+function unknownRecordIdentity(entry) {
+  const record = entry?.record;
+  if (
+    record !== null &&
+    typeof record === "object" &&
+    typeof record.specifier === "string" &&
+    record.specifier !== ""
+  ) {
+    return `unresolvable import '${record.specifier}'`;
+  }
+  return "unidentifiable unresolvable import";
+}
+
+/**
+ * The delta event's `findings` (design §1) mapped from a delta capture: the
+ * identity strings of the classified violations, plus every verdict-relevant
+ * unknown the run disclosed — violation unknowns, unresolvable-record
+ * unknowns, and custom-rule unknowns, each with its reason. Unresolvable
+ * introduced/resolved records are NOT findings: the delta carries them but
+ * never counts them as violations (no rule reached a verdict about them), and
+ * the event's findings mirror the delta's gating vocabulary.
+ *
+ * @param {object} delta The `deltaCommand` result payload (`violations`,
+ *   `unresolvable`, optional `customRules`).
+ * @returns {{introduced: string[], resolved: string[], unknown: {id: string,
+ *   reason: string}[]}}
+ */
+export function deltaFindings(delta) {
+  return {
+    introduced: delta.violations.introduced.map(deltaEntryIdentity),
+    resolved: delta.violations.resolved.map(deltaEntryIdentity),
+    unknown: [
+      ...delta.violations.unknown.map((entry) => ({
+        id: unknownViolationIdentity(entry),
+        reason: entry.reason,
+      })),
+      ...delta.unresolvable.unknown.map((entry) => ({
+        id: unknownRecordIdentity(entry),
+        reason: entry.reason,
+      })),
+      ...(delta.customRules === undefined
+        ? []
+        : delta.customRules.findings.unknown.map((entry) => ({
+            id: `custom rule '${entry.rule}'`,
+            reason: entry.reason,
+          }))),
+    ],
+  };
+}
+
+/**
+ * The identity string of one graph edge, in the design's canonical spelling
+ * `source>target:type` (the `(source, target, type)` identity the design
+ * §1 names, printed the way `docs/concepts/evolution.md`'s example shows).
+ * The ONE spelling the delta's event `observed.edges`/`affected.boundaries`
+ * use — a second spelling somewhere would be a second definition of "same
+ * edge", and two definitions drift.
+ *
+ * @param {{source: string, target: string, type: string}} edge
+ * @returns {string}
+ */
+export function edgeEvolutionIdentity({ source, target, type }) {
+  return `${source}>${target}:${type}`;
+}
+
+/**
+ * The delta event's per-constraint verdict deltas (design §1 `fitness`),
+ * derived from the classified entries the capture already carries — never a
+ * re-judgment. A constraint's base/head verdict is judged from the entries
+ * that name it: `fail` when an entry attributes any live site to that side
+ * (`baseCount`/`headCount`), `pass` otherwise. Only rows whose verdict MOVED
+ * are deltas — a constraint failing on both sides moved nothing, and a
+ * half-fixed one is the delta's report of the half it moved. Rows are sorted
+ * by constraint identity, so two runs over the same capture are
+ * byte-identical.
+ *
+ * @param {object} delta The `deltaCommand` result payload.
+ * @returns {{constraint: string, base: "pass"|"fail", head: "pass"|"fail"}[]}
+ */
+export function deltaVerdictDeltas(delta) {
+  const entries = [
+    ...delta.violations.introduced,
+    ...delta.violations.resolved,
+    ...delta.violations.unchanged,
+  ];
+  /** @type {Map<string, {base: number, head: number}>} */
+  const byConstraint = new Map();
+  for (const entry of entries) {
+    if (entry.constraint === undefined || entry.constraint === null) continue;
+    const id = canonicalizeJson(entry.constraint);
+    const row = byConstraint.get(id) ?? { base: 0, head: 0 };
+    if (entry.baseCount > 0) row.base += 1;
+    if (entry.headCount > 0) row.head += 1;
+    byConstraint.set(id, row);
+  }
+  /** @type {{constraint: string, base: "pass"|"fail", head: "pass"|"fail"}[]} */
+  const deltas = [];
+  for (const [constraint, counts] of byConstraint) {
+    /** @type {"pass"|"fail"} */
+    const base = counts.base > 0 ? "fail" : "pass";
+    /** @type {"pass"|"fail"} */
+    const head = counts.head > 0 ? "fail" : "pass";
+    if (base === head) continue;
+    deltas.push({ constraint, base, head });
+  }
+  return deltas;
+}
+
+/**
+ * The §1 mapping for a delta capture: feeds the delta's OWN signals — the
+ * classified violations with their waiver state, the policy-change fact, and
+ * the structural-change/code-drift signals the caller supplies when it
+ * computed them — to `classifyEvolution` (`../governance/evolution-event.mjs`),
+ * the one home of the classification predicates, and returns its verdict.
+ * This module adds no second opinion about what a class means; it maps.
+ *
+ * The delta's verdict-relevant unknowns — violation unknowns, unresolvable-
+ * record unknowns, custom-rule unknowns — are passed through as
+ * `violations.unknown`, so `classifyEvolution`'s fail-closed discipline holds
+ * for every item the delta itself could not place: each raises a `notes[]`
+ * disclosure and forces disposition `no-verdict`; none is ever folded into a
+ * clean class.
+ *
+ * `affected.constraints` is the one delta-specific derivation: the delta's
+ * governed constraints are the `depConstraints` rows its classified
+ * introduced/resolved entries name (the capture output carries each row), and
+ * no reconcile-vocabulary verdict exists for them — so they are mapped from
+ * the entries, never invented. `affected.projects`/`boundaries`/`decisions`
+ * come from `classifyEvolution`'s own mapping of the supplied signals.
+ *
+ * @param {object} delta The `deltaCommand` result payload.
+ * @param {{projects?: {added: string[], removed: string[], changed: string[]},
+ *   edges?: {added: string[], removed: string[]}, codeDrift?: boolean}} [signals]
+ *   The structural-change and drift signals a delta run derives from the two
+ *   graphs it holds (the graph diff is `diff`'s vocabulary, shared here, never
+ *   re-derived) — `projects`/`edges` carry identity strings (`edgeEvolutionIdentity`
+ *   for edges), and `codeDrift` is the delta's computed "provenance advanced,
+ *   no arch/policy change" fact. Absent signals are empty, so a delta that
+ *   computed none reads as a violation-only mapping.
+ * @returns {{classifications: string[], disposition: "accepted"|"rejected"|"no-verdict",
+ *   notes: string[], affected: {projects: string[], boundaries: string[],
+ *   constraints: string[], decisions: string[]}}} The full
+ *   `EvolutionClassification` — `classifications`/`notes` per the wave
+ *   contract, with `disposition`/`affected` riding from the one definition so
+ *   no caller re-derives either.
+ */
+export function classifyDeltaEvolution(delta, signals = {}) {
+  const projects = signals.projects ?? { added: [], removed: [], changed: [] };
+  const edges = signals.edges ?? { added: [], removed: [] };
+  const evolution = classifyEvolution({
+    observed: {
+      projects,
+      edges,
+      // `null` survives: it is the one-sided policy case, and `classifyEvolution`
+      // reads it as "could not be compared" — never as "the same". The
+      // one-sided/advanced facts are input facts the payload carries (F-HIST-1):
+      // both-sides-absent is also `null` but stays comparable.
+      policyChanged: delta.policyChanged,
+      policyOneSided: delta.policyOneSided,
+      provenanceChanged: delta.provenanceChanged,
+    },
+    codeDrift: signals.codeDrift === true,
+    violations: {
+      introduced: delta.violations.introduced.map((entry) => ({
+        id: deltaEntryIdentity(entry),
+        waived: entry.waived === true,
+      })),
+      resolved: delta.violations.resolved.map(deltaEntryIdentity),
+      unknown: [
+        ...delta.violations.unknown.map((entry) => ({
+          id: unknownViolationIdentity(entry),
+          reason: entry.reason,
+        })),
+        ...delta.unresolvable.unknown.map((entry) => ({
+          id: unknownRecordIdentity(entry),
+          reason: entry.reason,
+        })),
+        ...(delta.customRules === undefined
+          ? []
+          : delta.customRules.findings.unknown.map((entry) => ({
+              id: `custom rule '${entry.rule}'`,
+              reason: entry.reason,
+            }))),
+      ],
+    },
+  });
+
+  /** @type {Set<string>} */
+  const constraintIds = new Set();
+  for (const entry of [...delta.violations.introduced, ...delta.violations.resolved]) {
+    if (entry.constraint === undefined || entry.constraint === null) continue;
+    constraintIds.add(canonicalizeJson(entry.constraint));
+  }
+
+  return {
+    classifications: evolution.classifications,
+    disposition: evolution.disposition,
+    notes: evolution.notes,
+    affected: {
+      ...evolution.affected,
+      constraints: [...constraintIds].sort(cmpString),
+    },
+  };
+}
+
 /** Identity-or-reason wrapper applied to every raw violation. */
 function identityOf(violation) {
   const result = violationIdentity(violation);