@jsenv/test 1.0.0

package/src/runtime_node/child_exec_options.js

@@ -0,0 +1,166 @@
+import { findFreePort } from "@jsenv/server"
+
+import { createDetailedMessage } from "@jsenv/log"
+import { ExecOptions } from "./exec_options.js"
+
+export const createChildExecOptions = async ({
+  signal = new AbortController().signal,
+  // https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_automatically-attach-debugger-to-nodejs-subprocesses
+  processExecArgv = process.execArgv,
+  processDebugPort = process.debugPort,
+
+  debugPort = 0,
+  debugMode = "inherit",
+  debugModeInheritBreak = true,
+} = {}) => {
+  if (
+    typeof debugMode === "string" &&
+    AVAILABLE_DEBUG_MODE.indexOf(debugMode) === -1
+  ) {
+    throw new TypeError(
+      createDetailedMessage(`unexpected debug mode.`, {
+        ["debug mode"]: debugMode,
+        ["allowed debug mode"]: AVAILABLE_DEBUG_MODE,
+      }),
+    )
+  }
+  const childExecOptions = ExecOptions.fromExecArgv(processExecArgv)
+  await mutateDebuggingOptions(childExecOptions, {
+    signal,
+    processDebugPort,
+    debugMode,
+    debugPort,
+    debugModeInheritBreak,
+  })
+  return childExecOptions
+}
+
+const AVAILABLE_DEBUG_MODE = [
+  "none",
+  "inherit",
+  "inspect",
+  "inspect-brk",
+  "debug",
+  "debug-brk",
+]
+
+const mutateDebuggingOptions = async (
+  childExecOptions,
+  {
+    // ensure multiline
+    signal,
+    processDebugPort,
+    debugMode,
+    debugPort,
+    debugModeInheritBreak,
+  },
+) => {
+  const parentDebugInfo = getDebugInfo(childExecOptions)
+  const parentDebugModeOptionName = parentDebugInfo.debugModeOptionName
+  const parentDebugPortOptionName = parentDebugInfo.debugPortOptionName
+  const childDebugModeOptionName = getChildDebugModeOptionName({
+    parentDebugModeOptionName,
+    debugMode,
+    debugModeInheritBreak,
+  })
+
+  if (!childDebugModeOptionName) {
+    // remove debug mode and debug port fron child options
+    if (parentDebugModeOptionName) {
+      delete childExecOptions[parentDebugModeOptionName]
+    }
+    if (parentDebugPortOptionName) {
+      delete childExecOptions[parentDebugPortOptionName]
+    }
+    return
+  }
+
+  // replace child debug mode
+  if (
+    parentDebugModeOptionName &&
+    parentDebugModeOptionName !== childDebugModeOptionName
+  ) {
+    delete childExecOptions[parentDebugModeOptionName]
+  }
+  childExecOptions[childDebugModeOptionName] = ""
+
+  // this is required because vscode does not
+  // support assigning a child spawned without a specific port
+  const childDebugPortOptionValue =
+    debugPort === 0
+      ? await findFreePort(processDebugPort + 37, { signal })
+      : debugPort
+  // replace child debug port
+  if (parentDebugPortOptionName) {
+    delete childExecOptions[parentDebugPortOptionName]
+  }
+  childExecOptions[childDebugModeOptionName] = portToArgValue(
+    childDebugPortOptionValue,
+  )
+}
+
+const getChildDebugModeOptionName = ({
+  parentDebugModeOptionName,
+  debugMode,
+  debugModeInheritBreak,
+}) => {
+  if (debugMode === "none") {
+    return undefined
+  }
+  if (debugMode !== "inherit") {
+    return `--${debugMode}`
+  }
+  if (!parentDebugModeOptionName) {
+    return undefined
+  }
+  if (!debugModeInheritBreak && parentDebugModeOptionName === "--inspect-brk") {
+    return "--inspect"
+  }
+  if (!debugModeInheritBreak && parentDebugModeOptionName === "--debug-brk") {
+    return "--debug"
+  }
+  return parentDebugModeOptionName
+}
+
+const portToArgValue = (port) => {
+  if (typeof port !== "number") return ""
+  if (port === 0) return ""
+  return port
+}
+
+// https://nodejs.org/en/docs/guides/debugging-getting-started/
+const getDebugInfo = (processOptions) => {
+  const inspectOption = processOptions["--inspect"]
+  if (inspectOption !== undefined) {
+    return {
+      debugModeOptionName: "--inspect",
+      debugPortOptionName: "--inspect-port",
+    }
+  }
+  const inspectBreakOption = processOptions["--inspect-brk"]
+  if (inspectBreakOption !== undefined) {
+    return {
+      debugModeOptionName: "--inspect-brk",
+      debugPortOptionName: "--inspect-port",
+    }
+  }
+  const debugOption = processOptions["--debug"]
+  if (debugOption !== undefined) {
+    return {
+      debugModeOptionName: "--debug",
+      debugPortOptionName: "--debug-port",
+    }
+  }
+  const debugBreakOption = processOptions["--debug-brk"]
+  if (debugBreakOption !== undefined) {
+    return {
+      debugModeOptionName: "--debug-brk",
+      debugPortOptionName: "--debug-port",
+    }
+  }
+  return {}
+}
+
+// export const processIsExecutedByVSCode = () => {
+//   return typeof process.env.VSCODE_PID === "string"
+// }

