@ecoma-io/archkeep 0.13.0

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

@@ -0,0 +1,159 @@
+/**
+ * The terminal report for the agent architecture planning context: the
+ * deterministic facts an agent reasons over before changing a project.
+ *
+ * The layout mirrors what `context`, `impact`, `graph` and `check` each print,
+ * so a reader who has seen those commands recognises the same shapes here. The
+ * coverage claim sits ABOVE everything — the reader must know whether the
+ * result is complete before reading a single entry, the same reasoning as
+ * `./impact-text.mjs`.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`). Every fact here comes from the
+ * `result` object the command built; nothing is recomputed, and nothing is
+ * guessed. Sections that are empty state so rather than printing nothing — a
+ * plan with no violations and a plan the renderer forgot are not the same
+ * document (`AGENTS.md`: "an empty result is a claim, not a shrug").
+ */
+
+import { formatConstraint } from "./text.mjs";
+
+/** Two spaces of indent for detail lines. */
+const DETAIL = "  ";
+
+/**
+ * The whole planning-context report.
+ *
+ * @param {{project: object, coverage: object, unresolvedDecisionRefs?: Set<string>}} input
+ *   The `result` object the plan command built, plus its coverage.
+ *   `unresolvedDecisionRefs` — `decisionRef` values a matched constraint row
+ *   cites that do not resolve to any ADR, rule, or fitness record — is
+ *   forwarded to `formatConstraint`, the same seam `context`'s report uses.
+ * @returns {string}
+ */
+export function formatPlanContextReport({ project, coverage, unresolvedDecisionRefs }) {
+  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(`✔ planning context complete (${inspected})`);
+  } else {
+    const notAnalyzedCount = coverage.notAnalyzed.length;
+    sections.push(
+      `✖ planning context incomplete — ${notAnalyzedCount} file${notAnalyzedCount === 1 ? "" : "s"} ` +
+        `could not be analyzed, so these facts may be against an incomplete graph (${inspected})`,
+    );
+  }
+
+  const plan = project.plan;
+
+  // Target project, tags, policy fingerprint.
+  const tagsText = project.tags.length > 0 ? project.tags.join(", ") : "none";
+  sections.push(`Project  ${project.project}`);
+  sections.push(`Tags     ${tagsText}`);
+  sections.push(`Policy   fingerprint ${plan.policyFingerprint}`);
+
+  // Intent-bearing constraints.
+  if (project.constraints.length > 0) {
+    const count = project.constraints.length;
+    sections.push(`Constraints (${count} row${count === 1 ? "" : "s"} govern this project):`);
+    for (const constraint of project.constraints) {
+      sections.push(`${DETAIL}${formatConstraint(constraint, unresolvedDecisionRefs)}`);
+      if (constraint.description) {
+        sections.push(`${DETAIL}  description  ${constraint.description}`);
+      }
+      if (constraint.remediation) {
+        sections.push(`${DETAIL}  remediation   ${constraint.remediation}`);
+      }
+    }
+  } else {
+    sections.push(
+      "Constraints  (no matching constraint rows — this project's tags match no depConstraints entry)",
+    );
+  }
+
+  // Affected projects.
+  sections.push("Architecture");
+  sections.push(
+    `${DETAIL}affected projects  ${plan.architecture.targets.length > 0 ? plan.architecture.targets.join(", ") : "(none given — the whole workspace is in scope)"}`,
+  );
+  sections.push(`${DETAIL}projects           ${plan.architecture.projects.length}`);
+  sections.push(`${DETAIL}dependencies       ${plan.architecture.dependencies.length}`);
+
+  // Impact, capped with overflow note.
+  sections.push("Impact");
+  for (const entry of plan.impact) {
+    const capNote = entry.hasMore
+      ? ` (… and ${entry.dependentsTotal - entry.dependents.length} more)`
+      : "";
+    const word = entry.dependentsTotal === 1 ? "project" : "projects";
+    sections.push(
+      `${DETAIL}${entry.project}: ${entry.dependentsTotal} ${word} depend${entry.dependentsTotal === 1 ? "s" : ""} on it` +
+        ` (direct ${entry.direct.length}, transitive ${entry.transitive.length})${capNote}`,
+    );
+  }
+
+  // Violations (scoped reporting, whole-tree verdict).
+  sections.push(`Violations (${plan.violations.length} in scope of this change)`);
+  if (plan.violations.length === 0) {
+    sections.push(
+      `${DETAIL}none — the full-workspace rule-engine verdict found no violations in scope`,
+    );
+  } else {
+    for (const violation of plan.violations) {
+      const edge =
+        `${violation.sourceProject ?? "(no project)"} → ` +
+        `${violation.targetProject ?? "(unresolved)"}`;
+      sections.push(`${DETAIL}${edge}  ${violation.messageId}  ${violation.sourceFile}`);
+    }
+  }
+
+  // Drift.
+  sections.push("Drift");
+  sections.push(`${DETAIL}go.work        ${driftText(plan.drift.goWork)}`);
+  sections.push(`${DETAIL}tsconfig paths ${driftText(plan.drift.tsconfigPaths)}`);
+
+  // Canonical Architecture Intent — the same fold `check` and `drift` report.
+  const intentCount = plan.intent?.findings.length ?? 0;
+  const intentUnresolved = plan.intent?.unresolved.length ?? 0;
+  sections.push(`Intent (${plan.intent ? "verified" : "no intent declared"})`);
+  if (!plan.intent) {
+    sections.push(
+      `${DETAIL}towards architecture-intent.json — the workspace declares no intent, so none is judged`,
+    );
+  } else {
+    const verdict =
+      intentCount > 0
+        ? `${intentCount} finding${intentCount === 1 ? "" : "s"}`
+        : intentUnresolved > 0
+          ? `no-verdict (${intentUnresolved} unresolvable)`
+          : "ok";
+    sections.push(`${DETAIL}${plan.intent.verdict}: ${verdict} (${plan.intent.rows} rows)`);
+  }
+
+  // Verification commands.
+  sections.push("Verify after the change");
+  for (const command of plan.verify) {
+    sections.push(`${DETAIL}${command}`);
+  }
+
+  return sections.join("\n");
+}
+
+/**
+ * One drift section as text: a finding count, or the honest `null` answer —
+ * "not judged", which is NOT "clean" (`AGENTS.md`).
+ *
+ * @param {{checked: boolean, findings: object[]}|null} drift
+ * @returns {string}
+ */
+function driftText(drift) {
+  if (drift === null) return "not judged (no manifest to read)";
+  return drift.findings.length === 0
+    ? "checked, no drift"
+    : `${drift.findings.length} finding${drift.findings.length === 1 ? "" : "s"}`;
+}

