perfgraph 0.1.0

package/dist/cli/run.js

@@ -0,0 +1,243 @@
+/**
+ * `run` subcommand — full pipeline in one command.
+ *
+ * Chains collect → normalize → extract → analyze → report,
+ * writing intermediate artifacts to a temp directory and
+ * outputting only the final Report JSON.
+ *
+ * Usage:
+ *   perfgraph run --url <url> [--output <dir>] [--runs <n>] [--pretty]
+ */
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { writeManifest } from '../output/manifest.js';
+import { convertToon } from '../output/toon.js';
+import { run } from '../collect/orchestrator.js';
+import { loadRunDir } from '../shared/fs-utils.js';
+import { normalize } from '../normalize/index.js';
+import { extract } from '../extract/index.js';
+import { buildInsights } from '../distill/insights.js';
+import { buildNetworkSummary, buildLighthouseSummary, buildCoverageSummary, } from '../distill/summaries.js';
+import { buildCausalGraph } from '../causal/index.js';
+import { buildReport } from '../report/index.js';
+import { buildReportMarkdown } from '../report/markdown.js';
+import { DEFAULT_RUN_OPTIONS } from '../shared/types.js';
+/** Help text */
+const RUN_HELP = `
+RUN OPTIONS
+  --url <url>           Target URL to analyze (required)
+  --output <dir>        Output directory (default: ./perfgraph-output)
+  --runs <n>            Number of collection runs (default: 1)
+  --pretty              Pretty-print final report JSON
+  --device <name>       Device name for mobile emulation (e.g. "iPhone 13")
+  --no-lighthouse       Skip Lighthouse collection
+  --no-coverage         Skip JS/CSS coverage collection
+  --no-console          Skip console log collection
+  --no-dom              Skip DOM snapshot collection
+  --help, -h            Show this help message
+
+EXAMPLES
+  perfgraph run --url https://example.com
+  perfgraph run --url https://example.com --pretty
+  perfgraph run --url https://example.com --pretty --runs 3
+`;
+/**
+ * Execute the full pipeline.
+ *
+ * @param url - Target URL
+ * @param output - Base output directory for collection + final report
+ * @param runs - Number of collection runs
+ * @param pretty - Pretty-print final report
+ * @param flags - boolean flags for skipping collectors
+ * @param mobile - Device name for mobile emulation (e.g. "iPhone 13")
+ * @returns RunResult
+ */
+export async function runRun(url, output, runs, pretty, flags, mobile) {
+    // -----------------------------------------------------------------------
+    // 1. Collect
+    // -----------------------------------------------------------------------
+    const options = {
+        ...DEFAULT_RUN_OPTIONS,
+        url,
+        output,
+        runs,
+        noLighthouse: flags.noLighthouse ?? false,
+        noCoverage: flags.noCoverage ?? false,
+        noConsole: flags.noConsole ?? false,
+        noDom: flags.noDom ?? false,
+        mobile,
+    };
+    const collectResults = await run(url, options);
+    const successRuns = collectResults.filter((r) => r.success);
+    if (successRuns.length === 0) {
+        console.error('Error: All collection runs failed');
+        return null;
+    }
+    // Use the first successful run's output dir
+    const runDir = resolve(successRuns[0].outputDir);
+    // File paths for intermediate artifacts (set during pipeline)
+    let irFile = '';
+    let featuresFile = '';
+    let insightsFile = '';
+    let graphFile = '';
+    // -----------------------------------------------------------------------
+    // 2. Normalize
+    // -----------------------------------------------------------------------
+    const raw = loadRunDir(runDir);
+    let ir;
+    try {
+        ir = normalize(raw);
+    }
+    catch (err) {
+        console.error(`Error: Normalization failed: ${err.message}`);
+        return null;
+    }
+    // Write intermediate representation
+    irFile = resolve(runDir, 'ir.json');
+    writeFileSync(irFile, JSON.stringify(ir, null, 2), 'utf-8');
+    // Write compact summaries of raw data files
+    if (raw.network) {
+        const networkSummary = buildNetworkSummary(raw.network);
+        writeFileSync(resolve(runDir, 'network-summary.toon'), await convertToon(networkSummary), 'utf-8');
+    }
+    if (raw.lighthouse) {
+        const lighthouseSummary = buildLighthouseSummary(raw.lighthouse);
+        writeFileSync(resolve(runDir, 'lighthouse-summary.toon'), await convertToon(lighthouseSummary), 'utf-8');
+    }
+    if (raw.coverage) {
+        const coverageSummary = buildCoverageSummary(raw.coverage);
+        writeFileSync(resolve(runDir, 'coverage-summary.toon'), await convertToon(coverageSummary), 'utf-8');
+    }
+    // -----------------------------------------------------------------------
+    // 3. Extract
+    // -----------------------------------------------------------------------
+    const features = extract(ir);
+    // Write extracted features
+    featuresFile = resolve(runDir, 'features.toon');
+    writeFileSync(featuresFile, await convertToon(features), 'utf-8');
+    // Build and write insights.toon
+    const insights = buildInsights(features, raw.lighthouse ?? {});
+    insightsFile = resolve(runDir, 'insights.toon');
+    writeFileSync(insightsFile, await convertToon(insights), 'utf-8');
+    // -----------------------------------------------------------------------
+    // 4. Analyze (causal graph)
+    // -----------------------------------------------------------------------
+    const graph = buildCausalGraph(features);
+    // Write causal graph
+    graphFile = resolve(runDir, 'graph.toon');
+    writeFileSync(graphFile, await convertToon(graph), 'utf-8');
+    // -----------------------------------------------------------------------
+    // 5. Report
+    // -----------------------------------------------------------------------
+    const report = buildReport(graph, features);
+    // Write report as .toon (AI consumption) + keep JSON for stdout
+    const reportFile = resolve(runDir, 'report.toon');
+    writeFileSync(reportFile, await convertToon(report), 'utf-8');
+    const reportJson = JSON.stringify(report, null, pretty ? 2 : 0);
+    // Write human-readable markdown report
+    const reportMarkdown = buildReportMarkdown(report, insights);
+    const reportMdFile = resolve(runDir, 'report.md');
+    writeFileSync(reportMdFile, reportMarkdown, 'utf-8');
+    // Write manifest
+    await writeManifest(runDir);
+    // Also print to stdout
+    console.log(reportJson);
+    console.error(`Report written to ${reportFile}`);
+    return {
+        success: true,
+        reportFile,
+        outputDir: runDir,
+        files: {
+            ir: irFile,
+            features: featuresFile,
+            graph: graphFile,
+            report: reportFile,
+            insights: insightsFile,
+        },
+    };
+}
+/**
+ * Parse CLI arguments for the run command and execute.
+ */
+export async function runRunFromArgs(args) {
+    let url;
+    let output = DEFAULT_RUN_OPTIONS.output;
+    let runs = DEFAULT_RUN_OPTIONS.runs;
+    let pretty = false;
+    let mobile;
+    const flags = {
+        noLighthouse: false,
+        noCoverage: false,
+        noConsole: false,
+        noDom: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '--url':
+                if (i + 1 >= args.length) {
+                    console.error('Error: --url requires a value');
+                    return null;
+                }
+                url = args[++i];
+                break;
+            case '--output':
+                if (i + 1 >= args.length) {
+                    console.error('Error: --output requires a value');
+                    return null;
+                }
+                output = args[++i];
+                break;
+            case '--runs':
+                if (i + 1 >= args.length) {
+                    console.error('Error: --runs requires a value');
+                    return null;
+                }
+                runs = parseInt(args[++i], 10);
+                if (isNaN(runs) || runs < 1) {
+                    console.error('Error: --runs must be a positive integer');
+                    return null;
+                }
+                break;
+            case '--pretty':
+                pretty = true;
+                break;
+            case '--no-lighthouse':
+                flags.noLighthouse = true;
+                break;
+            case '--no-coverage':
+                flags.noCoverage = true;
+                break;
+            case '--no-console':
+                flags.noConsole = true;
+                break;
+            case '--no-dom':
+                flags.noDom = true;
+                break;
+            case '--device':
+                if (i + 1 >= args.length) {
+                    console.error('Error: --device requires a value');
+                    return null;
+                }
+                mobile = args[++i];
+                break;
+            case '--help':
+            case '-h':
+                console.log(RUN_HELP);
+                return null;
+            default:
+                if (arg.startsWith('--')) {
+                    console.error(`Error: Unknown flag "${arg}"`);
+                    return null;
+                }
+                break;
+        }
+    }
+    if (!url) {
+        console.error('Error: --url is required');
+        console.error('Usage: perfgraph run --url <url> [--output <dir>] [--runs <n>] [--pretty]');
+        return null;
+    }
+    return runRun(url, output, runs, pretty, flags, mobile);
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/run.js.map

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

