@knighted/module 1.0.0-alpha.8 → 1.0.0-beta.0

package/README.md

@@ -9,11 +9,10 @@ Node.js utility for transforming a JavaScript or TypeScript file from an ES modu
 - ES module ➡️ CommonJS
 - CommonJS ➡️ ES module
 
-By default `@knighted/module` transforms the one-to-one [differences between ES modules and CommonJS](https://nodejs.org/api/esm.html#differences-between-es-modules-and-commonjs), but it also accepts options that allow:
+> [!IMPORTANT]  
+> All parsing logic is applied under the assumption the code is in [strict mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode) which [modules run under by default](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#other_differences_between_modules_and_classic_scripts).
 
-- Converting `import`/`export` to `require`/`exports`
-- Extensions to be updated in relative specifiers
-- Write transformed source code to a filename
+By default `@knighted/module` transforms the one-to-one [differences between ES modules and CommonJS](https://nodejs.org/api/esm.html#differences-between-es-modules-and-commonjs). Options let you control syntax rewriting, specifier updates, and output.
 
 ## Requirements
 
@@ -47,9 +46,8 @@ You can transform it to the equivalent CommonJS module
 import { transform } from '@knighted/module'
 
 await transform('./file.js', {
-  type: 'commonjs'
-  moduleLoading: true,
-  out: './file.cjs'
+  target: 'commonjs',
+  out: './file.cjs',
 })
 ```
 
@@ -65,7 +63,10 @@ const { realpath } = require('node:fs/promises')
 const detectCalledFromCli = async path => {
   const realPath = await realpath(path)
 
-  if (require('node:url').pathToFileURL(__filename).toString() === pathToFileURL(realPath).href) {
+  if (
+    require('node:url').pathToFileURL(__filename).toString() ===
+    pathToFileURL(realPath).href
+  ) {
     console.log('invoked directly by node')
   }
 }
@@ -84,18 +85,29 @@ invoked directly by node
 
 ```ts
 type ModuleOptions = {
-  /* What module system to convert to. */
-  type?: 'module' | 'commonjs'
-  /* Whether import/export and require/exports should be transformed. */
-  modules?: boolean
-  /* Whether to change specifier extensions to the assigned value. If omitted they are left alone. */
-  specifier?: '.js' | '.mjs' | '.cjs' | '.ts' | '.mts' | '.cts'
-  /* What filepath to write the transformed source to. */
+  target: 'module' | 'commonjs'
+  sourceType?: 'auto' | 'module' | 'commonjs'
+  transformSyntax?: boolean
+  liveBindings?: 'strict' | 'loose' | 'off'
+  rewriteSpecifier?:
+    | '.js'
+    | '.mjs'
+    | '.cjs'
+    | '.ts'
+    | '.mts'
+    | '.cts'
+    | ((value: string) => string | null | undefined)
+  dirFilename?: 'inject' | 'preserve' | 'error'
+  importMeta?: 'preserve' | 'shim' | 'error'
+  requireSource?: 'builtin' | 'create-require'
+  cjsDefault?: 'module-exports' | 'auto' | 'none'
+  topLevelAwait?: 'error' | 'wrap' | 'preserve'
   out?: string
+  inPlace?: boolean
 }
 ```
 
 ## Roadmap
 
-- Support option `modules`.
 - Remove `@knighted/specifier` and avoid double parsing.
+- Flesh out live-binding and top-level await handling.

package/dist/assignmentExpression.d.ts

@@ -0,0 +1,12 @@
+import MagicString from 'magic-string';
+import type { Node, AssignmentExpression } from 'oxc-parser';
+import type { FormatterOptions, ExportsMeta } from '../types.js';
+type AssignmentExpressionArg = {
+    node: AssignmentExpression;
+    parent: Node | null;
+    code: MagicString;
+    opts: FormatterOptions;
+    meta: ExportsMeta;
+};
+export declare const assignmentExpression: ({ node, parent: _parent, code: _code, opts, meta: _meta, }: AssignmentExpressionArg) => Promise<void>;
+export {};

package/dist/cjs/assignmentExpression.d.cts

@@ -0,0 +1,12 @@
+import MagicString from 'magic-string';
+import type { Node, AssignmentExpression } from 'oxc-parser';
+import type { FormatterOptions, ExportsMeta } from '../types.cjs';
+type AssignmentExpressionArg = {
+    node: AssignmentExpression;
+    parent: Node | null;
+    code: MagicString;
+    opts: FormatterOptions;
+    meta: ExportsMeta;
+};
+export declare const assignmentExpression: ({ node, parent: _parent, code: _code, opts, meta: _meta, }: AssignmentExpressionArg) => Promise<void>;
+export {};

package/dist/cjs/expressionStatement.d.cts

@@ -1,5 +1,4 @@
 import MagicString from 'magic-string';
-import type { NodePath } from '@babel/traverse';
-import type { ExpressionStatement } from '@babel/types';
+import type { Node, ExpressionStatement } from 'oxc-parser';
 import type { FormatterOptions } from '../types.cjs';
-export declare const expressionStatement: (nodePath: NodePath<ExpressionStatement>, src: MagicString, options: FormatterOptions) => void;
+export declare const expressionStatement: (node: ExpressionStatement, parent: Node | null, src: MagicString, options: FormatterOptions) => void;

package/dist/cjs/format.cjs

@@ -5,37 +5,111 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.format = void 0;
 var _magicString = _interopRequireDefault(require("magic-string"));
-var _traverse2 = _interopRequireDefault(require("@babel/traverse"));
-var _nodeModuleType = require("node-module-type");
 var _identifier = require("./formatters/identifier.cjs");
 var _metaProperty = require("./formatters/metaProperty.cjs");
 var _memberExpression = require("./formatters/memberExpression.cjs");
+var _assignmentExpression = require("./formatters/assignmentExpression.cjs");
+var _utils = require("./utils.cjs");
+var _identifier2 = require("./helpers/identifier.cjs");
+var _walk = require("./walk.cjs");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-/**
- * Runtime hack to prevent issues with babel's default interop while dual building with tsc.
- * @see https://github.com/babel/babel/discussions/13093#discussioncomment-12705927
- * Temporary fix until I switch to oxc-parser.
- */
-const type = (0, _nodeModuleType.moduleType)();
-const traverse = typeof _traverse2.default === 'function' || type === 'commonjs' ? _traverse2.default : _traverse2.default.default;
-
 /**
  * Note, there is no specific conversion for `import.meta.main` as it does not exist.
  * @see https://github.com/nodejs/node/issues/49440
  */
-const format = (code, ast, options) => {
-  const src = new _magicString.default(code);
-  traverse(ast, {
-    Identifier(path) {
-      (0, _identifier.identifier)(path, src, options);
-    },
-    MetaProperty(path) {
-      (0, _metaProperty.metaProperty)(path, src, options);
-    },
-    MemberExpression(path) {
-      (0, _memberExpression.memberExpression)(path, src, options);
+const format = async (src, ast, opts) => {
+  const code = new _magicString.default(src);
+  const exportsMeta = {
+    hasExportsBeenReassigned: false,
+    defaultExportValue: undefined,
+    hasDefaultExportBeenReassigned: false,
+    hasDefaultExportBeenAssigned: false
+  };
+  await (0, _utils.collectModuleIdentifiers)(ast.program);
+  if (opts.target === 'module' && opts.transformSyntax) {
+    /**
+     * Prepare ESM output by renaming `exports` to `__exports` and seeding an
+     * `import.meta.filename` touch so import.meta is present even when the
+     * original source never referenced it.
+     */
+    code.prepend(`let ${_utils.exportsRename} = {};
+void import.meta.filename;
+`);
+  }
+  await (0, _walk.ancestorWalk)(ast.program, {
+    async enter(node, ancestors) {
+      const parent = ancestors[ancestors.length - 2] ?? null;
+      if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') {
+        const skipped = ['__filename', '__dirname'];
+        const skippedParams = node.params.filter(param => param.type === 'Identifier' && skipped.includes(param.name));
+        const skippedFuncIdentifier = node.id?.type === 'Identifier' && skipped.includes(node.id.name);
+        if (skippedParams.length || skippedFuncIdentifier) {
+          this.skip();
+        }
+      }
+
+      /**
+       * Check for assignment to `import.meta.url`.
+       */
+      if (node.type === 'AssignmentExpression' && node.left.type === 'MemberExpression' && node.left.object.type === 'MetaProperty' && node.left.property.type === 'Identifier' && node.left.property.name === 'url') {
+        if (node.right.type === 'Literal' && typeof node.right.value === 'string') {
+          if (!(0, _utils.isValidUrl)(node.right.value)) {
+            const rhs = code.snip(node.right.start, node.right.end).toString();
+            const assignment = code.snip(node.start, node.end).toString();
+            code.update(node.start, node.end, `/* Invalid assignment: ${rhs} is not a URL. ${assignment} */`);
+            this.skip();
+          }
+        }
+      }
+
+      /**
+       * Skip module scope CJS globals when they are object properties.
+       * Ignoring `exports` here.
+       */
+      if (node.type === 'MemberExpression' && node.property.type === 'Identifier' && ['__filename', '__dirname'].includes(node.property.name)) {
+        this.skip();
+      }
+
+      /**
+       * Check for bare `module.exports` expressions.
+       */
+      if (node.type === 'MemberExpression' && node.object.type === 'Identifier' && node.object.name === 'module' && node.property.type === 'Identifier' && node.property.name === 'exports' && parent?.type === 'ExpressionStatement') {
+        if (opts.target === 'module') {
+          code.update(node.start, node.end, ';');
+          // Prevent parsing the `exports` identifier again.
+          this.skip();
+        }
+      }
+
+      /**
+       * Format `module.exports` and `exports` assignments.
+       */
+      if (node.type === 'AssignmentExpression') {
+        await (0, _assignmentExpression.assignmentExpression)({
+          node,
+          parent,
+          code,
+          opts,
+          meta: exportsMeta
+        });
+      }
+      if (node.type === 'MetaProperty') {
+        (0, _metaProperty.metaProperty)(node, parent, code, opts);
+      }
+      if (node.type === 'MemberExpression') {
+        (0, _memberExpression.memberExpression)(node, parent, code, opts);
+      }
+      if ((0, _identifier2.isIdentifierName)(node)) {
+        (0, _identifier.identifier)({
+          node,
+          ancestors,
+          code,
+          opts,
+          meta: exportsMeta
+        });
+      }
     }
   });
-  return src;
+  return code.toString();
 };
 exports.format = format;

package/dist/cjs/format.d.cts

@@ -1,9 +1,8 @@
-import MagicString from 'magic-string';
-import type { ParseResult } from '@babel/parser';
-import type { File } from '@babel/types';
+import type { ParseResult } from 'oxc-parser';
 import type { FormatterOptions } from './types.cjs';
 /**
  * Note, there is no specific conversion for `import.meta.main` as it does not exist.
  * @see https://github.com/nodejs/node/issues/49440
  */
-export declare const format: (code: string, ast: ParseResult<File>, options: FormatterOptions) => MagicString;
+declare const format: (src: string, ast: ParseResult, opts: FormatterOptions) => Promise<string>;
+export { format };

package/dist/cjs/formatters/assignmentExpression.cjs

@@ -0,0 +1,37 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.assignmentExpression = void 0;
+var _walk = require("../walk.cjs");
+const assignmentExpression = async ({
+  node,
+  parent: _parent,
+  code: _code,
+  opts,
+  meta: _meta
+}) => {
+  if (opts.target === 'module' && opts.transformSyntax) {
+    await (0, _walk.walk)(node, {
+      enter(childNode, childParent) {
+        if (childNode.type === 'Identifier' && childNode.name === 'exports') {
+          if (childParent === node && node.left === childNode) {
+            /**
+             * The code is reassigning `exports` to something else.
+             * Redeclare it with a new variable name using var.
+             */
+            //meta.hasExportsBeenReassigned = true
+            //console.log('writing exports reassignment')
+            //code.update(node.left.start, node.left.end, exportsRename)
+            //console.log(code.slice(node.start, node.end))
+            //code.update(childNode.start, childNode.end, exportsRename)
+            //console.log('reassigning exports', childParent, code.update(node.left.start, node.left.end, exportsRename))
+          }
+          //console.log('found exports assignment', meta.hasExportsBeenReassigned, expr)
+        }
+      }
+    });
+  }
+};
+exports.assignmentExpression = assignmentExpression;

package/dist/cjs/formatters/expressionStatement.cjs

@@ -4,64 +4,45 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.expressionStatement = void 0;
-const expressionStatement = (nodePath, src, options) => {
-  if (options.type === 'module') {
-    const {
-      node
-    } = nodePath;
-    const {
-      start,
-      end
-    } = node;
-    if (typeof start === 'number' && typeof end === 'number') {
-      const isMemberExpressionModuleExports = expression => {
-        return expression.object.type === 'Identifier' && expression.object.name === 'module' && expression.property.type === 'Identifier' && expression.property.name === 'exports';
-      };
-      if (node.expression.type === 'Identifier') {
-        const name = node.expression.name;
+const expressionStatement = (node, parent, src, options) => {
+  if (options.target === 'module') {
+    if (node.expression.type === 'Identifier') {
+      const {
+        start,
+        end
+      } = node;
+      const name = node.expression.name;
 
-        // CommonJS globals
-        switch (name) {
-          case 'module':
-            src.update(start, end, 'import.meta');
-            break;
-          case 'exports':
-            src.update(start, end, '{}');
-            break;
-          case '__filename':
-            src.update(start, end, 'import.meta.filename');
-            break;
-          case '__dirname':
-            src.update(start, end, 'import.meta.dirname');
-            break;
-        }
-      }
-      if (node.expression.type === 'MemberExpression') {
-        const {
-          expression
-        } = node;
-
-        // Check for `module.exports` without an assignment
-        if (isMemberExpressionModuleExports(expression)) {
-          /**
-           * @TODO: Should this depend on `options.modules` being enabled?
-           * Probably not for the same reason `exports` is converted to an empty object (ReferenceError in ESM).
-           * This is a standalone reference to `module.exports` without being part of an AssignmentExpression.
-           */
+      // CommonJS globals (as bare identifiers)
+      switch (name) {
+        case 'require':
+          src.remove(start, end);
+          break;
+        case 'module':
+          src.update(start, end, 'import.meta');
+          break;
+        case 'exports':
           src.update(start, end, '{}');
-        }
-      }
-
-      /*
-      if (
-        options.modules &&
-        node.expression.type === 'AssignmentExpression' &&
-        node.expression.left.type === 'MemberExpression' &&
-        isMemberExpressionModuleExports(node.expression.left)
-      ) {
-        // @TODO support `modules` option.
+          break;
+        case '__filename':
+          src.update(start, end, 'import.meta.filename');
+          break;
+        case '__dirname':
+          src.update(start, end, 'import.meta.dirname');
+          break;
       }
-      */
+    }
+  }
+  if (options.target === 'commonjs') {
+    if (node.expression.type === 'Identifier') {
+      const {
+        start,
+        end
+      } = node;
+      const name = node.expression.name;
+      void start;
+      void end;
+      void name;
     }
   }
 };

package/dist/cjs/formatters/identifier.cjs

@@ -4,44 +4,44 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.identifier = void 0;
-const identifier = (nodePath, src, options) => {
-  if (options.type === 'module') {
-    const {
-      node
-    } = nodePath;
+var _utils = require("../utils.cjs");
+var _identifier = require("../helpers/identifier.cjs");
+const identifier = ({
+  node,
+  ancestors,
+  code,
+  opts,
+  meta
+}) => {
+  if (opts.target === 'module') {
     const {
       start,
-      end
+      end,
+      name
     } = node;
-    if (typeof start === 'number' && typeof end === 'number' && node.type === 'Identifier') {
-      const {
-        name
-      } = node;
-      const isMemberExpression = Boolean(nodePath.findParent(path => path.isMemberExpression()));
+    switch (name) {
+      case '__filename':
+        code.update(start, end, 'import.meta.url');
+        break;
+      case '__dirname':
+        code.update(start, end, 'import.meta.dirname');
+        break;
+      case 'exports':
+        {
+          const parent = ancestors[ancestors.length - 2];
+          if (opts.transformSyntax) {
+            if (parent.type === 'AssignmentExpression' && parent.left === node) {
+              // The code is reassigning `exports` to something else.
 
-      // CommonJS globals in expression/statement
-      switch (name) {
-        case 'module':
-          {
-            if (!isMemberExpression) {
-              src.update(start, end, 'import.meta');
+              meta.hasExportsBeenReassigned = true;
+              code.update(parent.left.start, parent.left.end, _utils.exportsRename);
             }
-            break;
-          }
-        case 'exports':
-          {
-            if (!isMemberExpression) {
-              src.update(start, end, '{}');
+            if (_identifier.identifier.isModuleScope(ancestors) && !_identifier.identifier.isFunctionExpressionId(ancestors) && !_identifier.identifier.isExportSpecifierAlias(ancestors) && !_identifier.identifier.isClassPropertyKey(ancestors) && !_identifier.identifier.isMethodDefinitionKey(ancestors) && !_identifier.identifier.isMemberKey(ancestors) && !_identifier.identifier.isPropertyKey(ancestors) && !_identifier.identifier.isIife(ancestors)) {
+              code.update(start, end, _utils.exportsRename);
             }
-            break;
           }
-        case '__filename':
-          src.update(start, end, 'import.meta.filename');
-          break;
-        case '__dirname':
-          src.update(start, end, 'import.meta.dirname');
-          break;
-      }
+        }
+        break;
     }
   }
 };

package/dist/cjs/formatters/memberExpression.cjs

@@ -4,16 +4,18 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.memberExpression = void 0;
-const memberExpression = (nodePath, src, options) => {
-  if (options.type === 'module') {
-    const {
-      node
-    } = nodePath;
-    const {
-      start,
-      end
-    } = node;
-    if (typeof start === 'number' && typeof end === 'number' && node.object.type === 'Identifier' && node.object.name === 'require' && node.property.type === 'Identifier') {
+var _utils = require("../utils.cjs");
+const memberExpression = (node, parent, src, options) => {
+  if (options.target === 'module') {
+    if (node.object.type === 'Identifier' && node.property.type === 'Identifier' && node.object.name === 'module' && node.property.name === 'exports') {
+      src.update(node.start, node.end, _utils.exportsRename);
+      return;
+    }
+    if (node.object.type === 'Identifier' && node.property.type === 'Identifier' && node.object.name === 'require') {
+      const {
+        start,
+        end
+      } = node;
       const {
         name
       } = node.property;
@@ -21,7 +23,18 @@ const memberExpression = (nodePath, src, options) => {
       // CommonJS properties of `require`
       switch (name) {
         case 'main':
-          src.update(start, end, 'import.meta');
+          /**
+           * Node.js team still quibbling over import.meta.main ¯\_(ツ)_/¯
+           * @see https://github.com/nodejs/node/pull/32223
+           */
+          if (parent?.type === 'ExpressionStatement') {
+            // This is a standalone expression so remove it to not cause run-time errors.
+            src.remove(start, end);
+          }
+          /**
+           * Transform require.main === module.
+           */
+          if (parent?.type === 'BinaryExpression') {}
           break;
         case 'resolve':
           src.update(start, end, 'import.meta.resolve');

package/dist/cjs/formatters/metaProperty.cjs

@@ -4,45 +4,33 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.metaProperty = void 0;
-const metaProperty = (nodePath, src, options) => {
-  if (options.type === 'commonjs') {
-    const path = nodePath.findParent(path => path.isMemberExpression());
-    if (path) {
-      const {
-        node
-      } = path;
-      const {
-        start,
-        end
-      } = node;
-      if (node.type === 'MemberExpression' && node.property.type === 'Identifier' && typeof start == 'number' && typeof end === 'number') {
-        const name = node.property.name;
-        switch (name) {
-          case 'url':
-            src.update(start, end, 'require("node:url").pathToFileURL(__filename).toString()');
-            break;
-          case 'filename':
-            src.update(start, end, '__filename');
-            break;
-          case 'dirname':
-            src.update(start, end, '__dirname');
-            break;
-          case 'resolve':
-            src.update(start, end, 'require.resolve');
-            break;
-        }
-      }
-    } else {
-      const {
-        node
-      } = nodePath;
+const metaProperty = (node, parent, src, options) => {
+  if (options.target === 'commonjs') {
+    if (parent?.type !== 'MemberExpression') {
+      // This is a bare `import.meta` expression
       const {
         start,
         end
       } = node;
-      if (node.property.type === 'Identifier' && node.property.name === 'meta' && typeof start === 'number' && typeof end === 'number') {
-        // This is an `import.meta` expression
-        src.update(start, end, 'require.main');
+      src.update(start, end, 'module');
+    }
+    if (parent?.type === 'MemberExpression' && parent.property.type === 'Identifier') {
+      switch (parent.property.name) {
+        case 'url':
+          src.update(parent.start, parent.end, 'require("node:url").pathToFileURL(__filename).href');
+          break;
+        case 'filename':
+          src.update(parent.start, parent.end, '__filename');
+          break;
+        case 'dirname':
+          src.update(parent.start, parent.end, '__dirname');
+          break;
+        case 'resolve':
+          /**
+           * Should this be `require('node:url').pathToFileURL(require.resolve(<parsed specifier>)).href`?
+           */
+          src.update(parent.start, parent.end, 'require.resolve');
+          break;
       }
     }
   }