trickle-observe 0.2.1 → 0.2.3

package/dist/trace-var.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * Variable-level tracing — captures the runtime type and sample value
+ * of variable assignments within function bodies.
+ *
+ * This is injected by the Module._compile source transform. After each
+ * `const/let/var x = expr;` statement, the transform inserts:
+ *
+ *   __trickle_tv(x, 'x', 42, 'my-module', '/path/to/file.ts');
+ *
+ * The traceVar function:
+ * 1. Infers the TypeNode from the runtime value
+ * 2. Captures a sanitized sample value
+ * 3. Appends to .trickle/variables.jsonl
+ * 4. Caches by (file:line:varName + typeHash) to avoid duplicates
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initVarTracer = initVarTracer;
+exports.traceVar = traceVar;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const type_inference_1 = require("./type-inference");
+const type_hash_1 = require("./type-hash");
+/** Where to write variable observations */
+let varsFilePath = '';
+let debugMode = false;
+/** Cache: "file:line:varName:typeHash" → already written */
+const varCache = new Set();
+/** Batch buffer for writing — avoids one fs.appendFileSync per variable */
+let varBuffer = [];
+let flushTimer = null;
+const FLUSH_INTERVAL_MS = 1000;
+const MAX_BUFFER_SIZE = 100;
+/**
+ * Initialize the variable tracer.
+ * Called once during observe-register setup.
+ */
+function initVarTracer(opts = {}) {
+    debugMode = opts.debug === true;
+    const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    varsFilePath = path.join(dir, 'variables.jsonl');
+    if (debugMode) {
+        console.log(`[trickle/vars] Variable tracing enabled → ${varsFilePath}`);
+    }
+}
+/**
+ * Trace a variable's runtime value.
+ * Called by injected code after each variable declaration.
+ *
+ * @param value - The variable's current value (already computed)
+ * @param varName - The variable name in source
+ * @param line - Line number in source file
+ * @param moduleName - Module name (derived from filename)
+ * @param filePath - Absolute path to source file
+ */
+function traceVar(value, varName, line, moduleName, filePath) {
+    // Auto-initialize if not yet done (needed for Vite/Vitest worker processes)
+    if (!varsFilePath) {
+        initVarTracer();
+        if (!varsFilePath)
+            return;
+    }
+    try {
+        const type = (0, type_inference_1.inferType)(value, 3);
+        // Create a stable hash for dedup
+        const dummyArgs = { kind: 'tuple', elements: [] };
+        const typeHash = (0, type_hash_1.hashType)(dummyArgs, type);
+        const cacheKey = `${filePath}:${line}:${varName}:${typeHash}`;
+        if (varCache.has(cacheKey))
+            return;
+        varCache.add(cacheKey);
+        const sample = sanitizeVarSample(value);
+        const observation = {
+            kind: 'variable',
+            varName,
+            line,
+            module: moduleName,
+            file: filePath,
+            type,
+            typeHash,
+            sample,
+        };
+        // Buffer the write
+        varBuffer.push(JSON.stringify(observation));
+        if (varBuffer.length >= MAX_BUFFER_SIZE) {
+            flushVarBuffer();
+        }
+        else if (!flushTimer) {
+            flushTimer = setTimeout(() => {
+                flushVarBuffer();
+            }, FLUSH_INTERVAL_MS);
+            if (flushTimer && typeof flushTimer === 'object' && 'unref' in flushTimer) {
+                flushTimer.unref();
+            }
+        }
+    }
+    catch {
+        // Never crash user's app
+    }
+}
+/**
+ * Flush buffered variable observations to disk.
+ */
+function flushVarBuffer() {
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    if (varBuffer.length === 0)
+        return;
+    const lines = varBuffer.join('\n') + '\n';
+    varBuffer = [];
+    try {
+        fs.appendFileSync(varsFilePath, lines);
+    }
+    catch {
+        // Never crash user's app
+    }
+}
+/**
+ * Sanitize a variable value for safe serialization.
+ * More aggressive truncation than function samples since there are many more variables.
+ */
+function sanitizeVarSample(value, depth = 2) {
+    if (depth <= 0)
+        return '[truncated]';
+    if (value === null || value === undefined)
+        return value;
+    const t = typeof value;
+    if (t === 'string') {
+        const s = value;
+        return s.length > 100 ? s.substring(0, 100) + '...' : s;
+    }
+    if (t === 'number' || t === 'boolean')
+        return value;
+    if (t === 'bigint')
+        return String(value);
+    if (t === 'symbol')
+        return String(value);
+    if (t === 'function')
+        return `[Function: ${value.name || 'anonymous'}]`;
+    if (Array.isArray(value)) {
+        return value.slice(0, 3).map(item => sanitizeVarSample(item, depth - 1));
+    }
+    if (t === 'object') {
+        if (value instanceof Date)
+            return value.toISOString();
+        if (value instanceof RegExp)
+            return String(value);
+        if (value instanceof Error)
+            return { error: value.message };
+        if (value instanceof Map)
+            return `[Map: ${value.size} entries]`;
+        if (value instanceof Set)
+            return `[Set: ${value.size} items]`;
+        if (value instanceof Promise)
+            return '[Promise]';
+        const obj = value;
+        const result = {};
+        const keys = Object.keys(obj).slice(0, 10);
+        for (const key of keys) {
+            try {
+                result[key] = sanitizeVarSample(obj[key], depth - 1);
+            }
+            catch {
+                result[key] = '[unreadable]';
+            }
+        }
+        return result;
+    }
+    return String(value);
+}
+// Flush on process exit — use 'exit' event (synchronous, fires even on process.exit())
+// because Vitest workers and forked processes may exit without 'beforeExit'.
+// flushVarBuffer uses fs.appendFileSync so it's safe in the 'exit' handler.
+if (typeof process !== 'undefined' && process.on) {
+    const exitFlush = () => { flushVarBuffer(); };
+    process.on('exit', exitFlush);
+    process.on('beforeExit', exitFlush);
+    process.on('SIGTERM', exitFlush);
+    process.on('SIGINT', exitFlush);
+}

