# cdk-preflight

> A Rego rule pack that catches deploy-time CloudFormation failures at `cdk synth` time, by injecting rules for schema-invisible constraints (doc-only limits, cross-property rules) into the AWS CDK built-in validator (aws-cdk-lib >= 2.267.0).

Scope: every deploy-time failure, and every post-deploy run that is certain to fail, that no existing CDK mechanism already catches. L2 construct validation does not count as coverage (L1, escape hatches, `addPropertyOverride` and included templates bypass it), so L2 overlap neither blocks a new rule nor retires an existing one; only the bundled engine or CloudFormation's server-side validation retires a rule, and then the rule is deleted outright. New rules land in minor releases, so a minor upgrade can newly fail a synth that passed before — pin the version, `exclude` the id, or set `enforce: false`.

## Install into a CDK app (agent playbook)

1. `npm i -D cdk-preflight`
2. `npx cdk-preflight init` (alias: `npx cdkpf init`) — locates the app entry via cdk.json and inserts `Preflight.apply(app)`. `--dry-run` previews, `--dir <path>` targets another directory. Idempotent.
3. `cdk synth` — violations FAIL the synth by default, reported with rule id, actual value, and suggested fix.
4. Opt-outs: `exclude: ['<rule-id>']` disables one rule; `enforce: false` reports as warnings only (with construct traces and per-finding acknowledgement). Add `strict: true` to also fail on the engine's own error-class findings (F-/E-prefixed) that CDK otherwise downgrades to warnings.
5. Opt-in: `checkQuotas: true` also compares what the app creates (VPCs, internet gateways, Elastic IPs per Region, reserved Lambda concurrency) against the target account's Service Quotas and usage. It is the only option that calls AWS at synth time; the app process needs credentials (`AWS_PROFILE`, since the CDK CLI does not pass `--profile` on), and without them the check is skipped with a `pf-quota-check-skipped` warning.
6. Machine-readable findings: synth with `-c @aws-cdk/core:validationReportJson=true`, then read `cdk.out/validation-report.json`.

## Key files

- README.md: usage and options
- docs/rules.md: generated table of bundled rules
- AGENTS.md: how to author a rule (fail/pass fixtures, duplication guard, real-deploy gate)
- rules/<service>/<rule-id>/: rule.rego + meta.yaml + templates

## API

- `Preflight.apply(scope: App | Stage, options?: { exclude?: string[]; enforce?: boolean; strict?: boolean; includeUpstreamPending?: boolean; checkQuotas?: boolean; quotaCacheTtl?: Duration })`
- `Preflight.ruleIds(): string[]`
