cdk-cost-analyzer 0.1.12 → 0.1.14

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

@@ -2,35 +2,35 @@
   "entries": {
     "AmazonS3:US East (N. Virginia):storageClass:General Purpose|volumeType:Standard": {
       "price": 0.023,
-      "timestamp": 1769029142702
+      "timestamp": 1769682402214
     },
     "AmazonDynamoDB:US East (N. Virginia):group:DDB-ReadUnits|groupDescription:OnDemand ReadRequestUnits": {
       "price": 0.023,
-      "timestamp": 1769029142713
+      "timestamp": 1769682402221
     },
     "AmazonDynamoDB:US East (N. Virginia):group:DDB-WriteUnits|groupDescription:OnDemand WriteRequestUnits": {
       "price": 0.023,
-      "timestamp": 1769029142713
+      "timestamp": 1769682402221
     },
     "AmazonEC2:US East (N. Virginia):capacitystatus:Used|instanceType:t3.micro|operatingSystem:Linux|preInstalledSw:NA|tenancy:Shared": {
       "price": 0.023,
-      "timestamp": 1769029142723
+      "timestamp": 1769682402229
     },
     "AWSLambda:US East (N. Virginia):group:AWS-Lambda-Requests": {
       "price": 0.023,
-      "timestamp": 1769029142728
+      "timestamp": 1769682402234
     },
     "AWSLambda:US East (N. Virginia):group:AWS-Lambda-Duration": {
       "price": 0.023,
-      "timestamp": 1769029142729
+      "timestamp": 1769682402234
     },
     "AmazonS3:EU (Frankfurt):storageClass:General Purpose|volumeType:Standard": {
       "price": 0.023,
-      "timestamp": 1769029153739
+      "timestamp": 1769682421898
     },
     "AmazonS3:invalid-region-123:storageClass:General Purpose|volumeType:Standard": {
       "price": 0.023,
-      "timestamp": 1769029153782
+      "timestamp": 1769682421939
     }
   }
 }

package/README.md

@@ -34,6 +34,43 @@ A TypeScript package that analyzes AWS CDK infrastructure changes and provides c
 npm install cdk-cost-analyzer
 ```
 
+## AWS Credentials
+
+CDK Cost Analyzer requires AWS credentials to query the AWS Pricing API for real-time cost data.
+
+### Configure Credentials
+
+```bash
+# Via environment variables
+export AWS_ACCESS_KEY_ID=your_access_key
+export AWS_SECRET_ACCESS_KEY=your_secret_key
+
+# Or via AWS CLI configuration
+aws configure
+```
+
+### Required IAM Permissions
+
+The AWS credentials must have permission to call the Pricing API:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "pricing:GetProducts",
+        "pricing:DescribeServices"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+For CI/CD environments, configure credentials as secrets/variables in your pipeline. See the [CI/CD Integration Guide](docs/CI_CD.md) for detailed setup instructions.
+
 ## Documentation
 
 - **[Configuration Guide](docs/CONFIGURATION.md)** - Configure thresholds, usage assumptions, and exclusions

package/dist/releasetag.txt

@@ -1 +1 @@
-v0.1.12
+v0.1.14

package/docs/CI_CD.md

@@ -12,164 +12,578 @@ This guide covers integrating CDK Cost Analyzer into your CI/CD pipelines for au
 
 ## GitHub Actions
 
-### Basic Setup
+### Basic Cost Analysis Workflow
 
-Create `.github/workflows/ci.yml`:
+Create `.github/workflows/cost-analysis.yml`:
 
 ```yaml
-name: CI
+name: Cost Analysis
 
 on:
-  push:
-    branches: ['**']
   pull_request:
-    branches: ['**']
+    branches: [main]
+    paths:
+      - 'infrastructure/**'
+      - 'cdk.json'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  analyze-costs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for comparison
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install CDK Cost Analyzer
+        run: npm install -g cdk-cost-analyzer
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: Synthesize base template
+        run: |
+          git checkout ${{ github.event.pull_request.base.sha }}
+          cd infrastructure
+          npx cdk synth --all --output ../cdk.out.base
+
+      - name: Synthesize target template
+        run: |
+          git checkout ${{ github.event.pull_request.head.sha }}
+          cd infrastructure
+          npx cdk synth --all --output ../cdk.out.target
+
+      - name: Analyze cost changes
+        id: cost-analysis
+        run: |
+          cdk-cost-analyzer compare \
+            cdk.out.base/MyStack.template.json \
+            cdk.out.target/MyStack.template.json \
+            --region us-east-1 \
+            --format markdown > cost-report.md
+
+      - name: Comment PR with cost analysis
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('cost-report.md', 'utf8');
+            
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: report
+            });
+```
+
+### Using Pipeline Command with Synthesis
+
+For automatic CDK synthesis:
+
+```yaml
+name: Cost Analysis
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
 
 jobs:
