@ecoma-io/archkeep 0.13.0

package/src/report/diff-text.mjs

@@ -0,0 +1,219 @@
+/**
+ * The terminal report for the `diff` command: two graph snapshots compared.
+ *
+ * Each section — added projects, removed projects, changed projects, added
+ * edges, removed edges — is printed only when it has content, and always ends
+ * with a count. A section with zero entries is absent from the report, and the
+ * summary line then names "no changes" rather than "0 added, 0 removed" — the
+ * two must never look identical, because "no changes" is a claim about a
+ * complete comparison while "0 added, 0 removed" would be ambiguous over a
+ * partial one (`../../../../AGENTS.md`).
+ *
+ * The changed-projects section lists projects that exist in both baseline and
+ * head but whose metadata (tags, type, root) changed. Each changed project
+ * shows the field name and its before → after values.
+ *
+ * When the diff carries a `ruleImpact` field (computed when a boundary config
+ * was provided), a rule-impact section lists violations introduced and
+ * resolved by the diff, plus a "no boundary-rule impact" line when the config
+ * was provided but no violations changed. This section appears whenever
+ * `ruleImpact` is present — even when there are no structural changes — so a
+ * reader can always tell "config provided, no impact" from "no config". The
+ * section is absent when no config was given, so a diff without `--config` is
+ * unchanged from its prior output.
+ *
+ * `coverage.notes` — provider-mismatch, cross-repository, one-sided-policy,
+ * and rule-impact-scope warnings `../commands/diff.mjs` pushes there — fold
+ * into the summary line the same way `check`'s text face folds `notes` into
+ * its own "inspected" line (`../report/text.mjs`'s `formatReport`): appended
+ * as `; note`, matching the presentation `check`'s text face already uses.
+ * Before this, a note pushed onto `coverage.notes` — a provider migration
+ * across baseline and head, say — rode the JSON envelope but never reached
+ * the text a terminal user actually reads.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/**
+ * One metadata change as a line.
+ *
+ * @param {{field: string, baseline: *, head: *}} change
+ * @returns {string}
+ */
+function formatChange(change) {
+  const formatValue = (v) => {
+    if (Array.isArray(v)) return v.length > 0 ? v.join(", ") : "(none)";
+    if (v === null || v === undefined) return "(none)";
+    return String(v);
+  };
+  return `  ${change.field}  ${formatValue(change.baseline)} → ${formatValue(change.head)}`;
+}
+
+/**
+ * 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.join(", ")}]` : "";
+  return `  ${project.name}  ${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 `  ${edge.source} → ${edge.target} (${edge.type})`;
+}
+
+/**
+ * One constraint-impact violation as a line.
+ *
+ * @param {{messageId: string, constraint: object|null, source: string, target: string}} violation
+ * @returns {string}
+ */
+function formatImpactViolation(violation) {
+  const tag =
+    violation.constraint?.sourceTag ??
+    violation.constraint?.allSourceTags?.join("+") ??
+    "(no matching constraint)";
+  return `  ${violation.source} → ${violation.target}  ${violation.messageId}  [${tag}]`;
+}
+
+/**
+ * The whole diff report.
+ *
+ * @param {{diff: object, coverage: object}} input
+ * @returns {string}
+ */
+export function formatDiffReport({ diff, coverage }) {
+  const sections = [];
+
+  // Baseline summary
+  sections.push(
+    `baseline  ${diff.baseline.path} — ${diff.baseline.projects} projects, ` +
+      `${diff.baseline.edges} edges`,
+  );
+  sections.push(`head      ${diff.head.projects} projects, ${diff.head.edges} edges`);
+
+  // Policy mismatch warning: when the boundary law changed between the
+  // baseline and head runs, rule-impact results may reflect the policy change
+  // rather than a structural change.
+  if (diff.policyMismatch) {
+    sections.push(
+      "⚠ policy changed between baseline and head — rule-impact results may reflect the policy change, not a structural change",
+    );
+  }
+
+  const hasChanges =
+    diff.addedProjects.length > 0 ||
+    diff.removedProjects.length > 0 ||
+    (diff.changedProjects && diff.changedProjects.length > 0) ||
+    diff.addedEdges.length > 0 ||
+    diff.removedEdges.length > 0;
+
+  if (hasChanges) {
+    if (diff.addedProjects.length > 0) {
+      const word = diff.addedProjects.length === 1 ? "project" : "projects";
+      sections.push(`+ ${diff.addedProjects.length} added ${word}`);
+      for (const project of diff.addedProjects) {
+        sections.push(formatProject(project));
+      }
+    }
+
+    if (diff.removedProjects.length > 0) {
+      const word = diff.removedProjects.length === 1 ? "project" : "projects";
+      sections.push(`- ${diff.removedProjects.length} removed ${word}`);
+      for (const project of diff.removedProjects) {
+        sections.push(formatProject(project));
+      }
+    }
+
+    if (diff.changedProjects && diff.changedProjects.length > 0) {
+      const word = diff.changedProjects.length === 1 ? "project" : "projects";
+      sections.push(`~ ${diff.changedProjects.length} changed ${word}`);
+      for (const project of diff.changedProjects) {
+        sections.push(`  ${project.name}`);
+        for (const change of project.changes) {
+          sections.push(formatChange(change));
+        }
+      }
+    }
+
+    if (diff.addedEdges.length > 0) {
+      const word = diff.addedEdges.length === 1 ? "edge" : "edges";
+      sections.push(`+ ${diff.addedEdges.length} added ${word}`);
+      for (const edge of diff.addedEdges) {
+        sections.push(formatEdge(edge));
+      }
+    }
+
+    if (diff.removedEdges.length > 0) {
+      const word = diff.removedEdges.length === 1 ? "edge" : "edges";
+      sections.push(`- ${diff.removedEdges.length} removed ${word}`);
+      for (const edge of diff.removedEdges) {
+        sections.push(formatEdge(edge));
+      }
+    }
+  }
+
+  // Rule-impact section: violations introduced or resolved by this diff.
+  // This section appears whenever the boundary config was provided, so a
+  // reader can always tell "config provided, no impact" from "no config".
+  if (diff.ruleImpact) {
+    const { introduced, resolved } = diff.ruleImpact;
+
+    if (introduced.length > 0) {
+      const word = introduced.length === 1 ? "violation" : "violations";
+      sections.push(`⚠ ${introduced.length} boundary ${word} introduced`);
+      for (const v of introduced) {
+        sections.push(formatImpactViolation(v));
+      }
+    }
+
+    if (resolved.length > 0) {
+      const word = resolved.length === 1 ? "violation" : "violations";
+      sections.push(`✔ ${resolved.length} boundary ${word} resolved`);
+      for (const v of resolved) {
+        sections.push(formatImpactViolation(v));
+      }
+    }
+
+    if (introduced.length === 0 && resolved.length === 0) {
+      sections.push("✔ no boundary-rule impact");
+    }
+  }
+
+  // The summary line states what was compared, so "no changes" reads as a
+  // claim about coverage, not as silence. `coverage.notes` — the same
+  // provider/cross-repo/policy/rule-impact-scope warnings the JSON envelope
+  // already carries — ride here too, exactly the way `check`'s text face
+  // folds its own `notes` into its "inspected" line: appended, never a
+  // section a caller could silently omit.
+  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"}` +
+    (coverage.notes && coverage.notes.length > 0 ? `; ${coverage.notes.join("; ")}` : "");
+
+  if (!hasChanges) {
+    sections.push(`✔ no changes between baseline and head (${inspected})`);
+  } else {
+    const totalChanges =
+      diff.addedProjects.length +
+      diff.removedProjects.length +
+      (diff.changedProjects ? diff.changedProjects.length : 0) +
+      diff.addedEdges.length +
+      diff.removedEdges.length;
+    sections.push(
+      `${totalChanges} change${totalChanges === 1 ? "" : "s"} between baseline and head (${inspected})`,
+    );
+  }
+
+  return sections.join("\n");
+}

