infraweaver 0.1.0

package/src/mcp/terraform/planDrift.ts

@@ -0,0 +1,520 @@
+import { type } from "arktype";
+import { PRODUCT_NAME } from "#app/brand";
+import { isStatefulResourceType } from "#app/mcp/terraform/governance";
+import {
+  buildConcern,
+  type Concern,
+  type Severity,
+} from "#app/mcp/terraform/types";
+
+/**
+ * Detect infrastructure DRIFT from a `terraform show -json` plan artifact WITHOUT the
+ * engine ever holding a cloud credential. The customer's CI already runs
+ * `terraform plan` (that is where the creds live) and writes the plan out as JSON;
+ * Infraweaver reads that artifact and reports which resources have drifted from code.
+ * This is the sovereign, zero-credential companion to running `terraform_plan`
+ * against live state ourselves.
+ *
+ * Scope: a plan produced on a run whose CODE is unchanged (a scheduled / drift
+ * workflow) shows changes only because the live state diverged — that is drift.
+ * Each `resource_changes[]` entry with a mutating action is a drift item. Drift is
+ * DETECTION ONLY here: reconciling it is an `apply` or a code change a human owns.
+ *
+ * NB the parser: this reads the `terraform show -json` DOCUMENT form
+ * (`resource_changes[].change.actions[]`), NOT the `terraform plan -json` log stream
+ * (`plan.ts`). They are different shapes; a CI plan artifact is the document form.
+ * Pure: no filesystem, no network (the tool supplies the JSON + the resource index).
+ */
+
+// --- plan document schema ----------------------------------------------------
+
+const PlanResourceChange = type({
+  address: "string",
+  "type?": "string",
+  "name?": "string",
+  "mode?": "string",
+  change: type({
+    actions: "string[]",
+    // `before`/`after` are the attribute maps the provider-noise filter diffs.
+    // Optional and untyped by design: their shape is the resource's own schema,
+    // and an absent pair simply means the filter makes no claim (never filters).
+    "before?": "unknown",
+    "after?": "unknown",
+  }),
+});
+
+// Terraform 1.15's plan document lists provider-action invocations (the runtime
+// counterpart of the static `imperative-action-trigger` finding). Field names
+// follow hashicorp/terraform-json's ActionInvocation. Everything but the address
+// is optional — this parser reports what is present, never demands more.
+const PlanActionInvocation = type({
+  address: "string",
+  "type?": "string",
+  "name?": "string",
+  "provider_name?": "string",
+  "lifecycle_action_trigger?": type({
+    "triggering_resource_address?": "string",
+    "action_trigger_event?": "string",
+  }),
+});
+
+export const PlanDocument = type({
+  /** Terraform stamps the document form with a schema version. Absent on very
+   *  old artifacts, so it stays optional — we tolerate rather than demand. */
+  "format_version?": "string",
+  "resource_changes?": PlanResourceChange.array(),
+  /** provider actions this plan will invoke (TF 1.15+). Absent on older plans. */
+  "action_invocations?": PlanActionInvocation.array(),
+});
+
+// --- drift classification ----------------------------------------------------
+
+/** Actions that do not mutate live infrastructure (mirrors `plan.ts`, plus the
+ *  document-form `no-op` spelling). A change made up only of these is not drift.
+ *  `open`/`renew`/`close` are EPHEMERAL lifecycle ops (TF 1.10+): an ephemeral
+ *  value being (re)opened is session plumbing, not a resource being changed —
+ *  classifying one as CRUD would fabricate drift out of a secret handshake. */
+const NON_MUTATING: ReadonlySet<string> = new Set([
+  "no-op",
+  "noop",
+  "read",
+  "open",
+  "renew",
+  "close",
+]);
+
+export type DriftKind = "modified" | "deleted" | "recreated" | "replaced";
+
+export interface DriftItem {
+  address: string;
+  type: string | null;
+  name: string | null;
+  /** the raw plan actions, e.g. ["update"] or ["delete","create"]. */
+  actions: string[];
+  kind: DriftKind;
+  /** top-level attributes whose value differs between `change.before` and
+   *  `change.after` — the input the provider-noise filter judges. `null` when
+   *  the plan carries no diffable before/after pair (the filter then makes no
+   *  claim about this item and always keeps it). */
+  changed_fields: string[] | null;
+}
+
+/** Classify a resource change's actions into a drift kind, or null when the change
+ *  is non-mutating (no drift). */
+function classify(actions: string[]): DriftKind | null {
+  const acts = actions.filter((a) => !NON_MUTATING.has(a));
+  // A `forget` drops the resource from state while the cloud object survives:
+  // no live change, so it is not drift. It IS a coverage gap — see
+  // `detectForgotten`, which reports it separately rather than silently.
+  if (acts.includes("forget")) return null;
+  if (acts.length === 0) return null;
+  const set = new Set(acts);
+  if (set.has("create") && set.has("delete")) return "replaced";
+  if (set.has("delete")) return "deleted";
+  if (set.has("create")) return "recreated"; // live is missing the resource
+  if (set.has("update")) return "modified";
+  return null;
+}
+
+/**
+ * The plan-JSON document schema versions this parser understands. Terraform has
+ * only ever shipped 1.x for the `show -json` document form and adds keys within
+ * it additively, so any 1.x parses; a 2.x would be a redesign we have not read.
+ *
+ * Forward-compatibility is the DEFAULT here: an unknown 1.x minor (or an absent
+ * version on an old artifact) parses normally, because arktype ignores keys we
+ * do not declare. Only a MAJOR bump is called out — and even then as an honest
+ * coverage gap for the caller to surface, never a silent mis-parse.
+ */
+export const SUPPORTED_PLAN_FORMAT_MAJOR = 1;
+
+/** True when a plan document's `format_version` is one this parser understands.
+ *  An absent version is accepted (pre-versioning artifacts). Pure. */
+export function isSupportedPlanFormat(
+  formatVersion: string | undefined,
+): boolean {
+  if (!formatVersion) return true;
+  const major = Number.parseInt(formatVersion.split(".")[0] ?? "", 10);
+  return Number.isFinite(major) && major === SUPPORTED_PLAN_FORMAT_MAJOR;
+}
+
+/** The resource TYPE for a plan entry: the declared `type` when present, else
+ *  parsed from the address (`module.a.aws_db_instance.b` → `aws_db_instance`).
+ *  Null when neither yields one. Pure. */
+function resourceTypeOf(rc: {
+  address: string;
+  type?: string | undefined;
+}): string | null {
+  if (rc.type) return rc.type;
+  const segments = rc.address.split(".");
+  return segments.length >= 2 ? (segments[segments.length - 2] ?? null) : null;
+}
+
+export interface ForgottenResource {
+  address: string;
+  type: string | null;
+  /** true when the type is data-bearing ([[governance]] `isStatefulResourceType`)
+   *  — forgetting a database is the case that must route through needs-human:
+   *  after it, the data-bearing object exists with NO destroy protection and no
+   *  drift visibility, and nothing in code says so. */
+  stateful: boolean;
+}
+
+/**
+ * Resources the plan would FORGET — dropped from state while the real cloud
+ * object keeps existing (Terraform `removed` blocks, OpenTofu `destroy = false`).
+ *
+ * A forget is deliberately NOT drift and NOT a destroy: nothing in the cloud
+ * changes, so reporting it as either would be a false positive. But it is not a
+ * non-event either — after a forget the resource is unmanaged, and every later
+ * drift scan is silently blind to it. Surfaced separately so the run can state
+ * the coverage gap instead of quietly shrinking what 'no drift' covers. Pure.
+ */
+export function classifyForgotten(
+  doc: typeof PlanDocument.infer,
+): ForgottenResource[] {
+  const forgotten: ForgottenResource[] = [];
+  for (const rc of doc.resource_changes ?? []) {
+    if (!rc.change.actions.includes("forget")) continue;
+    const resourceType = resourceTypeOf(rc);
+    forgotten.push({
+      address: rc.address,
+      type: resourceType,
+      stateful: resourceType !== null && isStatefulResourceType(resourceType),
+    });
+  }
+  return forgotten;
+}
+
+/** The forgotten addresses only — the compact form of {@link classifyForgotten}. */
+export function detectForgotten(doc: typeof PlanDocument.infer): string[] {
+  return classifyForgotten(doc).map((f) => f.address);
+}
+
+/** Structural equality on plan attribute values (JSON-shaped data only). */
+function sameValue(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (
+    typeof a !== "object" ||
+    typeof b !== "object" ||
+    a === null ||
+    b === null
+  )
+    return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => sameValue(v, b[i]));
+  }
+  const ka = Object.keys(a).sort();
+  const kb = Object.keys(b).sort();
+  if (ka.length !== kb.length || ka.some((k, i) => k !== kb[i])) return false;
+  return ka.every((k) =>
+    sameValue(
+      (a as Record<string, unknown>)[k],
+      (b as Record<string, unknown>)[k],
+    ),
+  );
+}
+
+/** Top-level attribute names whose value differs between `before` and `after`,
+ *  or null when the pair isn't two plain objects (nothing diffable). Pure. */
+function changedFields(before: unknown, after: unknown): string[] | null {
+  const isPlain = (v: unknown): v is Record<string, unknown> =>
+    typeof v === "object" && v !== null && !Array.isArray(v);
+  if (!isPlain(before) || !isPlain(after)) return null;
+  const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+  return [...keys].filter((k) => !sameValue(before[k], after[k])).sort();
+}
+
+/** Every drifted resource in a plan document. A clean plan yields `[]`. */
+export function detectDrift(doc: typeof PlanDocument.infer): DriftItem[] {
+  const items: DriftItem[] = [];
+  for (const rc of doc.resource_changes ?? []) {
+    const kind = classify(rc.change.actions);
+    if (!kind) continue;
+    items.push({
+      address: rc.address,
+      type: resourceTypeOf(rc),
+      name: rc.name ?? null,
+      actions: rc.change.actions,
+      kind,
+      changed_fields: changedFields(rc.change.before, rc.change.after),
+    });
+  }
+  return items;
+}
+
+// --- provider-noise filter ---------------------------------------------------
+
+/**
+ * Computed fields whose churn is PROVIDER bookkeeping, not an operator touching
+ * infrastructure — the documented, always-computed merge targets that generate
+ * perpetual "drift" whenever provider-level defaults shift:
+ *
+ *   - aws `tags_all`: the computed merge of `default_tags` into every resource's
+ *     tags (the canonical drift-noise field of the AWS provider).
+ *   - google `effective_labels` / `terraform_labels`: computed label merges
+ *     introduced by provider v5's default-labels model.
+ *
+ * The list is deliberately SHORT and only ever names fields a provider computes
+ * — a field an operator can hand-edit in the console never belongs here, because
+ * filtering it would be exactly the false no-drift the roadmap forbids.
+ */
+export const PROVIDER_NOISE_FIELDS: Readonly<
+  Record<string, readonly string[]>
+> = {
+  aws: ["tags_all"],
+  google: ["effective_labels", "terraform_labels"],
+};
+
+/** A drift item excluded by the noise filter — retained for auditability, so the
+ *  run can show WHAT was filtered and by which fields rather than silently
+ *  shrinking the drift set. */
+export interface NoiseFilteredDrift {
+  address: string;
+  kind: DriftKind;
+  /** the noisy fields that were the entire diff. */
+  fields: string[];
+}
+
+/**
+ * Split drift into signal and provider noise. An item is noise ONLY when every
+ * condition holds: it is a pure in-place update (`modified`), the plan carried a
+ * diffable before/after pair, at least one field changed, and EVERY changed
+ * field is on the noise list (the per-provider defaults plus any operator-
+ * supplied extras). Anything else — a delete, a replace, an undiffable change,
+ * a mixed diff where one field is real — is kept. The bias is deliberate:
+ * "never a false no-drift" means the filter must prove noise, not assume it.
+ */
+export function filterProviderNoise(
+  items: ReadonlyArray<DriftItem>,
+  extraNoiseFields: readonly string[] = [],
+): { kept: DriftItem[]; filtered: NoiseFilteredDrift[] } {
+  const kept: DriftItem[] = [];
+  const filtered: NoiseFilteredDrift[] = [];
+  for (const item of items) {
+    const provider = item.type?.split("_")[0] ?? "";
+    const noise = new Set([
+      ...(PROVIDER_NOISE_FIELDS[provider] ?? []),
+      ...extraNoiseFields,
+    ]);
+    const noiseOnly =
+      item.kind === "modified" &&
+      item.changed_fields !== null &&
+      item.changed_fields.length > 0 &&
+      item.changed_fields.every((f) => noise.has(f));
+    if (noiseOnly && item.changed_fields) {
+      filtered.push({
+        address: item.address,
+        kind: item.kind,
+        fields: item.changed_fields,
+      });
+    } else {
+      kept.push(item);
+    }
+  }
+  return { kept, filtered };
+}
+
+// --- action invocations (the runtime counterpart of imperative-action-trigger) --
+
+export interface ActionInvocationItem {
+  /** absolute action address, `action.<type>.<name>`. */
+  address: string;
+  action_type: string | null;
+  /** the resource whose lifecycle event fires this action, when the plan says. */
+  triggered_by: string | null;
+  /** the lifecycle event (`after_create`, …), when the plan says. */
+  event: string | null;
+}
+
+/**
+ * The provider actions this plan will invoke (TF 1.15's `action_invocations`).
+ * This is the RUNTIME counterpart of the static `imperative-action-trigger`
+ * finding ([[governance]]): the static rule says "an apply here can do work
+ * outside the resource graph"; this array is the plan saying "THIS apply will".
+ * Pure summarization — correlation to code happens in the tool, where the
+ * repo's HCL is available.
+ */
+export function summarizeActionInvocations(
+  doc: typeof PlanDocument.infer,
+): ActionInvocationItem[] {
+  return (doc.action_invocations ?? []).map((inv) => ({
+    address: inv.address,
+    action_type: inv.type ?? null,
+    triggered_by:
+      inv.lifecycle_action_trigger?.triggering_resource_address ?? null,
+    event: inv.lifecycle_action_trigger?.action_trigger_event ?? null,
+  }));
+}
+
+// --- drift → signed evidence -------------------------------------------------
+
+/**
+ * The drift statement the evidence bundle carries — the 2.1 differentiator:
+ * *signed, verifiable proof that live cloud matched the committed IaC at the
+ * time the plan artifact was produced*, with every bound on that claim stated
+ * in the artifact itself rather than left to the reader's optimism.
+ */
+export interface DriftEvidenceStatement {
+  /** the plan artifact the claim is derived from. */
+  source_file: string;
+  /** drifted resources AFTER noise filtering — the signal set. */
+  detected: number;
+  by_kind: Record<DriftKind, number>;
+  items: { address: string; kind: DriftKind }[];
+  /** drift excluded as provider bookkeeping — listed field-by-field so the
+   *  filtering is auditable (the unfiltered diff stays in the plan artifact). */
+  noise_filtered: NoiseFilteredDrift[];
+  /** resources this plan drops from management — the standing blind spot every
+   *  later drift claim inherits, so it must ride the signed statement. */
+  forgotten: ForgottenResource[];
+  /** drifted addresses with no matching resource block in code. */
+  unlocated: number;
+  /** honest bounds: unsupported format major, etc. Empty = fully readable. */
+  coverage_gaps: string[];
+  asserts: string;
+  does_not_assert: string;
+}
+
+/**
+ * Build the drift evidence statement (pure). The asserts line is graded by what
+ * the inputs actually prove: a clean, fully-readable plan asserts the live-
+ * matches-code claim; drift asserts the detection; a coverage gap asserts
+ * nothing confident. INCONCLUSIVE-over-silence, in the signed artifact itself.
+ */
+export function buildDriftStatement(args: {
+  sourceFile: string;
+  kept: ReadonlyArray<DriftItem>;
+  filtered: ReadonlyArray<NoiseFilteredDrift>;
+  forgotten: ReadonlyArray<ForgottenResource>;
+  unlocated: number;
+  coverageGaps?: readonly string[];
+}): DriftEvidenceStatement {
+  const { sourceFile, kept, filtered, forgotten, unlocated } = args;
+  const coverage_gaps = [...(args.coverageGaps ?? [])];
+  const by_kind: Record<DriftKind, number> = {
+    modified: 0,
+    deleted: 0,
+    recreated: 0,
+    replaced: 0,
+  };
+  for (const item of kept) by_kind[item.kind]++;
+
+  let asserts: string;
+  if (coverage_gaps.length > 0) {
+    asserts =
+      "nothing confident — the plan artifact could not be fully read (see coverage_gaps); " +
+      "treat this statement as INCONCLUSIVE, never as 'no drift'.";
+  } else if (kept.length === 0) {
+    asserts =
+      "at the time the plan artifact was produced, every resource under Terraform management " +
+      "matched the committed configuration (no mutating change was planned).";
+  } else {
+    asserts =
+      `${kept.length} resource(s) had drifted from the committed configuration when the plan ` +
+      "artifact was produced (each listed with the reconciling action kind).";
+  }
+
+  const forgottenNote = forgotten.length
+    ? ` ${forgotten.length} resource(s) are being dropped from management (\`forgotten\`) and are not observable by any later drift scan.`
+    : "";
+  const filteredNote = filtered.length
+    ? ` ${filtered.length} change(s) were excluded as provider-computed noise (listed field-by-field in \`noise_filtered\`; the unfiltered diff remains in the plan artifact).`
+    : "";
+  return {
+    source_file: sourceFile,
+    detected: kept.length,
+    by_kind,
+    items: kept.map((i) => ({ address: i.address, kind: i.kind })),
+    noise_filtered: [...filtered],
+    forgotten: [...forgotten],
+    unlocated,
+    coverage_gaps,
+    asserts,
+    does_not_assert:
+      "anything about resources outside Terraform management, or about changes made after " +
+      `the plan artifact was produced.${forgottenNote}${filteredNote}`,
+  };
+}
+
+// --- drift → concerns --------------------------------------------------------
+
+const DRIFT_SEVERITY: Record<DriftKind, Severity> = {
+  // Losing/replacing a live resource to reconcile risks data loss — the loud cases.
+  deleted: "high",
+  replaced: "high",
+  recreated: "medium",
+  modified: "medium",
+};
+
+const DRIFT_EVIDENCE: Record<DriftKind, string> = {
+  modified:
+    "configuration has drifted from code (a plan would update it to reconcile)",
+  deleted:
+    "the resource no longer exists in live infrastructure (a plan would recreate it)",
+  recreated:
+    "the resource is missing from live infrastructure and would be created",
+  replaced:
+    "live state has drifted such that a plan would destroy and recreate it",
+};
+
+/** Resolve a Terraform address to its source location, or null when the address
+ *  isn't found in the repo's code (e.g. a resource removed from code but still in
+ *  state). Supplied by the tool from a `.tf` resource index. */
+export type LocationResolver = (
+  address: string,
+) => { file: string; line: number } | null;
+
+/** A drift item that couldn't be tied to a resource block in code (reported, not dropped). */
+export interface UnlocatedDrift {
+  address: string;
+  kind: DriftKind;
+  reason: string;
+}
+
+export interface DriftConcerns {
+  concerns: Concern[];
+  unlocated: UnlocatedDrift[];
+}
+
+/**
+ * Turn drift items into `reviewer`-source concerns at each resource's file:line.
+ * Drift is honestly `not-code-verifiable` by the ✗→✓ re-scan (proving it fixed needs
+ * live cloud access, which Infraweaver refuses) — the `reviewer` source carries exactly
+ * that meaning. Items whose address isn't in code are returned under `unlocated`.
+ */
+export function driftToConcerns(
+  items: ReadonlyArray<DriftItem>,
+  resolve: LocationResolver,
+): DriftConcerns {
+  const concerns: Concern[] = [];
+  const unlocated: UnlocatedDrift[] = [];
+  for (const item of items) {
+    const loc = resolve(item.address);
+    if (!loc) {
+      unlocated.push({
+        address: item.address,
+        kind: item.kind,
+        reason: "no resource block in the repo matched this drifted address",
+      });
+      continue;
+    }
+    concerns.push(
+      buildConcern({
+        source: "reviewer",
+        // A stable, address-scoped rule token so the same drifted resource keeps its id.
+        rule: `drift-${item.kind}-${item.address}`,
+        file: loc.file,
+        line: loc.line,
+        severity: DRIFT_SEVERITY[item.kind],
+        category: "correctness",
+        evidence: `${item.address}: ${DRIFT_EVIDENCE[item.kind]}`,
+        remediation_hint:
+          "Reconcile the drift (an apply, or reverse the out-of-band change) or update the code to " +
+          `match intent — a human decision; ${PRODUCT_NAME} never applies.`,
+      }),
+    );
+  }
+  return { concerns, unlocated };
+}