package/src/runtime_node/controllable_child_process.mjs

@@ -0,0 +1,135 @@
+import { uneval } from "@jsenv/uneval"
+
+import { executeUsingDynamicImport } from "./execute_using_dynamic_import.js"
+
+const ACTIONS_AVAILABLE = {
+  "execute-using-dynamic-import": executeUsingDynamicImport,
+  "execute-using-require": async ({ fileUrl }) => {
+    const { createRequire } = await import("node:module")
+    const { fileURLToPath } = await import("node:url")
+    const filePath = fileURLToPath(fileUrl)
+    const require = createRequire(fileUrl)
+    // eslint-disable-next-line import/no-dynamic-require
+    const namespace = require(filePath)
+    const namespaceResolved = {}
+    await Promise.all(
+      Object.keys(namespace).map(async (key) => {
+        const value = await namespace[key]
+        namespaceResolved[key] = value
+      }),
+    )
+    return namespaceResolved
+  },
+}
+const ACTION_REQUEST_EVENT_NAME = "action"
+const ACTION_RESPONSE_EVENT_NAME = "action-result"
+const ACTION_RESPONSE_STATUS_FAILED = "action-failed"
+const ACTION_RESPONSE_STATUS_COMPLETED = "action-completed"
+
+const sendActionFailed = (error) => {
+  if (error.hasOwnProperty("toString")) {
+    delete error.toString
+  }
+  sendToParent(
+    ACTION_RESPONSE_EVENT_NAME,
+    // process.send algorithm does not send non enumerable values
+    // so use @jsenv/uneval
+    uneval(
+      {
+        status: ACTION_RESPONSE_STATUS_FAILED,
+        value: error,
+      },
+      { ignoreSymbols: true },
+    ),
+  )
+}
+
+const sendActionCompleted = (value) => {
+  sendToParent(
+    ACTION_RESPONSE_EVENT_NAME,
+    // here we use JSON.stringify because we should not
+    // have non enumerable value (unlike there is on Error objects)
+    // otherwise uneval is quite slow to turn a giant object
+    // into a string (and value can be giant when using coverage)
+    JSON.stringify({
+      status: ACTION_RESPONSE_STATUS_COMPLETED,
+      value,
+    }),
+  )
+}
+
+const sendToParent = (type, data) => {
+  // https://nodejs.org/api/process.html#process_process_connected
+  // not connected anymore, cannot communicate with parent
+  if (!process.connected) {
+    return
+  }
+  // this can keep process alive longer than expected
+  // when source is a long string.
+  // It means node process may stay alive longer than expected
+  // the time to send the data to the parent.
+  process.send({
+    jsenv: true,
+    type,
+    data,
+  })
+}
+
+const onceParentMessage = (type, callback) => {
+  const listener = (message) => {
+    if (message && message.jsenv && message.type === type) {
+      removeListener() // commenting this line keep this process alive
+      callback(message.data)
+    }
+  }
+  const removeListener = () => {
+    process.removeListener("message", listener)
+  }
+  process.on("message", listener)
+  return removeListener
+}
+
+const removeActionRequestListener = onceParentMessage(
+  ACTION_REQUEST_EVENT_NAME,
+  async ({ actionType, actionParams }) => {
+    const action = ACTIONS_AVAILABLE[actionType]
+    if (!action) {
+      sendActionFailed(new Error(`unknown action ${actionType}`))
+      return
+    }
+
+    let value
+    let failed = false
+    try {
+      value = await action(actionParams)
+    } catch (e) {
+      failed = true
+      value = e
+    }
+
+    // setTimeout(() => {}, 100)
+
+    if (failed) {
+      sendActionFailed(value)
+    } else {
+      sendActionCompleted(value)
+    }
+
+    // removeActionRequestListener()
+    if (actionParams.exitAfterAction) {
+      removeActionRequestListener()
+      // for some reason this fixes v8 coverage directory sometimes empty on Ubuntu
+      // process.exit()
+    }
+  },
+)
+
+// remove listener to process.on('message')
+// which is sufficient to let child process die
+// assuming nothing else keeps it alive
+// process.once("SIGTERM", removeActionRequestListener)
+// process.once("SIGINT", removeActionRequestListener)
+
+setTimeout(() => {
+  sendToParent("ready")
+})

