trickle-observe 0.2.96 → 0.2.97

package/dist/call-trace.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Call trace recorder — captures function call/return events with timing
+ * and parent-child relationships for building call graphs.
+ *
+ * Written to .trickle/calltrace.jsonl as:
+ *   { "kind": "call", "function": "createUser", "module": "api",
+ *     "parentId": 0, "callId": 1, "timestamp": 1710516000,
+ *     "durationMs": 2.5, "args": ["Alice"], "result": {...} }
+ */
+/**
+ * Record a function call event. Returns the callId for pairing with traceReturn.
+ */
+export declare function traceCall(functionName: string, moduleName: string): number;
+/**
+ * Record a function return event with timing.
+ */
+export declare function traceReturn(callId: number, functionName: string, moduleName: string, durationMs: number, error?: string): void;
+export declare function initCallTrace(): void;

package/dist/call-trace.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Call trace recorder — captures function call/return events with timing
+ * and parent-child relationships for building call graphs.
+ *
+ * Written to .trickle/calltrace.jsonl as:
+ *   { "kind": "call", "function": "createUser", "module": "api",
+ *     "parentId": 0, "callId": 1, "timestamp": 1710516000,
+ *     "durationMs": 2.5, "args": ["Alice"], "result": {...} }
+ */
+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.traceCall = traceCall;
+exports.traceReturn = traceReturn;
+exports.initCallTrace = initCallTrace;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+let traceFile = null;
+let callCounter = 0;
+let currentCallId = 0; // 0 = top level
+const callStack = [0];
+const MAX_TRACE_EVENTS = 500;
+let eventCount = 0;
+function getTraceFile() {
+    if (traceFile)
+        return traceFile;
+    const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    traceFile = path.join(dir, 'calltrace.jsonl');
+    try {
+        fs.writeFileSync(traceFile, '');
+    }
+    catch { }
+    return traceFile;
+}
+function writeEvent(event) {
+    if (eventCount >= MAX_TRACE_EVENTS)
+        return;
+    eventCount++;
+    try {
+        fs.appendFileSync(getTraceFile(), JSON.stringify(event) + '\n');
+    }
+    catch { }
+}
+/**
+ * Record a function call event. Returns the callId for pairing with traceReturn.
+ */
+function traceCall(functionName, moduleName) {
+    const id = ++callCounter;
+    const parentId = callStack[callStack.length - 1] || 0;
+    callStack.push(id);
+    // We record a placeholder — duration is filled in by traceReturn
+    return id;
+}
+/**
+ * Record a function return event with timing.
+ */
+function traceReturn(callId, functionName, moduleName, durationMs, error) {
+    const parentId = callStack.length >= 2 ? callStack[callStack.length - 2] : 0;
+    const depth = callStack.length - 1;
+    writeEvent({
+        kind: 'call',
+        function: functionName,
+        module: moduleName,
+        callId,
+        parentId,
+        depth,
+        timestamp: Date.now(),
+        durationMs: Math.round(durationMs * 100) / 100,
+        ...(error ? { error } : {}),
+    });
+    // Pop from stack
+    if (callStack[callStack.length - 1] === callId) {
+        callStack.pop();
+    }
+}
+function initCallTrace() {
+    // Ensure trace file is initialized
+    getTraceFile();
+}

package/dist/wrap.js

@@ -6,6 +6,7 @@ const type_inference_1 = require("./type-inference");
 const type_hash_1 = require("./type-hash");
 const cache_1 = require("./cache");
 const transport_1 = require("./transport");
+const call_trace_1 = require("./call-trace");
 const typeCache = new cache_1.TypeCache();
 exports.typeCache = typeCache;
 /** Symbol to mark already-wrapped functions, preventing double-wrap. */
