api-tests-coverage 1.0.0

package/dist/src/pluginLoader.d.ts

@@ -0,0 +1,51 @@
+import { CoverageResult } from './reporting';
+import { CoverageConfig } from './config';
+/**
+ * Context object passed to every plugin's `analyze` function.
+ */
+export interface PluginContext {
+    /** Raw OpenAPI / Swagger spec object (already parsed). May be undefined if not available. */
+    spec?: unknown;
+    /** Glob patterns that were used to locate test files */
+    testPatterns: string[];
+    /** Coverage results produced by the built-in analysers */
+    results: CoverageResult[];
+    /** The resolved configuration that the analyser is running with */
+    config: CoverageConfig;
+}
+/**
+ * The shape a plugin module must export.
+ */
+export interface Plugin {
+    /**
+     * Main entry-point of the plugin.
+     *
+     * @param context  Analysis context (spec, tests, results, config)
+     * @returns A `CoverageResult` (or array of `CoverageResult`s) to append to the report.
+     */
+    analyze: (context: PluginContext) => Promise<CoverageResult | CoverageResult[]>;
+}
+/**
+ * Dynamically load a plugin module from the given path.
+ *
+ * Plugin paths may be:
+ * - Absolute paths
+ * - Relative paths (resolved against `basedir`, default: `process.cwd()`)
+ * - Node module names (resolved normally)
+ *
+ * Errors during loading are caught and logged as warnings; `null` is returned.
+ */
+export declare function loadPlugin(pluginPath: string, basedir?: string): Promise<Plugin | null>;
+/**
+ * Run all plugins listed in `config.plugins`, collect their results, and
+ * return them as an array of `CoverageResult` objects.
+ *
+ * Errors thrown by individual plugins are caught, logged as warnings, and
+ * do not prevent other plugins from running.
+ *
+ * @param config    Resolved configuration containing the `plugins` list
+ * @param context   Context passed to each plugin's `analyze` function
+ * @param basedir   Directory used to resolve relative plugin paths (default: cwd)
+ */
+export declare function runPlugins(config: CoverageConfig, context: PluginContext, basedir?: string): Promise<CoverageResult[]>;
+//# sourceMappingURL=pluginLoader.d.ts.map

package/dist/src/pluginLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginLoader.d.ts","sourceRoot":"","sources":["../../src/pluginLoader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAI1C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,6FAA6F;IAC7F,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wDAAwD;IACxD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0DAA0D;IAC1D,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,mEAAmE;IACnE,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;OAKG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,GAAG,cAAc,EAAE,CAAC,CAAC;CACjF;AAID;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwB7F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,EAAE,CAAC,CAsB3B"}

package/dist/src/pluginLoader.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPlugin = loadPlugin;
+exports.runPlugins = runPlugins;
+// ─── Loader ───────────────────────────────────────────────────────────────────
+/**
+ * Dynamically load a plugin module from the given path.
+ *
+ * Plugin paths may be:
+ * - Absolute paths
+ * - Relative paths (resolved against `basedir`, default: `process.cwd()`)
+ * - Node module names (resolved normally)
+ *
+ * Errors during loading are caught and logged as warnings; `null` is returned.
+ */
+async function loadPlugin(pluginPath, basedir) {
+    const base = basedir !== null && basedir !== void 0 ? basedir : process.cwd();
+    let resolvedPath = pluginPath;
+    // Resolve relative paths against the base directory
+    if (pluginPath.startsWith('./') || pluginPath.startsWith('../')) {
+        resolvedPath = require('path').resolve(base, pluginPath);
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const mod = require(resolvedPath);
+        if (typeof mod.analyze !== 'function') {
+            console.warn(`[plugin] Warning: plugin "${pluginPath}" does not export an "analyze" function – skipping.`);
+            return null;
+        }
+        return mod;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[plugin] Warning: failed to load plugin "${pluginPath}": ${message}`);
+        return null;
+    }
+}
+/**
+ * Run all plugins listed in `config.plugins`, collect their results, and
+ * return them as an array of `CoverageResult` objects.
+ *
+ * Errors thrown by individual plugins are caught, logged as warnings, and
+ * do not prevent other plugins from running.
+ *
+ * @param config    Resolved configuration containing the `plugins` list
+ * @param context   Context passed to each plugin's `analyze` function
+ * @param basedir   Directory used to resolve relative plugin paths (default: cwd)
+ */
+async function runPlugins(config, context, basedir) {
+    var _a;
+    const pluginPaths = (_a = config.plugins) !== null && _a !== void 0 ? _a : [];
+    const allResults = [];
+    for (const pluginPath of pluginPaths) {
+        const plugin = await loadPlugin(pluginPath, basedir);
+        if (!plugin)
+            continue;
+        try {
+            const pluginResult = await plugin.analyze(context);
+            if (Array.isArray(pluginResult)) {
+                allResults.push(...pluginResult);
+            }
+            else {
+                allResults.push(pluginResult);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[plugin] Warning: plugin "${pluginPath}" threw an error during analysis: ${message}`);
+        }
+    }
+    return allResults;
+}

