test(coverage): warm source maps before process exit (#9330)

Node can hang when native coverage resolves a large ESM source-map cache during isolate teardown. Resolve maps as scripts load so the final V8 snapshot retains all execution counters and foreign coverage directories remain untouched.

Refs: nodejs/node#49344

* test(coverage): disconnect source-map observer before teardown

Drain the last queued URLs and disconnect the Debugger session from the JavaScript exit event before Node runs native coverage serialization. This keeps late exit-time maps while avoiding a live observer during isolate teardown.

* test(coverage): avoid renderer and exit-time source-map lookups

Electron renderers lack a usable Node inspector, so connecting a Session prevents renderer preload and IPC instrumentation from starting. Explicit process.exit skips the scheduled warm-up, moving the full source-map backlog into the exit event where Node's teardown can hang.

Skip only renderer observers and drain pending maps before explicit exit; the exit hook now only disconnects.

Author: BridgeAR

scripts/c8-ci.js

@@ -21,8 +21,11 @@ const { rmSync } = require('node:fs')
 const path = require('node:path')
 
 const { convertV8DirToReport } = require('../integration-tests/coverage/merge-lcov')
+const baseNycConfig = require('../nyc.config')
+const { markCoverageDirectory } = require('./c8-source-map-cache')
 
 const repoRoot = path.resolve(__dirname, '..')
+const sourceMapCacheFile = require.resolve('./c8-source-map-cache')
 
 const script = process.argv[2]
 if (!script) {
@@ -31,17 +34,19 @@ if (!script) {
 }
 const extraArgs = process.argv.slice(3)
 
-let event = process.env.npm_lifecycle_event ?? ''
-if (process.env.PLUGINS) event += `-${process.env.PLUGINS}`
-const label = `-${event.replaceAll(/[^a-zA-Z0-9._-]+/g, '-')}`
-const v8Dir = path.join(repoRoot, '.nyc_output', `node-${process.version}${label}`, 'v8')
-const reportDir = path.join(repoRoot, 'coverage', `node-${process.version}${label}`)
+const v8Dir = path.join(repoRoot, baseNycConfig.tempDir, 'v8')
+const reportDir = path.join(repoRoot, baseNycConfig.reportDir)
 
 // Fresh collector each run so a previous run's profiles don't leak in.
 rmSync(v8Dir, { force: true, recursive: true })
 rmSync(reportDir, { force: true, recursive: true })
+markCoverageDirectory(v8Dir)
 
-const coverageEnv = { ...process.env, NODE_V8_COVERAGE: v8Dir }
+const sourceMapCacheRequire = `--require=${sourceMapCacheFile}`
+const nodeOptions = process.env.NODE_OPTIONS
+  ? `${sourceMapCacheRequire} ${process.env.NODE_OPTIONS}`
+  : sourceMapCacheRequire
+const coverageEnv = { ...process.env, NODE_OPTIONS: nodeOptions, NODE_V8_COVERAGE: v8Dir }
 
 /**
  * @param {string[]} command command + args to run with V8 coverage enabled

scripts/c8-source-map-cache.js

@@ -0,0 +1,86 @@
+'use strict'
+
+const { existsSync, mkdirSync, writeFileSync } = require('node:fs')
+const path = require('node:path')
+
+const OWNERSHIP_FILE = '.dd-c8-coverage'
+
+const coverageDir = process.env.NODE_V8_COVERAGE
+if (coverageDir && existsSync(path.join(coverageDir, OWNERSHIP_FILE))) {
+  const preloadList = require('node-preload')
+
+  if (!preloadList.includes(__filename)) preloadList.push(__filename)
+  warmSourceMaps()
+}
+
+/**
+ * @param {string} coverageDir
+ */
+function markCoverageDirectory (coverageDir) {
+  mkdirSync(coverageDir, { recursive: true })
+  writeFileSync(path.join(coverageDir, OWNERSHIP_FILE), '')
+}
+
+function warmSourceMaps () {
+  // Electron renderers are initialized without a usable Node inspector.
+  if (process.versions.electron && process.type === 'renderer') return
+
+  const inspector = require('node:inspector')
+  const { findSourceMap } = require('node:module')
+  const { debuglog } = require('node:util')
+
+  // Avoid resolving the whole source-map cache during coverage teardown.
+  // https://github.com/nodejs/node/issues/49344
+  const debug = debuglog('dd-trace:coverage')
+  const pendingUrls = new Set()
+  const session = new inspector.Session()
+  let warmingScheduled = false
+
+  /**
+   * @param {{ params: { url: string } }} message
+   */
+  function onScriptParsed ({ params: { url } }) {
+    if (!url.startsWith('file:')) return
+
+    pendingUrls.add(url)
+    if (!warmingScheduled) {
+      warmingScheduled = true
+      setImmediate(warmPendingSourceMaps)
+    }
+  }
+
+  function warmPendingSourceMaps () {
+    warmingScheduled = false
+    for (const url of pendingUrls) {
+      pendingUrls.delete(url)
+      try {
+        findSourceMap(url)
+      } catch (error) {
+        debug('Failed to warm source map for %s: %s', url, error.stack || error.message)
+      }
+    }
+  }
+
+  function disconnectSourceMapObserver () {
+    session.disconnect()
+  }
+
+  const originalExit = process.exit
+
+  /**
+   * @param {number|string|undefined} code
+   * @returns {never}
+   */
+  function exitWithWarmedSourceMaps (code) {
+    warmPendingSourceMaps()
+    originalExit(code)
+  }
+
+  session.connect()
+  session.on('Debugger.scriptParsed', onScriptParsed)
+  session.post('Debugger.enable')
+  process.exit = exitWithWarmedSourceMaps
+  process.once('exit', disconnectSourceMapObserver)
+}
+
+module.exports = { markCoverageDirectory }

scripts/c8-source-map-cache.spec.mjs

@@ -0,0 +1,235 @@
+import assert from 'node:assert/strict'
+import { execFile } from 'node:child_process'
+import { mkdir, mkdtemp, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { promisify } from 'node:util'
+
+import { afterEach, beforeEach, describe, it } from 'mocha'
+
+const execFileAsync = promisify(execFile)
+const require = createRequire(import.meta.url)
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const nodePreloadFile = require.resolve('node-preload')
+const preloadFile = path.join(repoRoot, 'scripts', 'c8-source-map-cache.js')
+const { markCoverageDirectory } = require('./c8-source-map-cache')
+
+/**
+ * @param {string | undefined} coverageDir
+ * @param {string} fixtureDir
+ * @param {object} [options]
+ * @param {string} [options.childCoverageDir]
+ * @param {boolean} [options.exitImmediately]
+ * @param {boolean} [options.failLookup]
+ * @param {number} [options.moduleCount]
+ */
+async function runFixture (coverageDir, fixtureDir, options = {}) {
+  const childCoverageDir = options.childCoverageDir ?? coverageDir
+  const moduleCount = options.moduleCount ?? 0
+  const childCoverageLog = path.join(fixtureDir, 'child-coverage-dir.txt')
+  const exitMarker = path.join(fixtureDir, 'exit-started')
+  const lookupLog = path.join(fixtureDir, 'source-map-lookups.txt')
+  const modulesDir = path.join(fixtureDir, 'modules')
+  const observerFile = path.join(fixtureDir, 'observe-source-map-lookups.js')
+  const parentFile = path.join(fixtureDir, 'parent.js')
+  const targetFile = path.join(fixtureDir, 'target.mjs')
+
+  await mkdir(modulesDir)
+  const moduleFiles = new Array(moduleCount)
+  const importLines = new Array(moduleCount)
+  for (let i = 0; i < moduleCount; i++) {
+    const moduleFile = path.join(modulesDir, `${i}.mjs`)
+    moduleFiles[i] = writeFile(moduleFile, `export default ${i}\n//# sourceMappingURL=${i}.mjs.map\n`)
+    importLines[i] = `import ${JSON.stringify(pathToFileURL(moduleFile).href)}`
+  }
+  await Promise.all(moduleFiles)
+
+  await writeFile(observerFile, String.raw`
+    'use strict'
+    const fs = require('node:fs')
+    const inspector = require('node:inspector')
+    const Module = require('node:module')
+    const originalDisconnect = inspector.Session.prototype.disconnect
+    const originalFindSourceMap = Module.findSourceMap
+    inspector.Session.prototype.disconnect = function () {
+      originalDisconnect.call(this)
+      fs.appendFileSync(${JSON.stringify(lookupLog)}, 'disconnect\n')
+    }
+    Module.findSourceMap = function (url) {
+      const phase = fs.existsSync(${JSON.stringify(exitMarker)}) ? 'exit:' : ''
+      fs.appendFileSync(${JSON.stringify(lookupLog)}, phase + url + '\n')
+      ${options.failLookup
+        ? `const error = new Error('source map lookup failed')
+      if (url.endsWith('/target.mjs')) error.stack = undefined
+      throw error`
+        : ''}
+      return originalFindSourceMap(url)
+    }
+  `)
+  await writeFile(parentFile, `
+    'use strict'
+    const { spawnSync } = require('node:child_process')
+    const preloadList = require(${JSON.stringify(nodePreloadFile)})
+    preloadList.unshift(${JSON.stringify(observerFile)})
+    require(${JSON.stringify(preloadFile)})
+    const childEnv = {
+      ...process.env,
+      NODE_OPTIONS: '',
+      npm_lifecycle_event: 'nested-script',
+    }
+    ${childCoverageDir === undefined
+      ? "childEnv.NODE_V8_COVERAGE = ''"
+      : `childEnv.NODE_V8_COVERAGE = ${JSON.stringify(childCoverageDir)}`}
+    const result = spawnSync(process.execPath, [${JSON.stringify(targetFile)}], {
+      env: childEnv,
+      stdio: 'inherit',
+    })
+    process.exitCode = result.status ?? 1
+  `)
+  await writeFile(targetFile, `
+    import { writeFileSync } from 'node:fs'
+    import { createRequire } from 'node:module'
+    ${importLines.join('\n')}
+    const require = createRequire(import.meta.url)
+    writeFileSync(
+      ${JSON.stringify(childCoverageLog)},
+      process.env.NODE_V8_COVERAGE ?? ''
+    )
+    function markCoverageTail () {
+      globalThis.coverageTail = true
+    }
+    ${options.exitImmediately
+      ? `process.prependOnceListener('exit', () => writeFileSync(${JSON.stringify(exitMarker)}, ''))
+    markCoverageTail()
+    process.exit()`
+      : "process.once('beforeExit', markCoverageTail)"}
+  `)
+
+  const env = {
+    ...process.env,
+    NODE_V8_COVERAGE: coverageDir === undefined ? '' : coverageDir,
+  }
+  await execFileAsync(process.execPath, [parentFile], { cwd: repoRoot, env })
+
+  return {
+    childCoverageLog,
+    lookupLog,
+    targetFile: await realpath(targetFile),
+  }
+}
+
+/**
+ * @param {string} coverageDir
+ * @param {string} targetFile
+ */
+async function assertTailCovered (coverageDir, targetFile) {
+  const targetUrl = pathToFileURL(targetFile).href
+  const profileFiles = []
+  for (const filename of await readdir(coverageDir)) {
+    if (filename.endsWith('.json')) profileFiles.push(readFile(path.join(coverageDir, filename), 'utf8'))
+  }
+
+  let targetCoverage
+  for (const profileFile of await Promise.all(profileFiles)) {
+    const profile = JSON.parse(profileFile)
+    for (const entry of profile.result) {
+      if (entry.url === targetUrl) {
+        targetCoverage = entry
+        break
+      }
+    }
+    if (targetCoverage) break
+  }
+
+  assert.ok(targetCoverage, `No coverage found for ${targetUrl}`)
+  let functionCoverage
+  for (const entry of targetCoverage.functions) {
+    if (entry.functionName === 'markCoverageTail') {
+      functionCoverage = entry
+      break
+    }
+  }
+  assert.ok(functionCoverage, 'No coverage found for markCoverageTail')
+  assert.strictEqual(functionCoverage.ranges[0].count, 1)
+}
+
+describe('c8 source map cache', () => {
+  let fixtureDir
+
+  beforeEach(async () => {
+    fixtureDir = await mkdtemp(path.join(os.tmpdir(), 'dd-c8-source-map-cache-'))
+  })
+
+  afterEach(async () => {
+    await rm(fixtureDir, { force: true, recursive: true })
+  })
+
+  it('warms source maps for c8-owned coverage through custom child environments', async () => {
+    const ownCoverageDir = path.join(fixtureDir, 'own-coverage')
+    markCoverageDirectory(ownCoverageDir)
+    const { childCoverageLog, lookupLog, targetFile } =
+      await runFixture(ownCoverageDir, fixtureDir, { moduleCount: 200 })
+
+    assert.strictEqual(await readFile(childCoverageLog, 'utf8'), ownCoverageDir)
+    const lookups = await readFile(lookupLog, 'utf8')
+    assert.ok(lookups.includes(pathToFileURL(targetFile).href), `No source map lookup found for ${targetFile}`)
+    let moduleLookups = 0
+    for (const lookup of lookups.split('\n')) {
+      if (lookup.includes('/modules/')) moduleLookups++
+    }
+    assert.strictEqual(moduleLookups, 200)
+    await assertTailCovered(ownCoverageDir, targetFile)
+  })
+
+  it('does not warm source maps for a foreign coverage directory', async () => {
+    const ownCoverageDir = path.join(fixtureDir, 'own-coverage')
+    const foreignCoverageDir = path.join(fixtureDir, 'foreign-coverage')
+    markCoverageDirectory(ownCoverageDir)
+    const { childCoverageLog, lookupLog, targetFile } = await runFixture(ownCoverageDir, fixtureDir, {
+      childCoverageDir: foreignCoverageDir,
+    })
+
+    assert.strictEqual(await readFile(childCoverageLog, 'utf8'), foreignCoverageDir)
+    await assert.rejects(readFile(lookupLog), { code: 'ENOENT' })
+    await assertTailCovered(foreignCoverageDir, targetFile)
+  })
+
+  it('does not warm source maps without coverage', async () => {
+    const { childCoverageLog, lookupLog } = await runFixture(undefined, fixtureDir)
+
+    assert.strictEqual(await readFile(childCoverageLog, 'utf8'), '')
+    await assert.rejects(readFile(lookupLog), { code: 'ENOENT' })
+  })
+
+  it('continues when a source map lookup fails', async () => {
+    const ownCoverageDir = path.join(fixtureDir, 'own-coverage')
+    markCoverageDirectory(ownCoverageDir)
+    const { lookupLog, targetFile } = await runFixture(ownCoverageDir, fixtureDir, { failLookup: true })
+
+    const lookups = await readFile(lookupLog, 'utf8')
+    assert.ok(lookups.includes(pathToFileURL(targetFile).href), `No source map lookup found for ${targetFile}`)
+    await assertTailCovered(ownCoverageDir, targetFile)
+  })
+
+  it('warms pending source maps before explicit exit', async () => {
+    const ownCoverageDir = path.join(fixtureDir, 'own-coverage')
+    markCoverageDirectory(ownCoverageDir)
+    const { lookupLog, targetFile } =
+      await runFixture(ownCoverageDir, fixtureDir, { exitImmediately: true, moduleCount: 200 })
+
+    const lookupLogContent = await readFile(lookupLog, 'utf8')
+    const entries = lookupLogContent.trimEnd().split('\n')
+    const disconnectIndex = entries.indexOf('disconnect')
+    let moduleLookups = 0
+    for (const entry of entries) {
+      assert.strictEqual(entry.startsWith('exit:'), false, `Source map lookup ran during exit: ${entry}`)
+      if (entry.includes('/modules/')) moduleLookups++
+    }
+    assert.strictEqual(moduleLookups, 200)
+    assert.strictEqual(disconnectIndex, entries.length - 1)
+    assert.strictEqual(entries.lastIndexOf('disconnect'), disconnectIndex)
+    await assertTailCovered(ownCoverageDir, targetFile)
+  })
+})