@freshworks/shiftleft-tools 1.1.8

package/templates/postman/scripts/report-generators/generate-consolidated-report.sh

@@ -0,0 +1,445 @@
+#!/usr/bin/env bash
+# =============================================================================
+# generate-consolidated-report.sh
+# Generates consolidated JSON and HTML reports from individual Newman JSON outputs
+#
+# Usage: ./generate-consolidated-report.sh <ENV> <TIMESTAMP> <REPORTS_DIR> <PASSED> <FAILED> <RESULT>
+#
+# This script can be used by any test runner that generates multiple collections
+# =============================================================================
+
+set -euo pipefail
+
+# Arguments
+ENV="${1:-local}"
+TIMESTAMP="${2:-$(date '+%Y%m%d-%H%M%S')}"
+REPORTS_DIR="${3:-./reports}"
+PASSED_COLLECTIONS="${4:-0}"
+FAILED_COLLECTIONS="${5:-0}"
+TEST_RESULT="${6:-0}"
+
+# Display name for the report. Honor REPORT_LOGO from the caller (run-all.sh
+# exports it); otherwise derive the repo/service name from this script's path so
+# standalone runners (e.g. a protected run-tests-staging.sh) still get it right.
+_GCR_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPORT_LOGO="${REPORT_LOGO:-$(basename "$(cd "$_GCR_DIR/../../.." && pwd)")}"
+
+# Colors
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+echo ""
+echo -e "${BLUE}╔════════════════════════════════════════════════════════════╗${NC}"
+echo -e "${BLUE}║  Generating Consolidated Report                            ║${NC}"
+echo -e "${BLUE}╚════════════════════════════════════════════════════════════╝${NC}"
+echo ""
+
+# Find JSON files for this timestamp
+JSON_DIR="$REPORTS_DIR/json"
+
+# Check if JSON directory exists and has files
+if [ ! -d "$JSON_DIR" ]; then
+    echo -e "${YELLOW}⚠ No JSON reports directory found: ${JSON_DIR}${NC}"
+    exit 0
+fi
+
+# Find JSON files matching the timestamp (including product subdirectories)
+mapfile -t JSON_FILES < <(find "$JSON_DIR" -name "*-${TIMESTAMP}.json" -type f 2>/dev/null | sort)
+
+if [ ${#JSON_FILES[@]} -eq 0 ]; then
+    echo -e "${YELLOW}⚠ No JSON reports found for timestamp: ${TIMESTAMP}${NC}"
+    exit 0
+fi
+
+echo -e "${BLUE}Found ${#JSON_FILES[@]} JSON report(s)${NC}"
+
+# Calculate consolidated stats using jq
+TOTAL_ASSERTIONS=$(jq -s '[.[].run.stats.assertions.total // 0] | add' "${JSON_FILES[@]}" 2>/dev/null || echo "0")
+FAILED_ASSERTIONS=$(jq -s '[.[].run.stats.assertions.failed // 0] | add' "${JSON_FILES[@]}" 2>/dev/null || echo "0")
+TOTAL_REQUESTS=$(jq -s '[.[].run.stats.requests.total // 0] | add' "${JSON_FILES[@]}" 2>/dev/null || echo "0")
+FAILED_REQUESTS=$(jq -s '[.[].run.stats.requests.failed // 0] | add' "${JSON_FILES[@]}" 2>/dev/null || echo "0")
+# Calculate duration as (completed - started) for each run, then sum
+TOTAL_DURATION=$(jq -s '[.[].run.timings | (.completed // 0) - (.started // 0)] | add' "${JSON_FILES[@]}" 2>/dev/null || echo "0")
+
+PASSED_ASSERTIONS=$((TOTAL_ASSERTIONS - FAILED_ASSERTIONS))
+DURATION_SEC=$(echo "scale=2; $TOTAL_DURATION / 1000" | bc 2>/dev/null || echo "0")
+TOTAL_COLLECTIONS=$((PASSED_COLLECTIONS + FAILED_COLLECTIONS))
+
+# Print summary to console
+echo ""
+echo -e "  ${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "  ${BOLD}CONSOLIDATED RESULTS - ${ENV}${NC}"
+echo -e "  ${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo -e "  Collections:  ${GREEN}${PASSED_COLLECTIONS} passed${NC}, ${RED}${FAILED_COLLECTIONS} failed${NC} (${TOTAL_COLLECTIONS} total)"
+echo -e "  Assertions:   ${GREEN}${PASSED_ASSERTIONS} passed${NC}, ${RED}${FAILED_ASSERTIONS} failed${NC} (${TOTAL_ASSERTIONS} total)"
+echo -e "  Requests:     ${TOTAL_REQUESTS} total, ${FAILED_REQUESTS} failed"
+echo -e "  Duration:     ${DURATION_SEC}s"
+echo ""
+
+# Generate consolidated JSON
+CONSOLIDATED_JSON="$REPORTS_DIR/consolidated-${ENV}-${TIMESTAMP}.json"
+STATUS=$([ "$TEST_RESULT" -eq 0 ] && echo 'PASSED' || echo 'FAILED')
+
+jq -s '{
+  info: {
+    name: "'"${REPORT_LOGO}"' Consolidated Test Report",
+    timestamp: "'"${TIMESTAMP}"'",
+    environment: "'"${ENV}"'"
+  },
+  summary: {
+    status: "'"${STATUS}"'",
+    collections: {
+      total: '"${TOTAL_COLLECTIONS}"',
+      passed: '"${PASSED_COLLECTIONS}"',
+      failed: '"${FAILED_COLLECTIONS}"'
+    },
+    assertions: {
+      total: '"${TOTAL_ASSERTIONS}"',
+      passed: '"${PASSED_ASSERTIONS}"',
+      failed: '"${FAILED_ASSERTIONS}"'
+    },
+    requests: {
+      total: '"${TOTAL_REQUESTS}"',
+      failed: '"${FAILED_REQUESTS}"'
+    },
+    duration_ms: '"${TOTAL_DURATION}"'
+  },
+  runs: [.[]]
+}' "${JSON_FILES[@]}" > "$CONSOLIDATED_JSON"
+
+echo -e "${GREEN}✓ JSON: ${CONSOLIDATED_JSON}${NC}"
+
+# Build collection links as JSON for Python
+COLLECTION_LINKS_JSON="["
+first=true
+for json_file in "${JSON_FILES[@]}"; do
+    col_name=$(basename "$json_file" "-${TIMESTAMP}.json")
+    # Extract collection name - handle different naming patterns
+    if [[ "$col_name" == staging-* ]]; then
+        html_file="${col_name}-${TIMESTAMP}.html"
+        display_name=$(echo "$col_name" | sed "s/^staging-//" | sed 's/-/ /g' | sed 's/^[0-9]* //')
+    elif [[ "$col_name" == test-* ]]; then
+        html_file="${col_name}-${TIMESTAMP}.html"
+        display_name=$(echo "$col_name" | sed "s/^test-${ENV}-//" | sed 's/-/ /g' | sed 's/^[0-9]* //')
+    else
+        html_file="${col_name}-${TIMESTAMP}.html"
+        display_name=$(echo "$col_name" | sed 's/-/ /g' | sed 's/^[0-9]* //')
+    fi
+    if [ "$first" = true ]; then
+        first=false
+    else
+        COLLECTION_LINKS_JSON="${COLLECTION_LINKS_JSON},"
+    fi
+    COLLECTION_LINKS_JSON="${COLLECTION_LINKS_JSON}{\"name\":\"${display_name}\",\"file\":\"${html_file}\"}"
+done
+COLLECTION_LINKS_JSON="${COLLECTION_LINKS_JSON}]"
+
+# Generate consolidated HTML using Python library
+CONSOLIDATED_HTML="$REPORTS_DIR/consolidated-${ENV}-${TIMESTAMP}.html"
+STATUS=$([ "$TEST_RESULT" -eq 0 ] && echo 'PASSED' || echo 'FAILED')
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+python3 "$SCRIPT_DIR/../lib/report_generator.py" consolidated "$CONSOLIDATED_HTML" \
+    --env "$ENV" \
+    --timestamp "$TIMESTAMP" \
+    --total-assertions "$TOTAL_ASSERTIONS" \
+    --passed-assertions "$PASSED_ASSERTIONS" \
+    --failed-assertions "$FAILED_ASSERTIONS" \
+    --total-requests "$TOTAL_REQUESTS" \
+    --duration "$DURATION_SEC" \
+    --status "$STATUS" \
+    --collection-links "$COLLECTION_LINKS_JSON"
+
+# Skip inline HTML generation - now handled by Python
+: << 'SKIP_INLINE_HTML'
+STATUS_CLASS=$([ "$TEST_RESULT" -eq 0 ] && echo 'passed' || echo 'failed')
+STATUS_TEXT=$([ "$TEST_RESULT" -eq 0 ] && echo '✓ ALL PASSED' || echo '✗ FAILURES')
+FAILED_CLASS=$([ "$FAILED_ASSERTIONS" -gt 0 ] && echo 'err' || echo '')
+
+cat > "$CONSOLIDATED_HTML" << EOF
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Test Results - ${ENV} | ${REPORT_LOGO}</title>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+    <style>
+        :root {
+            --color-primary: #6366f1;
+            --color-primary-light: #818cf8;
+            --color-success: #22c55e;
+            --color-success-light: #86efac;
+            --color-error: #ef4444;
+            --color-error-light: #fca5a5;
+            --color-warning: #f59e0b;
+            --color-bg: #0f172a;
+            --color-surface: #1e293b;
+            --color-surface-hover: #334155;
+            --color-border: #334155;
+            --color-text: #f1f5f9;
+            --color-text-muted: #94a3b8;
+            --shadow-sm: 0 1px 2px rgba(0,0,0,0.3);
+            --shadow-md: 0 4px 12px rgba(0,0,0,0.4);
+            --shadow-lg: 0 8px 24px rgba(0,0,0,0.5);
+            --radius: 16px;
+            --radius-sm: 10px;
+        }
+
+        * { box-sizing: border-box; margin: 0; padding: 0; }
+
+        body {
+            font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+            background: var(--color-bg);
+            color: var(--color-text);
+            min-height: 100vh;
+            padding: 2.5rem;
+            line-height: 1.6;
+        }
+
+        .container { max-width: 1000px; margin: 0 auto; }
+
+        /* Header */
+        header {
+            text-align: center;
+            margin-bottom: 3rem;
+        }
+
+        .logo {
+            font-size: 0.85rem;
+            font-weight: 600;
+            color: var(--color-primary-light);
+            text-transform: uppercase;
+            letter-spacing: 0.1em;
+            margin-bottom: 0.75rem;
+        }
+
+        h1 {
+            font-size: 2.5rem;
+            font-weight: 700;
+            color: var(--color-text);
+            margin-bottom: 0.5rem;
+            letter-spacing: -0.02em;
+        }
+
+        .subtitle {
+            color: var(--color-text-muted);
+            font-size: 0.95rem;
+        }
+
+        .status-badge {
+            display: inline-flex;
+            align-items: center;
+            gap: 0.5rem;
+            padding: 0.75rem 2rem;
+            border-radius: 50px;
+            font-weight: 600;
+            font-size: 1rem;
+            margin-top: 1.5rem;
+            box-shadow: var(--shadow-md);
+            transition: transform 0.2s, box-shadow 0.2s;
+        }
+
+        .status-badge:hover {
+            transform: translateY(-2px);
+            box-shadow: var(--shadow-lg);
+        }
+
+        .status-badge.passed {
+            background: linear-gradient(135deg, var(--color-success), #16a34a);
+            color: white;
+        }
+
+        .status-badge.failed {
+            background: linear-gradient(135deg, var(--color-error), #dc2626);
+            color: white;
+        }
+
+        /* Stats Grid */
+        .stats-grid {
+            display: grid;
+            grid-template-columns: repeat(4, 1fr);
+            gap: 1rem;
+            margin: 2.5rem 0;
+        }
+
+        .stat-card {
+            background: var(--color-surface);
+            border: 1px solid var(--color-border);
+            border-radius: var(--radius);
+            padding: 1.5rem;
+            text-align: center;
+            transition: transform 0.2s, box-shadow 0.2s, border-color 0.2s;
+        }
+
+        .stat-card:hover {
+            transform: translateY(-4px);
+            box-shadow: var(--shadow-md);
+            border-color: var(--color-primary);
+        }
+
+        .stat-value {
+            font-size: 2.5rem;
+            font-weight: 700;
+            color: var(--color-primary-light);
+            line-height: 1;
+            margin-bottom: 0.5rem;
+        }
+
+        .stat-value.success { color: var(--color-success); }
+        .stat-value.error { color: var(--color-error); }
+
+        .stat-label {
+            color: var(--color-text-muted);
+            font-size: 0.75rem;
+            font-weight: 500;
+            text-transform: uppercase;
+            letter-spacing: 0.08em;
+        }
+
+        /* Collections Section */
+        .section {
+            margin-top: 2.5rem;
+        }
+
+        .section-header {
+            display: flex;
+            align-items: center;
+            gap: 0.75rem;
+            margin-bottom: 1.25rem;
+        }
+
+        .section-header h2 {
+            font-size: 1.25rem;
+            font-weight: 600;
+            color: var(--color-text);
+        }
+
+        .section-header .count {
+            background: var(--color-surface);
+            border: 1px solid var(--color-border);
+            padding: 0.25rem 0.75rem;
+            border-radius: 20px;
+            font-size: 0.8rem;
+            color: var(--color-text-muted);
+        }
+
+        .collection-list { list-style: none; }
+
+        .collection-item {
+            background: var(--color-surface);
+            border: 1px solid var(--color-border);
+            border-radius: var(--radius-sm);
+            padding: 1rem 1.25rem;
+            margin-bottom: 0.625rem;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            transition: all 0.2s;
+        }
+
+        .collection-item:hover {
+            background: var(--color-surface-hover);
+            border-color: var(--color-primary);
+            transform: translateX(4px);
+        }
+
+        .collection-name {
+            font-weight: 500;
+            color: var(--color-text);
+        }
+
+        .collection-link {
+            color: var(--color-primary-light);
+            text-decoration: none;
+            font-size: 0.875rem;
+            font-weight: 500;
+            display: inline-flex;
+            align-items: center;
+            gap: 0.375rem;
+            transition: color 0.2s;
+        }
+
+        .collection-link:hover {
+            color: var(--color-text);
+        }
+
+        /* Footer */
+        footer {
+            text-align: center;
+            margin-top: 3rem;
+            padding-top: 1.5rem;
+            border-top: 1px solid var(--color-border);
+            color: var(--color-text-muted);
+            font-size: 0.85rem;
+        }
+
+        footer span {
+            opacity: 0.5;
+            margin: 0 0.5rem;
+        }
+
+        @media (max-width: 768px) {
+            body { padding: 1.5rem; }
+            h1 { font-size: 1.75rem; }
+            .stats-grid { grid-template-columns: repeat(2, 1fr); }
+            .stat-value { font-size: 2rem; }
+        }
+    </style>
+</head>
+<body>
+<div class="container">
+    <header>
+        <div class="logo">${REPORT_LOGO}</div>
+        <h1>API Test Results</h1>
+        <p class="subtitle">${ENV} environment • ${TIMESTAMP}</p>
+        <div class="status-badge ${STATUS_CLASS}">${STATUS_TEXT}</div>
+    </header>
+
+    <div class="stats-grid">
+        <div class="stat-card">
+            <div class="stat-value">${TOTAL_ASSERTIONS}</div>
+            <div class="stat-label">Total Tests</div>
+        </div>
+        <div class="stat-card">
+            <div class="stat-value success">${PASSED_ASSERTIONS}</div>
+            <div class="stat-label">Passed</div>
+        </div>
+        <div class="stat-card">
+            <div class="stat-value ${FAILED_CLASS}">${FAILED_ASSERTIONS}</div>
+            <div class="stat-label">Failed</div>
+        </div>
+        <div class="stat-card">
+            <div class="stat-value">${TOTAL_REQUESTS}</div>
+            <div class="stat-label">Requests</div>
+        </div>
+    </div>
+
+    <div class="section">
+        <div class="section-header">
+            <h2>Collection Reports</h2>
+            <span class="count">${TOTAL_COLLECTIONS} collections</span>
+        </div>
+        <ul class="collection-list">${COLLECTION_LINKS}</ul>
+    </div>
+
+    <footer>
+        Duration: ${DURATION_SEC}s <span>•</span> Generated by Newman
+    </footer>
+</div>
+</body>
+</html>
+EOF
+SKIP_INLINE_HTML
+
+echo -e "${GREEN}✓ HTML: ${CONSOLIDATED_HTML}${NC}"
+echo ""
+echo -e "${BLUE}Open consolidated report:${NC}"
+echo -e "  ${BOLD}open ${CONSOLIDATED_HTML}${NC}"
+echo ""
+

package/templates/postman/scripts/report-generators/java-api-coverage-matrix.sh

@@ -0,0 +1,257 @@
+#!/bin/bash
+
+###############################################################################
+# API Coverage Matrix Generator
+#
+# Works with ANY Java Spring Boot service that has:
+# - Java controllers with @RequestMapping, @GetMapping, @PostMapping, etc.
+# - Postman collections with test assertions
+#
+# Tracks:
+# - Status codes tested per endpoint
+# - Test count per endpoint
+# - Response body assertions count
+# - Request body variations count
+# - Query parameter coverage
+# - Request body field coverage (for POST/PUT/PATCH)
+#
+# Usage:
+#   ./java-api-coverage-matrix.sh [CONTROLLER_DIR] [POSTMAN_DIR]
+#
+# Arguments:
+#   CONTROLLER_DIR  - Path to Java controller directory (auto-detected if not provided)
+#   POSTMAN_DIR     - Path to Postman collections directory (default: ./postman)
+#                     Can point to root postman/ or directly to collections subfolder
+#
+# Examples:
+#   # Auto-detect everything
+#   ./java-api-coverage-matrix.sh
+#
+#   # Specify controller dir only (postman/ auto-detected)
+#   ./java-api-coverage-matrix.sh ./src/main/java/com/company/controller
+#
+#   # Specify both paths explicitly
+#   ./java-api-coverage-matrix.sh \
+#       ./src/main/java/com/company/controller \
+#       ./postman/collections
+#
+# Exit Codes:
+#   0 - Success
+#   1 - Configuration error (missing directories)
+#   2 - Python not available
+#   3 - No endpoints found
+#   4 - No Postman collections found
+###############################################################################
+
+set -e
+
+# Colors for output (disabled if not a terminal)
+if [ -t 1 ]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[1;33m'
+    BLUE='\033[0;34m'
+    NC='\033[0m' # No Color
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    NC=''
+fi
+
+log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
+log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1" >&2; }
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+#------------------------------------------------------------------------------
+# Check Python availability
+#------------------------------------------------------------------------------
+check_python() {
+    if ! command -v python3 &> /dev/null; then
+        log_error "Python 3 is required but not installed."
+        exit 2
+    fi
+    
+    PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+    PYTHON_MAJOR=$(echo "$PYTHON_VERSION" | cut -d. -f1)
+    PYTHON_MINOR=$(echo "$PYTHON_VERSION" | cut -d. -f2)
+    
+    if [ "$PYTHON_MAJOR" -lt 3 ] || ([ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 6 ]); then
+        log_error "Python 3.6+ is required. Found: Python $PYTHON_VERSION"
+        exit 2
+    fi
+    
+    log_info "Using Python $PYTHON_VERSION"
+}
+
+#------------------------------------------------------------------------------
+# Find controller directory
+#------------------------------------------------------------------------------
+find_controller_dir() {
+    local base_dir="$1"
+    local max_depth="${2:-10}"
+    
+    found=$(find "$base_dir" -maxdepth "$max_depth" -type d -name "controller" \
+        ! -path "*/target/*" \
+        ! -path "*/build/*" \
+        ! -path "*/.git/*" \
+        ! -path "*/node_modules/*" \
+        2>/dev/null | while read -r dir; do
+        if ls "$dir"/*.java >/dev/null 2>&1; then
+            if echo "$dir" | grep -q "src/main/java"; then
+                echo "$dir"
+                break
+            fi
+        fi
+    done | head -1)
+    
+    if [ -n "$found" ]; then
+        echo "$found"
+        return 0
+    fi
+    
+    found=$(find "$base_dir" -maxdepth "$max_depth" -type d -name "controller" \
+        ! -path "*/target/*" \
+        ! -path "*/build/*" \
+        ! -path "*/.git/*" \
+        ! -path "*/node_modules/*" \
+        2>/dev/null | while read -r dir; do
+        if ls "$dir"/*.java >/dev/null 2>&1; then
+            echo "$dir"
+            break
+        fi
+    done | head -1)
+    
+    echo "$found"
+}
+
+find_postman_dir() {
+    local base_dir="$1"
+    local patterns=("postman" "tests/postman" "api-tests" "integration-tests/postman")
+    
+    for pattern in "${patterns[@]}"; do
+        if [ -d "$base_dir/$pattern" ]; then
+            echo "$base_dir/$pattern"
+            return 0
+        fi
+    done
+    echo ""
+}
+
+#------------------------------------------------------------------------------
+# Validate inputs
+#------------------------------------------------------------------------------
+validate_inputs() {
+    local controller_dir="$1"
+    local postman_dir="$2"
+    
+    if [ -z "$controller_dir" ] || [ ! -d "$controller_dir" ]; then
+        log_error "Controller directory not found: $controller_dir"
+        echo ""
+        echo "Usage: $0 [CONTROLLER_DIR] [POSTMAN_DIR]"
+        exit 1
+    fi
+    
+    JAVA_COUNT=$(find "$controller_dir" -name "*.java" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$JAVA_COUNT" -eq 0 ]; then
+        log_error "No Java files found in: $controller_dir"
+        exit 3
+    fi
+    log_info "Found $JAVA_COUNT Java controller files"
+    
+    if [ -z "$postman_dir" ] || [ ! -d "$postman_dir" ]; then
+        log_error "Postman directory not found: $postman_dir"
+        exit 1
+    fi
+    
+    # Check for collections in top level or in collections/ subdirectory
+    COLLECTION_COUNT=$(find "$postman_dir" -maxdepth 1 -name "*.json" ! -name "*environment*" ! -name "package*.json" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$COLLECTION_COUNT" -eq 0 ] && [ -d "$postman_dir/collections" ]; then
+        COLLECTION_COUNT=$(find "$postman_dir/collections" -name "*.json" 2>/dev/null | wc -l | tr -d ' ')
+    fi
+    if [ "$COLLECTION_COUNT" -eq 0 ]; then
+        log_error "No Postman collection files found in: $postman_dir or $postman_dir/collections"
+        exit 4
+    fi
+    log_info "Found $COLLECTION_COUNT Postman collection files"
+}
+
+#------------------------------------------------------------------------------
+# Clean up old reports (keep only last one)
+#------------------------------------------------------------------------------
+source "$SCRIPT_DIR/../lib/cleanup-reports.sh"
+
+cleanup_old_reports() {
+    cleanup_reports_by_pattern "$1" "api-coverage-matrix-*.html" "${2:-1}"
+}
+
+#------------------------------------------------------------------------------
+# Main script
+#------------------------------------------------------------------------------
+
+echo "========================================"
+echo "API Coverage Matrix Generator"
+echo "========================================"
+echo ""
+
+check_python
+
+# Determine directories
+if [ -n "$1" ] && [ -d "$1" ]; then
+    CONTROLLER_DIR="$1"
+else
+    PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." 2>/dev/null && pwd)" || PROJECT_ROOT="$(pwd)"
+    CONTROLLER_DIR=$(find_controller_dir "$PROJECT_ROOT")
+fi
+
+if [ -n "$2" ] && [ -d "$2" ]; then
+    POSTMAN_DIR="$2"
+else
+    PROJECT_ROOT="${PROJECT_ROOT:-$(pwd)}"
+    POSTMAN_DIR=$(find_postman_dir "$PROJECT_ROOT")
+fi
+
+echo "Configuration:"
+echo "  CONTROLLER_DIR: ${CONTROLLER_DIR:-<not found>}"
+echo "  POSTMAN_DIR: ${POSTMAN_DIR:-<not found>}"
+echo ""
+
+validate_inputs "$CONTROLLER_DIR" "$POSTMAN_DIR"
+
+# Create reports directory
+REPORTS_DIR="$POSTMAN_DIR/reports"
+mkdir -p "$REPORTS_DIR"
+
+# Cleanup old reports
+cleanup_old_reports "$REPORTS_DIR" 1
+
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+HTML_OUTPUT_FILE="$REPORTS_DIR/api-coverage-matrix-$TIMESTAMP.html"
+
+log_info "Generating coverage matrix..."
+
+# Run the external Python module (much cleaner than embedded code)
+cd "$SCRIPT_DIR/../lib"
+python3 api_coverage.py \
+    --controller-dir "$CONTROLLER_DIR" \
+    --postman-dir "$POSTMAN_DIR" \
+    --html-output "$HTML_OUTPUT_FILE"
+
+# Capture exit code
+PYTHON_EXIT=$?
+
+if [ $PYTHON_EXIT -ne 0 ]; then
+    echo ""
+    log_error "Matrix generation failed (exit code: $PYTHON_EXIT)"
+    exit $PYTHON_EXIT
+fi
+
+echo ""
+echo "========================================"
+log_success "Matrix Generation Complete"
+echo "HTML: $HTML_OUTPUT_FILE"
+echo "========================================"