trace-engine-cli 0.0.0-stage → 0.0.1

package/dist/src/engine/loader.js

@@ -0,0 +1,142 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { loadTraceEngine } from './adapter.js';
+/**
+ * Checks if the buffer starts with the gzip magic header bytes (0x1f, 0x8b).
+ */
+export function isGzipBuffer(buffer) {
+    return buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b;
+}
+/**
+ * Decompresses a trace buffer if it is gzip-compressed or has a .gz extension.
+ */
+export function decompressTraceBuffer(buffer, filePath) {
+    const isGz = Boolean(filePath?.endsWith('.gz')) || isGzipBuffer(buffer);
+    if (isGz) {
+        return zlib.gunzipSync(buffer).toString('utf-8');
+    }
+    return buffer.toString('utf-8');
+}
+/**
+ * Parses raw JSON string into an array of trace events.
+ * Accepts both raw arrays `[...]` and wrapped objects `{"traceEvents": [...]}`.
+ */
+export function parseTraceJson(jsonString) {
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonString);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse trace JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (Array.isArray(parsed)) {
+        return parsed;
+    }
+    if (typeof parsed === 'object' &&
+        parsed !== null &&
+        'traceEvents' in parsed &&
+        Array.isArray(parsed.traceEvents)) {
+        return parsed.traceEvents;
+    }
+    throw new Error('Unrecognized trace format: JSON root must be an array of trace events or an object containing a "traceEvents" array.');
+}
+function isLanternError(arg) {
+    if (!arg)
+        return false;
+    if (typeof arg === 'object' && arg !== null && ('name' in arg || 'constructor' in arg)) {
+        const errorObj = arg;
+        if (errorObj.name === 'LanternError' || errorObj.constructor?.name === 'LanternError') {
+            return true;
+        }
+        if (errorObj.message?.includes('NO_LCP')) {
+            return true;
+        }
+    }
+    if (typeof arg === 'string' && (arg.includes('LanternError') || arg.includes('NO_LCP'))) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Loads, decompresses, and parses a Chromium performance trace file using DevTools Trace Engine.
+ *
+ * Capabilities:
+ * - Transparently gunzips files with `.gz` extensions or gzip magic bytes (`0x1f 0x8b`).
+ * - Supports raw event arrays (`[...]`) and standard Chrome wrapper objects (`{ traceEvents: [...] }`).
+ * - Normalizes `parsedTrace` retrieval across different DevTools engine versions (`parsedTrace(0)` vs `traceParsedData(0)`).
+ * - Filters internal non-fatal Lantern simulation errors during model parsing.
+ *
+ * @param filePath - Relative or absolute path to the trace file.
+ * @param customEnginePath - Optional custom Trace Engine bundle path.
+ * @returns Object containing the TraceEngine instance, parsedTrace data, and rawEvents.
+ * @throws {Error} If the file does not exist, is invalid JSON, or lacks trace events.
+ */
+export async function loadTraceFromFile(filePath, customEnginePath) {
+    const absolutePath = path.resolve(process.cwd(), filePath);
+    let rawBuffer;
+    try {
+        rawBuffer = fs.readFileSync(absolutePath);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new Error(`Trace file not found: ${absolutePath}`);
+        }
+        if (err.code === 'EISDIR') {
+            throw new Error(`'${filePath}' is a directory. Trace engine commands accept a single trace file. To search across multiple files or directories, use: trace-cli scan "${filePath}" [options]`);
+        }
+        throw err;
+    }
+    const jsonContent = decompressTraceBuffer(rawBuffer, absolutePath);
+    const rawEvents = parseTraceJson(jsonContent);
+    const engine = await loadTraceEngine(customEnginePath);
+    const model = engine.TraceModel.Model.createWithAllHandlers();
+    const origWarn = console.warn;
+    const origError = console.error;
+    try {
+        console.warn = (...args) => {
+            if (args.length > 0 && isLanternError(args[0]))
+                return;
+            origWarn(...args);
+        };
+        console.error = (...args) => {
+            if (args.length > 0 && isLanternError(args[0]))
+                return;
+            origError(...args);
+        };
+        // biome-ignore lint/suspicious/noExplicitAny: trace engine parse events typing
+        await model.parse(rawEvents);
+    }
+    finally {
+        console.warn = origWarn;
+        console.error = origError;
+    }
+    // Normalize parsedTrace across devtools engine versions
+    const parsedTrace = typeof model.parsedTrace === 'function'
+        ? model.parsedTrace(0)
+        : typeof model.traceParsedData ===
+            'function'
+            ? model.traceParsedData(0)
+            : null;
+    if (!parsedTrace) {
+        throw new Error('Failed to retrieve parsed trace data from TraceEngine model.');
+    }
+    return {
+        engine,
+        parsedTrace,
+        rawEvents,
+    };
+}