package/dist/transport.js

@@ -202,8 +202,12 @@ function silentError() {
 }
 // Register process exit handler to flush remaining events
 if (typeof process !== 'undefined' && process.on) {
+    let flushing = false;
     process.on('beforeExit', () => {
-        flush().catch(silentError);
+        if (flushing || queue.length === 0)
+            return;
+        flushing = true;
+        flush().catch(silentError).finally(() => { flushing = false; stopTimer(); });
     });
     // SIGTERM / SIGINT: attempt a sync-ish flush
     const exitHandler = () => {

package/dist/type-inference.js

@@ -167,10 +167,18 @@ function inferArray(arr, depth, seen) {
     }
     return { kind: 'array', element: unifyTypes(elementTypes) };
 }
+const MAX_PROPERTIES = 20;
 function inferPlainObject(obj, depth, seen) {
     const properties = {};
     const keys = Object.keys(obj);
-    for (const key of keys) {
+    // Skip internal/private properties (common in Node.js built-in objects like
+    // http.Server, streams, etc.) — they make generated types unusably verbose.
+    const publicKeys = keys.filter(k => !k.startsWith('_'));
+    // If filtering removed everything, use all keys (it's a plain data object with _ keys)
+    const effectiveKeys = publicKeys.length > 0 ? publicKeys : keys;
+    // Cap the number of properties to keep types manageable
+    const cappedKeys = effectiveKeys.slice(0, MAX_PROPERTIES);
+    for (const key of cappedKeys) {
         try {
             properties[key] = infer(obj[key], depth - 1, seen);
         }

package/dist/vite-plugin.d.ts

@@ -2,8 +2,9 @@
  * Vite plugin for trickle observation.
  *
  * Integrates into Vite's (and Vitest's) transform pipeline to wrap
- * user functions with trickle observation — the same thing observe-register.ts
- * does for Node's Module._compile, but for Vite/Vitest.
+ * user functions with trickle observation AND trace variable assignments —
+ * the same thing observe-register.ts does for Node's Module._compile,
+ * but for Vite/Vitest.
  *
  * Usage in vitest.config.ts:
  *
@@ -25,6 +26,8 @@ export interface TricklePluginOptions {
     backendUrl?: string;
     /** Enable debug logging */
     debug?: boolean;
+    /** Disable variable tracing (default: enabled) */
+    traceVars?: boolean;
 }
 export declare function tricklePlugin(options?: TricklePluginOptions): {
     name: string;