@knighted/module 1.4.0-rc.0 → 1.4.0-rc.1

package/README.md

@@ -131,6 +131,7 @@ type ModuleOptions = {
   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'
@@ -156,7 +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 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.
+- `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

@@ -30,6 +30,7 @@ const defaultOptions = {
   requireMainStrategy: 'import-meta-main',
   detectCircularRequires: 'off',
   detectDualPackageHazard: 'warn',
+  dualPackageHazardScope: 'file',
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
@@ -156,6 +157,11 @@ const optionsTable = [{
   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',
@@ -249,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}`);
   }
@@ -288,6 +294,7 @@ const toModuleOptions = values => {
     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,
@@ -374,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');
@@ -383,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) {
@@ -405,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);
     }
@@ -454,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,7 @@
 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");
@@ -153,98 +153,147 @@ const describeDualPackage = pkgJson => {
     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);
+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) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+        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) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+        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) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+        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) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+        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) record(pkg.pkg, 'require', arg.value, pkg.subpath, {
+          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);
-      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);
+      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}`);
-      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);
+      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, filePath, cwd, manifestCache);
+      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('; ')})` : '';
-          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);
+          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);
+  }
 };
 
 /**

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',
@@ -158,6 +200,7 @@ const defaultOptions = {
   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

@@ -34,6 +34,8 @@ export type ModuleOptions = {
     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';
@@ -24,6 +24,7 @@ const defaultOptions = {
   requireMainStrategy: 'import-meta-main',
   detectCircularRequires: 'off',
   detectDualPackageHazard: 'warn',
+  dualPackageHazardScope: 'file',
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
@@ -150,6 +151,11 @@ const optionsTable = [{
   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 +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}`);
   }
@@ -282,6 +288,7 @@ const toModuleOptions = values => {
     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,
@@ -368,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');
@@ -377,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) {
@@ -399,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);
     }
@@ -448,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

@@ -146,98 +146,145 @@ const describeDualPackage = pkgJson => {
     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);
+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) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+        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) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+        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) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+        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) record(pkg.pkg, 'import', node.source.value, pkg.subpath, {
+        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) record(pkg.pkg, 'require', arg.value, pkg.subpath, {
+          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);
-      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);
+      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}`);
-      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);
+      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, filePath, cwd, manifestCache);
+      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('; ')})` : '';
-          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);
+          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);
+  }
 };
 
 /**
@@ -481,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',
@@ -155,6 +196,7 @@ const defaultOptions = {
   requireMainStrategy: 'import-meta-main',
   detectCircularRequires: 'off',
   detectDualPackageHazard: 'warn',
+  dualPackageHazardScope: 'file',
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
@@ -198,4 +240,4 @@ const transform = async (filename, options = defaultOptions) => {
   }
   return source;
 };
-export { transform };
+export { transform, collectProjectDualPackageHazards };

package/dist/types.d.ts

@@ -34,6 +34,8 @@ export type ModuleOptions = {
     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.4.0-rc.0",
+  "version": "1.4.0-rc.1",
   "description": "Bidirectional transform for ES modules and CommonJS.",
   "type": "module",
   "main": "dist/module.js",