@apm-js-collab/code-transformer 0.9.0 → 0.11.0

package/README.md

@@ -3,7 +3,7 @@
 This is a library to aid in instrumenting Node.js libraries at build or load
 time.
 
-It uses SWC's Rust AST walker to inject code that calls Node.js
+It uses an AST walker to inject code that calls Node.js
 [`TracingChannel`](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel).
 
 You likely don't want to use this library directly; instead, consider using:
@@ -16,18 +16,7 @@ You likely don't want to use this library directly; instead, consider using:
 
 ## JavaScript
 
-`@apm-js-collab/code-transformer` exposes the Rust library as a WebAssembly
-module.
-
-### Building
-
-To build the JavaScript module:
-
-- Ensure you have [Rust installed](https://www.rust-lang.org/tools/install)
-- Install the wasm toolchain\
-  `rustup target add wasm32-unknown-unknown --toolchain stable`
-- Install dependencies and build the module\
-  `npm install && npm run build`
+`@apm-js-collab/code-transformer` exposes the library.
 
 ### Usage
 
@@ -70,10 +59,6 @@ if (transformer === undefined) {
 const inputCode = "async function fetch() { return 42; }";
 const result = transformer.transform(inputCode, "unknown");
 console.log(result.code);
-
-// Both the matcher and transformer should be freed after use!
-matcher.free();
-transformer.free();
 ```
 
 ### Export Aliases
@@ -114,23 +99,23 @@ type FunctionKind = "Sync" | "Async";
 ```ts
 type FunctionQuery =
     | // Match class constructor
-    { className: string; index?: number; isExportAlias?: boolean }
+    { className: string; index?: number | null; isExportAlias?: boolean }
     | // Match class method
     {
         className: string;
         methodName: string;
         kind: FunctionKind;
-        index?: number;
+        index?: number | null;
         isExportAlias?: boolean;
     }
     | // Match method on objects
-    { methodName: string; kind: FunctionKind; index?: number }
+    { methodName: string; kind: FunctionKind; index?: number | null }
     | // Match standalone function
-    { functionName: string; kind: FunctionKind; index?: number; isExportAlias?: boolean }
+    { functionName: string; kind: FunctionKind; index?: number | null; isExportAlias?: boolean }
     | // Match arrow function or function expression
-    { expressionName: string; kind: FunctionKind; index?: number; isExportAlias?: boolean };
+    { expressionName: string; kind: FunctionKind; index?: number | null; isExportAlias?: boolean };
     | // Match private class methods
-    { className: string; privateMethodName: string; kind: FunctionKind; index?: number };
+    { className: string; privateMethodName: string; kind: FunctionKind; index?: number | null };
 ```
 
 #### **`ModuleMatcher`**
@@ -139,7 +124,7 @@ type FunctionQuery =
 type ModuleMatcher = {
     name: string; // Module name
     versionRange: string; // Matching semver range
-    filePath: string; // Path to the file from the module root
+    filePath: string; // Relative Unix-style path to the file from the module root (e.g. "lib/index.js")
 };
 ```
 
@@ -156,18 +141,18 @@ type InstrumentationConfig = {
 ### Functions
 
 ```ts
-create(configs: InstrumentationConfig[], dc_module?: string | null): InstrumentationMatcher;
+create(configs: InstrumentationConfig[], dcModule?: string | null): InstrumentationMatcher;
 ```
 
 Create a matcher for one or more instrumentation configurations.
 
 - `configs` - Array of instrumentation configurations.
-- `dc_module` - Optional module to import `diagnostics_channel` API from.
+- `dcModule` - Optional module to import `diagnostics_channel` API from.
 
 #### **`InstrumentationMatcher`**
 
 ```ts
-getTransformer(module_name: string, version: string, file_path: string): Transformer | undefined;
+getTransformer(moduleName: string, version: string, filePath: string): Transformer | undefined;
 ```
 
 Gets a transformer for a specific module and file.
@@ -175,36 +160,24 @@ Gets a transformer for a specific module and file.
 Returns a `Transformer` for the given module, or `undefined` if there were no
 matching instrumentation configurations.
 
-- `module_name` - Name of the module.
+- `moduleName` - Name of the module.
 - `version` - Version of the module.
-- `file_path` - Path to the file from the module root.
-
-```ts
-free(): void;
-```
-
-Free the matcher memory when it's no longer needed.
+- `filePath` - Relative Unix-style path to the file from the module root (e.g. `"lib/index.js"`). Windows-style backslash paths are also accepted and will be normalized automatically.
 
 #### **`Transformer`**
 
 ```ts
-transform(code: string, module_type: ModuleType, sourcemap?: string | undefined): TransformOutput;
+transform(code: string | Buffer, moduleType: ModuleType, sourcemap?: string | undefined): TransformOutput;
 ```
 
 Transforms the code, injecting tracing as configured.
 
 Returns `{ code, map }`. `map` will be undefined if no sourcemap was supplied.
 
-- `code` - The JavaScript/TypeScript code to transform.
-- `module_type` - The type of module being transformed.
+- `code` - The JavaScript code to transform.
+- `moduleType` - The type of module being transformed.
 - `sourcemap` - Optional existing source map for the code.
 
-```ts
-free(): void;
-```
-
-Free the transformer memory when it's no longer needed.
-
 ## License
 
 See LICENSE

package/index.d.ts

@@ -1,6 +1,114 @@
-import type { InstrumentationConfig, InstrumentationMatcher } from './pkg/orchestrion_js';
+/* tslint:disable */
+/* eslint-disable */
+import type { Node } from 'estree';
 /**
  * Create a new instrumentation matcher from an array of instrumentation configs.
  */
-export declare function create(configs: InstrumentationConfig[], dc_module?: string | null): InstrumentationMatcher;
-export type { FunctionKind, FunctionQuery, InstrumentationConfig, InstrumentationMatcher, ModuleMatcher, ModuleType, TransformOutput, Transformer, } from './pkg/orchestrion_js';
+export function create(configs: InstrumentationConfig[], dc_module?: string | null): InstrumentationMatcher;
+/**
+ * Output of a transformation operation
+ */
+export interface TransformOutput {
+    /**
+     * The transformed JavaScript code
+     */
+    code: string;
+    /**
+     * The sourcemap for the transformation (if generated)
+     */
+    map: string | undefined;
+}
+
+/**
+ * The kind of function
+ */
+export type FunctionKind = "Sync" | "Async" | "Callback";
+
+/**
+ * Describes which function to instrument
+ */
+export type FunctionQuery = { className: string; methodName: string; kind: FunctionKind; index?: number | null; isExportAlias?: boolean } | { className: string; privateMethodName: string; kind: FunctionKind; index?: number | null } | { className: string; index?: number | null; isExportAlias?: boolean } | { methodName: string; kind: FunctionKind; index?: number | null } | { functionName: string; kind: FunctionKind; index?: number | null; isExportAlias?: boolean } | { expressionName: string; kind: FunctionKind; index?: number | null; isExportAlias?: boolean };
+
+/**
+ * A custom transform function registered via `addTransform`.
+ * Receives the instrumentation state and the matched AST node.
+ */
+export type CustomTransform = (state: unknown, node: Node, parent: Node, ancestry: Node[]) => void;
+
+/**
+ * Configuration for injecting instrumentation code
+ */
+export interface InstrumentationConfig {
+    /**
+     * The name of the diagnostics channel to publish to
+     */
+    channelName: string;
+    /**
+     * The module matcher to identify the module and file to instrument
+     */
+    module: ModuleMatcher;
+    /**
+     * The function query to identify the function to instrument
+     */
+    functionQuery: FunctionQuery;
+    /**
+     * The name of a custom transform registered via `addTransform`.
+     * When set, takes precedence over `functionQuery.kind`.
+     */
+    transform?: string;
+}
+
+/**
+ * Describes the module and file path you would like to match
+ */
+export interface ModuleMatcher {
+    /**
+     * The name of the module you want to match
+     */
+    name: string;
+    /**
+     * The semver range that you want to match
+     */
+    versionRange: string;
+    /**
+     * The path of the file you want to match from the module root
+     */
+    filePath: string;
+}
+
+/**
+ * The type of module being passed - ESM, CJS or unknown
+ */
+export type ModuleType = "esm" | "cjs" | "unknown";
+
+/**
+ * The InstrumentationMatcher is responsible for matching specific modules
+ */
+export class InstrumentationMatcher {
+  private constructor();
+  free(): void;
+  /**
+   * Get a transformer for the given module name, version and file path.
+   * Returns `undefined` if no matching instrumentations are found.
+   */
+  getTransformer(moduleName: string, version: string, filePath: string): Transformer | undefined;
+  /**
+   * Register a custom transform function under the given name.
+   * The name can then be referenced via the `transform` option in an `InstrumentationConfig`.
+   */
+  addTransform(name: string, fn: CustomTransform): void;
+}
+/**
+ * The Transformer is responsible for transforming JavaScript code.
+ */
+export class Transformer {
+  private constructor();
+  free(): void;
+  /**
+   * Transform JavaScript code and optionally sourcemap.
+   *
+   * # Errors
+   * Returns an error if the transformation fails to find injection points.
+   */
+  transform(code: string | Buffer, moduleType: ModuleType, sourcemap?: string | null): TransformOutput;
+}

package/index.js

@@ -1,18 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.create = create;
-// ./pkg/orchestrion_js.js has a side effect of loading the wasm binary. 
-// We only want that if the library is actually used!
-var cachedCreate;
-/**
- * Create a new instrumentation matcher from an array of instrumentation configs.
- */
-function create(configs, dc_module) {
-    if (!cachedCreate) {
-        cachedCreate = require('./pkg/orchestrion_js.js').create;
-    }
-    if (cachedCreate === undefined) {
-        throw new Error("Failed to load '@apm-js-collab/code-transformer'");
-    }
-    return cachedCreate(configs, dc_module);
-}
+'use strict'
+
+module.exports = require('./lib')

package/lib/index.js

@@ -0,0 +1,17 @@
+'use strict'
+
+const { InstrumentationMatcher } = require('./matcher')
+
+/**
+ * Creates a new {@link InstrumentationMatcher} from the given instrumentation configs.
+ *
+ * @param {object[]} configs - Instrumentation configuration objects.
+ * @param {string} [dcModule] - The diagnostics_channel module specifier to use for imports.
+ *   Deprecated: pass `dcModule` via each config's `dcModule` field instead.
+ * @returns {InstrumentationMatcher}
+ */
+function create (configs, dcModule) {
+  return new InstrumentationMatcher(configs, dcModule)
+}
+
+module.exports = { create }

package/lib/matcher.js

@@ -0,0 +1,83 @@
+'use strict'
+
+const semifies = require('semifies')
+const { Transformer } = require('./transformer')
+
+/**
+ * Matches instrumentation configs against a given module/file/version triple and
+ * returns a cached {@link Transformer} for matching configs.
+ */
+class InstrumentationMatcher {
+  #configs = []
+  #dcModule = null
+  #transformers = {}
+  #customTransforms = {}
+
+  /**
+   * @param {object[]} configs - Array of instrumentation configuration objects.
+   * @param {string} [dcModule] - The diagnostics_channel module specifier to inject.
+   *   Defaults to `'diagnostics_channel'`.
+   */
+  constructor (configs, dcModule) {
+    this.#configs = configs
+    this.#dcModule = dcModule || 'diagnostics_channel'
+  }
+
+  /** Releases all cached transformers, freeing any associated resources. */
+  free () {
+    this.#transformers = {}
+  }
+
+  /**
+   * Registers a custom transform function under the given operator name.
+   *
+   * Custom transforms override built-in ones when an instrumentation config
+   * specifies the same `transform` value.
+   *
+   * @param {string} name - Operator name (e.g. `'traceSync'`).
+   * @param {Function} fn - Transform function `(state, node, parent, ancestry) => void`.
+   */
+  addTransform (name, fn) {
+    this.#customTransforms[name] = fn
+  }
+
+  /**
+   * Returns a {@link Transformer} for the given module/file/version, or `undefined`
+   * if no registered config matches.
+   *
+   * Results are cached by a `moduleName/filePath@version` key.
+   *
+   * @param {string} moduleName - The npm package name (e.g. `'express'`).
+   * @param {string} version - The installed semver version string.
+   * @param {string} filePath - The relative file path within the package.
+   * @returns {import('./transformer').Transformer|undefined}
+   */
+  getTransformer (moduleName, version, filePath) {
+    filePath = filePath.replace(/\\/g, '/')
+
+    const id = `${moduleName}/${filePath}@${version}`
+
+    if (this.#transformers[id]) return this.#transformers[id]
+
+    const configs = this.#configs.filter(({ module: mod }) =>
+      mod.name === moduleName &&
+      mod.filePath === filePath &&
+      semifies(version, mod.versionRange)
+    )
+
+    if (configs.length === 0) return
+
+    this.#transformers[id] = new Transformer(
+      moduleName,
+      version,
+      filePath,
+      configs,
+      this.#dcModule,
+      this.#customTransforms
+    )
+
+    return this.#transformers[id]
+  }
+}
+
+module.exports = { InstrumentationMatcher }

package/lib/transformer.js

@@ -0,0 +1,282 @@
+'use strict'
+
+const esquery = require('esquery')
+const { parse } = require('meriyah')
+const { generate } = require('astring')
+const transforms = require('./transforms')
+
+let SourceMapConsumer
+let SourceMapGenerator
+
+/**
+ * Applies a set of instrumentation configs to JavaScript source code by parsing
+ * it into an AST, locating the target functions via esquery selectors, injecting
+ * diagnostics_channel tracing wrappers, and regenerating the source.
+ */
+class Transformer {
+  #moduleName = null
+  #version = null
+  #filePath = null
+  #configs = []
+  #dcModule = null
+  #customTransforms = {}
+
+  /**
+   * @param {string} moduleName - The npm package name being instrumented.
+   * @param {string} version - The installed semver version string.
+   * @param {string} filePath - The relative file path within the package.
+   * @param {object[]} configs - Instrumentation configuration objects for this file.
+   * @param {string} dcModule - The diagnostics_channel module specifier to inject.
+   * @param {Record<string, Function>} [customTransforms] - Optional custom operator overrides.
+   */
+  constructor (moduleName, version, filePath, configs, dcModule, customTransforms = {}) {
+    this.#moduleName = moduleName // TODO: moduleName false for user module
+    this.#version = version
+    this.#filePath = filePath
+    this.#configs = configs
+    this.#dcModule = dcModule
+    this.#customTransforms = customTransforms
+  }
+
+  /** No-op — freeing resources is not needed for the JavaScript implementation. */
+  free () {}
+
+  /**
+   * Instruments `code` by injecting diagnostics_channel tracing around the
+   * target functions defined by this transformer's configs.
+   *
+   * @param {string|Buffer} code - Original JavaScript source, or a Buffer containing UTF-8 source.
+   * @param {'esm'|'cjs'|'unknown'} moduleType - Whether the source is an ES module or CommonJS.
+   * @param {string|object|null} [sourcemap] - Existing source map (raw string or object) to chain from.
+   * @returns {{ code: string, map?: string }}
+   *   The transformed source and an optional updated source map.
+   * @throws {Error} If no injection points are found for any config.
+   */
+  transform (code, moduleType, sourcemap) {
+    if (Buffer.isBuffer(code)) code = code.toString()
+    if (!code) return { code }
+
+    let ast
+    let aliases = {}
+    let injectionCount = 0
+
+    for (const config of this.#configs) {
+      const { astQuery, functionQuery = {} } = config
+
+      if (!ast) {
+        const options = {
+          loc: true,
+          ranges: true,
+          raw: true,
+          module: moduleType === 'esm',
+        }
+
+        try {
+          ast = parse(code, options)
+        } catch {
+          ast = parse(code, { ...options, module: !options.module })
+        }
+
+        if (moduleType === 'esm') { // TODO: cjs
+          aliases = this.#collectExportAliases(ast)
+        }
+      }
+
+      const resolvedFunctionQuery = this.#resolveExportAlias(functionQuery, aliases)
+      const query = astQuery || this.#fromFunctionQuery(resolvedFunctionQuery)
+      const state = {
+        ...config,
+        dcModule: this.#dcModule,
+        moduleType,
+        moduleVersion: this.#version,
+        functionQuery: resolvedFunctionQuery
+      }
+
+      state.operator = this.#getOperator(state)
+
+      esquery.traverse(ast, esquery.parse(query), (...args) => {
+        injectionCount++
+        this.#visit(state, ...args)
+      })
+    }
+
+    if (injectionCount === 0 && this.#configs.length > 0) {
+      const names = this.#configs.map(({ functionQuery = {} }) => {
+        const resolvedQuery = this.#resolveExportAlias(functionQuery, aliases)
+        const queryName = (q) => q.methodName || q.privateMethodName || q.functionName || q.expressionName || 'constructor'
+        const originalName = queryName(functionQuery)
+        const originalAlias = functionQuery.className || functionQuery.functionName || functionQuery.expressionName
+        const resolvedAlias = resolvedQuery.className || resolvedQuery.functionName || resolvedQuery.expressionName
+        if (originalAlias && originalAlias !== resolvedAlias) {
+          return `${originalAlias} (local name: ${resolvedAlias})`
+        }
+        return originalName
+      })
+      throw new Error(`Failed to find injection points for: ${JSON.stringify(names)}`)
+    }
+
+    if (ast) {
+      SourceMapConsumer ??= require('source-map').SourceMapConsumer
+      SourceMapGenerator ??= require('source-map').SourceMapGenerator
+
+      const file = `${this.#moduleName}/${this.#filePath}`
+      const sourceMapInput = sourcemap ? new SourceMapConsumer(sourcemap) : { file }
+      const sourceMap = new SourceMapGenerator(sourceMapInput)
+      const code = generate(ast, { sourceMap })
+      const map = sourceMap.toString()
+
+      return { code, map }
+    }
+
+    return { code }
+  }
+
+  /**
+   * Visitor called for each AST node that matches a config's query.
+   * Handles index-based filtering and delegates to the appropriate transform.
+   *
+   * @param {object} state - Merged config + runtime state for this traversal.
+   * @param {...unknown} args - `(node, parent, ancestry)` from esquery traverse.
+   */
+  #visit (state, ...args) {
+    const transform = this.#customTransforms[state.operator] ?? transforms[state.operator]
+    const { index = 0 } = state.functionQuery
+    const [node] = args
+    const type = node.init?.type || node.type
+
+    // Class nodes are visited for traceInstanceMethod (missing method patching),
+    // but when selecting by index we only want to count and match function nodes.
+    if (type !== 'ClassDeclaration' && type !== 'ClassExpression') {
+      state.functionIndex = ++state.functionIndex || 0
+
+      if (index !== null && index !== state.functionIndex) return
+    }
+
+    transform(state, ...args)
+  }
+
+  /**
+   * Resolves the operator name (transform function key) for a config.
+   *
+   * If the config has an explicit `transform` name it is used directly;
+   * otherwise the operator is derived from the `kind` field of `functionQuery`.
+   *
+   * @param {{ transform?: string, functionQuery: { kind?: string } }} state
+   * @returns {string} Operator name, e.g. `'tracePromise'`.
+   */
+  #getOperator ({ transform, functionQuery: { kind } }) {
+    if (transform) return transform
+
+    switch (kind) {
+      case 'Async': return 'tracePromise'
+      case 'Callback': return 'traceCallback'
+      case 'Sync': return 'traceSync'
+      default: return 'traceSync'
+    }
+  }
+
+  /**
+   * Collects a map of exported name → local name from `export { local as exported }`
+   * declarations so that instrumentation configs that reference export names can be
+   * resolved to local identifiers.
+   *
+   * @param {import('estree').Program} ast
+   * @returns {Record<string, string>} Map of exported name to local name.
+   */
+  #collectExportAliases (ast) {
+    const aliases = {}
+    for (const node of ast.body) {
+      if (node.type === 'ExportNamedDeclaration' && !node.source) {
+        for (const spec of node.specifiers) {
+          if (spec.exported && spec.local) {
+            const exportedName = spec.exported.name ?? spec.exported.value
+            const localName = spec.local.name ?? spec.local.value
+            if (exportedName && localName) {
+              aliases[exportedName] = localName
+            }
+          }
+        }
+      }
+    }
+    return aliases
+  }
+
+  /**
+   * If `functionQuery.isExportAlias` is set, replaces the exported identifier in
+   * `functionQuery` with the corresponding local name from `aliases`.
+   *
+   * @param {object} functionQuery
+   * @param {Record<string, string>} aliases - Map produced by {@link #collectExportAliases}.
+   * @returns {object} Resolved function query (may be the original object if unchanged).
+   */
+  #resolveExportAlias (functionQuery, aliases) {
+    if (!functionQuery.isExportAlias) return functionQuery
+    const { functionName, expressionName, className } = functionQuery
+    if (functionName && aliases[functionName]) {
+      return { ...functionQuery, functionName: aliases[functionName] }
+    }
+    if (expressionName && aliases[expressionName]) {
+      return { ...functionQuery, expressionName: aliases[expressionName] }
+    }
+    if (className && aliases[className]) {
+      return { ...functionQuery, className: aliases[className] }
+    }
+    return functionQuery
+  }
+
+  /**
+   * Builds a comma-separated esquery selector string from a `functionQuery` descriptor.
+   *
+   * Handles class methods, standalone functions, and expression assignments, producing
+   * multiple selector alternatives joined with `, `.
+   *
+   * @param {object} functionQuery
+   * @param {string} [functionQuery.className]
+   * @param {string} [functionQuery.methodName]
+   * @param {string} [functionQuery.privateMethodName]
+   * @param {string} [functionQuery.functionName]
+   * @param {string} [functionQuery.expressionName]
+   * @returns {string} esquery selector.
+   */
+  #fromFunctionQuery (functionQuery) {
+    const { functionName, expressionName, className } = functionQuery
+    const type = functionQuery.privateMethodName ? 'PrivateIdentifier' : 'Identifier'
+    const queries = []
+
+    let method = functionQuery.methodName || functionQuery.privateMethodName
+
+    if (className) {
+      method ??= 'constructor'
+      queries.push(
+        `[id.name="${className}"]`,
+        `[id.name="${className}"] > ClassExpression`,
+        `[id.name="${className}"] > ClassBody > [key.name="${method}"][key.type=${type}] > [async]`,
+        `[id.name="${className}"] > ClassExpression > ClassBody > [key.name="${method}"][key.type=${type}] > [async]`
+      )
+    } else if (method) {
+      queries.push(
+        `ClassBody > [key.name="${method}"][key.type=${type}] > [async]`,
+        `Property[key.name="${method}"][key.type=${type}] > [async]`
+      )
+    }
+
+    if (functionName) {
+      queries.push(`FunctionDeclaration[id.name="${functionName}"][async]`)
+    } else if (expressionName) {
+      queries.push(
+        `FunctionExpression[id.name="${expressionName}"][async]`,
+        `ArrowFunctionExpression[id.name="${expressionName}"][async]`,
+        `VariableDeclarator[id.name="${expressionName}"] > FunctionExpression[async]`,
+        `VariableDeclarator[id.name="${expressionName}"] > ArrowFunctionExpression[async]`,
+        `AssignmentExpression[left.property.name="${expressionName}"] > FunctionExpression[async]`,
+        `AssignmentExpression[left.property.name="${expressionName}"] > ArrowFunctionExpression[async]`,
+        `AssignmentExpression[left.name="${expressionName}"] > FunctionExpression[async]`,
+        `AssignmentExpression[left.name="${expressionName}"] > ArrowFunctionExpression[async]`
+      )
+    }
+
+    return queries.join(', ')
+  }
+}
+
+module.exports = { Transformer }