cdk-insights 1.8.0 → 1.8.2

package/README.md

@@ -171,7 +171,13 @@ Aspects.of(app).add(createCdkInsightsAspect());
 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) point at the property setter line — not the construct constructor — automatically. Older CDKs continue to work; you'll just get construct-level attribution.
+For accurate `file:line` source attribution, CDK needs to record per-construct stack traces during synth. Three ways to enable this, easiest first:
+
+- **`npx cdk-insights setup`** writes `"@aws-cdk/core:stackTrace": true` into your `cdk.json` `context` block — durable across every `cdk synth` invocation, no env-var dance. Recommended.
+- **`cdk synth --context @aws-cdk/core:stackTrace=true`** — one-off, scoped to that command.
+- **`CDK_DEBUG=true cdk synth`** — one-off, env-var form.
+
+`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.
 
 #### Validations plugin — for synth-time enforcement
 

package/dist/aspects/CdkInsightsAspect.d.ts

@@ -150,8 +150,13 @@ export interface CdkInsightsAspectOptions {
 }
 /**
  * Helper function to check if CDK stack traces are enabled.
- * Users should set CDK_DEBUG=true or add context @aws-cdk/core:stackTrace: true
- * for the most reliable source location capture.
+ * Three paths CDK honours, in order of how a user typically sets them:
+ *   1. `CDK_DEBUG=true` env var (per-shell, transient).
+ *   2. `CDK_CONTEXT_JSON` env containing the `@aws-cdk/core:stackTrace` flag
+ *      (used by `cdk synth --context @aws-cdk/core:stackTrace=true`).
+ *   3. `cdk.json` `context['@aws-cdk/core:stackTrace'] = true` (durable, the
+ *      path `cdk-insights setup` configures so users don't have to remember
+ *      anything).
  */
 export declare const isCdkDebugEnabled: () => boolean;
 /**