fix(rewriter): emit valid ESM imports for instrumented modules (#8526)

The local `traceAsyncIterator` transform read `state.sourceType`, but the
vendored matcher only exposes `state.moduleType`. The resulting `undefined`
fell into the CJS branch on every ESM file and baked `require()` into pure
ESM modules such as `@langchain/langgraph/dist/pregel/index.js`. When the
vendored ESM branch did fire, the injected specifier was the absolute
filesystem path returned by `require.resolve('dc-polyfill')`, which Node's
ESM resolver rejects with `ERR_INVALID_MODULE_SPECIFIER`.

Three coordinated pieces close it:

1. The local transform reads `moduleType` and emits the
   default-import-plus-destructure shape used by the vendored transform.
   Named imports from `dc-polyfill` are not recoverable via Node's CJS to
   ESM interop because the module does `module.exports = dc` at runtime.
2. The rewriter pre-computes a path form (for `require()`) and a `file://`
   URL (for `import`) and dispatches to one of two matchers by `moduleType`.
3. `compiler.parse` forwards `isModule` to oxc as `sourceType` so the
   option is honoured by both parser backends instead of silently lost.

Fixes: #7991

Author: BridgeAR

packages/datadog-instrumentations/src/helpers/rewriter/compiler.js

@@ -19,9 +19,10 @@ const compiler = {
       // TODO: Figure out ESBuild `createRequire` issue and remove this hack.
       const oxc = runtimeRequire(['oxc', 'parser'].join('-'))
 
-      compiler.parse = (sourceText, options) => {
+      compiler.parse = (sourceText, { range, isModule } = {}) => {
         const { program, errors } = oxc.parseSync('index.js', sourceText, {
-          ...options,
+          range,
+          sourceType: isModule ? 'module' : 'script',
           preserveParens: false,
         })
 

packages/datadog-instrumentations/src/helpers/rewriter/index.js

@@ -2,15 +2,25 @@
 
 const { readFileSync } = require('fs')
 const { join } = require('path')
+const { pathToFileURL } = require('url')
 const log = require('../../../../dd-trace/src/log')
 const { create } = require('../../../../../vendor/dist/@apm-js-collab/code-transformer')
 const { traceAsyncIterator, traceIterator } = require('./transforms')
 const instrumentations = require('./instrumentations')
 
-let dcPolyfill
+// `dc-polyfill` is referenced from injected `require()` (CJS) and `import`
+// (ESM) statements that the transformer splices into the rewritten module.
+// `require()` accepts an absolute filesystem path; the ESM resolver rejects it
+// with `ERR_INVALID_MODULE_SPECIFIER` and needs a `file://` URL instead. We
+// pre-compute both forms here so each matcher hands the transformer a
+// specifier that is valid for the module type it is rewriting.
+let dcPolyfillCjs
+let dcPolyfillEsm
 
 try {
-  dcPolyfill = require.resolve('dc-polyfill').replaceAll('\\', '/')
+  const resolved = require.resolve('dc-polyfill')
+  dcPolyfillCjs = resolved.replaceAll('\\', '/')
+  dcPolyfillEsm = pathToFileURL(resolved).href
 } catch {
   // The `dc-polyfill` module is unavailable for some reason (like bundling).
   // Let's just keep the default of using `diagnostics-channel` as a fallback
@@ -20,10 +30,13 @@ try {
 /** @type {Record<string, string>} map of module base name to version */
 const moduleVersions = {}
 const disabled = new Set()
-const matcher = create(instrumentations, dcPolyfill)
+const matcherCjs = create(instrumentations, dcPolyfillCjs)
+const matcherEsm = create(instrumentations, dcPolyfillEsm)
 
-matcher.addTransform('traceIterator', traceIterator)
-matcher.addTransform('traceAsyncIterator', traceAsyncIterator)
+for (const matcher of [matcherCjs, matcherEsm]) {
+  matcher.addTransform('traceIterator', traceIterator)
+  matcher.addTransform('traceAsyncIterator', traceAsyncIterator)
+}
 
 function rewrite (content, filename, format) {
   if (!content) return content
@@ -41,6 +54,7 @@ function rewrite (content, filename, format) {
 
   if (disabled.has(moduleName)) return content
 
+  const matcher = moduleType === 'esm' ? matcherEsm : matcherCjs
   const transformer = matcher.getTransformer(moduleName, version, filePath)
 
   if (!transformer) return content

packages/datadog-instrumentations/src/helpers/rewriter/transforms.js

@@ -10,17 +10,25 @@ const tracingChannelPredicate = (node) => (
 )
 
 const transforms = module.exports = {
-  tracingChannelImport ({ dcModule, sourceType }, node) {
+  /**
+   * @param {{ dcModule: string, moduleType: 'esm' | 'cjs' }} state
+   * @param {import('estree').Program} node
+   */
+  tracingChannelImport ({ dcModule, moduleType }, node) {
     if (node.body.some(tracingChannelPredicate)) return
 
+    // The vendored matcher state exposes `moduleType` (`esm` / `cjs`), so we
+    // read that field directly. Naming it `sourceType` here used to silently
+    // pick the CJS branch for every ESM file, leaving `require()` baked into
+    // pure ESM modules like `@langchain/langgraph/dist/pregel/index.js`.
+    const isModule = moduleType === 'esm'
+
     const index = node.body.findIndex(child => child.directive === 'use strict')
-    const code = isModuleSourceType(sourceType)
-      ? `import { tracingChannel as tr_ch_apm_tracingChannel } from "${dcModule}"`
+    const code = isModule
+      ? `import tr_ch_apm_dc from "${dcModule}"; const {tracingChannel: tr_ch_apm_tracingChannel} = tr_ch_apm_dc`
       : `const {tracingChannel: tr_ch_apm_tracingChannel} = require("${dcModule}")`
 
-    node.body.splice(index + 1, 0, parse(code, {
-      isModule: isModuleSourceType(sourceType),
-    }).body[0])
+    node.body.splice(index + 1, 0, ...parse(code, { isModule }).body)
   },
 
   tracingChannelDeclaration (state, node) {
@@ -53,13 +61,6 @@ function traceAny (state, node, _parent, ancestry) {
   }
 }
 
-/**
- * @param {string} sourceType
- */
-function isModuleSourceType (sourceType) {
-  return sourceType === 'module' || sourceType === 'esm'
-}
-
 function traceFunction (state, node, program) {
   transforms.tracingChannelDeclaration(state, program)
 

packages/datadog-instrumentations/test/helpers/rewriter/index.spec.js

@@ -1,9 +1,11 @@
 'use strict'
 
-const { readFileSync } = require('node:fs')
+const { mkdtempSync, readFileSync, writeFileSync } = require('node:fs')
+const { tmpdir } = require('node:os')
 const { resolve, join, dirname } = require('node:path')
 const Module = require('node:module')
 const assert = require('node:assert')
+const { pathToFileURL } = require('node:url')
 const { beforeEach, describe, it } = require('mocha')
 const proxyquire = require('proxyquire')
 const sinon = require('sinon')
@@ -261,6 +263,19 @@ describe('check-require-cache', () => {
           },
           channelName: 'trace_class_private_method',
         },
+        {
+          module: {
+            name: 'test-esm',
+            versionRange: '>=0.1',
+            filePath: 'pregel-class.js',
+          },
+          functionQuery: {
+            methodName: 'stream',
+            className: 'Pregel',
+          },
+          channelName: 'pregel_stream',
+          transform: 'traceAsyncIterator',
+        },
       ],
     })
   })
@@ -522,8 +537,42 @@ describe('check-require-cache', () => {
     content = readFileSync(filename, 'utf8')
     content = rewriter.rewrite(content, filename, 'module')
 
-    assert.match(content, /\bimport\s+.+\s+from\s+"/)
+    assert.match(content, /\bimport\s+.+\s+from\s+"file:\/\//)
     assert.match(content, /tr_ch_apm_tracingChannel/)
     assert.doesNotMatch(content, /require\("/)
   })
+
+  // Covers the local `traceAsyncIterator` transform shape used by the langgraph
+  // integration. Goes through `addTransform`, which the iterator-transform path
+  // unique to dd-trace uses, not the vendored orchestrion transform that the
+  // `kind: 'AsyncIterator'` test above happens to hit.
+  it('should rewrite ESM modules without injecting require() for the traceAsyncIterator transform', async () => {
+    const filename = resolve(__dirname, 'node_modules', 'test-esm', 'pregel-class.js')
+    const source = readFileSync(filename, 'utf8')
+
+    const rewritten = rewriter.rewrite(source, filename, 'module')
+
+    assert.match(rewritten, /^import\s/m, 'expected an ESM import in the rewritten output')
+    assert.doesNotMatch(rewritten, /\brequire\s*\(/, 'CJS require() must not appear in ESM output')
+    assert.match(rewritten, /from\s+"file:\/\/[^"]+"/, 'dc-polyfill specifier must be a file:// URL for ESM')
+
+    // End-to-end: write the rewritten module to disk and dynamic-import it.
+    // This is what fails at runtime today when the local transform emits
+    // `require()` (no `require` in ESM scope) or a bare absolute path (Node
+    // rejects with ERR_INVALID_MODULE_SPECIFIER).
+    const dir = mkdtempSync(join(tmpdir(), 'dd-rewriter-esm-'))
+    writeFileSync(join(dir, 'package.json'), '{"type":"module"}')
+    const outFile = join(dir, 'pregel-class.mjs')
+    writeFileSync(outFile, rewritten)
+
+    ch = tracingChannel('orchestrion:test-esm:pregel_stream')
+    subs = { start: sinon.spy() }
+    ch.subscribe(subs)
+
+    const mod = await import(pathToFileURL(outFile).href)
+    const iter = new mod.Pregel().stream()
+    await iter.next()
+
+    assert.ok(subs.start.calledOnce, 'instrumented start channel should fire once')
+  })
 })