api-tests-coverage 1.0.5 → 1.0.6

package/dist/src/inference/routeInference.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * Route Inference Engine
+ *
+ * Discovers HTTP routes from Express/Koa/Hapi/Fastify source files when no
+ * OpenAPI spec is available, enabling endpoint coverage analysis without
+ * a pre-authored specification.
+ *
+ * Patterns supported:
+ *  - Express/Koa: router.get('/path', ...) / app.post('/path', ...)
+ *  - Multi-line: router.get(\n  '/path', ...) — path on next line
+ *  - Chained: router.route('/path').get(...).post(...)
+ *  - JSDoc route annotations: @route {GET} /path (used only when no code pattern found)
+ *
+ * Deduplication:
+ *  - Routes are deduplicated by method:path within each file.
+ *  - Actual code patterns take priority over JSDoc annotations.
+ */
+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.HTTP_METHODS = void 0;
+exports.inferRoutesFromFile = inferRoutesFromFile;
+exports.inferRoutes = inferRoutes;
+exports.writeInferredRoutes = writeInferredRoutes;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ─── Public types ─────────────────────────────────────────────────────────────
+exports.HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+// ─── Patterns ─────────────────────────────────────────────────────────────────
+/** Matches: router.get('/path', ...) or app.post('/path', ...) — on a single line */
+const ROUTER_METHOD_INLINE = /(?:router|app|server)\s*\.\s*(get|post|put|patch|delete|head|options)\s*\(\s*['"`]([^'"`]+)['"`]/i;
+/**
+ * Matches the beginning of a router.method( call that spans multiple lines.
+ * Group 1 = method name (get|post|...).
+ * The route path is expected on the same or next line.
+ */
+const ROUTER_METHOD_MULTILINE_START = /(?:router|app|server)\s*\.\s*(get|post|put|patch|delete|head|options)\s*\(\s*$/i;
+/** Matches a standalone route path string (first arg in multi-line route) */
+const ROUTE_PATH_LINE = /^\s*['"`]([^'"`]+)['"`]\s*,?\s*$/;
+/** Matches: router.route('/path').get(...) — chained route definition */
+const CHAINED_ROUTE_PATTERN = /(?:router|app)\s*\.\s*route\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/i;
+const CHAINED_METHOD_PATTERN = /\.\s*(get|post|put|patch|delete|head|options)\s*\(/gi;
+/** Matches JSDoc @route {GET} /path */
+const JSDOC_ROUTE_PATTERN = /@route\s+\{(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\}\s+(\S+)/i;
+/**
+ * Matches the primary async service function call within a route handler body.
+ * e.g. `await deleteComment(...)` or `const result = await getArticles(...)`.
+ * Group 1 = function name.
+ *
+ * Note: This only detects `await`-based async calls. Synchronous handlers
+ * (e.g. `res.json(getUsers())`) are not matched by this pattern.
+ */
+const HANDLER_FUNCTION_PATTERN = /(?:await|const\s+\w+\s*=\s*await)\s+([a-zA-Z][a-zA-Z0-9]*)\s*\(/;
+/**
+ * Number of source lines scanned ahead to find the primary handler function
+ * when the route is defined on a single line (router.method('/path', ...)).
+ * The inline form starts the handler function close to the route definition.
+ */
+const HANDLER_SCAN_WINDOW_INLINE = 20;
+/**
+ * Number of source lines scanned ahead to find the primary handler function
+ * when the route is defined with the path on the next line. The multi-line
+ * form has more preamble (middleware, auth, etc.) before the handler function.
+ */
+const HANDLER_SCAN_WINDOW_MULTILINE = 25;
+// ─── Core inference function ──────────────────────────────────────────────────
+/**
+ * Infer routes from a single source file.
+ * Routes are deduplicated by method:path within the file.
+ * Code-based patterns take priority over JSDoc annotations for the same method+path.
+ */
+function inferRoutesFromFile(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const lines = content.split('\n');
+    // key = "method:path" → route (code-found routes win over jsdoc)
+    const byKey = new Map();
+    const addRoute = (method, routePath, lineNumber, discoveredVia, handlerFunction) => {
+        const key = `${method}:${routePath}`;
+        const existing = byKey.get(key);
+        // Prefer code-discovered over jsdoc; if same source, first occurrence wins
+        if (!existing || (discoveredVia === 'code' && existing.discoveredVia === 'jsdoc')) {
+            byKey.set(key, { method, path: routePath, handlerFunction, sourceFile: filePath, lineNumber, discoveredVia });
+        }
+    };
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+        const line = lines[lineIdx];
+        // 1a. router.method('/path', ...) — all on one line
+        const inlineMatch = line.match(ROUTER_METHOD_INLINE);
+        if (inlineMatch) {
+            const method = inlineMatch[1].toLowerCase();
+            const routePath = inlineMatch[2];
+            // Scan up to HANDLER_SCAN_WINDOW_INLINE following lines for the primary await function call
+            const handlerFn = findHandlerFunction(lines, lineIdx, HANDLER_SCAN_WINDOW_INLINE);
+            addRoute(method, routePath, lineIdx + 1, 'code', handlerFn);
+            continue;
+        }
+        // 1b. router.method(\n  '/path', ...) — method and path on separate lines
+        const multilineStart = line.match(ROUTER_METHOD_MULTILINE_START);
+        if (multilineStart && lineIdx + 1 < lines.length) {
+            const nextLine = lines[lineIdx + 1];
+            const pathMatch = nextLine.match(ROUTE_PATH_LINE);
+            if (pathMatch) {
+                const method = multilineStart[1].toLowerCase();
+                const routePath = pathMatch[1];
+                const handlerFn = findHandlerFunction(lines, lineIdx, HANDLER_SCAN_WINDOW_MULTILINE);
+                addRoute(method, routePath, lineIdx + 1, 'code', handlerFn);
+                lineIdx++; // skip the path line
+                continue;
+            }
+        }
+        // 2. JSDoc @route annotation (only added if no code pattern found for same route)
+        const jsDocMatch = line.match(JSDOC_ROUTE_PATTERN);
+        if (jsDocMatch) {
+            const method = jsDocMatch[1].toLowerCase();
+            const routePath = jsDocMatch[2];
+            addRoute(method, routePath, lineIdx + 1, 'jsdoc');
+            continue;
+        }
+        // 3. Chained: .route('/path').get(...).post(...)
+        const chainedPathMatch = line.match(CHAINED_ROUTE_PATTERN);
+        if (chainedPathMatch) {
+            const routePath = chainedPathMatch[1];
+            const windowEnd = Math.min(lineIdx + 5, lines.length);
+            const windowText = lines.slice(lineIdx, windowEnd).join(' ');
+            let methodMatch;
+            CHAINED_METHOD_PATTERN.lastIndex = 0;
+            while ((methodMatch = CHAINED_METHOD_PATTERN.exec(windowText)) !== null) {
+                const method = methodMatch[1].toLowerCase();
+                addRoute(method, routePath, lineIdx + 1, 'code');
+            }
+        }
+    }
+    return [...byKey.values()];
+}
+/**
+ * Scan ahead in the source lines from `startLine` to find the first awaited
+ * service function call in the route handler body.
+ */
+function findHandlerFunction(lines, startLine, maxLines) {
+    const end = Math.min(startLine + maxLines, lines.length);
+    for (let i = startLine; i < end; i++) {
+        const m = lines[i].match(HANDLER_FUNCTION_PATTERN);
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Infer routes from a set of service source files.
+ */
+function inferRoutes(serviceFiles) {
+    const allRoutes = [];
+    const warnings = [];
+    let filesAnalyzed = 0;
+    for (const fp of serviceFiles) {
+        const fileRoutes = inferRoutesFromFile(fp);
+        allRoutes.push(...fileRoutes);
+        filesAnalyzed++;
+    }
+    if (allRoutes.length === 0) {
+        warnings.push('No HTTP routes detected in service files.');
+    }
+    return { routes: allRoutes, filesAnalyzed, warnings };
+}
+/**
+ * Write inferred routes to the reports directory.
+ * Returns the path of the written file.
+ */
+function writeInferredRoutes(result, reportsDir) {
+    fs.mkdirSync(reportsDir, { recursive: true });
+    const outputPath = path.join(reportsDir, 'inferred-routes.json');
+    const output = {
+        generated_at: new Date().toISOString(),
+        route_source: 'inferred',
+        files_analyzed: result.filesAnalyzed,
+        route_count: result.routes.length,
+        routes: result.routes,
+    };
+    fs.writeFileSync(outputPath, JSON.stringify(output, null, 2), 'utf-8');
+    return outputPath;
+}

package/dist/src/inference/scanManifest.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Scan Manifest
+ *
+ * Records what was scanned during a zero-config `analyze` run —
+ * files analyzed, languages detected, frameworks detected, and
+ * per-metric coverage outcomes with their source (explicit / inferred / skipped).
+ *
+ * Written to: reports/scan-manifest.json
+ */
+export interface ScanTypeEntry {
+    type: string;
+    source: 'explicit' | 'inferred' | 'skipped';
+    reason?: string;
+    itemsFound: number;
+    itemsCovered: number;
+    coveragePercent: number;
+}
+export interface ScanManifest {
+    projectRoot: string;
+    analyzedAt: string;
+    discoveredFiles: {
+        serviceFiles: string[];
+        testFiles: string[];
+        specFiles: string[];
+    };
+    languages: string[];
+    frameworks: string[];
+    scanTypes: ScanTypeEntry[];
+}
+/**
+ * Write a scan manifest to the reports directory.
+ * Returns the path of the written file.
+ */
+export declare function writeScanManifest(manifest: ScanManifest, reportsDir: string): string;
+//# sourceMappingURL=scanManifest.d.ts.map

package/dist/src/inference/scanManifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanManifest.d.ts","sourceRoot":"","sources":["../../../src/inference/scanManifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE;QACf,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IACF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAKpF"}

package/dist/src/inference/scanManifest.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Scan Manifest
+ *
+ * Records what was scanned during a zero-config `analyze` run —
+ * files analyzed, languages detected, frameworks detected, and
+ * per-metric coverage outcomes with their source (explicit / inferred / skipped).
+ *
+ * Written to: reports/scan-manifest.json
+ */
+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.writeScanManifest = writeScanManifest;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ─── Writer ───────────────────────────────────────────────────────────────────
+/**
+ * Write a scan manifest to the reports directory.
+ * Returns the path of the written file.
+ */
+function writeScanManifest(manifest, reportsDir) {
+    fs.mkdirSync(reportsDir, { recursive: true });
+    const outputPath = path.join(reportsDir, 'scan-manifest.json');
+    fs.writeFileSync(outputPath, JSON.stringify(manifest, null, 2), 'utf-8');
+    return outputPath;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-tests-coverage",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "CLI and library to measure how thoroughly your test suite exercises your API surface area",
   "main": "dist/src/lib/index.js",
   "types": "dist/src/lib/index.d.ts",