package/src/runtime_node/controllable_worker_thread.mjs

@@ -0,0 +1,103 @@
+import { parentPort } from "node:worker_threads"
+import { uneval } from "@jsenv/uneval"
+
+import { executeUsingDynamicImport } from "./execute_using_dynamic_import.js"
+
+const ACTIONS_AVAILABLE = {
+  "execute-using-dynamic-import": executeUsingDynamicImport,
+}
+const ACTION_REQUEST_EVENT_NAME = "action"
+const ACTION_RESPONSE_EVENT_NAME = "action-result"
+const ACTION_RESPONSE_STATUS_FAILED = "action-failed"
+const ACTION_RESPONSE_STATUS_COMPLETED = "action-completed"
+
+const sendActionFailed = (error) => {
+  if (error.hasOwnProperty("toString")) {
+    delete error.toString
+  }
+  sendToParent(
+    ACTION_RESPONSE_EVENT_NAME,
+    // process.send algorithm does not send non enumerable values
+    // so use @jsenv/uneval
+    uneval(
+      {
+        status: ACTION_RESPONSE_STATUS_FAILED,
+        value: error,
+      },
+      { ignoreSymbols: true },
+    ),
+  )
+}
+
+const sendActionCompleted = (value) => {
+  sendToParent(
+    ACTION_RESPONSE_EVENT_NAME,
+    // here we use JSON.stringify because we should not
+    // have non enumerable value (unlike there is on Error objects)
+    // otherwise uneval is quite slow to turn a giant object
+    // into a string (and value can be giant when using coverage)
+    JSON.stringify({
+      status: ACTION_RESPONSE_STATUS_COMPLETED,
+      value,
+    }),
+  )
+}
+
+const sendToParent = (type, data) => {
+  // this can keep process alive longer than expected
+  // when source is a long string.
+  // It means node process may stay alive longer than expected
+  // the time to send the data to the parent.
+  parentPort.postMessage({
+    jsenv: true,
+    type,
+    data,
+  })
+}
+
+const onceParentMessage = (type, callback) => {
+  const listener = (message) => {
+    if (message && message.jsenv && message.type === type) {
+      removeListener() // commenting this line keep this worker alive
+      callback(message.data)
+    }
+  }
+  const removeListener = () => {
+    parentPort.removeListener("message", listener)
+  }
+  parentPort.on("message", listener)
+  return removeListener
+}
+
+const removeActionRequestListener = onceParentMessage(
+  ACTION_REQUEST_EVENT_NAME,
+  async ({ actionType, actionParams }) => {
+    const action = ACTIONS_AVAILABLE[actionType]
+    if (!action) {
+      sendActionFailed(new Error(`unknown action ${actionType}`))
+      return
+    }
+
+    let value
+    let failed = false
+    try {
+      value = await action(actionParams)
+    } catch (e) {
+      failed = true
+      value = e
+    }
+
+    if (failed) {
+      sendActionFailed(value)
+    } else {
+      sendActionCompleted(value)
+    }
+    if (actionParams.exitAfterAction) {
+      removeActionRequestListener()
+    }
+  },
+)
+
+setTimeout(() => {
+  sendToParent("ready")
+})

package/src/runtime_node/exec_options.js