package/dist/collect/buffer-monitor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * buffer-monitor — standalone trace buffer health analysis.
+ *
+ * Extracted from TraceCollector so that buffer health checks can be tested
+ * and reused independently of the CDP session lifecycle.
+ *
+ * @module
+ */
+import type { BufferUsageSample } from './types.js';
+/**
+ * Analyse collected buffer-usage samples and return human-readable warnings
+ * when the ring buffer exceeded safe thresholds.
+ *
+ * @param samples - Array of buffer usage samples from `Tracing.bufferUsage`
+ * @returns Warning strings (empty array = buffer health OK)
+ */
+export declare function checkBufferHealth(samples: BufferUsageSample[]): string[];
+/**
+ * Validate trace completeness by checking for expected critical event names.
+ *
+ * @param eventNames - Set or array of event name strings present in a trace
+ * @returns Warning strings for each missing critical event type
+ */
+export declare function validateTraceCompleteness(eventNames: string[] | Set<string>): string[];
+//# sourceMappingURL=buffer-monitor.d.ts.map

package/dist/collect/buffer-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer-monitor.d.ts","sourceRoot":"","sources":["../../src/collect/buffer-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAwBpD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAqBxE;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAmBtF"}

package/dist/collect/buffer-monitor.js

@@ -0,0 +1,69 @@
+/**
+ * buffer-monitor — standalone trace buffer health analysis.
+ *
+ * Extracted from TraceCollector so that buffer health checks can be tested
+ * and reused independently of the CDP session lifecycle.
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Warnings are emitted when peak usage exceeds this fraction (80%) */
+const WARN_THRESHOLD = 0.8;
+/** Critical warnings are emitted when peak usage exceeds this fraction (95%) */
+const CRITICAL_THRESHOLD = 0.95;
+/** Event names that should typically appear in a complete trace */
+const CRITICAL_TRACE_EVENTS = [
+    'navigationStart',
+    'firstContentfulPaint',
+    'firstPaint',
+    'LargestContentfulPaint',
+];
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Analyse collected buffer-usage samples and return human-readable warnings
+ * when the ring buffer exceeded safe thresholds.
+ *
+ * @param samples - Array of buffer usage samples from `Tracing.bufferUsage`
+ * @returns Warning strings (empty array = buffer health OK)
+ */
+export function checkBufferHealth(samples) {
+    const warnings = [];
+    if (samples.length === 0) {
+        return warnings;
+    }
+    const peakUsage = Math.max(...samples.map((s) => s.value));
+    if (peakUsage >= CRITICAL_THRESHOLD) {
+        warnings.push(`Trace buffer usage reached ${Math.round(peakUsage * 100)}% — data is very likely incomplete. ` +
+            'Consider reducing trace categories or increasing the buffer size.');
+    }
+    else if (peakUsage > WARN_THRESHOLD) {
+        warnings.push(`Trace buffer usage reached ${Math.round(peakUsage * 100)}% — data may be incomplete.`);
+    }
+    return warnings;
+}
+/**
+ * Validate trace completeness by checking for expected critical event names.
+ *
+ * @param eventNames - Set or array of event name strings present in a trace
+ * @returns Warning strings for each missing critical event type
+ */
+export function validateTraceCompleteness(eventNames) {
+    const warnings = [];
+    const present = eventNames instanceof Set ? eventNames : new Set(eventNames);
+    const missing = [];
+    for (const eventName of CRITICAL_TRACE_EVENTS) {
+        if (!present.has(eventName)) {
+            missing.push(eventName);
+        }
+    }
+    if (missing.length > 0) {
+        warnings.push(`Trace may be incomplete — missing expected events: ${missing.join(', ')}. ` +
+            'This may be normal for early-page-load traces.');
+    }
+    return warnings;
+}
+//# sourceMappingURL=buffer-monitor.js.map

