cdk-insights 1.27.0 → 1.28.0

package/README.md

@@ -103,6 +103,50 @@ CDK Insights scans for real problems across **35+ AWS services**:
 | Markdown report | `npx cdk-insights scan --output markdown > report.md` |
 | CI/CD with fail gate | `npx cdk-insights scan --all --output json --fail-on-critical` |
 | Create GitHub issue | `npx cdk-insights scan --output markdown --with-issue` |
+| Live feedback while editing | `npx cdk-insights scan --watch` |
+
+---
+
+<a id="watch-mode"></a>
+
+## 👀 Watch mode
+
+```bash
+npx cdk-insights scan --watch
+```
+
+Re-runs `cdk synth` + the static rule pack on every save and reprints the findings table — terminal stays focused on the latest result, vitest-watch style. **The watch loop never deploys**: it shells out to `cdk synth` only, never `cdk deploy`. Don't reach for `cdk watch` for this purpose; that's a shortcut for `deploy --watch` and will push real infra on every save.
+
+#### Reuses your existing `cdk.json` watch config
+
+The watcher reads the same `watch.include` / `watch.exclude` block CDK uses for `cdk watch`, so a single config drives both:
+
+```json
+{
+  "app": "node bin/my-app.js",
+  "watch": {
+    "include": ["lib/**/*.ts", "bin/**/*.ts"],
+    "exclude": ["**/*.test.ts", "**/handlers/**"]
+  }
+}
+```
+
+If the `watch` block is absent, defaults match aws-cdk's `CdkToolkit` exactly: include defaults to the project root (watch everything), and `**/.*`, `**/.*/**`, `**/node_modules/**`, plus the cloud-assembly output dir (`output` in cdk.json, default `cdk.out`) are always excluded — user-provided excludes are *appended to* this list, never replace it.
+
+#### Watch-safe defaults
+
+A few flags are forced or rejected because they don't make sense in a re-rendering live loop:
+
+| Flag | Behaviour in `--watch` | Why |
+|---|---|---|
+| AI analysis | Forced off (`--local`) | Cache-miss = 1 credit per resource. Running on every save would burn credits with each edit. Run `cdk-insights scan` manually when you want AI feedback on a known-good intermediate state. |
+| `--writeBaseline` | Rejected with error | Would silently overwrite the baseline file on every save. |
+| `--diff` | Rejected with error | Filters findings against a moving target; meaningless when re-running continuously. |
+| `--github`, `--withIssue`, `--prComment` | Forced off | Would otherwise create a GitHub issue / post a PR comment on every save. |
+| `failOnCritical` | Forced off | Would kill the watcher on the first critical finding. |
+| `--output json` / `sarif` / `markdown` / `github-actions` | Coerced to `table` (one-line warning) | Machine formats don't make sense for a re-rendering live loop. |
+
+Loop ergonomics: 300 ms debounce on file events, queue-while-running so a save during an in-flight analysis triggers exactly one follow-up, synth failures preserve the last good results instead of crashing the watcher, `Ctrl+C` cleans up the chokidar watcher before exit.
 
 ---
 
@@ -249,6 +293,12 @@ For accurate `file:line` source attribution, CDK needs to record per-construct s
 
 `cdk-insights scan` already sets `CDK_DEBUG=true` on its spawned synth process, so users on the CLI path get high-confidence attribution out of the box. The above is for users who run `cdk synth` themselves with the aspect attached. 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.
 
+##### Re-run findings on every save
+
+If you have the aspect attached and run `cdk synth` yourself (manually, or via your own watcher), the rules re-evaluate every time synth runs — no extra wiring needed.
+
+For an out-of-the-box live loop, use the `cdk-insights scan --watch` flag instead — it's documented in [Watch mode](#watch-mode) below and runs synth-only (no deploy). Don't reach for `cdk watch` for this purpose: it's a shortcut for `deploy --watch` and will push real infra to AWS on every save.
+
 #### Validations plugin — for synth-time enforcement
 
 Requires `aws-cdk-lib` ≥ 2.251.0:

package/dist/cli/commands/analyse.d.ts

@@ -1,3 +1,23 @@
 import type { CommandModule } from 'yargs';
+import type { IssueGroup } from '../../types/analysis.types';
 import type { AnalyzeCommandArgs } from '../types/cli.types';
+export declare function runStackAnalysis(finalConfig: AnalyzeCommandArgs, fingerprint?: string, authToken?: string, licenseInfo?: any, usageData?: any, _project?: string, licenseKey?: string, forceLocal?: boolean, sensitiveDataConfig?: {
+    enabled?: boolean;
+    warnOnly?: boolean;
+    allowPatterns?: string[];
+    ignoreProperties?: string[];
+    strictMode?: boolean;
+}, baselineExclude?: Set<string>, collectFingerprints?: Set<string>, skipRendering?: boolean): Promise<{
+    totalResources: number;
+    recommendationMaps: {};
+    hasCriticalIssues: boolean;
+    scannedResourceIds: Set<string>;
+    hasSensitiveData?: undefined;
+} | {
+    totalResources: number;
+    recommendationMaps: Record<string, IssueGroup>;
+    hasCriticalIssues: boolean;
+    hasSensitiveData: boolean;
+    scannedResourceIds: Set<string>;
+}>;
 export declare const analyzeCommand: CommandModule<Record<string, unknown>, AnalyzeCommandArgs>;

package/dist/cli/commands/watch.d.ts

@@ -0,0 +1,11 @@
+import type { AnalyzeCommandArgs } from '../types/cli.types';
+export interface RunWatchLoopArgs {
+    config: AnalyzeCommandArgs;
+    fingerprint: string;
+    authToken: string | undefined;
+    licenseInfo: unknown;
+    usageData: unknown;
+    project: string | undefined;
+    licenseKey: string | undefined;
+}
+export declare const runWatchLoop: (args: RunWatchLoopArgs) => Promise<void>;

package/dist/cli/types/cli.types.d.ts

@@ -30,6 +30,14 @@ export interface AnalyzeCommandArgs {
     writeBaseline?: boolean;
     /** Override path to baseline file (default `.cdk-insights-baseline.json`). */
     baseline?: string;
+    /**
+     * Watch CDK source files and re-run static analysis on save. Reuses
+     * cdk.json's `watch.include` / `watch.exclude` block when present
+     * (same conventions as `cdk watch`). AI analysis, baseline writes,
+     * GitHub issue creation, PR comments and scan history upload are all
+     * disabled while in watch mode.
+     */
+    watch?: boolean;
     cache?: {
         enabled?: boolean;
         ttl?: number;