@knighted/module 1.4.0 → 1.5.0-rc.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
@@ -167,6 +168,7 @@ type ModuleOptions = {
 - `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

@@ -38,6 +38,7 @@ const defaultOptions = {
   idiomaticExports: 'safe',
   importMetaPrelude: 'auto',
   topLevelAwait: 'error',
+  sourceMap: false,
   cwd: undefined,
   out: undefined,
   inPlace: false
@@ -183,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',
@@ -305,6 +311,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 +323,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 +459,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 +479,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 +495,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 +549,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 +572,6 @@ const runCli = async ({
       } : {})
     }]))
   });
-  const logger = makeLogger(stdout, stderr);
   if (values.help) {
     stdout.write(buildHelp(stdout.isTTY ?? false));
     return 0;
@@ -492,6 +582,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 +595,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 +653,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"));
@@ -291,13 +292,7 @@ const detectDualPackageHazards = async params => {
     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,
@@ -522,15 +517,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 = {
@@ -22,10 +23,8 @@ declare const dualPackageHazardDiagnostics: (params: {
     cwd?: string;
     manifestCache?: Map<string, any | null>;
 }) => 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");
@@ -205,11 +206,12 @@ const createDefaultOptions = () => ({
   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 +228,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 +250,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 +266,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

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';
@@ -32,6 +32,7 @@ const defaultOptions = {
   idiomaticExports: 'safe',
   importMetaPrelude: 'auto',
   topLevelAwait: 'error',
+  sourceMap: false,
   cwd: undefined,
   out: undefined,
   inPlace: false
@@ -177,6 +178,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',
@@ -299,6 +305,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 +317,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 +453,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 +473,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 +489,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 +543,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 +566,6 @@ const runCli = async ({
       } : {})
     }]))
   });
-  const logger = makeLogger(stdout, stderr);
   if (values.help) {
     stdout.write(buildHelp(stdout.isTTY ?? false));
     return 0;
@@ -486,6 +576,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 +589,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 +647,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 = {
@@ -22,10 +23,8 @@ declare const dualPackageHazardDiagnostics: (params: {
     cwd?: string;
     manifestCache?: Map<string, any | null>;
 }) => 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

@@ -282,13 +282,7 @@ const detectDualPackageHazards = async params => {
     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,
@@ -513,15 +507,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

@@ -201,11 +201,12 @@ const createDefaultOptions = () => ({
   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 +223,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 +245,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 +261,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

package/package.json

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