feat: cjs to esm exporting. (#16)

Author: knightedcodemonkey

codecov.yml

@@ -7,4 +7,4 @@ coverage:
     patch:
       default:
         target: 80.0
-        threshold: 5.0
+        threshold: 20

docs/cjs-exports.md

@@ -0,0 +1,27 @@
+# CommonJS export discovery
+
+## Supported patterns
+
+- `module.exports = value` → captured as default; if assigned an identifier, we re-use it, otherwise we export the `__exports` bag. Overwrite-then-augment flows like `module.exports = fn; module.exports.extra = 1` are supported.
+- Property writes: `exports.foo = x`, `module.exports.bar = y`, and computed literals like `exports['foo']`, `exports[42]`, `module.exports[`template`]`.
+- Aliases to the export bag: `const e = exports; e.foo = 1`, `const m = module.exports; m.bar = 2` (alias chains are tracked).
+- Destructuring to properties: `({ value: exports.foo } = obj)`.
+- `Object.assign(exports, { foo, bar: baz })` and `Object.assign(module.exports, { ... })` with literal keys.
+- `Object.defineProperty` / `Object.defineProperties` on exports/module.exports (aliases included) with literal keys; value and getter descriptors are collected. Getter-based exports are emitted via a proxy read (best-effort, not true ESM live bindings).
+
+## Ignored or intentionally excluded
+
+- Non-literal computed keys (e.g., `exports[key()] = x`) are ignored for static export emission; they may still exist on the runtime bag but no ESM binding is generated.
+- Symbol keys on exports/module.exports are ignored.
+- Patterns that do not resolve to `exports`/`module.exports` or aliases are ignored.
+
+## Emission rules
+
+- We rename the CJS surface to `__exports` and emit ESM bindings from the collected table.
+- Default export: `module.exports = id` emits `export default id`; otherwise `export default __exports`.
+- Named exports reuse identifiers when available; otherwise we create a temporary binding that reads from `__exports` (using bracket access for non-identifier names).
+
+## Testing strategy
+
+- Fixtures cover each supported pattern: computed literals, alias chains, destructuring, Object.assign fan-out, overwrite-then-augment sequences, and defineProperty/defineProperties (value + getter). Dynamic non-literal keys have a fixture to verify they remain un-exported.
+- Each transformed fixture is executed with Node before assertions to catch runtime/syntax issues, then its exports are asserted via ESM import.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/module",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.1",
   "description": "Transforms differences between ES modules and CommonJS.",
   "type": "module",
   "main": "dist/module.js",
@@ -21,10 +21,10 @@
   "imports": {
     "#parse": "./src/parse.js",
     "#format": "./src/format.js",
-    "#utils": "./src/utils.js",
+    "#utils/*.js": "./src/utils/*.js",
     "#walk": "./src/walk.js",
-    "#helpers/*": "./src/helpers/*.js",
-    "#formatters/*": "./src/formatters/*.js"
+    "#helpers/*.js": "./src/helpers/*.js",
+    "#formatters/*.js": "./src/formatters/*.js"
   },
   "engines": {
     "node": ">=20.11.0"

package.json

@@ -2,17 +2,20 @@ import type { ParseResult } from 'oxc-parser'
 import type { FormatterOptions, ExportsMeta } from './types.js'
 import MagicString from 'magic-string'
 
-import { identifier } from './formatters/identifier.js'
-import { metaProperty } from './formatters/metaProperty.js'
-import { memberExpression } from './formatters/memberExpression.js'
-import { assignmentExpression } from './formatters/assignmentExpression.js'
-import { isValidUrl, exportsRename, collectModuleIdentifiers } from './utils.js'
-import { isIdentifierName } from './helpers/identifier.js'
-import { ancestorWalk } from './walk.js'
+import { identifier } from '#formatters/identifier.js'
+import { metaProperty } from '#formatters/metaProperty.js'
+import { memberExpression } from '#formatters/memberExpression.js'
+import { assignmentExpression } from '#formatters/assignmentExpression.js'
+import { isValidUrl } from '#utils/url.js'
+import { exportsRename, collectCjsExports } from '#utils/exports.js'
+import { collectModuleIdentifiers } from '#utils/identifiers.js'
+import { isIdentifierName } from '#helpers/identifier.js'
+import { ancestorWalk } from '#walk'
 
 /**
- * Note, there is no specific conversion for `import.meta.main` as it does not exist.
- * @see https://github.com/nodejs/node/issues/49440
+ * Node added support for import.meta.main.
+ * Added in: v24.2.0, v22.18.0
+ * @see https://nodejs.org/api/esm.html#importmetamain
  */
 const format = async (src: string, ast: ParseResult, opts: FormatterOptions) => {
   const code = new MagicString(src)
@@ -22,6 +25,8 @@ const format = async (src: string, ast: ParseResult, opts: FormatterOptions) =>
     hasDefaultExportBeenReassigned: false,
     hasDefaultExportBeenAssigned: false,
   } satisfies ExportsMeta
+  const exportTable =
+    opts.target === 'module' ? await collectCjsExports(ast.program) : null
   await collectModuleIdentifiers(ast.program)
 
   if (opts.target === 'module' && opts.transformSyntax) {
@@ -144,6 +149,45 @@ void import.meta.filename;
     },
   })
 