package/dist/collect/buffer-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer-monitor.js","sourceRoot":"","sources":["../../src/collect/buffer-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,uEAAuE;AACvE,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,gFAAgF;AAChF,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,mEAAmE;AACnE,MAAM,qBAAqB,GAAG;IAC5B,iBAAiB;IACjB,sBAAsB;IACtB,YAAY;IACZ,wBAAwB;CAChB,CAAC;AAEX,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA4B;IAC5D,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAE3D,IAAI,SAAS,IAAI,kBAAkB,EAAE,CAAC;QACpC,QAAQ,CAAC,IAAI,CACX,8BAA8B,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC,sCAAsC;YAC7F,mEAAmE,CACtE,CAAC;IACJ,CAAC;SAAM,IAAI,SAAS,GAAG,cAAc,EAAE,CAAC;QACtC,QAAQ,CAAC,IAAI,CACX,8BAA8B,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC,6BAA6B,CACvF,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,UAAkC;IAC1E,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,OAAO,GAAG,UAAU,YAAY,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IAC7E,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,SAAS,IAAI,qBAAqB,EAAE,CAAC;QAC9C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,QAAQ,CAAC,IAAI,CACX,sDAAsD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC1E,gDAAgD,CACnD,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/collect/console.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ConsoleCollector — captures console API calls from the page via CDP.
+ *
+ * Listens for Runtime.consoleAPICalled events and records each entry
+ * with its type, arguments, timestamp, and optional stack trace.
+ * Groups entries by severity for quick analysis.
+ */
+import { type CDPSession } from 'playwright';
+import type { Collector, CollectorResult, ConsoleRawData } from './types.js';
+import type { CollectorRunOptions } from '../shared/types.js';
+export declare class ConsoleCollector implements Collector {
+    readonly name = "console";
+    private session;
+    private entries;
+    /**
+     * Start collecting console API calls.
+     * Enables Runtime domain and subscribes to consoleAPICalled events.
+     */
+    start(session: CDPSession, _options?: CollectorRunOptions): Promise<void>;
+    /**
+     * Stop collecting and return console data with severity counts.
+     */
+    stop(): Promise<CollectorResult<ConsoleRawData>>;
+}
+//# sourceMappingURL=console.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/collect/console.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAgB,MAAM,YAAY,CAAC;AAC3F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,qBAAa,gBAAiB,YAAW,SAAS;IAChD,QAAQ,CAAC,IAAI,aAAa;IAE1B,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,OAAO,CAAiC;IAEhD;;;OAGG;IACG,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoC/E;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;CA4BvD"}