package/dist/src/engine/types.d.ts

@@ -0,0 +1,452 @@
+/**
+ * Core Web Vitals rating category.
+ */
+export type CwvRating = 'good' | 'needs-improvement' | 'poor';
+/**
+ * High-level summary of trace bounds, Core Web Vitals, and main thread category distribution.
+ * All duration and timestamp properties are normalized to milliseconds (ms).
+ */
+export interface OverviewResult {
+    bounds: {
+        minMs: number;
+        maxMs: number;
+        durationMs: number;
+    };
+    mainUrl: string | null;
+    navigationStartMs: number | null;
+    coreWebVitals: {
+        fcp: {
+            valueMs: number;
+            rating: CwvRating;
+        } | null;
+        lcp: {
+            valueMs: number;
+            rating: CwvRating;
+            element?: string;
+            url?: string;
+        } | null;
+        cls: {
+            value: number;
+            rating: CwvRating;
+            worstClusterScore?: number;
+        } | null;
+        inp: {
+            valueMs: number;
+            rating: CwvRating;
+            interactionType?: string;
+        } | null;
+    };
+    mainThreadBreakdown: {
+        scriptingMs: number;
+        layoutMs: number;
+        renderingMs: number;
+        gcMs: number;
+        systemMs: number;
+        idleMs: number;
+        totalMs: number;
+    };
+    warnings: string[];
+}
+/**
+ * Detailed breakdown of Largest Contentful Paint subparts.
+ */
+export interface LcpBreakdownInsight {
+    totalLcpMs: number;
+    ttfbMs: number;
+    loadDelayMs: number;
+    loadDurationMs: number;
+    renderDelayMs: number;
+    lcpElement?: string;
+    lcpUrl?: string;
+}
+/**
+ * Detailed breakdown of Interaction to Next Paint longest interaction.
+ */
+export interface InpBreakdownInsight {
+    totalDurationMs: number;
+    inputDelayMs: number;
+    processingDurationMs: number;
+    presentationDelayMs: number;
+    eventType: string;
+    target?: string;
+}
+/**
+ * Diagnostic layout shift culprit information.
+ */
+export interface ClsCulpritInsight {
+    score: number;
+    timestampMs: number;
+    culpritNodes: string[];
+}
+/**
+ * Render-blocking stylesheet or script resource.
+ */
+export interface RenderBlockingInsight {
+    url: string;
+    durationMs: number;
+    transferSizeBytes: number;
+}
+/**
+ * Third-party entity resource usage and main thread CPU execution time.
+ */
+export interface ThirdPartyEntityInsight {
+    entityName: string;
+    transferSizeBytes: number;
+    mainThreadTimeMs: number;
+}
+/**
+ * Diagnostics and metric breakdowns for CWV bottlenecks.
+ */
+export interface InsightsResult {
+    navigationId?: string;
+    lcpBreakdown?: LcpBreakdownInsight | null;
+    inpBreakdown?: InpBreakdownInsight | null;
+    clsCulprits?: ClsCulpritInsight[];
+    renderBlocking?: RenderBlockingInsight[];
+    thirdParties?: ThirdPartyEntityInsight[];
+    warnings?: string[];
+}
+/**
+ * Executed task or aggregated call tree node on the main thread.
+ */
+export interface TaskItem {
+    startTimeMs: number;
+    durationMs: number;
+    selfTimeMs: number;
+    functionName: string;
+    url?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+}
+/**
+ * Aggregated main thread task execution details.
+ */
+export interface TasksResult {
+    mode: 'list' | 'top-down' | 'bottom-up';
+    tasks: TaskItem[];
+}
+/**
+ * Individual network request details and timing waterfall.
+ */
+export interface NetworkRequestItem {
+    requestId?: string;
+    url: string;
+    mimeType: string;
+    priority: string;
+    timing: {
+        queueingMs: number;
+        dnsMs: number;
+        sslMs: number;
+        ttfbMs: number;
+        downloadMs: number;
+        totalDurationMs: number;
+    };
+    transferSizeBytes: number;
+    renderBlocking?: boolean;
+}
+/**
+ * Single node in a network request initiator chain.
+ */
+export interface InitiatorChainItem {
+    url: string;
+    initiatorUrl?: string;
+    type?: string;
+}
+/**
+ * Network requests waterfall and initiator analysis result.
+ */
+export interface NetworkResult {
+    initiatorChain?: InitiatorChainItem[];
+    requests: NetworkRequestItem[];
+}
+/**
+ * User interaction timing details.
+ */
+export interface InteractionItem {
+    eventType: string;
+    startTimeMs: number;
+    durationMs: number;
+    inputDelayMs: number;
+    processingDurationMs: number;
+    presentationDelayMs: number;
+    targetElement?: string;
+    interactionId?: number;
+}
+/**
+ * User interaction timeline result.
+ */
+export interface InteractionsResult {
+    interactions: InteractionItem[];
+}
+/**
+ * DOM node identified as a layout shift culprit.
+ */
+export interface ShiftCulprit {
+    nodeId?: number;
+    tagName?: string;
+    selector?: string;
+    debugName?: string;
+    scoreDelta?: number;
+}
+/**
+ * Impacted DOM node in an individual layout shift event.
+ */
+export interface ShiftImpactedNodeItem {
+    nodeId?: number;
+    tagName?: string;
+    selector?: string;
+    debugName?: string;
+    oldRect?: [number, number, number, number];
+    newRect?: [number, number, number, number];
+}
+/**
+ * Individual layout shift event within a cluster.
+ */
+export interface ShiftIndividualEvent {
+    timestampMs: number;
+    score: number;
+    weightedScoreDelta?: number;
+    navigationId?: string;
+    hadRecentInput?: boolean;
+    impactedNodes?: ShiftImpactedNodeItem[];
+}
+/**
+ * Layout shift session window cluster.
+ */
+export interface ShiftClusterItem {
+    timestampMs: number;
+    durationMs: number;
+    cumulativeScore: number;
+    navigationId?: string;
+    culprits: ShiftCulprit[];
+    events?: ShiftIndividualEvent[];
+}
+/**
+ * Layout shifts analysis result.
+ */
+export interface ShiftsResult {
+    clusters: ShiftClusterItem[];
+}
+/**
+ * Individual invocation instance of a searched function.
+ */
+export interface FindCallInstance {
+    timestampMs: number;
+    durationMs: number;
+    url?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+}
+/**
+ * Temporal breakdown interval for function call distribution.
+ */
+export interface FindIntervalItem {
+    startMs: number;
+    endMs: number;
+    calls: number;
+    totalDurationMs: number;
+}
+/**
+ * Result of searching for a specific function's executions across a trace.
+ */
+export interface FindResult {
+    functionQuery: string;
+    timeRange?: {
+        startMs: number;
+        endMs: number;
+    };
+    totalCalls: number;
+    totalDurationMs: number;
+    avgDurationMs: number;
+    firstCallMs?: number;
+    lastCallMs?: number;
+    calls: FindCallInstance[];
+    intervals?: FindIntervalItem[];
+}
+/**
+ * Single time bucket summary in profile progression.
+ */
+export interface ProfileBucketItem {
+    startMs: number;
+    endMs: number;
+    totalActiveMs: number;
+    topFunctions: Array<{
+        name: string;
+        selfTimeMs: number;
+        selfTimePct: number;
+    }>;
+}
+/**
+ * Time-bucketed CPU profiling result.
+ */
+export interface ProfileResult {
+    timeRange: {
+        startMs: number;
+        endMs: number;
+    };
+    bucketSizeMs: number;
+    buckets: ProfileBucketItem[];
+}
+/**
+ * Single function comparison entry in a differential profile.
+ */
+export interface DiffEntryItem {
+    functionName: string;
+    url?: string;
+    selfTimeMsA: number;
+    selfTimePctA: number;
+    selfTimeMsB: number;
+    selfTimePctB: number;
+    deltaPct: number;
+}
+/**
+ * Differential profile result comparing two trace intervals.
+ */
+export interface DiffResult {
+    windowA: {
+        startMs: number;
+        endMs: number;
+        durationMs: number;
+    };
+    windowB: {
+        startMs: number;
+        endMs: number;
+        durationMs: number;
+    };
+    entries: DiffEntryItem[];
+}
+/**
+ * Lifecycle metrics for scheduled async primitives (rAF, Timers).
+ */
+export interface SchedulingStatItem {
+    scheduledCount: number;
+    canceledCount: number;
+    executedCount: number;
+    cancellationRatePct: number;
+}
+/**
+ * Async task and animation frame scheduling lifecycle result.
+ */
+export interface SchedulingResult {
+    timeRange?: {
+        startMs: number;
+        endMs: number;
+    };
+    animationFrames: SchedulingStatItem;
+    timers: SchedulingStatItem;
+    churnDetected: boolean;
+    warnings: string[];
+}
+/**
+ * Raw trace event dictionary from Chromium trace JSON payload.
+ */
+export interface RawTraceEvent {
+    name?: string;
+    cat?: string;
+    ph?: string;
+    ts?: number;
+    dur?: number;
+    pid?: number;
+    tid?: number;
+    args?: Record<string, unknown>;
+}
+/**
+ * Raw trace event entry.
+ */
+export interface RawTraceEventItem {
+    /** Event name (e.g. 'LayoutShift', 'RunTask'). */
+    name: string;
+    /** Normalized timestamp in milliseconds relative to trace start. */
+    tsMs: number;
+    /** Normalized event duration in milliseconds. */
+    durMs?: number;
+    /** Trace event category. */
+    cat?: string;
+    /** Chromium event phase code (e.g. 'X', 'I', 'B', 'E'). */
+    ph?: string;
+    /** Process ID. */
+    pid?: number;
+    /** Thread ID. */
+    tid?: number;
+    /** Raw event payload arguments. */
+    args?: Record<string, unknown>;
+    /** Extracted property values mapped from dot-notation query fields. */
+    selectedFields?: Record<string, unknown>;
+}
+/**
+ * Raw trace event filtering result.
+ */
+export interface EventsResult {
+    /** Total events matching the filter criteria across the trace. */
+    totalMatched: number;
+    /** Number of events returned in the events array (capped by limit). */
+    returned: number;
+    /** Array of matched and projected event items. */
+    events: RawTraceEventItem[];
+}
+/**
+ * Navigation entry from trace metadata.
+ */
+export interface NavigationItem {
+    /** Navigation identifier from trace event data (args.data.navigationId). */
+    navigationId: string;
+    /** Corresponding Trace Engine InsightSet identifier (e.g. 'NAVIGATION_0'). */
+    insightSetId?: string;
+    /** Frame identifier where navigation occurred. */
+    frameId?: string;
+    /** Navigation URL or loader URL. */
+    url: string;
+    /** Timestamp in milliseconds relative to trace start. */
+    timestampMs: number;
+    /** Whether the navigation belongs to the primary main frame. */
+    isMainFrame: boolean;
+    /** Whether an InsightSet exists for this navigation. */
+    hasInsights: boolean;
+}
+/**
+ * Navigation list result.
+ */
+export interface NavigationsResult {
+    /** Total number of navigations detected. */
+    total: number;
+    /** Ordered list of navigation entries. */
+    navigations: NavigationItem[];
+    /** Unique InsightSet identifiers present in the parsed trace. */
+    insightSetIds: string[];
+}
+/**
+ * Telemetry and match summary for a single trace file matched during a scan.
+ */
+export interface ScanMatchedFile {
+    /** Relative or normalized path to the trace file. */
+    file: string;
+    /** Total number of events matching query criteria in this file. */
+    matchCount: number;
+    /** Unique categories associated with the matched events. */
+    categories: string[];
+    /** Name of the first matching event found in the trace. */
+    firstEventName?: string;
+    /** Raw absolute timestamp of the first matching event in milliseconds (trace bounds uncalculated). */
+    firstEventTsMs?: number;
+}
+/**
+ * Result of scanning multiple trace files or directories.
+ */
+export interface ScanResult {
+    /** Search filters applied to the scan. */
+    query: {
+        names?: string[];
+        category?: string;
+        phase?: string;
+        grep?: string;
+        fields?: string[];
+    };
+    /** Total trace files discovered and inspected. */
+    totalFilesScanned: number;
+    /** Total trace files that contained at least one match. */
+    totalFilesMatched: number;
+    /** Total matching events across all inspected files. */
+    totalEventsMatched: number;
+    /** Ordered list of matched files, sorted by match count descending. */
+    matchedFiles: ScanMatchedFile[];
+}

