awaitly-visualizer 1.0.0

package/dist/performance-analyzer-BNwE4AiO.d.cts

@@ -0,0 +1,663 @@
+import { F as FlowNode, S as ScopeStartEvent, e as ScopeEndEvent, b as DecisionStartEvent, c as DecisionBranchEvent, d as DecisionEndEvent, W as WorkflowIR, I as IRSnapshot, z as StepState, C as ColorScheme, t as Renderer, s as RenderOptions, H as HTMLRenderOptions, q as LiveVisualizerOptions, T as TimeTravelState, N as NodePerformance, m as HeatmapData, l as HeatLevel } from './url-PkfQz4V5.cjs';
+import { WorkflowEvent } from 'awaitly/workflow';
+
+/**
+ * Parallel Detection - Heuristic detection of parallel execution from timing.
+ *
+ * When steps overlap in time (one starts before another ends), they are
+ * likely running in parallel. This module detects such patterns and
+ * groups overlapping steps into ParallelNode structures.
+ */
+
+/**
+ * Options for parallel detection.
+ */
+interface ParallelDetectorOptions {
+    /**
+     * Minimum overlap in milliseconds to consider steps parallel.
+     * Default: 0 (any overlap counts)
+     */
+    minOverlapMs?: number;
+    /**
+     * Maximum gap in milliseconds to still consider steps as part of same parallel group.
+     * Default: 5 (steps starting within 5ms are grouped)
+     */
+    maxGapMs?: number;
+}
+/**
+ * Group overlapping steps into parallel nodes.
+ *
+ * Algorithm:
+ * 1. Sort steps by start time
+ * 2. For each step, check if it overlaps with existing parallel groups
+ * 3. If it overlaps, add to group; otherwise start new sequence
+ * 4. Merge overlapping groups when step bridges them
+ *
+ * Note: If real scope nodes (from scope_start/scope_end) are present,
+ * heuristic detection is skipped to avoid conflicts.
+ */
+declare function detectParallelGroups(nodes: FlowNode[], options?: ParallelDetectorOptions): FlowNode[];
+/**
+ * Create a parallel detector that processes nodes.
+ */
+declare function createParallelDetector(options?: ParallelDetectorOptions): {
+    /**
+     * Process nodes and group overlapping ones into parallel nodes.
+     */
+    detect: (nodes: FlowNode[]) => FlowNode[];
+};
+
+/**
+ * IR Builder - Converts workflow events to Intermediate Representation.
+ *
+ * The builder maintains state as events arrive, constructing a tree
+ * representation of the workflow execution that can be rendered.
+ */
+
+/**
+ * Options for the IR builder.
+ */
+interface IRBuilderOptions {
+    /**
+     * Enable heuristic parallel detection based on timing.
+     * When true, overlapping steps are grouped into ParallelNodes.
+     * Default: true
+     */
+    detectParallel?: boolean;
+    /**
+     * Options for parallel detection.
+     */
+    parallelDetection?: ParallelDetectorOptions;
+    /**
+     * Enable snapshot recording for time-travel debugging.
+     * When true, the builder captures IR state after each event.
+     * Default: false
+     */
+    enableSnapshots?: boolean;
+    /**
+     * Maximum number of snapshots to keep (ring buffer behavior).
+     * When exceeded, oldest snapshots are discarded.
+     * Default: 1000
+     */
+    maxSnapshots?: number;
+}
+/**
+ * Creates an IR builder that processes workflow events.
+ */
+declare function createIRBuilder(options?: IRBuilderOptions): {
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    handleScopeEvent: (event: ScopeStartEvent | ScopeEndEvent) => void;
+    handleDecisionEvent: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+    getIR: () => WorkflowIR;
+    reset: () => void;
+    getSnapshots: () => IRSnapshot[];
+    getSnapshotAt: (index: number) => IRSnapshot | undefined;
+    getIRAt: (index: number) => WorkflowIR | undefined;
+    clearSnapshots: () => void;
+    /** Check if there are active (running) steps */
+    readonly hasActiveSteps: boolean;
+    /** Get the current workflow state */
+    readonly state: StepState;
+    /** Get the number of recorded snapshots */
+    readonly snapshotCount: number;
+    /** Check if snapshot recording is enabled */
+    readonly snapshotsEnabled: boolean;
+    /** Enable or disable snapshot recording (e.g. for time-travel stop/start) */
+    setSnapshotsEnabled(enabled: boolean): void;
+};
+/**
+ * Type for the IR builder instance.
+ */
+type IRBuilder = ReturnType<typeof createIRBuilder>;
+
+/**
+ * ANSI color utilities for terminal output.
+ */
+
+/**
+ * Default ANSI color scheme for step states.
+ */
+declare const defaultColorScheme: ColorScheme;
+
+/**
+ * ASCII Terminal Renderer
+ *
+ * Renders the workflow IR as ASCII art with box-drawing characters
+ * and ANSI colors for terminal display.
+ */
+
+/**
+ * Create the ASCII terminal renderer.
+ */
+declare function asciiRenderer(): Renderer;
+
+/**
+ * Mermaid Diagram Renderer
+ *
+ * Renders the workflow IR as a Mermaid flowchart diagram.
+ * Supports sequential flows, parallel (subgraph), and race patterns.
+ */
+
+/**
+ * Create the Mermaid diagram renderer.
+ */
+declare function mermaidRenderer(): Renderer;
+
+/**
+ * Logger Renderer - Outputs structured JSON optimized for logging systems.
+ *
+ * Works with any structured logger (Pino, Winston, Bunyan, console).
+ * Includes workflow summary, step details, and optional ASCII diagram.
+ *
+ * @example
+ * ```typescript
+ * const logData = JSON.parse(viz.renderAs('logger'));
+ * logger.info(logData, 'Workflow completed');
+ * ```
+ */
+
+/**
+ * Step log entry with execution details.
+ */
+interface StepLog {
+    id: string;
+    name: string;
+    key?: string;
+    state: string;
+    durationMs?: number;
+    startTs?: number;
+    endTs?: number;
+    retryCount?: number;
+    timedOut?: boolean;
+    timeoutMs?: number;
+    error?: string;
+}
+/**
+ * Hook execution log entry.
+ */
+interface HookLog {
+    shouldRun?: {
+        result?: boolean;
+        durationMs?: number;
+        error?: string;
+    };
+    onBeforeStart?: {
+        durationMs?: number;
+        error?: string;
+    };
+    onAfterStep?: Array<{
+        stepKey: string;
+        durationMs?: number;
+        error?: string;
+    }>;
+}
+/**
+ * Summary statistics for the workflow.
+ */
+interface WorkflowSummary {
+    totalSteps: number;
+    successCount: number;
+    errorCount: number;
+    cacheHits: number;
+    skippedCount: number;
+    totalRetries: number;
+    slowestStep?: {
+        name: string;
+        durationMs: number;
+    };
+}
+/**
+ * Complete logger output structure.
+ */
+interface LoggerOutput {
+    workflow: {
+        id: string;
+        name?: string;
+        state: string;
+        durationMs?: number;
+        startedAt?: number;
+        completedAt?: number;
+    };
+    steps: StepLog[];
+    summary: WorkflowSummary;
+    hooks?: HookLog;
+    diagram?: string;
+}
+/**
+ * Extended render options for logger renderer.
+ */
+interface LoggerRenderOptions extends RenderOptions {
+    /** Include ASCII diagram in output (default: true) */
+    includeDiagram?: boolean;
+    /** Strip ANSI color codes from diagram (default: true) */
+    stripAnsiColors?: boolean;
+    /** Diagram format: 'ascii' (tree-style) or 'flowchart' (boxes/arrows) (default: 'ascii') */
+    diagramFormat?: "ascii" | "flowchart";
+}
+/**
+ * Create a logger renderer that outputs structured JSON.
+ *
+ * @example
+ * ```typescript
+ * const viz = createVisualizer({ workflowName: 'checkout' });
+ * // ... run workflow ...
+ *
+ * const logData = JSON.parse(viz.renderAs('logger'));
+ * logger.info(logData, 'Workflow completed');
+ * ```
+ */
+declare function loggerRenderer(): Renderer;
+
+/**
+ * Flowchart ASCII Renderer
+ *
+ * Renders workflow IR as a proper flowchart with boxes and arrows.
+ * Uses a 2D canvas approach for spatial layout with proper fork/join patterns.
+ */
+
+declare function flowchartRenderer(): Renderer;
+
+/**
+ * HTML Renderer
+ *
+ * Renders the workflow IR as an interactive HTML page with:
+ * - SVG-based workflow diagram
+ * - Zoom and pan
+ * - Node inspection
+ * - Time-travel controls
+ * - Performance heatmap overlay
+ */
+
+/**
+ * Create the HTML renderer.
+ */
+declare function htmlRenderer(): Renderer;
+/**
+ * Render workflow IR to HTML with custom options.
+ */
+declare function renderToHTML(ir: WorkflowIR, options?: Partial<HTMLRenderOptions>): string;
+
+/**
+ * Live Visualizer - Real-time terminal updates during workflow execution.
+ *
+ * Uses ANSI escape codes to update the terminal in-place, showing
+ * workflow progress as it happens.
+ */
+
+/**
+ * Live visualizer with real-time terminal updates.
+ */
+interface LiveVisualizer {
+    /** Process a workflow event */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Process a scope event */
+    handleScopeEvent: (event: ScopeStartEvent | ScopeEndEvent) => void;
+    /** Process a decision event */
+    handleDecisionEvent: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+    /** Get current IR state */
+    getIR: () => WorkflowIR;
+    /** Render current state to string (without terminal output) */
+    render: () => string;
+    /** Start live rendering to terminal */
+    start: () => void;
+    /** Stop live rendering */
+    stop: () => void;
+    /** Force an immediate redraw */
+    refresh: () => void;
+    /** Reset state for a new workflow */
+    reset: () => void;
+}
+/**
+ * Create a live visualizer for real-time terminal updates.
+ *
+ * @example
+ * ```typescript
+ * const live = createLiveVisualizer({ workflowName: 'my-workflow' });
+ * const workflow = createWorkflow(deps, { onEvent: live.handleEvent });
+ *
+ * live.start();
+ * await workflow(async (step) => { ... });
+ * live.stop();
+ * ```
+ */
+declare function createLiveVisualizer(options?: LiveVisualizerOptions): LiveVisualizer;
+
+/**
+ * Decision Tracker - Helper for tracking conditional logic in workflows.
+ *
+ * This module provides utilities to track decision points (if/switch statements)
+ * so they can be visualized in workflow diagrams.
+ *
+ * @example
+ * ```typescript
+ * import { trackDecision } from 'awaitly-visualizer';
+ *
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: (event) => {
+ *     // Pass events to visualizer
+ *     viz.handleEvent(event);
+ *   }
+ * });
+ *
+ * await workflow(async (step) => {
+ *   const user = await step(fetchUser(id));
+ *
+ *   // Track a decision point
+ *   const decision = trackDecision('user-role-check', {
+ *     condition: 'user.role === "admin"',
+ *     value: user.role
+ *   });
+ *
+ *   if (user.role === 'admin') {
+ *     decision.takeBranch('admin', true);
+ *     await step(processAdminAction(user));
+ *   } else {
+ *     decision.takeBranch('user', false);
+ *     await step(processUserAction(user));
+ *   }
+ *
+ *   decision.end();
+ * });
+ * ```
+ */
+
+/**
+ * Options for creating a decision tracker.
+ */
+interface DecisionTrackerOptions {
+    /** Condition being evaluated (e.g., "user.role === 'admin'") */
+    condition?: string;
+    /** Value being evaluated */
+    value?: unknown;
+    /** Name/label for this decision point */
+    name?: string;
+    /** Workflow ID (auto-generated if not provided) */
+    workflowId?: string;
+    /** Event emitter function */
+    emit?: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+}
+/**
+ * Track a decision point in your workflow.
+ *
+ * Use this to annotate conditional logic (if/switch) so it appears
+ * in workflow visualizations.
+ *
+ * @param decisionId - Unique identifier for this decision
+ * @param options - Decision tracking options
+ * @returns A tracker object with methods to track branches
+ *
+ * @example
+ * ```typescript
+ * const decision = trackDecision('check-role', {
+ *   condition: 'user.role === "admin"',
+ *   value: user.role,
+ *   emit: (event) => viz.handleDecisionEvent(event)
+ * });
+ *
+ * if (user.role === 'admin') {
+ *   decision.takeBranch('admin', true);
+ *   // ... admin logic
+ * } else {
+ *   decision.takeBranch('user', false);
+ *   // ... user logic
+ * }
+ *
+ * decision.end();
+ * ```
+ */
+declare function trackDecision(decisionId: string, options?: DecisionTrackerOptions): DecisionTracker;
+/**
+ * Decision tracker instance.
+ */
+interface DecisionTracker {
+    /**
+     * Mark that a branch was taken or skipped.
+     * @param label - Label for this branch (e.g., "if", "else", "case 'admin'")
+     * @param taken - Whether this branch was executed
+     * @param branchCondition - Optional condition for this specific branch
+     */
+    takeBranch(label: string, taken: boolean, branchCondition?: string): void;
+    /**
+     * End the decision tracking.
+     * Call this after all branches have been evaluated.
+     */
+    end(): void;
+    /**
+     * Get which branch was taken.
+     */
+    getBranchTaken(): string | boolean | undefined;
+    /**
+     * Get all branches (taken and skipped).
+     */
+    getBranches(): Array<{
+        label: string;
+        condition?: string;
+        taken: boolean;
+    }>;
+}
+/**
+ * Track a simple if/else decision.
+ *
+ * @example
+ * ```typescript
+ * const decision = trackIf('check-admin', user.role === 'admin', {
+ *   condition: 'user.role === "admin"',
+ *   value: user.role,
+ *   emit: (e) => viz.handleDecisionEvent(e)
+ * });
+ *
+ * if (decision.condition) {
+ *   decision.then();
+ *   // admin logic
+ * } else {
+ *   decision.else();
+ *   // user logic
+ * }
+ *
+ * decision.end();
+ * ```
+ */
+declare function trackIf(decisionId: string, condition: boolean, options?: Omit<DecisionTrackerOptions, "value"> & {
+    value?: unknown;
+}): IfTracker;
+/**
+ * If tracker with convenience methods.
+ */
+interface IfTracker extends DecisionTracker {
+    /** The condition value */
+    condition: boolean;
+    /** Mark the "if" branch as taken */
+    then(): void;
+    /** Mark the "else" branch as taken */
+    else(): void;
+}
+/**
+ * Track a switch statement decision.
+ *
+ * @example
+ * ```typescript
+ * const decision = trackSwitch('process-type', user.type, {
+ *   emit: (e) => viz.handleDecisionEvent(e)
+ * });
+ *
+ * switch (user.type) {
+ *   case 'admin':
+ *     decision.case('admin', true);
+ *     // admin logic
+ *     break;
+ *   case 'user':
+ *     decision.case('user', true);
+ *     // user logic
+ *     break;
+ *   default:
+ *     decision.default(true);
+ *     // default logic
+ * }
+ *
+ * decision.end();
+ * ```
+ */
+declare function trackSwitch(decisionId: string, value: unknown, options?: Omit<DecisionTrackerOptions, "value">): SwitchTracker;
+/**
+ * Switch tracker with convenience methods.
+ */
+interface SwitchTracker extends DecisionTracker {
+    /** The value being switched on */
+    value: unknown;
+    /** Mark a case branch */
+    case(caseValue: string | number, taken: boolean): void;
+    /** Mark the default branch */
+    default(taken: boolean): void;
+}
+
+/**
+ * Time Travel Debugger
+ *
+ * Records IR snapshots at each event, enabling:
+ * - Step-by-step forward/backward navigation
+ * - Seeking to any point in execution
+ * - Playback at various speeds
+ * - State inspection at any moment
+ */
+
+/**
+ * Options for the time-travel controller.
+ */
+interface TimeTravelOptions {
+    /** Maximum snapshots to store (ring buffer) */
+    maxSnapshots?: number;
+    /** Automatically record snapshots on each event */
+    autoRecord?: boolean;
+    /** IR builder options (passed through) */
+    builderOptions?: Omit<IRBuilderOptions, "enableSnapshots" | "maxSnapshots">;
+}
+/**
+ * Time-travel controller interface.
+ */
+interface TimeTravelController {
+    /** Handle a workflow event (records snapshot if recording) */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Navigate to specific snapshot index */
+    seek: (index: number) => WorkflowIR | undefined;
+    /** Move one step forward */
+    stepForward: () => WorkflowIR | undefined;
+    /** Move one step backward */
+    stepBackward: () => WorkflowIR | undefined;
+    /** Start playback at given speed (1.0 = realtime) */
+    play: (speed?: number) => void;
+    /** Pause playback */
+    pause: () => void;
+    /** Get current IR state */
+    getCurrentIR: () => WorkflowIR;
+    /** Get IR at specific snapshot index */
+    getIRAt: (index: number) => WorkflowIR | undefined;
+    /** Get all snapshots */
+    getSnapshots: () => IRSnapshot[];
+    /** Get snapshot at specific index */
+    getSnapshotAt: (index: number) => IRSnapshot | undefined;
+    /** Get current time-travel state */
+    getState: () => TimeTravelState;
+    /** Subscribe to state changes */
+    onStateChange: (callback: (state: TimeTravelState) => void) => () => void;
+    /** Start/resume recording */
+    startRecording: () => void;
+    /** Stop recording */
+    stopRecording: () => void;
+    /** Reset to initial state */
+    reset: () => void;
+    /** Get the underlying IR builder */
+    getBuilder: () => IRBuilder;
+}
+/**
+ * Create a time-travel controller for workflow debugging.
+ *
+ * @example
+ * ```typescript
+ * const controller = createTimeTravelController();
+ *
+ * // Feed events from workflow execution
+ * workflow.onEvent(event => controller.handleEvent(event));
+ *
+ * // After execution, explore the timeline
+ * controller.seek(0);  // Go to start
+ * controller.stepForward();  // Step through
+ * controller.play(2);  // Playback at 2x speed
+ * ```
+ */
+declare function createTimeTravelController(options?: TimeTravelOptions): TimeTravelController;
+
+/**
+ * Performance Analyzer
+ *
+ * Analyzes workflow execution data to identify:
+ * - Slow steps (bottlenecks)
+ * - Retry patterns
+ * - Error-prone steps
+ * - Timing anomalies
+ *
+ * Aggregates metrics across multiple workflow runs to provide
+ * statistical insights and heatmap visualization data.
+ */
+
+/**
+ * A recorded workflow run for analysis.
+ */
+interface WorkflowRun {
+    /** Unique identifier for this run */
+    id: string;
+    /** Workflow start timestamp */
+    startTime: number;
+    /** All events from the workflow execution */
+    events: WorkflowEvent<unknown>[];
+}
+/**
+ * Performance analyzer interface.
+ */
+interface PerformanceAnalyzer {
+    /** Add a completed workflow run for analysis */
+    addRun: (run: WorkflowRun) => void;
+    /** Add events incrementally (alternative to addRun) */
+    addEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Finalize current run (when using addEvent) */
+    finalizeRun: (runId: string) => void;
+    /** Get performance stats for a specific node */
+    getNodePerformance: (nodeId: string) => NodePerformance | undefined;
+    /** Get heatmap data for an IR */
+    getHeatmap: (ir: WorkflowIR, metric?: "duration" | "retryRate" | "errorRate") => HeatmapData;
+    /** Get slowest nodes */
+    getSlowestNodes: (limit?: number) => NodePerformance[];
+    /** Get error-prone nodes */
+    getErrorProneNodes: (limit?: number) => NodePerformance[];
+    /** Get retry-prone nodes */
+    getRetryProneNodes: (limit?: number) => NodePerformance[];
+    /** Get all performance data */
+    getAllPerformance: () => Map<string, NodePerformance>;
+    /** Export performance data as JSON */
+    exportData: () => string;
+    /** Import performance data from JSON */
+    importData: (json: string) => void;
+    /** Clear all collected data */
+    clear: () => void;
+}
+/**
+ * Get heat level from normalized value (0-1).
+ */
+declare function getHeatLevel(heat: number): HeatLevel;
+/**
+ * Create a performance analyzer for workflow metrics.
+ *
+ * @example
+ * ```typescript
+ * const analyzer = createPerformanceAnalyzer();
+ *
+ * // Add completed runs
+ * analyzer.addRun({ id: 'run-1', startTime: Date.now(), events });
+ *
+ * // Get insights
+ * const slowest = analyzer.getSlowestNodes(5);
+ * const heatmap = analyzer.getHeatmap(ir, 'duration');
+ * ```
+ */
+declare function createPerformanceAnalyzer(): PerformanceAnalyzer;
+
+export { type DecisionTracker as D, type HookLog as H, type IRBuilderOptions as I, type LiveVisualizer as L, type ParallelDetectorOptions as P, type StepLog as S, type TimeTravelController as T, type WorkflowRun as W, type IfTracker as a, type LoggerOutput as b, type LoggerRenderOptions as c, type PerformanceAnalyzer as d, type SwitchTracker as e, type TimeTravelOptions as f, type WorkflowSummary as g, asciiRenderer as h, createIRBuilder as i, createLiveVisualizer as j, createParallelDetector as k, createPerformanceAnalyzer as l, createTimeTravelController as m, defaultColorScheme as n, detectParallelGroups as o, flowchartRenderer as p, getHeatLevel as q, htmlRenderer as r, loggerRenderer as s, mermaidRenderer as t, renderToHTML as u, trackDecision as v, trackIf as w, trackSwitch as x };