feat: basic esm to cjs lowering.

Author: knightedcodemonkey

docs/esm-to-cjs.md

@@ -0,0 +1,39 @@
+# ESM to CommonJS lowering
+
+## Scope
+
+- Translates ESM syntax to CommonJS when `target: 'commonjs'` with `transformSyntax` enabled.
+- Assumes Node 20.11+ runtime with `__filename`/`__dirname` shims supplied by the host.
+- Keeps optional live-binding behavior via `liveBindings` (strict/loose/off).
+
+## Imports and interop
+
+- `import` statements become `require` calls; side-effect imports become bare `require()` calls.
+- Default imports use the bundler-style helper `__interopDefault = mod => (mod && mod.__esModule ? mod.default : mod)` when `cjsDefault: 'auto'`; otherwise they can target `module.exports` or `.default` directly per option.
+- Namespace imports bind to the full `require` result; named imports destructure from the same binding.
+- Re-exporting a default (`export { default as x } from`) routes through the interop helper to match bundler behavior for CJS sources.
+- When the interop helper is emitted, `exports.__esModule = true` is also seeded for downstream consumers.
+
+## Exports
+
+- Local named exports emit to `exports.<name>` (or bracket access) with `Object.defineProperty` getters when `liveBindings: 'strict'`.
+- `export default` writes to `module.exports = <expr>`; default functions/classes preserve their identifier before exporting.
+- `export * from` lowers to a `for...in` over the required module, skipping `default`, guarding on `hasOwnProperty`, and defining getters to mirror live bindings.
+- Named re-exports from another module (`export { foo as bar } from`) assign using either a direct property read or the interop helper for `default`.
+
+## import.meta rewriting
+
+- `import.meta.url` → `require("node:url").pathToFileURL(__filename).href`
+- `import.meta.filename` → `__filename`
+- `import.meta.dirname` → `__dirname`
+- `import.meta.resolve` → `require.resolve`
+- `import.meta.main` → `process.argv[1] === __filename`
+- Bare `import.meta` becomes `module` so property accesses stay valid in CJS output.
+
+## Fixtures for this phase
+
+- `test/fixtures/esmDefault.mjs`: default import from the CJS provider, re-exported as default for interop checks (default import yields the CJS module object).
+- `test/fixtures/esmNamed.mjs`: named import and aliasing from the CJS provider, re-exported for assertions.
+- `test/fixtures/esmNamespace.mjs`: namespace import shape from the CJS provider, re-exported as `ns`.
+- `test/fixtures/esmReexport.mjs`: named + star re-exports from the CJS provider (includes live binding passthrough).
+- `test/fixtures/esmProvider.cjs`: CJS source exposing default/named exports plus a mutating `live` counter for binding checks (interval is `unref()`ed; tests wait ≥30ms to observe changes).

src/format.ts

@@ -12,6 +12,286 @@ import { collectModuleIdentifiers } from '#utils/identifiers.js'
 import { isIdentifierName } from '#helpers/identifier.js'
 import { ancestorWalk } from '#walk'
 
