@qulib/core 0.7.0 → 0.8.2

package/dist/schemas/repo-analysis.schema.d.ts

@@ -156,7 +156,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
         level: z.ZodNumber;
         label: z.ZodString;
         dimensions: z.ZodArray<z.ZodObject<{
-            dimension: z.ZodEnum<["test-coverage-breadth", "framework-adoption", "test-id-hygiene", "ci-integration", "auth-test-coverage", "component-test-ratio"]>;
+            dimension: z.ZodEnum<["test-coverage-breadth", "framework-adoption", "test-id-hygiene", "ci-integration", "auth-test-coverage", "component-test-ratio", "api-test-coverage"]>;
             score: z.ZodNumber;
             weight: z.ZodNumber;
             evidence: z.ZodArray<z.ZodString, "many">;
@@ -166,7 +166,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
             guidance: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             recommendations: string[];
-            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
+            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio" | "api-test-coverage";
             score: number;
             weight: number;
             evidence: string[];
@@ -175,7 +175,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
             guidance?: string | undefined;
         }, {
             recommendations: string[];
-            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
+            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio" | "api-test-coverage";
             score: number;
             weight: number;
             evidence: string[];
@@ -193,7 +193,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
         overallScore: number;
         dimensions: {
             recommendations: string[];
-            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
+            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio" | "api-test-coverage";
             score: number;
             weight: number;
             evidence: string[];
@@ -211,7 +211,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
         overallScore: number;
         dimensions: {
             recommendations: string[];
-            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
+            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio" | "api-test-coverage";
             score: number;
             weight: number;
             evidence: string[];
@@ -261,7 +261,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
         overallScore: number;
         dimensions: {
             recommendations: string[];
-            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
+            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio" | "api-test-coverage";
             score: number;
             weight: number;
             evidence: string[];
@@ -311,7 +311,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
         overallScore: number;
         dimensions: {
             recommendations: string[];
-            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
+            dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio" | "api-test-coverage";
             score: number;
             weight: number;
             evidence: string[];

package/dist/tools/repo/api-surface.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @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 type { RepoAnalysis } from '../../schemas/repo-analysis.schema.js';
+export interface DiscoveredEndpoint {
+    /** HTTP method inferred from the source — 'unknown' when ambiguous */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'unknown';
+    /** Path as extracted from source — may contain framework-specific params like [id] or :id */
+    path: string;
+    /** Repo-relative file path the evidence was read from */
+    sourceFile: string;
+    /** Discovery tier */
+    sourceTier: 'openapi' | 'framework' | 'heuristic';
+    /** Evidence confidence */
+    confidence: 'high' | 'medium' | 'low';
+    /** Human-readable summary from spec, if available (Tier1 only) */
+    summary?: string;
+    /** Parameter names extracted from spec (Tier1 only; never fabricated) */
+    parameterNames?: string[];
+}
+export interface ApiSurface {
+    discoveredAt: string;
+    repoPath: string;
+    endpoints: DiscoveredEndpoint[];
+    /** Number of OpenAPI/Swagger spec files found and successfully parsed */
+    openApiSpecsFound: number;
+    /** Tier3 heuristics were enabled */
+    tier3Enabled: boolean;
+}
+export interface DiscoverApiSurfaceOptions {
+    /** Enable Tier3 heuristic discovery (default false — opt-in) */
+    enableTier3?: boolean;
+}
+export declare function discoverApiSurface(repoPath: string, options?: DiscoverApiSurfaceOptions): Promise<ApiSurface>;
+/**
+ * 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 declare function discoverApiSurfaceWithRepo(repoPath: string, repo: RepoAnalysis, options?: DiscoverApiSurfaceOptions): Promise<ApiSurface>;
+//# sourceMappingURL=api-surface.d.ts.map

package/dist/tools/repo/api-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-surface.d.ts","sourceRoot":"","sources":["../../../src/tools/repo/api-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAiC1E,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IAChE,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,UAAU,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;IAClD,0BAA0B;IAC1B,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,yBAAyB;IACxC,gEAAgE;IAChE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAwXD,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,UAAU,CAAC,CAoCrB;AAED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,YAAY,EAClB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,UAAU,CAAC,CAQrB"}

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"}