cdk-insights 1.5.0 → 1.7.0

package/README.md

@@ -146,21 +146,59 @@ Create a `.cdk-insights.json` in your project root, or run:
 npx cdk-insights config setup
 ```
 
-### CDK Aspect (Enhanced Analysis)
+### In-App Integration
 
-For precise file/line metadata and richer context, add the aspect in your CDK app:
+CDK Insights ships two integration points; they are complementary, and most projects want both. Install them interactively with:
+
+```bash
+npx cdk-insights setup
+```
+
+| Integration | When to use | What you get |
+|-------------|-------------|--------------|
+| **Aspect** | Always — pairs with `cdk-insights scan` | Precise file/line metadata, source-location tracking, richer findings |
+| **Validations plugin** (`aws-cdk-lib` ≥ 2.251.0) | When you want CI to fail on synth | `cdk synth` blocks on findings; native CDK plugin surface; one less CI step |
+
+#### Aspect — for precise findings
 
 ```ts
 import { App, Aspects } from 'aws-cdk-lib';
-import { CdkInsightsAspect } from 'cdk-insights';
+import { createCdkInsightsAspect } from 'cdk-insights';
 
 const app = new App();
-Aspects.of(app).add(new CdkInsightsAspect());
+Aspects.of(app).add(createCdkInsightsAspect());
 // define stacks...
 app.synth();
 ```
 
-Run synth with `CDK_DEBUG=true` so CDK records stack traces for each construct. On `aws-cdk-lib` ≥ 2.252.0, findings on deferred or post-construction property assignments (lifecycle rules, env vars, role policies, `Lazy.string`/`Lazy.any` values) now point at the property setter line — not the construct constructor — automatically. Older CDKs continue to work; you'll just get construct-level attribution.
+Run synth with `CDK_DEBUG=true` so CDK records stack traces for each construct. On `aws-cdk-lib` ≥ 2.252.0, findings on deferred or post-construction property assignments (lifecycle rules, env vars, role policies, `Lazy.string`/`Lazy.any` values) point at the property setter line — not the construct constructor — automatically. Older CDKs continue to work; you'll just get construct-level attribution.
+
+#### Validations plugin — for synth-time enforcement
+
+Requires `aws-cdk-lib` ≥ 2.251.0:
+
+```ts
+import { App, Validations } from 'aws-cdk-lib';
+import { CdkInsightsPolicyValidationPlugin } from 'cdk-insights';
+
+const app = new App();
+Validations.of(app).addPlugins(new CdkInsightsPolicyValidationPlugin());
+// define stacks...
+app.synth();
+```
+
+`cdk synth` will fail with a CDK Insights report if any rules trigger. Pass `selectedServices`, `minimumSeverity`, or `customRules` to scope what counts as a synth-time block:
+
+```ts
+new CdkInsightsPolicyValidationPlugin({
+  selectedServices: ['IAM', 'S3'],
+  minimumSeverity: 'HIGH',
+});
+```
+
+The plugin sees synthesized templates only — no construct tree. Pair it with the aspect (above) when you also want source-location capture in the `cdk-insights scan` report.
+
+The plugin honours the same suppressions as `cdk-insights scan` — `.cdk-insights.json` (`ignoreRules` / `ignorePaths`) and inline `Validations.of(scope).acknowledge(...)` entries are both respected, so a finding suppressed in the CLI is also suppressed at synth time. Pass `ignoreProjectConfig: true` or `ignoreInlineAcknowledgements: true` to opt out of either source.
 
 ### Suppressing Findings
 

package/dist/analysis/static/awsServices/ECS/logging/ecsServiceConnectAccessLogs.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResults, CloudFormationStack, CreateFindingFunction } from '../../../../../types/analysis.types';
+export declare const checkECSServiceConnectAccessLogs: (template: CloudFormationStack, createFinding: CreateFindingFunction) => AnalysisResults;

package/dist/analysis/static/awsServices/ECS/logging/ecsServiceConnectAccessLogs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/analysis/static/staticAnalysis.d.ts

@@ -1,6 +1,6 @@
+import type { CustomRuleDefinition } from '../../rules/customRules.types';
 import type { AnalysisResults, CloudFormationStack, CreateFindingFunction, ServiceName, Severity } from '../../types/analysis.types';
 import type { ConstructMetadata } from './solutionConstructs/loadConstructMetadata';
-import type { CustomRuleDefinition } from '../../rules/customRules.types';
 export type AnalysisStatistics = {
     totalResources: number;
     analyzedResources: number;

package/dist/analysis/templateLevel/checks/schemaDrift/checkSchemaDrift.d.ts

@@ -0,0 +1,41 @@
+import { type SchemaChange } from '../../../../constants/cdkSchemaChanges';
+import type { AnalysisResults, CloudFormationStack, CreateFindingFunction } from '../../../../types/analysis.types';
+import type { RuleRegistry } from '../../../../types/rules.types';
+type RuleRegistryLike = RuleRegistry;
+type SchemaChangeRegistry = Record<string, SchemaChange[]>;
+/**
+ * Two finding kinds share the same registry and traversal:
+ *   - `regression`: a previously-readable property was removed or renamed,
+ *     so an existing rule may have silently lost coverage.
+ *   - `coverage-gap`: a new property was added on a resource type we already
+ *     have rules for, so a maintainer should *consider* whether a rule should
+ *     evaluate it. Lower urgency, lower noise — only fires for resource types
+ *     already on our radar.
+ */
+export type SchemaDriftKind = 'regression' | 'coverage-gap';
+/**
+ * Inner function exposed for unit tests so cdkVersion and the registries can be
+ * injected directly. Production callers should use the named wrapper for the
+ * specific finding kind they want to surface.
+ *
+ * @param kind - Which finding category to emit. Defaults to `regression` for
+ *   backwards compatibility with the original single-kind behaviour.
+ */
+export declare const findSchemaDriftFindings: (template: CloudFormationStack, createFinding: CreateFindingFunction, cdkVersion: string | null, kind?: SchemaDriftKind, schemaChanges?: SchemaChangeRegistry, rules?: RuleRegistryLike) => AnalysisResults;
+/**
+ * Template-level check: surface known L1 schema-drift events that may have
+ * silently invalidated rule coverage in the user's CDK version (removed or
+ * renamed properties on covered resource types).
+ *
+ * Silent fallback when the user's aws-cdk-lib version cannot be resolved.
+ */
+export declare const checkSchemaDrift: (template: CloudFormationStack, createFinding: CreateFindingFunction) => AnalysisResults;
+/**
+ * Template-level check: surface newly-added L1 properties on resource types
+ * already covered by cdk-insights rules. Hint to maintainers/users that a new
+ * rule may be worth opening — not a regression.
+ *
+ * Silent fallback when the user's aws-cdk-lib version cannot be resolved.
+ */
+export declare const checkSchemaDriftCoverageGaps: (template: CloudFormationStack, createFinding: CreateFindingFunction) => AnalysisResults;
+export {};

package/dist/analysis/templateLevel/checks/schemaDrift/checkSchemaDrift.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/analysis/templateLevel/types.d.ts

@@ -11,8 +11,9 @@ import type { CloudFormationStack, CreateFindingFunction, AnalysisResults, Sever
  * TL-LIMIT-xxx = Service limit checks
  * TL-XRES-xxx  = Cross-resource anti-pattern checks
  * TL-POL-xxx   = Policy analysis checks
+ * TL-DRIFT-xxx = CDK L1 schema-drift checks
  */
-export type TemplateLevelCategory = 'serviceLimits' | 'crossResourceAntiPatterns' | 'policyAnalysis';
+export type TemplateLevelCategory = 'serviceLimits' | 'crossResourceAntiPatterns' | 'policyAnalysis' | 'schemaDrift';
 /**
  * A template-level check function.
  * Receives the FULL CloudFormation stack (all resources).