+const isValidIdent = (name: string) => /^[$A-Z_a-z][$\w]*$/.test(name)
+
+const exportAssignment = (
+  name: string,
+  expr: string,
+  live: 'strict' | 'loose' | 'off',
+) => {
+  const prop = isValidIdent(name) ? `.${name}` : `[${JSON.stringify(name)}]`
+  if (live === 'strict') {
+    const key = JSON.stringify(name)
+    return `Object.defineProperty(exports, ${key}, { enumerable: true, get: () => ${expr} });`
+  }
+  return `exports${prop} = ${expr};`
+}
+
+const defaultInteropName = '__interopDefault'
+const interopHelper = `const ${defaultInteropName} = mod => (mod && mod.__esModule ? mod.default : mod);\n`
+
+const hasTopLevelAwait = (program: any) => {
+  let found = false
+
+  const walkNode = (node: any, inFunction: boolean) => {
+    if (found) return
+
+    switch (node.type) {
+      case 'FunctionDeclaration':
+      case 'FunctionExpression':
+      case 'ArrowFunctionExpression':
+      case 'ClassDeclaration':
+      case 'ClassExpression':
+        inFunction = true
+        break
+    }
+
+    if (!inFunction && node.type === 'AwaitExpression') {
+      found = true
+      return
+    }
+
+    const keys = Object.keys(node)
+    for (const key of keys) {
+      const value = (node as any)[key]
+      if (!value) continue
+
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (item && typeof item === 'object') {
+            walkNode(item, inFunction)
+            if (found) return
+          }
+        }
+      } else if (value && typeof value === 'object') {
+        walkNode(value, inFunction)
+        if (found) return
+      }
+    }
+  }
+
+  walkNode(program, false)
+  return found
+}
+
+const lowerEsmToCjs = (program: any, code: MagicString, opts: FormatterOptions) => {
+  const live = opts.liveBindings ?? 'strict'
+  const importTransforms: ImportTransform[] = []
+  const exportTransforms: ExportTransform[] = []
+  let needsInterop = false
+  let importIndex = 0
+
+  for (const node of program.body as any[]) {
+    if (node.type === 'ImportDeclaration') {
+      const srcLiteral = code.slice(node.source.start, node.source.end)
+      const specifiers = node.specifiers ?? []
+      const defaultSpec = specifiers.find((s: any) => s.type === 'ImportDefaultSpecifier')
+      const namespaceSpec = specifiers.find(
+        (s: any) => s.type === 'ImportNamespaceSpecifier',
+      )
+      const namedSpecs = specifiers.filter((s: any) => s.type === 'ImportSpecifier')
+
+      // Side-effect import
+      if (!specifiers.length) {
+        importTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `require(${srcLiteral});\n`,
+          needsInterop: false,
+        })
+        continue
+      }
+
+      const modIdent = `__mod${importIndex++}`
+      const lines: string[] = []
+
+      lines.push(`const ${modIdent} = require(${srcLiteral});`)
+
+      if (namespaceSpec) {
+        lines.push(`const ${namespaceSpec.local.name} = ${modIdent};`)
+      }
+
+      if (defaultSpec) {
+        let init = modIdent
+        switch (opts.cjsDefault) {
+          case 'module-exports':
+            init = modIdent
+            break
+          case 'none':
+            init = `${modIdent}.default`
+            break
+          case 'auto':
+          default:
+            init = `${defaultInteropName}(${modIdent})`
+            needsInterop = true
+            break
+        }
+        lines.push(`const ${defaultSpec.local.name} = ${init};`)
+      }
+
+      if (namedSpecs.length) {
+        const pairs = namedSpecs.map((s: any) => {
+          const imported = s.imported.name
+          const local = s.local.name
+          return imported === local ? imported : `${imported}: ${local}`
+        })
+        lines.push(`const { ${pairs.join(', ')} } = ${modIdent};`)
+      }
+
+      importTransforms.push({
+        start: node.start,
+        end: node.end,
+        code: `${lines.join('\n')}\n`,
+        needsInterop,
+      })
+    }
+
+    if (node.type === 'ExportNamedDeclaration') {
+      // Handle declaration exports
+      if (node.declaration) {
+        const decl = node.declaration
+        const declSrc = code.slice(decl.start, decl.end)
+        const exportedNames: string[] = []
+
+        if (decl.type === 'VariableDeclaration') {
+          for (const d of decl.declarations) {
+            if (d.id.type === 'Identifier') {
+              exportedNames.push(d.id.name)
+            }
+          }
+        } else if ((decl as any).id?.type === 'Identifier') {
+          exportedNames.push((decl as any).id.name)
+        }
+
+        const exportLines = exportedNames.map(name =>
+          exportAssignment(name, name, live as any),
+        )
+
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `${declSrc}\n${exportLines.join('\n')}\n`,
+        })
+        continue
+      }
+
+      // Handle re-export or local specifiers
+      if (node.specifiers?.length) {
+        if (node.source) {
+          const srcLiteral = code.slice(node.source.start, node.source.end)
+          const modIdent = `__mod${importIndex++}`
+          const lines = [`const ${modIdent} = require(${srcLiteral});`]
+
+          for (const spec of node.specifiers) {
+            if (spec.type !== 'ExportSpecifier') continue
+            const exported = spec.exported.name
+            const imported = spec.local.name
+
+            let rhs = `${modIdent}.${imported}`
+            if (imported === 'default') {
+              rhs = `${defaultInteropName}(${modIdent})`
+              needsInterop = true
+            }
+
+            lines.push(exportAssignment(exported, rhs, live as any))
+          }
+
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `${lines.join('\n')}\n`,
+            needsInterop,
+          })
+        } else {
+          const lines: string[] = []
+          for (const spec of node.specifiers) {
+            if (spec.type !== 'ExportSpecifier') continue
+            const exported = spec.exported.name
+            const local = spec.local.name
+            lines.push(exportAssignment(exported, local, live as any))
+          }
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `${lines.join('\n')}\n`,
+          })
+        }
+      }
+    }
+
+    if (node.type === 'ExportDefaultDeclaration') {
+      const decl = node.declaration
+      if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
+        if (decl.id?.name) {
+          const declSrc = code.slice(decl.start, decl.end)
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `${declSrc}\nmodule.exports = ${decl.id.name};\n`,
+          })
+        } else {
+          const declSrc = code.slice(decl.start, decl.end)
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `module.exports = ${declSrc};\n`,
+          })
+        }
+      } else {
+        const exprSrc = code.slice(decl.start, decl.end)
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `module.exports = ${exprSrc};\n`,
+        })
+      }
+    }
+
+    if (node.type === 'ExportAllDeclaration') {
+      const srcLiteral = code.slice(node.source.start, node.source.end)
+      if ((node as any).exported) {
+        const exported = (node as any).exported.name
+        const modIdent = `__mod${importIndex++}`
+        const lines = [
+          `const ${modIdent} = require(${srcLiteral});`,
+          exportAssignment(exported, modIdent, live as any),
+        ]
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `${lines.join('\n')}\n`,
+        })
+      } else {
+        const modIdent = `__mod${importIndex++}`
+        const lines = [`const ${modIdent} = require(${srcLiteral});`]
+        const loop = `for (const k in ${modIdent}) {\n  if (k === 'default') continue;\n  if (!Object.prototype.hasOwnProperty.call(${modIdent}, k)) continue;\n  Object.defineProperty(exports, k, { enumerable: true, get: () => ${modIdent}[k] });\n}`
+        lines.push(loop)
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `${lines.join('\n')}\n`,
+        })
+      }
+    }
+  }
+
+  return { importTransforms, exportTransforms, needsInterop }
+}
+
+type ImportTransform = {
+  start: number
+  end: number
+  code: string
+  needsInterop: boolean
+}
+
+type ExportTransform = {
+  start: number
+  end: number
+  code: string
+  needsInterop?: boolean
+}
+
 /**
  * Node added support for import.meta.main.
  * Added in: v24.2.0, v22.18.0
@@ -29,6 +309,33 @@ const format = async (src: string, ast: ParseResult, opts: FormatterOptions) =>
     opts.target === 'module' ? await collectCjsExports(ast.program) : null
   await collectModuleIdentifiers(ast.program)
 
+  if (opts.target === 'commonjs' && opts.transformSyntax) {
+    if (opts.topLevelAwait === 'error' && hasTopLevelAwait(ast.program)) {
+      throw new Error(
+        'Top-level await is not supported when targeting CommonJS (set topLevelAwait to "wrap" or "preserve" to override).',
+      )
+    }
+
+    const { importTransforms, exportTransforms, needsInterop } = lowerEsmToCjs(
+      ast.program,
+      code,
+      opts,
+    )
+
+    // Apply transforms in source order
+    const allTransforms = [...importTransforms, ...exportTransforms].sort(
+      (a, b) => a.start - b.start,
+    )
+
+    for (const t of allTransforms) {
+      code.overwrite(t.start, t.end, t.code)
+    }
+
+    if (needsInterop) {
+      code.prepend(`${interopHelper}exports.__esModule = true;\n`)
+    }
+  }
+
   if (opts.target === 'module' && opts.transformSyntax) {
     /**
      * Prepare ESM output by renaming `exports` to `__exports` and seeding an

src/formatters/metaProperty.ts

@@ -38,6 +38,9 @@ export const metaProperty = (
            */
           src.update(parent.start, parent.end, 'require.resolve')
           break
+        case 'main':
+          src.update(parent.start, parent.end, 'process.argv[1] === __filename')
+          break
       }
     }
   }

test/fixtures/esmDefault.mjs

@@ -0,0 +1,3 @@
+import foo from './esmProvider.cjs'
+
+export default foo

test/fixtures/esmNamed.mjs

@@ -0,0 +1,3 @@
+import { foo, bar as baz } from './esmProvider.cjs'
+
+export { foo, baz }

test/fixtures/esmNamespace.mjs

@@ -0,0 +1,3 @@
+import * as ns from './esmProvider.cjs'
+
+export { ns }