terramend 0.2.0

package/src/mcp/terraform/findings.ts

@@ -0,0 +1,333 @@
+import { ruleDocUrl } from "#app/mcp/terraform/decisions";
+import {
+  type Concern,
+  concernId,
+  isTerraformFile,
+  lowerSeverity,
+  type Severity,
+  toRepoRelative,
+} from "#app/mcp/terraform/types";
+
+// --- reviewer findings (read_findings) ------------------------------------
+
+/**
+ * The subset of a terraform-reviewer (Assessor) `findings.json` finding that
+ * Terramend consumes. The reviewer's contract is a deliberate SUPERSET of the
+ * Concern model (same content-id formula, same severity enum) — see
+ * ../terraform-reviewer/schemas/findings.schema.json. Extra fields
+ * (lens/standard/control_id/confidence/state) are ignored except `state`.
+ */
+interface ReviewerFinding {
+  category?: string;
+  source?: string;
+  rule_id?: string;
+  /** verified (deterministic) | evidence (confirm manually) | human_only (out of scope). */
+  state?: string;
+  severity?: string;
+  evidence?: string;
+  location?: { file?: string; line?: number | null };
+  remediation_hint?: string | null;
+}
+
+interface ReviewerFindingsReport {
+  schema_version?: string;
+  findings?: ReviewerFinding[] | null;
+}
+
+/**
+ * Map a reviewer `source` to a Concern source. The scanners Terramend also runs
+ * (checkov / tflint / trivy / terraform-fmt / terraform-validate) keep their
+ * name, so re-running them reproduces the identical content id — those concerns
+ * are ✗→✓ verifiable. Everything else (tfsec — whose rule ids differ from
+ * trivy's — plus infracost, llm, …) collapses to `reviewer`: the original tool
+ * stays visible in `rule_id`, but Terramend can't reproduce the id, so
+ * `terraform_verify_remediation` will honestly report it unresolved.
+ *
+ * NB: trivy ✗→✓ verifiability assumes the reviewer's trivy `rule_id` equals
+ * Terramend's (both `trivy:<AVDID>`). That holds today (the reviewer's SARIF
+ * `ruleId` is the AVD id); if a future Trivy diverges SARIF ruleId from the
+ * JSON AVDID, trivy-source findings would stop matching on re-scan.
+ */
+function mapReviewerSource(source: string | undefined): Concern["source"] {
+  switch (source) {
+    case "checkov":
+    case "tflint":
+    case "trivy":
+    case "terraform-fmt":
+    case "terraform-validate":
+      return source;
+    default:
+      return "reviewer";
+  }
+}
+
+function mapReviewerCategory(category: string | undefined): Concern["category"] {
+  switch (category) {
+    case "security":
+      return "security";
+    case "style":
+      return "style";
+    case "cost":
+      return "cost";
+    default:
+      return "correctness";
+  }
+}
+
+/**
+ * Map a reviewer `findings.json` body into Concern[]. Drops `human_only`
+ * findings (out of scope — not auto-remediable). Paths are normalized to
+ * repo-relative POSIX (same as the scanners) so ids and grouping stay portable.
+ */
+export function parseReviewerFindings(json: string, cwd = ""): Concern[] {
+  const parsed = JSON.parse(json || "{}") as ReviewerFindingsReport;
+  const out: Concern[] = [];
+  for (const f of parsed.findings ?? []) {
+    if (f.state === "human_only") continue;
+    const file = toRepoRelative(f.location?.file, cwd);
+    // Skip findings that don't point at a Terraform file — they aren't per-file
+    // remediable. In particular the reviewer's infracost/cost findings are keyed
+    // to a project *directory* (not a `.tf`), so they land here; cost is surfaced
+    // during remediation by `infracost_diff` (E1), not by editing a directory.
+    if (!isTerraformFile(file)) continue;
+    const line = f.location?.line ?? null;
+    const source = mapReviewerSource(f.source);
+    const ruleId = f.rule_id || "finding";
+    // Terramend's own parsers store `rule_id` namespaced (`${source}:${rule}`)
+    // but hash only the bare rule into the content id. Strip a matching
+    // `${source}:` prefix so a checkov/tflint/trivy/fmt finding from the reviewer
+    // reproduces the SAME id Terramend's own scan would — keeping it ✗→✓
+    // verifiable. `reviewer`-source findings keep the full rule_id in the hash
+    // (they aren't reproducible anyway). Both namespaced and bare inputs work.
+    const bareRule =
+      source !== "reviewer" && ruleId.startsWith(`${source}:`)
+        ? ruleId.slice(source.length + 1)
+        : ruleId;
+    out.push({
+      id: concernId(source, bareRule, file, line),
+      source,
+      rule_id: ruleId,
+      severity: lowerSeverity(f.severity),
+      category: mapReviewerCategory(f.category),
+      evidence: f.evidence || ruleId,
+      location: { file, line },
+      remediation_hint: f.remediation_hint ?? null,
+    });
+  }
+  return out;
+}
+
+// --- SARIF ingestion (read_findings) --------------------------------------
+
+interface SarifLocation {
+  physicalLocation?: {
+    artifactLocation?: { uri?: string };
+    region?: { startLine?: number };
+  };
+}
+interface SarifResult {
+  ruleId?: string;
+  level?: string;
+  message?: { text?: string };
+  locations?: SarifLocation[];
+  properties?: { "security-severity"?: string };
+}
+interface SarifRule {
+  id?: string;
+  helpUri?: string;
+  shortDescription?: { text?: string };
+}
+interface SarifRun {
+  tool?: { driver?: { name?: string; rules?: SarifRule[] } };
+  results?: SarifResult[];
+}
+interface SarifReport {
+  version?: string;
+  $schema?: string;
+  runs?: SarifRun[];
+}
+
+/** true when a parsed JSON object looks like a SARIF report (the standard
+ * scanner-output format) rather than a terraform-reviewer findings.json. */
+export function isSarif(parsed: unknown): boolean {
+  if (!parsed || typeof parsed !== "object") return false;
+  const o = parsed as Record<string, unknown>;
+  const schema = typeof o.$schema === "string" ? o.$schema.toLowerCase() : "";
+  return Array.isArray(o.runs) && (schema.includes("sarif") || typeof o.version === "string");
+}
+
+/** map a SARIF driver name to a Concern source (so a re-run reproduces the id
+ * for the scanners Terramend also runs; everything else → `reviewer`). */
+function mapSarifDriver(name: string | undefined): Concern["source"] {
+  switch ((name ?? "").toLowerCase()) {
+    case "trivy":
+      return "trivy";
+    case "checkov":
+      return "checkov";
+    case "tflint":
+      return "tflint";
+    default:
+      return "reviewer";
+  }
+}
+
+/** SARIF `level` → severity (a `security-severity` property refines it). */
+function sarifSeverity(level: string | undefined, securitySeverity: string | undefined): Severity {
+  const score = securitySeverity ? Number.parseFloat(securitySeverity) : Number.NaN;
+  if (Number.isFinite(score)) {
+    if (score >= 9) return "critical";
+    if (score >= 7) return "high";
+    if (score >= 4) return "medium";
+    if (score > 0) return "low";
+  }
+  switch ((level ?? "").toLowerCase()) {
+    case "error":
+      return "high";
+    case "warning":
+      return "medium";
+    case "note":
+      return "low";
+    default:
+      return "info";
+  }
+}
+
+/**
+ * Parse a SARIF 2.1.0 report (the standard scanner-output format Trivy /
+ * Checkov / tflint all emit) into Concern[]. The driver name picks the source so
+ * a finding from a scanner Terramend re-runs reproduces the SAME content id
+ * (✗→✓ verifiable); other tools collapse to `reviewer`. Rule docs come from the
+ * matching `tool.driver.rules[].helpUri`. Non-Terraform files are dropped.
+ */
+export function parseSarifFindings(json: string, cwd = ""): Concern[] {
+  let report: SarifReport;
+  try {
+    report = JSON.parse(json || "{}") as SarifReport;
+  } catch {
+    return [];
+  }
+  const out: Concern[] = [];
+  for (const run of report.runs ?? []) {
+    const source = mapSarifDriver(run.tool?.driver?.name);
+    const ruleDocs = new Map<string, string>();
+    for (const rule of run.tool?.driver?.rules ?? []) {
+      if (rule.id && rule.helpUri) ruleDocs.set(rule.id, rule.helpUri);
+    }
+    for (const result of run.results ?? []) {
+      const loc = result.locations?.[0]?.physicalLocation;
+      const file = toRepoRelative(loc?.artifactLocation?.uri, cwd);
+      if (!isTerraformFile(file)) continue;
+      const start = loc?.region?.startLine;
+      const line = typeof start === "number" && start > 0 ? start : null;
+      const rawRule = result.ruleId || "finding";
+      // strip a `${source}:` prefix if a tool already namespaced it, so the
+      // content id matches Terramend's own scan of the same rule.
+      const bareRule =
+        source !== "reviewer" && rawRule.startsWith(`${source}:`)
+          ? rawRule.slice(source.length + 1)
+          : rawRule;
+      const ruleId = source === "reviewer" ? rawRule : `${source}:${bareRule}`;
+      out.push({
+        id: concernId(source, bareRule, file, line),
+        source,
+        rule_id: ruleId,
+        severity: sarifSeverity(result.level, result.properties?.["security-severity"]),
+        category: source === "tflint" ? "style" : "security",
+        evidence: result.message?.text || ruleId,
+        location: { file, line },
+        remediation_hint: ruleDocs.get(rawRule) ?? null,
+      });
+    }
+  }
+  return out;
+}
+
+/** dispatch a findings file to the right parser: SARIF (standard scanner
+ * output) or a terraform-reviewer findings.json. */
+export function parseFindingsFile(json: string, cwd = ""): Concern[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json || "{}");
+  } catch {
+    return [];
+  }
+  return isSarif(parsed) ? parseSarifFindings(json, cwd) : parseReviewerFindings(json, cwd);
+}
+
+// --- SARIF emit (GitHub code-scanning) ------------------------------------
+
+/** Concern severity → SARIF `level`. SARIF has only error/warning/note, so
+ * critical+high collapse to `error`, medium → `warning`, low+info → `note`. The
+ * finer grade survives in the `security-severity` property below. */
+function severityToSarifLevel(s: Severity): "error" | "warning" | "note" {
+  switch (s) {
+    case "critical":
+    case "high":
+      return "error";
+    case "medium":
+      return "warning";
+    default:
+      return "note";
+  }
+}
+
+/** Concern severity → the numeric `security-severity` GitHub reads to colour the
+ * alert (0–10 CVSS-like scale). */
+function securitySeverityScore(s: Severity): string {
+  switch (s) {
+    case "critical":
+      return "9.5";
+    case "high":
+      return "8.0";
+    case "medium":
+      return "5.0";
+    case "low":
+      return "2.0";
+    default:
+      return "0.0";
+  }
+}
+
+/**
+ * Emit a set of concerns as a SARIF 2.1.0 report for GitHub code-scanning (the
+ * inverse of `parseSarifFindings` — close the loop so a Terramend scan can
+ * populate the repo's Security tab via `github/codeql-action/upload-sarif`). One
+ * `run` with the `terramend` driver, a deduped `rules` array (each rule's
+ * `helpUri` from `ruleDocUrl`), and one `result` per concern carrying its
+ * `level`, `security-severity`, message, and `file:line`. Pure + deterministic
+ * (rules sorted, stable partialFingerprints from the content id) so re-emitting
+ * an unchanged scan yields a byte-identical report.
+ */
+export function buildSarifReport(concerns: Concern[]): SarifReport {
+  // deduped rule metadata, keyed by the namespaced rule_id (the SARIF ruleId).
+  const rulesById = new Map<string, SarifRule>();
+  for (const c of concerns) {
+    if (rulesById.has(c.rule_id)) continue;
+    const helpUri = ruleDocUrl(c);
+    rulesById.set(c.rule_id, {
+      id: c.rule_id,
+      ...(helpUri ? { helpUri } : {}),
+      shortDescription: { text: c.evidence.slice(0, 200) },
+    });
+  }
+  const rules = [...rulesById.values()].sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""));
+  const results: SarifResult[] = concerns.map((c) => ({
+    ruleId: c.rule_id,
+    level: severityToSarifLevel(c.severity),
+    message: { text: c.evidence },
+    properties: { "security-severity": securitySeverityScore(c.severity) },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: { uri: c.location.file },
+          ...(c.location.line ? { region: { startLine: c.location.line } } : {}),
+        },
+      },
+    ],
+  }));
+  return {
+    version: "2.1.0",
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: [{ tool: { driver: { name: "terramend", rules } }, results }],
+  };
+}

