@jsenv/plugin-commonjs 0.0.5

package/main.js

@@ -0,0 +1,2 @@
+export { jsenvPluginCommonJs } from "./src/jsenv_plugin_commonjs.js"
+export { commonJsToJsModule } from "./src/cjs_to_esm.js"

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@jsenv/plugin-commonjs",
+  "version": "0.0.5",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jsenv/jsenv-core",
+    "directory": "packages/jsenv-plugin-commonjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "main": "./main.js",
+  "dependencies": {
+    "@jsenv/filesystem": "3.1.0",
+    "@jsenv/logger": "4.0.1",
+    "@rollup/plugin-commonjs": "22.0.0",
+    "@rollup/plugin-json": "4.1.0",
+    "@rollup/plugin-node-resolve": "13.3.0",
+    "@rollup/plugin-replace": "4.0.0",
+    "cjs-module-lexer": "1.2.2",
+    "is-valid-identifier": "2.0.2",
+    "resolve": "1.22.0",
+    "rollup": "2.73.0",
+    "rollup-plugin-node-globals": "1.4.0",
+    "rollup-plugin-polyfill-node": "0.9.0",
+    "vm2": "3.9.9"
+  }
+}

package/src/cjs_to_esm.js

@@ -0,0 +1,129 @@
+import { readFileSync } from "node:fs"
+import {
+  assertAndNormalizeDirectoryUrl,
+  urlIsInsideOf,
+  moveUrl,
+  ensureWindowsDriveLetter,
+  urlToExtension,
+  urlToBasename,
+} from "@jsenv/filesystem"
+
+import { setUrlExtension, setUrlFilename } from "@jsenv/utils/urls/url_utils.js"
+import { commonJsToJsModuleRaw } from "./cjs_to_esm_raw.js"
+import { reuseOrCreateCompiledFile } from "./compile_cache/compiled_file_cache.js"
+
+export const commonJsToJsModule = ({
+  logLevel,
+  filesystemCache = true,
+  rootDirectoryUrl,
+  sourceFileUrl,
+  processEnvNodeEnv,
+  ...rest
+}) => {
+  if (filesystemCache) {
+    rootDirectoryUrl = assertAndNormalizeDirectoryUrl(rootDirectoryUrl)
+    const compileDirectoryUrl = new URL(
+      "./.jsenv/cjs_to_esm/",
+      rootDirectoryUrl,
+    )
+    const compiledFileUrl = determineCompiledFileUrl({
+      url: sourceFileUrl,
+      rootDirectoryUrl,
+      compileDirectoryUrl,
+      processEnvNodeEnv,
+    })
+
+    return reuseOrCreateCompiledFile({
+      logLevel,
+      compileDirectoryUrl,
+      sourceFileUrl,
+      compiledFileUrl,
+      compile: async () => {
+        const { content, sourcemap } = await commonJsToJsModuleRaw({
+          logLevel,
+          rootDirectoryUrl,
+          sourceFileUrl,
+          processEnvNodeEnv,
+          ...rest,
+        })
+        const assets = extractCompileAssets({
+          sourceUrl: sourceFileUrl,
+          sourceContent: String(readFileSync(new URL(sourceFileUrl))),
+          compiledUrl: compiledFileUrl,
+          compiledContent: content,
+          sourcemap,
+        })
+        return {
+          content,
+          sourcemap,
+          assets,
+        }
+      },
+    })
+  }
+  return commonJsToJsModuleRaw({
+    logLevel,
+    rootDirectoryUrl,
+    sourceFileUrl,
+    ...rest,
+  })
+}
+
+const extractCompileAssets = ({
+  sourceUrl,
+  sourceContent,
+  compiledUrl,
+  sourcemap,
+}) => {
+  const compileAssets = {}
+
+  // ensure the source file is part of sources no matter what
+  // it covers cases where sourcemap.sources is empty
+  // or do not contain the real source file
+  // there is a check to prevent duplicate sources in case the sourcemap is correct and contains
+  // the source file in sourcemap.sources
+  compileAssets[sourceUrl] = { type: "source", content: sourceContent }
+  if (sourcemap) {
+    sourcemap.sources.forEach((source, index) => {
+      if (source.startsWith("file://")) {
+        const contentFromSourcemap = sourcemap.sourcesContent
+          ? sourcemap.sourcesContent[index]
+          : null
+        const content =
+          contentFromSourcemap || String(readFileSync(new URL(source)))
+        compileAssets[source] = { type: "source", content }
+      }
+    })
+    const sourcemapUrl = setUrlExtension(compiledUrl, ".map")
+    const sourcemapContent = JSON.stringify(sourcemap)
+    compileAssets[sourcemapUrl] = {
+      type: "sourcemap",
+      content: sourcemapContent,
+    }
+  }
+
+  return compileAssets
+}
+
+const determineCompiledFileUrl = ({
+  url,
+  rootDirectoryUrl,
+  compileDirectoryUrl,
+  processEnvNodeEnv,
+}) => {
+  if (!urlIsInsideOf(url, rootDirectoryUrl)) {
+    const fsRootUrl = ensureWindowsDriveLetter("file:///", url)
+    url = `${rootDirectoryUrl}@fs/${url.slice(fsRootUrl.length)}`
+  }
+  if (processEnvNodeEnv) {
+    const basename = urlToBasename(url)
+    const extension = urlToExtension(url)
+    url = setUrlFilename(url, `${basename}.${processEnvNodeEnv}${extension}`)
+  }
+  return moveUrl({
+    url,
+    from: rootDirectoryUrl,
+    to: compileDirectoryUrl,
+    preferAbsolute: true,
+  })
+}

