cdk-preflight 0.0.28 → 0.0.29

package/.claude/skills/find-preflight-rules/SKILL.md

@@ -51,11 +51,21 @@ CDK のプラグイン経路は `accountId` と `region` をエンジンに渡
 - テンプレート内の一意性。実測で **Export 名の重複はエンジン未検出**
 - スタック間の整合性。全スタックのテンプレートを一度に見られるのは我々だけ（`context.stackTemplates`）。ただし Rego はテンプレート単位で評価するので、実装は enforce プラグイン側（TypeScript）になる。**現状は未対応**なので、この種の候補が出たら設計変更の要否とセットで issue に書く
 
-### レンズ 5：集約・上限（多くはエンジン済み。必ず実測してから書く）
+### レンズ 5：集約・上限、および文字種・長さ（プロパティ単位で必ず実測）
 
-実測でエンジンが既に `FATAL` で止めていたもの、つまり**書いてはいけない**もの：リソース数 `F0007`、Output 数 `F0004`、テンプレートサイズ `E1002`、文字列長とパターン `F3031` / `F3033`。
+テンプレート全体に効く集約はエンジンが持っている：リソース数 `F0007`、Output 数 `F0004`、テンプレートサイズ `E1002`。論理 ID の長さは `I3012` の **INFO 止まり**（＝グレーゾーン）、Export 名の重複は検出なし。
 
-空いていたもの：論理 ID の長さは `I3012` の **INFO 止まり**（＝グレーゾーン）、Export 名の重複は検出なし。
+**文字種と長さ（`F3031` / `F3033`）を「エンジン済み」と一般化してはいけない**（2026-09-04、57 テンプレートで実測）。カバレッジは**スキーマがそのプロパティに pattern / maxLength を書いているかどうか**で決まるので、同じリソースの中でも非対称になる:
+
+| エンジンが止める | 素通り（＝候補） |
+|---|---|
+| `SecurityGroup.GroupDescription`（F3031） | **`SecurityGroupIngress[].Description`** |
+| DynamoDB GSI `IndexName`（F3031） | **`Table.TableName`** |
+| `IAM Role.Description`、`Lambda FunctionName`、`Events Rule.Name`、`S3 BucketName`、`Firehose DeliveryStreamName` | `ECS ClusterName/ServiceName/Family`、`ELBv2 Name`（LB/TG とも）、`Cognito UserPoolName/ClientName`、`Batch` の各名前、`SNS TopicName`、`SQS QueueName`、`RDS DBSubnetGroupName`、`CloudWatch Namespace`、`LaunchTemplateName` |
+
+しかも `SecurityGroupIngress[].Description` は CDK で日本語が最も入りやすい場所（`addIngressRule(peer, port, '説明')` の第 3 引数）。**プロパティ 1 つずつ重複ガードに掛けること。**
+
+そして「日本語なら落ちる」も成立しない。同じ「説明」でも RDS は non-printable 扱いで落ち、IAM ManagedPolicy・Lambda・CloudWatch AlarmDescription は通る。実機ゲートまで通して初めて候補が確定する。
 
 ### レンズ 6：時間で変わる制約（対象。ただし重複ガードを先に）
 

package/.jsii

@@ -9598,6 +9598,6 @@
       "symbolId": "src/index:PreflightOptions"
     }
   },
-  "version": "0.0.28",
-  "fingerprint": "fyyaGGeoMcLqWFI+MPfrrCIBeSIX9Z8OnWK77JFJpN0="
+  "version": "0.0.29",
+  "fingerprint": "56ha27pDnOg2btypvxrAXUJx727KVabcfRb2GtCwFuA="
 }

package/AGENTS.md

@@ -60,9 +60,16 @@ The ordering is by **how easily the L2 guard is bypassed in normal use**, not by
 
 ## Rule lifecycle: add fast, retire without ceremony
 
+The two failure modes are watched separately: **staleness** (the constraint disappeared at AWS — the fail template now deploys clean) is caught by the monthly real-deploy run and reported as BROKEN; **obsolescence** (the engine caught up — the rule is now a duplicate) is caught by the duplication guard and the redundancy scan and reported as REDUNDANT. Both land in the monthly issue.
+
 **Adding.** Two gates, both mechanical, and nothing else can reject a candidate: the duplication guard (`test/rules.test.ts`) and the real-deploy gate (`bench/verify-rule.sh`). The real-deploy gate is the one thing that did *not* get looser with the widened scope, and deliberately so — `enforce` is the default mode, so a false positive is a hard synth failure in someone's CI. The CloudFront survey is the standing evidence: 3 of 9 documented constraints deployed clean (see "A doc sentence is a hypothesis" above). Volume comes from running the bench over more services, never from lowering that bar.
 