package/src/report/provenance-text.mjs

@@ -0,0 +1,78 @@
+/**
+ * The terminal report for the `provenance` command: where this run's facts
+ * came from, and which governance rows carry an origin.
+ *
+ * Two lines state what was inspected before any verdict — the repo state (or
+ * its absence) and the row count — so "every row carries an origin" always
+ * reads as a claim about a specific, complete surface rather than a bare
+ * count. Determinism: every line derives from the static facts
+ * `../commands/provenance-command.mjs` already resolved — no wall-clock time
+ * and no `localeCompare` enter here, matching every other report renderer.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`./README.md`).
+ */
+
+/**
+ * @param {{establishment: boolean,
+ *   repo: {commit: string|null, remote: string|null, dirty: boolean|null}|null,
+ *   rowsTotal: number,
+ *   unattested: {kind: string, label: string, note: string}[],
+ *   decisionRefTotal: number,
+ *   unresolvedDecisionRefs: {kind: string, label: string, decisionRef: string, note: string}[]}} input
+ *   `decisionRefTotal` is how many governance rows cite a `decisionRef` at
+ *   all — the resolution section renders only when it is non-zero, the same
+ *   "no fact, no claim" bargain every optional axis in this tool states.
+ * @returns {string}
+ */
+export function formatProvenanceReport({
+  establishment,
+  repo,
+  rowsTotal,
+  unattested,
+  decisionRefTotal,
+  unresolvedDecisionRefs,
+}) {
+  const attestedCount = rowsTotal - unattested.length;
+  const text = [];
+  text.push(
+    establishment
+      ? `repo      ${repo.commit}${repo.dirty ? " (dirty)" : ""}` +
+          (repo.remote ? ` — ${repo.remote}` : "")
+      : "repo      provenance unavailable — not a git repository or git not installed",
+  );
+  text.push(
+    `rows      ${rowsTotal} governance row${rowsTotal === 1 ? "" : "s"}, ` +
+      `${attestedCount} with an origin, ${unattested.length} without`,
+  );
+  if (unattested.length > 0) {
+    text.push("unattested (no origin recorded — cannot attest):");
+    for (const row of unattested) {
+      text.push(`  ${row.kind}`);
+    }
+    text.push(`${unattested.length} of them carry no decision behind the rule`);
+  } else {
+    text.push(
+      `✔ every governance row carries an origin — each names who decided ` +
+        `on it and with what tool`,
+    );
+  }
+  if (decisionRefTotal > 0) {
+    if (unresolvedDecisionRefs.length > 0) {
+      text.push("unresolved decisionRefs (cite no known ADR, rule, or fitness record):");
+      for (const row of unresolvedDecisionRefs) {
+        text.push(`  ${row.kind} — "${row.decisionRef}"`);
+      }
+      text.push(
+        `${unresolvedDecisionRefs.length} of ${decisionRefTotal} decisionRef citation` +
+          `${decisionRefTotal === 1 ? "" : "s"} do not resolve`,
+      );
+    } else {
+      text.push(
+        `✔ every decisionRef citation (${decisionRefTotal}) resolves to a known ADR, ` +
+          `rule, or fitness record`,
+      );
+    }
+  }
+  return text.join("\n");
+}