package/dist/src/publishing.d.ts

@@ -0,0 +1,63 @@
+import type { CoverageResult } from './reporting';
+import type { QualityGateResult } from './qualityGate';
+import type { PublishingConfig } from './config';
+/** Metadata attached to each generated build bundle */
+export interface BuildMetadata {
+    buildId: string;
+    projectName: string;
+    repositoryName: string | null;
+    branch: string | null;
+    commitSha: string | null;
+    runId: string | null;
+    buildTimestamp: string;
+    thresholds: Record<string, number | undefined>;
+    actualCoverage: Record<string, number>;
+    passed: boolean;
+}
+/** All generated files for a single build */
+export interface GeneratedReports {
+    buildId: string;
+    bundleDir: string;
+    siteDir: string;
+    files: string[];
+    metadata: BuildMetadata;
+}
+/**
+ * Resolve the build ID from the publishing configuration and environment.
+ *
+ * Supported patterns:
+ *   - "timestamp"         → ISO timestamp (default)
+ *   - "commit-sha"        → GITHUB_SHA env var
+ *   - "run-number"        → GITHUB_RUN_NUMBER env var
+ *   - "branch-timestamp"  → branch name + timestamp
+ *   - any other string    → used as-is (custom naming)
+ */
+export declare function resolveBuildId(config: PublishingConfig): string;
+/** Build the metadata object for the current run */
+export declare function buildBuildMetadata(results: CoverageResult[], qualityGate: QualityGateResult, config: PublishingConfig, buildId: string, thresholds: Record<string, number | undefined>): BuildMetadata;
+/** Generate an AI-friendly markdown summary */
+export declare function generateMarkdownSummary(results: CoverageResult[], qualityGate: QualityGateResult, metadata: BuildMetadata): string;
+/** Generate the central index.html landing page */
+export declare function generateLandingPage(results: CoverageResult[], qualityGate: QualityGateResult, metadata: BuildMetadata, config: PublishingConfig, screenshotPaths: string[]): string;
+/**
+ * Generate a complete publishable build bundle.
+ *
+ * The bundle is written to:
+ *   `<outputDir>/builds/<buildId>/`
+ *
+ * And the static site root is:
+ *   `<outputDir>/`
+ */
+export declare function generateBuildBundle(results: CoverageResult[], qualityGate: QualityGateResult, config: PublishingConfig, thresholds: Record<string, number | undefined>, screenshotPaths?: string[]): GeneratedReports;
+/**
+ * Copy existing report files from `reportsDir` into the bundle and site directories.
+ * Useful to include the standard multi-format reports in the static site.
+ */
+export declare function copyReportFilesToBundle(reportsDir: string, bundleDir: string, siteDir: string, artifacts?: {
+    includeJson?: boolean;
+    includeHtml?: boolean;
+    includeCsv?: boolean;
+    includeJunit?: boolean;
+    includeMarkdown?: boolean;
+}): string[];
+//# sourceMappingURL=publishing.d.ts.map

