taist 1.1.0

package/lib/traced.js

@@ -0,0 +1,223 @@
+/**
+ * Taist Traced - Seamless integration testing helpers for Vitest
+ *
+ * Spawns child processes with tracing enabled, automatically merging
+ * traces into the main Vitest trace output.
+ *
+ * Usage:
+ *   import { traced } from 'taist/lib/traced.js';
+ *
+ *   const result = await traced.run('./my-script.js', ['--arg']);
+ *   expect(result.exitCode).toBe(0);
+ *   // Traces automatically appear in TOON output - no manual inspection needed
+ */
+
+import { spawn } from 'node:child_process';
+import { writeFileSync, readFileSync, existsSync, appendFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const loaderPath = resolve(__dirname, 'loader.js');
+
+/**
+ * Get the shared trace file path from Vitest environment
+ * Falls back to creating a temp file if not in Vitest context
+ */
+function getTraceFilePath() {
+  // Use the same trace file as Vitest workers
+  if (process.env.TAIST_TRACE_FILE) {
+    return process.env.TAIST_TRACE_FILE;
+  }
+
+  // Fallback for standalone usage
+  const path = join(tmpdir(), `taist-integration-${Date.now()}.json`);
+  if (!existsSync(path)) {
+    writeFileSync(path, '[]');
+  }
+  return path;
+}
+
+/**
+ * Merge traces from a child process into the main trace file
+ */
+function mergeTraces(childTraceFile, mainTraceFile) {
+  try {
+    if (!existsSync(childTraceFile)) return;
+
+    const childTraces = JSON.parse(readFileSync(childTraceFile, 'utf-8'));
+    if (childTraces.length === 0) return;
+
+    let mainTraces = [];
+    if (existsSync(mainTraceFile)) {
+      try {
+        mainTraces = JSON.parse(readFileSync(mainTraceFile, 'utf-8'));
+      } catch {
+        mainTraces = [];
+      }
+    }
+
+    writeFileSync(mainTraceFile, JSON.stringify([...mainTraces, ...childTraces]));
+  } catch (e) {
+    // Silently fail - traces are optional
+  }
+}
+
+/**
+ * Run a Node.js script with tracing, merging traces into Vitest output
+ *
+ * @param {string} scriptPath - Path to the script to run
+ * @param {string[]} args - Arguments to pass to the script
+ * @param {Object} options - Options
+ * @returns {Promise<{ stdout: string, stderr: string, exitCode: number }>}
+ */
+async function run(scriptPath, args = [], options = {}) {
+  const mainTraceFile = getTraceFilePath();
+  const childTraceFile = join(tmpdir(), `taist-child-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  writeFileSync(childTraceFile, '[]');
+
+  const env = {
+    ...process.env,
+    ...options.env,
+    TAIST_TRACE_FILE: childTraceFile,
+    NODE_OPTIONS: `--import ${loaderPath} ${process.env.NODE_OPTIONS || ''}`.trim()
+  };
+
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn('node', [scriptPath, ...args], {
+      cwd: options.cwd || process.cwd(),
+      env,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => { stdout += data.toString(); });
+    child.stderr.on('data', (data) => { stderr += data.toString(); });
+
+    child.on('error', reject);
+
+    child.on('close', (exitCode) => {
+      // Small delay for trace file to be written
+      setTimeout(() => {
+        mergeTraces(childTraceFile, mainTraceFile);
+        try { existsSync(childTraceFile) && require('fs').unlinkSync(childTraceFile); } catch {}
+
+        resolvePromise({
+          stdout,
+          stderr,
+          exitCode: exitCode ?? 0
+        });
+      }, 50);
+    });
+  });
+}
+
+/**
+ * Execute any command with tracing (for Node.js commands)
+ */
+async function exec(command, args = [], options = {}) {
+  const mainTraceFile = getTraceFilePath();
+  const childTraceFile = join(tmpdir(), `taist-child-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  writeFileSync(childTraceFile, '[]');
+
+  const env = {
+    ...process.env,
+    ...options.env,
+    TAIST_TRACE_FILE: childTraceFile,
+    NODE_OPTIONS: `--import ${loaderPath} ${process.env.NODE_OPTIONS || ''}`.trim()
+  };
+
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd || process.cwd(),
+      env,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => { stdout += data.toString(); });
+    child.stderr.on('data', (data) => { stderr += data.toString(); });
+
+    child.on('error', reject);
+
+    child.on('close', (exitCode) => {
+      setTimeout(() => {
+        mergeTraces(childTraceFile, mainTraceFile);
+        try { existsSync(childTraceFile) && require('fs').unlinkSync(childTraceFile); } catch {}
+
+        resolvePromise({
+          stdout,
+          stderr,
+          exitCode: exitCode ?? 0
+        });
+      }, 50);
+    });
+  });
+}
+
+/**
+ * Start a long-running service with tracing
+ * Returns control functions to manage the service lifecycle
+ */
+function serve(scriptPath, args = [], options = {}) {
+  const mainTraceFile = getTraceFilePath();
+  const childTraceFile = join(tmpdir(), `taist-service-${Date.now()}.json`);
+  writeFileSync(childTraceFile, '[]');
+
+  const env = {
+    ...process.env,
+    ...options.env,
+    TAIST_TRACE_FILE: childTraceFile,
+    NODE_OPTIONS: `--import ${loaderPath} ${process.env.NODE_OPTIONS || ''}`.trim()
+  };
+
+  const child = spawn('node', [scriptPath, ...args], {
+    cwd: options.cwd || process.cwd(),
+    env,
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+
+  let stdout = '';
+  let stderr = '';
+
+  child.stdout.on('data', (data) => { stdout += data.toString(); });
+  child.stderr.on('data', (data) => { stderr += data.toString(); });
+
+  return {
+    /** The underlying child process */
+    process: child,
+
+    /** Get current stdout */
+    get stdout() { return stdout; },
+
+    /** Get current stderr */
+    get stderr() { return stderr; },
+
+    /** Wait for output to contain a string (e.g., "Server listening") */
+    async waitFor(text, timeout = 5000) {
+      const start = Date.now();
+      while (Date.now() - start < timeout) {
+        if (stdout.includes(text) || stderr.includes(text)) return true;
+        await new Promise(r => setTimeout(r, 100));
+      }
+      throw new Error(`Timeout waiting for "${text}"`);
+    },
+
+    /** Stop the service and merge traces */
+    async stop() {
+      child.kill('SIGTERM');
+      await new Promise(r => setTimeout(r, 100));
+      mergeTraces(childTraceFile, mainTraceFile);
+      try { existsSync(childTraceFile) && require('fs').unlinkSync(childTraceFile); } catch {}
+    }
+  };
+}
+
+export const traced = { run, exec, serve };
+export default traced;

package/lib/tracer-setup.js

@@ -0,0 +1,115 @@
+/**
+ * Vitest setup file for execution tracing
+ * This runs in the worker context before tests, setting up the global tracer
+ */
+
+// Simple tracer that collects execution traces
+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]';
+  }
+}
+
+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;
+  }
+};
+
+// Export traces at the end of all tests via afterAll hook
+if (typeof afterAll === 'function') {
+  afterAll(async () => {
+    if (traces.length > 0) {
+      // Write traces to the file specified by TAIST_TRACE_FILE env var
+      const tracePath = process.env.TAIST_TRACE_FILE;
+      if (tracePath) {
+        const fs = await import('fs');
+        try {
+          // Read existing traces and append
+          let existing = [];
+          if (fs.existsSync(tracePath)) {
+            existing = JSON.parse(fs.readFileSync(tracePath, 'utf-8'));
+          }
+          fs.writeFileSync(tracePath, JSON.stringify([...existing, ...traces]));
+        } catch (e) {
+          console.error('[taist] Failed to write traces:', e.message);
+        }
+      }
+    }
+  });
+}

