@ecoma-io/archkeep 0.13.0 → 0.15.0

package/src/report/delta-text.mjs

@@ -0,0 +1,264 @@
+/**
+ * The terminal report for the `delta` command: how boundary violations moved
+ * between a captured baseline and the current tree, both re-judged under the
+ * current law (`../commands/delta.mjs`).
+ *
+ * Sections render only when they have content — introduced (with waived
+ * annotations), resolved, unchanged (with the occurrences-reduced note where
+ * one applies), unknown (with the reason each identity could not be stated),
+ * the unresolvable-import block, and the custom-rules block (only when the
+ * delta computed one — `../commands/delta.mjs` keeps it absent for a
+ * workspace where neither side declares custom rules) — and the summary line
+ * always states what
+ * was compared: base and head identity, record and project counts, and the
+ * bucket totals. "No introduced violations" is a claim about a comparison the
+ * reader can verify, never silence (`../../../../AGENTS.md`).
+ *
+ * `coverage.notes` — the policy-changed, dirty-tree, and provenance warnings
+ * `../commands/delta.mjs` pushes there — fold into the report as their own
+ * lines, so a note that rides the JSON envelope also reaches the terminal.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`./README.md`).
+ */
+
+/** A side's identity for prose: its commit prefix, or an honest absence. */
+function describeOrigin(provenance) {
+  if (!provenance || typeof provenance.commit !== "string") return "unverified origin";
+  const dirty = provenance.dirty ? ", dirty" : "";
+  return `${provenance.commit.slice(0, 8)}${dirty}`;
+}
+
+/** One classified violation entry as its report lines. */
+function violationLines(entry) {
+  const source = entry.sourceProject ?? "(unattributed)";
+  const arrow = entry.targetIsSpecifier ? "⇢" : "→";
+  const counts = `${entry.baseCount} at base, ${entry.headCount} at head`;
+  const waived = entry.waived === true ? "  [waived]" : "";
+  const lines = [`  ${source} ${arrow} ${entry.target}  ${entry.messageId}  (${counts})${waived}`];
+  if (entry.note !== undefined) lines.push(`    ${entry.note}`);
+  const sites = entry.headSites.length > 0 ? entry.headSites : entry.baseSites;
+  for (const site of sites) {
+    lines.push(`    at ${site.file}:${site.line}:${site.column}`);
+  }
+  return lines;
+}
+
+/** One classified unresolvable-record entry as its report lines. */
+function unresolvableLines(entry) {
+  const source = entry.sourceProject ?? "(unattributed)";
+  const counts = `${entry.baseCount} at base, ${entry.headCount} at head`;
+  const lines = [`  ${source} ⇢ ${entry.specifier}  (${entry.kind || "unknown kind"}; ${counts})`];
+  if (entry.note !== undefined) lines.push(`    ${entry.note}`);
+  const sites = entry.headSites.length > 0 ? entry.headSites : entry.baseSites;
+  for (const site of sites) {
+    lines.push(`    at ${site.file}:${site.line}:${site.column}`);
+  }
+  return lines;
+}
+
+/** One unknown entry — the reason is the load-bearing half. */
+function unknownLines(entry) {
+  return [`  ? ${entry.reason}`];
+}
+
+/** One classified custom-finding entry as its report lines. */
+function customFindingLines(entry) {
+  const where = entry.project === null ? "" : `  in ${entry.project}`;
+  const counts = `${entry.baseCount} at base, ${entry.headCount} at head`;
+  const lines = [`  ${entry.ruleId}${where}  (${counts})`];
+  if (entry.message !== undefined) lines.push(`    ${entry.message}`);
+  if (entry.note !== undefined) lines.push(`    ${entry.note}`);
+  const sites = entry.headSites.length > 0 ? entry.headSites : entry.baseSites;
+  for (const site of sites) {
+    // A custom finding states a position only when its rule stated one — a
+    // whole-workspace finding has no file, and no line is printed for it.
+    if (site.file !== undefined) lines.push(`    at ${site.file}:${site.line}:${site.column}`);
+  }
+  return lines;
+}
+
+/** One unknown custom entry — the rule name plus the mandatory reason. */
+function customUnknownLines(entry) {
+  return [`  ? ${entry.rule}: ${entry.reason}`];
+}
+
+/**
+ * The custom-rules block, rendered only when the delta computed one — a
+ * workspace where neither side declares custom rules keeps the exact report
+ * it already had.
+ *
+ * @param {{judged: object[], skipped: object[], removed: string[],
+ *   findings: object}} customRules
+ * @param {{customFindings: {introduced: number, resolved: number,
+ *   unchanged: number, unknown: number}}} summary
+ * @returns {string[]}
+ */
+function customRulesSections(customRules, summary) {
+  const { judged, skipped, removed, findings } = customRules;
+  const counts = summary.customFindings;
+  const lines = [
+    `custom rules (${judged.length} judged, ${skipped.length} skipped, ${removed.length} removed)`,
+  ];
+  lines.push(
+    ...section(
+      `  ⚠ ${counts.introduced} introduced custom finding${counts.introduced === 1 ? "" : "s"}`,
+      findings.introduced.map(customFindingLines),
+    ),
+  );
+  lines.push(
+    ...section(
+      `  ✔ ${counts.resolved} resolved custom finding${counts.resolved === 1 ? "" : "s"}`,
+      findings.resolved.map(customFindingLines),
+    ),
+  );
+  lines.push(
+    ...section(
+      `  = ${counts.unchanged} unchanged custom finding${counts.unchanged === 1 ? "" : "s"}`,
+      findings.unchanged.map(customFindingLines),
+    ),
+  );
+  lines.push(
+    ...section(
+      `  ? ${counts.unknown} unclassifiable custom item${counts.unknown === 1 ? "" : "s"}`,
+      findings.unknown.map(customUnknownLines),
+    ),
+  );
+  return lines;
+}
+
+/**
+ * One classification bucket as a section, or nothing when it is empty.
+ *
+ * @param {string} heading Rendered above the entries, already carrying its count.
+ * @param {string[][]} entryLines
+ * @returns {string[]}
+ */
+function section(heading, entryLines) {
+  if (entryLines.length === 0) return [];
+  return [heading, ...entryLines.flat()];
+}
+
+/**
+ * The whole delta report.
+ *
+ * @param {{delta: object, coverage: object}} input `delta` is
+ *   `../commands/delta.mjs`'s result payload; `coverage` its coverage block.
+ * @returns {string}
+ */
+export function formatDeltaReport({ delta, coverage }) {
+  const sections = [];
+  const { baseline, head, summary, violations, unresolvable } = delta;
+
+  sections.push(
+    `baseline  ${baseline.path} — ${describeOrigin(baseline.provenance)}, ` +
+      `${baseline.records} record${baseline.records === 1 ? "" : "s"}, ` +
+      `${baseline.projects} project${baseline.projects === 1 ? "" : "s"}`,
+  );
+  sections.push(
+    `head      ${describeOrigin(head.provenance)}, ` +
+      `${head.records} record${head.records === 1 ? "" : "s"}, ` +
+      `${head.projects} project${head.projects === 1 ? "" : "s"}`,
+  );
+
+  for (const note of coverage.notes ?? []) {
+    sections.push(`⚠ ${note}`);
+  }
+
+  const introducedWord = summary.introduced === 1 ? "violation" : "violations";
+  sections.push(
+    ...section(
+      `⚠ ${summary.introduced} introduced ${introducedWord}` +
+        (summary.introducedWaived > 0
+          ? ` (${summary.introducedWaived} waived — reported, not gating)`
+          : ""),
+      violations.introduced.map(violationLines),
+    ),
+  );
+  sections.push(
+    ...section(
+      `✔ ${summary.resolved} resolved ${summary.resolved === 1 ? "violation" : "violations"}`,
+      violations.resolved.map(violationLines),
+    ),
+  );
+  sections.push(
+    ...section(
+      `= ${summary.unchanged} unchanged ${summary.unchanged === 1 ? "violation" : "violations"}`,
+      violations.unchanged.map(violationLines),
+    ),
+  );
+  sections.push(
+    ...section(
+      `? ${summary.unknown} unclassifiable ${summary.unknown === 1 ? "item" : "items"}`,
+      violations.unknown.map(unknownLines),
+    ),
+  );
+
+  const unresolvableTotal =
+    summary.unresolvable.introduced +
+    summary.unresolvable.resolved +
+    summary.unresolvable.unchanged +
+    summary.unresolvable.unknown;
+  if (unresolvableTotal > 0) {
+    sections.push(
+      `unresolvable imports (carried, never counted as violations — no rule reached a verdict ` +
+        `about them)`,
+    );
+    sections.push(
+      ...section(
+        `  + ${summary.unresolvable.introduced} introduced`,
+        unresolvable.introduced.map(unresolvableLines),
+      ),
+    );
+    sections.push(
+      ...section(
+        `  - ${summary.unresolvable.resolved} resolved`,
+        unresolvable.resolved.map(unresolvableLines),
+      ),
+    );
+    sections.push(
+      ...section(
+        `  = ${summary.unresolvable.unchanged} unchanged`,
+        unresolvable.unchanged.map(unresolvableLines),
+      ),
+    );
+    sections.push(
+      ...section(
+        `  ? ${summary.unresolvable.unknown} unclassifiable`,
+        unresolvable.unknown.map(unknownLines),
+      ),
+    );
+  }
+
+  if (delta.customRules !== undefined) {
+    sections.push(...customRulesSections(delta.customRules, summary));
+  }
+
+  // The closing claim always states what was compared, so an empty delta is a
+  // verifiable statement rather than silence.
+  const compared =
+    `compared baseline ${describeOrigin(baseline.provenance)} ` +
+    `(${baseline.records} record${baseline.records === 1 ? "" : "s"}) against head ` +
+    `${describeOrigin(head.provenance)} (${head.records} record${head.records === 1 ? "" : "s"}, ` +
+    `${coverage.analyzedFiles} analyzed file${coverage.analyzedFiles === 1 ? "" : "s"}, ` +
+    `${coverage.projects} project${coverage.projects === 1 ? "" : "s"})`;
+  if (summary.introduced === 0) {
+    sections.push(`✔ no introduced violations — ${compared}`);
+  } else {
+    sections.push(
+      `${summary.introduced - summary.introducedWaived} introduced ${introducedWord} not ` +
+        `waived — ${compared}`,
+    );
+  }
+  // The custom gate's own closing claim, so a delta whose only introduction is
+  // a custom finding does not end on a line reading clean.
+  if (delta.customRules !== undefined && summary.customFindings.introduced > 0) {
+    const count = summary.customFindings.introduced;
+    sections.push(
+      `⚠ ${count} introduced custom finding${count === 1 ? "" : "s"} — custom findings have ` +
+        `no waiver lane, every one gates`,
+    );
+  }
+
+  return sections.join("\n");
+}

