@qulib/core 0.7.0 → 0.9.0

package/dist/tools/repo/api-surface.js

@@ -0,0 +1,414 @@
+/**
+ * @module tools/repo/api-surface
+ * @packageBoundary @qulib/core
+ *
+ * Evidence-only API surface discovery. Three tiers of confidence:
+ *   Tier1 — OpenAPI / Swagger spec files (YAML or JSON). Only reads `summary` and
+ *            `parameters` from a real spec; never fabricates endpoints.
+ *   Tier2 — Framework route files: Next.js App-Router `route.ts` exports,
+ *            Next.js Pages `pages/api/`, Express router calls from RepoAnalysis.routes,
+ *            Fastify `fastify.{method}`, Hono `app.{method}`, NestJS decorators.
+ *   Tier3 — Opt-in heuristics. Currently: tRPC router definition files.
+ *            Only activated when `options.enableTier3 === true`.
+ *
+ * Every endpoint carries:
+ *   sourceFile  — repo-relative file path that evidence was read from
+ *   sourceTier  — 'openapi' | 'framework' | 'heuristic'
+ *   confidence  — 'high' | 'medium' | 'low'
+ *
+ * NEVER invents endpoints or parameters. When a spec file cannot be parsed,
+ * or a file pattern does not clearly indicate a route, the file is skipped.
+ */
+import { readFile } from 'node:fs/promises';
+import { relative, basename } from 'node:path';
+import glob from 'fast-glob';
+const IGNORE_PATTERNS = ['**/node_modules/**', '**/.next/**', '**/dist/**', '**/build/**'];
+/**
+ * Shared fast-glob options for every discovery tier. `suppressErrors: true` makes the
+ * recursive walk skip subtrees it cannot read (EACCES/EPERM) or that disappear mid-scan
+ * (ENOENT) instead of throwing. Real repos — and shared dirs like /tmp on CI runners
+ * (e.g. the root-owned, unreadable /tmp/snap-private-tmp on Ubuntu) — routinely contain
+ * directories the scanner cannot enter; discovery must degrade gracefully, never crash.
+ * `cwd` is supplied per-call.
+ */
+const GLOB_OPTIONS = {
+    onlyFiles: true,
+    absolute: true,
+    ignore: IGNORE_PATTERNS,
+    suppressErrors: true,
+};
+function toPosix(p) {
+    return p.split('\\').join('/');
+}
+function normalizeMethod(raw) {
+    const upper = raw.toUpperCase();
+    if (upper === 'GET')
+        return 'GET';
+    if (upper === 'POST')
+        return 'POST';
+    if (upper === 'PUT')
+        return 'PUT';
+    if (upper === 'DELETE')
+        return 'DELETE';
+    if (upper === 'PATCH')
+        return 'PATCH';
+    return 'unknown';
+}
+function isOpenApiDocument(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return false;
+    const obj = raw;
+    return ((typeof obj['openapi'] === 'string' || typeof obj['swagger'] === 'string') &&
+        typeof obj['paths'] === 'object');
+}
+async function discoverFromOpenApi(repoPath) {
+    const endpoints = [];
+    const specFiles = await glob([
+        '**/openapi.yaml',
+        '**/openapi.yml',
+        '**/openapi.json',
+        '**/swagger.yaml',
+        '**/swagger.yml',
+        '**/swagger.json',
+        '**/api-docs.yaml',
+        '**/api-docs.json',
+    ], { cwd: repoPath, ...GLOB_OPTIONS });
+    let specsFound = 0;
+    for (const file of specFiles) {
+        const rel = toPosix(relative(repoPath, file));
+        let raw;
+        try {
+            const content = await readFile(file, 'utf8');
+            if (file.endsWith('.json')) {
+                raw = JSON.parse(content);
+            }
+            else {
+                // Dynamic import of js-yaml to avoid bundling issues
+                const yaml = (await import('js-yaml'));
+                raw = yaml.load(content);
+            }
+        }
+        catch {
+            // Skip unparseable files — never fabricate
+            continue;
+        }
+        if (!isOpenApiDocument(raw))
+            continue;
+        specsFound++;
+        const paths = raw.paths ?? {};
+        for (const [path, pathItem] of Object.entries(paths)) {
+            if (typeof pathItem !== 'object' || pathItem === null)
+                continue;
+            const methods = ['get', 'post', 'put', 'delete', 'patch'];
+            for (const method of methods) {
+                const operation = pathItem[method];
+                if (typeof operation !== 'object' || operation === null)
+                    continue;
+                const op = operation;
+                const parameterNames = (op.parameters ?? [])
+                    .filter((p) => typeof p?.name === 'string')
+                    .map((p) => p.name);
+                endpoints.push({
+                    method: normalizeMethod(method),
+                    path,
+                    sourceFile: rel,
+                    sourceTier: 'openapi',
+                    confidence: 'high',
+                    ...(typeof op.summary === 'string' && op.summary ? { summary: op.summary } : {}),
+                    ...(parameterNames.length > 0 ? { parameterNames } : {}),
+                });
+            }
+        }
+    }
+    return { endpoints, specsFound };
+}
+// ---------------------------------------------------------------------------
+// Tier 2 — Framework route files
+// ---------------------------------------------------------------------------
+async function discoverNextAppRouterEndpoints(repoPath) {
+    const endpoints = [];
+    const routeFiles = await glob(['app/**/route.ts', 'app/**/route.tsx', 'src/app/**/route.ts', 'src/app/**/route.tsx'], {
+        cwd: repoPath,
+        ...GLOB_OPTIONS,
+    });
+    for (const file of routeFiles) {
+        const rel = toPosix(relative(repoPath, file));
+        let content;
+        try {
+            content = await readFile(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // Extract the route path from the file location
+        const routeSegment = rel
+            .replace(/^(src\/)?app\//, '')
+            .replace(/\/route\.tsx?$/, '');
+        // Normalize Next.js dynamic segments: [id] -> [id] (keep as-is, it's the real path)
+        const routePath = `/${routeSegment}`.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+        // Find exported HTTP method functions: export async function GET/POST/PUT/DELETE/PATCH
+        const methodExportRe = /export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH)\b/g;
+        let match;
+        let foundAny = false;
+        while ((match = methodExportRe.exec(content)) !== null) {
+            foundAny = true;
+            endpoints.push({
+                method: normalizeMethod(match[1] ?? 'unknown'),
+                path: routePath,
+                sourceFile: rel,
+                sourceTier: 'framework',
+                confidence: 'high',
+            });
+        }
+        // If the file exists but has no recognized export, it's still a route — emit as unknown method
+        if (!foundAny) {
+            endpoints.push({
+                method: 'unknown',
+                path: routePath,
+                sourceFile: rel,
+                sourceTier: 'framework',
+                confidence: 'medium',
+            });
+        }
+    }
+    return endpoints;
+}
+async function discoverNextPagesApiEndpoints(repoPath) {
+    const endpoints = [];
+    const apiFiles = await glob(['pages/api/**/*.ts', 'pages/api/**/*.tsx', 'src/pages/api/**/*.ts'], {
+        cwd: repoPath,
+        ...GLOB_OPTIONS,
+    });
+    for (const file of apiFiles) {
+        const rel = toPosix(relative(repoPath, file));
+        const name = basename(rel);
+        if (name.startsWith('_'))
+            continue;
+        const routeSegment = rel
+            .replace(/^(src\/)?pages\/api\//, '')
+            .replace(/\.tsx?$/, '');
+        const routePath = routeSegment === 'index'
+            ? '/api'
+            : `/api/${routeSegment.replace(/\/index$/, '')}`.replace(/\/+/g, '/');
+        let content;
+        try {
+            content = await readFile(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // Pages API routes export a default handler that typically checks req.method internally.
+        // We can't know the HTTP methods without executing the code, so we emit 'unknown'.
+        // Look for explicit method checks like: req.method === 'POST'
+        const methodCheckRe = /req\.method\s*(?:===|==|!==|!=)\s*['"`](GET|POST|PUT|DELETE|PATCH)['"`]/g;
+        const methods = new Set();
+        let match;
+        while ((match = methodCheckRe.exec(content)) !== null) {
+            if (match[1])
+                methods.add(match[1]);
+        }
+        if (methods.size > 0) {
+            for (const method of methods) {
+                endpoints.push({
+                    method: normalizeMethod(method),
+                    path: routePath,
+                    sourceFile: rel,
+                    sourceTier: 'framework',
+                    confidence: 'medium',
+                });
+            }
+        }
+        else {
+            endpoints.push({
+                method: 'unknown',
+                path: routePath,
+                sourceFile: rel,
+                sourceTier: 'framework',
+                confidence: 'medium',
+            });
+        }
+    }
+    return endpoints;
+}
+function discoverExpressEndpoints(repo) {
+    // Re-use existing RepoAnalysis.routes which already extracted Express router calls.
+    // Filter to only include routes that came from src/ files (Express pattern).
+    return repo.routes
+        .filter((r) => r.method !== 'GET' || r.file.startsWith('src/'))
+        .map((r) => ({
+        method: normalizeMethod(r.method),
+        path: r.path,
+        sourceFile: r.file,
+        sourceTier: 'framework',
+        confidence: 'medium',
+    }));
+}
+async function discoverFastifyEndpoints(repoPath) {
+    const endpoints = [];
+    const files = await glob(['src/**/*.ts', 'src/**/*.js', 'routes/**/*.ts', 'routes/**/*.js'], {
+        cwd: repoPath,
+        ...GLOB_OPTIONS,
+    });
+    for (const file of files) {
+        const rel = toPosix(relative(repoPath, file));
+        let content;
+        try {
+            content = await readFile(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // Fastify: fastify.get('/path', ...) or fastify.route({ method: 'GET', url: '/path' })
+        const fastifyCallRe = /(?:fastify|app|server)\.(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)['"`]/gi;
+        let match;
+        while ((match = fastifyCallRe.exec(content)) !== null) {
+            const method = match[1];
+            const path = match[2];
+            if (method && path) {
+                endpoints.push({
+                    method: normalizeMethod(method),
+                    path: path.startsWith('/') ? path : `/${path}`,
+                    sourceFile: rel,
+                    sourceTier: 'framework',
+                    confidence: 'medium',
+                });
+            }
+        }
+        // Hono: app.get('/path', ...) — same pattern, already covered above if variable is named app/server
+        // NestJS decorators: @Get('/path'), @Post('/path'), etc.
+        const nestDecoratorRe = /@(Get|Post|Put|Delete|Patch)\s*\(\s*['"`]([^'"`]*)['"`]\s*\)/g;
+        while ((match = nestDecoratorRe.exec(content)) !== null) {
+            const method = match[1];
+            const path = match[2];
+            if (method !== undefined && path !== undefined) {
+                endpoints.push({
+                    method: normalizeMethod(method),
+                    path: path === '' ? '/' : (path.startsWith('/') ? path : `/${path}`),
+                    sourceFile: rel,
+                    sourceTier: 'framework',
+                    confidence: 'medium',
+                });
+            }
+        }
+    }
+    return endpoints;
+}
+// ---------------------------------------------------------------------------
+// Tier 3 — Heuristic (opt-in): tRPC
+// ---------------------------------------------------------------------------
+async function discoverTrpcEndpoints(repoPath) {
+    const endpoints = [];
+    const trpcFiles = await glob(['src/**/*.ts', 'server/**/*.ts', 'lib/**/*.ts', 'app/**/*.ts'], { cwd: repoPath, ...GLOB_OPTIONS });
+    for (const file of trpcFiles) {
+        const rel = toPosix(relative(repoPath, file));
+        let content;
+        try {
+            content = await readFile(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // Only look at files that import from @trpc
+        if (!content.includes('@trpc/server') && !content.includes('@trpc/next'))
+            continue;
+        // tRPC procedure definitions: .query({ ... }) or .mutation({ ... })
+        // These aren't HTTP routes in the traditional sense, but procedure names are the "paths"
+        const queryRe = /(\w+)\s*:\s*(?:publicProcedure|protectedProcedure|procedure)\s*\.(?:input\([^)]*\)\s*\.)?query\s*\(/g;
+        const mutationRe = /(\w+)\s*:\s*(?:publicProcedure|protectedProcedure|procedure)\s*\.(?:input\([^)]*\)\s*\.)?mutation\s*\(/g;
+        let match;
+        while ((match = queryRe.exec(content)) !== null) {
+            const name = match[1];
+            if (name) {
+                endpoints.push({
+                    method: 'GET',
+                    path: `/trpc/${name}`,
+                    sourceFile: rel,
+                    sourceTier: 'heuristic',
+                    confidence: 'low',
+                    summary: `tRPC query: ${name}`,
+                });
+            }
+        }
+        while ((match = mutationRe.exec(content)) !== null) {
+            const name = match[1];
+            if (name) {
+                endpoints.push({
+                    method: 'POST',
+                    path: `/trpc/${name}`,
+                    sourceFile: rel,
+                    sourceTier: 'heuristic',
+                    confidence: 'low',
+                    summary: `tRPC mutation: ${name}`,
+                });
+            }
+        }
+    }
+    return endpoints;
+}
+// ---------------------------------------------------------------------------
+// De-duplication
+// ---------------------------------------------------------------------------
+function deduplicateEndpoints(endpoints) {
+    // Higher tier = higher priority; within a tier, first seen wins
+    const tierRank = { openapi: 0, framework: 1, heuristic: 2 };
+    const seen = new Map();
+    for (const ep of endpoints) {
+        const key = `${ep.method}:${ep.path}`;
+        const existing = seen.get(key);
+        if (!existing) {
+            seen.set(key, ep);
+        }
+        else {
+            // Keep the one with higher tier rank (lower number = better)
+            const existingRank = tierRank[existing.sourceTier];
+            const newRank = tierRank[ep.sourceTier];
+            if (newRank < existingRank) {
+                seen.set(key, ep);
+            }
+        }
+    }
+    return [...seen.values()];
+}
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+export async function discoverApiSurface(repoPath, options = {}) {
+    const tier3Enabled = options.enableTier3 === true;
+    // Run tiers in parallel for speed
+    const [tier1Result, nextAppEndpoints, nextPagesEndpoints, fastifyEndpoints,] = await Promise.all([
+        discoverFromOpenApi(repoPath),
+        discoverNextAppRouterEndpoints(repoPath),
+        discoverNextPagesApiEndpoints(repoPath),
+        discoverFastifyEndpoints(repoPath),
+    ]);
+    // Express uses existing RepoAnalysis — callers may pass a pre-scanned repo via a
+    // separate helper. Here we expose the raw discovery functions; the integration
+    // layer in computeApiCoverage passes the repo. For standalone usage we return
+    // only file-based discoveries.
+    const tier1 = tier1Result.endpoints;
+    const tier2 = [...nextAppEndpoints, ...nextPagesEndpoints, ...fastifyEndpoints];
+    const tier3 = tier3Enabled
+        ? await discoverTrpcEndpoints(repoPath)
+        : [];
+    const allEndpoints = deduplicateEndpoints([...tier1, ...tier2, ...tier3]);
+    return {
+        discoveredAt: new Date().toISOString(),
+        repoPath,
+        endpoints: allEndpoints,
+        openApiSpecsFound: tier1Result.specsFound,
+        tier3Enabled,
+    };
+}
+/**
+ * Variant that also incorporates RepoAnalysis.routes (Express routes already
+ * extracted by scanRepo). Use this when you already have a RepoAnalysis to avoid
+ * double-reading files.
+ */
+export async function discoverApiSurfaceWithRepo(repoPath, repo, options = {}) {
+    const base = await discoverApiSurface(repoPath, options);
+    const expressEndpoints = discoverExpressEndpoints(repo);
+    return {
+        ...base,
+        endpoints: deduplicateEndpoints([...base.endpoints, ...expressEndpoints]),
+    };
+}

package/dist/tools/scoring/api-coverage.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @module tools/scoring/api-coverage
+ *
+ * Computes the `api-test-coverage` dimension for the automation maturity score.
+ *
+ * Weight: 0.15. The six existing dimensions have been rebalanced to sum to 1.0:
+ *
+ *   Before (sum = 1.0):
+ *     test-coverage-breadth   0.28
+ *     framework-adoption      0.22
+ *     test-id-hygiene         0.18
+ *     ci-integration          0.14
+ *     auth-test-coverage      0.10
+ *     component-test-ratio    0.08
+ *                             ────
+ *                             1.00
+ *
+ *   After (sum = 1.0, api-test-coverage added at 0.15):
+ *     test-coverage-breadth   0.24   (-0.04)
+ *     framework-adoption      0.19   (-0.03)
+ *     test-id-hygiene         0.15   (-0.03)
+ *     ci-integration          0.12   (-0.02)
+ *     auth-test-coverage      0.09   (-0.01)
+ *     component-test-ratio    0.06   (-0.02)
+ *     api-test-coverage       0.15   (new)
+ *                             ────
+ *                             1.00
+ *
+ * Scoring rules:
+ *   - If 0 API endpoints discovered → applicability = 'not_applicable' (excluded from denominator)
+ *   - A test file "covers" an endpoint if:
+ *       (a) the endpoint path appears verbatim in the file's coveredPaths, OR
+ *       (b) the file name contains a token from the endpoint path (heuristic fallback)
+ *   - Each endpoint that is covered raises the score proportionally.
+ *   - POST/PUT/DELETE endpoints are HIGH severity gaps when untested;
+ *     GET endpoints are MEDIUM severity gaps when untested.
+ *
+ * Evidence is per-endpoint and contextual:
+ *   "GET /api/users — found in app/api/users/route.ts, covered by tests/api/users.test.ts"
+ *   "POST /api/orders — found in app/api/orders/route.ts, NOT covered"
+ */
+import type { RepoAnalysis } from '../../schemas/repo-analysis.schema.js';
+import type { AutomationMaturityDimension } from '../../schemas/automation-maturity.schema.js';
+import type { ApiSurface, DiscoveredEndpoint } from '../repo/api-surface.js';
+export declare const W_API_COVERAGE = 0.15;
+/**
+ * Rebalanced weights for the original 6 dimensions (sum = 0.85).
+ * Export these so automation-maturity.ts can import and use them.
+ */
+export declare const REBALANCED_WEIGHTS: {
+    readonly TEST_BREADTH: 0.24;
+    readonly FRAMEWORK: 0.19;
+    readonly TEST_ID: 0.15;
+    readonly CI: 0.12;
+    readonly AUTH_TESTS: 0.09;
+    readonly COMPONENT_RATIO: 0.06;
+};
+export interface ApiEndpointCoverage {
+    method: DiscoveredEndpoint['method'];
+    path: string;
+    sourceFile: string;
+    sourceTier: DiscoveredEndpoint['sourceTier'];
+    covered: boolean;
+    coveringTestFile?: string;
+    severity: 'high' | 'medium' | 'low';
+}
+export interface ApiCoverageResult {
+    dimension: AutomationMaturityDimension;
+    endpointCoverage: ApiEndpointCoverage[];
+    untestedHighSeverityCount: number;
+    untestedMediumSeverityCount: number;
+}
+export declare function computeApiCoverage(repo: RepoAnalysis, apiSurface: ApiSurface): ApiCoverageResult;
+//# sourceMappingURL=api-coverage.d.ts.map

package/dist/tools/scoring/api-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-coverage.d.ts","sourceRoot":"","sources":["../../../src/tools/scoring/api-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EACV,2BAA2B,EAE5B,MAAM,6CAA6C,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE7E,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;;CAOrB,CAAC;AAEX,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,2BAA2B,CAAC;IACvC,gBAAgB,EAAE,mBAAmB,EAAE,CAAC;IACxC,yBAAyB,EAAE,MAAM,CAAC;IAClC,2BAA2B,EAAE,MAAM,CAAC;CACrC;AA+BD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,YAAY,EAClB,UAAU,EAAE,UAAU,GACrB,iBAAiB,CA8FnB"}

package/dist/tools/scoring/api-coverage.js

@@ -0,0 +1,158 @@
+/**
+ * @module tools/scoring/api-coverage
+ *
+ * Computes the `api-test-coverage` dimension for the automation maturity score.
+ *
+ * Weight: 0.15. The six existing dimensions have been rebalanced to sum to 1.0:
+ *
+ *   Before (sum = 1.0):
+ *     test-coverage-breadth   0.28
+ *     framework-adoption      0.22
+ *     test-id-hygiene         0.18
+ *     ci-integration          0.14
+ *     auth-test-coverage      0.10
+ *     component-test-ratio    0.08
+ *                             ────
+ *                             1.00
+ *
+ *   After (sum = 1.0, api-test-coverage added at 0.15):
+ *     test-coverage-breadth   0.24   (-0.04)
+ *     framework-adoption      0.19   (-0.03)
+ *     test-id-hygiene         0.15   (-0.03)
+ *     ci-integration          0.12   (-0.02)
+ *     auth-test-coverage      0.09   (-0.01)
+ *     component-test-ratio    0.06   (-0.02)
+ *     api-test-coverage       0.15   (new)
+ *                             ────
+ *                             1.00
+ *
+ * Scoring rules:
+ *   - If 0 API endpoints discovered → applicability = 'not_applicable' (excluded from denominator)
+ *   - A test file "covers" an endpoint if:
+ *       (a) the endpoint path appears verbatim in the file's coveredPaths, OR
+ *       (b) the file name contains a token from the endpoint path (heuristic fallback)
+ *   - Each endpoint that is covered raises the score proportionally.
+ *   - POST/PUT/DELETE endpoints are HIGH severity gaps when untested;
+ *     GET endpoints are MEDIUM severity gaps when untested.
+ *
+ * Evidence is per-endpoint and contextual:
+ *   "GET /api/users — found in app/api/users/route.ts, covered by tests/api/users.test.ts"
+ *   "POST /api/orders — found in app/api/orders/route.ts, NOT covered"
+ */
+export const W_API_COVERAGE = 0.15;
+/**
+ * Rebalanced weights for the original 6 dimensions (sum = 0.85).
+ * Export these so automation-maturity.ts can import and use them.
+ */
+export const REBALANCED_WEIGHTS = {
+    TEST_BREADTH: 0.24,
+    FRAMEWORK: 0.19,
+    TEST_ID: 0.15,
+    CI: 0.12,
+    AUTH_TESTS: 0.09,
+    COMPONENT_RATIO: 0.06,
+};
+/**
+ * Returns true if testCoveredPaths or test filename hints that it covers endpointPath.
+ */
+function endpointIsCovered(endpoint, testFile) {
+    const ep = endpoint.path.toLowerCase();
+    // (a) Exact or prefix match in coveredPaths
+    const directCover = testFile.coveredPaths.some((cp) => {
+        const norm = cp.toLowerCase();
+        return norm === ep || (ep !== '/' && ep.startsWith(norm) && (norm === ep || ep[norm.length] === '/'));
+    });
+    if (directCover)
+        return true;
+    // (b) Heuristic: test filename tokens match endpoint path segments
+    const testFileName = testFile.file.toLowerCase();
+    const segments = ep.split('/').filter((s) => s.length > 2 && !/^\[/.test(s));
+    if (segments.length === 0)
+        return false;
+    return segments.some((seg) => testFileName.includes(seg));
+}
+function classifySeverity(method) {
+    if (method === 'POST' || method === 'PUT' || method === 'DELETE')
+        return 'high';
+    if (method === 'PATCH')
+        return 'high';
+    return 'medium';
+}
+export function computeApiCoverage(repo, apiSurface) {
+    const endpoints = apiSurface.endpoints;
+    // Not applicable when there are no API endpoints
+    if (endpoints.length === 0) {
+        const dim = {
+            dimension: 'api-test-coverage',
+            score: 0,
+            weight: W_API_COVERAGE,
+            evidence: ['No API endpoints discovered — api-test-coverage dimension does not apply.'],
+            recommendations: [],
+            applicability: 'not_applicable',
+            reason: 'No API endpoints discovered — api-test-coverage dimension does not apply.',
+            guidance: 'No API endpoints were found. If this repo has REST endpoints, ensure they are declared in a supported framework (Next.js route.ts, Express, Fastify, NestJS) or an OpenAPI spec file.',
+        };
+        return { dimension: dim, endpointCoverage: [], untestedHighSeverityCount: 0, untestedMediumSeverityCount: 0 };
+    }
+    const endpointCoverage = [];
+    let coveredCount = 0;
+    let untestedHighSeverityCount = 0;
+    let untestedMediumSeverityCount = 0;
+    const evidence = [];
+    for (const ep of endpoints) {
+        const severity = classifySeverity(ep.method);
+        // Find the first test file that covers this endpoint
+        let coveringTestFile;
+        for (const tf of repo.testFiles) {
+            if (endpointIsCovered(ep, tf)) {
+                coveringTestFile = tf.file;
+                break;
+            }
+        }
+        const covered = coveringTestFile !== undefined;
+        if (covered) {
+            coveredCount++;
+            evidence.push(`${ep.method} ${ep.path} — found in ${ep.sourceFile}, covered by ${coveringTestFile}`);
+        }
+        else {
+            if (severity === 'high')
+                untestedHighSeverityCount++;
+            else
+                untestedMediumSeverityCount++;
+            evidence.push(`${ep.method} ${ep.path} — found in ${ep.sourceFile}, NOT covered`);
+        }
+        endpointCoverage.push({
+            method: ep.method,
+            path: ep.path,
+            sourceFile: ep.sourceFile,
+            sourceTier: ep.sourceTier,
+            covered,
+            ...(coveringTestFile !== undefined ? { coveringTestFile } : {}),
+            severity,
+        });
+    }
+    const score = Math.round((100 * coveredCount) / endpoints.length);
+    const recommendations = [];
+    if (untestedHighSeverityCount > 0) {
+        recommendations.push(`${untestedHighSeverityCount} high-severity API endpoint(s) (POST/PUT/DELETE/PATCH) have no test coverage — add supertest or API-level tests.`);
+    }
+    if (untestedMediumSeverityCount > 0) {
+        recommendations.push(`${untestedMediumSeverityCount} GET endpoint(s) have no test coverage — add route smoke tests.`);
+    }
+    const specNote = apiSurface.openApiSpecsFound > 0
+        ? ` (${apiSurface.openApiSpecsFound} OpenAPI spec(s) parsed — Tier1 high-confidence)`
+        : '';
+    const dim = {
+        dimension: 'api-test-coverage',
+        score,
+        weight: W_API_COVERAGE,
+        evidence: [
+            `${coveredCount}/${endpoints.length} API endpoints appear covered by test files${specNote}.`,
+            ...evidence.slice(0, 10),
+            ...(evidence.length > 10 ? [`… and ${evidence.length - 10} more endpoint(s)`] : []),
+        ],
+        recommendations,
+        applicability: 'applicable',
+    };
+    return { dimension: dim, endpointCoverage, untestedHighSeverityCount, untestedMediumSeverityCount };
+}

package/dist/tools/scoring/automation-maturity.d.ts

@@ -1,4 +1,14 @@
 import type { RepoAnalysis } from '../../schemas/repo-analysis.schema.js';
 import type { AutomationMaturity } from '../../schemas/automation-maturity.schema.js';
-export declare function computeAutomationMaturity(repo: RepoAnalysis): AutomationMaturity;
+import { type ApiCoverageResult } from './api-coverage.js';
+/**
+ * Compute automation maturity for a repo.
+ *
+ * @param repo - The scanned repo analysis.
+ * @param apiCoverageResult - Optional pre-computed API coverage result. When absent the
+ *   6 original dimensions are scored with the original weights (backward-compatible).
+ *   When provided, a 7th dimension (`api-test-coverage`) is added and weights are
+ *   rebalanced so the total still sums to 1.0 across applicable dimensions.
+ */
+export declare function computeAutomationMaturity(repo: RepoAnalysis, apiCoverageResult?: ApiCoverageResult): AutomationMaturity;
 //# sourceMappingURL=automation-maturity.d.ts.map

package/dist/tools/scoring/automation-maturity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"automation-maturity.d.ts","sourceRoot":"","sources":["../../../src/tools/scoring/automation-maturity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EACV,kBAAkB,EAGnB,MAAM,6CAA6C,CAAC;AAiDrD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,YAAY,GAAG,kBAAkB,CAmMhF"}
+{"version":3,"file":"automation-maturity.d.ts","sourceRoot":"","sources":["../../../src/tools/scoring/automation-maturity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EACV,kBAAkB,EAGnB,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AA4D/E;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,YAAY,EAClB,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,kBAAkB,CAiNpB"}