@ecoma-io/archkeep 0.17.0 → 0.18.1

package/src/report/evolution-text.mjs

@@ -22,8 +22,10 @@ import { formatChanges, sanitize, transitionKind } from "./snapshot-text.mjs";
  * @param {{result: {base: string, head: string,
  *   revisions: {commit: string, id: string}[],
  *   transitions: {from: string, to: string, architectureChanged: boolean,
- *     changes: object|null, policyChanged: boolean|null, providerChanged: boolean,
- *     codeDrift: boolean, notes: string[]}[]}, coverage: object}} input
+ *     changes: object|null, policyChanged: boolean|null, policyOneSided: boolean,
+ *     provenanceChanged: boolean|null, providerChanged: boolean,
+ *     codeDrift: boolean, notes: string[], comparison?: object}[],
+ *   summary?: object}, coverage: object}} input
  * @returns {string}
  */
 export function formatEvolutionReport({ result, coverage }) {
@@ -62,6 +64,17 @@ export function formatEvolutionReport({ result, coverage }) {
     for (const note of transition.notes) {
       sections.push(`  ${note}`);
     }
+    // The per-transition comparison report — the eight questions answered on
+    // this one revision pair (design §6), from the envelope fields the command
+    // already computed. An incomparable axis is printed with its reason, never
+    // folded into silence.
+    if (transition.comparison) {
+      sections.push(``);
+      sections.push(
+        `  comparison for ${sanitize(transition.from.slice(0, 12))} → ${sanitize(transition.to.slice(0, 12))}`,
+      );
+      sections.push(...formatComparisonSection(transition.comparison));
+    }
   }
 
   if (changed === 0) {
@@ -79,5 +92,221 @@ export function formatEvolutionReport({ result, coverage }) {
     );
   }
 
+  // The range-wide summary — the same eight questions answered over the whole
+  // record, so a reader sees both the per-pair detail and the verdict carried
+  // by all of them together (design §8). An axis that any pair could not
+  // compare is reported as n/a with the reason, never as a fabricated clean
+  // aggregate.
+  if (result.summary) {
+    sections.push(``);
+    sections.push(`summary`);
+    sections.push(...formatSummarySection(result.summary));
+  }
+
   return sections.join("\n");
 }
