@qulib/core 0.7.0 → 0.8.2

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

package/dist/tools/scoring/automation-maturity.js

@@ -1,16 +1,29 @@
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { AutomationMaturitySchema } from '../../schemas/automation-maturity.schema.js';
+import { REBALANCED_WEIGHTS } from './api-coverage.js';
 /**
- * Dimension weights (sum = 1). Breadth + harness adoption dominate: shipping risk is mostly
- * untested routes and missing Playwright/Cypress-level coverage.
+ * Dimension weights (sum = 1).
+ *
+ * When apiSurface is NOT provided (backward-compat path), the original 6 dimensions
+ * continue to use the original weights (sum = 1.0). When apiSurface IS provided, the
+ * rebalanced weights from api-coverage.ts are used and the 7th dimension is added.
+ *
+ * Original weights (no API surface):
+ *   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
+ *
+ * Rebalanced weights (with API surface, sum still = 1.0 across all 7):
+ *   test-coverage-breadth  0.24, framework-adoption 0.19, test-id-hygiene 0.15,
+ *   ci-integration 0.12, auth-test-coverage 0.09, component-test-ratio 0.06,
+ *   api-test-coverage 0.15
  */
-const W_TEST_BREADTH = 0.28;
-const W_FRAMEWORK = 0.22;
-const W_TEST_ID = 0.18;
-const W_CI = 0.14;
-const W_AUTH_TESTS = 0.1;
-const W_COMPONENT_RATIO = 0.08;
+const W_TEST_BREADTH_ORIGINAL = 0.28;
+const W_FRAMEWORK_ORIGINAL = 0.22;
+const W_TEST_ID_ORIGINAL = 0.18;
+const W_CI_ORIGINAL = 0.14;
+const W_AUTH_TESTS_ORIGINAL = 0.1;
+const W_COMPONENT_RATIO_ORIGINAL = 0.08;
 function hasCiAtRoot(repoPath) {
     const ev = [];
     const gh = join(repoPath, '.github', 'workflows');
@@ -49,7 +62,24 @@ function scoreLevel(overall) {
         return { level: 4, label: 'L4 — strong automation' };
     return { level: 5, label: 'L5 — advanced QA automation' };
 }
-export function computeAutomationMaturity(repo) {
+/**
+ * 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 function computeAutomationMaturity(repo, apiCoverageResult) {
+    // Choose weights based on whether we have an API surface result
+    const hasApiDim = apiCoverageResult !== undefined;
+    const W_TEST_BREADTH = hasApiDim ? REBALANCED_WEIGHTS.TEST_BREADTH : W_TEST_BREADTH_ORIGINAL;
+    const W_FRAMEWORK = hasApiDim ? REBALANCED_WEIGHTS.FRAMEWORK : W_FRAMEWORK_ORIGINAL;
+    const W_TEST_ID = hasApiDim ? REBALANCED_WEIGHTS.TEST_ID : W_TEST_ID_ORIGINAL;
+    const W_CI = hasApiDim ? REBALANCED_WEIGHTS.CI : W_CI_ORIGINAL;
+    const W_AUTH_TESTS = hasApiDim ? REBALANCED_WEIGHTS.AUTH_TESTS : W_AUTH_TESTS_ORIGINAL;
+    const W_COMPONENT_RATIO = hasApiDim ? REBALANCED_WEIGHTS.COMPONENT_RATIO : W_COMPONENT_RATIO_ORIGINAL;
     const routePaths = [...new Set(repo.routes.map((r) => r.path))];
     let coveredRoutes = 0;
     for (const p of routePaths) {
@@ -204,6 +234,10 @@ export function computeAutomationMaturity(repo) {
         ...(compGuidance && { guidance: compGuidance }),
     };
     const dimensions = [breadthDim, frameworkDim, hygieneDim, ciDim, authDim, compDim];
+    // Append api-test-coverage dimension when an API surface result was provided
+    if (apiCoverageResult) {
+        dimensions.push(apiCoverageResult.dimension);
+    }
     // Overall score normalizes over applicable dimensions only.
     // overallScore = round( Σ score_i * weight_i / Σ weight_i ) for i ∈ applicable.
     // If no dimension is applicable (degenerate repo), overall = 0 and level = L1.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qulib/core",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "description": "Qulib — analyze deployed web apps for honest quality gaps (CLI + programmatic API)",
   "license": "MIT",
   "author": "Tapesh Nagarwal",
@@ -48,7 +48,7 @@
     "analyze": "tsx src/cli/index.ts analyze",
     "clean": "tsx src/cli/index.ts clean",
     "build": "tsc",
-    "test": "node --import tsx/esm --test src/llm/__tests__/cost-intelligence.test.ts src/llm/__tests__/context-builder.test.ts src/tools/scoring/__tests__/gaps.test.ts src/tools/auth/__tests__/gaps.test.ts src/tools/auth/__tests__/detect.test.ts src/tools/scoring/__tests__/automation-maturity.test.ts src/harness/__tests__/state-manager.test.ts src/telemetry/__tests__/redact-url.test.ts src/cli/__tests__/auth-login.test.ts src/cli/__tests__/cli-version.test.ts src/__tests__/agent-summary.test.ts src/__tests__/cli-agent-summary.test.ts src/__tests__/analyze.storage-state-invalid.test.ts src/__tests__/analyze.fixtures.test.ts",
+    "test": "node --import tsx/esm --test src/llm/__tests__/cost-intelligence.test.ts src/llm/__tests__/context-builder.test.ts src/tools/scoring/__tests__/gaps.test.ts src/tools/auth/__tests__/gaps.test.ts src/tools/auth/__tests__/detect.test.ts src/tools/scoring/__tests__/automation-maturity.test.ts src/tools/scoring/__tests__/api-coverage.test.ts src/tools/scoring/__tests__/automation-maturity-with-api.test.ts src/harness/__tests__/state-manager.test.ts src/telemetry/__tests__/redact-url.test.ts src/cli/__tests__/auth-login.test.ts src/cli/__tests__/cli-version.test.ts src/__tests__/agent-summary.test.ts src/__tests__/cli-agent-summary.test.ts src/__tests__/analyze.storage-state-invalid.test.ts src/__tests__/analyze.fixtures.test.ts src/adapters/__tests__/playwright-adapter.test.ts src/adapters/__tests__/api-adapter.test.ts src/tools/repo/__tests__/api-surface.test.ts",
     "test:integration": "node --import tsx/esm --test src/__tests__/analyze.integration.test.ts",
     "smoke": "tsx src/cli/index.ts analyze --url https://example.com --ephemeral",
     "cost-doctor": "tsx src/cli/index.ts cost doctor"
@@ -58,9 +58,11 @@
     "@playwright/test": "^1.44.0",
     "commander": "^12.1.0",
     "fast-glob": "^3.3.2",
+    "js-yaml": "^4.2.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.0.0",
     "tsx": "^4.11.0",
     "typescript": "^5.4.0"