cdk-cost-analyzer 0.1.1

package/.kiro/specs/cdk-cost-analyzer/requirements.md

@@ -0,0 +1,183 @@
+# Requirements Document
+
+## Introduction
+
+The CDK Cost Analyzer is a TypeScript/Node.js package that analyzes AWS CDK infrastructure changes and provides cost impact summaries. The package can be used as a CLI tool or imported programmatically, helping developers understand the financial implications of their infrastructure changes at ANWB.
+
+This document covers requirements for both Phase 1 (MVP) and Phase 2 (Enhanced Features). Phase 1 focuses on core functionality: comparing CloudFormation templates, calculating costs for common resources, and providing clear reports. Phase 2 adds GitLab integration, advanced features, and broader resource support.
+
+## Glossary
+
+- **CDK Cost Analyzer**: The npm package that analyzes CDK infrastructure changes and generates cost reports
+- **Cost Impact Report**: A summary document showing estimated cost changes between current and proposed infrastructure
+- **GitLab MR**: GitLab Merge Request, a code review mechanism where infrastructure changes are proposed
+- **CDK Synthesizer**: The component that converts CDK code into CloudFormation templates
+- **Cost Estimator**: The component that calculates AWS resource costs using pricing data
+- **CLI Interface**: The command-line interface for running cost analysis from terminal or CI/CD pipelines
+- **Programmatic API**: The TypeScript/JavaScript API for integrating cost analysis into custom applications
+- **Base Infrastructure**: The current deployed infrastructure state before proposed changes
+- **Target Infrastructure**: The proposed infrastructure state after applying merge request changes
+- **Resource Diff**: The set of added, modified, or removed AWS resources between base and target infrastructure
+- **AWS Pricing API**: The AWS service providing current pricing information for AWS resources
+
+## Requirements
+
+## Phase 1: MVP Requirements
+
+### Requirement 1
+
+**User Story:** As a developer, I want to compare two CloudFormation templates and see the cost difference, so that I can understand the financial impact of infrastructure changes.
+
+#### Acceptance Criteria
+
+1. WHEN provided with two CloudFormation template files THEN the CDK Cost Analyzer SHALL parse both templates successfully
+2. WHEN templates are parsed THEN the CDK Cost Analyzer SHALL identify added, removed, and modified resources
+3. WHEN resources are identified THEN the CDK Cost Analyzer SHALL calculate estimated monthly costs for each resource type
+4. WHEN cost calculations complete THEN the CDK Cost Analyzer SHALL generate a summary showing total cost delta
+5. WHEN displaying the summary THEN the CDK Cost Analyzer SHALL list resources grouped by added, removed, and modified categories
+
+### Requirement 2
+
+**User Story:** As a developer, I want to see cost estimates for common AWS resources, so that I can understand the pricing of basic infrastructure components.
+
+#### Acceptance Criteria
+
+1. WHEN analyzing EC2 instances THEN the CDK Cost Analyzer SHALL calculate monthly costs based on instance type and region
+2. WHEN analyzing S3 buckets THEN the CDK Cost Analyzer SHALL estimate storage costs using default assumptions
+3. WHEN analyzing Lambda functions THEN the CDK Cost Analyzer SHALL estimate costs based on memory configuration and default invocation assumptions
+4. WHEN analyzing RDS instances THEN the CDK Cost Analyzer SHALL calculate monthly costs based on instance class and engine type
+5. WHEN a resource type is not supported THEN the CDK Cost Analyzer SHALL mark the cost as unknown and continue processing
+
+### Requirement 3
+
+**User Story:** As a developer, I want to use the cost analyzer as a CLI tool, so that I can quickly compare templates from the command line.
+
+#### Acceptance Criteria
+
+1. WHEN the package is installed THEN the CDK Cost Analyzer SHALL provide a CLI executable named cdk-cost-analyzer
+2. WHEN running the CLI THEN the CDK Cost Analyzer SHALL accept two file paths as arguments for base and target templates
+3. WHEN running the CLI THEN the CDK Cost Analyzer SHALL accept an AWS region flag with a default value of eu-central-1
+4. WHEN analysis completes THEN the CDK Cost Analyzer SHALL output a formatted cost report to stdout
+5. IF template files are missing or invalid THEN the CDK Cost Analyzer SHALL exit with a non-zero status code and display an error message
+
+### Requirement 4
+
+**User Story:** As a developer, I want to use the cost analyzer programmatically in my code, so that I can integrate it into custom scripts and tools.
+
+#### Acceptance Criteria
+
+1. WHEN the package is imported THEN the CDK Cost Analyzer SHALL export a main analysis function
+2. WHEN calling the analysis function THEN the CDK Cost Analyzer SHALL accept base template content, target template content, and region as parameters
+3. WHEN analysis completes THEN the CDK Cost Analyzer SHALL return a structured object containing cost data and resource details
+4. WHEN errors occur during analysis THEN the CDK Cost Analyzer SHALL throw descriptive errors
+5. WHEN using TypeScript THEN the CDK Cost Analyzer SHALL provide type definitions for all exported functions and types
+
+### Requirement 5
+
+**User Story:** As a developer, I want the cost analyzer to fetch current AWS pricing data, so that cost estimates reflect actual AWS prices.
+
+#### Acceptance Criteria
+
+1. WHEN calculating costs THEN the CDK Cost Analyzer SHALL query the AWS Pricing API for current pricing information
+2. WHEN querying pricing data THEN the CDK Cost Analyzer SHALL filter by the specified AWS region
+3. WHEN pricing API calls fail THEN the CDK Cost Analyzer SHALL retry up to 3 times with exponential backoff
+4. IF pricing data cannot be retrieved THEN the CDK Cost Analyzer SHALL use cached pricing data if available
+5. IF no pricing data is available THEN the CDK Cost Analyzer SHALL mark affected resources as having unknown costs
+
+### Requirement 6
+
+**User Story:** As a developer, I want clear and readable cost reports, so that I can quickly understand the financial impact without parsing complex data.
+
+#### Acceptance Criteria
+
+1. WHEN generating a report THEN the CDK Cost Analyzer SHALL display the total monthly cost delta prominently
+2. WHEN listing resources THEN the CDK Cost Analyzer SHALL show resource logical ID, type, and estimated monthly cost
+3. WHEN displaying costs THEN the CDK Cost Analyzer SHALL format currency values with two decimal places and currency symbol
+4. WHEN showing cost increases THEN the CDK Cost Analyzer SHALL use a plus sign prefix for positive deltas
+5. WHEN showing cost decreases THEN the CDK Cost Analyzer SHALL use a minus sign prefix for negative deltas
+
+## Phase 2: Enhanced Features
+
+### Requirement 7
+
+**User Story:** As a developer, I want the cost analysis to integrate with GitLab merge requests, so that I receive cost feedback automatically in my MR workflow.
+
+#### Acceptance Criteria
+
+1. WHEN the GitLab pipeline executes THEN the CDK Cost Analyzer SHALL run as a dedicated pipeline stage
+2. WHEN the cost analysis stage runs THEN the CDK Cost Analyzer SHALL access the merge request source and target branches
+3. WHEN accessing GitLab resources THEN the CDK Cost Analyzer SHALL authenticate using GitLab CI/CD environment variables
+4. WHEN the cost analysis completes THEN the CDK Cost Analyzer SHALL post the cost report as a comment on the merge request
+5. IF the cost analysis fails THEN the CDK Cost Analyzer SHALL report the error in the pipeline logs and mark the job as failed
+
+### Requirement 8
+
+**User Story:** As a FinOps engineer, I want to set cost thresholds for merge requests, so that expensive changes require additional review before merging.
+
+#### Acceptance Criteria
+
+1. WHEN a cost threshold is configured THEN the CDK Cost Analyzer SHALL compare the total cost delta against the threshold
+2. WHEN the cost delta exceeds the threshold THEN the CDK Cost Analyzer SHALL mark the pipeline job as requiring manual approval
+3. WHEN the cost delta is below the threshold THEN the CDK Cost Analyzer SHALL mark the pipeline job as passed
+4. WHEN threshold validation occurs THEN the CDK Cost Analyzer SHALL include threshold status in the cost impact report
+5. WHERE multiple threshold levels are configured THEN the CDK Cost Analyzer SHALL apply the appropriate threshold based on cost delta magnitude
+
+### Requirement 9
+
+**User Story:** As a developer, I want the cost analyzer to automatically synthesize CDK applications, so that I don't need to manually generate CloudFormation templates.
+
+#### Acceptance Criteria
+
+1. WHEN provided with a CDK application path THEN the CDK Cost Analyzer SHALL execute CDK synthesis to generate CloudFormation templates
+2. WHEN synthesis is required for both base and target THEN the CDK Cost Analyzer SHALL synthesize each independently
+3. IF CDK synthesis fails THEN the CDK Cost Analyzer SHALL report the synthesis error with the CDK error message
+4. WHEN synthesis completes THEN the CDK Cost Analyzer SHALL use the generated templates for cost analysis
+5. WHEN synthesis generates multiple stacks THEN the CDK Cost Analyzer SHALL analyze all stacks and aggregate costs
+
+### Requirement 10
+
+**User Story:** As a developer, I want to see cost estimates for resources across multiple AWS regions, so that I can understand regional pricing variations.
+
+#### Acceptance Criteria
+
+1. WHEN analyzing resources THEN the CDK Cost Analyzer SHALL detect the AWS region from CloudFormation template metadata
+2. WHEN multiple regions are present THEN the CDK Cost Analyzer SHALL calculate costs separately for each region
+3. WHEN displaying regional costs THEN the CDK Cost Analyzer SHALL group resources by region in the cost impact report
+4. WHEN region information is unavailable THEN the CDK Cost Analyzer SHALL use the default region from configuration
+5. WHEN displaying cost summaries THEN the CDK Cost Analyzer SHALL show both per-region and total cost deltas
+
+### Requirement 11
+
+**User Story:** As a developer, I want detailed cost breakdowns for modified resources, so that I can understand how configuration changes affect pricing.
+
+#### Acceptance Criteria
+
+1. WHEN a resource is modified THEN the CDK Cost Analyzer SHALL show the cost difference between old and new configurations
+2. WHEN displaying modified resources THEN the CDK Cost Analyzer SHALL highlight configuration properties that impact cost
+3. WHEN instance types or sizes change THEN the CDK Cost Analyzer SHALL show the cost impact of the sizing change
+4. WHEN storage configurations change THEN the CDK Cost Analyzer SHALL calculate the cost difference based on storage type and size
+5. WHEN displaying cost comparisons THEN the CDK Cost Analyzer SHALL show both before and after monthly costs
+
+### Requirement 12
+
+**User Story:** As a FinOps engineer, I want to track cost analysis history, so that I can identify cost trends and optimization opportunities over time.
+
+#### Acceptance Criteria
+
+1. WHEN cost analysis completes THEN the CDK Cost Analyzer SHALL store analysis results in a structured format
+2. WHEN storing analysis results THEN the CDK Cost Analyzer SHALL include merge request ID, timestamp, cost delta, and resource details
+3. WHERE a storage backend is configured THEN the CDK Cost Analyzer SHALL persist analysis results to the configured backend
+4. WHEN storing results THEN the CDK Cost Analyzer SHALL handle storage failures gracefully without blocking the pipeline
+5. WHEN analysis results are stored THEN the CDK Cost Analyzer SHALL include metadata about the analyzed CDK application and stacks
+
+### Requirement 13
+
+**User Story:** As a developer, I want support for additional AWS resource types, so that I can get cost estimates for my complete infrastructure.
+
+#### Acceptance Criteria
+
+1. WHEN analyzing DynamoDB tables THEN the CDK Cost Analyzer SHALL estimate costs based on capacity mode and throughput settings
+2. WHEN analyzing ECS services THEN the CDK Cost Analyzer SHALL calculate costs based on task definitions and desired count
+3. WHEN analyzing API Gateway APIs THEN the CDK Cost Analyzer SHALL estimate costs based on request volume assumptions
+4. WHEN analyzing CloudFront distributions THEN the CDK Cost Analyzer SHALL estimate costs based on data transfer assumptions
+5. WHEN analyzing NAT Gateways THEN the CDK Cost Analyzer SHALL calculate costs based on hourly rates and data processing assumptions

