perfgraph 0.1.0

package/dist/collect/session.d.ts

@@ -0,0 +1,58 @@
+/**
+ * CDP session manager.
+ *
+ * Launches a headless Chromium instance via Playwright and establishes a
+ * raw CDP session for sending Chrome DevTools Protocol commands.
+ */
+import { type Browser, type BrowserContext, type Page, type CDPSession, type BrowserServer } from 'playwright';
+/** The result of launching a browser and creating a CDP session */
+export interface BrowserSession {
+    /** The Playwright Browser instance */
+    browser: Browser;
+    /** The BrowserContext (isolated session) */
+    context: BrowserContext;
+    /** The Page that was opened */
+    page: Page;
+    /** Raw CDP session bound to the page */
+    cdp: CDPSession;
+    /** CDP debugging port for connecting external tools (e.g. Lighthouse) */
+    cdpPort?: number;
+    /** Browser server instance (when using launchServer) */
+    browserServer?: BrowserServer;
+}
+/**
+ * Launch a headless Chromium instance, create a new page, and establish a
+ * raw CDP session.
+ *
+ * @param timeoutMs - Timeout for browser launch (default: 30_000)
+ * @returns A BrowserSession with browser, context, page, and CDP session
+ */
+export declare function launchBrowser(timeoutMs?: number): Promise<BrowserSession>;
+/**
+ * Safely close a browser instance.
+ * Logs but does not propagate any errors during cleanup.
+ *
+ * @param browser - The Browser instance to close
+ */
+export declare function closeBrowser(browser: Browser): Promise<void>;
+/**
+ * Launch a headless Chromium instance with an exposed CDP debugging port.
+ *
+ * Unlike the basic `launchBrowser()`, this starts Chrome with
+ * `--remote-debugging-port` so external tools (e.g. Lighthouse) can
+ * connect directly via the Chrome DevTools Protocol without going
+ * through Playwright. Playwright itself still uses its normal pipe.
+ *
+ * @param timeoutMs - Timeout for browser launch (default: 30_000)
+ * @param deviceName - Optional device name for emulation (e.g. "iPhone 13", "Pixel 7")
+ * @returns A BrowserSession with cdpPort, browser, page, and CDP session
+ */
+export declare function launchBrowserServer(timeoutMs?: number, deviceName?: string): Promise<BrowserSession>;
+/**
+ * Safely close a BrowserServer and its underlying Chrome process.
+ * Logs but does not propagate any errors during cleanup.
+ *
+ * @param browserServer - The BrowserServer to close
+ */
+export declare function closeBrowserServer(browserServer: BrowserServer): Promise<void>;
+//# sourceMappingURL=session.d.ts.map

package/dist/collect/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/collect/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAqB,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,IAAI,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAGlI,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,OAAO,EAAE,cAAc,CAAC;IACxB,+BAA+B;IAC/B,IAAI,EAAE,IAAI,CAAC;IACX,wCAAwC;IACxC,GAAG,EAAE,UAAU,CAAC;IAChB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,SAAS,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAqC/E;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlE;AAqBD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,SAAS,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CA2D1G;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAMpF"}

package/dist/collect/session.js

