taist 1.1.0

package/lib/output-formatter.js

@@ -0,0 +1,151 @@
+/**
+ * Output Formatter - Multi-format test result formatter
+ * Supports TOON, JSON, and Compact output formats
+ */
+
+import { ToonFormatter } from './toon-formatter.js';
+
+export class OutputFormatter {
+  constructor(options = {}) {
+    this.formatType = options.format || 'toon';
+    this.options = options;
+    this.toonFormatter = new ToonFormatter(options);
+  }
+
+  /**
+   * Format test results based on configured format
+   * @param {Object} results - Test results object
+   * @returns {string} - Formatted output
+   */
+  format(results) {
+    switch (this.formatType.toLowerCase()) {
+      case 'toon':
+        return this.formatToon(results);
+      case 'json':
+        return this.formatJson(results);
+      case 'compact':
+        return this.formatCompact(results);
+      default:
+        throw new Error(`Unknown format: ${this.formatType}. Use: toon, json, or compact`);
+    }
+  }
+
+  /**
+   * Format as TOON
+   */
+  formatToon(results) {
+    return this.toonFormatter.format(results);
+  }
+
+  /**
+   * Format as JSON
+   */
+  formatJson(results) {
+    const output = {
+      status: this.determineStatus(results),
+      stats: results.stats || {
+        total: 0,
+        passed: 0,
+        failed: 0,
+        skipped: 0
+      },
+      failures: (results.failures || []).map(f => this.formatFailureForJson(f)),
+      trace: results.trace || [],
+      coverage: results.coverage || null,
+      duration: results.duration || 0,
+      timestamp: new Date().toISOString()
+    };
+
+    return JSON.stringify(output, null, this.options.pretty ? 2 : 0);
+  }
+
+  /**
+   * Format as compact one-liner
+   */
+  formatCompact(results) {
+    const stats = results.stats || {};
+    const passed = stats.passed || 0;
+    const total = stats.total || 0;
+    const failed = stats.failed || 0;
+
+    const status = failed === 0 ? '✓' : '✗';
+    const parts = [`${status} ${passed}/${total}`];
+
+    if (failed > 0) {
+      parts.push(`${failed} fail`);
+      if (results.failures && results.failures.length > 0) {
+        const firstError = results.failures[0];
+        const errorMsg = this.extractErrorMessage(firstError);
+        parts.push(`(${errorMsg})`);
+      }
+    }
+
+    if (results.coverage) {
+      parts.push(`cov:${Math.round(results.coverage.percent)}%`);
+    }
+
+    if (results.duration) {
+      parts.push(`${Math.round(results.duration)}ms`);
+    }
+
+    return parts.join(' ');
+  }
+
+  /**
+   * Determine overall status
+   */
+  determineStatus(results) {
+    const stats = results.stats || {};
+    if (stats.failed > 0) return 'fail';
+    if (stats.passed === 0 && stats.total === 0) return 'empty';
+    return 'pass';
+  }
+
+  /**
+   * Format failure for JSON output
+   */
+  formatFailureForJson(failure) {
+    return {
+      test: failure.test || failure.name,
+      error: this.extractErrorMessage(failure),
+      location: failure.location || null,
+      diff: failure.diff || null,
+      stack: this.formatStackForJson(failure.stack),
+      path: failure.path || null
+    };
+  }
+
+  /**
+   * Extract error message
+   */
+  extractErrorMessage(failure) {
+    if (failure.error) {
+      if (typeof failure.error === 'string') return failure.error;
+      if (failure.error.message) return failure.error.message;
+      return String(failure.error);
+    }
+    return 'Unknown error';
+  }
+
+  /**
+   * Format stack trace for JSON
+   */
+  formatStackForJson(stack) {
+    if (!stack) return null;
+    if (typeof stack === 'string') {
+      return stack.split('\n')
+        .filter(line => line.trim())
+        .slice(0, 5);
+    }
+    return stack;
+  }
+
+  /**
+   * Set format type
+   */
+  setFormat(format) {
+    this.formatType = format;
+  }
+}
+
+export default OutputFormatter;

