cdk-preflight 0.0.92 → 0.0.94

package/.jsii

@@ -9416,7 +9416,7 @@
   },
   "name": "cdk-preflight",
   "readme": {
-    "markdown": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/badmintoncryer/cdk-preflight/main/assets/logo.png\" alt=\"cdk-preflight\" width=\"104\" height=\"104\">\n</p>\n\n<h1 align=\"center\">cdk-preflight</h1>\n\n<p align=\"center\">\n  <strong>Catch deploy-time CloudFormation failures at <code>cdk synth</code> time.</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/badmintoncryer/cdk-preflight/actions/workflows/monthly-verify.yml\"><img src=\"https://github.com/badmintoncryer/cdk-preflight/actions/workflows/monthly-verify.yml/badge.svg\" alt=\"monthly real-deploy verification\"></a>\n  <a href=\"https://www.npmjs.com/package/cdk-preflight\"><img src=\"https://img.shields.io/npm/v/cdk-preflight.svg\" alt=\"npm version\"></a>\n  <a href=\"https://www.npmjs.com/package/cdk-preflight\"><img src=\"https://img.shields.io/npm/dt/cdk-preflight.svg\" alt=\"npm total downloads\"></a>\n  <a href=\"docs/rules.md\"><img src=\"https://img.shields.io/badge/rules-1918-blue\" alt=\"1918 bundled rules\"></a>\n</p>\n\nSome CloudFormation constraints are not expressed in resource provider schemas — they live only in documentation, in service API validation, or across multiple properties. Templates that violate them pass `cdk synth`, pass CloudFormation pre-deployment validation, and then fail minutes into a deployment, burning a rollback cycle.\n\ncdk-preflight is a curated [Rego rule pack](docs/rules.md) for exactly those constraints, evaluated with the CloudFormation validation engine that ships inside `aws-cdk-lib` (>= 2.267.0). By default a violation **fails `cdk synth`** — a template that is known to fail at deploy time never leaves your machine.\n\nThe pack aims at **every deploy-time failure that no existing CDK mechanism already catches** — nothing narrower. Every bundled rule is backed by a `fail`/`pass` template pair, and the failure has been reproduced against real AWS. The handful of rules that could not be reproduced are marked `doc-only` and report as **warnings**: they show up in the validation report but never fail synth. Rules that the built-in validation engine already covers are deliberately **not** duplicated — a test suite enforces this.\n\n> **Requires `aws-cdk-lib` >= 2.267.0** (released 2026-08-27) — the first release that bundles\n> the CloudFormation validation engine. On older versions the rules cannot run at all.\n\n## Quick start\n\n```bash\nnpm i -D cdk-preflight\nnpx cdkpf init   # inserts Preflight.apply(app) into your CDK app\n                         # (`npx cdkpf init` is the same command, shorter)\n```\n\nor add one line yourself:\n\n```ts\nimport { Preflight } from 'cdk-preflight';\n\nconst app = new App();\nPreflight.apply(app);\n```\n\nOn violation, `cdk synth` fails with one error per finding, including the construct trace:\n\n```text\nERROR idle_timeout.timeout_seconds is 5000 but must be between 1 and 4000 seconds (cdk-preflight)\n   MyStack/Alb/Resource (Alb16C2F182) aws-cdk-lib.aws_elasticloadbalancingv2.CfnLoadBalancer\n\nSynthesis finished with errors\n```\n\n## What it catches\n\nFour ordinary-looking snippets. All of them pass `cdk synth` and CloudFormation\npre-deployment validation, and all of them fail minutes into a deployment:\n\n```ts\n// 1) pf-iam-inline-policy-size — enumerate buckets, grant each one, blow past 10,240 chars\n//    \"Maximum policy size of 10240 bytes exceeded for role IngestRole\"\n//    (via role.addToPolicy the CDK auto-splits into managed policies instead,\n//     and you hit the 6,144-char limit as pf-iam-managed-policy-size)\nnew iam.Policy(this, 'IngestPolicy', {\n  roles: [role],\n  statements: [new iam.PolicyStatement({\n    actions: ['s3:GetObject', 's3:ListBucket'],\n    resources: Array.from({ length: 200 },\n      (_, i) => `arn:aws:s3:::data-lake-landing-zone-${i}/year=*/month=*/*`),\n  })],\n});\n\n// 2) pf-lambda-env-size — a config blob in the environment, over the 4KB total\n//    \"Lambda was unable to configure your environment variables because the\n//     environment variables you have provided exceeded the 4KB limit\"\nnew lambda.Function(this, 'Fn', {\n  runtime: lambda.Runtime.NODEJS_22_X,\n  handler: 'index.handler',\n  code: lambda.Code.fromInline('exports.handler = async () => {};'),\n  environment: { FEATURE_FLAGS: JSON.stringify(bigFeatureFlagMap) },\n});\n\n// 3) pf-sfn-asl-missing-state (+ pf-sfn-asl-unreachable-state) — a typo in a state name\n//    \"Invalid State Machine Definition: 'MISSING_TRANSITION_TARGET: ...'\"\nnew sfn.StateMachine(this, 'Pipeline', {\n  definitionBody: sfn.DefinitionBody.fromString(JSON.stringify({\n    StartAt: 'Validate',\n    States: {\n      Validate: { Type: 'Pass', Next: 'Transform' },\n      Trasform: { Type: 'Pass', End: true },   // typo: Transform\n    },\n  })),\n});\n\n// 4) pf-logs-filter-pattern-bracket — a filter pattern opened with '[' and never closed\n//    \"If a filter pattern starts with '[' it must end with ']'\"\nnew logs.MetricFilter(this, 'ErrorFilter', {\n  logGroup,\n  metricNamespace: 'Pipeline',\n  metricName: 'Errors',\n  filterPattern: logs.FilterPattern.literal('[time, level=ERROR, msg'),\n});\n```\n\nNone of these are type errors, so the L2 constructs accept them; none of them are\nexpressible in a resource schema, so CloudFormation accepts the template. With\n`Preflight.apply(app)` in place they fail `cdk synth` instead.\n\n## Observe-only mode\n\nTo roll the rules out gradually, start with `enforce: false`: findings then surface as synth **warnings** through the CDK built-in validator, with construct traces and per-finding acknowledgement:\n\n```ts\nPreflight.apply(app, { enforce: false });\n```\n\n```text\nWARNING idle_timeout.timeout_seconds is 5000 but must be between 1 and 4000 seconds (CloudFormation Validate)\n   MyStack/Alb (Alb) aws-cdk-lib.aws_elasticloadbalancingv2.CfnLoadBalancer\n   Acknowledge with 'CloudFormation-Validate::pf-elbv2-lb-idle-timeout-range'\n```\n\n> **Known limitation with stages.** The AWS CDK CLI drops validation findings for stacks nested in a `Stage`\n> before printing them, so in observe-only mode those findings appear **only** in `cdk.out/validation-report.json`\n> and never on the console. Enforce mode is not affected: cdk-preflight reports such findings itself and fails\n> synthesis. This is a CLI-side bug (present since aws-cdk 2.1128.1), not a rule evaluation problem.\n\n> **If the rules cannot run, the build stops.** When the evaluation engine fails on a template (a rule pack that\n> does not compile, an engine bug), enforce mode reports it as a violation named `pf-engine-error` and fails\n> synthesis for that stack instead of passing green with no rule having run. The other stacks keep their rules.\n> `pf-engine-error` is not a bundled rule and cannot be `exclude`d; `enforce: false` unblocks the build if you\n> need one.\n\n| Option | Default | Effect |\n|---|---|---|\n| `enforce` | `true` | Violations of bundled rules fail synthesis; set to `false` to only warn |\n| `strict` | `false` | With `enforce`: also fail on error-class findings (`ERROR`/`FATAL`, e.g. `F3034`) of the built-in validation engine itself, which the CDK currently downgrades to warnings |\n| `exclude` | `[]` | Rule ids to disable |\n| `includeUpstreamPending` | `true` | Include rules already proposed to the upstream engine but not yet merged |\n\nTo opt out of a single rule everywhere, pass its id in `exclude`. To suppress a\nsingle *finding* on one construct, acknowledge it — this works in both modes, the\nid prefix just differs (`cdk-preflight::` when enforcing, `CloudFormation-Validate::`\nin observe-only, as printed in the warning text):\n\n```ts\ncdk.Validations.of(errorFilter).acknowledge({\n  id: 'cdk-preflight::pf-logs-filter-pattern-bracket',\n  reason: 'log group is written by a legacy producer; pattern is fixed upstream',\n});\n```\n\n## Bundled rules\n\nSee [docs/rules.md](docs/rules.md) for the generated rule table. Highlights:\n\n- **ELBv2**: `idle_timeout` / `deregistration_delay` / `slow_start` attribute ranges (stringly-typed Key/Value attributes are invisible to schema validation)\n- **IAM**: managed (6,144 chars) and inline (role/group/user) policy document size limits\n- **CloudFront**: `MinTTL <= DefaultTTL <= MaxTTL` ordering, ACM certificates must live in `us-east-1`\n- **Step Functions**: `Next`/`Default`/`Choices` must reference defined states (a dangling `StartAt` is already caught by the engine's built-in `E3601`)\n- **EC2**: security group TCP/UDP port ranges and `FromPort <= ToPort`\n\n## For AI agents\n\nTo add cdk-preflight to a CDK app:\n\n1. `npm i -D cdk-preflight`\n2. `npx cdk-preflight init` — or the shorter alias `npx cdkpf init` (finds the entry point via `cdk.json` and inserts `Preflight.apply(app)`; use `--dry-run` to preview)\n3. Run `cdk synth`. Violations fail the synth with a validation report; each finding carries a rule id, the actual value, and a suggested fix\n4. To fix a finding, prefer correcting the resource. To opt out instead: `exclude: ['<rule-id>']` disables one rule, `enforce: false` switches to warn-only reporting\n\nThe machine-readable findings are written to `cdk.out/validation-report.json` when synthesizing with `-c @aws-cdk/core:validationReportJson=true`.\n\n### Report missed deploy errors\n\ncdk-preflight only knows the failure modes it has benched. When a deploy fails on a constraint the pack should have caught, that report is how new rules get added — but at that moment cdk-preflight is out of the loop (it passed the synth), so the instruction has to already sit in your agent's context. Paste this into your repository's `AGENTS.md` (or `CLAUDE.md`):\n\n```markdown\n## cdk-preflight: report missed deploy errors\n\nIf `cdk deploy` fails even though `cdk synth` (with cdk-preflight enabled) passed,\nand the failure is a service-side validation rejection — CREATE_FAILED/UPDATE_FAILED\nwith a 400-class message such as \"Invalid request provided: ...\" — cdk-preflight is\nmissing a rule. Report it:\n\n1. Qualify first. NOT reportable: AccessDenied / permissions, service quotas,\n   throttling, name conflicts with existing resources, stabilization timeouts.\n2. Redact account-specific data (account IDs -> 123456789012, real ARNs/domains\n   -> placeholders).\n3. Search existing issues: https://github.com/badmintoncryer/cdk-preflight/issues\n4. With your user's approval, open a \"Missed deploy error\" issue with the verbatim\n   error message, the resource type, a minimal template snippet, and your\n   aws-cdk-lib / cdk-preflight versions.\n```\n\n## Scope and rule lifecycle\n\nA constraint belongs in the pack when violating it makes a real deployment fail *and* no layer that sees the same synthesized template already blocks it. There is no further \"is this worth a rule\" question — if the gap is real, it gets a rule.\n\nCDK L2 construct validation is deliberately **not** one of those layers. `CfnXxx` usage, escape hatches, `addPropertyOverride`, `cloudformation-include` and migrated templates all bypass L2, so an L2 guard covering the same mistake neither disqualifies a rule nor retires one.\n\nThat makes growth the normal state, and it has a consequence worth knowing before you upgrade: **new rules land in minor releases, so a minor upgrade can newly fail a `cdk synth` that passed yesterday.** That is intended, not a regression. If you need a frozen rule set, pin the version; to drop a single rule, `exclude: ['<rule-id>']`; to see everything without failing the build, `enforce: false`.\n\nRules move the other way too. Once the validation engine bundled in `aws-cdk-lib` (or CloudFormation's own pre-deploy validation) starts blocking a constraint, the rule is deleted rather than kept as a duplicate — staying on an older `aws-cdk-lib` and an older cdk-preflight keeps the old behavior.\n\n## How it works\n\n`Preflight.apply()` evaluates the rules with the [cloudformation-validate](https://github.com/aws-cloudformation/cloudformation-validate) Rust/WASM engine that ships inside `aws-cdk-lib` — no extra binaries, no network access at synth time. In the default enforce mode the engine is invoked through a dedicated CDK validation plugin so that violations fail synthesis; with `enforce: false` the rules are instead injected into the CDK built-in `CloudFormationValidatePlugin` and reported as warnings.\n\nConstraints that *can* be expressed in schemas or generic engine rules also make good upstream PRs to that engine, but nothing here waits on one — the upstream release cycle is deliberately slower than this pack's. Each rule's `meta.yaml` tracks its upstream status so that retirement stays bookkeeping.\n\n## Requirements\n\n- `aws-cdk-lib` >= 2.267.0, released 2026-08-27 (the first release that bundles the built-in CloudFormation validator). This is a recent release — an existing CDK app may need an upgrade before cdk-preflight can run.\n\n## Contributing\n\nRule authoring, the verification gates (including real-deploy reproduction), and the test layout are documented in [AGENTS.md](AGENTS.md) — written for AI coding agents and humans alike.\n\n## License\n\nApache-2.0\n"
+    "markdown": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/badmintoncryer/cdk-preflight/main/assets/logo.png\" alt=\"cdk-preflight\" width=\"104\" height=\"104\">\n</p>\n\n<h1 align=\"center\">cdk-preflight</h1>\n\n<p align=\"center\">\n  <strong>Catch deploy-time CloudFormation failures at <code>cdk synth</code> time.</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/badmintoncryer/cdk-preflight/actions/workflows/monthly-verify.yml\"><img src=\"https://github.com/badmintoncryer/cdk-preflight/actions/workflows/monthly-verify.yml/badge.svg\" alt=\"monthly real-deploy verification\"></a>\n  <a href=\"https://www.npmjs.com/package/cdk-preflight\"><img src=\"https://img.shields.io/npm/v/cdk-preflight.svg\" alt=\"npm version\"></a>\n  <a href=\"https://www.npmjs.com/package/cdk-preflight\"><img src=\"https://img.shields.io/npm/dt/cdk-preflight.svg\" alt=\"npm total downloads\"></a>\n  <a href=\"docs/rules.md\"><img src=\"https://img.shields.io/badge/rules-1986-blue\" alt=\"1986 bundled rules\"></a>\n</p>\n\nSome CloudFormation constraints are not expressed in resource provider schemas — they live only in documentation, in service API validation, or across multiple properties. Templates that violate them pass `cdk synth`, pass CloudFormation pre-deployment validation, and then fail minutes into a deployment, burning a rollback cycle.\n\ncdk-preflight is a curated [Rego rule pack](docs/rules.md) for exactly those constraints, evaluated with the CloudFormation validation engine that ships inside `aws-cdk-lib` (>= 2.267.0). By default a violation **fails `cdk synth`** — a template that is known to fail at deploy time never leaves your machine.\n\nThe pack aims at **every deploy-time failure that no existing CDK mechanism already catches** — nothing narrower. Every bundled rule is backed by a `fail`/`pass` template pair, and the failure has been reproduced against real AWS. The handful of rules that could not be reproduced are marked `doc-only` and report as **warnings**: they show up in the validation report but never fail synth. Rules that the built-in validation engine already covers are deliberately **not** duplicated — a test suite enforces this.\n\n> **Requires `aws-cdk-lib` >= 2.267.0** (released 2026-08-27) — the first release that bundles\n> the CloudFormation validation engine. On older versions the rules cannot run at all.\n\n## Quick start\n\n```bash\nnpm i -D cdk-preflight\nnpx cdkpf init   # inserts Preflight.apply(app) into your CDK app\n                         # (`npx cdkpf init` is the same command, shorter)\n```\n\nor add one line yourself:\n\n```ts\nimport { Preflight } from 'cdk-preflight';\n\nconst app = new App();\nPreflight.apply(app);\n```\n\nOn violation, `cdk synth` fails with one error per finding, including the construct trace:\n\n```text\nERROR idle_timeout.timeout_seconds is 5000 but must be between 1 and 4000 seconds (cdk-preflight)\n   MyStack/Alb/Resource (Alb16C2F182) aws-cdk-lib.aws_elasticloadbalancingv2.CfnLoadBalancer\n\nSynthesis finished with errors\n```\n\n## What it catches\n\nFour ordinary-looking snippets. All of them pass `cdk synth` and CloudFormation\npre-deployment validation, and all of them fail minutes into a deployment:\n\n```ts\n// 1) pf-iam-inline-policy-size — enumerate buckets, grant each one, blow past 10,240 chars\n//    \"Maximum policy size of 10240 bytes exceeded for role IngestRole\"\n//    (via role.addToPolicy the CDK auto-splits into managed policies instead,\n//     and you hit the 6,144-char limit as pf-iam-managed-policy-size)\nnew iam.Policy(this, 'IngestPolicy', {\n  roles: [role],\n  statements: [new iam.PolicyStatement({\n    actions: ['s3:GetObject', 's3:ListBucket'],\n    resources: Array.from({ length: 200 },\n      (_, i) => `arn:aws:s3:::data-lake-landing-zone-${i}/year=*/month=*/*`),\n  })],\n});\n\n// 2) pf-lambda-env-size — a config blob in the environment, over the 4KB total\n//    \"Lambda was unable to configure your environment variables because the\n//     environment variables you have provided exceeded the 4KB limit\"\nnew lambda.Function(this, 'Fn', {\n  runtime: lambda.Runtime.NODEJS_22_X,\n  handler: 'index.handler',\n  code: lambda.Code.fromInline('exports.handler = async () => {};'),\n  environment: { FEATURE_FLAGS: JSON.stringify(bigFeatureFlagMap) },\n});\n\n// 3) pf-sfn-asl-missing-state (+ pf-sfn-asl-unreachable-state) — a typo in a state name\n//    \"Invalid State Machine Definition: 'MISSING_TRANSITION_TARGET: ...'\"\nnew sfn.StateMachine(this, 'Pipeline', {\n  definitionBody: sfn.DefinitionBody.fromString(JSON.stringify({\n    StartAt: 'Validate',\n    States: {\n      Validate: { Type: 'Pass', Next: 'Transform' },\n      Trasform: { Type: 'Pass', End: true },   // typo: Transform\n    },\n  })),\n});\n\n// 4) pf-logs-filter-pattern-bracket — a filter pattern opened with '[' and never closed\n//    \"If a filter pattern starts with '[' it must end with ']'\"\nnew logs.MetricFilter(this, 'ErrorFilter', {\n  logGroup,\n  metricNamespace: 'Pipeline',\n  metricName: 'Errors',\n  filterPattern: logs.FilterPattern.literal('[time, level=ERROR, msg'),\n});\n```\n\nNone of these are type errors, so the L2 constructs accept them; none of them are\nexpressible in a resource schema, so CloudFormation accepts the template. With\n`Preflight.apply(app)` in place they fail `cdk synth` instead.\n\n## Observe-only mode\n\nTo roll the rules out gradually, start with `enforce: false`: findings then surface as synth **warnings** through the CDK built-in validator, with construct traces and per-finding acknowledgement:\n\n```ts\nPreflight.apply(app, { enforce: false });\n```\n\n```text\nWARNING idle_timeout.timeout_seconds is 5000 but must be between 1 and 4000 seconds (CloudFormation Validate)\n   MyStack/Alb (Alb) aws-cdk-lib.aws_elasticloadbalancingv2.CfnLoadBalancer\n   Acknowledge with 'CloudFormation-Validate::pf-elbv2-lb-idle-timeout-range'\n```\n\n> **Known limitation with stages.** The AWS CDK CLI drops validation findings for stacks nested in a `Stage`\n> before printing them, so in observe-only mode those findings appear **only** in `cdk.out/validation-report.json`\n> and never on the console. Enforce mode is not affected: cdk-preflight reports such findings itself and fails\n> synthesis. This is a CLI-side bug (present since aws-cdk 2.1128.1), not a rule evaluation problem.\n\n> **If the rules cannot run, the build stops.** When the evaluation engine fails on a template (a rule pack that\n> does not compile, an engine bug), enforce mode reports it as a violation named `pf-engine-error` and fails\n> synthesis for that stack instead of passing green with no rule having run. The other stacks keep their rules.\n> `pf-engine-error` is not a bundled rule and cannot be `exclude`d; `enforce: false` unblocks the build if you\n> need one.\n\n| Option | Default | Effect |\n|---|---|---|\n| `enforce` | `true` | Violations of bundled rules fail synthesis; set to `false` to only warn |\n| `strict` | `false` | With `enforce`: also fail on error-class findings (`ERROR`/`FATAL`, e.g. `F3034`) of the built-in validation engine itself, which the CDK currently downgrades to warnings |\n| `exclude` | `[]` | Rule ids to disable |\n| `includeUpstreamPending` | `true` | Include rules already proposed to the upstream engine but not yet merged |\n\nTo opt out of a single rule everywhere, pass its id in `exclude`. To suppress a\nsingle *finding* on one construct, acknowledge it — this works in both modes, the\nid prefix just differs (`cdk-preflight::` when enforcing, `CloudFormation-Validate::`\nin observe-only, as printed in the warning text):\n\n```ts\ncdk.Validations.of(errorFilter).acknowledge({\n  id: 'cdk-preflight::pf-logs-filter-pattern-bracket',\n  reason: 'log group is written by a legacy producer; pattern is fixed upstream',\n});\n```\n\n## Bundled rules\n\nSee [docs/rules.md](docs/rules.md) for the generated rule table. Highlights:\n\n- **ELBv2**: `idle_timeout` / `deregistration_delay` / `slow_start` attribute ranges (stringly-typed Key/Value attributes are invisible to schema validation)\n- **IAM**: managed (6,144 chars) and inline (role/group/user) policy document size limits\n- **CloudFront**: `MinTTL <= DefaultTTL <= MaxTTL` ordering, ACM certificates must live in `us-east-1`\n- **Step Functions**: `Next`/`Default`/`Choices` must reference defined states (a dangling `StartAt` is already caught by the engine's built-in `E3601`)\n- **EC2**: security group TCP/UDP port ranges and `FromPort <= ToPort`\n\n## For AI agents\n\nTo add cdk-preflight to a CDK app:\n\n1. `npm i -D cdk-preflight`\n2. `npx cdk-preflight init` — or the shorter alias `npx cdkpf init` (finds the entry point via `cdk.json` and inserts `Preflight.apply(app)`; use `--dry-run` to preview)\n3. Run `cdk synth`. Violations fail the synth with a validation report; each finding carries a rule id, the actual value, and a suggested fix\n4. To fix a finding, prefer correcting the resource. To opt out instead: `exclude: ['<rule-id>']` disables one rule, `enforce: false` switches to warn-only reporting\n\nThe machine-readable findings are written to `cdk.out/validation-report.json` when synthesizing with `-c @aws-cdk/core:validationReportJson=true`.\n\n### Report missed deploy errors\n\ncdk-preflight only knows the failure modes it has benched. When a deploy fails on a constraint the pack should have caught, that report is how new rules get added — but at that moment cdk-preflight is out of the loop (it passed the synth), so the instruction has to already sit in your agent's context. Paste this into your repository's `AGENTS.md` (or `CLAUDE.md`):\n\n```markdown\n## cdk-preflight: report missed deploy errors\n\nIf `cdk deploy` fails even though `cdk synth` (with cdk-preflight enabled) passed,\nand the failure is a service-side validation rejection — CREATE_FAILED/UPDATE_FAILED\nwith a 400-class message such as \"Invalid request provided: ...\" — cdk-preflight is\nmissing a rule. Report it:\n\n1. Qualify first. NOT reportable: AccessDenied / permissions, service quotas,\n   throttling, name conflicts with existing resources, stabilization timeouts.\n2. Redact account-specific data (account IDs -> 123456789012, real ARNs/domains\n   -> placeholders).\n3. Search existing issues: https://github.com/badmintoncryer/cdk-preflight/issues\n4. With your user's approval, open a \"Missed deploy error\" issue with the verbatim\n   error message, the resource type, a minimal template snippet, and your\n   aws-cdk-lib / cdk-preflight versions.\n```\n\n## Scope and rule lifecycle\n\nA constraint belongs in the pack when violating it makes a real deployment fail *and* no layer that sees the same synthesized template already blocks it. There is no further \"is this worth a rule\" question — if the gap is real, it gets a rule.\n\nCDK L2 construct validation is deliberately **not** one of those layers. `CfnXxx` usage, escape hatches, `addPropertyOverride`, `cloudformation-include` and migrated templates all bypass L2, so an L2 guard covering the same mistake neither disqualifies a rule nor retires one.\n\nThat makes growth the normal state, and it has a consequence worth knowing before you upgrade: **new rules land in minor releases, so a minor upgrade can newly fail a `cdk synth` that passed yesterday.** That is intended, not a regression. If you need a frozen rule set, pin the version; to drop a single rule, `exclude: ['<rule-id>']`; to see everything without failing the build, `enforce: false`.\n\nRules move the other way too. Once the validation engine bundled in `aws-cdk-lib` (or CloudFormation's own pre-deploy validation) starts blocking a constraint, the rule is deleted rather than kept as a duplicate — staying on an older `aws-cdk-lib` and an older cdk-preflight keeps the old behavior.\n\n## How it works\n\n`Preflight.apply()` evaluates the rules with the [cloudformation-validate](https://github.com/aws-cloudformation/cloudformation-validate) Rust/WASM engine that ships inside `aws-cdk-lib` — no extra binaries, no network access at synth time. In the default enforce mode the engine is invoked through a dedicated CDK validation plugin so that violations fail synthesis; with `enforce: false` the rules are instead injected into the CDK built-in `CloudFormationValidatePlugin` and reported as warnings.\n\nConstraints that *can* be expressed in schemas or generic engine rules also make good upstream PRs to that engine, but nothing here waits on one — the upstream release cycle is deliberately slower than this pack's. Each rule's `meta.yaml` tracks its upstream status so that retirement stays bookkeeping.\n\n## Requirements\n\n- `aws-cdk-lib` >= 2.267.0, released 2026-08-27 (the first release that bundles the built-in CloudFormation validator). This is a recent release — an existing CDK app may need an upgrade before cdk-preflight can run.\n\n## Contributing\n\nRule authoring, the verification gates (including real-deploy reproduction), and the test layout are documented in [AGENTS.md](AGENTS.md) — written for AI coding agents and humans alike.\n\n## License\n\nApache-2.0\n"
   },
   "repository": {
     "type": "git",
@@ -9600,6 +9600,6 @@
       "symbolId": "src/index:PreflightOptions"
     }
   },