package/dist/src/engine/types.js

@@ -0,0 +1,14 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+export {};

package/dist/src/formatters/index.d.ts

@@ -0,0 +1,6 @@
+export interface FormatOptions {
+    format: 'toon' | 'md';
+    type?: 'overview' | 'insights' | 'tasks' | 'network' | 'interactions' | 'shifts' | 'find' | 'profile' | 'diff' | 'scheduling' | 'events' | 'navigations' | 'scan';
+    includeHint?: boolean;
+}
+export declare function formatResult(data: unknown, options: FormatOptions): string;

package/dist/src/formatters/index.js

@@ -0,0 +1,66 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { formatMarkdown } from './markdown.js';
+import { formatToon } from './toon.js';
+const NEXT_STEPS_HINT_TOON = `
+# Drill-down commands:
+# - trace-cli insights <file> [--category <lcp|inp|cls|render-blocking|third-parties>] [--navigation <id>]
+# - trace-cli tasks <file> [--min-duration <ms>] [--tree <bottom-up|top-down>] [--top <n>]
+# - trace-cli find <file> --function <name> [--time-range <start,end>]
+# - trace-cli profile <file> [--time-range <start,end>] [--bucket <ms>]
+# - trace-cli diff <file> --window-a <start,end> --window-b <start,end>
+# - trace-cli scheduling <file> [--time-range <start,end>]
+# - trace-cli network <file> [--render-blocking] [--slowest <n>] [--initiator-chain <url>]
+# - trace-cli interactions <file>
+# - trace-cli shifts <file> [--events]
+# - trace-cli events <file> [--name <names>] [--cat <category>] [--fields <fields>]
+# - trace-cli navigations <file>
+#
+# Multi-file search:
+# - trace-cli scan <dir-or-glob> [--name <names>] [--cat <category>] [--grep <pattern>]
+`.trim();
+const NEXT_STEPS_HINT_MD = `
+---
+### Drill-down Commands
+- \`trace-cli insights <file> [--category <lcp|inp|cls|render-blocking|third-parties>] [--navigation <id>]\`
+- \`trace-cli tasks <file> [--min-duration <ms>] [--tree <bottom-up|top-down>] [--top <n>]\`
+- \`trace-cli find <file> --function <name> [--time-range <start,end>]\`
+- \`trace-cli profile <file> [--time-range <start,end>] [--bucket <ms>]\`
+- \`trace-cli diff <file> --window-a <start,end> --window-b <start,end>\`
+- \`trace-cli scheduling <file> [--time-range <start,end>]\`
+- \`trace-cli network <file> [--render-blocking] [--slowest <n>] [--initiator-chain <url>]\`
+- \`trace-cli interactions <file>\`
+- \`trace-cli shifts <file> [--events]\`
+- \`trace-cli events <file> [--name <names>] [--cat <category>] [--fields <fields>]\`
+- \`trace-cli navigations <file>\`
+
+### Multi-file Search
+- \`trace-cli scan <dir-or-glob> [--name <names>] [--cat <category>] [--grep <pattern>]\`
+`.trim();
+export function formatResult(data, options) {
+    let output = '';
+    if (options.format === 'md') {
+        output = formatMarkdown(data, options.type);
+        if (options.includeHint) {
+            output = `${output}\n\n${NEXT_STEPS_HINT_MD}`;
+        }
+    }
+    else {
+        output = formatToon(data);
+        if (options.includeHint) {
+            output = `${output}\n\n${NEXT_STEPS_HINT_TOON}`;
+        }
+    }
+    return output;
+}

