cdk-insights 0.7.4 → 0.8.0

package/README.md

@@ -16,44 +16,38 @@ npx cdk-insights scan
 
 # Or install in your project
 npm install --save-dev cdk-insights
-npx cdk-insights scan
-```
 
-### Development Setup
+# Initialize npm scripts automatically
+npx cdk-insights init
 
-For contributors, git hooks are automatically installed via Husky when you run:
-
-```bash
-npm install
+# Then use familiar npm commands
+npm run cdk-insights
+npm run cdk-insights:all
+npm run cdk-insights:ci
 ```
 
-The hooks will:
+### What `cdk-insights init` adds
 
-- **Pre-commit**: Prompt for version bump and update changelog
-- **Pre-push**: Run tests before pushing
-- **Commit-msg**: Validate commit message format
-
-You can also add convenience scripts to your `package.json`:
+The `init` command adds these npm scripts to your `package.json`:
 
 ```json
 {
   "scripts": {
-    "scan": "cdk-insights scan",
-    "scan:all": "cdk-insights scan --all",
-    "scan:json": "cdk-insights scan --format json",
-    "scan:markdown": "cdk-insights scan --format markdown",
-    "scan:summary": "cdk-insights scan --format summary",
-    "scan:with-issue": "cdk-insights scan --withIssue"
+    "cdk-insights": "cdk-insights scan",
+    "cdk-insights:all": "cdk-insights scan --all",
+    "cdk-insights:json": "cdk-insights scan --output json",
+    "cdk-insights:markdown": "cdk-insights scan --output markdown",
+    "cdk-insights:ci": "cdk-insights scan --all --output json --fail-on-critical"
   }
 }
 ```
 
-Then run: `npm run scan`
+Use `npx cdk-insights init --all` to include additional scripts for GitHub issues and summary output.
 
 ### Quick Compatibility Check
 
 ```bash
