@ecoma-io/archkeep 0.16.1 → 0.18.0

package/src/report/report-text.mjs

@@ -155,7 +155,13 @@ function fitnessLines(fitness) {
  */
 function decisionLines(decisions) {
   const lines = [surfaceLine("decisions", decisions)];
-  if (decisions.registry.count !== null) {
+  // "does not resolve" is a claim about the REF — that nothing in the
+  // workspace answers to it. When the registry itself could not be read, that
+  // claim is not one this run established: it could not look. The two get
+  // different sentences, for the same reason `unknown` and `not_applicable`
+  // do (`count: null` is how the command says the registry was unreadable).
+  const registryUnread = decisions.registry.count === null;
+  if (!registryUnread) {
     lines.push(
       `    ${decisions.registry.count} record${decisions.registry.count === 1 ? "" : "s"} in ` +
         `${decisions.registry.dir}/`,
@@ -165,29 +171,58 @@ function decisionLines(decisions) {
         record.bindings.length > 0
           ? `binds ${record.bindings.join(", ")}`
           : "binds nothing — not yet enforceable";
+      // The record row is byte-identical to the pre-wave-2 line; the fitness
+      // and "stands on" lines below it are additive surface (contract items
+      // 3 + F/B), never a rewrite of what a longer-maintained reader expects.
       lines.push(`      ${record.id}  (${record.status})  ${binds}`);
+      if (record.fitness !== undefined) {
+        const fit = record.fitness;
+        const reasonString =
+          typeof fit.reason === "string"
+            ? ` — ${fit.reason}`
+            : fit.verified
+              ? " — verified true: bound constraints resolve and pass"
+              : "";
+        lines.push(`          fitness: ${fit.level}${reasonString}`);
+      }
+      if (record.authority) {
+        if (record.constraints.length > 0) {
+          const refs = record.constraints.map((c) => `${c.kind} ${c.label}`).join(", ");
+          lines.push(`          stands on: ${refs}`);
+        } else {
+          lines.push("          stands on: no governed row cites this decision");
+        }
+      }
     }
   }
+  // The citations render even when the registry could not be read: that is
+  // exactly the case where "does not resolve" must NOT be claimed and the
+  // registry-unreadable sentence must. Skipping them here would print the
+  // "unknown" verdict with no citation lines to back it — the silent direction.
   if (decisions.citations.length === 0) {
     lines.push("    no governed row cites a decisionRef");
-    return lines;
+  } else {
+    for (const citation of decisions.citations) {
+      const target =
+        citation.resolution === "adr" && citation.adr !== null
+          ? `${citation.adr.id} (${citation.adr.status})`
+          : citation.resolution === "fitness"
+            ? `${citation.decisionRef} — a fitness rule this law declares`
+            : registryUnread
+              ? `${citation.decisionRef} — unresolved: the decision registry could not be read`
+              : `${citation.decisionRef} — does not resolve`;
+      lines.push(`    ${citation.resolution.padEnd(10)}${citation.label} → ${target}`);
+    }
   }
-  // "does not resolve" is a claim about the REF — that nothing in the
-  // workspace answers to it. When the registry itself could not be read, that
-  // claim is not one this run established: it could not look. The two get
-  // different sentences, for the same reason `unknown` and `not_applicable`
-  // do (`count: null` is how the command says the registry was unreadable).
-  const registryUnread = decisions.registry.count === null;
-  for (const citation of decisions.citations) {
-    const target =
-      citation.resolution === "adr" && citation.adr !== null
-        ? `${citation.adr.id} (${citation.adr.status})`
-        : citation.resolution === "fitness"
-          ? `${citation.decisionRef} — a fitness rule this law declares`
-          : registryUnread
-            ? `${citation.decisionRef} — unresolved: the decision registry could not be read`
-            : `${citation.decisionRef} — does not resolve`;
-    lines.push(`    ${citation.resolution.padEnd(10)}${citation.label} → ${target}`);
+  if (
+    !registryUnread &&
+    Array.isArray(decisions.unresolvedDecisionRefs) &&
+    decisions.unresolvedDecisionRefs.length > 0
+  ) {
+    lines.push("    unresolved decisionRefs:");
+    for (const ref of decisions.unresolvedDecisionRefs) {
+      lines.push(`      ${ref.kind} ${ref.label} → ${ref.reason}`);
+    }
   }
   return lines;
 }

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