@ecoma-io/archkeep 0.13.0

package/src/providers/nx.mjs

@@ -0,0 +1,178 @@
+/**
+ * The Nx project-model provider — the seam's first (and today, only)
+ * implementation.
+ *
+ * `evaluate(importSites, graph, config)` in `../rules/index.mjs` is pure and
+ * takes a graph it does not build (`../../AGENTS.md`, "Layout, and what each
+ * layer may know"). Something still has to produce that graph, and until this
+ * module existed the answer was hardcoded into `../workspace.mjs`: `check()`
+ * called `readProjectGraph` and there was nowhere else the graph could come
+ * from. This file is that answer pulled out from behind the hardcoding — the
+ * `ProjectModelProvider` contract below is what a second source (a
+ * `archkeep.json`-driven native model, with no Nx installed at all) will
+ * implement beside this one, without `../workspace.mjs`, `../../cli.mjs`, or
+ * `../lsp/` needing to know which provider they are holding.
+ *
+ * @typedef {object} ProjectModelProvider
+ * @property {string} name Short, stable identifier — `"nx"` here — for a
+ *   diagnostic that needs to say which provider answered (or failed to).
+ * @property {(workspaceRoot: string, io?: object) => object} readProjectGraph
+ *   The workspace root, plus whatever spawns/reads this provider needs
+ *   injected for a test — and back comes the graph half of the shape
+ *   `evaluate()` consumes: `{nodes, dependencies}`, plus `externalNodes` and
+ *   `workspaceLayout` when the provider's source of truth carries them.
+ *   `nx graph --file=` itself emits neither (see `readProjectGraph` below) —
+ *   `externalNodes` stays absent, deliberately (`../../AGENTS.md` argues that
+ *   refusal), but `workspaceLayout` is merged back in from `nx.json` by
+ *   `readProjectGraph` itself, because that command's own output is not the
+ *   whole of what the workspace declared. Everything the source DOES emit
+ *   must travel inside that one object, because a provider that dropped a
+ *   field its source supplied would force a second call to the same source
+ *   outside the seam. Three node facts
+ *   deliberately do NOT come from the provider: `mfeRemote`, `entryPoints`
+ *   and `declaredPackages` are annotated onto `graph.nodes` by the caller
+ *   afterwards (`../../cli.mjs`, via `annotateMFERemotes` and
+ *   `annotatePackageFacts`), read from disk the way upstream reads them — a
+ *   provider that filled them in would only be overwritten.
+ */
+
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { runProcess } from "../process.mjs";
+import { readWorkspaceLayout, requireCompleteWorkspaceLayout } from "../options.mjs";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Absolute path to Nx's own CLI entry — the JS file its `nx` bin points at.
+ *
+ * Spawned under this Node binary rather than through `pnpm nx`, which takes the
+ * package manager's platform-specific bin shim out of the picture instead of
+ * wrapping it, and leaves no shell for a `TMPDIR` carrying metacharacters to
+ * reach. It resolves by Node's own rules from this file's location, and that is
+ * correct rather than incidental: `nx` is a **peer** dependency, so what those
+ * rules find is the copy the consumer installed — the same version answering
+ * `pnpm nx` in their tree — and never a second one bundled in here. A tool that
+ * shipped its own Nx could report a graph the workspace's own CLI disagrees with.
+ *
+ * `nx` is declared `peerDependenciesMeta.nx.optional`, so this resolution is
+ * allowed to fail — but `check()` calls `readProjectGraph` unconditionally
+ * (`../../cli.mjs`), so a workspace that never installed `nx` gets no working
+ * `archkeep check` at all: every run exits 3 with the diagnostic below. The
+ * "Installing it" section of `../../README.md` states the same thing for a
+ * reader outside this file. What this function must not do on failure is let
+ * Node's own
+ * `MODULE_NOT_FOUND` reach the caller: that error names a package specifier,
+ * not a workspace-facing action, and `cli.mjs` prints `error.message` verbatim
+ * on the exit-3 path — a raw resolver stack there would read as a bug in this
+ * tool rather than the true cause, an absent peer.
+ *
+ * `resolveNx` is injectable for the same reason `run` is: this repository has
+ * `nx` installed, so nothing here can drive the real "not installed" path
+ * without faking the resolver — `nx.test.mjs` does exactly that, over a
+ * `resolveNx` that throws the way `require.resolve` does when nothing on disk
+ * answers `nx/package.json`. It takes no argument because it only ever
+ * resolves that one specifier — accepting one and forwarding it to
+ * `require`'s own resolver would hand that call a variable rather than a
+ * literal, which is exactly the load `../conformance/boundary.test.mjs`
+ * cannot see through and reports as opaque rather than trusting.
+ *
+ * @param {{ resolveNx?: () => string }} [io]
+ * @throws {Error} named `archkeep: nx is not installed`, when `resolveNx`
+ *   cannot find it.
+ */
+function nxCli({ resolveNx = () => require.resolve("nx/package.json") } = {}) {
+  let manifest;
+  try {
+    manifest = resolveNx();
+  } catch (cause) {
+    // Only an absent package earns the "not installed" story. Any other
+    // resolver failure — say, an installed nx whose `exports` stopped exposing
+    // `./package.json` — is a different fact, and renaming it here would send
+    // the reader to install a package they already have.
+    if (/** @type {{code?: string}} */ (cause)?.code !== "MODULE_NOT_FOUND") throw cause;
+    throw new Error(
+      "archkeep: nx is not installed — `nx` is an optional peer dependency, needed only for " +
+        "`archkeep check`'s project-graph discovery (`nx graph`). Install it in this workspace, " +
+        "or run a command that does not need the graph.",
+      { cause },
+    );
+  }
+  const { bin } = JSON.parse(readFileSync(manifest, "utf8"));
+  return join(dirname(manifest), typeof bin === "string" ? bin : bin.nx);
+}
+
+/**
+ * The Nx project graph for `workspaceRoot`, in the shape `evaluate()` consumes.
+ *
+ * `nx graph --file=<json>` emits `{ graph: { nodes, dependencies } }` and no
+ * `externalNodes`; the rule engine synthesises those from the analysis records
+ * instead, which is what makes `bannedExternalImports` reachable for crates and
+ * Go modules at all (`../rules/index.mjs` → `externalNodeFor`).
+ *
+ * The command also emits no `workspaceLayout` — measured, the same way — so
+ * this function reads `nx.json`'s own `workspaceLayout` key separately
+ * (`../options.mjs`'s `readWorkspaceLayout`) and merges it onto the graph
+ * before returning: without this, `../rules/index.mjs`'s
+ * `graph.workspaceLayout ?? DEFAULT_WORKSPACE_LAYOUT` fallback would apply the
+ * DEFAULT layout to every Nx workspace regardless of what `nx.json` declares,
+ * silencing `noRelativeOrAbsoluteImportsAcrossLibraries` on exactly the
+ * workspaces that set a non-default `appsDir`/`libsDir` (issue #31). The key
+ * is merged in only when something was declared and is complete
+ * (`requireCompleteWorkspaceLayout`) — absent when nothing was declared,
+ * exactly as `../providers/native/graph.mjs` already does for `archkeep.json`,
+ * which is what keeps `graph.workspaceLayout ?? DEFAULT_WORKSPACE_LAYOUT`
+ * working unchanged and keeps the two providers structurally identical here.
+ * A declared-but-incomplete layout throws rather than being silently dropped
+ * or silently completed — the same refusal
+ * `../providers/native/model.mjs`'s `workspaceLayoutViolations` already
+ * applies to `archkeep.json`'s identically-shaped field, so the two providers
+ * agree on the same declared object rather than one merging onto a default
+ * the other would have refused.
+ *
+ * @param {string} workspaceRoot
+ * @param {{ run?: typeof runProcess, resolveNx?: () => string,
+ *   readLayout?: typeof readWorkspaceLayout }} [io]
+ *   Injectable spawn, injectable Nx resolution (see `nxCli`), and injectable
+ *   `workspaceLayout` read (see `../options.mjs`).
+ * @returns {object} `{ nodes, dependencies }`, plus `workspaceLayout` when
+ *   `nx.json` declares a complete one.
+ */
+export function readProjectGraph(
+  workspaceRoot,
+  { run = runProcess, resolveNx, readLayout = readWorkspaceLayout } = {},
+) {
+  const dir = mkdtempSync(join(tmpdir(), "archkeep-"));
+  const file = join(dir, "graph.json");
+  try {
+    run(process.execPath, [nxCli({ resolveNx }), "graph", `--file=${file}`], workspaceRoot);
+    const { graph } = JSON.parse(readFileSync(file, "utf8"));
+    if (!graph?.nodes) {
+      throw new Error(
+        `archkeep: \`nx graph\` produced no \`graph.nodes\` in ${file} — ` +
+          `nothing can be judged against a graph with no projects in it`,
+      );
+    }
+    const workspaceLayout = requireCompleteWorkspaceLayout(readLayout(workspaceRoot));
+    return workspaceLayout === null ? graph : { ...graph, workspaceLayout };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The `ProjectModelProvider` object a future provider-selection seam holds —
+ * not consumed by anything yet (`cli.mjs` and `index.mjs` still import
+ * `readProjectGraph` directly, the same function this wraps), but exported now
+ * so a second provider has a real shape to match rather than a description of
+ * one.
+ *
+ * @type {ProjectModelProvider}
+ */
+export const nxProvider = {
+  name: "nx",
+  readProjectGraph,
+};

package/src/report/README.md

@@ -0,0 +1,89 @@
+# `src/report/` — rendering violations and descriptive payloads
+
+The formatters that turn command output into text or protocol payloads, one per
+surface, sharing one input. Each is a pure function from records to output:
+
+- `text.mjs` — the terminal report for `../../cli.mjs`'s `check`, in the
+  `file:line:column` shape an editor and a terminal both make clickable — which
+  is why the analysis record carries 1-based positions
+  (`../analysis/contract.md`);
+- `sarif.mjs` — SARIF 2.1.0 for CI, so a failing job can be read without
+  scraping a human report, and so GitHub can annotate the diff. The failure it
+  guards against is a file GitHub silently rejects: the job stays green, no
+  annotation appears, and nothing says why. Nothing here validates against the
+  published schema — there is no schema validator in this workspace at all.
+  What `sarif.integration.test.mjs` pins instead is the subset of the 2.1.0
+  schema a rejected upload turns on, checked against the real message table:
+  `version`, `tool.driver.name`, a `ruleId` that resolves in the catalogue, a
+  non-empty `message.text`, and a repository-relative `uri` with a 1-based
+  `startLine`/`startColumn`.
+- `graph-text.mjs` — the terminal report for `../../cli.mjs`'s `graph` command:
+  projects with their outgoing edges listed beneath each one, `(no
+dependencies)` for projects with no edges, and a coverage claim above the
+  listing. Renders the same payload `json.mjs` wraps; decides nothing.
+- `diff-text.mjs` — the terminal report for `../../cli.mjs`'s `diff` command:
+  baseline/head summaries, added/removed sections, and a change count. Empty
+  sections are omitted so "no changes" and "0 added, 0 removed" never look
+  identical. Renders the same payload `json.mjs` wraps; decides nothing.
+- `impact-text.mjs` — the terminal report for `../../cli.mjs`'s `impact`
+  command: a coverage claim above the listing, the target project header, each
+  dependent on its own line, and a summary line with direct/transitive counts.
+  A project with no dependents states the 0 count explicitly — an empty
+  `dependents` list is a claim, not silence. Renders the same payload
+  `json.mjs` wraps; decides nothing.
+- `explain-text.mjs` — the terminal report for `../../cli.mjs`'s `explain`
+  command: the `file:line:column` position unindented (clickable), then the
+  import specifier, source/target projects with tags, matched constraint rows,
+  and the verdict (allowed/VIOLATION/UNRESOLVABLE), each indented. Coverage
+  sits at the bottom, same shape as every other command. Renders the same
+  payload `json.mjs` wraps; decides nothing.
+- `history-text.mjs` — the terminal report for `../../cli.mjs`'s `history`
+  command: the history directory, a capture line, each snapshot with its short
+  id, and each transition classified (architecture / policy / provider /
+  code drift / unchanged) with its changes and disclosure notes. Renders the
+  same payload `json.mjs` wraps; decides nothing.
+- `evidence.mjs` — the decision builder, `buildDecision`: turns a command's
+  verdict counts into the `decision` the envelope optionally carries, enforcing
+  the five evidence invariants (`../governance/verdict.mjs` states them) in
+  code — `pass` requires complete coverage, `fail` requires a finding, `unknown`
+  requires a reason, `not_applicable` requires `notApplicableReason`, and a
+  could-not-determine run is never a `pass`. It decides nothing about whether a
+  finding IS one; it throws when the verdict and its evidence disagree.
+
+`json.mjs` is not a formatter in that sense — it does not turn violations into
+output. `jsonEnvelope` wraps whatever result object a command already computed
+(`../../cli.mjs`'s `check` builds its own `result.violations`/`result.goWork`/
+`result.tsconfigPaths`) in one versioned envelope every `--format json`
+consumer shares, and enforces in code the three consistency rules
+`docs/reference/json-output.md` documents in prose: `status: "ok"` never rides
+incomplete coverage, `status` and `exitCode` never disagree, and
+`coverage.complete` never disagrees with whether `coverage.notAnalyzed` is
+empty. It throws rather than degrade on any of the three, because a mismatch
+there is a bug in the command that built the envelope, not a fact about the
+workspace being judged. It also refuses a `decision` whose `verdict` contradicts
+the envelope's `status` — the same rule, at the evidence layer.
+
+## Where the LSP conversion lives, and why not here
+
+Not here. Language Server Protocol positions are 0-based and the analysis
+record's are 1-based, and the subtraction is in `../lsp/diagnostics.mjs` beside
+the rest of the protocol shaping — because a diagnostic is more than a
+converted position, and splitting it across two directories would put half a
+format in each. `../../AGENTS.md` records the same division: everything with a
+decision in it lives under `src/lsp/`, and `lsp.mjs` holds only the wiring.
+
+## The two formats say the same thing in different places
+
+The terminal report puts the constraint row that fired on its own line; SARIF
+appends it to `message.text`, because GitHub renders that field and nothing
+else. Both carry the upstream `messageId` unchanged — SARIF as `ruleId`, text
+as the first line — since that id, not the prose, is what makes a verdict
+comparable to ESLint's.
+
+## What must not land here
+
+- **Any decision about whether something is a violation.** A formatter that
+  filters is a rule wearing a formatter's name, and it will disagree with the
+  rule engine the first time one of them changes.
+- **A process exit code.** The exit-code table is `../../cli.mjs`'s contract
+  and is documented in its header.

package/src/report/adr-text.mjs

@@ -0,0 +1,129 @@
+/**
+ * The `adr` command's text renderers — one function per surface the command
+ * prints, all pure so a test drives them without a registry on disk.
+ *
+ * The renderers state the registry and its binding completeness, and never
+ * invent a verdict the registry did not establish: an ADR with no bindings is
+ * named "not yet enforceable", a binding naming no known rule/fitness is named
+ * unknown, and an empty registry stays a sentence, never a table. The dump and
+ * the single-record report render one record's bindings through one function
+ * (`bindingsLine`), so the two faces cannot disagree about which of them is
+ * marked.
+ */
+import { ADR_DIR, ADR_STATUSES } from "../governance/adr-registry.mjs";
+
+/** A status label for a record, in the text a human reads. */
+function statusLabel(status) {
+  if (status === "accepted") return "accepted";
+  if (status === "superseded") return "superseded";
+  return "proposed";
+}
+
+/**
+ * The `bindings:` line for one record — the ONE place either face decides how
+ * a binding is rendered.
+ *
+ * A binding names an id in the rule/fitness name space, and `../commands/adr.mjs`
+ * cannot verify that anything declares it (its header's "What it cannot
+ * assert" owns why). What it can do is say which ids the registry itself
+ * mentions, and mark the rest — so `(unknown)` is the reader's signal that a
+ * decision claims to bind something nothing here corroborates.
+ *
+ * This lived twice, and the second copy did not carry the marker at all:
+ * `formatAdrRecord` took no known set, so `adr <NNN-slug>` printed a dangling
+ * binding identically to an enforced one while `formatAdrDump` marked it on
+ * the same record, and the JSON face carried the fact to a machine reader that
+ * the terminal reader never saw. One function is what keeps the two faces from
+ * disagreeing again.
+ *
+ * @param {{bindings: string[]}} record
+ * @param {Set<string>} known The ids the registry's records mention.
+ * @returns {string}
+ */
+function bindingsLine(record, known) {
+  if (record.bindings.length === 0) {
+    return `bindings:   (none — not yet enforceable)`;
+  }
+  const bound = record.bindings.map((binding) =>
+    known.has(binding) ? binding : `${binding} (unknown)`,
+  );
+  return `bindings:   ${bound.join(", ")}`;
+}
+
+/**
+ * Renders the whole registry: one block per record, each naming its status,
+ * its supersession chain, and the rules/fitnesses it binds.
+ *
+ * @param {{records: object[], knownFitness?: Set<string>}} result
+ * @returns {string}
+ */
+export function formatAdrDump({ records, knownFitness }) {
+  if (records.length === 0) {
+    return `no ADRs in ${ADR_DIR}/ — nothing is recorded, and nothing is enforceable through it`;
+  }
+  const known = knownFitness ?? new Set();
+  const blocks = records.map((record) => {
+    const header = `${record.id}  (${statusLabel(record.status)})`;
+    const lines = [header, "-".repeat(header.length)];
+    if (record.supersedes.length > 0) {
+      lines.push(`supersedes: ${record.supersedes.join(", ")}`);
+    }
+    lines.push(bindingsLine(record, known));
+    lines.push(`status set: ${ADR_STATUSES.join(", ")}`);
+    return lines.join("\n");
+  });
+  return blocks.join("\n\n");
+}
+
+/**
+ * Renders a reverse lookup: which ADRs bind a given rule/fitness id. An empty
+ * answer is a sentence naming the unknown, never silence.
+ *
+ * @param {{fitnessId: string, adrIds: string[]}} result
+ * @returns {string}
+ */
+export function formatAdrReverse({ fitnessId, adrIds }) {
+  if (adrIds.length === 0) {
+    return `no ADR in ${ADR_DIR}/ binds ${fitnessId} — it is not enforced by any recorded decision`;
+  }
+  return `${fitnessId} is bound by: ${adrIds.join(", ")}`;
+}
+
+/**
+ * Renders a requested ADR id that matches the `NNN-slug` pattern but names no
+ * file — the one case the command reads as unresolved, never as an empty
+ * reverse lookup.
+ *
+ * @param {{adrId: string}} result
+ * @returns {string}
+ */
+export function formatAdrMissing({ adrId }) {
+  return (
+    `no ADR ${adrId} in ${ADR_DIR}/ — nothing is recorded under that id, and a ` +
+    `decisionRef naming it cannot resolve`
+  );
+}
+
+/**
+ * Renders one record's details — the `adr <NNN-slug>` face of the same record
+ * the dump above renders, and it must mark an unknown binding the same way:
+ * a reader who asked about one record sees strictly less than one who dumped
+ * the registry otherwise, and what they stop seeing is the marker.
+ *
+ * @param {{id: string, status: string, supersedes: string[], bindings: string[]}} record
+ * @param {Set<string>} [knownFitness] The ids the registry's records mention.
+ *   Optional only so the parameter can be omitted where there is nothing to
+ *   compare against; an absent set marks every binding rather than none,
+ *   because "nothing corroborates this" is the honest answer when no set was
+ *   supplied — never the quiet one.
+ * @returns {string}
+ */
+export function formatAdrRecord(record, knownFitness) {
+  const header = `${record.id}  (${statusLabel(record.status)})`;
+  const lines = [header, "-".repeat(header.length)];
+  if (record.supersedes.length > 0) {
+    lines.push(`supersedes: ${record.supersedes.join(", ")}`);
+  }
+  lines.push(bindingsLine(record, knownFitness ?? new Set()));
+  return lines.join("\n");
+}

package/src/report/context-text.mjs

@@ -0,0 +1,109 @@
+/**
+ * The terminal report for the `context` command: the architecture constraints
+ * that apply to a project.
+ *
+ * The project's tags are listed first, then each matching constraint row
+ * rendered the same way `./text.mjs`'s `formatConstraint` renders them — a
+ * reader who has seen a violation's constraint line in `check` output
+ * recognises the same shape here. When a constraint row carries `description`
+ * or `remediation`, those appear indented below the row.
+ *
+ * The project's current dependencies follow, each with a per-edge constraint
+ * verdict — so a developer (or an AI agent) sees which edges are allowed and
+ * which violate before writing a new import.
+ *
+ * A project with no tags states so explicitly — "no tags" — because a project
+ * with no tags and a renderer that printed nothing would be indistinguishable
+ * (`AGENTS.md`: "an empty result is a claim, not a shrug"). A project whose
+ * tags match no constraint row states that too: the `check` command would
+ * flag it as `projectWithoutTagsCannotHaveDependencies`, so a reader seeing
+ * "(no matching constraint rows)" knows the project is unconstrained rather
+ * than the command having failed to look.
+ *
+ * The coverage claim sits ABOVE the listing, not below it, so the reader
+ * knows whether the result is complete before reading any 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`).
+ */
+
+import { formatConstraint } from "./text.mjs";
+
+/** Two spaces of indent for detail lines. */
+const DETAIL = "  ";
+
+/**
+ * The whole context report.
+ *
+ * @param {{projectContext: {project: string, tags: string[], constraints: object[],
+ *   dependencies: {target: string, type: string, violations: object[]}[]},
+ *   coverage: object, unresolvedDecisionRefs?: Set<string>}} input
+ *   `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 `check`'s report uses.
+ * @returns {string}
+ */
+export function formatContextReport({ projectContext, coverage, unresolvedDecisionRefs }) {
+  const sections = [];
+
+  // Coverage claim goes FIRST — above the listing — so the reader knows
+  // whether the context is complete before reading any entry.
+  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(`✔ context complete (${inspected})`);
+  } else {
+    const notAnalyzedCount = coverage.notAnalyzed.length;
+    sections.push(
+      `✖ context incomplete — ${notAnalyzedCount} file${notAnalyzedCount === 1 ? "" : "s"} ` +
+        `could not be analyzed, so these constraints may be against an incomplete graph (${inspected})`,
+    );
+  }
+
+  // Project name and tags.
+  const tagsText = projectContext.tags.length > 0 ? projectContext.tags.join(", ") : "none";
+  sections.push(`Project  ${projectContext.project}`);
+  sections.push(`Tags     ${tagsText}`);
+
+  // Constraint rows.
+  if (projectContext.constraints.length > 0) {
+    const count = projectContext.constraints.length;
+    sections.push(
+      `Constraints (${count} row${count === 1 ? "" : "s"} match${count === 1 ? "es" : ""}):`,
+    );
+    for (const constraint of projectContext.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)",
+    );
+  }
+
+  // Dependencies with per-edge verdicts.
+  if (projectContext.dependencies && projectContext.dependencies.length > 0) {
+    const count = projectContext.dependencies.length;
+    sections.push(`Dependencies (${count} edge${count === 1 ? "" : "s"}):`);
+    for (const dep of projectContext.dependencies) {
+      const verdict = dep.violations.length > 0 ? "VIOLATION" : "allowed";
+      sections.push(`${DETAIL}${dep.target} (${dep.type}) ${verdict}`);
+      for (const v of dep.violations) {
+        sections.push(`${DETAIL}  ${v.messageId}`);
+      }
+    }
+  } else {
+    sections.push("Dependencies  (none)");
+  }
+
+  return sections.join("\n");
+}