package/src/cjs_to_esm_raw.js

@@ -0,0 +1,167 @@
+import { fileURLToPath } from "node:url"
+import { createLogger } from "@jsenv/logger"
+
+import { rollupPluginCommonJsNamedExports } from "./rollup_plugin_commonjs_named_exports.js"
+
+export const commonJsToJsModuleRaw = async ({
+  logLevel,
+  sourceFileUrl,
+
+  replaceGlobalObject = true,
+  replaceGlobalFilename = true,
+  replaceGlobalDirname = true,
+  replaceProcessEnvNodeEnv = true,
+  replaceProcess = true,
+  replaceBuffer = true,
+  processEnvNodeEnv = process.env.NODE_ENV,
+  replaceMap = {},
+  convertBuiltinsToBrowser = true,
+  external = [],
+  sourcemapExcludeSources,
+} = {}) => {
+  const logger = createLogger({ logLevel })
+  if (!sourceFileUrl.startsWith("file:///")) {
+    // it's possible to make rollup compatible with http:// for instance
+    // however it's an exotic use case for now
+    throw new Error(
+      `compatible only with file:// protocol, got ${sourceFileUrl}`,
+    )
+  }
+  const sourceFilePath = fileURLToPath(sourceFileUrl)
+
+  const { nodeResolve } = await import("@rollup/plugin-node-resolve")
+  const nodeResolveRollupPlugin = nodeResolve({
+    mainFields: [
+      "browser:module",
+      "module",
+      "browser",
+      "main:esnext",
+      "jsnext:main",
+      "main",
+    ],
+    extensions: [".mjs", ".cjs", ".js", ".json"],
+    preferBuiltins: false,
+    exportConditions: [],
+  })
+
+  const { default: createJSONRollupPlugin } = await import(
+    "@rollup/plugin-json"
+  )
+  const jsonRollupPlugin = createJSONRollupPlugin({
+    preferConst: true,
+    indent: "  ",
+    compact: false,
+    namedExports: true,
+  })
+
+  const { default: createReplaceRollupPlugin } = await import(
+    "@rollup/plugin-replace"
+  )
+  const replaceRollupPlugin = createReplaceRollupPlugin({
+    preventAssignment: true,
+    values: {
+      ...(replaceProcessEnvNodeEnv
+        ? { "process.env.NODE_ENV": JSON.stringify(processEnvNodeEnv) }
+        : {}),
+      ...(replaceGlobalObject ? { global: "globalThis" } : {}),
+      ...(replaceGlobalFilename ? { __filename: __filenameReplacement } : {}),
+      ...(replaceGlobalDirname ? { __dirname: __dirnameReplacement } : {}),
+      ...replaceMap,
+    },
+  })
+
+  const { default: commonjs } = await import("@rollup/plugin-commonjs")
+  const commonJsRollupPlugin = commonjs({
+    extensions: [".js", ".cjs"],
+    // esmExternals: true,
+    // defaultIsModuleExports: true,
+    // requireReturnsDefault: "namespace",
+    requireReturnsDefault: "auto",
+  })
+
+  const { default: createNodeGlobalRollupPlugin } = await import(
+    "rollup-plugin-node-globals"
+  )
+  const nodeGlobalRollupPlugin = createNodeGlobalRollupPlugin({
+    global: false, // handled by replaceMap
+    dirname: false, // handled by replaceMap
+    filename: false, // handled by replaceMap
+    process: replaceProcess,
+    buffer: replaceBuffer,
+  })
+
+  const commonJsNamedExportsRollupPlugin = rollupPluginCommonJsNamedExports({
+    logger,
+  })
+
+  const { default: rollupPluginNodePolyfills } = await import(
+    "rollup-plugin-polyfill-node"
+  )
+
+  const { rollup } = await import("rollup")
+  const rollupBuild = await rollup({
+    input: sourceFilePath,
+    inlineDynamicImports: true,
+    external,
+    plugins: [
+      nodeResolveRollupPlugin,
+      jsonRollupPlugin,
+      replaceRollupPlugin,
+      commonJsRollupPlugin,
+      commonJsNamedExportsRollupPlugin,
+      nodeGlobalRollupPlugin,
+      ...(convertBuiltinsToBrowser
+        ? [
+            rollupPluginNodePolyfills({
+              include: null,
+            }),
+          ]
+        : []),
+    ],
+    onwarn: (warning) => {
+      const { loc, message } = warning
+      const logMessage = loc
+        ? `${loc.file}:${loc.line}:${loc.column} ${message}`
+        : message
+
+      // These warnings are usually harmless in packages, so don't show them by default
+      if (
+        warning.code === "CIRCULAR_DEPENDENCY" ||
+        warning.code === "NAMESPACE_CONFLICT" ||
+        warning.code === "THIS_IS_UNDEFINED" ||
+        warning.code === "EMPTY_BUNDLE" ||
+        warning.code === "UNUSED_EXTERNAL_IMPORT"
+      ) {
+        logger.debug(logMessage)
+      } else {
+        logger.warn(logMessage)
+      }
+    },
+  })
+  const abstractDirUrl = new URL("./dist/", sourceFileUrl) // to help rollup generate property sourcemap paths
+  const generateOptions = {
+    // https://rollupjs.org/guide/en#output-format
+    format: "esm",
+    // entryFileNames: `./[name].js`,
+    // https://rollupjs.org/guide/en#output-sourcemap
+    sourcemap: true,
+    sourcemapExcludeSources,
+    exports: "named",
+    dir: fileURLToPath(abstractDirUrl),
+    sourcemapPathTransform: (relativePath) => {
+      const sourceUrl = new URL(relativePath, abstractDirUrl).href
+      return sourceUrl
+    },
+  }
+
+  const { output } = await rollupBuild.generate(generateOptions)
+  const { code, map } = output[0]
+  return {
+    content: code,
+    sourcemap: map,
+  }
+}
+
+const __filenameReplacement = `import.meta.url.slice('file:///'.length)`
+
+const __dirnameReplacement = `import.meta.url.slice('file:///'.length).replace(/[\\\/\\\\][^\\\/\\\\]*$/, '')`

