@knighted/module 1.2.0 → 1.3.0-rc.0

package/README.md

@@ -16,6 +16,7 @@ Highlights
 - Configurable lowering modes: full syntax transforms or globals-only.
 - Specifier tools: add extensions, add directory indexes, or map with a custom callback.
 - Output control: write to disk (`out`/`inPlace`) or return the transformed string.
+- CLI: `dub` for batch transforms, dry-run/list/summary, stdin/stdout, and colorized diagnostics. See [docs/cli.md](docs/cli.md).
 
 > [!IMPORTANT]  
 > All parsing logic is applied under the assumption the code is in [strict mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode) which [modules run under by default](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#other_differences_between_modules_and_classic_scripts).
@@ -143,7 +144,7 @@ type ModuleOptions = {
 ### Behavior notes (defaults in parentheses)
 
 - `target` (`commonjs`): output module system.
-- `transformSyntax` (true): enable/disable the ESM↔CJS lowering pass; set to `'globals-only'` to rewrite module globals (`import.meta.*`, `__dirname`, `__filename`, `require.main` shims) while leaving import/export syntax untouched. In `'globals-only'`, no helpers are injected (e.g., `__requireResolve`), `require.resolve` rewrites to `import.meta.resolve`, and `idiomaticExports` is skipped. See [globals-only](#globals-only-scope).
+- `transformSyntax` (`true`): enable/disable the ESM↔CJS lowering pass; set to `'globals-only'` to rewrite module globals (`import.meta.*`, `__dirname`, `__filename`, `require.main` shims) while leaving import/export syntax untouched. In `'globals-only'`, no helpers are injected (e.g., `__requireResolve`), `require.resolve` rewrites to `import.meta.resolve`, and `idiomaticExports` is skipped. See [globals-only](docs/globals-only.md).
 - `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).
@@ -159,7 +160,7 @@ type ModuleOptions = {
 - `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`: write the transformed code to a file; otherwise the function returns the transformed string only.
+- `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.
 - `cwd` (`process.cwd()`): Base directory used to resolve relative `out` paths.
 
 > [!NOTE]
@@ -170,13 +171,6 @@ See [docs/esm-to-cjs.md](docs/esm-to-cjs.md) for deeper notes on live bindings,
 > [!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`.
 
-### Globals-only scope
-
-- Rewrites module globals (`import.meta.*`, `__dirname`, `__filename`, `require.main` shims) for the target side.
-- Optional specifier rewrites still run (`rewriteSpecifier`, `appendJsExtension`, `appendDirectoryIndex`).
-- Leaves imports/exports and interop untouched (no export bag, no idiomaticExports, no live-binding synthesis, no helpers like `__requireResolve`).
-- CJS→ESM: `require.resolve` maps to `import.meta.resolve` (URL return, ESM resolver) and may differ from CJS resolution. ESM→CJS: `import.meta` maps to CJS globals; no import lowering.
-
 ### Diagnostics callback example
 
 Pass a `diagnostics` callback to surface CJS→ESM edge cases (mixed `module.exports`/`exports`, top-level `return`, legacy `require.cache`/`require.extensions`, live-binding reassignments, string-literal export names):
@@ -213,20 +207,9 @@ TypeScript reports asymmetric module-global errors (e.g., `import.meta` in CJS,
 
 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`
+```bash
+dub -t commonjs "src/**/*.{ts,js,mts,cts}" --ignore node_modules/** --transform-syntax globals-only --in-place
+tsc
 ```
 
-This pre-`tsc` step removes the flagged globals in the compiled orientation; runtime semantics still match the target build.
+This pre-`tsc` step rewrites globals-only (keeps import/export syntax) so the TypeScript checker sees already-rewritten sources; runtime semantics still match the target build.

package/dist/cjs/cli.cjs

@@ -0,0 +1,553 @@
+#!/usr/bin/env node
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.runCli = void 0;
+var _nodeProcess = require("node:process");
+var _nodeUtil = require("node:util");
+var _promises = require("node:fs/promises");
+var _nodePath = require("node:path");
+var _nodeModule = require("node:module");
+var _glob = require("glob");
+var _module = require("./module.cjs");
+var _parse = require("./parse.cjs");
+var _format = require("./format.cjs");
+var _specifier = require("./specifier.cjs");
+var _lang = require("./utils/lang.cjs");
+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',
+  idiomaticExports: 'safe',
+  importMetaPrelude: 'auto',
+  topLevelAwait: 'error',
+  cwd: undefined,
+  out: undefined,
+  inPlace: false
+};
+const icons = {
+  info: 'i',
+  warn: '⚠',
+  error: '✖',
+  success: '✔'
+};
+const codes = {
+  reset: '\u001b[0m',
+  bold: '\u001b[1m',
+  dim: '\u001b[2m',
+  red: '\u001b[31m',
+  yellow: '\u001b[33m',
+  green: '\u001b[32m',
+  cyan: '\u001b[36m'
+};
+const colorize = enabled => {
+  if (!enabled) {
+    return {
+      bold: v => v,
+      dim: v => v,
+      red: v => v,
+      yellow: v => v,
+      green: v => v,
+      cyan: v => v
+    };
+  }
+  const wrap = code => v => `${code}${v}${codes.reset}`;
+  return {
+    bold: wrap(codes.bold),
+    dim: wrap(codes.dim),
+    red: wrap(codes.red),
+    yellow: wrap(codes.yellow),
+    green: wrap(codes.green),
+    cyan: wrap(codes.cyan)
+  };
+};
+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 collapseSpecifier = value => value.replace(/['"`+)\s]|new String\(/g, '');
+const appendExtensionIfNeeded = (value, mode, dirIndex) => {
+  if (mode === 'off') 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)sx?([)'"]*)?$/, `$1${rewriteSpecifier}$2`);
+  }
+};
+const normalizeBuiltinSpecifier = value => {
+  const collapsed = collapseSpecifier(value);
+  if (!collapsed) return;
+  const specPart = collapsed.split(/[?#]/)[0] ?? '';
+  if (/^(?:\.\.?(?:\/)|\/)/.test(specPart)) return;
+  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 optionsTable = [{
+  long: 'target',
+  short: 't',
+  type: 'string',
+  desc: 'Output format (module|commonjs)'
+}, {
+  long: 'transform-syntax',
+  short: 'x',
+  type: 'string',
+  desc: 'Syntax transforms (true|false|globals-only)'
+}, {
+  long: 'rewrite-specifier',
+  short: 'r',
+  type: 'string',
+  desc: 'Rewrite import specifiers (.js/.mjs/.cjs/.ts/.mts/.cts)'
+}, {
+  long: 'append-js-extension',
+  short: 'j',
+  type: 'string',
+  desc: 'Append .js to relative imports (off|relative-only|all)'
+}, {
+  long: 'append-directory-index',
+  short: 'i',
+  type: 'string',
+  desc: 'Append directory index (e.g. index.js) or false'
+}, {
+  long: 'detect-circular-requires',
+  short: 'c',
+  type: 'string',
+  desc: 'Warn/error on circular require (off|warn|error)'
+}, {
+  long: 'top-level-await',
+  short: 'a',
+  type: 'string',
+  desc: 'TLA handling (error|wrap|preserve)'
+}, {
+  long: 'cjs-default',
+  short: 'd',
+  type: 'string',
+  desc: 'Default interop (module-exports|auto|none)'
+}, {
+  long: 'idiomatic-exports',
+  short: 'e',
+  type: 'string',
+  desc: 'Emit idiomatic exports when safe (off|safe|aggressive)'
+}, {
+  long: 'import-meta-prelude',
+  short: 'm',
+  type: 'string',
+  desc: 'Emit import.meta prelude (off|auto|on)'
+}, {
+  long: 'nested-require-strategy',
+  short: 'n',
+  type: 'string',
+  desc: 'Rewrite nested require (create-require|dynamic-import)'
+}, {
+  long: 'require-main-strategy',
+  short: 'R',
+  type: 'string',
+  desc: 'Detect main (import-meta-main|realpath)'
+}, {
+  long: 'live-bindings',
+  short: 'l',
+  type: 'string',
+  desc: 'Live binding strategy (strict|loose|off)'
+}, {
+  long: 'out-dir',
+  short: 'o',
+  type: 'string',
+  desc: 'Write outputs to a directory mirror'
+}, {
+  long: 'in-place',
+  short: 'p',
+  type: 'boolean',
+  desc: 'Rewrite files in place'
+}, {
+  long: 'dry-run',
+  short: 'y',
+  type: 'boolean',
+  desc: 'Do not write files; report planned changes'
+}, {
+  long: 'list',
+  short: 'L',
+  type: 'boolean',
+  desc: 'List files that would change'
+}, {
+  long: 'summary',
+  short: 's',
+  type: 'boolean',
+  desc: 'Print a summary of work performed'
+}, {
+  long: 'json',
+  short: 'J',
+  type: 'boolean',
+  desc: 'Emit machine-readable JSON summary/diagnostics'
+}, {
+  long: 'cwd',
+  short: 'C',
+  type: 'string',
+  desc: 'Working directory for resolving files/out paths'
+}, {
+  long: 'stdin-filename',
+  short: 'f',
+  type: 'string',
+  desc: 'Virtual filename when reading from stdin'
+}, {
+  long: 'ignore',
+  short: 'g',
+  type: 'string',
+  desc: 'Glob pattern(s) to ignore (repeatable)'
+}, {
+  long: 'help',
+  short: 'h',
+  type: 'boolean',
+  desc: 'Show help'
+}, {
+  long: 'version',
+  short: 'v',
+  type: 'boolean',
+  desc: 'Show version'
+}];
+const buildHelp = enableColor => {
+  const c = colorize(enableColor);
+  const maxFlagLength = Math.max(...optionsTable.map(opt => `  -${opt.short}, --${opt.long}`.length));
+  const lines = [`${c.bold('Usage:')} dub [options] <files...>`, '', 'Examples:', '  dub -t module src/index.cjs --out-dir dist', '  dub -t commonjs src/**/*.mjs -p', '  cat input.cjs | dub -t module --stdin-filename input.cjs', '', 'Options:'];
+  for (const opt of optionsTable) {
+    const flag = `  -${opt.short}, --${opt.long}`;
+    const pad = ' '.repeat(Math.max(2, maxFlagLength - flag.length + 2));
+    lines.push(`${c.bold(flag)}${pad}${opt.desc}`);
+  }
+  return `${lines.join('\n')}\n`;
+};
+const parseEnum = (value, allowed) => {
+  if (value === undefined) return undefined;
+  return allowed.includes(value) ? value : undefined;
+};
+const parseTransformSyntax = value => {
+  if (value === undefined) return defaultOptions.transformSyntax;
+  if (value === 'globals-only') return 'globals-only';
+  if (value === 'false') return false;
+  if (value === 'true') return true;
+  return defaultOptions.transformSyntax;
+};
+const parseAppendDirectoryIndex = value => {
+  if (value === undefined) return undefined;
+  if (value === 'false') return false;
+  return value;
+};
+const toModuleOptions = values => {
+  const target = parseEnum(values.target, ['module', 'commonjs']) ?? defaultOptions.target;
+  const transformSyntax = parseTransformSyntax(values['transform-syntax']);
+  const appendJsExtension = parseEnum(values['append-js-extension'], ['off', 'relative-only', 'all']);
+  const appendDirectoryIndex = parseAppendDirectoryIndex(values['append-directory-index']);
+  const opts = {
+    ...defaultOptions,
+    target,
+    transformSyntax,
+    rewriteSpecifier: values['rewrite-specifier'] ?? undefined,
+    appendJsExtension: appendJsExtension,
+    appendDirectoryIndex,
+    detectCircularRequires: parseEnum(values['detect-circular-requires'], ['off', 'warn', 'error']) ?? defaultOptions.detectCircularRequires,
+    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,
+    importMetaPrelude: parseEnum(values['import-meta-prelude'], ['off', 'auto', 'on']) ?? defaultOptions.importMetaPrelude,
+    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,
+    cwd: values.cwd ? (0, _nodePath.resolve)(String(values.cwd)) : defaultOptions.cwd
+  };
+  return opts;
+};
+const readStdin = async stdin => {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+};
+const expandFiles = async (patterns, cwd, ignore) => {
+  const files = new Set();
+  for (const pattern of patterns) {
+    const matches = await (0, _glob.glob)(pattern, {
+      cwd,
+      absolute: true,
+      nodir: true,
+      windowsPathsNoEscape: true,
+      ignore
+    });
+    for (const m of matches) files.add((0, _nodePath.resolve)(m));
+  }
+  return [...files];
+};
+const makeLogger = (stdout, stderr) => {
+  const enableColor = stdout.isTTY ?? stderr.isTTY ?? false;
+  const c = colorize(enableColor);
+  const log = (kind, message, stream) => {
+    const icon = icons[kind];
+    const colored = kind === 'error' ? c.red(message) : kind === 'warn' ? c.yellow(message) : kind === 'success' ? c.green(message) : c.cyan(message);
+    stream.write(`${icon} ${colored}\n`);
+  };
+  return {
+    info: msg => log('info', msg, stdout),
+    warn: msg => log('warn', msg, stderr),
+    error: msg => log('error', msg, stderr),
+    success: msg => log('success', msg, stdout),
+    color: c
+  };
+};
+const applySpecifierUpdates = async (source, filename, opts, appendMode, dirIndex) => {
+  if (!opts.rewriteSpecifier && appendMode === 'off' && !dirIndex) return source;
+  const lang = (0, _lang.getLangFromExt)(filename);
+  const updated = await _specifier.specifier.updateSrc(source, lang, spec => {
+    const normalized = normalizeBuiltinSpecifier(spec.value);
+    const rewritten = rewriteSpecifierValue(normalized ?? spec.value, opts.rewriteSpecifier);
+    const baseValue = rewritten ?? normalized ?? spec.value;
+    const appended = appendExtensionIfNeeded(baseValue, appendMode, dirIndex);
+    return appended ?? rewritten ?? normalized ?? undefined;
+  });
+  return updated;
+};
+const transformVirtual = async (source, filename, opts) => {
+  const ast = (0, _parse.parse)(filename, source);
+  let output = await (0, _format.format)(source, ast, {
+    ...opts,
+    filePath: filename
+  });
+  const appendMode = opts.appendJsExtension ?? (opts.target === 'module' ? 'relative-only' : 'off');
+  const dirIndex = opts.appendDirectoryIndex === undefined ? 'index.js' : opts.appendDirectoryIndex;
+  output = await applySpecifierUpdates(output, filename, opts, appendMode, dirIndex);
+  return output;
+};
+const summarizeDiagnostics = diags => {
+  let warnings = 0;
+  let errors = 0;
+  for (const d of diags) {
+    if (d.level === 'warning') warnings += 1;
+    if (d.level === 'error') errors += 1;
+  }
+  return {
+    warnings,
+    errors
+  };
+};
+const runFiles = async (files, moduleOpts, io, flags) => {
+  const results = [];
+  const logger = makeLogger(io.stdout, io.stderr);
+  for (const file of files) {
+    const diagnostics = [];
+    const original = await (0, _promises.readFile)(file, 'utf8');
+    const outPath = flags.outDir ? (0, _nodePath.join)(flags.outDir, (0, _nodePath.relative)(moduleOpts.cwd ?? process.cwd(), file)) : undefined;
+    const perFileOpts = {
+      ...moduleOpts,
+      diagnostics: diag => diagnostics.push(diag),
+      out: undefined,
+      inPlace: false,
+      filePath: file
+    };
+    let writeTarget;
+    if (!flags.dryRun && !flags.list) {
+      if (flags.inPlace) {
+        perFileOpts.inPlace = true;
+      } else if (outPath) {
+        writeTarget = outPath;
+        perFileOpts.out = outPath;
+        await (0, _promises.mkdir)((0, _nodePath.dirname)(outPath), {
+          recursive: true
+        });
+      } else if (!flags.allowStdout) {
+        logger.error('Specify --out-dir or --in-place when transforming files');
+        return {
+          code: 2,
+          results
+        };
+      }
+    }
+    const output = await (0, _module.transform)(file, perFileOpts);
+    const changed = output !== original;
+    if (flags.list && changed) {
+      logger.info(file);
+    }
+    if (!flags.dryRun && !flags.list && !writeTarget && !perFileOpts.inPlace) {
+      io.stdout.write(output);
+    }
+    results.push({
+      filePath: file,
+      changed,
+      diagnostics
+    });
+    const counts = summarizeDiagnostics(diagnostics);
+    if (!flags.json) {
+      for (const diag of diagnostics) {
+        const prefix = diag.level === 'error' ? logger.error : logger.warn;
+        const loc = diag.loc ? ` [${diag.loc.start}-${diag.loc.end}]` : '';
+        prefix(`${diag.code}: ${diag.message}${loc}`);
+      }
+    }
+    if (counts.errors > 0) {
+      return {
+        code: 1,
+        results
+      };
+    }
+  }
+  if (flags.summary && !flags.json) {
+    const changedCount = results.filter(r => r.changed).length;
+    logger.success(`Processed ${results.length} file(s); changed ${changedCount}`);
+  }
+  return {
+    code: 0,
+    results
+  };
+};
+const runCli = async ({
+  argv = process.argv.slice(2),
+  stdin = _nodeProcess.stdin,
+  stdout = _nodeProcess.stdout,
+  stderr = _nodeProcess.stderr
+} = {}) => {
+  const {
+    values,
+    positionals
+  } = (0, _nodeUtil.parseArgs)({
+    args: argv,
+    allowPositionals: true,
+    options: Object.fromEntries(optionsTable.map(opt => [opt.long, {
+      type: opt.type,
+      short: opt.short
+    }]))
+  });
+  const logger = makeLogger(stdout, stderr);
+  if (values.help) {
+    stdout.write(buildHelp(stdout.isTTY ?? false));
+    return 0;
+  }
+  if (values.version) {
+    const pkg = JSON.parse(await (0, _promises.readFile)(new URL('../package.json', import.meta.url), 'utf8'));
+    stdout.write(`${pkg.version}\n`);
+    return 0;
+  }
+  const moduleOpts = toModuleOptions(values);
+  const cwd = moduleOpts.cwd ?? process.cwd();
+  const allowStdout = positionals.length <= 1;
+  const fromStdin = positionals.length === 0 || positionals.includes('-');
+  const patterns = positionals.filter(p => p !== '-');
+  const ignoreValues = values.ignore;
+  const ignore = ignoreValues ? (Array.isArray(ignoreValues) ? ignoreValues : [ignoreValues]).map(String) : undefined;
+  const outDir = values['out-dir'] ? (0, _nodePath.resolve)(cwd, String(values['out-dir'])) : undefined;
+  const inPlace = Boolean(values['in-place']);
+  const dryRun = Boolean(values['dry-run']);
+  const list = Boolean(values.list);
+  const summary = Boolean(values.summary);
+  const json = Boolean(values.json);
+  if (outDir && inPlace) {
+    logger.error('Choose either --out-dir or --in-place, not both');
+    return 2;
+  }
+  if (fromStdin && (outDir || inPlace)) {
+    logger.error('Cannot combine stdin with --out-dir or --in-place; output goes to stdout');
+    return 2;
+  }
+  const files = await expandFiles(patterns, cwd, ignore);
+  if (!fromStdin && files.length === 0) {
+    logger.error('No input files were provided or matched');
+    return 2;
+  }
+  const tasks = [];
+  if (fromStdin) {
+    const virtualName = values['stdin-filename'] ?? 'stdin.js';
+    const source = await readStdin(stdin);
+    const diagnostics = [];
+    const output = await transformVirtual(source, virtualName, {
+      ...moduleOpts,
+      diagnostics: diag => diagnostics.push(diag),
+      filePath: virtualName,
+      cwd
+    });
+    tasks.push({
+      filePath: virtualName,
+      changed: true,
+      diagnostics
+    });
+    stdout.write(output);
+    if (!json) {
+      for (const diag of diagnostics) {
+        const prefix = diag.level === 'error' ? logger.error : logger.warn;
+        const loc = diag.loc ? ` [${diag.loc.start}-${diag.loc.end}]` : '';
+        prefix(`${diag.code}: ${diag.message}${loc}`);
+      }
+    }
+    const diagSummary = summarizeDiagnostics(diagnostics);
+    if (diagSummary.errors > 0) return 1;
+  }
+  if (files.length) {
+    const result = await runFiles(files, {
+      ...moduleOpts,
+      cwd
+    }, {
+      stdout,
+      stderr
+    }, {
+      dryRun,
+      list,
+      summary,
+      json,
+      outDir,
+      inPlace,
+      allowStdout
+    });
+    if (typeof result.code === 'number' && result.code !== 0) return result.code;
+    tasks.push(...result.results);
+  }
+  if (json) {
+    const summaryDiag = summarizeDiagnostics(tasks.flatMap(t => t.diagnostics));
+    stdout.write(`${JSON.stringify({
+      files: tasks,
+      summary: summaryDiag
+    }, null, 2)}\n`);
+  }
+  return 0;
+};
+exports.runCli = runCli;
+if (import.meta.main) {
+  runCli().then(code => {
+    if (code !== 0) process.exit(code);
+  }, err => {
+    // eslint-disable-next-line no-console -- CLI surface
+    console.error(err);
+    process.exit(1);
+  });
+}

package/dist/cjs/cli.d.cts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { stdin as defaultStdin } from 'node:process';
+type StreamLike = {
+    isTTY?: boolean;
+    write: (chunk: string | Uint8Array) => unknown;
+};
+type CliOptions = {
+    argv?: string[];
+    stdin?: typeof defaultStdin;
+    stdout?: StreamLike;
+    stderr?: StreamLike;
+};
+declare const runCli: ({ argv, stdin, stdout, stderr, }?: CliOptions) => Promise<number>;
+export { runCli };

package/dist/cjs/format.cjs

@@ -580,7 +580,10 @@ const format = async (src, ast, opts) => {
           seen.add(propName);
           if (rhs.type === 'Identifier') {
             const rhsId = rhsSourceFor(rhs);
-            if (rhsId === rhs.name) {
+            const rhsName = rhs.name;
+            if (rhsId === rhsName && rhsName === propName) {
+              exportsOut.push(`export { ${propName} };`);
+            } else if (rhsId === rhsName) {
               exportsOut.push(`export { ${rhsId} as ${propName} };`);
             } else {
               exportsOut.push(`export const ${propName} = ${rhsId};`);
@@ -589,9 +592,15 @@ const format = async (src, ast, opts) => {
             exportsOut.push(`export const ${propName} = ${rhsSrc};`);
           }
         }
+
+        // Trim trailing whitespace and one optional semicolon so the idiomatic export
+        // replacement does not leave the original `;` behind (avoids emitting `;;`).
+        let end = write.end;
+        while (end < src.length && (src[end] === ' ' || src[end] === '\t')) end++;
+        if (end < src.length && src[end] === ';') end++;
         replacements.push({
           start: write.start,
-          end: write.end
+          end
         });
       }
       if (!seen.size) return {

package/dist/cjs/formatters/metaProperty.cjs

@@ -49,6 +49,9 @@ const metaProperty = (node, parent, src, options) => {
         case 'main':
           src.update(parent.start, parent.end, importMetaMainExpr(options.importMetaMain));
           break;
+        default:
+          src.update(parent.start, parent.end, `module.${parent.property.name}`);
+          break;
       }
     }
   }

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { stdin as defaultStdin } from 'node:process';
+type StreamLike = {
+    isTTY?: boolean;
+    write: (chunk: string | Uint8Array) => unknown;
+};
+type CliOptions = {
+    argv?: string[];
+    stdin?: typeof defaultStdin;
+    stdout?: StreamLike;
+    stderr?: StreamLike;
+};
+declare const runCli: ({ argv, stdin, stdout, stderr, }?: CliOptions) => Promise<number>;
+export { runCli };

package/dist/cli.js

@@ -0,0 +1,547 @@
+#!/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 { builtinModules } from 'node:module';
+import { glob } from 'glob';
+import { transform } from './module.js';
+import { parse } from './parse.js';
+import { format } from './format.js';
+import { specifier } from './specifier.js';
+import { getLangFromExt } from './utils/lang.js';
+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',
+  idiomaticExports: 'safe',
+  importMetaPrelude: 'auto',
+  topLevelAwait: 'error',
+  cwd: undefined,
+  out: undefined,
+  inPlace: false
+};
+const icons = {
+  info: 'i',
+  warn: '⚠',
+  error: '✖',
+  success: '✔'
+};
+const codes = {
+  reset: '\u001b[0m',
+  bold: '\u001b[1m',
+  dim: '\u001b[2m',
+  red: '\u001b[31m',
+  yellow: '\u001b[33m',
+  green: '\u001b[32m',
+  cyan: '\u001b[36m'
+};
+const colorize = enabled => {
+  if (!enabled) {
+    return {
+      bold: v => v,
+      dim: v => v,
+      red: v => v,
+      yellow: v => v,
+      green: v => v,
+      cyan: v => v
+    };
+  }
+  const wrap = code => v => `${code}${v}${codes.reset}`;
+  return {
+    bold: wrap(codes.bold),
+    dim: wrap(codes.dim),
+    red: wrap(codes.red),
+    yellow: wrap(codes.yellow),
+    green: wrap(codes.green),
+    cyan: wrap(codes.cyan)
+  };
+};
+const builtinSpecifiers = new Set(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 collapseSpecifier = value => value.replace(/['"`+)\s]|new String\(/g, '');
+const appendExtensionIfNeeded = (value, mode, dirIndex) => {
+  if (mode === 'off') 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)sx?([)'"]*)?$/, `$1${rewriteSpecifier}$2`);
+  }
+};
+const normalizeBuiltinSpecifier = value => {
+  const collapsed = collapseSpecifier(value);
+  if (!collapsed) return;
+  const specPart = collapsed.split(/[?#]/)[0] ?? '';
+  if (/^(?:\.\.?(?:\/)|\/)/.test(specPart)) return;
+  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 optionsTable = [{
+  long: 'target',
+  short: 't',
+  type: 'string',
+  desc: 'Output format (module|commonjs)'
+}, {
+  long: 'transform-syntax',
+  short: 'x',
+  type: 'string',
+  desc: 'Syntax transforms (true|false|globals-only)'
+}, {
+  long: 'rewrite-specifier',
+  short: 'r',
+  type: 'string',
+  desc: 'Rewrite import specifiers (.js/.mjs/.cjs/.ts/.mts/.cts)'
+}, {
+  long: 'append-js-extension',
+  short: 'j',
+  type: 'string',
+  desc: 'Append .js to relative imports (off|relative-only|all)'
+}, {
+  long: 'append-directory-index',
+  short: 'i',
+  type: 'string',
+  desc: 'Append directory index (e.g. index.js) or false'
+}, {
+  long: 'detect-circular-requires',
+  short: 'c',
+  type: 'string',
+  desc: 'Warn/error on circular require (off|warn|error)'
+}, {
+  long: 'top-level-await',
+  short: 'a',
+  type: 'string',
+  desc: 'TLA handling (error|wrap|preserve)'
+}, {
+  long: 'cjs-default',
+  short: 'd',
+  type: 'string',
+  desc: 'Default interop (module-exports|auto|none)'
+}, {
+  long: 'idiomatic-exports',
+  short: 'e',
+  type: 'string',
+  desc: 'Emit idiomatic exports when safe (off|safe|aggressive)'
+}, {
+  long: 'import-meta-prelude',
+  short: 'm',
+  type: 'string',
+  desc: 'Emit import.meta prelude (off|auto|on)'
+}, {
+  long: 'nested-require-strategy',
+  short: 'n',
+  type: 'string',
+  desc: 'Rewrite nested require (create-require|dynamic-import)'
+}, {
+  long: 'require-main-strategy',
+  short: 'R',
+  type: 'string',
+  desc: 'Detect main (import-meta-main|realpath)'
+}, {
+  long: 'live-bindings',
+  short: 'l',
+  type: 'string',
+  desc: 'Live binding strategy (strict|loose|off)'
+}, {
+  long: 'out-dir',
+  short: 'o',
+  type: 'string',
+  desc: 'Write outputs to a directory mirror'
+}, {
+  long: 'in-place',
+  short: 'p',
+  type: 'boolean',
+  desc: 'Rewrite files in place'
+}, {
+  long: 'dry-run',
+  short: 'y',
+  type: 'boolean',
+  desc: 'Do not write files; report planned changes'
+}, {
+  long: 'list',
+  short: 'L',
+  type: 'boolean',
+  desc: 'List files that would change'
+}, {
+  long: 'summary',
+  short: 's',
+  type: 'boolean',
+  desc: 'Print a summary of work performed'
+}, {
+  long: 'json',
+  short: 'J',
+  type: 'boolean',
+  desc: 'Emit machine-readable JSON summary/diagnostics'
+}, {
+  long: 'cwd',
+  short: 'C',
+  type: 'string',
+  desc: 'Working directory for resolving files/out paths'
+}, {
+  long: 'stdin-filename',
+  short: 'f',
+  type: 'string',
+  desc: 'Virtual filename when reading from stdin'
+}, {
+  long: 'ignore',
+  short: 'g',
+  type: 'string',
+  desc: 'Glob pattern(s) to ignore (repeatable)'
+}, {
+  long: 'help',
+  short: 'h',
+  type: 'boolean',
+  desc: 'Show help'
+}, {
+  long: 'version',
+  short: 'v',
+  type: 'boolean',
+  desc: 'Show version'
+}];
+const buildHelp = enableColor => {
+  const c = colorize(enableColor);
+  const maxFlagLength = Math.max(...optionsTable.map(opt => `  -${opt.short}, --${opt.long}`.length));
+  const lines = [`${c.bold('Usage:')} dub [options] <files...>`, '', 'Examples:', '  dub -t module src/index.cjs --out-dir dist', '  dub -t commonjs src/**/*.mjs -p', '  cat input.cjs | dub -t module --stdin-filename input.cjs', '', 'Options:'];
+  for (const opt of optionsTable) {
+    const flag = `  -${opt.short}, --${opt.long}`;
+    const pad = ' '.repeat(Math.max(2, maxFlagLength - flag.length + 2));
+    lines.push(`${c.bold(flag)}${pad}${opt.desc}`);
+  }
+  return `${lines.join('\n')}\n`;
+};
+const parseEnum = (value, allowed) => {
+  if (value === undefined) return undefined;
+  return allowed.includes(value) ? value : undefined;
+};
+const parseTransformSyntax = value => {
+  if (value === undefined) return defaultOptions.transformSyntax;
+  if (value === 'globals-only') return 'globals-only';
+  if (value === 'false') return false;
+  if (value === 'true') return true;
+  return defaultOptions.transformSyntax;
+};
+const parseAppendDirectoryIndex = value => {
+  if (value === undefined) return undefined;
+  if (value === 'false') return false;
+  return value;
+};
+const toModuleOptions = values => {
+  const target = parseEnum(values.target, ['module', 'commonjs']) ?? defaultOptions.target;
+  const transformSyntax = parseTransformSyntax(values['transform-syntax']);
+  const appendJsExtension = parseEnum(values['append-js-extension'], ['off', 'relative-only', 'all']);
+  const appendDirectoryIndex = parseAppendDirectoryIndex(values['append-directory-index']);
+  const opts = {
+    ...defaultOptions,
+    target,
+    transformSyntax,
+    rewriteSpecifier: values['rewrite-specifier'] ?? undefined,
+    appendJsExtension: appendJsExtension,
+    appendDirectoryIndex,
+    detectCircularRequires: parseEnum(values['detect-circular-requires'], ['off', 'warn', 'error']) ?? defaultOptions.detectCircularRequires,
+    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,
+    importMetaPrelude: parseEnum(values['import-meta-prelude'], ['off', 'auto', 'on']) ?? defaultOptions.importMetaPrelude,
+    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,
+    cwd: values.cwd ? resolve(String(values.cwd)) : defaultOptions.cwd
+  };
+  return opts;
+};
+const readStdin = async stdin => {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+};
+const expandFiles = async (patterns, cwd, ignore) => {
+  const files = new Set();
+  for (const pattern of patterns) {
+    const matches = await glob(pattern, {
+      cwd,
+      absolute: true,
+      nodir: true,
+      windowsPathsNoEscape: true,
+      ignore
+    });
+    for (const m of matches) files.add(resolve(m));
+  }
+  return [...files];
+};
+const makeLogger = (stdout, stderr) => {
+  const enableColor = stdout.isTTY ?? stderr.isTTY ?? false;
+  const c = colorize(enableColor);
+  const log = (kind, message, stream) => {
+    const icon = icons[kind];
+    const colored = kind === 'error' ? c.red(message) : kind === 'warn' ? c.yellow(message) : kind === 'success' ? c.green(message) : c.cyan(message);
+    stream.write(`${icon} ${colored}\n`);
+  };
+  return {
+    info: msg => log('info', msg, stdout),
+    warn: msg => log('warn', msg, stderr),
+    error: msg => log('error', msg, stderr),
+    success: msg => log('success', msg, stdout),
+    color: c
+  };
+};
+const applySpecifierUpdates = async (source, filename, opts, appendMode, dirIndex) => {
+  if (!opts.rewriteSpecifier && appendMode === 'off' && !dirIndex) return source;
+  const lang = getLangFromExt(filename);
+  const updated = await specifier.updateSrc(source, lang, spec => {
+    const normalized = normalizeBuiltinSpecifier(spec.value);
+    const rewritten = rewriteSpecifierValue(normalized ?? spec.value, opts.rewriteSpecifier);
+    const baseValue = rewritten ?? normalized ?? spec.value;
+    const appended = appendExtensionIfNeeded(baseValue, appendMode, dirIndex);
+    return appended ?? rewritten ?? normalized ?? undefined;
+  });
+  return updated;
+};
+const transformVirtual = async (source, filename, opts) => {
+  const ast = parse(filename, source);
+  let output = await format(source, ast, {
+    ...opts,
+    filePath: filename
+  });
+  const appendMode = opts.appendJsExtension ?? (opts.target === 'module' ? 'relative-only' : 'off');
+  const dirIndex = opts.appendDirectoryIndex === undefined ? 'index.js' : opts.appendDirectoryIndex;
+  output = await applySpecifierUpdates(output, filename, opts, appendMode, dirIndex);
+  return output;
+};
+const summarizeDiagnostics = diags => {
+  let warnings = 0;
+  let errors = 0;
+  for (const d of diags) {
+    if (d.level === 'warning') warnings += 1;
+    if (d.level === 'error') errors += 1;
+  }
+  return {
+    warnings,
+    errors
+  };
+};
+const runFiles = async (files, moduleOpts, io, flags) => {
+  const results = [];
+  const logger = makeLogger(io.stdout, io.stderr);
+  for (const file of files) {
+    const diagnostics = [];
+    const original = await readFile(file, 'utf8');
+    const outPath = flags.outDir ? join(flags.outDir, relative(moduleOpts.cwd ?? process.cwd(), file)) : undefined;
+    const perFileOpts = {
+      ...moduleOpts,
+      diagnostics: diag => diagnostics.push(diag),
+      out: undefined,
+      inPlace: false,
+      filePath: file
+    };
+    let writeTarget;
+    if (!flags.dryRun && !flags.list) {
+      if (flags.inPlace) {
+        perFileOpts.inPlace = true;
+      } else if (outPath) {
+        writeTarget = outPath;
+        perFileOpts.out = outPath;
+        await mkdir(dirname(outPath), {
+          recursive: true
+        });
+      } else if (!flags.allowStdout) {
+        logger.error('Specify --out-dir or --in-place when transforming files');
+        return {
+          code: 2,
+          results
+        };
+      }
+    }
+    const output = await transform(file, perFileOpts);
+    const changed = output !== original;
+    if (flags.list && changed) {
+      logger.info(file);
+    }
+    if (!flags.dryRun && !flags.list && !writeTarget && !perFileOpts.inPlace) {
+      io.stdout.write(output);
+    }
+    results.push({
+      filePath: file,
+      changed,
+      diagnostics
+    });
+    const counts = summarizeDiagnostics(diagnostics);
+    if (!flags.json) {
+      for (const diag of diagnostics) {
+        const prefix = diag.level === 'error' ? logger.error : logger.warn;
+        const loc = diag.loc ? ` [${diag.loc.start}-${diag.loc.end}]` : '';
+        prefix(`${diag.code}: ${diag.message}${loc}`);
+      }
+    }
+    if (counts.errors > 0) {
+      return {
+        code: 1,
+        results
+      };
+    }
+  }
+  if (flags.summary && !flags.json) {
+    const changedCount = results.filter(r => r.changed).length;
+    logger.success(`Processed ${results.length} file(s); changed ${changedCount}`);
+  }
+  return {
+    code: 0,
+    results
+  };
+};
+const runCli = async ({
+  argv = process.argv.slice(2),
+  stdin = defaultStdin,
+  stdout = defaultStdout,
+  stderr = defaultStderr
+} = {}) => {
+  const {
+    values,
+    positionals
+  } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: Object.fromEntries(optionsTable.map(opt => [opt.long, {
+      type: opt.type,
+      short: opt.short
+    }]))
+  });
+  const logger = makeLogger(stdout, stderr);
+  if (values.help) {
+    stdout.write(buildHelp(stdout.isTTY ?? false));
+    return 0;
+  }
+  if (values.version) {
+    const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    stdout.write(`${pkg.version}\n`);
+    return 0;
+  }
+  const moduleOpts = toModuleOptions(values);
+  const cwd = moduleOpts.cwd ?? process.cwd();
+  const allowStdout = positionals.length <= 1;
+  const fromStdin = positionals.length === 0 || positionals.includes('-');
+  const patterns = positionals.filter(p => p !== '-');
+  const ignoreValues = values.ignore;
+  const ignore = ignoreValues ? (Array.isArray(ignoreValues) ? ignoreValues : [ignoreValues]).map(String) : undefined;
+  const outDir = values['out-dir'] ? resolve(cwd, String(values['out-dir'])) : undefined;
+  const inPlace = Boolean(values['in-place']);
+  const dryRun = Boolean(values['dry-run']);
+  const list = Boolean(values.list);
+  const summary = Boolean(values.summary);
+  const json = Boolean(values.json);
+  if (outDir && inPlace) {
+    logger.error('Choose either --out-dir or --in-place, not both');
+    return 2;
+  }
+  if (fromStdin && (outDir || inPlace)) {
+    logger.error('Cannot combine stdin with --out-dir or --in-place; output goes to stdout');
+    return 2;
+  }
+  const files = await expandFiles(patterns, cwd, ignore);
+  if (!fromStdin && files.length === 0) {
+    logger.error('No input files were provided or matched');
+    return 2;
+  }
+  const tasks = [];
+  if (fromStdin) {
+    const virtualName = values['stdin-filename'] ?? 'stdin.js';
+    const source = await readStdin(stdin);
+    const diagnostics = [];
+    const output = await transformVirtual(source, virtualName, {
+      ...moduleOpts,
+      diagnostics: diag => diagnostics.push(diag),
+      filePath: virtualName,
+      cwd
+    });
+    tasks.push({
+      filePath: virtualName,
+      changed: true,
+      diagnostics
+    });
+    stdout.write(output);
+    if (!json) {
+      for (const diag of diagnostics) {
+        const prefix = diag.level === 'error' ? logger.error : logger.warn;
+        const loc = diag.loc ? ` [${diag.loc.start}-${diag.loc.end}]` : '';
+        prefix(`${diag.code}: ${diag.message}${loc}`);
+      }
+    }
+    const diagSummary = summarizeDiagnostics(diagnostics);
+    if (diagSummary.errors > 0) return 1;
+  }
+  if (files.length) {
+    const result = await runFiles(files, {
+      ...moduleOpts,
+      cwd
+    }, {
+      stdout,
+      stderr
+    }, {
+      dryRun,
+      list,
+      summary,
+      json,
+      outDir,
+      inPlace,
+      allowStdout
+    });
+    if (typeof result.code === 'number' && result.code !== 0) return result.code;
+    tasks.push(...result.results);
+  }
+  if (json) {
+    const summaryDiag = summarizeDiagnostics(tasks.flatMap(t => t.diagnostics));
+    stdout.write(`${JSON.stringify({
+      files: tasks,
+      summary: summaryDiag
+    }, null, 2)}\n`);
+  }
+  return 0;
+};
+if (import.meta.main) {
+  runCli().then(code => {
+    if (code !== 0) process.exit(code);
+  }, err => {
+    // eslint-disable-next-line no-console -- CLI surface
+    console.error(err);
+    process.exit(1);
+  });
+}
+export { runCli };

package/dist/format.js

@@ -573,7 +573,10 @@ const format = async (src, ast, opts) => {
           seen.add(propName);
           if (rhs.type === 'Identifier') {
             const rhsId = rhsSourceFor(rhs);
-            if (rhsId === rhs.name) {
+            const rhsName = rhs.name;
+            if (rhsId === rhsName && rhsName === propName) {
+              exportsOut.push(`export { ${propName} };`);
+            } else if (rhsId === rhsName) {
               exportsOut.push(`export { ${rhsId} as ${propName} };`);
             } else {
               exportsOut.push(`export const ${propName} = ${rhsId};`);
@@ -582,9 +585,15 @@ const format = async (src, ast, opts) => {
             exportsOut.push(`export const ${propName} = ${rhsSrc};`);
           }
         }
+
+        // Trim trailing whitespace and one optional semicolon so the idiomatic export
+        // replacement does not leave the original `;` behind (avoids emitting `;;`).
+        let end = write.end;
+        while (end < src.length && (src[end] === ' ' || src[end] === '\t')) end++;
+        if (end < src.length && src[end] === ';') end++;
         replacements.push({
           start: write.start,
-          end: write.end
+          end
         });
       }
       if (!seen.size) return {

package/dist/formatters/metaProperty.js

@@ -43,6 +43,9 @@ export const metaProperty = (node, parent, src, options) => {
         case 'main':
           src.update(parent.start, parent.end, importMetaMainExpr(options.importMetaMain));
           break;
+        default:
+          src.update(parent.start, parent.end, `module.${parent.property.name}`);
+          break;
       }
     }
   }

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@knighted/module",
-  "version": "1.2.0",
+  "version": "1.3.0-rc.0",
   "description": "Bidirectional transform for ES modules and CommonJS.",
   "type": "module",
   "main": "dist/module.js",
+  "bin": {
+    "dub": "dist/cli.js"
+  },
   "exports": {
     ".": {
       "import": {
@@ -28,7 +31,10 @@
     "prettier:check": "prettier -c .",
     "lint": "oxlint --config oxlint.json .",
     "prepare": "husky",
-    "test": "c8 --reporter=text --reporter=text-summary --reporter=lcov tsx --test --test-reporter=spec test/*.ts",
+    "test:base": "tsx --test --test-reporter=spec",
+    "test:cli": "npm run test:base -- test/cli.ts",
+    "test:module": "npm run test:base -- test/module.ts",
+    "test": "c8 --reporter=text --reporter=text-summary --reporter=lcov npm run test:base -- test/*.ts",
     "build:types": "tsc --emitDeclarationOnly",
     "build:dual": "babel-dual-package src --extensions .ts",
     "build": "npm run build:types && npm run build:dual",
@@ -59,7 +65,7 @@
   },
   "devDependencies": {
     "@knighted/dump": "^1.0.3",
-    "@types/node": "^22.13.17",
+    "@types/node": "^22.19.3",
     "babel-dual-package": "^1.2.3",
     "c8": "^10.1.3",
     "husky": "^9.1.7",
@@ -71,6 +77,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "glob": "^13.0.0",
     "magic-string": "^0.30.21",
     "oxc-parser": "^0.105.0",
     "periscopic": "^4.0.2"