taist 0.1.0 → 0.1.1

package/README.md

@@ -13,6 +13,7 @@ Version: 0.1.0 | January 2025 | [Technical Specification](./SPEC.md)
 5. [Test Integration](#test-integration)
 6. [Configuration Reference](#configuration-reference)
 7. [Usage Examples](#usage-examples)
+8. [TypeScript Support](#typescript-support)
 
 ---
 
@@ -236,6 +237,63 @@ const tracedFn = tracer.wrapMethod(myFunction, 'myFunction');
 - Custom trace collection logic
 - Maximum flexibility needed
 
+### Side-Effect Import vs Direct Function Calls
+
+The `import 'taist/instrument'` side-effect import is **optional**. It provides convenience features but is not required for basic instrumentation.
+
+#### What the Side-Effect Import Does
+
+When you add `import 'taist/instrument'` to your entry point, it:
+
+1. **Creates a global ServiceTracer** - Initialized from environment variables
+2. **Sets up signal handlers** - Outputs trace summary on SIGINT/SIGTERM
+3. **Configures periodic output** - Writes trace summaries at intervals
+4. **Exports a pre-configured `tracer`** - Ready for immediate use
+
+#### When to Use the Side-Effect Import
+
+**Use `import 'taist/instrument'`** when:
+- You want automatic trace output on process shutdown
+- You're instrumenting at application startup
+- You want environment-variable-based configuration
+- You need the global tracer instance
+
+```javascript
+// Entry point - loads global tracer and signal handlers
+import 'taist/instrument';
+import { instrumentExpress, instrumentService } from 'taist/instrument';
+```
+
+#### When to Skip the Side-Effect Import
+
+**Skip the side-effect import** when:
+- You're instrumenting post-startup (e.g., in tests)
+- You want more control over tracer lifecycle
+- You don't want signal handlers registered
+- You're creating multiple independent tracers
+
+```javascript
+// Direct function imports - no side effects
+import { instrumentExpress, instrumentService } from 'taist/instrument';
+
+// Or use the programmatic API for full control
+import { ServiceTracer } from 'taist';
+const tracer = new ServiceTracer({ enabled: true });
+```
+
+#### Post-Startup Instrumentation
+
+The instrumentation functions (`instrumentExpress`, `instrumentService`, etc.) work independently of the side-effect import. You can instrument services after your application has started:
+
+```javascript
+// No side-effect import needed
+import { instrumentService } from 'taist/instrument';
+
+// Instrument a service created dynamically
+const service = new DynamicService();
+const traced = instrumentService(service, 'DynamicService');
+```
+
 ---
 
 ## Test Integration
@@ -310,6 +368,139 @@ session.printTraces({
 });
 ```
 
+### Vitest Reporter Plugin
+
+The taist Vitest reporter replaces Vitest's default output with TOON format and adds execution tracing. When you run `vitest`, you get:
+- Token-optimized test results (90% fewer tokens than default output)
+- Automatic execution traces from instrumented code
+- Call hierarchy with timing, arguments, and return values
+
+#### Step 1: Configure vitest.config.js
+
+```javascript
+// vitest.config.js
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    reporters: ['taist/vitest-reporter']
+  }
+});
+```
+
+#### Step 2: Instrument Your Code
+
+In your test file or setup file, instrument the services you want to trace:
+
+```javascript
+// test/my-service.test.js
+import { describe, it, expect } from 'vitest';
+import { instrumentService } from 'taist/instrument';
+import { UserService } from '../src/user-service.js';
+
+// Wrap the service with instrumentation
+const userService = instrumentService(new UserService(), 'UserService');
+
+describe('UserService', () => {
+  it('should create a user', async () => {
+    // Calls to userService methods are now traced
+    const user = await userService.create({ name: 'Alice' });
+    expect(user.id).toBeDefined();
+  });
+});
+```
+
+#### Step 3: Run Tests
+
+```bash
+vitest run
+```
+
+#### Example Output
+
+```
+===TESTS: 5/5===
+
+============================================================
+TRACE OUTPUT
+============================================================
+Traces: 12 | Requests: 5
+
+--- UserService.create ---
+  fn:UserService.create depth:0 45ms
+    fn:UserService.validate depth:1 5ms
+    fn:UserService.hashPassword depth:1 30ms
+    fn:UserService.save depth:1 10ms
+
+--- UserService.getById ---
+  fn:UserService.getById depth:0 8ms
+    fn:Cache.get depth:1 2ms
+```
+
+#### Reporter Options
+
+```javascript
+export default defineConfig({
+  test: {
+    reporters: [['taist/vitest-reporter', {
+      format: 'toon',        // Output format: 'toon' | 'json' | 'compact'
+      traceEnabled: true,    // Start trace collector (default: true)
+      traceDepth: 3,         // Max depth to trace (default: 3)
+      showTrace: true,       // Include trace output (default: true)
+      maxTraceGroups: 10,    // Max trace groups to show (default: 10)
+      silent: false,         // Suppress all output (default: false)
+      outputFile: null       // Write to file instead of stdout
+    }]]
+  }
+});
+```
+
+#### How Trace Collection Works
+
+1. **Reporter starts** → Creates a TraceCollector (Unix socket server)
+2. **Environment set** → Sets `TAIST_ENABLED=true` and `TAIST_COLLECTOR_SOCKET=/tmp/taist-collector-xxx.sock`
+3. **Tests run** → Instrumented code sends traces to the collector via the socket
+4. **Tests finish** → Reporter collects traces and outputs them with test results
+
+**Note:** Traces are collected from code instrumented with `instrumentService()` or `instrumentExpress()`. Code that isn't instrumented won't appear in the trace output.
+
+#### Using with Test Setup Files
+
+For larger projects, instrument services in a setup file:
+
+```javascript
+// test/setup.js
+import { instrumentService } from 'taist/instrument';
+import { UserService } from '../src/services/user-service.js';
+import { OrderService } from '../src/services/order-service.js';
+
+// Export instrumented services for use in tests
+export const userService = instrumentService(new UserService(), 'UserService');
+export const orderService = instrumentService(new OrderService(), 'OrderService');
+```
+
+```javascript
+// vitest.config.js
+export default defineConfig({
+  test: {
+    reporters: ['taist/vitest-reporter'],
+    setupFiles: ['./test/setup.js']
+  }
+});
+```
+
+```javascript
+// test/user.test.js
+import { userService } from './setup.js';
+
+describe('UserService', () => {
+  it('should get user by id', async () => {
+    const user = await userService.getById(123);
+    expect(user).toBeDefined();
+  });
+});
+```
+
 ### Example Output
 
 When tests complete, you'll see the execution tree grouped by HTTP request:
@@ -461,6 +652,39 @@ npm install --save-dev taist
 
 ---
 
+## TypeScript Support
+
+Taist includes TypeScript type definitions out of the box. No additional `@types` packages needed.
+
+```typescript
+import { Taist, TestResults } from 'taist';
+import { instrumentExpress, instrumentService } from 'taist/instrument';
+import { TraceSession, TraceCollector } from 'taist/testing';
+
+// Full type safety
+const taist = new Taist({ format: 'toon', depth: 3 });
+const results: TestResults = await taist.run();
+
+// Typed instrumentation
+import express from 'express';
+const app = express();
+instrumentExpress(app);
+
+class MyService {
+  getData(): string { return 'data'; }
+}
+const service = instrumentService(new MyService(), 'MyService');
+```
+
+Types are available for all exports:
+- `taist` - Main API (Taist class, TestResults, etc.)
+- `taist/instrument` - Instrumentation functions
+- `taist/testing` - Test utilities (TraceSession, TraceCollector)
+- `taist/vitest-reporter` - Vitest reporter
+- `taist/types` - All types re-exported
+
+---
+
 ## License
 
 MIT License - Open source and free for commercial use

package/instrument.js

@@ -1,11 +1,40 @@
 /**
  * Taist Auto-Instrumentation Module
  *
- * Add this line at the top of your service to enable tracing:
- * import 'taist/instrument';
+ * This module can be used in two ways:
  *
- * Or use require:
- * require('taist/instrument');
+ * 1. SIDE-EFFECT IMPORT (optional):
+ *    Add `import 'taist/instrument';` at the top of your entry point.
+ *    This initializes a global tracer, sets up signal handlers for graceful
+ *    shutdown, and configures periodic trace output based on environment variables.
+ *
+ *    @example
+ *    // Entry point - loads global tracer and signal handlers
+ *    import 'taist/instrument';
+ *    import { instrumentExpress } from 'taist/instrument';
+ *
+ * 2. DIRECT FUNCTION IMPORTS (no side effects):
+ *    Import only the functions you need:
+ *    `import { instrumentExpress, instrumentService } from 'taist/instrument';`
+ *    This is useful for post-startup instrumentation or when you want more
+ *    control over the tracer lifecycle.
+ *
+ *    @example
+ *    // Direct imports for post-startup instrumentation
+ *    import { instrumentService } from 'taist/instrument';
+ *    const traced = instrumentService(myService, 'MyService');
+ *
+ * Environment Variables (used by side-effect import):
+ * - TAIST_ENABLED: Enable/disable tracing (default: true)
+ * - TAIST_DEPTH: Trace depth level (default: 3)
+ * - TAIST_FORMAT: Output format: toon, json, compact (default: toon)
+ * - TAIST_OUTPUT_FILE: Write traces to file instead of stdout
+ * - TAIST_OUTPUT_INTERVAL: Output interval in ms (default: 30000)
+ * - TAIST_INCLUDE: Only trace modules matching patterns (comma-separated)
+ * - TAIST_EXCLUDE: Skip modules matching patterns
+ * - TAIST_SLOW_THRESHOLD: Slow operation threshold in ms (default: 100)
+ *
+ * @module taist/instrument
  */
 
 import { ServiceTracer, autoInstrument } from './lib/service-tracer.js';

package/lib/vitest-reporter.js

@@ -0,0 +1,309 @@
+/**
+ * Vitest TOON Reporter
+ *
+ * A native Vitest reporter that outputs test results in TOON format
+ * with integrated trace collection for execution visibility.
+ *
+ * The reporter automatically:
+ * - Starts a TraceCollector to receive traces from instrumented code
+ * - Sets environment variables so instrumented code can connect
+ * - Collects and outputs execution traces alongside test results
+ *
+ * Usage in vitest.config.js:
+ *   reporters: ['taist/vitest-reporter']
+ *
+ * With options:
+ *   reporters: [['taist/vitest-reporter', { format: 'toon', traceDepth: 3 }]]
+ *
+ * Your test setup should instrument code that will be tested:
+ *   import { instrumentService } from 'taist/instrument';
+ *   const service = instrumentService(new MyService(), 'MyService');
+ */
+
+import { ToonFormatter } from './toon-formatter.js';
+import { TraceCollector } from './trace-collector.js';
+import fs from 'fs';
+
+/**
+ * @typedef {Object} TaistReporterOptions
+ * @property {'toon' | 'json' | 'compact'} [format='toon'] - Output format
+ * @property {boolean} [traceEnabled=true] - Enable execution tracing
+ * @property {number} [traceDepth=3] - Trace depth level
+ * @property {boolean} [showTrace=true] - Include traces in output
+ * @property {boolean} [silent=false] - Suppress output
+ * @property {string | null} [outputFile=null] - Write to file instead of stdout
+ * @property {number} [maxTraceGroups=10] - Max request groups to show in trace output
+ */
+
+export class TaistReporter {
+  /**
+   * @param {TaistReporterOptions} options
+   */
+  constructor(options = {}) {
+    this.options = {
+      format: options.format || 'toon',
+      traceEnabled: options.traceEnabled !== false,
+      traceDepth: options.traceDepth || 3,
+      showTrace: options.showTrace !== false,
+      silent: options.silent || false,
+      outputFile: options.outputFile || null,
+      maxTraceGroups: options.maxTraceGroups || 10,
+      ...options
+    };
+
+    this.formatter = new ToonFormatter(this.options);
+    this.vitest = null;
+    this.startTime = 0;
+    this.collector = null;
+    this.collectorReady = null;
+    this.taskResults = new Map(); // Map task id to result
+    this.results = {
+      stats: { total: 0, passed: 0, failed: 0, skipped: 0 },
+      failures: [],
+      duration: 0,
+      trace: []
+    };
+  }
+
+  /**
+   * Called when Vitest is initialized
+   * @param {import('vitest/node').Vitest} vitest
+   */
+  onInit(vitest) {
+    this.vitest = vitest;
+    this.startTime = performance.now();
+
+    // Start trace collector if tracing is enabled
+    if (this.options.traceEnabled) {
+      this.collector = new TraceCollector({
+        maxTraces: 10000
+      });
+
+      // Start collector and store the promise
+      this.collectorReady = this.collector.start().then(() => {
+        // Set environment variables so instrumented code can connect
+        process.env.TAIST_ENABLED = 'true';
+        process.env.TAIST_DEPTH = String(this.options.traceDepth);
+        process.env.TAIST_COLLECTOR_SOCKET = this.collector.getSocketPath();
+      }).catch(err => {
+        console.error('[taist] Failed to start trace collector:', err.message);
+        this.collector = null;
+      });
+    }
+  }
+
+  /**
+   * Called when task results are updated (Vitest 2.x)
+   * @param {Array} packs - Array of [taskId, result, meta]
+   */
+  onTaskUpdate(packs) {
+    if (!packs) return;
+
+    for (const pack of packs) {
+      const [taskId, result] = pack;
+      if (result) {
+        this.taskResults.set(taskId, result);
+      }
+    }
+  }
+
+  /**
+   * Called when test run finishes (Vitest 2.x)
+   * @param {Array} files - Test files with results
+   * @param {Array} errors - Unhandled errors
+   */
+  async onFinished(files, errors) {
+    this.results.duration = performance.now() - this.startTime;
+
+    // Reset stats
+    this.results.stats = { total: 0, passed: 0, failed: 0, skipped: 0 };
+    this.results.failures = [];
+
+    // Process all test files
+    if (files) {
+      for (const file of files) {
+        this._processFile(file);
+      }
+    }
+
+    // Add unhandled errors as failures
+    if (errors) {
+      for (const error of errors) {
+        this.results.failures.push({
+          test: 'Unhandled Error',
+          error: error.message || String(error),
+          stack: error.stack
+        });
+        this.results.stats.total++;
+        this.results.stats.failed++;
+      }
+    }
+
+    // Collect traces if enabled
+    if (this.options.traceEnabled && this.collector) {
+      // Wait for collector to be ready
+      if (this.collectorReady) {
+        await this.collectorReady;
+      }
+
+      // Give a small delay for any final traces to arrive
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      // Get collected traces
+      if (this.options.showTrace) {
+        this.results.trace = this.collector.getTraces();
+      }
+
+      // Stop the collector
+      await this.collector.stop();
+      this.collector = null;
+    }
+
+    // Output results
+    this._outputResults();
+  }
+
+  /**
+   * Process a test file and its tasks recursively
+   * @private
+   */
+  _processFile(file) {
+    if (file.tasks) {
+      for (const task of file.tasks) {
+        this._processTask(task, file);
+      }
+    }
+  }
+
+  /**
+   * Process a task (test or suite) recursively
+   * @private
+   */
+  _processTask(task, file) {
+    if (task.type === 'test') {
+      this.results.stats.total++;
+
+      const state = task.result?.state;
+      if (state === 'pass') {
+        this.results.stats.passed++;
+      } else if (state === 'fail') {
+        this.results.stats.failed++;
+        this.results.failures.push(this._formatFailure(task, file));
+      } else if (state === 'skip') {
+        this.results.stats.skipped++;
+      }
+    } else if (task.type === 'suite' && task.tasks) {
+      // Process nested tasks
+      for (const subtask of task.tasks) {
+        this._processTask(subtask, file);
+      }
+    }
+  }
+
+  /**
+   * Format a test failure for TOON output
+   * @private
+   */
+  _formatFailure(task, file) {
+    const failure = {
+      test: this._getTestName(task),
+      location: this._getLocation(task, file)
+    };
+
+    const error = task.result?.errors?.[0];
+    if (error) {
+      failure.error = error.message || String(error);
+      failure.stack = error.stack;
+
+      // Extract diff if available
+      if (error.expected !== undefined || error.actual !== undefined) {
+        failure.diff = {
+          expected: error.expected,
+          actual: error.actual
+        };
+      }
+    }
+
+    return failure;
+  }
+
+  /**
+   * Get full test name including suite hierarchy
+   * @private
+   */
+  _getTestName(task) {
+    const names = [];
+    let current = task;
+
+    while (current) {
+      if (current.name && current.type !== 'file') {
+        names.unshift(current.name);
+      }
+      current = current.suite;
+    }
+
+    return names.join(' > ') || task.name;
+  }
+
+  /**
+   * Get test location
+   * @private
+   */
+  _getLocation(task, file) {
+    if (task.location) {
+      return {
+        file: file?.filepath || file?.name || '',
+        line: task.location.line,
+        column: task.location.column
+      };
+    }
+    return file?.filepath || file?.name || '';
+  }
+
+  /**
+   * Output formatted results
+   * @private
+   */
+  _outputResults() {
+    if (this.options.silent) {
+      return;
+    }
+
+    // Format test results
+    let output = this.formatter.format(this.results);
+
+    // Add trace tree if we have traces
+    if (this.options.showTrace && this.results.trace && this.results.trace.length > 0) {
+      output += '\n\n';
+      output += this.formatter.formatTraceTree(this.results.trace, {
+        maxGroups: this.options.maxTraceGroups,
+        showHeader: true
+      });
+    }
+
+    if (this.options.outputFile) {
+      fs.writeFileSync(this.options.outputFile, output);
+    } else {
+      console.log(output);
+    }
+  }
+
+  /**
+   * Get the collected results (for programmatic access)
+   * @returns {Object} Test results
+   */
+  getResults() {
+    return this.results;
+  }
+
+  /**
+   * Get the trace collector socket path (for manual instrumentation setup)
+   * @returns {string|null} Socket path or null if collector not running
+   */
+  getSocketPath() {
+    return this.collector?.getSocketPath() || null;
+  }
+}
+
+// Default export for Vitest reporter configuration
+export default TaistReporter;

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "taist",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Token-Optimized Testing Framework for AI-Assisted Development",
   "main": "index.js",
   "type": "module",
   "bin": {
     "taist": "./taist.js"
   },
+  "types": "./types/index.d.ts",
   "files": [
     "lib/",
+    "types/",
     "index.js",
     "taist.js",
     "instrument.js",
@@ -18,11 +20,28 @@
     ".taistrc.json"
   ],
   "exports": {
-    ".": "./index.js",
-    "./instrument": "./instrument.js",
-    "./testing": "./testing.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./index.js"
+    },
+    "./instrument": {
+      "types": "./types/instrument.d.ts",
+      "default": "./instrument.js"
+    },
+    "./testing": {
+      "types": "./types/testing.d.ts",
+      "default": "./testing.js"
+    },
+    "./vitest-reporter": {
+      "types": "./types/vitest-reporter.d.ts",
+      "default": "./lib/vitest-reporter.js"
+    },
+    "./types": "./types/index.d.ts",
     "./module-patcher": "./lib/module-patcher.js",
-    "./trace-collector": "./lib/trace-collector.js",
+    "./trace-collector": {
+      "types": "./types/trace-collector.d.ts",
+      "default": "./lib/trace-collector.js"
+    },
     "./trace-reporter": "./lib/trace-reporter.js",
     "./trace-context": "./lib/trace-context.js",
     "./instrument-all": "./lib/instrument-all.js",

package/types/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Taist - Token-Optimized Testing Framework
+ * Main type definitions
+ */
+
+// Main entry point exports
+export {
+  Taist,
+  TaistOptions,
+  RunConfig,
+  WatchConfig,
+  TestResults,
+  TestStats,
+  TestFailure,
+  TraceEntry,
+  CoverageInfo,
+  LocationInfo,
+  DiffInfo
+} from './taist';
+
+export { VitestRunner, VitestRunnerOptions } from './vitest-runner';
+export { OutputFormatter, OutputFormatterOptions } from './output-formatter';
+export { WatchHandler, WatchHandlerOptions } from './watch-handler';
+export { ExecutionTracer, ExecutionTracerOptions } from './execution-tracer';
+export {
+  ToonFormatter,
+  ToonFormatterOptions,
+  FormatTraceTreeOptions
+} from './toon-formatter';
+
+// Re-export instrument types
+export * from './instrument';
+
+// Re-export testing types
+export * from './testing';
+
+// Re-export trace-collector types
+export * from './trace-collector';
+
+// Re-export vitest-reporter types
+export { TaistReporter, TaistReporterOptions } from './vitest-reporter';