package/src/compile_cache/compiled_file_cache.js

@@ -0,0 +1,176 @@
+import { readFileSync, writeFileSync } from "node:fs"
+import { createLogger } from "@jsenv/logger"
+import { UNICODE } from "@jsenv/log"
+import {
+  assertAndNormalizeFileUrl,
+  ensureEmptyDirectory,
+} from "@jsenv/filesystem"
+
+import { validateCompileCache } from "./validate_compile_cache.js"
+import { createLockRegistry } from "./file_lock_registry.js"
+import { updateCompileCache } from "./update_compile_cache.js"
+
+const { lockForRessource } = createLockRegistry()
+
+export const reuseOrCreateCompiledFile = async ({
+  logLevel,
+  compileDirectoryUrl,
+  sourceFileUrl,
+  compiledFileUrl,
+  compileCacheStrategy,
+  compileCacheAssetsValidation,
+  compile,
+}) => {
+  const logger = createLogger({ logLevel })
+  await initCompileDirectory({ logger, compileDirectoryUrl })
+  sourceFileUrl = assertAndNormalizeFileUrl(sourceFileUrl)
+  if (typeof compile !== "function") {
+    throw new TypeError(`compile must be a function, got ${compile}`)
+  }
+
+  return startAsap(
+    async () => {
+      logger.debug(`check cache for ${compiledFileUrl}`)
+      const cacheValidity = validateCompileCache({
+        logger,
+        compiledFileUrl,
+        compileCacheStrategy,
+        compileCacheAssetsValidation,
+      })
+      if (cacheValidity.isValid) {
+        logger.debug(`${UNICODE.OK} found a valid cache`)
+        const compileInfo = cacheValidity.compileInfo.data
+        const content = String(cacheValidity.compiledFile.data.buffer)
+        const assets = {}
+        let sourcemap = null
+        Object.keys(compileInfo.assetInfos).forEach((assetRelativeUrl) => {
+          const assetUrl = new URL(assetRelativeUrl, compiledFileUrl).href
+          const assetValidity = cacheValidity.assets.data[assetUrl]
+          const asset = {
+            type: compileInfo.assetInfos[assetRelativeUrl].type,
+            etag: compileInfo.assetInfos[assetRelativeUrl].etag,
+            content: assetValidity.data.content,
+          }
+          assets[assetUrl] = asset
+          if (asset.type === "sourcemap") {
+            sourcemap = assetValidity.data.sourcemap
+          }
+        })
+        updateCompileCache({
+          logger,
+          compiledFileUrl,
+          content,
+          assets,
+          compileResultStatus: "cached",
+        })
+        return {
+          content,
+          sourcemap,
+        }
+      }
+      if (cacheValidity.code === "SOURCES_EMPTY") {
+        logger.warn(
+          `${UNICODE.WARN} meta.sources is empty for ${compiledFileUrl}`,
+        )
+      }
+      logger.debug(`${UNICODE.INFO} cache not found or invalid`)
+      const compileInfoIsValid = cacheValidity.compileInfo
+        ? cacheValidity.compileInfo.isValid
+        : false
+      const fileContentAsBuffer = readFileSync(new URL(sourceFileUrl))
+      const fileContentAsString = String(fileContentAsBuffer)
+
+      const compileResult = await compile({
+        content: fileContentAsString,
+      })
+      if (typeof compileResult !== "object" || compileResult === null) {
+        throw new TypeError(
+          `compile must return an object, got ${compileResult}`,
+        )
+      }
+      const { content, sourcemap, assets } = compileResult
+      updateCompileCache({
+        logger,
+        compiledFileUrl,
+        content,
+        assets,
+        compileResultStatus: compileInfoIsValid ? "updated" : "created",
+      })
+      return {
+        content,
+        sourcemap,
+      }
+    },
+    {
+      compiledFileUrl,
+    },
+  )
+}
+
+const initalized = {}
+const initCompileDirectory = async ({ logger, compileDirectoryUrl }) => {
+  if (initalized[compileDirectoryUrl]) {
+    return
+  }
+  initalized[compileDirectoryUrl] = true
+  logger.debug(`check compile directory at ${compileDirectoryUrl}`)
+  const compileContextJsonFileUrl = new URL(
+    "./__compile_context__.json",
+    compileDirectoryUrl,
+  )
+  const version = JSON.parse(
+    readFileSync(new URL("../../package.json", import.meta.url)),
+  ).version
+  const compileContext = readCompileContextFile({
+    logger,
+    compileContextJsonFileUrl,
+  })
+  if (compileContext && compileContext.version === version) {
+    logger.debug(`${UNICODE.OK} reuse compile directory`)
+  } else {
+    if (compileContext) {
+      logger.debug(`${UNICODE.WARN} clean existing directory`)
+    } else {
+      logger.debug(`${UNICODE.INFO} create an empty directory`)
+    }
+    await ensureEmptyDirectory(compileDirectoryUrl)
+    writeFileSync(
+      compileContextJsonFileUrl,
+      JSON.stringify({ version }, null, "  "),
+    )
+  }
+}
+
+const readCompileContextFile = ({ logger, compileContextJsonFileUrl }) => {
+  let compileContextFileContent
+  try {
+    compileContextFileContent = readFileSync(compileContextJsonFileUrl)
+  } catch (e) {
+    logger.debug(
+      `${UNICODE.INFO} cannot read compile context at ${compileContextJsonFileUrl}`,
+    )
+    return null
+  }
+  try {
+    const compileContext = JSON.parse(compileContextFileContent)
+    return compileContext
+  } catch (e) {
+    if (e.name === "SyntaxError") {
+      logger.warn(
+        `${UNICODE.WARN} syntax error in ${compileContextJsonFileUrl}`,
+      )
+      return null
+    }
+    throw e
+  }
+}
+
+const startAsap = async (fn, { compiledFileUrl }) => {
+  const unlockLocal = await lockForRessource(compiledFileUrl)
+  try {
+    return await fn()
+  } finally {
+    // "finally" we want to unlock in case of error too
+    unlockLocal()
+  }
+}