-  "version": "0.0.92",
-  "fingerprint": "NbXncTMvlWgLHvXcL3XO4/JWV1NhrGSx8nN8xxspMLE="
+  "version": "0.0.94",
+  "fingerprint": "LJqIYqn5fMknjEaRRkwzrQJrU7FkpXHynR77ctHJMyM="
 }

package/README.md

@@ -12,7 +12,7 @@
   <a href="https://github.com/badmintoncryer/cdk-preflight/actions/workflows/monthly-verify.yml"><img src="https://github.com/badmintoncryer/cdk-preflight/actions/workflows/monthly-verify.yml/badge.svg" alt="monthly real-deploy verification"></a>
   <a href="https://www.npmjs.com/package/cdk-preflight"><img src="https://img.shields.io/npm/v/cdk-preflight.svg" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/cdk-preflight"><img src="https://img.shields.io/npm/dt/cdk-preflight.svg" alt="npm total downloads"></a>
-  <a href="docs/rules.md"><img src="https://img.shields.io/badge/rules-1918-blue" alt="1918 bundled rules"></a>
+  <a href="docs/rules.md"><img src="https://img.shields.io/badge/rules-1986-blue" alt="1986 bundled rules"></a>
 </p>
 
 Some CloudFormation constraints are not expressed in resource provider schemas — they live only in documentation, in service API validation, or across multiple properties. Templates that violate them pass `cdk synth`, pass CloudFormation pre-deployment validation, and then fail minutes into a deployment, burning a rollback cycle.

