@qulib/core 0.4.1 → 0.4.3

package/dist/tools/automation-maturity.js

@@ -97,16 +97,32 @@ export function computeAutomationMaturity(repo) {
         evidence: fwEvidence,
         recommendations: frameworkScore >= 80 ? [] : ['Standardize on Playwright or Cypress for E2E against deployed URLs.'],
     };
-    const hygienePenalty = Math.min(100, repo.missingTestIds.length * 6);
-    const hygieneScore = Math.max(0, 100 - hygienePenalty);
+    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: [
-            `${repo.missingTestIds.length} TSX file(s) with interactive markup but no data-testid (heuristic scan).`,
-        ],
-        recommendations: hygieneScore >= 85 ? [] : ['Add stable data-testid (or role-based selectors) on interactive components used in tests.'],
+        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 = {
@@ -117,36 +133,75 @@ export function computeAutomationMaturity(repo) {
         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 authScore = authCovered ? 90 : 25;
+    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: authCovered
-            ? ['At least one test references /login, /auth, or /signin in coveredPaths.']
-            : ['No obvious auth-route coverage in extracted test path strings.'],
-        recommendations: authCovered ? [] : ['Add focused tests for sign-in and post-auth landing behavior.'],
+        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;
-    const compRatioScore = cypressTotal === 0 ? 50 : Math.round((100 * cypressComp) / cypressTotal);
+    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: [
-            `Cypress e2e files (matched): ${cypressE2e}, component: ${cypressComp}.`,
-        ],
-        recommendations: cypressComp === 0 || cypressTotal === 0
-            ? []
-            : ['Balance component vs E2E Cypress tests so critical flows stay fast in CI.'],
+        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];
-    const overallScore = Math.round(dimensions.reduce((s, d) => s + d.score * d.weight, 0));
+    // 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 = [...dimensions]
+    const topRecommendations = [...applicableDims]
         .sort((a, b) => a.score - b.score)
         .flatMap((d) => d.recommendations)
         .filter(Boolean)
@@ -159,5 +214,6 @@ export function computeAutomationMaturity(repo) {
         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/explorers/browser.d.ts

@@ -0,0 +1,3 @@
+import { type Browser } from '@playwright/test';
+export declare function launchBrowser(): Promise<Browser>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/tools/explorers/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE1D,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAYtD"}

package/dist/tools/explorers/browser.js

@@ -0,0 +1,13 @@
+import { chromium } from '@playwright/test';
+export async function launchBrowser() {
+    try {
+        return await chromium.launch({ headless: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("Executable doesn't exist") || message.includes('chromium')) {
+            throw new Error(`Playwright Chromium browser is not installed. Run:\n\n  npx playwright install chromium\n\nThen retry your qulib command. This is a one-time setup step.`);
+        }
+        throw err;
+    }
+}

package/dist/tools/explorers/cypress-explorer.d.ts

@@ -0,0 +1,8 @@
+import type { AppExplorer } from './explorer.interface.js';
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+import type { RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { RunArtifactsOptions } from '../../harness/run-options.js';
+export declare class CypressExplorer implements AppExplorer {
+    explore(_baseUrl: string, _config: HarnessConfig, _artifacts?: RunArtifactsOptions): Promise<RouteInventory>;
+}
+//# sourceMappingURL=cypress-explorer.d.ts.map

package/dist/tools/explorers/cypress-explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cypress-explorer.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/cypress-explorer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,qBAAa,eAAgB,YAAW,WAAW;IAC3C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;CAGnH"}

package/dist/tools/explorers/cypress-explorer.js

@@ -0,0 +1,5 @@
+export class CypressExplorer {
+    async explore(_baseUrl, _config, _artifacts) {
+        throw new Error('Not implemented');
+    }
+}

package/dist/tools/explorers/cypress.d.ts

@@ -0,0 +1,8 @@
+import type { AppExplorer } from './types.js';
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+import type { RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { RunArtifactsOptions } from '../../harness/run-options.js';
+export declare class CypressExplorer implements AppExplorer {
+    explore(_baseUrl: string, _config: HarnessConfig, _artifacts?: RunArtifactsOptions): Promise<RouteInventory>;
+}
+//# sourceMappingURL=cypress.d.ts.map

package/dist/tools/explorers/cypress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cypress.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/cypress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,qBAAa,eAAgB,YAAW,WAAW;IAC3C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;CAGnH"}

package/dist/tools/explorers/cypress.js

@@ -0,0 +1,5 @@
+export class CypressExplorer {
+    async explore(_baseUrl, _config, _artifacts) {
+        throw new Error('Not implemented');
+    }
+}

package/dist/tools/explorers/explorer.interface.d.ts

@@ -0,0 +1,7 @@
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+import type { RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { RunArtifactsOptions } from '../../harness/run-options.js';
+export interface AppExplorer {
+    explore(baseUrl: string, config: HarnessConfig, artifacts?: RunArtifactsOptions): Promise<RouteInventory>;
+}
+//# sourceMappingURL=explorer.interface.d.ts.map

package/dist/tools/explorers/explorer.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorer.interface.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/explorer.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3G"}

package/dist/tools/explorers/explorer.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/explorers/factory.d.ts

@@ -0,0 +1,4 @@
+import type { ExplorerType } from '../../schemas/config.schema.js';
+import type { AppExplorer } from './types.js';
+export declare function createExplorer(type: ExplorerType): AppExplorer;
+//# sourceMappingURL=factory.d.ts.map

package/dist/tools/explorers/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,CAS9D"}

package/dist/tools/explorers/factory.js

@@ -0,0 +1,12 @@
+import { PlaywrightExplorer } from './playwright.js';
+import { CypressExplorer } from './cypress.js';
+export function createExplorer(type) {
+    switch (type) {
+        case 'playwright':
+            return new PlaywrightExplorer();
+        case 'cypress':
+            return new CypressExplorer();
+        default:
+            throw new Error(`Unknown explorer type: ${type}`);
+    }
+}

package/dist/tools/explorers/playwright-explorer.d.ts

@@ -0,0 +1,8 @@
+import type { AppExplorer } from './explorer.interface.js';
+import { type RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+import type { RunArtifactsOptions } from '../../harness/run-options.js';
+export declare class PlaywrightExplorer implements AppExplorer {
+    explore(baseUrl: string, config: HarnessConfig, artifacts?: RunArtifactsOptions): Promise<RouteInventory>;
+}
+//# sourceMappingURL=playwright-explorer.d.ts.map

package/dist/tools/explorers/playwright-explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-explorer.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/playwright-explorer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAwB,KAAK,cAAc,EAAc,MAAM,yCAAyC,CAAC;AAChH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAoBxE,qBAAa,kBAAmB,YAAW,WAAW;IAC9C,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;CAsKhH"}

package/dist/tools/explorers/playwright-explorer.js

@@ -0,0 +1,172 @@
+import { launchBrowser } from './browser.js';
+import { AxeBuilder } from '@axe-core/playwright';
+import { createAuthenticatedContext } from '../auth/apply.js';
+import { RouteInventorySchema } from '../../schemas/route-inventory.schema.js';
+function crawlHostKey(hostname) {
+    return hostname.replace(/^www\./i, '').toLowerCase();
+}
+function isInternalHref(href, baseUrlStr) {
+    try {
+        const u = new URL(href);
+        const base = new URL(baseUrlStr);
+        return u.protocol === base.protocol && crawlHostKey(u.hostname) === crawlHostKey(base.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function debugMode() {
+    return process.env.QULIB_DEBUG === '1';
+}
+export class PlaywrightExplorer {
+    async explore(baseUrl, config, artifacts) {
+        const progress = artifacts?.progressLog;
+        const browser = await launchBrowser();
+        let context;
+        try {
+            context = await createAuthenticatedContext(browser, config.auth, config.timeoutMs);
+        }
+        catch (err) {
+            await browser.close();
+            throw new Error(`Authentication failed: ${String(err)}. Check your auth config and credentials.`);
+        }
+        if (config.auth) {
+            const label = config.auth.type === 'form-login' ? config.auth.credentials.username : 'storage-state';
+            progress?.info(`Authenticated context: ${label}`);
+            if (!progress) {
+                process.stderr.write(`[qulib] authenticated as ${label}\n`);
+            }
+        }
+        const visited = new Set();
+        const queue = [baseUrl];
+        const routes = [];
+        let budgetExceeded = false;
+        try {
+            while (queue.length > 0) {
+                if (visited.size >= config.maxPagesToScan) {
+                    budgetExceeded = queue.length > 0;
+                    break;
+                }
+                const url = queue.shift();
+                if (!url) {
+                    continue;
+                }
+                const normalized = url.split('?')[0].split('#')[0];
+                if (visited.has(normalized))
+                    continue;
+                visited.add(normalized);
+                const page = await context.newPage();
+                const consoleErrors = [];
+                page.on('console', (msg) => {
+                    if (msg.type() === 'error') {
+                        consoleErrors.push(msg.text());
+                    }
+                });
+                try {
+                    const navResponse = await page.goto(url, {
+                        timeout: config.timeoutMs,
+                        waitUntil: 'domcontentloaded',
+                    });
+                    const httpStatus = navResponse?.status() ?? 0;
+                    if (debugMode()) {
+                        const html = await page.content();
+                        progress?.debug(`page HTML byteLength=${Buffer.byteLength(html, 'utf8')} url=${normalized}`);
+                    }
+                    const pageTitle = await page.title();
+                    const formCount = await page.locator('form').count();
+                    const buttonLabels = await page.locator('button').allInnerTexts();
+                    const hrefs = await page.evaluate(() => Array.from(document.querySelectorAll('a[href]'))
+                        .map((a) => a.href)
+                        .filter(Boolean));
+                    const internalLinks = hrefs
+                        .filter((href) => isInternalHref(href, baseUrl))
+                        .map((href) => href.split('?')[0].split('#')[0]);
+                    const uniqueInternal = [...new Set(internalLinks)];
+                    for (const link of uniqueInternal) {
+                        if (!visited.has(link) && !queue.includes(link)) {
+                            queue.push(link);
+                        }
+                    }
+                    const brokenLinks = [];
+                    for (const link of uniqueInternal.slice(0, 20)) {
+                        try {
+                            const response = await page.request.head(link, { timeout: 5000 });
+                            if (response.status() >= 400) {
+                                brokenLinks.push({ url: link, status: response.status() });
+                            }
+                        }
+                        catch (err) {
+                            brokenLinks.push({ url: link, status: null, reason: String(err) });
+                        }
+                    }
+                    let a11yViolations = [];
+                    try {
+                        const axeResults = await new AxeBuilder({ page })
+                            .withTags(['wcag2a', 'wcag2aa'])
+                            .analyze();
+                        if (debugMode()) {
+                            progress?.debug(`raw axe violations (pre-map) count=${axeResults.violations.length} json=${JSON.stringify(axeResults.violations)}`);
+                        }
+                        a11yViolations = axeResults.violations.map((v) => ({
+                            id: v.id,
+                            impact: v.impact ?? 'unknown',
+                            helpUrl: v.helpUrl,
+                            nodeCount: v.nodes.length,
+                        }));
+                    }
+                    catch (err) {
+                        consoleErrors.push(`axe-core failure: ${String(err)}`);
+                    }
+                    const path = new URL(url).pathname || '/';
+                    progress?.info(`Crawled ${normalized} status=${httpStatus} a11yViolations=${a11yViolations.length}`);
+                    routes.push({
+                        path,
+                        pageTitle,
+                        links: uniqueInternal,
+                        formCount,
+                        buttonLabels: buttonLabels.map((b) => b.trim()).filter(Boolean),
+                        consoleErrors,
+                        brokenLinks,
+                        a11yViolations,
+                        statusCode: httpStatus,
+                    });
+                }
+                catch (err) {
+                    const path = (() => {
+                        try {
+                            return new URL(url).pathname || '/';
+                        }
+                        catch {
+                            return url;
+                        }
+                    })();
+                    progress?.info(`Crawled ${normalized} status=error a11yViolations=0 err=${String(err).slice(0, 120)}`);
+                    routes.push({
+                        path,
+                        pageTitle: '',
+                        links: [],
+                        formCount: 0,
+                        buttonLabels: [],
+                        consoleErrors: [`Navigation error: ${String(err)}`],
+                        brokenLinks: [],
+                        a11yViolations: [],
+                    });
+                }
+                finally {
+                    await page.close();
+                }
+            }
+        }
+        finally {
+            await context.close();
+            await browser.close();
+        }
+        return RouteInventorySchema.parse({
+            scannedAt: new Date().toISOString(),
+            baseUrl,
+            routes,
+            pagesSkipped: budgetExceeded ? queue.length : 0,
+            budgetExceeded,
+        });
+    }
+}

package/dist/tools/explorers/playwright.d.ts

@@ -0,0 +1,8 @@
+import type { AppExplorer } from './types.js';
+import { type RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+import type { RunArtifactsOptions } from '../../harness/run-options.js';
+export declare class PlaywrightExplorer implements AppExplorer {
+    explore(baseUrl: string, config: HarnessConfig, artifacts?: RunArtifactsOptions): Promise<RouteInventory>;
+}
+//# sourceMappingURL=playwright.d.ts.map

package/dist/tools/explorers/playwright.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/playwright.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAwB,KAAK,cAAc,EAAc,MAAM,yCAAyC,CAAC;AAChH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAoBxE,qBAAa,kBAAmB,YAAW,WAAW;IAC9C,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;CAsKhH"}

package/dist/tools/explorers/playwright.js

@@ -0,0 +1,172 @@
+import { launchBrowser } from './browser.js';
+import { AxeBuilder } from '@axe-core/playwright';
+import { createAuthenticatedContext } from '../auth/apply.js';
+import { RouteInventorySchema } from '../../schemas/route-inventory.schema.js';
+function crawlHostKey(hostname) {
+    return hostname.replace(/^www\./i, '').toLowerCase();
+}
+function isInternalHref(href, baseUrlStr) {
+    try {
+        const u = new URL(href);
+        const base = new URL(baseUrlStr);
+        return u.protocol === base.protocol && crawlHostKey(u.hostname) === crawlHostKey(base.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function debugMode() {
+    return process.env.QULIB_DEBUG === '1';
+}
+export class PlaywrightExplorer {
+    async explore(baseUrl, config, artifacts) {
+        const progress = artifacts?.progressLog;
+        const browser = await launchBrowser();
+        let context;
+        try {
+            context = await createAuthenticatedContext(browser, config.auth, config.timeoutMs);
+        }
+        catch (err) {
+            await browser.close();
+            throw new Error(`Authentication failed: ${String(err)}. Check your auth config and credentials.`);
+        }
+        if (config.auth) {
+            const label = config.auth.type === 'form-login' ? config.auth.credentials.username : 'storage-state';
+            progress?.info(`Authenticated context: ${label}`);
+            if (!progress) {
+                process.stderr.write(`[qulib] authenticated as ${label}\n`);
+            }
+        }
+        const visited = new Set();
+        const queue = [baseUrl];
+        const routes = [];
+        let budgetExceeded = false;
+        try {
+            while (queue.length > 0) {
+                if (visited.size >= config.maxPagesToScan) {
+                    budgetExceeded = queue.length > 0;
+                    break;
+                }
+                const url = queue.shift();
+                if (!url) {
+                    continue;
+                }
+                const normalized = url.split('?')[0].split('#')[0];
+                if (visited.has(normalized))
+                    continue;
+                visited.add(normalized);
+                const page = await context.newPage();
+                const consoleErrors = [];
+                page.on('console', (msg) => {
+                    if (msg.type() === 'error') {
+                        consoleErrors.push(msg.text());
+                    }
+                });
+                try {
+                    const navResponse = await page.goto(url, {
+                        timeout: config.timeoutMs,
+                        waitUntil: 'domcontentloaded',
+                    });
+                    const httpStatus = navResponse?.status() ?? 0;
+                    if (debugMode()) {
+                        const html = await page.content();
+                        progress?.debug(`page HTML byteLength=${Buffer.byteLength(html, 'utf8')} url=${normalized}`);
+                    }
+                    const pageTitle = await page.title();
+                    const formCount = await page.locator('form').count();
+                    const buttonLabels = await page.locator('button').allInnerTexts();
+                    const hrefs = await page.evaluate(() => Array.from(document.querySelectorAll('a[href]'))
+                        .map((a) => a.href)
+                        .filter(Boolean));
+                    const internalLinks = hrefs
+                        .filter((href) => isInternalHref(href, baseUrl))
+                        .map((href) => href.split('?')[0].split('#')[0]);
+                    const uniqueInternal = [...new Set(internalLinks)];
+                    for (const link of uniqueInternal) {
+                        if (!visited.has(link) && !queue.includes(link)) {
+                            queue.push(link);
+                        }
+                    }
+                    const brokenLinks = [];
+                    for (const link of uniqueInternal.slice(0, 20)) {
+                        try {
+                            const response = await page.request.head(link, { timeout: 5000 });
+                            if (response.status() >= 400) {
+                                brokenLinks.push({ url: link, status: response.status() });
+                            }
+                        }
+                        catch (err) {
+                            brokenLinks.push({ url: link, status: null, reason: String(err) });
+                        }
+                    }
+                    let a11yViolations = [];
+                    try {
+                        const axeResults = await new AxeBuilder({ page })
+                            .withTags(['wcag2a', 'wcag2aa'])
+                            .analyze();
+                        if (debugMode()) {
+                            progress?.debug(`raw axe violations (pre-map) count=${axeResults.violations.length} json=${JSON.stringify(axeResults.violations)}`);
+                        }
+                        a11yViolations = axeResults.violations.map((v) => ({
+                            id: v.id,
+                            impact: v.impact ?? 'unknown',
+                            helpUrl: v.helpUrl,
+                            nodeCount: v.nodes.length,
+                        }));
+                    }
+                    catch (err) {
+                        consoleErrors.push(`axe-core failure: ${String(err)}`);
+                    }
+                    const path = new URL(url).pathname || '/';
+                    progress?.info(`Crawled ${normalized} status=${httpStatus} a11yViolations=${a11yViolations.length}`);
+                    routes.push({
+                        path,
+                        pageTitle,
+                        links: uniqueInternal,
+                        formCount,
+                        buttonLabels: buttonLabels.map((b) => b.trim()).filter(Boolean),
+                        consoleErrors,
+                        brokenLinks,
+                        a11yViolations,
+                        statusCode: httpStatus,
+                    });
+                }
+                catch (err) {
+                    const path = (() => {
+                        try {
+                            return new URL(url).pathname || '/';
+                        }
+                        catch {
+                            return url;
+                        }
+                    })();
+                    progress?.info(`Crawled ${normalized} status=error a11yViolations=0 err=${String(err).slice(0, 120)}`);
+                    routes.push({
+                        path,
+                        pageTitle: '',
+                        links: [],
+                        formCount: 0,
+                        buttonLabels: [],
+                        consoleErrors: [`Navigation error: ${String(err)}`],
+                        brokenLinks: [],
+                        a11yViolations: [],
+                    });
+                }
+                finally {
+                    await page.close();
+                }
+            }
+        }
+        finally {
+            await context.close();
+            await browser.close();
+        }
+        return RouteInventorySchema.parse({
+            scannedAt: new Date().toISOString(),
+            baseUrl,
+            routes,
+            pagesSkipped: budgetExceeded ? queue.length : 0,
+            budgetExceeded,
+        });
+    }
+}

package/dist/tools/explorers/types.d.ts

@@ -0,0 +1,7 @@
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+import type { RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { RunArtifactsOptions } from '../../harness/run-options.js';
+export interface AppExplorer {
+    explore(baseUrl: string, config: HarnessConfig, artifacts?: RunArtifactsOptions): Promise<RouteInventory>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/explorers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3G"}

package/dist/tools/explorers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/playwright-explorer.js

@@ -1,6 +1,6 @@
 import { launchBrowser } from './browser.js';
 import { AxeBuilder } from '@axe-core/playwright';
-import { createAuthenticatedContext } from './auth.js';
+import { createAuthenticatedContext } from './apply-auth.js';
 import { RouteInventorySchema } from '../schemas/route-inventory.schema.js';
 function crawlHostKey(hostname) {
     return hostname.replace(/^www\./i, '').toLowerCase();