trickle-observe 0.1.0

package/dist/observe-register.js

@@ -0,0 +1,455 @@
+"use strict";
+/**
+ * Auto-observation register — patches Node's module loader to automatically
+ * wrap ALL functions in user code (not just exports).
+ *
+ * Uses two complementary hooks:
+ * 1. Module._compile: Transforms source code to wrap function declarations
+ *    IMMEDIATELY after each function body. This catches:
+ *    - Entry file functions (previously invisible)
+ *    - Non-exported helper functions inside modules
+ *    - All function declarations in user code
+ * 2. Module._load: Wraps exported functions on the exports object
+ *    (covers module.exports patterns like { foo, bar })
+ *
+ * A double-wrap guard in wrapFunction prevents the same function being
+ * wrapped by both hooks.
+ *
+ * Usage:
+ *
+ *   node -r trickle/observe app.js
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL     — Backend URL (default: http://localhost:4888)
+ *   TRICKLE_ENABLED         — Set to "0" or "false" to disable
+ *   TRICKLE_DEBUG           — Set to "1" for debug logging
+ *   TRICKLE_ENV             — Override detected environment
+ *   TRICKLE_OBSERVE_INCLUDE — Comma-separated substrings to include (default: all user code)
+ *   TRICKLE_OBSERVE_EXCLUDE — Comma-separated substrings to exclude (default: none)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const module_1 = __importDefault(require("module"));
+const path_1 = __importDefault(require("path"));
+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 M = module_1.default;
+const originalLoad = M._load;
+const originalCompile = M.prototype._compile;
+// Read config from environment
+const backendUrl = process.env.TRICKLE_BACKEND_URL || 'http://localhost:4888';
+const enabled = process.env.TRICKLE_ENABLED !== '0' && process.env.TRICKLE_ENABLED !== 'false';
+const debug = process.env.TRICKLE_DEBUG === '1' || process.env.TRICKLE_DEBUG === 'true';
+const envOverride = process.env.TRICKLE_ENV || undefined;
+const includePatterns = process.env.TRICKLE_OBSERVE_INCLUDE
+    ? process.env.TRICKLE_OBSERVE_INCLUDE.split(',').map(s => s.trim())
+    : [];
+const excludePatterns = process.env.TRICKLE_OBSERVE_EXCLUDE
+    ? process.env.TRICKLE_OBSERVE_EXCLUDE.split(',').map(s => s.trim())
+    : [];
+const wrapped = new Set();
+/**
+ * Check if a file path should be observed (user code, not node_modules/trickle internals).
+ */
+function shouldObserve(filename) {
+    if (!filename || !filename.startsWith('/'))
+        return false;
+    if (filename.includes('node_modules'))
+        return false;
+    // Don't transform trickle's own code
+    if (filename.includes('client-js/') || filename.includes('trickle-client/') || filename.includes('trickle/dist/'))
+        return false;
+    // Apply include/exclude filters
+    if (includePatterns.length > 0) {
+        if (!includePatterns.some(p => filename.includes(p)))
+            return false;
+    }
+    if (excludePatterns.length > 0) {
+        if (excludePatterns.some(p => filename.includes(p)))
+            return false;
+    }
+    // Only transform JS/TS files
+    const ext = path_1.default.extname(filename).toLowerCase();
+    if (!['.js', '.jsx', '.ts', '.tsx', '.cjs', '.mjs'].includes(ext))
+        return false;
+    return true;
+}
+/**
+ * Find the closing brace position for a function body starting at `openBrace`.
+ * Handles nested braces, strings, template literals, and comments.
+ */
+function findClosingBrace(source, openBrace) {
+    let depth = 1;
+    let pos = openBrace + 1;
+    while (pos < source.length && depth > 0) {
+        const ch = source[pos];
+        if (ch === '{') {
+            depth++;
+        }
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0)
+                return pos;
+        }
+        else if (ch === '"' || ch === "'" || ch === '`') {
+            // Skip string/template literal
+            const quote = ch;
+            pos++;
+            while (pos < source.length) {
+                if (source[pos] === '\\') {
+                    pos++;
+                } // skip escaped char
+                else if (source[pos] === quote)
+                    break;
+                else if (quote === '`' && source[pos] === '$' && pos + 1 < source.length && source[pos + 1] === '{') {
+                    // Template literal expression — skip nested content
+                    pos += 2;
+                    let tDepth = 1;
+                    while (pos < source.length && tDepth > 0) {
+                        if (source[pos] === '{')
+                            tDepth++;
+                        else if (source[pos] === '}')
+                            tDepth--;
+                        else if (source[pos] === '"' || source[pos] === "'" || source[pos] === '`') {
+                            const q = source[pos];
+                            pos++;
+                            while (pos < source.length && source[pos] !== q) {
+                                if (source[pos] === '\\')
+                                    pos++;
+                                pos++;
+                            }
+                        }
+                        pos++;
+                    }
+                    continue;
+                }
+                pos++;
+            }
+        }
+        else if (ch === '/' && pos + 1 < source.length && source[pos + 1] === '/') {
+            // Line comment — skip to end of line
+            while (pos < source.length && source[pos] !== '\n')
+                pos++;
+        }
+        else if (ch === '/' && pos + 1 < source.length && source[pos + 1] === '*') {
+            // Block comment — skip to */
+            pos += 2;
+            while (pos < source.length - 1 && !(source[pos] === '*' && source[pos + 1] === '/'))
+                pos++;
+            pos++; // skip past /
+        }
+        pos++;
+    }
+    return -1; // not found
+}
+/**
+ * Transform CJS source code to wrap function declarations with trickle observation.
+ *
+ * For each `function foo(...) { ... }` found, inserts a wrapper call
+ * IMMEDIATELY AFTER the function body closes:
+ *
+ *   function foo(a) { return a; }
+ *   foo = __trickle_wrap(foo, 'foo');
+ *
+ * This ensures functions are wrapped before subsequent code calls them,
+ * which is critical for entry files where functions are defined and used
+ * in the same top-level scope.
+ */
+function transformCjsSource(source, filename, moduleName, env) {
+    const funcRegex = /^[ \t]*(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
+    const insertions = [];
+    let match;
+    while ((match = funcRegex.exec(source)) !== null) {
+        const name = match[1];
+        // Skip common false positives
+        if (name === 'require' || name === 'exports' || name === 'module')
+            continue;
+        // Find the opening brace of the function body
+        const afterMatch = match.index + match[0].length;
+        const openBrace = source.indexOf('{', afterMatch);
+        if (openBrace === -1)
+            continue;
+        // Extract parameter names from the source between ( and {
+        const paramStr = source.slice(afterMatch, openBrace).replace(/[()]/g, '').trim();
+        const paramNames = paramStr
+            ? paramStr.split(',').map(p => {
+                // Handle default values: "x = 5" → "x", destructuring: "{a, b}" → skip
+                const trimmed = p.trim().split('=')[0].trim().split(':')[0].trim();
+                // Skip destructuring patterns and rest params
+                if (trimmed.startsWith('{') || trimmed.startsWith('[') || trimmed.startsWith('...'))
+                    return '';
+                return trimmed;
+            }).filter(Boolean)
+            : [];
+        // Find the matching closing brace
+        const closeBrace = findClosingBrace(source, openBrace);
+        if (closeBrace === -1)
+            continue;
+        insertions.push({ position: closeBrace + 1, name, paramNames });
+    }
+    if (insertions.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 = [
+        `var __trickle_mod = require(${JSON.stringify(wrapHelperPath)});`,
+        `var __trickle_wrap = function(fn, name, paramNames) {`,
+        `  var opts = {`,
+        `    functionName: name,`,
+        `    module: ${JSON.stringify(moduleName)},`,
+        `    trackArgs: true,`,
+        `    trackReturn: true,`,
+        `    sampleRate: 1,`,
+        `    maxDepth: 5,`,
+        `    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];
+        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);
+    }
+    return prefix + result;
+}
+/**
+ * Extract parameter names from a function using fn.toString().
+ */
+function extractParamNames(fn) {
+    try {
+        const src = fn.toString();
+        const parenMatch = src.match(/^(?:async\s+)?(?:function\s*\w*|\w+)\s*\(([^)]*)\)/);
+        if (!parenMatch)
+            return [];
+        const paramStr = parenMatch[1].trim();
+        if (!paramStr)
+            return [];
+        return paramStr.split(',').map(p => {
+            const trimmed = p.trim().split('=')[0].trim().split(':')[0].trim();
+            if (trimmed.startsWith('{') || trimmed.startsWith('[') || trimmed.startsWith('...'))
+                return '';
+            return trimmed;
+        }).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+if (enabled) {
+    const environment = envOverride || (0, env_detect_1.detectEnvironment)();
+    (0, transport_1.configure)({
+        backendUrl,
+        batchIntervalMs: 2000,
+        debug,
+        enabled: true,
+        environment,
+    });
+    if (debug) {
+        console.log(`[trickle/observe] Auto-observation enabled (backend: ${backendUrl})`);
+    }
+    // ── Hook 0: Patch global.fetch to capture HTTP response types ──
+    (0, fetch_observer_1.patchFetch)(environment, 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) {
+        if (shouldObserve(filename)) {
+            const moduleName = path_1.default.basename(filename).replace(/\.[jt]sx?$/, '');
+            try {
+                const transformed = transformCjsSource(content, filename, moduleName, environment);
+                if (transformed !== content) {
+                    // Count how many functions were wrapped (from insertions)
+                    const funcRegex = /^[ \t]*(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
+                    let count = 0;
+                    let m;
+                    while ((m = funcRegex.exec(content)) !== null) {
+                        if (m[1] !== 'require' && m[1] !== 'exports' && m[1] !== 'module')
+                            count++;
+                    }
+                    if (debug && count > 0) {
+                        console.log(`[trickle/observe] Deep-wrapped ${count} functions in ${moduleName} (${filename})`);
+                    }
+                    return originalCompile.call(this, transformed, filename);
+                }
+            }
+            catch (err) {
+                // If transform fails, fall through to original compilation
+                if (debug) {
+                    console.log(`[trickle/observe] Transform failed for ${filename}: ${err}`);
+                }
+            }
+        }
+        return originalCompile.call(this, content, filename);
+    };
+    // ── Hook 2: Module._load — wrap exports object (catches module.exports patterns) ──
+    // 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.
+    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;
+        }
+        // Resolve to absolute path for dedup
+        let resolvedPath;
+        try {
+            resolvedPath = M._resolveFilename(request, parent);
+        }
+        catch {
+            return exports;
+        }
+        // Skip node_modules and trickle internals
+        if (resolvedPath.includes('node_modules'))
+            return exports;
+        if (resolvedPath.includes('client-js/') || resolvedPath.includes('trickle-client/') || resolvedPath.includes('trickle/dist/'))
+            return exports;
+        // Skip already-wrapped modules
+        if (wrapped.has(resolvedPath))
+            return exports;
+        // Apply include/exclude filters
+        if (includePatterns.length > 0) {
+            const matches = includePatterns.some(p => resolvedPath.includes(p));
+            if (!matches)
+                return exports;
+        }
+        if (excludePatterns.length > 0) {
+            const excluded = excludePatterns.some(p => resolvedPath.includes(p));
+            if (excluded)
+                return exports;
+        }
+        wrapped.add(resolvedPath);
+        // Derive module name from file path
+        const moduleName = path_1.default.basename(resolvedPath).replace(/\.[jt]sx?$/, '');
+        // Wrap exported functions
+        if (exports && typeof exports === 'object') {
+            let count = 0;
+            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');
+                    if (isClass)
+                        continue;
+                    const paramNames = extractParamNames(fn);
+                    const wrapOpts = {
+                        functionName: key,
+                        module: moduleName,
+                        trackArgs: true,
+                        trackReturn: true,
+                        sampleRate: 1,
+                        maxDepth: 5,
+                        environment,
+                        enabled: true,
+                        paramNames: paramNames.length > 0 ? paramNames : undefined,
+                    };
+                    exports[key] = (0, wrap_1.wrapFunction)(fn, wrapOpts);
+                    count++;
+                }
+            }
+            // Handle default export if it's a function
+            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++;
+            }
+            // 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');
+                    for (const method of protoNames) {
+                        if (method.startsWith('_'))
+                            continue;
+                        try {
+                            const origMethod = val.prototype[method];
+                            if (origMethod[Symbol.for('__trickle_wrapped')])
+                                continue;
+                            const methodParamNames = extractParamNames(origMethod);
+                            const methodOpts = {
+                                functionName: `${key}.${method}`,
+                                module: moduleName,
+                                trackArgs: true,
+                                trackReturn: true,
+                                sampleRate: 1,
+                                maxDepth: 5,
+                                environment,
+                                enabled: true,
+                                paramNames: methodParamNames.length > 0 ? methodParamNames : undefined,
+                            };
+                            val.prototype[method] = (0, wrap_1.wrapFunction)(origMethod, methodOpts);
+                            count++;
+                        }
+                        catch { /* skip methods that can't be wrapped */ }
+                    }
+                }
+            }
+            if (debug && count > 0) {
+                console.log(`[trickle/observe] Wrapped ${count} exports from ${moduleName} (${resolvedPath})`);
+            }
+        }
+        else if (typeof exports === 'function') {
+            // Module exports a single function (e.g. module.exports = fn)
+            const fn = exports;
+            const fnParamNames = extractParamNames(fn);
+            const wrapOpts = {
+                functionName: fn.name || moduleName,
+                module: moduleName,
+                trackArgs: true,
+                trackReturn: true,
+                sampleRate: 1,
+                maxDepth: 5,
+                environment,
+                enabled: true,
+                paramNames: fnParamNames.length > 0 ? fnParamNames : undefined,
+            };
+            const wrappedFn = (0, wrap_1.wrapFunction)(fn, wrapOpts);
+            // Copy static properties
+            for (const key of Object.keys(fn)) {
+                wrappedFn[key] = fn[key];
+            }
+            // Update require cache
+            try {
+                if (require.cache[resolvedPath]) {
+                    require.cache[resolvedPath].exports = wrappedFn;
+                }
+            }
+            catch {
+                // Cache update failed — non-critical
+            }
+            if (debug) {
+                console.log(`[trickle/observe] Wrapped default export from ${moduleName}`);
+            }
+            return wrappedFn;
+        }
+        return exports;
+    };
+}
+else if (debug) {
+    console.log('[trickle/observe] Auto-observation disabled (TRICKLE_ENABLED=false)');
+}

package/dist/observe.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Universal function observation — wrap any module's exports to capture
+ * runtime types and sample data for every function call.
+ *
+ * Usage:
+ *
+ *   import { observe } from 'trickle';
+ *   import * as helpers from './myHelpers';
+ *
+ *   const { fetchUser, createOrder } = observe(helpers, { module: 'my-helpers' });
+ *   // Every call to fetchUser / createOrder now captures types + samples
+ *
+ * Works with any object whose values are functions — module exports, plain
+ * objects, class instances, test helpers, SDK clients, etc.
+ */
+export interface ObserveOpts {
+    /** Module name shown in `trickle functions` output. Defaults to 'observed'. */
+    module?: string;
+    /** Environment label. Auto-detected if omitted. */
+    environment?: string;
+    /** Fraction of calls to capture (0–1). Defaults to 1 (all calls). */
+    sampleRate?: number;
+    /** Max depth for type inference. Defaults to 5. */
+    maxDepth?: number;
+    /** Set to false to disable observation (passthrough). Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Wrap every function property on `obj` so calls are observed by trickle.
+ * Non-function properties are copied through unchanged.
+ *
+ * Returns a new object with the same shape — the original is never mutated.
+ */
+export declare function observe<T extends Record<string, any>>(obj: T, opts?: ObserveOpts): T;
+/**
+ * Wrap a single function for observation.
+ * Convenience for when you don't have a module object to pass to observe().
+ *
+ *   import { observeFn } from 'trickle';
+ *   const tracedFetch = observeFn(fetchUser, { module: 'api', name: 'fetchUser' });
+ */
+export declare function observeFn<T extends (...args: any[]) => any>(fn: T, opts?: ObserveOpts & {
+    name?: string;
+}): T;

package/dist/observe.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Universal function observation — wrap any module's exports to capture
+ * runtime types and sample data for every function call.
+ *
+ * Usage:
+ *
+ *   import { observe } from 'trickle';
+ *   import * as helpers from './myHelpers';
+ *
+ *   const { fetchUser, createOrder } = observe(helpers, { module: 'my-helpers' });
+ *   // Every call to fetchUser / createOrder now captures types + samples
+ *
+ * Works with any object whose values are functions — module exports, plain
+ * objects, class instances, test helpers, SDK clients, etc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observe = observe;
+exports.observeFn = observeFn;
+const wrap_1 = require("./wrap");
+const env_detect_1 = require("./env-detect");
+/**
+ * Wrap every function property on `obj` so calls are observed by trickle.
+ * Non-function properties are copied through unchanged.
+ *
+ * Returns a new object with the same shape — the original is never mutated.
+ */
+function observe(obj, opts) {
+    if (!obj || typeof obj !== 'object')
+        return obj;
+    const moduleName = opts?.module || inferModuleName();
+    const environment = opts?.environment || (0, env_detect_1.detectEnvironment)();
+    const enabled = opts?.enabled !== false;
+    const sampleRate = opts?.sampleRate ?? 1;
+    const maxDepth = opts?.maxDepth ?? 5;
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        const val = obj[key];
+        if (typeof val === 'function') {
+            const wrapOpts = {
+                functionName: key,
+                module: moduleName,
+                trackArgs: true,
+                trackReturn: true,
+                sampleRate,
+                maxDepth,
+                environment,
+                enabled,
+            };
+            result[key] = (0, wrap_1.wrapFunction)(val, wrapOpts);
+        }
+        else {
+            result[key] = val;
+        }
+    }
+    return result;
+}
+/**
+ * Wrap a single function for observation.
+ * Convenience for when you don't have a module object to pass to observe().
+ *
+ *   import { observeFn } from 'trickle';
+ *   const tracedFetch = observeFn(fetchUser, { module: 'api', name: 'fetchUser' });
+ */
+function observeFn(fn, opts) {
+    const wrapOpts = {
+        functionName: opts?.name || fn.name || 'anonymous',
+        module: opts?.module || inferModuleName(),
+        trackArgs: true,
+        trackReturn: true,
+        sampleRate: opts?.sampleRate ?? 1,
+        maxDepth: opts?.maxDepth ?? 5,
+        environment: opts?.environment || (0, env_detect_1.detectEnvironment)(),
+        enabled: opts?.enabled !== false,
+    };
+    return (0, wrap_1.wrapFunction)(fn, wrapOpts);
+}
+/**
+ * Attempt to infer a module name from the call stack.
+ */
+function inferModuleName() {
+    try {
+        const stack = new Error().stack;
+        if (!stack)
+            return 'observed';
+        const lines = stack.split('\n');
+        // Skip internal frames (Error, observe internals)
+        for (let i = 3; i < lines.length; i++) {
+            const line = lines[i].trim();
+            const match = line.match(/(?:at\s+)?(?:.*?\s+\()?(.+?)(?::\d+:\d+)?\)?$/);
+            if (match) {
+                const filePath = match[1];
+                if (filePath.includes('node_modules'))
+                    continue;
+                if (filePath.includes('trickle'))
+                    continue;
+                const parts = filePath.split('/');
+                const filename = parts[parts.length - 1];
+                if (filename && !filename.startsWith('<')) {
+                    return filename.replace(/\.[jt]sx?$/, '');
+                }
+            }
+        }
+    }
+    catch {
+        // Don't crash on stack inspection failure
+    }
+    return 'observed';
+}

package/dist/proxy-tracker.d.ts

@@ -0,0 +1,15 @@
+import { TypeNode } from './types';
+/**
+ * Creates a deep Proxy around a value to track property accesses.
+ * Returns the proxy and a function to retrieve all accessed paths with their inferred types.
+ *
+ * The proxy is designed to be fully transparent:
+ * - Array.isArray() returns true for proxied arrays
+ * - JSON.stringify works correctly
+ * - typeof, ===, iteration, spread, Object.keys all work identically
+ * - Symbol.toPrimitive, Symbol.iterator, Symbol.toStringTag are forwarded
+ */
+export declare function createTracker(value: unknown): {
+    proxy: unknown;
+    getAccessedPaths: () => Map<string, TypeNode>;
+};