package/src/compile_cache/file_lock_registry.js

@@ -0,0 +1,24 @@
+export const createLockRegistry = () => {
+  let lockArray = []
+  const lockForRessource = async (ressource) => {
+    const currentLock = lockArray.find((lock) => lock.ressource === ressource)
+    let unlockResolve
+    const unlocked = new Promise((resolve) => {
+      unlockResolve = resolve
+    })
+    const lock = {
+      ressource,
+      unlocked,
+    }
+    lockArray = [...lockArray, lock]
+
+    if (currentLock) await currentLock.unlocked
+
+    const unlock = () => {
+      lockArray = lockArray.filter((lockCandidate) => lockCandidate !== lock)
+      unlockResolve()
+    }
+    return unlock
+  }
+  return { lockForRessource }
+}

package/src/compile_cache/update_compile_cache.js

@@ -0,0 +1,97 @@
+import { existsSync, utimesSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import {
+  urlToRelativeUrl,
+  writeFileSync,
+  bufferToEtag,
+} from "@jsenv/filesystem"
+
+export const updateCompileCache = ({
+  logger,
+  compiledFileUrl,
+  content,
+  assets,
+  mtime,
+  compileResultStatus,
+}) => {
+  const isNew = compileResultStatus === "created"
+  const isUpdated = compileResultStatus === "updated"
+  if (!isNew && !isUpdated) {
+    return
+  }
+
+  // ensure source that does not leads to files are not capable to invalidate the cache
+  const filesRemoved = []
+  Object.keys(assets).forEach((assetUrl) => {
+    if (
+      assetUrl.startsWith("file://") &&
+      assets[assetUrl].type === "source" &&
+      !existsSync(new URL(assetUrl))
+    ) {
+      delete assets[assetUrl]
+      filesRemoved.push(assetUrl)
+    }
+  })
+  const notFoundCount = filesRemoved.length
+  if (notFoundCount > 0) {
+    logger.warn(`COMPILE_ASSET_FILE_NOT_FOUND: ${notFoundCount} file(s) not found.
+--- consequence ---
+cache will be reused even if one of the source file is modified
+--- files not found ---
+${filesRemoved.join(`\n`)}`)
+  }
+
+  logger.debug(`write compiled file at ${fileURLToPath(compiledFileUrl)}`)
+  writeFileSync(compiledFileUrl, content, {
+    fileLikelyNotFound: isNew,
+  })
+  // mtime is passed, it meant the file mtime is important
+  // -> we update file mtime
+  if (mtime) {
+    utimesSync(new URL(compiledFileUrl), new Date(mtime), new Date(mtime))
+  }
+
+  const assetInfos = {}
+  Object.keys(assets).forEach((assetUrl) => {
+    logger.debug(`write compiled file asset at ${fileURLToPath(assetUrl)}`)
+    const asset = assets[assetUrl]
+    writeFileSync(assetUrl, asset.content, {
+      fileLikelyNotFound: isNew,
+    })
+    const assetRelativeUrl = urlToRelativeUrl(assetUrl, compiledFileUrl)
+    const assetEtag = asset.etag || bufferToEtag(Buffer.from(asset.content))
+    assetInfos[assetRelativeUrl] = {
+      type: asset.type,
+      etag: assetEtag,
+    }
+  })
+
+  const compileInfoFileUrl = `${compiledFileUrl}__compile_info__.json`
+  let latestCompileInfo
+  if (isNew) {
+    latestCompileInfo = {
+      // was used at some point to ensure the compiled file matches browser etag
+      // etag: bufferToEtag(Buffer.from(content)),
+      assetInfos,
+      createdMs: Number(Date.now()),
+      lastModifiedMs: Number(Date.now()),
+    }
+  } else if (isUpdated) {
+    latestCompileInfo = {
+      // was used at some point to ensure the compiled file matches browser etag
+      // etag: bufferToEtag(Buffer.from(content)),
+      assetInfos,
+      lastModifiedMs: Number(Date.now()),
+    }
+  }
+  logger.debug(
+    `write compiled file info at ${fileURLToPath(compileInfoFileUrl)}`,
+  )
+  writeFileSync(
+    compileInfoFileUrl,
+    JSON.stringify(latestCompileInfo, null, "  "),
+    {
+      fileLikelyNotFound: isNew,
+    },
+  )
+}

package/src/compile_cache/validate_compile_cache.js

@@ -0,0 +1,226 @@
+import { readFileSync, statSync } from "node:fs"
+import { bufferToEtag } from "@jsenv/filesystem"
+
+export const validateCompileCache = ({
+  compiledFileUrl,
+  compileCacheStrategy,
+  compileCacheAssetsValidation = true,
+}) => {
+  const validity = { isValid: true }
+  const compileInfoValidity = validateCompileInfoFile({
+    compiledFileUrl,
+  })
+  validity.compileInfo = compileInfoValidity
+  mergeValidity(validity, compileInfoValidity)
+  if (!validity.isValid) {
+    return validity
+  }
+  const compiledFileValidity = validateCompiledFile({
+    compiledFileUrl,
+    compileCacheStrategy,
+  })
+  validity.compiledFile = compiledFileValidity
+  mergeValidity(validity, compiledFileValidity)
+  if (!validity.isValid) {
+    return validity
+  }
+  const compileInfo = compileInfoValidity.data
+  const assetsValidity = compileCacheAssetsValidation
+    ? validateAssets({
+        compiledFileUrl,
+        compileInfo,
+      })
+    : { isValid: true, code: "ASSETS_VALIDATION_DISABLED" }
+  validity.assets = assetsValidity
+  mergeValidity(validity, assetsValidity)
+  if (!validity.isValid) {
+    return validity
+  }
+  return validity
+}
+
+const validateCompileInfoFile = ({ compiledFileUrl }) => {
+  const compileInfoFileUrl = `${compiledFileUrl}__compile_info__.json`
+  const validity = { isValid: true, data: {} }
+  let compileInfoFileContentAsBuffer
+  try {
+    compileInfoFileContentAsBuffer = readFileSync(new URL(compileInfoFileUrl))
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      validity.isValid = false
+      validity.code = "COMPILE_INFO_FILE_NOT_FOUND"
+      return validity
+    }
+    throw error
+  }
+  const compileInfoFileContentAsString = String(compileInfoFileContentAsBuffer)
+  let compileInfo
+  try {
+    compileInfo = JSON.parse(compileInfoFileContentAsString)
+  } catch (error) {
+    if (error && error.name === "SyntaxError") {
+      validity.isValid = false
+      validity.code = "COMPILE_INFO_FILE_SYNTAX_ERROR"
+      return validity
+    }
+    throw error
+  }
+  validity.data = compileInfo
+  if (Object.keys(compileInfo.assetInfos).length === 0) {
+    validity.isValid = false
+    validity.code = "ASSETS_EMPTY"
+    return validity
+  }
+  return validity
+}
+
+const validateCompiledFile = ({
+  compiledFileUrl,
+  compileCacheStrategy,
+  lastEtag,
+  lastModificationTime,
+}) => {
+  const validity = { isValid: true, data: {} }
+  try {
+    const buffer = readFileSync(new URL(compiledFileUrl))
+    validity.data.buffer = buffer
+    if (compileCacheStrategy === "etag" && lastEtag) {
+      const etag = bufferToEtag(buffer)
+      validity.data.etag = etag
+      if (lastEtag && lastEtag !== etag) {
+        validity.isValid = false
+        validity.code = "COMPILED_FILE_ETAG_MISMATCH"
+        return validity
+      }
+    }
+    if (compileCacheStrategy === "mtime" && lastModificationTime) {
+      const stats = statSync(new URL(compiledFileUrl))
+      const mtime = Math.floor(stats.mtimeMs)
+      validity.data.mtime = mtime
+      let ifModifiedSinceDate
+      try {
+        ifModifiedSinceDate = new Date(lastModificationTime)
+      } catch (e) {
+        ifModifiedSinceDate = null
+        // ideally we should rather respond with
+        // 400 "if-modified-since header is not a valid date"
+      }
+      if (
+        ifModifiedSinceDate &&
+        ifModifiedSinceDate < dateToSecondsPrecision(mtime)
+      ) {
+        validity.isValid = false
+        validity.code = "COMPILED_FILE_MTIME_OUTDATED"
+        return validity
+      }
+    }
+    return validity
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      validity.isValid = false
+      validity.code = "COMPILED_FILE_NOT_FOUND"
+      return validity
+    }
+    throw error
+  }
+}
+
+const validateAssets = ({ compiledFileUrl, compileInfo }) => {
+  const assetsValidity = { isValid: true, data: {} }
+
+  const assetRelativeUrls = Object.keys(compileInfo.assetInfos)
+  for (const assetRelativeUrl of assetRelativeUrls) {
+    const assetInfo = compileInfo.assetInfos[assetRelativeUrl]
+    const assetUrl = new URL(assetRelativeUrl, compiledFileUrl).href
+    const assetValidity = { isValid: true, data: {} }
+    if (assetInfo.type === "source") {
+      validateSource(assetValidity, {
+        sourceFileUrl: assetUrl,
+        eTag: assetInfo.etag,
+      })
+    }
+    if (assetInfo.type === "sourcemap") {
+      validateSourcemap(assetValidity, {
+        sourcemapFileUrl: assetUrl,
+      })
+    }
+    assetsValidity.data[assetUrl] = assetValidity
+    mergeValidity(assetsValidity, assetValidity)
+    if (!assetsValidity.isValid) {
+      break
+    }
+  }
+
+  return assetsValidity
+}
+
+const validateSource = (validity, { sourceFileUrl, eTag }) => {
+  try {
+    const sourceBuffer = readFileSync(new URL(sourceFileUrl))
+    const sourceETag = bufferToEtag(sourceBuffer)
+    validity.data.content = String(sourceBuffer)
+    validity.data.etag = sourceETag
+    if (sourceETag !== eTag) {
+      validity.isValid = false
+      validity.code = "SOURCE_ETAG_MISMATCH"
+      return validity
+    }
+    return validity
+  } catch (e) {
+    if (e && e.code === "ENOENT") {
+      // missing source invalidates the cache because
+      // we cannot check its validity
+      // HOWEVER inside writeMeta we will check if a source can be found
+      // when it cannot we will not put it as a dependency
+      // to invalidate the cache.
+      // It is important because some files are constructed on other files
+      // which are not truly on the filesystem
+      // (IN theory the above happens only for convertCommonJsWithRollup because jsenv
+      // always have a concrete file especially to avoid that kind of thing)
+      validity.isValid = false
+      validity.code = "SOURCE_NOT_FOUND"
+      return validity
+    }
+    throw e
+  }
+}
+
+const validateSourcemap = (validity, { sourcemapFileUrl }) => {
+  let sourcemapFileContentAsBuffer
+  try {
+    sourcemapFileContentAsBuffer = readFileSync(new URL(sourcemapFileUrl))
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      validity.isValid = false
+      validity.code = "SOURCEMAP_FILE_NOT_FOUND"
+      return validity
+    }
+    throw error
+  }
+  const sourcemapFileContentAsString = String(sourcemapFileContentAsBuffer)
+  validity.data.content = sourcemapFileContentAsString
+  let sourcemap
+  try {
+    sourcemap = JSON.parse(sourcemapFileContentAsString)
+  } catch (error) {
+    if (error && error.name === "SyntaxError") {
+      validity.isValid = false
+      validity.code = "SOURCEMAP_FILE_SYNTAX_ERROR"
+      return validity
+    }
+    throw error
+  }
+  validity.data.sourcemap = sourcemap
+  return validity
+}
+
+const mergeValidity = (parentValidity, childValidity) => {
+  parentValidity.isValid = childValidity.isValid
+  if (childValidity.code) parentValidity.code = childValidity.code
+}
+
+const dateToSecondsPrecision = (date) => {
+  const dateWithSecondsPrecision = new Date(date)
+  dateWithSecondsPrecision.setMilliseconds(0)
+  return dateWithSecondsPrecision
+}