+
+/**
+ * Renders an incomparable axis marker as `n/a — <reason>` (design §6). An
+ * axis that could not be answered is never folded into a clean "none".
+ *
+ * @param {{available: false, reason?: string}|undefined} axis
+ * @returns {string}
+ */
+function naWithReason(axis) {
+  return `n/a — ${axis?.reason ?? "not comparable"}`;
+}
+
+/**
+ * Renders one verdict value: a verdict string as-is, an incomparable marker
+ * as `n/a — <reason>`, and an absent value as `n/a` with a fallback reason.
+ *
+ * @param {string|{available: false, reason?: string}|undefined} value
+ * @param {string} [fallbackReason]
+ * @returns {string}
+ */
+function renderVerdict(value, fallbackReason) {
+  if (value === undefined || value === null) return `n/a — ${fallbackReason ?? "unknown"}`;
+  if (typeof value === "object" && value.available === false) {
+    return `n/a — ${value.reason ?? "not comparable"}`;
+  }
+  return String(value);
+}
+
+/**
+ * Names an edge for the report: `source→target:type` for the object shape the
+ * diff produces, plain text otherwise.
+ *
+ * @param {object|string} edge
+ * @returns {string}
+ */
+function edgeName(edge) {
+  return edge && typeof edge === "object"
+    ? `${edge.source}→${edge.target}${edge.type ? `:${edge.type}` : ""}`
+    : String(edge);
+}
+
+/**
+ * The report section for one transition's comparison (design §6) — the eight
+ * questions answered for that single revision pair. Reads the envelope fields
+ * the command computed; incomparable axes print `n/a — <reason>`, never a
+ * fabricated clean answer.
+ *
+ * @param {object} comparison One `result.transitions[i].comparison`.
+ * @returns {string[]} Report lines.
+ */
+function formatComparisonSection(comparison) {
+  const out = [];
+  const observed = comparison.observed ?? {};
+  const projects = observed.projects ?? {};
+  const edges = observed.edges ?? {};
+  const projectName = (p) => (typeof p === "string" ? p : (p?.name ?? JSON.stringify(p)));
+  const listLine = (label, items) =>
+    items.length === 0 ? [] : [`  ${label}: ${items.join(", ")}`];
+
+  out.push(`  disposition: ${comparison.disposition ?? "unknown"}`);
+  const cls = comparison.classifications ?? [];
+  out.push(`  classifications: ${cls.length === 0 ? "none" : cls.join(", ")}`);
+  out.push(`  architecture changed: ${observed.architectureChanged ? "yes" : "no"}`);
+  out.push(...listLine("projects added", (projects.added ?? []).map(projectName)));
+  out.push(...listLine("projects removed", (projects.removed ?? []).map(projectName)));
+  out.push(...listLine("projects changed", (projects.changed ?? []).map(projectName)));
+  out.push(...listLine("edges added", (edges.added ?? []).map(edgeName)));
+  out.push(...listLine("edges removed", (edges.removed ?? []).map(edgeName)));
+  if (observed.policyChanged === true || observed.policyChanged === false) {
+    out.push(`  policy changed: ${observed.policyChanged ? "yes" : "no"}`);
+  }
+  if (observed.policyOneSided === true) out.push(`  policy changed: one-sided`);
+  if (observed.providerChanged === true || observed.providerChanged === false) {
+    out.push(`  provider changed: ${observed.providerChanged ? "yes" : "no"}`);
+  }
+  if (observed.provenanceChanged === true) out.push(`  provenance changed: yes`);
+
+  const findings = comparison.findings;
+  if (findings?.available === false) out.push(`  drift findings: ${naWithReason(findings)}`);
+  else if (findings) {
+    out.push(
+      `  drift findings: introduced ${findings.introduced.length}, resolved ${findings.resolved.length}` +
+        (findings.unknown?.length ? `, unknown ${findings.unknown.length}` : ""),
+    );
+  }
+
+  const debt = comparison.debt;
+  if (debt?.available === false) out.push(`  debt: ${naWithReason(debt)}`);
+  else if (debt)
+    out.push(`  debt: introduced ${debt.introduced.length}, resolved ${debt.resolved.length}`);
+
+  const fitness = comparison.fitness;
+  if (fitness?.available === false) out.push(`  fitness: ${naWithReason(fitness)}`);
+  else if (fitness?.verdictDeltas) {
+    out.push(`  fitness:`);
+    for (const delta of fitness.verdictDeltas) {
+      out.push(`    ${delta.id}: ${renderVerdict(delta.base)} → ${renderVerdict(delta.head)}`);
+    }
+  }
+
+  const cov = comparison.coverage;
+  if (cov) {
+    out.push(
+      `  coverage: base ${cov.base?.projects ?? 0} project${cov.base?.projects === 1 ? "" : "s"} / ` +
+        `${cov.base?.analyzedFiles ?? 0} files / ${cov.base?.imports ?? 0} imports; ` +
+        `head ${cov.head?.projects ?? 0} / ${cov.head?.analyzedFiles ?? 0} / ${cov.head?.imports ?? 0}`,
+    );
+  }
+
+  const affected = comparison.affected;
+  if (affected) {
+    if (affected.projects?.length) out.push(`  affected projects: ${affected.projects.join(", ")}`);
+    if (affected.boundaries?.length)
+      out.push(`  affected boundaries: ${affected.boundaries.join(", ")}`);
+    if (affected.constraints?.length)
+      out.push(`  affected constraints: ${affected.constraints.join(", ")}`);
+    if (affected.decisions?.length)
+      out.push(`  affected decisions: ${affected.decisions.join(", ")}`);
+    if (
+      !["projects", "boundaries", "constraints", "decisions", "lineage"].some(
+        (key) => affected[key]?.length,
+      )
+    ) {
+      out.push(`  affected: none`);
+    }
+  }
+
+  for (const note of comparison.notes ?? []) out.push(`  note: ${note}`);
+  return out;
+}
+
+/**
+ * The report section for the whole-range summary (design §8) — the same eight
+ * questions answered over every transition together. Any axis with an
+ * incomparable transition prints `n/a — <reason>` naming that transition.
+ *
+ * @param {object} summary `result.summary`.
+ * @returns {string[]} Report lines.
+ */
+function formatSummarySection(summary) {
+  const out = [];
+  out.push(`  transitions: ${summary.transitions}`);
+  out.push(`  disposition: ${summary.disposition ?? "unknown"}`);
+  const cls = summary.classifications ?? [];
+  out.push(`  classifications: ${cls.length === 0 ? "none" : cls.join(", ")}`);
+
+  const observed = summary.observed ?? {};
+  const projects = observed.projects ?? {};
+  const edges = observed.edges ?? {};
+  const listLine = (label, items) =>
+    items.length === 0 ? [] : [`  ${label}: ${items.join(", ")}`];
+  out.push(
+    `  architecture changed in ${observed.architectureChanged ?? 0} transition${
+      observed.architectureChanged === 1 ? "" : "s"
+    }`,
+  );
+  out.push(...listLine("projects added", projects.added ?? []));
+  out.push(...listLine("projects removed", projects.removed ?? []));
+  out.push(...listLine("projects changed", projects.changed ?? []));
+  out.push(...listLine("edges added", (edges.added ?? []).map(edgeName)));
+  out.push(...listLine("edges removed", (edges.removed ?? []).map(edgeName)));
+  const policyChanged = observed.policyChanged;
+  if (policyChanged !== undefined && policyChanged !== null) {
+    out.push(
+      typeof policyChanged === "object" && policyChanged.available === false
+        ? `  policy: ${naWithReason(policyChanged)}`
+        : `  policy changed: ${policyChanged}`,
+    );
+  }
+  const findings = summary.findings;
+  if (findings?.available === false) out.push(`  drift findings: ${naWithReason(findings)}`);
+  else if (findings) {
+    out.push(
+      `  drift findings: introduced ${findings.introduced.length}, resolved ${findings.resolved.length}`,
+    );
+  }
+
+  const debt = summary.debt;
+  if (debt?.available === false) out.push(`  debt: ${naWithReason(debt)}`);
+  else if (debt)
+    out.push(`  debt: introduced ${debt.introduced.length}, resolved ${debt.resolved.length}`);
+
+  const fitness = summary.fitness;
+  if (fitness?.available === false) out.push(`  fitness: ${naWithReason(fitness)}`);
+  else if (fitness?.verdictDeltas) {
+    out.push(`  fitness:`);
+    for (const delta of fitness.verdictDeltas) {
+      out.push(`    ${delta.id}: ${renderVerdict(delta.base)} → ${renderVerdict(delta.head)}`);
+    }
+  }
+
+  const affected = summary.affected;
+  if (affected) {
+    if (affected.projects?.length) out.push(`  affected projects: ${affected.projects.join(", ")}`);
+    if (affected.boundaries?.length)
+      out.push(`  affected boundaries: ${affected.boundaries.join(", ")}`);
+    if (affected.constraints?.length)
+      out.push(`  affected constraints: ${affected.constraints.join(", ")}`);
+    if (affected.decisions?.length)
+      out.push(`  affected decisions: ${affected.decisions.join(", ")}`);
+  }
+
+  for (const note of summary.notes ?? []) out.push(`  note: ${note}`);
+  return out;
+}

