@knighted/duel 3.2.2 → 3.2.4

package/README.md

@@ -53,48 +53,41 @@ And then running it:
 npm run build
 ```
 
-If everything worked, you should have an ESM build inside of `dist` and a CJS build inside of `dist/cjs`. Now you can update your [`exports`](https://nodejs.org/api/packages.html#exports) to match the build output.
+If everything worked, you should have an ESM build inside of `dist` and a CJS build inside of `dist/cjs`. You can manually update your [`exports`](https://nodejs.org/api/packages.html#exports) to match the build output, or run `duel --exports <mode>` to generate them automatically (see [docs/exports.md](docs/exports.md)).
 
 It should work similarly for a CJS-first project. Except, your package.json file would use `"type": "commonjs"` and the dual build directory is in `dist/esm`.
 
-### Output directories
-
-If you prefer to have both builds in directories inside of your defined `outDir`, you can use the `--dirs` option.
+> [!IMPORTANT]
+> This works best if your CJS-first project uses file extensions in _relative_ specifiers. That is acceptable in CJS and [required in ESM](https://nodejs.org/api/esm.html#import-specifiers). `duel` does not rewrite bare specifiers or remap relative specifiers to directory indexes.
 
-```json
-"scripts": {
-  "build": "duel --dirs"
-}
-```
-
-Assuming an `outDir` of `dist`, running the above will create `dist/esm` and `dist/cjs` directories.
-
-### Module transforms
+> [!NOTE]
+> While `duel` runs it briefly swaps in a temporary package.json with the needed `type`; your original file is restored when the build finishes.
 
-TypeScript will throw compiler errors when using `import.meta` globals while targeting a CommonJS dual build, but _will not_ throw compiler errors when the inverse is true, i.e. using CommonJS globals (`__filename`, `__dirname`, etc.) while targeting an ES module dual build. There is an [open issue](https://github.com/microsoft/TypeScript/issues/58658) regarding this asymmetry. Prefer the single-switch `--mode` interface: `--mode globals` (equivalent to `--modules`) or `--mode full` (equivalent to `--modules --transform-syntax`) to have the [ESM vs CJS differences](https://nodejs.org/api/esm.html#differences-between-es-modules-and-commonjs) transformed by `duel` prior to running `tsc` so you avoid compilation or runtime errors. The legacy `--modules`/`--transform-syntax` flags remain supported.
+### Build orientation
 
 `duel` infers the primary vs dual build orientation from your `package.json` `type`:
 
 - `"type": "module"` → primary ESM, dual CJS
 - `"type": "commonjs"` → primary CJS, dual ESM
 
-The `--dirs` flag nests outputs under `outDir/esm` and `outDir/cjs` accordingly. There is a small performance cost because sources are copied to run the transform before `tsc`.
+### Output directories
+
+If you prefer to have both builds in directories inside of your defined `outDir`, you can use the `--dirs` option.
 
 ```json
 "scripts": {
-  "build": "duel --modules"
+  "build": "duel --dirs"
 }
 ```
 
-For projects that need full syntax lowering, opt in explicitly:
+Assuming an `outDir` of `dist`, running the above will create `dist/esm` and `dist/cjs` directories.
 
-```json
-"scripts": {
-  "build": "duel --modules --transform-syntax"
-}
-```
+### Module transforms
 
-Using the single switch:
+`tsc` is asymmetric: `import.meta` globals fail in a CJS-targeted build, but CommonJS globals like `__filename`/`__dirname` pass when targeting ESM, causing runtime errors in the compiled output. See [TypeScript#58658](https://github.com/microsoft/TypeScript/issues/58658). Use `--mode` to mitigate:
+
+- `--mode globals` [rewrites module globals](https://github.com/knightedcodemonkey/module/blob/main/docs/globals-only.md#rewrites-at-a-glance).
+- `--mode full` adds syntax lowering _in addition to_ the globals rewrite.
 
 ```json
 "scripts": {
@@ -108,9 +101,7 @@ Using the single switch:
 }
 ```
 
-#### Pre-`tsc` transform (TypeScript 58658)
-
-When you enable module transforms (`--mode globals`, `--mode full`, or `--modules`), `duel` copies your sources and runs [`@knighted/module`](https://github.com/knightedcodemonkey/module) **before** `tsc` so the transformed files no longer trigger TypeScript’s asymmetrical module-global errors (see [TypeScript#58658](https://github.com/microsoft/TypeScript/issues/58658)). No extra setup is needed: module transforms are the pre-`tsc` mitigation. If you also select full lowering (`--mode full` or `--transform-syntax`), that pre-`tsc` step performs full lowering instead of globals-only.
+When `--mode` is enabled, `duel` copies sources and runs [`@knighted/module`](https://github.com/knightedcodemonkey/module) **before** `tsc`, so TypeScript sees already-mitigated sources. That pre-`tsc` step is globals-only for `--mode globals` and full lowering for `--mode full`.
 
 ## Options
 
@@ -118,9 +109,7 @@ The available options are limited, because you should define most of them inside
 
 - `--project, -p` The path to the project's configuration file. Defaults to `tsconfig.json`.
 - `--pkg-dir, -k` The directory to start looking for a package.json file. Defaults to `--project` dir.
-- `--mode` Optional shorthand for the module transform mode: `none` (default), `globals` (modules + globals-only), `full` (modules + full syntax lowering). Recommended.
-- `--modules, -m` Transform module globals for dual build target. Defaults to false.
-- `--transform-syntax, -s` Opt in to full syntax lowering via `@knighted/module` (default is globals-only). Implies `--modules`.
+- `--mode` Optional shorthand for the module transform mode: `none` (default), `globals` (globals-only), `full` (globals + full syntax lowering).
 - `--dirs, -d` Outputs both builds to directories inside of `outDir`. Defaults to `false`.
 - `--exports, -e` Generate `package.json` `exports` from build output. Values: `wildcard` | `dir` | `name`.
 
@@ -129,16 +118,6 @@ The available options are limited, because you should define most of them inside
 
 You can run `duel --help` to get the same info.
 
-## Gotchas
-
-These are definitely edge cases, and would only really come up if your project mixes file extensions. For example, if you have `.ts` files combined with `.mts`, and/or `.cts`. For most projects, things should just work as expected.
-
-- This is going to work best if your CJS-first project uses file extensions in _relative_ specifiers. This is completely acceptable in CJS projects, and [required in ESM projects](https://nodejs.org/api/esm.html#import-specifiers). This package makes no attempt to rewrite bare specifiers, or remap any relative specifiers to a directory index.
-
-- Unfortunately, `tsc` doesn't support [dual packages](https://nodejs.org/api/packages.html#dual-commonjses-module-packages) completely. For mitigation details, see the pre-`tsc` transform note above (`--modules`).
-
-- If running `duel` with your project's package.json file open in your editor, you may temporarily see the content replaced. This is because `duel` dynamically creates a new package.json using the `type` necessary for the dual build. Your original package.json will be restored after the build completes.
-
 ## Notes
 
 As far as I can tell, `duel` is one (if not the only) way to get a correct dual package build using `tsc` without requiring multiple `tsconfig.json` files or extra configuration. The TypeScript team [keep](https://github.com/microsoft/TypeScript/pull/54546) [talking](https://github.com/microsoft/TypeScript/issues/54593) about dual build support, but they continue to [refuse to rewrite specifiers](https://github.com/microsoft/TypeScript/issues/16577).

package/dist/cjs/duel.cjs

@@ -27,7 +27,7 @@ const getSubpath = (mode, relFromRoot) => {
     }
     if (mode === 'dir') {
         const last = segments.at(-1);
-        return last ? `./${last}` : null;
+        return last ? `./${last}/*` : null;
     }
     if (mode === 'wildcard') {
         const first = segments[0];
@@ -56,6 +56,17 @@ const generateExports = async (options) => {
     if (esmRootPosix.startsWith(`${cjsRootPosix}/`)) {
         cjsIgnore.push(`${esmRootPosix}/**`);
     }
+    const toWildcardValue = value => {
+        const dir = node_path_1.posix.dirname(value);
+        const file = node_path_1.posix.basename(value);
+        const dtsMatch = file.match(/(\.d\.(?:ts|mts|cts))$/i);
+        if (dtsMatch) {
+            const ext = dtsMatch[1];
+            return dir === '.' ? `./*${ext}` : `${dir}/*${ext}`;
+        }
+        const ext = node_path_1.posix.extname(file);
+        return dir === '.' ? `./*${ext}` : `${dir}/*${ext}`;
+    };
     const recordPath = (kind, filePath, root) => {
         const relPkg = toPosix((0, node_path_1.relative)(pkgDir, filePath));
         const relFromRoot = toPosix((0, node_path_1.relative)(root, filePath));
@@ -65,18 +76,19 @@ const generateExports = async (options) => {
         baseEntry[kind] = withDot;
         baseMap.set(baseKey, baseEntry);
         const subpath = getSubpath(mode, relFromRoot);
+        const useWildcard = subpath?.includes('*');
         if (kind === 'types') {
             const mappedSubpath = baseToSubpath.get(baseKey);
             if (mappedSubpath) {
                 const subEntry = subpathMap.get(mappedSubpath) ?? {};
-                subEntry.types = withDot;
+                subEntry.types = useWildcard ? toWildcardValue(withDot) : withDot;
                 subpathMap.set(mappedSubpath, subEntry);
             }
             return;
         }
         if (subpath && subpath !== '.') {
             const subEntry = subpathMap.get(subpath) ?? {};
-            subEntry[kind] = withDot;
+            subEntry[kind] = useWildcard ? toWildcardValue(withDot) : withDot;
             subpathMap.set(subpath, subEntry);
             baseToSubpath.set(baseKey, subpath);
         }
@@ -148,9 +160,10 @@ const generateExports = async (options) => {
             exportsMap[subpath] = out;
         }
     }
-    if (!exportsMap['.'] && baseMap.size) {
-        const [subpath, entry] = subpathMap.entries().next().value ?? [];
-        if (entry) {
+    if (!exportsMap['.']) {
+        const firstNonWildcard = [...subpathMap.entries()].find(([key]) => !key.includes('*'));
+        if (firstNonWildcard) {
+            const [subpath, entry] = firstNonWildcard;
             const out = {};
             if (entry.types) {
                 out.types = entry.types;
@@ -169,7 +182,9 @@ const generateExports = async (options) => {
             }
             if (Object.keys(out).length) {
                 exportsMap['.'] = out;
-                exportsMap[subpath] ??= out;
+                if (!exportsMap[subpath]) {
+                    exportsMap[subpath] = out;
+                }
             }
         }
     }

package/dist/cjs/init.cjs

@@ -68,15 +68,21 @@ const init = async (args) => {
         (0, util_js_1.log)('Options:', 'info', bare);
         (0, util_js_1.log)("--project, -p [path] \t\t Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.", 'info', bare);
         (0, util_js_1.log)('--pkg-dir, -k [path] \t\t The directory to start looking for a package.json file. Defaults to --project directory.', 'info', bare);
-        (0, util_js_1.log)('--modules, -m \t\t\t Transform module globals for dual build target. Defaults to false.', 'info', bare);
+        (0, util_js_1.log)('--modules, -m \t\t\t Transform module globals for dual build target. Defaults to false. (deprecated; use --mode globals/full).', 'info', bare);
         (0, util_js_1.log)('--dirs, -d \t\t\t Output both builds to directories inside of outDir. [esm, cjs].', 'info', bare);
         (0, util_js_1.log)('--exports, -e \t\t\t Generate package.json exports. Values: wildcard | dir | name.', 'info', bare);
-        (0, util_js_1.log)('--transform-syntax, -s \t\t Opt in to full syntax lowering via @knighted/module (default is globals-only).', 'info', bare);
+        (0, util_js_1.log)('--transform-syntax, -s \t\t Opt in to full syntax lowering via @knighted/module (default is globals-only). (deprecated; use --mode full).', 'info', bare);
         (0, util_js_1.log)('--mode [none|globals|full] \t Optional shorthand for module transforms and syntax lowering.', 'info', bare);
         (0, util_js_1.log)('--help, -h \t\t\t Print this message.', 'info', bare);
     }
     else {
         const { project, 'target-extension': targetExt, 'pkg-dir': pkgDir, modules, dirs, exports: exportsOpt, 'transform-syntax': transformSyntax, mode, } = parsed;
+        if (modules) {
+            (0, util_js_1.logWarn)('--modules is deprecated; prefer --mode globals or --mode full.');
+        }
+        if (transformSyntax) {
+            (0, util_js_1.logWarn)('--transform-syntax is deprecated; prefer --mode full.');
+        }
         let configPath = (0, node_path_1.resolve)(project);
         let stats = null;
         let pkg = null;

package/dist/esm/duel.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { argv, platform } from 'node:process';
-import { join, dirname, resolve, relative, parse as parsePath } from 'node:path';
+import { join, dirname, resolve, relative, parse as parsePath, posix } from 'node:path';
 import { spawn } from 'node:child_process';
 import { writeFile, rm, rename, mkdir, cp, access, readFile } from 'node:fs/promises';
 import { randomBytes } from 'node:crypto';
@@ -24,7 +24,7 @@ const getSubpath = (mode, relFromRoot) => {
     }
     if (mode === 'dir') {
         const last = segments.at(-1);
-        return last ? `./${last}` : null;
+        return last ? `./${last}/*` : null;
     }
     if (mode === 'wildcard') {
         const first = segments[0];
@@ -53,6 +53,17 @@ const generateExports = async (options) => {
     if (esmRootPosix.startsWith(`${cjsRootPosix}/`)) {
         cjsIgnore.push(`${esmRootPosix}/**`);
     }
+    const toWildcardValue = value => {
+        const dir = posix.dirname(value);
+        const file = posix.basename(value);
+        const dtsMatch = file.match(/(\.d\.(?:ts|mts|cts))$/i);
+        if (dtsMatch) {
+            const ext = dtsMatch[1];
+            return dir === '.' ? `./*${ext}` : `${dir}/*${ext}`;
+        }
+        const ext = posix.extname(file);
+        return dir === '.' ? `./*${ext}` : `${dir}/*${ext}`;
+    };
     const recordPath = (kind, filePath, root) => {
         const relPkg = toPosix(relative(pkgDir, filePath));
         const relFromRoot = toPosix(relative(root, filePath));
@@ -62,18 +73,19 @@ const generateExports = async (options) => {
         baseEntry[kind] = withDot;
         baseMap.set(baseKey, baseEntry);
         const subpath = getSubpath(mode, relFromRoot);
+        const useWildcard = subpath?.includes('*');
         if (kind === 'types') {
             const mappedSubpath = baseToSubpath.get(baseKey);
             if (mappedSubpath) {
                 const subEntry = subpathMap.get(mappedSubpath) ?? {};
-                subEntry.types = withDot;
+                subEntry.types = useWildcard ? toWildcardValue(withDot) : withDot;
                 subpathMap.set(mappedSubpath, subEntry);
             }
             return;
         }
         if (subpath && subpath !== '.') {
             const subEntry = subpathMap.get(subpath) ?? {};
-            subEntry[kind] = withDot;
+            subEntry[kind] = useWildcard ? toWildcardValue(withDot) : withDot;
             subpathMap.set(subpath, subEntry);
             baseToSubpath.set(baseKey, subpath);
         }
@@ -145,9 +157,10 @@ const generateExports = async (options) => {
             exportsMap[subpath] = out;
         }
     }
-    if (!exportsMap['.'] && baseMap.size) {
-        const [subpath, entry] = subpathMap.entries().next().value ?? [];
-        if (entry) {
+    if (!exportsMap['.']) {
+        const firstNonWildcard = [...subpathMap.entries()].find(([key]) => !key.includes('*'));
+        if (firstNonWildcard) {
+            const [subpath, entry] = firstNonWildcard;
             const out = {};
             if (entry.types) {
                 out.types = entry.types;
@@ -166,7 +179,9 @@ const generateExports = async (options) => {
             }
             if (Object.keys(out).length) {
                 exportsMap['.'] = out;
-                exportsMap[subpath] ??= out;
+                if (!exportsMap[subpath]) {
+                    exportsMap[subpath] = out;
+                }
             }
         }
     }

package/dist/esm/init.js

@@ -3,7 +3,7 @@ import { resolve, join, dirname } from 'node:path';
 import { stat } from 'node:fs/promises';
 import { parseTsconfig } from 'get-tsconfig';
 import { readPackageUp } from 'read-package-up';
-import { logError, log } from './util.js';
+import { logError, log, logWarn } from './util.js';
 const init = async (args) => {
     let parsed = null;
     try {
@@ -65,15 +65,21 @@ const init = async (args) => {
         log('Options:', 'info', bare);
         log("--project, -p [path] \t\t Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.", 'info', bare);
         log('--pkg-dir, -k [path] \t\t The directory to start looking for a package.json file. Defaults to --project directory.', 'info', bare);
-        log('--modules, -m \t\t\t Transform module globals for dual build target. Defaults to false.', 'info', bare);
+        log('--modules, -m \t\t\t Transform module globals for dual build target. Defaults to false. (deprecated; use --mode globals/full).', 'info', bare);
         log('--dirs, -d \t\t\t Output both builds to directories inside of outDir. [esm, cjs].', 'info', bare);
         log('--exports, -e \t\t\t Generate package.json exports. Values: wildcard | dir | name.', 'info', bare);
-        log('--transform-syntax, -s \t\t Opt in to full syntax lowering via @knighted/module (default is globals-only).', 'info', bare);
+        log('--transform-syntax, -s \t\t Opt in to full syntax lowering via @knighted/module (default is globals-only). (deprecated; use --mode full).', 'info', bare);
         log('--mode [none|globals|full] \t Optional shorthand for module transforms and syntax lowering.', 'info', bare);
         log('--help, -h \t\t\t Print this message.', 'info', bare);
     }
     else {
         const { project, 'target-extension': targetExt, 'pkg-dir': pkgDir, modules, dirs, exports: exportsOpt, 'transform-syntax': transformSyntax, mode, } = parsed;
+        if (modules) {
+            logWarn('--modules is deprecated; prefer --mode globals or --mode full.');
+        }
+        if (transformSyntax) {
+            logWarn('--transform-syntax is deprecated; prefer --mode full.');
+        }
         let configPath = resolve(project);
         let stats = null;
         let pkg = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/duel",
-  "version": "3.2.2",
+  "version": "3.2.4",
   "description": "TypeScript dual packages.",
   "type": "module",
   "main": "dist/esm/duel.js",
@@ -26,7 +26,7 @@
     "test:integration": "node --test --test-reporter=spec test/integration.js",
     "test:monorepos": "node --test --test-reporter=spec test/monorepos.js",
     "test": "c8 --reporter=text --reporter=text-summary --reporter=lcov node --test --test-reporter=spec test/integration.js test/monorepos.js",
-    "build": "node src/duel.js --dirs --modules",
+    "build": "node src/duel.js --dirs --mode globals",
     "prepack": "npm run build",
     "prepare": "husky"
   },
@@ -82,7 +82,7 @@
     "vite": "^7.2.4"
   },
   "dependencies": {
-    "@knighted/module": "^1.3.0",
+    "@knighted/module": "^1.3.1",
     "find-up": "^8.0.0",
     "get-tsconfig": "^4.13.0",
     "glob": "^13.0.0",