trickle-observe 0.2.2 → 0.2.3

package/dist/observe-register.js

@@ -37,6 +37,8 @@ const transport_1 = require("./transport");
 const env_detect_1 = require("./env-detect");
 const wrap_1 = require("./wrap");
 const fetch_observer_1 = require("./fetch-observer");
+const express_1 = require("./express");
+const trace_var_1 = require("./trace-var");
 const M = module_1.default;
 const originalLoad = M._load;
 const originalCompile = M.prototype._compile;
@@ -159,6 +161,228 @@ function findClosingBrace(source, openBrace) {
  * which is critical for entry files where functions are defined and used
  * in the same top-level scope.
  */
+/**
+ * Find variable declarations in source and return insertions for tracing.
+ * Handles: const x = ...; let x = ...; var x = ...;
+ * Skips: destructuring, for-loop vars, require() calls, imports.
+ */
+function findVarDeclarations(source) {
+    const varInsertions = [];
+    // Match: const/let/var <identifier> = <something>
+    // We look for lines containing a simple variable declaration with an assignment
+    const varRegex = /^([ \t]*)(const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=[^=]/gm;
+    let vmatch;
+    while ((vmatch = varRegex.exec(source)) !== null) {
+        const varName = vmatch[3];
+        // Skip common noise
+        if (varName === '__trickle_mod' || varName === '__trickle_wrap' || varName === '__trickle_tv')
+            continue;
+        if (varName.startsWith('__trickle'))
+            continue;
+        if (varName === '_a' || varName === '_b' || varName === '_c')
+            continue; // TS compiled vars
+        // Check if this is a require() call — skip those (they're imports, not interesting values)
+        const restOfLine = source.slice(vmatch.index + vmatch[0].length - 1, vmatch.index + vmatch[0].length + 200);
+        if (/^\s*require\s*\(/.test(restOfLine))
+            continue;
+        // Calculate line number (count newlines before this position)
+        let lineNo = 1;
+        for (let i = 0; i < vmatch.index; i++) {
+            if (source[i] === '\n')
+                lineNo++;
+        }
+        // Find the end of this statement — look for the semicolon at depth 0
+        // or the end of the line for semicolon-free code
+        const startPos = vmatch.index + vmatch[0].length - 1; // position of the '='
+        let pos = startPos;
+        let depth = 0;
+        let foundEnd = -1;
+        while (pos < source.length) {
+            const ch = source[pos];
+            if (ch === '(' || ch === '[' || ch === '{') {
+                depth++;
+            }
+            else if (ch === ')' || ch === ']' || ch === '}') {
+                depth--;
+                if (depth < 0)
+                    break; // we've gone past our scope
+            }
+            else if (ch === ';' && depth === 0) {
+                foundEnd = pos;
+                break;
+            }
+            else if (ch === '\n' && depth === 0) {
+                // For semicolon-free code, the newline is the end
+                // But only if the next non-whitespace isn't a continuation (., +, etc.)
+                const nextNonWs = source.slice(pos + 1).match(/^\s*(\S)/);
+                if (nextNonWs && !'.+=-|&?:,'.includes(nextNonWs[1])) {
+                    foundEnd = pos;
+                    break;
+                }
+            }
+            else if (ch === '"' || ch === "'" || ch === '`') {
+                // Skip strings
+                const quote = ch;
+                pos++;
+                while (pos < source.length) {
+                    if (source[pos] === '\\') {
+                        pos++;
+                    }
+                    else if (source[pos] === quote)
+                        break;
+                    pos++;
+                }
+            }
+            else if (ch === '/' && pos + 1 < source.length && source[pos + 1] === '/') {
+                // Skip line comment
+                while (pos < source.length && source[pos] !== '\n')
+                    pos++;
+                continue;
+            }
+            else if (ch === '/' && pos + 1 < source.length && source[pos + 1] === '*') {
+                // Skip block comment
+                pos += 2;
+                while (pos < source.length - 1 && !(source[pos] === '*' && source[pos + 1] === '/'))
+                    pos++;
+                pos++;
+            }
+            pos++;
+        }
+        if (foundEnd === -1)
+            continue; // couldn't find statement end
+        varInsertions.push({ lineEnd: foundEnd + 1, varName, lineNo });
+    }
+    return varInsertions;
+}
+/**
+ * Find destructured variable declarations: const { a, b } = ... and const [a, b] = ...
+ */
+function findDestructuredDeclarations(source) {
+    const results = [];
+    const destructRegex = /^[ \t]*(?:export\s+)?(?:const|let|var)\s+(\{[^}]*\}|\[[^\]]*\])\s*(?::\s*[^=]+?)?\s*=[^=]/gm;
+    let match;
+    while ((match = destructRegex.exec(source)) !== null) {
+        const pattern = match[1];
+        const varNames = extractDestructuredNames(pattern);
+        if (varNames.length === 0)
+            continue;
+        const restOfLine = source.slice(match.index + match[0].length - 1, match.index + match[0].length + 200);
+        if (/^\s*require\s*\(/.test(restOfLine))
+            continue;
+        let lineNo = 1;
+        for (let i = 0; i < match.index; i++) {
+            if (source[i] === '\n')
+                lineNo++;
+        }
+        const startPos = match.index + match[0].length - 1;
+        let pos = startPos;
+        let depth = 0;
+        let foundEnd = -1;
+        while (pos < source.length) {
+            const ch = source[pos];
+            if (ch === '(' || ch === '[' || ch === '{') {
+                depth++;
+            }
+            else if (ch === ')' || ch === ']' || ch === '}') {
+                depth--;
+                if (depth < 0)
+                    break;
+            }
+            else if (ch === ';' && depth === 0) {
+                foundEnd = pos;
+                break;
+            }
+            else if (ch === '\n' && depth === 0) {
+                const nextNonWs = source.slice(pos + 1).match(/^\s*(\S)/);
+                if (nextNonWs && !'.+=-|&?:,'.includes(nextNonWs[1])) {
+                    foundEnd = pos;
+                    break;
+                }
+            }
+            else if (ch === '"' || ch === "'" || ch === '`') {
+                const quote = ch;
+                pos++;
+                while (pos < source.length) {
+                    if (source[pos] === '\\') {
+                        pos++;
+                    }
+                    else if (source[pos] === quote)
+                        break;
+                    pos++;
+                }
+            }
+            else if (ch === '/' && pos + 1 < source.length && source[pos + 1] === '/') {
+                while (pos < source.length && source[pos] !== '\n')
+                    pos++;
+                continue;
+            }
+            else if (ch === '/' && pos + 1 < source.length && source[pos + 1] === '*') {
+                pos += 2;
+                while (pos < source.length - 1 && !(source[pos] === '*' && source[pos + 1] === '/'))
+                    pos++;
+                pos++;
+            }
+            pos++;
+        }
+        if (foundEnd === -1)
+            continue;
+        results.push({ lineEnd: foundEnd + 1, varNames, lineNo });
+    }
+    return results;
+}
+/**
+ * Extract variable names from a destructuring pattern.
+ * { a, b, c: d } → ['a', 'b', 'd'], [a, b, ...rest] → ['a', 'b', 'rest']
+ */
+function extractDestructuredNames(pattern) {
+    const names = [];
+    const inner = pattern.slice(1, -1).trim();
+    if (!inner)
+        return names;
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of inner) {
+        if (ch === '{' || ch === '[')
+            depth++;
+        else if (ch === '}' || ch === ']')
+            depth--;
+        else if (ch === ',' && depth === 0) {
+            parts.push(current.trim());
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    for (const part of parts) {
+        if (part.startsWith('...')) {
+            const restName = part.slice(3).trim().split(/[\s:]/)[0];
+            if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(restName))
+                names.push(restName);
+            continue;
+        }
+        const colonIdx = part.indexOf(':');
+        if (colonIdx !== -1) {
+            const afterColon = part.slice(colonIdx + 1).trim();
+            if (afterColon.startsWith('{') || afterColon.startsWith('[')) {
+                names.push(...extractDestructuredNames(afterColon));
+            }
+            else {
+                const localName = afterColon.split(/[\s=]/)[0].trim();
+                if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(localName))
+                    names.push(localName);
+            }
+        }
+        else {
+            const name = part.split(/[\s=]/)[0].trim();
+            if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name))
+                names.push(name);
+        }
+    }
+    return names;
+}
 function transformCjsSource(source, filename, moduleName, env) {
     const funcRegex = /^[ \t]*(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
     const insertions = [];
@@ -191,12 +415,16 @@ function transformCjsSource(source, filename, moduleName, env) {
             continue;
         insertions.push({ position: closeBrace + 1, name, paramNames });
     }
-    if (insertions.length === 0)
+    // Also find variable declarations for tracing
+    const varTraceEnabled = process.env.TRICKLE_TRACE_VARS !== '0';
+    const varInsertions = varTraceEnabled ? findVarDeclarations(source) : [];
+    const destructInsertions = varTraceEnabled ? findDestructuredDeclarations(source) : [];
+    if (insertions.length === 0 && varInsertions.length === 0 && destructInsertions.length === 0)
         return source;
     // Resolve the path to the wrap helper (compiled JS)
     const wrapHelperPath = path_1.default.join(__dirname, 'wrap.js');
     // Prepend: load the wrapper and create the wrap helper
-    const prefix = [
+    const prefixLines = [
         `var __trickle_mod = require(${JSON.stringify(wrapHelperPath)});`,
         `var __trickle_wrap = function(fn, name, paramNames) {`,
         `  var opts = {`,
@@ -205,22 +433,47 @@ function transformCjsSource(source, filename, moduleName, env) {
         `    trackArgs: true,`,
         `    trackReturn: true,`,
         `    sampleRate: 1,`,
-        `    maxDepth: 5,`,
+        `    maxDepth: 3,`,
         `    environment: ${JSON.stringify(env)},`,
         `    enabled: true,`,
         `  };`,
         `  if (paramNames && paramNames.length) opts.paramNames = paramNames;`,
         `  return __trickle_mod.wrapFunction(fn, opts);`,
         `};`,
-        '',
-    ].join('\n');
-    // Insert wrapper calls immediately after each function body (reverse order to preserve positions)
-    let result = source;
-    for (let i = insertions.length - 1; i >= 0; i--) {
-        const { position, name, paramNames } = insertions[i];
+    ];
+    // Add variable tracing helper if we have var insertions
+    if (varInsertions.length > 0 || destructInsertions.length > 0) {
+        const traceVarPath = path_1.default.join(__dirname, 'trace-var.js');
+        prefixLines.push(`var __trickle_tv_mod = require(${JSON.stringify(traceVarPath)});`, `var __trickle_tv = function(v, n, l) { try { __trickle_tv_mod.traceVar(v, n, l, ${JSON.stringify(moduleName)}, ${JSON.stringify(filename)}); } catch(e){} };`);
+    }
+    prefixLines.push('');
+    const prefix = prefixLines.join('\n');
+    const allInsertions = [];
+    for (const { position, name, paramNames } of insertions) {
         const paramNamesArg = paramNames.length > 0 ? JSON.stringify(paramNames) : 'null';
-        const wrapperCall = `\ntry{${name}=__trickle_wrap(${name},'${name}',${paramNamesArg})}catch(__e){}\n`;
-        result = result.slice(0, position) + wrapperCall + result.slice(position);
+        allInsertions.push({
+            position,
+            code: `\ntry{${name}=__trickle_wrap(${name},'${name}',${paramNamesArg})}catch(__e){}\n`,
+        });
+    }
+    for (const { lineEnd, varName, lineNo } of varInsertions) {
+        allInsertions.push({
+            position: lineEnd,
+            code: `\ntry{__trickle_tv(${varName},${JSON.stringify(varName)},${lineNo})}catch(__e){}\n`,
+        });
+    }
+    for (const { lineEnd, varNames, lineNo } of destructInsertions) {
+        const calls = varNames.map(n => `__trickle_tv(${n},${JSON.stringify(n)},${lineNo})`).join(';');
+        allInsertions.push({
+            position: lineEnd,
+            code: `\n;try{${calls}}catch(__e){}\n`,
+        });
+    }
+    // Sort by position descending (insert from end to preserve earlier positions)
+    allInsertions.sort((a, b) => b.position - a.position);
+    let result = source;
+    for (const { position, code } of allInsertions) {
+        result = result.slice(0, position) + code + result.slice(position);
     }
     return prefix + result;
 }
@@ -259,8 +512,12 @@ if (enabled) {
     if (debug) {
         console.log(`[trickle/observe] Auto-observation enabled (backend: ${backendUrl})`);
     }
-    // ── Hook 0: Patch global.fetch to capture HTTP response types ──
+    // ── Hook 0a: Patch global.fetch to capture HTTP response types ──
     (0, fetch_observer_1.patchFetch)(environment, debug);
+    // ── Hook 0b: Initialize variable tracer ──
+    if (process.env.TRICKLE_TRACE_VARS !== '0') {
+        (0, trace_var_1.initVarTracer)({ debug });
+    }
     // ── Hook 1: Module._compile — transform source to wrap function declarations ──
     // This catches ALL functions including entry file and non-exported helpers.
     M.prototype._compile = function hookedCompile(content, filename) {
@@ -296,13 +553,79 @@ if (enabled) {
     // Still useful for wrapping exports that use inline function expressions
     // (e.g. module.exports = { foo: function() {} }).
     // The double-wrap guard in wrapFunction prevents redundant wrapping.
+    // Track whether we've already patched Express to avoid double-patching
+    const expressPatched = new Set();
     M._load = function hookedLoad(request, parent, isMain) {
         const exports = originalLoad.apply(this, arguments);
-        // Only process user modules (relative paths)
-        if (!request.startsWith('.') && !request.startsWith('/')) {
-            return exports;
+        // ── Express auto-detection: wrap Express factory to capture route types ──
+        // When someone requires 'express', wrap the factory so every app.get/post/etc
+        // automatically captures { body, params, query } → res.json() type data.
+        if (request === 'express' && !expressPatched.has('express')) {
+            expressPatched.add('express');
+            try {
+                const origExpress = exports;
+                const wrappedExpress = function (...args) {
+                    const app = origExpress.apply(this, args);
+                    // Tag the app so we can verify the middleware was injected
+                    app.__trickle_instrumented = true;
+                    try {
+                        // Wrap route methods for future route definitions
+                        (0, express_1.instrumentExpress)(app, { environment });
+                        // Also inject middleware to capture routes defined BEFORE instrumentation
+                        // (common in DI/class-based architectures where routes are defined in constructors)
+                        if (typeof app.use === 'function') {
+                            app.use((0, express_1.trickleMiddleware)({ environment }));
+                            if (debug) {
+                                console.log('[trickle/observe] Injected trickleMiddleware into Express app');
+                            }
+                        }
+                        if (debug) {
+                            console.log('[trickle/observe] Auto-instrumented Express app (route types will be captured)');
+                        }
+                    }
+                    catch (e) {
+                        if (debug) {
+                            console.log('[trickle/observe] Express instrumentation error:', e.message);
+                        }
+                    }
+                    return app;
+                };
+                // Copy all static properties (express.json, express.static, express.Router, etc.)
+                for (const key of Object.keys(origExpress)) {
+                    wrappedExpress[key] = origExpress[key];
+                }
+                Object.setPrototypeOf(wrappedExpress, Object.getPrototypeOf(origExpress));
+                // Also wrap express.Router() to instrument route handlers on Router instances.
+                // Most real Express apps define routes on Routers, not directly on the app.
+                if (typeof origExpress.Router === 'function') {
+                    const origRouter = origExpress.Router;
+                    wrappedExpress.Router = function (...rArgs) {
+                        const router = origRouter.apply(this, rArgs);
+                        try {
+                            (0, express_1.instrumentExpress)(router, { environment });
+                            if (debug) {
+                                console.log('[trickle/observe] Auto-instrumented Express Router');
+                            }
+                        }
+                        catch { /* don't crash */ }
+                        return router;
+                    };
+                }
+                // Update require cache
+                try {
+                    const resolvedPath = M._resolveFilename(request, parent);
+                    if (require.cache[resolvedPath]) {
+                        require.cache[resolvedPath].exports = wrappedExpress;
+                    }
+                }
+                catch { /* non-critical */ }
+                return wrappedExpress;
+            }
+            catch { /* fall through to normal processing */ }
         }
-        // Resolve to absolute path for dedup
+        // Resolve to absolute path for dedup — do this FIRST since bundlers like
+        // tsx/esbuild may use path aliases (e.g., @config/env) that don't start
+        // with './' or '/'. We need the resolved path to decide if it's user code.
         let resolvedPath;
         try {
             resolvedPath = M._resolveFilename(request, parent);
@@ -310,6 +633,9 @@ if (enabled) {
         catch {
             return exports;
         }
+        // Skip built-in modules (they resolve to names like 'fs', 'path', not absolute paths)
+        if (!resolvedPath.startsWith('/'))
+            return exports;
         // Skip node_modules and trickle internals
         if (resolvedPath.includes('node_modules'))
             return exports;
@@ -338,9 +664,26 @@ if (enabled) {
             for (const key of Object.keys(exports)) {
                 if (typeof exports[key] === 'function' && key !== 'default') {
                     const fn = exports[key];
-                    // Skip classes — their prototype methods are wrapped separately below
-                    const isClass = fn.prototype && fn.prototype.constructor === fn &&
-                        Object.getOwnPropertyNames(fn.prototype).some(m => m !== 'constructor' && typeof fn.prototype[m] === 'function');
+                    // Skip classes — wrapping them breaks DI containers (tsyringe, inversify, etc.)
+                    // and decorator metadata. Detect via toString() for ES2015+ classes,
+                    // and via prototype check for classes with prototype methods.
+                    // Wrapped in try-catch because some prototype property access can throw
+                    // (e.g., Node.js stream classes with getter-only properties).
+                    let isClass = false;
+                    try {
+                        const fnStr = Function.prototype.toString.call(fn);
+                        isClass = fnStr.startsWith('class ') ||
+                            (fn.prototype && fn.prototype.constructor === fn &&
+                                Object.getOwnPropertyNames(fn.prototype).some(m => {
+                                    try {
+                                        return m !== 'constructor' && typeof fn.prototype[m] === 'function';
+                                    }
+                                    catch {
+                                        return false;
+                                    }
+                                }));
+                    }
+                    catch { /* assume not a class */ }
                     if (isClass)
                         continue;
                     const paramNames = extractParamNames(fn);
@@ -350,39 +693,98 @@ if (enabled) {
                         trackArgs: true,
                         trackReturn: true,
                         sampleRate: 1,
-                        maxDepth: 5,
+                        maxDepth: 3,
                         environment,
                         enabled: true,
                         paramNames: paramNames.length > 0 ? paramNames : undefined,
                     };
-                    exports[key] = (0, wrap_1.wrapFunction)(fn, wrapOpts);
+                    const wrapped = (0, wrap_1.wrapFunction)(fn, wrapOpts);
+                    try {
+                        exports[key] = wrapped;
+                    }
+                    catch {
+                        // Property might be getter-only (tsx/esbuild uses getter exports).
+                        // Redefine with Object.defineProperty.
+                        try {
+                            Object.defineProperty(exports, key, {
+                                value: wrapped,
+                                enumerable: true,
+                                configurable: true,
+                                writable: true,
+                            });
+                        }
+                        catch {
+                            continue; /* truly read-only, skip */
+                        }
+                    }
                     count++;
                 }
             }
-            // Handle default export if it's a function
+            // Handle default export if it's a function (but not a class)
             if (typeof exports.default === 'function') {
                 const fn = exports.default;
-                const paramNames = extractParamNames(fn);
-                const wrapOpts = {
-                    functionName: fn.name || 'default',
-                    module: moduleName,
-                    trackArgs: true,
-                    trackReturn: true,
-                    sampleRate: 1,
-                    maxDepth: 5,
-                    environment,
-                    enabled: true,
-                    paramNames: paramNames.length > 0 ? paramNames : undefined,
-                };
-                exports.default = (0, wrap_1.wrapFunction)(fn, wrapOpts);
-                count++;
+                let defaultIsClass = false;
+                try {
+                    const defaultFnStr = Function.prototype.toString.call(fn);
+                    defaultIsClass = defaultFnStr.startsWith('class ') ||
+                        (fn.prototype && fn.prototype.constructor === fn &&
+                            Object.getOwnPropertyNames(fn.prototype).some(m => {
+                                try {
+                                    return m !== 'constructor' && typeof fn.prototype[m] === 'function';
+                                }
+                                catch {
+                                    return false;
+                                }
+                            }));
+                }
+                catch { /* assume not a class */ }
+                if (!defaultIsClass) {
+                    const paramNames = extractParamNames(fn);
+                    const wrapOpts = {
+                        functionName: fn.name || 'default',
+                        module: moduleName,
+                        trackArgs: true,
+                        trackReturn: true,
+                        sampleRate: 1,
+                        maxDepth: 3,
+                        environment,
+                        enabled: true,
+                        paramNames: paramNames.length > 0 ? paramNames : undefined,
+                    };
+                    const wrapped = (0, wrap_1.wrapFunction)(fn, wrapOpts);
+                    try {
+                        exports.default = wrapped;
+                    }
+                    catch {
+                        try {
+                            Object.defineProperty(exports, 'default', {
+                                value: wrapped, enumerable: true, configurable: true, writable: true,
+                            });
+                        }
+                        catch { /* skip */ }
+                    }
+                    count++;
+                }
             }
             // Wrap class prototype methods for exported classes
             for (const key of Object.keys(exports)) {
                 const val = exports[key];
                 if (typeof val === 'function' && val.prototype && val.prototype.constructor === val) {
-                    const protoNames = Object.getOwnPropertyNames(val.prototype)
-                        .filter(m => m !== 'constructor' && typeof val.prototype[m] === 'function');
+                    let protoNames;
+                    try {
+                        protoNames = Object.getOwnPropertyNames(val.prototype)
+                            .filter(m => { try {
+                            return m !== 'constructor' && typeof val.prototype[m] === 'function';
+                        }
+                        catch {
+                            return false;
+                        } });
+                    }
+                    catch {
+                        continue;
+                    }
+                    // Use the class's actual name, not the export key (avoids "default.method")
+                    const className = val.name || key;
                     for (const method of protoNames) {
                         if (method.startsWith('_'))
                             continue;
@@ -392,12 +794,12 @@ if (enabled) {
                                 continue;
                             const methodParamNames = extractParamNames(origMethod);
                             const methodOpts = {
-                                functionName: `${key}.${method}`,
+                                functionName: `${className}.${method}`,
                                 module: moduleName,
                                 trackArgs: true,
                                 trackReturn: true,
                                 sampleRate: 1,
-                                maxDepth: 5,
+                                maxDepth: 3,
                                 environment,
                                 enabled: true,
                                 paramNames: methodParamNames.length > 0 ? methodParamNames : undefined,
@@ -415,7 +817,14 @@ if (enabled) {
         }
         else if (typeof exports === 'function') {
             // Module exports a single function (e.g. module.exports = fn)
+            // But skip classes — wrapping them breaks DI, decorators, and instanceof
             const fn = exports;
+            const singleFnStr = Function.prototype.toString.call(fn);
+            const singleIsClass = singleFnStr.startsWith('class ') ||
+                (fn.prototype && fn.prototype.constructor === fn &&
+                    Object.getOwnPropertyNames(fn.prototype).some(m => m !== 'constructor' && typeof fn.prototype[m] === 'function'));
+            if (singleIsClass)
+                return exports;
             const fnParamNames = extractParamNames(fn);
             const wrapOpts = {
                 functionName: fn.name || moduleName,
@@ -423,7 +832,7 @@ if (enabled) {
                 trackArgs: true,
                 trackReturn: true,
                 sampleRate: 1,
-                maxDepth: 5,
+                maxDepth: 3,
                 environment,
                 enabled: true,
                 paramNames: fnParamNames.length > 0 ? fnParamNames : undefined,

package/dist/trace-var.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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
+ */
+import { TypeNode } from './types';
+export interface VariableObservation {
+    kind: 'variable';
+    varName: string;
+    line: number;
+    module: string;
+    file: string;
+    type: TypeNode;
+    typeHash: string;
+    sample: unknown;
+}
+/**
+ * Initialize the variable tracer.
+ * Called once during observe-register setup.
+ */
+export declare function initVarTracer(opts?: {
+    debug?: boolean;
+}): void;
+/**
+ * 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
+ */
+export declare function traceVar(value: unknown, varName: string, line: number, moduleName: string, filePath: string): void;