api-tests-coverage 1.0.0

package/dist/src/errorCoverage.js

@@ -0,0 +1,698 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_CATEGORIES = void 0;
+exports.statusCodeToCategories = statusCodeToCategories;
+exports.parseErrorScenarios = parseErrorScenarios;
+exports.segmentMentionsEndpoint = segmentMentionsEndpoint;
+exports.matchesCategoryHeuristic = matchesCategoryHeuristic;
+exports.segmentCoversScenario = segmentCoversScenario;
+exports.analyzeErrorCoverage = analyzeErrorCoverage;
+exports.buildErrorCoverageReport = buildErrorCoverageReport;
+exports.generateErrorReports = generateErrorReports;
+const swagger_parser_1 = __importDefault(require("@apidevtools/swagger-parser"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const astAnalysisOrchestrator_1 = require("./ast/astAnalysisOrchestrator");
+exports.ERROR_CATEGORIES = [
+    'missing-parameter',
+    'invalid-value',
+    'unauthorized',
+    'forbidden',
+    'not-found',
+    'conflict',
+    'server-error',
+];
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Map a HTTP status code (and optional description) to one or more error
+ * categories that are relevant for heuristic matching.
+ */
+function statusCodeToCategories(statusCode, description) {
+    const descLower = description.toLowerCase();
+    const categories = [];
+    switch (statusCode) {
+        case 400:
+            // Distinguish by description when possible; otherwise include both
+            if (descLower.includes('missing') || descLower.includes('required')) {
+                categories.push('missing-parameter');
+            }
+            else if (descLower.includes('invalid') ||
+                descLower.includes('format') ||
+                descLower.includes('type') ||
+                descLower.includes('value')) {
+                categories.push('invalid-value');
+            }
+            else {
+                categories.push('missing-parameter', 'invalid-value');
+            }
+            break;
+        case 401:
+            categories.push('unauthorized');
+            break;
+        case 403:
+            categories.push('forbidden');
+            break;
+        case 404:
+            categories.push('not-found');
+            break;
+        case 409:
+            categories.push('conflict');
+            break;
+        case 422:
+            categories.push('invalid-value');
+            break;
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+            categories.push('server-error');
+            break;
+        default:
+            if (statusCode >= 400 && statusCode < 500) {
+                categories.push('invalid-value');
+            }
+            else if (statusCode >= 500) {
+                categories.push('server-error');
+            }
+    }
+    return categories;
+}
+// ─── Spec parsing ─────────────────────────────────────────────────────────────
+/**
+ * Parse an OpenAPI 3 spec and return all non-2xx (error) response scenarios.
+ */
+async function parseErrorScenarios(specPath) {
+    var _a;
+    const api = (await swagger_parser_1.default.dereference(specPath));
+    const scenarios = [];
+    if (!api.paths)
+        return scenarios;
+    for (const [apiPath, pathItem] of Object.entries(api.paths)) {
+        if (!pathItem)
+            continue;
+        for (const method of HTTP_METHODS) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            if (!operation.responses)
+                continue;
+            const endpoint = `${method.toUpperCase()} ${apiPath}`;
+            for (const [statusCodeStr, responseObj] of Object.entries(operation.responses)) {
+                const statusCode = parseInt(statusCodeStr, 10);
+                // Only 4xx and 5xx responses
+                if (isNaN(statusCode) || statusCode < 400)
+                    continue;
+                const response = responseObj;
+                const description = (_a = response.description) !== null && _a !== void 0 ? _a : '';
+                const categories = statusCodeToCategories(statusCode, description);
+                scenarios.push({
+                    id: `${endpoint}:${statusCode}`,
+                    endpoint,
+                    method: method.toUpperCase(),
+                    path: apiPath,
+                    statusCode,
+                    description,
+                    categories,
+                });
+            }
+        }
+    }
+    return scenarios;
+}
+/**
+ * Split a test file into individual test blocks (test / it declarations).
+ */
+function extractTestSegments(fileContents) {
+    const segments = [];
+    const declPattern = /\b(?:test|it)\s*\(\s*(['"`])([\s\S]*?)\1/g;
+    const positions = [];
+    let m;
+    while ((m = declPattern.exec(fileContents)) !== null) {
+        positions.push({ start: m.index, desc: m[2] });
+    }
+    for (let i = 0; i < positions.length; i++) {
+        const start = positions[i].start;
+        const end = i + 1 < positions.length ? positions[i + 1].start : fileContents.length;
+        segments.push({ description: positions[i].desc, content: fileContents.slice(start, end) });
+    }
+    return segments;
+}
+// ─── Endpoint matching ────────────────────────────────────────────────────────
+/**
+ * Return true if the test segment appears to exercise the endpoint associated
+ * with the given error scenario.
+ *
+ * Detection strategy (in order):
+ *  1. Description contains "METHOD /pathBase" (e.g. "POST /users")
+ *  2. Description contains the path base
+ *  3. Content contains the path base AND the HTTP method as a string literal
+ */
+function segmentMentionsEndpoint(segment, scenario) {
+    const contentLower = segment.content.toLowerCase();
+    const descLower = segment.description.toLowerCase();
+    const pathBase = scenario.path.split('{')[0].toLowerCase(); // e.g. "/users/" or "/users"
+    const methodLower = scenario.method.toLowerCase();
+    // 1. Description contains "METHOD /pathBase" phrase
+    if (descLower.includes(`${methodLower} ${pathBase}`))
+        return true;
+    // 2. Description contains the pathBase AND method keyword
+    if (descLower.includes(pathBase) && descLower.includes(methodLower))
+        return true;
+    // 3. Content contains pathBase (as a URL string) AND method (as a string literal)
+    const pathInContent = contentLower.includes(pathBase);
+    const methodInContent = contentLower.includes(`'${methodLower}'`) ||
+        contentLower.includes(`"${methodLower}"`);
+    if (pathInContent && methodInContent)
+        return true;
+    return false;
+}
+// ─── Category heuristics ──────────────────────────────────────────────────────
+/**
+ * Return true when a segment's description or content hints that it is
+ * exercising the given error category.
+ */
+function matchesCategoryHeuristic(segment, category) {
+    const descLower = segment.description.toLowerCase();
+    const contentLower = segment.content.toLowerCase();
+    switch (category) {
+        case 'missing-parameter':
+            // Description keywords
+            if (descLower.includes('missing') ||
+                descLower.includes('without') ||
+                descLower.includes('omit') ||
+                descLower.includes('no body') ||
+                descLower.includes('required field'))
+                return true;
+            // Code: delete obj.field or field = undefined
+            if (/delete\s+\w+\.\w+/.test(segment.content))
+                return true;
+            if (/\w+\s*=\s*undefined/.test(segment.content))
+                return true;
+            return false;
+        case 'invalid-value':
+            // Description keywords
+            if (descLower.includes('invalid') ||
+                descLower.includes('wrong type') ||
+                descLower.includes('bad value') ||
+                descLower.includes('malformed') ||
+                descLower.includes('incorrect format') ||
+                descLower.includes('out of range') ||
+                descLower.includes('exceeds'))
+                return true;
+            // Code: field: null or field: undefined
+            if (/['"]?\w+['"]?\s*:\s*(null|undefined)\b/.test(segment.content))
+                return true;
+            return false;
+        case 'unauthorized':
+            // Description keywords
+            if (descLower.includes('unauthorized') ||
+                descLower.includes('unauthenticated') ||
+                descLower.includes('no token') ||
+                descLower.includes('missing token') ||
+                descLower.includes('invalid token') ||
+                descLower.includes('no auth') ||
+                descLower.includes('missing auth') ||
+                descLower.includes('without auth') ||
+                descLower.includes('without token') ||
+                descLower.includes('missing api key') ||
+                descLower.includes('invalid api key') ||
+                descLower.includes('no api key'))
+                return true;
+            // Code: Authorization header with empty or bare "Bearer " token
+            if (/authorization\s*:\s*['"]\s*['"]/.test(contentLower))
+                return true;
+            if (/authorization\s*:\s*['"]bearer\s+['"]/.test(contentLower))
+                return true;
+            return false;
+        case 'forbidden':
+            // Description keywords
+            if (descLower.includes('forbidden') ||
+                descLower.includes('not allowed') ||
+                descLower.includes('insufficient permission') ||
+                descLower.includes('access denied') ||
+                descLower.includes('no permission'))
+                return true;
+            return false;
+        case 'not-found':
+            // Description keywords
+            if (descLower.includes('not found') ||
+                descLower.includes('nonexistent') ||
+                descLower.includes('non-existent') ||
+                descLower.includes('unknown id') ||
+                descLower.includes('does not exist') ||
+                descLower.includes('missing resource'))
+                return true;
+            // Code: very large / obviously fake numeric IDs (6+ digits)
+            if (/\/\d{6,}/.test(segment.content))
+                return true;
+            if (/['"`]\d{6,}['"`]/.test(segment.content))
+                return true;
+            // Nil UUID
+            if (/00000000-0000-0000-0000-000000000000/.test(segment.content))
+                return true;
+            return false;
+        case 'conflict':
+            if (descLower.includes('conflict') ||
+                descLower.includes('duplicate') ||
+                descLower.includes('already exists') ||
+                descLower.includes('already registered') ||
+                descLower.includes('already in use') ||
+                descLower.includes('taken'))
+                return true;
+            return false;
+        case 'server-error':
+            if (descLower.includes('server error') ||
+                descLower.includes('internal error') ||
+                descLower.includes('service unavailable') ||
+                descLower.includes('unexpected error'))
+                return true;
+            return false;
+    }
+}
+// ─── Coverage determination ───────────────────────────────────────────────────
+/**
+ * Return true if the segment contains a direct status-code assertion
+ * matching the scenario's status code.
+ *
+ * Recognised patterns:
+ *   .toBe(400)  .toEqual(400)  status === 400  statusCode: 400
+ *   expect(…).toBe(400)
+ */
+function hasStatusCodeAssertion(segment, statusCode) {
+    const patterns = [
+        new RegExp(`\\.toBe\\(\\s*${statusCode}\\s*\\)`),
+        new RegExp(`\\.toEqual\\(\\s*${statusCode}\\s*\\)`),
+        new RegExp(`status\\s*[=!]=+\\s*${statusCode}\\b`),
+        new RegExp(`statusCode\\s*[=!]=+\\s*${statusCode}\\b`),
+        new RegExp(`statusCode\\s*:\\s*${statusCode}\\b`),
+    ];
+    return patterns.some((p) => p.test(segment.content));
+}
+/**
+ * Return true if the segment contains an assertion on an error message body
+ * that is consistent with the given category.
+ *
+ * Examples detected:
+ *   expect(res.body).toHaveProperty('error')
+ *   expect(res.body.message).toContain('not found')
+ *   expect(thrown.message).toMatch(/unauthorized/i)
+ */
+function hasErrorMessageAssertion(segment, category) {
+    const contentLower = segment.content.toLowerCase();
+    // Generic: any error-body assertion
+    const hasBodyErrorProp = /tohaveproperty\s*\(\s*['"]error['"]/.test(contentLower) ||
+        /\.body\.error/.test(contentLower) ||
+        /\.body\.message/.test(contentLower);
+    if (!hasBodyErrorProp)
+        return false;
+    // Narrow by category keyword inside the assertion
+    const categoryKeywords = {
+        'missing-parameter': ['required', 'missing', 'must be provided'],
+        'invalid-value': ['invalid', 'format', 'type', 'must be', 'out of range'],
+        unauthorized: ['unauthorized', 'unauthenticated', 'token', 'api key'],
+        forbidden: ['forbidden', 'permission', 'access denied'],
+        'not-found': ['not found', 'does not exist'],
+        conflict: ['conflict', 'duplicate', 'already', 'in use'],
+        'server-error': ['internal', 'server error', 'unexpected'],
+    };
+    const keywords = categoryKeywords[category];
+    // If any keyword appears anywhere in the test content → match
+    return keywords.some((kw) => contentLower.includes(kw));
+}
+/**
+ * Decide whether a single test segment covers the given error scenario.
+ */
+function segmentCoversScenario(segment, scenario) {
+    // 1. Direct status code assertion
+    if (hasStatusCodeAssertion(segment, scenario.statusCode))
+        return true;
+    // 2. Category heuristics from description
+    for (const cat of scenario.categories) {
+        if (matchesCategoryHeuristic(segment, cat))
+            return true;
+    }
+    // 3. Indirect error-body assertion with category keywords
+    for (const cat of scenario.categories) {
+        if (hasErrorMessageAssertion(segment, cat))
+            return true;
+    }
+    return false;
+}
+// ─── AST augmentation ─────────────────────────────────────────────────────────
+/** Detect language from file extension for AST analysis. */
+function detectLanguageForAst(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    switch (ext) {
+        case '.ts':
+        case '.tsx': return 'typescript';
+        case '.js':
+        case '.jsx': return 'javascript';
+        case '.java': return 'java';
+        case '.kt':
+        case '.kts': return 'kotlin';
+        case '.py': return 'python';
+        case '.rb': return 'ruby';
+        case '.feature': return 'cucumber';
+        default: return 'auto';
+    }
+}
+/** Normalize a path for loose matching against OpenAPI templates. */
+function normalizeErrPath(p) {
+    return p.split('?')[0].replace(/\/$/, '').toLowerCase();
+}
+/**
+ * Return true when the interaction's path loosely matches the scenario path.
+ */
+function errorPathMatches(interaction, scenarioPath) {
+    var _a;
+    const iPath = normalizeErrPath((_a = interaction.normalizedPath) !== null && _a !== void 0 ? _a : interaction.path);
+    const aPath = normalizeErrPath(scenarioPath);
+    if (iPath === aPath)
+        return true;
+    const templateBase = aPath.split('{')[0].replace(/\/$/, '');
+    return !!(templateBase && iPath.startsWith(templateBase));
+}
+/**
+ * Map parameterScenarios strings to error categories.
+ */
+function scenariosToErrorCategories(scenarios) {
+    const s = scenarios.map((x) => x.toLowerCase());
+    const cats = [];
+    if (s.some((x) => x.includes('missing') || x.includes('required')))
+        cats.push('missing-parameter');
+    if (s.some((x) => x.includes('invalid') || x.includes('bad') || x.includes('malformed')))
+        cats.push('invalid-value');
+    if (s.some((x) => x.includes('unauth') || x.includes('401')))
+        cats.push('unauthorized');
+    if (s.some((x) => x.includes('forbidden') || x.includes('403')))
+        cats.push('forbidden');
+    if (s.some((x) => x.includes('not-found') || x.includes('404')))
+        cats.push('not-found');
+    if (s.some((x) => x.includes('conflict') || x.includes('409')))
+        cats.push('conflict');
+    if (s.some((x) => x.includes('server') || x.includes('5xx') || x.includes('500')))
+        cats.push('server-error');
+    return cats;
+}
+/**
+ * Build AST interaction map from test files for error coverage augmentation.
+ */
+function buildErrorAstMap(testFiles, astOptions) {
+    var _a;
+    (0, astAnalysisOrchestrator_1.registerAllAnalyzers)();
+    const context = (0, astAnalysisOrchestrator_1.buildAnalysisContext)(astOptions.astConfig, astOptions.deepConfig);
+    const map = new Map();
+    for (const filePath of testFiles) {
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const lang = detectLanguageForAst(filePath);
+        const interactions = (0, astAnalysisOrchestrator_1.analyzeFile)(content, filePath, lang, context);
+        for (const interaction of interactions) {
+            const key = normalizeErrPath((_a = interaction.normalizedPath) !== null && _a !== void 0 ? _a : interaction.path);
+            if (!map.has(key))
+                map.set(key, []);
+            map.get(key).push(interaction);
+        }
+    }
+    return map;
+}
+/**
+ * Check if AST interactions at the scenario's endpoint cover this error scenario.
+ * Returns truthy with metadata when an AST-derived signal is found.
+ */
+function checkAstErrorCoverage(matchingInteractions, scenario) {
+    let bestInteraction;
+    for (const interaction of matchingInteractions) {
+        // A status-code assertion indicates the test checks an HTTP status at this
+        // endpoint — a strong signal that the scenario is exercised
+        if (interaction.assertionType === 'status-code' ||
+            interaction.assertionType === 'fluent-chain') {
+            bestInteraction = interaction;
+        }
+        // parameterScenarios → error category matching
+        if (interaction.parameterScenarios && interaction.parameterScenarios.length > 0) {
+            const cats = scenariosToErrorCategories(interaction.parameterScenarios);
+            if (cats.some((c) => scenario.categories.includes(c))) {
+                bestInteraction = interaction;
+            }
+        }
+    }
+    if (!bestInteraction)
+        return { covered: false };
+    return {
+        covered: true,
+        astMetadata: {
+            sourceLanguage: bestInteraction.sourceLanguage,
+            resolutionType: bestInteraction.resolutionType,
+            confidence: bestInteraction.confidence,
+        },
+    };
+}
+// ─── Analysis ─────────────────────────────────────────────────────────────────
+/**
+ * Scan test files matching testGlob and determine which error scenarios are
+ * covered. Optionally augments text-scan results with AST-derived semantic
+ * signals when `astOptions` is provided.
+ */
+async function analyzeErrorCoverage(scenarios, testGlob, astOptions) {
+    const testFiles = await (0, fast_glob_1.default)(testGlob, { onlyFiles: true });
+    // Pre-read and segment all test files
+    const allSegments = [];
+    for (const filePath of testFiles) {
+        const contents = fs.readFileSync(filePath, 'utf-8');
+        allSegments.push(...extractTestSegments(contents));
+    }
+    // Build AST interaction map when AST options provided
+    const astMap = astOptions
+        ? buildErrorAstMap(testFiles, astOptions)
+        : null;
+    return scenarios.map((scenario) => {
+        var _a;
+        // ── Text-scan pass ──────────────────────────────────────────────────────
+        const matchedTests = [];
+        for (const segment of allSegments) {
+            if (segmentMentionsEndpoint(segment, scenario) && segmentCoversScenario(segment, scenario)) {
+                matchedTests.push(segment.description);
+            }
+        }
+        let covered = matchedTests.length > 0;
+        let astMetadata;
+        // ── AST augmentation pass ───────────────────────────────────────────────
+        if (astMap !== null && !covered) {
+            const matchingInteractions = [];
+            for (const [, interactions] of astMap) {
+                for (const interaction of interactions) {
+                    if (errorPathMatches(interaction, scenario.path) &&
+                        interaction.method.toUpperCase() === scenario.method.toUpperCase()) {
+                        matchingInteractions.push(interaction);
+                    }
+                }
+            }
+            if (matchingInteractions.length > 0) {
+                const astResult = checkAstErrorCoverage(matchingInteractions, scenario);
+                if (astResult.covered) {
+                    covered = true;
+                    astMetadata = astResult.astMetadata;
+                }
+            }
+        }
+        else if (covered && astMap !== null) {
+            // Already covered by text-scan — still attach AST metadata if available
+            const matchingInteractions = [];
+            for (const [, interactions] of astMap) {
+                for (const interaction of interactions) {
+                    if (errorPathMatches(interaction, scenario.path) &&
+                        interaction.method.toUpperCase() === scenario.method.toUpperCase()) {
+                        matchingInteractions.push(interaction);
+                    }
+                }
+            }
+            if (matchingInteractions.length > 0) {
+                const best = (_a = matchingInteractions.find((i) => i.confidence === 'high' || i.confidence === 'medium')) !== null && _a !== void 0 ? _a : matchingInteractions[0];
+                astMetadata = {
+                    sourceLanguage: best.sourceLanguage,
+                    resolutionType: best.resolutionType,
+                    confidence: best.confidence,
+                };
+            }
+        }
+        return { scenario, covered, matchedTests, astMetadata };
+    });
+}
+// ─── Report building ──────────────────────────────────────────────────────────
+/**
+ * Aggregate error coverage results into a summary report.
+ */
+function buildErrorCoverageReport(coverages) {
+    const total = coverages.length;
+    const covered = coverages.filter((c) => c.covered).length;
+    const percentage = total === 0 ? 0 : Math.round((covered / total) * 10000) / 100;
+    // Per-category tallies
+    const categorySummary = exports.ERROR_CATEGORIES.reduce((acc, cat) => {
+        acc[cat] = { total: 0, covered: 0 };
+        return acc;
+    }, {});
+    for (const c of coverages) {
+        for (const cat of c.scenario.categories) {
+            categorySummary[cat].total += 1;
+            if (c.covered)
+                categorySummary[cat].covered += 1;
+        }
+    }
+    return { total, covered, percentage, scenarios: coverages, categorySummary };
+}
+// ─── Report generation ────────────────────────────────────────────────────────
+/**
+ * Write JSON and HTML error-coverage reports to reportsDir.
+ */
+function generateErrorReports(report, reportsDir) {
+    if (!fs.existsSync(reportsDir)) {
+        fs.mkdirSync(reportsDir, { recursive: true });
+    }
+    // ── JSON ─────────────────────────────────────────────────────────────────
+    const jsonPath = path.join(reportsDir, 'error-coverage.json');
+    const jsonReport = {
+        total: report.total,
+        covered: report.covered,
+        percentage: report.percentage,
+        categorySummary: report.categorySummary,
+        scenarios: report.scenarios.map(({ scenario, covered, matchedTests }) => ({
+            id: scenario.id,
+            endpoint: scenario.endpoint,
+            statusCode: scenario.statusCode,
+            description: scenario.description,
+            categories: scenario.categories,
+            covered,
+            matchedTests,
+        })),
+    };
+    fs.writeFileSync(jsonPath, JSON.stringify(jsonReport, null, 2), 'utf-8');
+    // ── HTML ─────────────────────────────────────────────────────────────────
+    const htmlPath = path.join(reportsDir, 'error-coverage.html');
+    const catHeaders = exports.ERROR_CATEGORIES.map((c) => `<th>${c}</th>`).join('\n        ');
+    const rows = report.scenarios
+        .map(({ scenario, covered, matchedTests }) => {
+        const rowClass = covered ? 'covered' : 'uncovered';
+        const statusCell = covered ? '✅ Covered' : '❌ Not covered';
+        const catCells = exports.ERROR_CATEGORIES.map((cat) => {
+            if (!scenario.categories.includes(cat))
+                return '<td class="na">—</td>';
+            return covered ? '<td class="yes">✅</td>' : '<td class="no">❌</td>';
+        }).join('\n        ');
+        const testsHint = matchedTests.length > 0 ? matchedTests.map((t) => `• ${t}`).join('<br>') : '—';
+        return `      <tr class="${rowClass}" title="${testsHint}">
+        <td>${scenario.endpoint}</td>
+        <td>${scenario.statusCode}</td>
+        <td>${scenario.description}</td>
+        <td>${statusCell}</td>
+        ${catCells}
+      </tr>`;
+    })
+        .join('\n');
+    const catSummaryRows = exports.ERROR_CATEGORIES.map((cat) => {
+        const s = report.categorySummary[cat];
+        const pct = s.total === 0 ? '—' : `${Math.round((s.covered / s.total) * 100)}%`;
+        return `      <tr>
+        <td>${cat}</td>
+        <td>${s.covered}/${s.total}</td>
+        <td>${pct}</td>
+      </tr>`;
+    }).join('\n');
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Error Coverage Report</title>
+  <style>
+    body { font-family: sans-serif; padding: 2rem; }
+    h1, h2 { margin-bottom: 0.5rem; }
+    .summary { margin-bottom: 1.5rem; font-size: 1.1rem; }
+    table { border-collapse: collapse; width: 100%; margin-bottom: 2rem; }
+    th, td { border: 1px solid #ccc; padding: 0.5rem 1rem; text-align: left; }
+    th { background: #f0f0f0; }
+    tr.covered { background: #e6ffe6; }
+    tr.uncovered { background: #ffe6e6; }
+    td.yes { color: #2a7a2a; font-weight: bold; }
+    td.no  { color: #aa2222; font-weight: bold; }
+    td.na  { color: #999; }
+  </style>
+</head>
+<body>
+  <h1>Error Coverage Report</h1>
+  <div class="summary">
+    Covered: <strong>${report.covered}/${report.total}</strong> error scenarios
+    (<strong>${report.percentage}%</strong>)
+  </div>
+  <table>
+    <thead>
+      <tr>
+        <th>Endpoint</th>
+        <th>Status</th>
+        <th>Description</th>
+        <th>Coverage</th>
+        ${catHeaders}
+      </tr>
+    </thead>
+    <tbody>
+${rows}
+    </tbody>
+  </table>
+  <h2>Category Summary</h2>
+  <table>
+    <thead>
+      <tr><th>Category</th><th>Covered / Total</th><th>%</th></tr>
+    </thead>
+    <tbody>
+${catSummaryRows}
+    </tbody>
+  </table>
+</body>
+</html>`;
+    fs.writeFileSync(htmlPath, html, 'utf-8');
+}