api-tests-coverage 1.0.0

package/dist/src/businessCoverage.js

@@ -0,0 +1,290 @@
+"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.parseBusinessRules = parseBusinessRules;
+exports.analyzeBusinessCoverage = analyzeBusinessCoverage;
+exports.buildBusinessCoverageReport = buildBusinessCoverageReport;
+exports.generateBusinessReports = generateBusinessReports;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml = __importStar(require("js-yaml"));
+const fast_glob_1 = __importDefault(require("fast-glob"));
+// ─── Parsing ──────────────────────────────────────────────────────────────────
+/**
+ * Parse a YAML or JSON business-rules definition file.
+ * The file must contain a top-level `rules` array.
+ */
+function parseBusinessRules(rulesPath) {
+    const raw = fs.readFileSync(rulesPath, 'utf-8');
+    const ext = path.extname(rulesPath).toLowerCase();
+    let parsed;
+    if (ext === '.json') {
+        parsed = JSON.parse(raw);
+    }
+    else {
+        // Default to YAML (also handles .yaml and .yml)
+        parsed = yaml.load(raw);
+    }
+    if (!parsed ||
+        typeof parsed !== 'object' ||
+        !Array.isArray(parsed.rules)) {
+        throw new Error(`Invalid business rules file: expected a top-level "rules" array in ${rulesPath}`);
+    }
+    return parsed.rules;
+}
+/**
+ * Extract all test / it declarations from a file, together with their
+ * description string and the surrounding code up to the next declaration.
+ */
+function extractTestEntries(filePath, fileContents) {
+    const entries = [];
+    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;
+        entries.push({
+            description: positions[i].desc,
+            content: fileContents.slice(start, end),
+            filePath,
+        });
+    }
+    return entries;
+}
+/**
+ * Determine whether a test entry matches a given set of keywords or rule ID annotation.
+ *
+ * A match occurs when:
+ *   1. The test description contains `@rule <ruleId>` (case-insensitive), OR
+ *   2. The test description (lowercased) contains at least one of the keywords.
+ */
+function testMatchesKeywords(entry, ruleId, keywords) {
+    const descLower = entry.description.toLowerCase();
+    // Annotation-based match: @rule BL001
+    const annotationPattern = new RegExp(`@rule\\s+${ruleId}`, 'i');
+    if (annotationPattern.test(entry.description) || annotationPattern.test(entry.content)) {
+        return true;
+    }
+    // Keyword-based match (checked against description only for precision)
+    for (const kw of keywords) {
+        if (descLower.includes(kw.toLowerCase())) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Analyse test files matching the given glob pattern and determine which
+ * business rules are covered.
+ */
+async function analyzeBusinessCoverage(rules, testGlob) {
+    const testFiles = await (0, fast_glob_1.default)(testGlob, { onlyFiles: true });
+    // Pre-read all test files and extract test entries
+    const allEntries = [];
+    for (const filePath of testFiles) {
+        const contents = fs.readFileSync(filePath, 'utf-8');
+        allEntries.push(...extractTestEntries(filePath, contents));
+    }
+    return rules.map((rule) => {
+        var _a;
+        const matchedTests = [];
+        const matchedFiles = new Set();
+        for (const entry of allEntries) {
+            if (testMatchesKeywords(entry, rule.id, rule.keywords)) {
+                matchedTests.push(entry.description);
+                matchedFiles.add(entry.filePath);
+            }
+        }
+        const covered = matchedTests.length > 0;
+        // Scenario-level coverage
+        const scenarios = ((_a = rule.scenarios) !== null && _a !== void 0 ? _a : []).map((scenario) => {
+            var _a;
+            const scenarioMatches = [];
+            const scenarioKeywords = [
+                scenario.id,
+                ...((_a = scenario.keywords) !== null && _a !== void 0 ? _a : []),
+            ];
+            for (const entry of allEntries) {
+                // A test matches a scenario if it already matched the rule AND
+                // matches the scenario keywords/ID
+                if (testMatchesKeywords(entry, rule.id, rule.keywords) &&
+                    testMatchesKeywords(entry, scenario.id, scenarioKeywords)) {
+                    scenarioMatches.push(entry.description);
+                }
+            }
+            return {
+                scenario,
+                covered: scenarioMatches.length > 0,
+                matchedTests: scenarioMatches,
+            };
+        });
+        return {
+            rule,
+            covered,
+            testFiles: Array.from(matchedFiles),
+            matchedTests,
+            scenarios,
+        };
+    });
+}
+// ─── Report building ──────────────────────────────────────────────────────────
+/**
+ * Build the coverage summary from a list of per-rule coverages.
+ */
+function buildBusinessCoverageReport(coverages) {
+    const total = coverages.length;
+    const coveredCount = coverages.filter((c) => c.covered).length;
+    const percentage = total === 0 ? 0 : Math.round((coveredCount / total) * 10000) / 100;
+    const uncoveredRules = coverages.filter((c) => !c.covered).map((c) => c.rule);
+    return { total, covered: coveredCount, percentage, uncoveredRules, rules: coverages };
+}
+// ─── Report generation ────────────────────────────────────────────────────────
+/**
+ * Write JSON and HTML business-coverage reports to the given directory.
+ */
+function generateBusinessReports(report, reportsDir) {
+    if (!fs.existsSync(reportsDir)) {
+        fs.mkdirSync(reportsDir, { recursive: true });
+    }
+    // ── JSON ─────────────────────────────────────────────────────────────────
+    const jsonPath = path.join(reportsDir, 'business-coverage.json');
+    const jsonReport = {
+        total: report.total,
+        covered: report.covered,
+        percentage: report.percentage,
+        uncoveredRules: report.uncoveredRules.map(({ id, description }) => ({ id, description })),
+        rules: report.rules.map(({ rule, covered, testFiles, matchedTests, scenarios }) => {
+            var _a;
+            return ({
+                id: rule.id,
+                description: rule.description,
+                endpoints: (_a = rule.endpoints) !== null && _a !== void 0 ? _a : [],
+                covered,
+                testFiles,
+                matchedTests,
+                scenarios: scenarios.map(({ scenario, covered: sCovered, matchedTests: sTests }) => ({
+                    id: scenario.id,
+                    description: scenario.description,
+                    covered: sCovered,
+                    matchedTests: sTests,
+                })),
+            });
+        }),
+    };
+    fs.writeFileSync(jsonPath, JSON.stringify(jsonReport, null, 2), 'utf-8');
+    // ── HTML ─────────────────────────────────────────────────────────────────
+    const htmlPath = path.join(reportsDir, 'business-coverage.html');
+    const rows = report.rules
+        .map(({ rule, covered, matchedTests, scenarios }) => {
+        var _a;
+        const rowClass = covered ? 'covered' : 'uncovered';
+        const status = covered ? '✅ Covered' : '❌ Not covered';
+        const tests = matchedTests.length > 0 ? matchedTests.join('<br>') : '—';
+        const endpoints = ((_a = rule.endpoints) !== null && _a !== void 0 ? _a : []).join(', ') || '—';
+        const scenarioRows = scenarios.length > 0
+            ? scenarios
+                .map(({ scenario, covered: sc, matchedTests: st }) => {
+                const scStatus = sc ? '✅' : '❌';
+                const scTests = st.length > 0 ? st.join('<br>') : '—';
+                return `      <tr class="scenario ${sc ? 'covered' : 'uncovered'}">
+        <td></td>
+        <td class="scenario-id">${scenario.id}</td>
+        <td>${scenario.description}</td>
+        <td>${scStatus}</td>
+        <td>${scTests}</td>
+      </tr>`;
+            })
+                .join('\n')
+            : '';
+        return `    <tr class="${rowClass}">
+      <td><strong>${rule.id}</strong></td>
+      <td>${rule.description}</td>
+      <td>${endpoints}</td>
+      <td>${status}</td>
+      <td>${tests}</td>
+    </tr>
+${scenarioRows}`;
+    })
+        .join('\n');
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Business Logic Coverage Report</title>
+  <style>
+    body { font-family: sans-serif; padding: 2rem; }
+    h1 { margin-bottom: 0.5rem; }
+    .summary { margin-bottom: 1.5rem; font-size: 1.1rem; }
+    table { border-collapse: collapse; width: 100%; }
+    th, td { border: 1px solid #ccc; padding: 0.5rem 1rem; text-align: left; }
+    th { background: #f0f0f0; }
+    tr.covered { background: #e6ffe6; }
+    tr.uncovered { background: #ffe6e6; }
+    tr.scenario { font-size: 0.9rem; }
+    tr.scenario td { padding: 0.3rem 1rem; }
+    td.scenario-id { font-style: italic; padding-left: 2rem; }
+  </style>
+</head>
+<body>
+  <h1>Business Logic Coverage Report</h1>
+  <div class="summary">
+    Covered: <strong>${report.covered}/${report.total}</strong> business rules
+    (<strong>${report.percentage}%</strong>)
+  </div>
+  <table>
+    <thead>
+      <tr>
+        <th>Rule ID</th>
+        <th>Description</th>
+        <th>Endpoints</th>
+        <th>Status</th>
+        <th>Matched Tests</th>
+      </tr>
+    </thead>
+    <tbody>
+${rows}
+    </tbody>
+  </table>
+</body>
+</html>`;
+    fs.writeFileSync(htmlPath, html, 'utf-8');
+}

package/dist/src/compatibilityCoverage.d.ts

@@ -0,0 +1,83 @@
+import { OpenAPIV3 } from 'openapi-types';
+export type ChangeType = 'added' | 'removed' | 'changed-response-codes' | 'changed-parameter' | 'changed-schema';
+export interface EndpointChange {
+    method: string;
+    path: string;
+    changeType: ChangeType;
+    breaking: boolean;
+    description: string;
+}
+/** A single interaction parsed from a consumer contract (Pact) file. */
+export interface ContractInteraction {
+    description: string;
+    method: string;
+    path: string;
+    requestBody?: unknown;
+    expectedStatus: number;
+    expectedBody?: unknown;
+}
+/** A parsed consumer contract (Pact JSON) file. */
+export interface ConsumerContract {
+    consumer: string;
+    provider: string;
+    interactions: ContractInteraction[];
+    filePath: string;
+}
+export interface ContractVerificationResult {
+    contract: ConsumerContract;
+    interactionResults: InteractionVerificationResult[];
+    passed: boolean;
+}
+export interface InteractionVerificationResult {
+    interaction: ContractInteraction;
+    passed: boolean;
+    reason?: string;
+}
+export interface CompatibilityReport {
+    generatedAt: string;
+    oldSpecPath: string;
+    newSpecPath: string;
+    totalOldEndpoints: number;
+    breakingChanges: EndpointChange[];
+    nonBreakingChanges: EndpointChange[];
+    compatibilityPercent: number;
+    contractVerificationResults: ContractVerificationResult[];
+    totalNewEndpoints: number;
+    contractCoveredEndpoints: number;
+    contractCoveragePercent: number;
+}
+/**
+ * Load and dereference an OpenAPI/Swagger spec from a file path.
+ */
+export declare function loadSpec(specPath: string): Promise<OpenAPIV3.Document>;
+/**
+ * Compare two API specs and return a list of detected changes.
+ */
+export declare function compareSpecs(oldApi: OpenAPIV3.Document, newApi: OpenAPIV3.Document): EndpointChange[];
+/**
+ * Parse Pact-format JSON contract files matching the given glob pattern or directory.
+ */
+export declare function parseContractFiles(contractsGlob: string): Promise<ConsumerContract[]>;
+/**
+ * Verify consumer contracts against a new API spec.
+ */
+export declare function verifyContracts(contracts: ConsumerContract[], newApi: OpenAPIV3.Document): ContractVerificationResult[];
+/**
+ * Compute compatibility percentage based on detected breaking changes.
+ */
+export declare function computeCompatibilityPercent(totalOldEndpoints: number, breakingChanges: EndpointChange[]): number;
+/**
+ * Compute what fraction of new spec endpoints are covered by at least one
+ * contract interaction.
+ */
+export declare function computeContractCoveragePercent(contracts: ConsumerContract[], newApi: OpenAPIV3.Document): {
+    coveredEndpoints: number;
+    totalEndpoints: number;
+    coveragePercent: number;
+};
+export declare function buildCompatibilityReport(oldApi: OpenAPIV3.Document, newApi: OpenAPIV3.Document, changes: EndpointChange[], verificationResults: ContractVerificationResult[], oldSpecPath: string, newSpecPath: string): CompatibilityReport;
+/**
+ * Generate JSON and HTML compatibility reports.
+ */
+export declare function generateCompatibilityReports(report: CompatibilityReport, reportsDir: string): void;
+//# sourceMappingURL=compatibilityCoverage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compatibilityCoverage.d.ts","sourceRoot":"","sources":["../../src/compatibilityCoverage.ts"],"names":[],"mappings":"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"}