evergreen-sdk 1.0.1 → 1.0.3

package/dist/index.d.ts

@@ -2,15 +2,23 @@ interface ApiCallMeta {
     callee: string;
     arg0?: string;
 }
+interface RunOptions {
+    callTrace?: {
+        include?: string[];
+        exclude?: string[];
+    };
+}
 interface StepOptions {
     input?: any;
     children?: string[];
     apiCalls?: ApiCallMeta[];
     __not_async?: boolean;
 }
+declare function runWithContext<T>(jobId: string, fn: () => T): T;
+declare function runWithContext<T>(jobId: string, options: RunOptions, fn: () => T): T;
 export declare const evergreen: {
     clear(): void;
-    run<T>(jobId: string, fn: () => T): T;
+    run: typeof runWithContext;
     __autoStep<T>(name: string, location: {
         file: string;
         line: number;

package/dist/index.js

@@ -10,15 +10,44 @@ const traceStorage = new node_async_hooks_1.AsyncLocalStorage();
 let ws = null;
 let isConnected = false;
 const pendingTelemetry = [];
+function getTelemetryWsUrl() {
+    const explicit = process.env.EVERGREEN_TRACE_WS_URL;
+    if (explicit && explicit.trim())
+        return explicit.trim();
+    return "ws://localhost:4321";
+}
+function shouldDebugTelemetryConnection() {
+    return (process.env.EVERGREEN_TRACE_DEBUG === "1" ||
+        process.env.EVERGREEN_TRACE_DEBUG === "true");
+}
+function shouldDisableWs() {
+    // In tests, keeping a websocket instance around can keep the Node test runner alive.
+    if (process.env.NODE_ENV === "test")
+        return true;
+    return (process.env.EVERGREEN_TRACE_DISABLE_WS === "1" ||
+        process.env.EVERGREEN_TRACE_DISABLE_WS === "true");
+}
 // Connect to the VS Code Extension Hub
 function connect() {
+    if (shouldDisableWs())
+        return;
     if (ws &&
         (ws.readyState === ws_1.default.CONNECTING || ws.readyState === ws_1.default.OPEN))
         return;
+    const url = getTelemetryWsUrl();
+    const debug = shouldDebugTelemetryConnection();
     try {
-        ws = new ws_1.default("ws://localhost:3000");
+        if (debug) {
+            // eslint-disable-next-line no-console
+            console.log(`🌲 Evergreen Trace: connecting to ${url}`);
+        }
+        ws = new ws_1.default(url);
         ws.on("open", () => {
             isConnected = true;
+            if (debug) {
+                // eslint-disable-next-line no-console
+                console.log(`🌲 Evergreen Trace: connected to ${url}`);
+            }
             // Flush any telemetry that was emitted before the socket became ready.
             while (pendingTelemetry.length > 0) {
                 const queued = pendingTelemetry.shift();
@@ -75,6 +104,41 @@ function sendTelemetry(payload) {
         // Fire and forget, silently ignore send errors
     }
 }
+function escapeRegexLiteral(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function matchesPattern(value, pattern) {
+    // Support:
+    // - exact match: "app.listen"
+    // - simple wildcard: "redis.*" or "prisma.*.findMany" etc.
+    if (!pattern)
+        return false;
+    if (!pattern.includes("*"))
+        return value === pattern;
+    const re = new RegExp("^" +
+        pattern
+            .split("*")
+            .map((part) => escapeRegexLiteral(part))
+            .join(".*") +
+        "$");
+    return re.test(value);
+}
+function filterApiCallsForRun(apiCalls, store) {
+    if (!apiCalls || apiCalls.length === 0)
+        return [];
+    const include = store.callTrace?.include?.filter(Boolean) ?? [];
+    const exclude = store.callTrace?.exclude?.filter(Boolean) ?? [];
+    return apiCalls.filter((c) => {
+        if (exclude.length && exclude.some((p) => matchesPattern(c.callee, p))) {
+            return false;
+        }
+        if (include.length) {
+            return include.some((p) => matchesPattern(c.callee, p));
+        }
+        // default: include everything that was collected
+        return true;
+    });
+}
 function extractLocationFromStack(stack) {
     if (!stack)
         return undefined;
@@ -93,13 +157,19 @@ function extractLocationFromStack(stack) {
     }
     return undefined;
 }
+function runWithContext(jobId, a, b) {
+    const fn = typeof a === "function" ? a : b;
+    const options = typeof a === "function" ? undefined : a;
+    if (!fn) {
+        throw new Error("evergreen.run(jobId, fn) requires a function");
+    }
+    return traceStorage.run({ jobId, callTrace: options?.callTrace }, fn);
+}
 exports.evergreen = {
     clear() {
         sendTelemetry({ type: "CLEAR" });
     },
-    run(jobId, fn) {
-        return traceStorage.run({ jobId }, fn);
-    },
+    run: runWithContext,
     async __autoStep(name, location, fn, options) {
         const store = traceStorage.getStore();
         // If no context, just execute the function normally without tracing
@@ -107,6 +177,7 @@ exports.evergreen = {
             return await fn();
         }
         const { jobId, previousStep } = store;
+        const filteredApiCalls = filterApiCallsForRun(options?.apiCalls, store);
         const timestamp = Date.now();
         const startTime = process.hrtime.bigint();
         // Emit NODE_STARTED
@@ -118,7 +189,7 @@ exports.evergreen = {
             previousStep,
             location,
             children: options?.children || [],
-            apiCalls: options?.apiCalls || [],
+            apiCalls: filteredApiCalls,
             __not_async: options?.__not_async ?? false,
             timestamp,
         });
@@ -151,7 +222,7 @@ exports.evergreen = {
                 location,
                 // include children and apiCalls again so the UI can still render ghost edges & API badges even if NODE_STARTED was missed
                 children: options?.children || [],
-                apiCalls: options?.apiCalls || [],
+                apiCalls: filteredApiCalls,
                 __not_async: options?.__not_async ?? false,
                 timestamp: Date.now(),
             });

package/dist/index.test.d.ts

@@ -1 +1,2 @@
 export declare function testAlsPropagation(): Promise<void>;
+export declare function testRunCallTraceFiltering(): Promise<void>;

package/dist/index.test.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.testAlsPropagation = testAlsPropagation;
+exports.testRunCallTraceFiltering = testRunCallTraceFiltering;
 const index_1 = require("./index");
 // Simple Node-style test (compatible with node --test once compiled)
 // exported for use in dist/index.test.js
@@ -44,3 +45,39 @@ async function testAlsPropagation() {
         }
     }
 }
+async function testRunCallTraceFiltering() {
+    const events = [];
+    const originalSend = index_1.evergreen.__test__?.sendTelemetry;
+    if (originalSend) {
+        index_1.evergreen.__test__.sendTelemetry = (payload) => {
+            events.push(payload);
+            originalSend(payload);
+        };
+    }
+    try {
+        await index_1.evergreen.run("job-filter", { callTrace: { include: ["app.listen", "redis.*"], exclude: ["redis.ping"] } }, async () => {
+            await index_1.evergreen.__autoStep("step", { file: "test.ts", line: 1, column: 0 }, async () => 1, {
+                apiCalls: [
+                    { callee: "app.listen", arg0: "3000" },
+                    { callee: "redis.ping" },
+                    { callee: "redis.get", arg0: "k" },
+                    { callee: "prisma.user.findMany" },
+                ],
+            });
+        });
+        const started = events.find((e) => e.event === "NODE_STARTED" && e.stepName === "step");
+        if (!started) {
+            throw new Error("Expected NODE_STARTED for step");
+        }
+        const callees = (started.apiCalls || []).map((c) => c.callee);
+        const expected = ["app.listen", "redis.get"];
+        if (JSON.stringify(callees) !== JSON.stringify(expected)) {
+            throw new Error(`Unexpected filtered callees: ${JSON.stringify(callees)} expected ${JSON.stringify(expected)}`);
+        }
+    }
+    finally {
+        if (originalSend) {
+            index_1.evergreen.__test__.sendTelemetry = originalSend;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evergreen-sdk",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Evergreen Trace Backend SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.test.ts

@@ -56,3 +56,56 @@ export async function testAlsPropagation() {
   }
 }
 
+export async function testRunCallTraceFiltering() {
+  const events: any[] = [];
+  const originalSend = (evergreen as any).__test__?.sendTelemetry;
+
+  if (originalSend) {
+    (evergreen as any).__test__.sendTelemetry = (payload: any) => {
+      events.push(payload);
+      originalSend(payload);
+    };
+  }
+
+  try {
+    await evergreen.run(
+      "job-filter",
+      { callTrace: { include: ["app.listen", "redis.*"], exclude: ["redis.ping"] } },
+      async () => {
+        await evergreen.__autoStep(
+          "step",
+          { file: "test.ts", line: 1, column: 0 },
+          async () => 1,
+          {
+            apiCalls: [
+              { callee: "app.listen", arg0: "3000" },
+              { callee: "redis.ping" },
+              { callee: "redis.get", arg0: "k" },
+              { callee: "prisma.user.findMany" },
+            ],
+          },
+        );
+      },
+    );
+
+    const started = events.find(
+      (e) => e.event === "NODE_STARTED" && e.stepName === "step",
+    );
+    if (!started) {
+      throw new Error("Expected NODE_STARTED for step");
+    }
+
+    const callees = (started.apiCalls || []).map((c: any) => c.callee);
+    const expected = ["app.listen", "redis.get"];
+    if (JSON.stringify(callees) !== JSON.stringify(expected)) {
+      throw new Error(
+        `Unexpected filtered callees: ${JSON.stringify(callees)} expected ${JSON.stringify(expected)}`,
+      );
+    }
+  } finally {
+    if (originalSend) {
+      (evergreen as any).__test__.sendTelemetry = originalSend;
+    }
+  }
+}
+

package/src/index.ts

@@ -4,6 +4,10 @@ import WebSocket from "ws";
 interface EvergreenContext {
   jobId: string;
   previousStep?: string;
+  callTrace?: {
+    include?: string[];
+    exclude?: string[];
+  };
 }
 
 interface ApiCallMeta {
@@ -11,6 +15,13 @@ interface ApiCallMeta {
   arg0?: string;
 }
 
+interface RunOptions {
+  callTrace?: {
+    include?: string[]; // patterns like "app.listen" or "redis.*"
+    exclude?: string[];
+  };
+}
+
 interface StepOptions {
   input?: any;
   children?: string[];
@@ -36,8 +47,18 @@ function shouldDebugTelemetryConnection(): boolean {
   );
 }
 
+function shouldDisableWs(): boolean {
+  // In tests, keeping a websocket instance around can keep the Node test runner alive.
+  if (process.env.NODE_ENV === "test") return true;
+  return (
+    process.env.EVERGREEN_TRACE_DISABLE_WS === "1" ||
+    process.env.EVERGREEN_TRACE_DISABLE_WS === "true"
+  );
+}
+
 // Connect to the VS Code Extension Hub
 function connect() {
+  if (shouldDisableWs()) return;
   if (
     ws &&
     (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN)
@@ -123,6 +144,48 @@ function sendTelemetry(payload: any) {
   }
 }
 
+function escapeRegexLiteral(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function matchesPattern(value: string, pattern: string): boolean {
+  // Support:
+  // - exact match: "app.listen"
+  // - simple wildcard: "redis.*" or "prisma.*.findMany" etc.
+  if (!pattern) return false;
+  if (!pattern.includes("*")) return value === pattern;
+
+  const re = new RegExp(
+    "^" +
+      pattern
+        .split("*")
+        .map((part) => escapeRegexLiteral(part))
+        .join(".*") +
+      "$",
+  );
+  return re.test(value);
+}
+
+function filterApiCallsForRun(
+  apiCalls: ApiCallMeta[] | undefined,
+  store: EvergreenContext,
+): ApiCallMeta[] {
+  if (!apiCalls || apiCalls.length === 0) return [];
+  const include = store.callTrace?.include?.filter(Boolean) ?? [];
+  const exclude = store.callTrace?.exclude?.filter(Boolean) ?? [];
+
+  return apiCalls.filter((c) => {
+    if (exclude.length && exclude.some((p) => matchesPattern(c.callee, p))) {
+      return false;
+    }
+    if (include.length) {
+      return include.some((p) => matchesPattern(c.callee, p));
+    }
+    // default: include everything that was collected
+    return true;
+  });
+}
+
 function extractLocationFromStack(
   stack?: string,
 ): { file: string; line: number } | undefined {
@@ -146,14 +209,27 @@ function extractLocationFromStack(
   return undefined;
 }
 
+function runWithContext<T>(jobId: string, fn: () => T): T;
+function runWithContext<T>(jobId: string, options: RunOptions, fn: () => T): T;
+function runWithContext<T>(
+  jobId: string,
+  a: RunOptions | (() => T),
+  b?: () => T,
+): T {
+  const fn = typeof a === "function" ? a : b;
+  const options = typeof a === "function" ? undefined : a;
+  if (!fn) {
+    throw new Error("evergreen.run(jobId, fn) requires a function");
+  }
+  return traceStorage.run({ jobId, callTrace: options?.callTrace }, fn);
+}
+
 export const evergreen = {
   clear() {
     sendTelemetry({ type: "CLEAR" });
   },
 
-  run<T>(jobId: string, fn: () => T): T {
-    return traceStorage.run({ jobId }, fn);
-  },
+  run: runWithContext,
 
   async __autoStep<T>(
     name: string,
@@ -169,6 +245,7 @@ export const evergreen = {
     }
 
     const { jobId, previousStep } = store;
+    const filteredApiCalls = filterApiCallsForRun(options?.apiCalls, store);
 
     const timestamp = Date.now();
     const startTime = process.hrtime.bigint();
@@ -182,7 +259,7 @@ export const evergreen = {
       previousStep,
       location,
       children: options?.children || [],
-      apiCalls: options?.apiCalls || [],
+      apiCalls: filteredApiCalls,
       __not_async: options?.__not_async ?? false,
       timestamp,
     });
@@ -219,7 +296,7 @@ export const evergreen = {
         location,
         // include children and apiCalls again so the UI can still render ghost edges & API badges even if NODE_STARTED was missed
         children: options?.children || [],
-        apiCalls: options?.apiCalls || [],
+        apiCalls: filteredApiCalls,
         __not_async: options?.__not_async ?? false,
         timestamp: Date.now(),
       });

package/src/index.js

@@ -1,160 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.evergreen = void 0;
-const node_async_hooks_1 = require("node:async_hooks");
-const ws_1 = require("ws");
-const traceStorage = new node_async_hooks_1.AsyncLocalStorage();
-let ws = null;
-let isConnected = false;
-// Connect to the VS Code Extension Hub
-function connect() {
-    if (ws && (ws.readyState === ws_1.default.CONNECTING || ws.readyState === ws_1.default.OPEN))
-        return;
-    try {
-        ws = new ws_1.default('ws://localhost:3000');
-        ws.on('open', () => {
-            isConnected = true;
-        });
-        ws.on('close', () => {
-            isConnected = false;
-            // Optionally implement reconnect logic here
-        });
-        ws.on('error', () => {
-            isConnected = false;
-            // Silently fail if extension is not running
-        });
-    }
-    catch (error) {
-        isConnected = false;
-    }
-}
-// Ensure connection is attempted
-connect();
-function sanitizePayload(obj, maxDepth = 3) {
-    if (maxDepth <= 0)
-        return '[Max Depth Reached]';
-    if (obj === null || obj === undefined)
-        return obj;
-    if (typeof obj !== 'object')
-        return obj;
-    if (obj instanceof Error) {
-        return { name: obj.name, message: obj.message, stack: obj.stack };
-    }
-    if (Array.isArray(obj)) {
-        return obj.map(item => sanitizePayload(item, maxDepth - 1));
-    }
-    const sanitized = {};
-    for (const [key, value] of Object.entries(obj)) {
-        sanitized[key] = sanitizePayload(value, maxDepth - 1);
-    }
-    return sanitized;
-}
-function sendTelemetry(payload) {
-    if (!isConnected || !ws || ws.readyState !== ws_1.default.OPEN)
-        return;
-    try {
-        ws.send(JSON.stringify(payload));
-    }
-    catch (error) {
-        // Fire and forget, silently ignore send errors
-    }
-}
-function extractLocationFromStack(stack) {
-    if (!stack)
-        return undefined;
-    // The stack will look like:
-    // Error
-    //   at Object.step (/path/to/sdk/index.ts:...)
-    //   at myBusinessLogic (/path/to/business/logic.ts:42:15)
-    const lines = stack.split('\n');
-    if (lines.length >= 3) {
-        const callerLine = lines[2];
-        const match = callerLine.match(/\((.+):(\d+):\d+\)/) || callerLine.match(/at (.+):(\d+):\d+/);
-        if (match && match.length >= 3) {
-            return { file: match[1], line: parseInt(match[2], 10) };
-        }
-    }
-    return undefined;
-}
-exports.evergreen = {
-    clear() {
-        sendTelemetry({ type: 'CLEAR' });
-    },
-    run(jobId, fn) {
-        return traceStorage.run({ jobId }, fn);
-    },
-    async step(name, fn, options) {
-        const store = traceStorage.getStore();
-        // If no context, just execute the function normally without tracing
-        if (!store) {
-            return await fn();
-        }
-        const { jobId, previousStep } = store;
-        // Capture location using a throwaway error
-        const locationError = new Error();
-        const location = extractLocationFromStack(locationError.stack) || { file: 'unknown', line: 0 };
-        const timestamp = Date.now();
-        const startTime = process.hrtime.bigint();
-        // Emit NODE_STARTED
-        sendTelemetry({
-            event: 'NODE_STARTED',
-            status: 'PENDING',
-            jobId,
-            stepName: name,
-            previousStep,
-            location,
-            timestamp
-        });
-        // We must ensure subsequent nested steps know this step is their parent.
-        // To do this, we run the inner function in a nested context.
-        const newContext = { ...store, previousStep: name };
-        try {
-            // Execute the business logic within the new nested context
-            const result = await traceStorage.run(newContext, async () => {
-                return await fn();
-            });
-            const endTime = process.hrtime.bigint();
-            const durationMs = Number(endTime - startTime) / 1000000;
-            // Emit NODE_COMPLETED
-            sendTelemetry({
-                event: 'NODE_COMPLETED',
-                status: 'SUCCESS',
-                jobId,
-                stepName: name,
-                previousStep,
-                payload: { input: sanitizePayload(options?.input), output: sanitizePayload(result) },
-                context: {
-                    input: sanitizePayload(options?.input),
-                    output: sanitizePayload(result),
-                    duration: durationMs
-                },
-                location,
-                timestamp: Date.now()
-            });
-            return result;
-        }
-        catch (error) {
-            const endTime = process.hrtime.bigint();
-            const durationMs = Number(endTime - startTime) / 1000000;
-            // Emit NODE_FAILED
-            sendTelemetry({
-                event: 'NODE_FAILED',
-                status: 'FAILED',
-                jobId,
-                stepName: name,
-                previousStep,
-                payload: { input: sanitizePayload(options?.input), error: sanitizePayload(error) },
-                context: {
-                    input: sanitizePayload(options?.input),
-                    error: sanitizePayload(error),
-                    duration: durationMs
-                },
-                location,
-                timestamp: Date.now()
-            });
-            // Re-throw so backend logic behaves normally
-            throw error;
-        }
-    }
-};
-//# sourceMappingURL=index.js.map