-node --version  # Should be 18+
+node --version  # Should be 20+
 ls cdk.json     # Should exist in CDK project
 ```
 
@@ -73,12 +67,35 @@ ls cdk.json     # Should exist in CDK project
 
 ## 💡 Usage Examples for AWS CDK Projects
 
-| Scenario               | Command Example                                                      |
-| ---------------------- | -------------------------------------------------------------------- |
-| Full project scan      | `npx cdk-insights scan --all --format summary`                       |
-| Security-only focus    | `npx cdk-insights scan --services IAM,S3,KMS --rule-filter Security` |
-| Markdown report output | `npx cdk-insights scan --format markdown > report.md`                |
-| CI/CD pipeline check   | `npx cdk-insights scan --format json --fail-on-critical`             |
+| Scenario               | Command Example                                                       |
+| ---------------------- | --------------------------------------------------------------------- |
+| Full project scan      | `npx cdk-insights scan --all --output summary`                        |
+| Security-only focus    | `npx cdk-insights scan --services IAM,S3,KMS --rule-filter Security`  |
+| Markdown report output | `npx cdk-insights scan --output markdown > report.md`                 |
+| CI/CD pipeline check   | `npx cdk-insights scan --all --output json --fail-on-critical`        |
+| Create GitHub issue    | `npx cdk-insights scan --output markdown --with-issue`                |
+
+---
+
+## 🔄 CI/CD Integration
+
+CDK Insights automatically detects CI environments (GitHub Actions, GitLab CI, Jenkins, etc.) and adjusts behavior accordingly:
+
+```yaml
+# GitHub Actions example
+- name: Run CDK Insights
+  run: npx cdk-insights scan --fail-on-critical
+  env:
+    CDK_INSIGHTS_LICENSE_KEY: ${{ secrets.CDK_INSIGHTS_LICENSE_KEY }}
+```
+
+In CI mode, CDK Insights will:
+- Automatically analyze all stacks
+- Output JSON format for easy parsing
+- Skip interactive prompts
+- Exit with code 1 on critical issues (with `--fail-on-critical`)
+
+👉 [Full CI/CD Setup Guide →](https://github.com/TheLeePriest/cdk-insights/blob/main/docs/ci-setup.md)
 
 ---
 

package/dist/aspects/CdkInsightsAspect.d.ts

@@ -1,9 +1,202 @@
 import { type IAspect } from 'aws-cdk-lib';
 import { type INagLogger, type NagLoggerComplianceData, type NagLoggerErrorData, type NagLoggerNonComplianceData, type NagLoggerNotApplicableData, type NagLoggerSuppressedData, type NagLoggerSuppressedErrorData, NagPack, type NagPackProps } from 'cdk-nag';
 import type { IConstruct } from 'constructs';
-export declare const createExtremelyHelpfulConsoleLogger: () => INagLogger;
-export declare const createCdkInsightsAspect: () => IAspect;
+/** Metadata schema version for tracking compatibility */
+declare const CDK_INSIGHTS_METADATA_VERSION = "2.2.0";
+/** Prefix used to identify cdk-insights annotations in CloudFormation metadata */
+declare const CDK_INSIGHTS_ANNOTATION_PREFIX = "cdk-insights::";
+/** Confidence level for source location detection */
+export type SourceLocationConfidence = 'high' | 'medium' | 'low';
+/** Source location information for a construct */
+export interface SourceLocation {
+    filePath: string;
+    line: number;
+    column: number;
+    /** End line for multi-line constructs */
+    endLine?: number;
+    /** End column */
+    endColumn?: number;
+    /** How confident we are in this location */
+    confidence?: SourceLocationConfidence;
+    /** The method used to determine this location */
+    method?: 'creation_stack' | 'metadata_trace' | 'source_analysis' | 'source_map' | 'ast_analysis' | 'fallback';
+    /** The function or class containing this construct */
+    enclosingScope?: string;
+    /** Code snippet around the construct definition */
+    codeSnippet?: string;
+    /** Original TypeScript file if source maps were used */
+    originalFile?: string;
+}
+/** Enhanced metadata captured for each construct */
+export interface CdkInsightsMetadata {
+    source: 'cdk_insights';
+    version: string;
+    stackName: string;
+    stackId: string;
+    constructPath: string;
+    constructType: string;
+    friendlyName: string;
+    id?: string;
+    /** Logical ID in CloudFormation template */
+    logicalId?: string;
+    sourceLocation?: SourceLocation;
+    /** Parent construct path for hierarchy visualization */
+    parentPath?: string;
+    /** Number of child constructs */
+    childCount?: number;
+    /** Resource tags if available */
+    tags?: Record<string, string>;
+    timestamp: string;
+    /** The L2 construct type (e.g., "aws_s3.Bucket") if this is an L1 resource under an L2 */
+    l2ConstructType?: string;
+    /** The L2 construct ID */
+    l2ConstructId?: string;
+    /** Full construct hierarchy from root to this node */
+    constructHierarchy?: ConstructHierarchyEntry[];
+    /** CloudFormation resource type (e.g., "AWS::S3::Bucket") */
+    cfnResourceType?: string;
+    /** CloudFormation logical IDs this resource depends on */
+    dependencies?: string[];
+    /** CloudFormation logical IDs that depend on this resource */
+    dependents?: string[];
+    /** Properties that may have security/compliance implications */
+    sensitiveProperties?: SensitiveProperty[];
+    /** AWS service category (e.g., "Storage", "Compute", "Security") */
+    serviceCategory?: string;
+    /** Whether this resource uses default configuration (potential concern) */
+    usesDefaults?: boolean;
+    /** CDK construct library version if detectable */
+    cdkVersion?: string;
+    /**
+     * Human-readable description of what created this resource.
+     * Helpful for implicitly created resources like subnets from a VPC.
+     */
+    createdBy?: string;
+    /**
+     * Source location of the nearest ancestor that has a known source location.
+     * Used when this resource doesn't have a direct source location.
+     */
+    rootSourceLocation?: SourceLocation;
+    /**
+     * Search hint to help users find this resource in their codebase.
+     * Contains keywords to search for.
+     */
+    searchHint?: string;
+}
+/** Entry in the construct hierarchy */
+export interface ConstructHierarchyEntry {
+    id: string;
+    type: string;
+    /** Fully qualified name if available (e.g., "aws-cdk-lib.aws_s3.Bucket") */
+    fqn?: string;
+}
+/** Property that may have security/compliance implications */
+export interface SensitiveProperty {
+    /** Property path (e.g., "encryption.enabled") */
+    path: string;
+    /** Current value (redacted if sensitive) */
+    value: string | boolean | number | null;
+    /** Whether this is using a default value */
+    isDefault?: boolean;
+    /** Recommendation for this property */
+    recommendation?: string;
+}
+/** Configuration options for the logger */
+export interface CdkInsightsLoggerOptions {
+    /** Log compliant resources (default: false) */
+    logCompliance?: boolean;
+    /** Log not-applicable rules (default: false) */
+    logNotApplicable?: boolean;
+    /** Enable verbose/debug logging (default: false) */
+    verbose?: boolean;
+}
+/** Configuration options for the aspect */
+export interface CdkInsightsAspectOptions {
+    /** Run CDK-Nag compliance checks (default: true) */
+    runNagChecks?: boolean;
+    /** Capture source location from stack traces (default: true) */
+    captureSourceLocation?: boolean;
+    /** Capture resource tags (default: true) */
+    captureTags?: boolean;
+    /** Capture parent/child relationships (default: true) */
+    captureRelationships?: boolean;
+    /** Capture full construct hierarchy (default: true) */
+    captureHierarchy?: boolean;
+    /** Capture resource dependencies (default: true) */
+    captureDependencies?: boolean;
+    /** Capture sensitive properties that may have security implications (default: true) */
+    captureSensitiveProperties?: boolean;
+    /** Logger options */
+    logger?: CdkInsightsLoggerOptions;
+    /**
+     * Enable source file analysis for location detection (default: true)
+     * When enabled, the aspect will search source files to find construct definitions.
+     * This is useful when CDK debug mode is not enabled.
+     */
+    analyzeSourceFiles?: boolean;
+    /**
+     * Enable source map support for mapping compiled JS back to TS (default: true)
+     * When enabled and source maps are available, the aspect will use them to
+     * provide accurate TypeScript file locations even when stack traces point to
+     * compiled JavaScript files.
+     */
+    useSourceMaps?: boolean;
+    /**
+     * Include code snippets around construct definitions (default: true)
+     * When enabled, the source location will include a few lines of code
+     * around the construct definition for quick reference.
+     */
+    includeCodeSnippets?: boolean;
+}
+/**
+ * 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.
+ */
+export declare const isCdkDebugEnabled: () => boolean;
+/**
+ * Creates a configurable CDK-Nag logger with verbosity control.
+ */
+export declare const createCdkInsightsLogger: (options?: CdkInsightsLoggerOptions) => INagLogger;
+/**
+ * Creates a playful logger with more expressive messages.
+ * Useful for development and debugging.
+ */
+export declare const createExtremelyHelpfulConsoleLogger: (options?: CdkInsightsLoggerOptions) => INagLogger;
+/**
+ * Creates a CDK Insights aspect using functional composition.
+ * This is the recommended approach for new projects.
+ *
+ * @example
+ * ```typescript
+ * import { Aspects } from 'aws-cdk-lib';
+ * import { createCdkInsightsAspect } from 'cdk-insights';
+ *
+ * // Basic usage
+ * Aspects.of(app).add(createCdkInsightsAspect());
+ *
+ * // With options
+ * Aspects.of(app).add(createCdkInsightsAspect({
+ *   runNagChecks: true,
+ *   captureSourceLocation: true,
+ *   captureTags: true,
+ *   logger: { verbose: true }
+ * }));
+ *
+ * // Metadata-only mode (no CDK-Nag)
+ * Aspects.of(app).add(createCdkInsightsAspect({
+ *   runNagChecks: false
+ * }));
+ * ```
+ */
+export declare const createCdkInsightsAspect: (options?: CdkInsightsAspectOptions) => IAspect;
+/**
+ * Legacy class-based logger for backward compatibility.
+ * @deprecated Use createCdkInsightsLogger() instead
+ */
 export declare class ExtremelyHelpfulConsoleLogger implements INagLogger {
+    private readonly options;
+    constructor(options?: CdkInsightsLoggerOptions);
     onCompliance(data: NagLoggerComplianceData): void;
     onNonCompliance(data: NagLoggerNonComplianceData): void;
     onSuppressed(data: NagLoggerSuppressedData): void;
@@ -11,8 +204,38 @@ export declare class ExtremelyHelpfulConsoleLogger implements INagLogger {
     onSuppressedError(data: NagLoggerSuppressedErrorData): void;
     onNotApplicable(data: NagLoggerNotApplicableData): void;
 }
+/**
+ * Class-based CDK Insights aspect for backward compatibility.
+ * Extends NagPack for integration with CDK-Nag ecosystem.
+ *
+ * @deprecated Use createCdkInsightsAspect() for new projects
+ *
+ * @example
+ * ```typescript
+ * import { Aspects } from 'aws-cdk-lib';
+ * import { CdkInsightsAspect } from 'cdk-insights';
+ *
+ * Aspects.of(app).add(new CdkInsightsAspect());
+ * ```
+ */
 export declare class CdkInsightsAspect extends NagPack implements IAspect {
     private readonly delegate;
-    constructor(props?: NagPackProps);
+    private readonly options;
+    constructor(props?: NagPackProps & CdkInsightsAspectOptions);
     visit(node: IConstruct): void;
 }
+/** Re-export constants for external use */
+export { CDK_INSIGHTS_METADATA_VERSION, CDK_INSIGHTS_ANNOTATION_PREFIX };
+/**
+ * Clears all internal caches. Useful for testing or when processing
+ * multiple independent CDK apps in the same process.
+ */
+export declare const clearCaches: () => void;
+/**
+ * Returns cache statistics for debugging/monitoring.
+ */
+export declare const getCacheStats: () => {
+    sourceFiles: number;
+    constructLocations: number;
+    sourceMaps: number;
+};