-  test:
+  analyze-costs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+
       - uses: actions/setup-node@v4
         with:
-          node-version: '18.x'
+          node-version: '20.x'
           cache: 'npm'
-      - run: npm ci
-      - run: npm run eslint
-      - run: npm run lint
-      - run: npm run build
-      - run: npm run test:silent
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install CDK Cost Analyzer
+        run: npm install -g cdk-cost-analyzer
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: Run cost analysis
+        id: cost-analysis
+        run: |
+          cdk-cost-analyzer pipeline \
+            --synth \
+            --cdk-app-path ./infrastructure \
+            --region us-east-1 \
+            --config .cdk-cost-analyzer.yml \
+            --format markdown > cost-report.md
+
+      - name: Comment PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('cost-report.md', 'utf8');
+            
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: report
+            });
+```
+
+### Single Template Analysis
+
+Analyze a single template without comparison:
+
+```yaml
+name: Cost Estimation
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  estimate-costs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Install CDK Cost Analyzer
+        run: npm install -g cdk-cost-analyzer
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: Analyze template
+        run: |
+          cdk-cost-analyzer analyze infrastructure/template.json \
+            --region us-east-1 \
+            --format markdown > cost-estimate.md
+
+      - name: Comment PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('cost-estimate.md', 'utf8');
+            
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: report
+            });
 ```
 
 ### Configuration Options
 
+#### AWS Credentials Setup
+
+**Important**: CDK Cost Analyzer requires AWS credentials to query the AWS Pricing API for real-time cost data. Without valid credentials, the tool cannot fetch pricing information.
+
+**Required IAM Permissions**:
+
+The AWS credentials must have permission to call the Pricing API:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "pricing:GetProducts",
+        "pricing:DescribeServices"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+**GitHub Repository Secrets**:
+
+Store AWS credentials as GitHub repository secrets:
+
+1. Go to **Settings** → **Secrets and variables** → **Actions**
+2. Add secrets:
+   - `AWS_ACCESS_KEY_ID` - AWS access key with Pricing API permissions
+   - `AWS_SECRET_ACCESS_KEY` - AWS secret access key
+   - `AWS_REGION` (optional, can be set in workflow)
+
+**Note**: The Pricing API is a global service, but credentials must be configured. The region parameter in the workflow determines which regional pricing data to fetch, not which AWS region to authenticate against.
+
 #### Trigger Events
 
 ```yaml
 # Run on all branches
 on:
-  push:
-    branches: ['**']
   pull_request:
     branches: ['**']
 
 # Run only on specific branches
 on:
-  push:
-    branches: [main, develop]
   pull_request:
-    branches: [main]
+    branches: [main, develop]
 
 # Run on specific paths
 on:
-  push:
+  pull_request:
     paths:
-      - 'src/**'
-      - 'test/**'
-      - 'package.json'
+      - 'infrastructure/**'
+      - 'cdk.json'
+      - '.cdk-cost-analyzer.yml'
+```
+
+#### Cost Threshold Enforcement
+
+Fail the workflow if costs exceed thresholds:
+
+```yaml
+name: Cost Analysis with Thresholds
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  analyze-costs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Install CDK Cost Analyzer
+        run: npm install -g cdk-cost-analyzer
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: Run cost analysis with thresholds
+        run: |
+          cdk-cost-analyzer pipeline \
+            --synth \
+            --cdk-app-path ./infrastructure \
+            --region us-east-1 \
+            --config .cdk-cost-analyzer.yml \
+            --environment production \
+            --format markdown > cost-report.md
+        # Exit code 2 means threshold exceeded
+        continue-on-error: true
+        id: cost-check
+
+      - name: Comment PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('cost-report.md', 'utf8');
+            
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: report
+            });
+
+      - name: Fail if threshold exceeded
+        if: steps.cost-check.outcome == 'failure'
+        run: |
+          echo "Cost threshold exceeded - requires approval"
+          exit 1
 ```
 
-#### Multi-Version Testing
+#### Multi-Stack Analysis
+
+Analyze multiple stacks in a monorepo:
 
 ```yaml
