@knighted/module 1.0.0-rc.5 → 1.0.0

package/README.md

@@ -11,14 +11,16 @@ Node.js utility for transforming a JavaScript or TypeScript file from an ES modu
 
 Highlights
 
+- ESM ➡️ CJS and CJS ➡️ ESM with one function call.
 - Defaults to safe CommonJS output: strict live bindings, import.meta shims, and specifier preservation.
-- Opt into stricter/looser behaviors: live binding enforcement, import.meta.main gating, and top-level await strategies.
-- Can optionally rewrite relative specifiers and write transformed output to disk.
+- Configurable lowering modes: full syntax transforms or globals-only.
+- Specifier tools: add extensions, add directory indexes, or map with a custom callback.
+- Output control: write to disk (`out`/`inPlace`) or return the transformed string.
 
 > [!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).
 
-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.
+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 (full vs globals-only), specifier updates, and output.
 
 ## Requirements
 
@@ -30,9 +32,9 @@ By default `@knighted/module` transforms the one-to-one [differences between ES
 npm install @knighted/module
 ```
 
-## Example
+## Quick examples
 
-Given an ES module:
+ESM ➡️ CJS:
 
 **file.js**
 
@@ -93,13 +95,24 @@ use@computer: $ node file.cjs
 invoked directly by node
 ```
 
+CJS ➡️ ESM:
+
+```js
+import { transform } from '@knighted/module'
+
+await transform('./file.cjs', {
+  target: 'module',
+  out: './file.mjs',
+})
+```
+
 ## Options
 
 ```ts
 type ModuleOptions = {
   target: 'module' | 'commonjs'
   sourceType?: 'auto' | 'module' | 'commonjs'
-  transformSyntax?: boolean
+  transformSyntax?: boolean | 'globals-only'
   liveBindings?: 'strict' | 'loose' | 'off'
   appendJsExtension?: 'off' | 'relative-only' | 'all'
   appendDirectoryIndex?: string | false
@@ -124,20 +137,21 @@ type ModuleOptions = {
 }
 ```
 
-Behavior notes (defaults in parentheses)
+### Behavior notes (defaults in parentheses)
 
 - `target` (`commonjs`): output module system.
-- `transformSyntax` (true): enable/disable the ESM↔CJS lowering pass.
+- `transformSyntax` (true): enable/disable the ESM↔CJS lowering pass; set to `'globals-only'` to rewrite module globals (`import.meta.*`, `__dirname`, `__filename`, `require.main` shims) while leaving import/export syntax untouched. In `'globals-only'`, no helpers are injected (e.g., `__requireResolve`), `require.resolve` rewrites to `import.meta.resolve`, and `idiomaticExports` is skipped. See [globals-only](#globals-only-scope).
 - `liveBindings` (`strict`): getter-based live bindings, or snapshot (`loose`/`off`).
 - `appendJsExtension` (`relative-only` when targeting ESM): append `.js` to relative specifiers; never touches bare specifiers.
 - `appendDirectoryIndex` (`index.js`): when a relative specifier ends with a slash, append this index filename (set `false` to disable).
+- `appenders` precedence: `rewriteSpecifier` runs first; if it returns a string, that result is used. If it returns `undefined` or `null`, `appendJsExtension` and `appendDirectoryIndex` still run. Bare specifiers are never modified by appenders.
 - `dirFilename` (`inject`): inject `__dirname`/`__filename`, preserve existing, or throw.
 - `importMeta` (`shim`): rewrite `import.meta.*` to CommonJS equivalents.
 - `importMetaMain` (`shim`): gate `import.meta.main` with shimming/warning/error when Node support is too old.
 - `requireMainStrategy` (`import-meta-main`): use `import.meta.main` or the realpath-based `pathToFileURL(realpathSync(process.argv[1])).href` check.
 - `detectCircularRequires` (`off`): optionally detect relative static require cycles and warn/throw.
 - `topLevelAwait` (`error`): throw, wrap, or preserve when TLA appears in CommonJS output.
-- `rewriteSpecifier` (off): rewrite relative specifiers to a chosen extension or via a callback.
+- `rewriteSpecifier` (off): rewrite relative specifiers to a chosen extension or via a callback. Precedence: the callback (if provided) runs first; if it returns a string, that wins. If it returns `undefined` or `null`, the appenders still apply.
 - `requireSource` (`builtin`): whether `require` comes from Node or `createRequire`.
 - `cjsDefault` (`auto`): bundler-style default interop vs direct `module.exports`.
 - `out`/`inPlace`: write the transformed code to a file; otherwise the function returns the transformed string only.
@@ -151,6 +165,13 @@ See [docs/esm-to-cjs.md](docs/esm-to-cjs.md) for deeper notes on live bindings,
 > [!NOTE]
 > Known limitations: `with` and unshadowed `eval` are rejected when raising CJS to ESM because the rewrite would be unsound; bare specifiers are not rewritten—only relative specifiers participate in `rewriteSpecifier`.
 
+### Globals-only scope
+
+- Rewrites module globals (`import.meta.*`, `__dirname`, `__filename`, `require.main` shims) for the target side.
+- Optional specifier rewrites still run (`rewriteSpecifier`, `appendJsExtension`, `appendDirectoryIndex`).
+- Leaves imports/exports and interop untouched (no export bag, no idiomaticExports, no live-binding synthesis, no helpers like `__requireResolve`).
+- CJS→ESM: `require.resolve` maps to `import.meta.resolve` (URL return, ESM resolver) and may differ from CJS resolution. ESM→CJS: `import.meta` maps to CJS globals; no import lowering.
+
 ### Diagnostics callback example
 
 Pass a `diagnostics` callback to surface CJS→ESM edge cases (mixed `module.exports`/`exports`, top-level `return`, legacy `require.cache`/`require.extensions`, live-binding reassignments, string-literal export names):
@@ -183,7 +204,7 @@ console.log(diagnostics)
 
 ## Pre-`tsc` transforms for TypeScript diagnostics
 
-TypeScript reports asymmetric module-global errors (e.g., `import.meta` in CJS, `__dirname` in ESM) as tracked in [microsoft/TypeScript#58658](https://github.com/microsoft/TypeScript/issues/58658). You can mitigate this by running `@knighted/module` **before** `tsc` so the checker sees already-rewritten sources.
+TypeScript reports asymmetric module-global errors (e.g., `import.meta` in CJS, `__dirname` in ESM) as tracked in [microsoft/TypeScript#58658](https://github.com/microsoft/TypeScript/issues/58658). You can mitigate this by running `@knighted/module` **before** `tsc` so the checker sees already-rewritten sources. For a specifier + globals-only pass that leaves import/export syntax for `tsc`, set `transformSyntax: 'globals-only'`.
 
 Minimal flow:
 

package/dist/cjs/format.cjs

@@ -16,6 +16,36 @@ var _identifier2 = require("#helpers/identifier.js");
 var _walk = require("#walk");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const isValidIdent = name => /^[$A-Z_a-z][$\w]*$/.test(name);
+const expressionHasRequireCall = (node, shadowed) => {
+  let found = false;
+  const walkNode = n => {
+    if (!n || found) return;
+    if (n.type === 'CallExpression' && n.callee?.type === 'Identifier' && n.callee.name === 'require' && !shadowed.has('require')) {
+      found = true;
+      return;
+    }
+    if (n.type === 'CallExpression' && n.callee?.type === 'MemberExpression' && n.callee.object?.type === 'Identifier' && n.callee.object.name === 'require' && !shadowed.has('require')) {
+      found = true;
+      return;
+    }
+    const keys = Object.keys(n);
+    for (const key of keys) {
+      const value = n[key];
+      if (!value) continue;
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (item && typeof item === 'object') walkNode(item);
+          if (found) return;
+        }
+      } else if (value && typeof value === 'object') {
+        walkNode(value);
+        if (found) return;
+      }
+    }
+  };
+  walkNode(node);
+  return found;
+};
 const exportAssignment = (name, expr, live) => {
   const prop = isValidIdent(name) ? `.${name}` : `[${JSON.stringify(name)}]`;
   if (live === 'strict') {
@@ -397,14 +427,20 @@ const format = async (src, ast, opts) => {
       loc
     });
   };
+  const transformMode = opts.transformSyntax;
+  const fullTransform = transformMode === true;
   const moduleIdentifiers = await (0, _identifiers.collectModuleIdentifiers)(ast.program);
   const shadowedBindings = new Set([...moduleIdentifiers.entries()].filter(([, meta]) => meta.declare.length > 0).map(([name]) => name));
-  if (opts.target === 'module' && opts.transformSyntax) {
+  if (opts.target === 'module' && fullTransform) {
     if (shadowedBindings.has('module') || shadowedBindings.has('exports')) {
       throw new Error('Cannot transform to ESM: module or exports is shadowed in module scope.');
     }
   }
   const exportTable = opts.target === 'module' ? await (0, _exports.collectCjsExports)(ast.program) : null;
+  const idiomaticMode = opts.target === 'module' && fullTransform ? opts.idiomaticExports ?? 'safe' : 'off';
+  let useExportsBag = fullTransform;
+  let idiomaticPlan = null;
+  let idiomaticFallbackReason;
   if (opts.target === 'module' && exportTable) {
     const hasExportsVia = [...exportTable.values()].some(entry => entry.via.has('exports'));
     const hasModuleExportsVia = [...exportTable.values()].some(entry => entry.via.has('module.exports'));
@@ -416,15 +452,163 @@ const format = async (src, ast, opts) => {
         end: firstExports?.end ?? 0
       });
     }
+    const reservedExports = new Set(['await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'implements', 'import', 'in', 'instanceof', 'interface', 'let', 'new', 'null', 'package', 'private', 'protected', 'public', 'return', 'static', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'yield']);
+    const isValidExportName = name => /^[$A-Z_a-z][$\w]*$/.test(name) && !reservedExports.has(name);
+    const isAllowedRhs = node => {
+      return node.type === 'Identifier' || node.type === 'Literal' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression' || node.type === 'ClassExpression';
+    };
+    const buildIdiomaticPlan = () => {
+      if (idiomaticMode === 'off') return {
+        ok: false,
+        reason: 'disabled'
+      };
+      const entries = [...exportTable.values()];
+      if (!entries.length) return {
+        ok: false,
+        reason: 'no-exports'
+      };
+      if (exportTable.hasUnsupportedExportWrite) {
+        return {
+          ok: false,
+          reason: 'unsupported-left'
+        };
+      }
+      const viaSet = new Set();
+      for (const entry of entries) {
+        entry.via.forEach(v => viaSet.add(v));
+        if (entry.hasGetter) return {
+          ok: false,
+          reason: 'getter-present'
+        };
+        if (entry.reassignments.length) return {
+          ok: false,
+          reason: 'reassignment'
+        };
+        if (entry.hasNonTopLevelWrite) return {
+          ok: false,
+          reason: 'non-top-level'
+        };
+        if (entry.writes.length !== 1) return {
+          ok: false,
+          reason: 'multiple-writes'
+        };
+        if (!isValidExportName(entry.key)) return {
+          ok: false,
+          reason: 'non-identifier-key'
+        };
+      }
+      if (viaSet.size > 1) return {
+        ok: false,
+        reason: 'mixed-exports'
+      };
+      const replacements = [];
+      const exportsOut = [];
+      const seen = new Set();
+      const requireShadowed = shadowedBindings;
+      const rhsSourceFor = node => {
+        const raw = code.slice(node.start, node.end);
+        return raw.replace(/\b__dirname\b/g, 'import.meta.dirname').replace(/\b__filename\b/g, 'import.meta.filename');
+      };
+      for (const entry of entries) {
+        const write = entry.writes[0];
+        if (write.type !== 'AssignmentExpression') {
+          return {
+            ok: false,
+            reason: 'unsupported-write-kind'
+          };
+        }
+        const left = write.left;
+        if (left.type !== 'MemberExpression' || left.computed || left.property.type !== 'Identifier') {
+          return {
+            ok: false,
+            reason: 'unsupported-left'
+          };
+        }
+        const base = left.object;
+        const propName = left.property.name;
+        const baseIsExports = base.type === 'Identifier' && base.name === 'exports';
+        const baseIsModuleExports = base.type === 'MemberExpression' && base.object.type === 'Identifier' && base.object.name === 'module' && base.property.type === 'Identifier' && base.property.name === 'exports';
+        if (!baseIsExports && !baseIsModuleExports) {
+          return {
+            ok: false,
+            reason: 'unsupported-base'
+          };
+        }
+        const rhs = write.right;
+        if (!isAllowedRhs(rhs)) return {
+          ok: false,
+          reason: 'unsupported-rhs'
+        };
+        if (expressionHasRequireCall(rhs, requireShadowed)) {
+          return {
+            ok: false,
+            reason: 'rhs-require'
+          };
+        }
+        const rhsSrc = rhsSourceFor(rhs);
+        if (propName === 'exports' && baseIsModuleExports) {
+          // module.exports = ... handles default
+          if (seen.has('default')) return {
+            ok: false,
+            reason: 'duplicate-default'
+          };
+          seen.add('default');
+          exportsOut.push(`export default ${rhsSrc};`);
+        } else {
+          if (seen.has(propName)) return {
+            ok: false,
+            reason: 'duplicate-key'
+          };
+          seen.add(propName);
+          if (rhs.type === 'Identifier') {
+            const rhsId = rhsSourceFor(rhs);
+            if (rhsId === rhs.name) {
+              exportsOut.push(`export { ${rhsId} as ${propName} };`);
+            } else {
+              exportsOut.push(`export const ${propName} = ${rhsId};`);
+            }
+          } else {
+            exportsOut.push(`export const ${propName} = ${rhsSrc};`);
+          }
+        }
+        replacements.push({
+          start: write.start,
+          end: write.end
+        });
+      }
+      if (!seen.size) return {
+        ok: false,
+        reason: 'no-seen'
+      };
+      return {
+        ok: true,
+        plan: {
+          replacements,
+          exports: exportsOut
+        }
+      };
+    };
+    if (idiomaticMode !== 'off') {
+      const res = buildIdiomaticPlan();
+      if (res.ok && res.plan) {
+        useExportsBag = false;
+        idiomaticPlan = res.plan;
+      } else if (res.reason) {
+        idiomaticFallbackReason = res.reason;
+      }
+    }
   }
-  const shouldCheckTopLevelAwait = opts.target === 'commonjs' && opts.transformSyntax;
+  const shouldCheckTopLevelAwait = opts.target === 'commonjs' && fullTransform;
   const containsTopLevelAwait = shouldCheckTopLevelAwait ? hasTopLevelAwait(ast.program) : false;
+  if (idiomaticFallbackReason && idiomaticMode !== 'off') {
+    warnOnce('idiomatic-exports-fallback', `Idiomatic exports disabled for this file: ${idiomaticFallbackReason}. Falling back to helper exports.`);
+  }
   const requireMainStrategy = opts.requireMainStrategy ?? 'import-meta-main';
   let requireMainNeedsRealpath = false;
   let needsRequireResolveHelper = false;
   const nestedRequireStrategy = opts.nestedRequireStrategy ?? 'create-require';
-  const shouldLowerCjs = opts.target === 'commonjs' && opts.transformSyntax;
-  const shouldRaiseEsm = opts.target === 'module' && opts.transformSyntax;
+  const shouldLowerCjs = opts.target === 'commonjs' && fullTransform;
+  const shouldRaiseEsm = opts.target === 'module' && fullTransform;
   let hoistedImports = [];
   let hoistedStatements = [];
   let pendingRequireTransforms = [];
@@ -574,7 +758,7 @@ const format = async (src, ast, opts) => {
           onDiagnostic: (codeId, message, loc) => {
             if (shouldRaiseEsm) warnOnce(codeId, message, loc);
           }
-        });
+        }, useExportsBag, fullTransform);
       }
       if (shouldRaiseEsm && node.type === 'ThisExpression') {
         const bindsThis = ancestor => {
@@ -594,7 +778,8 @@ const format = async (src, ast, opts) => {
           code,
           opts,
           meta: exportsMeta,
-          shadowed: shadowedBindings
+          shadowed: shadowedBindings,
+          useExportsBag
         });
       }
     }