package/src/report/reconcile-text.mjs

@@ -0,0 +1,159 @@
+/**
+ * The terminal report for the `reconcile` command: the intended model and the
+ * observed architecture compared element by element, then — with `--propose` —
+ * the ranked candidate list of model edits.
+ *
+ * Every section states what it is a claim about: the intent fingerprint and
+ * row count, the observed project and edge counts (implicit edges excluded and
+ * counted), then the divergence in fixed plane order — projects, edges, tags,
+ * boundaries, intent rows — each only when it has content and each ending with
+ * a count. A clean reconciliation prints "✔ model and reality agree" — never
+ * "0 divergences", which would be ambiguous over a partial comparison
+ * (`../../../../AGENTS.md`). An `unknown` score prints as such, never as a
+ * match.
+ *
+ * The `--propose` face ends with the ranked candidate list: one line per
+ * candidate in list order (severity, then plane, then name — the order
+ * `buildRankedCandidates` returned), each carrying its `proposed` /
+ * `notAuthoritative` marker explicitly so a reader can never mistake the
+ * description of an edit for an applied one.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/**
+ * Neutralises control and terminal-escape sequences in a name or value before
+ * it is printed — the same `sanitize` `history-text.mjs` uses, so a crafted
+ * project/tag/edge name cannot inject escape sequences into a consumer's
+ * terminal (`../../../../SECURITY.md`).
+ *
+ * @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")}`;
+  });
+}
+
+/** The planes in report order. */
+const PLANE_ORDER = ["projects", "edges", "tags", "boundaries", "intentRows"];
+
+/** A one-line label per plane, for the diverging section. */
+const PLANE_LABEL = new Map([
+  ["projects", "observed projects the model does not match"],
+  ["edges", "observed edges the model does not match"],
+  ["tags", "required-tag and tag-rule divergence"],
+  ["boundaries", "boundary membership divergence"],
+  ["intentRows", "intent rows whose statement is not observed"],
+]);
+
+/** The state symbol a diverging element prints. */
+const STATE_SYMBOL = new Map([
+  ["unexpected", "+"],
+  ["absent", "-"],
+  ["unknown", "?"],
+]);
+
+/**
+ * One diverging element as a line.
+ *
+ * @param {import("../governance/reconcile-score.mjs").ScoredElement} element
+ * @returns {string}
+ */
+function formatElement(element) {
+  const symbol = STATE_SYMBOL.get(element.state) ?? " ";
+  return `  ${symbol} ${sanitize(element.name)}  (${sanitize(element.classification)})`;
+}
+
+/**
+ * One candidate as a line.
+ *
+ * @param {import("../governance/reconcile-candidates.mjs").CandidateEdit} candidate
+ * @returns {string}
+ */
+function formatCandidate(candidate) {
+  const edit = candidate.edit;
+  const where = edit.section ? `${edit.action} in ${edit.section}` : edit.action;
+  return `  ${candidate.kind}  ${sanitize(candidate.name)}  (${sanitize(where)} — ${sanitize(edit.reason)})`;
+}
+
+/**
+ * The whole reconcile report.
+ *
+ * @param {object} input
+ * @param {object} input.scores From `reconcileScores`.
+ * @param {import("../governance/reconcile-candidates.mjs").CandidateEdit[]|null} input.candidates
+ *   The ranked candidate list, `null` unless `--propose`.
+ * @param {{fingerprint: string, rows: number}} input.intent
+ * @param {{projects: number, edges: number, implicitEdges: number}} input.observed
+ * @returns {string}
+ */
+export function formatReconcileReport({ scores, candidates, intent, observed }) {
+  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)`
+      : "";
+  sections.push(
+    `observed  ${observed.projects} project${observed.projects === 1 ? "" : "s"}, ` +
+      `${observed.edges} edge${observed.edges === 1 ? "" : "s"}${excluded}`,
+  );
+
+  // Iterate every key `scores` actually carries, not only the five this
+  // module names in `PLANE_ORDER` — `total` and every rendered section come
+  // from that walk, so a plane the label map does not know is named and
+  // counted rather than silently dropped from the report and from the
+  // "no divergence" claim below (the invariant this module is judged
+  // against, `../../../../AGENTS.md`). Known planes still render first, in
+  // their fixed order; anything else follows, in the order `scores` carries it.
+  const knownPlanes = new Set(PLANE_ORDER);
+  const planes = [...PLANE_ORDER, ...Object.keys(scores).filter((key) => !knownPlanes.has(key))];
+
+  let total = 0;
+  for (const plane of planes) {
+    const group = scores[plane] ?? [];
+    const diverging = group.filter((element) => element.state !== "match");
+    if (diverging.length === 0) continue;
+    total += diverging.length;
+    const word = diverging.length === 1 ? "element" : "elements";
+    const label = PLANE_LABEL.get(plane) ?? `unknown plane "${plane}"`;
+    sections.push(`⚠ ${diverging.length} ${word}: ${label}`);
+    for (const element of diverging) sections.push(formatElement(element));
+  }
+
+  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 divergence — the observed architecture matches the intended model (${inspected})`,
+    );
+  } else {
+    sections.push(`${total} divergence${total === 1 ? "" : "s"} (${inspected})`);
+  }
+
+  if (candidates) {
+    const listLabel = candidates.length === 1 ? "1 candidate" : `${candidates.length} candidates`;
+    sections.push(`proposal  ${listLabel}, ranked — proposed, not authoritative, never written`);
+    for (const candidate of candidates) sections.push(formatCandidate(candidate));
+    if (candidates.length > 0) {
+      sections.push(
+        "           — apply none of these without review; architecture-intent.json is untouched",
+      );
+    }
+  }
+
+  return sections.join("\n");
+}

