@qulib/core 0.4.2 → 0.4.3

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();

package/dist/tools/repo/detect-framework.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module tools/repo/detect-framework
+ * @packageBoundary @qulib/core (candidate: @qulib/analyzer)
+ *
+ * Framework detection runs during the observe phase as part of repo scanning.
+ * It is a pure static analysis operation with no browser or LLM dependency.
+ * Move this to @qulib/analyzer when that package is created.
+ *
+ * // TODO(@qulib/analyzer): When @qulib/analyzer is extracted, this module should move there.
+ * // It is currently embedded in @qulib/core because repo scanning is part of the observe phase.
+ * // The package boundary decision: core = runtime QA analysis, analyzer = static repo intelligence.
+ */
+import { type FrameworkDetectionResult } from '../../schemas/repo-analysis.schema.js';
+export declare function detectFramework(repoPath: string): Promise<FrameworkDetectionResult>;
+//# sourceMappingURL=detect-framework.d.ts.map

package/dist/tools/repo/detect-framework.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-framework.d.ts","sourceRoot":"","sources":["../../../src/tools/repo/detect-framework.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAA4B,KAAK,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AAuBhH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CA4GzF"}

package/dist/tools/repo/detect-framework.js

@@ -0,0 +1,153 @@
+/**
+ * @module tools/repo/detect-framework
+ * @packageBoundary @qulib/core (candidate: @qulib/analyzer)
+ *
+ * Framework detection runs during the observe phase as part of repo scanning.
+ * It is a pure static analysis operation with no browser or LLM dependency.
+ * Move this to @qulib/analyzer when that package is created.
+ *
+ * // TODO(@qulib/analyzer): When @qulib/analyzer is extracted, this module should move there.
+ * // It is currently embedded in @qulib/core because repo scanning is part of the observe phase.
+ * // The package boundary decision: core = runtime QA analysis, analyzer = static repo intelligence.
+ */
+import { access, readFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+import { FrameworkDetectionSchema } from '../../schemas/repo-analysis.schema.js';
+async function fileExists(repoPath, rel) {
+    try {
+        await access(join(repoPath, rel), constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function depNames(pkg) {
+    return new Set([
+        ...Object.keys(pkg.dependencies ?? {}),
+        ...Object.keys(pkg.devDependencies ?? {}),
+    ]);
+}
+export async function detectFramework(repoPath) {
+    const evidence = [];
+    const testFrameworks = new Set();
+    let pkg = {};
+    try {
+        const raw = await readFile(join(repoPath, 'package.json'), 'utf8');
+        pkg = JSON.parse(raw);
+        evidence.push('read package.json');
+    }
+    catch {
+        evidence.push('package.json missing or unreadable');
+    }
+    const deps = depNames(pkg);
+    const has = (n) => deps.has(n);
+    if (has('@playwright/test') || has('playwright')) {
+        testFrameworks.add('playwright');
+        evidence.push('dependency: @playwright/test or playwright');
+    }
+    if (has('cypress')) {
+        testFrameworks.add('cypress-e2e');
+        evidence.push('dependency: cypress');
+    }
+    if (has('jest')) {
+        testFrameworks.add('jest');
+        evidence.push('dependency: jest');
+    }
+    if (has('vitest')) {
+        testFrameworks.add('vitest');
+        evidence.push('dependency: vitest');
+    }
+    if (testFrameworks.size === 0) {
+        testFrameworks.add('other');
+    }
+    const nextCfg = (await fileExists(repoPath, 'next.config.js')) ||
+        (await fileExists(repoPath, 'next.config.mjs')) ||
+        (await fileExists(repoPath, 'next.config.ts'));
+    const nuxtCfg = await fileExists(repoPath, 'nuxt.config.ts');
+    const svelteCfg = await fileExists(repoPath, 'svelte.config.js');
+    const astroCfg = await fileExists(repoPath, 'astro.config.mjs');
+    const remixCfg = await fileExists(repoPath, 'remix.config.js');
+    const viteCfg = await fileExists(repoPath, 'vite.config.ts');
+    if (nextCfg)
+        evidence.push('found next.config.*');
+    if (nuxtCfg)
+        evidence.push('found nuxt.config.ts');
+    if (svelteCfg)
+        evidence.push('found svelte.config.js');
+    if (astroCfg)
+        evidence.push('found astro.config.mjs');
+    if (remixCfg)
+        evidence.push('found remix.config.js');
+    if (viteCfg)
+        evidence.push('found vite.config.ts');
+    const hasAppDir = await fileExists(repoPath, 'app');
+    const hasPagesDir = await fileExists(repoPath, 'pages');
+    if (has('next') && hasAppDir)
+        evidence.push('Next.js app/ directory present');
+    if (has('next') && hasPagesDir)
+        evidence.push('Next.js pages/ directory present');
+    if (has('@remix-run/react') || has('@remix-run/node'))
+        evidence.push('Remix packages in package.json');
+    if (has('nuxt') || has('nuxt3'))
+        evidence.push('Nuxt in package.json');
+    if (has('@sveltejs/kit'))
+        evidence.push('@sveltejs/kit in package.json');
+    if (has('astro'))
+        evidence.push('astro in package.json');
+    if (has('vite') && !has('next'))
+        evidence.push('vite in package.json (non-Next)');
+    let primary = 'unknown';
+    let confidence = 'low';
+    if (has('next')) {
+        if (hasAppDir && (await fileExists(repoPath, join('app', 'layout.tsx')))) {
+            primary = 'nextjs-app-router';
+            confidence = nextCfg || hasAppDir ? 'high' : 'medium';
+        }
+        else if (hasPagesDir) {
+            primary = 'nextjs-pages-router';
+            confidence = nextCfg || hasPagesDir ? 'high' : 'medium';
+        }
+        else {
+            primary = 'nextjs-app-router';
+            confidence = 'medium';
+            evidence.push('next detected without clear app/ vs pages/ layout');
+        }
+    }
+    else if (has('@remix-run/react') || remixCfg) {
+        primary = 'remix';
+        confidence = remixCfg ? 'high' : 'medium';
+    }
+    else if (has('nuxt') || nuxtCfg) {
+        primary = 'nuxt';
+        confidence = nuxtCfg ? 'high' : 'medium';
+    }
+    else if (has('@sveltejs/kit') || svelteCfg) {
+        primary = 'sveltekit';
+        confidence = svelteCfg ? 'high' : 'medium';
+    }
+    else if (has('astro') || astroCfg) {
+        primary = 'astro';
+        confidence = astroCfg ? 'high' : 'medium';
+    }
+    else if (viteCfg && !has('next')) {
+        primary = 'vite';
+        confidence = 'medium';
+    }
+    else if (has('express')) {
+        primary = 'express';
+        confidence = 'medium';
+        evidence.push('express listed in dependencies');
+    }
+    else {
+        /* keep unknown */
+    }
+    const raw = {
+        primary,
+        confidence,
+        evidence,
+        testFrameworks: [...testFrameworks],
+    };
+    return FrameworkDetectionSchema.parse(raw);
+}

package/dist/tools/repo/framework-detector.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module framework-detector
+ * @packageBoundary @qulib/core (candidate: @qulib/analyzer)
+ *
+ * Framework detection runs during the observe phase as part of repo scanning.
+ * It is a pure static analysis operation with no browser or LLM dependency.
+ * Move this to @qulib/analyzer when that package is created.
+ *
+ * // TODO(@qulib/analyzer): When @qulib/analyzer is extracted, this module should move there.
+ * // It is currently embedded in @qulib/core because repo scanning is part of the observe phase.
+ * // The package boundary decision: core = runtime QA analysis, analyzer = static repo intelligence.
+ */
+import { type FrameworkDetectionResult } from '../../schemas/repo-analysis.schema.js';
+export declare function detectFramework(repoPath: string): Promise<FrameworkDetectionResult>;
+//# sourceMappingURL=framework-detector.d.ts.map

package/dist/tools/repo/framework-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-detector.d.ts","sourceRoot":"","sources":["../../../src/tools/repo/framework-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAA4B,KAAK,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AAuBhH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CA4GzF"}