@contrast/esm-hooks 2.4.1 → 2.5.0

package/lib/common.mjs

@@ -12,51 +12,17 @@
  * engineered, modified, repackaged, sold, redistributed or otherwise used in a
  * way not consistent with the End User License Agreement.
  */
-
+// @ts-check
 import { readdir } from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const REDIRECTS_PATH = './redirects';
 
 export const mappings = await makeMappings();
 
-// why do we need to fix paths? Because windows, node, and URLs don't get
-// along very well.
-//
-// the load() hook receives an URL. When the URL is converted into an URL object,
-// the pathname property will be '/C:/Users/.../redirects' on windows. And that
-// doesn't start with a drive letter, so when fsp.readdir() gets it, node decides
-// to add a drive letter: 'C:/C:/Users/.../redirects'. So we have to strip off the
-// the leading / so the drive letter is recognized and another isn't added. it seems
-// like a node bug (or possibly windows bug) but i don't have time to research the
-// standards to figure out what URL.pathname should be in a windows file: context.
-//
-// maybe this should be in the load() hook?
-//
-// should
-/**
- *
- * @param {string} path
- * @returns {string}
- */
-export function fixPath(p) {
-  if (p.match(/^\/[A-Z]:/)) {
-    p = p.slice(1);
-  }
-  return p;
-}
-
-import { getFileType } from './get-file-type.mjs';
-export { getFileType };
-
-async function makeMappings() {
-  /**
-   * @typedef { 'builtin' | 'commonjs' | 'module' } TargetType
-   * @typedef {string} RequireSpecifier
-   */
-  /**
-   * @type {Record<RequireSpecifier, {url: URL, target: TargetType}>}
-   */
+export async function makeMappings() {
+  /** @type {Record<string, string>} */
   const mappings = Object.create(null);
 
   // the name of the directory is the format of the target being loaded. so "cjs"
@@ -80,12 +46,15 @@ async function makeMappings() {
 
     // get an absolute path because reading the redirect file is going to be executed
     // in another context.
-    const p = path.join(REDIRECTS_PATH, dir);
-    const redirectDir = new URL(p, import.meta.url);
-    const dirpath = fixPath(redirectDir.pathname);
+    const redirectsPath = path.resolve(
+      path.dirname(fileURLToPath(import.meta.url)),
+      REDIRECTS_PATH,
+      dir,
+    );
 
-    await recursiveReaddir(dirpath);
+    await recursiveReaddir(redirectsPath);
 
+    /** @param {string} dirpath */
     // eslint-disable-next-line no-inner-declarations
     async function recursiveReaddir(dirpath) {
       const dirents = await readdir(dirpath, { withFileTypes: true });
@@ -101,13 +70,15 @@ async function makeMappings() {
         if (!dirent.name.endsWith('.mjs')) {
           continue;
         }
-        // it a file that ends with .mjs, so it's a redirect file.
-        const redirectURL = new URL(path.join(p, ...pathStack, dirent.name), import.meta.url);
+        // it's a file that ends with .mjs, so it's a redirect file.
+        const redirectURL = pathToFileURL(path.join(dirpath, dirent.name));
 
-        // all redirects point to .mjs files; the target property specifies the type of the
-        // the file that will be loaded by the .mjs. target. target is builtin, commonjs, or
-        // module.
-        // e.g., //'node-fetch': {url: new URL(`${p}/node-fetch.mjs`, import.meta.url), target: 'module'},
+        // all redirects point to .mjs files.
+        // the 'csi-flag' query specifies the type of file that will be loaded
+        // by the redirecting .mjs file:
+        // e.g.,
+        // 'node-fetch': 'file://.../redirects/esm/node-fetch.mjs?csi-flag=module`
+        // 'fs/promises': 'file://.../redirects/builtin/fs/promises.mjs?csi-flag=builtin`,
         //
         // there is a separate builtin directory because putting a colon in a filename doesn't work on windows. so
         // that's why the mapping below adds the `node:` prefix.
@@ -115,13 +86,26 @@ async function makeMappings() {
         if (pathStack.length) {
           name = `${pathStack.join('/')}/${name}`;
         }
+
+        // set flag to module or commonjs. i'm not sure this is needed but am keeping it
+        // in place until we have to implement esm-native module rewrites/wrapping. this
+        // is the point at which resolve() communicates to load().
+        //
+        // builtin's are probably the most likely to be loaded, so they're first.
+        // some tweaks might be needed when we start to patch esm-native modules
+        // in esm-native-code:
+        // https://nodejs.org/docs/latest-v20.x/api/esm.html#builtin-modules
+        // https://nodejs.org/docs/latest-v20.x/api/module.html#modulesyncbuiltinesmexports
         if (dir === 'builtin') {
-          mappings[name] = { url: redirectURL, target: 'builtin' };
-          mappings[`node:${name}`] = { url: redirectURL, target: 'builtin' };
+          redirectURL.searchParams.set('csi-flag', 'builtin');
+          mappings[name] = redirectURL.href;
+          mappings[`node:${name}`] = redirectURL.href;
         } else if (dir === 'cjs') {
-          mappings[name] = { url: redirectURL, target: 'commonjs' };
+          redirectURL.searchParams.set('csi-flag', 'commonjs');
+          mappings[name] = redirectURL.href;
         } else if (dir === 'esm') {
-          mappings[name] = { url: redirectURL, target: 'module' };
+          redirectURL.searchParams.set('csi-flag', 'module');
+          mappings[name] = redirectURL.href;
         } else {
           throw new Error(`target type ${dir} not yet implemented`);
         }
@@ -131,6 +115,3 @@ async function makeMappings() {
 
   return mappings;
 }
-
-// useful for tests
-export { makeMappings };

package/lib/get-file-type.mjs

@@ -12,11 +12,11 @@
  * engineered, modified, repackaged, sold, redistributed or otherwise used in a
  * way not consistent with the End User License Agreement.
  */
-import fs from 'node:fs';
-import path from 'path';
-import M from 'module';
-
-import { findPackageJsonSync } from '@contrast/find-package-json';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import M from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { findPackageJson } from '@contrast/find-package-json';
 
 const isBuiltin = M.isBuiltin || function(pathname) {
   if (pathname.startsWith('node:')) {
@@ -25,30 +25,26 @@ const isBuiltin = M.isBuiltin || function(pathname) {
   return M.builtinModules.includes(pathname);
 };
 
+/** @typedef { 'builtin' | 'commonjs' | 'module' } Format */
+
 /**
- *
- * @param {string} path
- * @returns {string}
+ * @param {string | URL} filename
+ * @param {import('@contrast/find-package-json').Options["stopAt"]=} stopAt
+ * @returns {Promise<Format | null>}
  */
-export function fixPath(p) {
-  if (p.match(/^(\\|\/)[A-Za-z]:/)) {
-    p = p.slice(1);
+export async function getFileType(filename, stopAt) {
+  try {
+    filename = fileURLToPath(filename);
+  } catch (err) {
+    // already a path or node: url
   }
-  return p;
-}
 
-export function getFileType(filename) {
-  let pathname = filename.pathname || filename;
-  // presumes 16.17+
-  if (isBuiltin(pathname)) {
+  if (isBuiltin(filename)) {
     return 'builtin';
   }
 
-  pathname = pathname.replace('file://', '');
-
-  // if the file extension specifies the type, there's no need to do extra
-  // IO.
-  const ext = path.extname(pathname);
+  // if the file extension specifies the type, there's no need to do extra IO.
+  const ext = path.extname(filename);
   if (ext === '.mjs') {
     return 'module';
   } else if (ext === '.cjs') {
@@ -58,14 +54,12 @@ export function getFileType(filename) {
   // Node assumes `commonjs` if `type` is not set in package.json
   let parentType = 'commonjs';
   try {
-    // should this have stopAt set at the application root? do we know what the
-    // root of the application is?
-    const pkg = findPackageJsonSync({ cwd: fixPath(path.dirname(pathname)) });
+    const pkg = await findPackageJson({ cwd: filename, stopAt });
     if (pkg) {
-      let json = fs.readFileSync(pkg, 'utf8');
-      json = JSON.parse(json);
-      if (json.type) {
-        parentType = json.type;
+      const json = await readFile(pkg, 'utf8');
+      const { type } = JSON.parse(json);
+      if (type) {
+        parentType = type;
       }
     }
   } catch (err) {

package/lib/hooks.mjs

@@ -13,29 +13,41 @@
  * way not consistent with the End User License Agreement.
  */
 
-import { readFile as rf } from 'node:fs/promises';
 import * as process from 'node:process';
-import { fixPath, getFileType, mappings } from './common.mjs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { mappings } from './common.mjs';
+import { getFileType } from './get-file-type.mjs';
 import { default as initLoaderAgent } from './loader-agent.mjs';
 const [major, minor] = process.versions.node.split('.').map(it => +it);
 const isLT16_12 = major < 16 || (major === 16 && minor < 12);
 
-const readFile = rf;
+/**
+ * @typedef {Object} ResolveResult
+ * @prop {string=} format A hint to the load hook (it might be ignored) 'builtin' | 'commonjs' | 'json' | 'module' | 'wasm'
+ * @prop {Object=} importAssertions The import assertions to use when caching the module (optional; if excluded the input will be used) (before v21)
+ * @prop {Object=} importAttributes The import attributes to use when caching the module (optional; if excluded the input will be used) (after v21)
+ * @prop {boolean=} shortCircuit A signal that this hook intends to terminate the chain of `resolve` hooks. Default: `false`
+ * @prop {string} url The absolute URL to which this input resolves
+ */
+
+/**
+ * @typedef {Object} LoadResult
+ * @prop {string} format
+ * @prop {boolean=} shortCircuit A signal that this hook intends to terminate the chain of resolve hooks. Default: `false`
+ * @prop {string | ArrayBuffer | TypedArray} source The source for Node.js to evaluate
+ */
 
 /**
  * Agent instance with minimum footprint that handles functionality related esm module loading.
  * - We handles redirects to force require.
  * - Module rewriting via exported load hook
+ * @type {import('./loader-agent.mjs').LoaderAgent=}
  */
 let loaderAgent;
 
 /**
- * @param {{
- *   modes: string[],
- *   port: import('node:worker_threads').MessagePort,
- *   appInfo: import('@contrast/common').AppInfo,
- *   agentVersion: string,
- * }} data
+ * Module.register callback
+ * @param {import('./loader-agent.mjs').InitData} data
  */
 async function initialize(data = {}) {
   loaderAgent = initLoaderAgent(data);
@@ -43,116 +55,127 @@ async function initialize(data = {}) {
   await loaderAgent.install();
 }
 
+/**
+ * @param {string} specifier
+ * @param {Object} context
+ * @param {string[]} context.conditions Export conditions of the relevant package.json
+ * @param {Object=} context.importAssertions An object whose key-value pairs represent the assertions for the module to import (before v21)
+ * @param {Object=} context.importAttributes An object whose key-value pairs represent the attributes for the module to import (after v21)
+ * @param {string=} context.parentURL The module importing this one, or undefined if this is the Node.js entry point
+ * @param {(specifier, context) => Promise<ResolveResult>} nextResolve The subsequent resolve hook in the chain, or the Node.js default resolve hook after the last user-supplied resolve hook
+ * @returns {Promise<ResolveResult>}
+ */
 async function resolve(specifier, context, nextResolve) {
   loaderAgent?.esmHooks?.debugEsmResolve?.(specifier);
 
+  if (!loaderAgent?.enable) {
+    return protectedNextResolve(specifier, context, nextResolve);
+  }
+
   let isFlaggedToPatch = false;
   if (context.parentURL) {
-    isFlaggedToPatch = context.parentURL.endsWith('csi-flag=', context.parentURL.length - 1);
+    isFlaggedToPatch = new URL(context.parentURL).searchParams.has('csi-flag');
   }
 
-  if (loaderAgent?.enable && !isFlaggedToPatch && specifier in mappings) {
-    // eslint-disable-next-line prefer-const
-    let { url, format, target } = mappings[specifier];
-    // set flag to module or commonjs. i'm not sure this is needed but am keeping it
-    // in place until we have to implement esm-native module rewrites/wrapping. this
-    // is the point at which resolve() communicates to load().
-    //
-    // builtin's are probably the most likely to be loaded, so they're first.
-    // some tweaks might be needed when we start to patch esm-native modules
-    // in esm-native-code:
-    // https://nodejs.org/docs/latest-v20.x/api/esm.html#builtin-modules
-    // https://nodejs.org/docs/latest-v20.x/api/module.html#modulesyncbuiltinesmexports
-    if (target === 'builtin') {
-      url = `${url.href}?csi-flag=m`;
-      format = 'module';
-    } else if (target === 'commonjs') {
-      url = `${url.href}?csi-flag=c`;
-      format = getFileType(url) || format || 'commonjs';
-    } else if (target === 'module') {
-      url = `${url.href}?csi-flag=m`;
-      format = getFileType(url) || format || 'module';
-    } else {
-      throw new Error(`unexpected target ${target} for ${specifier}`);
-    }
-
+  if (!isFlaggedToPatch && specifier in mappings) {
     return {
-      url,
-      format,
+      url: mappings[specifier],
+      format: 'module',
       shortCircuit: true,
     };
   }
 
-  return protectedNextResolve(nextResolve, specifier, context);
+  return protectedNextResolve(specifier, context, nextResolve);
 }
 
+/**
+ * @param {string} url The URL returned by the resolve chain
+ * @param {Object} context
+ * @param {string[]} context.conditions Export conditions of the relevant package.json
+ * @param {string=} context.format The format optionally supplied by the resolve hook chain
+ * @param {Object=} context.importAssertions (before v21)
+ * @param {Object=} context.importAttributes (after v21)
+ * @param {(url, context) => Promise<LoadResult>} nextLoad The subsequent load hook in the chain, or the Node.js default load hook after the last user-supplied load hook
+ * @returns {Promise<LoadResult>}
+ */
 async function load(url, context, nextLoad) {
   loaderAgent?.esmHooks?.debugEsmLoad?.(url);
 
   const urlObject = new URL(url);
+  const type = await getFileType(url, loaderAgent?.appInfo.app_dir);
 
-  if (loaderAgent?.enable && urlObject.searchParams.has('csi-flag')) {
-    const { pathname } = urlObject;
-    const source = await readFile(fixPath(pathname), 'utf8');
-    return {
-      source,
-      format: 'module',
-      shortCircuit: true,
-    };
+  // if it's not a builtin or a flagged file, it needs to be rewritten.
+  // if it's not an es module it will be rewritten by the require hooks.
+  if (!loaderAgent?.enable || urlObject.searchParams.has('csi-flag') || type !== 'module') {
+    return nextLoad(url, context);
   }
 
-  if (urlObject.pathname.endsWith('.node')) {
-    const metaUrl = JSON.stringify(url);
-    const addon = urlObject.pathname;
+  const filename = fileURLToPath(url);
+
+  // Handles the event that other hooks redirect an import to a `.node` addon.
+  if (filename.endsWith('.node')) {
     return {
-      source: `require("node:module").createRequire(${metaUrl})("${addon}")`,
+      source: `module.exports = require("${filename}");`,
       format: 'commonjs',
       shortCircuit: true,
     };
   }
 
-  // if it's not a builtin, a .node addon, or a flagged file, it needs to be
-  // rewritten if it's a module.
-  if (urlObject.pathname.match(/(.js|.mjs|.cjs)$/)) {
-    // if it's not a module it will be rewritten by the require hooks.
-    const type = getFileType(urlObject);
-    if (type !== 'module') {
-      return nextLoad(url, context);
-    }
+  if (loaderAgent.config.agent.node.rewrite.cache.enable) {
+    const cached = await loaderAgent.rewriter.cache.find(filename);
 
-    const filename = fixPath(urlObject.pathname);
-    const source = await readFile(filename, 'utf8');
-    let result;
-
-    if (loaderAgent?.enable) {
-      const rewriteOptions = {
-        filename,
-        isModule: type === 'module',
-        inject: true,
-        wrap: type !== 'module', // cannot wrap modules
-      };
-      result = await loaderAgent.rewriter.rewrite(source, rewriteOptions);
-
-      if (process.env.CSI_EXPOSE_CORE) {
-        // only do this in testing scenarios (todo: compose this functionality into test agents instead)
-        loaderAgent.esmHooks.portClient.sendStatus('rewriting file during ESM load hook', rewriteOptions);
-      }
+    if (cached) {
+      return nextLoad(pathToFileURL(cached).href, context);
     }
+  }
 
-    return {
-      source: result?.code || source,
-      format: type || 'commonjs', // don't know what else to do here. log?
-      shortCircuit: true,
-    };
+  /** @type {import('@contrast/rewriter').RewriteOpts} */
+  const rewriteOptions = {
+    filename,
+    isModule: true,
+    inject: true,
+    wrap: false, // cannot wrap modules
+    trim: false,
+  };
+
+  const { source } = await nextLoad(url, context);
+  const rewriteResult = await loaderAgent.rewriter.rewrite(
+    source.toString(), // might be a Buffer
+    rewriteOptions
+  );
+
+  if (process.env.CSI_EXPOSE_CORE) {
+    // only do this in testing scenarios (todo: compose this functionality into test agents instead)
+    loaderAgent.esmHooks.portClient.sendStatus('rewriting file during ESM load hook', rewriteOptions);
   }
 
-  // this never gets called, so hmmm.
-  return nextLoad(url, context);
+  if (loaderAgent.config.agent.node.rewrite.cache.enable) {
+    loaderAgent.rewriter.cache.write(filename, rewriteResult);
+  }
+
+  return {
+    source: rewriteResult.code,
+    format: 'module',
+    shortCircuit: true,
+  };
 }
 
-async function protectedNextResolve(nextResolve, specifier, context) {
+/**
+ * from https://github.com/iambumblehead/esmock/blob/main/src/esmockLoader.js#L89
+ *
+ * new versions of node: when multiple loaders are used and context
+ * is passed to nextResolve, the process crashes in a recursive call
+ * see: /esmock/issues/#48
+ *
+ * old versions of node: if context.parentURL is defined, and context
+ * is not passed to nextResolve, the tests fail
+ *
+ * later versions of node v16 include 'node-addons'
+ * @type {typeof resolve}
+ */
+async function protectedNextResolve(specifier, context, nextResolve) {
   if (context.parentURL) {
-    if (context.conditions.at(-1) === 'node-addons' || context.importAssertions || isLT16_12) {
+    if (context.conditions.at(-1) === 'node-addons' || context.importAssertions || context.importAttributes || isLT16_12) {
       return nextResolve(specifier, context);
     }
   }

package/lib/index.mjs

@@ -16,7 +16,6 @@
 import Module from 'node:module';
 import { MessageChannel } from 'node:worker_threads';
 import { default as debugMethods } from './debug-methods.mjs';
-import { initialize, load, resolve } from './hooks.mjs';
 import { default as portClient } from './post-message/main-client.mjs';
 
 export default function init(core) {
@@ -26,7 +25,6 @@ export default function init(core) {
   } = new MessageChannel();
 
   const esmHooks = core.esmHooks = {
-    hooks: { resolve, load }, // remove when all LTS versions support Module.register
     getActiveModes() {
       const modes = [];
       if (core.config.getEffectiveValue('assess.enable')) {
@@ -53,12 +51,14 @@ export default function init(core) {
       // Instantiate loader agent via register (if available) or manually.
       // we can simplify when all LTS versions support register
       if (Module.register) {
-        await Module.register(new URL('./hooks.mjs', import.meta.url).href, {
+        await Module.register('./hooks.mjs', import.meta.url, {
           data,
           transferList: [workerPort],
         });
       } else {
+        const { initialize, resolve, load } = await import('./hooks.mjs');
         await initialize(data);
+        esmHooks.hooks = { resolve, load };
       }
 
       // these have side-effects, so compose during installation phase

package/lib/loader-agent.mjs

@@ -19,18 +19,34 @@ import { default as debugMethods } from './debug-methods.mjs';
 import { default as portClient } from './post-message/loader-client.mjs';
 const require = Module.createRequire(import.meta.url);
 
-// TODO: language
+/**
+ * @typedef {Object} InitData
+ * @prop {import('@contrast/rewriter').Mode[]} modes
+ * @prop {import('node:worker_threads').MessagePort} port
+ * @prop {import('@contrast/common').AppInfo} appInfo
+ * @prop {string} agentVersion
+ */
+
+/**
+ * @typedef {Object} LoaderAgent
+ * @prop {import('@contrast/common').Messages} messages
+ * @prop {import('@contrast/common').AppInfo} appInfo
+ * @prop {string} agentVersion
+ * @prop {boolean} enable
+ * @prop {Record<never, never>} esmHooks
+ * @prop {import('@contrast/config').Config} config
+ * @prop {import('@contrast/logger').Logger} logger
+ * @prop {import('@contrast/rewriter').Rewriter} rewriter
+ */
+
 const ERROR_MESSAGE = 'An error prevented the Contrast agent from initializing in the loader thread.';
 
 /**
- * @param {{
- *   modes: string[],
- *   port: import('node:worker_threads').MessagePort,
- *   appInfo: import('@contrast/common').AppInfo,
- *   agentVersion: string,
- * }} data
+ * @param {InitData} data
+ * @returns {LoaderAgent}
  */
 export default function init({ appInfo, agentVersion, port, modes }) {
+  /** @type {LoaderAgent} */
   const core = {
     appInfo,
     agentVersion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/esm-hooks",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "type": "module",
   "description": "Support for loading and instrumenting ECMAScript modules",
   "license": "SEE LICENSE IN LICENSE",
@@ -19,8 +19,8 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.19.0",
-    "@contrast/core": "1.30.0",
+    "@contrast/common": "1.20.0",
+    "@contrast/core": "1.31.0",
     "@contrast/find-package-json": "^1.0.0"
   }
 }