@knighted/module 1.0.0-rc.2 → 1.0.0-rc.3

package/README.md

@@ -101,6 +101,8 @@ type ModuleOptions = {
   sourceType?: 'auto' | 'module' | 'commonjs'
   transformSyntax?: boolean
   liveBindings?: 'strict' | 'loose' | 'off'
+  appendJsExtension?: 'off' | 'relative-only' | 'all'
+  appendDirectoryIndex?: string | false
   rewriteSpecifier?:
     | '.js'
     | '.mjs'
@@ -112,6 +114,8 @@ type ModuleOptions = {
   dirFilename?: 'inject' | 'preserve' | 'error'
   importMeta?: 'preserve' | 'shim' | 'error'
   importMetaMain?: 'shim' | 'warn' | 'error'
+  requireMainStrategy?: 'import-meta-main' | 'realpath'
+  detectCircularRequires?: 'off' | 'warn' | 'error'
   requireSource?: 'builtin' | 'create-require'
   cjsDefault?: 'module-exports' | 'auto' | 'none'
   topLevelAwait?: 'error' | 'wrap' | 'preserve'
@@ -125,9 +129,13 @@ Behavior notes (defaults in parentheses)
 - `target` (`commonjs`): output module system.
 - `transformSyntax` (true): enable/disable the ESM↔CJS lowering pass.
 - `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).
 - `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.
 - `requireSource` (`builtin`): whether `require` comes from Node or `createRequire`.
@@ -135,11 +143,38 @@ Behavior notes (defaults in parentheses)
 - `out`/`inPlace`: write the transformed code to a file; otherwise the function returns the transformed string only.
 - CommonJS → ESM lowering will throw on `with` statements and unshadowed `eval` calls to avoid unsound rewrites.
 
+> [!NOTE]
+> Package-level metadata (`package.json` updates such as setting `"type": "module"` or authoring `exports`) is not edited by this tool today; plan that change outside the per-file transform.
+
 See [docs/esm-to-cjs.md](docs/esm-to-cjs.md) for deeper notes on live bindings, interop helpers, top-level await behavior, and `import.meta.main` handling. For CommonJS to ESM lowering details, read [docs/cjs-to-esm.md](docs/cjs-to-esm.md).
 
 > [!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`.
 
+## 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.
+
+Minimal flow:
+
+```js
+import { glob } from 'glob'
+import { transform } from '@knighted/module'
+
+const files = await glob('src/**/*.{ts,js,mts,cts}', { ignore: 'node_modules/**' })
+
+for (const file of files) {
+  await transform(file, {
+    target: 'commonjs', // or 'module' when raising CJS → ESM
+    inPlace: true,
+    transformSyntax: true,
+  })
+}
+// then run `tsc`
+```
+
+This pre-`tsc` step removes the flagged globals in the compiled orientation; runtime semantics still match the target build.
+
 ## Roadmap
 
 - Emit source maps and clearer diagnostics for transform choices.

package/dist/cjs/format.cjs

@@ -26,6 +26,8 @@ const exportAssignment = (name, expr, live) => {
 };
 const defaultInteropName = '__interopDefault';
 const interopHelper = `const ${defaultInteropName} = mod => (mod && mod.__esModule ? mod.default : mod);\n`;
+const requireInteropName = '__requireDefault';
+const requireInteropHelper = `const ${requireInteropName} = mod => (mod && typeof mod === 'object' && 'default' in mod ? mod.default : mod);\n`;
 const isRequireCallee = (callee, shadowed) => {
   if (callee.type === 'Identifier' && callee.name === 'require' && !shadowed.has('require')) {
     return true;
@@ -40,8 +42,14 @@ const isRequireCall = (node, shadowed) => node.type === 'CallExpression' && isRe
 const lowerCjsRequireToImports = (program, code, shadowed) => {
   const transforms = [];
   const imports = [];
+  const hoisted = [];
   let nsIndex = 0;
   let needsCreateRequire = false;
+  let needsInteropHelper = false;
+  const isJsonSpecifier = value => {
+    const base = value.split(/[?#]/)[0] ?? value;
+    return base.endsWith('.json');
+  };
   for (const stmt of program.body) {
     if (stmt.type === 'VariableDeclaration') {
       const decls = stmt.declarations;
@@ -49,14 +57,21 @@ const lowerCjsRequireToImports = (program, code, shadowed) => {
       if (allStatic) {
         for (const decl of decls) {
           const init = decl.init;
-          const source = code.slice(init.arguments[0].start, init.arguments[0].end);
+          const arg = init.arguments[0];
+          const source = code.slice(arg.start, arg.end);
+          const value = arg.value;
+          const isJson = typeof value === 'string' && isJsonSpecifier(value);
+          const ns = `__cjsImport${nsIndex++}`;
+          const jsonImport = isJson ? `${source} with { type: "json" }` : source;
           if (decl.id.type === 'Identifier') {
-            imports.push(`import * as ${decl.id.name} from ${source};\n`);
-          } else if (decl.id.type === 'ObjectPattern') {
-            const ns = `__cjsImport${nsIndex++}`;
+            imports.push(isJson ? `import ${ns} from ${jsonImport};\n` : `import * as ${ns} from ${jsonImport};\n`);
+            hoisted.push(isJson ? `const ${decl.id.name} = ${ns};\n` : `const ${decl.id.name} = ${requireInteropName}(${ns});\n`);
+            needsInteropHelper ||= !isJson;
+          } else if (decl.id.type === 'ObjectPattern' || decl.id.type === 'ArrayPattern') {
             const pattern = code.slice(decl.id.start, decl.id.end);
-            imports.push(`import * as ${ns} from ${source};\n`);
-            imports.push(`const ${pattern} = ${ns};\n`);
+            imports.push(isJson ? `import ${ns} from ${jsonImport};\n` : `import * as ${ns} from ${jsonImport};\n`);
+            hoisted.push(isJson ? `const ${pattern} = ${ns};\n` : `const ${pattern} = ${requireInteropName}(${ns});\n`);
+            needsInteropHelper ||= !isJson;
           } else {
             needsCreateRequire = true;
           }
@@ -78,8 +93,12 @@ const lowerCjsRequireToImports = (program, code, shadowed) => {
     if (stmt.type === 'ExpressionStatement') {
       const expr = stmt.expression;
       if (expr && isStaticRequire(expr, shadowed)) {
-        const source = code.slice(expr.arguments[0].start, expr.arguments[0].end);
-        imports.push(`import ${source};\n`);
+        const arg = expr.arguments[0];
+        const source = code.slice(arg.start, arg.end);
+        const value = arg.value;
+        const isJson = typeof value === 'string' && isJsonSpecifier(value);
+        const jsonImport = isJson ? `${source} with { type: "json" }` : source;
+        imports.push(`import ${jsonImport};\n`);
         transforms.push({
           start: stmt.start,
           end: stmt.end,
@@ -95,7 +114,9 @@ const lowerCjsRequireToImports = (program, code, shadowed) => {
   return {
     transforms,
     imports,
-    needsCreateRequire
+    hoisted,
+    needsCreateRequire,
+    needsInteropHelper
   };
 };
 const isRequireMainMember = (node, shadowed) => node && node.type === 'MemberExpression' && node.object.type === 'Identifier' && node.object.name === 'require' && !shadowed.has('require') && node.property.type === 'Identifier' && node.property.name === 'main';
@@ -136,6 +157,20 @@ const hasTopLevelAwait = program => {
   walkNode(program, false);
   return found;
 };
+const isAsyncContext = ancestors => {
+  for (let i = ancestors.length - 1; i >= 0; i -= 1) {
+    const node = ancestors[i];
+    if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') {
+      return !!node.async;
+    }
+    if (node.type === 'ClassDeclaration' || node.type === 'ClassExpression') {
+      return false;
+    }
+  }
+
+  // Program scope (top-level) supports await in ESM.
+  return true;
+};
 const lowerEsmToCjs = (program, code, opts, containsTopLevelAwait) => {
   const live = opts.liveBindings ?? 'strict';
   const importTransforms = [];
@@ -345,11 +380,17 @@ const format = async (src, ast, opts) => {
   const exportTable = opts.target === 'module' ? await (0, _exports.collectCjsExports)(ast.program) : null;
   const shouldCheckTopLevelAwait = opts.target === 'commonjs' && opts.transformSyntax;
   const containsTopLevelAwait = shouldCheckTopLevelAwait ? hasTopLevelAwait(ast.program) : false;
+  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;
   let hoistedImports = [];
+  let hoistedStatements = [];
   let pendingRequireTransforms = [];
   let needsCreateRequire = false;
+  let needsImportInterop = false;
   let pendingCjsTransforms = null;
   if (shouldLowerCjs && opts.topLevelAwait === 'error' && containsTopLevelAwait) {
     throw new Error('Top-level await is not supported when targeting CommonJS (set topLevelAwait to "wrap" or "preserve" to override).');
@@ -358,11 +399,15 @@ const format = async (src, ast, opts) => {
     const {
       transforms,
       imports,
-      needsCreateRequire: reqCreate
+      hoisted,
+      needsCreateRequire: reqCreate,
+      needsInteropHelper: reqInteropHelper
     } = lowerCjsRequireToImports(ast.program, code, shadowedBindings);
     pendingRequireTransforms = transforms;
     hoistedImports = imports;
+    hoistedStatements = hoisted;
     needsCreateRequire = reqCreate;
+    needsImportInterop = reqInteropHelper;
   }
   await (0, _walk.ancestorWalk)(ast.program, {
     async enter(node, ancestors) {
@@ -377,7 +422,11 @@ const format = async (src, ast, opts) => {
           const rightModule = node.right.type === 'Identifier' && node.right.name === 'module' && !shadowedBindings.has('module');
           if (leftMain && rightModule || rightMain && leftModule) {
             const negate = op === '!==' || op === '!=';
-            code.update(node.start, node.end, negate ? '!import.meta.main' : 'import.meta.main');
+            const mainExpr = requireMainStrategy === 'import-meta-main' ? 'import.meta.main' : 'import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href';
+            if (requireMainStrategy === 'realpath') {
+              requireMainNeedsRealpath = true;
+            }
+            code.update(node.start, node.end, negate ? `!(${mainExpr})` : mainExpr);
             return;
           }
         }
@@ -399,6 +448,18 @@ const format = async (src, ast, opts) => {
         const topLevelVarDecl = parent?.type === 'VariableDeclarator' && grandparent?.type === 'VariableDeclaration' && greatGrandparent?.type === 'Program';
         const hoistableTopLevel = isStatic && (topLevelExprStmt || topLevelVarDecl);
         if (!isStatic || !hoistableTopLevel) {
+          if (nestedRequireStrategy === 'dynamic-import') {
+            const asyncCapable = isAsyncContext(ancestors);
+            if (asyncCapable) {
+              const arg = node.arguments[0];
+              const argSrc = arg ? code.slice(arg.start, arg.end) : 'undefined';
+              const literalVal = arg?.value;
+              const isJson = arg?.type === 'Literal' && typeof literalVal === 'string' && (literalVal.split(/[?#]/)[0] ?? literalVal).endsWith('.json');
+              const importTarget = isJson ? `${argSrc} with { type: "json" }` : argSrc;
+              code.update(node.start, node.end, `(await import(${importTarget}))`);
+              return;
+            }
+          }
           needsCreateRequire = true;
         }
       }
@@ -460,7 +521,23 @@ const format = async (src, ast, opts) => {
         (0, _metaProperty.metaProperty)(node, parent, code, opts);
       }
       if (node.type === 'MemberExpression') {
-        (0, _memberExpression.memberExpression)(node, parent, code, opts, shadowedBindings);
+        (0, _memberExpression.memberExpression)(node, parent, code, opts, shadowedBindings, {
+          onRequireResolve: () => {
+            if (shouldRaiseEsm) needsRequireResolveHelper = true;
+          },
+          requireResolveName: '__requireResolve'
+        });
+      }
+      if (shouldRaiseEsm && node.type === 'ThisExpression') {
+        const bindsThis = ancestor => {
+          return ancestor.type === 'FunctionDeclaration' || ancestor.type === 'FunctionExpression' || ancestor.type === 'ClassDeclaration' || ancestor.type === 'ClassExpression';
+        };
+        const bindingAncestor = ancestors.find(ancestor => bindsThis(ancestor));
+        const isTopLevel = !bindingAncestor;
+        if (isTopLevel) {
+          code.update(node.start, node.end, _exports.exportsRename);
+          return;
+        }
       }
       if ((0, _identifier2.isIdentifierName)(node)) {
         (0, _identifier.identifier)({
@@ -529,14 +606,36 @@ const format = async (src, ast, opts) => {
   }
   if (shouldRaiseEsm && opts.transformSyntax) {
     const importPrelude = [];
-    if (needsCreateRequire) {
+    if (needsCreateRequire || needsRequireResolveHelper) {
       importPrelude.push('import { createRequire } from "node:module";\n');
     }
+    if (needsRequireResolveHelper) {
+      importPrelude.push('import { fileURLToPath } from "node:url";\n');
+    }
+    if (requireMainNeedsRealpath) {
+      importPrelude.push('import { realpathSync } from "node:fs";\n');
+      importPrelude.push('import { pathToFileURL } from "node:url";\n');
+    }
     if (hoistedImports.length) {
       importPrelude.push(...hoistedImports);
     }
+    const setupPrelude = [];
+    if (needsImportInterop) {
+      setupPrelude.push(requireInteropHelper);
+    }
+    if (hoistedStatements.length) {
+      setupPrelude.push(...hoistedStatements);
+    }
     const requireInit = needsCreateRequire ? 'const require = createRequire(import.meta.url);\n' : '';
-    const prelude = `${importPrelude.join('')}${importPrelude.length ? '\n' : ''}${requireInit}let ${_exports.exportsRename} = {};
+    const requireResolveInit = needsRequireResolveHelper ? needsCreateRequire ? `const __requireResolve = (id, parent) => {
+  const resolved = require.resolve(id, parent);
+  return resolved.startsWith("file://") ? fileURLToPath(resolved) : resolved;
+};\n` : `const __requireResolve = (id, parent) => {
+  const req = createRequire(parent ?? import.meta.url);
+  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;
 `;
     code.prepend(prelude);

package/dist/cjs/formatters/identifier.cjs

@@ -25,7 +25,7 @@ const identifier = ({
     }
     switch (name) {
       case '__filename':
-        code.update(start, end, 'import.meta.url');
+        code.update(start, end, 'import.meta.filename');
         break;
       case '__dirname':
         code.update(start, end, 'import.meta.dirname');

package/dist/cjs/formatters/memberExpression.cjs

@@ -5,7 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.memberExpression = void 0;
 var _exports = require("#utils/exports.js");
-const memberExpression = (node, parent, src, options, shadowed) => {
+const memberExpression = (node, parent, src, options, shadowed, extras) => {
   if (options.target === 'module') {
     if (node.object.type === 'Identifier' && shadowed?.has(node.object.name) || node.property.type === 'Identifier' && shadowed?.has(node.property.name)) {
       return;
@@ -32,7 +32,8 @@ const memberExpression = (node, parent, src, options, shadowed) => {
           src.update(start, end, 'import.meta.main');
           break;
         case 'resolve':
-          src.update(start, end, 'import.meta.resolve');
+          extras?.onRequireResolve?.();
+          src.update(start, end, extras?.requireResolveName ?? 'import.meta.resolve');
           break;
         case 'cache':
           /**

package/dist/cjs/helpers/identifier.cjs

@@ -30,6 +30,31 @@ const getScopeContext = program => {
   scopeCache.set(program, context);
   return context;
 };
+const isInBindingPattern = (pattern, target) => {
+  if (pattern === target) return true;
+  switch (pattern.type) {
+    case 'Identifier':
+      return pattern === target;
+    case 'AssignmentPattern':
+      return isInBindingPattern(pattern.left, target);
+    case 'RestElement':
+      return isInBindingPattern(pattern.argument, target);
+    case 'ObjectPattern':
+      return (pattern.properties ?? []).some(prop => {
+        if (prop.type === 'Property') {
+          return isInBindingPattern(prop.value, target);
+        }
+        if (prop.type === 'RestElement') {
+          return isInBindingPattern(prop.argument, target);
+        }
+        return false;
+      });
+    case 'ArrayPattern':
+      return (pattern.elements ?? []).some(elem => elem && isInBindingPattern(elem, target));
+    default:
+      return false;
+  }
+};
 
 /**
  * All methods receive the full set of ancestors, which
@@ -48,6 +73,7 @@ const identifier = exports.identifier = {
   isModuleScope(ancestors, includeImports = false) {
     const node = ancestors[ancestors.length - 1];
     const parent = ancestors[ancestors.length - 2];
+    const grandParent = ancestors[ancestors.length - 3];
     const program = ancestors[0];
     if (!identifier.isNamed(node) || identifier.isMetaProperty(ancestors) || parent.type === 'LabeledStatement' || parent.type === 'BreakStatement' || parent.type === 'ContinueStatement') {
       return false;
@@ -56,7 +82,9 @@ const identifier = exports.identifier = {
       return includeImports && parent.local.name === node.name;
     }
     if (parent.type === 'Property' && parent.key === node && !parent.computed) {
-      return false;
+      if (grandParent?.type !== 'ObjectPattern') {
+        return false;
+      }
     }
     if (parent.type === 'MemberExpression' && parent.property === node && !parent.computed) {
       return false;
@@ -78,8 +106,17 @@ const identifier = exports.identifier = {
   },
   isDeclaration(ancestors) {
     const node = ancestors[ancestors.length - 1];
-    const parent = ancestors[ancestors.length - 2];
-    return (parent.type === 'VariableDeclarator' || parent.type === 'FunctionDeclaration' || parent.type === 'ClassDeclaration') && parent.id === node;
+    // Walk outwards to find a declarator that binds the node
+    for (let i = ancestors.length - 2; i >= 0; i--) {
+      const parent = ancestors[i];
+      if (parent.type === 'VariableDeclarator') {
+        return parent.id === node || isInBindingPattern(parent.id, node);
+      }
+      if (parent.type === 'FunctionDeclaration' || parent.type === 'ClassDeclaration') {
+        return parent.id === node;
+      }
+    }
+    return false;
   },
   isClassOrFuncDeclarationId(ancestors) {
     const node = ancestors[ancestors.length - 1];
@@ -88,12 +125,16 @@ const identifier = exports.identifier = {
   },
   isVarDeclarationInGlobalScope(ancestors) {
     const node = ancestors[ancestors.length - 1];
-    const parent = ancestors[ancestors.length - 2];
-    const grandParent = ancestors[ancestors.length - 3];
     const varBoundScopes = ['ClassDeclaration', 'ClassExpression', 'FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'];
-    return parent.type === 'VariableDeclarator' && parent.id === node && grandParent.type === 'VariableDeclaration' && grandParent.kind === 'var' && ancestors.every(ancestor => {
-      return !varBoundScopes.includes(ancestor.type);
+    const declaratorIndex = ancestors.findIndex(ancestor => {
+      return ancestor.type === 'VariableDeclarator' && (ancestor === node || isInBindingPattern(ancestor.id, node));
     });
+    if (declaratorIndex === -1) return false;
+    const declarator = ancestors[declaratorIndex];
+    const declaration = ancestors[declaratorIndex - 1];
+    return declaration?.type === 'VariableDeclaration' && declaration.kind === 'var' && ancestors.every(ancestor => {
+      return !varBoundScopes.includes(ancestor.type);
+    }) && (declarator.id === node || isInBindingPattern(declarator.id, node));
   },
   isIife(ancestors) {
     const parent = ancestors[ancestors.length - 2];

package/dist/cjs/memberExpression.d.cts

@@ -1,4 +1,9 @@
 import MagicString from 'magic-string';
 import type { MemberExpression, Node } from 'oxc-parser';
 import type { FormatterOptions } from '../types.cjs';
-export declare const memberExpression: (node: MemberExpression, parent: Node | null, src: MagicString, options: FormatterOptions, shadowed?: Set<string>) => void;
+type MemberExpressionExtras = {
+    onRequireResolve?: () => void;
+    requireResolveName?: string;
+};
+export declare const memberExpression: (node: MemberExpression, parent: Node | null, src: MagicString, options: FormatterOptions, shadowed?: Set<string>, extras?: MemberExpressionExtras) => void;
+export {};

package/dist/cjs/module.cjs

@@ -10,16 +10,155 @@ var _specifier = require("./specifier.cjs");
 var _parse = require("#parse");
 var _format = require("#format");
 var _lang = require("#utils/lang.js");
+var _nodeModule = require("node:module");
+var _walk = require("#walk");
+const collapseSpecifier = value => value.replace(/['"`+)\s]|new String\(/g, '');
+const builtinSpecifiers = new Set(_nodeModule.builtinModules.map(mod => mod.startsWith('node:') ? mod.slice(5) : mod).flatMap(mod => {
+  const parts = mod.split('/');
+  const base = parts[0];
+  return parts.length > 1 ? [mod, base] : [mod];
+}));
+const appendExtensionIfNeeded = (spec, mode, dirIndex, value = spec.value) => {
+  if (mode === 'off') return;
+  if (spec.type === 'TemplateLiteral') {
+    const node = spec.node;
+    if (node.expressions.length > 0) return;
+  } else if (spec.type !== 'StringLiteral') {
+    return;
+  }
+  const collapsed = collapseSpecifier(value);
+  const isRelative = /^(?:\.\.?)\//.test(collapsed);
+  if (!isRelative) return;
+  const base = collapsed.split(/[?#]/)[0];
+  if (!base) return;
+  if (base.endsWith('/')) {
+    if (!dirIndex) return;
+    return `${value}${dirIndex}`;
+  }
+  const lastSegment = base.split('/').pop() ?? '';
+  if (lastSegment.includes('.')) return;
+  return `${value}.js`;
+};
+const rewriteSpecifierValue = (value, rewriteSpecifier) => {
+  if (!rewriteSpecifier) return;
+  if (typeof rewriteSpecifier === 'function') {
+    return rewriteSpecifier(value) ?? undefined;
+  }
+  const collapsed = collapseSpecifier(value);
+  const relative = /^(?:\.\.?)\//;
+  if (relative.test(collapsed)) {
+    return value.replace(/(.+)\.(?:m|c)?(?:j|t)s([)'"]*)?$/, `$1${rewriteSpecifier}$2`);
+  }
+};
+const normalizeBuiltinSpecifier = value => {
+  const collapsed = collapseSpecifier(value);
+  if (!collapsed) return;
+  const specPart = collapsed.split(/[?#]/)[0] ?? '';
+
+  // Ignore relative and absolute paths.
+  if (/^(?:\.\.?\/|\/)/.test(specPart)) return;
+
+  // Skip other protocols (e.g., http:, data:) but allow node:.
+  if (/^[a-zA-Z][a-zA-Z+.-]*:/.test(specPart) && !specPart.startsWith('node:')) return;
+  const bare = specPart.startsWith('node:') ? specPart.slice(5) : specPart;
+  const base = bare.split('/')[0] ?? '';
+  if (!builtinSpecifiers.has(bare) && !builtinSpecifiers.has(base)) return;
+  if (specPart.startsWith('node:')) return;
+  const quote = /^['"`]/.exec(value)?.[0] ?? '';
+  return quote ? `${quote}node:${value.slice(quote.length)}` : `node:${value}`;
+};
+const fileExists = async candidate => {
+  try {
+    const s = await (0, _promises.stat)(candidate);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+};
+const resolveRequirePath = async (fromFile, spec, dirIndex) => {
+  if (!spec.startsWith('./') && !spec.startsWith('../')) return null;
+  const base = (0, _nodePath.resolve)((0, _nodePath.dirname)(fromFile), spec);
+  const ext = (0, _nodePath.extname)(base);
+  const candidates = [];
+  if (ext) {
+    candidates.push(base);
+  } else {
+    candidates.push(`${base}.js`, `${base}.cjs`, `${base}.mjs`);
+    candidates.push((0, _nodePath.join)(base, dirIndex));
+  }
+  for (const candidate of candidates) {
+    if (await fileExists(candidate)) return candidate;
+  }
+  return null;
+};
+const collectStaticRequires = async (filePath, dirIndex) => {
+  const src = await (0, _promises.readFile)(filePath, 'utf8');
+  const ast = (0, _parse.parse)(filePath, src);
+  const specs = [];
+  await (0, _walk.walk)(ast.program, {
+    enter(node) {
+      if (node.type === 'CallExpression' && node.callee.type === 'Identifier' && node.callee.name === 'require' && node.arguments.length === 1 && node.arguments[0].type === 'Literal' && typeof node.arguments[0].value === 'string') {
+        const spec = node.arguments[0].value;
+        if (spec.startsWith('./') || spec.startsWith('../')) {
+          specs.push(spec);
+        }
+      }
+    }
+  });
+  const resolved = [];
+  for (const spec of specs) {
+    const target = await resolveRequirePath(filePath, spec, dirIndex);
+    if (target) resolved.push(target);
+  }
+  return resolved;
+};
+const detectCircularRequireGraph = async (entryFile, mode, dirIndex) => {
+  const cache = new Map();
+  const visiting = new Set();
+  const visited = new Set();
+  const dfs = async (file, stack) => {
+    if (visiting.has(file)) {
+      const cycle = [...stack, file];
+      const msg = `Circular require detected: ${cycle.join(' -> ')}`;
+      if (mode === 'error') {
+        throw new Error(msg);
+      }
+      // eslint-disable-next-line no-console -- surfaced when cycle detection is warn-only
+      console.warn(msg);
+      return;
+    }
+    if (visited.has(file)) return;
+    visiting.add(file);
+    stack.push(file);
+    let deps = cache.get(file);
+    if (!deps) {
+      deps = await collectStaticRequires(file, dirIndex);
+      cache.set(file, deps);
+    }
+    for (const dep of deps) {
+      await dfs(dep, stack);
+    }
+    stack.pop();
+    visiting.delete(file);
+    visited.add(file);
+  };
+  await dfs(entryFile, []);
+};
 const defaultOptions = {
   target: 'commonjs',
   sourceType: 'auto',
   transformSyntax: true,
   liveBindings: 'strict',
   rewriteSpecifier: undefined,
+  appendJsExtension: undefined,
+  appendDirectoryIndex: 'index.js',
   dirFilename: 'inject',
   importMeta: 'shim',
   importMetaMain: 'shim',
+  requireMainStrategy: 'import-meta-main',
+  detectCircularRequires: 'off',
   requireSource: 'builtin',
+  nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
   topLevelAwait: 'error',
   out: undefined,
@@ -30,28 +169,26 @@ const transform = async (filename, options = defaultOptions) => {
     ...defaultOptions,
     ...options
   };
+  const appendMode = options?.appendJsExtension ?? (opts.target === 'module' ? 'relative-only' : 'off');
+  const dirIndex = opts.appendDirectoryIndex === undefined ? 'index.js' : opts.appendDirectoryIndex;
+  const detectCycles = opts.detectCircularRequires ?? 'off';
   const file = (0, _nodePath.resolve)(filename);
   const code = (await (0, _promises.readFile)(file)).toString();
   const ast = (0, _parse.parse)(filename, code);
   let source = await (0, _format.format)(code, ast, opts);
-  if (opts.rewriteSpecifier) {
-    const code = await _specifier.specifier.updateSrc(source, (0, _lang.getLangFromExt)(filename), ({
-      value
-    }) => {
-      if (typeof opts.rewriteSpecifier === 'function') {
-        return opts.rewriteSpecifier(value) ?? undefined;
-      }
-
-      // Collapse any BinaryExpression or NewExpression to test for a relative specifier
-      const collapsed = value.replace(/['"`+)\s]|new String\(/g, '');
-      const relative = /^(?:\.|\.\.)\//;
-      if (relative.test(collapsed)) {
-        // $2 is for any closing quotation/parens around BE or NE
-        return value.replace(/(.+)\.(?:m|c)?(?:j|t)s([)'"]*)?$/, `$1${opts.rewriteSpecifier}$2`);
-      }
+  if (opts.rewriteSpecifier || appendMode !== 'off' || dirIndex) {
+    const code = await _specifier.specifier.updateSrc(source, (0, _lang.getLangFromExt)(filename), spec => {
+      const normalized = normalizeBuiltinSpecifier(spec.value);
+      const rewritten = rewriteSpecifierValue(normalized ?? spec.value, opts.rewriteSpecifier);
+      const baseValue = rewritten ?? normalized ?? spec.value;
+      const appended = appendExtensionIfNeeded(spec, appendMode, dirIndex, baseValue);
+      return appended ?? rewritten ?? normalized ?? undefined;
     });
     source = code;
   }
+  if (detectCycles !== 'off' && opts.target === 'module' && opts.transformSyntax) {
+    await detectCircularRequireGraph(file, detectCycles, dirIndex || 'index.js');
+  }
   const outputPath = opts.inPlace ? file : opts.out ? (0, _nodePath.resolve)(opts.out) : undefined;
   if (outputPath) {
     await (0, _promises.writeFile)(outputPath, source);

package/dist/cjs/specifier.cjs

@@ -128,7 +128,7 @@ const formatSpecifiers = async (src, ast, cb) => {
       }
       if (node.type === 'CallExpression') {
         // Handle require(), require.resolve(), import.meta.resolve()
-        if (node.callee.type === 'Identifier' && node.callee.name === 'require' || node.callee.type === 'MemberExpression' && node.callee.object.type === 'Identifier' && node.callee.object.name === 'require' && node.callee.property.type === 'Identifier' && node.callee.property.name === 'resolve' || node.callee.type === 'MemberExpression' && node.callee.object.type === 'MetaProperty' && node.callee.object.meta.name === 'import' && node.callee.property.type === 'Identifier' && node.callee.property.name === 'resolve') {
+        if (node.callee.type === 'Identifier' && node.callee.name === 'require' || node.callee.type === 'MemberExpression' && node.callee.object.type === 'Identifier' && node.callee.object.name === 'require' && node.callee.property.type === 'Identifier' && node.callee.property.name === 'resolve' || node.callee.type === 'Identifier' && node.callee.name === '__requireResolve' || node.callee.type === 'MemberExpression' && node.callee.object.type === 'MetaProperty' && node.callee.object.meta.name === 'import' && node.callee.property.type === 'Identifier' && node.callee.property.name === 'resolve') {
           formatExpression(node);
         }
       }