test(integ): add drift-revert-arrays integ (tag-list / ARN-array canonicalization, #802) (#833)

Author: go-to-k

docs/_generated/integ-coverage.json

@@ -728,6 +728,7 @@
         "bench-cdk-sample",
         "cache-streaming",
         "docdb-neptune",
+        "drift-revert-arrays",
         "drift-revert-vpc",
         "ec2-instance",
         "ec2-vpc",
@@ -763,6 +764,9 @@
         "docdb-neptune": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "drift-revert-vpc": [
           "l2"
         ],
@@ -820,6 +824,7 @@
         "bench-cdk-sample",
         "cache-streaming",
         "docdb-neptune",
+        "drift-revert-arrays",
         "drift-revert-vpc",
         "ec2-instance",
         "ec2-vpc",
@@ -855,6 +860,9 @@
         "docdb-neptune": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "drift-revert-vpc": [
           "l2"
         ],
@@ -934,6 +942,7 @@
         "bench-cdk-sample",
         "cache-streaming",
         "docdb-neptune",
+        "drift-revert-arrays",
         "drift-revert-vpc",
         "ec2-instance",
         "ec2-vpc",
@@ -969,6 +978,9 @@
         "docdb-neptune": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "drift-revert-vpc": [
           "l2"
         ],
@@ -1026,6 +1038,7 @@
         "bench-cdk-sample",
         "cache-streaming",
         "docdb-neptune",
+        "drift-revert-arrays",
         "drift-revert-vpc",
         "ec2-instance",
         "ec2-vpc",
@@ -1061,6 +1074,9 @@
         "docdb-neptune": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "drift-revert-vpc": [
           "l2"
         ],
@@ -1118,6 +1134,7 @@
         "bench-cdk-sample",
         "cache-streaming",
         "docdb-neptune",
+        "drift-revert-arrays",
         "drift-revert-vpc",
         "ec2-instance",
         "ec2-vpc",
@@ -1150,6 +1167,9 @@
         "docdb-neptune": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "drift-revert-vpc": [
           "l2"
         ],
@@ -1210,6 +1230,7 @@
         "bench-cdk-sample",
         "cache-streaming",
         "docdb-neptune",
+        "drift-revert-arrays",
         "drift-revert-vpc",
         "ec2-instance",
         "ec2-vpc",
@@ -1245,6 +1266,9 @@
         "docdb-neptune": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "drift-revert-vpc": [
           "l2"
         ],
@@ -1313,6 +1337,7 @@
         "bench-cdk-sample",
         "cache-streaming",
         "docdb-neptune",
+        "drift-revert-arrays",
         "drift-revert-vpc",
         "ec2-instance",
         "ec2-vpc",
@@ -1348,6 +1373,9 @@
         "docdb-neptune": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "drift-revert-vpc": [
           "l2"
         ],
@@ -1405,6 +1433,7 @@
         "bench-cdk-sample",
         "cache-streaming",
         "docdb-neptune",
+        "drift-revert-arrays",
         "drift-revert-vpc",
         "ec2-instance",
         "ec2-vpc",
@@ -1440,6 +1469,9 @@
         "docdb-neptune": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "drift-revert-vpc": [
           "l2"
         ],
@@ -1498,6 +1530,7 @@
         "bench-cdk-sample",
         "cache-streaming",
         "docdb-neptune",
+        "drift-revert-arrays",
         "drift-revert-vpc",
         "ec2-instance",
         "ec2-vpc",
@@ -1533,6 +1566,9 @@
         "docdb-neptune": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "drift-revert-vpc": [
           "l2"
         ],
@@ -2709,6 +2745,7 @@
         "data-analytics",
         "diff-intrinsic-target-change",
         "drift-revert",
+        "drift-revert-arrays",
         "event-driven",
         "export",
         "full-stack-demo",
@@ -2765,6 +2802,9 @@
         "drift-revert": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "event-driven": [
           "l2"
         ],
@@ -2922,6 +2962,7 @@
         "composite-stack",
         "deployment-events",
         "drift-revert",
+        "drift-revert-arrays",
         "event-driven",
         "export",
         "full-stack-demo",
@@ -2949,6 +2990,9 @@
         "drift-revert": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "event-driven": [
           "l2"
         ],
@@ -3002,6 +3046,7 @@
         "bench-sdk",
         "composite-stack",
         "data-pipeline",
+        "drift-revert-arrays",
         "event-driven",
         "eventbridge",
         "full-stack-demo",
@@ -3027,6 +3072,9 @@
         "data-pipeline": [
           "l2"
         ],
+        "drift-revert-arrays": [
+          "l2"
+        ],
         "event-driven": [
           "l2"
         ],

docs/_generated/integ-last-run.tsv

@@ -127,3 +127,4 @@ custom-resource-provider	2026-06-13T09:16:21Z	PASS	290	standard	regression sweep
 deployment-events	2026-06-13T09:16:21Z	PASS	34	verify.sh	#808 events sidecar + cdkd events + no-secrets + survives-destroy; 2 deleted 0 err
 update-replace	2026-06-13T10:43:46Z	PASS	65	verify.sh	in-place(S3/Lambda/IAM/SG)+replacement(S3 rename); 0 err 0 orphan
 s3-asset-deploy	2026-06-13T10:51:36Z	PASS	44	verify.sh	S3 zip asset upload + Lambda runs from it + generic Asset read-back; 0 err
+drift-revert-arrays	2026-06-13T10:57:27Z	PASS	114	verify.sh	#802 tag/ARN-array canonicalize; no-false-positive + true-drift detect+revert; 0 err

docs/_generated/scenario-coverage.json

@@ -32,6 +32,10 @@
       "tag": "deployment-events",
       "description": "Structured deployment events to S3 + `cdkd events` command (issue #808): per-run `deployments/{runId}.jsonl` + `index.json` (separate key family from state.json, no schema bump), events survive `cdkd destroy`, and carry error + metadata ONLY (no resource properties / secrets)."
     },
