jaku.sh 1.0.0

package/src/core/broken-flow-detector.js

@@ -0,0 +1,207 @@
+import { createFinding } from '../utils/finding.js';
+
+/**
+ * Broken Flow Detector — Detects common broken patterns in web applications.
+ * Analyzes crawl data for dead links, empty states, unresponsive elements, etc.
+ */
+export class BrokenFlowDetector {
+    constructor(logger) {
+        this.logger = logger;
+        this.findings = [];
+    }
+
+    /**
+     * Analyze crawled surfaces for broken flows.
+     */
+    analyze(surfaceInventory) {
+        this._detectDeadLinks(surfaceInventory);
+        this._detectServerErrors(surfaceInventory);
+        this._detectSlowPages(surfaceInventory);
+        this._detectPagesWithErrors(surfaceInventory);
+        this._detectMissingTitles(surfaceInventory);
+        this._detectFormsWithoutSubmit(surfaceInventory);
+
+        this.logger?.info?.(`Broken flow detector found ${this.findings.length} issues`);
+        return this.findings;
+    }
+
+    /**
+     * Detect pages that returned 404 or other client errors.
+     */
+    _detectDeadLinks(inventory) {
+        for (const page of inventory.pages) {
+            if (page.status >= 400 && page.status < 500) {
+                this.findings.push(
+                    createFinding({
+                        module: 'qa',
+                        title: `Dead Link: ${page.status} at ${this._shortUrl(page.url)}`,
+                        severity: page.status === 404 ? 'medium' : 'low',
+                        affected_surface: page.url,
+                        description: `The page returned HTTP ${page.status}. This indicates a broken link or missing resource that users may encounter during navigation.`,
+                        reproduction: [
+                            `1. Navigate to ${page.url}`,
+                            `2. Observe HTTP ${page.status} response`,
+                        ],
+                        remediation: page.status === 404
+                            ? 'Either fix the broken link pointing here or create the missing page/resource. Consider adding a custom 404 page with navigation back to working pages.'
+                            : `Investigate why the page returns ${page.status} and fix the underlying issue.`,
+                    })
+                );
+            }
+        }
+    }
+
+    /**
+     * Detect pages that returned 5xx server errors.
+     */
+    _detectServerErrors(inventory) {
+        for (const page of inventory.pages) {
+            if (typeof page.status === 'number' && page.status >= 500) {
+                this.findings.push(
+                    createFinding({
+                        module: 'qa',
+                        title: `Server Error: ${page.status} at ${this._shortUrl(page.url)}`,
+                        severity: 'high',
+                        affected_surface: page.url,
+                        description: `The page returned HTTP ${page.status} (server error). This indicates a server-side issue that completely blocks the user experience.`,
+                        reproduction: [
+                            `1. Navigate to ${page.url}`,
+                            `2. Observe HTTP ${page.status} server error`,
+                        ],
+                        remediation: 'Check server logs for the root cause. This is a server-side error that needs immediate attention.',
+                    })
+                );
+            } else if (page.status === 'error') {
+                this.findings.push(
+                    createFinding({
+                        module: 'qa',
+                        title: `Page Load Failure: ${this._shortUrl(page.url)}`,
+                        severity: 'high',
+                        affected_surface: page.url,
+                        description: `The page failed to load entirely: ${page.error || 'Unknown error'}. This may indicate a timeout, DNS failure, or crash.`,
+                        reproduction: [
+                            `1. Attempt to navigate to ${page.url}`,
+                            `2. Observe page load failure`,
+                        ],
+                        remediation: 'Investigate the page load failure. Check for timeouts, infinite redirects, or server availability.',
+                    })
+                );
+            }
+        }
+    }
+
+    /**
+     * Detect pages with slow load times.
+     */
+    _detectSlowPages(inventory) {
+        const SLOW_THRESHOLD = 5000; // 5 seconds
+
+        for (const page of inventory.pages) {
+            if (page.loadTime > SLOW_THRESHOLD) {
+                this.findings.push(
+                    createFinding({
+                        module: 'qa',
+                        title: `Slow Page Load: ${(page.loadTime / 1000).toFixed(1)}s at ${this._shortUrl(page.url)}`,
+                        severity: 'low',
+                        affected_surface: page.url,
+                        description: `This page took ${(page.loadTime / 1000).toFixed(1)} seconds to reach network idle. Pages loading over ${SLOW_THRESHOLD / 1000}s significantly hurt user experience and SEO.`,
+                        reproduction: [
+                            `1. Navigate to ${page.url}`,
+                            `2. Measure the time to load (observed: ${page.loadTime}ms)`,
+                        ],
+                        remediation: 'Optimize page load performance. Consider lazy loading, code splitting, image optimization, and caching.',
+                    })
+                );
+            }
+        }
+    }
+
+    /**
+     * Detect pages that had console errors during load.
+     */
+    _detectPagesWithErrors(inventory) {
+        for (const page of inventory.pages) {
+            const errorCount = (page.consoleErrors || []).length;
+            const failedCount = (page.failedRequests || []).length;
+
+            if (errorCount + failedCount > 5) {
+                this.findings.push(
+                    createFinding({
+                        module: 'qa',
+                        title: `High Error Rate: ${errorCount + failedCount} issues on ${this._shortUrl(page.url)}`,
+                        severity: 'medium',
+                        affected_surface: page.url,
+                        description: `This page generated ${errorCount} console errors and ${failedCount} failed network requests during load. A high error rate indicates significant quality issues.`,
+                        reproduction: [
+                            `1. Navigate to ${page.url}`,
+                            `2. Open DevTools console`,
+                            `3. Observe ${errorCount} errors and ${failedCount} failed requests`,
+                        ],
+                        remediation: 'Systematically address console errors and failed requests. Prioritize JavaScript exceptions and critical API failures.',
+                    })
+                );
+            }
+        }
+    }
+
+    /**
+     * Detect pages with missing or empty titles.
+     */
+    _detectMissingTitles(inventory) {
+        for (const page of inventory.pages) {
+            if (typeof page.status !== 'number' || page.status >= 400) continue;
+            if (!page.title || page.title.trim() === '') {
+                this.findings.push(
+                    createFinding({
+                        module: 'qa',
+                        title: `Missing Page Title: ${this._shortUrl(page.url)}`,
+                        severity: 'low',
+                        affected_surface: page.url,
+                        description: 'This page has no <title> tag or it is empty. Page titles are critical for SEO, accessibility, and user orientation.',
+                        reproduction: [
+                            `1. Navigate to ${page.url}`,
+                            `2. Check the browser tab — no title is displayed`,
+                        ],
+                        remediation: 'Add a descriptive <title> tag to the page\'s <head>. Each page should have a unique, descriptive title.',
+                    })
+                );
+            }
+        }
+    }
+
+    /**
+     * Detect forms that have no submit button.
+     */
+    _detectFormsWithoutSubmit(inventory) {
+        for (const form of inventory.forms) {
+            if (!form.hasSubmitButton) {
+                this.findings.push(
+                    createFinding({
+                        module: 'qa',
+                        title: `Form Without Submit Button: ${form.id} on ${this._shortUrl(form.page)}`,
+                        severity: 'low',
+                        affected_surface: form.page,
+                        description: `The form "${form.id}" (action: ${form.action}) has no visible submit button (no <button type="submit"> or <input type="submit">). Users may not know how to submit the form.`,
+                        reproduction: [
+                            `1. Navigate to ${form.page}`,
+                            `2. Locate form "${form.id}"`,
+                            `3. Observe no submit button is present`,
+                        ],
+                        remediation: 'Add a visible submit button to the form. If submission is handled via JavaScript, ensure the interaction is clear to users.',
+                    })
+                );
+            }
+        }
+    }
+
+    _shortUrl(url) {
+        try {
+            const u = new URL(url);
+            return u.pathname === '/' ? u.hostname : u.pathname;
+        } catch {
+            return url;
+        }
+    }
+}
+
+export default BrokenFlowDetector;

