taist 0.1.9 → 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.8 | 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()` |
 
@@ -321,6 +322,86 @@ This is particularly useful for:
 - 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taist",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Token-Optimized Testing Framework for AI-Assisted Development",
   "main": "index.js",
   "type": "module",