@ai-setting/roy-agent-core 1.0.0

package/src/env/debug/formatters/tree-formatter.test.ts

@@ -0,0 +1,107 @@
+import { describe, test, expect } from 'bun:test';
+import { TreeFormatter } from './tree-formatter';
+import type { TraceTreeNode, TraceEntry } from '../types';
+
+describe('TreeFormatter', () => {
+  const formatter = new TreeFormatter();
+
+  const mockRootNode: TraceTreeNode = {
+    traceId: 'trace-001',
+    function: 'agent.execute',
+    startTime: '2026-04-08T10:00:00.000',
+    endTime: '2026-04-08T10:00:05.000',
+    durationMs: 5000,
+    children: [
+      {
+        traceId: 'trace-001',
+        function: 'llm.component.invoke',
+        startTime: '2026-04-08T10:00:01.000',
+        endTime: '2026-04-08T10:00:03.000',
+        durationMs: 2000,
+        children: [],
+        entry: {} as TraceEntry,
+      },
+      {
+        traceId: 'trace-001',
+        function: 'tool.execute',
+        startTime: '2026-04-08T10:00:03.000',
+        endTime: '2026-04-08T10:00:04.000',
+        durationMs: 1000,
+        children: [],
+        entry: {} as TraceEntry,
+      },
+    ],
+    entry: {} as TraceEntry,
+  };
+
+  test('formatTree - should format tree with proper indentation', () => {
+    const result = formatter.formatTree(mockRootNode);
+    
+    // Should show root function
+    expect(result).toContain('agent.execute');
+    // Should show duration (5s because it's > 1000ms)
+    expect(result).toContain('5.00s');
+    // Should have tree branch connectors
+    expect(result).toContain('├──');
+    expect(result).toContain('└──');
+  });
+
+  test('formatTree - should show children with correct markers', () => {
+    const result = formatter.formatTree(mockRootNode);
+    
+    // Should show children
+    expect(result).toContain('llm.component.invoke');
+    expect(result).toContain('tool.execute');
+  });
+
+  test('formatTree - should handle empty children', () => {
+    const leafNode: TraceTreeNode = {
+      traceId: 'trace-001',
+      function: 'leaf.function',
+      startTime: '2026-04-08T10:00:00.000',
+      children: [],
+      entry: {} as TraceEntry,
+    };
+    
+    const result = formatter.formatTree(leafNode);
+    expect(result).toContain('leaf.function');
+    expect(result).not.toContain('children');
+  });
+
+  test('formatTree - should format duration', () => {
+    const result = formatter.formatTree(mockRootNode);
+    
+    // Duration should be visible (formatted as seconds for values >= 1000ms)
+    expect(result).toContain('5.00s');  // 5000ms
+    expect(result).toContain('2.00s');  // 2000ms
+    expect(result).toContain('1.00s');  // 1000ms
+  });
+
+  test('formatTrees - should format multiple trees', () => {
+    const node2: TraceTreeNode = {
+      ...mockRootNode,
+      traceId: 'trace-002',
+      function: 'another.function',
+    };
+    
+    const result = formatter.formatTrees([mockRootNode, node2]);
+    
+    // Should have two separate trees
+    expect(result.split('\n\n')).toHaveLength(2);
+    expect(result).toContain('agent.execute');
+    expect(result).toContain('another.function');
+  });
+
+  test('formatTrees - should handle empty array', () => {
+    const result = formatter.formatTrees([]);
+    expect(result).toBe('No trace trees');
+  });
+
+  test('toJSON - should output valid JSON', () => {
+    const result = formatter.toJSON([mockRootNode]);
+    const parsed = JSON.parse(result);
+    
+    expect(parsed).toHaveLength(1);
+    expect(parsed[0].function).toBe('agent.execute');
+  });
+});

package/src/env/debug/formatters/tree-formatter.ts