@@ -0,0 +1,162 @@
+/**
+ * CDP session manager.
+ *
+ * Launches a headless Chromium instance via Playwright and establishes a
+ * raw CDP session for sending Chrome DevTools Protocol commands.
+ */
+import { createServer as createTcpServer } from 'net';
+import { chromium, devices } from 'playwright';
+import ow from 'ow';
+/**
+ * Launch a headless Chromium instance, create a new page, and establish a
+ * raw CDP session.
+ *
+ * @param timeoutMs - Timeout for browser launch (default: 30_000)
+ * @returns A BrowserSession with browser, context, page, and CDP session
+ */
+export async function launchBrowser(timeoutMs = 30_000) {
+    ow(timeoutMs, 'timeoutMs', ow.number.positive);
+    const browser = await chromium.launch({
+        headless: true,
+        args: [
+            '--no-sandbox',
+            '--disable-setuid-sandbox',
+            '--disable-dev-shm-usage',
+            '--disable-gpu',
+            '--disable-background-networking',
+        ],
+        timeout: timeoutMs,
+    });
+    try {
+        const context = await browser.newContext({
+            userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36',
+            ignoreHTTPSErrors: false,
+        });
+        const page = await context.newPage();
+        // Set a generous navigation timeout
+        page.setDefaultNavigationTimeout(60_000);
+        page.setDefaultTimeout(60_000);
+        // Establish raw CDP session
+        const cdp = await context.newCDPSession(page);
+        return { browser, context, page, cdp };
+    }
+    catch (error) {
+        // Clean up the browser if context/page creation fails
+        await browser.close().catch(() => { });
+        throw error;
+    }
+}
+/**
+ * Safely close a browser instance.
+ * Logs but does not propagate any errors during cleanup.
+ *
+ * @param browser - The Browser instance to close
+ */
+export async function closeBrowser(browser) {
+    ow(browser, 'browser', ow.object);
+    try {
+        await browser.close();
+    }
+    catch (error) {
+        console.error(`[session] Error closing browser: ${error}`);
+    }
+}
+/**
+ * Find a free TCP port on localhost.
+ * Used to pick a port for Chrome's `--remote-debugging-port` flag.
+ */
+function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = createTcpServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (address && typeof address === 'object') {
+                server.close(() => resolve(address.port));
+            }
+            else {
+                server.close(() => reject(new Error('Could not determine free port')));
+            }
+        });
+    });
+}
+/**
+ * Launch a headless Chromium instance with an exposed CDP debugging port.
+ *
+ * Unlike the basic `launchBrowser()`, this starts Chrome with
+ * `--remote-debugging-port` so external tools (e.g. Lighthouse) can
+ * connect directly via the Chrome DevTools Protocol without going
+ * through Playwright. Playwright itself still uses its normal pipe.
+ *
+ * @param timeoutMs - Timeout for browser launch (default: 30_000)
+ * @param deviceName - Optional device name for emulation (e.g. "iPhone 13", "Pixel 7")
+ * @returns A BrowserSession with cdpPort, browser, page, and CDP session
+ */
+export async function launchBrowserServer(timeoutMs = 30_000, deviceName) {
+    ow(timeoutMs, 'timeoutMs', ow.number.positive);
+    // Pick a free port for Chrome's CDP debugging server
+    const cdpPort = await findFreePort();
+    // Launch Chrome with --remote-debugging-port so Lighthouse can connect
+    // via raw HTTP CDP (not just Playwright's internal pipe).
+    const browser = await chromium.launch({
+        headless: true,
+        args: [
+            '--no-sandbox',
+            '--disable-setuid-sandbox',
+            '--disable-dev-shm-usage',
+            '--disable-gpu',
+            '--disable-background-networking',
+            `--remote-debugging-port=${cdpPort}`,
+        ],
+        timeout: timeoutMs,
+    });
+    try {
+        let context;
+        if (deviceName && deviceName.length > 0) {
+            const device = devices[deviceName];
+            if (device) {
+                context = await browser.newContext({
+                    ...device,
+                    ignoreHTTPSErrors: false,
+                });
+            }
+            else {
+                console.error(`[session] Unknown device "${deviceName}", falling back to desktop`);
+                context = await browser.newContext({
+                    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36',
+                    ignoreHTTPSErrors: false,
+                });
+            }
+        }
+        else {
+            context = await browser.newContext({
+                userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36',
+                ignoreHTTPSErrors: false,
+            });
+        }
+        const page = await context.newPage();
+        page.setDefaultNavigationTimeout(60_000);
+        page.setDefaultTimeout(60_000);
+        const cdp = await context.newCDPSession(page);
+        return { browser, context, page, cdp, cdpPort };
+    }
+    catch (error) {
+        await browser.close().catch(() => { });
+        throw error;
+    }
+}
+/**
+ * Safely close a BrowserServer and its underlying Chrome process.
+ * Logs but does not propagate any errors during cleanup.
+ *
+ * @param browserServer - The BrowserServer to close
+ */
+export async function closeBrowserServer(browserServer) {
+    try {
+        await browserServer.close();
+    }
+    catch (error) {
+        console.error(`[session] Error closing browser server: ${error}`);
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/collect/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/collect/session.ts"],"names":[],"mappings":"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"}

package/dist/collect/trace.d.ts

@@ -0,0 +1,40 @@
+/**
+ * TraceCollector — captures Chrome trace events via the Tracing CDP domain.
+ *
+ * Sends `Tracing.start` with a comprehensive set of categories, buffers
+ * events delivered via `Tracing.dataCollected`, and on `stop()` sends
+ * `Tracing.end` and waits for `Tracing.tracingComplete`.
+ *
+ * Also monitors `Tracing.bufferUsage` and emits warnings when the ring
+ * buffer exceeds safe thresholds. Buffer health analysis is delegated
+ * to the standalone `buffer-monitor` module.
+ */
+import { type CDPSession } from 'playwright';
+import type { Collector, CollectorResult } from './types.js';
+import type { TraceRawData, BufferUsageSample } from './types.js';
+import type { CollectorRunOptions } from '../shared/types.js';
+export declare class TraceCollector implements Collector {
+    readonly name = "trace";
+    private session;
+    private events;
+    private dataCollectedCount;
+    private bufferUsageSamples;
+    private tracingDone;
+    private resolveTracingComplete;
+    private tracingCompletePromise;
+    constructor();
+    /**
+     * Start tracing via the CDP Tracing domain.
+     * Registers event listeners for data collection, completion, and buffer usage.
+     */
+    start(session: CDPSession, _options?: CollectorRunOptions): Promise<void>;
+    /**
+     * Stop tracing, wait for completion, and return collected trace data.
+     *
+     * @returns CollectorResult with TraceRawData on success
+     */
+    stop(): Promise<CollectorResult<TraceRawData>>;
+    /** Return collected buffer usage samples (useful for tests and monitoring) */
+    getBufferUsageSamples(): BufferUsageSample[];
+}
+//# sourceMappingURL=trace.d.ts.map

package/dist/collect/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/collect/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAc,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAkB9D,qBAAa,cAAe,YAAW,SAAS;IAC9C,QAAQ,CAAC,IAAI,WAAW;IAExB,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,kBAAkB,CAA2B;IACrD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,sBAAsB,CAAc;IAC5C,OAAO,CAAC,sBAAsB,CAAgB;;IAQ9C;;;OAGG;IACG,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyC/E;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IAwCpD,8EAA8E;IAC9E,qBAAqB,IAAI,iBAAiB,EAAE;CAG7C"}

package/dist/collect/trace.js

@@ -0,0 +1,127 @@
+/**
+ * TraceCollector — captures Chrome trace events via the Tracing CDP domain.
+ *
+ * Sends `Tracing.start` with a comprehensive set of categories, buffers
+ * events delivered via `Tracing.dataCollected`, and on `stop()` sends
+ * `Tracing.end` and waits for `Tracing.tracingComplete`.
+ *
+ * Also monitors `Tracing.bufferUsage` and emits warnings when the ring
+ * buffer exceeds safe thresholds. Buffer health analysis is delegated
+ * to the standalone `buffer-monitor` module.
+ */
+import {} from 'playwright';
+import { checkBufferHealth, validateTraceCompleteness } from './buffer-monitor.js';
+/** Categories requested for tracing */
+const TRACE_CATEGORIES = [
+    'devtools.timeline',
+    'disabled-by-default-devtools.timeline',
+    'disabled-by-default-devtools.timeline.frame',
+    'blink.user_timing',
+    'loading',
+    'blink',
+    'cc',
+    'gpu',
+    'v8',
+    'disabled-by-default-v8.cpu_profiler',
+    'disabled-by-default-v8.compile',
+];
+export class TraceCollector {
+    name = 'trace';
+    session = null;
+    events = [];
+    dataCollectedCount = 0;
+    bufferUsageSamples = [];
+    tracingDone = false;
+    resolveTracingComplete;
+    tracingCompletePromise;
+    constructor() {
+        this.tracingCompletePromise = new Promise((resolve) => {
+            this.resolveTracingComplete = resolve;
+        });
+    }
+    /**
+     * Start tracing via the CDP Tracing domain.
+     * Registers event listeners for data collection, completion, and buffer usage.
+     */
+    async start(session, _options) {
+        this.session = session;
+        this.events = [];
+        this.dataCollectedCount = 0;
+        this.bufferUsageSamples = [];
+        this.tracingDone = false;
+        this.tracingCompletePromise = new Promise((resolve) => {
+            this.resolveTracingComplete = resolve;
+        });
+        // Listen for batched trace events
+        session.on('Tracing.dataCollected', (event) => {
+            if (Array.isArray(event.value)) {
+                this.events.push(...event.value);
+                this.dataCollectedCount++;
+            }
+        });
+        // Listen for tracing completion
+        session.on('Tracing.tracingComplete', () => {
+            this.tracingDone = true;
+            this.resolveTracingComplete();
+        });
+        // Monitor buffer usage for overflow detection
+        session.on('Tracing.bufferUsage', (event) => {
+            if (event.value !== undefined) {
+                this.bufferUsageSamples.push({
+                    value: event.value,
+                    timestamp: Date.now(),
+                });
+            }
+        });
+        // Send Tracing.start — categories is a comma-separated string per CDP spec
+        await session.send('Tracing.start', {
+            categories: [...TRACE_CATEGORIES].join(','),
+            transferMode: 'ReportEvents',
+        });
+    }
+    /**
+     * Stop tracing, wait for completion, and return collected trace data.
+     *
+     * @returns CollectorResult with TraceRawData on success
+     */
+    async stop() {
+        if (!this.session) {
+            return { ok: false, error: 'TraceCollector: session not initialized' };
+        }
+        try {
+            // Send Tracing.end and wait for TracingComplete
+            await this.session.send('Tracing.end');
+            await this.tracingCompletePromise;
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: `TraceCollector: failed to stop tracing — ${String(error)}`,
+            };
+        }
+        // Analyze buffer health via standalone module
+        const warnings = [];
+        warnings.push(...checkBufferHealth(this.bufferUsageSamples));
+        // Run completeness validation via standalone module
+        const eventNames = this.events.map((e) => e.name);
+        warnings.push(...validateTraceCompleteness(eventNames));
+        const categories = [...TRACE_CATEGORIES];
+        return {
+            ok: true,
+            data: {
+                events: this.events,
+                metadata: {
+                    categories,
+                    totalEvents: this.events.length,
+                    dataCollectedCount: this.dataCollectedCount,
+                },
+                warnings,
+            },
+        };
+    }
+    /** Return collected buffer usage samples (useful for tests and monitoring) */
+    getBufferUsageSamples() {
+        return [...this.bufferUsageSamples];
+    }
+}
+//# sourceMappingURL=trace.js.map

package/dist/collect/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/collect/trace.ts"],"names":[],"mappings":"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"}