package/src/jsenv_plugin_commonjs.js

@@ -0,0 +1,63 @@
+import { normalizeStructuredMetaMap, urlToMeta } from "@jsenv/url-meta"
+
+import { fetchOriginalUrlInfo } from "@jsenv/utils/graph/fetch_original_url_info.js"
+import { injectQueryParams } from "@jsenv/utils/urls/url_utils.js"
+import { commonJsToJsModule } from "./cjs_to_esm.js"
+
+export const jsenvPluginCommonJs = ({ logLevel, include }) => {
+  const structuredMetaMap = normalizeStructuredMetaMap(
+    {
+      commonjs: include,
+    },
+    "file://",
+  )
+
+  return {
+    name: "jsenv:commonjs",
+    appliesDuring: "*",
+    redirectUrl: {
+      js_import_export: (reference) => {
+        const { commonjs } = urlToMeta({
+          url: reference.url,
+          structuredMetaMap,
+        })
+        if (!commonjs) {
+          return null
+        }
+        reference.data.commonjs = commonjs
+        return injectQueryParams(reference.url, {
+          cjs_as_js_module: "",
+        })
+      },
+    },
+    fetchUrlContent: async (urlInfo, context) => {
+      const originalUrlInfo = await fetchOriginalUrlInfo({
+        urlInfo,
+        context,
+        searchParam: "cjs_as_js_module",
+        // during this fetch we don't want to alter the original file
+        // so we consider it as text
+        expectedType: "text",
+      })
+      if (!originalUrlInfo) {
+        return null
+      }
+      const { content, sourcemap } = await commonJsToJsModule({
+        logLevel,
+        rootDirectoryUrl: context.rootDirectoryUrl,
+        sourceFileUrl: originalUrlInfo.url,
+        processEnvNodeEnv:
+          context.scenario === "dev" || context.scenario === "test"
+            ? "development"
+            : "production",
+        ...urlInfo.data.commonjs,
+      })
+      return {
+        type: "js_module",
+        contentType: "text/javascript",
+        content,
+        sourcemap,
+      }
+    },
+  }
+}

