taist 0.1.8 → 0.1.10

package/README.md

@@ -1,7 +1,7 @@
 # Taist - AI Test Runner
 ## Token-Optimized Testing Framework for AI-Assisted Development
 
-Version: 0.1.0 | January 2025 | [Technical Specification](./SPEC.md)
+Version: 0.1.9 | January 2025 | [Technical Specification](./SPEC.md)
 
 ---
 
@@ -135,6 +135,7 @@ tracer.instrument(MyClass, 'MyClass');
 | Method | Use Case | Setup |
 |--------|----------|-------|
 | **ESM Loader** | Node.js apps, automatic tracing | `node --import taist/module-patcher app.js` |
+| **Build-Time** | Bundled apps (Directus, Vite) | `taist/vite-plugin` in build config |
 | **Import-based** | Express apps, selective tracing | `import 'taist/instrument'` |
 | **Programmatic** | Full control, multiple tracers | `new ServiceTracer()` |
 
@@ -294,6 +295,113 @@ const service = new DynamicService();
 const traced = instrumentService(service, 'DynamicService');
 ```
 
+#### Module-Level Instrumentation
+
+When you have a module with multiple exported functions or classes, use `instrumentModule` to wrap all exports at once:
+
+```javascript
+import { instrumentModule } from 'taist/instrument';
+import * as orderServices from './services/order.js';
+
+// Wrap all exports from the module
+export const Order = instrumentModule(orderServices, 'Order');
+
+// Now all functions in Order are traced:
+// Order.createOrder() → traced as "Order.createOrder"
+// Order.getOrder()    → traced as "Order.getOrder"
+// Order.updateOrder() → traced as "Order.updateOrder"
+```
+
+This is particularly useful for:
+- **GraphQL resolvers** - Instrument all resolver functions in a module
+- **Service layers** - Wrap entire service modules without individual instrumentation
+- **Utility modules** - Trace helper functions across a module
+
+**How it works:**
+- Functions are wrapped with context-aware tracing
+- Classes are wrapped so new instances are automatically instrumented
+- Non-function exports are passed through unchanged
+
+### Build-Time Instrumentation (Bundled Apps)
+
+For applications that bundle their code (like Directus extensions, Vite apps, etc.), runtime instrumentation can't see inside the bundle. Use the **Rollup/Vite plugin** to instrument during build instead.
+
+**The Problem:**
+```
+src/order.js  ─┐
+src/user.js   ─┼─► Bundler ─► dist/bundle.js (one file)
+src/utils.js  ─┘
+                                    ↑
+                    ESM loader only sees this one module
+```
+
+**The Solution:** Instrument source files BEFORE bundling:
+```
+src/order.js  ─► instrument ─┐
+src/user.js   ─► instrument ─┼─► Bundler ─► dist/bundle.js
+src/utils.js  ─► instrument ─┘              (instrumented!)
+```
+
+#### Vite Configuration
+
+```javascript
+// vite.config.js
+import { defineConfig } from 'vite';
+import taistPlugin from 'taist/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    taistPlugin({
+      include: ['src/**/*.js', 'src/**/*.ts'],
+      exclude: ['**/*.test.js']
+    })
+  ],
+  build: {
+    rollupOptions: {
+      // Keep taist as external - it's a runtime dependency
+      external: ['taist/lib/trace-reporter.js', 'taist/lib/trace-context.js']
+    }
+  }
+});
+```
+
+#### Rollup Configuration
+
+```javascript
+// rollup.config.js
+import taistPlugin from 'taist/rollup-plugin';
+
+export default {
+  input: 'src/index.js',
+  output: { file: 'dist/bundle.js', format: 'es' },
+  plugins: [
+    taistPlugin({
+      include: ['src/**/*.js']
+    })
+  ],
+  external: ['taist/lib/trace-reporter.js', 'taist/lib/trace-context.js']
+};
+```
+
+#### Plugin Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `include` | `string[]` | `['src/**/*.js']` | Glob patterns for files to instrument |
+| `exclude` | `string[]` | `['**/node_modules/**']` | Glob patterns to skip |
+| `enabled` | `boolean` | `true` | Enable/disable (respects `TAIST_ENABLED` env) |
+
+**When to use:**
+- Directus extensions
+- Vite/Rollup bundled applications
+- Any code that gets bundled before deployment
+- When ESM loader can't intercept your modules
+
+**Runtime requirements:**
+- `taist` must be installed as a dependency of the host application
+- Set `TAIST_ENABLED=true` and `TAIST_COLLECTOR_SOCKET` at runtime
+- The built code will send traces to the collector when executed
+
 ---
 
 ## Test Integration

package/lib/rollup-plugin.js

@@ -0,0 +1,120 @@
+/**
+ * Taist Rollup Plugin - Build-time instrumentation for bundled code
+ *
+ * Transforms source files during build to add tracing, BEFORE bundling
+ * collapses them into a single file. This enables deep tracing of internal
+ * functions within bundled applications.
+ *
+ * Usage:
+ *   import taistPlugin from 'taist/rollup-plugin';
+ *
+ *   export default {
+ *     plugins: [
+ *       taistPlugin({
+ *         include: ['src/**\/*.js'],
+ *         exclude: ['**\/*.test.js']
+ *       })
+ *     ]
+ *   };
+ */
+
+import { transformSource } from './transform.js';
+import { shouldInstrument, matchGlob, loadConfig } from './config-loader.js';
+import path from 'node:path';
+
+/**
+ * Create a Taist Rollup plugin
+ * @param {Object} options - Plugin options
+ * @param {string[]} [options.include] - Glob patterns for files to instrument
+ * @param {string[]} [options.exclude] - Glob patterns for files to skip
+ * @param {boolean} [options.enabled] - Enable/disable plugin (default: true, or TAIST_ENABLED env)
+ * @returns {import('rollup').Plugin}
+ */
+export function taistPlugin(options = {}) {
+  // Determine if enabled
+  const enabled = options.enabled ?? (process.env.TAIST_ENABLED !== 'false');
+
+  if (!enabled) {
+    return {
+      name: 'taist',
+      // No-op plugin when disabled
+    };
+  }
+
+  // Build config from options or load from file
+  let config;
+
+  return {
+    name: 'taist',
+
+    async buildStart() {
+      if (options.include || options.exclude) {
+        // Use provided options
+        config = {
+          include: options.include || ['**/*.js', '**/*.ts'],
+          exclude: options.exclude || ['**/node_modules/**', '**/*.test.*', '**/*.spec.*'],
+        };
+      } else {
+        // Load from .taistrc.json
+        config = await loadConfig();
+        if (config.include.length === 0) {
+          // Default to instrumenting src/ if no config
+          config.include = ['src/**/*.js', 'src/**/*.ts'];
+        }
+      }
+    },
+
+    transform(code, id) {
+      // Skip if no config yet
+      if (!config) {
+        return null;
+      }
+
+      // Skip node_modules
+      if (id.includes('node_modules')) {
+        return null;
+      }
+
+      // Skip non-JS/TS files
+      if (!id.match(/\.[jt]sx?$/)) {
+        return null;
+      }
+
+      // Get relative path for matching
+      const relativePath = path.relative(process.cwd(), id);
+
+      // Check include patterns
+      const included = config.include.some(pattern => matchGlob(relativePath, pattern));
+      if (!included) {
+        return null;
+      }
+
+      // Check exclude patterns
+      const excluded = config.exclude.some(pattern => matchGlob(relativePath, pattern));
+      if (excluded) {
+        return null;
+      }
+
+      try {
+        // Transform the source
+        const transformed = transformSource(code, {
+          filename: id,
+          useReporter: true,
+          // Use package paths - these should be externalized or bundled with the app
+          traceReporterPath: null, // Uses default 'taist/lib/trace-reporter.js'
+          traceContextPath: null,  // Uses default 'taist/lib/trace-context.js'
+        });
+
+        return {
+          code: transformed,
+          map: null, // TODO: Add sourcemap support
+        };
+      } catch (err) {
+        this.warn(`Failed to transform ${relativePath}: ${err.message}`);
+        return null;
+      }
+    },
+  };
+}
+
+export default taistPlugin;

package/lib/transform.js

@@ -242,10 +242,18 @@ const __taist_module = "${moduleName}";
 
   let transformed = shebang + injection + sourceWithoutShebang;
 
-  // Rename original exports
-  for (const exp of exports) {
+  // Separate classes from functions - classes need different handling to preserve hoisting
+  const classExports = exports.filter(e => e.type === "class");
+  const functionExports = exports.filter(e => e.type !== "class");
+
+  // For CLASSES: Keep original export, instrument in-place (preserves hoisting)
+  // This avoids TDZ issues with circular dependencies
+  // We'll add __taist_instrumentClass() calls at the end instead of re-exporting
+
+  // For FUNCTIONS: Rename and re-export (original behavior)
+  for (const exp of functionExports) {
     if (exp.declaration === "inline") {
-      // Inline exports: export function/class/const Name
+      // Inline exports: export function/const Name
       if (exp.type === "function") {
         // Rename: export function foo -> function __taist_orig_foo
         transformed = transformed.replace(
@@ -261,23 +269,10 @@ const __taist_module = "${moduleName}";
           new RegExp(`export\\s+const\\s+${exp.name}\\s*=`, "g"),
           `const __taist_orig_${exp.name} =`
         );
-      } else if (exp.type === "class") {
-        // Rename: export class Foo -> class __taist_orig_Foo
-        transformed = transformed.replace(
-          new RegExp(`export\\s+class\\s+${exp.name}\\b`, "g"),
-          `class __taist_orig_${exp.name}`
-        );
       }
     } else if (exp.declaration === "named") {
-      // Named exports: class Foo {...} then export { Foo }
-      // Rename the declaration (not the export)
-      if (exp.type === "class") {
-        // Rename: class Foo -> class __taist_orig_Foo (handles extends)
-        transformed = transformed.replace(
-          new RegExp(`\\bclass\\s+${exp.name}\\s*(extends\\s+\\w+\\s*)?([{<])`, "g"),
-          (match, ext, brace) => `class __taist_orig_${exp.name} ${ext || ''}${brace}`
-        );
-      } else if (exp.type === "function") {
+      // Named exports: function foo {...} then export { foo }
+      if (exp.type === "function") {
         // Rename: function foo -> function __taist_orig_foo
         transformed = transformed.replace(
           new RegExp(`\\bfunction\\s+${exp.name}\\s*\\(`, "g"),
@@ -292,10 +287,10 @@ const __taist_module = "${moduleName}";
     }
   }
 
-  // Remove named export statements that we're replacing
+  // Remove named export statements for FUNCTIONS we're replacing (not classes)
   // Match: export { Name1, Name2 } and remove names we're wrapping
-  const namedExportNames = exports.filter(e => e.declaration === "named").map(e => e.name);
-  if (namedExportNames.length > 0) {
+  const namedFunctionExportNames = functionExports.filter(e => e.declaration === "named").map(e => e.name);
+  if (namedFunctionExportNames.length > 0) {
     transformed = transformed.replace(
       /export\s*\{([^}]+)\}/g,
       (match, names) => {
@@ -303,7 +298,7 @@ const __taist_module = "${moduleName}";
           .map(n => n.trim())
           .filter(n => {
             const name = n.split(/\s+as\s+/)[0].trim();
-            return !namedExportNames.includes(name);
+            return !namedFunctionExportNames.includes(name);
           });
         if (remaining.length === 0) {
           return '// export moved to end';
@@ -313,11 +308,12 @@ const __taist_module = "${moduleName}";
     );
   }
 
-  // Track default exports that need to be moved to after re-exports
+  // Track default exports for FUNCTIONS that need to be moved to after re-exports
   const defaultExports = [];
 
-  // Remove `export default Name;` from original location (will add after re-exports)
-  for (const exp of exports) {
+  // Remove `export default Name;` from original location for FUNCTIONS only
+  // (Classes keep their default export in place)
+  for (const exp of functionExports) {
     // Match: export default Name;
     if (transformed.match(new RegExp(`export\\s+default\\s+${exp.name}\\s*;`))) {
       transformed = transformed.replace(
@@ -336,22 +332,34 @@ const __taist_module = "${moduleName}";
     }
   }
 
-  // Add wrapped re-exports at the end
+  // Add wrapped re-exports for FUNCTIONS at the end
   // Only add module prefix if it differs from export name to avoid "Calculator.Calculator"
-  const reexports = exports
+  const functionReexports = functionExports
     .map((exp) => {
       const nameExpr = `(__taist_module === "${exp.name}" ? "${exp.name}" : __taist_module + ".${exp.name}")`;
-      if (exp.type === "class") {
-        // Classes use instrument() to wrap prototype methods
-        return `export const ${exp.name} = __taist_instrumentClass(__taist_orig_${exp.name}, ${nameExpr});`;
-      } else {
-        // Functions use wrapMethod()
-        return `export const ${exp.name} = __taist_wrap(__taist_orig_${exp.name}, ${nameExpr});`;
-      }
+      // Functions use wrapMethod()
+      return `export const ${exp.name} = __taist_wrap(__taist_orig_${exp.name}, ${nameExpr});`;
     })
     .join("\n");
 
-  transformed += `\n\n// --- TAIST WRAPPED EXPORTS ---\n${reexports}\n`;
+  // Add in-place instrumentation for CLASSES (preserves hoisting/TDZ)
+  // __taist_instrumentClass mutates the prototype in-place
+  const classInstrumentations = classExports
+    .map((exp) => {
+      const nameExpr = `(__taist_module === "${exp.name}" ? "${exp.name}" : __taist_module + ".${exp.name}")`;
+      return `__taist_instrumentClass(${exp.name}, ${nameExpr});`;
+    })
+    .join("\n");
+
+  transformed += `\n\n// --- TAIST INSTRUMENTATION ---\n`;
+
+  if (functionReexports) {
+    transformed += `// Wrapped function exports\n${functionReexports}\n`;
+  }
+
+  if (classInstrumentations) {
+    transformed += `// In-place class instrumentation (preserves hoisting)\n${classInstrumentations}\n`;
+  }
 
   // Add default exports at the end (after the wrapped versions are defined)
   for (const name of defaultExports) {

package/lib/vite-plugin.js

@@ -0,0 +1,22 @@
+/**
+ * Taist Vite Plugin - Build-time instrumentation for bundled code
+ *
+ * Vite uses Rollup under the hood, so this re-exports the Rollup plugin.
+ *
+ * Usage:
+ *   import taistPlugin from 'taist/vite-plugin';
+ *
+ *   export default defineConfig({
+ *     plugins: [
+ *       taistPlugin({
+ *         include: ['src/**\/*.js'],
+ *         exclude: ['**\/*.test.js']
+ *       })
+ *     ]
+ *   });
+ */
+
+import { taistPlugin } from './rollup-plugin.js';
+
+export { taistPlugin };
+export default taistPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taist",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Token-Optimized Testing Framework for AI-Assisted Development",
   "main": "index.js",
   "type": "module",
@@ -46,6 +46,14 @@
     "./trace-context": "./lib/trace-context.js",
     "./instrument-all": "./lib/instrument-all.js",
     "./config-loader": "./lib/config-loader.js",
+    "./rollup-plugin": {
+      "types": "./types/rollup-plugin.d.ts",
+      "default": "./lib/rollup-plugin.js"
+    },
+    "./vite-plugin": {
+      "types": "./types/vite-plugin.d.ts",
+      "default": "./lib/vite-plugin.js"
+    },
     "./lib/*": "./lib/*"
   },
   "scripts": {

package/types/rollup-plugin.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Taist Rollup Plugin Type Definitions
+ */
+
+import type { Plugin } from 'rollup';
+
+/**
+ * Options for the Taist Rollup/Vite plugin
+ */
+export interface TaistPluginOptions {
+  /**
+   * Glob patterns for files to instrument.
+   * If not provided, loads from .taistrc.json or defaults to ['src/**\/*.js', 'src/**\/*.ts']
+   */
+  include?: string[];
+
+  /**
+   * Glob patterns for files to skip.
+   * Defaults to ['**\/node_modules/**', '**\/*.test.*', '**\/*.spec.*']
+   */
+  exclude?: string[];
+
+  /**
+   * Enable/disable the plugin.
+   * Defaults to true, or respects TAIST_ENABLED environment variable.
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Create a Taist Rollup plugin for build-time instrumentation.
+ *
+ * Transforms source files during build to add tracing, BEFORE bundling
+ * collapses them into a single file. This enables deep tracing of internal
+ * functions within bundled applications like Directus extensions.
+ *
+ * @param options - Plugin options
+ * @returns Rollup plugin
+ *
+ * @example
+ * // rollup.config.js
+ * import taistPlugin from 'taist/rollup-plugin';
+ *
+ * export default {
+ *   input: 'src/index.js',
+ *   output: { file: 'dist/bundle.js', format: 'es' },
+ *   plugins: [
+ *     taistPlugin({
+ *       include: ['src/**\/*.js'],
+ *       exclude: ['**\/*.test.js']
+ *     })
+ *   ]
+ * };
+ */
+export function taistPlugin(options?: TaistPluginOptions): Plugin;
+
+export default taistPlugin;

package/types/vite-plugin.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Taist Vite Plugin Type Definitions
+ *
+ * Re-exports the Rollup plugin types since Vite uses Rollup internally.
+ */
+
+import type { Plugin } from 'vite';
+import type { TaistPluginOptions } from './rollup-plugin';
+
+export type { TaistPluginOptions };
+
+/**
+ * Create a Taist Vite plugin for build-time instrumentation.
+ *
+ * Transforms source files during build to add tracing, BEFORE bundling
+ * collapses them into a single file. This enables deep tracing of internal
+ * functions within bundled applications like Directus extensions.
+ *
+ * @param options - Plugin options
+ * @returns Vite plugin
+ *
+ * @example
+ * // vite.config.js
+ * import { defineConfig } from 'vite';
+ * import taistPlugin from 'taist/vite-plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     taistPlugin({
+ *       include: ['src/**\/*.js'],
+ *       exclude: ['**\/*.test.js']
+ *     })
+ *   ]
+ * });
+ */
+export function taistPlugin(options?: TaistPluginOptions): Plugin;
+
+export default taistPlugin;