package/src/report/evolution-text.mjs

@@ -0,0 +1,83 @@
+/**
+ * The terminal report for the `evolution` command: the selected revisions in
+ * history order, each transition classified, and what the whole record can
+ * and cannot say.
+ *
+ * Like `history-text.mjs`, counts end every section so a reader never decides
+ * whether an omission is content or silence — and the summary line names the
+ * range the record is a claim ABOUT, because "how the architecture evolved"
+ * without naming the compared revisions is not a reproducible claim.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`); the transition formatters are
+ * shared with `history-text.mjs` (`./snapshot-text.mjs`) so both commands
+ * render one classification the same way.
+ */
+
+import { formatChanges, sanitize, transitionKind } from "./snapshot-text.mjs";
+
+/**
+ * The whole evolution report.
+ *
+ * @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
+ * @returns {string}
+ */
+export function formatEvolutionReport({ result, coverage }) {
+  const sections = [];
+
+  const transitionWord = result.transitions.length === 1 ? "transition" : "transitions";
+  const revisionWord = result.revisions.length === 1 ? "revision" : "revisions";
+  const inspected = `${coverage.imports} import${
+    coverage.imports === 1 ? "" : "s"
+  } in ${coverage.analyzedFiles} file${
+    coverage.analyzedFiles === 1 ? "" : "s"
+  } across ${coverage.projects} project${coverage.projects === 1 ? "" : "s"}`;
+
+  sections.push(
+    `evolution  ${sanitize(result.base.slice(0, 12))}..${sanitize(result.head.slice(0, 12))}`,
+  );
+  sections.push(
+    `${result.revisions.length} ${revisionWord}, ${result.transitions.length} ${transitionWord} (${inspected})`,
+  );
+
+  for (const [i, revision] of result.revisions.entries()) {
+    sections.push(`${i}  ${sanitize(revision.commit)}  ${revision.id.slice(0, 8)}`);
+  }
+
+  // The footer counts true architectural change only — the same discipline as
+  // `history-text.mjs`: a policy or provider transition is a change to how the
+  // record reads, not to the architecture itself.
+  let changed = 0;
+  for (const transition of result.transitions) {
+    if (transition.architectureChanged) changed += 1;
+    const kind = transitionKind(transition);
+    sections.push(`~ ${sanitize(transition.from)} → ${sanitize(transition.to)}  (${kind})`);
+    if (transition.changes) {
+      for (const line of formatChanges(transition.changes)) sections.push(`  ${line}`);
+    }
+    for (const note of transition.notes) {
+      sections.push(`  ${note}`);
+    }
+  }
+
+  if (changed === 0) {
+    const anySignal = result.transitions.some(
+      (t) => t.policyChanged === true || t.providerChanged || t.codeDrift,
+    );
+    sections.push(
+      anySignal
+        ? "✔ no architectural change across the selected revisions (only policy, provider, or drift signals)"
+        : "✔ no change at all across the selected revisions",
+    );
+  } else {
+    sections.push(
+      `${changed} transition${changed === 1 ? "" : "s"} recorded an architectural change`,
+    );
+  }
+
+  return sections.join("\n");
+}

