@knighted/module 1.3.1 → 1.4.0-rc.0

package/README.md

@@ -130,6 +130,7 @@ type ModuleOptions = {
   importMetaMain?: 'shim' | 'warn' | 'error'
   requireMainStrategy?: 'import-meta-main' | 'realpath'
   detectCircularRequires?: 'off' | 'warn' | 'error'
+  detectDualPackageHazard?: 'off' | 'warn' | 'error'
   requireSource?: 'builtin' | 'create-require'
   importMetaPrelude?: 'off' | 'auto' | 'on'
   cjsDefault?: 'module-exports' | 'auto' | 'none'
@@ -155,6 +156,7 @@ 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 a file mixes `import` and `require` of the same package or combines root and subpath specifiers that can resolve to separate module instances (dual packages). Set to `error` to fail the transform.
 - `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,7 @@ const defaultOptions = {
   importMetaMain: 'shim',
   requireMainStrategy: 'import-meta-main',
   detectCircularRequires: 'off',
+  detectDualPackageHazard: 'warn',
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
@@ -150,6 +151,11 @@ 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: 'top-level-await',
   short: 'a',
@@ -281,6 +287,7 @@ 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,
     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,

package/dist/cjs/format.cjs

@@ -4,6 +4,9 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.format = 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,225 @@ 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 detectDualPackageHazards = async params => {
+  const {
+    program,
+    shadowedBindings,
+    hazardLevel,
+    filePath,
+    cwd,
+    diagOnce
+  } = params;
+  const usages = new Map();
+  const manifestCache = new Map();
+  const record = (pkg, kind, spec, subpath, loc) => {
+    const existing = usages.get(pkg) ?? {
+      imports: [],
+      requires: []
+    };
+    const bucket = kind === 'import' ? existing.imports : existing.requires;
+    bucket.push({
+      spec,
+      subpath,
+      loc
+    });
+    usages.set(pkg, existing);
+  };
+  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) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        });
+      }
+      if (node.type === 'ExportNamedDeclaration' && node.source && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        });
+      }
+      if (node.type === 'ExportAllDeclaration' && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        });
+      }
+      if (node.type === 'ImportExpression' && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        });
+      }
+      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) record(pkg.pkg, 'require', arg.value, pkg.subpath, {
+            start: arg.start,
+            end: arg.end
+          });
+        }
+      }
+    }
+  });
+  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));
+    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);
+      diagOnce(hazardLevel, 'dual-package-mixed-specifiers', `Package '${pkg}' is loaded via import (${importSpecs.join(', ')}) and require (${requireSpecs.join(', ')}); conditional exports can instantiate it twice.`, usage.imports[0]?.loc ?? usage.requires[0]?.loc);
+    }
+    if (hasRoot && hasSubpath) {
+      const subpaths = combined.filter(entry => entry.subpath).map(entry => `${pkg}/${entry.subpath}`);
+      diagOnce(hazardLevel, 'dual-package-subpath', `Package '${pkg}' is referenced via root specifier '${pkg}' and subpath(s) ${subpaths.join(', ')}; mixing them loads separate module instances.`, combined.find(entry => entry.subpath)?.loc ?? combined[0]?.loc);
+    }
+    if (hasImport && hasRequire) {
+      const manifest = await readPackageManifest(pkg, filePath, cwd, manifestCache);
+      if (manifest) {
+        const meta = describeDualPackage(manifest);
+        if (meta.hasHazardSignals) {
+          const detail = meta.details.length ? ` (${meta.details.join('; ')})` : '';
+          diagOnce(hazardLevel, 'dual-package-conditional-exports', `Package '${pkg}' exposes different entry points for import vs require${detail}. Mixed usage can produce distinct instances.`, usage.imports[0]?.loc ?? usage.requires[0]?.loc);
+        }
+      }
+    }
+  }
+};
 
 /**
  * Node added support for import.meta.main.
@@ -53,22 +275,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/module.cjs

@@ -157,6 +157,7 @@ const defaultOptions = {
   importMetaMain: 'shim',
   requireMainStrategy: 'import-meta-main',
   detectCircularRequires: 'off',
+  detectDualPackageHazard: 'warn',
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',

package/dist/cjs/types.d.cts

@@ -32,6 +32,8 @@ 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';
     /** 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

@@ -23,6 +23,7 @@ const defaultOptions = {
   importMetaMain: 'shim',
   requireMainStrategy: 'import-meta-main',
   detectCircularRequires: 'off',
+  detectDualPackageHazard: 'warn',
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
@@ -144,6 +145,11 @@ 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: 'top-level-await',
   short: 'a',
@@ -275,6 +281,7 @@ 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,
     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,

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,225 @@ 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 detectDualPackageHazards = async params => {
+  const {
+    program,
+    shadowedBindings,
+    hazardLevel,
+    filePath,
+    cwd,
+    diagOnce
+  } = params;
+  const usages = new Map();
+  const manifestCache = new Map();
+  const record = (pkg, kind, spec, subpath, loc) => {
+    const existing = usages.get(pkg) ?? {
+      imports: [],
+      requires: []
+    };
+    const bucket = kind === 'import' ? existing.imports : existing.requires;
+    bucket.push({
+      spec,
+      subpath,
+      loc
+    });
+    usages.set(pkg, existing);
+  };
+  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) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        });
+      }
+      if (node.type === 'ExportNamedDeclaration' && node.source && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        });
+      }
+      if (node.type === 'ExportAllDeclaration' && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        });
+      }
+      if (node.type === 'ImportExpression' && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        const pkg = packageFromSpecifier(node.source.value);
+        if (pkg) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+          start: node.source.start,
+          end: node.source.end
+        });
+      }
+      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) record(pkg.pkg, 'require', arg.value, pkg.subpath, {
+            start: arg.start,
+            end: arg.end
+          });
+        }
+      }
+    }
+  });
+  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));
+    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);
+      diagOnce(hazardLevel, 'dual-package-mixed-specifiers', `Package '${pkg}' is loaded via import (${importSpecs.join(', ')}) and require (${requireSpecs.join(', ')}); conditional exports can instantiate it twice.`, usage.imports[0]?.loc ?? usage.requires[0]?.loc);
+    }
+    if (hasRoot && hasSubpath) {
+      const subpaths = combined.filter(entry => entry.subpath).map(entry => `${pkg}/${entry.subpath}`);
+      diagOnce(hazardLevel, 'dual-package-subpath', `Package '${pkg}' is referenced via root specifier '${pkg}' and subpath(s) ${subpaths.join(', ')}; mixing them loads separate module instances.`, combined.find(entry => entry.subpath)?.loc ?? combined[0]?.loc);
+    }
+    if (hasImport && hasRequire) {
+      const manifest = await readPackageManifest(pkg, filePath, cwd, manifestCache);
+      if (manifest) {
+        const meta = describeDualPackage(manifest);
+        if (meta.hasHazardSignals) {
+          const detail = meta.details.length ? ` (${meta.details.join('; ')})` : '';
+          diagOnce(hazardLevel, 'dual-package-conditional-exports', `Package '${pkg}' exposes different entry points for import vs require${detail}. Mixed usage can produce distinct instances.`, usage.imports[0]?.loc ?? usage.requires[0]?.loc);
+        }
+      }
+    }
+  }
+};
 
 /**
  * Node added support for import.meta.main.
@@ -46,22 +268,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.');

package/dist/module.js

@@ -154,6 +154,7 @@ const defaultOptions = {
   importMetaMain: 'shim',
   requireMainStrategy: 'import-meta-main',
   detectCircularRequires: 'off',
+  detectDualPackageHazard: 'warn',
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',

package/dist/types.d.ts

@@ -32,6 +32,8 @@ 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';
     /** 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.0",
   "description": "Bidirectional transform for ES modules and CommonJS.",
   "type": "module",
   "main": "dist/module.js",