package/docs/rules.md

@@ -212,10 +212,78 @@
 | `pf-batch-fargate-cpu-memory` | AWS::Batch::JobDefinition | Fargate job definitions must use a supported vCPU/memory combination | ERROR | none |
 | `pf-batch-fargate-execution-role` | AWS::Batch::JobDefinition | Fargate job definitions require ExecutionRoleArn | ERROR | none |
 | `pf-batch-fargate-multinode` | AWS::Batch::JobDefinition | Multi-node parallel jobs are not supported on Fargate | ERROR | none |
+| `pf-batch-jd-consumable-resource-duplicate` | AWS::Batch::JobDefinition | A job must not declare the same consumable resource twice | ERROR | none |
+| `pf-batch-jd-consumable-resource-list-max` | AWS::Batch::JobDefinition | A job may declare at most 5 consumable resources | ERROR | none |
+| `pf-batch-jd-container-type-requires-props` | AWS::Batch::JobDefinition | A container job definition must carry one of the container property blocks | ERROR | none |
+| `pf-batch-jd-device-permissions-value` | AWS::Batch::JobDefinition | Device.Permissions must be READ, WRITE or MKNOD | ERROR | none |
+| `pf-batch-jd-ecs-container-name-unique` | AWS::Batch::JobDefinition | Container names must be unique within a task element | ERROR | none |
+| `pf-batch-jd-ecs-depends-on-condition-value` | AWS::Batch::JobDefinition | DependsOn.Condition must be START, COMPLETE or SUCCESS | ERROR | none |
+| `pf-batch-jd-ecs-depends-on-container-exists` | AWS::Batch::JobDefinition | DependsOn must name a container in the same task element | ERROR | none |
+| `pf-batch-jd-ecs-depends-on-essential-complete` | AWS::Batch::JobDefinition | COMPLETE and SUCCESS dependencies cannot target an essential container | ERROR | none |
+| `pf-batch-jd-ecs-depends-on-single-container` | AWS::Batch::JobDefinition | Container dependencies need more than one container | ERROR | none |
+| `pf-batch-jd-ecs-essential-required` | AWS::Batch::JobDefinition | An ECS task element needs one essential container | ERROR | none |
+| `pf-batch-jd-ecs-fargate-execution-role` | AWS::Batch::JobDefinition | Fargate task properties require an execution role | ERROR | none |
+| `pf-batch-jd-ecs-firelens-log-driver` | AWS::Batch::JobDefinition | A Firelens task needs a container using the awsfirelens log driver | ERROR | none |
+| `pf-batch-jd-ecs-ipc-mode-value` | AWS::Batch::JobDefinition | EcsTaskProperties.IpcMode must be host, task or none | ERROR | none |
+| `pf-batch-jd-ecs-pid-mode-value` | AWS::Batch::JobDefinition | EcsTaskProperties.PidMode must be host or task | ERROR | none |
+| `pf-batch-jd-ecs-task-containers-max` | AWS::Batch::JobDefinition | An ECS task element supports at most 10 containers | ERROR | none |
+| `pf-batch-jd-ecs-task-containers-required` | AWS::Batch::JobDefinition | An ECS task element must define at least one container | ERROR | none |
+| `pf-batch-jd-efs-access-point-root-directory` | AWS::Batch::JobDefinition | An EFS access point forces the root directory to / | ERROR | none |
+| `pf-batch-jd-efs-access-point-transit-encryption` | AWS::Batch::JobDefinition | An EFS access point requires transit encryption | ERROR | none |
+| `pf-batch-jd-efs-file-system-id-format` | AWS::Batch::JobDefinition | EFS FileSystemId must be an fs- identifier | ERROR | none |
+| `pf-batch-jd-efs-iam-transit-encryption` | AWS::Batch::JobDefinition | EFS IAM authorization requires transit encryption | ERROR | none |
+| `pf-batch-jd-efs-transit-encryption-port-range` | AWS::Batch::JobDefinition | EFS TransitEncryptionPort must be a valid port number | ERROR | none |
+| `pf-batch-jd-env-name-required` | AWS::Batch::JobDefinition | Every Environment entry needs a Name | ERROR | none |
+| `pf-batch-jd-evaluate-on-exit-condition-required` | AWS::Batch::JobDefinition | Each EvaluateOnExit entry needs at least one condition | ERROR | none |
+| `pf-batch-jd-evaluate-on-exit-exitcode-format` | AWS::Batch::JobDefinition | EvaluateOnExit.OnExitCode accepts only digits and * | ERROR | none |
+| `pf-batch-jd-evaluate-on-exit-pattern-length` | AWS::Batch::JobDefinition | EvaluateOnExit conditions are limited to 512 characters | ERROR | none |
+| `pf-batch-jd-evaluate-on-exit-requires-attempts` | AWS::Batch::JobDefinition | RetryStrategy.EvaluateOnExit requires Attempts | ERROR | none |
+| `pf-batch-jd-fargate-efs-platform-version` | AWS::Batch::JobDefinition | EFS volumes on Fargate require platform version 1.4.0 or later | ERROR | none |
+| `pf-batch-jd-fargate-ephemeral-storage-range` | AWS::Batch::JobDefinition | Fargate ephemeral storage must be between 21 and 200 GiB | ERROR | none |
+| `pf-batch-jd-fargate-linux-devices` | AWS::Batch::JobDefinition | LinuxParameters.Devices is not supported on Fargate | ERROR | none |
+| `pf-batch-jd-fargate-log-driver` | AWS::Batch::JobDefinition | Fargate jobs support only the awslogs, splunk and awsfirelens log drivers | ERROR | none |
+| `pf-batch-jd-fargate-max-swap` | AWS::Batch::JobDefinition | LinuxParameters.MaxSwap is not supported on Fargate | ERROR | none |
+| `pf-batch-jd-fargate-platform-config-on-ec2` | AWS::Batch::JobDefinition | FargatePlatformConfiguration is not applicable to EC2 jobs | ERROR | none |
+| `pf-batch-jd-fargate-privileged` | AWS::Batch::JobDefinition | Privileged is not supported on Fargate | ERROR | none |
+| `pf-batch-jd-fargate-shared-memory-size` | AWS::Batch::JobDefinition | LinuxParameters.SharedMemorySize is not supported on Fargate | ERROR | none |
+| `pf-batch-jd-fargate-swappiness` | AWS::Batch::JobDefinition | LinuxParameters.Swappiness is not supported on Fargate | ERROR | none |
+| `pf-batch-jd-fargate-tmpfs` | AWS::Batch::JobDefinition | LinuxParameters.Tmpfs is not supported on Fargate | ERROR | none |
+| `pf-batch-jd-fargate-ulimits` | AWS::Batch::JobDefinition | Ulimits are not supported on Fargate | ERROR | none |
+| `pf-batch-jd-fargate-volume-host-source-path` | AWS::Batch::JobDefinition | Volume Host.SourcePath is not supported on Fargate | ERROR | none |
+| `pf-batch-jd-legacy-and-resource-requirements` | AWS::Batch::JobDefinition | The legacy Vcpus/Memory fields cannot be combined with ResourceRequirements | ERROR | none |
+| `pf-batch-jd-linux-max-swap-negative` | AWS::Batch::JobDefinition | LinuxParameters.MaxSwap must not be negative | ERROR | none |
+| `pf-batch-jd-linux-swappiness-range` | AWS::Batch::JobDefinition | LinuxParameters.Swappiness must be between 0 and 100 | ERROR | none |
+| `pf-batch-jd-log-awslogs-unknown-option` | AWS::Batch::JobDefinition | The awslogs driver takes only the documented options | ERROR | none |
+| `pf-batch-jd-max-swap-requires-swappiness` | AWS::Batch::JobDefinition | LinuxParameters.MaxSwap requires Swappiness | ERROR | none |
+| `pf-batch-jd-memory-minimum` | AWS::Batch::JobDefinition | ContainerProperties.Memory must be at least 4 MiB | ERROR | none |
+| `pf-batch-jd-mi-os-family-linux` | AWS::Batch::JobDefinition | ECS Managed Instances jobs only support the LINUX operating system family | ERROR | none |
+| `pf-batch-jd-mi-requires-ecs-properties` | AWS::Batch::JobDefinition | MANAGED_INSTANCES job definitions must use EcsProperties | ERROR | none |
+| `pf-batch-jd-multinode-requires-node-properties` | AWS::Batch::JobDefinition | A multinode job definition requires NodeProperties | ERROR | none |
 | `pf-batch-jd-name` | AWS::Batch::JobDefinition | Job definition names allow only letters, numbers, hyphen and underscore | ERROR | none |
