@freshworks/shiftleft-tools 1.1.8

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

@@ -0,0 +1,167 @@
+#!/bin/bash
+
+###############################################################################
+# API Coverage Matrix Generator - Node.js Services (thin wrapper)
+#
+# Usage:
+#   ./node-api-coverage-matrix.sh [ROUTES_DIR] [POSTMAN_DIR]
+###############################################################################
+
+set -e
+
+if [ -t 1 ]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[1;33m'
+    BLUE='\033[0;34m'
+    NC='\033[0m'
+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)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+REPO_ROOT="$PROJECT_ROOT"
+
+source "$SCRIPT_DIR/../lib/cleanup-reports.sh"
+
+check_python() {
+    if ! command -v python3 &> /dev/null; then
+        log_error "Python 3 is required but not installed."
+        exit 2
+    fi
+}
+
+find_routes_dir() {
+    local base_dir="$1"
+    local patterns=("src/controllers" "src/routes" "routes" "lib/routes" "app/routes" "api/routes" "server/routes" "controllers")
+    for pattern in "${patterns[@]}"; do
+        if [ -d "$base_dir/$pattern" ]; then
+            echo "$base_dir/$pattern"
+            return 0
+        fi
+    done
+    echo ""
+}
+
+find_postman_dir() {
+    local base_dir="$1"
+    if [ -d "$base_dir/postman" ]; then
+        echo "$base_dir/postman"
+        return 0
+    fi
+    echo ""
+}
+
+validate_inputs() {
+    local routes_dir="$1"
+    local postman_dir="$2"
+    if [ -z "$routes_dir" ] || [ ! -d "$routes_dir" ]; then
+        log_error "Routes directory not found: $routes_dir"
+        exit 1
+    fi
+    JS_COUNT=$(find "$routes_dir" \( -name "*.js" -o -name "*.ts" \) 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$JS_COUNT" -eq 0 ]; then
+        log_error "No JavaScript/TypeScript files found in: $routes_dir"
+        exit 3
+    fi
+    log_info "Found $JS_COUNT route files"
+    if [ -z "$postman_dir" ] || [ ! -d "$postman_dir" ]; then
+        log_error "Postman directory not found: $postman_dir"
+        exit 1
+    fi
+}
+
+echo "========================================"
+echo "Node.js API Coverage Matrix Generator"
+echo "========================================"
+echo ""
+
+check_python
+
+if [ -n "${1:-}" ]; then
+    if [ -d "$1" ]; then
+        ROUTES_DIR="$(cd "$1" && pwd)"
+    elif [ -d "$REPO_ROOT/$1" ]; then
+        ROUTES_DIR="$(cd "$REPO_ROOT/$1" && pwd)"
+    else
+        ROUTES_DIR=$(find_routes_dir "$REPO_ROOT")
+        log_warn "Routes path '$1' not found; using: ${ROUTES_DIR:-<none>}"
+    fi
+else
+    ROUTES_DIR=$(find_routes_dir "$REPO_ROOT")
+fi
+
+if [ -n "${2:-}" ]; then
+    if [ -d "$2" ]; then
+        POSTMAN_DIR="$(cd "$2" && pwd)"
+    elif [ -d "$REPO_ROOT/$2" ]; then
+        POSTMAN_DIR="$(cd "$REPO_ROOT/$2" && pwd)"
+    else
+        POSTMAN_DIR=$(find_postman_dir "$REPO_ROOT")
+        log_warn "Postman path '$2' not found; using: ${POSTMAN_DIR:-<none>}"
+    fi
+else
+    POSTMAN_DIR=$(find_postman_dir "$REPO_ROOT")
+fi
+
+echo "Configuration:"
+echo "  ROUTES_DIR: ${ROUTES_DIR:-<not found>}"
+echo "  POSTMAN_DIR: ${POSTMAN_DIR:-<not found>}"
+echo ""
+
+validate_inputs "$ROUTES_DIR" "$POSTMAN_DIR"
+
+REPORTS_DIR="$POSTMAN_DIR/reports"
+mkdir -p "$REPORTS_DIR"
+cleanup_reports_by_pattern "$REPORTS_DIR" "api-coverage-matrix-*.html" 1
+cleanup_reports_by_pattern "$REPORTS_DIR" "api-coverage-matrix-*.json" 1
+
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+HTML_OUTPUT_FILE="$REPORTS_DIR/api-coverage-matrix-$TIMESTAMP.html"
+
+log_info "Generating coverage matrix..."
+cd "$SCRIPT_DIR/lib"
+if [ -f api_coverage_node.py ]; then
+    COVERAGE_SCRIPT=api_coverage_node.py
+else
+    log_error "api_coverage_node.py not found in lib/ — re-run shiftleft init-postman --stack node"
+    exit 1
+fi
+python3 "$COVERAGE_SCRIPT" \
+    --routes-dir "$ROUTES_DIR" \
+    --postman-dir "$POSTMAN_DIR" \
+    --html-output "$HTML_OUTPUT_FILE"
+PYTHON_EXIT=$?
+
+if [ $PYTHON_EXIT -ne 0 ]; then
+    log_error "Matrix generation failed (exit code: $PYTHON_EXIT)"
+    exit $PYTHON_EXIT
+fi
+
+LATEST_LINK="$REPORTS_DIR/api-coverage-matrix-latest.html"
+cp -f "$HTML_OUTPUT_FILE" "$LATEST_LINK"
+log_info "Latest report copy: $LATEST_LINK"
+
+CANONICAL_REPORTS_DIR="$REPO_ROOT/postman/reports"
+mkdir -p "$CANONICAL_REPORTS_DIR"
+REAL_REPORTS="$(cd "$REPORTS_DIR" && pwd)"
+REAL_CANON="$(cd "$CANONICAL_REPORTS_DIR" && pwd)"
+if [ "$REAL_REPORTS" != "$REAL_CANON" ]; then
+    cp -f "$HTML_OUTPUT_FILE" "$CANONICAL_REPORTS_DIR/"
+    cp -f "$LATEST_LINK" "$CANONICAL_REPORTS_DIR/api-coverage-matrix-latest.html"
+    JSON_SIDE="${HTML_OUTPUT_FILE%.html}.json"
+    [ -f "$JSON_SIDE" ] && cp -f "$JSON_SIDE" "$CANONICAL_REPORTS_DIR/"
+    log_info "Mirrored reports to $CANONICAL_REPORTS_DIR for Jenkins publishHTML."
+fi
+
+echo ""
+echo "========================================"
+log_success "Matrix Generation Complete"
+echo "HTML: $HTML_OUTPUT_FILE"
+echo "========================================"

package/templates/postman/scripts/report-generators/stage-report-artifacts.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+#
+# Copy JaCoCo and PIT HTML reports into postman/reports/artifacts/
+# so the combined quality report can link to them with relative URLs (Jenkins-safe).
+#
+# Usage: stage-report-artifacts.sh <project_root> <reports_dir>
+
+set -euo pipefail
+
+PROJECT_ROOT="${1:?project root required}"
+REPORTS_DIR="${2:?reports dir required}"
+ARTIFACTS_DIR="$REPORTS_DIR/artifacts"
+
+rm -rf "$ARTIFACTS_DIR"
+mkdir -p "$ARTIFACTS_DIR/jacoco" "$ARTIFACTS_DIR/pit"
+
+JACOCO_SRC="$PROJECT_ROOT/target/site/jacoco"
+if [ -d "$JACOCO_SRC" ] && [ -f "$JACOCO_SRC/index.html" ]; then
+    cp -R "$JACOCO_SRC/." "$ARTIFACTS_DIR/jacoco/"
+    echo "Staged JaCoCo report -> artifacts/jacoco/"
+fi
+
+PIT_DIR="$PROJECT_ROOT/target/pit-reports"
+if [ -f "$PIT_DIR/index.html" ]; then
+    cp -R "$PIT_DIR/." "$ARTIFACTS_DIR/pit/"
+    echo "Staged PIT report -> artifacts/pit/"
+fi

package/templates/postman/scripts/run-all.sh

@@ -0,0 +1,452 @@
+#!/bin/bash
+#
+# Unified Test & Quality Report Runner
+# =====================================
+# Single script that runs everything and produces one combined report:
+#   1. Unit Tests + JaCoCo Coverage
+#   2. PIT Mutation Testing
+#   3. Postman API Integration Tests (local or staging)
+#   4. API Coverage Matrix
+#   5. Combined Quality Report (all in one)
+#
+# Usage:
+#   ./run-all.sh [OPTIONS]
+#
+# Options:
+#   --env {local|staging}  Target environment for Postman tests (default: local)
+#   --skip-unit            Skip unit tests (use existing results)
+#   --skip-mutation        Skip mutation tests (use existing results)
+#   --skip-postman         Skip Postman API tests (use existing results)
+#   --skip-coverage        Skip API coverage matrix (use existing results)
+#   --skip-report          Skip quality report generation
+#   --no-delay             Skip delays between phases
+#   -h, --help             Show this help message
+#
+# Examples:
+#   ./run-all.sh                           # Run everything (local tests)
+#   ./run-all.sh --env staging             # Run everything against staging
+#   ./run-all.sh --skip-mutation           # Skip slow mutation tests
+#   ./run-all.sh --env staging --skip-unit # Staging tests only, no unit tests
+#
+
+set -euo pipefail
+
+# Colors
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+# Display name shown on the reports — the repo/service name, overridable.
+REPORT_LOGO="${SHIFTLEFT_REPORT_LOGO:-$(basename "$PROJECT_ROOT")}"
+export REPORT_LOGO
+POSTMAN_DIR="$(dirname "$SCRIPT_DIR")"
+REPORTS_DIR="$POSTMAN_DIR/reports"
+APP_PORT="${APP_PORT:-9090}"
+TIMESTAMP=$(date +"%Y%m%d-%H%M%S")
+
+# Environment selection (local or staging)
+POSTMAN_ENV="${POSTMAN_ENV:-local}"
+
+# Flags
+SKIP_UNIT=false
+SKIP_MUTATION=false
+SKIP_POSTMAN=false
+SKIP_COVERAGE=false
+SKIP_REPORT=false
+SKIP_DELAY=false
+
+# Track results
+UNIT_OK=false
+MUTATION_OK=false
+POSTMAN_OK=false
+COVERAGE_OK=false
+POSTMAN_RESULT=0
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help) head -31 "$0" | tail -29; exit 0 ;;
+        --env) POSTMAN_ENV="$2"; shift 2 ;;
+        --skip-unit) SKIP_UNIT=true; shift ;;
+        --skip-mutation) SKIP_MUTATION=true; shift ;;
+        --skip-postman) SKIP_POSTMAN=true; shift ;;
+        --skip-coverage) SKIP_COVERAGE=true; shift ;;
+        --skip-report) SKIP_REPORT=true; shift ;;
+        --no-delay) SKIP_DELAY=true; shift ;;
+        *) echo -e "${RED}Unknown option: $1${NC}"; exit 1 ;;
+    esac
+done
+
+# Validate environment
+if [[ ! "$POSTMAN_ENV" =~ ^(local|staging)$ ]]; then
+    echo -e "${RED}✗ Error: Invalid environment '$POSTMAN_ENV'${NC}"
+    echo -e "${YELLOW}Supported environments: local, staging${NC}"
+    exit 1
+fi
+
+# Cleanup function
+cleanup() {
+    # Stop Spring Boot if running
+    if [ -f "$SCRIPT_DIR/spring-boot-app.pid" ]; then
+        APP_PID=$(cat "$SCRIPT_DIR/spring-boot-app.pid" 2>/dev/null || echo "")
+        if [ -n "$APP_PID" ] && ps -p "$APP_PID" > /dev/null 2>&1; then
+            echo -e "${YELLOW}Stopping Spring Boot application...${NC}"
+            kill "$APP_PID" 2>/dev/null || true
+            sleep 2
+            if ps -p "$APP_PID" > /dev/null 2>&1; then
+                kill -9 "$APP_PID" 2>/dev/null || true
+            fi
+        fi
+        rm -f "$SCRIPT_DIR/spring-boot-app.pid"
+    fi
+    # Stop WireMock only if local Postman tests were actually run (mocks were started)
+    if [ "$SKIP_POSTMAN" = false ] && [ "$POSTMAN_ENV" = "local" ]; then
+        "$SCRIPT_DIR/infra/stop-mocks.sh" 2>/dev/null || true
+    fi
+}
+
+trap cleanup EXIT
+
+mkdir -p "$REPORTS_DIR"
+
+# Clean up old reports — keep only the latest 3 of each type
+echo -e "${YELLOW}Cleaning up old reports...${NC}"
+_keep_latest() {
+    local pattern="$1" keep="${2:-3}"
+    # shellcheck disable=SC2012
+    ls -t $pattern 2>/dev/null | tail -n +$((keep + 1)) | xargs rm -f 2>/dev/null || true
+}
+_keep_latest "$REPORTS_DIR/quality-report-*.html" 3
+if [ "$SKIP_POSTMAN" = false ]; then
+    # Remove only THIS environment's stale per-collection Newman HTML reports
+    # (they are about to be regenerated). Scoping the delete to the current env
+    # leaves the other env's reports — and the "View Details" links of its kept
+    # consolidated report — intact.
+    find "$REPORTS_DIR" -maxdepth 1 -name "test-${POSTMAN_ENV}-*.html" \
+        -delete 2>/dev/null || true
+fi
+if [ "$SKIP_POSTMAN" = false ]; then
+    _keep_latest "$REPORTS_DIR/consolidated-*.html" 3
+    _keep_latest "$REPORTS_DIR/consolidated-*.json" 3
+    rm -rf "$REPORTS_DIR"/json 2>/dev/null || true
+fi
+if [ "$SKIP_COVERAGE" = false ]; then
+    _keep_latest "$REPORTS_DIR/api-coverage-matrix-*.html" 3
+    _keep_latest "$REPORTS_DIR/api-coverage-matrix-*.json" 3
+fi
+echo -e "${GREEN}✓ Old reports cleaned${NC}"
+echo ""
+
+# Print header
+[ -t 1 ] && clear || true
+echo -e "${BOLD}${BLUE}╔════════════════════════════════════════════════════════════╗${NC}"
+echo -e "${BOLD}${BLUE}║         UNIFIED TEST & QUALITY REPORT RUNNER               ║${NC}"
+echo -e "${BOLD}${BLUE}║            (One Command, One Report!)                       ║${NC}"
+echo -e "${BOLD}${BLUE}╚════════════════════════════════════════════════════════════╝${NC}"
+echo ""
+echo -e "${CYAN}This will run:${NC}"
+[ "$SKIP_UNIT" = false ]     && echo -e "  ${BOLD}1.${NC} Unit Tests + JaCoCo Coverage" || echo -e "  ${BOLD}1.${NC} Unit Tests + JaCoCo Coverage ${YELLOW}(skipped)${NC}"
+[ "$SKIP_MUTATION" = false ] && echo -e "  ${BOLD}2.${NC} PIT Mutation Testing"          || echo -e "  ${BOLD}2.${NC} PIT Mutation Testing ${YELLOW}(skipped)${NC}"
+[ "$SKIP_POSTMAN" = false ]  && echo -e "  ${BOLD}3.${NC} Postman API Integration Tests" || echo -e "  ${BOLD}3.${NC} Postman API Integration Tests ${YELLOW}(skipped)${NC}"
+[ "$SKIP_COVERAGE" = false ] && echo -e "  ${BOLD}4.${NC} API Coverage Matrix"           || echo -e "  ${BOLD}4.${NC} API Coverage Matrix ${YELLOW}(skipped)${NC}"
+echo -e "  ${BOLD}5.${NC} Combined Quality Report"
+echo ""
+if [ "$SKIP_DELAY" = "false" ]; then
+    echo -e "${YELLOW}Starting in 2 seconds... (Ctrl+C to cancel)${NC}"
+    sleep 2
+fi
+
+# ============================================================================
+# PHASE 1: Unit Tests + JaCoCo Coverage
+# ============================================================================
+echo ""
+echo -e "${CYAN}╔════════════════════════════════════════════════════════════╗${NC}"
+echo -e "${CYAN}║  Phase 1: Unit Tests + JaCoCo Coverage                    ║${NC}"
+echo -e "${CYAN}╚════════════════════════════════════════════════════════════╝${NC}"
+echo ""
+
+SUREFIRE_DIR="$PROJECT_ROOT/target/surefire-reports"
+JACOCO_XML="$PROJECT_ROOT/target/site/jacoco/jacoco.xml"
+UNIT_JACOCO_XML="$PROJECT_ROOT/target/site/jacoco/jacoco-unit.xml"
+
+if [ "$SKIP_UNIT" = false ]; then
+    echo -e "${YELLOW}Running unit tests with coverage...${NC}"
+    cd "$PROJECT_ROOT"
+    if mvn clean test jacoco:report -q; then
+        echo -e "${GREEN}✓ Unit tests passed${NC}"
+        UNIT_OK=true
+    else
+        echo -e "${RED}✗ Unit tests had failures${NC}"
+        UNIT_OK=true  # Still continue - report will show failures
+    fi
+    # Preserve unit test JaCoCo before Postman phase overwrites it
+    if [ -f "$JACOCO_XML" ]; then
+        cp "$JACOCO_XML" "$UNIT_JACOCO_XML"
+        echo -e "${GREEN}✓ Unit test coverage preserved${NC}"
+    fi
+else
+    echo -e "${YELLOW}Skipping unit tests (using existing results)${NC}"
+    if [ -d "$SUREFIRE_DIR" ]; then
+        UNIT_OK=true
+        echo -e "${GREEN}✓ Found existing Surefire reports${NC}"
+    else
+        echo -e "${RED}✗ No existing Surefire reports found${NC}"
+    fi
+    # Check for preserved unit JaCoCo
+    if [ -f "$UNIT_JACOCO_XML" ]; then
+        echo -e "${GREEN}✓ Found preserved unit test coverage${NC}"
+    elif [ -f "$JACOCO_XML" ]; then
+        cp "$JACOCO_XML" "$UNIT_JACOCO_XML"
+        echo -e "${GREEN}✓ Current JaCoCo report preserved${NC}"
+    fi
+fi
+
+# ============================================================================
+# PHASE 2: PIT Mutation Testing
+# ============================================================================
+echo ""
+echo -e "${CYAN}╔════════════════════════════════════════════════════════════╗${NC}"
+echo -e "${CYAN}║  Phase 2: PIT Mutation Testing                            ║${NC}"
+echo -e "${CYAN}╚════════════════════════════════════════════════════════════╝${NC}"
+echo ""
+
+MUTATIONS_XML="$PROJECT_ROOT/target/pit-reports/mutations.xml"
+
+if [ "$SKIP_MUTATION" = false ]; then
+    echo -e "${YELLOW}Running mutation tests (this may take 2-3 minutes)...${NC}"
+    cd "$PROJECT_ROOT"
+    # PIT is profile-gated (-Pmutation-tests) per the setup-mutation-tests skill, so the
+    # profile's pinned pitest-maven version + pitest-junit5-plugin dependency are used.
+    # Without it, Maven resolves PIT's latest with no JUnit 5 plugin -> "could not run any tests".
+    # test-compile ensures test classes exist when unit tests were skipped/reused.
+    if mvn test-compile org.pitest:pitest-maven:mutationCoverage -Pmutation-tests -q 2>&1; then
+        echo -e "${GREEN}✓ Mutation tests completed${NC}"
+        MUTATION_OK=true
+    else
+        echo -e "${RED}✗ Mutation tests failed${NC}"
+    fi
+else
+    echo -e "${YELLOW}Skipping mutation tests (using existing results)${NC}"
+    if [ -f "$MUTATIONS_XML" ]; then
+        MUTATION_OK=true
+        echo -e "${GREEN}✓ Found existing mutation data${NC}"
+    else
+        echo -e "${RED}✗ No existing mutation data found${NC}"
+    fi
+fi
+
+# ============================================================================
+# PHASE 3: Postman API Integration Tests
+# ============================================================================
+echo ""
+echo -e "${CYAN}╔════════════════════════════════════════════════════════════╗${NC}"
+echo -e "${CYAN}║  Phase 3: Postman API Integration Tests ($(echo "$POSTMAN_ENV" | tr '[:lower:]' '[:upper:]'))      ║${NC}"
+echo -e "${CYAN}╚════════════════════════════════════════════════════════════╝${NC}"
+echo ""
+
+POSTMAN_PASSED=0
+POSTMAN_FAILED=0
+POSTMAN_JSON_DIR="$REPORTS_DIR/json"
+
+if [ "$SKIP_POSTMAN" = false ]; then
+    # Clear old JSON reports so totals only reflect this run
+    rm -rf "$POSTMAN_JSON_DIR"
+
+    # Delegate to appropriate test runner (local or staging)
+    set +e
+    if [ "$POSTMAN_ENV" = "staging" ]; then
+        "$SCRIPT_DIR/runners/run-tests-staging.sh"
+    else
+        "$SCRIPT_DIR/runners/run-tests-local.sh"
+    fi
+    POSTMAN_RESULT=$?
+    set -e
+
+    # Derive collection pass/fail counts from the consolidated JSON
+    # (individual JSON reports are cleaned up by run-*sh scripts after consolidation)
+    CONSOLIDATED_JSON=$(ls -t "$REPORTS_DIR"/consolidated-*.json 2>/dev/null | head -1)
+    if [ -n "$CONSOLIDATED_JSON" ] && [ -f "$CONSOLIDATED_JSON" ]; then
+        POSTMAN_PASSED=$(jq '.summary.collections.passed // 0' "$CONSOLIDATED_JSON" 2>/dev/null || echo "0")
+        POSTMAN_FAILED=$(jq '.summary.collections.failed // 0' "$CONSOLIDATED_JSON" 2>/dev/null || echo "0")
+        POSTMAN_OK=true
+    fi
+else
+    echo -e "${YELLOW}Skipping Postman tests (using existing results)${NC}"
+    if ls "$POSTMAN_JSON_DIR"/*.json 1>/dev/null 2>&1; then
+        POSTMAN_OK=true
+        echo -e "${GREEN}✓ Found existing Postman results${NC}"
+    else
+        echo -e "${RED}✗ No existing Postman results found${NC}"
+    fi
+fi
+
+# ============================================================================
+# PHASE 4: API Coverage Matrix
+# ============================================================================
+echo ""
+echo -e "${CYAN}╔════════════════════════════════════════════════════════════╗${NC}"
+echo -e "${CYAN}║  Phase 4: API Coverage Matrix                             ║${NC}"
+echo -e "${CYAN}╚════════════════════════════════════════════════════════════╝${NC}"
+echo ""
+
+API_COVERAGE_JSON=""
+
+if [ "$SKIP_COVERAGE" = false ]; then
+    echo -e "${YELLOW}Generating API coverage matrix...${NC}"
+    if "$SCRIPT_DIR/report-generators/java-api-coverage-matrix.sh" 2>&1; then
+        COVERAGE_OK=true
+        echo -e "${GREEN}✓ API coverage matrix generated${NC}"
+    else
+        echo -e "${RED}✗ API coverage matrix failed${NC}"
+    fi
+else
+    echo -e "${YELLOW}Skipping API coverage matrix (using existing results)${NC}"
+    if ls "$REPORTS_DIR"/api-coverage-matrix-*.json 1>/dev/null 2>&1; then
+        COVERAGE_OK=true
+        echo -e "${GREEN}✓ Found existing API coverage data${NC}"
+    fi
+fi
+
+# Load API coverage JSON if available
+COVERAGE_JSON_FILE=$(ls -t "$REPORTS_DIR"/api-coverage-matrix-*.json 2>/dev/null | head -1 || true)
+if [ -n "$COVERAGE_JSON_FILE" ] && [ -f "$COVERAGE_JSON_FILE" ]; then
+    API_COVERAGE_JSON=$(cat "$COVERAGE_JSON_FILE")
+fi
+
+# ============================================================================
+# PHASE 5: Generate Combined Quality Report
+# ============================================================================
+echo ""
+echo -e "${CYAN}╔════════════════════════════════════════════════════════════╗${NC}"
+echo -e "${CYAN}║  Phase 5: Generate Combined Quality Report                ║${NC}"
+echo -e "${CYAN}╚════════════════════════════════════════════════════════════╝${NC}"
+echo ""
+
+if [ "$SKIP_REPORT" = false ]; then
+    # Calculate Postman stats from the consolidated JSON
+    # (individual JSON reports are cleaned up by run-tests-local.sh after consolidation)
+    POSTMAN_TOTAL_ASSERTIONS=0
+    POSTMAN_PASSED_ASSERTIONS=0
+    POSTMAN_FAILED_ASSERTIONS=0
+    POSTMAN_TOTAL_REQUESTS=0
+    POSTMAN_DURATION="0"
+
+    CONSOLIDATED_JSON="${CONSOLIDATED_JSON:-$(ls -t "$REPORTS_DIR"/consolidated-*.json 2>/dev/null | head -1)}"
+    if [ -n "$CONSOLIDATED_JSON" ] && [ -f "$CONSOLIDATED_JSON" ]; then
+        POSTMAN_TOTAL_ASSERTIONS=$(jq '.summary.assertions.total // 0' "$CONSOLIDATED_JSON" 2>/dev/null || echo "0")
+        POSTMAN_FAILED_ASSERTIONS=$(jq '.summary.assertions.failed // 0' "$CONSOLIDATED_JSON" 2>/dev/null || echo "0")
+        POSTMAN_TOTAL_REQUESTS=$(jq '.summary.requests.total // 0' "$CONSOLIDATED_JSON" 2>/dev/null || echo "0")
+        POSTMAN_TOTAL_DURATION=$(jq '.summary.duration_ms // 0' "$CONSOLIDATED_JSON" 2>/dev/null || echo "0")
+        POSTMAN_PASSED_ASSERTIONS=$((POSTMAN_TOTAL_ASSERTIONS - POSTMAN_FAILED_ASSERTIONS))
+        POSTMAN_DURATION=$(echo "scale=2; $POSTMAN_TOTAL_DURATION / 1000" | bc 2>/dev/null || echo "0")
+    fi
+
+    COMBINED_OUTPUT="$REPORTS_DIR/quality-report-$TIMESTAMP.html"
+
+    echo -e "${YELLOW}Staging report artifacts for Jenkins-safe links...${NC}"
+    "$SCRIPT_DIR/report-generators/stage-report-artifacts.sh" "$PROJECT_ROOT" "$REPORTS_DIR"
+
+    echo -e "${YELLOW}Generating combined report...${NC}"
+
+# Build report arguments as an array to handle spaces properly
+REPORT_ARGS=(combined "$COMBINED_OUTPUT" --logo "$REPORT_LOGO" --env "$POSTMAN_ENV" --timestamp "$TIMESTAMP")
+
+# Unit test data (use preserved unit test JaCoCo, not the postman one)
+[ -d "$SUREFIRE_DIR" ] && REPORT_ARGS+=(--surefire-dir "$SUREFIRE_DIR")
+if [ -f "$UNIT_JACOCO_XML" ]; then
+    REPORT_ARGS+=(--jacoco-xml "$UNIT_JACOCO_XML")
+elif [ -f "$JACOCO_XML" ]; then
+    REPORT_ARGS+=(--jacoco-xml "$JACOCO_XML")
+fi
+[ -f "$MUTATIONS_XML" ] && REPORT_ARGS+=(--mutations-xml "$MUTATIONS_XML")
+
+# Postman data
+REPORT_ARGS+=(--postman-assertions-total "$POSTMAN_TOTAL_ASSERTIONS")
+REPORT_ARGS+=(--postman-assertions-passed "$POSTMAN_PASSED_ASSERTIONS")
+REPORT_ARGS+=(--postman-assertions-failed "$POSTMAN_FAILED_ASSERTIONS")
+REPORT_ARGS+=(--postman-requests "$POSTMAN_TOTAL_REQUESTS")
+REPORT_ARGS+=(--postman-duration "$POSTMAN_DURATION")
+REPORT_ARGS+=(--postman-collections-passed "$POSTMAN_PASSED")
+REPORT_ARGS+=(--postman-collections-failed "$POSTMAN_FAILED")
+
+# API coverage data
+TEMP_COVERAGE=""
+if [ -n "$API_COVERAGE_JSON" ]; then
+    TEMP_COVERAGE="/tmp/api-coverage-data-$$.json"
+    echo "$API_COVERAGE_JSON" > "$TEMP_COVERAGE"
+    REPORT_ARGS+=(--api-coverage-file "$TEMP_COVERAGE")
+fi
+
+# API coverage HTML (for linking)
+API_COVERAGE_HTML=$(ls -t "$REPORTS_DIR"/api-coverage-matrix-*.html 2>/dev/null | head -1 || true)
+if [ -n "$API_COVERAGE_HTML" ]; then
+    REPORT_ARGS+=(--api-coverage-html "$API_COVERAGE_HTML")
+fi
+
+# Newman JSON results directory (for per-collection details)
+if [ -d "$POSTMAN_JSON_DIR" ]; then
+    REPORT_ARGS+=(--postman-json-dir "$POSTMAN_JSON_DIR")
+fi
+
+# Consolidated Postman HTML report (for linking).
+# Always (re)generate it for THIS run's timestamp so the combined report never
+# links to a stale consolidated report whose per-collection detail files have
+# already been cleaned up. Only fall back to the newest existing one if this
+# run produced no consolidated JSON to render.
+POSTMAN_CONSOLIDATED_HTML="$REPORTS_DIR/consolidated-${POSTMAN_ENV}-${TIMESTAMP}.html"
+CONSOLIDATED_JSON_THIS_RUN="$REPORTS_DIR/consolidated-${POSTMAN_ENV}-${TIMESTAMP}.json"
+if [ ! -f "$POSTMAN_CONSOLIDATED_HTML" ] && [ -f "$CONSOLIDATED_JSON_THIS_RUN" ]; then
+    echo -e "${YELLOW}Generating consolidated HTML report...${NC}"
+    "$SCRIPT_DIR/report-generators/generate-consolidated-report.sh" "$POSTMAN_ENV" "$TIMESTAMP" "$REPORTS_DIR" "$POSTMAN_PASSED" "$POSTMAN_FAILED" 0 >/dev/null 2>&1 || true
+fi
+if [ ! -f "$POSTMAN_CONSOLIDATED_HTML" ]; then
+    POSTMAN_CONSOLIDATED_HTML=$(ls -t "$REPORTS_DIR"/consolidated-*.html 2>/dev/null | head -1 || true)
+fi
+if [ -n "$POSTMAN_CONSOLIDATED_HTML" ] && [ -f "$POSTMAN_CONSOLIDATED_HTML" ]; then
+    REPORT_ARGS+=(--postman-consolidated-html "$POSTMAN_CONSOLIDATED_HTML")
+fi
+
+    python3 "$SCRIPT_DIR/lib/report_generator.py" "${REPORT_ARGS[@]}"
+
+    # Cleanup temp file
+    [ -n "$TEMP_COVERAGE" ] && rm -f "$TEMP_COVERAGE"
+
+    if [ -f "$COMBINED_OUTPUT" ]; then
+        echo -e "${GREEN}✓ Combined report generated${NC}"
+
+        echo ""
+        echo -e "${CYAN}═══════════════════════════════════════════════════════════════${NC}"
+        echo -e "${BOLD}                    FINAL SUMMARY${NC}"
+        echo -e "${CYAN}═══════════════════════════════════════════════════════════════${NC}"
+        echo ""
+        echo -e "  ${BLUE}Environment:${NC} ${POSTMAN_ENV^^}"
+        echo ""
+        [ "$UNIT_OK" = true ]     && echo -e "  ${GREEN}✓${NC} Unit Tests"          || echo -e "  ${RED}✗${NC} Unit Tests"
+        [ "$MUTATION_OK" = true ] && echo -e "  ${GREEN}✓${NC} Mutation Testing"    || echo -e "  ${RED}✗${NC} Mutation Testing"
+        [ "$POSTMAN_OK" = true ]  && echo -e "  ${GREEN}✓${NC} Postman API Tests (${POSTMAN_PASSED} passed, ${POSTMAN_FAILED} failed)" || echo -e "  ${RED}✗${NC} Postman API Tests"
+        [ "$COVERAGE_OK" = true ] && echo -e "  ${GREEN}✓${NC} API Coverage Matrix" || echo -e "  ${RED}✗${NC} API Coverage Matrix"
+        echo ""
+        echo -e "  ${GREEN}Report:${NC} $COMBINED_OUTPUT"
+        echo ""
+        echo -e "${CYAN}═══════════════════════════════════════════════════════════════${NC}"
+
+        # Open report on macOS
+        if [[ "$OSTYPE" == "darwin"* ]]; then
+            open "$COMBINED_OUTPUT" 2>/dev/null || true
+        fi
+    else
+        echo -e "${RED}✗ Failed to generate combined report${NC}"
+        exit 1
+    fi
+else
+    echo -e "${YELLOW}Skipping quality report generation (--skip-report flag set)${NC}"
+fi
+
+exit $POSTMAN_RESULT