package/dist/src/publishing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishing.d.ts","sourceRoot":"","sources":["../../src/publishing.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAIjD,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC/C,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;CACzB;AAID;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAuB/D;AAID,oDAAoD;AACpD,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,cAAc,EAAE,EACzB,WAAW,EAAE,iBAAiB,EAC9B,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC7C,aAAa,CAkBf;AAID,+CAA+C;AAC/C,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,cAAc,EAAE,EACzB,WAAW,EAAE,iBAAiB,EAC9B,QAAQ,EAAE,aAAa,GACtB,MAAM,CA0ER;AAID,mDAAmD;AACnD,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EAAE,EACzB,WAAW,EAAE,iBAAiB,EAC9B,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,gBAAgB,EACxB,eAAe,EAAE,MAAM,EAAE,GACxB,MAAM,CAoHR;AAWD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EAAE,EACzB,WAAW,EAAE,iBAAiB,EAC9B,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC9C,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB,gBAAgB,CA4ClB;AAID;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,GAAE;IACT,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;CACtB,GACL,MAAM,EAAE,CAwCV"}

package/dist/src/publishing.js

@@ -0,0 +1,379 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBuildId = resolveBuildId;
+exports.buildBuildMetadata = buildBuildMetadata;
+exports.generateMarkdownSummary = generateMarkdownSummary;
+exports.generateLandingPage = generateLandingPage;
+exports.generateBuildBundle = generateBuildBundle;
+exports.copyReportFilesToBundle = copyReportFilesToBundle;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ─── Build ID resolution ──────────────────────────────────────────────────────
+/**
+ * Resolve the build ID from the publishing configuration and environment.
+ *
+ * Supported patterns:
+ *   - "timestamp"         → ISO timestamp (default)
+ *   - "commit-sha"        → GITHUB_SHA env var
+ *   - "run-number"        → GITHUB_RUN_NUMBER env var
+ *   - "branch-timestamp"  → branch name + timestamp
+ *   - any other string    → used as-is (custom naming)
+ */
+function resolveBuildId(config) {
+    var _a, _b, _c, _d;
+    const pattern = (_a = config.buildId) !== null && _a !== void 0 ? _a : 'timestamp';
+    switch (pattern) {
+        case 'timestamp':
+            return new Date().toISOString().replace(/[:.]/g, '-');
+        case 'commit-sha':
+            return (_b = process.env['GITHUB_SHA']) !== null && _b !== void 0 ? _b : new Date().toISOString().replace(/[:.]/g, '-');
+        case 'run-number':
+            return (_c = process.env['GITHUB_RUN_NUMBER']) !== null && _c !== void 0 ? _c : new Date().toISOString().replace(/[:.]/g, '-');
+        case 'branch-timestamp': {
+            const branch = ((_d = process.env['GITHUB_REF_NAME']) !== null && _d !== void 0 ? _d : 'local').replace(/[^a-zA-Z0-9-_]/g, '-');
+            const ts = new Date().toISOString().replace(/[:.]/g, '-');
+            return `${branch}-${ts}`;
+        }
+        default:
+            // Custom or environment-variable pattern
+            return pattern;
+    }
+}
+// ─── Metadata builder ─────────────────────────────────────────────────────────
+/** Build the metadata object for the current run */
+function buildBuildMetadata(results, qualityGate, config, buildId, thresholds) {
+    var _a, _b, _c, _d, _e, _f;
+    const actualCoverage = {};
+    for (const r of results) {
+        actualCoverage[r.type] = r.coveragePercent;
+    }
+    return {
+        buildId,
+        projectName: (_b = (_a = process.env['GITHUB_REPOSITORY']) === null || _a === void 0 ? void 0 : _a.split('/')[1]) !== null && _b !== void 0 ? _b : 'api-coverage',
+        repositoryName: (_c = process.env['GITHUB_REPOSITORY']) !== null && _c !== void 0 ? _c : null,
+        branch: (_d = process.env['GITHUB_REF_NAME']) !== null && _d !== void 0 ? _d : null,
+        commitSha: (_e = process.env['GITHUB_SHA']) !== null && _e !== void 0 ? _e : null,
+        runId: (_f = process.env['GITHUB_RUN_ID']) !== null && _f !== void 0 ? _f : null,
+        buildTimestamp: new Date().toISOString(),
+        thresholds,
+        actualCoverage,
+        passed: qualityGate.passed,
+    };
+}
+// ─── Markdown report generator ────────────────────────────────────────────────
+/** Generate an AI-friendly markdown summary */
+function generateMarkdownSummary(results, qualityGate, metadata) {
+    var _a, _b, _c;
+    const statusEmoji = metadata.passed ? '✅' : '❌';
+    const lines = [
+        `# API Coverage Report — ${statusEmoji} ${metadata.passed ? 'PASSED' : 'FAILED'}`,
+        '',
+        `**Project:** ${metadata.projectName}`,
+        `**Repository:** ${(_a = metadata.repositoryName) !== null && _a !== void 0 ? _a : 'N/A'}`,
+        `**Branch:** ${(_b = metadata.branch) !== null && _b !== void 0 ? _b : 'N/A'}`,
+        `**Commit:** ${(_c = metadata.commitSha) !== null && _c !== void 0 ? _c : 'N/A'}`,
+        `**Build ID:** ${metadata.buildId}`,
+        `**Timestamp:** ${metadata.buildTimestamp}`,
+        '',
+        '## Coverage Summary',
+        '',
+        '| Category | Total | Covered | % |',
+        '|---|---|---|---|',
+    ];
+    for (const r of results) {
+        const pct = r.coveragePercent.toFixed(2);
+        const status = qualityGate.failures.some((f) => f.category === r.type) ? '❌' : '✅';
+        lines.push(`| ${r.type} ${status} | ${r.totalItems} | ${r.coveredItems} | ${pct}% |`);
+    }
+    lines.push('');
+    lines.push('## Quality Gate');
+    lines.push('');
+    if (qualityGate.failures.length === 0) {
+        lines.push('✅ All coverage thresholds met.');
+    }
+    else {
+        lines.push('❌ The following categories did not meet their thresholds:');
+        lines.push('');
+        for (const f of qualityGate.failures) {
+            lines.push(`- **${f.category}**: expected ≥ ${f.expected}%, actual ${f.actual}%, gap ${f.gap}%`);
+        }
+    }
+    lines.push('');
+    lines.push('## AI-Friendly Analysis');
+    lines.push('');
+    lines.push('<details>');
+    lines.push('<summary>Expand for AI-friendly analysis</summary>');
+    lines.push('');
+    lines.push('### Coverage Gaps');
+    lines.push('');
+    const gaps = results.filter((r) => r.coveragePercent < 100);
+    if (gaps.length === 0) {
+        lines.push('No coverage gaps found.');
+    }
+    else {
+        for (const g of gaps) {
+            lines.push(`- **${g.type}**: ${g.coveredItems}/${g.totalItems} covered (${g.coveragePercent.toFixed(2)}%)`);
+        }
+    }
+    lines.push('');
+    lines.push('### Recommended Next Steps');
+    lines.push('');
+    if (qualityGate.failures.length > 0) {
+        for (const f of qualityGate.failures) {
+            lines.push(`- Increase **${f.category}** coverage by at least ${f.gap}% to meet the configured threshold.`);
+        }
+    }
+    else {
+        lines.push('- Coverage meets all configured thresholds. Consider increasing thresholds to maintain quality.');
+    }
+    lines.push('');
+    lines.push('</details>');
+    return lines.join('\n');
+}
+// ─── Landing page generator ───────────────────────────────────────────────────
+/** Generate the central index.html landing page */
+function generateLandingPage(results, qualityGate, metadata, config, screenshotPaths) {
+    var _a, _b, _c, _d, _e;
+    const basePath = (_b = (_a = config.githubPages) === null || _a === void 0 ? void 0 : _a.basePath) !== null && _b !== void 0 ? _b : '/';
+    const statusClass = metadata.passed ? 'passed' : 'failed';
+    const statusText = metadata.passed ? '✅ PASSED' : '❌ FAILED';
+    const coverageRows = results.map((r) => {
+        const pct = r.coveragePercent.toFixed(2);
+        const rowStatus = qualityGate.failures.some((f) => f.category === r.type)
+            ? 'below'
+            : 'above';
+        return `<tr class="${rowStatus}">
+      <td>${r.type}</td>
+      <td>${r.totalItems}</td>
+      <td>${r.coveredItems}</td>
+      <td>${pct}%</td>
+    </tr>`;
+    }).join('\n');
+    const failureRows = qualityGate.failures.map((f) => `
+    <li><strong>${f.category}</strong>: expected ≥ ${f.expected}%, actual ${f.actual}%, gap ${f.gap}%</li>
+  `).join('');
+    const screenshotSection = screenshotPaths.length > 0
+        ? `<section class="screenshots">
+        <h2>Dashboard Screenshots</h2>
+        <div class="screenshot-grid">
+          ${screenshotPaths.map((p) => `<figure>
+            <img src="${p}" alt="Dashboard screenshot" loading="lazy">
+          </figure>`).join('\n')}
+        </div>
+      </section>`
+        : `<section class="screenshots">
+        <p class="notice">No screenshots available. Run with screenshot capture enabled.</p>
+      </section>`;
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>API Coverage Report — ${metadata.projectName}</title>
+  <style>
+    body { font-family: system-ui, sans-serif; max-width: 1100px; margin: 0 auto; padding: 1rem; }
+    h1 { border-bottom: 2px solid #333; padding-bottom: .5rem; }
+    .status { display: inline-block; padding: .25rem .75rem; border-radius: 4px; font-weight: bold; }
+    .passed { background: #d4edda; color: #155724; }
+    .failed { background: #f8d7da; color: #721c24; }
+    table { border-collapse: collapse; width: 100%; margin: 1rem 0; }
+    th, td { border: 1px solid #dee2e6; padding: .5rem .75rem; text-align: left; }
+    th { background: #f8f9fa; }
+    tr.above td:last-child { color: #155724; }
+    tr.below { background: #fff3cd; }
+    tr.below td:last-child { color: #856404; font-weight: bold; }
+    .meta { background: #f8f9fa; padding: 1rem; border-radius: 4px; margin: 1rem 0; }
+    .meta p { margin: .25rem 0; }
+    details summary { cursor: pointer; font-weight: bold; padding: .5rem 0; }
+    .screenshot-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 1rem; }
+    .screenshot-grid img { width: 100%; border: 1px solid #dee2e6; border-radius: 4px; }
+    .notice { color: #6c757d; font-style: italic; }
+    ul { padding-left: 1.5rem; }
+  </style>
+</head>
+<body>
+  <h1>API Coverage Report <span class="status ${statusClass}">${statusText}</span></h1>
+
+  <div class="meta">
+    <p><strong>Project:</strong> ${metadata.projectName}</p>
+    <p><strong>Repository:</strong> ${(_c = metadata.repositoryName) !== null && _c !== void 0 ? _c : 'N/A'}</p>
+    <p><strong>Branch:</strong> ${(_d = metadata.branch) !== null && _d !== void 0 ? _d : 'N/A'}</p>
+    <p><strong>Commit:</strong> ${(_e = metadata.commitSha) !== null && _e !== void 0 ? _e : 'N/A'}</p>
+    <p><strong>Build ID:</strong> ${metadata.buildId}</p>
+    <p><strong>Timestamp:</strong> ${metadata.buildTimestamp}</p>
+  </div>
+
+  <h2>Coverage Summary</h2>
+  <table>
+    <thead><tr><th>Category</th><th>Total</th><th>Covered</th><th>%</th></tr></thead>
+    <tbody>${coverageRows}</tbody>
+  </table>
+
+  <h2>Quality Gate</h2>
+  ${qualityGate.failures.length === 0
+        ? '<p class="status passed">✅ All coverage thresholds met.</p>'
+        : `<p class="status failed">❌ ${qualityGate.failures.length} threshold(s) not met:</p>
+       <ul>${failureRows}</ul>`}
+
+  ${screenshotSection}
+
+  <details>
+    <summary>AI-Friendly Analysis</summary>
+    <h3>Coverage Gaps</h3>
+    <ul>
+    ${results
+        .filter((r) => r.coveragePercent < 100)
+        .map((r) => `<li><strong>${r.type}</strong>: ${r.coveredItems}/${r.totalItems} covered (${r.coveragePercent.toFixed(2)}%)</li>`)
+        .join('\n') || '<li>No coverage gaps found.</li>'}
+    </ul>
+    <h3>Recommended Next Steps</h3>
+    <ul>
+    ${qualityGate.failures.length > 0
+        ? qualityGate.failures.map((f) => `<li>Increase <strong>${f.category}</strong> coverage by at least ${f.gap}% to meet the configured threshold.</li>`).join('\n')
+        : '<li>Coverage meets all configured thresholds. Consider increasing thresholds to maintain quality.</li>'}
+    </ul>
+  </details>
+
+  <h2>Report Links</h2>
+  <ul>
+    ${results.map((r) => `<li><a href="${basePath}${r.type}-coverage.html">${r.type} coverage report</a></li>`).join('\n')}
+    <li><a href="${basePath}coverage-summary.json">coverage-summary.json</a></li>
+    <li><a href="${basePath}coverage-summary.csv">coverage-summary.csv</a></li>
+    <li><a href="${basePath}coverage-summary-junit.xml">coverage-summary-junit.xml</a></li>
+    <li><a href="${basePath}ai-summary.md">AI-Friendly Markdown Summary</a></li>
+  </ul>
+</body>
+</html>`;
+}
+// ─── Bundle generator ─────────────────────────────────────────────────────────
+/** Write the build metadata JSON file */
+function writeBuildMetadata(bundleDir, metadata) {
+    const metaPath = path.join(bundleDir, 'build-metadata.json');
+    fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2), 'utf-8');
+    return metaPath;
+}
+/**
+ * Generate a complete publishable build bundle.
+ *
+ * The bundle is written to:
+ *   `<outputDir>/builds/<buildId>/`
+ *
+ * And the static site root is:
+ *   `<outputDir>/`
+ */
+function generateBuildBundle(results, qualityGate, config, thresholds, screenshotPaths) {
+    var _a;
+    const outputDir = (_a = config.outputDir) !== null && _a !== void 0 ? _a : 'site';
+    const buildId = resolveBuildId(config);
+    const bundleDir = path.join(outputDir, 'builds', buildId);
+    const screenshots = screenshotPaths !== null && screenshotPaths !== void 0 ? screenshotPaths : [];
+    fs.mkdirSync(bundleDir, { recursive: true });
+    const metadata = buildBuildMetadata(results, qualityGate, config, buildId, thresholds);
+    const files = [];
+    // ── Build metadata ───────────────────────────────────────────────────────
+    files.push(writeBuildMetadata(bundleDir, metadata));
+    // ── Markdown summary (AI-friendly) ───────────────────────────────────────
+    const mdSummary = generateMarkdownSummary(results, qualityGate, metadata);
+    const mdPath = path.join(bundleDir, 'ai-summary.md');
+    fs.writeFileSync(mdPath, mdSummary, 'utf-8');
+    files.push(mdPath);
+    // ── Landing page ─────────────────────────────────────────────────────────
+    const landingHtml = generateLandingPage(results, qualityGate, metadata, config, screenshots);
+    const indexPath = path.join(bundleDir, 'index.html');
+    fs.writeFileSync(indexPath, landingHtml, 'utf-8');
+    files.push(indexPath);
+    // ── Site root index (always points to latest build) ──────────────────────
+    fs.mkdirSync(outputDir, { recursive: true });
+    const siteIndexPath = path.join(outputDir, 'index.html');
+    fs.writeFileSync(siteIndexPath, landingHtml, 'utf-8');
+    files.push(siteIndexPath);
+    // ── AI-friendly markdown at site root ────────────────────────────────────
+    const siteAiMdPath = path.join(outputDir, 'ai-summary.md');
+    fs.writeFileSync(siteAiMdPath, mdSummary, 'utf-8');
+    files.push(siteAiMdPath);
+    return {
+        buildId,
+        bundleDir,
+        siteDir: outputDir,
+        files,
+        metadata,
+    };
+}
+// ─── Site copyover ────────────────────────────────────────────────────────────
+/**
+ * Copy existing report files from `reportsDir` into the bundle and site directories.
+ * Useful to include the standard multi-format reports in the static site.
+ */
+function copyReportFilesToBundle(reportsDir, bundleDir, siteDir, artifacts = {}) {
+    const copied = [];
+    const defaults = {
+        includeJson: true,
+        includeHtml: true,
+        includeCsv: true,
+        includeJunit: true,
+        includeMarkdown: true,
+        ...artifacts,
+    };
+    const extensions = [];
+    if (defaults.includeJson)
+        extensions.push('.json');
+    if (defaults.includeHtml)
+        extensions.push('.html');
+    if (defaults.includeCsv)
+        extensions.push('.csv');
+    if (defaults.includeJunit)
+        extensions.push('.xml');
+    if (defaults.includeMarkdown)
+        extensions.push('.md');
+    if (!fs.existsSync(reportsDir))
+        return copied;
+    for (const file of fs.readdirSync(reportsDir)) {
+        const ext = path.extname(file);
+        if (!extensions.includes(ext))
+            continue;
+        const src = path.join(reportsDir, file);
+        if (!fs.statSync(src).isFile())
+            continue;
+        const content = fs.readFileSync(src);
+        const bundleDest = path.join(bundleDir, file);
+        fs.writeFileSync(bundleDest, content);
+        copied.push(bundleDest);
+        const siteDest = path.join(siteDir, file);
+        fs.writeFileSync(siteDest, content);
+        copied.push(siteDest);
+    }
+    return copied;
+}

package/dist/src/qualityGate.d.ts

@@ -0,0 +1,58 @@
+import type { CoverageResult } from './reporting';
+/** Details of a single category that failed its threshold check */
+export interface QualityGateFailure {
+    category: string;
+    expected: number;
+    actual: number;
+    gap: number;
+}
+/** Structured result of a quality gate evaluation */
+export interface QualityGateResult {
+    passed: boolean;
+    /** The effective threshold applied (global scalar or per-category map) */
+    threshold: number | Record<string, number>;
+    /** Actual coverage per category */
+    actual: Record<string, number>;
+    /** Details of every category that did not meet its threshold */
+    failures: QualityGateFailure[];
+}
+/** Configuration accepted by evaluateQualityGate */
+export interface QualityGateConfig {
+    /** Per-category thresholds; a 'global' key sets the default for all categories */
+    thresholds?: Record<string, number | undefined>;
+    /** Branch-aware thresholds keyed by branch glob (e.g. "main", "feature/*") */
+    thresholdsByBranch?: Record<string, Record<string, number | undefined>>;
+    qualityGate?: {
+        enabled?: boolean;
+        failBuildOnThresholdMiss?: boolean;
+        /** "strict" = all categories must pass; "warn" = log but do not fail */
+        mode?: 'strict' | 'warn';
+    };
+}
+/**
+ * Determine whether a branch name matches a glob-style pattern.
+ * Supports `*` (single segment) and `**` (any segments).
+ */
+export declare function matchesBranchPattern(branchName: string, pattern: string): boolean;
+/**
+ * Resolve the effective threshold map for the given branch, merging
+ * branch-aware overrides on top of the global threshold config.
+ */
+export declare function resolveThresholdsForBranch(config: QualityGateConfig, branchName?: string): Record<string, number>;
+/**
+ * Compute the effective per-category threshold for a given category,
+ * using the 'global' key as the default when no category-specific value exists.
+ */
+export declare function effectiveThresholdForCategory(thresholds: Record<string, number>, category: string): number | undefined;
+/**
+ * Evaluate all coverage results against configured thresholds.
+ *
+ * Default behaviour when no thresholds are configured: every category must
+ * reach 100% (spec requirement: "default threshold = 100%").
+ *
+ * @param results      Coverage results from one or more analysis passes.
+ * @param config       Quality-gate / threshold configuration.
+ * @param branchName   Current git branch name (used for branch-aware thresholds).
+ */
+export declare function evaluateQualityGate(results: CoverageResult[], config: QualityGateConfig, branchName?: string): QualityGateResult;
+//# sourceMappingURL=qualityGate.d.ts.map

package/dist/src/qualityGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qualityGate.d.ts","sourceRoot":"","sources":["../../src/qualityGate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,CAAC;IAChB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,gEAAgE;IAChE,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAChD,8EAA8E;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACxE,WAAW,CAAC,EAAE;QACZ,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,wBAAwB,CAAC,EAAE,OAAO,CAAC;QACnC,wEAAwE;QACxE,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;KAC1B,CAAC;CACH;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAMjF;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,iBAAiB,EACzB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2BxB;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAIpB;AAID;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EAAE,EACzB,MAAM,EAAE,iBAAiB,EACzB,UAAU,CAAC,EAAE,MAAM,GAClB,iBAAiB,CAuDnB"}