@knighted/module 1.4.0 → 1.5.0

package/README.md

@@ -114,6 +114,7 @@ type ModuleOptions = {
   target: 'module' | 'commonjs'
   sourceType?: 'auto' | 'module' | 'commonjs'
   transformSyntax?: boolean | 'globals-only'
+  sourceMap?: boolean
   liveBindings?: 'strict' | 'loose' | 'off'
   appendJsExtension?: 'off' | 'relative-only' | 'all'
   appendDirectoryIndex?: string | false
@@ -133,6 +134,7 @@ type ModuleOptions = {
   detectCircularRequires?: 'off' | 'warn' | 'error'
   detectDualPackageHazard?: 'off' | 'warn' | 'error'
   dualPackageHazardScope?: 'file' | 'project'
+  dualPackageHazardAllowlist?: string[]
   requireSource?: 'builtin' | 'create-require'
   importMetaPrelude?: 'off' | 'auto' | 'on'
   cjsDefault?: 'module-exports' | 'auto' | 'none'
@@ -161,12 +163,14 @@ type ModuleOptions = {
 - `detectCircularRequires` (`off`): optionally detect relative static require cycles across `.js`/`.mjs`/`.cjs`/`.ts`/`.mts`/`.cts` (realpath-normalized) and warn/throw.
 - `detectDualPackageHazard` (`warn`): flag when `import` and `require` mix for the same package or root/subpath are combined in ways that can resolve to separate module instances (dual packages). Set to `error` to fail the transform.
 - `dualPackageHazardScope` (`file`): `file` preserves the legacy per-file detector; `project` aggregates package usage across all CLI inputs (useful in monorepos/hoisted installs) and emits one diagnostic per package.
+- `dualPackageHazardAllowlist` (`[]`): suppress dual-package hazard diagnostics for the listed packages. Accepts an array in the API; entries are trimmed and empty values dropped. The CLI flag `--dual-package-hazard-allowlist pkg1,pkg2` parses a comma- or space-separated string into this array. Applies to both `file` and `project` scopes.
 - `topLevelAwait` (`error`): throw, wrap, or preserve when TLA appears in CommonJS output. `wrap` runs the file body inside an async IIFE (exports may resolve after the initial tick); `preserve` leaves `await` at top level, which Node will reject for CJS.
 - `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`.
 - `idiomaticExports` (`safe`): when raising CJS to ESM, attempt to synthesize `export` statements directly when it is safe. `off` always uses the helper bag; `aggressive` currently matches `safe` heuristics.
 - `out`/`inPlace`: choose output location. Default returns the transformed string (CLI emits to stdout). `out` writes to the provided path. `inPlace` overwrites the input files on disk and does not return/emit the code.
+- `sourceMap` (`false`): when true, returns `{ code, map }` from `transform` and writes the map if you also set `out`/`inPlace`. Maps are generated from the same MagicString pipeline used for the code.
 - `cwd` (`process.cwd()`): Base directory used to resolve relative `out` paths.
 
 > [!NOTE]

package/dist/cjs/cli.cjs

@@ -32,12 +32,14 @@ const defaultOptions = {
   detectCircularRequires: 'off',
   detectDualPackageHazard: 'warn',
   dualPackageHazardScope: 'file',
+  dualPackageHazardAllowlist: [],
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
   idiomaticExports: 'safe',
   importMetaPrelude: 'auto',
   topLevelAwait: 'error',
+  sourceMap: false,
   cwd: undefined,
   out: undefined,
   inPlace: false
@@ -163,6 +165,11 @@ const optionsTable = [{
   short: undefined,
   type: 'string',
   desc: 'Scope for dual package hazard detection (file|project)'
+}, {
+  long: 'dual-package-hazard-allowlist',
+  short: undefined,
+  type: 'string',
+  desc: 'Comma-separated packages to ignore for dual package hazard checks'
 }, {
   long: 'top-level-await',
   short: 'a',
@@ -183,6 +190,11 @@ const optionsTable = [{
   short: 'm',
   type: 'string',
   desc: 'Emit import.meta prelude (off|auto|on)'
+}, {
+  long: 'source-map',
+  short: undefined,
+  type: 'boolean',
+  desc: 'Emit a source map alongside transformed output (use --source-map=inline for stdout)'
 }, {
   long: 'nested-require-strategy',
   short: 'n',
@@ -281,12 +293,17 @@ const parseAppendDirectoryIndex = value => {
   if (value === 'false') return false;
   return value;
 };
+const parseAllowlist = value => {
+  const values = value === undefined ? [] : Array.isArray(value) ? value : [value];
+  return values.flatMap(entry => String(entry).split(',')).map(item => item.trim()).filter(Boolean);
+};
 const toModuleOptions = values => {
   const target = parseEnum(values.target, ['module', 'commonjs']) ?? defaultOptions.target;
   const transformSyntax = parseTransformSyntax(values['transform-syntax']);
   const rewriteTemplateLiterals = parseEnum(values['rewrite-template-literals'], ['allow', 'static-only']) ?? defaultOptions.rewriteTemplateLiterals;
   const appendJsExtension = parseEnum(values['append-js-extension'], ['off', 'relative-only', 'all']);
   const appendDirectoryIndex = parseAppendDirectoryIndex(values['append-directory-index']);
+  const dualPackageHazardAllowlist = parseAllowlist(values['dual-package-hazard-allowlist']);
   const opts = {
     ...defaultOptions,
     target,
@@ -298,6 +315,7 @@ const toModuleOptions = values => {
     detectCircularRequires: parseEnum(values['detect-circular-requires'], ['off', 'warn', 'error']) ?? defaultOptions.detectCircularRequires,
     detectDualPackageHazard: parseEnum(values['detect-dual-package-hazard'], ['off', 'warn', 'error']) ?? defaultOptions.detectDualPackageHazard,
     dualPackageHazardScope: parseEnum(values['dual-package-hazard-scope'], ['file', 'project']) ?? defaultOptions.dualPackageHazardScope,
+    dualPackageHazardAllowlist,
     topLevelAwait: parseEnum(values['top-level-await'], ['error', 'wrap', 'preserve']) ?? defaultOptions.topLevelAwait,
     cjsDefault: parseEnum(values['cjs-default'], ['module-exports', 'auto', 'none']) ?? defaultOptions.cjsDefault,
     idiomaticExports: parseEnum(values['idiomatic-exports'], ['off', 'safe', 'aggressive']) ?? defaultOptions.idiomaticExports,
@@ -305,6 +323,7 @@ const toModuleOptions = values => {
     nestedRequireStrategy: parseEnum(values['nested-require-strategy'], ['create-require', 'dynamic-import']) ?? defaultOptions.nestedRequireStrategy,
     requireMainStrategy: parseEnum(values['require-main-strategy'], ['import-meta-main', 'realpath']) ?? defaultOptions.requireMainStrategy,
     liveBindings: parseEnum(values['live-bindings'], ['strict', 'loose', 'off']) ?? defaultOptions.liveBindings,
+    sourceMap: Boolean(values['source-map']),
     cwd: values.cwd ? (0, _nodePath.resolve)(String(values.cwd)) : defaultOptions.cwd
   };
   return opts;
@@ -316,6 +335,55 @@ const readStdin = async stdin => {
   }
   return Buffer.concat(chunks).toString('utf8');
 };
+const normalizeSourceMapArgv = argv => {
+  let sourceMapInline = false;
+  let invalidSourceMapValue = null;
+  const normalized = [];
+  const recordInvalid = value => {
+    if (!invalidSourceMapValue) invalidSourceMapValue = value;
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--source-map') {
+      const next = argv[i + 1];
+      if (next === 'inline') {
+        sourceMapInline = true;
+        normalized.push('--source-map');
+        i += 1;
+        continue;
+      }
+      if (next === 'true' || next === 'false') {
+        normalized.push(`--source-map=${next}`);
+        i += 1;
+        continue;
+      }
+    }
+    if (arg.startsWith('--source-map=')) {
+      const value = arg.slice('--source-map='.length);
+      if (value === 'inline') {
+        sourceMapInline = true;
+        normalized.push('--source-map');
+        continue;
+      }
+      if (value === 'true' || value === 'false') {
+        normalized.push(arg);
+        continue;
+      }
+      recordInvalid(value);
+      continue;
+    }
+    if (arg === '--source-map' && argv[i + 1] && argv[i + 1].startsWith('--')) {
+      normalized.push('--source-map');
+      continue;
+    }
+    normalized.push(arg);
+  }
+  return {
+    argv: normalized,
+    sourceMapInline,
+    invalidSourceMapValue
+  };
+};
 const expandFiles = async (patterns, cwd, ignore) => {
   const files = new Set();
   for (const pattern of patterns) {
@@ -403,8 +471,10 @@ const runFiles = async (files, moduleOpts, io, flags) => {
       filePath: file,
       detectDualPackageHazard: hazardScope === 'project' ? 'off' : moduleOpts.detectDualPackageHazard
     };
+    const allowWrites = !flags.dryRun && !flags.list;
+    const writeInPlace = allowWrites && flags.inPlace;
     let writeTarget;
-    if (!flags.dryRun && !flags.list) {
+    if (allowWrites) {
       if (flags.inPlace) {
         perFileOpts.inPlace = true;
       } else if (outPath) {
@@ -421,8 +491,15 @@ const runFiles = async (files, moduleOpts, io, flags) => {
         };
       }
     }
-    const output = await (0, _module.transform)(file, perFileOpts);
+    if (moduleOpts.sourceMap && (writeTarget || writeInPlace)) {
+      perFileOpts.out = undefined;
+      perFileOpts.inPlace = false;
+    }
+    const transformed = await (0, _module.transform)(file, perFileOpts);
+    const output = typeof transformed === 'string' ? transformed : transformed.code;
+    const map = typeof transformed === 'string' ? null : transformed.map;
     const changed = output !== original;
+    let finalOutput = output;
     if (projectHazards) {
       const extras = projectHazards.get(file);
       if (extras?.length) diagnostics.push(...extras);
@@ -430,8 +507,24 @@ const runFiles = async (files, moduleOpts, io, flags) => {
     if (flags.list && changed) {
       logger.info(file);
     }
-    if (!flags.dryRun && !flags.list && !writeTarget && !perFileOpts.inPlace) {
-      io.stdout.write(output);
+    if (map && flags.sourceMapInline && !writeTarget && !writeInPlace) {
+      const mapUri = Buffer.from(JSON.stringify(map)).toString('base64');
+      finalOutput = `${output.replace(/\/\/# sourceMappingURL=.*/g, '').trimEnd()}\n//# sourceMappingURL=data:application/json;charset=utf-8;base64,${mapUri}\n`;
+    } else if (map && (writeTarget || writeInPlace)) {
+      const target = writeTarget ?? file;
+      const mapPath = `${target}.map`;
+      const mapFile = (0, _nodePath.basename)(mapPath);
+      map.file = (0, _nodePath.basename)(target);
+      const updated = `${output.replace(/\/\/# sourceMappingURL=.*/g, '').trimEnd()}\n//# sourceMappingURL=${mapFile}\n`;
+      await (0, _promises.writeFile)(mapPath, JSON.stringify(map));
+      if (writeTarget) {
+        await (0, _promises.writeFile)(writeTarget, updated);
+      } else if (writeInPlace) {
+        await (0, _promises.writeFile)(file, updated);
+      }
+    }
+    if (!flags.dryRun && !flags.list && !writeTarget && !writeInPlace) {
+      io.stdout.write(finalOutput);
     }
     results.push({
       filePath: file,
@@ -468,11 +561,21 @@ const runCli = async ({
   stdout = _nodeProcess.stdout,
   stderr = _nodeProcess.stderr
 } = {}) => {
+  const logger = makeLogger(stdout, stderr);
+  const {
+    argv: normalizedArgv,
+    sourceMapInline,
+    invalidSourceMapValue
+  } = normalizeSourceMapArgv(argv);
+  if (invalidSourceMapValue) {
+    logger.error(`Invalid --source-map value: ${invalidSourceMapValue}`);
+    return 2;
+  }
   const {
     values,
     positionals
   } = (0, _nodeUtil.parseArgs)({
-    args: argv,
+    args: normalizedArgv,
     allowPositionals: true,
     options: Object.fromEntries(optionsTable.map(opt => [opt.long, {
       type: opt.type,
@@ -481,7 +584,6 @@ const runCli = async ({
       } : {})
     }]))
   });
-  const logger = makeLogger(stdout, stderr);
   if (values.help) {
     stdout.write(buildHelp(stdout.isTTY ?? false));
     return 0;
@@ -492,6 +594,7 @@ const runCli = async ({
     return 0;
   }
   const moduleOpts = toModuleOptions(values);
+  if (sourceMapInline) moduleOpts.sourceMap = true;
   const cwd = moduleOpts.cwd ?? process.cwd();
   const allowStdout = positionals.length <= 1;
   const fromStdin = positionals.length === 0 || positionals.includes('-');
@@ -504,6 +607,10 @@ const runCli = async ({
   const list = Boolean(values.list);
   const summary = Boolean(values.summary);
   const json = Boolean(values.json);
+  if (sourceMapInline && (outDir || inPlace)) {
+    logger.error('Inline source maps are only supported when writing to stdout');
+    return 2;
+  }
   if (outDir && inPlace) {
     logger.error('Choose either --out-dir or --in-place, not both');
     return 2;
@@ -558,7 +665,8 @@ const runCli = async ({
       json,
       outDir,
       inPlace,
-      allowStdout
+      allowStdout,
+      sourceMapInline
     });
     if (typeof result.code === 'number' && result.code !== 0) return result.code;
     tasks.push(...result.results);

package/dist/cjs/format.cjs

@@ -3,7 +3,8 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.format = exports.dualPackageHazardDiagnostics = exports.collectDualPackageUsage = void 0;
+exports.dualPackageHazardDiagnostics = exports.collectDualPackageUsage = void 0;
+exports.format = format;
 var _nodePath = require("node:path");
 var _promises = require("node:fs/promises");
 var _magicString = _interopRequireDefault(require("magic-string"));
@@ -148,6 +149,9 @@ const describeDualPackage = pkgJson => {
     requireTarget
   };
 };
+const normalizeAllowlist = allowlist => {
+  return new Set([...(allowlist ?? [])].map(item => item.trim()).filter(item => item.length > 0));
+};
 const recordUsage = (usages, pkg, kind, spec, subpath, loc, filePath) => {
   const existing = usages.get(pkg) ?? {
     imports: [],
@@ -217,8 +221,10 @@ const dualPackageHazardDiagnostics = async params => {
     cwd
   } = params;
   const manifestCache = params.manifestCache ?? new Map();
+  const allowlist = normalizeAllowlist(params.hazardAllowlist);
   const diags = [];
   for (const [pkg, usage] of usages) {
+    if (allowlist.has(pkg)) continue;
     const hasImport = usage.imports.length > 0;
     const hasRequire = usage.requires.length > 0;
     const combined = [...usage.imports, ...usage.requires];
@@ -285,19 +291,14 @@ const detectDualPackageHazards = async params => {
     hazardLevel,
     filePath,
     cwd,
-    manifestCache
+    manifestCache,
+    hazardAllowlist: params.hazardAllowlist
   });
   for (const diag of diags) {
     diagOnce(diag.level, diag.code, diag.message, diag.loc);
   }
 };
-
-/**
- * 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, ast, opts) => {
+async function format(src, ast, opts) {
   const code = new _magicString.default(src);
   const exportsMeta = {
     hasExportsBeenReassigned: false,
@@ -346,7 +347,8 @@ const format = async (src, ast, opts) => {
       hazardLevel,
       filePath: opts.filePath,
       cwd: opts.cwd,
-      diagOnce
+      diagOnce,
+      hazardAllowlist: opts.dualPackageHazardAllowlist
     });
   }
   if (opts.target === 'module' && fullTransform) {
@@ -522,15 +524,15 @@ const format = async (src, ast, opts) => {
     code.prepend(prelude);
   }
   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`;
-      const setPromise = `const __setTla = target => {\n  if (!target) return;\n  const type = typeof target;\n  if (type !== 'object' && type !== 'function') return;\n  target.__tla = __tla;\n};\n`;
-      const attach = `__setTla(module.exports);\n__tla.then(resolved => __setTla(resolved), err => { throw err; });\n`;
-      return `${tlaPromise}${setPromise}${attach}`;
+      code.prepend('const __tla = (async () => {\n');
+      code.append('\nreturn module.exports;\n})();\n');
+      code.append('const __setTla = target => {\n  if (!target) return;\n  const type = typeof target;\n  if (type !== "object" && type !== "function") return;\n  target.__tla = __tla;\n};\n');
+      code.append('__setTla(module.exports);\n__tla.then(resolved => __setTla(resolved), err => { throw err; });\n');
+    } else {
+      code.prepend(';(async () => {\n');
+      code.append('\n})();\n');
     }
-    return `;(async () => {\n${body}\n})();\n`;
   }
-  return code.toString();
-};
-exports.format = format;
+  return opts.sourceMap ? code : code.toString();
+}

package/dist/cjs/format.d.cts

@@ -1,4 +1,5 @@
 import type { Node, ParseResult } from 'oxc-parser';
+import MagicString from 'magic-string';
 import type { Diagnostic, FormatterOptions } from './types.cjs';
 type HazardLevel = 'warning' | 'error';
 export type PackageUse = {
@@ -21,11 +22,10 @@ declare const dualPackageHazardDiagnostics: (params: {
     filePath?: string;
     cwd?: string;
     manifestCache?: Map<string, any | null>;
+    hazardAllowlist?: Iterable<string>;
 }) => Promise<Diagnostic[]>;
-/**
- * Node added support for import.meta.main.
- * Added in: v24.2.0, v22.18.0
- * @see https://nodejs.org/api/esm.html#importmetamain
- */
-declare const format: (src: string, ast: ParseResult, opts: FormatterOptions) => Promise<string>;
+declare function format(src: string, ast: ParseResult, opts: FormatterOptions & {
+    sourceMap: true;
+}): Promise<MagicString>;
+declare function format(src: string, ast: ParseResult, opts: FormatterOptions): Promise<string>;
 export { format, collectDualPackageUsage, dualPackageHazardDiagnostics };

package/dist/cjs/module.cjs

@@ -3,7 +3,8 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.transform = exports.collectProjectDualPackageHazards = void 0;
+exports.collectProjectDualPackageHazards = void 0;
+exports.transform = transform;
 var _nodePath = require("node:path");
 var _promises = require("node:fs/promises");
 var _specifier = require("./specifier.cjs");
@@ -170,8 +171,10 @@ const collectProjectDualPackageHazards = async (files, opts) => {
   const diags = await (0, _format.dualPackageHazardDiagnostics)({
     usages,
     hazardLevel,
+    filePath: opts.filePath,
     cwd: opts.cwd,
-    manifestCache
+    manifestCache,
+    hazardAllowlist: opts.dualPackageHazardAllowlist
   });
   const byFile = new Map();
   for (const diag of diags) {
@@ -199,17 +202,19 @@ const createDefaultOptions = () => ({
   detectCircularRequires: 'off',
   detectDualPackageHazard: 'warn',
   dualPackageHazardScope: 'file',
+  dualPackageHazardAllowlist: [],
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
   idiomaticExports: 'safe',
   importMetaPrelude: 'auto',
   topLevelAwait: 'error',
+  sourceMap: false,
   cwd: undefined,
   out: undefined,
   inPlace: false
 });
-const transform = async (filename, options) => {
+async function transform(filename, options) {
   const base = createDefaultOptions();
   const opts = options ? {
     ...base,
@@ -226,9 +231,19 @@ const transform = async (filename, options) => {
   const file = (0, _nodePath.resolve)(cwdBase, 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);
+  let sourceCode = null;
+  let source;
+  if (opts.sourceMap) {
+    sourceCode = await (0, _format.format)(code, ast, {
+      ...opts,
+      sourceMap: true
+    });
+    source = sourceCode.toString();
+  } else {
+    source = await (0, _format.format)(code, ast, opts);
+  }
   if (opts.rewriteSpecifier || appendMode !== 'off' || dirIndex) {
-    const code = await _specifier.specifier.updateSrc(source, (0, _lang.getLangFromExt)(filename), spec => {
+    const applyRewrite = spec => {
       if (spec.type === 'TemplateLiteral' && opts.rewriteTemplateLiterals === 'static-only') {
         const node = spec.node;
         if (node.expressions.length > 0) return;
@@ -238,8 +253,14 @@ const transform = async (filename, options) => {
       const baseValue = rewritten ?? normalized ?? spec.value;
       const appended = appendExtensionIfNeeded(spec, appendMode, dirIndex, baseValue);
       return appended ?? rewritten ?? normalized ?? undefined;
-    });
-    source = code;
+    };
+    if (opts.sourceMap && sourceCode) {
+      await _specifier.specifier.updateMagicString(sourceCode, code, ast, applyRewrite);
+      source = sourceCode.toString();
+    } else {
+      const rewritten = await _specifier.specifier.updateSrc(source, (0, _lang.getLangFromExt)(filename), applyRewrite);
+      source = rewritten;
+    }
   }
   if (detectCycles !== 'off' && opts.target === 'module' && opts.transformSyntax) {
     await detectCircularRequireGraph(file, detectCycles, dirIndex || 'index.js');
@@ -248,6 +269,17 @@ const transform = async (filename, options) => {
   if (outputPath) {
     await (0, _promises.writeFile)(outputPath, source);
   }
+  if (opts.sourceMap && sourceCode) {
+    const map = sourceCode.generateMap({
+      hires: true,
+      includeContent: true,
+      file: outputPath ?? filename,
+      source: opts.filePath ?? filename
+    });
+    return {
+      code: source,
+      map
+    };
+  }
   return source;
-};
-exports.transform = transform;
+}

package/dist/cjs/module.d.cts

@@ -1,4 +1,17 @@
 import type { ModuleOptions, Diagnostic } from './types.cjs';
+import type { SourceMap } from 'magic-string';
 declare const collectProjectDualPackageHazards: (files: string[], opts: ModuleOptions) => Promise<Map<string, Diagnostic[]>>;
-declare const transform: (filename: string, options?: ModuleOptions) => Promise<string>;
+declare function transform(filename: string, options: ModuleOptions & {
+    sourceMap: true;
+}): Promise<{
+    code: string;
+    map: SourceMap;
+}>;
+declare function transform(filename: string, options?: ModuleOptions & {
+    sourceMap?: false | undefined;
+}): Promise<string>;
+declare function transform(filename: string, options?: ModuleOptions): Promise<string | {
+    code: string;
+    map: SourceMap;
+}>;
 export { transform, collectProjectDualPackageHazards };

package/dist/cjs/specifier.cjs

@@ -20,8 +20,7 @@ const isBinaryExpression = node => {
 const isCallExpression = node => {
   return node.type === 'CallExpression' && node.callee !== undefined;
 };
-const formatSpecifiers = async (src, ast, cb) => {
-  const code = new _magicString.default(src);
+const formatSpecifiers = async (src, ast, cb, code = new _magicString.default(src)) => {
   const formatExpression = expression => {
     const node = isCallExpression(expression) ? expression.arguments[0] : expression.source;
     const {
@@ -235,7 +234,7 @@ const formatSpecifiers = async (src, ast, cb) => {
       }
     }
   });
-  return code.toString();
+  return code;
 };
 const isValidFilename = async filename => {
   let stats;
@@ -258,11 +257,17 @@ const specifier = exports.specifier = {
     }
     const src = (await (0, _promises.readFile)(filename)).toString();
     const ast = (0, _oxcParser.parseSync)(filename, src);
-    return await formatSpecifiers(src, ast, callback);
+    const code = await formatSpecifiers(src, ast, callback);
+    return code.toString();
   },
   async updateSrc(src, lang, callback) {
     const filename = lang === 'ts' ? 'file.ts' : lang === 'tsx' ? 'file.tsx' : lang === 'js' ? 'file.js' : 'file.jsx';
     const ast = (0, _oxcParser.parseSync)(filename, src);
-    return await formatSpecifiers(src, ast, callback);
+    const code = await formatSpecifiers(src, ast, callback);
+    return code.toString();
+  },
+  async updateMagicString(code, src, ast, callback) {
+    await formatSpecifiers(src, ast, callback, code);
+    return code;
   }
 };

package/dist/cjs/specifier.d.cts

@@ -1,4 +1,5 @@
-import type { ParserOptions, StringLiteral, TemplateLiteral, BinaryExpression, NewExpression, ImportDeclaration, ExportNamedDeclaration, ExportAllDeclaration, TSImportType, ImportExpression, CallExpression } from 'oxc-parser';
+import MagicString from 'magic-string';
+import type { ParserOptions, ParseResult, StringLiteral, TemplateLiteral, BinaryExpression, NewExpression, ImportDeclaration, ExportNamedDeclaration, ExportAllDeclaration, TSImportType, ImportExpression, CallExpression } from 'oxc-parser';
 type Spec = {
     type: 'StringLiteral' | 'TemplateLiteral' | 'BinaryExpression' | 'NewExpression';
     node: StringLiteral | TemplateLiteral | BinaryExpression | NewExpression;
@@ -11,6 +12,7 @@ type Callback = (spec: Spec) => string | void;
 declare const specifier: {
     update(path: string, callback: Callback): Promise<string>;
     updateSrc(src: string, lang: ParserOptions["lang"], callback: Callback): Promise<string>;
+    updateMagicString(code: MagicString, src: string, ast: ParseResult, callback: Callback): Promise<MagicString>;
 };
 export { specifier };
 export type { Spec, Callback };

package/dist/cjs/types.d.cts

@@ -6,6 +6,8 @@ export type ModuleOptions = {
     target: 'module' | 'commonjs';
     /** Explicit source type; auto infers from file extension. */
     sourceType?: 'auto' | 'module' | 'commonjs';
+    /** Emit a source map alongside the transformed code. */
+    sourceMap?: boolean;
     /**
      * Enable syntax transforms beyond parsing.
      * - true: full CJS↔ESM lowering/raising
@@ -38,6 +40,8 @@ export type ModuleOptions = {
     detectDualPackageHazard?: 'off' | 'warn' | 'error';
     /** Scope for dual package hazard detection. */
     dualPackageHazardScope?: 'file' | 'project';
+    /** Packages to ignore for dual package hazard diagnostics. */
+    dualPackageHazardAllowlist?: string[];
     /** Source used to provide require in ESM output. */
     requireSource?: 'builtin' | 'create-require';
     /** How to rewrite nested or non-hoistable require calls. */

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { stdin as defaultStdin, stdout as defaultStdout, stderr as defaultStderr } from 'node:process';
 import { parseArgs } from 'node:util';
-import { readFile, mkdir } from 'node:fs/promises';
-import { dirname, resolve, relative, join } from 'node:path';
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve, relative, join, basename } from 'node:path';
 import { glob } from 'glob';
 import { transform, collectProjectDualPackageHazards } from './module.js';
 import { parse } from './parse.js';
@@ -26,12 +26,14 @@ const defaultOptions = {
   detectCircularRequires: 'off',
   detectDualPackageHazard: 'warn',
   dualPackageHazardScope: 'file',
+  dualPackageHazardAllowlist: [],
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
   idiomaticExports: 'safe',
   importMetaPrelude: 'auto',
   topLevelAwait: 'error',
+  sourceMap: false,
   cwd: undefined,
   out: undefined,
   inPlace: false
@@ -157,6 +159,11 @@ const optionsTable = [{
   short: undefined,
   type: 'string',
   desc: 'Scope for dual package hazard detection (file|project)'
+}, {
+  long: 'dual-package-hazard-allowlist',
+  short: undefined,
+  type: 'string',
+  desc: 'Comma-separated packages to ignore for dual package hazard checks'
 }, {
   long: 'top-level-await',
   short: 'a',
@@ -177,6 +184,11 @@ const optionsTable = [{
   short: 'm',
   type: 'string',
   desc: 'Emit import.meta prelude (off|auto|on)'
+}, {
+  long: 'source-map',
+  short: undefined,
+  type: 'boolean',
+  desc: 'Emit a source map alongside transformed output (use --source-map=inline for stdout)'
 }, {
   long: 'nested-require-strategy',
   short: 'n',
@@ -275,12 +287,17 @@ const parseAppendDirectoryIndex = value => {
   if (value === 'false') return false;
   return value;
 };
+const parseAllowlist = value => {
+  const values = value === undefined ? [] : Array.isArray(value) ? value : [value];
+  return values.flatMap(entry => String(entry).split(',')).map(item => item.trim()).filter(Boolean);
+};
 const toModuleOptions = values => {
   const target = parseEnum(values.target, ['module', 'commonjs']) ?? defaultOptions.target;
   const transformSyntax = parseTransformSyntax(values['transform-syntax']);
   const rewriteTemplateLiterals = parseEnum(values['rewrite-template-literals'], ['allow', 'static-only']) ?? defaultOptions.rewriteTemplateLiterals;
   const appendJsExtension = parseEnum(values['append-js-extension'], ['off', 'relative-only', 'all']);
   const appendDirectoryIndex = parseAppendDirectoryIndex(values['append-directory-index']);
+  const dualPackageHazardAllowlist = parseAllowlist(values['dual-package-hazard-allowlist']);
   const opts = {
     ...defaultOptions,
     target,
@@ -292,6 +309,7 @@ const toModuleOptions = values => {
     detectCircularRequires: parseEnum(values['detect-circular-requires'], ['off', 'warn', 'error']) ?? defaultOptions.detectCircularRequires,
     detectDualPackageHazard: parseEnum(values['detect-dual-package-hazard'], ['off', 'warn', 'error']) ?? defaultOptions.detectDualPackageHazard,
     dualPackageHazardScope: parseEnum(values['dual-package-hazard-scope'], ['file', 'project']) ?? defaultOptions.dualPackageHazardScope,
+    dualPackageHazardAllowlist,
     topLevelAwait: parseEnum(values['top-level-await'], ['error', 'wrap', 'preserve']) ?? defaultOptions.topLevelAwait,
     cjsDefault: parseEnum(values['cjs-default'], ['module-exports', 'auto', 'none']) ?? defaultOptions.cjsDefault,
     idiomaticExports: parseEnum(values['idiomatic-exports'], ['off', 'safe', 'aggressive']) ?? defaultOptions.idiomaticExports,
@@ -299,6 +317,7 @@ const toModuleOptions = values => {
     nestedRequireStrategy: parseEnum(values['nested-require-strategy'], ['create-require', 'dynamic-import']) ?? defaultOptions.nestedRequireStrategy,
     requireMainStrategy: parseEnum(values['require-main-strategy'], ['import-meta-main', 'realpath']) ?? defaultOptions.requireMainStrategy,
     liveBindings: parseEnum(values['live-bindings'], ['strict', 'loose', 'off']) ?? defaultOptions.liveBindings,
+    sourceMap: Boolean(values['source-map']),
     cwd: values.cwd ? resolve(String(values.cwd)) : defaultOptions.cwd
   };
   return opts;
@@ -310,6 +329,55 @@ const readStdin = async stdin => {
   }
   return Buffer.concat(chunks).toString('utf8');
 };
+const normalizeSourceMapArgv = argv => {
+  let sourceMapInline = false;
+  let invalidSourceMapValue = null;
+  const normalized = [];
+  const recordInvalid = value => {
+    if (!invalidSourceMapValue) invalidSourceMapValue = value;
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--source-map') {
+      const next = argv[i + 1];
+      if (next === 'inline') {
+        sourceMapInline = true;
+        normalized.push('--source-map');
+        i += 1;
+        continue;
+      }
+      if (next === 'true' || next === 'false') {
+        normalized.push(`--source-map=${next}`);
+        i += 1;
+        continue;
+      }
+    }
+    if (arg.startsWith('--source-map=')) {
+      const value = arg.slice('--source-map='.length);
+      if (value === 'inline') {
+        sourceMapInline = true;
+        normalized.push('--source-map');
+        continue;
+      }
+      if (value === 'true' || value === 'false') {
+        normalized.push(arg);
+        continue;
+      }
+      recordInvalid(value);
+      continue;
+    }
+    if (arg === '--source-map' && argv[i + 1] && argv[i + 1].startsWith('--')) {
+      normalized.push('--source-map');
+      continue;
+    }
+    normalized.push(arg);
+  }
+  return {
+    argv: normalized,
+    sourceMapInline,
+    invalidSourceMapValue
+  };
+};
 const expandFiles = async (patterns, cwd, ignore) => {
   const files = new Set();
   for (const pattern of patterns) {
@@ -397,8 +465,10 @@ const runFiles = async (files, moduleOpts, io, flags) => {
       filePath: file,
       detectDualPackageHazard: hazardScope === 'project' ? 'off' : moduleOpts.detectDualPackageHazard
     };
+    const allowWrites = !flags.dryRun && !flags.list;
+    const writeInPlace = allowWrites && flags.inPlace;
     let writeTarget;
-    if (!flags.dryRun && !flags.list) {
+    if (allowWrites) {
       if (flags.inPlace) {
         perFileOpts.inPlace = true;
       } else if (outPath) {
@@ -415,8 +485,15 @@ const runFiles = async (files, moduleOpts, io, flags) => {
         };
       }
     }
-    const output = await transform(file, perFileOpts);
+    if (moduleOpts.sourceMap && (writeTarget || writeInPlace)) {
+      perFileOpts.out = undefined;
+      perFileOpts.inPlace = false;
+    }
+    const transformed = await transform(file, perFileOpts);
+    const output = typeof transformed === 'string' ? transformed : transformed.code;
+    const map = typeof transformed === 'string' ? null : transformed.map;
     const changed = output !== original;
+    let finalOutput = output;
     if (projectHazards) {
       const extras = projectHazards.get(file);
       if (extras?.length) diagnostics.push(...extras);
@@ -424,8 +501,24 @@ const runFiles = async (files, moduleOpts, io, flags) => {
     if (flags.list && changed) {
       logger.info(file);
     }
-    if (!flags.dryRun && !flags.list && !writeTarget && !perFileOpts.inPlace) {
-      io.stdout.write(output);
+    if (map && flags.sourceMapInline && !writeTarget && !writeInPlace) {
+      const mapUri = Buffer.from(JSON.stringify(map)).toString('base64');
+      finalOutput = `${output.replace(/\/\/# sourceMappingURL=.*/g, '').trimEnd()}\n//# sourceMappingURL=data:application/json;charset=utf-8;base64,${mapUri}\n`;
+    } else if (map && (writeTarget || writeInPlace)) {
+      const target = writeTarget ?? file;
+      const mapPath = `${target}.map`;
+      const mapFile = basename(mapPath);
+      map.file = basename(target);
+      const updated = `${output.replace(/\/\/# sourceMappingURL=.*/g, '').trimEnd()}\n//# sourceMappingURL=${mapFile}\n`;
+      await writeFile(mapPath, JSON.stringify(map));
+      if (writeTarget) {
+        await writeFile(writeTarget, updated);
+      } else if (writeInPlace) {
+        await writeFile(file, updated);
+      }
+    }
+    if (!flags.dryRun && !flags.list && !writeTarget && !writeInPlace) {
+      io.stdout.write(finalOutput);
     }
     results.push({
       filePath: file,
@@ -462,11 +555,21 @@ const runCli = async ({
   stdout = defaultStdout,
   stderr = defaultStderr
 } = {}) => {
+  const logger = makeLogger(stdout, stderr);
+  const {
+    argv: normalizedArgv,
+    sourceMapInline,
+    invalidSourceMapValue
+  } = normalizeSourceMapArgv(argv);
+  if (invalidSourceMapValue) {
+    logger.error(`Invalid --source-map value: ${invalidSourceMapValue}`);
+    return 2;
+  }
   const {
     values,
     positionals
   } = parseArgs({
-    args: argv,
+    args: normalizedArgv,
     allowPositionals: true,
     options: Object.fromEntries(optionsTable.map(opt => [opt.long, {
       type: opt.type,
@@ -475,7 +578,6 @@ const runCli = async ({
       } : {})
     }]))
   });
-  const logger = makeLogger(stdout, stderr);
   if (values.help) {
     stdout.write(buildHelp(stdout.isTTY ?? false));
     return 0;
@@ -486,6 +588,7 @@ const runCli = async ({
     return 0;
   }
   const moduleOpts = toModuleOptions(values);
+  if (sourceMapInline) moduleOpts.sourceMap = true;
   const cwd = moduleOpts.cwd ?? process.cwd();
   const allowStdout = positionals.length <= 1;
   const fromStdin = positionals.length === 0 || positionals.includes('-');
@@ -498,6 +601,10 @@ const runCli = async ({
   const list = Boolean(values.list);
   const summary = Boolean(values.summary);
   const json = Boolean(values.json);
+  if (sourceMapInline && (outDir || inPlace)) {
+    logger.error('Inline source maps are only supported when writing to stdout');
+    return 2;
+  }
   if (outDir && inPlace) {
     logger.error('Choose either --out-dir or --in-place, not both');
     return 2;
@@ -552,7 +659,8 @@ const runCli = async ({
       json,
       outDir,
       inPlace,
-      allowStdout
+      allowStdout,
+      sourceMapInline
     });
     if (typeof result.code === 'number' && result.code !== 0) return result.code;
     tasks.push(...result.results);

package/dist/format.d.ts

@@ -1,4 +1,5 @@
 import type { Node, ParseResult } from 'oxc-parser';
+import MagicString from 'magic-string';
 import type { Diagnostic, FormatterOptions } from './types.js';
 type HazardLevel = 'warning' | 'error';
 export type PackageUse = {
@@ -21,11 +22,10 @@ declare const dualPackageHazardDiagnostics: (params: {
     filePath?: string;
     cwd?: string;
     manifestCache?: Map<string, any | null>;
+    hazardAllowlist?: Iterable<string>;
 }) => Promise<Diagnostic[]>;
-/**
- * Node added support for import.meta.main.
- * Added in: v24.2.0, v22.18.0
- * @see https://nodejs.org/api/esm.html#importmetamain
- */
-declare const format: (src: string, ast: ParseResult, opts: FormatterOptions) => Promise<string>;
+declare function format(src: string, ast: ParseResult, opts: FormatterOptions & {
+    sourceMap: true;
+}): Promise<MagicString>;
+declare function format(src: string, ast: ParseResult, opts: FormatterOptions): Promise<string>;
 export { format, collectDualPackageUsage, dualPackageHazardDiagnostics };

package/dist/format.js

@@ -141,6 +141,9 @@ const describeDualPackage = pkgJson => {
     requireTarget
   };
 };
+const normalizeAllowlist = allowlist => {
+  return new Set([...(allowlist ?? [])].map(item => item.trim()).filter(item => item.length > 0));
+};
 const recordUsage = (usages, pkg, kind, spec, subpath, loc, filePath) => {
   const existing = usages.get(pkg) ?? {
     imports: [],
@@ -209,8 +212,10 @@ const dualPackageHazardDiagnostics = async params => {
     cwd
   } = params;
   const manifestCache = params.manifestCache ?? new Map();
+  const allowlist = normalizeAllowlist(params.hazardAllowlist);
   const diags = [];
   for (const [pkg, usage] of usages) {
+    if (allowlist.has(pkg)) continue;
     const hasImport = usage.imports.length > 0;
     const hasRequire = usage.requires.length > 0;
     const combined = [...usage.imports, ...usage.requires];
@@ -276,19 +281,14 @@ const detectDualPackageHazards = async params => {
     hazardLevel,
     filePath,
     cwd,
-    manifestCache
+    manifestCache,
+    hazardAllowlist: params.hazardAllowlist
   });
   for (const diag of diags) {
     diagOnce(diag.level, diag.code, diag.message, diag.loc);
   }
 };
-
-/**
- * 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, ast, opts) => {
+async function format(src, ast, opts) {
   const code = new MagicString(src);
   const exportsMeta = {
     hasExportsBeenReassigned: false,
@@ -337,7 +337,8 @@ const format = async (src, ast, opts) => {
       hazardLevel,
       filePath: opts.filePath,
       cwd: opts.cwd,
-      diagOnce
+      diagOnce,
+      hazardAllowlist: opts.dualPackageHazardAllowlist
     });
   }
   if (opts.target === 'module' && fullTransform) {
@@ -513,15 +514,16 @@ const format = async (src, ast, opts) => {
     code.prepend(prelude);
   }
   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`;
-      const setPromise = `const __setTla = target => {\n  if (!target) return;\n  const type = typeof target;\n  if (type !== 'object' && type !== 'function') return;\n  target.__tla = __tla;\n};\n`;
-      const attach = `__setTla(module.exports);\n__tla.then(resolved => __setTla(resolved), err => { throw err; });\n`;
-      return `${tlaPromise}${setPromise}${attach}`;
+      code.prepend('const __tla = (async () => {\n');
+      code.append('\nreturn module.exports;\n})();\n');
+      code.append('const __setTla = target => {\n  if (!target) return;\n  const type = typeof target;\n  if (type !== "object" && type !== "function") return;\n  target.__tla = __tla;\n};\n');
+      code.append('__setTla(module.exports);\n__tla.then(resolved => __setTla(resolved), err => { throw err; });\n');
+    } else {
+      code.prepend(';(async () => {\n');
+      code.append('\n})();\n');
     }
-    return `;(async () => {\n${body}\n})();\n`;
   }
-  return code.toString();
-};
+  return opts.sourceMap ? code : code.toString();
+}
 export { format, collectDualPackageUsage, dualPackageHazardDiagnostics };

package/dist/module.d.ts

@@ -1,4 +1,17 @@
 import type { ModuleOptions, Diagnostic } from './types.js';
+import type { SourceMap } from 'magic-string';
 declare const collectProjectDualPackageHazards: (files: string[], opts: ModuleOptions) => Promise<Map<string, Diagnostic[]>>;
-declare const transform: (filename: string, options?: ModuleOptions) => Promise<string>;
+declare function transform(filename: string, options: ModuleOptions & {
+    sourceMap: true;
+}): Promise<{
+    code: string;
+    map: SourceMap;
+}>;
+declare function transform(filename: string, options?: ModuleOptions & {
+    sourceMap?: false | undefined;
+}): Promise<string>;
+declare function transform(filename: string, options?: ModuleOptions): Promise<string | {
+    code: string;
+    map: SourceMap;
+}>;
 export { transform, collectProjectDualPackageHazards };

package/dist/module.js

@@ -167,8 +167,10 @@ const collectProjectDualPackageHazards = async (files, opts) => {
   const diags = await dualPackageHazardDiagnostics({
     usages,
     hazardLevel,
+    filePath: opts.filePath,
     cwd: opts.cwd,
-    manifestCache
+    manifestCache,
+    hazardAllowlist: opts.dualPackageHazardAllowlist
   });
   const byFile = new Map();
   for (const diag of diags) {
@@ -195,17 +197,19 @@ const createDefaultOptions = () => ({
   detectCircularRequires: 'off',
   detectDualPackageHazard: 'warn',
   dualPackageHazardScope: 'file',
+  dualPackageHazardAllowlist: [],
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
   idiomaticExports: 'safe',
   importMetaPrelude: 'auto',
   topLevelAwait: 'error',
+  sourceMap: false,
   cwd: undefined,
   out: undefined,
   inPlace: false
 });
-const transform = async (filename, options) => {
+async function transform(filename, options) {
   const base = createDefaultOptions();
   const opts = options ? {
     ...base,
@@ -222,9 +226,19 @@ const transform = async (filename, options) => {
   const file = resolve(cwdBase, filename);
   const code = (await readFile(file)).toString();
   const ast = parse(filename, code);
-  let source = await format(code, ast, opts);
+  let sourceCode = null;
+  let source;
+  if (opts.sourceMap) {
+    sourceCode = await format(code, ast, {
+      ...opts,
+      sourceMap: true
+    });
+    source = sourceCode.toString();
+  } else {
+    source = await format(code, ast, opts);
+  }
   if (opts.rewriteSpecifier || appendMode !== 'off' || dirIndex) {
-    const code = await specifier.updateSrc(source, getLangFromExt(filename), spec => {
+    const applyRewrite = spec => {
       if (spec.type === 'TemplateLiteral' && opts.rewriteTemplateLiterals === 'static-only') {
         const node = spec.node;
         if (node.expressions.length > 0) return;
@@ -234,8 +248,14 @@ const transform = async (filename, options) => {
       const baseValue = rewritten ?? normalized ?? spec.value;
       const appended = appendExtensionIfNeeded(spec, appendMode, dirIndex, baseValue);
       return appended ?? rewritten ?? normalized ?? undefined;
-    });
-    source = code;
+    };
+    if (opts.sourceMap && sourceCode) {
+      await specifier.updateMagicString(sourceCode, code, ast, applyRewrite);
+      source = sourceCode.toString();
+    } else {
+      const rewritten = await specifier.updateSrc(source, getLangFromExt(filename), applyRewrite);
+      source = rewritten;
+    }
   }
   if (detectCycles !== 'off' && opts.target === 'module' && opts.transformSyntax) {
     await detectCircularRequireGraph(file, detectCycles, dirIndex || 'index.js');
@@ -244,6 +264,18 @@ const transform = async (filename, options) => {
   if (outputPath) {
     await writeFile(outputPath, source);
   }
+  if (opts.sourceMap && sourceCode) {
+    const map = sourceCode.generateMap({
+      hires: true,
+      includeContent: true,
+      file: outputPath ?? filename,
+      source: opts.filePath ?? filename
+    });
+    return {
+      code: source,
+      map
+    };
+  }
   return source;
-};
+}
 export { transform, collectProjectDualPackageHazards };

package/dist/specifier.d.ts

@@ -1,4 +1,5 @@
-import type { ParserOptions, StringLiteral, TemplateLiteral, BinaryExpression, NewExpression, ImportDeclaration, ExportNamedDeclaration, ExportAllDeclaration, TSImportType, ImportExpression, CallExpression } from 'oxc-parser';
+import MagicString from 'magic-string';
+import type { ParserOptions, ParseResult, StringLiteral, TemplateLiteral, BinaryExpression, NewExpression, ImportDeclaration, ExportNamedDeclaration, ExportAllDeclaration, TSImportType, ImportExpression, CallExpression } from 'oxc-parser';
 type Spec = {
     type: 'StringLiteral' | 'TemplateLiteral' | 'BinaryExpression' | 'NewExpression';
     node: StringLiteral | TemplateLiteral | BinaryExpression | NewExpression;
@@ -11,6 +12,7 @@ type Callback = (spec: Spec) => string | void;
 declare const specifier: {
     update(path: string, callback: Callback): Promise<string>;
     updateSrc(src: string, lang: ParserOptions["lang"], callback: Callback): Promise<string>;
+    updateMagicString(code: MagicString, src: string, ast: ParseResult, callback: Callback): Promise<MagicString>;
 };
 export { specifier };
 export type { Spec, Callback };

package/dist/specifier.js

@@ -13,8 +13,7 @@ const isBinaryExpression = node => {
 const isCallExpression = node => {
   return node.type === 'CallExpression' && node.callee !== undefined;
 };
-const formatSpecifiers = async (src, ast, cb) => {
-  const code = new MagicString(src);
+const formatSpecifiers = async (src, ast, cb, code = new MagicString(src)) => {
   const formatExpression = expression => {
     const node = isCallExpression(expression) ? expression.arguments[0] : expression.source;
     const {
@@ -228,7 +227,7 @@ const formatSpecifiers = async (src, ast, cb) => {
       }
     }
   });
-  return code.toString();
+  return code;
 };
 const isValidFilename = async filename => {
   let stats;
@@ -251,12 +250,18 @@ const specifier = {
     }
     const src = (await readFile(filename)).toString();
     const ast = parseSync(filename, src);
-    return await formatSpecifiers(src, ast, callback);
+    const code = await formatSpecifiers(src, ast, callback);
+    return code.toString();
   },
   async updateSrc(src, lang, callback) {
     const filename = lang === 'ts' ? 'file.ts' : lang === 'tsx' ? 'file.tsx' : lang === 'js' ? 'file.js' : 'file.jsx';
     const ast = parseSync(filename, src);
-    return await formatSpecifiers(src, ast, callback);
+    const code = await formatSpecifiers(src, ast, callback);
+    return code.toString();
+  },
+  async updateMagicString(code, src, ast, callback) {
+    await formatSpecifiers(src, ast, callback, code);
+    return code;
   }
 };
 export { specifier };

package/dist/types.d.ts

@@ -6,6 +6,8 @@ export type ModuleOptions = {
     target: 'module' | 'commonjs';
     /** Explicit source type; auto infers from file extension. */
     sourceType?: 'auto' | 'module' | 'commonjs';
+    /** Emit a source map alongside the transformed code. */
+    sourceMap?: boolean;
     /**
      * Enable syntax transforms beyond parsing.
      * - true: full CJS↔ESM lowering/raising
@@ -38,6 +40,8 @@ export type ModuleOptions = {
     detectDualPackageHazard?: 'off' | 'warn' | 'error';
     /** Scope for dual package hazard detection. */
     dualPackageHazardScope?: 'file' | 'project';
+    /** Packages to ignore for dual package hazard diagnostics. */
+    dualPackageHazardAllowlist?: string[];
     /** Source used to provide require in ESM output. */
     requireSource?: 'builtin' | 'create-require';
     /** How to rewrite nested or non-hoistable require calls. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/module",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Bidirectional transform for ES modules and CommonJS.",
   "type": "module",
   "main": "dist/module.js",