package/src/report/discover-text.mjs

@@ -0,0 +1,186 @@
+/**
+ * The terminal report for the `discover` command: observed facts, and under
+ * `--propose` the candidate architecture those facts imply.
+ *
+ * The coverage claim sits ABOVE everything — the reader knows whether the
+ * observations are complete before reading any entry, exactly like
+ * `./graph-text.mjs`'s report. The proposal, when present, is rendered below
+ * the observations with the proposal-only banner (`proposed`, `not
+ * authoritative`) repeated on every line of every candidate, so a reader who
+ * scans the report cannot mistake a candidate for a decision.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/** The three confidence markers, in the order the legend prints them. */
+const CONFIDENCE_ORDER = ["high", "medium", "low"];
+
+/** One project as a line — the same shape `./graph-text.mjs` prints. */
+function formatProject(project) {
+  const type = project.type ? `  ${project.type}` : "";
+  const tags = project.tags.length > 0 ? ` [${project.tags.join(", ")}]` : "";
+  return `  ${project.name}  ${project.root}${type}${tags}`;
+}
+
+/** One edge as a line — the same shape `./graph-text.mjs` prints. */
+function formatEdge(edge) {
+  return `    → ${edge.target} (${edge.type})`;
+}
+
+const PROPOSAL_BANNER = "  [proposed — not authoritative] ";
+
+/**
+ * One proposal candidate as one or more lines, every line carrying the
+ * proposal-only banner — never a bare candidate that could be read as a
+ * decision.
+ *
+ * The four candidate lists hold different item shapes, so each is formatted by
+ * the function that knows its shape rather than by one switch over a flat
+ * array — a candidate's `kind` names its role inside its own list
+ * (`"component"` means a shared-directory assertion inside
+ * `boundaryAssertions.items`, a `"component"` component inside
+ * `components.items`), which is why the lists are never concatenated.
+ */
+
+/** @param {{name: string, projects: string[], confidence: string}} item */
+function formatComponent(item) {
+  const confidence = item.confidence ? ` (${item.confidence} confidence)` : "";
+  return [
+    `${PROPOSAL_BANNER}component ${item.name}${confidence}`,
+    `    members: ${item.projects.join(", ")}`,
+  ];
+}
+
+/** @param {{component: string|undefined, source: string, target: string, confidence: string}} item */
+function formatBoundaryAssertion(item) {
+  const confidence = item.confidence ? ` (${item.confidence} confidence)` : "";
+  return item.component !== undefined
+    ? [`${PROPOSAL_BANNER}boundary: projects of ${item.component} share a role${confidence}`]
+    : [
+        `${PROPOSAL_BANNER}boundary: ${item.source} and ${item.target} belong to different components${confidence}`,
+        `    evidence: edge ${item.source} → ${item.target}`,
+      ];
+}
+
+/** @param {{axis: string|undefined, values: string[]|undefined, tag: string, members: string[], confidence: string}} item */
+function formatTag(item) {
+  const confidence = item.confidence ? ` (${item.confidence} confidence)` : "";
+  return item.axis !== undefined
+    ? [
+        `${PROPOSAL_BANNER}tag axis ${item.axis}${confidence}`,
+        `    values: ${(item.values ?? []).join(", ")}`,
+      ]
+    : [
+        `${PROPOSAL_BANNER}tag ${item.tag}${confidence}`,
+        `    members: ${(item.members ?? []).join(", ")}`,
+      ];
+}
+
+/** @param {{kind: "noDependency"|"boundary", source: string, target: string, component: string, evidence: object[], confidence: string}} item */
+function formatRule(item) {
+  const confidence = item.confidence ? ` (${item.confidence} confidence)` : "";
+  return item.kind === "noDependency"
+    ? [`${PROPOSAL_BANNER}rule: ${item.source} must not depend on ${item.target}${confidence}`]
+    : [
+        `${PROPOSAL_BANNER}rule: declare a boundary around ${item.component}${confidence}`,
+        `    members: ${item.evidence
+          .filter((e) => e.kind === "shared-directory")
+          .map((e) => e.project)
+          .join(", ")}`,
+      ];
+}
+
+/**
+ * The whole discover report.
+ *
+ * @param {{discovery: {projects: object[], edges: object[], tags: string[]},
+ *   proposal: object|null,
+ *   coverage: object}} input
+ * @returns {string}
+ */
+export function formatDiscoverReport({ discovery, proposal, coverage }) {
+  const sections = [];
+
+  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"}`;
+
+  if (coverage.complete) {
+    sections.push(`✔ discovery complete (${inspected})`);
+  } else {
+    const notAnalyzedCount = coverage.notAnalyzed.length;
+    sections.push(
+      `✖ discovery incomplete — ${notAnalyzedCount} file${notAnalyzedCount === 1 ? "" : "s"} ` +
+        `could not be analyzed, so these observations may under-represent the workspace (${inspected})`,
+    );
+  }
+
+  const projectWord = discovery.projects.length === 1 ? "project" : "projects";
+  sections.push(`${discovery.projects.length} ${projectWord}`);
+
+  const edgesBySource = new Map();
+  for (const edge of discovery.edges) {
+    let list = edgesBySource.get(edge.source);
+    if (!list) {
+      list = [];
+      edgesBySource.set(edge.source, list);
+    }
+    list.push(edge);
+  }
+
+  for (const project of discovery.projects) {
+    sections.push(formatProject(project));
+    const edges = edgesBySource.get(project.name);
+    if (edges && edges.length > 0) {
+      for (const edge of edges) {
+        sections.push(formatEdge(edge));
+      }
+    } else {
+      sections.push("    (no dependencies)");
+    }
+  }
+
+  const edgeWord = discovery.edges.length === 1 ? "edge" : "edges";
+  sections.push(`${discovery.edges.length} ${edgeWord}`);
+
+  if (discovery.tags.length > 0) {
+    sections.push(`tags ${discovery.tags.join(", ")}`);
+  } else {
+    sections.push("tags (none observed)");
+  }
+
+  if (proposal) {
+    sections.push("");
+    sections.push("proposed architecture — NOT authoritative, never written");
+    if (proposal.unknown) {
+      sections.push("  no observed projects — nothing to propose");
+    } else {
+      const counts = [
+        `${proposal.components.total} component${proposal.components.total === 1 ? "" : "s"}`,
+        `${proposal.boundaryAssertions.total} boundary ` +
+          `assertion${proposal.boundaryAssertions.total === 1 ? "" : "s"}`,
+        `${proposal.tagVocabulary.total} tag candidate${proposal.tagVocabulary.total === 1 ? "" : "s"}`,
+        `${proposal.rules.total} rule${proposal.rules.total === 1 ? "" : "s"}`,
+      ];
+      const confidenceLegend = CONFIDENCE_ORDER.map(
+        (level) => `${level} (${proposal.uncertainty[level]})`,
+      ).join(" · ");
+      sections.push(`  ${counts.join(", ")}`);
+      sections.push(`  confidence: ${confidenceLegend}`);
+
+      const items = [
+        ...proposal.components.items.map(formatComponent),
+        ...proposal.boundaryAssertions.items.map(formatBoundaryAssertion),
+        ...proposal.tagVocabulary.items.map(formatTag),
+        ...proposal.rules.items.map(formatRule),
+      ];
+      for (const lines of items) {
+        sections.push(...lines);
+      }
+    }
+  }
+
+  return sections.join("\n");
+}