package/dist/collect/console.js

@@ -0,0 +1,82 @@
+/**
+ * ConsoleCollector — captures console API calls from the page via CDP.
+ *
+ * Listens for Runtime.consoleAPICalled events and records each entry
+ * with its type, arguments, timestamp, and optional stack trace.
+ * Groups entries by severity for quick analysis.
+ */
+import {} from 'playwright';
+export class ConsoleCollector {
+    name = 'console';
+    session = null;
+    entries = [];
+    /**
+     * Start collecting console API calls.
+     * Enables Runtime domain and subscribes to consoleAPICalled events.
+     */
+    async start(session, _options) {
+        this.session = session;
+        this.entries = [];
+        // Ensure Runtime domain is enabled for console API events
+        await session.send('Runtime.enable');
+        // Capture every console API call
+        session.on('Runtime.consoleAPICalled', (event) => {
+            // Serialise arguments: prefer value, fall back to description, then type hint
+            const args = (event.args ?? []).map((a) => a.value ?? a.description ?? `<${a.type}>`);
+            const entry = {
+                // CDP timestamp is in seconds; convert to milliseconds
+                timestamp: event.timestamp * 1000,
+                type: event.type,
+                args,
+                stackTrace: event.stackTrace?.callFrames?.map((f) => ({
+                    url: f.url,
+                    lineNumber: f.lineNumber,
+                    columnNumber: f.columnNumber,
+                    functionName: f.functionName,
+                })),
+            };
+            this.entries.push(entry);
+        });
+    }
+    /**
+     * Stop collecting and return console data with severity counts.
+     */
+    async stop() {
+        if (!this.session) {
+            return { ok: false, error: 'ConsoleCollector: session not initialised' };
+        }
+        // Compute severity counts
+        const counts = { log: 0, warn: 0, error: 0, info: 0, debug: 0, other: 0 };
+        for (const entry of this.entries) {
+            switch (entry.type) {
+                case 'log':
+                    counts.log++;
+                    break;
+                case 'warn':
+                    counts.warn++;
+                    break;
+                case 'error':
+                    counts.error++;
+                    break;
+                case 'info':
+                    counts.info++;
+                    break;
+                case 'debug':
+                    counts.debug++;
+                    break;
+                default:
+                    counts.other++;
+                    break;
+            }
+        }
+        return {
+            ok: true,
+            data: {
+                entries: this.entries,
+                counts,
+                warnings: [],
+            },
+        };
+    }
+}
+//# sourceMappingURL=console.js.map

