@qulib/core 0.4.2 → 0.5.0

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

@@ -0,0 +1,231 @@
+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;
+    let hygieneGuidance;
+    const hygieneEvidence = [];
+    if (interactiveTsxScanned === 0) {
+        hygieneApplicability = 'unknown';
+        hygieneReason = 'No interactive TSX files scanned — cannot compute a missing-id ratio honestly.';
+        hygieneGuidance =
+            'Qulib could not collect enough signal to score this dimension. Run against a repo with more test files or a larger page scan to improve signal.';
+        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 }),
+        ...(hygieneGuidance && { guidance: hygieneGuidance }),
+    };
+    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;
+    let authGuidance;
+    const authEvidence = [];
+    if (!repoHasAnyAuthSignal) {
+        authApplicability = 'not_applicable';
+        authReason = 'No auth routes, auth-named test files, or auth path coverage detected — repo appears auth-free.';
+        authGuidance =
+            'No auth signal detected in this app. If authentication exists, run qulib with a storage-state file to enable auth-test-coverage scoring.';
+        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 }),
+        ...(authGuidance && { guidance: authGuidance }),
+    };
+    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;
+    let compGuidance;
+    const compEvidence = [];
+    if (cypressTotal === 0) {
+        compApplicability = 'not_applicable';
+        compReason = 'No Cypress (e2e or component) tests detected — component-test-ratio does not apply.';
+        compGuidance =
+            'No Cypress component test setup detected. Add cypress/component/ tests and a component config to enable this dimension.';
+        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 }),
+        ...(compGuidance && { guidance: compGuidance }),
+    };
+    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"}

package/dist/tools/scoring/gaps.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/public-surface.d.ts

@@ -0,0 +1,5 @@
+import type { RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { Gap } from '../../schemas/gap-analysis.schema.js';
+import type { PublicSurface } from '../../schemas/public-surface.schema.js';
+export declare function buildPublicSurface(pages: RouteInventory['routes'], gaps: Gap[]): PublicSurface;
+//# sourceMappingURL=public-surface.d.ts.map

package/dist/tools/scoring/public-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-surface.d.ts","sourceRoot":"","sources":["../../../src/tools/scoring/public-surface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sCAAsC,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAmD,MAAM,wCAAwC,CAAC;AAE7H,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,aAAa,CAY9F"}

package/dist/tools/scoring/public-surface.js

@@ -0,0 +1,13 @@
+export function buildPublicSurface(pages, gaps) {
+    const accessibilityViolations = [];
+    const brokenLinks = [];
+    for (const r of pages) {
+        for (const v of r.a11yViolations) {
+            accessibilityViolations.push({ ...v, path: r.path });
+        }
+        for (const b of r.brokenLinks) {
+            brokenLinks.push({ ...b, path: r.path });
+        }
+    }
+    return { pages, gaps, accessibilityViolations, brokenLinks };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qulib/core",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Qulib — analyze deployed web apps for honest quality gaps (CLI + programmatic API)",
   "license": "MIT",
   "author": "Tapesh Nagarwal",
@@ -48,8 +48,8 @@
     "analyze": "tsx src/cli/index.ts analyze",
     "clean": "tsx src/cli/index.ts clean",
     "build": "tsc",
-    "test": "node --import tsx/esm --test src/llm/cost-intelligence.test.ts src/tools/gap-engine.test.ts src/tools/auth-block-gap.test.ts src/tools/auth-detector.test.ts src/tools/automation-maturity.test.ts src/harness/state-manager.test.ts src/telemetry/redact-url.test.ts src/cli/auth-login.test.ts src/cli/cli-version.test.ts",
-    "test:integration": "node --import tsx/esm --test src/analyze.integration.test.ts",
+    "test": "node --import tsx/esm --test src/llm/__tests__/cost-intelligence.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__/analyze.storage-state-invalid.test.ts src/__tests__/analyze.fixtures.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"
   },