package/src/core/browser-manager.js

@@ -0,0 +1,119 @@
+import { chromium } from 'playwright';
+
+/**
+ * BrowserManager — Global Playwright browser lifecycle manager.
+ *
+ * Fixes:
+ *  - Fix 2: Ensures browsers are always closed on process exit, even if agents
+ *    crash mid-execution, preventing zombie Chromium processes on CI runners.
+ *
+ * Usage:
+ *   const browser = await BrowserManager.launch({ headless: true });
+ *   // browser is tracked globally and closed on process.exit
+ */
+export class BrowserManager {
+    static _instances = new Set();
+    static _exitHandlerRegistered = false;
+
+    /**
+     * Launch a new browser, registering it for automatic cleanup on exit.
+     */
+    static async launch(options = {}) {
+        if (!BrowserManager._exitHandlerRegistered) {
+            BrowserManager._registerExitHandlers();
+        }
+
+        const browser = await chromium.launch({ headless: true, ...options });
+        BrowserManager._instances.add(browser);
+
+        // Remove from registry when browser closes normally
+        browser.on('disconnected', () => {
+            BrowserManager._instances.delete(browser);
+        });
+
+        return browser;
+    }
+
+    /**
+     * Wrap a function that uses a browser. Guarantees cleanup.
+     * @param {object} options - Playwright launch options
+     * @param {Function} fn - async (browser) => result
+     */
+    static async withBrowser(options, fn) {
+        const browser = await BrowserManager.launch(options);
+        try {
+            return await fn(browser);
+        } finally {
+            await BrowserManager._closeSafely(browser);
+        }
+    }
+
+    /**
+     * Close all tracked browsers — called automatically on process exit.
+     */
+    static async closeAll() {
+        const closePromises = [...BrowserManager._instances].map(b =>
+            BrowserManager._closeSafely(b)
+        );
+        await Promise.allSettled(closePromises);
+        BrowserManager._instances.clear();
+    }
+
+    static async _closeSafely(browser) {
+        try {
+            if (browser.isConnected()) {
+                await browser.close();
+            }
+        } catch {
+            // Best effort
+        } finally {
+            BrowserManager._instances.delete(browser);
+        }
+    }
+
+    /**
+     * Register exit handlers to clean up zombie browsers.
+     */
+    static _registerExitHandlers() {
+        BrowserManager._exitHandlerRegistered = true;
+
+        const cleanup = async (signal) => {
+            if (BrowserManager._instances.size > 0) {
+                await BrowserManager.closeAll();
+            }
+            // Re-emit after cleanup so the process actually exits
+            if (signal) process.kill(process.pid, signal);
+        };
+
+        // Synchronous exit — use sync-compatible cleanup
+        process.on('exit', () => {
+            // Can't await in 'exit' handler — fire and forget
+            for (const browser of BrowserManager._instances) {
+                try { browser.close(); } catch { /* ignore */ }
+            }
+        });
+
+        // Async-capable signals
+        process.once('SIGINT', async () => {
+            await cleanup('SIGINT');
+        });
+
+        process.once('SIGTERM', async () => {
+            await cleanup('SIGTERM');
+        });
+
+        process.on('uncaughtException', async (err) => {
+            console.error('[JAKU] Uncaught exception — cleaning up browsers:', err.message);
+            await BrowserManager.closeAll();
+            process.exit(1);
+        });
+
+        process.on('unhandledRejection', async (reason) => {
+            console.error('[JAKU] Unhandled rejection — cleaning up browsers:', reason);
+            await BrowserManager.closeAll();
+            process.exit(1);
+        });
+    }
+}
+
+export default BrowserManager;