package/dist/collect/console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.js","sourceRoot":"","sources":["../../src/collect/console.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAmB,MAAM,YAAY,CAAC;AAI7C,MAAM,OAAO,gBAAgB;IAClB,IAAI,GAAG,SAAS,CAAC;IAElB,OAAO,GAAsB,IAAI,CAAC;IAClC,OAAO,GAA8B,EAAE,CAAC;IAEhD;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,OAAmB,EAAE,QAA8B;QAC7D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAElB,0DAA0D;QAC1D,MAAM,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAErC,iCAAiC;QACjC,OAAO,CAAC,EAAE,CAAC,0BAA0B,EAAE,CAAC,KAKvC,EAAE,EAAE;YACH,8EAA8E;YAC9E,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CACjC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,IAAI,GAAG,CACjD,CAAC;YAEF,MAAM,KAAK,GAAsC;gBAC/C,uDAAuD;gBACvD,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,IAAI;gBACjC,IAAI,EAAE,KAAK,CAAC,IAAiD;gBAC7D,IAAI;gBACJ,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACpD,GAAG,EAAE,CAAC,CAAC,GAAG;oBACV,UAAU,EAAE,CAAC,CAAC,UAAU;oBACxB,YAAY,EAAE,CAAC,CAAC,YAAY;oBAC5B,YAAY,EAAE,CAAC,CAAC,YAAY;iBAC7B,CAAC,CAAC;aACJ,CAAC;YAEF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,2CAA2C,EAAE,CAAC;QAC3E,CAAC;QAED,0BAA0B;QAC1B,MAAM,MAAM,GAA6B,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAEpG,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;gBACnB,KAAK,KAAK;oBAAI,MAAM,CAAC,GAAG,EAAE,CAAC;oBAAG,MAAM;gBACpC,KAAK,MAAM;oBAAG,MAAM,CAAC,IAAI,EAAE,CAAC;oBAAE,MAAM;gBACpC,KAAK,OAAO;oBAAE,MAAM,CAAC,KAAK,EAAE,CAAC;oBAAC,MAAM;gBACpC,KAAK,MAAM;oBAAG,MAAM,CAAC,IAAI,EAAE,CAAC;oBAAE,MAAM;gBACpC,KAAK,OAAO;oBAAE,MAAM,CAAC,KAAK,EAAE,CAAC;oBAAC,MAAM;gBACpC;oBAAc,MAAM,CAAC,KAAK,EAAE,CAAC;oBAAC,MAAM;YACtC,CAAC;QACH,CAAC;QAED,OAAO;YACL,EAAE,EAAE,IAAI;YACR,IAAI,EAAE;gBACJ,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,MAAM;gBACN,QAAQ,EAAE,EAAE;aACb;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/collect/coverage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * CoverageCollector — captures JavaScript and CSS code coverage via CDP.
+ *
+ * Uses Profiler.startPreciseCoverage for JS and CSS.startRuleUsageTracking
+ * for stylesheets. Both are started pre-navigation and stopped post-navigation
+ * to capture coverage data for the full page lifecycle.
+ */
+import { type CDPSession } from 'playwright';
+import type { Collector, CollectorResult, CoverageRawData } from './types.js';
+import type { CollectorRunOptions } from '../shared/types.js';
+export declare class CoverageCollector implements Collector {
+    readonly name = "coverage";
+    private session;
+    /**
+     * Start collecting coverage data.
+     * Enables Profiler and CSS domains, then starts precise JS coverage
+     * and CSS rule usage tracking.
+     */
+    start(session: CDPSession, _options?: CollectorRunOptions): Promise<void>;
+    /**
+     * Stop collecting and return coverage data.
+     * Takes precise JS coverage + CSS rule usage, then stops both trackers.
+     */
+    stop(): Promise<CollectorResult<CoverageRawData>>;
+}
+//# sourceMappingURL=coverage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/collect/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAiC,MAAM,YAAY,CAAC;AAC7G,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,qBAAa,iBAAkB,YAAW,SAAS;IACjD,QAAQ,CAAC,IAAI,cAAc;IAE3B,OAAO,CAAC,OAAO,CAA2B;IAE1C;;;;OAIG;IACG,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB/E;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC;CAiFxD"}

