cdk-cost-analyzer 0.1.8 → 0.1.10

package/.cdk-cost-analyzer-cache/metadata.json

@@ -2,11 +2,11 @@
   "entries": {
     "AmazonS3:EU (Frankfurt):storageClass:General Purpose|volumeType:Standard": {
       "price": 0.023,
-      "timestamp": 1768936544693
+      "timestamp": 1768990516595
     },
     "AmazonS3:invalid-region-123:storageClass:General Purpose|volumeType:Standard": {
       "price": 0.023,
-      "timestamp": 1768936544730
+      "timestamp": 1768990516633
     }
   }
 }

package/.kiro/specs/single-template-analysis/design.md

@@ -0,0 +1,319 @@
+# Design Document: Single Template Cost Analysis
+
+## Overview
+
+This design extends the cdk-cost-analyzer tool to support analyzing a single CloudFormation template for estimated monthly costs. The feature leverages the existing pricing service architecture while introducing new components for single template processing and specialized reporting.
+
+The solution introduces a new `analyze` CLI command and `analyzeSingleTemplate` API function that processes a single template, calculates costs for all resources, and provides detailed cost breakdowns without requiring a comparison baseline.
+
+## Architecture
+
+The single template analysis feature integrates with the existing architecture through these key components:
+
+```mermaid
+graph TB
+    CLI[CLI Interface] --> API[API Layer]
+    API --> Parser[Template Parser]
+    API --> SingleAnalyzer[Single Template Analyzer]
+    SingleAnalyzer --> PricingService[Pricing Service]
+    SingleAnalyzer --> SingleReporter[Single Template Reporter]
+    PricingService --> Calculators[Resource Calculators]
+    PricingService --> PricingClient[Pricing Client]
+    SingleReporter --> Output[Formatted Output]
+    
+    subgraph "New Components"
+        SingleAnalyzer
+        SingleReporter
+    end
+    
+    subgraph "Existing Components"
+        Parser
+        PricingService
+        Calculators
+        PricingClient
+    end
+```
+
+The design maintains separation of concerns by:
+- Reusing existing template parsing and pricing calculation logic
+- Creating specialized components for single template analysis workflow
+- Extending the reporter to handle single template output formats
+- Maintaining backward compatibility with existing comparison functionality
+
+## Components and Interfaces
+
+### SingleTemplateAnalyzer
+
+A new service class responsible for orchestrating single template cost analysis:
+
+```typescript
+interface SingleTemplateAnalyzer {
+  analyzeCosts(template: string, region: string, config?: AnalysisConfig): Promise<SingleTemplateCostResult>;
+}
+
+interface AnalysisConfig {
+  usageAssumptions?: UsageAssumptionsConfig;
+  excludedResourceTypes?: string[];
+  cacheConfig?: CacheConfig;
+}
+
+interface SingleTemplateCostResult {
+  totalMonthlyCost: number;
+  currency: string;
+  resourceCosts: ResourceCost[];
+  costBreakdown: CostBreakdown;
+  summary: string;
+}
+
+interface CostBreakdown {
+  byResourceType: ResourceTypeCost[];
+  byConfidenceLevel: ConfidenceLevelCost[];
+  assumptions: string[];
+}
+
+interface ResourceTypeCost {
+  resourceType: string;
+  count: number;
+  totalCost: number;
+  resources: ResourceCost[];
+}
+
+interface ConfidenceLevelCost {
+  confidence: 'high' | 'medium' | 'low' | 'unknown';
+  count: number;
+  totalCost: number;
+}
+```
+
+### Extended API Interface
+
+The existing API will be extended with a new function:
+
+```typescript
+interface AnalyzeSingleTemplateOptions {
+  template: string;
+  region?: string;
+  format?: 'text' | 'json' | 'markdown';
+  config?: AnalysisConfig;
+}
+
+export async function analyzeSingleTemplate(
+  options: AnalyzeSingleTemplateOptions
+): Promise<SingleTemplateCostResult>;
+```
+
+### CLI Command Extension
+
+A new `analyze` command will be added to the CLI:
+
+```bash
+cdk-cost-analyzer analyze <template> [options]
+```
+
+Options:
+- `--region <region>`: AWS region for pricing (default: eu-central-1)
+- `--format <format>`: Output format: text|json|markdown (default: text)
+- `--config <path>`: Path to configuration file
+- `--debug`: Enable verbose debug logging
+
+### SingleTemplateReporter
+
+A specialized reporter for single template analysis results:
+
+```typescript
+interface SingleTemplateReporter {
+  generateReport(
+    result: SingleTemplateCostResult,
+    format: ReportFormat,
+    options?: SingleTemplateReportOptions
+  ): string;
+}
+
+interface SingleTemplateReportOptions {
+  showBreakdown?: boolean;
+  showAssumptions?: boolean;
+  groupByType?: boolean;
+  sortBy?: 'cost' | 'name' | 'type';
+}
+```
+
+## Data Models
+
+### Resource Cost Model
+
+Extends the existing ResourceCost interface to include additional metadata:
+
+```typescript
+interface EnhancedResourceCost extends ResourceCost {
+  properties?: Record<string, any>;
+  region: string;
+  calculatedAt: Date;
+}
+```
+
+### Analysis Result Model
+
+```typescript
+interface SingleTemplateCostResult {
+  totalMonthlyCost: number;
+  currency: string;
+  resourceCosts: EnhancedResourceCost[];
+  costBreakdown: CostBreakdown;
+  summary: string;
+  metadata: AnalysisMetadata;
+}
+
+interface AnalysisMetadata {
+  templateHash: string;
+  region: string;
+  analyzedAt: Date;
+  resourceCount: number;
+  supportedResourceCount: number;
+  unsupportedResourceCount: number;
+}
+```
+
+## Correctness Properties
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+Now I need to use the prework tool to analyze the acceptance criteria before writing the correctness properties:
+
+<function_calls>
+<invoke name="prework">
+<parameter name="featureName">single-template-analysis
+
+### Property 1: Template Processing Completeness
+*For any* valid CloudFormation template, analyzing it should calculate costs for all supported resources and return a complete cost breakdown with total monthly cost.
+**Validates: Requirements 1.1, 1.2**
+
+### Property 2: Output Format Consistency  
+*For any* single template analysis result, the output should include individual resource costs with logical IDs, resource types, confidence levels, and assumptions, properly grouped by type and sorted by cost in descending order.
+**Validates: Requirements 1.3, 3.1, 3.2, 3.3, 3.4, 3.5, 7.1, 7.2**
+
+### Property 3: Unsupported Resource Handling
+*For any* template containing unsupported resource types, those resources should appear in the output with zero cost and unknown confidence level.
+**Validates: Requirements 1.4, 7.3**
+
+### Property 4: Error Handling Consistency
+*For any* invalid input (malformed templates, missing files, invalid configuration), the system should return descriptive error messages and appropriate exit codes without crashing.
+**Validates: Requirements 1.5, 2.5, 4.4, 6.4**
+
+### Property 5: CLI Command Behavior
+*For any* valid template file and CLI options, the analyze command should execute single template analysis and produce output in the requested format.
+**Validates: Requirements 2.1, 2.3, 6.5**
+
+### Property 6: Regional Pricing Accuracy
+*For any* region parameter provided, the pricing calculations should use region-specific pricing data and note regional variations in assumptions.
+**Validates: Requirements 2.2, 5.4, 7.4**
+
+### Property 7: Debug Logging Activation
+*For any* analysis run with debug flag enabled, verbose logging should be produced for pricing API calls.
+**Validates: Requirements 2.4**
+
+### Property 8: Configuration Application
+*For any* valid configuration provided (usage assumptions, excluded resource types, cache settings), the analysis should apply these settings and reflect them in the results.
+**Validates: Requirements 4.3, 5.1, 5.2, 5.3**
+
+### Property 9: API Interface Consistency
+*For any* valid template processed through the API, the result should have a consistent structure with total cost, resource breakdown, and metadata.
+**Validates: Requirements 4.2**
+
+### Property 10: Resource Cleanup
+*For any* completed analysis, all connections and resources should be properly cleaned up to prevent hanging connections.
+**Validates: Requirements 4.5**
+
+### Property 11: Configuration Graceful Degradation
+*For any* invalid or missing configuration, the system should use default values and continue analysis without failure.
+**Validates: Requirements 5.5**
+
+### Property 12: CI/CD Environment Support
+*For any* CI/CD environment execution, the single template analysis should work without requiring baseline templates and provide appropriate exit codes.
+**Validates: Requirements 6.1, 6.3**
+
+### Property 13: AWS Credentials Error Messaging
+*For any* execution with missing AWS credentials, helpful error messages with setup instructions should be displayed.
+**Validates: Requirements 6.2**
+
+### Property 14: Usage Assumption Transparency
+*For any* cost calculation that uses usage assumptions, those assumptions should be clearly explained in the output.
+**Validates: Requirements 7.5**
+
+### Property 15: Template Parser Robustness
+*For any* CloudFormation template (JSON/YAML, with functions, parameters, or nested stacks), the parser should handle it appropriately or provide specific error messages.
+**Validates: Requirements 8.1, 8.2, 8.3, 8.4, 8.5**
+
+### Property 16: GitHub Integration Completeness
+*For any* implementation task created, corresponding GitHub issues should be generated with complete information, appropriate labels, and dependency references.
+**Validates: Requirements 9.1, 9.2, 9.3, 9.4, 9.5**
+
+### Property 17: Test Result Consistency
+*For any* demo template analyzed multiple times with the same configuration, the results should be consistent.
+**Validates: Requirements 10.4**
+
+### Property 18: Authentication Method Preference
+*For any* AWS operation requiring credentials, OIDC should be used over stored access keys when available.
+**Validates: Requirements 10.5**
+
+## Error Handling
+
+The single template analysis feature implements comprehensive error handling across multiple layers:
+
+### Template Processing Errors
+- **Invalid JSON/YAML**: Descriptive parsing errors with line numbers when possible
+- **Missing Templates**: Clear file not found errors with suggested paths
+- **Malformed CloudFormation**: Specific validation errors for CloudFormation structure issues
+- **Unsupported Resources**: Graceful handling with zero cost and clear indication
+
+### Pricing Service Errors
+- **API Failures**: Retry logic with exponential backoff for transient failures
+- **Missing Pricing Data**: Fallback to zero cost with unknown confidence
+- **Rate Limiting**: Automatic retry with appropriate delays
+- **Network Issues**: Timeout handling and connection cleanup
+
+### Configuration Errors
+- **Invalid Config Files**: Validation with specific error messages
+- **Missing AWS Credentials**: Helpful setup instructions for different environments
+- **Invalid Regions**: Clear error messages with supported region list
+- **Permission Issues**: Specific IAM permission guidance
+
+### CLI Error Handling
+- **Exit Codes**: 0 for success, 1 for user errors, 2 for system errors
+- **Error Messages**: Consistent formatting with actionable guidance
+- **Debug Mode**: Enhanced error information when debug flag is enabled
+
+## Testing Strategy
+
+The testing strategy employs a dual approach combining unit tests for specific scenarios and property-based tests for comprehensive coverage:
+
+### Unit Testing Approach
+Unit tests focus on specific examples, edge cases, and integration points:
+- **Template Parsing**: Test specific CloudFormation templates with known structures
+- **Error Conditions**: Test specific error scenarios (missing files, invalid JSON, etc.)
+- **CLI Integration**: Test command-line argument parsing and output formatting
+- **Configuration Loading**: Test specific configuration file formats and validation
+- **GitHub Integration**: Test issue creation and status updates with mock GitHub API
+
+### Property-Based Testing Approach
+Property-based tests verify universal properties across randomized inputs:
+- **Template Processing**: Generate random valid CloudFormation templates and verify cost calculation completeness
+- **Output Formatting**: Test output consistency across different template structures and formats
+- **Configuration Handling**: Generate random configuration combinations and verify proper application
+- **Error Handling**: Generate invalid inputs and verify consistent error responses
+- **Regional Pricing**: Test pricing consistency across different regions and resource types
+
+### Testing Configuration
+- **Property Test Iterations**: Minimum 100 iterations per property test
+- **Test Framework**: Jest for unit tests, fast-check for property-based testing
+- **Test Tagging**: Each property test tagged with format: **Feature: single-template-analysis, Property {number}: {property_text}**
+- **Coverage Requirements**: Minimum 90% code coverage for new components
+- **Integration Testing**: End-to-end tests using demo templates from testaccount01
+
+### Verification Testing
+- **Demo Templates**: Use templates from demo/cdk.out.1 and demo/cdk.out.2 directories
+- **AWS Profile**: All tests use testaccount01 profile for authentication
+- **OIDC Authentication**: GitHub Actions authenticate using OIDC to testaccount01
+- **Consistency Verification**: Same template should produce identical results across runs
+- **Performance Testing**: Verify analysis completes within reasonable time limits
+
+The testing strategy ensures both correctness through property-based testing and practical reliability through comprehensive unit testing of specific scenarios and edge cases.