package/src/report/debt-text.mjs

@@ -0,0 +1,105 @@
+/**
+ * The terminal report for the `debt` command: the architecture-debt ledger as
+ * a table a reader can act on.
+ *
+ * Every section ends with a count, and the header states what the ledger is a
+ * claim about — how many entries, across how many snapshots, and whether the
+ * ages are real. `agings: false` is the debt-report way of saying "observed,
+ * not yet aged": ages are all 0 because the directory cannot establish time,
+ * and showing them as 0 while disclosing why keeps "this debt is exactly one
+ * snapshot old" from ever being read as "born yesterday".
+ *
+ * An empty ledger prints a "✔ no architecture debt" line — a claim about the
+ * whole comparison, never a bare zero. The aggregates are printed even when
+ * empty, so a reader can tell "no debt" from "the report forgot a section".
+ *
+ * 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, so a crafted suppression path, project name or finding cannot
+ * inject escape sequences into a consumer's terminal (`SECURITY.md`). The same
+ * sanitation every other report renderer uses.
+ *
+ * @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 whole debt report.
+ *
+ * @param {{ledger: {dir: string, snapshots: number, agings: boolean,
+ *   sampleTime: string, entries: {source: string, kind: string,
+ *   severity: string, age: number, count: number, remediationHint: string}[],
+ *   total: number, byKind: object, bySeverity: object},
+ *   coverage: object}} input
+ * @returns {string}
+ */
+export function formatDebtReport({ ledger, coverage }) {
+  const sections = [];
+
+  sections.push(`debt  ${ledger.dir}`);
+  const word = ledger.total === 1 ? "entry" : "entries";
+  const ageWord = ledger.agings
+    ? "a snapshot-relative ledger"
+    : "ages not yet established (fewer than two snapshots)";
+  sections.push(
+    `${ledger.total} ${word} across ${ledger.snapshots} snapshot${ledger.snapshots === 1 ? "" : "s"} — ${ageWord}`,
+  );
+
+  const orderedKinds = [
+    ["waiver", "waivers (accepted boundary violations)"],
+    ["aspirational-gap", "aspirational gaps (optional allowed rows not built)"],
+    ["drift", "drift findings"],
+    ["unresolved", "unresolved intent"],
+  ];
+  let sawAny = false;
+  for (const [kind, label] of orderedKinds) {
+    const items = ledger.entries.filter((e) => e.kind === kind);
+    if (items.length === 0) continue;
+    sawAny = true;
+    sections.push(`${items.length} ${label}:`);
+    for (const entry of items) {
+      const age = ledger.agings ? `age ${entry.age}` : "age not yet established";
+      sections.push(
+        `  [${entry.kind}] ${entry.severity}  ${sanitize(entry.source)}  (${age}, count ${entry.count})`,
+      );
+      sections.push(`    ${sanitize(entry.remediationHint)}`);
+    }
+  }
+
+  if (!sawAny) {
+    sections.push(
+      "✔ no architecture debt — no waivers, aspirational gaps, drift or unresolved intent",
+    );
+  }
+
+  sections.push(
+    `total ${ledger.total} ${word} · byKind: waiver ${ledger.byKind.waiver}, ` +
+      `aspirational-gap ${ledger.byKind["aspirational-gap"]}, drift ${ledger.byKind.drift}, ` +
+      `unresolved ${ledger.byKind.unresolved} · bySeverity: high ${ledger.bySeverity.high}, ` +
+      `medium ${ledger.bySeverity.medium}, low ${ledger.bySeverity.low}`,
+  );
+  sections.push(`sampled ${ledger.sampleTime}`);
+
+  // The coverage line states what the ledger is a claim about, the same
+  // disclosure every other report renderer makes (`graph-text.mjs`, etc.).
+  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(coverage.complete ? `✔ complete (${inspected})` : `✖ ${inspected}`);
+
+  return sections.join("\n");
+}