package/src/mcp/terraform/plan.ts

@@ -0,0 +1,348 @@
+import type { BlastTier } from "#app/mcp/terraform/types";
+
+// --- terraform plan (the safety gate) -------------------------------------
+
+export interface PlanSummary {
+  /** resources to add / change / destroy, from the plan's change_summary. */
+  add: number;
+  change: number;
+  destroy: number;
+  /** every resource with a real action (create/update/delete/replace) — the set
+   * that powers blast-radius (§2.6) and plan-stability (§1.3). */
+  changed: { address: string; action: string }[];
+  /** resources that would be deleted or replaced — the destructive set. */
+  destructive: { address: string; action: string }[];
+  hasDestroyOrReplace: boolean;
+  /** state-only moves (`moved {}` blocks / refactors): the new address and the
+   * address it came from. Moves don't mutate live infrastructure, so they are
+   * NOT in `changed` — they power the M2 modularization gate (`isPureMovePlan`). */
+  moved: { address: string; previousAddress: string | null }[];
+}
+
+/**
+ * Parse `terraform plan -json` (newline-delimited JSON). `change_summary` gives
+ * the add/change/destroy totals; each `planned_change` with a real action is
+ * collected into `changed`, and the delete/replace subset into `destructive`
+ * (the high-risk set a reviewer must scrutinise). Non-mutating actions are
+ * ignored, as are non-JSON / non-plan lines, so a noisy stream (provider logs,
+ * diagnostics) parses cleanly.
+ *
+ * NB on the action enum: terraform's machine-readable UI (the `-json` stream)
+ * spells no-op as `"noop"` — NOT `"no-op"` — and also emits `"move"` / `"import"`
+ * / `"forget"` for state-only operations that don't mutate live infrastructure.
+ * None of those should count toward `changed` (they'd inflate the blast radius
+ * §2.6). We skip them explicitly; `"no-op"` is tolerated too in case a wrapper
+ * or older format hyphenates it. See
+ * https://developer.hashicorp.com/terraform/internals/machine-readable-ui.
+ */
+const NON_MUTATING_PLAN_ACTIONS: ReadonlySet<string> = new Set([
+  "noop",
+  "no-op",
+  "read",
+  "move",
+  "import",
+  "forget",
+]);
+
+export function parseTerraformPlanJson(stdout: string): PlanSummary {
+  let add = 0;
+  let change = 0;
+  let destroy = 0;
+  const changed: { address: string; action: string }[] = [];
+  const destructive: { address: string; action: string }[] = [];
+  const moved: { address: string; previousAddress: string | null }[] = [];
+  for (const line of stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) continue;
+    let msg: {
+      type?: string;
+      changes?: { add?: number; change?: number; remove?: number };
+      change?: {
+        action?: string;
+        resource?: { addr?: string; resource?: string };
+        previous_resource?: { addr?: string; resource?: string };
+      };
+    };
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (msg.type === "change_summary" && msg.changes) {
+      add = Number(msg.changes.add) || 0;
+      change = Number(msg.changes.change) || 0;
+      destroy = Number(msg.changes.remove) || 0;
+    } else if (msg.type === "planned_change" && msg.change) {
+      const action = String(msg.change.action ?? "");
+      // moves are state-only (no infra mutation) but are tracked separately —
+      // they prove an M2 modularization refactor is a no-op (`isPureMovePlan`).
+      if (action === "move") {
+        const address = msg.change.resource?.addr || msg.change.resource?.resource || "(unknown)";
+        const previousAddress =
+          msg.change.previous_resource?.addr || msg.change.previous_resource?.resource || null;
+        moved.push({ address, previousAddress });
+        continue;
+      }
+      if (!action || NON_MUTATING_PLAN_ACTIONS.has(action)) continue;
+      const address = msg.change.resource?.addr || msg.change.resource?.resource || "(unknown)";
+      changed.push({ address, action });
+      // "delete", "replace", and the "*-then-delete" / "delete-then-*" forms.
+      if (action.includes("delete") || action === "replace") {
+        destructive.push({ address, action });
+      }
+    }
+  }
+  return {
+    add,
+    change,
+    destroy,
+    changed,
+    destructive,
+    hasDestroyOrReplace: destructive.length > 0,
+    moved,
+  };
+}
+
+/**
+ * §M2 modularization gate — true when the plan is PURELY state moves: at least
+ * one `moved` entry and zero create/update/delete/replace. That proves a
+ * resources→module refactor preserved every resource address (via `moved {}`
+ * blocks) and is a no-op on live infrastructure — the condition under which a
+ * modularization PR may proceed without human escalation.
+ */
+export function isPureMovePlan(plan: {
+  add: number;
+  change: number;
+  destroy: number;
+  changed: { address: string }[];
+  moved: { address: string }[];
+}): boolean {
+  return (
+    plan.moved.length > 0 &&
+    plan.changed.length === 0 &&
+    plan.add + plan.change + plan.destroy === 0
+  );
+}
+
+// --- stateful destroy/replace classification (safety gate §2.5) ------------
+
+/**
+ * Resource types that hold data/state — destroying or replacing one of these
+ * means data loss, not just recreation. A remediation that would delete or
+ * replace one is hard-blocked at push time unless the operator opts in via the
+ * `allow_replace` input. Not exhaustive: it covers the common managed
+ * datastores across AWS / Azure / GCP; extend as new ones come up.
+ */
+export const STATEFUL_RESOURCE_TYPES: ReadonlySet<string> = new Set([
+  // AWS
+  "aws_db_instance",
+  "aws_rds_cluster",
+  "aws_rds_cluster_instance",
+  "aws_s3_bucket",
+  "aws_ebs_volume",
+  "aws_efs_file_system",
+  "aws_dynamodb_table",
+  "aws_dynamodb_global_table",
+  "aws_elasticache_cluster",
+  "aws_elasticache_replication_group",
+  "aws_redshift_cluster",
+  "aws_docdb_cluster",
+  "aws_neptune_cluster",
+  "aws_opensearch_domain",
+  "aws_elasticsearch_domain",
+  // Azure
+  "azurerm_sql_database",
+  "azurerm_mssql_database",
+  "azurerm_postgresql_database",
+  "azurerm_postgresql_flexible_server",
+  "azurerm_mysql_database",
+  "azurerm_mysql_flexible_server",
+  "azurerm_cosmosdb_account",
+  "azurerm_cosmosdb_sql_database",
+  "azurerm_storage_account",
+  "azurerm_managed_disk",
+  // GCP
+  "google_sql_database_instance",
+  "google_storage_bucket",
+  "google_bigtable_instance",
+  "google_bigquery_dataset",
+  "google_spanner_database",
+  "google_redis_instance",
+  "google_filestore_instance",
+  "google_compute_disk",
+]);
+
+/**
+ * Extract the Terraform resource TYPE from a plan address, stripping any
+ * `module.<name>.` prefixes and an instance index/key suffix:
+ *   `module.db.aws_db_instance.main`               -> `aws_db_instance`
+ *   `aws_s3_bucket.data["prod"]`                   -> `aws_s3_bucket`
+ *   `module.a.module.b.google_storage_bucket.x[0]` -> `google_storage_bucket`
+ * Returns "" when the address has no parseable `type.name` pair.
+ */
+export function resourceTypeOf(address: string): string {
+  const withoutModules = address.replace(/^(?:module\.[^.]+\.)+/, "");
+  const cleaned = withoutModules.replace(/\[[^\]]*\]$/, "");
+  const segments = cleaned.split(".");
+  return segments.at(-2) ?? "";
+}
+
+export interface DestroyClassification {
+  /** destroy/replace of a data-bearing type — high-risk, blocked by default. */
+  stateful: { address: string; action: string; type: string }[];
+  /** destroy/replace of a recreatable type — recorded, not blocked. */
+  ephemeral: { address: string; action: string; type: string }[];
+}
+
+/** partition a plan's destructive set into stateful (blocked) vs ephemeral. */
+export function classifyDestructive(
+  destructive: { address: string; action: string }[],
+): DestroyClassification {
+  const stateful: DestroyClassification["stateful"] = [];
+  const ephemeral: DestroyClassification["ephemeral"] = [];
+  for (const d of destructive) {
+    const type = resourceTypeOf(d.address);
+    (STATEFUL_RESOURCE_TYPES.has(type) ? stateful : ephemeral).push({ ...d, type });
+  }
+  return { stateful, ephemeral };
+}
+
+// --- blast-radius scoring (§2.6) -------------------------------------------
+
+export interface BlastRadius {
+  tier: BlastTier;
+  /** count of resources the plan would create/update/delete/replace. */
+  resourceCount: number;
+  /** distinct module addresses touched (root resources count as `root`). */
+  modules: string[];
+}
+
+/**
+ * Extract the module address from a resource address: the `module.X[.module.Y]`
+ * call path, or `root` for a top-level resource. Strips instance index/key from
+ * EVERY segment — a `count`/`for_each` MODULE carries its key on the module
+ * segment (`module.net[0]`), so all instances of one module collapse to one
+ * address (else a single-module fix would look cross-module). Removing keys
+ * first also tolerates a `.` inside a `for_each` string key.
+ *   `aws_s3_bucket.b`                  -> `root`
+ *   `module.db.aws_db_instance.main`   -> `module.db`
+ *   `module.net[0].aws_vpc.main`       -> `module.net`
+ *   `module.a.module.b.google_x.y[0]`  -> `module.a.module.b`
+ */
+export function moduleAddressOf(address: string): string {
+  const cleaned = address.replace(/\[[^\]]*\]/g, "");
+  const segments = cleaned.split(".");
+  // the resource is the final `type.name` pair; anything before is the module path.
+  return segments.length <= 2 ? "root" : segments.slice(0, segments.length - 2).join(".");
+}
+
+/**
+ * Score how much a fix touches, to route large changes through stricter review:
+ * 1–2 resources = `low`, 3–10 = `medium`, more than 10 OR spanning more than one
+ * module = `high`. A `high` blast radius should force human-in-the-loop
+ * regardless of finding severity (feeds §3.9). 0 changes is `low` (nothing to do).
+ */
+export function computeBlastRadius(changed: { address: string }[]): BlastRadius {
+  const resourceCount = changed.length;
+  const modules = [...new Set(changed.map((c) => moduleAddressOf(c.address)))].sort();
+  const crossModule = modules.length > 1;
+  let tier: BlastTier;
+  if (resourceCount > 10 || crossModule) tier = "high";
+  else if (resourceCount >= 3) tier = "medium";
+  else tier = "low";
+  return { tier, resourceCount, modules };
+}
+
+// --- plan stability / idempotency (§1.3) -----------------------------------
+
+export interface StabilityResult {
+  /** true when a second plan produced the identical change set. */
+  stable: boolean;
+  reason?: string;
+}
+
+/** a normalized signature of a plan's change set (summary counts + sorted
+ * address:action pairs) — two plans with the same signature are equivalent. */
+function planSignature(s: PlanSummary): string {
+  const set = s.changed
+    .map((c) => `${c.address}:${c.action}`)
+    .sort()
+    .join(",");
+  return `+${s.add}~${s.change}-${s.destroy}|${set}`;
+}
+
+/**
+ * Compare two consecutive plans for stability. Terramend never `apply`s (it only
+ * opens PRs), so a true "no perpetual diff after apply" cannot be proven here —
+ * but a fix whose plan is non-deterministic (e.g. `timestamp()`, `uuid()`, an
+ * unkeyed `random_*`, or a data source that varies run-to-run) yields a DIFFERENT
+ * plan on the second run, and that is a real perpetual-diff smell we can catch
+ * without applying. Stable ⇒ the two plans matched; unstable ⇒ report it.
+ */
+export function comparePlanStability(first: PlanSummary, second: PlanSummary): StabilityResult {
+  if (planSignature(first) === planSignature(second)) return { stable: true };
+  return {
+    stable: false,
+    reason:
+      `the plan is not deterministic — a second \`terraform plan\` (same state, no apply) produced a ` +
+      `different change set (first: +${first.add} ~${first.change} -${first.destroy}; ` +
+      `second: +${second.add} ~${second.change} -${second.destroy}). This is a perpetual-diff smell, ` +
+      `usually a non-deterministic value in the config (timestamp()/uuid()/unkeyed random_*/a varying data source).`,
+  };
+}
+
+// --- multi-root plan aggregation -------------------------------------------
+
+export interface RootPlan {
+  /** display label for the root ("." for the top-level root). */
+  dir: string;
+  summary: PlanSummary;
+  stable: boolean;
+}
+
+export interface AggregatedPlan {
+  add: number;
+  change: number;
+  destroy: number;
+  changed: { address: string; action: string }[];
+  destructive: { address: string; action: string }[];
+  hasDestroyOrReplace: boolean;
+  idempotent: boolean;
+  moved: { address: string; previousAddress: string | null }[];
+}
+
+/**
+ * Aggregate per-root plan results into one view: SUM the add/change/destroy
+ * counts, UNION the changed + destructive sets (so blast-radius and the
+ * destroy-block see every root's effect), and treat the whole run as
+ * non-idempotent if ANY root's plan was unstable. Pure. Single-root input passes
+ * straight through (identical to the pre-multi-root behaviour).
+ */
+export function aggregatePlans(roots: RootPlan[]): AggregatedPlan {
+  let add = 0;
+  let change = 0;
+  let destroy = 0;
+  let idempotent = true;
+  const changed: { address: string; action: string }[] = [];
+  const destructive: { address: string; action: string }[] = [];
+  const moved: { address: string; previousAddress: string | null }[] = [];
+  for (const r of roots) {
+    add += r.summary.add;
+    change += r.summary.change;
+    destroy += r.summary.destroy;
+    changed.push(...r.summary.changed);
+    destructive.push(...r.summary.destructive);
+    moved.push(...r.summary.moved);
+    if (!r.stable) idempotent = false;
+  }
+  return {
+    add,
+    change,
+    destroy,
+    changed,
+    destructive,
+    hasDestroyOrReplace: destructive.length > 0,
+    idempotent,
+    moved,
+  };
+}