playwright-intelligence-engine 0.0.0-stage → 2.0.0

package/src/trace/archive-reader.ts

@@ -0,0 +1,246 @@
+import AdmZip from 'adm-zip';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { ZipSlipSecurityError, TraceCorruptedError } from '../core/errors/engine-errors.js';
+
+export interface UnpackOptions {
+  maxTotalSize?: number;      // Default 500 MB
+  maxEntries?: number;        // Default 10,000 entries
+  targetDir?: string;         // Directory to extract to
+}
+
+export interface ExtractedTraceArchive {
+  archivePath: string;
+  extractDir: string;
+  entryNames: string[];
+  hasTraceEventFile: boolean;
+  hasNetworkEventFile: boolean;
+}
+
+export interface TraceEntryDiscovery {
+  /** Best stream for backward-compatible single-stream consumers. */
+  traceEntryName?: string | undefined;
+  networkEntryName?: string | undefined;
+  /** All streams, ordered with explicit failure streams first. */
+  traceEntryNames?: string[] | undefined;
+  networkEntryNames?: string[] | undefined;
+}
+
+export class ArchiveReader {
+  private static readonly DEFAULT_MAX_SIZE = 100 * 1024 * 1024; // 100 MB max uncompressed
+  private static readonly DEFAULT_MAX_ENTRIES = 10000;
+  private static readonly MAX_COMPRESSION_RATIO = 10; // 10:1 ratio protection
+  private static readonly MAX_SINGLE_ENTRY_SIZE = 50 * 1024 * 1024; // 50 MB max single entry
+
+  /**
+   * Automatically discovers the primary trace and network JSONL entry names inside a Playwright trace archive.
+   * Matches stream and worker IDs between .trace and .network files to prevent cross-worker mismatch.
+   */
+  public static findTraceFileEntries(zipPath: string): TraceEntryDiscovery {
+    try {
+      const zip = new AdmZip(zipPath);
+      const entries = zip.getEntries();
+
+      // A Playwright archive can contain several streams. The largest stream is
+      // often a browser/page stream, while the runner's test.trace contains the
+      // actual failed pw:api action and error. Prefer the stream with explicit
+      // failed-action evidence, then fall back to the largest stream for older
+      // or minimal archives.
+      const traceCandidates = entries
+        .filter((e) => e.entryName.endsWith('.trace'))
+        .map((entry) => {
+          const text = entry.getData().toString('utf8');
+          const lines = text.split(/\r?\n/);
+          let failureScore = 0;
+          for (const line of lines) {
+            if (!line.includes('"type":"')) continue;
+            if (line.includes('"type":"after"') && line.includes('"error"')) failureScore += 100;
+            if (line.includes('"type":"error"') && (line.includes('"message"') || line.includes('"error"'))) failureScore += 80;
+            if (line.includes('"type":"log"')) failureScore += 1;
+          }
+          if (path.basename(entry.entryName).toLowerCase() === 'test.trace' && failureScore > 0) {
+            failureScore += 10;
+          }
+          return { entry, failureScore };
+        })
+        .sort((a, b) => b.failureScore - a.failureScore || b.entry.header.size - a.entry.header.size);
+
+      const orderedTraceNames = traceCandidates.map(({ entry }) => entry.entryName);
+      const bestTrace = orderedTraceNames[0];
+      if (!bestTrace) {
+        return {};
+      }
+
+      // Correlate network entry with matching stream / worker prefix if possible
+      const traceBase = path.basename(bestTrace, '.trace');
+      const networkCandidates = entries.filter((e) => e.entryName.endsWith('.network'));
+      const networkEntryNames = networkCandidates.map((entry) => entry.entryName);
+
+      let bestNetwork: string | undefined;
+      // 1. Exact base match (e.g. 0.trace -> 0.network, trace.trace -> trace.network)
+      const exactMatch = networkCandidates.find((e) => path.basename(e.entryName, '.network') === traceBase);
+      if (exactMatch) {
+        bestNetwork = exactMatch.entryName;
+      } else {
+        // 2. Prefix match (e.g. 0-trace.trace -> 0-network.network or 0.network)
+        const workerPrefix = traceBase.split('-')[0] ?? '';
+        const prefixMatch = networkCandidates.find((e) => path.basename(e.entryName, '.network').startsWith(workerPrefix));
+        bestNetwork = prefixMatch ? prefixMatch.entryName : networkCandidates.sort((a, b) => b.header.size - a.header.size)[0]?.entryName;
+      }
+
+      return {
+        traceEntryName: bestTrace,
+        networkEntryName: bestNetwork,
+        traceEntryNames: orderedTraceNames,
+        networkEntryNames,
+      };
+    } catch {
+      return {};
+    }
+  }
+
+  /** Reads multiple archive entries and joins them as one logical JSONL stream. */
+  public static async readEntriesAsText(zipPath: string, entryNames: string[]): Promise<string> {
+    const uniqueNames = [...new Set(entryNames.filter(Boolean))];
+    const texts = await Promise.all(uniqueNames.map((entryName) => ArchiveReader.readEntryAsText(zipPath, entryName)));
+    return texts.join('\n');
+  }
+
+  /**
+   * Reads a single entry as a UTF-8 string directly from a .zip file in memory
+   * with strict per-entry size limits.
+   */
+  public static async readEntryAsText(zipPath: string, entryName: string): Promise<string> {
+    try {
+      const zip = new AdmZip(zipPath);
+      const entry = zip.getEntry(entryName);
+      if (!entry) {
+        throw new Error(`Entry '${entryName}' not found in archive '${zipPath}'`);
+      }
+      if (entry.header.size > ArchiveReader.MAX_SINGLE_ENTRY_SIZE) {
+        throw new TraceCorruptedError(
+          zipPath,
+          `Entry '${entryName}' size ${entry.header.size} bytes exceeds single entry limit of ${ArchiveReader.MAX_SINGLE_ENTRY_SIZE} bytes`
+        );
+      }
+      return entry.getData().toString('utf8');
+    } catch (err: any) {
+      if (err instanceof ZipSlipSecurityError) throw err;
+      throw new TraceCorruptedError(zipPath, err.message);
+    }
+  }
+
+  /**
+   * Safely unpacks a Playwright trace.zip archive to an isolated destination directory
+   * with strict Zip-Slip and Zip-Bomb protections.
+   */
+  public static async unpackSafely(
+    zipPath: string,
+    destinationDir: string,
+    options?: UnpackOptions
+  ): Promise<ExtractedTraceArchive> {
+    const maxSize = options?.maxTotalSize ?? ArchiveReader.DEFAULT_MAX_SIZE;
+    const maxEntries = options?.maxEntries ?? ArchiveReader.DEFAULT_MAX_ENTRIES;
+
+    const resolvedDest = path.resolve(destinationDir);
+    await fs.mkdir(resolvedDest, { recursive: true });
+
+    let zip: AdmZip;
+    try {
+      zip = new AdmZip(zipPath);
+    } catch (err: any) {
+      throw new TraceCorruptedError(zipPath, `Failed to initialize zip reader: ${err.message}`);
+    }
+
+    const entries = zip.getEntries();
+    if (entries.length > maxEntries) {
+      throw new TraceCorruptedError(
+        zipPath,
+        `Zip-Bomb suspected: archive contains ${entries.length} entries (max allowed: ${maxEntries})`
+      );
+    }
+
+    let totalSize = 0;
+    const entryNames: string[] = [];
+
+    // Phase 1: Validate all entries BEFORE writing anything to disk (All-or-nothing check)
+    for (const entry of entries) {
+      totalSize += entry.header.size;
+      if (totalSize > maxSize) {
+        throw new TraceCorruptedError(
+          zipPath,
+          `Zip-Bomb suspected: uncompressed size exceeded limit of ${maxSize} bytes`
+        );
+      }
+
+      // Check for Zip-Bomb compression ratio anomaly (e.g. 100:1 ratio)
+      if (entry.header.compressedSize > 0 && entry.header.size > 512 * 1024) {
+        const ratio = entry.header.size / entry.header.compressedSize;
+        if (ratio > ArchiveReader.MAX_COMPRESSION_RATIO) {
+          throw new TraceCorruptedError(
+            zipPath,
+            `Zip-Bomb suspected: compression ratio ${ratio.toFixed(1)}:1 exceeds limit of ${ArchiveReader.MAX_COMPRESSION_RATIO}:1 for entry '${entry.entryName}'`
+          );
+        }
+      }
+
+      // Check for Zip-Slip path traversal vulnerability
+      const entryName = entry.entryName;
+      // Cross-platform check: reject absolute paths, drive letters, UNC paths, and root-relative paths
+      if (
+        path.isAbsolute(entryName) ||
+        path.win32.isAbsolute(entryName) ||
+        path.posix.isAbsolute(entryName) ||
+        /^[a-zA-Z]:[/\\]/.test(entryName) ||
+        entryName.startsWith('/') ||
+        entryName.startsWith('\\')
+      ) {
+        throw new ZipSlipSecurityError(entry.entryName);
+      }
+
+      // Ensure target path is strictly within destination directory on both Windows and POSIX
+      const normalizedEntry = entryName.replace(/\\/g, '/');
+      const targetFilePath = path.resolve(resolvedDest, normalizedEntry);
+      const relative = path.relative(resolvedDest, targetFilePath);
+      if (
+        relative.startsWith('..') ||
+        path.isAbsolute(relative) ||
+        path.win32.isAbsolute(relative) ||
+        path.posix.isAbsolute(relative)
+      ) {
+        throw new ZipSlipSecurityError(entry.entryName);
+      }
+
+      entryNames.push(entry.entryName);
+    }
+
+    // Phase 2: Safe extraction
+    for (const entry of entries) {
+      const normalizedEntry = entry.entryName.replace(/\\/g, '/');
+      const targetFilePath = path.resolve(resolvedDest, normalizedEntry);
+      if (entry.isDirectory) {
+        await fs.mkdir(targetFilePath, { recursive: true });
+      } else {
+        await fs.mkdir(path.dirname(targetFilePath), { recursive: true });
+        const content = entry.getData();
+        await fs.writeFile(targetFilePath, content);
+      }
+    }
+
+    const hasTraceEventFile = entryNames.some(
+      (name) => name === 'trace.trace' || name.endsWith('.trace')
+    );
+    const hasNetworkEventFile = entryNames.some(
+      (name) => name === 'trace.network' || name.endsWith('.network')
+    );
+
+    return {
+      archivePath: zipPath,
+      extractDir: resolvedDest,
+      entryNames,
+      hasTraceEventFile,
+      hasNetworkEventFile,
+    };
+  }
+}
+