+    {
+      "tag": "drift-revert-array-canonicalization",
+      "description": "cdkd drift no-false-positive on tag-list / resource-id / ARN array REORDER (issue #802 `drift-normalize.ts` canonicalization) while still detecting real value / Action / SG-rule drift."
+    },
     {
       "tag": "drift-revert-roundtrip",
       "description": "cdkd drift detection + `--revert` round-trip via each provider.update()."
@@ -359,6 +363,14 @@
         "drift-revert-roundtrip"
       ]
     },
+    {
+      "name": "drift-revert-arrays",
+      "annotated": true,
+      "scenarios": [
+        "drift-revert-array-canonicalization",
+        "drift-revert-roundtrip"
+      ]
+    },
     {
       "name": "drift-revert-vpc",
       "annotated": true,
@@ -1016,11 +1028,19 @@
         "deployment-events"
       ]
     },
+    {
+      "scenario": "drift-revert-array-canonicalization",
+      "description": "cdkd drift no-false-positive on tag-list / resource-id / ARN array REORDER (issue #802 `drift-normalize.ts` canonicalization) while still detecting real value / Action / SG-rule drift.",
+      "fixtures": [
+        "drift-revert-arrays"
+      ]
+    },
     {
       "scenario": "drift-revert-roundtrip",
       "description": "cdkd drift detection + `--revert` round-trip via each provider.update().",
       "fixtures": [
         "drift-revert",
+        "drift-revert-arrays",
         "drift-revert-vpc"
       ]
     },

docs/changelog-cdkd.md

