@ecoma-io/archkeep 0.14.0 → 0.16.0

package/src/providers/native/graph.mjs

@@ -232,3 +232,61 @@ export function buildNativeGraph({
     ...(exemptedFiles && exemptedFiles.length > 0 ? { exemptedFiles } : {}),
   };
 }
+
+/**
+ * Folds manifest-resolver records — `{source, target, sourceFile, type}` from
+ * `../../graph/create-dependencies.mjs`'s `resolveDeclaredManifestEdges` —
+ * into an already-built graph's `dependencies`, in place. The callers are the
+ * graph assemblies that have no plugin host to draw these edges for them:
+ * this module's own `buildGraph` (the CLI's native branch and this package's
+ * language-server index), the Moon branch of both, and the language server's
+ * Nx-shaped index. On the CLI's Nx branch the polyglot plugin registers into
+ * Nx's own graph computation instead — `resolvePolyglotDependencies` there,
+ * these same resolvers — so that face arrives with the edges already drawn.
+ *
+ * Deduplication is by `(source, target, type)`, the same key `buildDependencies`
+ * dedupes import sites by and the same key the JSON envelope flattens on, so a
+ * dependency witnessed by BOTH tracks — a written `using` and the
+ * `<ProjectReference>` for it, a Kotlin import and the Gradle `project(":x")`
+ * — carries one record, exactly as one witnessed by two imports does. The
+ * resolvers iterate only the workspace's own projects and resolve every target
+ * against that same project list, so source and target are nodes of the graph
+ * this fold serves by construction; no membership check is taken here, because
+ * one that skipped would be the silent direction — an edge dropped for not
+ * being a node is a finding unreported, where a mismatch between the merged
+ * records and the graph's nodes is a caller bug that should surface.
+ *
+ * @param {{nodes: Record<string, object>, dependencies?: Record<string, {source: string, target: string, type: string}[]>}} graph
+ *   Mutated in place.
+ * @param {{source: string, target: string, sourceFile?: string, type: string}[]} records
+ * @returns {{nodes: Record<string, object>, dependencies: Record<string, {source: string, target: string, type: string}[]>}} The same graph.
+ */
+export function mergeDeclaredEdges(graph, records) {
+  // Null-prototype for the same reason `buildDependencies` above uses one:
+  // every key is a project name this package does not control.
+  const dependencies = graph.dependencies ?? Object.create(null);
+  graph.dependencies = dependencies;
+  const seen = new Set();
+  for (const list of Object.values(dependencies)) {
+    for (const edge of list ?? []) {
+      seen.add(JSON.stringify([edge.source, edge.target, edge.type]));
+    }
+  }
+  for (const record of records) {
+    const key = JSON.stringify([record.source, record.target, record.type]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    (dependencies[record.source] ??= []).push({
+      source: record.source,
+      target: record.target,
+      type: record.type,
+    });
+  }
+  // The cast is the post-condition the signature promises: the fold above
+  // guarantees `dependencies` exists on the graph it returns, but the
+  // parameter's declared type — which admits a graph arriving without one —
+  // is what `graph` carries here.
+  return /** @type {{nodes: Record<string, object>, dependencies: Record<string, {source: string, target: string, type: string}[]>}} */ (
+    graph
+  );
+}

package/src/providers/native/model.mjs

@@ -195,10 +195,66 @@ export const DEFAULT_MANIFEST_NAMES = Object.freeze([
   "go.mod",
   "Cargo.toml",
   "pyproject.toml",
+  // Maven: every tracked root pom.xml anchors a project (ADR 0005). Identity
+  // is `(groupId, artifactId)` read by `../../analysis/jvm/maven.mjs`; the
+  // name follows the same precedence as every other inferred manifest, so
+  // pom-discovered projects land on their directory basename unless a
+  // declared row names them.
+  "pom.xml",
+  // Gradle: settings.gradle / settings.gradle.kts anchors a Gradle build
+  // (ADR 0005 Decision 2). Identity is the root project name and included
+  // projects from the settings file; edges are read from build.gradle /
+  // build.gradle.kts by `../../analysis/jvm/gradle.mjs`. The settings file
+  // is the discovery manifest — it defines the reactor structure — while
+  // the build files hold the dependency declarations.
+  "settings.gradle",
+  "settings.gradle.kts",
+  // .NET/C#: every tracked root .csproj anchors a project (ADR 0006). Identity
+  // is the project name read by `../../analysis/dotnet/csproj.mjs`; the
+  // name follows the same precedence as every other inferred manifest, so
+  // csproj-discovered projects land on their directory basename unless a
+  // declared row names them.
+  "*.csproj",
 ]);
 
 const PROJECT_TYPES = ["app", "lib", "e2e"];
 
+/**
+ * The deliberate default for `projects.infer.exclude` — the anchor-exclusion
+ * half of the phantom-project policy (issue #371): a tracked manifest inside a
+ * directory that is documentation or test data about the workspace, rather
+ * than a part of it, never anchors an inferred project, because inference over
+ * it would judge a phantom as real. `docs/`, `fixtures/` and `__fixtures__/`
+ * as whole path segments are the complete set: those three names mean "data
+ * about the tree" in every convention this package has measured, and a name
+ * like `examples/` was deliberately left OFF it — example projects are
+ * commonly real, built, governed code, so excluding them by name would be the
+ * same over-broad-by-name error the `obj`/`bin` half of the same issue
+ * repudiated (`./discover.mjs`'s `isDotnetGeneratedOutput`).
+ *
+ * Two facts make this exclusion safe rather than a silent hole:
+ *
+ * - `projects.declared` is exempt — a workspace with a real project under one
+ *   of these paths declares it, and declaration is the authoritative channel
+ *   inference never touches.
+ * - A dropped anchor's analyzable files do not vanish silently: they surface
+ *   through `./coverage.mjs`'s unclaimed-file judgment as whole-file failures
+ *   until the workspace either declares the project or records a reasoned
+ *   `coverage.exempt` row — which is the loud, explicit opt-in for "this
+ *   directory is fixture data".
+ *
+ * An explicit `exclude` list REPLACES this default (the `tsc` convention for
+ * the same field): a workspace that names its own list takes over the whole
+ * decision, `exclude: []` included — that spelling is the documented opt-out.
+ *
+ * @see DEFAULT_MANIFEST_NAMES
+ */
+export const DEFAULT_INFER_EXCLUDE = Object.freeze([
+  "**/docs/**",
+  "**/fixtures/**",
+  "**/__fixtures__/**",
+]);
+
 /** @type {(value: unknown) => value is Record<string, unknown>} */
 const isPlainObject = (value) =>
   typeof value === "object" && value !== null && !Array.isArray(value);
@@ -702,7 +758,9 @@ export function normalizeNativeModel(raw) {
           : {
               manifests: rawInfer.manifests ?? DEFAULT_MANIFEST_NAMES,
               include: rawInfer.include ?? ["**"],
-              exclude: rawInfer.exclude ?? [],
+              // Replaces, never merges: an explicit list takes over the whole
+              // decision — `DEFAULT_INFER_EXCLUDE`'s doc comment owns the why.
+              exclude: rawInfer.exclude ?? DEFAULT_INFER_EXCLUDE,
             },
     },
     projectRules: /** @type {unknown[]} */ (raw.projectRules ?? []).map((row) => {

package/src/report/change-text.mjs

@@ -0,0 +1,148 @@
+/**
+ * The terminal report for the `change` command: a declared change-intent
+ * contract against the architectural delta actually observed
+ * (`../commands/change.mjs`).
+ *
+ * The report is a review document, so it renders every axis separately and in
+ * full: what was declared, what matched, what appeared without a declaration,
+ * which declared changes never happened, how each declared constraint judged,
+ * and — informational, never this command's verdict — how many live boundary
+ * violations the tree currently carries under the current law, with `check`
+ * named as the authority on that axis. A section renders only when it has
+ * content; the closing line always states what was compared and with what
+ * outcome, so an empty reconciliation is a verifiable claim rather than
+ * silence (`../../../../AGENTS.md`).
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`./README.md`).
+ */
+
+/** One expected-fact row as report lines. */
+function factLines(entry) {
+  switch (entry.kind) {
+    case "project-added":
+      return [`  + project ${entry.project}`];
+    case "project-removed":
+      return [`  - project ${entry.project}`];
+    case "edge-added":
+      return [
+        `  + edge ${entry.from} -> ${entry.to}${entry.type === undefined ? "" : ` (${entry.type})`}`,
+      ];
+    case "edge-removed":
+      return [
+        `  - edge ${entry.from} -> ${entry.to}${entry.type === undefined ? "" : ` (${entry.type})`}`,
+      ];
+    case "project-changed": {
+      const lines = [`  ! project ${entry.project} changed:`];
+      for (const change of entry.changes ?? []) {
+        lines.push(
+          `      ${change.field}: ${JSON.stringify(change.baseline)} -> ${JSON.stringify(change.head)}`,
+        );
+      }
+      return lines;
+    }
+    default:
+      return [`  ? ${entry.kind} ${entry.project ?? `${entry.from} -> ${entry.to}`}`];
+  }
+}
+
+/** One constraint verdict row as its report lines. */
+function constraintLines(row) {
+  const glyph = row.verdict === "pass" ? "✔" : row.verdict === "fail" ? "✗" : "?";
+  return [`${glyph} ${row.name}: ${row.verdict} — ${row.message}`];
+}
+
+/** 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}`;
+}
+
+/**
+ * The whole change report.
+ *
+ * @param {{change: object, coverage: object}} input `change` is
+ *   `../commands/change.mjs`'s result payload; `coverage` its coverage block.
+ * @returns {string}
+ */
+export function formatChangeReport({ change, coverage }) {
+  const { intent, baseline, head, reconciliation, constraints, policy } = change;
+  const sections = [];
+
+  sections.push(
+    `intent     ${intent.file} — base ${intent.base.commit.slice(0, 8)}` +
+      (intent.summary === undefined ? "" : `\n             "${intent.summary}"`),
+  );
+  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.projects} project${head.projects === 1 ? "" : "s"}`,
+  );
+
+  for (const note of coverage.notes ?? []) sections.push(`⚠ ${note}`);
+
+  const verdictLine = {
+    matched: "✔ MATCHED — the delta is exactly the declared change",
+    undeclared: "⚠ UNDECLARED — the delta contains changes no declaration covers",
+    unfulfilled: "✗ UNFULFILLED — nothing undeclared, but declared changes never happened",
+    unproven: "? UNPROVEN — the base identity could not be established",
+  }[reconciliation.verdict];
+  sections.push(`reconciliation ${verdictLine}`);
+  for (const reason of reconciliation.reasons) sections.push(`  because: ${reason}`);
+
+  if (reconciliation.matched.length > 0) {
+    sections.push(
+      `✔ ${reconciliation.matched.length} declared change${reconciliation.matched.length === 1 ? "" : "s"} observed`,
+      ...reconciliation.matched.flatMap(factLines),
+    );
+  }
+  if (reconciliation.unexpected.length > 0) {
+    sections.push(
+      `! ${reconciliation.unexpected.length} undeclared material change${reconciliation.unexpected.length === 1 ? "" : "s"} — a review signal, not a law verdict`,
+      ...reconciliation.unexpected.flatMap(factLines),
+    );
+  }
+  if (reconciliation.missingExpected.length > 0) {
+    sections.push(
+      `? ${reconciliation.missingExpected.length} declared change${reconciliation.missingExpected.length === 1 ? "" : "s"} never observed`,
+      ...reconciliation.missingExpected.flatMap(factLines),
+    );
+  }
+
+  if (constraints.length > 0) {
+    sections.push("declared constraints");
+    sections.push(...constraints.flatMap(constraintLines));
+  }
+
+  // Informational on purpose: this number says what `check` would count right
+  // now. It gates nothing here — collapsing it into the intent verdict would
+  // hide one signal behind the other.
+  sections.push(
+    policy.liveViolations === null
+      ? `workspace law  not evaluated — the run could not prove the base identity (archkeep check remains the authority)`
+      : `workspace law  ${policy.liveViolations} live violation${policy.liveViolations === 1 ? "" : "s"} under the current law${policy.changedSinceBase ? ", which changed since capture" : ""} — informational; archkeep check remains the authoritative verdict`,
+  );
+
+  // The closing claim always states what was compared, so every outcome —
+  // including a full match over an unchanged tree — is a verifiable statement
+  // rather than silence.
+  const declaredCount =
+    intent.declared.projectsAdd +
+    intent.declared.projectsRemove +
+    intent.declared.edgesAdd +
+    intent.declared.edgesRemove;
+  sections.push(
+    `reconciled ${declaredCount} declared change${declaredCount === 1 ? "" : "s"} and ` +
+      `${constraints.length} declared constraint${constraints.length === 1 ? "" : "s"} — ` +
+      `base ${describeOrigin(baseline.provenance)} (${baseline.projects} projects, ` +
+      `${baseline.records} records) against head ${describeOrigin(head.provenance)} ` +
+      `(${head.projects} projects)`,
+  );
+
+  return sections.join("\n");
+}

package/src/report/delta-text.mjs

@@ -6,7 +6,10 @@
  * 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),
- * and the unresolvable-import block — and the summary line always states what
+ * 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`).
@@ -59,6 +62,71 @@ 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.
  *
@@ -162,6 +230,10 @@ export function formatDeltaReport({ delta, coverage }) {
     );
   }
 
+  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 =
@@ -178,6 +250,15 @@ export function formatDeltaReport({ delta, coverage }) {
         `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/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.