@intentius/chant 0.18.37 → 0.19.1

package/src/terraform/aws-resources.test.ts

@@ -0,0 +1,81 @@
+import { describe, test, expect } from "vitest";
+import { AWS_CARVE_TYPES, awsCarveType, applyAwsMapper } from "./aws-resources";
+import { TIER_MAP } from "./tier-map";
+import { canAdoptFromState } from "./adopt-state";
+
+describe("AWS carve-out table", () => {
+  test("advise and emit cover exactly the same AWS types (no cliff)", () => {
+    // Every AWS type the advisor ranks (tier map) must be emittable, and vice
+    // versa. Non-AWS entries (kubernetes_manifest) are excluded.
+    const tierAws = Object.keys(TIER_MAP).filter((t) => t.startsWith("aws_")).sort();
+    const emitAws = AWS_CARVE_TYPES.map((t) => t.tfType).sort();
+    expect(tierAws).toEqual(emitAws);
+    for (const t of emitAws) expect(canAdoptFromState(t)).toBe(true);
+  });
+
+  test("covers the common carve targets across families", () => {
+    const types = new Set(AWS_CARVE_TYPES.map((t) => t.tfType));
+    for (const t of [
+      "aws_s3_bucket", "aws_iam_role", "aws_iam_policy", "aws_dynamodb_table",
+      "aws_lambda_function", "aws_sns_topic", "aws_sqs_queue", "aws_kms_key",
+      "aws_secretsmanager_secret", "aws_ssm_parameter", "aws_ecr_repository",
+      "aws_vpc", "aws_subnet", "aws_security_group", "aws_route53_zone",
+      "aws_cloudwatch_log_group",
+    ]) {
+      expect(types.has(t)).toBe(true);
+    }
+    expect(AWS_CARVE_TYPES.length).toBeGreaterThanOrEqual(20);
+  });
+
+  test("constructors are non-empty and consistent per native type", () => {
+    // A constructor may be shared by TF aliases for the same native resource
+    // (e.g. aws_lb and aws_alb both → LoadBalancer), but a given native type
+    // must always map to the same constructor.
+    const byNative = new Map<string, string>();
+    for (const t of AWS_CARVE_TYPES) {
+      expect(t.ctor.length).toBeGreaterThan(0);
+      const seen = byNative.get(t.nativeType);
+      if (seen) expect(t.ctor).toBe(seen);
+      else byNative.set(t.nativeType, t.ctor);
+    }
+  });
+});
+
+describe("applyAwsMapper", () => {
+  test("renames fields to CloudFormation props and reshapes tags", () => {
+    const { props, mappedKeys } = applyAwsMapper(awsCarveType("aws_s3_bucket")!, {
+      id: "b", bucket: "my-bucket", tags: { Env: "prod" }, force_destroy: false,
+    });
+    expect(props).toEqual({ BucketName: "my-bucket", Tags: [{ Key: "Env", Value: "prod" }] });
+    expect(mappedKeys).toContain("bucket");
+    expect(mappedKeys).toContain("tags");
+    expect(mappedKeys).not.toContain("force_destroy"); // stays unmapped
+  });
+
+  test("parses a JSON-string policy into an object", () => {
+    const { props } = applyAwsMapper(awsCarveType("aws_iam_role")!, {
+      name: "r",
+      assume_role_policy: '{"Version":"2012-10-17","Statement":[]}',
+      managed_policy_arns: ["arn:aws:iam::aws:policy/X"],
+    });
+    expect(props.RoleName).toBe("r");
+    expect(props.AssumeRolePolicyDocument).toEqual({ Version: "2012-10-17", Statement: [] });
+    expect(props.ManagedPolicyArns).toEqual(["arn:aws:iam::aws:policy/X"]);
+  });
+
+  test("wraps an instance-profile role into a list", () => {
+    const { props } = applyAwsMapper(awsCarveType("aws_iam_instance_profile")!, { name: "p", role: "my-role" });
+    expect(props).toEqual({ InstanceProfileName: "p", Roles: ["my-role"] });
+  });
+
+  test("a malformed JSON policy is preserved as a string, not dropped", () => {
+    const { props } = applyAwsMapper(awsCarveType("aws_iam_policy")!, { name: "p", policy: "not json {" });
+    expect(props.PolicyDocument).toBe("not json {");
+  });
+
+  test("omits absent attributes", () => {
+    const { props } = applyAwsMapper(awsCarveType("aws_subnet")!, { vpc_id: "vpc-1", cidr_block: "10.0.1.0/24" });
+    expect(props).toEqual({ VpcId: "vpc-1", CidrBlock: "10.0.1.0/24" });
+    expect(props).not.toHaveProperty("AvailabilityZone");
+  });
+});