+name: Multi-Stack Cost Analysis
+
+on:
+  pull_request:
+    branches: [main]
+
 jobs:
-  test:
+  analyze-costs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [18.x, 20.x, 22.x]
+        stack:
+          - name: NetworkStack
+            path: packages/network
+          - name: ComputeStack
+            path: packages/compute
+          - name: StorageStack
+            path: packages/storage
     steps:
       - uses: actions/checkout@v4
+
       - uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run build
-      - run: npm run test:silent
+          node-version: '20.x'
+
+      - name: Install CDK Cost Analyzer
+        run: npm install -g cdk-cost-analyzer
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: Analyze ${{ matrix.stack.name }}
+        run: |
+          cdk-cost-analyzer pipeline \
+            --synth \
+            --cdk-app-path ${{ matrix.stack.path }} \
+            --region us-east-1 \
+            --format markdown > cost-${{ matrix.stack.name }}.md
+
+      - name: Comment PR with ${{ matrix.stack.name }} costs
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('cost-${{ matrix.stack.name }}.md', 'utf8');
+            
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `## ${{ matrix.stack.name }} Cost Analysis\n\n${report}`
+            });
 ```
 
-#### Test Coverage
+#### Caching for Faster Builds
+
+Cache pricing data and dependencies:
 
 ```yaml
+name: Cost Analysis with Caching
+
+on:
+  pull_request:
+    branches: [main]
+
 jobs:
-  test:
+  analyze-costs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+
       - uses: actions/setup-node@v4
         with:
-          node-version: '18.x'
+          node-version: '20.x'
           cache: 'npm'
-      - run: npm ci
-      - run: npm run test:coverage
-      
-      - name: Upload coverage
-        uses: codecov/codecov-action@v4
+
+      - name: Cache pricing data
+        uses: actions/cache@v4
         with:
-          files: ./coverage/coverage-final.json
-```
+          path: .cdk-cost-analyzer-cache
+          key: pricing-cache-${{ runner.os }}-${{ hashFiles('.cdk-cost-analyzer.yml') }}
+          restore-keys: |
+            pricing-cache-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install CDK Cost Analyzer
+        run: npm install -g cdk-cost-analyzer
 
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: Run cost analysis
+        run: |
+          cdk-cost-analyzer pipeline \
+            --synth \
+            --cdk-app-path ./infrastructure \
+            --region us-east-1 \
+            --format markdown > cost-report.md
+
+      - name: Comment PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('cost-report.md', 'utf8');
+            
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: report
+            });
+```
 ### Status Badge
 
-Add to your README:
+Add a status badge to your README:
 
 ```markdown
-[![CI](https://github.com/USERNAME/REPOSITORY/actions/workflows/ci.yml/badge.svg)](https://github.com/USERNAME/REPOSITORY/actions/workflows/ci.yml)
+[![Cost Analysis](https://github.com/USERNAME/REPOSITORY/actions/workflows/cost-analysis.yml/badge.svg)](https://github.com/USERNAME/REPOSITORY/actions/workflows/cost-analysis.yml)
 ```
 
 ### Complete Example
 
