@knighted/module 1.3.1 → 1.4.0-rc.1

package/README.md

@@ -130,6 +130,8 @@ type ModuleOptions = {
   importMetaMain?: 'shim' | 'warn' | 'error'
   requireMainStrategy?: 'import-meta-main' | 'realpath'
   detectCircularRequires?: 'off' | 'warn' | 'error'
+  detectDualPackageHazard?: 'off' | 'warn' | 'error'
+  dualPackageHazardScope?: 'file' | 'project'
   requireSource?: 'builtin' | 'create-require'
   importMetaPrelude?: 'off' | 'auto' | 'on'
   cjsDefault?: 'module-exports' | 'auto' | 'none'
@@ -155,6 +157,8 @@ type ModuleOptions = {
 - `requireMainStrategy` (`import-meta-main`): use `import.meta.main` or the realpath-based `pathToFileURL(realpathSync(process.argv[1])).href` check.
 - `importMetaPrelude` (`auto`): emit a no-op `void import.meta.filename;` touch. `on` always emits; `off` never emits; `auto` emits only when helpers that reference `import.meta.*` are synthesized (e.g., `__dirname`/`__filename` in CJS→ESM, require-main shims, createRequire helpers). Useful for bundlers/transpilers that do usage-based `import.meta` polyfilling.
 - `detectCircularRequires` (`off`): optionally detect relative static require cycles 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.
 - `topLevelAwait` (`error`): throw, wrap, or preserve when TLA appears in CommonJS output.
 - `rewriteSpecifier` (off): rewrite relative specifiers to a chosen extension or via a callback. 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`.

package/dist/cjs/cli.cjs

@@ -29,6 +29,8 @@ const defaultOptions = {
   importMetaMain: 'shim',
   requireMainStrategy: 'import-meta-main',
   detectCircularRequires: 'off',
+  detectDualPackageHazard: 'warn',
+  dualPackageHazardScope: 'file',
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
@@ -150,6 +152,16 @@ const optionsTable = [{
   short: 'c',
   type: 'string',
   desc: 'Warn/error on circular require (off|warn|error)'
+}, {
+  long: 'detect-dual-package-hazard',
+  short: 'H',
+  type: 'string',
+  desc: 'Warn/error on mixed import/require of dual packages (off|warn|error)'
+}, {
+  long: 'dual-package-hazard-scope',
+  short: undefined,
+  type: 'string',
+  desc: 'Scope for dual package hazard detection (file|project)'
 }, {
   long: 'top-level-await',
   short: 'a',
@@ -243,10 +255,10 @@ const optionsTable = [{
 }];
 const buildHelp = enableColor => {
   const c = colorize(enableColor);
-  const maxFlagLength = Math.max(...optionsTable.map(opt => `  -${opt.short}, --${opt.long}`.length));
+  const maxFlagLength = Math.max(...optionsTable.map(opt => opt.short ? `  -${opt.short}, --${opt.long}`.length : `      --${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 flag = opt.short ? `  -${opt.short}, --${opt.long}` : `      --${opt.long}`;
     const pad = ' '.repeat(Math.max(2, maxFlagLength - flag.length + 2));
     lines.push(`${c.bold(flag)}${pad}${opt.desc}`);
   }
@@ -281,6 +293,8 @@ const toModuleOptions = values => {
     appendJsExtension: appendJsExtension,
     appendDirectoryIndex,
     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,
     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,
@@ -367,6 +381,9 @@ const summarizeDiagnostics = diags => {
 const runFiles = async (files, moduleOpts, io, flags) => {
   const results = [];
   const logger = makeLogger(io.stdout, io.stderr);
+  const hazardScope = moduleOpts.dualPackageHazardScope ?? 'file';
+  const hazardMode = moduleOpts.detectDualPackageHazard ?? 'warn';
+  const projectHazards = hazardScope === 'project' && hazardMode !== 'off' ? await (0, _module.collectProjectDualPackageHazards)(files, moduleOpts) : null;
   for (const file of files) {
     const diagnostics = [];
     const original = await (0, _promises.readFile)(file, 'utf8');
@@ -376,7 +393,8 @@ const runFiles = async (files, moduleOpts, io, flags) => {
       diagnostics: diag => diagnostics.push(diag),
       out: undefined,
       inPlace: false,
-      filePath: file
+      filePath: file,
+      detectDualPackageHazard: hazardScope === 'project' ? 'off' : moduleOpts.detectDualPackageHazard
     };
     let writeTarget;
     if (!flags.dryRun && !flags.list) {
@@ -398,6 +416,10 @@ const runFiles = async (files, moduleOpts, io, flags) => {
     }
     const output = await (0, _module.transform)(file, perFileOpts);
     const changed = output !== original;
+    if (projectHazards) {
+      const extras = projectHazards.get(file);
+      if (extras?.length) diagnostics.push(...extras);
+    }
     if (flags.list && changed) {
       logger.info(file);
     }
@@ -447,7 +469,9 @@ const runCli = async ({
     allowPositionals: true,
     options: Object.fromEntries(optionsTable.map(opt => [opt.long, {
       type: opt.type,
-      short: opt.short
+      ...(opt.short ? {
+        short: opt.short
+      } : {})
     }]))
   });
   const logger = makeLogger(stdout, stderr);

package/dist/cjs/format.cjs

@@ -3,7 +3,10 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.format = void 0;
+exports.format = exports.dualPackageHazardDiagnostics = exports.collectDualPackageUsage = void 0;
+var _nodeModule = require("node:module");
+var _nodePath = require("node:path");
+var _promises = require("node:fs/promises");
 var _magicString = _interopRequireDefault(require("magic-string"));
 var _async = require("./helpers/async.cjs");
 var _identifier = require("./helpers/identifier.cjs");
@@ -24,6 +27,274 @@ var _url = require("./utils/url.cjs");
 var _walk = require("./walk.cjs");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const isRequireMainMember = (node, shadowed) => node.type === 'MemberExpression' && node.object.type === 'Identifier' && node.object.name === 'require' && !shadowed.has('require') && node.property.type === 'Identifier' && node.property.name === 'main';
+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 stripQuery = value => value.includes('?') || value.includes('#') ? value.split(/[?#]/)[0] ?? value : value;
+const packageFromSpecifier = spec => {
+  const cleaned = stripQuery(spec);
+  if (!cleaned) return null;
+  if (cleaned.startsWith('node:')) return null;
+  if (/^(?:\.?\.?\/|\/)/.test(cleaned)) return null;
+  if (/^[a-zA-Z][a-zA-Z+.-]*:/.test(cleaned)) return null;
+  const parts = cleaned.split('/');
+  if (cleaned.startsWith('@')) {
+    if (parts.length < 2) return null;
+    const pkg = `${parts[0]}/${parts[1]}`;
+    if (builtinSpecifiers.has(pkg) || builtinSpecifiers.has(parts[1] ?? '')) return null;
+    const subpath = parts.slice(2).join('/');
+    return {
+      pkg,
+      subpath
+    };
+  }
+  const pkg = parts[0] ?? '';
+  if (!pkg || builtinSpecifiers.has(pkg)) return null;
+  const subpath = parts.slice(1).join('/');
+  return {
+    pkg,
+    subpath
+  };
+};
+const fileExists = async filename => {
+  try {
+    const stats = await (0, _promises.stat)(filename);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+};
+const findPackageManifest = async (pkg, filePath, cwd) => {
+  const startDir = filePath ? (0, _nodePath.dirname)((0, _nodePath.resolve)(filePath)) : (0, _nodePath.resolve)(cwd ?? process.cwd());
+  const seen = new Set();
+  let dir = startDir;
+  while (!seen.has(dir)) {
+    seen.add(dir);
+    const candidate = (0, _nodePath.join)(dir, 'node_modules', pkg, 'package.json');
+    if (await fileExists(candidate)) return candidate;
+    const parent = (0, _nodePath.dirname)(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+};
+const readPackageManifest = async (pkg, filePath, cwd, cache) => {
+  const start = (0, _nodePath.resolve)(filePath ? (0, _nodePath.dirname)(filePath) : cwd ?? process.cwd());
+  const cacheKey = `${pkg}@${start}`;
+  if (cache.has(cacheKey)) return cache.get(cacheKey);
+  const manifestPath = await findPackageManifest(pkg, filePath, cwd);
+  if (!manifestPath) {
+    cache.set(cacheKey, null);
+    return null;
+  }
+  try {
+    const raw = await (0, _promises.readFile)(manifestPath, 'utf8');
+    const json = JSON.parse(raw);
+    cache.set(cacheKey, json);
+    return json;
+  } catch {
+    cache.set(cacheKey, null);
+    return null;
+  }
+};
+const analyzeExportsTargets = exportsField => {
+  const root = exportsField && typeof exportsField === 'object' && !Array.isArray(exportsField) ?
+  // @ts-expect-error -- loose lookup of root export condition
+  exportsField['.'] ?? exportsField : exportsField;
+  if (typeof root === 'string') {
+    return {
+      importTarget: root,
+      requireTarget: root
+    };
+  }
+  if (root && typeof root === 'object') {
+    const record = root;
+    const importTarget = typeof record.import === 'string' ? record.import : undefined;
+    const requireTarget = typeof record.require === 'string' ? record.require : undefined;
+    const defaultTarget = typeof record.default === 'string' ? record.default : undefined;
+    return {
+      importTarget: importTarget ?? defaultTarget,
+      requireTarget: requireTarget ?? defaultTarget
+    };
+  }
+  return {
+    importTarget: undefined,
+    requireTarget: undefined
+  };
+};
+const describeDualPackage = pkgJson => {
+  const {
+    importTarget,
+    requireTarget
+  } = analyzeExportsTargets(pkgJson?.exports);
+  const moduleField = typeof pkgJson?.module === 'string' ? pkgJson.module : undefined;
+  const mainField = typeof pkgJson?.main === 'string' ? pkgJson.main : undefined;
+  const typeField = typeof pkgJson?.type === 'string' ? pkgJson.type : undefined;
+  const divergentExports = importTarget && requireTarget && importTarget !== requireTarget;
+  const divergentModuleMain = moduleField && mainField && moduleField !== mainField;
+  const typeModuleMainCjs = typeField === 'module' && typeof mainField === 'string' && mainField.endsWith('.cjs');
+  const hasHazardSignals = divergentExports || divergentModuleMain || typeModuleMainCjs;
+  const details = [];
+  if (divergentExports) {
+    details.push(`exports import -> ${importTarget}, require -> ${requireTarget}`);
+  }
+  if (divergentModuleMain) {
+    details.push(`module -> ${moduleField}, main -> ${mainField}`);
+  }
+  if (typeModuleMainCjs) {
+    details.push(`type: module with CommonJS main (${mainField})`);
+  }
+  return {
+    hasHazardSignals,
+    details,
+    importTarget,
+    requireTarget
+  };
+};
+const recordUsage = (usages, pkg, kind, spec, subpath, loc, filePath) => {
+  const existing = usages.get(pkg) ?? {
+    imports: [],
+    requires: []
+  };
+  const bucket = kind === 'import' ? existing.imports : existing.requires;
+  bucket.push({
+    spec,
+    subpath,
+    loc,
+    filePath
+  });
+  usages.set(pkg, existing);
+};
+const collectDualPackageUsage = async (program, shadowedBindings, filePath) => {
+  const usages = new Map();
+  await (0, _walk.ancestorWalk)(program, {
+    enter(node) {
+      if (node.type === 'ImportDeclaration' && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) recordUsage(usages, pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        }, filePath);
+      }
+      if (node.type === 'ExportNamedDeclaration' && node.source && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) recordUsage(usages, pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        }, filePath);
+      }
+      if (node.type === 'ExportAllDeclaration' && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) recordUsage(usages, pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        }, filePath);
+      }
+      if (node.type === 'ImportExpression' && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) recordUsage(usages, pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        }, filePath);
+      }
+      if (node.type === 'CallExpression' && (0, _lowerCjsRequireToImports.isStaticRequire)(node, shadowedBindings)) {
+        const arg = node.arguments[0];
+        if (arg?.type === 'Literal' && typeof arg.value === 'string') {
+          const pkg = packageFromSpecifier(arg.value);
+          if (pkg) recordUsage(usages, pkg.pkg, 'require', arg.value, pkg.subpath, {
+            start: arg.start,
+            end: arg.end
+          }, filePath);
+        }
+      }
+    }
+  });
+  return usages;
+};
+exports.collectDualPackageUsage = collectDualPackageUsage;
+const dualPackageHazardDiagnostics = async params => {
+  const {
+    usages,
+    hazardLevel,
+    filePath,
+    cwd
+  } = params;
+  const manifestCache = params.manifestCache ?? new Map();
+  const diags = [];
+  for (const [pkg, usage] of usages) {
+    const hasImport = usage.imports.length > 0;
+    const hasRequire = usage.requires.length > 0;
+    const combined = [...usage.imports, ...usage.requires];
+    const hasRoot = combined.some(entry => !entry.subpath);
+    const hasSubpath = combined.some(entry => Boolean(entry.subpath));
+    const origin = usage.imports[0] ?? usage.requires[0];
+    const diagFile = origin?.filePath ?? filePath;
+    if (hasImport && hasRequire) {
+      const importSpecs = usage.imports.map(u => u.subpath ? `${pkg}/${u.subpath}` : pkg);
+      const requireSpecs = usage.requires.map(u => u.subpath ? `${pkg}/${u.subpath}` : pkg);
+      diags.push({
+        level: hazardLevel,
+        code: 'dual-package-mixed-specifiers',
+        message: `Package '${pkg}' is loaded via import (${importSpecs.join(', ')}) and require (${requireSpecs.join(', ')}); conditional exports can instantiate it twice.`,
+        filePath: diagFile,
+        loc: origin?.loc
+      });
+    }
+    if (hasRoot && hasSubpath) {
+      const subpaths = combined.filter(entry => entry.subpath).map(entry => `${pkg}/${entry.subpath}`);
+      const originSubpath = combined.find(entry => entry.subpath) ?? combined[0];
+      diags.push({
+        level: hazardLevel,
+        code: 'dual-package-subpath',
+        message: `Package '${pkg}' is referenced via root specifier '${pkg}' and subpath(s) ${subpaths.join(', ')}; mixing them loads separate module instances.`,
+        filePath: originSubpath?.filePath ?? filePath,
+        loc: originSubpath?.loc
+      });
+    }
+    if (hasImport && hasRequire) {
+      const manifest = await readPackageManifest(pkg, diagFile, cwd, manifestCache);
+      if (manifest) {
+        const meta = describeDualPackage(manifest);
+        if (meta.hasHazardSignals) {
+          const detail = meta.details.length ? ` (${meta.details.join('; ')})` : '';
+          diags.push({
+            level: hazardLevel,
+            code: 'dual-package-conditional-exports',
+            message: `Package '${pkg}' exposes different entry points for import vs require${detail}. Mixed usage can produce distinct instances.`,
+            filePath: diagFile,
+            loc: origin?.loc
+          });
+        }
+      }
+    }
+  }
+  return diags;
+};
+exports.dualPackageHazardDiagnostics = dualPackageHazardDiagnostics;
+const detectDualPackageHazards = async params => {
+  const {
+    program,
+    shadowedBindings,
+    hazardLevel,
+    filePath,
+    cwd,
+    diagOnce
+  } = params;
+  const manifestCache = new Map();
+  const usages = await collectDualPackageUsage(program, shadowedBindings, filePath);
+  const diags = await dualPackageHazardDiagnostics({
+    usages,
+    hazardLevel,
+    filePath,
+    cwd,
+    manifestCache
+  });
+  for (const diag of diags) {
+    diagOnce(diag.level, diag.code, diag.message, diag.loc);
+  }
+};
 
 /**
  * Node added support for import.meta.main.
@@ -53,22 +324,35 @@ const format = async (src, ast, opts) => {
     // eslint-disable-next-line no-console -- used for opt-in diagnostics
     console.error(diag.message);
   };
-  const warnOnce = (codeId, message, loc) => {
-    const key = `${codeId}:${loc?.start ?? ''}`;
+  const diagOnce = (level, codeId, message, loc) => {
+    const key = `${level}:${codeId}:${loc?.start ?? ''}`;
     if (warned.has(key)) return;
     warned.add(key);
     emitDiagnostic({
-      level: 'warning',
+      level,
       code: codeId,
       message,
       filePath: opts.filePath,
       loc
     });
   };
+  const warnOnce = (codeId, message, loc) => diagOnce('warning', codeId, message, loc);
   const transformMode = opts.transformSyntax;
   const fullTransform = transformMode === true;
   const moduleIdentifiers = await (0, _identifiers.collectModuleIdentifiers)(ast.program);
   const shadowedBindings = new Set([...moduleIdentifiers.entries()].filter(([, meta]) => meta.declare.length > 0).map(([name]) => name));
+  const hazardMode = opts.detectDualPackageHazard ?? 'warn';
+  if (hazardMode !== 'off') {
+    const hazardLevel = hazardMode === 'error' ? 'error' : 'warning';
+    await detectDualPackageHazards({
+      program: ast.program,
+      shadowedBindings,
+      hazardLevel,
+      filePath: opts.filePath,
+      cwd: opts.cwd,
+      diagOnce
+    });
+  }
   if (opts.target === 'module' && fullTransform) {
     if (shadowedBindings.has('module') || shadowedBindings.has('exports')) {
       throw new Error('Cannot transform to ESM: module or exports is shadowed in module scope.');

package/dist/cjs/format.d.cts

@@ -1,9 +1,31 @@
-import type { ParseResult } from 'oxc-parser';
-import type { FormatterOptions } from './types.cjs';
+import type { Node, ParseResult } from 'oxc-parser';
+import type { Diagnostic, FormatterOptions } from './types.cjs';
+type HazardLevel = 'warning' | 'error';
+export type PackageUse = {
+    spec: string;
+    subpath: string;
+    loc?: {
+        start: number;
+        end: number;
+    };
+    filePath?: string;
+};
+export type PackageUsage = {
+    imports: PackageUse[];
+    requires: PackageUse[];
+};
+declare const collectDualPackageUsage: (program: Node, shadowedBindings: Set<string>, filePath?: string) => Promise<Map<string, PackageUsage>>;
+declare const dualPackageHazardDiagnostics: (params: {
+    usages: Map<string, PackageUsage>;
+    hazardLevel: HazardLevel;
+    filePath?: string;
+    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>;
-export { format };
+export { format, collectDualPackageUsage, dualPackageHazardDiagnostics };

package/dist/cjs/module.cjs

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.transform = void 0;
+exports.transform = exports.collectProjectDualPackageHazards = void 0;
 var _nodePath = require("node:path");
 var _promises = require("node:fs/promises");
 var _specifier = require("./specifier.cjs");
@@ -12,6 +12,7 @@ var _format = require("./format.cjs");
 var _lang = require("./utils/lang.cjs");
 var _nodeModule = require("node:module");
 var _walk = require("./walk.cjs");
+var _identifiers = require("./utils/identifiers.cjs");
 const collapseSpecifier = value => value.replace(/['"`+)\s]|new String\(/g, '');
 const builtinSpecifiers = new Set(_nodeModule.builtinModules.map(mod => mod.startsWith('node:') ? mod.slice(5) : mod).flatMap(mod => {
   const parts = mod.split('/');
@@ -144,6 +145,47 @@ const detectCircularRequireGraph = async (entryFile, mode, dirIndex) => {
   };
   await dfs(entryFile, []);
 };
+const mergeUsageMaps = (target, source) => {
+  for (const [pkg, usage] of source) {
+    const existing = target.get(pkg) ?? {
+      imports: [],
+      requires: []
+    };
+    existing.imports.push(...usage.imports);
+    existing.requires.push(...usage.requires);
+    target.set(pkg, existing);
+  }
+};
+const collectProjectDualPackageHazards = async (files, opts) => {
+  const hazardMode = opts.detectDualPackageHazard ?? 'warn';
+  if (hazardMode === 'off') return new Map();
+  const hazardLevel = hazardMode === 'error' ? 'error' : 'warning';
+  const usages = new Map();
+  const manifestCache = new Map();
+  for (const file of files) {
+    const code = await (0, _promises.readFile)(file, 'utf8');
+    const ast = (0, _parse.parse)(file, code);
+    const moduleIdentifiers = await (0, _identifiers.collectModuleIdentifiers)(ast.program);
+    const shadowedBindings = new Set([...moduleIdentifiers.entries()].filter(([, meta]) => meta.declare.length > 0).map(([name]) => name));
+    const perFileUsage = await (0, _format.collectDualPackageUsage)(ast.program, shadowedBindings, file);
+    mergeUsageMaps(usages, perFileUsage);
+  }
+  const diags = await (0, _format.dualPackageHazardDiagnostics)({
+    usages,
+    hazardLevel,
+    cwd: opts.cwd,
+    manifestCache
+  });
+  const byFile = new Map();
+  for (const diag of diags) {
+    const key = diag.filePath ?? files[0];
+    const existing = byFile.get(key) ?? [];
+    existing.push(diag);
+    byFile.set(key, existing);
+  }
+  return byFile;
+};
+exports.collectProjectDualPackageHazards = collectProjectDualPackageHazards;
 const defaultOptions = {
   target: 'commonjs',
   sourceType: 'auto',
@@ -157,6 +199,8 @@ const defaultOptions = {
   importMetaMain: 'shim',
   requireMainStrategy: 'import-meta-main',
   detectCircularRequires: 'off',
+  detectDualPackageHazard: 'warn',
+  dualPackageHazardScope: 'file',
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',

package/dist/cjs/module.d.cts

@@ -1,3 +1,4 @@
-import type { ModuleOptions } from './types.cjs';
+import type { ModuleOptions, Diagnostic } from './types.cjs';
+declare const collectProjectDualPackageHazards: (files: string[], opts: ModuleOptions) => Promise<Map<string, Diagnostic[]>>;
 declare const transform: (filename: string, options?: ModuleOptions) => Promise<string>;
-export { transform };
+export { transform, collectProjectDualPackageHazards };

package/dist/cjs/types.d.cts

@@ -32,6 +32,10 @@ export type ModuleOptions = {
     requireMainStrategy?: 'import-meta-main' | 'realpath';
     /** Detect circular require usage level. */
     detectCircularRequires?: 'off' | 'warn' | 'error';
+    /** Detect divergent import/require usage of the same dual package (default warn). */
+    detectDualPackageHazard?: 'off' | 'warn' | 'error';
+    /** Scope for dual package hazard detection. */
+    dualPackageHazardScope?: 'file' | 'project';
     /** 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

@@ -5,7 +5,7 @@ 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 { transform, collectProjectDualPackageHazards } from './module.js';
 import { parse } from './parse.js';
 import { format } from './format.js';
 import { specifier } from './specifier.js';
@@ -23,6 +23,8 @@ const defaultOptions = {
   importMetaMain: 'shim',
   requireMainStrategy: 'import-meta-main',
   detectCircularRequires: 'off',
+  detectDualPackageHazard: 'warn',
+  dualPackageHazardScope: 'file',
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
@@ -144,6 +146,16 @@ const optionsTable = [{
   short: 'c',
   type: 'string',
   desc: 'Warn/error on circular require (off|warn|error)'
+}, {
+  long: 'detect-dual-package-hazard',
+  short: 'H',
+  type: 'string',
+  desc: 'Warn/error on mixed import/require of dual packages (off|warn|error)'
+}, {
+  long: 'dual-package-hazard-scope',
+  short: undefined,
+  type: 'string',
+  desc: 'Scope for dual package hazard detection (file|project)'
 }, {
   long: 'top-level-await',
   short: 'a',
@@ -237,10 +249,10 @@ const optionsTable = [{
 }];
 const buildHelp = enableColor => {
   const c = colorize(enableColor);
-  const maxFlagLength = Math.max(...optionsTable.map(opt => `  -${opt.short}, --${opt.long}`.length));
+  const maxFlagLength = Math.max(...optionsTable.map(opt => opt.short ? `  -${opt.short}, --${opt.long}`.length : `      --${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 flag = opt.short ? `  -${opt.short}, --${opt.long}` : `      --${opt.long}`;
     const pad = ' '.repeat(Math.max(2, maxFlagLength - flag.length + 2));
     lines.push(`${c.bold(flag)}${pad}${opt.desc}`);
   }
@@ -275,6 +287,8 @@ const toModuleOptions = values => {
     appendJsExtension: appendJsExtension,
     appendDirectoryIndex,
     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,
     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,
@@ -361,6 +375,9 @@ const summarizeDiagnostics = diags => {
 const runFiles = async (files, moduleOpts, io, flags) => {
   const results = [];
   const logger = makeLogger(io.stdout, io.stderr);
+  const hazardScope = moduleOpts.dualPackageHazardScope ?? 'file';
+  const hazardMode = moduleOpts.detectDualPackageHazard ?? 'warn';
+  const projectHazards = hazardScope === 'project' && hazardMode !== 'off' ? await collectProjectDualPackageHazards(files, moduleOpts) : null;
   for (const file of files) {
     const diagnostics = [];
     const original = await readFile(file, 'utf8');
@@ -370,7 +387,8 @@ const runFiles = async (files, moduleOpts, io, flags) => {
       diagnostics: diag => diagnostics.push(diag),
       out: undefined,
       inPlace: false,
-      filePath: file
+      filePath: file,
+      detectDualPackageHazard: hazardScope === 'project' ? 'off' : moduleOpts.detectDualPackageHazard
     };
     let writeTarget;
     if (!flags.dryRun && !flags.list) {
@@ -392,6 +410,10 @@ const runFiles = async (files, moduleOpts, io, flags) => {
     }
     const output = await transform(file, perFileOpts);
     const changed = output !== original;
+    if (projectHazards) {
+      const extras = projectHazards.get(file);
+      if (extras?.length) diagnostics.push(...extras);
+    }
     if (flags.list && changed) {
       logger.info(file);
     }
@@ -441,7 +463,9 @@ const runCli = async ({
     allowPositionals: true,
     options: Object.fromEntries(optionsTable.map(opt => [opt.long, {
       type: opt.type,
-      short: opt.short
+      ...(opt.short ? {
+        short: opt.short
+      } : {})
     }]))
   });
   const logger = makeLogger(stdout, stderr);

package/dist/format.d.ts

@@ -1,9 +1,31 @@
-import type { ParseResult } from 'oxc-parser';
-import type { FormatterOptions } from './types.js';
+import type { Node, ParseResult } from 'oxc-parser';
+import type { Diagnostic, FormatterOptions } from './types.js';
+type HazardLevel = 'warning' | 'error';
+export type PackageUse = {
+    spec: string;
+    subpath: string;
+    loc?: {
+        start: number;
+        end: number;
+    };
+    filePath?: string;
+};
+export type PackageUsage = {
+    imports: PackageUse[];
+    requires: PackageUse[];
+};
+declare const collectDualPackageUsage: (program: Node, shadowedBindings: Set<string>, filePath?: string) => Promise<Map<string, PackageUsage>>;
+declare const dualPackageHazardDiagnostics: (params: {
+    usages: Map<string, PackageUsage>;
+    hazardLevel: HazardLevel;
+    filePath?: string;
+    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>;
-export { format };
+export { format, collectDualPackageUsage, dualPackageHazardDiagnostics };

package/dist/format.js

@@ -1,3 +1,6 @@
+import { builtinModules } from 'node:module';
+import { dirname, join, resolve as pathResolve } from 'node:path';
+import { readFile as fsReadFile, stat as fsStat } from 'node:fs/promises';
 import MagicString from 'magic-string';
 import { hasTopLevelAwait, isAsyncContext } from './helpers/async.js';
 import { isIdentifierName } from './helpers/identifier.js';
@@ -17,6 +20,272 @@ import { collectModuleIdentifiers } from './utils/identifiers.js';
 import { isValidUrl } from './utils/url.js';
 import { ancestorWalk } from './walk.js';
 const isRequireMainMember = (node, shadowed) => node.type === 'MemberExpression' && node.object.type === 'Identifier' && node.object.name === 'require' && !shadowed.has('require') && node.property.type === 'Identifier' && node.property.name === 'main';
+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 stripQuery = value => value.includes('?') || value.includes('#') ? value.split(/[?#]/)[0] ?? value : value;
+const packageFromSpecifier = spec => {
+  const cleaned = stripQuery(spec);
+  if (!cleaned) return null;
+  if (cleaned.startsWith('node:')) return null;
+  if (/^(?:\.?\.?\/|\/)/.test(cleaned)) return null;
+  if (/^[a-zA-Z][a-zA-Z+.-]*:/.test(cleaned)) return null;
+  const parts = cleaned.split('/');
+  if (cleaned.startsWith('@')) {
+    if (parts.length < 2) return null;
+    const pkg = `${parts[0]}/${parts[1]}`;
+    if (builtinSpecifiers.has(pkg) || builtinSpecifiers.has(parts[1] ?? '')) return null;
+    const subpath = parts.slice(2).join('/');
+    return {
+      pkg,
+      subpath
+    };
+  }
+  const pkg = parts[0] ?? '';
+  if (!pkg || builtinSpecifiers.has(pkg)) return null;
+  const subpath = parts.slice(1).join('/');
+  return {
+    pkg,
+    subpath
+  };
+};
+const fileExists = async filename => {
+  try {
+    const stats = await fsStat(filename);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+};
+const findPackageManifest = async (pkg, filePath, cwd) => {
+  const startDir = filePath ? dirname(pathResolve(filePath)) : pathResolve(cwd ?? process.cwd());
+  const seen = new Set();
+  let dir = startDir;
+  while (!seen.has(dir)) {
+    seen.add(dir);
+    const candidate = join(dir, 'node_modules', pkg, 'package.json');
+    if (await fileExists(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+};
+const readPackageManifest = async (pkg, filePath, cwd, cache) => {
+  const start = pathResolve(filePath ? dirname(filePath) : cwd ?? process.cwd());
+  const cacheKey = `${pkg}@${start}`;
+  if (cache.has(cacheKey)) return cache.get(cacheKey);
+  const manifestPath = await findPackageManifest(pkg, filePath, cwd);
+  if (!manifestPath) {
+    cache.set(cacheKey, null);
+    return null;
+  }
+  try {
+    const raw = await fsReadFile(manifestPath, 'utf8');
+    const json = JSON.parse(raw);
+    cache.set(cacheKey, json);
+    return json;
+  } catch {
+    cache.set(cacheKey, null);
+    return null;
+  }
+};
+const analyzeExportsTargets = exportsField => {
+  const root = exportsField && typeof exportsField === 'object' && !Array.isArray(exportsField) ?
+  // @ts-expect-error -- loose lookup of root export condition
+  exportsField['.'] ?? exportsField : exportsField;
+  if (typeof root === 'string') {
+    return {
+      importTarget: root,
+      requireTarget: root
+    };
+  }
+  if (root && typeof root === 'object') {
+    const record = root;
+    const importTarget = typeof record.import === 'string' ? record.import : undefined;
+    const requireTarget = typeof record.require === 'string' ? record.require : undefined;
+    const defaultTarget = typeof record.default === 'string' ? record.default : undefined;
+    return {
+      importTarget: importTarget ?? defaultTarget,
+      requireTarget: requireTarget ?? defaultTarget
+    };
+  }
+  return {
+    importTarget: undefined,
+    requireTarget: undefined
+  };
+};
+const describeDualPackage = pkgJson => {
+  const {
+    importTarget,
+    requireTarget
+  } = analyzeExportsTargets(pkgJson?.exports);
+  const moduleField = typeof pkgJson?.module === 'string' ? pkgJson.module : undefined;
+  const mainField = typeof pkgJson?.main === 'string' ? pkgJson.main : undefined;
+  const typeField = typeof pkgJson?.type === 'string' ? pkgJson.type : undefined;
+  const divergentExports = importTarget && requireTarget && importTarget !== requireTarget;
+  const divergentModuleMain = moduleField && mainField && moduleField !== mainField;
+  const typeModuleMainCjs = typeField === 'module' && typeof mainField === 'string' && mainField.endsWith('.cjs');
+  const hasHazardSignals = divergentExports || divergentModuleMain || typeModuleMainCjs;
+  const details = [];
+  if (divergentExports) {
+    details.push(`exports import -> ${importTarget}, require -> ${requireTarget}`);
+  }
+  if (divergentModuleMain) {
+    details.push(`module -> ${moduleField}, main -> ${mainField}`);
+  }
+  if (typeModuleMainCjs) {
+    details.push(`type: module with CommonJS main (${mainField})`);
+  }
+  return {
+    hasHazardSignals,
+    details,
+    importTarget,
+    requireTarget
+  };
+};
+const recordUsage = (usages, pkg, kind, spec, subpath, loc, filePath) => {
+  const existing = usages.get(pkg) ?? {
+    imports: [],
+    requires: []
+  };
+  const bucket = kind === 'import' ? existing.imports : existing.requires;
+  bucket.push({
+    spec,
+    subpath,
+    loc,
+    filePath
+  });
+  usages.set(pkg, existing);
+};
+const collectDualPackageUsage = async (program, shadowedBindings, filePath) => {
+  const usages = new Map();
+  await ancestorWalk(program, {
+    enter(node) {
+      if (node.type === 'ImportDeclaration' && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) recordUsage(usages, pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        }, filePath);
+      }
+      if (node.type === 'ExportNamedDeclaration' && node.source && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) recordUsage(usages, pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        }, filePath);
+      }
+      if (node.type === 'ExportAllDeclaration' && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) recordUsage(usages, pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        }, filePath);
+      }
+      if (node.type === 'ImportExpression' && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) recordUsage(usages, pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        }, filePath);
+      }
+      if (node.type === 'CallExpression' && isStaticRequire(node, shadowedBindings)) {
+        const arg = node.arguments[0];
+        if (arg?.type === 'Literal' && typeof arg.value === 'string') {
+          const pkg = packageFromSpecifier(arg.value);
+          if (pkg) recordUsage(usages, pkg.pkg, 'require', arg.value, pkg.subpath, {
+            start: arg.start,
+            end: arg.end
+          }, filePath);
+        }
+      }
+    }
+  });
+  return usages;
+};
+const dualPackageHazardDiagnostics = async params => {
+  const {
+    usages,
+    hazardLevel,
+    filePath,
+    cwd
+  } = params;
+  const manifestCache = params.manifestCache ?? new Map();
+  const diags = [];
+  for (const [pkg, usage] of usages) {
+    const hasImport = usage.imports.length > 0;
+    const hasRequire = usage.requires.length > 0;
+    const combined = [...usage.imports, ...usage.requires];
+    const hasRoot = combined.some(entry => !entry.subpath);
+    const hasSubpath = combined.some(entry => Boolean(entry.subpath));
+    const origin = usage.imports[0] ?? usage.requires[0];
+    const diagFile = origin?.filePath ?? filePath;
+    if (hasImport && hasRequire) {
+      const importSpecs = usage.imports.map(u => u.subpath ? `${pkg}/${u.subpath}` : pkg);
+      const requireSpecs = usage.requires.map(u => u.subpath ? `${pkg}/${u.subpath}` : pkg);
+      diags.push({
+        level: hazardLevel,
+        code: 'dual-package-mixed-specifiers',
+        message: `Package '${pkg}' is loaded via import (${importSpecs.join(', ')}) and require (${requireSpecs.join(', ')}); conditional exports can instantiate it twice.`,
+        filePath: diagFile,
+        loc: origin?.loc
+      });
+    }
+    if (hasRoot && hasSubpath) {
+      const subpaths = combined.filter(entry => entry.subpath).map(entry => `${pkg}/${entry.subpath}`);
+      const originSubpath = combined.find(entry => entry.subpath) ?? combined[0];
+      diags.push({
+        level: hazardLevel,
+        code: 'dual-package-subpath',
+        message: `Package '${pkg}' is referenced via root specifier '${pkg}' and subpath(s) ${subpaths.join(', ')}; mixing them loads separate module instances.`,
+        filePath: originSubpath?.filePath ?? filePath,
+        loc: originSubpath?.loc
+      });
+    }
+    if (hasImport && hasRequire) {
+      const manifest = await readPackageManifest(pkg, diagFile, cwd, manifestCache);
+      if (manifest) {
+        const meta = describeDualPackage(manifest);
+        if (meta.hasHazardSignals) {
+          const detail = meta.details.length ? ` (${meta.details.join('; ')})` : '';
+          diags.push({
+            level: hazardLevel,
+            code: 'dual-package-conditional-exports',
+            message: `Package '${pkg}' exposes different entry points for import vs require${detail}. Mixed usage can produce distinct instances.`,
+            filePath: diagFile,
+            loc: origin?.loc
+          });
+        }
+      }
+    }
+  }
+  return diags;
+};
+const detectDualPackageHazards = async params => {
+  const {
+    program,
+    shadowedBindings,
+    hazardLevel,
+    filePath,
+    cwd,
+    diagOnce
+  } = params;
+  const manifestCache = new Map();
+  const usages = await collectDualPackageUsage(program, shadowedBindings, filePath);
+  const diags = await dualPackageHazardDiagnostics({
+    usages,
+    hazardLevel,
+    filePath,
+    cwd,
+    manifestCache
+  });
+  for (const diag of diags) {
+    diagOnce(diag.level, diag.code, diag.message, diag.loc);
+  }
+};
 
 /**
  * Node added support for import.meta.main.
@@ -46,22 +315,35 @@ const format = async (src, ast, opts) => {
     // eslint-disable-next-line no-console -- used for opt-in diagnostics
     console.error(diag.message);
   };
-  const warnOnce = (codeId, message, loc) => {
-    const key = `${codeId}:${loc?.start ?? ''}`;
+  const diagOnce = (level, codeId, message, loc) => {
+    const key = `${level}:${codeId}:${loc?.start ?? ''}`;
     if (warned.has(key)) return;
     warned.add(key);
     emitDiagnostic({
-      level: 'warning',
+      level,
       code: codeId,
       message,
       filePath: opts.filePath,
       loc
     });
   };
+  const warnOnce = (codeId, message, loc) => diagOnce('warning', codeId, message, loc);
   const transformMode = opts.transformSyntax;
   const fullTransform = transformMode === true;
   const moduleIdentifiers = await collectModuleIdentifiers(ast.program);
   const shadowedBindings = new Set([...moduleIdentifiers.entries()].filter(([, meta]) => meta.declare.length > 0).map(([name]) => name));
+  const hazardMode = opts.detectDualPackageHazard ?? 'warn';
+  if (hazardMode !== 'off') {
+    const hazardLevel = hazardMode === 'error' ? 'error' : 'warning';
+    await detectDualPackageHazards({
+      program: ast.program,
+      shadowedBindings,
+      hazardLevel,
+      filePath: opts.filePath,
+      cwd: opts.cwd,
+      diagOnce
+    });
+  }
   if (opts.target === 'module' && fullTransform) {
     if (shadowedBindings.has('module') || shadowedBindings.has('exports')) {
       throw new Error('Cannot transform to ESM: module or exports is shadowed in module scope.');
@@ -246,4 +528,4 @@ const format = async (src, ast, opts) => {
   }
   return code.toString();
 };
-export { format };
+export { format, collectDualPackageUsage, dualPackageHazardDiagnostics };

package/dist/module.d.ts

@@ -1,3 +1,4 @@
-import type { ModuleOptions } from './types.js';
+import type { ModuleOptions, Diagnostic } from './types.js';
+declare const collectProjectDualPackageHazards: (files: string[], opts: ModuleOptions) => Promise<Map<string, Diagnostic[]>>;
 declare const transform: (filename: string, options?: ModuleOptions) => Promise<string>;
-export { transform };
+export { transform, collectProjectDualPackageHazards };

package/dist/module.js

@@ -2,13 +2,14 @@ import { resolve } from 'node:path';
 import { readFile, writeFile } from 'node:fs/promises';
 import { specifier } from './specifier.js';
 import { parse } from './parse.js';
-import { format } from './format.js';
+import { format, collectDualPackageUsage, dualPackageHazardDiagnostics } from './format.js';
 import { getLangFromExt } from './utils/lang.js';
 import { builtinModules } from 'node:module';
 import { resolve as pathResolve, dirname as pathDirname, extname, join } from 'node:path';
 import { readFile as fsReadFile, stat } from 'node:fs/promises';
 import { parse as parseModule } from './parse.js';
 import { walk } from './walk.js';
+import { collectModuleIdentifiers } from './utils/identifiers.js';
 const collapseSpecifier = value => value.replace(/['"`+)\s]|new String\(/g, '');
 const builtinSpecifiers = new Set(builtinModules.map(mod => mod.startsWith('node:') ? mod.slice(5) : mod).flatMap(mod => {
   const parts = mod.split('/');
@@ -141,6 +142,46 @@ const detectCircularRequireGraph = async (entryFile, mode, dirIndex) => {
   };
   await dfs(entryFile, []);
 };
+const mergeUsageMaps = (target, source) => {
+  for (const [pkg, usage] of source) {
+    const existing = target.get(pkg) ?? {
+      imports: [],
+      requires: []
+    };
+    existing.imports.push(...usage.imports);
+    existing.requires.push(...usage.requires);
+    target.set(pkg, existing);
+  }
+};
+const collectProjectDualPackageHazards = async (files, opts) => {
+  const hazardMode = opts.detectDualPackageHazard ?? 'warn';
+  if (hazardMode === 'off') return new Map();
+  const hazardLevel = hazardMode === 'error' ? 'error' : 'warning';
+  const usages = new Map();
+  const manifestCache = new Map();
+  for (const file of files) {
+    const code = await readFile(file, 'utf8');
+    const ast = parseModule(file, code);
+    const moduleIdentifiers = await collectModuleIdentifiers(ast.program);
+    const shadowedBindings = new Set([...moduleIdentifiers.entries()].filter(([, meta]) => meta.declare.length > 0).map(([name]) => name));
+    const perFileUsage = await collectDualPackageUsage(ast.program, shadowedBindings, file);
+    mergeUsageMaps(usages, perFileUsage);
+  }
+  const diags = await dualPackageHazardDiagnostics({
+    usages,
+    hazardLevel,
+    cwd: opts.cwd,
+    manifestCache
+  });
+  const byFile = new Map();
+  for (const diag of diags) {
+    const key = diag.filePath ?? files[0];
+    const existing = byFile.get(key) ?? [];
+    existing.push(diag);
+    byFile.set(key, existing);
+  }
+  return byFile;
+};
 const defaultOptions = {
   target: 'commonjs',
   sourceType: 'auto',
@@ -154,6 +195,8 @@ const defaultOptions = {
   importMetaMain: 'shim',
   requireMainStrategy: 'import-meta-main',
   detectCircularRequires: 'off',
+  detectDualPackageHazard: 'warn',
+  dualPackageHazardScope: 'file',
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
@@ -197,4 +240,4 @@ const transform = async (filename, options = defaultOptions) => {
   }
   return source;
 };
-export { transform };
+export { transform, collectProjectDualPackageHazards };

package/dist/types.d.ts

@@ -32,6 +32,10 @@ export type ModuleOptions = {
     requireMainStrategy?: 'import-meta-main' | 'realpath';
     /** Detect circular require usage level. */
     detectCircularRequires?: 'off' | 'warn' | 'error';
+    /** Detect divergent import/require usage of the same dual package (default warn). */
+    detectDualPackageHazard?: 'off' | 'warn' | 'error';
+    /** Scope for dual package hazard detection. */
+    dualPackageHazardScope?: 'file' | 'project';
     /** 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.3.1",
+  "version": "1.4.0-rc.1",
   "description": "Bidirectional transform for ES modules and CommonJS.",
   "type": "module",
   "main": "dist/module.js",