@@ -0,0 +1,325 @@
+/**
+ * @fileoverview Tree Formatter
+ * 
+ * Formats trace call trees for console output with:
+ * - ANSI color support
+ * - Duration display with percentage
+ * - Time bar visualization
+ * - Proper indentation
+ */
+
+import type { TraceTreeNode } from '../types';
+
+/**
+ * ANSI color codes
+ */
+const Colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+};
+
+/**
+ * Apply color to text
+ */
+function color(text: string, colorCode: string): string {
+  return `${colorCode}${text}${Colors.reset}`;
+}
+
+/**
+ * Tree drawing characters
+ */
+const CHARS = {
+  VERTICAL: '│',
+  VERTICAL_CONNECTOR: '├──',
+  LAST_CONNECTOR: '└──',
+  SPACE: ' ',
+  BAR: '█',
+  EMPTY: '░',
+  DASH: '─',
+};
+
+/**
+ * Options for tree formatting
+ */
+export interface TreeFormatOptions {
+  /** Show duration percentage (default: true) */
+  showPercent?: boolean;
+  /** Show time bar (default: false) */
+  showTimeBar?: boolean;
+  /** Width of time bar (default: 10) */
+  barWidth?: number;
+}
+
+/**
+ * Formats trace call trees for human-readable output
+ */
+export class TreeFormatter {
+  private options: TreeFormatOptions;
+
+  constructor(options: TreeFormatOptions = {}) {
+    this.options = {
+      showPercent: true,
+      showTimeBar: false, // Default off, use --bar flag to enable
+      barWidth: 10,
+      ...options,
+    };
+  }
+
+  /**
+   * Color function based on percentage
+   */
+  private colorByPercent(percent: number): string {
+    if (percent >= 80) return Colors.red;
+    if (percent >= 50) return Colors.yellow;
+    if (percent >= 20) return Colors.cyan;
+    return Colors.dim;
+  }
+
+  /**
+   * Format a single trace tree
+   */
+  formatTree(node: TraceTreeNode): string {
+    const lines: string[] = [];
+    const totalDuration = node.durationMs || 0;
+    // Use sum of direct children for percentage base (better for virtual root nodes)
+    const percentBase = node.children.reduce((sum, c) => sum + (c.durationMs || 0), 0) || totalDuration;
+    
+    // Root node line
+    lines.push(this.formatNode(node, totalDuration, percentBase, '', true, true));
+    
+    // Process children recursively
+    this.formatChildren(node.children, '', lines, totalDuration, percentBase);
+    
+    return lines.join('\n');
+  }
+
+  /**
+   * Format a single node
+   */
+  private formatNode(
+    node: TraceTreeNode,
+    totalDuration: number,
+    percentBase: number,
+    prefix: string,
+    isLast: boolean,
+    isRoot: boolean
+  ): string {
+    // Tree connector
+    const connector = isRoot ? '' : (isLast ? CHARS.LAST_CONNECTOR : CHARS.VERTICAL_CONNECTOR);
+    const prefixStr = isRoot ? '' : prefix;
+    
+    let line = `${prefixStr}${connector} ${node.function}`;
+    
+    // Duration
+    if (node.durationMs !== undefined) {
+      line += color(` (${this.formatDuration(node.durationMs)})`, Colors.dim);
+    }
+    
+    // Percentage - skip for:
+    // 1. Virtual root nodes (function is '(root)')
+    // 2. Actual root of tree (isRoot=true) - root is 100% by definition
+    if (this.options.showPercent && percentBase > 0 && node.durationMs !== undefined && 
+        node.function !== '(root)' && !isRoot) {
+      const percent = Math.round((node.durationMs / percentBase) * 100);
+      const percentStr = ` [${percent}%]`;
+      line += color(percentStr, this.colorByPercent(percent));
+    }
+    
+    // Time bar - only show for nested spans where totalDuration is meaningful
+    if (this.options.showTimeBar && node.durationMs !== undefined && totalDuration > 0 && !isRoot) {
+      line += ' ' + this.renderTimeBar(node.durationMs, totalDuration);
+    }
+    
+    return isRoot ? color(line, Colors.bold) : line;
+  }
+
+  /**
+   * Recursively format children
+   */
+  private formatChildren(
+    children: TraceTreeNode[],
+    prefix: string,
+    lines: string[],
+    totalDuration: number,
+    percentBase: number
+  ): void {
+    children.forEach((child, index) => {
+      const isLast = index === children.length - 1;
+      const newPrefix = prefix + (isLast ? '    ' : `${CHARS.VERTICAL}   `);
+      
+      lines.push(this.formatNode(child, totalDuration, percentBase, prefix, isLast, false));
+      
+      if (child.children.length > 0) {
+        this.formatChildren(child.children, newPrefix, lines, totalDuration, percentBase);
+      }
+    });
+  }
+
+  /**
+   * Render a time bar showing relative duration
+   */
+  private renderTimeBar(duration: number, total: number): string {
+    const width = this.options.barWidth || 10;
+    const filledWidth = Math.round((duration / total) * width);
+    const emptyWidth = width - filledWidth;
+    
+    const bar = CHARS.BAR.repeat(filledWidth) + CHARS.EMPTY.repeat(emptyWidth);
+    return color(`[${bar}]`, Colors.dim);
+  }
+
+  /**
+   * Format duration in human-readable form
+   */
+  private formatDuration(ms: number): string {
+    if (ms < 1000) {
+      return `${ms}ms`;
+    } else if (ms < 60000) {
+      return `${(ms / 1000).toFixed(2)}s`;
+    } else if (ms < 3600000) { // < 1 hour
+      const mins = Math.floor(ms / 60000);
+      const secs = Math.round((ms % 60000) / 1000);
+      return `${mins}m ${secs}s`;
+    } else {
+      const hours = Math.floor(ms / 3600000);
+      const mins = Math.floor((ms % 3600000) / 60000);
+      return `${hours}h ${mins}m`;
+    }
+  }
+
+  /**
+   * Format multiple trace trees
+   */
+  formatTrees(trees: TraceTreeNode[]): string {
+    if (trees.length === 0) {
+      return 'No trace trees';
+    }
+    
+    return trees.map(tree => this.formatTree(tree)).join('\n\n');
+  }
+
+  /**
+   * Output as JSON
+   */
+  toJSON(trees: TraceTreeNode[]): string {
+    return JSON.stringify(trees, null, 2);
+  }
+
+  /**
+   * Generate a summary table of all spans sorted by duration
+   */
+  formatSummary(node: TraceTreeNode): string {
+    const rows: { func: string; duration: number; percent: number; depth: number }[] = [];
+    // For virtual root nodes with multiple children, use the root's own duration
+    // which is calculated from children's time span
+    const total = node.durationMs || 0;
+    
+    // Calculate sum of direct children durations for percentage base
+    const childrenTotal = node.children.reduce((sum, c) => sum + (c.durationMs || 0), 0);
+    const percentBase = total > 0 ? total : childrenTotal;
+    
+    const collect = (n: TraceTreeNode, depth: number): void => {
+      if (n.durationMs !== undefined) {
+        rows.push({
+          func: n.function,
+          duration: n.durationMs,
+          percent: percentBase > 0 ? Math.round((n.durationMs / percentBase) * 100) : 0,
+          depth,
+        });
+      }
+      n.children.forEach(child => collect(child, depth + 1));
+    };
+    
+    collect(node, 0);
+    
+    // Sort by duration descending
+    rows.sort((a, b) => b.duration - a.duration);
+    
+    const lines: string[] = [];
+    lines.push(color('\n=== Duration Summary ===', Colors.bold));
+    lines.push(color('(sorted by time consumption)\n', Colors.dim));
+    
+    // Table header
+    lines.push(color(`  ${'─'.repeat(65)}`, Colors.dim));
+    lines.push(color(`  ${'FUNCTION'.padEnd(35)} ${'TIME'.padEnd(12)} %`, Colors.dim));
+    lines.push(color(`  ${'─'.repeat(65)}`, Colors.dim));
+    
+    for (const row of rows) {
+      const indent = '  '.repeat(row.depth);
+      const funcDisplay = row.depth > 0 ? '└─ '.repeat(row.depth) + row.func : row.func;
+      
+      const percentStr = String(row.percent).padStart(3) + '%';
+      const percentColor = row.percent >= 50 ? Colors.red :
+                          row.percent >= 20 ? Colors.yellow :
+                          Colors.dim;
+      
+      lines.push(
+        `  ${indent}${funcDisplay.substring(0, 35).padEnd(35)}${this.formatDuration(row.duration).padEnd(12)} ${color(percentStr, percentColor)}`
+      );
+    }
+    
+    return lines.join('\n');
+  }
+
+  /**
+   * Format tree with timeline visualization
+   */
+  formatTimeline(node: TraceTreeNode): string {
+    const lines: string[] = [];
+    const totalDuration = node.durationMs || 0;
+    
+    lines.push(color(`\n=== Timeline: ${node.function} ===`, Colors.bold));
+    lines.push(color(`Total: ${this.formatDuration(totalDuration)}\n`, Colors.dim));
+    
+    // Build timeline
+    const timeline = this.buildTimeline(node, totalDuration, 0, 0);
+    lines.push(...timeline);
+    
+    return lines.join('\n');
+  }
+
+  /**
+   * Build timeline visualization with absolute positioning
+   */
+  private buildTimeline(
+    node: TraceTreeNode,
+    totalDuration: number,
+    absoluteOffset: number,
+    depth: number
+  ): string[] {
+    const lines: string[] = [];
+    const width = 40;
+    
+    // Calculate position based on absolute offset
+    const startPos = Math.round((absoluteOffset / totalDuration) * width);
+    const durationWidth = node.durationMs !== undefined 
+      ? Math.max(2, Math.round((node.durationMs / totalDuration) * width))
+      : 2;
+    
+    // Build the bar with proper positioning
+    const bar = ' '.repeat(Math.max(0, startPos)) + CHARS.BAR.repeat(durationWidth);
+    
+    // Format line
+    const indent = '  '.repeat(depth);
+    const funcName = node.function.length > 25 ? '...' + node.function.slice(-22) : node.function;
+    const time = node.durationMs !== undefined ? this.formatDuration(node.durationMs) : '-';
+    const percent = node.durationMs !== undefined 
+      ? ` [${Math.round((node.durationMs / totalDuration) * 100)}%]`
+      : '';
+    lines.push(`${indent}${funcName.padEnd(25)} ${bar} ${color(time + percent, Colors.dim)}`);
+    
+    // Process children with absolute offset within this node
+    let childOffset = absoluteOffset;
+    for (const child of node.children) {
+      lines.push(...this.buildTimeline(child, totalDuration, childOffset, depth + 1));
+      childOffset += child.durationMs || 0;
+    }
+    
+    return lines;
+  }
+}