package/src/report/explain-text.mjs

@@ -152,6 +152,45 @@ function formatDecisionEntry(entry) {
   }
   return lines;
 }
+
+/**
+ * The lineage-comparison disclosure — `explain`'s optional base-registry
+ * seam, rendered only when the caller supplied a base registry and the
+ * resolved-site explanation carries a `decisionChange` field. The fact is
+ * stated either way — superseded or not — because "the lineage was compared
+ * and did not move" must read differently from "no comparison happened"
+ * (`../../../../AGENTS.md`: an empty result is a claim, never a shrug);
+ * every disclosure note rides appended lines. Appended only: an explanation
+ * that has no `decisionChange` field renders exactly as it did before.
+ *
+ * @param {{superseded: boolean, comparable: boolean, notes: string[]}} change
+ *   A `detectDecisionChange` result. `superseded` is meaningful only when
+ *   `comparable` is `true`; a non-comparable comparison (one-sided or
+ *   unreadable) renders "could not compare", never "did not move", because
+ *   the latter would assert a fact the comparison could not hold.
+ * @returns {string[]}
+ */
+function formatDecisionChange(change) {
+  const lines = [];
+  if (change.comparable === false) {
+    lines.push(
+      `${DETAIL}decisionChange  could not compare — the decision lineage was not established between the compared registry states`,
+    );
+  } else if (change.superseded) {
+    lines.push(
+      `${DETAIL}decisionChange  superseded — the decision lineage moved between the compared registry states`,
+    );
+  } else {
+    lines.push(
+      `${DETAIL}decisionChange  none — the decision lineage did not move between the compared registry states`,
+    );
+  }
+  for (const note of change.notes) {
+    lines.push(`${DETAIL}decisionChange  ${note}`);
+  }
+  return lines;
+}
+
 /**
  * The whole explain report.
  *
@@ -233,6 +272,12 @@ export function formatExplainReport({ explanation, coverage }) {
     } else {
       sections.push(`${DETAIL}verdict      allowed — no constraint was violated`);
     }
+    // The lineage-comparison disclosure — present only when the explanation
+    // carries it (the caller supplied a base registry); otherwise nothing
+    // here renders, and the report is byte-for-byte what it was.
+    if (explanation.decisionChange !== undefined) {
+      sections.push(...formatDecisionChange(explanation.decisionChange));
+    }
 
     // The "why does this constraint exist" chain — one block per governing
     // decision the matched rows name. Additive: an explanation whose rows

package/src/report/history-text.mjs

@@ -12,7 +12,7 @@
  * becomes prose, so the two commands cannot disagree about it.
  */
 