package/dist/src/formatters/markdown.d.ts

@@ -0,0 +1,15 @@
+import type { DiffResult, EventsResult, FindResult, InsightsResult, InteractionsResult, NavigationsResult, NetworkResult, OverviewResult, ProfileResult, ScanResult, SchedulingResult, ShiftsResult, TasksResult } from '../engine/types.js';
+export declare function formatOverviewMarkdown(overview: OverviewResult): string;
+export declare function formatInsightsMarkdown(insights: InsightsResult): string;
+export declare function formatTasksMarkdown(tasksResult: TasksResult): string;
+export declare function formatNetworkMarkdown(network: NetworkResult): string;
+export declare function formatInteractionsMarkdown(interactions: InteractionsResult): string;
+export declare function formatShiftsMarkdown(shifts: ShiftsResult): string;
+export declare function formatFindMarkdown(findResult: FindResult): string;
+export declare function formatProfileMarkdown(profileResult: ProfileResult): string;
+export declare function formatDiffMarkdown(diffResult: DiffResult): string;
+export declare function formatSchedulingMarkdown(sched: SchedulingResult): string;
+export declare function formatEventsMarkdown(result: EventsResult): string;
+export declare function formatNavigationsMarkdown(result: NavigationsResult): string;
+export declare function formatScanMarkdown(result: ScanResult): string;
+export declare function formatMarkdown(data: unknown, type?: string): string;