package/src/env/debug/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Debug Component Index
+ * 
+ * Export all debug-related types and classes.
+ */
+
+// Types
+export type {
+  TraceEntry,
+  TraceTreeNode,
+  ParserOptions,
+  LogDiscoveryOptions,
+  ParsedLogLine,
+  TraceIdInfo,
+  TraceSummary,
+  FormatOptions,
+  TraceAction,
+  LogLevel,
+} from './types';
+
+// Data source types (defined in debug-component.ts)
+export type { TraceDataSource, TraceParserOptions } from './debug-component';
+
+// Components
+export { DebugComponent } from './debug-component';
+
+// Reader
+export { LogReader } from './reader/log-reader';
+export { SpanDbReader } from './reader/span-db-reader';
+
+// Parser
+export { RegexParser } from './parser/regex-parser';
+export { SpanBuilder } from './parser/span-builder';
+
+// Formatters
+export { TraceFormatter } from './formatters/trace-formatter';
+export { TreeFormatter } from './formatters/tree-formatter';
+export { ReplFormatter } from './formatters/repl-formatter';

package/src/env/debug/parser/regex-parser.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, test, beforeEach } from 'bun:test';
+import { RegexParser } from './regex-parser';
+
+describe('RegexParser', () => {
+  let parser: RegexParser;
+
+  beforeEach(() => {
+    parser = new RegexParser();
+  });
+
+  describe('parseLogLine', () => {
+    test('should parse enter trace line', () => {
+      const line = '2026-04-08 19:12:36.134 [INFO] [cli/src/bin/roy.js:80752][traced:llm.component.invoke] [TRACE] >>> llm.component.invoke enter: [{\"messages\":[{\"role\":\"user\"}]},{\"providerId\":\"minimax\"}]';
+      
+      const result = parser.parseLogLine(line);
+      
+      expect(result).not.toBeNull();
+      expect(result!.timestamp).toBe('2026-04-08T19:12:36.134'); // ISO format with T
+      expect(result!.level).toBe('INFO');
+      expect(result!.source).toBe('cli/src/bin/roy.js:80752');
+      expect(result!.category).toBe('traced:llm.component.invoke');
+      expect(result!.action).toBe('>>>');
+      expect(result!.method).toBe('llm.component.invoke');
+      expect(result!.actionType).toBe('enter');
+    });
+
+    test('should parse quit trace line', () => {
+      const line = '2026-04-08 19:12:39.213 [INFO] [cli/src/bin/roy.js:80752][traced:llm.component.invoke] [TRACE] <<< llm.component.invoke quit: {\"output\":{\"content\":\"Hello\"}}';
+      
+      const result = parser.parseLogLine(line);
+      
+      expect(result).not.toBeNull();
+      expect(result!.action).toBe('<<<');
+      expect(result!.actionType).toBe('quit');
+    });
+
+    test('should parse error trace line', () => {
+      const line = '2026-04-08 19:12:39.213 [ERROR] [cli/src/bin/roy.js:80752][traced:llm.component.invoke] [TRACE] !!! llm.component.invoke error: Connection timeout';
+      
+      const result = parser.parseLogLine(line);
+      
+      expect(result).not.toBeNull();
+      expect(result!.action).toBe('!!!');
+      expect(result!.actionType).toBe('error');
+      expect(result!.level).toBe('ERROR');
+    });
+
+    test('should return null for non-trace lines', () => {
+      const line = '2026-04-08 19:12:36.134 [INFO] Some regular log message';
+      
+      const result = parser.parseLogLine(line);
+      
+      expect(result).toBeNull();
+    });
+
+    test('should return null for malformed trace lines', () => {
+      const line = '2026-04-08 19:12:36.134 [INFO] [TRACE] >>> invalid line';
+      
+      const result = parser.parseLogLine(line);
+      
+      expect(result).toBeNull();
+    });
+
+    test('should parse line with method name', () => {
+      // Note: The requestId is extracted separately via extractTraceId
+      const line = '2026-04-08 19:12:36.134 [INFO] [cli/src/bin/roy.js:80752][traced:llm.component.invoke] [TRACE] >>> llm.component.invoke enter: [{}]';
+      
+      const result = parser.parseLogLine(line);
+      
+      expect(result).not.toBeNull();
+      expect(result!.method).toBe('llm.component.invoke');
+    });
+  });
+
+  describe('parseArgs', () => {
+    test('should parse JSON array args', () => {
+      const raw = '[{\"messages\":[{\"role\":\"user\"}]},{\"providerId\":\"minimax\"}]';
+      
+      const result = parser.parseArgs(raw);
+      
+      expect(Array.isArray(result)).toBe(true);
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({ messages: [{ role: 'user' }] });
+      expect(result[1]).toEqual({ providerId: 'minimax' });
+    });
+
+    test('should parse JSON object args', () => {
+      const raw = '{\"name\":\"test\",\"value\":123}';
+      
+      const result = parser.parseArgs(raw);
+      
+      expect(result).toEqual({ name: 'test', value: 123 });
+    });
+
+    test('should parse simple string args', () => {
+      const raw = 'simple string argument';
+      
+      const result = parser.parseArgs(raw);
+      
+      expect(result).toBe('simple string argument');
+    });
+
+    test('should handle empty args', () => {
+      const raw = '';
+      
+      const result = parser.parseArgs(raw);
+      
+      expect(result).toBeNull();
+    });
+
+    test('should handle malformed JSON gracefully', () => {
+      const raw = '{invalid json}';
+      
+      const result = parser.parseArgs(raw);
+      
+      expect(result).toBe(raw); // Return raw string on parse failure
+    });
+  });
+
+  describe('isTraceLine', () => {
+    test('should return true for trace lines', () => {
+      const line = '2026-04-08 19:12:36.134 [INFO] [TRACE] >>> method enter: [{}]';
+      expect(parser.isTraceLine(line)).toBe(true);
+    });
+
+    test('should return false for non-trace lines', () => {
+      const line = '2026-04-08 19:12:36.134 [INFO] Regular log message';
+      expect(parser.isTraceLine(line)).toBe(false);
+    });
+  });
+
+  describe('filterByLevel', () => {
+    test('should filter by info level', () => {
+      const lines = [
+        '2026-04-08 19:12:36.134 [INFO] [TRACE] >>> method enter: [{}]',
+        '2026-04-08 19:12:36.134 [DEBUG] [TRACE] >>> method enter: [{}]',
+        '2026-04-08 19:12:36.134 [ERROR] [TRACE] >>> method enter: [{}]',
+      ];
+
+      const filtered = parser.filterByLevel(lines, 'info');
+      
+      expect(filtered).toHaveLength(1);
+      expect(filtered[0]).toContain('[INFO]');
+    });
+
+    test('should return all lines if no level specified', () => {
+      const lines = [
+        '2026-04-08 19:12:36.134 [INFO] [TRACE] >>> method enter: [{}]',
+        '2026-04-08 19:12:36.134 [DEBUG] [TRACE] >>> method enter: [{}]',
+      ];
+
+      const filtered = parser.filterByLevel(lines);
+      
+      expect(filtered).toHaveLength(2);
+    });
+  });
+
+  describe('filterByFunction', () => {
+    test('should filter by function name', () => {
+      const lines = [
+        '2026-04-08 19:12:36.134 [INFO] [TRACE] >>> llm.invoke enter: [{}]',
+        '2026-04-08 19:12:36.134 [INFO] [TRACE] >>> tool.execute enter: [{}]',
+        '2026-04-08 19:12:36.134 [INFO] [TRACE] >>> db.query enter: [{}]',
+      ];
+
+      const filtered = parser.filterByFunction(lines, 'llm');
+      
+      expect(filtered).toHaveLength(1);
+      expect(filtered[0]).toContain('llm.invoke');
+    });
+
+    test('should return all lines if no function specified', () => {
+      const lines = [
+        '2026-04-08 19:12:36.134 [INFO] [TRACE] >>> llm.invoke enter: [{}]',
+        '2026-04-08 19:12:36.134 [INFO] [TRACE] >>> tool.execute enter: [{}]',
+      ];
+
+      const filtered = parser.filterByFunction(lines);
+      
+      expect(filtered).toHaveLength(2);
+    });
+  });
+
+  describe('extractTraceId', () => {
+    test('should extract traceId from category', () => {
+      const line = '2026-04-08 19:12:36.134 [INFO] [source][requestId=req_123] [TRACE] >>> method enter: [{}]';
+      
+      const traceId = parser.extractTraceId(line);
+      
+      expect(traceId).toBe('req_123');
+    });
+
+    test('should return null if no traceId found', () => {
+      const line = '2026-04-08 19:12:36.134 [INFO] [source] [TRACE] >>> method enter: [{}]';
+      
+      const traceId = parser.extractTraceId(line);
+      
+      expect(traceId).toBeNull();
+    });
+  });
+});