package/src/terraform/aws-resources.ts

@@ -0,0 +1,214 @@
+/**
+ * The AWS carve-out resource table — the single source of truth for which AWS
+ * Terraform types chant can carve, and how.
+ *
+ * Both the advisor (tier map / scoring) and `carve emit --state` derive from
+ * this one list, so advise and emit cover exactly the same AWS types: advise
+ * never ranks a resource emit cannot produce, and emit never claims a type
+ * advise did not score. Adding a type here lights it up for both at once.
+ *
+ * Each entry maps the common, high-confidence Terraform attributes to their
+ * CloudFormation property names (chant AWS constructors take CFN PascalCase
+ * props). Attributes without a mapping here are preserved in a reference
+ * comment on emit, never dropped — a curated seed, not a full TF↔CFN transform.
+ */
+
+/** A Terraform attribute → CloudFormation property mapping. */
+type FieldSpec = string | { prop: string; transform: (v: unknown) => unknown };
+
+export interface AwsCarveType {
+  /** Terraform resource type, e.g. `aws_s3_bucket`. */
+  tfType: string;
+  /** Native-spec map tier: 1 clean 1:1, 2 some reshaping, 3 heavy composite. */
+  tier: 1 | 2 | 3;
+  /** CloudFormation type, e.g. `AWS::S3::Bucket`. */
+  nativeType: string;
+  /** chant AWS lexicon constructor, e.g. `Bucket` (verified against generated exports). */
+  ctor: string;
+  /** The HCL attribute carrying the physical name (for the live-import hint / graph identity). */
+  identityAttr?: string;
+  /** Terraform attribute → CFN property mappings. */
+  fields: Record<string, FieldSpec>;
+  /** Map the Terraform `tags` map to CloudFormation `Tags` list. */
+  tags?: boolean;
+}
+
+export const AWS_LEXICON_IMPORT = "@intentius/chant-lexicon-aws";
+
+/** Parse a Terraform JSON-string attribute (IAM policy docs) into an object. */
+const asJson = (v: unknown): unknown => {
+  if (typeof v !== "string") return v;
+  try {
+    return JSON.parse(v);
+  } catch {
+    return v;
+  }
+};
+const json = (prop: string): FieldSpec => ({ prop, transform: asJson });
+
+export const AWS_CARVE_TYPES: AwsCarveType[] = [
+  // ── Storage & data ──
+  { tfType: "aws_s3_bucket", tier: 1, nativeType: "AWS::S3::Bucket", ctor: "Bucket", identityAttr: "bucket",
+    fields: { bucket: "BucketName" }, tags: true },
+  { tfType: "aws_dynamodb_table", tier: 2, nativeType: "AWS::DynamoDB::Table", ctor: "Table", identityAttr: "name",
+    fields: { name: "TableName", billing_mode: "BillingMode" }, tags: true },
+  { tfType: "aws_efs_file_system", tier: 1, nativeType: "AWS::EFS::FileSystem", ctor: "EFSFileSystem",
+    fields: { encrypted: "Encrypted", performance_mode: "PerformanceMode", throughput_mode: "ThroughputMode" }, tags: true },
+
+  // ── Messaging ──
+  { tfType: "aws_sns_topic", tier: 1, nativeType: "AWS::SNS::Topic", ctor: "Topic", identityAttr: "name",
+    fields: { name: "TopicName", display_name: "DisplayName", fifo_topic: "FifoTopic" }, tags: true },
+  { tfType: "aws_sqs_queue", tier: 1, nativeType: "AWS::SQS::Queue", ctor: "Queue", identityAttr: "name",
+    fields: { name: "QueueName", visibility_timeout_seconds: "VisibilityTimeout", fifo_queue: "FifoQueue", delay_seconds: "DelaySeconds" }, tags: true },
+
+  // ── IAM ──
+  { tfType: "aws_iam_role", tier: 2, nativeType: "AWS::IAM::Role", ctor: "Role", identityAttr: "name",
+    fields: { name: "RoleName", assume_role_policy: json("AssumeRolePolicyDocument"), managed_policy_arns: "ManagedPolicyArns", description: "Description", path: "Path" }, tags: true },
+  { tfType: "aws_iam_policy", tier: 1, nativeType: "AWS::IAM::ManagedPolicy", ctor: "ManagedPolicy", identityAttr: "name",
+    fields: { name: "ManagedPolicyName", policy: json("PolicyDocument"), description: "Description", path: "Path" } },
+  { tfType: "aws_iam_instance_profile", tier: 1, nativeType: "AWS::IAM::InstanceProfile", ctor: "InstanceProfile", identityAttr: "name",
+    fields: { name: "InstanceProfileName", path: "Path", role: { prop: "Roles", transform: (v) => (v === undefined ? v : [v]) } } },
+
+  // ── Registry, keys, secrets, config ──
+  { tfType: "aws_ecr_repository", tier: 1, nativeType: "AWS::ECR::Repository", ctor: "ECRRepository", identityAttr: "name",
+    fields: { name: "RepositoryName", image_tag_mutability: "ImageTagMutability" }, tags: true },
+  { tfType: "aws_kms_key", tier: 2, nativeType: "AWS::KMS::Key", ctor: "KmsKey",
+    fields: { description: "Description", enable_key_rotation: "EnableKeyRotation", deletion_window_in_days: "PendingWindowInDays", is_enabled: "Enabled" }, tags: true },
+  { tfType: "aws_secretsmanager_secret", tier: 1, nativeType: "AWS::SecretsManager::Secret", ctor: "Secret", identityAttr: "name",
+    fields: { name: "Name", description: "Description", kms_key_id: "KmsKeyId" }, tags: true },
+  { tfType: "aws_ssm_parameter", tier: 1, nativeType: "AWS::SSM::Parameter", ctor: "SsmParameter", identityAttr: "name",
+    fields: { name: "Name", type: "Type", value: "Value", tier: "Tier", description: "Description" } },
+
+  // ── Compute ──
+  { tfType: "aws_lambda_function", tier: 2, nativeType: "AWS::Lambda::Function", ctor: "Function", identityAttr: "function_name",
+    fields: { function_name: "FunctionName", runtime: "Runtime", handler: "Handler", memory_size: "MemorySize", timeout: "Timeout", description: "Description", architectures: "Architectures" }, tags: true },
+  { tfType: "aws_ecs_service", tier: 3, nativeType: "AWS::ECS::Service", ctor: "EcsService", identityAttr: "name",
+    fields: { name: "ServiceName", cluster: "Cluster", desired_count: "DesiredCount", launch_type: "LaunchType", task_definition: "TaskDefinition" }, tags: true },
+
+  // ── Networking ──
+  { tfType: "aws_vpc", tier: 1, nativeType: "AWS::EC2::VPC", ctor: "Vpc",
+    fields: { cidr_block: "CidrBlock", enable_dns_support: "EnableDnsSupport", enable_dns_hostnames: "EnableDnsHostnames", instance_tenancy: "InstanceTenancy" }, tags: true },
+  { tfType: "aws_subnet", tier: 1, nativeType: "AWS::EC2::Subnet", ctor: "Subnet",
+    fields: { vpc_id: "VpcId", cidr_block: "CidrBlock", availability_zone: "AvailabilityZone", map_public_ip_on_launch: "MapPublicIpOnLaunch" }, tags: true },
+  { tfType: "aws_security_group", tier: 2, nativeType: "AWS::EC2::SecurityGroup", ctor: "SecurityGroup", identityAttr: "name",
+    fields: { description: "GroupDescription", name: "GroupName", vpc_id: "VpcId" }, tags: true },
+  { tfType: "aws_route_table", tier: 2, nativeType: "AWS::EC2::RouteTable", ctor: "RouteTable",
+    fields: { vpc_id: "VpcId" }, tags: true },
+  { tfType: "aws_internet_gateway", tier: 1, nativeType: "AWS::EC2::InternetGateway", ctor: "InternetGateway",
+    fields: {}, tags: true },
+  { tfType: "aws_eip", tier: 1, nativeType: "AWS::EC2::EIP", ctor: "EIP",
+    fields: { domain: "Domain", instance: "InstanceId" }, tags: true },
+  { tfType: "aws_nat_gateway", tier: 2, nativeType: "AWS::EC2::NatGateway", ctor: "NatGateway",
+    fields: { subnet_id: "SubnetId", allocation_id: "AllocationId", connectivity_type: "ConnectivityType" }, tags: true },
+
+  // ── DNS & observability ──
+  { tfType: "aws_route53_zone", tier: 1, nativeType: "AWS::Route53::HostedZone", ctor: "HostedZone", identityAttr: "name",
+    fields: { name: "Name", comment: "HostedZoneConfig" } },
+  { tfType: "aws_cloudwatch_log_group", tier: 1, nativeType: "AWS::Logs::LogGroup", ctor: "LogGroup", identityAttr: "name",
+    fields: { name: "LogGroupName", retention_in_days: "RetentionInDays", kms_key_id: "KmsKeyId" }, tags: true },
+  { tfType: "aws_cloudwatch_metric_alarm", tier: 2, nativeType: "AWS::CloudWatch::Alarm", ctor: "Alarm", identityAttr: "alarm_name",
+    fields: { alarm_name: "AlarmName", comparison_operator: "ComparisonOperator", metric_name: "MetricName", namespace: "Namespace", threshold: "Threshold", evaluation_periods: "EvaluationPeriods", period: "Period", statistic: "Statistic", alarm_description: "AlarmDescription" }, tags: true },
+  { tfType: "aws_cloudwatch_event_rule", tier: 2, nativeType: "AWS::Events::Rule", ctor: "EventRule", identityAttr: "name",
+    fields: { name: "Name", schedule_expression: "ScheduleExpression", event_pattern: json("EventPattern"), description: "Description", state: "State" } },
+
+  // ── Compute (EC2 / ECS / ASG) ──
+  { tfType: "aws_instance", tier: 2, nativeType: "AWS::EC2::Instance", ctor: "Instance",
+    fields: { ami: "ImageId", instance_type: "InstanceType", subnet_id: "SubnetId", key_name: "KeyName", availability_zone: "AvailabilityZone", iam_instance_profile: "IamInstanceProfile" }, tags: true },
+  { tfType: "aws_launch_template", tier: 2, nativeType: "AWS::EC2::LaunchTemplate", ctor: "LaunchTemplate", identityAttr: "name",
+    fields: { name: "LaunchTemplateName" }, tags: true },
+  { tfType: "aws_autoscaling_group", tier: 2, nativeType: "AWS::AutoScaling::AutoScalingGroup", ctor: "AutoScalingGroup", identityAttr: "name",
+    fields: { name: "AutoScalingGroupName", min_size: "MinSize", max_size: "MaxSize", desired_capacity: "DesiredCapacity", vpc_zone_identifier: "VPCZoneIdentifier", health_check_type: "HealthCheckType" } },
+  { tfType: "aws_ecs_cluster", tier: 1, nativeType: "AWS::ECS::Cluster", ctor: "EcsCluster", identityAttr: "name",
+    fields: { name: "ClusterName" }, tags: true },
+  { tfType: "aws_ecs_task_definition", tier: 3, nativeType: "AWS::ECS::TaskDefinition", ctor: "TaskDefinition",
+    fields: { family: "Family", cpu: "Cpu", memory: "Memory", network_mode: "NetworkMode", execution_role_arn: "ExecutionRoleArn", task_role_arn: "TaskRoleArn" }, tags: true },
+  { tfType: "aws_ebs_volume", tier: 1, nativeType: "AWS::EC2::Volume", ctor: "EC2Volume",
+    fields: { availability_zone: "AvailabilityZone", size: "Size", type: "VolumeType", encrypted: "Encrypted", iops: "Iops" }, tags: true },
+
+  // ── Load balancing (ELBv2; aws_alb is a legacy alias) ──
+  { tfType: "aws_lb", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::LoadBalancer", ctor: "LoadBalancer", identityAttr: "name",
+    fields: { name: "Name", load_balancer_type: "Type", internal: { prop: "Scheme", transform: (v) => (v === true ? "internal" : v === false ? "internet-facing" : v) } }, tags: true },
+  { tfType: "aws_alb", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::LoadBalancer", ctor: "LoadBalancer", identityAttr: "name",
+    fields: { name: "Name", load_balancer_type: "Type", internal: { prop: "Scheme", transform: (v) => (v === true ? "internal" : v === false ? "internet-facing" : v) } }, tags: true },
+  { tfType: "aws_lb_target_group", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::TargetGroup", ctor: "TargetGroup", identityAttr: "name",
+    fields: { name: "Name", port: "Port", protocol: "Protocol", vpc_id: "VpcId", target_type: "TargetType" }, tags: true },
+  { tfType: "aws_lb_listener", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::Listener", ctor: "Listener",
+    fields: { port: "Port", protocol: "Protocol", load_balancer_arn: "LoadBalancerArn" } },
+
+  // ── Databases & cache ──
+  { tfType: "aws_db_instance", tier: 2, nativeType: "AWS::RDS::DBInstance", ctor: "DbInstance", identityAttr: "identifier",
+    fields: { identifier: "DBInstanceIdentifier", engine: "Engine", engine_version: "EngineVersion", instance_class: "DBInstanceClass", allocated_storage: "AllocatedStorage", db_name: "DBName", multi_az: "MultiAZ", storage_encrypted: "StorageEncrypted" }, tags: true },
+  { tfType: "aws_db_subnet_group", tier: 1, nativeType: "AWS::RDS::DBSubnetGroup", ctor: "RDSDBSubnetGroup", identityAttr: "name",
+    fields: { name: "DBSubnetGroupName", description: "DBSubnetGroupDescription", subnet_ids: "SubnetIds" }, tags: true },
+  { tfType: "aws_elasticache_cluster", tier: 2, nativeType: "AWS::ElastiCache::CacheCluster", ctor: "CacheCluster",
+    fields: { engine: "Engine", node_type: "CacheNodeType", num_cache_nodes: "NumCacheNodes", engine_version: "EngineVersion" }, tags: true },
+  { tfType: "aws_elasticache_replication_group", tier: 2, nativeType: "AWS::ElastiCache::ReplicationGroup", ctor: "ReplicationGroup", identityAttr: "replication_group_id",
+    fields: { replication_group_id: "ReplicationGroupId", description: "ReplicationGroupDescription", node_type: "CacheNodeType", engine: "Engine" }, tags: true },
+
+  // ── DNS, CDN & API ──
+  { tfType: "aws_route53_record", tier: 2, nativeType: "AWS::Route53::RecordSet", ctor: "RecordSet",
+    fields: { name: "Name", type: "Type", ttl: "TTL", zone_id: "HostedZoneId", records: "ResourceRecords" } },
+  { tfType: "aws_api_gateway_rest_api", tier: 2, nativeType: "AWS::ApiGateway::RestApi", ctor: "RestApi", identityAttr: "name",
+    fields: { name: "Name", description: "Description" }, tags: true },
+  { tfType: "aws_apigatewayv2_api", tier: 2, nativeType: "AWS::ApiGatewayV2::Api", ctor: "HttpApi", identityAttr: "name",
+    fields: { name: "Name", protocol_type: "ProtocolType", description: "Description" }, tags: true },
+
+  // ── IAM (users/groups), certs & keys ──
+  { tfType: "aws_iam_user", tier: 1, nativeType: "AWS::IAM::User", ctor: "IAMUser", identityAttr: "name",
+    fields: { name: "UserName", path: "Path" }, tags: true },
+  { tfType: "aws_iam_group", tier: 1, nativeType: "AWS::IAM::Group", ctor: "IAMGroup", identityAttr: "name",
+    fields: { name: "GroupName", path: "Path" } },
+  { tfType: "aws_acm_certificate", tier: 2, nativeType: "AWS::CertificateManager::Certificate", ctor: "AcmCertificate", identityAttr: "domain_name",
+    fields: { domain_name: "DomainName", validation_method: "ValidationMethod", subject_alternative_names: "SubjectAlternativeNames" }, tags: true },
+  { tfType: "aws_kms_alias", tier: 1, nativeType: "AWS::KMS::Alias", ctor: "KMSAlias", identityAttr: "name",
+    fields: { name: "AliasName", target_key_id: "TargetKeyId" } },
+
+  // ── Messaging & step functions ──
+  { tfType: "aws_sns_topic_subscription", tier: 2, nativeType: "AWS::SNS::Subscription", ctor: "Subscription",
+    fields: { protocol: "Protocol", endpoint: "Endpoint", topic_arn: "TopicArn" } },
+  { tfType: "aws_sfn_state_machine", tier: 3, nativeType: "AWS::StepFunctions::StateMachine", ctor: "StateMachine", identityAttr: "name",
+    fields: { name: "StateMachineName", role_arn: "RoleArn", type: "StateMachineType" }, tags: true },
+];
+
+const BY_TYPE = new Map(AWS_CARVE_TYPES.map((t) => [t.tfType, t]));
+
+export function awsCarveType(tfType: string): AwsCarveType | undefined {
+  return BY_TYPE.get(tfType);
+}
+
+/** TF `tags` map → CloudFormation `Tags` list of {Key, Value}. */
+function tagsToCfn(tags: unknown): Array<{ Key: string; Value: unknown }> | undefined {
+  if (!tags || typeof tags !== "object" || Array.isArray(tags)) return undefined;
+  const entries = Object.entries(tags as Record<string, unknown>);
+  return entries.length ? entries.map(([Key, Value]) => ({ Key, Value })) : undefined;
+}
+
+/**
+ * Apply an entry's field mappings to a resource's Terraform attributes, yielding
+ * CloudFormation properties and the set of attribute keys that were consumed
+ * (so the caller can report the rest as unmapped).
+ */
+export function applyAwsMapper(
+  entry: AwsCarveType,
+  attrs: Record<string, unknown>,
+): { props: Record<string, unknown>; mappedKeys: string[] } {
+  const props: Record<string, unknown> = {};
+  const mappedKeys: string[] = ["id", "arn"]; // identity/computed attrs, ignored not dropped
+  for (const [tfAttr, spec] of Object.entries(entry.fields)) {
+    const value = attrs[tfAttr];
+    if (value === undefined) continue;
+    if (typeof spec === "string") {
+      props[spec] = value;
+    } else {
+      const t = spec.transform(value);
+      if (t !== undefined) props[spec.prop] = t;
+    }
+    mappedKeys.push(tfAttr);
+  }
+  if (entry.tags) {
+    const tags = tagsToCfn(attrs.tags);
+    if (tags) props.Tags = tags;
+    mappedKeys.push("tags");
+  }
+  return { props, mappedKeys };
+}