@@ -0,0 +1,57 @@
+export const ExecOptions = {
+  fromExecArgv: (execArgv) => {
+    const execOptions = {}
+    let i = 0
+    while (i < execArgv.length) {
+      const execArg = execArgv[i]
+      const option = execOptionFromExecArg(execArg)
+      const existing = execOptions[option.name]
+      if (existing) {
+        execOptions[option.name] = Array.isArray(existing)
+          ? [...existing, option.value]
+          : [existing, option.value]
+      } else {
+        execOptions[option.name] = option.value
+      }
+      i++
+    }
+    return execOptions
+  },
+  toExecArgv: (execOptions) => {
+    const execArgv = []
+    Object.keys(execOptions).forEach((optionName) => {
+      const optionValue = execOptions[optionName]
+      if (optionValue === "unset") {
+        return
+      }
+      if (optionValue === "") {
+        execArgv.push(optionName)
+        return
+      }
+      if (Array.isArray(optionValue)) {
+        optionValue.forEach((subValue) => {
+          execArgv.push(`${optionName}=${subValue}`)
+        })
+      } else {
+        execArgv.push(`${optionName}=${optionValue}`)
+      }
+    })
+    return execArgv
+  },
+}
+
+const execOptionFromExecArg = (execArg) => {
+  const equalCharIndex = execArg.indexOf("=")
+  if (equalCharIndex === -1) {
+    return {
+      name: execArg,
+      value: "",
+    }
+  }
+  const name = execArg.slice(0, equalCharIndex)
+  const value = execArg.slice(equalCharIndex + 1)
+  return {
+    name,
+    value,
+  }
+}

package/src/runtime_node/execute_using_dynamic_import.js

@@ -0,0 +1,53 @@
+import { writeFileSync } from "node:fs"
+
+import { startJsCoverage } from "./profiler_v8_coverage.js"
+import { startObservingPerformances } from "./node_execution_performance.js"
+
+export const executeUsingDynamicImport = async ({
+  rootDirectoryUrl,
+  fileUrl,
+  collectPerformance,
+  coverageEnabled,
+  coverageConfig,
+  coverageMethodForNodeJs,
+  coverageFileUrl,
+}) => {
+  const result = {}
+  const afterImportCallbacks = []
+  if (coverageEnabled && coverageMethodForNodeJs === "Profiler") {
+    const { filterV8Coverage } = await import("../coverage/v8_coverage.js")
+    const { stopJsCoverage } = await startJsCoverage()
+    afterImportCallbacks.push(async () => {
+      const coverage = await stopJsCoverage()
+      const coverageLight = await filterV8Coverage(coverage, {
+        rootDirectoryUrl,
+        coverageConfig,
+      })
+      writeFileSync(
+        new URL(coverageFileUrl),
+        JSON.stringify(coverageLight, null, "  "),
+      )
+    })
+  }
+  if (collectPerformance) {
+    const getPerformance = startObservingPerformances()
+    afterImportCallbacks.push(async () => {
+      const performance = await getPerformance()
+      result.performance = performance
+    })
+  }
+  const namespace = await import(fileUrl)
+  const namespaceResolved = {}
+  await Promise.all(
+    Object.keys(namespace).map(async (key) => {
+      const value = await namespace[key]
+      namespaceResolved[key] = value
+    }),
+  )
+  result.namespace = namespaceResolved
+  await afterImportCallbacks.reduce(async (previous, afterImportCallback) => {
+    await previous
+    await afterImportCallback()
+  }, Promise.resolve())
+  return result
+}

package/src/runtime_node/exit_codes.js

@@ -0,0 +1,9 @@
+// https://nodejs.org/api/process.html#process_signal_events
+const SIGINT_SIGNAL_NUMBER = 2
+const SIGABORT_SIGNAL_NUMBER = 6
+const SIGTERM_SIGNAL_NUMBER = 15
+export const EXIT_CODES = {
+  SIGINT: 128 + SIGINT_SIGNAL_NUMBER,
+  SIGABORT: 128 + SIGABORT_SIGNAL_NUMBER,
+  SIGTERM: 128 + SIGTERM_SIGNAL_NUMBER,
+}

package/src/runtime_node/importmap_node_loader.mjs

