infraweaver 0.1.0

package/src/mcp/terraform/transformPacks.ts

@@ -0,0 +1,594 @@
+/**
+ * Versioned provider-upgrade transform packs (TC-2.2).
+ *
+ * WHAT A PACK IS — AND, MORE IMPORTANTLY, WHAT IT IS NOT. A pack is *codified
+ * knowledge* about one provider major-version boundary: which resource types
+ * disappeared, which arguments were renamed, and — the part that actually
+ * matters — which of those changes cannot be made without moving state. It is
+ * modelled on `fix_memory` deliberately (same shape: identity, match, merge,
+ * coerce, fleet stats): a pack entry is a **PRIOR, never a patch**. Nothing here
+ * rewrites HCL. The agent edits, `terraform plan` proves, and the existing
+ * destroy/replace guardrail blocks.
+ *
+ * WHY NOT A CODEMOD. A rewriter that silently renamed `enable_x` to `x_enabled`
+ * across a repo would be the single most dangerous thing in this codebase: a
+ * wrong rename that still parses produces a plan that destroys and recreates
+ * live infrastructure, and the failure surfaces in production, not in CI. The
+ * whole product thesis is proof over assertion, so the upgrade path is: detect
+ * deterministically → hand the agent leads → make it prove the plan → route
+ * anything state-moving to a human.
+ *
+ * ⚠️ THE SELF-TEST IS THE LOAD-BEARING PART. A hand-written migration table goes
+ * stale, and a stale entry is worse than no entry. So a rename entry is checked
+ * against the **installed provider schema** before it is offered
+ * (`verifyEntry`): a pack claiming `a → b` is believed only when the schema
+ * agrees that exactly one of the two exists. That is the same discipline §5.2
+ * applies to generated rules — a rule that can never fire is refused rather
+ * than shipped.
+ *
+ * What the self-test does NOT cover, stated rather than implied: a whole-resource
+ * rename (asking the schema about a type that v4 removed cannot distinguish
+ * "removed" from "provider not installed"), a pure deletion (absence of the old
+ * name is equally consistent with a misattributed entry), and `argument_required`
+ * (a schema says what exists, not what is mandatory). Those come back
+ * `unverified`, which is reported honestly and — the part that matters —
+ * **excluded from fleet capture**, so doubt is never laundered into a proven
+ * counter. It still reaches the agent as a lead, because a lead it can check is
+ * more use than silence.
+ *
+ * PACKS ARE NOT EXHAUSTIVE AND SAY SO. `terraform_validate`'s `unknown_arguments`
+ * (checked against the installed schema, not a table) remains the authoritative
+ * answer to "what did I miss". A pack's job is to say what to replace a thing
+ * WITH — the direction `unknown_arguments` can't give you.
+ */
+import { AZURERM_3_TO_4 } from "#app/mcp/terraform/packs/azurerm-3-4";
+import { CLOUDFLARE_4_TO_5 } from "#app/mcp/terraform/packs/cloudflare-4-5";
+import { STATEFUL_RESOURCE_TYPES } from "#app/mcp/terraform/plan";
+import type {
+  LocatedResource,
+  ProviderRequirement,
+} from "#app/mcp/terraform/scanners";
+
+/** Bumped when the pack SHAPE changes (not when an individual pack's content
+ *  does — each pack carries its own `version`). Mirrors `FixMemoryFile.version`. */
+export const TRANSFORM_PACK_SCHEMA = "infraweaver-transform-pack/v1" as const;
+
+/**
+ * The built-in packs.
+ *
+ * Built in rather than fetched: a migration table pulled at runtime is a remote
+ * input that decides how live infrastructure gets edited, which is the last
+ * thing that should be mutable outside a reviewed release. Adding a pack is a
+ * code change with a diff, a review and a version — exactly like the crosswalk.
+ *
+ * These ship to everyone, OSS included, with no input to enable. The only
+ * Cloud-gated part of TC-2.2 is the fleet-wide *proven* counters.
+ */
+export const BUILTIN_TRANSFORM_PACKS: readonly TransformPack[] = [
+  AZURERM_3_TO_4,
+  CLOUDFLARE_4_TO_5,
+];
+
+/**
+ * How a transform's state has to move.
+ *
+ * This is the field the whole feature turns on, because it — not the size of the
+ * diff — decides whether a human must look. `auto` is a pure config edit that
+ * `plan` should show as a no-op. `moved_block` needs a `moved {}` block authored
+ * (Terraform ≥ 1.8) but keeps the resource. `manual_import` means the state
+ * entry cannot be carried across: without `state rm` + `import`, applying the
+ * change DESTROYS and RECREATES the resource.
+ */
+export type StateMove = "auto" | "moved_block" | "manual_import";
+
+export type TransformKind =
+  | "resource_renamed"
+  | "resource_removed"
+  | "argument_renamed"
+  | "argument_removed"
+  | "argument_required"
+  | "provider_setting";
+
+/** One codified breaking change. */
+export interface TransformEntry {
+  /** stable id, `<provider>.<from>-<to>.<slug>` — the fleet-sharing match key. */
+  id: string;
+  kind: TransformKind;
+  /** the resource type the change applies to; `null` for provider-block changes. */
+  resource_type: string | null;
+  /** what the config says today (old resource type, old argument name). */
+  from: string;
+  /** what it becomes; `null` when the thing was removed with no replacement. */
+  to: string | null;
+  state_move: StateMove;
+  /** true when applying this change is expected to force replacement even after
+   *  the config edit — the pre-plan signal that a human will be needed. */
+  forces_replacement: boolean;
+  /**
+   * Set when the VALUE must change too, not just the identifier.
+   *
+   * This exists because the most dangerous entry in any migration table is the
+   * one that looks like a pure rename and isn't: `disable_bgp_route_propagation`
+   * → `bgp_route_propagation_enabled` inverts the boolean, and a mechanical
+   * rename would silently flip the routing behaviour of a live network while
+   * `validate`, `plan` and every scanner stayed green. When this is set, the
+   * transform is never presented as a rename.
+   */
+  value_change?: string;
+  /** one line the agent can act on. */
+  note: string;
+}
+
+export interface TransformPack {
+  /** registry provider name, e.g. `azurerm`. */
+  provider: string;
+  from_major: number;
+  to_major: number;
+  /** pack content version — bump when entries change. */
+  version: string;
+  /** the upstream guide these entries were transcribed from. Every claim in this
+   *  file is someone else's documented breaking change, so it gets a citation. */
+  source: string;
+  /** ALWAYS false in practice, and stated rather than implied: no pack here is a
+   *  complete migration. `unknown_arguments` is the exhaustive check. */
+  exhaustive: boolean;
+  /** upstream's own migration tool, when one exists. Preferring it over our own
+   *  leads is "integrate upward, don't compete" applied to migrations. */
+  official_tool?: string;
+  entries: TransformEntry[];
+}
+
+/**
+ * Whether the installed provider schema CORROBORATES a pack entry.
+ *
+ * - `pre-upgrade`  — schema has `from`, not `to`. Consistent with the old major
+ *                    still being installed; the entry is a valid lead.
+ * - `post-upgrade` — schema has `to`, not `from`. The new major is installed, so
+ *                    any remaining use of `from` is a confirmed must-fix.
+ * - `unverified`   — schema has both, neither, or wasn't loadable. The pack is
+ *                    not believed; the entry is reported but never actionable.
+ */
+export type SchemaAgreement = "pre-upgrade" | "post-upgrade" | "unverified";
+
+/**
+ * How sure we are that this entry applies to a specific piece of the config.
+ *
+ * `absent` exists because one entry kind — `argument_required` — fires on the
+ * argument NOT being there. Reporting that as `confirmed` (which is documented
+ * as "the identifier was found") would tell the reader the exact opposite of
+ * what happened.
+ */
+export type MatchConfidence = "confirmed" | "nested" | "absent";
+
+export interface TransformMatch {
+  entry: TransformEntry;
+  /** the pack that produced it. Carried per-match rather than read from the
+   *  run's primary pack, because a repo can be mid-upgrade on two providers and
+   *  the fleet row's provider/major columns must describe the right one. */
+  provider: string;
+  from_major: number;
+  to_major: number;
+  /** where it was found. */
+  file: string;
+  /** the resource block's local name (`""` for provider-block matches). */
+  resource_name: string;
+  /**
+   * `confirmed` — the exact top-level identifier was found in the parsed config.
+   * `nested`    — the entry names a path inside a block (`a.b.c`) and the parser
+   *               only sees top-level argument names, so the resource TYPE
+   *               matched but the argument itself was not confirmed. Reported as
+   *               a lead to check by hand, never as a certainty.
+   */
+  confidence: MatchConfidence;
+  schema_agreement: SchemaAgreement;
+  /** true when this match must not be applied autonomously. */
+  needs_human: boolean;
+  /** why, when it does. */
+  needs_human_reason: string | null;
+}
+
+/** A pack entry is nested when it names a path inside a block. */
+function isNestedPath(arg: string): boolean {
+  return arg.includes(".");
+}
+
+/** The leaf identifier of a possibly-dotted path. */
+function leafOf(path: string): string {
+  const parts = path.split(".");
+  return parts[parts.length - 1] ?? path;
+}
+
+/**
+ * Does this transform need a human?
+ *
+ * Two independent triggers, both deliberately conservative:
+ *  1. `manual_import` — the state cannot be carried across automatically, so an
+ *     unattended apply destroys and recreates. Always human, every resource type.
+ *  2. `forces_replacement` on a STATEFUL resource type. Stateful-ness is read
+ *     from `plan.ts`'s `STATEFUL_RESOURCE_TYPES` — the exact set the push-time
+ *     `assertNoBlockedDestroy` guardrail uses — and NOT from `governance.ts`'s
+ *     regex heuristic, because the point of pre-declaring this is to predict
+ *     what the guard will actually block. Predicting it with a different
+ *     definition than the guard uses would be worse than not predicting it.
+ */
+export function transformNeedsHuman(entry: TransformEntry): {
+  needs: boolean;
+  reason: string | null;
+} {
+  if (entry.state_move === "manual_import") {
+    return {
+      needs: true,
+      reason:
+        "state cannot be moved automatically — without `terraform state rm` + `import` this destroys and recreates the resource",
+    };
+  }
+  if (entry.forces_replacement) {
+    const type = entry.resource_type ?? "";
+    if (STATEFUL_RESOURCE_TYPES.has(type)) {
+      return {
+        needs: true,
+        reason: `forces replacement of ${type}, which holds data — the push guardrail blocks this unless explicitly allowed`,
+      };
+    }
+    return {
+      needs: true,
+      reason: "forces resource replacement — confirm the plan before shipping",
+    };
+  }
+  return { needs: false, reason: null };
+}
+
+/** Schema lookup seam. Returns the argument names known for a resource type, or
+ *  `null` when the schema could not be loaded / the type is unknown to it. */
+export type SchemaLookup = (resourceType: string) => ReadonlySet<string> | null;
+
+/**
+ * Check one entry against the installed provider schema.
+ *
+ * Only argument-level entries are checkable this way — a removed RESOURCE type
+ * cannot be corroborated by asking the schema about it (its absence is equally
+ * consistent with "removed in v4" and "this provider isn't installed"), so those
+ * return `unverified` and lean on the deterministic type match instead.
+ */
+export function verifyEntry(
+  entry: TransformEntry,
+  lookup: SchemaLookup,
+): SchemaAgreement {
+  if (entry.kind !== "argument_renamed" && entry.kind !== "argument_removed")
+    return "unverified";
+  if (!entry.resource_type) return "unverified";
+  const known = lookup(entry.resource_type);
+  if (!known) return "unverified";
+  const hasFrom = known.has(leafOf(entry.from));
+  // A pure deletion has no replacement name to look for, so the ONLY signal is
+  // the old name's absence — which is equally consistent with "v4 is installed"
+  // and "this entry names the wrong argument". Treating absence as
+  // `post-upgrade` made the verdict unfalsifiable and, worse, made a
+  // misattributed entry read as MORE confirmed, not less. Deletions therefore
+  // corroborate in one direction only.
+  if (entry.to === null) return hasFrom ? "pre-upgrade" : "unverified";
+  const hasTo = known.has(leafOf(entry.to));
+  if (hasFrom && !hasTo) return "pre-upgrade";
+  if (!hasFrom && hasTo) return "post-upgrade";
+  return "unverified";
+}
+
+/**
+ * Select the packs that apply to what this repo actually pins.
+ *
+ * A pack applies when the provider is required AND the pinned lower-bound major
+ * equals the pack's `from_major`. An unconstrained provider (`major: null`)
+ * matches nothing: guessing which major an unpinned provider resolves to is how
+ * you hand someone a migration they don't need.
+ */
+export function packsForRequirements(
+  packs: readonly TransformPack[],
+  requirements: readonly ProviderRequirement[],
+): TransformPack[] {
+  const pinned = new Map<string, number>();
+  for (const r of requirements) {
+    if (r.major !== null && !pinned.has(r.name)) pinned.set(r.name, r.major);
+  }
+  return packs.filter((p) => pinned.get(p.provider) === p.from_major);
+}
+
+/**
+ * Match a pack's entries against the parsed configuration. Pure.
+ *
+ * `resources` comes from `parseResourceArguments`, which reports TOP-LEVEL
+ * argument names only. That bound is honoured rather than papered over: a
+ * dotted entry produces a `nested` match (resource type present, argument not
+ * confirmed) so the agent knows to look inside the block itself.
+ */
+export function matchTransforms(
+  pack: TransformPack,
+  resources: readonly LocatedResource[],
+  lookup: SchemaLookup,
+): TransformMatch[] {
+  const matches: TransformMatch[] = [];
+  for (const entry of pack.entries) {
+    const agreement = verifyEntry(entry, lookup);
+    const { needs, reason } = transformNeedsHuman(entry);
+    const base = {
+      entry,
+      provider: pack.provider,
+      from_major: pack.from_major,
+      to_major: pack.to_major,
+      schema_agreement: agreement,
+      needs_human: needs,
+      needs_human_reason: reason,
+    };
+
+    if (
+      entry.kind === "resource_renamed" ||
+      entry.kind === "resource_removed"
+    ) {
+      for (const r of resources) {
+        if (r.resourceType !== entry.from) continue;
+        matches.push({
+          ...base,
+          file: r.file,
+          resource_name: r.name,
+          confidence: "confirmed",
+        });
+      }
+      continue;
+    }
+    if (entry.kind === "provider_setting") {
+      // Provider-block settings aren't resources; they are reported once, without
+      // a location, because `parseResourceArguments` doesn't see provider blocks.
+      matches.push({
+        ...base,
+        file: "",
+        resource_name: "",
+        confidence: "nested",
+      });
+      continue;
+    }
+    // argument-level
+    for (const r of resources) {
+      if (r.resourceType !== entry.resource_type) continue;
+      if (isNestedPath(entry.from)) {
+        matches.push({
+          ...base,
+          file: r.file,
+          resource_name: r.name,
+          confidence: "nested",
+        });
+        continue;
+      }
+      // `argument_required` is the one entry kind whose trigger is ABSENCE: the
+      // argument became mandatory, so the resources that need work are the ones
+      // NOT carrying it. Matching on presence here (as every other kind does)
+      // would report exactly the resources that are already correct.
+      const present = r.args.includes(entry.from);
+      const requiredAndMissing = entry.kind === "argument_required" && !present;
+      if (requiredAndMissing) {
+        matches.push({
+          ...base,
+          file: r.file,
+          resource_name: r.name,
+          confidence: "absent",
+        });
+      } else if (present && entry.kind !== "argument_required") {
+        matches.push({
+          ...base,
+          file: r.file,
+          resource_name: r.name,
+          confidence: "confirmed",
+        });
+      }
+    }
+  }
+  return matches;
+}
+
+/**
+ * Fleet reuse stats for a transform id — the §5.12-shaped half.
+ *
+ * Notice what is NOT here: no config, no snippet, no repo name. A transform is
+ * already fully described by the pack every engine ships; the only thing worth
+ * sharing across an org is *whether it has been proven to plan cleanly, and how
+ * widely*. That keeps the fleet payload a set of counters, so there is no path
+ * by which one repo's configuration reaches another.
+ */
+export interface ProvenTransform {
+  /** matches `TransformEntry.id`. */
+  transform_id: string;
+  provider: string;
+  from_major: number;
+  to_major: number;
+  /** how many times this transform's upgrade planned cleanly. */
+  times_proven?: number;
+  /** distinct repos it has been proven on. */
+  repos_count?: number;
+  last_proven?: string;
+  /** operator retired it in the dashboard — never offered as proven. */
+  disabled?: boolean;
+}
+
+export function isProvenTransform(value: unknown): value is ProvenTransform {
+  if (!value || typeof value !== "object") return false;
+  const p = value as Record<string, unknown>;
+  return (
+    typeof p.transform_id === "string" &&
+    p.transform_id.length > 0 &&
+    typeof p.provider === "string" &&
+    typeof p.from_major === "number" &&
+    typeof p.to_major === "number"
+  );
+}
+
+/** Coerce the untrusted Cloud `provenTransforms` blob. Pure — the wire boundary
+ *  can't be typechecked across repos (same reasoning as `coerceLibrary`). */
+export function coerceProvenTransforms(raw: unknown): ProvenTransform[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(isProvenTransform).filter((p) => !p.disabled);
+}
+
+/**
+ * What `terraform_provider_upgrade` detected this run, parked on the session so
+ * the evidence builder can bind it to the plan that came after.
+ */
+export interface UpgradeIntent {
+  provider: string;
+  from_major: number;
+  to_major: number;
+  pack_version: string;
+  pack_source: string;
+  pack_exhaustive: boolean;
+  /** ids of every transform matched in this config, deduped, sorted. */
+  transform_ids: string[];
+  /** how many of those must not be applied autonomously. */
+  needing_human: number;
+}
+
+/** The plan facts the proof rests on. Supplied by the caller from the session so
+ *  this stays pure and testable. */
+export interface UpgradePlanFacts {
+  to_add: number;
+  to_change: number;
+  to_destroy: number;
+  /** count of destroy/replace actions across all roots. */
+  destructive: number;
+  /** count of those that hit a data-bearing resource type. */
+  stateful_destructive: number;
+  /** false when a second plan disagreed with the first. */
+  idempotent: boolean;
+}
+
+/**
+ * The signed-evidence statement for a provider upgrade (TC-2.2's "carrying the
+ * passing plan as proof").
+ *
+ * The verdict is computed from the plan, never asserted by the agent, and — per
+ * §8 — the statement carries what it does NOT claim. A clean plan proves that
+ * Terraform intends no destructive change to the resources it can see. It does
+ * not prove the upgrade is behaviourally correct, and it says so.
+ */
+export interface UpgradeEvidenceStatement {
+  provider: string;
+  from_major: number;
+  to_major: number;
+  pack_version: string;
+  pack_source: string;
+  /** always false, carried into the signed bytes so a reader cannot mistake the
+   *  transform list for a complete migration. */
+  pack_exhaustive: boolean;
+  verdict: "plan-proven" | "plan-unclean" | "no-plan";
+  transforms_detected: number;
+  transforms_needing_human: number;
+  transform_ids: string[];
+  plan?: UpgradePlanFacts | undefined;
+  asserts: string;
+  does_not_assert: string;
+}
+
+const UPGRADE_DOES_NOT_ASSERT =
+  "Does NOT assert that the upgraded configuration is behaviourally equivalent to the previous " +
+  "major, that the transform list was complete, or that unlisted breaking changes were handled. " +
+  "A plan reflects only what Terraform can see from the configuration and state it was given.";
+
+/**
+ * Build the upgrade statement. Pure. `facts` is undefined when no plan ran —
+ * which is itself recorded as a verdict rather than omitted, because an upgrade
+ * shipped without a plan is precisely the case a reader must be able to spot.
+ */
+export function buildUpgradeStatement(
+  intent: UpgradeIntent | undefined,
+  facts: UpgradePlanFacts | undefined,
+): UpgradeEvidenceStatement | undefined {
+  if (!intent) return undefined;
+  // ⚠️ `destructive`, not just `stateful_destructive`. A migration's entire
+  // premise is that state survives it, so ANY destroy/replace refutes it —
+  // including on resource types `STATEFUL_RESOURCE_TYPES` has never heard of.
+  // The first cut gated on stateful-ness alone, which meant 200 renamed
+  // `cloudflare_record`s missing their `moved {}` blocks planned as 200
+  // destroy+create, agreed with themselves across both runs, and signed as
+  // `plan-proven` — a clean bill of health for a plan that erases a DNS zone.
+  const verdict: UpgradeEvidenceStatement["verdict"] = !facts
+    ? "no-plan"
+    : facts.destructive === 0 &&
+        facts.to_destroy === 0 &&
+        facts.stateful_destructive === 0 &&
+        facts.idempotent
+      ? "plan-proven"
+      : "plan-unclean";
+  const asserts =
+    verdict === "plan-proven"
+      ? `A \`terraform plan\` after the ${intent.provider} v${intent.from_major}→v${intent.to_major} upgrade was stable across two runs and destroys or replaces NOTHING.`
+      : verdict === "plan-unclean"
+        ? `A \`terraform plan\` ran after the ${intent.provider} v${intent.from_major}→v${intent.to_major} upgrade and was NOT clean — it is recorded here as evidence, not as a pass.`
+        : `The ${intent.provider} v${intent.from_major}→v${intent.to_major} transforms below were detected in the configuration. NO plan backs this run, so nothing is proven about runtime behaviour.`;
+  return {
+    provider: intent.provider,
+    from_major: intent.from_major,
+    to_major: intent.to_major,
+    pack_version: intent.pack_version,
+    pack_source: intent.pack_source,
+    pack_exhaustive: intent.pack_exhaustive,
+    verdict,
+    transforms_detected: intent.transform_ids.length,
+    transforms_needing_human: intent.needing_human,
+    transform_ids: intent.transform_ids,
+    ...(facts ? { plan: facts } : {}),
+    asserts,
+    does_not_assert: UPGRADE_DOES_NOT_ASSERT,
+  };
+}
+
+/**
+ * The transforms this run may report to the org's fleet library as PROVEN.
+ *
+ * Only on a `plan-proven` verdict, and only transforms that did not need a
+ * human — a transform a person had to intervene on is not evidence that the
+ * transform is safe to apply unattended, which is the only claim the fleet
+ * counter is allowed to make.
+ */
+export function captureProvenTransforms(
+  statement: UpgradeEvidenceStatement | undefined,
+  matches: readonly TransformMatch[],
+): ProvenTransform[] {
+  if (statement?.verdict !== "plan-proven") return [];
+  const seen = new Set<string>();
+  const out: ProvenTransform[] = [];
+  for (const m of matches) {
+    if (m.needs_human) continue;
+    // A provider-block setting matches unconditionally — there is no config to
+    // confirm it against — so counting it as proven would inflate its fleet
+    // counter with every repo that never used the setting at all.
+    if (m.entry.kind === "provider_setting") continue;
+    // An entry the installed schema did not corroborate must not become fleet
+    // evidence. `unverified` is the honest "we could not check this"; promoting
+    // it to a proven counter would launder the doubt away.
+    if (
+      m.schema_agreement === "unverified" &&
+      m.entry.kind !== "resource_renamed"
+    )
+      continue;
+    if (seen.has(m.entry.id)) continue;
+    seen.add(m.entry.id);
+    // Coordinates come from the match's OWN pack, not the statement's. A repo
+    // mid-upgrade on two providers records the intent for the primary pack
+    // only, so stamping every match with those majors filed cloudflare
+    // migrations in the org's table as `azurerm` 3→4.
+    out.push({
+      transform_id: m.entry.id,
+      provider: m.provider,
+      from_major: m.from_major,
+      to_major: m.to_major,
+    });
+  }
+  return out;
+}
+
+/** Index a fleet library by transform id for O(1) lookup while rendering. */
+export function indexProvenTransforms(
+  library: readonly ProvenTransform[],
+): Map<string, ProvenTransform> {
+  const byId = new Map<string, ProvenTransform>();
+  for (const p of library) {
+    if (!byId.has(p.transform_id)) byId.set(p.transform_id, p);
+  }
+  return byId;
+}