+Full workflow with all features:
+
 ```yaml
-name: CI
+name: Cost Analysis
 
 on:
-  push:
-    branches: ['**']
-    paths:
-      - 'src/**'
-      - 'test/**'
-      - 'package.json'
-      - 'package-lock.json'
   pull_request:
-    branches: ['**']
+    branches: [main]
+    paths:
+      - 'infrastructure/**'
+      - 'cdk.json'
+      - '.cdk-cost-analyzer.yml'
+
+permissions:
+  contents: read
+  pull-requests: write
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: cost-analysis-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  test:
+  analyze-costs:
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: true
-      matrix:
-        node-version: [18.x, 20.x, 22.x]
-    
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
-      
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: '20.x'
           cache: 'npm'
-      
+
+      - name: Cache pricing data
+        uses: actions/cache@v4
+        with:
+          path: .cdk-cost-analyzer-cache
+          key: pricing-cache-${{ runner.os }}-${{ hashFiles('.cdk-cost-analyzer.yml') }}
+          restore-keys: |
+            pricing-cache-${{ runner.os }}-
+
       - name: Install dependencies
         run: npm ci
-      
-      - name: Run linting
-        run: npm run eslint
-      
-      - name: Run type checking
-        run: npm run lint
-      
-      - name: Build project
-        run: npm run build
-      
-      - name: Run tests
-        run: npm run test:silent
+
+      - name: Install CDK Cost Analyzer
+        run: npm install -g cdk-cost-analyzer
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: Run cost analysis
+        id: cost-analysis
+        continue-on-error: true
+        run: |
+          cdk-cost-analyzer pipeline \
+            --synth \
+            --cdk-app-path ./infrastructure \
+            --region us-east-1 \
+            --config .cdk-cost-analyzer.yml \
+            --environment production \
+            --format markdown > cost-report.md
+
+      - name: Comment PR with results
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('cost-report.md', 'utf8');
+            
+            // Find existing comment
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            
+            const botComment = comments.find(comment => 
+              comment.user.type === 'Bot' && 
+              comment.body.includes('Cost Analysis')
+            );
+            
+            const commentBody = `## 💰 Cost Analysis\n\n${report}\n\n---\n*Updated: ${new Date().toISOString()}*`;
+            
+            if (botComment) {
+              // Update existing comment
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: commentBody
+              });
+            } else {
+              // Create new comment
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: commentBody
+              });
+            }
+
+      - name: Check threshold status
+        if: steps.cost-analysis.outcome == 'failure'
+        run: |
+          echo "::error::Cost threshold exceeded - requires approval"
+          exit 1
 ```
 
 ---
@@ -225,10 +639,34 @@ cost-analysis:
 
 ### AWS Credentials
 
+**Important**: CDK Cost Analyzer requires AWS credentials to query the AWS Pricing API for real-time cost data.
+
+**Required IAM Permissions**:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "pricing:GetProducts",
+        "pricing:DescribeServices"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+**GitLab CI/CD Variables**:
+
 Configure in **Settings > CI/CD > Variables**:
-- `AWS_ACCESS_KEY_ID` (masked)
-- `AWS_SECRET_ACCESS_KEY` (masked)
-- `AWS_REGION`
+- `AWS_ACCESS_KEY_ID` (masked) - AWS access key with Pricing API permissions
+- `AWS_SECRET_ACCESS_KEY` (masked) - AWS secret access key
+- `AWS_REGION` - Target region for pricing data (e.g., us-east-1, eu-central-1)
+
+**Note**: The Pricing API is a global service. The region variable determines which regional pricing data to fetch, not authentication region.
 
 ### Cost Analysis Options
 

package/docs/CONFIGURATION.md

@@ -195,8 +195,8 @@ synthesis:
 ```
 
 **Timeout Behavior:**
-- CDK synthesis has a built-in 25-second timeout to prevent hanging processes
-- Process receives SIGTERM for graceful termination, followed by SIGKILL after 5 seconds
+- CDK synthesis has a built-in 15-second timeout to prevent hanging processes
+- Process receives SIGTERM for graceful termination, followed by SIGKILL after 1 second
 - If synthesis requires more time, use a custom command with extended timeout:
   ```yaml
   synthesis:

package/docs/DEVELOPMENT.md

@@ -202,7 +202,7 @@ npm run test:silent
 npm run test:watch
 
 # Run specific test file
-npx vitest run test/parser/TemplateParser.test.ts
+npx jest test/parser/TemplateParser.test.ts
 ```
 
 ### Test Structure
