evergreen-trace-runtime 0.1.0

package/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+
+function printUsage() {
+  // eslint-disable-next-line no-console
+  console.log(
+    "Usage: evergreen-trace run <entry> [-- <args>...]\n" +
+      "Example: evergreen-trace run src/server.js -- --port 4321",
+  );
+}
+
+function run() {
+  const argv = process.argv.slice(2); // drop node + script
+
+  const [cmd, entry, ...rest] = argv;
+
+  if (cmd !== "run" || !entry) {
+    printUsage();
+    process.exit(1);
+  }
+
+  const entryPath = path.resolve(process.cwd(), entry);
+
+  const child = spawn(
+    process.execPath,
+    ["--require", "evergreen-trace-runtime/register", entryPath, ...rest],
+    { stdio: "inherit" },
+  );
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 0);
+    }
+  });
+}
+
+run();

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "evergreen-trace-runtime",
+  "version": "0.1.0",
+  "description": "Evergreen Trace runtime loader and CLI",
+  "main": "register.js",
+  "bin": {
+    "evergreen-trace": "cli.js"
+  },
+  "exports": {
+    "./register": "./register.js"
+  },
+  "dependencies": {
+    "@babel/core": "^7.23.0",
+    "micromatch": "^4.0.0",
+    "evergreen-babel-plugin": "file:../evergreen-babel-plugin",
+    "evergreen-sdk": "file:../evergreen-sdk"
+  }
+}
+

package/register.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+"use strict";
+
+// Runtime entrypoint for Evergreen Trace loader.
+// In this monorepo, we reuse the root loader implementation.
+// When publishing, this file can be replaced with a compiled copy.
+
+module.exports = require("./src/register.js");
+

package/src/instrument-cache.js