+| `pf-batch-jd-platform-capabilities-single` | AWS::Batch::JobDefinition | PlatformCapabilities takes exactly one value | ERROR | none |
+| `pf-batch-jd-platform-capability-value` | AWS::Batch::JobDefinition | PlatformCapabilities accepts only EC2, FARGATE and MANAGED_INSTANCES | ERROR | none |
+| `pf-batch-jd-props-container-and-ecs` | AWS::Batch::JobDefinition | ContainerProperties and EcsProperties are mutually exclusive | ERROR | none |
+| `pf-batch-jd-props-container-and-eks` | AWS::Batch::JobDefinition | ContainerProperties and EksProperties are mutually exclusive | ERROR | none |
+| `pf-batch-jd-props-ecs-and-eks` | AWS::Batch::JobDefinition | EcsProperties and EksProperties are mutually exclusive | ERROR | none |
+| `pf-batch-jd-resource-requirements-duplicate-type` | AWS::Batch::JobDefinition | ResourceRequirements must not repeat a type | ERROR | none |
+| `pf-batch-jd-resource-requirements-gpu-integer` | AWS::Batch::JobDefinition | A GPU resource requirement must be a whole number | ERROR | none |
+| `pf-batch-jd-resource-requirements-gpu-not-fargate` | AWS::Batch::JobDefinition | GPU resource requirements are not supported on Fargate | ERROR | none |
+| `pf-batch-jd-resource-requirements-required` | AWS::Batch::JobDefinition | A container job definition must request VCPU | ERROR | none |
+| `pf-batch-jd-resource-requirements-vcpu-min` | AWS::Batch::JobDefinition | An EC2 job must request at least one vCPU | ERROR | none |
+| `pf-batch-jd-runtime-platform-cpu-arch-value` | AWS::Batch::JobDefinition | RuntimePlatform.CpuArchitecture must be X86_64 or ARM64 | ERROR | none |
+| `pf-batch-jd-runtime-platform-ec2-only` | AWS::Batch::JobDefinition | RuntimePlatform is not applicable to EC2 jobs | ERROR | none |
+| `pf-batch-jd-runtime-platform-os-family-value` | AWS::Batch::JobDefinition | RuntimePlatform.OperatingSystemFamily must be LINUX or a Windows Server family | ERROR | none |
+| `pf-batch-jd-runtime-platform-windows-vcpu-min` | AWS::Batch::JobDefinition | Windows containers need at least one vCPU | ERROR | none |
+| `pf-batch-jd-runtime-platform-windows-x86` | AWS::Batch::JobDefinition | Windows containers require the X86_64 architecture | ERROR | none |
+| `pf-batch-jd-s3files-requires-job-role` | AWS::Batch::JobDefinition | S3 Files volumes require a job role | ERROR | none |
+| `pf-batch-jd-scheduling-priority-range` | AWS::Batch::JobDefinition | SchedulingPriority must be between 0 and 9999 | ERROR | none |
+| `pf-batch-jd-secret-options-requires-execution-role` | AWS::Batch::JobDefinition | LogConfiguration.SecretOptions requires an execution role | ERROR | none |
+| `pf-batch-jd-secrets-requires-execution-role` | AWS::Batch::JobDefinition | Injecting secrets requires an execution role | ERROR | none |
+| `pf-batch-jd-tmpfs-size-min` | AWS::Batch::JobDefinition | Tmpfs.Size must be a positive number of MiB | ERROR | none |
+| `pf-batch-jd-volume-config-exclusive` | AWS::Batch::JobDefinition | A volume takes exactly one configuration type | ERROR | none |
 | `pf-batch-managed-compute-resources` | AWS::Batch::ComputeEnvironment | MANAGED compute environments require ComputeResources | ERROR | none |
 | `pf-batch-queue-order-required` | AWS::Batch::JobQueue | ComputeEnvironmentOrder may not be empty | ERROR | none |
-| `pf-batch-retry-attempts` | AWS::Batch::JobDefinition | RetryStrategy.Attempts may not exceed 10 | ERROR | none |
+| `pf-batch-retry-attempts` | AWS::Batch::JobDefinition | RetryStrategy.Attempts must be between 1 and 10 | ERROR | none |
 | `pf-batch-timeout-minimum` | AWS::Batch::JobDefinition | Timeout.AttemptDurationSeconds must be at least 60 | ERROR | none |
 | `pf-batch-unmanaged-fargate` | AWS::Batch::ComputeEnvironment | UNMANAGED compute environments cannot be Fargate | ERROR | none |
 | `pf-bedrock-automated-reasoning-policy-names-unique` | AWS::Bedrock::AutomatedReasoningPolicy | Names and ids inside a policy definition must be unique | ERROR | none |

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.92" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdk-preflight.Preflight", version: "0.0.94" };
     /**
      * Register the cdk-preflight rules on an App or Stage.
      */