package/src/rollup_plugin_commonjs_named_exports.js

@@ -0,0 +1,186 @@
+// https://github.com/snowpackjs/snowpack/blob/main/esinstall/src/rollup-plugins/rollup-plugin-wrap-install-targets.ts
+
+import { readFileSync } from "node:fs"
+import { fileURLToPath, pathToFileURL } from "node:url"
+import { VM as VM2 } from "vm2"
+import resolve from "resolve"
+import isValidIdentifier from "is-valid-identifier"
+import { init, parse } from "cjs-module-lexer"
+
+export const rollupPluginCommonJsNamedExports = ({ logger }) => {
+  const inputSummaries = {}
+  const cjsScannedNamedExports = {}
+
+  return {
+    async buildStart({ input }) {
+      await init()
+
+      Object.keys(input).forEach((key) => {
+        const inputFilePath = input[key]
+        const inputFileUrl = pathToFileURL(inputFilePath)
+        inputSummaries[inputFileUrl] = {
+          all: true,
+          default: true,
+          namespace: true,
+          named: [],
+        }
+
+        const cjsExports =
+          detectStaticExports({ logger, fileUrl: inputFileUrl }) ||
+          detectExportsUsingSandboxedRuntime({ logger, fileUrl: inputFileUrl })
+
+        if (cjsExports && cjsExports.length) {
+          cjsScannedNamedExports[inputFileUrl] = cjsExports
+        }
+        input[key] = `jsenv:${inputFileUrl}`
+      })
+    },
+    resolveId(source) {
+      if (source.startsWith("jsenv:")) {
+        return source
+      }
+
+      return null
+    },
+    load(id) {
+      if (!id.startsWith("jsenv:")) {
+        return null
+      }
+
+      const inputFileUrl = id.substring("jsenv:".length)
+      const inputSummary = inputSummaries[inputFileUrl]
+      let uniqueNamedExports = inputSummary.named
+      const scannedNamedExports = cjsScannedNamedExports[inputFileUrl]
+      if (scannedNamedExports) {
+        uniqueNamedExports = scannedNamedExports || []
+        inputSummary.default = true
+      }
+      const codeForExports = generateCodeForExports({
+        uniqueNamedExports,
+        inputSummary,
+        inputFileUrl,
+      })
+      return codeForExports
+    },
+  }
+}
+
+/*
+ * Attempt #1: Static analysis: Lower Fidelity, but faster.
+ * Do our best job to statically scan a file for named exports. This uses "cjs-module-lexer", the
+ * same CJS export scanner that Node.js uses internally. Very fast, but only works on some modules,
+ * depending on how they were build/written/compiled.
+ */
+const detectStaticExports = ({ logger, fileUrl, visited = new Set() }) => {
+  const isMainEntrypoint = visited.size === 0
+  // Prevent infinite loops via circular dependencies.
+  if (visited.has(fileUrl)) {
+    return []
+  }
+  visited.add(fileUrl)
+
+  const fileContents = readFileSync(new URL(fileUrl), "utf8")
+  try {
+    const { exports, reexports } = parse(fileContents)
+    // If re-exports were detected (`exports.foo = require(...)`) then resolve them here.
+    let resolvedReexports = []
+    if (reexports.length > 0) {
+      reexports.forEach((reexport) => {
+        const reExportedFilePath = resolve.sync(reexport, {
+          basedir: fileURLToPath(new URL("./", fileUrl)),
+        })
+        const reExportedFileUrl = pathToFileURL(reExportedFilePath)
+        const staticExports = detectStaticExports({
+          logger,
+          fileUrl: reExportedFileUrl,
+          visited,
+        })
+        if (staticExports) {
+          resolvedReexports = [...resolvedReexports, ...staticExports]
+        }
+      })
+    }
+    const resolvedExports = Array.from(
+      new Set([...exports, ...resolvedReexports]),
+    ).filter(isValidNamedExport)
+
+    if (isMainEntrypoint && resolvedExports.length === 0) {
+      return undefined
+    }
+
+    return resolvedExports
+  } catch (err) {
+    // Safe to ignore, this is usually due to the file not being CJS.
+    logger.debug(`detectStaticExports ${fileUrl}: ${err.message}`)
+    return undefined
+  }
+}
+
+/*
+ * Attempt #2b - Sandboxed runtime analysis: More powerful, but slower.
+ * This will only work on UMD and very simple CJS files (require not supported).
+ * Uses VM2 to run safely sandbox untrusted code (no access no Node.js primitives, just JS).
+ * If nothing was detected, return undefined.
+ */
+const detectExportsUsingSandboxedRuntime = ({ logger, fileUrl }) => {
+  try {
+    const fileContents = readFileSync(new URL(fileUrl), "utf8")
+    const vm = new VM2({ wasm: false, fixAsync: false })
+    const codeToRun = wrapCodeToRunInVm(fileContents)
+    const vmResult = vm.run(codeToRun)
+    const exportsResult = Object.keys(vmResult)
+    logger.debug(
+      `detectExportsUsingSandboxedRuntime success ${fileUrl}: ${exportsResult}`,
+    )
+    return exportsResult.filter((identifier) => isValidIdentifier(identifier))
+  } catch (err) {
+    logger.debug(
+      `detectExportsUsingSandboxedRuntime error ${fileUrl}: ${err.message}`,
+    )
+    return undefined
+  }
+}
+
+const isValidNamedExport = (name) =>
+  name !== "default" && name !== "__esModule" && isValidIdentifier(name)
+
+const wrapCodeToRunInVm = (code) => {
+  return `const exports = {};
+const module = { exports };
+${code};;
+module.exports;`
+}
+
+const generateCodeForExports = ({
+  uniqueNamedExports,
+  inputSummary,
+  inputFileUrl,
+}) => {
+  const from =
+    process.platform === "win32"
+      ? inputFileUrl.slice("file:///".length)
+      : inputFileUrl.slice("file://".length)
+  const lines = [
+    ...(inputSummary.namespace ? [stringifyNamespaceReExport({ from })] : []),
+    ...(inputSummary.default ? [stringifyDefaultReExport({ from })] : []),
+    stringifyNamedReExports({
+      namedExports: uniqueNamedExports,
+      from,
+    }),
+  ]
+  return lines.join(`
+`)
+}
+
+const stringifyNamespaceReExport = ({ from }) => {
+  return `export * from "${from}";`
+}
+
+const stringifyDefaultReExport = ({ from }) => {
+  return `import __jsenv_default_import__ from "${from}";
+export default __jsenv_default_import__;`
+}
+
+const stringifyNamedReExports = ({ namedExports, from }) => {
+  return `export { ${namedExports.join(",")} } from "${from}";`
+}