@knighted/module 1.5.0-rc.0 → 1.5.1

package/README.md

@@ -4,14 +4,14 @@
 [![codecov](https://codecov.io/gh/knightedcodemonkey/module/graph/badge.svg?token=AjayQQxghy)](https://codecov.io/gh/knightedcodemonkey/module)
 [![NPM version](https://img.shields.io/npm/v/@knighted/module.svg)](https://www.npmjs.com/package/@knighted/module)
 
-Node.js utility for transforming a JavaScript or TypeScript file from an ES module to CommonJS, or vice versa.
+Node.js utility for transforming a JavaScript or TypeScript file from CommonJS to an ES module, or vice versa.
 
-- ES module ➡️ CommonJS
 - CommonJS ➡️ ES module
+- ES module ➡️ CommonJS
 
 Highlights
 
-- ESM ➡️ CJS and CJS ➡️ ESM with one function call.
+- CJS ➡️ ESM and ESM ➡️ CJS with one function call.
 - Defaults to safe CommonJS output: strict live bindings, import.meta shims, and specifier preservation.
 - Configurable lowering modes: full syntax transforms or globals-only.
 - Specifier tools: add extensions, add directory indexes, or map with a custom callback.
@@ -25,7 +25,7 @@ By default `@knighted/module` transforms the one-to-one [differences between ES
 
 ## Requirements
 
-- Node 22 or 24 (tested on 22.21.1 and 24.11.1)
+- Node 22.21.1+ or 24+
 
 ## Install
 
@@ -134,6 +134,7 @@ type ModuleOptions = {
   detectCircularRequires?: 'off' | 'warn' | 'error'
   detectDualPackageHazard?: 'off' | 'warn' | 'error'
   dualPackageHazardScope?: 'file' | 'project'
+  dualPackageHazardAllowlist?: string[]
   requireSource?: 'builtin' | 'create-require'
   importMetaPrelude?: 'off' | 'auto' | 'on'
   cjsDefault?: 'module-exports' | 'auto' | 'none'
@@ -162,6 +163,7 @@ type ModuleOptions = {
 - `detectCircularRequires` (`off`): optionally detect relative static require cycles across `.js`/`.mjs`/`.cjs`/`.ts`/`.mts`/`.cts` (realpath-normalized) 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.
+- `dualPackageHazardAllowlist` (`[]`): suppress dual-package hazard diagnostics for the listed packages. Accepts an array in the API; entries are trimmed and empty values dropped. The CLI flag `--dual-package-hazard-allowlist pkg1,pkg2` parses a comma- or space-separated string into this array. Applies to both `file` and `project` scopes.
 - `topLevelAwait` (`error`): throw, wrap, or preserve when TLA appears in CommonJS output. `wrap` runs the file body inside an async IIFE (exports may resolve after the initial tick); `preserve` leaves `await` at top level, which Node will reject for CJS.
 - `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

@@ -32,6 +32,7 @@ const defaultOptions = {
   detectCircularRequires: 'off',
   detectDualPackageHazard: 'warn',
   dualPackageHazardScope: 'file',
+  dualPackageHazardAllowlist: [],
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
@@ -164,6 +165,11 @@ const optionsTable = [{
   short: undefined,
   type: 'string',
   desc: 'Scope for dual package hazard detection (file|project)'
+}, {
+  long: 'dual-package-hazard-allowlist',
+  short: undefined,
+  type: 'string',
+  desc: 'Comma-separated packages to ignore for dual package hazard checks'
 }, {
   long: 'top-level-await',
   short: 'a',
@@ -287,12 +293,17 @@ const parseAppendDirectoryIndex = value => {
   if (value === 'false') return false;
   return value;
 };
+const parseAllowlist = value => {
+  const values = value === undefined ? [] : Array.isArray(value) ? value : [value];
+  return values.flatMap(entry => String(entry).split(',')).map(item => item.trim()).filter(Boolean);
+};
 const toModuleOptions = values => {
   const target = parseEnum(values.target, ['module', 'commonjs']) ?? defaultOptions.target;
   const transformSyntax = parseTransformSyntax(values['transform-syntax']);
   const rewriteTemplateLiterals = parseEnum(values['rewrite-template-literals'], ['allow', 'static-only']) ?? defaultOptions.rewriteTemplateLiterals;
   const appendJsExtension = parseEnum(values['append-js-extension'], ['off', 'relative-only', 'all']);
   const appendDirectoryIndex = parseAppendDirectoryIndex(values['append-directory-index']);
+  const dualPackageHazardAllowlist = parseAllowlist(values['dual-package-hazard-allowlist']);
   const opts = {
     ...defaultOptions,
     target,
@@ -304,6 +315,7 @@ const toModuleOptions = values => {
     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,
+    dualPackageHazardAllowlist,
     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

@@ -149,6 +149,9 @@ const describeDualPackage = pkgJson => {
     requireTarget
   };
 };
+const normalizeAllowlist = allowlist => {
+  return new Set([...(allowlist ?? [])].map(item => item.trim()).filter(item => item.length > 0));
+};
 const recordUsage = (usages, pkg, kind, spec, subpath, loc, filePath) => {
   const existing = usages.get(pkg) ?? {
     imports: [],
@@ -218,8 +221,10 @@ const dualPackageHazardDiagnostics = async params => {
     cwd
   } = params;
   const manifestCache = params.manifestCache ?? new Map();
+  const allowlist = normalizeAllowlist(params.hazardAllowlist);
   const diags = [];
   for (const [pkg, usage] of usages) {
+    if (allowlist.has(pkg)) continue;
     const hasImport = usage.imports.length > 0;
     const hasRequire = usage.requires.length > 0;
     const combined = [...usage.imports, ...usage.requires];
@@ -286,7 +291,8 @@ const detectDualPackageHazards = async params => {
     hazardLevel,
     filePath,
     cwd,
-    manifestCache
+    manifestCache,
+    hazardAllowlist: params.hazardAllowlist
   });
   for (const diag of diags) {
     diagOnce(diag.level, diag.code, diag.message, diag.loc);
@@ -341,7 +347,8 @@ async function format(src, ast, opts) {
       hazardLevel,
       filePath: opts.filePath,
       cwd: opts.cwd,
-      diagOnce
+      diagOnce,
+      hazardAllowlist: opts.dualPackageHazardAllowlist
     });
   }
   if (opts.target === 'module' && fullTransform) {

package/dist/cjs/format.d.cts

@@ -22,6 +22,7 @@ declare const dualPackageHazardDiagnostics: (params: {
     filePath?: string;
     cwd?: string;
     manifestCache?: Map<string, any | null>;
+    hazardAllowlist?: Iterable<string>;
 }) => Promise<Diagnostic[]>;
 declare function format(src: string, ast: ParseResult, opts: FormatterOptions & {
     sourceMap: true;

package/dist/cjs/module.cjs

@@ -171,8 +171,10 @@ const collectProjectDualPackageHazards = async (files, opts) => {
   const diags = await (0, _format.dualPackageHazardDiagnostics)({
     usages,
     hazardLevel,
+    filePath: opts.filePath,
     cwd: opts.cwd,
-    manifestCache
+    manifestCache,
+    hazardAllowlist: opts.dualPackageHazardAllowlist
   });
   const byFile = new Map();
   for (const diag of diags) {
@@ -200,6 +202,7 @@ const createDefaultOptions = () => ({
   detectCircularRequires: 'off',
   detectDualPackageHazard: 'warn',
   dualPackageHazardScope: 'file',
+  dualPackageHazardAllowlist: [],
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',

package/dist/cjs/types.d.cts

@@ -40,6 +40,8 @@ export type ModuleOptions = {
     detectDualPackageHazard?: 'off' | 'warn' | 'error';
     /** Scope for dual package hazard detection. */
     dualPackageHazardScope?: 'file' | 'project';
+    /** Packages to ignore for dual package hazard diagnostics. */
+    dualPackageHazardAllowlist?: string[];
     /** 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

@@ -26,6 +26,7 @@ const defaultOptions = {
   detectCircularRequires: 'off',
   detectDualPackageHazard: 'warn',
   dualPackageHazardScope: 'file',
+  dualPackageHazardAllowlist: [],
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
@@ -158,6 +159,11 @@ const optionsTable = [{
   short: undefined,
   type: 'string',
   desc: 'Scope for dual package hazard detection (file|project)'
+}, {
+  long: 'dual-package-hazard-allowlist',
+  short: undefined,
+  type: 'string',
+  desc: 'Comma-separated packages to ignore for dual package hazard checks'
 }, {
   long: 'top-level-await',
   short: 'a',
@@ -281,12 +287,17 @@ const parseAppendDirectoryIndex = value => {
   if (value === 'false') return false;
   return value;
 };
+const parseAllowlist = value => {
+  const values = value === undefined ? [] : Array.isArray(value) ? value : [value];
+  return values.flatMap(entry => String(entry).split(',')).map(item => item.trim()).filter(Boolean);
+};
 const toModuleOptions = values => {
   const target = parseEnum(values.target, ['module', 'commonjs']) ?? defaultOptions.target;
   const transformSyntax = parseTransformSyntax(values['transform-syntax']);
   const rewriteTemplateLiterals = parseEnum(values['rewrite-template-literals'], ['allow', 'static-only']) ?? defaultOptions.rewriteTemplateLiterals;
   const appendJsExtension = parseEnum(values['append-js-extension'], ['off', 'relative-only', 'all']);
   const appendDirectoryIndex = parseAppendDirectoryIndex(values['append-directory-index']);
+  const dualPackageHazardAllowlist = parseAllowlist(values['dual-package-hazard-allowlist']);
   const opts = {
     ...defaultOptions,
     target,
@@ -298,6 +309,7 @@ const toModuleOptions = values => {
     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,
+    dualPackageHazardAllowlist,
     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.d.ts

@@ -22,6 +22,7 @@ declare const dualPackageHazardDiagnostics: (params: {
     filePath?: string;
     cwd?: string;
     manifestCache?: Map<string, any | null>;
+    hazardAllowlist?: Iterable<string>;
 }) => Promise<Diagnostic[]>;
 declare function format(src: string, ast: ParseResult, opts: FormatterOptions & {
     sourceMap: true;

package/dist/format.js

@@ -141,6 +141,9 @@ const describeDualPackage = pkgJson => {
     requireTarget
   };
 };
+const normalizeAllowlist = allowlist => {
+  return new Set([...(allowlist ?? [])].map(item => item.trim()).filter(item => item.length > 0));
+};
 const recordUsage = (usages, pkg, kind, spec, subpath, loc, filePath) => {
   const existing = usages.get(pkg) ?? {
     imports: [],
@@ -209,8 +212,10 @@ const dualPackageHazardDiagnostics = async params => {
     cwd
   } = params;
   const manifestCache = params.manifestCache ?? new Map();
+  const allowlist = normalizeAllowlist(params.hazardAllowlist);
   const diags = [];
   for (const [pkg, usage] of usages) {
+    if (allowlist.has(pkg)) continue;
     const hasImport = usage.imports.length > 0;
     const hasRequire = usage.requires.length > 0;
     const combined = [...usage.imports, ...usage.requires];
@@ -276,7 +281,8 @@ const detectDualPackageHazards = async params => {
     hazardLevel,
     filePath,
     cwd,
-    manifestCache
+    manifestCache,
+    hazardAllowlist: params.hazardAllowlist
   });
   for (const diag of diags) {
     diagOnce(diag.level, diag.code, diag.message, diag.loc);
@@ -331,7 +337,8 @@ async function format(src, ast, opts) {
       hazardLevel,
       filePath: opts.filePath,
       cwd: opts.cwd,
-      diagOnce
+      diagOnce,
+      hazardAllowlist: opts.dualPackageHazardAllowlist
     });
   }
   if (opts.target === 'module' && fullTransform) {

package/dist/module.js

@@ -167,8 +167,10 @@ const collectProjectDualPackageHazards = async (files, opts) => {
   const diags = await dualPackageHazardDiagnostics({
     usages,
     hazardLevel,
+    filePath: opts.filePath,
     cwd: opts.cwd,
-    manifestCache
+    manifestCache,
+    hazardAllowlist: opts.dualPackageHazardAllowlist
   });
   const byFile = new Map();
   for (const diag of diags) {
@@ -195,6 +197,7 @@ const createDefaultOptions = () => ({
   detectCircularRequires: 'off',
   detectDualPackageHazard: 'warn',
   dualPackageHazardScope: 'file',
+  dualPackageHazardAllowlist: [],
   requireSource: 'builtin',
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',

package/dist/types.d.ts

@@ -40,6 +40,8 @@ export type ModuleOptions = {
     detectDualPackageHazard?: 'off' | 'warn' | 'error';
     /** Scope for dual package hazard detection. */
     dualPackageHazardScope?: 'file' | 'project';
+    /** Packages to ignore for dual package hazard diagnostics. */
+    dualPackageHazardAllowlist?: string[];
     /** 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.5.0-rc.0",
+  "version": "1.5.1",
   "description": "Bidirectional transform for ES modules and CommonJS.",
   "type": "module",
   "main": "dist/module.js",
@@ -38,7 +38,7 @@
     "build:types": "tsc --emitDeclarationOnly",
     "build:dual": "babel-dual-package src --extensions .ts",
     "build": "npm run build:types && npm run build:dual",
-    "cycles": "madge --circular src --extensions ts,js --ts-config tsconfig.json",
+    "cycles": "oxlint --import-plugin --tsconfig tsconfig.json -A all -D import/no-cycle src test",
     "prepack": "npm run build"
   },
   "keywords": [
@@ -64,29 +64,22 @@
     "url": "https://github.com/knightedcodemonkey/module/issues"
   },
   "devDependencies": {
-    "@knighted/dump": "^1.0.3",
     "@types/node": "^22.19.3",
     "babel-dual-package": "^1.2.3",
-    "c8": "^10.1.3",
+    "c8": "^11.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
-    "madge": "^8.0.0",
-    "oxlint": "^1.35.0",
+    "oxlint": "^1.51.0",
     "prettier": "^3.7.4",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "glob": "^13.0.0",
+    "glob": "^13.0.6",
     "magic-string": "^0.30.21",
-    "oxc-parser": "^0.105.0",
+    "oxc-parser": "^0.116.0",
     "periscopic": "^4.0.2"
   },
-  "overrides": {
-    "module-lookup-amd": {
-      "glob": "^9.0.0"
-    }
-  },
   "prettier": {
     "arrowParens": "avoid",
     "printWidth": 90,