package/.kiro/specs/cdk-cost-analyzer/tasks.md

@@ -0,0 +1,357 @@
+# Implementation Plan
+
+- [x] 1. Set up project structure and dependencies
+  - Initialize TypeScript project with proper tsconfig
+  - Install production dependencies: aws-sdk (v3), js-yaml, commander
+  - Install development dependencies: typescript, fast-check, vitest, type definitions
+  - Configure build and test scripts in package.json
+  - Set up source directory structure (src/parser, src/diff, src/pricing, src/reporter, src/cli, src/api)
+  - _Requirements: 4.5, 13_
+
+- [x] 2. Implement CloudFormation template parser
+  - Create TemplateParser interface and implementation
+  - Support JSON template parsing
+  - Support YAML template parsing using js-yaml
+  - Validate template structure (Resources section required)
+  - Extract resource definitions with logical IDs
+  - _Requirements: 1.1_
+
+- [x] 2.1 Write property test for template parser
+  - **Property 1: Template parsing succeeds for valid templates**
+  - **Validates: Requirements 1.1**
+  - Generate random valid CloudFormation templates
+  - Verify parser returns structured template object without errors
+  - Test with both JSON and YAML formats
+
+- [x] 2.2 Write unit tests for template parser
+  - Test parsing valid JSON templates
+  - Test parsing valid YAML templates
+  - Test handling malformed JSON/YAML
+  - Test handling missing Resources section
+  - Test handling empty templates
+  - _Requirements: 1.1_
+
+- [x] 3. Implement diff engine
+  - Create DiffEngine interface and implementation
+  - Identify added resources (in target, not in base)
+  - Identify removed resources (in base, not in target)
+  - Identify modified resources (in both, properties differ)
+  - Implement deep property comparison for modified resources
+  - _Requirements: 1.2_
+
+- [x] 3.1 Write property test for diff categorization
+  - **Property 2: Diff engine correctly categorizes resources**
+  - **Validates: Requirements 1.2**
+  - Generate random template pairs with known differences
+  - Verify all added, removed, and modified resources are correctly identified
+
+- [x] 3.2 Write property test for resource uniqueness
+  - **Property 5: Resources appear in exactly one category**
+  - **Validates: Requirements 1.5**
+  - Generate random template pairs
+  - Verify each resource appears in exactly one category (added, removed, or modified)
+  - Verify all resources from diff appear in the report
+
+- [x] 3.3 Write unit tests for diff engine
+  - Test identifying added resources
+  - Test identifying removed resources
+  - Test identifying modified resources
+  - Test handling identical templates (no changes)
+  - Test handling completely different templates
+  - _Requirements: 1.2_
+
+- [x] 4. Implement pricing service foundation
+  - Create PricingService interface
+  - Set up AWS SDK v3 Pricing API client
+  - Implement pricing data caching mechanism
+  - Implement retry logic with exponential backoff (3 retries)
+  - Handle pricing API failures gracefully
+  - _Requirements: 5.1, 5.3, 5.4, 5.5_
+
+- [x] 4.1 Write property test for pricing API integration
+  - **Property 17: Pricing queries include region filter**
+  - **Validates: Requirements 5.2**
+  - Generate random resource types and regions
+  - Verify pricing API queries include correct region parameter
+
+- [x] 4.2 Write property test for retry logic
+  - **Property 18: Failed pricing calls trigger retries**
+  - **Validates: Requirements 5.3**
+  - Simulate transient API failures
+  - Verify system retries up to 3 times with exponential backoff
+
+- [x] 4.3 Write property test for cache fallback
+  - **Property 19: Cache is used when API fails**
+  - **Validates: Requirements 5.4**
+  - Simulate API failure with cached data available
+  - Verify cached data is used instead of marking cost as unknown
+
+- [x] 4.4 Write property test for unknown cost handling
+  - **Property 20: Unavailable pricing results in unknown cost**
+  - **Validates: Requirements 5.5**
+  - Simulate scenarios where pricing data is unavailable
+  - Verify resources are marked with confidence 'unknown' and processing continues
+
+- [x] 5. Implement EC2 cost calculator
+  - Create ResourceCostCalculator interface
+  - Implement EC2Calculator class
+  - Extract instance type from EC2 resource properties
+  - Query AWS Pricing API for EC2 instance pricing
+  - Calculate monthly cost (730 hours * hourly rate)
+  - Handle different regions
+  - _Requirements: 2.1_
+
+- [x] 5.1 Write property test for EC2 cost variation
+  - **Property 6: EC2 costs vary by instance type and region**
+  - **Validates: Requirements 2.1**
+  - Generate EC2 instances with different instance types and regions
+  - Verify calculated costs differ appropriately
+
+- [x] 5.2 Write unit tests for EC2 calculator
+  - Test cost calculation for specific instance types (t3.micro, m5.large)
+  - Test cost calculation for different regions
+  - Test handling missing instance type property
+  - _Requirements: 2.1_
+
+- [x] 6. Implement S3 cost calculator
+  - Implement S3Calculator class
+  - Apply default storage assumptions (100 GB standard storage)
+  - Query AWS Pricing API for S3 storage pricing
+  - Calculate monthly storage cost
+  - Document assumptions in MonthlyCost object
+  - _Requirements: 2.2_
+
+- [x] 6.1 Write property test for S3 cost estimates
+  - **Property 7: S3 buckets receive cost estimates**
+  - **Validates: Requirements 2.2**
+  - Generate random S3 bucket resources
+  - Verify cost estimates are greater than zero
+
+- [x] 6.2 Write unit tests for S3 calculator
+  - Test cost calculation with default assumptions
+  - Test cost calculation for different regions
+  - _Requirements: 2.2_
+
+- [x] 7. Implement Lambda cost calculator
+  - Implement LambdaCalculator class
+  - Extract memory configuration from Lambda resource properties
+  - Apply default invocation assumptions (1M invocations/month, 1s duration)
+  - Query AWS Pricing API for Lambda pricing
+  - Calculate monthly cost (requests + compute)
+  - _Requirements: 2.3_
+
+- [x] 7.1 Write property test for Lambda cost scaling
+  - **Property 8: Lambda costs scale with memory configuration**
+  - **Validates: Requirements 2.3**
+  - Generate Lambda functions with different memory allocations
+  - Verify higher memory results in equal or higher cost
+
+- [x] 7.2 Write unit tests for Lambda calculator
+  - Test cost calculation for different memory configurations
+  - Test cost calculation with default assumptions
+  - Test handling missing memory property
+  - _Requirements: 2.3_
+
+- [x] 8. Implement RDS cost calculator
+  - Implement RDSCalculator class
+  - Extract instance class and engine type from RDS resource properties
+  - Apply default storage assumptions (100 GB)
+  - Query AWS Pricing API for RDS instance pricing
+  - Calculate monthly cost (instance + storage)
+  - _Requirements: 2.4_
+
+- [x] 8.1 Write property test for RDS cost calculation
+  - **Property 9: RDS costs are calculated for all engine types**
+  - **Validates: Requirements 2.4**
+  - Generate RDS instances with different engine types
+  - Verify cost estimates are greater than zero for all engines
+
+- [x] 8.2 Write unit tests for RDS calculator
+  - Test cost calculation for different instance classes
+  - Test cost calculation for different engine types (MySQL, PostgreSQL)
+  - Test handling missing properties
+  - _Requirements: 2.4_
+
+- [x] 9. Implement cost aggregation and delta calculation
+  - Implement getCostDelta method in PricingService
+  - Calculate costs for all added resources
+  - Calculate costs for all removed resources
+  - Calculate costs for all modified resources (before and after)
+  - Aggregate total cost delta
+  - _Requirements: 1.3, 1.4_
+
+- [x] 9.1 Write property test for cost calculation validity
+  - **Property 3: Cost calculation produces valid results**
+  - **Validates: Requirements 1.3**
+  - Generate random supported resources
+  - Verify cost calculations return non-negative values with valid currency and confidence
+
+- [x] 9.2 Write property test for cost delta summation
+  - **Property 4: Total cost delta equals sum of individual costs**
+  - **Validates: Requirements 1.4**
+  - Generate random cost analysis results
+  - Verify total delta equals sum of added minus removed plus modified deltas
+
+- [x] 9.3 Write property test for unsupported resource handling
+  - **Property 10: Unsupported resources don't cause failures**
+  - **Validates: Requirements 2.5**
+  - Generate templates with unsupported resource types
+  - Verify analysis completes successfully with resources marked as unknown cost
+
+- [x] 10. Checkpoint - Ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 11. Implement text report formatter
+  - Create Reporter interface and implementation
+  - Implement generateReport method for text format
+  - Display total cost delta prominently at top
+  - Group resources by added, removed, modified categories
+  - Sort resources by cost impact (descending)
+  - Format currency with 2 decimal places and symbol
+  - Use + prefix for positive deltas, - for negative
+  - Include resource logical ID, type, and cost for each entry
+  - _Requirements: 1.5, 6.1, 6.2, 6.3, 6.4, 6.5_
+
+- [x] 11.1 Write property test for report resource fields
+  - **Property 21: Reports contain all required resource fields**
+  - **Validates: Requirements 6.2**
+  - Generate random cost analysis results
+  - Verify each resource in report includes logical ID, type, and cost
+
+- [x] 11.2 Write property test for currency formatting
+  - **Property 22: Currency values are consistently formatted**
+  - **Validates: Requirements 6.3**
+  - Generate random cost values
+  - Verify all formatted values have exactly 2 decimal places and currency symbol
+
+- [x] 11.3 Write property test for positive delta formatting
+  - **Property 23: Positive deltas have plus sign prefix**
+  - **Validates: Requirements 6.4**
+  - Generate cost deltas greater than zero
+  - Verify formatted values include + prefix
+
+- [x] 11.4 Write property test for negative delta formatting
+  - **Property 24: Negative deltas have minus sign prefix**
+  - **Validates: Requirements 6.5**
+  - Generate cost deltas less than zero
+  - Verify formatted values include - prefix
+
+- [x] 11.5 Write unit tests for text reporter
+  - Test report generation with added resources
+  - Test report generation with removed resources
+  - Test report generation with modified resources
+  - Test currency formatting
+  - Test delta sign formatting
+  - Test resource sorting by cost impact
+  - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5_
+
+- [x] 12. Implement JSON report formatter
+  - Add JSON format support to Reporter
+  - Return structured JSON with all cost data
+  - Include totalDelta, currency, addedResources, removedResources, modifiedResources
+  - Ensure JSON is properly formatted and parseable
+  - _Requirements: 4.3_
+
+- [x] 12.1 Write unit tests for JSON reporter
+  - Test JSON structure matches expected schema
+  - Test JSON is valid and parseable
+  - Test all required fields are present
+  - _Requirements: 4.3_
+
+- [x] 13. Implement programmatic API
+  - Create main analyzeCosts function
+  - Accept AnalyzeOptions (baseTemplate, targetTemplate, region)
+  - Orchestrate: parse templates → diff → calculate costs → generate report
+  - Return CostAnalysisResult with structured data
+  - Throw typed exceptions for errors
+  - Export TypeScript type definitions
+  - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5_
+
+- [x] 13.1 Write property test for API return structure
+  - **Property 15: API returns structured results**
+  - **Validates: Requirements 4.3**
+  - Generate random valid template pairs
+  - Verify return value contains all required fields (totalDelta, currency, resources, summary)
+
+- [x] 13.2 Write property test for API error handling
+  - **Property 16: API throws errors for invalid inputs**
+  - **Validates: Requirements 4.4**
+  - Generate invalid inputs (malformed templates, invalid regions)
+  - Verify API throws descriptive errors instead of crashing
+
+- [x] 13.3 Write unit tests for programmatic API
+  - Test successful analysis with valid templates
+  - Test error handling for invalid templates
+  - Test error handling for invalid region
+  - Test TypeScript type definitions are exported
+  - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5_
+
+- [x] 14. Implement CLI interface
+  - Create CLI entry point using commander
+  - Define command: cdk-cost-analyzer <base> <target>
+  - Add --region flag with default eu-central-1
+  - Add --format flag (text, json) with default text
+  - Add --help and --version flags
+  - Read template files from filesystem
+  - Call analyzeCosts API function
+  - Output report to stdout
+  - Handle errors and exit with appropriate status codes
+  - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_
+
+- [x] 14.1 Write property test for CLI argument parsing
+  - **Property 11: CLI accepts valid template file paths**
+  - **Validates: Requirements 3.2**
+  - Generate valid file paths
+  - Verify CLI accepts them and proceeds with analysis
+
+- [x] 14.2 Write property test for CLI region flag
+  - **Property 12: CLI region flag overrides default**
+  - **Validates: Requirements 3.3**
+  - Generate random valid AWS regions
+  - Verify analysis uses provided region instead of default
+
+- [x] 14.3 Write property test for CLI success output
+  - **Property 13: Successful analysis outputs to stdout**
+  - **Validates: Requirements 3.4**
+  - Generate valid template pairs
+  - Verify CLI outputs to stdout and exits with code 0
+
+- [x] 14.4 Write property test for CLI error handling
+  - **Property 14: Invalid inputs cause non-zero exit**
+  - **Validates: Requirements 3.5**
+  - Generate invalid inputs (missing files, malformed templates)
+  - Verify CLI exits with non-zero code and writes to stderr
+
+- [x] 14.5 Write unit tests for CLI
+  - Test CLI with valid template files
+  - Test CLI with missing files
+  - Test CLI with invalid region
+  - Test --help flag
+  - Test --version flag
+  - Test output to stdout
+  - Test error output to stderr
+  - Test exit codes
+  - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_
+
+- [x] 15. Add package.json configuration
+  - Configure package name, version, description
+  - Set main entry point for programmatic API
+  - Set bin entry point for CLI executable
+  - Configure TypeScript build output
+  - Add scripts: build, test, lint
+  - Specify files to include in npm package
+  - Add repository, author, license information
+  - _Requirements: 3.1, 4.1_
+
+- [x] 16. Create README documentation
+  - Document installation instructions
+  - Document CLI usage with examples
+  - Document programmatic API usage with examples
+  - Document supported resource types
+  - Document cost calculation assumptions
+  - Document error handling behavior
+  - Include example templates and output
+  - _Requirements: All_
+
+- [x] 17. Final checkpoint - Ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.