+  if (opts.target === 'module' && opts.transformSyntax && exportTable) {
+    const isValidExportName = (name: string) => /^[$A-Z_a-z][$\w]*$/.test(name)
+    const asExportName = (name: string) =>
+      isValidExportName(name) ? name : JSON.stringify(name)
+    const accessProp = (name: string) =>
+      isValidExportName(name)
+        ? `${exportsRename}.${name}`
+        : `${exportsRename}[${JSON.stringify(name)}]`
+    const tempNameFor = (name: string) => {
+      const sanitized = name.replace(/[^$\w]/g, '_') || 'value'
+      const safe = /^[0-9]/.test(sanitized) ? `_${sanitized}` : sanitized
+      return `__export_${safe}`
+    }
+
+    const lines: string[] = []
+
+    const defaultEntry = exportTable.get('default')
+    if (defaultEntry) {
+      const def = defaultEntry.fromIdentifier ?? exportsRename
+      lines.push(`export default ${def};`)
+    }
+
+    for (const [key, entry] of exportTable) {
+      if (key === 'default') continue
+
+      if (entry.fromIdentifier) {
+        lines.push(`export { ${entry.fromIdentifier} as ${asExportName(key)} };`)
+      } else {
+        const temp = tempNameFor(key)
+        lines.push(`const ${temp} = ${accessProp(key)};`)
+        lines.push(`export { ${temp} as ${asExportName(key)} };`)
+      }
+    }
+
+    if (lines.length) {
+      code.append(`\n${lines.join('\n')}\n`)
+    }
+  }
+
   return code.toString()
 }
 

src/format.ts

@@ -1,6 +1,6 @@
 import MagicString from 'magic-string'
 import type { Node, AssignmentExpression } from 'oxc-parser'
-import { walk } from '../walk.js'
+import { walk } from '#walk'
 
 import type { FormatterOptions, ExportsMeta } from '../types.js'
 

src/formatters/assignmentExpression.ts

@@ -2,8 +2,8 @@ import MagicString from 'magic-string'
 import type { Node, IdentifierName } from 'oxc-parser'
 
 import type { FormatterOptions, ExportsMeta } from '../types.js'
-import { exportsRename } from '../utils.js'
-import { identifier as ident } from '../helpers/identifier.js'
+import { exportsRename } from '#utils/exports.js'
+import { identifier as ident } from '#helpers/identifier.js'
 
 type IdentifierArg = {
   node: IdentifierName

src/formatters/identifier.ts

@@ -2,7 +2,7 @@ import MagicString from 'magic-string'
 import type { MemberExpression, Node } from 'oxc-parser'
 
 import type { FormatterOptions } from '../types.js'
-import { exportsRename } from '../utils.js'
+import { exportsRename } from '#utils/exports.js'
 
 export const memberExpression = (
   node: MemberExpression,

src/formatters/memberExpression.ts

@@ -3,9 +3,9 @@ import { readFile, writeFile } from 'node:fs/promises'
 
 import { specifier } from '@knighted/specifier'
 
-import { parse } from './parse.js'
-import { format } from './format.js'
-import { getLangFromExt } from './utils.js'
+import { parse } from '#parse'
+import { format } from '#format'
+import { getLangFromExt } from '#utils/lang.js'
 import type { ModuleOptions } from './types.js'
 
 const defaultOptions = {

src/module.ts

@@ -41,6 +41,15 @@ export type ExportsMeta = {
   defaultExportValue: unknown
 }
 
+export type CjsExport = {
+  key: string
+  writes: SpannedNode[]
+  fromIdentifier?: string
+  via: Set<'exports' | 'module.exports'>
+  reassignments: SpannedNode[]
+  hasGetter?: boolean
+}
+
 export type IdentMeta = {
   /*
     `var` can be redeclared in the same scope.