# 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 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` — 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. 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 })`
- `Preflight.ruleIds(): string[]`