package/lib/spawn-traced.js

@@ -0,0 +1,204 @@
+/**
+ * Taist Spawn Helper - Run child processes with execution tracing
+ *
+ * Provides utilities for spawning Node.js processes with instrumentation
+ * enabled, collecting traces, and integrating with test frameworks.
+ *
+ * Usage:
+ *   import { spawnTraced, execTraced } from 'taist/spawn-traced';
+ *
+ *   const { traces, stdout, stderr, exitCode } = await execTraced('node', ['my-script.js']);
+ *   console.log(traces); // Array of execution traces
+ */
+
+import { spawn, execFile } from 'node:child_process';
+import { writeFileSync, readFileSync, unlinkSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Get the directory of this file to find the loader
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const loaderPath = resolve(__dirname, 'loader.js');
+
+/**
+ * Create a temporary file for trace collection
+ * @returns {{ path: string, cleanup: () => void }}
+ */
+function createTraceFile() {
+  const path = join(tmpdir(), `taist-trace-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  writeFileSync(path, '[]');
+  return {
+    path,
+    cleanup: () => {
+      try {
+        if (existsSync(path)) unlinkSync(path);
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  };
+}
+
+/**
+ * Read traces from a trace file
+ * @param {string} path - Path to trace file
+ * @returns {Array} Array of trace entries
+ */
+function readTraces(path) {
+  try {
+    if (!existsSync(path)) return [];
+    const content = readFileSync(path, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Execute a Node.js script with tracing enabled
+ * Returns a promise that resolves when the process exits
+ *
+ * @param {string} command - Command to run (usually 'node')
+ * @param {string[]} args - Arguments to pass
+ * @param {Object} options - Options
+ * @param {string} options.cwd - Working directory
+ * @param {Object} options.env - Additional environment variables
+ * @param {boolean} options.debug - Enable debug output
+ * @param {number} options.timeout - Timeout in milliseconds
+ * @returns {Promise<{ traces: Array, stdout: string, stderr: string, exitCode: number }>}
+ */
+export async function execTraced(command, args = [], options = {}) {
+  const traceFile = createTraceFile();
+
+  const env = {
+    ...process.env,
+    ...options.env,
+    TAIST_TRACE_FILE: traceFile.path,
+    NODE_OPTIONS: `--import ${loaderPath} ${process.env.NODE_OPTIONS || ''}`.trim()
+  };
+
+  if (options.debug) {
+    env.TAIST_DEBUG = '1';
+  }
+
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd || process.cwd(),
+      env,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let timeoutId;
+
+    if (options.timeout) {
+      timeoutId = setTimeout(() => {
+        child.kill('SIGTERM');
+        reject(new Error(`Process timed out after ${options.timeout}ms`));
+      }, options.timeout);
+    }
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('error', (error) => {
+      if (timeoutId) clearTimeout(timeoutId);
+      traceFile.cleanup();
+      reject(error);
+    });
+
+    child.on('close', (exitCode) => {
+      if (timeoutId) clearTimeout(timeoutId);
+
+      // Give a small delay for trace file to be written
+      setTimeout(() => {
+        const traces = readTraces(traceFile.path);
+        traceFile.cleanup();
+
+        resolvePromise({
+          traces,
+          stdout,
+          stderr,
+          exitCode: exitCode ?? 0
+        });
+      }, 50);
+    });
+  });
+}
+
+/**
+ * Spawn a Node.js process with tracing enabled
+ * Returns the child process immediately (for streaming output)
+ *
+ * @param {string} command - Command to run
+ * @param {string[]} args - Arguments
+ * @param {Object} options - Spawn options
+ * @returns {{ child: ChildProcess, getTraces: () => Array, cleanup: () => void }}
+ */
+export function spawnTraced(command, args = [], options = {}) {
+  const traceFile = createTraceFile();
+
+  const env = {
+    ...process.env,
+    ...options.env,
+    TAIST_TRACE_FILE: traceFile.path,
+    NODE_OPTIONS: `--import ${loaderPath} ${process.env.NODE_OPTIONS || ''}`.trim()
+  };
+
+  if (options.debug) {
+    env.TAIST_DEBUG = '1';
+  }
+
+  const child = spawn(command, args, {
+    ...options,
+    env,
+    stdio: options.stdio || 'pipe'
+  });
+
+  return {
+    child,
+    getTraces: () => readTraces(traceFile.path),
+    cleanup: () => traceFile.cleanup()
+  };
+}
+
+/**
+ * Run a Node.js script file with tracing
+ * Convenience wrapper for execTraced('node', [scriptPath, ...args])
+ *
+ * @param {string} scriptPath - Path to the script to run
+ * @param {string[]} args - Arguments to pass to the script
+ * @param {Object} options - Options (same as execTraced)
+ * @returns {Promise<{ traces: Array, stdout: string, stderr: string, exitCode: number }>}
+ */
+export async function runTraced(scriptPath, args = [], options = {}) {
+  return execTraced('node', [scriptPath, ...args], options);
+}
+
+/**
+ * Create a test helper for integration testing
+ * Returns functions pre-configured for a specific working directory
+ *
+ * @param {string} cwd - Working directory for the tests
+ * @returns {{ run: Function, exec: Function, spawn: Function }}
+ */
+export function createTestHelper(cwd) {
+  return {
+    run: (scriptPath, args, options) =>
+      runTraced(scriptPath, args, { ...options, cwd }),
+    exec: (command, args, options) =>
+      execTraced(command, args, { ...options, cwd }),
+    spawn: (command, args, options) =>
+      spawnTraced(command, args, { ...options, cwd })
+  };
+}
+
+export default { execTraced, spawnTraced, runTraced, createTestHelper };

package/lib/toon-formatter.js

@@ -0,0 +1,351 @@
+/**
+ * TOON Formatter - Token-Optimized Output Notation
+ * Converts test results to a token-efficient format for AI consumption
+ */
+
+export class ToonFormatter {
+  constructor(options = {}) {
+    this.options = {
+      abbreviate: options.abbreviate !== false,
+      maxTokens: options.maxTokens || 1000,
+      maxStringLength: options.maxStringLength || 50,
+      maxStackFrames: options.maxStackFrames || 2,
+      maxObjectKeys: options.maxObjectKeys || 3,
+      maxArrayItems: options.maxArrayItems || 2,
+      ...options
+    };
+
+    // Abbreviation dictionary
+    this.abbrev = {
+      function: 'fn',
+      error: 'err',
+      expected: 'exp',
+      received: 'got',
+      actual: 'got',
+      undefined: 'undef',
+      null: 'nil',
+      test: 'tst',
+      testing: 'tst',
+      passed: 'pass',
+      failed: 'fail',
+      arguments: 'args',
+      return: 'ret',
+      result: 'ret',
+      message: 'msg',
+      location: 'loc',
+      line: 'ln',
+      column: 'col'
+    };
+  }
+
+  /**
+   * Format test results in TOON format
+   * @param {Object} results - Test results object
+   * @returns {string} - Formatted TOON output
+   */
+  format(results) {
+    const lines = [];
+
+    // Header
+    lines.push(this.formatHeader(results));
+
+    // Failures
+    if (results.failures && results.failures.length > 0) {
+      lines.push('');
+      lines.push('FAILURES:');
+      results.failures.forEach(failure => {
+        lines.push(...this.formatFailure(failure));
+      });
+    }
+
+    // Trace
+    if (results.trace && results.trace.length > 0) {
+      lines.push('');
+      lines.push('TRACE:');
+      results.trace.forEach(entry => {
+        lines.push(this.formatTraceEntry(entry));
+      });
+    }
+
+    // Coverage
+    if (results.coverage) {
+      lines.push('');
+      lines.push(this.formatCoverage(results.coverage));
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Format test result header
+   */
+  formatHeader(results) {
+    const passed = results.stats?.passed || 0;
+    const total = results.stats?.total || 0;
+    return `===TESTS: ${passed}/${total}===`;
+  }
+
+  /**
+   * Format a single test failure
+   */
+  formatFailure(failure) {
+    const lines = [];
+
+    // Test name
+    lines.push(`✗ ${this.truncate(failure.test || failure.name)}`);
+
+    // Location
+    if (failure.location) {
+      lines.push(`  @${this.formatLocation(failure.location)}`);
+    }
+
+    // Error message
+    if (failure.error) {
+      const msg = this.cleanErrorMessage(failure.error);
+      lines.push(`  ${msg}`);
+    }
+
+    // Expected vs Actual
+    if (failure.diff) {
+      if (failure.diff.expected !== undefined) {
+        lines.push(`  exp: ${this.formatValue(failure.diff.expected)}`);
+      }
+      if (failure.diff.actual !== undefined) {
+        lines.push(`  got: ${this.formatValue(failure.diff.actual)}`);
+      }
+    }
+
+    // Execution path
+    if (failure.path) {
+      lines.push(`  path: ${this.formatPath(failure.path)}`);
+    }
+
+    // Stack trace (abbreviated)
+    if (failure.stack && this.options.maxStackFrames > 0) {
+      const stack = this.formatStack(failure.stack);
+      if (stack) {
+        lines.push(`  ${stack}`);
+      }
+    }
+
+    return lines;
+  }
+
+  /**
+   * Format trace entry
+   */
+  formatTraceEntry(entry) {
+    const parts = [`fn:${entry.name}`];
+
+    if (entry.duration !== undefined) {
+      parts.push(`ms:${Math.round(entry.duration)}`);
+    }
+
+    if (entry.args && entry.args.length > 0) {
+      const args = entry.args
+        .slice(0, this.options.maxArrayItems)
+        .map(arg => this.formatValue(arg))
+        .join(',');
+      parts.push(`args:[${args}]`);
+    }
+
+    if (entry.result !== undefined) {
+      parts.push(`ret:${this.formatValue(entry.result)}`);
+    }
+
+    if (entry.error) {
+      parts.push(`err:${this.cleanErrorMessage(entry.error)}`);
+    }
+
+    return `  ${parts.join(' ')}`;
+  }
+
+  /**
+   * Format coverage information
+   */
+  formatCoverage(coverage) {
+    const percent = Math.round(coverage.percent || 0);
+    const covered = coverage.covered || 0;
+    const total = coverage.total || 0;
+    return `COV: ${percent}% (${covered}/${total})`;
+  }
+
+  /**
+   * Format a location reference
+   */
+  formatLocation(location) {
+    if (typeof location === 'string') {
+      return this.abbreviatePath(location);
+    }
+
+    const file = this.abbreviatePath(location.file || '');
+    const line = location.line || '';
+    const col = location.column || '';
+
+    if (col) {
+      return `${file}:${line}:${col}`;
+    } else if (line) {
+      return `${file}:${line}`;
+    }
+    return file;
+  }
+
+  /**
+   * Format an execution path
+   */
+  formatPath(path) {
+    if (Array.isArray(path)) {
+      return path
+        .map(step => {
+          if (typeof step === 'string') return step;
+          if (step.fn && step.result !== undefined) {
+            return `${step.fn}(...)→${this.formatValue(step.result)}`;
+          }
+          return step.fn || String(step);
+        })
+        .join('→');
+    }
+    return String(path);
+  }
+
+  /**
+   * Format a value for output
+   */
+  formatValue(value) {
+    if (value === null) return 'nil';
+    if (value === undefined) return 'undef';
+
+    const type = typeof value;
+
+    if (type === 'string') {
+      return `"${this.truncate(value)}"`;
+    }
+
+    if (type === 'number' || type === 'boolean') {
+      return String(value);
+    }
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) return '[]';
+      const items = value
+        .slice(0, this.options.maxArrayItems)
+        .map(v => this.formatValue(v))
+        .join(',');
+      const more = value.length > this.options.maxArrayItems
+        ? `...+${value.length - this.options.maxArrayItems}`
+        : '';
+      return `[${items}${more}]`;
+    }
+
+    if (type === 'object') {
+      const keys = Object.keys(value).slice(0, this.options.maxObjectKeys);
+      if (keys.length === 0) return '{}';
+      const more = Object.keys(value).length > this.options.maxObjectKeys
+        ? '...'
+        : '';
+      return `{${keys.join(',')}${more}}`;
+    }
+
+    return String(value).slice(0, 20);
+  }
+
+  /**
+   * Format stack trace
+   */
+  formatStack(stack) {
+    if (typeof stack === 'string') {
+      const lines = stack.split('\n')
+        .filter(line => line.trim() && !line.includes('node_modules'))
+        .slice(0, this.options.maxStackFrames);
+
+      return lines
+        .map(line => {
+          // Extract file:line:col from stack frame
+          const match = line.match(/\((.+):(\d+):(\d+)\)/) ||
+                       line.match(/at (.+):(\d+):(\d+)/);
+          if (match) {
+            const [, file, line, col] = match;
+            return `@${this.abbreviatePath(file)}:${line}`;
+          }
+          return line.trim().slice(0, 50);
+        })
+        .join(' ');
+    }
+    return '';
+  }
+
+  /**
+   * Clean error message
+   */
+  cleanErrorMessage(error) {
+    if (typeof error === 'object' && error.message) {
+      error = error.message;
+    }
+
+    let msg = String(error);
+
+    // Remove ANSI codes
+    msg = msg.replace(/\u001b\[\d+m/g, '');
+
+    // Remove timestamps
+    msg = msg.replace(/\[\d{2}:\d{2}:\d{2}\]/g, '');
+
+    // Remove absolute paths
+    msg = msg.replace(/\/[^\s]+\//g, match => {
+      const parts = match.split('/');
+      return parts[parts.length - 1] || match;
+    });
+
+    // Truncate
+    msg = this.truncate(msg);
+
+    return msg;
+  }
+
+  /**
+   * Abbreviate file path
+   */
+  abbreviatePath(path) {
+    if (!path) return '';
+
+    // Remove common prefixes
+    path = path.replace(/^.*\/node_modules\//, 'npm/');
+    path = path.replace(/^.*\/src\//, 'src/');
+    path = path.replace(/^.*\/test\//, 'test/');
+    path = path.replace(/^.*\/lib\//, 'lib/');
+
+    // Get just filename if still too long
+    if (path.length > 30) {
+      const parts = path.split('/');
+      path = parts[parts.length - 1];
+    }
+
+    return path;
+  }
+
+  /**
+   * Truncate string
+   */
+  truncate(str, maxLength = this.options.maxStringLength) {
+    if (!str) return '';
+    str = String(str);
+    if (str.length <= maxLength) return str;
+    return str.slice(0, maxLength - 3) + '...';
+  }
+
+  /**
+   * Apply abbreviations
+   */
+  abbreviate(text) {
+    if (!this.options.abbreviate) return text;
+
+    let result = text;
+    for (const [full, abbr] of Object.entries(this.abbrev)) {
+      const regex = new RegExp(`\\b${full}\\b`, 'gi');
+      result = result.replace(regex, abbr);
+    }
+    return result;
+  }
+}
+
+export default ToonFormatter;