-import { formatChanges, transitionKind } from "./snapshot-text.mjs";
+import { formatChanges, formatClassifications, transitionKind } from "./snapshot-text.mjs";
 
 /**
  * The whole history report.
@@ -20,8 +20,9 @@ import { formatChanges, transitionKind } from "./snapshot-text.mjs";
  * @param {{evolution: {dir: string, captured: object|null,
  *   snapshots: {name: string, id: string}[],
  *   transitions: {from: string, to: string, architectureChanged: boolean,
- *     changes: object|null, policyChanged: boolean|null, providerChanged: boolean,
- *     codeDrift: boolean, notes: string[]}[]}, coverage: object}} input
+ *     changes: object|null, policyChanged: boolean|null, policyOneSided: boolean,
+ *     provenanceChanged: boolean|null, providerChanged: boolean,
+ *     codeDrift: boolean, notes: string[], classifications?: string[]}[]}, coverage: object}} input
  * @returns {string}
  */
 export function formatHistoryReport({ evolution, coverage }) {
@@ -61,6 +62,11 @@ export function formatHistoryReport({ evolution, coverage }) {
     if (transition.architectureChanged) changed += 1;
     const kind = transitionKind(transition);
     sections.push(`~ ${transition.from} → ${transition.to}  (${kind})`);
+    // The canonical classes, appended as their own line so the kind label
+    // (a display shorthand) and the classification (a fact) both print.
+    for (const line of formatClassifications(transition.classifications)) {
+      sections.push(`  ${line}`);
+    }
     if (transition.changes) {
       for (const line of formatChanges(transition.changes)) sections.push(`  ${line}`);
     }

package/src/report/plan-context-text.mjs

@@ -76,6 +76,68 @@ export function formatPlanContextReport({ project, coverage, unresolvedDecisionR
     );
   }
 
+  // Decisions / ADRs in scope (resolved decision lineage).
+  if (plan.decisions && plan.decisions.length > 0) {
+    sections.push(
+      `Decisions (${plan.decisions.length} resolved reference${plan.decisions.length === 1 ? "" : "s"})`,
+    );
+    for (const d of plan.decisions) {
+      const title = d.record ? `${d.record.id}: ${d.record.title}` : d.decisionRef;
+      const status = d.record ? d.record.status : "unresolved";
+      sections.push(`${DETAIL}${title}  (${status})`);
+      if (d.record?.context) {
+        sections.push(`${DETAIL}  context: ${d.record.context}`);
+      }
+    }
+  }
+
+  // Fitness.
+  if (plan.fitness) {
+    sections.push("Fitness");
+    if (!plan.fitness.verified) {
+      sections.push(`${DETAIL}no-verdict — ${plan.fitness.error ?? "could not be evaluated"}`);
+    } else {
+      sections.push(`${DETAIL}overall verdict: ${plan.fitness.overall.verdict}`);
+      if (plan.fitness.decisions.length > 0) {
+        for (const d of plan.fitness.decisions) {
+          sections.push(
+            `${DETAIL}${d.name ?? d.id}: ${d.verdict}${d.reason ? ` — ${d.reason}` : ""}`,
+          );
+        }
+      }
+    }
+  } else {
+    sections.push("Fitness  (no fitness functions declared in the boundary policy)");
+  }
+
+  // Waivers.
+  sections.push("Waivers");
+  if (!plan.waivers.declared) {
+    sections.push(`${DETAIL}no suppressions declared — every boundary is enforced`);
+  } else {
+    const waiverCount = plan.waivers.waivers.length;
+    const permCount = plan.waivers.permanentSuppressions.length;
+    sections.push(
+      `${DETAIL}${waiverCount} waiver${waiverCount === 1 ? "" : "s"}, ` +
+        `${permCount} permanent suppression${permCount === 1 ? "" : "s"}, ` +
+        `${plan.waivers.covered} covering violations, ` +
+        `${plan.waivers.expired} expired, ` +
+        `${plan.waivers.stale} stale`,
+    );
+    if (waiverCount > 0) {
+      for (const w of plan.waivers.waivers) {
+        const term = w.expiresAt
+          ? `expires ${w.expiresAt} (${w.status}, ${w.remainingMs}ms remaining)`
+          : "permanent";
+        sections.push(
+          `${DETAIL}${w.path}  ${term}  covers ${w.covered} violation${w.covered === 1 ? "" : "s"}`,
+        );
+        if (w.reason) sections.push(`${DETAIL}  reason: ${w.reason}`);
+        if (w.origin) sections.push(`${DETAIL}  origin: ${w.origin}`);
+      }
+    }
+  }
+
   // Affected projects.
   sections.push("Architecture");
   sections.push(
@@ -135,6 +197,38 @@ export function formatPlanContextReport({ project, coverage, unresolvedDecisionR
     sections.push(`${DETAIL}${plan.intent.verdict}: ${verdict} (${plan.intent.rows} rows)`);
   }
 
+  // Architecture debt.
+  if (plan.debt) {
+    sections.push("Architecture debt");
+    if (!plan.debt.available) {
+      sections.push(
+        `${DETAIL}not available — ${plan.debt.reason ?? "history directory unavailable"}`,
+      );
+    } else {
+      const entries = plan.debt.entries;
+      const open = plan.debt.total.open;
+      const resolved = plan.debt.total.resolved;
+      sections.push(
+        `${DETAIL}${entries.length} entry${entries.length === 1 ? "" : "s"} ` +
+          `(${open} open, ${resolved} resolved, ${plan.debt.total.total} total) ` +
+          `across ${plan.debt.snapshots} snapshot` +
+          `${plan.debt.snapshots === 1 ? "" : "s"}`,
+      );
+      if (plan.debt.byKind && Object.keys(plan.debt.byKind).length > 0) {
+        const kinds = Object.entries(plan.debt.byKind)
+          .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+          .map(([kind, count]) => `${kind}: ${count}`);
+        sections.push(`${DETAIL}by kind: ${kinds.join(", ")}`);
+      }
+      if (plan.debt.agings && plan.debt.agings.meanDays !== null) {
+        sections.push(
+          `${DETAIL}mean age: ${plan.debt.agings.meanDays.toFixed(1)} days` +
+            `${plan.debt.agings.maxDays !== null ? `, max ${plan.debt.agings.maxDays.toFixed(1)} days` : ""}`,
+        );
+      }
+    }
+  }
+
   // Verification commands.
   sections.push("Verify after the change");
   for (const command of plan.verify) {

package/src/report/snapshot-text.mjs

@@ -111,13 +111,47 @@ export function formatChanges(changes) {
  * Classifies one transition into the short "kind" a reader skims for.
  *
  * @param {{architectureChanged: boolean, codeDrift: boolean, policyChanged: boolean|null,
+ *   policyOneSided: boolean, provenanceChanged: boolean|null,
  *   providerChanged: boolean}} transition
- * @returns {string}
  */
 export function transitionKind(transition) {
   if (transition.architectureChanged) return "architecture";
   if (transition.providerChanged) return "provider";
   if (transition.policyChanged === true) return "policy";
   if (transition.codeDrift) return "code drift";
+  // A pair whose policy could not be compared — one side records the law
+  // (`policyOneSided`) or neither does while the commit advanced
+  // (F-HIST-1) — is never rendered "unchanged": that label claims every
+  // comparable signal was compared and equal. The record carries these as
+  // fields, never parsed out of its notes.
+  if (
+    transition.policyChanged === null &&
+    (transition.policyOneSided || transition.provenanceChanged === true)
+  ) {
+    return "not comparable";
+  }
   return "unchanged";
 }
+
+/**
+ * One transition's canonical evolution classes as a renderable line. Shared
+ * by every reporter that renders a transition record (`history` today;
+ * `evolution` will render the same record), so the JSON field and its prose
+ * cannot disagree about what a classification is — one spelling, one home,
+ * beside the sibling `transitionKind` label.
+ *
+ * The line appears only when the record carries classifications: an
+ * unclassified transition is labelled by its kind, and the empty-classification
+ * statement — where it applies — is a note on the record, never a second line
+ * this helper has to invent.
+ *
+ * @param {string[]|undefined} classifications The record's `classifications`
+ *   array; `undefined` when the caller's record predates the field.
+ * @returns {string[]} The line, or `[]` when there is nothing to state.
+ */
+export function formatClassifications(classifications) {
+  if (!Array.isArray(classifications) || classifications.length === 0) {
+    return [];
+  }
+  return [`classifications: ${classifications.map((c) => sanitize(c)).join(", ")}`];
+}

package/src/report/trajectory-text.mjs

@@ -96,7 +96,8 @@ function formatAxis(axis, withChanged) {
  *   transitions: {count: number, architecture: number, policy: number,
  *     provider: number, codeDrift: number, incomparable: number, unchanged: number},
  *   disclosures: {policyOneSided: number, provenanceOneSided: number, crossRepo: number},
- *   projects: object, edges: object}, coverage: object}} input
+ *   projects: object, edges: object,
+ *   trends: object|null}, coverage: object}} input
  * @returns {string}
  */
 export function formatTrajectoryReport({ trajectory, coverage }) {
@@ -135,6 +136,34 @@ export function formatTrajectoryReport({ trajectory, coverage }) {
       `dirty captures ${observations.dirtyProvenance} · with provenance ${observations.withProvenance}`,
   );
 
+  // The trend facts, from the SAME comparable transitions the signals line
+  // counts. `null` prints as n/a — an insufficient or fully-incomparable
+  // history never reads as zero change — and the basis line names exactly
+  // what the counts are a claim about.
+  if (trajectory.trends === null) {
+    sections.push(
+      trajectory.available
+        ? "trends  n/a — no comparable transition classifications"
+        : "trends  n/a",
+    );
+  } else {
+    const byClass = trajectory.trends.byClass;
+    sections.push(
+      `trends  CHANGE ${byClass.CHANGE} · DRIFT ${byClass.DRIFT} · VIOLATION ${byClass.VIOLATION} · ` +
+        `REPAIR ${byClass.REPAIR} · DECISION_CHANGE ${byClass.DECISION_CHANGE} · ` +
+        `violations introduced ${trajectory.trends.violationsIntroduced} · resolved ` +
+        `${trajectory.trends.violationsResolved}`,
+    );
+    sections.push(
+      `trends basis  ${trajectory.trends.comparableTransitions} comparable transition${
+        trajectory.trends.comparableTransitions === 1 ? "" : "s"
+      } (${trajectory.trends.basis})`,
+    );
+    if (typeof trajectory.trends.note === "string" && trajectory.trends.note !== "") {
+      sections.push(sanitize(trajectory.trends.note));
+    }
+  }
+
   for (const note of coverage.notes) {
     sections.push(sanitize(note));
   }