-**Retiring.** The trigger is the bundled engine (or CloudFormation's server-side validation) starting to block the constraint — never an L2 construct, never cfn-lint. You do not have to watch for it: the duplication guard turns red on its own the first time an `aws-cdk-lib` bump brings an engine that reports ERROR/FATAL on the rule's fail template. Then:
+**Retiring.** The trigger is the bundled engine (or CloudFormation's server-side validation) starting to block the constraint — never an L2 construct, never cfn-lint. You do not have to watch for it; two mechanisms report it:
+
+- The jest duplication guard turns red on its own the first time an `aws-cdk-lib` bump brings an engine that reports ERROR/FATAL on a rule's fail template, and its failure message names the rule to delete.
+- `npx projen redundancy-scan` lists every such rule at once (no AWS account, no cost — it just re-runs each fail template through the bare engine). The monthly `monthly-verify` workflow runs it and files the results under a **REDUNDANT** heading in the same issue that reports drift, so obsolescence and staleness arrive on one page.
+
+Then:
 
 1. `rm -rf rules/<service>/<rule-id>/` — delete outright, no tombstone. `upstream: retired` exists for a rule mid-flight, not for a corpse.
 2. `npx projen bundle-rules` (regenerates `src/rules.generated.ts` and `docs/rules.md`).
@@ -128,4 +135,10 @@ bench/                      # real-deploy verification (needs an AWS account; no
 - **`net.cidr_*` builtins do not exist** in the engine's Rego build ("could not find func", measured 2026-09-03 on `net.cidr_contains` / `net.cidr_intersects` / `net.cidr_is_valid`). CIDR math must be hand-rolled: `split`, `to_number`, a 33-entry power-of-two table, and `floor` (which does exist). The gap matters less than it looks: the engine already ships cross-resource CIDR checks — subnet-not-within-VPC is `E3059` and sibling-subnet overlap is `E3060` (both fire on `Ref`-wired resources in one template).
 - The engine validates instance/node types **against the deploy region** when one is supplied via `validateDetailed(tpl, { pseudoParameterOverrides: { region } })` — `E3628` ('trn1.32xlarge' is not valid for region 'ap-northeast-1'), measured 2026-09-03. Without a region it validates against the union of all regions and emits `I9003`. The enforce plugin passes the region whenever the app's env is concrete, so region-availability rules for instance types belong to the engine, not this pack.
 - **`json.unmarshal` and `json.is_valid` exist** (measured 2026-09-03, 1.7.0-beta). Opaque JSON-in-a-string properties (CloudWatch `DashboardBody`) can be parsed and validated structurally in Rego — this is the lens-2 workhorse. Reference implementations: `pf-cloudwatch-dashboard-*`.
+- **The Rego regex builtins exist** (`regex.match`, `regex.is_valid`, `regex.find_n`, `regex.replace`) — but the engine is Rust, so its regex flavour is **not** the one AWS's published patterns assume. Two traps, both measured 2026-09-04, both of which shipped broken rules before they were caught:
+  - *Character classes are Unicode-aware.* `\w`, `\d` and `\s` match non-ASCII — `regex.match("[\\w]+", "テスト用")` is **true**. AWS API patterns like Cognito's `[\w\s+=,.@-]+` are ASCII-semantics, so copying one verbatim yields a rule that never fires. Write explicit ranges (`^[A-Za-z0-9_ \t+=,.@-]+$`).
+  - *No lookahead/lookbehind.* ELBv2 publishes `(?!^-)(?!.*-$)^[A-Za-z0-9-]+$` for `targetGroupName`; that pattern does not compile here, and `regex.match` then returns false for **every** input — the rule fires on all values, which is worse than not firing. Rewrite without lookaround: `^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$`.
+- **The absence sentinel must not be a string.** The `object.get(props, "<Key>", "__pf_absent")` idiom is only safe when the next step is `== "__pf_absent"`. If the next step is `is_string(v)` followed by a format check, an *absent* key yields the sentinel string and the rule fires on every resource that omits the property. Use `null` as the default in that case — `is_string(null)` is false, so the rule skips. (This produced three false-positive rules in the 2026-09-04 batch, visible only because other rules' pass fixtures went red.)
+- **Tuple destructuring in `some [a, b] in <array literal>` does not schedule** ("statements not scheduled in query", measured 2026-09-04). Iterating a table of pairs inline is not available; build a set with one helper rule per case and destructure that set (`some [name, path, v] in _pf_x_bad`), which does work.
+- **Schema pattern/length coverage is per property, not per resource or per service.** `AWS::EC2::SecurityGroup.GroupDescription` carries a pattern (`F3031`) while the rule-level `SecurityGroupIngress[].Description` on the same resource carries none; DynamoDB's GSI `IndexName` has one while the table's own `TableName` does not. Never generalise "the engine handles names/lengths" from a sample — probe the exact property (measured 2026-09-04 across 57 templates).
 - **Probing the raw engine with custom rules**: the rule set must be named `violation` (`data.<pkg>.violation` is looked up; a `diagnostics` set fails with "not a valid rule path"), and hand-built diagnostic objects need lowercase severities (`error`, not `ERROR`/`CUSTOM` — those are display labels added by the wrapper). Pack rules never see this because `make_diag_full` handles the shape.

package/lib/index.js

@@ -17,7 +17,7 @@ const rules_generated_1 = require("./rules.generated");
  * Preflight.apply(app);
  */
 class Preflight {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdk-preflight.Preflight", version: "0.0.28" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdk-preflight.Preflight", version: "0.0.29" };
     /**
      * Register the cdk-preflight rules on an App or Stage.
      */

package/package.json

@@ -27,6 +27,7 @@
     "post-compile": "projen post-compile",
     "post-upgrade": "projen post-upgrade",
     "pre-compile": "projen pre-compile",
+    "redundancy-scan": "projen redundancy-scan",
     "release": "projen release",
     "test": "projen test",
     "test:watch": "projen test:watch",
@@ -87,7 +88,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.28",
+  "version": "0.0.29",
   "jest": {
     "coverageProvider": "v8",
     "testMatch": [