package/dist/collect/coverage.js

@@ -0,0 +1,99 @@
+/**
+ * CoverageCollector — captures JavaScript and CSS code coverage via CDP.
+ *
+ * Uses Profiler.startPreciseCoverage for JS and CSS.startRuleUsageTracking
+ * for stylesheets. Both are started pre-navigation and stopped post-navigation
+ * to capture coverage data for the full page lifecycle.
+ */
+import {} from 'playwright';
+export class CoverageCollector {
+    name = 'coverage';
+    session = null;
+    /**
+     * Start collecting coverage data.
+     * Enables Profiler and CSS domains, then starts precise JS coverage
+     * and CSS rule usage tracking.
+     */
+    async start(session, _options) {
+        this.session = session;
+        // Enable required domains (CSS.enable requires DOM.enable first)
+        await session.send('DOM.enable');
+        await session.send('Profiler.enable');
+        await session.send('CSS.enable');
+        // Start precise JS coverage (detailed = true gives per-byte ranges)
+        await session.send('Profiler.startPreciseCoverage', {
+            callCount: false,
+            detailed: true,
+        });
+        // Start CSS rule usage tracking
+        await session.send('CSS.startRuleUsageTracking');
+    }
+    /**
+     * Stop collecting and return coverage data.
+     * Takes precise JS coverage + CSS rule usage, then stops both trackers.
+     */
+    async stop() {
+        if (!this.session) {
+            return { ok: false, error: 'CoverageCollector: session not initialised' };
+        }
+        const warnings = [];
+        let js = [];
+        let css = [];
+        // --- Collect JS coverage ---
+        try {
+            const jsResult = await this.session.send('Profiler.takePreciseCoverage');
+            js = (jsResult.result ?? []).map((entry) => ({
+                scriptId: entry.scriptId,
+                url: entry.url,
+                functions: entry.functions.map((f) => ({
+                    functionName: f.functionName,
+                    ranges: f.ranges.map((r) => ({
+                        startOffset: r.startOffset,
+                        endOffset: r.endOffset,
+                        count: r.count,
+                    })),
+                    isBlockCoverage: f.isBlockCoverage,
+                })),
+            }));
+        }
+        catch (error) {
+            warnings.push(`Failed to collect JS coverage: ${String(error)}`);
+        }
+        // --- Collect CSS coverage ---
+        try {
+            const cssResult = await this.session.send('CSS.stopRuleUsageTracking');
+            // CSS rule usage entries have styleSheetId + ranges but not the URL
+            // directly at the rule level — group them by styleSheetId
+            const cssBySheet = new Map();
+            const rawEntries = cssResult.ruleUsage ?? [];
+            for (const entry of rawEntries) {
+                let sheet = cssBySheet.get(entry.styleSheetId);
+                if (!sheet) {
+                    sheet = { styleSheetId: entry.styleSheetId, url: '', ranges: [] };
+                    cssBySheet.set(entry.styleSheetId, sheet);
+                }
+                sheet.ranges.push({
+                    startOffset: entry.startOffset,
+                    endOffset: entry.endOffset,
+                    count: entry.used ? 1 : 0,
+                });
+            }
+            css = [...cssBySheet.values()];
+        }
+        catch (error) {
+            warnings.push(`Failed to collect CSS coverage: ${String(error)}`);
+        }
+        // --- Clean up JS profiler ---
+        try {
+            await this.session.send('Profiler.stopPreciseCoverage');
+        }
+        catch {
+            // Non-critical cleanup
+        }
+        return {
+            ok: true,
+            data: { js, css, warnings },
+        };
+    }
+}
+//# sourceMappingURL=coverage.js.map