package/src/report/drift-text.mjs

@@ -0,0 +1,194 @@
+/**
+ * The terminal report for the `drift` command: the observed architecture
+ * compared against the declared intended one.
+ *
+ * Each section — one per finding kind, in a fixed taxonomy order — is printed
+ * only when it has content, and always ends with a count. A section with zero
+ * entries is absent from the report, and the summary line then names "no
+ * drift" rather than "0 findings": the two must never look identical, because
+ * "no drift" is a claim about a complete comparison while "0 findings" would
+ * be ambiguous over a partial one (`../../../../AGENTS.md`). The header
+ * states what was compared — the intent fingerprint, the row count, and the
+ * observed projects and edges, including how many `implicit` edges were
+ * excluded — so "no drift" always reads as a claim about the exact tree and
+ * contract the run judged.
+ *
+ * The taxonomy is the judge's own ten-verb catalogue
+ * (`../architecture-intent/judge.mjs`) — the message ids `findings` carry in
+ * their `rule`. This report is deterministic as long as the taxonomy list is,
+ * and it never re-sorts: the judge already orders findings by total key.
+ *
+ * `notes` — coverage warnings the judge attaches (`../architecture-intent/judge.mjs`'s
+ * `verdict.notes`; today an `optional: true` allowed row the team has not
+ * built yet) — fold into the "observed" summary line the same way `check`'s
+ * text face folds its own `notes` into its "inspected" line
+ * (`../report/text.mjs`'s `formatReport`): appended as `; note`, never a
+ * section a caller could silently drop.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`./README.md`).
+ */
+
+/** The taxonomy in report order. Every rule `judgeIntent` can emit appears here. */
+const TAXONOMY = [
+  "intentForbiddenEdge",
+  "intentAllowedMissing",
+  "projectMissing",
+  "projectPresent",
+  "projectTagMissing",
+  "dependencyForbidden",
+  "dependencyNotAllowed",
+  "tagDependencyForbidden",
+  "intentUnknownProject",
+  "intentUnknownTag",
+];
+
+/** A one-line heading per finding kind, for the grouped section. */
+const LEAVE_LABEL = new Map([
+  ["intentForbiddenEdge", "dependencies the intended architecture forbids exist"],
+  ["intentAllowedMissing", "dependencies the intended architecture allows are not being built"],
+  ["projectMissing", "projects the intent requires are missing"],
+  ["projectPresent", "projects the intent forbids are present"],
+  ["projectTagMissing", "required projects lack required tags"],
+  ["dependencyForbidden", "dependencies the intent forbids exist"],
+  ["dependencyNotAllowed", "dependencies that are not allowed exist"],
+  ["tagDependencyForbidden", "tag-forbidden dependencies exist"],
+  ["intentUnknownProject", "intent rows name projects the architecture does not have"],
+  ["intentUnknownTag", "tag rules name tags no project carries"],
+]);
+
+function formatFinding(finding) {
+  // Edge findings are compact — the pair is the fact. Presence and tag
+  // findings carry no source/target pair (the canonical judge sets both to
+  // null there), so their message — which names the project or tag — is the
+  // fact.
+  switch (finding.rule) {
+    case "intentForbiddenEdge":
+    case "intentAllowedMissing":
+    case "dependencyForbidden":
+    case "dependencyNotAllowed":
+    case "tagDependencyForbidden":
+      return `  ${finding.source} → ${finding.target}`;
+    default:
+      return `  ${finding.message}`;
+  }
+}
+
+/**
+ * The whole drift report.
+ *
+ * @param {{findings: {rule: string, source: string|null, target: string|null,
+ *   message: string}[],
+ *   intent: {fingerprint: string, rows: number},
+ *   observed: {projects: number, edges: number, implicitEdges: number},
+ *   notes?: string[],
+ *   unresolvedDecisionRefs?: {kind: string, decisionRef: string}[],
+ *   decisionRefsChecked?: number}} input
+ *   `unresolvedDecisionRefs` — rows whose `decisionRef` cites no ADR, rule, or
+ *   fitness record this workspace's registry knows — is a documentation fact,
+ *   not a drift finding: it is rendered in its own section and never folds
+ *   into the finding count or the "no drift" claim below. `decisionRefsChecked`
+ *   is how many rows carry a `decisionRef` at all (resolved or not) — the
+ *   same "no fact, no claim" distinction `formatGoWork` states: a section
+ *   appears when the axis was exercised, silence only when it was not, so
+ *   "every citation resolves" is never confused with "nothing uses the field".
+ *   `notes` — coverage warnings (an `optional: true` allowed row not yet
+ *   built) — fold into the "observed" line; empty/absent changes nothing.
+ * @returns {string}
+ */
+export function formatDriftReport({
+  findings,
+  intent,
+  observed,
+  notes = [],
+  unresolvedDecisionRefs = [],
+  decisionRefsChecked = unresolvedDecisionRefs.length,
+}) {
+  const sections = [];
+
+  sections.push(
+    `intent    ${intent.fingerprint} — ${intent.rows} row${intent.rows === 1 ? "" : "s"}`,
+  );
+  const excluded =
+    observed.implicitEdges > 0
+      ? ` (${observed.implicitEdges} implicit edge${observed.implicitEdges === 1 ? "" : "s"} excluded)`
+      : "";
+  // `notes` folds in here, the same "; note" convention `check`'s text face
+  // uses for its own coverage notes — appended, not a section a caller could
+  // silently drop.
+  const notesSuffix = notes.length > 0 ? `; ${notes.join("; ")}` : "";
+  sections.push(
+    `observed  ${observed.projects} project${observed.projects === 1 ? "" : "s"}, ` +
+      `${observed.edges} edge${observed.edges === 1 ? "" : "s"}${excluded}${notesSuffix}`,
+  );
+
+  const byId = new Map();
+  for (const finding of findings) {
+    if (!byId.has(finding.rule)) byId.set(finding.rule, []);
+    byId.get(finding.rule).push(finding);
+  }
+
+  // `total` is taken from `findings.length` itself, never accumulated only
+  // over the rules this walk visits: a finding whose `rule` the taxonomy does
+  // not know must still be counted and rendered, under its own heading,
+  // rather than silently dropped from both the report and the "no drift"
+  // claim below (the invariant this module is judged against,
+  // `../../../../AGENTS.md`).
+  const total = findings.length;
+  for (const rule of TAXONOMY) {
+    const group = byId.get(rule) ?? [];
+    if (group.length === 0) continue;
+    const word = group.length === 1 ? "finding" : "findings";
+    sections.push(`⚠ ${group.length} ${word}: ${LEAVE_LABEL.get(rule)}`);
+    for (const finding of group) {
+      sections.push(formatFinding(finding));
+    }
+  }
+
+  const knownRules = new Set(TAXONOMY);
+  const unclassified = findings.filter((finding) => !knownRules.has(finding.rule));
+  if (unclassified.length > 0) {
+    const word = unclassified.length === 1 ? "finding" : "findings";
+    sections.push(
+      `⚠ ${unclassified.length} unclassified ${word}: rule id not in this report's taxonomy`,
+    );
+    for (const finding of unclassified) {
+      sections.push(`  [${finding.rule}] ${formatFinding(finding).trimStart()}`);
+    }
+  }
+
+  const inspected =
+    `${observed.projects} project${observed.projects === 1 ? "" : "s"}` +
+    ` and ${observed.edges} edge${observed.edges === 1 ? "" : "s"}` +
+    (observed.implicitEdges > 0 ? ` (${observed.implicitEdges} implicit excluded)` : "");
+
+  if (total === 0) {
+    sections.push(`✔ no drift — the observed architecture matches the intended one (${inspected})`);
+  } else {
+    sections.push(`${total} drift finding${total === 1 ? "" : "s"} (${inspected})`);
+  }
+
+  // A separate, non-verdict axis — rendered last, after the drift verdict
+  // itself, so a clean "no drift" line never reads as though it also vouches
+  // for an unresolvable decisionRef sitting above it. "No fact, no claim": a
+  // workspace whose rows carry no decisionRef gets no section at all, but one
+  // that DOES use the field and finds every citation clean still gets a
+  // stated line — silence there would be indistinguishable from never
+  // having checked, the same reasoning `formatGoWork` states for its own axis.
+  if (unresolvedDecisionRefs.length > 0) {
+    sections.push(
+      [
+        `⚠ ${unresolvedDecisionRefs.length} intent row${unresolvedDecisionRefs.length === 1 ? "" : "s"} ` +
+          `cite${unresolvedDecisionRefs.length === 1 ? "s" : ""} a decisionRef that does not resolve ` +
+          `to a known ADR, rule, or fitness record:`,
+        ...unresolvedDecisionRefs.map(({ kind, decisionRef }) => `  ${kind} — "${decisionRef}"`),
+      ].join("\n"),
+    );
+  } else if (decisionRefsChecked > 0) {
+    sections.push(
+      `✔ every decisionRef citation (${decisionRefsChecked}) resolves to a known ADR, rule, or fitness record`,
+    );
+  }
+
+  return sections.join("\n");
+}