package/src/report/explain-text.mjs

@@ -15,6 +15,10 @@
  * - the constraint row(s) that matched (which rule applied)
  * - the verdict (violation or allowed)
  * - the message, when there is one (what the verdict means in prose)
+ * - for a violation: the allowed direction when the governing row states one,
+ *   and a remediation line that is the author's declared guidance verbatim —
+ *   or, when none is declared, an explicit pointer at the constraint row and
+ *   its `decisionRef`, never a fix this renderer composed
  * - coverage information (whether this explanation is complete)
  *
  * This module decides nothing. A formatter that filtered would be a rule
@@ -131,8 +135,31 @@ export function formatExplainReport({ explanation, coverage }) {
         if (v.constraint?.description) {
           sections.push(`${DETAIL}rule         ${v.constraint.description}`);
         }
+        // The allowed direction, verbatim from the governing row when it
+        // states one. A `notDependOnLibsWithTags` row states no allowed list,
+        // and computing its complement here would be this renderer inventing
+        // a direction the law never wrote — the constraint line above is the
+        // honest answer there, so no line is printed.
+        if (Array.isArray(v.constraint?.onlyDependOnLibsWithTags)) {
+          sections.push(
+            `${DETAIL}allowed      ${formatTags(v.constraint.onlyDependOnLibsWithTags)}`,
+          );
+        }
+        // The remediation line is always printed for a violation: the
+        // author's declared guidance verbatim, or an explicit pointer at
+        // where guidance lives — never a fix this renderer composed, and
+        // never silence a reader could mistake for "nothing to consult".
         if (v.constraint?.remediation) {
           sections.push(`${DETAIL}remediation  ${v.constraint.remediation}`);
+        } else if (v.constraint) {
+          const ref = v.constraint.decisionRef
+            ? ` and its decisionRef ${v.constraint.decisionRef}`
+            : "";
+          sections.push(`${DETAIL}remediation  none declared — consult the constraint row${ref}`);
+        } else {
+          sections.push(
+            `${DETAIL}remediation  none declared — no depConstraints row drives this check`,
+          );
         }
       }
     } else {

package/src/report/history-text.mjs

@@ -7,122 +7,12 @@
  * actually holds. Counts end every section, so a reader is never left deciding
  * whether an omission is content or silence.
  *
- * This module decides nothing. A formatter that filtered would be a rule
- * wearing a formatter's name (`../README.md`).
+ * The per-transition formatters live in `./snapshot-text.mjs`, beside the
+ * ones `evolution-text.mjs` renders from — one home for the way a transition
+ * becomes prose, so the two commands cannot disagree about it.
  */
 
-/**
- * Neutralises control and terminal-escape sequences in a name or value before
- * it is printed, so a crafted project/tag/edge name cannot inject escape
- * sequences into a consumer's terminal (`SECURITY.md`). Real project names are
- * ordinary characters and pass through untouched; only C0 control characters
- * (which includes the ESC byte) and DEL become visible escapes.
- *
- * @param {string} text
- * @returns {string}
- */
-function sanitize(text) {
-  // eslint-disable-next-line no-control-regex
-  return String(text).replace(/[\x00-\x1F\x7F]/g, (c) => {
-    if (c === "\n") return "\\n";
-    if (c === "\t") return "\\t";
-    if (c === "\r") return "\\r";
-    return `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`;
-  });
-}
-
-/**
- * One project as a line, same shape as `graph-text.mjs`.
- *
- * @param {{name: string, root: string, tags: string[]}} project
- * @returns {string}
- */
-function formatProject(project) {
-  const tags =
-    project.tags.length > 0 ? ` [${project.tags.map((t) => sanitize(t)).join(", ")}]` : "";
-  return `  ${sanitize(project.name)}  ${sanitize(project.root)}${tags}`;
-}
-
-/**
- * One edge as a line, same shape as `graph-text.mjs`.
- *
- * @param {{source: string, target: string, type: string}} edge
- * @returns {string}
- */
-function formatEdge(edge) {
-  return `  ${sanitize(edge.source)} → ${sanitize(edge.target)} (${sanitize(edge.type)})`;
-}
-
-/**
- * One metadata change as a line, same shape as `diff-text.mjs`.
- *
- * @param {{field: string, baseline: *, head: *}} change
- * @returns {string}
- */
-function formatChange(change) {
-  const formatValue = (v) => {
-    if (Array.isArray(v)) return v.length > 0 ? v.map((x) => sanitize(x)).join(", ") : "(none)";
-    if (v === null || v === undefined) return "(none)";
-    return sanitize(String(v));
-  };
-  return `  ${change.field}  ${formatValue(change.baseline)} → ${formatValue(change.head)}`;
-}
-
-/**
- * How the architecture actually changed between two snapshots: the added and
- * removed projects and edges rendered as one line each. Changed projects
- * render their changed fields beneath the project line, like `diff`.
- *
- * @param {object} changes The `computeDiff` payload.
- * @returns {string[]}
- */
-function formatChanges(changes) {
-  const lines = [];
-  if (changes.addedProjects.length > 0) {
-    const word = changes.addedProjects.length === 1 ? "project" : "projects";
-    lines.push(`+ ${changes.addedProjects.length} added ${word}`);
-    for (const project of changes.addedProjects) lines.push(formatProject(project));
-  }
-  if (changes.removedProjects.length > 0) {
-    const word = changes.removedProjects.length === 1 ? "project" : "projects";
-    lines.push(`- ${changes.removedProjects.length} removed ${word}`);
-    for (const project of changes.removedProjects) lines.push(formatProject(project));
-  }
-  if (changes.changedProjects.length > 0) {
-    const word = changes.changedProjects.length === 1 ? "project" : "projects";
-    lines.push(`~ ${changes.changedProjects.length} changed ${word}`);
-    for (const project of changes.changedProjects) {
-      lines.push(`  ${project.name}`);
-      for (const change of project.changes) lines.push(formatChange(change));
-    }
-  }
-  if (changes.addedEdges.length > 0) {
-    const word = changes.addedEdges.length === 1 ? "edge" : "edges";
-    lines.push(`+ ${changes.addedEdges.length} added ${word}`);
-    for (const edge of changes.addedEdges) lines.push(formatEdge(edge));
-  }
-  if (changes.removedEdges.length > 0) {
-    const word = changes.removedEdges.length === 1 ? "edge" : "edges";
-    lines.push(`- ${changes.removedEdges.length} removed ${word}`);
-    for (const edge of changes.removedEdges) lines.push(formatEdge(edge));
-  }
-  return lines;
-}
-
-/**
- * Classifies one transition into the short "kind" a reader skims for.
- *
- * @param {{architectureChanged: boolean, codeDrift: boolean, policyChanged: boolean|null,
- *   providerChanged: boolean}} transition
- * @returns {string}
- */
-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";
-  return "unchanged";
-}
+import { formatChanges, transitionKind } from "./snapshot-text.mjs";
 
 /**
  * The whole history report.