@@ -0,0 +1,51 @@
+import { readFileSync } from "node:fs"
+import { pathToFileURL } from "node:url"
+import { normalizeImportMap, resolveImport } from "@jsenv/importmap"
+
+let importMap
+
+const cwdUrl = `${String(pathToFileURL(process.cwd()))}/`
+
+if (process.env.IMPORT_MAP) {
+  importMap = JSON.parse(process.env.IMPORT_MAP)
+} else if (process.env.IMPORT_MAP_PATH) {
+  const importmapFileUrl = pathToFileURL(process.env.IMPORT_MAP_PATH)
+  const importmapFileContentAsString = readFileSync(importmapFileUrl, "utf8")
+  importMap = JSON.parse(importmapFileContentAsString)
+} else {
+  const importmapFileUrl = new URL("./import_map.json", cwdUrl)
+  const importmapFileContentAsString = readFileSync(importmapFileUrl, "utf8")
+  importMap = JSON.parse(importmapFileContentAsString)
+}
+
+const importMapBaseUrl = process.env.IMPORT_MAP_BASE_URL || cwdUrl
+importMap = normalizeImportMap(importMap, importMapBaseUrl)
+
+export const resolve = (specifier, context, nextResolve) => {
+  try {
+    let mapped
+    const importer = context.parentURL ? String(context.parentURL) : undefined
+    const resolved = resolveImport({
+      specifier,
+      importer,
+      importMap,
+      defaultExtension: ".js",
+      onImportMapping: () => {
+        mapped = true
+      },
+    })
+    if (mapped) {
+      return {
+        shortCircuit: true,
+        url: resolved,
+      }
+    }
+  } catch (e) {
+    if (e.message.includes("bare specifier")) {
+      return nextResolve(specifier, context)
+    }
+    console.error(e)
+    return nextResolve(specifier, context)
+  }
+  return nextResolve(specifier, context)
+}

package/src/runtime_node/importmap_node_loader_file_url.js

@@ -0,0 +1,4 @@
+export const IMPORTMAP_NODE_LOADER_FILE_URL = new URL(
+  "./importmap_node_loader.mjs?entry_point",
+  import.meta.url,
+).href

package/src/runtime_node/kill_process_tree.js

@@ -0,0 +1,76 @@
+import { requireFromJsenv } from "@jsenv/core/src/helpers/require_from_jsenv.js"
+
+// see also https://github.com/sindresorhus/execa/issues/96
+export const killProcessTree = async (
+  processId,
+  { signal, timeout = 2000 },
+) => {
+  const pidtree = requireFromJsenv("pidtree")
+
+  let descendantProcessIds
+  try {
+    descendantProcessIds = await pidtree(processId)
+  } catch (e) {
+    if (e.message === "No matching pid found") {
+      descendantProcessIds = []
+    } else {
+      throw e
+    }
+  }
+  descendantProcessIds.forEach((descendantProcessId) => {
+    try {
+      process.kill(descendantProcessId, signal)
+    } catch (error) {
+      // ignore
+    }
+  })
+
+  try {
+    process.kill(processId, signal)
+  } catch (e) {
+    if (e.code !== "ESRCH") {
+      throw e
+    }
+  }
+
+  let remainingIds = [...descendantProcessIds, processId]
+
+  const updateRemainingIds = () => {
+    remainingIds = remainingIds.filter((remainingId) => {
+      try {
+        process.kill(remainingId, 0)
+        return true
+      } catch (e) {
+        return false
+      }
+    })
+  }
+
+  let timeSpentWaiting = 0
+
+  const check = async () => {
+    updateRemainingIds()
+    if (remainingIds.length === 0) {
+      return
+    }
+
+    if (timeSpentWaiting > timeout) {
+      const timeoutError = new Error(
+        `timed out waiting for ${
+          remainingIds.length
+        } process to exit (${remainingIds.join(" ")})`,
+      )
+      timeoutError.code = "TIMEOUT"
+      throw timeoutError
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 400))
+    timeSpentWaiting += 400
+    await check()
+  }
+
+  await new Promise((resolve) => {
+    setTimeout(resolve, 0)
+  })
+  await check()
+}

package/src/runtime_node/no_experimental_warnings.cjs

@@ -0,0 +1,13 @@
+// see https://github.com/nodejs/node/issues/47478
+const originalEmit = process.emit
+process.emit = (event, error) => {
+  if (event === "warning" && error.name === "ExperimentalWarning") {
+    if (
+      error.message.includes("--experimental-loader") ||
+      error.message.includes("Custom ESM Loaders is an experimental")
+    ) {
+      return false
+    }
+  }
+  return originalEmit.call(process, event, error)
+}

package/src/runtime_node/no_experimental_warnings_file_url.js

@@ -0,0 +1,4 @@
+export const NO_EXPERIMENTAL_WARNING_FILE_URL = new URL(
+  "./no_experimental_warnings.cjs?entry_point",
+  import.meta.url,
+).href