@@ -0,0 +1,113 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+function hashContent(content) {
+  return crypto.createHash("sha1").update(content, "utf8").digest("hex");
+}
+
+function hashConfig(config) {
+  const minimal = {
+    ignore: Array.isArray(config.ignore) ? config.ignore : [],
+    include: Array.isArray(config.include) ? config.include : [],
+  };
+  return crypto
+    .createHash("sha1")
+    .update(JSON.stringify(minimal), "utf8")
+    .digest("hex");
+}
+
+function hashKey(logicalKey) {
+  // Stable serialization
+  const json = JSON.stringify({
+    filename: logicalKey.filename,
+    contentHash: logicalKey.contentHash,
+    configHash: logicalKey.configHash,
+    toolVersion: logicalKey.toolVersion,
+  });
+  return crypto.createHash("sha1").update(json, "utf8").digest("hex");
+}
+
+function ensureDir(dirPath, onWarn) {
+  try {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+  } catch (err) {
+    if (onWarn) onWarn("[Evergreen Trace] Failed to ensure directory:", err);
+  }
+}
+
+function readJsonFile(filePath, onWarn) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (onWarn) onWarn("[Evergreen Trace] Failed to read cache entry:", err);
+    return null;
+  }
+}
+
+function writeJsonFile(filePath, payload, onWarn) {
+  try {
+    fs.writeFileSync(filePath, JSON.stringify(payload), "utf8");
+  } catch (err) {
+    if (onWarn) onWarn("[Evergreen Trace] Failed to write cache entry:", err);
+  }
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {(msg: string, ...args: any[]) => void} [args.onWarn]
+ * @returns {{ getOrTransform: (content: string, filename: string, config: any, instrumentSource: Function) => { code: string, map: any, cacheKey: string, hit: boolean, meta: any } }}
+ */
+function createInstrumentCache({ projectRoot, onWarn }) {
+  const cacheEntriesDir = path.join(projectRoot, ".evergreen-cache", "entries");
+  ensureDir(cacheEntriesDir, onWarn);
+
+  function getOrTransform(content, filename, config, instrumentSource) {
+    const contentHash = hashContent(content);
+    const configHash = hashConfig(config);
+    const toolVersion = "v1";
+
+    const meta = { filename, contentHash, configHash, toolVersion };
+    const cacheKey = hashKey(meta);
+    const entryPath = path.join(cacheEntriesDir, `${cacheKey}.json`);
+
+    const cached = readJsonFile(entryPath, onWarn);
+    if (cached && typeof cached.code === "string") {
+      return {
+        code: cached.code,
+        map: cached.map || null,
+        cacheKey,
+        hit: true,
+        meta: cached.meta || meta,
+      };
+    }
+
+    const { code, map } = instrumentSource(content, filename, config);
+
+    writeJsonFile(
+      entryPath,
+      {
+        code,
+        map: map || null,
+        meta,
+      },
+      onWarn,
+    );
+
+    return { code, map: map || null, cacheKey, hit: false, meta };
+  }
+
+  return { getOrTransform };
+}
+
+module.exports = {
+  createInstrumentCache,
+};
+

package/src/register.js

@@ -0,0 +1,324 @@
+// register.js
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const Module = require("module");
+const micromatch = require("micromatch");
+const { instrumentSource } = require("./transform");
+const { createInstrumentCache } = require("./instrument-cache");
+
+// -----------------------------------------------------------------------------
+// 1. Project root detection
+// -----------------------------------------------------------------------------
+
+// For MVP we treat the CWD as the project root. Later you can walk up to find package.json.
+const PROJECT_ROOT = process.cwd();
+// Cache is managed by src/instrument-cache.js
+
+// -----------------------------------------------------------------------------
+// 2. Config loading
+// -----------------------------------------------------------------------------
+
+/**
+ * Shape of the in-memory Evergreen config.
+ * ignore/include are arrays of glob strings (not yet compiled).
+ */
+function loadConfig() {
+  const defaultConfig = {
+    ignore: ["node_modules/**", "dist/**", "coverage/**"],
+    include: [], // empty means "everything else"
+  };
+
+  let fileConfig = {};
+  const configPath = path.join(PROJECT_ROOT, ".evergreen-trace.json");
+
+  try {
+    if (fs.existsSync(configPath)) {
+      const raw = fs.readFileSync(configPath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object") {
+        fileConfig = {
+          ignore: Array.isArray(parsed.ignore) ? parsed.ignore : [],
+          include: Array.isArray(parsed.include) ? parsed.include : [],
+        };
+      }
+    }
+  } catch (err) {
+    // Fail-soft: just log and fall back to defaults.
+    safeLogWarn("[Evergreen Trace] Failed to load .evergreen-trace.json:", err);
+  }
+
+  // Env overrides (comma-separated lists)
+  const envIgnore =
+    process.env.EVERGREEN_TRACE_IGNORE &&
+    process.env.EVERGREEN_TRACE_IGNORE.split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+  const envInclude =
+    process.env.EVERGREEN_TRACE_INCLUDE &&
+    process.env.EVERGREEN_TRACE_INCLUDE.split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+  return {
+    ignore:
+      envIgnore && envIgnore.length
+        ? envIgnore
+        : fileConfig.ignore || defaultConfig.ignore,
+    include:
+      envInclude && envInclude.length
+        ? envInclude
+        : fileConfig.include || defaultConfig.include,
+  };
+}
+
+const CONFIG = loadConfig();
+const DEBUG =
+  process.env.EVERGREEN_TRACE_DEBUG === "1" ||
+  process.env.EVERGREEN_TRACE_DEBUG === "true";
+
+const instrumentCache = createInstrumentCache({
+  projectRoot: PROJECT_ROOT,
+  onWarn: safeLogWarn,
+});
+
+// Pre-compile glob patterns for selective instrumentation (Phase 4).
+const ignorePatterns = CONFIG.ignore || [];
+const includePatterns = CONFIG.include || [];
+const hasInclude = includePatterns.length > 0;
+
+function matchesAny(patterns, relPath) {
+  return patterns.length > 0 && micromatch.isMatch(relPath, patterns);
+}
+
+// -----------------------------------------------------------------------------
+// 3. Logging helpers (fail-soft)
+// -----------------------------------------------------------------------------
+
+function safeLog(...args) {
+  try {
+    // eslint-disable-next-line no-console
+    console.log(...args);
+  } catch (_) {
+    // ignore
+  }
+}
+
+function safeLogWarn(...args) {
+  try {
+    // eslint-disable-next-line no-console
+    console.warn(...args);
+  } catch (_) {
+    // ignore
+  }
+}
+
+function debugLog(...args) {
+  if (!DEBUG) return;
+  safeLog("[Evergreen Trace DEBUG]", ...args);
+}
+
+// -----------------------------------------------------------------------------
+// 4. Instrumentation decision stub (Phase 1)
+// -----------------------------------------------------------------------------
+
+/**
+ * Decide whether this absolute filename should be instrumented.
+ * Phase 1: only apply basic rules; glob-based include/ignore can be added later.
+ */
+function shouldInstrument(filename) {
+  // Skip internal Node modules and non-absolute paths
+  if (!path.isAbsolute(filename)) {
+    debugLog("Skipping (non-absolute or internal):", filename);
+    return false;
+  }
+
+  const normalized = filename.split(path.sep).join(path.posix.sep);
+
+  // Skip anything under node_modules
+  if (normalized.includes("/node_modules/")) {
+    debugLog("Skipping (node_modules):", filename);
+    return false;
+  }
+
+  // Skip this repo's own extension/runtime code (e.g. src/register.js)
+  const srcRoot = path
+    .join(PROJECT_ROOT, "packages", "evergreen-trace", "src")
+    .split(path.sep)
+    .join(path.posix.sep);
+
+  if (normalized.startsWith(srcRoot)) {
+    debugLog("Skipping (extension/runtime src):", filename);
+    return false;
+  }
+
+  // Skip SDK build output to avoid require cycles
+  if (normalized.includes("/packages/evergreen-sdk/dist/")) {
+    debugLog("Skipping (SDK build output):", filename);
+    return false;
+  }
+
+  // Skip all tests/fixtures. Node's test runner may execute these under ESM
+  // semantics, which can conflict with CJS fixtures (module.exports) after
+  // transformation.
+  if (normalized.includes("/__tests__/")) {
+    debugLog("Skipping (tests/fixtures):", filename);
+    return false;
+  }
+
+  // Only instrument .js and .cjs
+  if (!filename.endsWith(".js") && !filename.endsWith(".cjs")) {
+    debugLog("Skipping (extension):", filename);
+    return false;
+  }
+
+  // Phase 4: config-based ignore/include using project-root-relative POSIX paths
+  const rel = path.relative(PROJECT_ROOT, filename);
+  const relPosix = rel.split(path.sep).join("/");
+
+  // Ignore takes precedence
+  if (matchesAny(ignorePatterns, relPosix)) {
+    debugLog("Skipping (config ignore):", filename);
+    return false;
+  }
+
+  // If include list exists, only instrument included paths
+  if (hasInclude && !matchesAny(includePatterns, relPosix)) {
+    debugLog("Skipping (not in include set):", filename);
+    return false;
+  }
+
+  return true;
+}
+
+// -----------------------------------------------------------------------------
+// 5. Transform stub (Phase 1)
+// -----------------------------------------------------------------------------
+
+// -----------------------------------------------------------------------------
+// 5. Cache-backed instrumentation (Phase 2)
+// -----------------------------------------------------------------------------
+
+function getTransformedFromCacheOrBabel(content, filename, config) {
+  const result = instrumentCache.getOrTransform(
+    content,
+    filename,
+    config,
+    instrumentSource,
+  );
+  if (result.hit) debugLog("Cache hit for", filename);
+  else debugLog("Cache miss for", filename, "- running Babel transform");
+  return { code: result.code, map: result.map || null };
+}
+
+function stripExistingSourceMappingURL(code) {
+  const lines = code.split("\n");
+  while (
+    lines.length > 0 &&
+    /sourceMappingURL=/.test(lines[lines.length - 1].trim())
+  ) {
+    lines.pop();
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Phase 3: attach inline source map if available.
+ *
+ * @param {string} code
+ * @param {string} filename
+ * @param {any} maybeMap
+ */
+function attachSourceMapIfPresent(code, filename, maybeMap) {
+  if (!maybeMap) {
+    return code;
+  }
+
+  try {
+    if (!maybeMap.file) {
+      maybeMap.file = filename;
+    }
+
+    const json = JSON.stringify(maybeMap);
+    const base64 = Buffer.from(json, "utf8").toString("base64");
+    const comment =
+      "//# sourceMappingURL=data:application/json;base64," + base64;
+
+    const stripped = stripExistingSourceMappingURL(code);
+
+    return stripped + "\n" + comment + "\n";
+  } catch (err) {
+    safeLogWarn(
+      "[Evergreen Trace] Failed to attach source map for",
+      filename,
+      err,
+    );
+    return code;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// 6. Capture and wrap Module.prototype._compile
+// -----------------------------------------------------------------------------
+
+const originalCompile = Module.prototype._compile;
+
+function evergreenCompileHook(content, filename) {
+  // Early exit: if anything goes wrong, fall back to original behavior.
+  try {
+    if (!shouldInstrument(filename)) {
+      return originalCompile.call(this, content, filename);
+    }
+
+    debugLog("Instrumenting file:", filename);
+
+    // Phase 2: transform with Babel + Evergreen plugin, with persistent cache.
+    const { code, map } = getTransformedFromCacheOrBabel(
+      content,
+      filename,
+      CONFIG,
+    );
+
+    // Phase 2: ignore map until Phase 3 wires in source maps.
+    const finalCode = attachSourceMapIfPresent(code, filename, map);
+
+    return originalCompile.call(this, finalCode, filename);
+  } catch (err) {
+    safeLogWarn(
+      "[Evergreen Trace] Failed during compile hook for",
+      filename,
+      err,
+    );
+    // Fail-safe: execute original code so the app still runs.
+    return originalCompile.call(this, content, filename);
+  }
+}
+
+// Install the hook
+Module.prototype._compile = function evergreenCompileWrapper(
+  content,
+  filename,
+) {
+  return evergreenCompileHook.call(this, content, filename);
+};
+
+// -----------------------------------------------------------------------------
+// 7. Startup banner
+// -----------------------------------------------------------------------------
+
+safeLog("🌲 Evergreen Trace: Loader active (Phase 1).");
+
+if (DEBUG) {
+  safeLog("[Evergreen Trace] DEBUG mode enabled.");
+  safeLog("[Evergreen Trace] Project root:", PROJECT_ROOT);
+  safeLog("[Evergreen Trace] Config:", CONFIG);
+}
+
+// Test hooks (used only in automated tests to verify config behavior)
+if (process.env.NODE_ENV === "test") {
+  module.exports.__test__ = {
+    shouldInstrument,
+  };
+}

package/src/transform.js

@@ -0,0 +1,84 @@
+"use strict";
+
+const { transformSync } = require("@babel/core");
+const path = require("path");
+
+// Try to resolve the Evergreen Babel plugin. In this monorepo it should be
+// available as a local package; in published form it will be a normal
+// dependency.
+let evergreenBabelPlugin;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  evergreenBabelPlugin = require("evergreen-babel-plugin");
+  // Support both default and named export styles
+  if (evergreenBabelPlugin && evergreenBabelPlugin.default) {
+    evergreenBabelPlugin = evergreenBabelPlugin.default;
+  }
+} catch (err) {
+  throw new Error(
+    "[Evergreen Trace] Failed to load evergreen-babel-plugin. " +
+      "Ensure it is installed and built before using the loader.\n" +
+      String(err),
+  );
+}
+
+/**
+ * Perform on-the-fly instrumentation of a single source file.
+ * Returns transformed code and a source map.
+ *
+ * @param {string} content - Original source code.
+ * @param {string} filename - Absolute path to the file on disk.
+ * @param {object} config - Evergreen config (include/ignore etc).
+ * @returns {{ code: string; map: any }}
+ */
+function instrumentSource(content, filename, config) {
+  const result = transformSync(content, {
+    filename,
+    // Pass config through in case the plugin wants to use it.
+    plugins: [[evergreenBabelPlugin, { evergreenConfig: config }]],
+    sourceMaps: true,
+    ast: false,
+    // Allow parsing modern syntax; tweak as needed.
+    parserOpts: {
+      sourceType: "unambiguous",
+    },
+    generatorOpts: {
+      // Keep output readable; not strictly required.
+      compact: false,
+    },
+  });
+
+  if (!result || typeof result.code !== "string") {
+    throw new Error(
+      `[Evergreen Trace] Babel transform returned no code for ${filename}`,
+    );
+  }
+
+  let map = result.map || null;
+
+  if (map) {
+    // Ensure the map clearly references the transformed file and original source.
+    map.file = filename;
+    if (!Array.isArray(map.sources) || map.sources.length === 0) {
+      map.sources = [filename];
+    } else {
+      map.sources[0] = filename;
+    }
+
+    // Normalize sources to absolute paths so debuggers and Jump to Code work
+    // regardless of how Babel chose to emit them.
+    map.sources = map.sources.map((s) =>
+      path.isAbsolute(s) ? s : path.resolve(path.dirname(filename), s),
+    );
+  }
+
+  return {
+    code: result.code,
+    map,
+  };
+}
+
+module.exports = {
+  instrumentSource,
+};
+