@qulib/core 0.4.1 → 0.4.3

package/dist/tools/repo/scanner.js

@@ -0,0 +1,181 @@
+/**
+ * @module repo-scanner
+ * @packageBoundary @qulib/core (candidate: @qulib/analyzer)
+ *
+ * This module performs static analysis of a repository's file structure.
+ * It is currently embedded in @qulib/core because repo scanning is part of
+ * the observe phase and @qulib/core is the only consumer.
+ *
+ * Extraction to @qulib/analyzer is appropriate when:
+ *   1. A consumer needs repo analysis without URL crawling
+ *   2. The module grows to include PRD/Jira/Confluence ingestion
+ *   3. A standalone CLI command `qulib analyze-repo` is needed
+ *
+ * Before extraction: ensure RepoAnalysis schema is re-exported from @qulib/analyzer
+ * and @qulib/core depends on @qulib/analyzer (not the reverse).
+ */
+import { readFile } from 'node:fs/promises';
+import { relative, basename } from 'node:path';
+import glob from 'fast-glob';
+import { RepoAnalysisSchema } from '../../schemas/repo-analysis.schema.js';
+import { detectFramework } from './framework-detector.js';
+import { computeAutomationMaturity } from '../scoring/automation-maturity.js';
+const IGNORE_PATTERNS = ['**/node_modules/**', '**/.next/**', '**/dist/**', '**/build/**'];
+function toPosix(path) {
+    return path.split('\\').join('/');
+}
+function normalizeRoutePath(path) {
+    const normalized = `/${path}`.replace(/\/+/g, '/').replace(/\/$/, '');
+    return normalized === '' ? '/' : normalized;
+}
+function detectTestType(filePath, content) {
+    const normalizedPath = toPosix(filePath);
+    if (normalizedPath.includes('cypress/e2e'))
+        return 'cypress-e2e';
+    if (normalizedPath.includes('cypress/component'))
+        return 'cypress-component';
+    if ((normalizedPath.includes('playwright') || normalizedPath.includes('e2e')) &&
+        normalizedPath.endsWith('.spec.ts')) {
+        return 'playwright';
+    }
+    if (/\bfrom\s+['"]vitest['"]|\brequire\(['"]vitest['"]\)/.test(content))
+        return 'vitest';
+    if (/\bfrom\s+['"]jest['"]|\brequire\(['"]jest['"]\)/.test(content))
+        return 'jest';
+    return 'other';
+}
+function extractCoveredPaths(content) {
+    const matches = [...content.matchAll(/['"`](\/[a-zA-Z0-9\/_\-\[\]]+)['"`]/g)].map((m) => m[1]);
+    return [...new Set(matches)];
+}
+export async function scanRepo(repoPath) {
+    const routes = [];
+    const appRouterFiles = await glob(['app/**/page.tsx', 'app/**/page.ts'], {
+        cwd: repoPath,
+        onlyFiles: true,
+        absolute: true,
+        ignore: IGNORE_PATTERNS,
+    });
+    for (const file of appRouterFiles) {
+        const rel = toPosix(relative(repoPath, file));
+        const routeSegment = rel.replace(/^app\//, '').replace(/\/page\.tsx?$/, '');
+        const routePath = normalizeRoutePath(routeSegment);
+        routes.push({ path: routePath, file: rel, method: 'GET' });
+    }
+    const pagesRouterFiles = await glob(['pages/**/*.tsx', 'pages/**/*.ts'], {
+        cwd: repoPath,
+        onlyFiles: true,
+        absolute: true,
+        ignore: IGNORE_PATTERNS,
+    });
+    for (const file of pagesRouterFiles) {
+        const rel = toPosix(relative(repoPath, file));
+        const name = basename(rel);
+        if (name.startsWith('_'))
+            continue;
+        const routeSegment = rel.replace(/^pages\//, '').replace(/\.tsx?$/, '');
+        const routePath = routeSegment === 'index'
+            ? '/'
+            : normalizeRoutePath(routeSegment.replace(/\/index$/, ''));
+        routes.push({ path: routePath, file: rel, method: 'GET' });
+    }
+    const expressFiles = await glob(['src/**/*.ts', 'src/**/*.js'], {
+        cwd: repoPath,
+        onlyFiles: true,
+        absolute: true,
+        ignore: IGNORE_PATTERNS,
+    });
+    for (const file of expressFiles) {
+        const rel = toPosix(relative(repoPath, file));
+        const content = await readFile(file, 'utf8');
+        const routeRegex = /router\.(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)/gi;
+        for (const match of content.matchAll(routeRegex)) {
+            const method = match[1]?.toUpperCase();
+            const routePath = normalizeRoutePath(match[2] ?? '/');
+            routes.push({ path: routePath, file: rel, method });
+        }
+    }
+    const testFilePaths = await glob([
+        '**/*.spec.ts',
+        '**/*.test.ts',
+        '**/*.spec.tsx',
+        '**/*.test.tsx',
+        '**/cypress/e2e/**/*.ts',
+        '**/cypress/e2e/**/*.cy.ts',
+    ], {
+        cwd: repoPath,
+        onlyFiles: true,
+        absolute: true,
+        ignore: IGNORE_PATTERNS,
+    });
+    const testFiles = [];
+    for (const file of [...new Set(testFilePaths)]) {
+        const rel = toPosix(relative(repoPath, file));
+        const content = await readFile(file, 'utf8');
+        testFiles.push({
+            file: rel,
+            type: detectTestType(rel, content),
+            coveredPaths: extractCoveredPaths(content),
+        });
+    }
+    const cypressRoot = await glob(['cypress'], { cwd: repoPath, onlyDirectories: true, absolute: false, deep: 1 });
+    const e2eFolder = await glob(['cypress/e2e'], { cwd: repoPath, onlyDirectories: true, absolute: false, deep: 1 });
+    const componentFolder = await glob(['cypress/component'], { cwd: repoPath, onlyDirectories: true, absolute: false, deep: 1 });
+    const fixturesFolder = await glob(['cypress/fixtures'], { cwd: repoPath, onlyDirectories: true, absolute: false, deep: 1 });
+    const supportFolder = await glob(['cypress/support'], { cwd: repoPath, onlyDirectories: true, absolute: false, deep: 1 });
+    const commandsFile = await glob(['cypress/support/commands.ts'], { cwd: repoPath, onlyFiles: true, absolute: false });
+    const existingE2eFiles = await glob(['cypress/e2e/**/*.cy.ts'], { cwd: repoPath, onlyFiles: true, absolute: false });
+    const existingComponentFiles = await glob(['cypress/component/**/*.cy.tsx'], {
+        cwd: repoPath,
+        onlyFiles: true,
+        absolute: false,
+    });
+    const tsxFiles = await glob(['**/*.tsx'], {
+        cwd: repoPath,
+        onlyFiles: true,
+        absolute: true,
+        ignore: [...IGNORE_PATTERNS, '**/*.spec.tsx'],
+    });
+    const missingTestIds = [];
+    let interactiveTsxFilesScanned = 0;
+    for (const file of tsxFiles) {
+        const rel = toPosix(relative(repoPath, file));
+        const content = await readFile(file, 'utf8');
+        const hasInteractive = content.includes('<button') || content.includes('<input') || content.includes('<a ');
+        if (hasInteractive) {
+            interactiveTsxFilesScanned += 1;
+            if (!content.includes('data-testid')) {
+                missingTestIds.push(rel);
+            }
+        }
+    }
+    const base = {
+        scannedAt: new Date().toISOString(),
+        repoPath,
+        routes,
+        testFiles,
+        missingTestIds: [...new Set(missingTestIds)],
+        interactiveTsxFilesScanned,
+        cypressStructure: {
+            detected: cypressRoot.length > 0,
+            e2eFolder: e2eFolder[0],
+            componentFolder: componentFolder[0],
+            fixturesFolder: fixturesFolder[0],
+            supportFolder: supportFolder[0],
+            hasCommandsFile: commandsFile.length > 0,
+            existingE2eFiles,
+            existingComponentFiles,
+        },
+    };
+    let parsed = RepoAnalysisSchema.parse(base);
+    try {
+        const framework = await detectFramework(repoPath);
+        parsed = RepoAnalysisSchema.parse({ ...parsed, framework });
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.warn(`[qulib] framework detection failed for ${repoPath}: ${msg}`);
+    }
+    const automationMaturity = computeAutomationMaturity(parsed);
+    return RepoAnalysisSchema.parse({ ...parsed, automationMaturity });
+}

package/dist/tools/repo-scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repo-scanner.d.ts","sourceRoot":"","sources":["../../src/tools/repo-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAmC3F,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAyItE"}
+{"version":3,"file":"repo-scanner.d.ts","sourceRoot":"","sources":["../../src/tools/repo-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAmC3F,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA8ItE"}

package/dist/tools/repo-scanner.js

@@ -137,12 +137,16 @@ export async function scanRepo(repoPath) {
         ignore: [...IGNORE_PATTERNS, '**/*.spec.tsx'],
     });
     const missingTestIds = [];
+    let interactiveTsxFilesScanned = 0;
     for (const file of tsxFiles) {
         const rel = toPosix(relative(repoPath, file));
         const content = await readFile(file, 'utf8');
         const hasInteractive = content.includes('<button') || content.includes('<input') || content.includes('<a ');
-        if (hasInteractive && !content.includes('data-testid')) {
-            missingTestIds.push(rel);
+        if (hasInteractive) {
+            interactiveTsxFilesScanned += 1;
+            if (!content.includes('data-testid')) {
+                missingTestIds.push(rel);
+            }
         }
     }
     const base = {
@@ -151,6 +155,7 @@ export async function scanRepo(repoPath) {
         routes,
         testFiles,
         missingTestIds: [...new Set(missingTestIds)],
+        interactiveTsxFilesScanned,
         cypressStructure: {
             detected: cypressRoot.length > 0,
             e2eFolder: e2eFolder[0],

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

@@ -0,0 +1,4 @@
+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;
+//# sourceMappingURL=automation-maturity.d.ts.map

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

@@ -0,0 +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,CAuLhF"}

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

@@ -0,0 +1,219 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { AutomationMaturitySchema } from '../../schemas/automation-maturity.schema.js';
+/**
+ * Dimension weights (sum = 1). Breadth + harness adoption dominate: shipping risk is mostly
+ * untested routes and missing Playwright/Cypress-level coverage.
+ */
+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;
+function hasCiAtRoot(repoPath) {
+    const ev = [];
+    const gh = join(repoPath, '.github', 'workflows');
+    if (existsSync(gh) && statSync(gh).isDirectory()) {
+        try {
+            const files = readdirSync(gh).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+            if (files.length > 0) {
+                ev.push(`.github/workflows (${files.length} workflow file(s))`);
+                return { ok: true, evidence: ev };
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (existsSync(join(repoPath, '.circleci'))) {
+        ev.push('.circleci/ present');
+        return { ok: true, evidence: ev };
+    }
+    for (const f of ['.gitlab-ci.yml', 'Jenkinsfile']) {
+        if (existsSync(join(repoPath, f))) {
+            ev.push(`${f} present`);
+            return { ok: true, evidence: ev };
+        }
+    }
+    return { ok: false, evidence: ['No GitHub Actions, CircleCI, GitLab CI, or Jenkinsfile detected at repo root'] };
+}
+function scoreLevel(overall) {
+    if (overall < 20)
+        return { level: 1, label: 'L1 — nascent automation' };
+    if (overall < 40)
+        return { level: 2, label: 'L2 — emerging coverage' };
+    if (overall < 60)
+        return { level: 3, label: 'L3 — building maturity' };
+    if (overall < 80)
+        return { level: 4, label: 'L4 — strong automation' };
+    return { level: 5, label: 'L5 — advanced QA automation' };
+}
+export function computeAutomationMaturity(repo) {
+    const routePaths = [...new Set(repo.routes.map((r) => r.path))];
+    let coveredRoutes = 0;
+    for (const p of routePaths) {
+        const covered = repo.testFiles.some((tf) => tf.coveredPaths.some((c) => p === c || (c !== '/' && p.startsWith(c))));
+        if (covered)
+            coveredRoutes++;
+    }
+    const breadthScore = routePaths.length === 0 ? 100 : Math.round((100 * coveredRoutes) / routePaths.length);
+    const breadthDim = {
+        dimension: 'test-coverage-breadth',
+        score: breadthScore,
+        weight: W_TEST_BREADTH,
+        evidence: routePaths.length === 0
+            ? ['No static routes inferred from repo layout']
+            : [
+                `${coveredRoutes}/${routePaths.length} inferred routes appear in at least one test coveredPaths`,
+            ],
+        recommendations: breadthScore >= 80
+            ? []
+            : ['Add route-level smoke tests that assert critical paths referenced in production URLs.'],
+    };
+    const types = new Set(repo.testFiles.map((t) => t.type));
+    let frameworkScore = 0;
+    const fwEvidence = [`Test runners seen: ${[...types].join(', ') || 'none'}`];
+    if (types.has('playwright') || types.has('cypress-e2e') || types.has('cypress-component')) {
+        frameworkScore = 100;
+        fwEvidence.push('Playwright or Cypress present — good browser harness signal.');
+    }
+    else if (types.has('jest') || types.has('vitest')) {
+        frameworkScore = 55;
+        fwEvidence.push('Jest/Vitest only — add Playwright or Cypress for deployment-facing checks.');
+    }
+    else if (repo.testFiles.length > 0) {
+        frameworkScore = 30;
+        fwEvidence.push('Tests exist but no recognized browser harness in scanned files.');
+    }
+    else {
+        frameworkScore = 0;
+        fwEvidence.push('No test files matched qulib scan globs.');
+    }
+    const frameworkDim = {
+        dimension: 'framework-adoption',
+        score: frameworkScore,
+        weight: W_FRAMEWORK,
+        evidence: fwEvidence,
+        recommendations: frameworkScore >= 80 ? [] : ['Standardize on Playwright or Cypress for E2E against deployed URLs.'],
+    };
+    const missingIds = repo.missingTestIds.length;
+    const interactiveTsxScanned = repo.interactiveTsxFilesScanned ?? missingIds;
+    let hygieneScore = 0;
+    let hygieneApplicability = 'applicable';
+    let hygieneReason;
+    const hygieneEvidence = [];
+    if (interactiveTsxScanned === 0) {
+        hygieneApplicability = 'unknown';
+        hygieneReason = 'No interactive TSX files scanned — cannot compute a missing-id ratio honestly.';
+        hygieneEvidence.push(hygieneReason);
+    }
+    else {
+        const missingRatio = missingIds / interactiveTsxScanned;
+        hygieneScore = Math.round(Math.max(0, 100 * (1 - missingRatio)));
+        hygieneEvidence.push(`${missingIds}/${interactiveTsxScanned} interactive TSX file(s) lacked data-testid (heuristic scan).`);
+    }
+    const hygieneDim = {
+        dimension: 'test-id-hygiene',
+        score: hygieneScore,
+        weight: W_TEST_ID,
+        evidence: hygieneEvidence,
+        recommendations: hygieneApplicability === 'applicable' && hygieneScore < 85
+            ? ['Add stable data-testid (or role-based selectors) on interactive components used in tests.']
+            : [],
+        applicability: hygieneApplicability,
+        ...(hygieneReason && { reason: hygieneReason }),
+    };
+    const ci = hasCiAtRoot(repo.repoPath);
+    const ciDim = {
+        dimension: 'ci-integration',
+        score: ci.ok ? 100 : 0,
+        weight: W_CI,
+        evidence: ci.evidence,
+        recommendations: ci.ok ? [] : ['Add a CI workflow that runs unit/E2E tests on every PR.'],
+    };
+    const authRe = /\/(login|auth|signin)(\/|$)/i;
+    const authRouteFileRe = /(login|auth|signin)/i;
+    const authCovered = repo.testFiles.some((tf) => tf.coveredPaths.some((c) => authRe.test(c)));
+    const repoHasAuthRoute = repo.routes.some((r) => authRe.test(r.path));
+    const repoHasAuthTestFile = repo.testFiles.some((tf) => authRouteFileRe.test(tf.file));
+    const repoHasAnyAuthSignal = repoHasAuthRoute || repoHasAuthTestFile || authCovered;
+    let authScore = 0;
+    let authApplicability = 'applicable';
+    let authReason;
+    const authEvidence = [];
+    if (!repoHasAnyAuthSignal) {
+        authApplicability = 'not_applicable';
+        authReason = 'No auth routes, auth-named test files, or auth path coverage detected — repo appears auth-free.';
+        authEvidence.push(authReason);
+    }
+    else {
+        authScore = authCovered ? 90 : 25;
+        authEvidence.push(authCovered
+            ? 'At least one test references /login, /auth, or /signin in coveredPaths.'
+            : 'Repo has auth-shaped routes or test files but no auth-route coverage in extracted test path strings.');
+    }
+    const authDim = {
+        dimension: 'auth-test-coverage',
+        score: authScore,
+        weight: W_AUTH_TESTS,
+        evidence: authEvidence,
+        recommendations: authApplicability === 'applicable' && !authCovered
+            ? ['Add focused tests for sign-in and post-auth landing behavior.']
+            : [],
+        applicability: authApplicability,
+        ...(authReason && { reason: authReason }),
+    };
+    const cypressE2e = repo.testFiles.filter((t) => t.type === 'cypress-e2e').length;
+    const cypressComp = repo.testFiles.filter((t) => t.type === 'cypress-component').length;
+    const cypressTotal = cypressE2e + cypressComp;
+    let compRatioScore = 0;
+    let compApplicability = 'applicable';
+    let compReason;
+    const compEvidence = [];
+    if (cypressTotal === 0) {
+        compApplicability = 'not_applicable';
+        compReason = 'No Cypress (e2e or component) tests detected — component-test-ratio does not apply.';
+        compEvidence.push(compReason);
+    }
+    else {
+        compRatioScore = Math.round((100 * cypressComp) / cypressTotal);
+        compEvidence.push(`Cypress e2e files (matched): ${cypressE2e}, component: ${cypressComp}.`);
+    }
+    const compDim = {
+        dimension: 'component-test-ratio',
+        score: compRatioScore,
+        weight: W_COMPONENT_RATIO,
+        evidence: compEvidence,
+        recommendations: compApplicability === 'applicable' && cypressComp > 0
+            ? ['Balance component vs E2E Cypress tests so critical flows stay fast in CI.']
+            : [],
+        applicability: compApplicability,
+        ...(compReason && { reason: compReason }),
+    };
+    const dimensions = [breadthDim, frameworkDim, hygieneDim, ciDim, authDim, compDim];
+    // 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.
+    const applicableDims = dimensions.filter((d) => (d.applicability ?? 'applicable') === 'applicable');
+    const weightSum = applicableDims.reduce((s, d) => s + d.weight, 0);
+    const overallScore = weightSum > 0
+        ? Math.round(applicableDims.reduce((s, d) => s + d.score * d.weight, 0) / weightSum)
+        : 0;
+    const { level, label } = scoreLevel(overallScore);
+    const topRecommendations = [...applicableDims]
+        .sort((a, b) => a.score - b.score)
+        .flatMap((d) => d.recommendations)
+        .filter(Boolean)
+        .slice(0, 8);
+    return AutomationMaturitySchema.parse({
+        computedAt: new Date().toISOString(),
+        repoPath: repo.repoPath,
+        overallScore,
+        level,
+        label,
+        dimensions,
+        topRecommendations,
+        scoreFormula: 'overallScore = round( Σ (score * weight) / Σ weight ) for applicable dimensions only. not_applicable and unknown dimensions are excluded from the denominator.',
+    });
+}

package/dist/tools/scoring/gap-engine.d.ts

@@ -0,0 +1,8 @@
+import { type GapAnalysis, type Gap } from '../../schemas/gap-analysis.schema.js';
+import type { RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { RepoAnalysis } from '../../schemas/repo-analysis.schema.js';
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+export declare function computeQualityScoreFromGaps(gaps: Gap[], scoringWeights?: HarnessConfig['scoringWeights']): number;
+export declare function computeCoverageScore(routes: RouteInventory): number | null;
+export declare function analyzeGaps(routes: RouteInventory, repo: RepoAnalysis | null, mode: 'url-only' | 'url-repo', config: HarnessConfig): Omit<GapAnalysis, 'scenarios' | 'generatedTests'>;
+//# sourceMappingURL=gap-engine.d.ts.map

package/dist/tools/scoring/gap-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gap-engine.d.ts","sourceRoot":"","sources":["../../../src/tools/scoring/gap-engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,WAAW,EAAE,KAAK,GAAG,EAAE,MAAM,sCAAsC,CAAC;AAC7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAQpE,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,GAAG,EAAE,EACX,cAAc,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAC/C,MAAM,CAkBR;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAa1E;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,YAAY,GAAG,IAAI,EACzB,IAAI,EAAE,UAAU,GAAG,UAAU,EAC7B,MAAM,EAAE,aAAa,GACpB,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB,CAAC,CAqGnD"}

package/dist/tools/scoring/gap-engine.js

@@ -0,0 +1,138 @@
+import { randomUUID } from 'node:crypto';
+import { GapSchema } from '../../schemas/gap-analysis.schema.js';
+// TODO: Add category-specific weight overrides (e.g., auth-surface gaps should cost more than untested-route gaps by default).
+// Requires a 2D weight matrix: { [severity]: { [category]: number } }.
+// Deferred until there is empirical data from real scan runs to calibrate.
+const DEFAULT_SCORING_WEIGHTS = { critical: 25, high: 20, medium: 8, low: 3 };
+export function computeQualityScoreFromGaps(gaps, scoringWeights) {
+    let critical = 0;
+    let high = 0;
+    let medium = 0;
+    let low = 0;
+    for (const g of gaps) {
+        if (g.severity === 'critical')
+            critical++;
+        else if (g.severity === 'high')
+            high++;
+        else if (g.severity === 'medium')
+            medium++;
+        else
+            low++;
+    }
+    const w = {
+        critical: scoringWeights?.critical ?? DEFAULT_SCORING_WEIGHTS.critical,
+        high: scoringWeights?.high ?? DEFAULT_SCORING_WEIGHTS.high,
+        medium: scoringWeights?.medium ?? DEFAULT_SCORING_WEIGHTS.medium,
+        low: scoringWeights?.low ?? DEFAULT_SCORING_WEIGHTS.low,
+    };
+    return Math.max(0, 100 - critical * w.critical - high * w.high - medium * w.medium - low * w.low);
+}
+export function computeCoverageScore(routes) {
+    const scanned = routes.routes.length;
+    const skipped = routes.pagesSkipped;
+    const denom = scanned + skipped;
+    // TODO: return null here once the explorer exposes an explicit "discovered-but-unknown" signal
+    //       (i.e. routes were found but the full set couldn't be confirmed — a low score is misleading)
+    if (denom === 0) {
+        if (routes.budgetExceeded) {
+            return 0;
+        }
+        return scanned === 0 ? 0 : 100;
+    }
+    return Math.round((100 * scanned) / denom);
+}
+export function analyzeGaps(routes, repo, mode, config) {
+    const coveredPaths = new Set();
+    if (repo) {
+        for (const testFile of repo.testFiles) {
+            for (const path of testFile.coveredPaths) {
+                coveredPaths.add(path);
+            }
+        }
+    }
+    const gaps = [];
+    const addGap = (gap) => {
+        const validated = GapSchema.parse(gap);
+        gaps.push(validated);
+    };
+    let hasNavigationFailures = false;
+    for (const route of routes.routes) {
+        if (repo && !coveredPaths.has(route.path)) {
+            const highRisk = /checkout|payment|auth|login|order/i.test(route.path);
+            addGap({
+                id: randomUUID(),
+                path: route.path,
+                severity: highRisk ? 'high' : 'medium',
+                reason: `Route is not covered by existing tests: ${route.path}`,
+                category: 'untested-route',
+            });
+        }
+        const navErrors = route.consoleErrors.filter((e) => e.startsWith('Navigation error:'));
+        if (navErrors.length > 0) {
+            hasNavigationFailures = true;
+            addGap({
+                id: randomUUID(),
+                path: route.path,
+                severity: 'high',
+                reason: `Navigation failed: ${navErrors.join('; ')}`,
+                category: 'console-error',
+            });
+        }
+        else if (route.consoleErrors.length > 0) {
+            addGap({
+                id: randomUUID(),
+                path: route.path,
+                severity: 'high',
+                reason: `Console errors detected (${route.consoleErrors.length})`,
+                category: 'console-error',
+            });
+        }
+        if (route.brokenLinks.length > 0) {
+            addGap({
+                id: randomUUID(),
+                path: route.path,
+                severity: 'medium',
+                reason: `Broken or invalid links detected (${route.brokenLinks.length})`,
+                category: 'broken-link',
+            });
+        }
+        for (const violation of route.a11yViolations) {
+            const impact = violation.impact.toLowerCase();
+            const severity = impact === 'critical'
+                ? 'critical'
+                : impact === 'serious'
+                    ? 'high'
+                    : impact === 'moderate'
+                        ? 'medium'
+                        : 'low';
+            addGap({
+                id: randomUUID(),
+                path: route.path,
+                severity,
+                reason: `A11y violation ${violation.id} (${violation.impact}): ${violation.helpUrl}`,
+                category: 'a11y',
+            });
+        }
+    }
+    const releaseConfidence = computeQualityScoreFromGaps(gaps, config.scoringWeights);
+    const pagesScanned = routes.routes.length;
+    let coverageWarning;
+    if (routes.budgetExceeded) {
+        coverageWarning = 'budget-exceeded';
+    }
+    else if (hasNavigationFailures) {
+        coverageWarning = 'navigation-failures';
+    }
+    else if (pagesScanned < config.minPagesForConfidence) {
+        coverageWarning = 'low-coverage';
+    }
+    return {
+        analyzedAt: new Date().toISOString(),
+        mode,
+        releaseConfidence,
+        coveragePagesScanned: pagesScanned,
+        coverageBudgetExceeded: routes.budgetExceeded,
+        coverageWarning,
+        gaps,
+    };
+}

package/dist/tools/scoring/gaps.d.ts

@@ -0,0 +1,8 @@
+import { type GapAnalysis, type Gap } from '../../schemas/gap-analysis.schema.js';
+import type { RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { RepoAnalysis } from '../../schemas/repo-analysis.schema.js';
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+export declare function computeQualityScoreFromGaps(gaps: Gap[], scoringWeights?: HarnessConfig['scoringWeights']): number;
+export declare function computeCoverageScore(routes: RouteInventory): number | null;
+export declare function analyzeGaps(routes: RouteInventory, repo: RepoAnalysis | null, mode: 'url-only' | 'url-repo', config: HarnessConfig): Omit<GapAnalysis, 'scenarios' | 'generatedTests'>;
+//# sourceMappingURL=gaps.d.ts.map

package/dist/tools/scoring/gaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaps.d.ts","sourceRoot":"","sources":["../../../src/tools/scoring/gaps.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,WAAW,EAAE,KAAK,GAAG,EAAE,MAAM,sCAAsC,CAAC;AAC7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAQpE,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,GAAG,EAAE,EACX,cAAc,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAC/C,MAAM,CAkBR;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAa1E;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,YAAY,GAAG,IAAI,EACzB,IAAI,EAAE,UAAU,GAAG,UAAU,EAC7B,MAAM,EAAE,aAAa,GACpB,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB,CAAC,CAqGnD"}