package/lib/vitest-plugin.js

@@ -0,0 +1,138 @@
+/**
+ * Taist Vitest Plugin - Code instrumentation for execution tracing
+ *
+ * This plugin integrates with Vite/Vitest to transform source code at build time,
+ * injecting tracer calls at function entry/exit points.
+ *
+ * Captures:
+ * - Function entry with arguments
+ * - Return values
+ * - Thrown errors
+ * - Execution timing
+ */
+
+import { transformCode, defaultShouldInstrument } from './ast-transformer.js';
+import { writeFileSync, readFileSync, existsSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+// Trace file path for cross-process communication
+let traceFilePath = null;
+
+/**
+ * Initialize trace collection file
+ * @returns {string} Path to the trace file
+ */
+export function initTraceFile() {
+  traceFilePath = join(tmpdir(), `taist-traces-${Date.now()}.json`);
+  writeFileSync(traceFilePath, '[]');
+  return traceFilePath;
+}
+
+/**
+ * Get collected traces from the trace file
+ * @returns {Array} Array of trace entries
+ */
+export function getCollectedTraces() {
+  if (!traceFilePath || !existsSync(traceFilePath)) {
+    return [];
+  }
+  try {
+    const content = readFileSync(traceFilePath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Clean up trace file
+ */
+export function cleanupTraceFile() {
+  if (traceFilePath && existsSync(traceFilePath)) {
+    try {
+      unlinkSync(traceFilePath);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+  traceFilePath = null;
+}
+
+/**
+ * Get trace file path
+ * @returns {string|null}
+ */
+export function getTraceFilePath() {
+  return traceFilePath;
+}
+
+// Legacy functions for compatibility
+export function setGlobalTracer(tracer) {
+  globalThis.__taistTracer = tracer;
+}
+
+export function getGlobalTracer() {
+  return globalThis.__taistTracer;
+}
+
+/**
+ * Check if a file should be instrumented (Vitest-specific version)
+ * @param {string} id - File path
+ * @param {Object} options - Plugin options
+ * @returns {boolean}
+ */
+function shouldInstrument(id, options) {
+  if (!options.enabled) return false;
+
+  // Use default filter as base
+  if (!defaultShouldInstrument(id, options)) {
+    return false;
+  }
+
+  // Additional Vitest-specific exclusions
+  if (id.includes('vitest-plugin') || id.includes('execution-tracer') || id.includes('tracer-setup')) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Create the Taist Vitest plugin for code instrumentation
+ * @param {Object} options - Plugin options
+ * @param {boolean} options.enabled - Whether instrumentation is enabled
+ * @param {number} options.depth - Trace depth level (1-5)
+ * @returns {import('vite').Plugin}
+ */
+export function taistPlugin(options = {}) {
+  const pluginOptions = {
+    enabled: true,
+    depth: 2,
+    ...options
+  };
+
+  return {
+    name: 'taist-tracer',
+    enforce: 'pre',
+
+    transform(code, id) {
+      if (!shouldInstrument(id, pluginOptions)) {
+        return null;
+      }
+
+      const result = transformCode(code, id, { debug: pluginOptions.debug });
+
+      if (result) {
+        return {
+          code: result.code,
+          map: result.map
+        };
+      }
+
+      return null;
+    }
+  };
+}
+
+export default taistPlugin;