@@ -19,6 +19,7 @@ The CLAUDE.md `## Known Limitations` section retains the load-bearing summary
 **Recently Implemented** (2026-06-13):
 
 - ✅ **New `s3-asset-deploy` integ exercises the S3 file/ZIP asset-publishing path during a real `cdkd deploy`** — `tests/integration/s3-asset-deploy/**`. Most Lambda fixtures use inline code (`Code.fromInline`) or never assert the asset upload itself, leaving cdkd's `FileAssetPublisher` (S3 zip + upload, content-addressed skip-if-exists) without a dedicated end-to-end regression. The new `CdkdS3AssetDeployExample` stack closes that gap: a Lambda whose code comes from a **local multi-file directory** (`lambda/` — handler + `helpers/` + `vendored/` Python sub-packages, so the asset is a genuine multi-file ZIP, not a trivial single file) forces cdkd to zip the directory + upload it to the CDK bootstrap asset bucket and wire the function's `Code.S3Bucket`/`Code.S3Key` to the uploaded object; AND a generic `s3_assets.Asset` (`asset-data/`) is uploaded to the same bucket with its resolved `s3BucketName`/`s3ObjectKey` threaded into the Lambda as `CONFIG_BUCKET`/`CONFIG_KEY` env vars (synth confirms both are emitted as `Fn::Sub`-backed bucket + literal key refs, exercising cdkd's intrinsic resolver). `verify.sh` (BSD/macOS-portable, real-rc + explicit `[verify] PASS`) deploys, asserts the function's `CodeSize > 500` bytes (proves it ran from the uploaded ZIP, not inline), invokes it and asserts the handler marker (`cdkd-s3-asset-deploy-marker-v1`) plus a non-zero `configBytes` from the generic-asset S3 read-back (proving that upload reached AWS and the bucket/key env wiring resolved), then destroys and asserts the Lambda + state file are gone with 0 errors. The bootstrap-bucket asset OBJECTS persist by design (cdkd does not own / delete the CDK bootstrap bucket) — the script deliberately does NOT assert their absence and notes this. New scenario tag `s3-asset-deploy` in the canonical taxonomy (`scripts/build-scenario-coverage-matrix.ts`); coverage matrices regenerated. (NOTE: not yet run against real AWS — needs `/run-integ s3-asset-deploy` before merge.)
+- ✅ **New `drift-revert-arrays` integ broadens drift coverage to TAG-heavy / ARRAY-heavy resource types (refs issue [#802](https://github.com/go-to-k/cdkd/issues/802))** — `tests/integration/drift-revert-arrays/` (new fixture; no `src/` change). Issue #802 added `src/analyzer/drift-normalize.ts` (`canonicalizeTagListsDeep` + `canonicalizeIdArraysDeep`) so a benign AWS-side reorder of a tag list (`{Key,Value}[]`) or a resource-id / ARN array no longer surfaces as phantom drift, but the existing `drift-revert` / `drift-revert-vpc` fixtures carry none of those unordered-set array shapes — the canonicalization path had unit coverage only. This fixture (`CdkdDriftArraysExample`) deploys an S3 Bucket, SNS Topic, SQS Queue (each with six user tags), an IAM ManagedPolicy with a multi-statement document carrying multiple `Action[]` (plain scalar arrays — intentionally NOT canonicalized) + multiple `Resource[]` ARN arrays (canonicalized) + six tags, and a VPC (`natGateways: 0`, no NAT cost) + SecurityGroup with four CIDR ingress rules + six tags. `verify.sh` asserts (a) **no false positive on a clean deploy** (`cdkd drift` exit 0 even though AWS reorders the tag lists / ARN arrays on readback), (b) **no false positive on an induced reorder** (`inject-drift.ts reorder` re-PUTs the same six S3 tags reversed; `cdkd drift` still exit 0 — proves `canonicalizeTagListsDeep`), (c) **true drift still detected** (`inject-drift.ts drift` changes a tag VALUE + adds a managed-policy Action + authorizes a new SG ingress rule out of band; `cdkd drift` exit 1), then `cdkd drift --revert -y` reverts and a follow-up `cdkd drift` is clean, and destroy leaves 0 orphans. The script is BSD/macOS-portable (no `grep -P` / `date -d`), captures each `cdkd drift` real exit code, hard-fails with a canonicalizer-naming message, and prints `[verify] PASS` only on full success. The `subnet-…` / `sg-…` resource-id branch of `canonicalizeIdArraysDeep` stays unit-covered (`tests/unit/analyzer/drift-normalize.test.ts`); the integ exercises the ARN branch of the same function end-to-end. New scenario tag `drift-revert-array-canonicalization`.
 - ✅ **Extracted the triplicated `ensureClientForBucket()` state-bucket-region rebuild into one shared helper (issue [#827](https://github.com/go-to-k/cdkd/issues/827))** — `src/utils/bucket-region-client.ts` (new) + `src/state/s3-state-backend.ts` + `src/state/lock-manager.ts` + `src/state/export-index-store.ts`. Pure refactor, no behavior change. The "resolve the state bucket's region via the cached `GetBucketLocation` probe, short-circuit when it already matches the client's region, else rebuild a region-corrected `S3Client` reusing the caller's credentials" pattern had drifted into three near-identical private `ensureClientForBucket()` copies (the state backend PR #60, the lock manager #803, the exports index store #819). They are now one exported helper `rebuildClientForBucketRegion(client, bucket, opts): Promise<S3Client | null>` — it returns `null` to mean "no rebuild needed, keep the original client" and a fresh client otherwise. Every load-bearing per-store difference is preserved via options rather than collapsed: `destroyOldClient` (the state backend OWNS its client and `.destroy()`s the replaced one; the lock manager + exports store share `AwsClients.s3` and must NOT), `profile` + static `credentials` (the state backend threads its constructor `clientOpts` into both the probe and the rebuild) vs `reuseClientCredentials` (the other two authenticate the probe via `client.config.credentials()` best-effort and reuse the original client's `config.credentials` PROVIDER REFERENCE — not a resolved snapshot — for the rebuild), and `tolerateNonStandardClient` (only the exports store gracefully degrades a test double whose `config.region` is not a function by returning `null`; the other two read `config.region()` directly as before). Each store keeps its own per-instance memoization (`clientResolved` flag + single-flight `resolveInFlight` promise) and its own debug log wording via an `onRebuild` callback. The helper deliberately lives in its OWN module rather than alongside `resolveBucketRegion` in `aws-region-resolver.ts`: the three stores' unit tests mock `resolveBucketRegion` via `vi.mock('aws-region-resolver.js', ...)`, and a helper co-located in that module would call its sibling through an in-module binding vitest cannot intercept (a module cannot mock itself) — a separate module imports the mocked binding cross-module so the mock still applies. Tests: all 75 existing unit tests across `tests/unit/state/{s3-state-backend,lock-manager,export-index-store}.test.ts` (incl. each store's 301-rebuild / same-region-no-rebuild / resolve-once-cached suites) pass UNCHANGED, plus 7 new focused tests in `tests/unit/utils/bucket-region-client.test.ts` (region-mismatch → rebuilt client with correct region; same-region → `null`; static-credential carry-over to probe + rebuild; provider-reference reuse; `destroyOldClient` gating; non-standard-client tolerance → `null`; no-credentials → omit `credentials` from the rebuilt client). No runtime behavior change for any of the three cross-region-state-bucket paths (lock acquisition, state read/write, exports index).
 - ✅ **`--region` deprecation warning no longer contradicts the actual behavior (issue [#818](https://github.com/go-to-k/cdkd/issues/818))** — `src/cli/options.ts`. `warnIfDeprecatedRegion` and the hidden `deprecatedRegionOption` help text both claimed `--region` "has no effect" on non-bootstrap commands, but every non-bootstrap command (`deploy`, `destroy`, `diff`, `synth`, `list`, `state`, `force-unlock`, `publish-assets`, `import`, `export`, `orphan`, `drift`, `events`, `local *`, …) actually consumes `options.region` as the highest-precedence region source: `const region = options.region || process.env['AWS_REGION'] || 'us-east-1'` feeds the provisioning / state-bucket SDK clients and the `applyRoleArnIfSet` STS hop, and `deploy` / `destroy` / `import` / `export` / `orphan` additionally inject it into `process.env.AWS_REGION` so the CDK synth subprocess inherits it (e.g. `deploy.ts` ~L167/L175/L341). The warning and the code therefore disagreed — a user passing `--region` was told it did nothing while it silently took effect. **Investigation determined `--region` IS legitimately honored everywhere (option B in the issue), so the fix is purely in the warning + help text — no command implementation (`deploy.ts` etc.) was touched**, keeping the change out of the `integ-broad` merge-gate scope and carrying zero behavior-change risk. The warning now reads "`--region is deprecated and will be removed in a future release. It is still honored for now (it overrides AWS_REGION / your AWS profile), but prefer the AWS_REGION environment variable or your AWS profile…`" and the option description drops the false "No effect" claim. The recommended mechanism is still `AWS_REGION` / the AWS profile; the flag stays hidden + deprecated, just honestly described. Docs corrected: two "deprecated and ignored" lines in [docs/cli-reference.md](cli-reference.md) and the `--region` bullet in [.claude/rules/cli-internals.md](../.claude/rules/cli-internals.md). Tests: `tests/unit/cli/options.test.ts` — the existing message assertion updated, plus new assertions that neither the warning nor the option description contains "no effect" and that both mention the flag is "still honored" (issue #818).
 - ✅ **`destroy` waits for NAT Gateway deletion before detaching / deleting the IGW + VPCGatewayAttachment (issue [#817](https://github.com/go-to-k/cdkd/issues/817))** — `src/analyzer/implicit-delete-deps.ts`. Destroying a VPC + NAT Gateway + IGW stack attempted the `VPCGatewayAttachment` detach while the NAT Gateway's Elastic IP was still mapped to the VPC's public address space, failing with `Network vpc-xxx has some mapped public address(es)`, after which the IGW delete hung (~19 min observed). This was the first-run failure split out of the #804 incident as a separate issue. The fix adds two type-based implicit delete-dependency edges so the shared deploy DELETE phase + standalone destroy command order the teardown like CloudFormation does: `AWS::EC2::InternetGateway` gains `AWS::EC2::NatGateway` (alongside its existing `AWS::EC2::VPCGatewayAttachment` dependee) and a new `AWS::EC2::VPCGatewayAttachment` key lists `AWS::EC2::NatGateway` — both are deleted AFTER the NAT Gateway is gone (NAT deletion releases / decouples the EIP). No type-based rule is needed for the EIP itself: the NAT Ref's its EIP via `AllocationId`, so the reversed delete traversal already deletes the NAT before the EIP is released. The injection logic (`destroy-runner.ts` / `deploy-engine.ts`) naturally produces no edge when no NatGateway is in state. Tests: 4 unit assertions in `tests/unit/analyzer/implicit-delete-deps.test.ts` (IGW-after-NAT edge, VPCGatewayAttachment-after-NAT edge, no NatGateway / EIP key registered; the existing no-self-cycle guard covers the new entries). Integ: the existing `vpc-nat-gateway` fixture (VPC + public/private subnets + IGW + NatGateway + EIP) exercises exactly this teardown end-to-end.