package/src/core/console-monitor.js

@@ -0,0 +1,111 @@
+import { createFinding } from '../utils/finding.js';
+import { CSRWaiter } from './csr-waiter.js';
+
+/**
+ * Console Monitor — Captures and classifies browser console output.
+ * Hooks into Playwright page events to capture errors, warnings, and failed requests.
+ */
+export class ConsoleMonitor {
+    constructor(logger) {
+        this.logger = logger;
+        this.entries = [];
+        this.findings = [];
+    }
+
+    /**
+     * Analyze console errors and failed requests from crawled surfaces.
+     */
+    analyze(surfaceInventory) {
+        const errorMap = new Map(); // Deduplication
+
+        for (const page of surfaceInventory.pages) {
+            // Process console errors — filter out known CSR/Supabase loading-state noise
+            for (const error of (page.consoleErrors || [])) {
+                // Skip errors that are just loading-state artifacts from Supabase/Clerk/etc.
+                if (!CSRWaiter.isRealError(error.text || error.message || '')) continue;
+
+                const key = `${error.type}:${error.text}`;
+                if (!errorMap.has(key)) {
+                    errorMap.set(key, {
+                        ...error,
+                        pages: [error.url],
+                        count: 1,
+                    });
+                } else {
+                    const existing = errorMap.get(key);
+                    if (!existing.pages.includes(error.url)) {
+                        existing.pages.push(error.url);
+                    }
+                    existing.count++;
+                }
+            }
+
+            // Process failed network requests
+            for (const req of (page.failedRequests || [])) {
+                this.findings.push(
+                    createFinding({
+                        module: 'qa',
+                        title: `Failed Network Request: ${req.method} ${this._truncateUrl(req.url)}`,
+                        severity: 'medium',
+                        affected_surface: req.page,
+                        description: `A network request to ${req.url} failed with error: ${req.failure}. This indicates a broken resource, missing API endpoint, or connectivity issue.`,
+                        reproduction: [
+                            `1. Navigate to ${req.page}`,
+                            `2. Observe the network panel for failed ${req.method} request to ${req.url}`,
+                            `3. Error: ${req.failure}`,
+                        ],
+                        evidence: JSON.stringify(req, null, 2),
+                        remediation: 'Verify the endpoint exists and is accessible. Check for CORS issues, missing routes, or server errors.',
+                    })
+                );
+            }
+        }
+
+        // Convert deduplicated errors to findings
+        for (const [, error] of errorMap) {
+            const severity = error.type === 'exception' ? 'high' : 'medium';
+            this.findings.push(
+                createFinding({
+                    module: 'qa',
+                    title: `Console ${error.type === 'exception' ? 'Exception' : 'Error'}: ${this._truncateText(error.text, 80)}`,
+                    severity,
+                    affected_surface: error.pages.join(', '),
+                    description: `A JavaScript ${error.type} was detected across ${error.count} occurrence(s) on ${error.pages.length} page(s):\n\n${error.text}`,
+                    reproduction: [
+                        `1. Navigate to ${error.pages[0]}`,
+                        `2. Open browser DevTools console`,
+                        `3. Observe the error: ${error.text}`,
+                    ],
+                    evidence: JSON.stringify({
+                        type: error.type,
+                        message: error.text,
+                        pages: error.pages,
+                        occurrences: error.count,
+                    }, null, 2),
+                    remediation: error.type === 'exception'
+                        ? 'This is an uncaught JavaScript exception. Add try/catch blocks or fix the root cause to prevent runtime crashes.'
+                        : 'Investigate and resolve the console error. Even non-critical errors can indicate underlying issues.',
+                })
+            );
+        }
+
+        this.logger?.info?.(`Console monitor found ${this.findings.length} issues`);
+        return this.findings;
+    }
+
+    _truncateText(text, maxLen = 100) {
+        if (!text) return '';
+        return text.length > maxLen ? text.substring(0, maxLen) + '...' : text;
+    }
+
+    _truncateUrl(url) {
+        try {
+            const u = new URL(url);
+            return u.pathname.length > 50 ? u.pathname.substring(0, 50) + '...' : u.pathname;
+        } catch {
+            return url;
+        }
+    }
+}
+
+export default ConsoleMonitor;