package/src/terraform/bridge.test.ts

@@ -0,0 +1,118 @@
+import { describe, test, expect } from "vitest";
+import { buildGraph } from "./graph";
+import { boundaryReport } from "./carve";
+import { generateBridge, type CarvedIdentity } from "./bridge";
+import type { Hcl2JsonTree } from "./types";
+
+const workedExample: Hcl2JsonTree = {
+  resource: {
+    aws_s3_bucket: { assets: [{ bucket: "myapp-assets-prod" }] },
+    aws_lambda_function: {
+      api: [
+        {
+          function_name: "myapp-api",
+          environment: {
+            variables: {
+              ASSETS_BUCKET: "${aws_s3_bucket.assets.bucket}",
+              ASSETS_ARN: "${aws_s3_bucket.assets.arn}",
+            },
+          },
+        },
+      ],
+    },
+  },
+};
+
+// The original surviving Terraform text (bare HCL references, as authored).
+const API_TF = `resource "aws_lambda_function" "api" {
+  function_name = "myapp-api"
+  environment {
+    variables = {
+      ASSETS_BUCKET = aws_s3_bucket.assets.bucket
+      ASSETS_ARN    = aws_s3_bucket.assets.arn
+    }
+  }
+}
+`;
+
+const identities = new Map<string, CarvedIdentity>([
+  ["aws_s3_bucket.assets", { attr: "bucket", value: "myapp-assets-prod" }],
+]);
+
+describe("generateBridge — inbound (data-source rewrite)", () => {
+  test("adds a data source for the carved bucket", () => {
+    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], identities);
+
+    expect(plan.dataSources).toHaveLength(1);
+    expect(plan.dataSources[0]).toMatchObject({ address: "aws_s3_bucket.assets", type: "aws_s3_bucket", name: "assets" });
+    expect(plan.dataSources[0].hcl).toBe(
+      'data "aws_s3_bucket" "assets" {\n  bucket = "myapp-assets-prod"\n}',
+    );
+  });
+
+  test("rewrites survivor references to the data source", () => {
+    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], identities);
+
+    const rewrite = plan.rewrites.find((r) => r.path === "api.tf")!;
+    expect(rewrite.changed).toBe(true);
+    expect(rewrite.rewritten).toContain("data.aws_s3_bucket.assets.bucket");
+    expect(rewrite.rewritten).toContain("data.aws_s3_bucket.assets.arn");
+    // The bare references are gone.
+    expect(rewrite.rewritten).not.toMatch(/(?<!data\.)\baws_s3_bucket\.assets\.bucket/);
+  });
+
+  test("does not double-prefix an already-rewritten reference (idempotent)", () => {
+    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const already = API_TF.replace(/aws_s3_bucket\.assets/g, "data.aws_s3_bucket.assets");
+    const plan = generateBridge(report, [{ path: "api.tf", content: already }], identities);
+    const rewrite = plan.rewrites.find((r) => r.path === "api.tf")!;
+    expect(rewrite.changed).toBe(false);
+    expect(rewrite.rewritten).not.toContain("data.data.aws_s3_bucket");
+  });
+
+  test("does not touch the carved resource's own declaration (quoted labels)", () => {
+    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const decl = `resource "aws_s3_bucket" "assets" {\n  bucket = "myapp-assets-prod"\n}\n`;
+    const plan = generateBridge(report, [{ path: "bucket.tf", content: decl }], identities);
+    const rewrite = plan.rewrites.find((r) => r.path === "bucket.tf")!;
+    // `resource "aws_s3_bucket" "assets"` uses quoted labels, not the dotted
+    // token, so it is left alone.
+    expect(rewrite.rewritten).toContain('resource "aws_s3_bucket" "assets"');
+    expect(rewrite.changed).toBe(false);
+  });
+
+  test("unknown identity emits a TODO data source instead of a wrong value", () => {
+    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], new Map());
+    expect(plan.dataSources[0].hcl).toContain("# TODO");
+  });
+});
+
+describe("generateBridge — outbound (deferred inputs)", () => {
+  test("records outbound edges as deferred deploy-time inputs", () => {
+    const tree: Hcl2JsonTree = {
+      resource: {
+        aws_sns_topic: { alerts: [{ name: "a" }] },
+        aws_sqs_queue: { dlq: [{ name: "d", redrive: "${aws_sns_topic.alerts.arn}" }] },
+      },
+    };
+    const report = boundaryReport(buildGraph(tree), "aws_sqs_queue.dlq")!;
+    const plan = generateBridge(report, [], new Map());
+    expect(plan.dataSources).toEqual([]); // no inbound → no survivor patch
+    expect(plan.deferredInputs).toHaveLength(1);
+    expect(plan.deferredInputs[0]).toMatchObject({ survivor: "aws_sns_topic.alerts", carved: "aws_sqs_queue.dlq" });
+  });
+});
+
+describe("generateBridge — runbook", () => {
+  test("is reversible and observe-first, with the state-rm and import steps", () => {
+    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], identities);
+    expect(plan.runbook).toContain("terraform state rm aws_s3_bucket.assets");
+    expect(plan.runbook).toContain("does NOT destroy");
+    expect(plan.runbook).toContain("terraform import aws_s3_bucket.assets");
+    expect(plan.runbook).toMatch(/reversible/i);
+  });
+});