package/.kiro/specs/single-template-analysis/requirements.md

@@ -0,0 +1,138 @@
+# Requirements Document
+
+## Introduction
+
+This document specifies the requirements for adding single template cost analysis functionality to the cdk-cost-analyzer tool. The feature will enable users to analyze the estimated monthly costs of all resources in a single CloudFormation template without requiring a comparison baseline.
+
+## Glossary
+
+- **Single_Template_Analysis**: The process of analyzing a single CloudFormation template to estimate monthly costs of all resources
+- **Cost_Analyzer**: The cdk-cost-analyzer tool that currently supports template comparison
+- **Template_Parser**: The existing component that parses CloudFormation templates
+- **Pricing_Service**: The existing service that calculates resource costs using AWS Pricing API
+- **CLI**: Command Line Interface for the cost analyzer tool
+- **API**: Application Programming Interface for programmatic access
+- **Resource_Cost**: The estimated monthly cost for a specific AWS resource
+- **Cost_Breakdown**: A detailed view of costs organized by resource type or logical ID
+
+## Requirements
+
+### Requirement 1
+
+**User Story:** As a developer, I want to analyze a single CloudFormation template to see estimated monthly costs, so that I can understand the cost implications before deployment.
+
+#### Acceptance Criteria
+
+1. WHEN a user provides a single CloudFormation template file, THE Cost_Analyzer SHALL parse the template and calculate estimated monthly costs for all resources
+2. WHEN the analysis is complete, THE Cost_Analyzer SHALL display the total estimated monthly cost
+3. WHEN displaying results, THE Cost_Analyzer SHALL show individual resource costs with logical IDs and resource types
+4. WHEN a resource type is not supported for cost calculation, THE Cost_Analyzer SHALL indicate this in the output with zero cost
+5. WHEN the template contains invalid JSON or YAML, THE Cost_Analyzer SHALL return a descriptive error message
+
+### Requirement 2
+
+**User Story:** As a DevOps engineer, I want to get cost estimates through a CLI command, so that I can integrate cost analysis into my deployment workflows.
+
+#### Acceptance Criteria
+
+1. WHEN a user runs the analyze command with a template path, THE CLI SHALL execute single template analysis
+2. WHEN the --region option is provided, THE Cost_Analyzer SHALL use that region for pricing calculations
+3. WHEN the --format option is provided, THE Cost_Analyzer SHALL output results in the specified format (text, json, markdown)
+4. WHEN the --debug option is provided, THE Cost_Analyzer SHALL enable verbose logging for pricing API calls
+5. WHEN the template file does not exist, THE CLI SHALL display an error message and exit with code 1
+
+### Requirement 3
+
+**User Story:** As a cost analyst, I want to understand the cost breakdown of existing templates, so that I can identify the most expensive resources and optimize costs.
+
+#### Acceptance Criteria
+
+1. WHEN analyzing a template, THE Cost_Analyzer SHALL group resources by type in the cost breakdown
+2. WHEN displaying cost breakdown, THE Cost_Analyzer SHALL sort resources by cost in descending order
+3. WHEN a resource has cost calculation assumptions, THE Cost_Analyzer SHALL display these assumptions
+4. WHEN multiple resources of the same type exist, THE Cost_Analyzer SHALL show both individual and aggregate costs per type
+5. WHEN the confidence level for cost calculation is low or unknown, THE Cost_Analyzer SHALL indicate this in the output
+
+### Requirement 4
+
+**User Story:** As an application developer, I want to access single template analysis programmatically, so that I can integrate cost analysis into my applications and tools.
+
+#### Acceptance Criteria
+
+1. WHEN calling the API with a single template, THE API SHALL accept a new analyzeSingleTemplate function
+2. WHEN the API processes a single template, THE API SHALL return a structured result with total cost and resource breakdown
+3. WHEN configuration options are provided, THE API SHALL apply usage assumptions and excluded resource types
+4. WHEN the API encounters errors, THE API SHALL throw typed exceptions with descriptive messages
+5. WHEN the analysis is complete, THE API SHALL clean up resources to prevent hanging connections
+
+### Requirement 5
+
+**User Story:** As a system administrator, I want to configure cost analysis behavior, so that I can customize the analysis for my organization's needs.
+
+#### Acceptance Criteria
+
+1. WHEN a configuration file is provided, THE Cost_Analyzer SHALL apply usage assumptions for single template analysis
+2. WHEN excluded resource types are configured, THE Cost_Analyzer SHALL skip cost calculation for those types
+3. WHEN cache configuration is provided, THE Cost_Analyzer SHALL use cached pricing data when available
+4. WHEN region-specific pricing is needed, THE Cost_Analyzer SHALL use the appropriate regional pricing data
+5. WHEN configuration is invalid or missing, THE Cost_Analyzer SHALL use default values and continue analysis
+
+### Requirement 6
+
+**User Story:** As a developer using CI/CD pipelines, I want to analyze template costs in automated workflows, so that I can catch cost issues early in the development process.
+
+#### Acceptance Criteria
+
+1. WHEN running in CI/CD environments, THE Cost_Analyzer SHALL support single template analysis without requiring baseline templates
+2. WHEN AWS credentials are not configured, THE Cost_Analyzer SHALL display helpful error messages with setup instructions
+3. WHEN the analysis completes successfully, THE Cost_Analyzer SHALL exit with code 0
+4. WHEN errors occur during analysis, THE Cost_Analyzer SHALL exit with appropriate error codes
+5. WHEN output format is JSON, THE Cost_Analyzer SHALL provide machine-readable results for further processing
+
+### Requirement 7
+
+**User Story:** As a cost-conscious developer, I want to see cost estimates with confidence indicators, so that I can understand the reliability of the estimates.
+
+#### Acceptance Criteria
+
+1. WHEN displaying resource costs, THE Cost_Analyzer SHALL include confidence levels (high, medium, low, unknown)
+2. WHEN cost calculations use assumptions, THE Cost_Analyzer SHALL list all assumptions made
+3. WHEN pricing data is unavailable for a resource, THE Cost_Analyzer SHALL indicate this with unknown confidence
+4. WHEN regional pricing varies significantly, THE Cost_Analyzer SHALL note this in the assumptions
+5. WHEN usage patterns affect costs significantly, THE Cost_Analyzer SHALL explain the usage assumptions used
+
+### Requirement 8
+
+**User Story:** As a template author, I want to validate that my CloudFormation templates can be analyzed for costs, so that I can ensure cost transparency for users of my templates.
+
+#### Acceptance Criteria
+
+1. WHEN parsing CloudFormation templates, THE Template_Parser SHALL support both JSON and YAML formats
+2. WHEN templates use CloudFormation functions, THE Template_Parser SHALL handle intrinsic functions appropriately
+3. WHEN templates reference parameters, THE Template_Parser SHALL use default values or indicate missing parameters
+4. WHEN templates are malformed, THE Template_Parser SHALL provide specific error messages about the parsing failure
+5. WHEN templates contain nested stacks, THE Template_Parser SHALL analyze the parent template resources only
+
+### Requirement 9
+
+**User Story:** As a project manager, I want to track implementation progress through GitHub issues, so that I can monitor development status and coordinate team efforts.
+
+#### Acceptance Criteria
+
+1. WHEN implementation tasks are created, THE System SHALL generate corresponding GitHub issues for each task
+2. WHEN a task is completed, THE System SHALL update the corresponding GitHub issue status
+3. WHEN issues are created, THE System SHALL include task descriptions and acceptance criteria
+4. WHEN tasks have dependencies, THE System SHALL reference related issues in the GitHub issue description
+5. WHEN implementation begins, THE System SHALL assign appropriate labels to categorize the issues (enhancement, bug, documentation)
+
+### Requirement 10
+
+**User Story:** As a quality assurance engineer, I want to verify the single template analysis functionality using standardized test data, so that I can ensure the feature works correctly across different scenarios.
+
+#### Acceptance Criteria
+
+1. WHEN testing the single template analysis feature, THE System SHALL use the testaccount01 AWS profile for authentication
+2. WHEN running verification tests, THE System SHALL analyze templates from the demo/cdk.out.1 and demo/cdk.out.2 directories
+3. WHEN GitHub Actions runs tests, THE System SHALL authenticate to testaccount01 using OIDC (OpenID Connect)
+4. WHEN tests execute, THE System SHALL verify that single template analysis produces consistent results for the demo templates
+5. WHEN AWS credentials are required, THE System SHALL use the configured OIDC connection rather than stored access keys