@@ -326,7 +326,7 @@ export class DynamoDBCalculator implements ResourceCostCalculator {
 
 ### Build Errors
 
-Check Node.js version (>= 18.0.0):
+Check Node.js version (>= 20.0.0):
 ```bash
 node --version
 ```
@@ -375,7 +375,7 @@ aws sts get-caller-identity --no-cli-pager
 
 ### Development
 - `typescript`: TypeScript compiler
-- `vitest`: Testing framework
+- `jest`: Testing framework
 - `fast-check`: Property-based testing
 - `@types/*`: Type definitions
 

package/docs/NAT_GATEWAY_TESTING.md

@@ -7,14 +7,14 @@ This guide provides information on testing and debugging the NAT Gateway pricing
 The NAT Gateway calculator had an issue with region prefix formatting that prevented it from fetching correct pricing data from the AWS Pricing API.
 
 ### Problem
-- **Before**: UsageType format was `EUC1NatGateway-Hours` (missing hyphen)
-- **After**: UsageType format is `EUC1-NatGateway-Hours` (correct format)
+- **Before**: UsageType format was `EUC1NatGateway-Hours` (missing hyphen and "Regional")
+- **After**: UsageType format is `EUC1-RegionalNatGateway-Hours` (correct format)
 
 ### Changes Made
 
 1. **Fixed UsageType Format** (NatGatewayCalculator.ts)
-   - Changed from `${regionPrefix}NatGateway-Hours` to `${regionPrefix}-NatGateway-Hours`
-   - Changed from `${regionPrefix}NatGateway-Bytes` to `${regionPrefix}-NatGateway-Bytes`
+   - Changed from `${regionPrefix}NatGateway-Hours` to `${regionPrefix}-RegionalNatGateway-Hours`
+   - Changed from `${regionPrefix}NatGateway-Bytes` to `${regionPrefix}-RegionalNatGateway-Bytes`
 
 2. **Expanded Region Coverage**
    - Added comprehensive region prefix mappings for all AWS commercial and government regions
@@ -116,7 +116,7 @@ npx ts-node tools/discover-nat-gateway-pricing.ts
 
 1. **Tests Multiple Format Combinations**:
    - Different region prefix formats (EUC1, EUC1-, EU-Central-1, etc.)
-   - Different usage type formats (NatGateway-Hours, NGW-Hours, etc.)
+   - Different usage type formats (RegionalNatGateway-Hours, NatGateway-Hours, NGW-Hours, etc.)
 
 2. **Lists All NAT Gateway Products**: Shows all available NAT Gateway products without filters
 
@@ -136,10 +136,10 @@ npx ts-node tools/discover-nat-gateway-pricing.ts
 
 Testing different filter combinations...
 
-Trying prefix "EUC1" with usageType: EUC1-NatGateway-Hours
+Trying prefix "EUC1" with usageType: EUC1-RegionalNatGateway-Hours
   ✅ SUCCESS! Found pricing data
   Region: EU (Frankfurt)
-  UsageType: EUC1-NatGateway-Hours
+  UsageType: EUC1-RegionalNatGateway-Hours
   Operation: NatGateway
   Description: $0.045 per NAT Gateway Hour
   Price: $0.045/Hrs
@@ -148,9 +148,9 @@ Trying prefix "EUC1" with usageType: EUC1-NatGateway-Hours
 Found 200+ NAT Gateway products
 
 📍 Found NAT Gateway products for EU (Frankfurt):
-  - UsageType: EUC1-NatGateway-Hours
+  - UsageType: EUC1-RegionalNatGateway-Hours
     Description: $0.045 per NAT Gateway Hour
-  - UsageType: EUC1-NatGateway-Bytes
+  - UsageType: EUC1-RegionalNatGateway-Bytes
     Description: $0.045 per GB - data processed by NAT Gateways
 ```
 
@@ -201,7 +201,7 @@ When debug logging is enabled, you'll see:
    [DEBUG 2025-01-09T10:30:02.000Z] NAT Gateway hourly rate retrieved
    {
      "hourlyRate": 0.045,
-     "usageType": "EUC1-NatGateway-Hours"
+     "usageType": "EUC1-RegionalNatGateway-Hours"
    }
    ```
 

package/docs/README.md

@@ -0,0 +1,74 @@
+# CDK Cost Analyzer Documentation
+
+This directory contains the documentation for CDK Cost Analyzer, published to GitHub Pages.
+
+## Documentation Structure
+
+- **index.md** - Homepage with overview and quick start
+- **CONFIGURATION.md** - Configuration guide for thresholds, usage assumptions, and exclusions
+- **CI_CD.md** - CI/CD integration guide for GitHub Actions and GitLab CI
+- **CALCULATORS.md** - Resource calculator reference with cost calculation methods
+- **TROUBLESHOOTING.md** - Common issues and solutions
+- **DEVELOPMENT.md** - Local development, testing, and architecture
+- **RELEASE.md** - Release process documentation
+- **SINGLE-TEMPLATE-ANALYSIS.md** - Single template analysis guide
+- **NAT_GATEWAY_TESTING.md** - NAT Gateway testing and debugging guide
+
+## GitHub Pages Setup
+
+The documentation is automatically published to GitHub Pages when changes are pushed to the `main` branch.
+
+### Configuration Files
+
+- **_config.yml** - Jekyll configuration for GitHub Pages
+- **.github/workflows/pages.yml** - GitHub Actions workflow for deployment
+
+### Viewing the Documentation
+
+The documentation is available at: https://buildinginthecloud.github.io/cdk-cost-analyzer/
+
+### Local Preview
+
+To preview the documentation locally:
+
+```bash
+# Install Jekyll (requires Ruby)
+gem install bundler jekyll
+
+# Navigate to docs directory
+cd docs
+
+# Serve the site locally
+jekyll serve
+
+# Open http://localhost:4000 in your browser
+```
+
+### Theme
+
+The documentation uses the Cayman theme, which provides:
+- Clean, professional appearance
+- Responsive design for mobile devices
+- Syntax highlighting for code blocks
+- GitHub integration
+
+## Updating Documentation
+
+1. Edit the relevant Markdown files in the `docs/` directory
+2. Commit and push changes to the `main` branch
+3. GitHub Actions automatically rebuilds and deploys the site
+4. Changes are live within a few minutes
+
+## Documentation Standards
+
+All documentation follows these standards:
+
+- Professional, technical tone similar to AWS documentation
+- Active voice and imperative mood for instructions
+- US English spelling
+- Code blocks with language specification
+- No emojis or casual language
+- Complete, working examples
+- Proper AWS service name capitalization
+
+See `.kiro/steering/documentation-style.md` for complete style guidelines.

package/docs/TROUBLESHOOTING.md

@@ -14,11 +14,11 @@ This guide covers common issues and solutions when using CDK Cost Analyzer.
 
 ## CDK Synthesis Errors
 
-### Error: CDK synthesis timed out after 20 seconds
+### Error: CDK synthesis timed out after 15 seconds
 
 **Symptoms:**
 ```
-Error: CDK synthesis timed out after 20 seconds
+Error: CDK synthesis timed out after 15 seconds
 ```
 
 **Causes:**
@@ -64,7 +64,7 @@ cd infrastructure
 time npx cdk synth --all  # Measure synthesis time
 ```
 
-**Note:** The 20-second timeout is designed to prevent hanging processes in CI/CD environments while providing faster feedback. The timeout includes improved process cleanup with graceful termination (SIGTERM) followed by force termination (SIGKILL) after 2 seconds if needed. If your CDK application legitimately requires more time, consider optimizing the synthesis process or using a custom command with extended timeout.
+**Note:** The 15-second timeout is designed to prevent hanging processes in CI/CD environments while providing faster feedback. The timeout includes improved process cleanup with graceful termination (SIGTERM) followed by force termination (SIGKILL) after 1 second if needed. If your CDK application legitimately requires more time, consider optimizing the synthesis process or using a custom command with extended timeout.
 
 ### Error: CDK synthesis failed with exit code 1
 

package/docs/_config.yml

@@ -0,0 +1,63 @@
+title: CDK Cost Analyzer
+description: Analyze AWS CDK infrastructure changes and provide cost impact summaries
+theme: jekyll-theme-cayman
+show_downloads: true
+
+# GitHub repository
+repository: buildinginthecloud/cdk-cost-analyzer
+
+# Navigation
+navigation:
+  - title: Home
+    url: /
+  - title: Configuration
+    url: /CONFIGURATION
+  - title: CI/CD Integration
+    url: /CI_CD
+  - title: Calculators
+    url: /CALCULATORS
+  - title: Troubleshooting
+    url: /TROUBLESHOOTING
+  - title: Development
+    url: /DEVELOPMENT
+  - title: Release Process
+    url: /RELEASE
+
+# Plugins
+plugins:
+  - jekyll-relative-links
+  - jekyll-optional-front-matter
+  - jekyll-readme-index
+  - jekyll-titles-from-headings
+  - jekyll-github-metadata
+
+# Relative links configuration
+relative_links:
+  enabled: true
+  collections: true
+
+# Optional front matter
+optional_front_matter:
+  remove_originals: true
+
+# Titles from headings
+titles_from_headings:
+  enabled: true
+  strip_title: true
+  collections: true
+
+# Markdown settings
+markdown: kramdown
+kramdown:
+  input: GFM
+  hard_wrap: false
+  syntax_highlighter: rouge
+
+# Exclude from processing
+exclude:
+  - node_modules
+  - vendor
+  - .git
+  - .github
+  - .gitignore
+  - README.md

package/docs/index.md

@@ -0,0 +1,307 @@
+---
+layout: default
+title: Home
+---
+
+# CDK Cost Analyzer
+
+[![Test](https://github.com/buildinginthecloud/cdk-cost-analyzer/actions/workflows/test.yml/badge.svg)](https://github.com/buildinginthecloud/cdk-cost-analyzer/actions/workflows/test.yml)
+[![Build](https://github.com/buildinginthecloud/cdk-cost-analyzer/actions/workflows/build.yml/badge.svg)](https://github.com/buildinginthecloud/cdk-cost-analyzer/actions/workflows/build.yml)
+[![Release](https://github.com/buildinginthecloud/cdk-cost-analyzer/actions/workflows/release.yml/badge.svg)](https://github.com/buildinginthecloud/cdk-cost-analyzer/actions/workflows/release.yml)
+[![npm version](https://badge.fury.io/js/cdk-cost-analyzer.svg)](https://www.npmjs.com/package/cdk-cost-analyzer)
+
+A TypeScript package that analyzes AWS CDK infrastructure changes and provides cost impact summaries. Compare CloudFormation templates to understand the financial implications of your infrastructure changes before deployment.
+
+## Key Features
+
+- **Single Template Analysis** - Analyze individual CloudFormation templates for estimated monthly costs without comparison
+- **Template Comparison** - Parse and diff CloudFormation templates (JSON/YAML) to identify added, removed, and modified resources
+- **Cost Estimation** - Calculate monthly costs for AWS resources using real-time AWS Pricing API data
+- **Automatic CDK Synthesis** - Optionally synthesize CDK applications in CI/CD pipelines
+- **Cost Threshold Enforcement** - Fail pipelines when cost increases exceed configured thresholds
+- **Configuration Management** - Project-specific configuration for thresholds, usage assumptions, and exclusions
+- **Dual Interface** - Use as a CLI tool for quick analysis or import as a library for programmatic integration
+- **Clear Reporting** - Generate formatted cost reports in text, JSON, or Markdown formats
+- **GitLab Integration** - Post cost analysis reports as comments on GitLab merge requests
+- **FinOps Awareness** - Help developers understand cost implications during the development cycle
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install cdk-cost-analyzer
+```
+
+### AWS Credentials
+
+CDK Cost Analyzer requires AWS credentials to query the AWS Pricing API for real-time cost data.
+
+**Configure credentials**:
+
+```bash
+# Option 1: Environment variables
+export AWS_ACCESS_KEY_ID=your_access_key
+export AWS_SECRET_ACCESS_KEY=your_secret_key
+
+# Option 2: AWS CLI configuration
+aws configure
+
+# Option 3: IAM role (when running in AWS)
+# Credentials are automatically available
+```
+
+**Required IAM permissions**:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "pricing:GetProducts",
+        "pricing:DescribeServices"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+### CLI Usage
+
+```bash
+# Analyze a single CloudFormation template
+cdk-cost-analyzer analyze template.json --region us-east-1
+
+# Compare two CloudFormation templates
+cdk-cost-analyzer compare base.json target.json --region eu-central-1
+
+# Use pipeline command with automatic synthesis
+cdk-cost-analyzer pipeline \
+  --synth \
+  --cdk-app-path ./infrastructure \
+  --region eu-central-1 \
+  --config .cdk-cost-analyzer.yml
+```
+
+### Programmatic Usage
+
+```typescript
+import { analyzeSingleTemplate } from 'cdk-cost-analyzer';
+
+const result = await analyzeSingleTemplate({
+  template: templateContent,
+  region: 'us-east-1',
+  format: 'text'
+});
+
+console.log(`Total monthly cost: ${result.totalMonthlyCost} ${result.currency}`);
+```
+
+## Documentation
+
+### Getting Started
+
+- [Installation & Quick Start](#quick-start)
+- [Configuration Guide](CONFIGURATION.md) - Configure thresholds, usage assumptions, and exclusions
+- [CI/CD Integration](CI_CD.md) - GitHub Actions and GitLab CI/CD setup guides
+
+### Reference
+
+- [Resource Calculator Reference](CALCULATORS.md) - Detailed cost calculation methods and assumptions
+- [Single Template Analysis](SINGLE-TEMPLATE-ANALYSIS.md) - Analyze individual templates without comparison
+- [NAT Gateway Testing](NAT_GATEWAY_TESTING.md) - Testing and debugging NAT Gateway pricing
+
+### Operations
+
+- [Troubleshooting Guide](TROUBLESHOOTING.md) - Common issues and solutions
+- [Development Guide](DEVELOPMENT.md) - Local development, testing, and architecture
+- [Release Process](RELEASE.md) - How to release new versions
+
+## Supported Resource Types
+
+### Compute & Storage
+- AWS::EC2::Instance
+- AWS::S3::Bucket
+- AWS::Lambda::Function
+- AWS::RDS::DBInstance
+- AWS::DynamoDB::Table
+- AWS::ECS::Service
+
+### Networking
+- AWS::EC2::NatGateway
+- AWS::ElasticLoadBalancingV2::LoadBalancer (ALB & NLB)
+- AWS::EC2::VPCEndpoint
+
+### API & Content Delivery
+- AWS::ApiGateway::RestApi
+- AWS::ApiGatewayV2::Api (HTTP & WebSocket)
+- AWS::CloudFront::Distribution
+
+### Caching
+- AWS::ElastiCache::CacheCluster
+
+See the [Calculator Reference](CALCULATORS.md) for complete details on cost calculation methods and assumptions.
+
+## Configuration Example
+
+Create `.cdk-cost-analyzer.yml` in your project:
+
+```yaml
+# Cost thresholds
+thresholds:
+  default:
+    warning: 50
+    error: 200
+  environments:
+    production:
+      warning: 25
+      error: 100
+
+# Custom usage assumptions
+usageAssumptions:
+  s3:
+    storageGB: 500
+  lambda:
+    invocationsPerMonth: 5000000
+  natGateway:
+    dataProcessedGB: 500
+
+# Resource exclusions
+exclusions:
+  resourceTypes:
+    - AWS::IAM::Role
+    - AWS::Logs::LogGroup
+```
+
+See the [Configuration Guide](CONFIGURATION.md) for complete documentation.
+
+## CI/CD Integration
+
+### GitLab CI
+
+```yaml
+cost-analysis:
+  stage: cost-analysis
+  image: node:20
+  before_script:
+    - npm install -g cdk-cost-analyzer
+  script:
+    - |
+      cdk-cost-analyzer pipeline \
+        --synth \
+        --cdk-app-path ./infrastructure \
+        --region $AWS_REGION \
+        --format markdown \
+        --post-to-gitlab
+  only:
+    - merge_requests
+```
+
+### GitHub Actions
+
+```yaml
+name: CI
+on:
+  push:
+    branches: ['**']
+  pull_request:
+    branches: ['**']
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - run: npm run test:silent
+```
+
+See the [CI/CD Integration Guide](CI_CD.md) for complete documentation.
+
+## Report Formats
+
+### Text Format (Default)
+
+```
+============================================================
+CDK Cost Analysis Report
+============================================================
+
+Total Cost Delta: +$245.60
+
+ADDED RESOURCES:
+------------------------------------------------------------
+  • MyEC2Instance (AWS::EC2::Instance): $30.40 [high]
+  • MyRDSInstance (AWS::RDS::DBInstance): $215.20 [high]
+```
+
+### Markdown Format
+
+Perfect for GitLab merge request comments:
+
+```markdown
+# CDK Cost Analysis Report
+
+**Total Cost Delta:** +$245.60
+
+## Added Resources
+
+| Logical ID | Type | Monthly Cost |
+|------------|------|--------------|
+| MyEC2Instance | AWS::EC2::Instance | $30.40 |
+| MyRDSInstance | AWS::RDS::DBInstance | $215.20 |
+```
+
+### JSON Format
+
+For programmatic processing:
+
+```json
+{
+  "totalDelta": 245.60,
+  "currency": "USD",
+  "addedCosts": [...],
+  "removedCosts": [...],
+  "modifiedCosts": [...]
+}
+```
+
+## Contributing
+
+Contributions are welcome! This project uses [Projen](https://projen.io/) for project management.
+
+```bash
+# Clone the repository
+git clone https://github.com/buildinginthecloud/cdk-cost-analyzer.git
+cd cdk-cost-analyzer
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm run test
+```
+
+See the [Development Guide](DEVELOPMENT.md) for detailed development instructions.
+
+## License
+
+MIT
+
+## Links
+
+- [GitHub Repository](https://github.com/buildinginthecloud/cdk-cost-analyzer)
+- [NPM Package](https://www.npmjs.com/package/cdk-cost-analyzer)
+- [Issue Tracker](https://github.com/buildinginthecloud/cdk-cost-analyzer/issues)
+- [Releases](https://github.com/buildinginthecloud/cdk-cost-analyzer/releases)

package/package.json

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