@@ -604,6 +789,20 @@ const format = async (src, ast, opts) => {
       code.overwrite(t.start, t.end, t.code);
     }
   }
+  if (!useExportsBag && idiomaticPlan) {
+    if (idiomaticPlan.exports.length === idiomaticPlan.replacements.length) {
+      idiomaticPlan.replacements.forEach((rep, idx) => {
+        code.overwrite(rep.start, rep.end, idiomaticPlan.exports[idx]);
+      });
+    } else {
+      for (const rep of idiomaticPlan.replacements) {
+        code.overwrite(rep.start, rep.end, ';');
+      }
+      if (idiomaticPlan.exports.length) {
+        code.append(`\n${idiomaticPlan.exports.join('\n')}\n`);
+      }
+    }
+  }
   if (shouldLowerCjs) {
     const {
       importTransforms,
@@ -623,7 +822,7 @@ const format = async (src, ast, opts) => {
       code.prepend(`${interopHelper}exports.__esModule = true;\n`);
     }
   }
-  if (opts.target === 'module' && opts.transformSyntax && exportTable) {
+  if (useExportsBag && opts.target === 'module' && fullTransform && exportTable) {
     const isValidExportName = name => /^[$A-Z_a-z][$\w]*$/.test(name);
     const asExportName = name => isValidExportName(name) ? name : JSON.stringify(name);
     const accessProp = name => isValidExportName(name) ? `${_exports.exportsRename}.${name}` : `${_exports.exportsRename}[${JSON.stringify(name)}]`;
@@ -683,7 +882,7 @@ const format = async (src, ast, opts) => {
       code.append(`\n${lines.join('\n')}\n`);
     }
   }
-  if (shouldRaiseEsm && opts.transformSyntax) {
+  if (shouldRaiseEsm && fullTransform) {
     const importPrelude = [];
     if (needsCreateRequire || needsRequireResolveHelper) {
       importPrelude.push('import { createRequire } from "node:module";\n');
@@ -714,12 +913,14 @@ const format = async (src, ast, opts) => {
   const resolved = req.resolve(id, parent);
   return resolved.startsWith("file://") ? fileURLToPath(resolved) : resolved;
 };\n` : '';
-    const prelude = `${importPrelude.join('')}${importPrelude.length ? '\n' : ''}${setupPrelude.join('')}${setupPrelude.length ? '\n' : ''}${requireInit}${requireResolveInit}let ${_exports.exportsRename} = {};
-void import.meta.filename;
+    const exportsBagInit = useExportsBag ? `let ${_exports.exportsRename} = {};
+` : '';
+    const modulePrelude = '';
+    const prelude = `${importPrelude.join('')}${importPrelude.length ? '\n' : ''}${setupPrelude.join('')}${setupPrelude.length ? '\n' : ''}${requireInit}${requireResolveInit}${exportsBagInit}${modulePrelude}void import.meta.filename;
 `;
     code.prepend(prelude);
   }
-  if (opts.target === 'commonjs' && opts.transformSyntax && containsTopLevelAwait) {
+  if (opts.target === 'commonjs' && fullTransform && containsTopLevelAwait) {
     const body = code.toString();
     if (opts.topLevelAwait === 'wrap') {
       const tlaPromise = `const __tla = (async () => {\n${body}\nreturn module.exports;\n})();\n`;

package/dist/cjs/formatters/identifier.cjs

@@ -12,7 +12,8 @@ const identifier = ({
   code,
   opts,
   meta,
-  shadowed
+  shadowed,
+  useExportsBag = true
 }) => {
   if (opts.target === 'module') {
     const {
@@ -33,7 +34,7 @@ const identifier = ({
       case 'exports':
         {
           const parent = ancestors[ancestors.length - 2];
-          if (opts.transformSyntax) {
+          if (opts.transformSyntax && useExportsBag) {
             if (parent.type === 'AssignmentExpression' && parent.left === node) {
               // The code is reassigning `exports` to something else.
 

package/dist/cjs/formatters/memberExpression.cjs

@@ -5,15 +5,33 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.memberExpression = void 0;
 var _exports = require("#utils/exports.js");
-const memberExpression = (node, parent, src, options, shadowed, extras) => {
+const memberExpression = (node, parent, src, options, shadowed, extras, useExportsBag = true, rewriteExports = true) => {
   if (options.target === 'module') {
-    if (node.object.type === 'Identifier' && shadowed?.has(node.object.name) || node.property.type === 'Identifier' && shadowed?.has(node.property.name)) {
-      return;
+    if (rewriteExports && !useExportsBag) {
+      if (parent?.type === 'MemberExpression' && parent.object === node && parent.property.type === 'Identifier') {
+        const baseIsExportsIdent = node.object.type === 'Identifier' && node.object.name === 'exports';
+        const baseIsModuleExports = node.object.type === 'Identifier' && node.object.name === 'module' && node.property.type === 'Identifier' && node.property.name === 'exports';
+        if (baseIsExportsIdent || baseIsModuleExports) {
+          src.update(parent.start, parent.end, parent.property.name);
+          return;
+        }
+      }
+      if (node.object.type === 'Identifier' && node.property.type === 'Identifier' && node.object.name === 'module' && node.property.name === 'exports') {
+        src.update(node.start, node.end, 'undefined');
+        return;
+      }
     }
-    if (node.object.type === 'Identifier' && node.property.type === 'Identifier' && node.object.name === 'module' && node.property.name === 'exports') {
-      src.update(node.start, node.end, _exports.exportsRename);
+    if (rewriteExports && (node.object.type === 'Identifier' && shadowed?.has(node.object.name) || node.property.type === 'Identifier' && shadowed?.has(node.property.name))) {
       return;
     }
+    if (rewriteExports) {
+      if (node.object.type === 'Identifier' && node.property.type === 'Identifier' && node.object.name === 'module' && node.property.name === 'exports') {
+        if (useExportsBag) {
+          src.update(node.start, node.end, _exports.exportsRename);
+        }
+        return;
+      }
+    }
     if (node.object.type === 'Identifier' && node.property.type === 'Identifier' && node.object.name === 'require') {
       const {
         start,
@@ -32,6 +50,10 @@ const memberExpression = (node, parent, src, options, shadowed, extras) => {
           src.update(start, end, 'import.meta.main');
           break;
         case 'resolve':
+          if (options.transformSyntax !== true) {
+            src.update(start, end, 'import.meta.resolve');
+            return;
+          }
           extras?.onRequireResolve?.();
           src.update(start, end, extras?.requireResolveName ?? 'import.meta.resolve');
           break;

package/dist/cjs/memberExpression.d.cts

@@ -9,5 +9,5 @@ type MemberExpressionExtras = {
         end: number;
     }) => void;
 };
-export declare const memberExpression: (node: MemberExpression, parent: Node | null, src: MagicString, options: FormatterOptions, shadowed?: Set<string>, extras?: MemberExpressionExtras) => void;
+export declare const memberExpression: (node: MemberExpression, parent: Node | null, src: MagicString, options: FormatterOptions, shadowed?: Set<string>, extras?: MemberExpressionExtras, useExportsBag?: boolean, rewriteExports?: boolean) => void;
 export {};

package/dist/cjs/module.cjs

@@ -47,7 +47,7 @@ const rewriteSpecifierValue = (value, rewriteSpecifier) => {
   const collapsed = collapseSpecifier(value);
   const relative = /^(?:\.\.?)\//;
   if (relative.test(collapsed)) {
-    return value.replace(/(.+)\.(?:m|c)?(?:j|t)s([)'"]*)?$/, `$1${rewriteSpecifier}$2`);
+    return value.replace(/(.+)\.(?:m|c)?(?:j|t)sx?([)'"]*)?$/, `$1${rewriteSpecifier}$2`);
   }
 };
 const normalizeBuiltinSpecifier = value => {
@@ -160,6 +160,7 @@ const defaultOptions = {
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
+  idiomaticExports: 'safe',
   topLevelAwait: 'error',
   out: undefined,
   inPlace: false

package/dist/cjs/specifier.cjs

@@ -118,6 +118,9 @@ const formatSpecifiers = async (src, ast, cb) => {
   };
   await (0, _walk.walk)(ast.program, {
     enter(node) {
+      if (node.type === 'ImportExpression') {
+        formatExpression(node);
+      }
       if (node.type === 'ExpressionStatement') {
         const {
           expression

package/dist/cjs/types.d.cts

@@ -6,8 +6,13 @@ export type ModuleOptions = {
     target: 'module' | 'commonjs';
     /** Explicit source type; auto infers from file extension. */
     sourceType?: 'auto' | 'module' | 'commonjs';
-    /** Enable syntax transforms beyond parsing. */
-    transformSyntax?: boolean;
+    /**
+     * Enable syntax transforms beyond parsing.
+     * - true: full CJS↔ESM lowering/raising
+     * - 'globals-only': rewrite module-global differences (import.meta, __dirname/filename, require.main shims) while leaving import/export shapes untouched
+     * - false/undefined: no syntax transforms
+     */
+    transformSyntax?: boolean | 'globals-only';
     /** How to emit live bindings for ESM exports. */
     liveBindings?: 'strict' | 'loose' | 'off';
     /** Rewrite import specifiers (e.g. add extensions). */
@@ -16,7 +21,8 @@ export type ModuleOptions = {
     appendJsExtension?: 'off' | 'relative-only' | 'all';
     /** Add directory index (e.g. /index.js) or disable. */
     appendDirectoryIndex?: string | false;
-    /** Control __dirname and __filename handling. */
+    /** Precedence: rewriteSpecifier runs first; if it returns a string that wins. If it returns undefined or null, appenders apply. Bare specifiers are never modified by appenders. */
+    /** Control __dirname/__filename handling (inject shims, preserve existing, or throw on use). */
     dirFilename?: 'inject' | 'preserve' | 'error';
     /** How to treat import.meta. */
     importMeta?: 'preserve' | 'shim' | 'error';
@@ -32,6 +38,8 @@ export type ModuleOptions = {
     nestedRequireStrategy?: 'create-require' | 'dynamic-import';
     /** Default interop style for CommonJS default imports. */
     cjsDefault?: 'module-exports' | 'auto' | 'none';
+    /** Emit idiomatic exports when raising CJS to ESM. */
+    idiomaticExports?: 'off' | 'safe' | 'aggressive';
     /** Handling for top-level await constructs. */
     topLevelAwait?: 'error' | 'wrap' | 'preserve';
     /** Optional diagnostics sink for warnings/errors emitted during transform. */
@@ -67,6 +75,7 @@ export type CjsExport = {
     via: Set<'exports' | 'module.exports'>;
     reassignments: SpannedNode[];
     hasGetter?: boolean;
+    hasNonTopLevelWrite?: boolean;
 };
 export type IdentMeta = {
     declare: SpannedNode[];

package/dist/cjs/utils/exports.cjs

@@ -69,6 +69,12 @@ const collectCjsExports = async ast => {
   const localToExport = new Map();
   const aliases = new Map();
   const literals = new Map();
+  let hasUnsupportedExportWrite = false;
+  const isTopLevelWrite = ancestors => {
+    const parent = ancestors[ancestors.length - 2];
+    const grandparent = ancestors[ancestors.length - 3];
+    return grandparent?.type === 'Program' && (parent?.type === 'ExpressionStatement' || parent?.type === 'VariableDeclaration');
+  };
   const addExport = (ref, node, rhs, options) => {
     const entry = exportsMap.get(ref.key) ?? {
       key: ref.key,
@@ -81,6 +87,9 @@ const collectCjsExports = async ast => {
     if (options?.hasGetter) {
       entry.hasGetter = true;
     }
+    if (options?.topLevel === false) {
+      entry.hasNonTopLevelWrite = true;
+    }
     if (rhs) {
       entry.fromIdentifier ??= rhs.name;
       const set = localToExport.get(rhs.name) ?? new Set();
@@ -110,9 +119,15 @@ const collectCjsExports = async ast => {
         const target = resolveExportTarget(node.left, aliases, literals, ancestors);
         if (target) {
           const rhsIdent = node.right.type === 'Identifier' ? node.right : undefined;
-          addExport(target, node, rhsIdent);
+          const topLevel = isTopLevelWrite(ancestors);
+          addExport(target, node, rhsIdent, {
+            topLevel
+          });
           return;
         }
+        if (node.left.type === 'MemberExpression' && resolveBase(node.left.object, aliases, ancestors)) {
+          hasUnsupportedExportWrite = true;
+        }
         if (node.left.type === 'Identifier') {
           const keys = localToExport.get(node.left.name);
           if (keys) {
@@ -129,7 +144,12 @@ const collectCjsExports = async ast => {
           const findExportRefs = pattern => {
             if (pattern.type === 'MemberExpression') {
               const ref = resolveExportTarget(pattern, aliases, literals, ancestors);
-              if (ref) addExport(ref, node);
+              if (ref) {
+                const topLevel = isTopLevelWrite(ancestors);
+                addExport(ref, node, undefined, {
+                  topLevel
+                });
+              }
               return;
             }
             if (pattern.type === 'ObjectPattern') {
@@ -171,10 +191,13 @@ const collectCjsExports = async ast => {
                 if (prop.value.type === 'Identifier') {
                   rhsIdent = prop.value;
                 }
+                const topLevel = isTopLevelWrite(ancestors);
                 addExport({
                   key: keyName,
                   via: ref
-                }, node, rhsIdent);
+                }, node, rhsIdent, {
+                  topLevel
+                });
               }
             }
           }
@@ -203,11 +226,13 @@ const collectCjsExports = async ast => {
               // Setter-only doesn’t create a readable export; ignore beyond marking write
             }
           }
+          const topLevel = isTopLevelWrite(ancestors);
           addExport({
             key: keyName,
             via: target
           }, node, rhsIdent, {
-            hasGetter
+            hasGetter,
+            topLevel
           });
         }
 
@@ -234,17 +259,20 @@ const collectCjsExports = async ast => {
                 hasGetter = true;
               }
             }
+            const topLevel = isTopLevelWrite(ancestors);
             addExport({
               key: keyName,
               via: target
             }, node, rhsIdent, {
-              hasGetter
+              hasGetter,
+              topLevel
             });
           }
         }
       }
     }
   });
+  exportsMap.hasUnsupportedExportWrite = hasUnsupportedExportWrite;
   return exportsMap;
 };
 exports.collectCjsExports = collectCjsExports;