@@ -33,6 +34,7 @@ function wrapFunction(fn, opts) {
         let caughtError;
         const trackers = [];
         const startTime = performance.now();
+        const callId = (0, call_trace_1.traceCall)(opts.functionName, opts.module);
         try {
             // Always pass ORIGINAL args to the function — never proxied ones.
             // Proxied args can break framework internals (Express Router, DI containers, etc.)
@@ -45,6 +47,7 @@ function wrapFunction(fn, opts) {
             try {
                 const durationMs = performance.now() - startTime;
                 captureErrorPayload(functionKey, opts, args, trackers, err, durationMs);
+                (0, call_trace_1.traceReturn)(callId, opts.functionName, opts.module, durationMs, err?.message);
             }
             catch {
                 // Never let our instrumentation interfere
@@ -58,6 +61,7 @@ function wrapFunction(fn, opts) {
                 try {
                     const durationMs = performance.now() - startTime;
                     capturePayload(functionKey, opts, args, trackers, resolved, true, durationMs);
+                    (0, call_trace_1.traceReturn)(callId, opts.functionName, opts.module, durationMs);
                 }
                 catch {
                     // Never let our instrumentation interfere
@@ -67,6 +71,7 @@ function wrapFunction(fn, opts) {
                 try {
                     const durationMs = performance.now() - startTime;
                     captureErrorPayload(functionKey, opts, args, trackers, err, durationMs);
+                    (0, call_trace_1.traceReturn)(callId, opts.functionName, opts.module, durationMs, err?.message);
                 }
                 catch {
                     // Never let our instrumentation interfere
@@ -79,6 +84,7 @@ function wrapFunction(fn, opts) {
         try {
             const durationMs = performance.now() - startTime;
             capturePayload(functionKey, opts, args, trackers, result, false, durationMs);
+            (0, call_trace_1.traceReturn)(callId, opts.functionName, opts.module, durationMs);
         }
         catch {
             // Never let our instrumentation interfere

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-observe",
-  "version": "0.2.96",
+  "version": "0.2.97",
   "description": "Runtime type observability for JavaScript applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/call-trace.ts

@@ -0,0 +1,95 @@
+/**
+ * Call trace recorder — captures function call/return events with timing
+ * and parent-child relationships for building call graphs.
+ *
+ * Written to .trickle/calltrace.jsonl as:
+ *   { "kind": "call", "function": "createUser", "module": "api",
+ *     "parentId": 0, "callId": 1, "timestamp": 1710516000,
+ *     "durationMs": 2.5, "args": ["Alice"], "result": {...} }
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface CallEvent {
+  kind: 'call';
+  function: string;
+  module: string;
+  callId: number;
+  parentId: number;
+  depth: number;
+  timestamp: number;
+  durationMs: number;
+  error?: string;
+}
+
+let traceFile: string | null = null;
+let callCounter = 0;
+let currentCallId = 0; // 0 = top level
+const callStack: number[] = [0];
+const MAX_TRACE_EVENTS = 500;
+let eventCount = 0;
+
+function getTraceFile(): string {
+  if (traceFile) return traceFile;
+  const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  traceFile = path.join(dir, 'calltrace.jsonl');
+  try { fs.writeFileSync(traceFile, ''); } catch {}
+  return traceFile;
+}
+
+function writeEvent(event: CallEvent): void {
+  if (eventCount >= MAX_TRACE_EVENTS) return;
+  eventCount++;
+  try {
+    fs.appendFileSync(getTraceFile(), JSON.stringify(event) + '\n');
+  } catch {}
+}
+
+/**
+ * Record a function call event. Returns the callId for pairing with traceReturn.
+ */
+export function traceCall(functionName: string, moduleName: string): number {
+  const id = ++callCounter;
+  const parentId = callStack[callStack.length - 1] || 0;
+  callStack.push(id);
+  // We record a placeholder — duration is filled in by traceReturn
+  return id;
+}
+
+/**
+ * Record a function return event with timing.
+ */
+export function traceReturn(
+  callId: number,
+  functionName: string,
+  moduleName: string,
+  durationMs: number,
+  error?: string,
+): void {
+  const parentId = callStack.length >= 2 ? callStack[callStack.length - 2] : 0;
+  const depth = callStack.length - 1;
+
+  writeEvent({
+    kind: 'call',
+    function: functionName,
+    module: moduleName,
+    callId,
+    parentId,
+    depth,
+    timestamp: Date.now(),
+    durationMs: Math.round(durationMs * 100) / 100,
+    ...(error ? { error } : {}),
+  });
+
+  // Pop from stack
+  if (callStack[callStack.length - 1] === callId) {
+    callStack.pop();
+  }
+}
+
+export function initCallTrace(): void {
+  // Ensure trace file is initialized
+  getTraceFile();
+}

package/src/wrap.ts

@@ -4,6 +4,7 @@ import { hashType } from './type-hash';
 import { createTracker } from './proxy-tracker';
 import { TypeCache } from './cache';
 import { enqueue } from './transport';
+import { traceCall, traceReturn } from './call-trace';
 
 const typeCache = new TypeCache();
 
@@ -35,6 +36,7 @@ export function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: Wra
     let caughtError: unknown;
     const trackers: Array<{ proxy: unknown; getAccessedPaths: () => Map<string, TypeNode> }> = [];
     const startTime = performance.now();
+    const callId = traceCall(opts.functionName, opts.module);
 
     try {
       // Always pass ORIGINAL args to the function — never proxied ones.
@@ -48,6 +50,7 @@ export function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: Wra
       try {
         const durationMs = performance.now() - startTime;
         captureErrorPayload(functionKey, opts, args, trackers, err, durationMs);
+        traceReturn(callId, opts.functionName, opts.module, durationMs, (err as Error)?.message);
       } catch {
         // Never let our instrumentation interfere
       }
@@ -63,6 +66,7 @@ export function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: Wra
           try {
             const durationMs = performance.now() - startTime;
             capturePayload(functionKey, opts, args, trackers, resolved, true, durationMs);
+            traceReturn(callId, opts.functionName, opts.module, durationMs);
           } catch {
             // Never let our instrumentation interfere
           }
@@ -72,6 +76,7 @@ export function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: Wra
           try {
             const durationMs = performance.now() - startTime;
             captureErrorPayload(functionKey, opts, args, trackers, err, durationMs);
+            traceReturn(callId, opts.functionName, opts.module, durationMs, (err as Error)?.message);
           } catch {
             // Never let our instrumentation interfere
           }
@@ -85,6 +90,7 @@ export function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: Wra
     try {
       const durationMs = performance.now() - startTime;
       capturePayload(functionKey, opts, args, trackers, result, false, durationMs);
+      traceReturn(callId, opts.functionName, opts.module, durationMs);
     } catch {
       // Never let our instrumentation interfere
     }