taist 1.1.0

package/lib/execution-tracer.js

@@ -0,0 +1,370 @@
+/**
+ * Execution Tracer - Runtime execution tracing without explicit logging
+ * Captures function calls, arguments, return values, and errors
+ */
+
+export class ExecutionTracer {
+  constructor(options = {}) {
+    this.enabled = options.enabled !== false;
+    this.depth = options.depth || 2;
+    this.maxEntries = options.maxEntries || 1000;
+
+    // Trace buffer (circular buffer)
+    this.traces = [];
+    this.currentIndex = 0;
+
+    // Call stack tracking
+    this.callStack = [];
+    this.currentDepth = 0;
+
+    // Performance tracking
+    this.startTimes = new Map();
+  }
+
+  /**
+   * Start tracing
+   */
+  start() {
+    this.enabled = true;
+    this.traces = [];
+    this.currentIndex = 0;
+    this.callStack = [];
+    this.currentDepth = 0;
+  }
+
+  /**
+   * Stop tracing
+   */
+  stop() {
+    this.enabled = false;
+  }
+
+  /**
+   * Clear all traces
+   */
+  clear() {
+    this.traces = [];
+    this.currentIndex = 0;
+    this.callStack = [];
+    this.currentDepth = 0;
+    this.startTimes.clear();
+  }
+
+  /**
+   * Get all traces
+   */
+  getTraces() {
+    return this.traces.filter(t => t !== undefined);
+  }
+
+  /**
+   * Record function entry
+   */
+  enter(name, args = []) {
+    if (!this.enabled) return;
+    if (this.currentDepth >= this.depth) return;
+
+    const traceId = this.generateId();
+    const entry = {
+      id: traceId,
+      name,
+      type: 'enter',
+      args: this.shouldCaptureArgs() ? this.sanitizeArgs(args) : undefined,
+      depth: this.currentDepth,
+      timestamp: Date.now()
+    };
+
+    this.callStack.push(traceId);
+    this.currentDepth++;
+    this.startTimes.set(traceId, performance.now());
+
+    this.addTrace(entry);
+
+    return traceId;
+  }
+
+  /**
+   * Record function exit
+   */
+  exit(name, result) {
+    if (!this.enabled) return;
+    if (this.callStack.length === 0) return;
+
+    const traceId = this.callStack.pop();
+    this.currentDepth = Math.max(0, this.currentDepth - 1);
+
+    const startTime = this.startTimes.get(traceId);
+    const duration = startTime ? performance.now() - startTime : 0;
+    this.startTimes.delete(traceId);
+
+    const entry = {
+      id: traceId,
+      name,
+      type: 'exit',
+      result: this.shouldCaptureResult() ? this.sanitizeValue(result) : undefined,
+      duration,
+      depth: this.currentDepth,
+      timestamp: Date.now()
+    };
+
+    this.addTrace(entry);
+  }
+
+  /**
+   * Record an error
+   */
+  error(name, error) {
+    if (!this.enabled) return;
+
+    const traceId = this.callStack.length > 0 ? this.callStack[this.callStack.length - 1] : this.generateId();
+
+    const entry = {
+      id: traceId,
+      name,
+      type: 'error',
+      error: this.sanitizeError(error),
+      depth: this.currentDepth,
+      timestamp: Date.now()
+    };
+
+    this.addTrace(entry);
+  }
+
+  /**
+   * Record a custom event
+   */
+  event(name, data = {}) {
+    if (!this.enabled) return;
+
+    const entry = {
+      id: this.generateId(),
+      name,
+      type: 'event',
+      data: this.sanitizeValue(data),
+      depth: this.currentDepth,
+      timestamp: Date.now()
+    };
+
+    this.addTrace(entry);
+  }
+
+  /**
+   * Wrap a function with tracing
+   */
+  wrap(fn, name) {
+    if (!this.enabled) return fn;
+
+    const tracer = this;
+    return new Proxy(fn, {
+      apply(target, thisArg, args) {
+        tracer.enter(name || fn.name || 'anonymous', args);
+
+        try {
+          const result = Reflect.apply(target, thisArg, args);
+
+          // Handle promises
+          if (result && typeof result.then === 'function') {
+            return result
+              .then(value => {
+                tracer.exit(name || fn.name || 'anonymous', value);
+                return value;
+              })
+              .catch(error => {
+                tracer.error(name || fn.name || 'anonymous', error);
+                throw error;
+              });
+          }
+
+          tracer.exit(name || fn.name || 'anonymous', result);
+          return result;
+        } catch (error) {
+          tracer.error(name || fn.name || 'anonymous', error);
+          throw error;
+        }
+      }
+    });
+  }
+
+  /**
+   * Add trace to buffer (circular buffer)
+   */
+  addTrace(entry) {
+    if (this.traces.length < this.maxEntries) {
+      this.traces.push(entry);
+    } else {
+      this.traces[this.currentIndex] = entry;
+      this.currentIndex = (this.currentIndex + 1) % this.maxEntries;
+    }
+  }
+
+  /**
+   * Generate unique ID
+   */
+  generateId() {
+    return `t${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Determine if should capture args based on depth level
+   */
+  shouldCaptureArgs() {
+    return this.depth >= 3;
+  }
+
+  /**
+   * Determine if should capture result based on depth level
+   */
+  shouldCaptureResult() {
+    return this.depth >= 2;
+  }
+
+  /**
+   * Sanitize arguments for storage
+   */
+  sanitizeArgs(args) {
+    if (!Array.isArray(args)) return [];
+    return args.map(arg => this.sanitizeValue(arg));
+  }
+
+  /**
+   * Sanitize a value for storage
+   */
+  sanitizeValue(value, maxDepth = 2, currentDepth = 0) {
+    if (currentDepth >= maxDepth) {
+      return '[deep]';
+    }
+
+    if (value === null) return null;
+    if (value === undefined) return undefined;
+
+    const type = typeof value;
+
+    if (type === 'string') {
+      return value.length > 100 ? value.slice(0, 100) + '...' : value;
+    }
+
+    if (type === 'number' || type === 'boolean') {
+      return value;
+    }
+
+    if (type === 'function') {
+      return `[Function: ${value.name || 'anonymous'}]`;
+    }
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) return [];
+      if (value.length > 5) {
+        return [
+          ...value.slice(0, 5).map(v => this.sanitizeValue(v, maxDepth, currentDepth + 1)),
+          `...(${value.length - 5} more)`
+        ];
+      }
+      return value.map(v => this.sanitizeValue(v, maxDepth, currentDepth + 1));
+    }
+
+    if (type === 'object') {
+      if (value instanceof Error) {
+        return this.sanitizeError(value);
+      }
+
+      if (value instanceof Date) {
+        return value.toISOString();
+      }
+
+      // Regular object
+      const keys = Object.keys(value);
+      if (keys.length === 0) return {};
+      if (keys.length > 5) {
+        const result = {};
+        keys.slice(0, 5).forEach(key => {
+          result[key] = this.sanitizeValue(value[key], maxDepth, currentDepth + 1);
+        });
+        result['...'] = `(${keys.length - 5} more)`;
+        return result;
+      }
+
+      const result = {};
+      keys.forEach(key => {
+        result[key] = this.sanitizeValue(value[key], maxDepth, currentDepth + 1);
+      });
+      return result;
+    }
+
+    return String(value).slice(0, 50);
+  }
+
+  /**
+   * Sanitize error object
+   */
+  sanitizeError(error) {
+    if (typeof error === 'string') {
+      return { message: error };
+    }
+
+    return {
+      name: error.name || 'Error',
+      message: error.message || String(error),
+      stack: error.stack ? error.stack.split('\n').slice(0, 3) : undefined
+    };
+  }
+
+  /**
+   * Get summary of traces
+   */
+  getSummary() {
+    const traces = this.getTraces();
+
+    return {
+      total: traces.length,
+      byType: {
+        enter: traces.filter(t => t.type === 'enter').length,
+        exit: traces.filter(t => t.type === 'exit').length,
+        error: traces.filter(t => t.type === 'error').length,
+        event: traces.filter(t => t.type === 'event').length
+      },
+      errors: traces.filter(t => t.type === 'error'),
+      duration: traces.length > 0
+        ? traces[traces.length - 1].timestamp - traces[0].timestamp
+        : 0
+    };
+  }
+
+  /**
+   * Export traces in TOON-friendly format
+   */
+  exportForToon() {
+    const traces = this.getTraces();
+
+    return traces
+      .filter(t => t.type === 'exit' || t.type === 'error')
+      .map(t => ({
+        name: t.name,
+        duration: t.duration,
+        args: t.args,
+        result: t.result,
+        error: t.error
+      }));
+  }
+}
+
+/**
+ * Create and register a global tracer instance
+ * This allows instrumented code to access the tracer via globalThis.__taistTracer
+ * @param {Object} options - Tracer options
+ * @returns {ExecutionTracer}
+ */
+export function createGlobalTracer(options = {}) {
+  const tracer = new ExecutionTracer(options);
+  globalThis.__taistTracer = tracer;
+  return tracer;
+}
+
+/**
+ * Get the global tracer instance
+ * @returns {ExecutionTracer|undefined}
+ */
+export function getGlobalTracer() {
+  return globalThis.__taistTracer;
+}
+
+export default ExecutionTracer;

package/lib/loader-hooks.js

@@ -0,0 +1,71 @@
+/**
+ * Taist Node.js Module Hooks - ESM Loader for code instrumentation
+ *
+ * This file implements Node.js module hooks to instrument code at load time.
+ * Use with: node --import ./lib/loader.js your-script.js
+ *
+ * The hooks intercept module loading and apply AST transformation to add
+ * tracing calls to all functions in the loaded code.
+ */
+
+import { transformCode, defaultShouldInstrument } from './ast-transformer.js';
+import { fileURLToPath } from 'url';
+import { readFile } from 'fs/promises';
+
+/**
+ * Resolve hook - determines how to resolve module specifiers
+ * We use default resolution, just passing through
+ */
+export async function resolve(specifier, context, nextResolve) {
+  return nextResolve(specifier, context);
+}
+
+/**
+ * Load hook - transforms source code before it's executed
+ * This is where we inject instrumentation into the code
+ */
+export async function load(url, context, nextLoad) {
+  // Only process file:// URLs (local files)
+  if (!url.startsWith('file://')) {
+    return nextLoad(url, context);
+  }
+
+  const filePath = fileURLToPath(url);
+
+  // Check if this file should be instrumented
+  if (!defaultShouldInstrument(filePath, { enabled: true })) {
+    return nextLoad(url, context);
+  }
+
+  // Load the original source
+  const result = await nextLoad(url, context);
+
+  // Only transform JavaScript/TypeScript modules
+  if (result.format !== 'module' && result.format !== 'commonjs') {
+    return result;
+  }
+
+  // Get the source code
+  let source;
+  if (result.source) {
+    source = typeof result.source === 'string'
+      ? result.source
+      : new TextDecoder().decode(result.source);
+  } else {
+    // If source isn't provided, read it from the file
+    source = await readFile(filePath, 'utf-8');
+  }
+
+  // Transform the code
+  const transformed = transformCode(source, filePath, { debug: process.env.TAIST_DEBUG });
+
+  if (transformed) {
+    return {
+      ...result,
+      source: transformed.code,
+      shortCircuit: true
+    };
+  }
+
+  return result;
+}

package/lib/loader.js

@@ -0,0 +1,154 @@
+/**
+ * Taist Loader - Entry point for Node.js module instrumentation
+ *
+ * Usage:
+ *   node --import ./lib/loader.js your-script.js
+ *
+ * Or set NODE_OPTIONS:
+ *   NODE_OPTIONS="--import ./lib/loader.js" node your-script.js
+ *
+ * Environment variables:
+ *   TAIST_TRACE_FILE - Path to write traces (required for trace collection)
+ *   TAIST_DEBUG - Enable debug output
+ */
+
+import { register } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+
+// Get the directory of this file
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Register the module hooks
+register('./loader-hooks.js', pathToFileURL(__dirname + '/'));
+
+// Set up the global tracer
+const traces = [];
+const callStack = [];
+
+/**
+ * Safely serialize a value for tracing
+ * Handles circular references and large objects
+ */
+function safeSerialize(value, depth = 0) {
+  if (depth > 2) return '[max depth]';
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (typeof value === 'function') return `[Function: ${value.name || 'anonymous'}]`;
+  if (typeof value === 'symbol') return value.toString();
+  if (typeof value === 'bigint') return value.toString() + 'n';
+  if (typeof value !== 'object') return value;
+
+  // Handle arrays
+  if (Array.isArray(value)) {
+    if (value.length > 5) {
+      return [...value.slice(0, 5).map(v => safeSerialize(v, depth + 1)), `...+${value.length - 5}`];
+    }
+    return value.map(v => safeSerialize(v, depth + 1));
+  }
+
+  // Handle objects
+  try {
+    const keys = Object.keys(value);
+    if (keys.length > 5) {
+      const result = {};
+      keys.slice(0, 5).forEach(k => {
+        result[k] = safeSerialize(value[k], depth + 1);
+      });
+      result['...'] = `+${keys.length - 5} more`;
+      return result;
+    }
+    const result = {};
+    keys.forEach(k => {
+      result[k] = safeSerialize(value[k], depth + 1);
+    });
+    return result;
+  } catch {
+    return '[unserializable]';
+  }
+}
+
+// Install the global tracer
+globalThis.__taistTracer = {
+  enter(name, args) {
+    const startTime = performance.now();
+    callStack.push({ name, startTime, args: safeSerialize(args) });
+  },
+
+  exit(name, result) {
+    const entry = callStack.pop();
+    if (!entry) return;
+
+    const duration = performance.now() - entry.startTime;
+    traces.push({
+      name: entry.name,
+      duration: Math.round(duration * 100) / 100,
+      args: entry.args,
+      result: safeSerialize(result),
+      type: 'exit'
+    });
+  },
+
+  error(name, error) {
+    const entry = callStack.pop();
+    if (!entry) return;
+
+    const duration = performance.now() - entry.startTime;
+    traces.push({
+      name: entry.name,
+      duration: Math.round(duration * 100) / 100,
+      args: entry.args,
+      error: {
+        name: error?.name || 'Error',
+        message: error?.message || String(error)
+      },
+      type: 'error'
+    });
+  },
+
+  getTraces() {
+    return traces;
+  }
+};
+
+// Write traces on process exit
+function writeTraces() {
+  const tracePath = process.env.TAIST_TRACE_FILE;
+  if (!tracePath || traces.length === 0) return;
+
+  try {
+    // Read existing traces and append
+    let existing = [];
+    if (existsSync(tracePath)) {
+      try {
+        existing = JSON.parse(readFileSync(tracePath, 'utf-8'));
+      } catch {
+        existing = [];
+      }
+    }
+    writeFileSync(tracePath, JSON.stringify([...existing, ...traces]));
+
+    if (process.env.TAIST_DEBUG) {
+      console.error(`[taist] Wrote ${traces.length} traces to ${tracePath}`);
+    }
+  } catch (e) {
+    console.error('[taist] Failed to write traces:', e.message);
+  }
+}
+
+// Register exit handlers
+process.on('exit', writeTraces);
+process.on('SIGINT', () => {
+  writeTraces();
+  process.exit(130);
+});
+process.on('SIGTERM', () => {
+  writeTraces();
+  process.exit(143);
+});
+
+if (process.env.TAIST_DEBUG) {
+  console.error('[taist] Loader initialized');
+}