package/.kiro/specs/single-template-analysis/tasks.md

@@ -0,0 +1,243 @@
+# Implementation Plan: Single Template Cost Analysis
+
+## Overview
+
+This implementation plan converts the single template cost analysis design into discrete coding tasks. Each task builds incrementally on previous work, with property-based tests integrated throughout to catch errors early. The plan includes GitHub issue creation for project tracking and uses the existing TypeScript codebase architecture.
+
+## Tasks
+
+- [ ] 1. Create GitHub issues for project tracking
+  - Create GitHub issues for each implementation task with appropriate labels
+  - Include task descriptions, acceptance criteria, and dependency references
+  - Assign "enhancement" labels for new features and "testing" labels for test tasks
+  - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5_
+
+- [ ] 2. Set up core interfaces and types for single template analysis
+  - [ ] 2.1 Create SingleTemplateAnalyzer interface and types
+    - Define AnalysisConfig, SingleTemplateCostResult, CostBreakdown interfaces
+    - Create ResourceTypeCost and ConfidenceLevelCost interfaces
+    - Add AnalysisMetadata interface for tracking analysis information
+    - _Requirements: 4.1, 4.2_
+  
+  - [ ] 2.2 Write property test for interface completeness
+    - **Property 9: API Interface Consistency**
+    - **Validates: Requirements 4.2**
+
+- [ ] 3. Implement SingleTemplateAnalyzer service
+  - [ ] 3.1 Create SingleTemplateAnalyzer class with core analysis logic
+    - Implement analyzeCosts method that processes single templates
+    - Integrate with existing TemplateParser and PricingService
+    - Handle resource cost calculation and aggregation
+    - _Requirements: 1.1, 1.2, 4.2_
+  
+  - [ ] 3.2 Write property test for template processing completeness
+    - **Property 1: Template Processing Completeness**
+    - **Validates: Requirements 1.1, 1.2**
+  
+  - [ ] 3.3 Implement cost breakdown generation
+    - Group resources by type and confidence level
+    - Calculate aggregate costs and resource counts
+    - Generate assumptions list from individual resource calculations
+    - _Requirements: 3.1, 3.4, 7.2_
+  
+  - [ ] 3.4 Write property test for cost breakdown accuracy
+    - **Property 2: Output Format Consistency**
+    - **Validates: Requirements 3.1, 3.4, 7.2**
+
+- [ ] 4. Extend API with analyzeSingleTemplate function
+  - [ ] 4.1 Add analyzeSingleTemplate function to API module
+    - Create AnalyzeSingleTemplateOptions interface
+    - Implement function that uses SingleTemplateAnalyzer
+    - Handle configuration application and error handling
+    - _Requirements: 4.1, 4.3, 4.4_
+  
+  - [ ] 4.2 Write property test for configuration handling
+    - **Property 8: Configuration Application**
+    - **Validates: Requirements 4.3, 5.1, 5.2**
+  
+  - [ ] 4.3 Implement resource cleanup in API function
+    - Ensure PricingService.destroy() is called after analysis
+    - Handle cleanup in error scenarios using try/finally
+    - _Requirements: 4.5_
+  
+  - [ ] 4.4 Write property test for resource cleanup
+    - **Property 10: Resource Cleanup**
+    - **Validates: Requirements 4.5**
+
+- [ ] 5. Create SingleTemplateReporter for specialized output formatting
+  - [ ] 5.1 Implement SingleTemplateReporter class
+    - Create generateReport method for single template results
+    - Support text, JSON, and markdown output formats
+    - Implement resource sorting by cost (descending order)
+    - _Requirements: 1.3, 2.3, 3.2_
+  
+  - [ ] 5.2 Implement cost breakdown formatting
+    - Format resources grouped by type with individual and aggregate costs
+    - Display confidence levels and assumptions clearly
+    - Handle unsupported resources with zero cost indication
+    - _Requirements: 1.4, 3.3, 3.5, 7.1, 7.3_
+  
+  - [ ] 5.3 Write property test for output format consistency
+    - **Property 2: Output Format Consistency**
+    - **Validates: Requirements 1.3, 3.2, 3.3, 7.1**
+  
+  - [ ] 5.4 Write property test for unsupported resource handling
+    - **Property 3: Unsupported Resource Handling**
+    - **Validates: Requirements 1.4, 7.3**
+
+- [ ] 6. Checkpoint - Core functionality complete
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [ ] 7. Add CLI analyze command
+  - [ ] 7.1 Implement analyze command in CLI module
+    - Add command definition with template argument and options
+    - Handle --region, --format, --config, --debug options
+    - Integrate with analyzeSingleTemplate API function
+    - _Requirements: 2.1, 2.2, 2.3, 2.4_
+  
+  - [ ] 7.2 Implement file handling and error reporting
+    - Check template file existence with descriptive errors
+    - Handle invalid templates with specific error messages
+    - Implement proper exit codes (0 for success, 1 for errors)
+    - _Requirements: 2.5, 6.3, 6.4_
+  
+  - [ ] 7.3 Write property test for CLI command behavior
+    - **Property 5: CLI Command Behavior**
+    - **Validates: Requirements 2.1, 2.3**
+  
+  - [ ] 7.4 Write property test for error handling consistency
+    - **Property 4: Error Handling Consistency**
+    - **Validates: Requirements 1.5, 2.5, 4.4, 6.4**
+
+- [ ] 8. Implement enhanced error handling and messaging
+  - [ ] 8.1 Add AWS credentials error handling
+    - Detect missing AWS credentials in CLI and API
+    - Provide helpful setup instructions for different environments
+    - Include specific guidance for CI/CD environments
+    - _Requirements: 6.2_
+  
+  - [ ] 8.2 Implement template parser error improvements
+    - Handle JSON/YAML parsing errors with line numbers
+    - Support CloudFormation functions and parameters gracefully
+    - Provide specific error messages for malformed templates
+    - _Requirements: 8.1, 8.2, 8.3, 8.4, 8.5_
+  
+  - [ ] 8.3 Write property test for template parser robustness
+    - **Property 15: Template Parser Robustness**
+    - **Validates: Requirements 8.1, 8.2, 8.3, 8.4, 8.5**
+  
+  - [ ] 8.4 Write property test for AWS credentials error messaging
+    - **Property 13: AWS Credentials Error Messaging**
+    - **Validates: Requirements 6.2**
+
+- [ ] 9. Add regional pricing and configuration features
+  - [ ] 9.1 Implement regional pricing accuracy
+    - Ensure region parameter is properly passed to pricing service
+    - Add regional pricing variation notes to assumptions
+    - Handle unsupported regions with clear error messages
+    - _Requirements: 5.4, 7.4_
+  
+  - [ ] 9.2 Implement configuration graceful degradation
+    - Handle invalid configuration files without failing analysis
+    - Use default values when configuration is missing or invalid
+    - Log configuration issues without stopping analysis
+    - _Requirements: 5.5_
+  
+  - [ ] 9.3 Write property test for regional pricing accuracy
+    - **Property 6: Regional Pricing Accuracy**
+    - **Validates: Requirements 2.2, 5.4, 7.4**
+  
+  - [ ] 9.4 Write property test for configuration graceful degradation
+    - **Property 11: Configuration Graceful Degradation**
+    - **Validates: Requirements 5.5**
+
+- [ ] 10. Implement debug logging and transparency features
+  - [ ] 10.1 Add debug logging activation
+    - Enable verbose logging when --debug flag is used
+    - Log pricing API calls and responses
+    - Include timing information for performance analysis
+    - _Requirements: 2.4_
+  
+  - [ ] 10.2 Implement usage assumption transparency
+    - Clearly document all usage assumptions in output
+    - Explain how assumptions affect cost calculations
+    - Note when custom assumptions from configuration are used
+    - _Requirements: 7.5_
+  
+  - [ ] 10.3 Write property test for debug logging activation
+    - **Property 7: Debug Logging Activation**
+    - **Validates: Requirements 2.4**
+  
+  - [ ] 10.4 Write property test for usage assumption transparency
+    - **Property 14: Usage Assumption Transparency**
+    - **Validates: Requirements 7.5**
+
+- [ ] 11. Add CI/CD and authentication support
+  - [ ] 11.1 Implement CI/CD environment support
+    - Ensure single template analysis works in automated environments
+    - Support analysis without requiring baseline templates
+    - Handle environment variable detection for CI/CD
+    - _Requirements: 6.1_
+  
+  - [ ] 11.2 Implement OIDC authentication preference
+    - Prefer OIDC authentication over stored access keys
+    - Handle GitHub Actions OIDC authentication
+    - Provide clear guidance for OIDC setup
+    - _Requirements: 10.5_
+  
+  - [ ] 11.3 Write property test for CI/CD environment support
+    - **Property 12: CI/CD Environment Support**
+    - **Validates: Requirements 6.1, 6.3**
+  
+  - [ ] 11.4 Write property test for authentication method preference
+    - **Property 18: Authentication Method Preference**
+    - **Validates: Requirements 10.5**
+
+- [ ] 12. Create verification tests with demo templates
+  - [ ] 12.1 Set up test infrastructure for demo templates
+    - Configure tests to use testaccount01 AWS profile
+    - Set up test data using demo/cdk.out.1 and demo/cdk.out.2 templates
+    - Configure GitHub Actions with OIDC authentication
+    - _Requirements: 10.1, 10.2, 10.3_
+  
+  - [ ] 12.2 Write property test for result consistency
+    - **Property 17: Test Result Consistency**
+    - **Validates: Requirements 10.4**
+  
+  - [ ] 12.3 Create integration tests with real AWS pricing
+    - Test single template analysis with actual demo templates
+    - Verify cost calculations are reasonable and consistent
+    - Test different output formats with demo data
+    - _Requirements: 10.4_
+
+- [ ] 13. Final integration and documentation
+  - [ ] 13.1 Update API exports and documentation
+    - Export new analyzeSingleTemplate function from main API
+    - Update TypeScript type definitions
+    - Add JSDoc comments for new interfaces and functions
+    - _Requirements: 4.1_
+  
+  - [ ] 13.2 Update CLI help and usage documentation
+    - Add analyze command to CLI help text
+    - Update README with single template analysis examples
+    - Document new command-line options and usage patterns
+    - _Requirements: 2.1_
+  
+  - [ ] 13.3 Update GitHub issue status
+    - Mark completed tasks as done in corresponding GitHub issues
+    - Update issue labels and close completed issues
+    - Document any remaining work or follow-up tasks
+    - _Requirements: 9.2_
+
+- [ ] 14. Final checkpoint - Ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+## Notes
+
+- Each task references specific requirements for traceability
+- Property tests validate universal correctness properties from the design
+- Unit tests validate specific examples and edge cases
+- GitHub issues will be created for each task to enable project tracking
+- Tests use testaccount01 profile and demo templates for verification
+- OIDC authentication is preferred over stored AWS credentials
+- All tasks are required for comprehensive implementation from start

package/dist/releasetag.txt

@@ -1 +1 @@
-v0.1.8
+v0.1.10

package/package.json

@@ -56,7 +56,7 @@
     "jest": "^30.2.0",
     "jest-junit": "^16",
     "lint-staged": "^15.0.0",
-    "projen": "^0.99.3",
+    "projen": "^0.99.4",
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
@@ -82,7 +82,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.8",
+  "version": "0.1.10",
   "bugs": {
     "url": "https://github.com/buildinginthecloud/cdk-cost-analyzer/issues"
   },