package/src/report/report-text.mjs

@@ -0,0 +1,264 @@
+/**
+ * The terminal report for the `report` command: the architecture governance
+ * document — the health metrics, the waiver surface, the fitness gates, the
+ * recorded decisions each governed row cites, the run's provenance, and last
+ * the evidence the run could not inspect.
+ *
+ * Three rules this renderer holds, all of them the empty-result invariant
+ * (`../../../../AGENTS.md`) wearing a formatter's clothes:
+ *
+ * - **A surface that could not be established never renders as a clean
+ *   zero.** Its verdict word is `unknown` and the reason it carries is
+ *   printed beside it, and the same fact appears again in the closing
+ *   `could not inspect` block. A reader skimming either one sees the gap.
+ * - **`not_applicable` is loud too, and says why.** "The workspace declared
+ *   none" and "the run could not look" are different sentences and must never
+ *   read alike.
+ * - **A citation that resolves to nothing is `unknown`, never a pass.** A
+ *   governed row linking to an ADR the registry knows prints that record and
+ *   its status; a row citing something unresolvable prints `unknown` with the
+ *   ref that failed.
+ *
+ * The metric block is rendered through `./health-text.mjs`'s own
+ * `formatMetricLine`/`HEALTH_METRIC_ORDER` rather than a second copy of them,
+ * so `health` and `report` can never disagree about how a verdict looks or in
+ * what order the metrics come.
+ *
+ * Determinism: every list here arrives already ordered by the command
+ * (`../commands/report.mjs` states which order and why), and this module adds
+ * no sort, no clock and no locale-sensitive comparison. It decides nothing —
+ * a formatter that filtered would be a rule wearing a formatter's name
+ * (`./README.md`).
+ *
+ * Plain text, not Markdown, deliberately: every identity in this document —
+ * a project name, a waiver's glob, an ADR id, a fitness function's name —
+ * comes from the workspace, and a Markdown rendering would have to escape
+ * each one or silently render it wrong (a `_` in a project name, a `*` in a
+ * suppression path). A document that quietly mis-renders the name of the
+ * thing it is reporting on is the same class of defect as one that reports
+ * nothing.
+ */
+import { HEALTH_METRIC_ORDER, formatCoverageHeadline, formatMetricLine } from "./health-text.mjs";
+
+/** A section heading, with a blank line before it. */
+function heading(title) {
+  return `\n${title}`;
+}
+
+/**
+ * The verdict word for a whole surface, aligned to the same column the metric
+ * lines use, with the reason a non-measuring verdict must carry.
+ *
+ * @param {string} label
+ * @param {{verdict: string, note?: string|null}} surface
+ * @returns {string}
+ */
+function surfaceLine(label, surface) {
+  const note = surface.note ? `  (${surface.note})` : "";
+  return `  ${surface.verdict.padEnd(16)}${label}${note}`;
+}
+
+/**
+ * The provenance block: where this run's facts came from. An unestablished
+ * origin prints as a stated absence, never as a blank line a reader could
+ * mistake for a clean commit.
+ *
+ * @param {object} provenance
+ * @param {{root: string, provider: string, marker: string}} context
+ * @returns {string[]}
+ */
+function provenanceLines(provenance, context) {
+  const lines = [
+    `  root        ${context.root}`,
+    `  provider    ${context.provider} (${context.marker})`,
+    `  policy      ${provenance.policySource ?? "none declared — no boundary law governs this run"}`,
+  ];
+  if (provenance.established) {
+    lines.push(`  commit      ${provenance.repo.commit}${provenance.repo.dirty ? " (dirty)" : ""}`);
+    lines.push(`  remote      ${provenance.repo.remote ?? "none configured"}`);
+  } else {
+    lines.push("  commit      repo provenance unavailable — this report carries no origin claim");
+  }
+  const { total, unattested } = provenance.rows;
+  lines.push(
+    `  rows        ${total} governed row${total === 1 ? "" : "s"}, ` +
+      `${unattested.length} with no origin recorded`,
+  );
+  for (const row of unattested) {
+    lines.push(`    unattested  ${row.label} — no origin recorded, cannot attest`);
+  }
+  return lines;
+}
+
+/**
+ * The waiver block: the counts, then one line per suppression on the table.
+ *
+ * @param {object} waivers
+ * @returns {string[]}
+ */
+function waiverLines(waivers) {
+  // "waivers", not "waiver surface": the metric block above already carries a
+  // line by that name, and the two are different facts — the metric counts
+  // the violations a suppression currently covers, this section describes the
+  // table those suppressions live in. Two labels reading alike is how a
+  // reader comes to believe one number answers the other's question.
+  const lines = [surfaceLine("waivers", waivers)];
+  if (waivers.counts === null) return lines;
+  const c = waivers.counts;
+  lines.push(
+    `    ${c.waivers} waiver${c.waivers === 1 ? "" : "s"} ` +
+      `(${c.expired} expired, ${c.stale} covering nothing), ` +
+      `${c.suppressions} permanent suppression${c.suppressions === 1 ? "" : "s"} ` +
+      `hiding ${c.suppressed} violation${c.suppressed === 1 ? "" : "s"}`,
+  );
+  for (const row of waivers.rows) {
+    const expiry = row.expiresAt === null ? "" : ` until ${row.expiresAt}`;
+    lines.push(
+      `    ${row.status.padEnd(10)}${row.path}${expiry} — covers ${row.covered} ` +
+        `violation${row.covered === 1 ? "" : "s"}`,
+    );
+    if (row.reason !== null) lines.push(`      reason: ${row.reason}`);
+  }
+  return lines;
+}
+
+/**
+ * The fitness block: one line per declared gate, with the ADR(s) binding it.
+ *
+ * `adrs: null` means the registry could not be read, which is a different
+ * statement from `[]` ("no recorded decision binds this gate") and is printed
+ * as such.
+ *
+ * @param {object} fitness
+ * @returns {string[]}
+ */
+function fitnessLines(fitness) {
+  const lines = [surfaceLine("fitness gates", fitness)];
+  for (const fn of fitness.functions) {
+    const bound =
+      fn.adrs === null
+        ? "  bound by: unknown — the decision registry could not be read"
+        : fn.adrs.length > 0
+          ? `  bound by: ${fn.adrs.join(", ")}`
+          : "  bound by: no recorded decision";
+    lines.push(`    ${fn.verdict.padEnd(16)}${fn.name}${bound}`);
+    if (fn.verdict !== "pass" && fn.message !== null) lines.push(`      ${fn.message}`);
+  }
+  return lines;
+}
+
+/**
+ * The decisions block: the registry, and every governed row that cites one.
+ *
+ * @param {object} decisions
+ * @returns {string[]}
+ */
+function decisionLines(decisions) {
+  const lines = [surfaceLine("decisions", decisions)];
+  if (decisions.registry.count !== null) {
+    lines.push(
+      `    ${decisions.registry.count} record${decisions.registry.count === 1 ? "" : "s"} in ` +
+        `${decisions.registry.dir}/`,
+    );
+    for (const record of decisions.records) {
+      const binds =
+        record.bindings.length > 0
+          ? `binds ${record.bindings.join(", ")}`
+          : "binds nothing — not yet enforceable";
+      lines.push(`      ${record.id}  (${record.status})  ${binds}`);
+    }
+  }
+  if (decisions.citations.length === 0) {
+    lines.push("    no governed row cites a decisionRef");
+    return lines;
+  }
+  // "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}`);
+  }
+  return lines;
+}
+
+/**
+ * The whole governance report.
+ *
+ * @param {{coverage: object, metrics: object, trends: object|null,
+ *   waivers: object, fitness: object, decisions: object, provenance: object,
+ *   uninspectable: {surface: string, reason: string}[],
+ *   context: {root: string, provider: string, marker: string}}} input
+ * @returns {string}
+ */
+export function formatGovernanceReport({
+  coverage,
+  metrics,
+  trends,
+  waivers,
+  fitness,
+  decisions,
+  provenance,
+  uninspectable,
+  context,
+}) {
+  const sections = [];
+
+  // The document's own verdict, first: whether it could be established at
+  // all. A reader who stops after one line must not read "no verdict" as
+  // "healthy".
+  sections.push(
+    uninspectable.length === 0
+      ? "architecture governance report — every surface reached a verdict"
+      : `architecture governance report — NO VERDICT: ${uninspectable.length} ` +
+          `surface${uninspectable.length === 1 ? "" : "s"} could not be inspected`,
+  );
+
+  sections.push(heading("provenance"));
+  sections.push(...provenanceLines(provenance, context));
+
+  sections.push(heading("health"));
+  sections.push(formatCoverageHeadline(coverage, "report"));
+  for (const { key, label } of HEALTH_METRIC_ORDER) {
+    sections.push(formatMetricLine(label, metrics[key]));
+  }
+
+  sections.push(heading("governance surfaces"));
+  sections.push(...waiverLines(waivers));
+  sections.push(...fitnessLines(fitness));
+  sections.push(...decisionLines(decisions));
+
+  if (trends) {
+    sections.push(heading("trends"));
+    sections.push(
+      `  ${trends.snapshots.length} snapshot${trends.snapshots.length === 1 ? "" : "s"}`,
+    );
+    for (const snapshot of trends.snapshots) {
+      sections.push(
+        `    ${snapshot.name}  ${snapshot.projects} projects, ${snapshot.dependencies} edges`,
+      );
+    }
+    for (const note of trends.notes) sections.push(`    ${note}`);
+  }
+
+  // Last, and unconditional: an empty block is the claim "every surface was
+  // inspectable", which is exactly what it must mean.
+  sections.push(heading("could not inspect"));
+  if (uninspectable.length === 0) {
+    sections.push("  nothing — every surface in this report reached a verdict");
+  } else {
+    for (const gap of uninspectable) sections.push(`  ${gap.surface}: ${gap.reason}`);
+  }
+
+  return sections.join("\n");
+}