package/src/terraform/bridge.ts

@@ -0,0 +1,164 @@
+/**
+ * Boundary bridging for the strangler-fig carve (#197) — the centerpiece.
+ *
+ * Carving a resource cuts edges. This generates the edits to the Terraform you
+ * LEAVE BEHIND so its plan stays valid once the resource is chant-owned:
+ *
+ *  - inbound edge  → the survivor loses its reference to the carved resource.
+ *    Bridge: add a `data` source for the (now chant-managed) resource and
+ *    rewrite the survivor's `type.name.attr` references to `data.type.name.attr`.
+ *    Required immediately, or `terraform plan` errors on the dangling ref.
+ *
+ *  - outbound edge → the carved resource read a value from a survivor. That
+ *    value must enter chant from outside synthesis, as a deploy-time input.
+ *    Deferred until apply; here we only record the provenance.
+ *
+ * Pure text transform over the original `.tf` content — no wasm, no shell, no
+ * mutation. The command layer writes the results and (optionally) diffs them
+ * into a git-applyable patch. A carve never destroys or recreates; the runbook
+ * is reversible via `terraform import`.
+ */
+
+import type { CarveReport } from "./carve";
+
+export interface CarvedIdentity {
+  /** The HCL identity attribute, e.g. `bucket` or `name`. */
+  attr?: string;
+  /** Its literal value, e.g. `myapp-assets-prod`. */
+  value?: string;
+}
+
+export interface DataSourceBlock {
+  /** Carved resource address the data source stands in for. */
+  address: string;
+  type: string;
+  name: string;
+  hcl: string;
+}
+
+export interface FileRewrite {
+  path: string;
+  original: string;
+  rewritten: string;
+  changed: boolean;
+}
+
+export interface DeferredInput {
+  survivor: string;
+  carved: string;
+  attrs: string[];
+  note: string;
+}
+
+export interface BridgePlan {
+  target: string;
+  dataSources: DataSourceBlock[];
+  rewrites: FileRewrite[];
+  deferredInputs: DeferredInput[];
+  runbook: string;
+}
+
+/** `aws_s3_bucket.assets` → a regex matching that reference head, not already `data.`-prefixed. */
+function referenceRegex(address: string): RegExp {
+  const escaped = address.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // (?<!data\.) — do not double-prefix an existing data source reference.
+  return new RegExp(`(?<!data\\.)\\b${escaped}\\b`, "g");
+}
+
+function dataSourceHcl(type: string, name: string, identity: CarvedIdentity): string {
+  const body =
+    identity.attr && identity.value !== undefined
+      ? `  ${identity.attr} = ${JSON.stringify(identity.value)}`
+      : `  # TODO: identify the resource (its name/id was interpolated in the source)`;
+  return `data ${JSON.stringify(type)} ${JSON.stringify(name)} {\n${body}\n}`;
+}
+
+/**
+ * Build the bridge plan for a carve.
+ *
+ * @param report    the boundary report (from `boundaryReport`)
+ * @param files     every `.tf` file in the estate, as { path, content }
+ * @param identities physical identity per carved address, for the data sources
+ */
+export function generateBridge(
+  report: CarveReport,
+  files: Array<{ path: string; content: string }>,
+  identities: Map<string, CarvedIdentity>,
+): BridgePlan {
+  // Carved resources that something still depends on need a data source.
+  const carvedWithInbound = new Map<string, { type: string; name: string }>();
+  for (const e of report.inbound) {
+    const [type, ...rest] = e.carved.split(".");
+    carvedWithInbound.set(e.carved, { type, name: rest.join(".") });
+  }
+
+  const dataSources: DataSourceBlock[] = [...carvedWithInbound.entries()].map(([address, { type, name }]) => ({
+    address,
+    type,
+    name,
+    hcl: dataSourceHcl(type, name, identities.get(address) ?? {}),
+  }));
+
+  // Rewrite every survivor reference to the carved resources into a data ref.
+  const rewrites: FileRewrite[] = files.map(({ path, content }) => {
+    let rewritten = content;
+    for (const address of carvedWithInbound.keys()) {
+      rewritten = rewritten.replace(referenceRegex(address), `data.${address}`);
+    }
+    return { path, original: content, rewritten, changed: rewritten !== content };
+  });
+
+  const deferredInputs: DeferredInput[] = report.outbound.map((e) => ({
+    survivor: e.survivor,
+    carved: e.carved,
+    attrs: e.attrs,
+    note: `${e.carved} reads ${e.survivor}.${e.attrs.join(", ")} — supply this as a deploy-time input to the carved component at apply.`,
+  }));
+
+  return {
+    target: report.target,
+    dataSources,
+    rewrites,
+    deferredInputs,
+    runbook: buildRunbook(report, dataSources, deferredInputs),
+  };
+}
+
+/** The reversible, observe-first handoff runbook (#197). */
+function buildRunbook(report: CarveReport, dataSources: DataSourceBlock[], deferred: DeferredInput[]): string {
+  const carvedAddrs = report.carveSet.map((m) => m.address);
+  const L: string[] = [];
+  L.push(`# Carve-out: ${report.target} → chant   [observe-first, reversible]`);
+  L.push("");
+  L.push(`Peelability ${report.peelability}. Carves ${carvedAddrs.length} Terraform resource(s) into chant, leaving the live resource untouched.`);
+  L.push("");
+  L.push("## 1. Review the emitted chant source");
+  L.push("    (produced by `chant carve emit` — confirm it builds to a spec-true template)");
+  L.push("");
+  L.push("## 2. Stop Terraform managing the resource (does NOT destroy it)");
+  L.push(`    terraform state rm ${carvedAddrs.join(" ")}`);
+  L.push("");
+  L.push("## 3. Confirm no destroy, then patch the survivors");
+  L.push("    terraform plan   # expect 0 to destroy; refs to the carved resource now error");
+  if (dataSources.length) {
+    L.push("    # apply the generated bridge patch — it adds these data sources and rewires references:");
+    for (const ds of dataSources) L.push(`    #   data.${ds.type}.${ds.name}  (for ${ds.address})`);
+  } else {
+    L.push("    # no inbound edges — no survivor patch needed.");
+  }
+  L.push("    terraform plan   # expect: in-place updates to the survivors only");
+  L.push("    terraform apply");
+  L.push("");
+  L.push("## 4. Adopt the live resource into chant (now an orphan)");
+  L.push("    chant carve emit --from <tf-dir> --select " + report.target + " --env <env>   # already done if you ran emit");
+  L.push("    # then apply the ownership marker so chant owns it (carve apply, next step)");
+  if (deferred.length) {
+    L.push("");
+    L.push("## Deferred deploy-time inputs (wire these when you turn the dial to apply)");
+    for (const d of deferred) L.push(`    - ${d.note}`);
+  }
+  L.push("");
+  L.push("## Rollback (any time before apply-graduation)");
+  L.push(`    terraform import ${report.target} <physical-id>   # back under Terraform`);
+  return L.join("\n");
+}