package/dist/collect/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/collect/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAmB,MAAM,YAAY,CAAC;AAI7C,MAAM,OAAO,iBAAiB;IACnB,IAAI,GAAG,UAAU,CAAC;IAEnB,OAAO,GAAsB,IAAI,CAAC;IAE1C;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,OAAmB,EAAE,QAA8B;QAC7D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEvB,iEAAiE;QACjE,MAAM,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACjC,MAAM,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QACtC,MAAM,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAEjC,oEAAoE;QACpE,MAAM,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE;YAClD,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;QAEH,gCAAgC;QAChC,MAAM,OAAO,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;IACnD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,4CAA4C,EAAE,CAAC;QAC5E,CAAC;QAED,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,IAAI,EAAE,GAA0B,EAAE,CAAC;QACnC,IAAI,GAAG,GAA2B,EAAE,CAAC;QAErC,8BAA8B;QAC9B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;YACzE,EAAE,GAAG,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAC9B,CAAC,KAQA,EAAE,EAAE,CAAC,CAAC;gBACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACrC,YAAY,EAAE,CAAC,CAAC,YAAY;oBAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;wBAC3B,WAAW,EAAE,CAAC,CAAC,WAAW;wBAC1B,SAAS,EAAE,CAAC,CAAC,SAAS;wBACtB,KAAK,EAAE,CAAC,CAAC,KAAK;qBACf,CAAC,CAAC;oBACH,eAAe,EAAE,CAAC,CAAC,eAAe;iBACnC,CAAC,CAAC;aACJ,CAAC,CACH,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,QAAQ,CAAC,IAAI,CAAC,kCAAkC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACnE,CAAC;QAED,+BAA+B;QAC/B,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;YACvE,oEAAoE;YACpE,0DAA0D;YAC1D,MAAM,UAAU,GAAG,IAAI,GAAG,EAA0C,CAAC;YACrE,MAAM,UAAU,GAKX,SAAS,CAAC,SAAS,IAAI,EAAE,CAAC;YAE/B,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;gBAC/B,IAAI,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;gBAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,KAAK,GAAG,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;oBAClE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;gBAC5C,CAAC;gBACD,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC;oBAChB,WAAW,EAAE,KAAK,CAAC,WAAW;oBAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;oBAC1B,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;iBAC1B,CAAC,CAAC;YACL,CAAC;YACD,GAAG,GAAG,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,QAAQ,CAAC,IAAI,CAAC,mCAAmC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACpE,CAAC;QAED,+BAA+B;QAC/B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;QAC1D,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;QAED,OAAO;YACL,EAAE,EAAE,IAAI;YACR,IAAI,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE;SAC5B,CAAC;IACJ,CAAC;CACF"}

package/dist/collect/dom.d.ts

@@ -0,0 +1,37 @@
+/**
+ * DOMCollector — captures DOM structure metadata via page.evaluate().
+ *
+ * Extracts the following from the live page after navigation:
+ * - Total node count (elements, text nodes, comments)
+ * - Maximum DOM tree depth
+ * - Element type distribution (count per tag name)
+ * - Total text content length
+ *
+ * Uses page.evaluate() rather than CDP domains for lightweight introspection.
+ * Does NOT traverse the full DOM tree — collects aggregate stats only.
+ */
+import { type CDPSession, type Page } from 'playwright';
+import type { Collector, CollectorResult, DomRawData } from './types.js';
+import type { CollectorRunOptions } from '../shared/types.js';
+export declare class DOMCollector implements Collector {
+    private readonly page;
+    readonly name = "dom";
+    private session;
+    /**
+     * @param page - Playwright Page instance used for evaluate() calls.
+     *               The page reference is required because DOM stats are
+     *               extracted via in-page JavaScript, not CDP commands.
+     */
+    constructor(page: Page);
+    /**
+     * Start collecting DOM data.
+     * Currently a no-op — DOM snapshot is taken on stop() after navigation.
+     */
+    start(session: CDPSession, _options?: CollectorRunOptions): Promise<void>;
+    /**
+     * Stop collecting and return DOM metadata.
+     * Runs page.evaluate() to extract aggregate DOM statistics.
+     */
+    stop(): Promise<CollectorResult<DomRawData>>;
+}
+//# sourceMappingURL=dom.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/collect/dom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,qBAAa,YAAa,YAAW,SAAS;IAUhC,OAAO,CAAC,QAAQ,CAAC,IAAI;IATjC,QAAQ,CAAC,IAAI,SAAS;IAEtB,OAAO,CAAC,OAAO,CAA2B;IAE1C;;;;OAIG;gBAC0B,IAAI,EAAE,IAAI;IAEvC;;;OAGG;IACG,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/E;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;CA6FnD"}