package/src/trace/snapshot-resolver.ts

@@ -0,0 +1,308 @@
+export type NodeSnapshot =
+  | string
+  | number
+  | [string, Record<string, string>, ...NodeSnapshot[]];
+
+export interface ResolvedElement {
+  tag: string;
+  attributes: Record<string, string>;
+  text: string;
+  children: ResolvedElement[];
+  role?: string | undefined;
+  accessibleName?: string | undefined;
+}
+
+export type SnapshotCompleteness = 'COMPLETE' | 'PARTIAL' | 'UNAVAILABLE';
+
+export interface ResolvedSnapshot {
+  frameId: string;
+  callId?: string | undefined;
+  phase: 'before' | 'action' | 'after';
+  completeness: SnapshotCompleteness;
+  unresolvedReferences: string[];
+  dom: ResolvedElement[];
+}
+
+export interface FrameSnapshotRecord {
+  frameId: string;
+  pageId?: string | undefined;
+  callId?: string | undefined;
+  snapshotName?: string | undefined;
+  phase?: 'before' | 'action' | 'after' | undefined;
+  node?: NodeSnapshot | undefined;
+}
+
+export class SnapshotResolver {
+  /**
+   * Reconstructs an in-memory resolved element tree from Playwright's array-based NodeSnapshot,
+   * tracking provenance, snapshot phase, and evidence completeness.
+   */
+  public static resolveSnapshot(record: FrameSnapshotRecord): ResolvedSnapshot {
+    const frameId = record.frameId || 'main-frame';
+    const phase = record.phase ?? 'before';
+    const unresolvedReferences: string[] = [];
+
+    if (!record.node) {
+      return {
+        frameId,
+        callId: record.callId,
+        phase,
+        completeness: 'UNAVAILABLE',
+        unresolvedReferences: ['Missing root node in snapshot record'],
+        dom: [],
+      };
+    }
+
+    const rootElement = SnapshotResolver.resolveNode(record.node, unresolvedReferences);
+    const completeness: SnapshotCompleteness =
+      unresolvedReferences.length > 0 ? 'PARTIAL' : rootElement ? 'COMPLETE' : 'UNAVAILABLE';
+
+    return {
+      frameId,
+      callId: record.callId,
+      phase,
+      completeness,
+      unresolvedReferences,
+      dom: rootElement ? [rootElement] : [],
+    };
+  }
+
+  /**
+   * Reconstructs an in-memory resolved element tree from Playwright's array-based NodeSnapshot.
+   */
+  public static resolveNode(node: NodeSnapshot, unresolvedRefs?: string[]): ResolvedElement | null {
+    if (typeof node === 'string' || typeof node === 'number') {
+      if (typeof node === 'string' && node.startsWith('ref:')) {
+        unresolvedRefs?.push(node);
+      }
+      return null;
+    }
+
+    if (!Array.isArray(node) || node.length < 2) {
+      return null;
+    }
+
+    const tag = (node[0] as string).toLowerCase();
+    const attributes = (node[1] as Record<string, string>) ?? {};
+    const rawChildren = node.slice(2) as NodeSnapshot[];
+
+    const children: ResolvedElement[] = [];
+    let textAccumulator = '';
+
+    for (const child of rawChildren) {
+      if (typeof child === 'string') {
+        if (child.startsWith('ref:')) {
+          unresolvedRefs?.push(child);
+        } else {
+          textAccumulator += child.trim() + ' ';
+        }
+      } else if (Array.isArray(child)) {
+        const resolvedChild = SnapshotResolver.resolveNode(child, unresolvedRefs);
+        if (resolvedChild) {
+          children.push(resolvedChild);
+          textAccumulator += resolvedChild.text + ' ';
+        }
+      }
+    }
+
+    const role = attributes['role'] ?? SnapshotResolver.inferRoleFromTag(tag, attributes);
+    const accessibleName =
+      attributes['aria-label'] ??
+      attributes['alt'] ??
+      attributes['title'] ??
+      attributes['placeholder'] ??
+      textAccumulator.trim();
+
+    return {
+      tag,
+      attributes,
+      text: textAccumulator.trim(),
+      children,
+      role,
+      accessibleName: accessibleName || undefined,
+    };
+  }
+
+  /**
+   * Traverses and collects all nodes in depth-first order as Playwright's snapshotNodes does.
+   */
+  public static snapshotNodes(snap: any): any[] {
+    if (!snap) return [];
+    if (snap._nodes) return snap._nodes;
+    const nodes: any[] = [];
+    const visit = (n: any) => {
+      if (typeof n === 'string' || typeof n === 'number') {
+        nodes.push(n);
+      } else if (Array.isArray(n) && typeof n[0] === 'string') {
+        const [, , ...children] = n;
+        for (const child of children) visit(child);
+        nodes.push(n);
+      }
+    };
+    if (snap.html) visit(snap.html);
+    else if (snap.node) visit(snap.node);
+    snap._nodes = nodes;
+    return nodes;
+  }
+
+  /**
+   * Resolves a modern Playwright differential snapshot node with support for subtree references [ [ delta, nodeIndex ] ].
+   */
+  public static resolveDifferentialNode(
+    n: any,
+    snapshotIndex: number,
+    allSnapshots: any[],
+    unresolvedRefs?: string[]
+  ): ResolvedElement | string | null {
+    if (typeof n === 'string' || typeof n === 'number') {
+      return String(n);
+    }
+
+    // Check for Playwright subtree reference [ [ delta, nodeIndex ] ]
+    if (
+      Array.isArray(n) &&
+      n.length === 1 &&
+      Array.isArray(n[0]) &&
+      n[0].length === 2 &&
+      typeof n[0][0] === 'number' &&
+      typeof n[0][1] === 'number'
+    ) {
+      const referenceIndex = snapshotIndex - n[0][0];
+      if (referenceIndex >= 0 && referenceIndex < allSnapshots.length) {
+        const nodes = SnapshotResolver.snapshotNodes(allSnapshots[referenceIndex]);
+        const nodeIndex = n[0][1];
+        if (nodeIndex >= 0 && nodeIndex < nodes.length) {
+          return SnapshotResolver.resolveDifferentialNode(
+            nodes[nodeIndex],
+            referenceIndex,
+            allSnapshots,
+            unresolvedRefs
+          );
+        }
+      }
+      unresolvedRefs?.push(`Subtree reference out of bounds: [${n[0][0]}, ${n[0][1]}]`);
+      return null;
+    }
+
+    if (!Array.isArray(n) || n.length < 2 || typeof n[0] !== 'string') {
+      return null;
+    }
+
+    const tag = (n[0] as string).toLowerCase();
+    const attributes = (n[1] as Record<string, string>) ?? {};
+    const rawChildren = n.slice(2);
+
+    const children: ResolvedElement[] = [];
+    let textAccumulator = '';
+
+    for (const child of rawChildren) {
+      const resolved = SnapshotResolver.resolveDifferentialNode(
+        child,
+        snapshotIndex,
+        allSnapshots,
+        unresolvedRefs
+      );
+      if (typeof resolved === 'string') {
+        textAccumulator += resolved.trim() + ' ';
+      } else if (resolved && typeof resolved === 'object' && 'tag' in resolved) {
+        children.push(resolved as ResolvedElement);
+        textAccumulator += (resolved as ResolvedElement).text + ' ';
+      }
+    }
+
+    const role = attributes['role'] ?? SnapshotResolver.inferRoleFromTag(tag, attributes);
+    const accessibleName =
+      attributes['aria-label'] ??
+      attributes['alt'] ??
+      attributes['title'] ??
+      attributes['placeholder'] ??
+      textAccumulator.trim();
+
+    return {
+      tag,
+      attributes,
+      text: textAccumulator.trim(),
+      children,
+      role,
+      accessibleName: accessibleName || undefined,
+    };
+  }
+
+  /**
+   * Serializes a resolved element tree back into clean, formatted HTML.
+   */
+  public static toHtml(element: ResolvedElement, indent = 0): string {
+    const spacing = '  '.repeat(indent);
+    const attrs = Object.entries(element.attributes)
+      .map(([k, v]) => `${k}="${v.replace(/"/g, '&quot;')}"`)
+      .join(' ');
+    const attrString = attrs.length > 0 ? ` ${attrs}` : '';
+
+    if (element.children.length === 0) {
+      return `${spacing}<${element.tag}${attrString}>${element.text}</${element.tag}>`;
+    }
+
+    const childrenHtml = element.children.map((c) => SnapshotResolver.toHtml(c, indent + 1)).join('\n');
+    return `${spacing}<${element.tag}${attrString}>\n${childrenHtml}\n${spacing}</${element.tag}>`;
+  }
+
+  /**
+   * Collects all descendant interactive elements (buttons, inputs, links, selects, roles).
+   */
+  public static extractInteractiveElements(root: ResolvedElement): ResolvedElement[] {
+    const interactiveTags = new Set(['button', 'a', 'input', 'select', 'textarea', 'option']);
+    const interactiveRoles = new Set([
+      'button',
+      'link',
+      'textbox',
+      'combobox',
+      'checkbox',
+      'radio',
+      'tab',
+      'menuitem',
+    ]);
+
+    const results: ResolvedElement[] = [];
+
+    function traverse(node: ResolvedElement) {
+      const isInteractive =
+        interactiveTags.has(node.tag) ||
+        (node.role && interactiveRoles.has(node.role.toLowerCase())) ||
+        Boolean(node.attributes?.['onclick']) ||
+        node.attributes?.['cursor'] === 'pointer';
+
+      if (isInteractive) {
+        results.push(node);
+      }
+
+      for (const child of node.children) {
+        traverse(child);
+      }
+    }
+
+    traverse(root);
+    return results;
+  }
+
+  private static inferRoleFromTag(tag: string, attributes: Record<string, string>): string | undefined {
+    switch (tag) {
+      case 'button':
+        return 'button';
+      case 'a':
+        return attributes['href'] ? 'link' : undefined;
+      case 'input': {
+        const type = attributes['type']?.toLowerCase() ?? 'text';
+        if (type === 'button' || type === 'submit' || type === 'reset') return 'button';
+        if (type === 'checkbox') return 'checkbox';
+        if (type === 'radio') return 'radio';
+        return 'textbox';
+      }
+      case 'select':
+        return 'combobox';
+      case 'textarea':
+        return 'textbox';
+      default:
+        return undefined;
+    }
+  }
+}