feat: v4. (#89)

Co-authored-by: Copilot <[email protected]>

Author: knightedcodemonkey

README.md

@@ -60,9 +60,6 @@ It should work similarly for a CJS-first project. Except, your package.json file
 > [!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.
 
-> [!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.
-
 ### Build orientation
 
 `duel` infers the primary vs dual build orientation from your `package.json` `type`:
@@ -103,6 +100,15 @@ Assuming an `outDir` of `dist`, running the above will create `dist/esm` and `di
 
 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`.
 
+### Dual package hazards
+
+Mixed `import`/`require` of the same dual package (especially when conditional exports differ) can create two module instances. `duel` exposes the detector from `@knighted/module`:
+
+- `--detect-dual-package-hazard [off|warn|error]` (default `warn`): emit diagnostics; `error` exits non-zero.
+- `--dual-package-hazard-scope [file|project]` (default `file`): per-file checks or a project-wide pre-pass that aggregates package usage across all compiled sources before building.
+
+Project scope is helpful in monorepos or hoisted installs where hazards surface only when looking across files.
+
 ## Options
 
 The available options are limited, because you should define most of them inside your project's `tsconfig.json` file.
@@ -112,6 +118,15 @@ The available options are limited, because you should define most of them inside
 - `--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`.
+- `--exports-config` Provide a JSON file with `{ "entries": ["./dist/index.js", ...], "main": "./dist/index.js" }` to limit which outputs become exports.
+- `--exports-validate` Dry-run exports generation/validation without writing package.json; combine with `--exports` or `--exports-config` to emit after validation.
+- `--rewrite-policy [safe|warn|skip]` Control how specifier rewrites behave when a matching target is missing (`safe` warns and skips, `warn` rewrites and warns, `skip` leaves specifiers untouched).
+- `--validate-specifiers` Validate that rewritten specifiers resolve to outputs; defaults to `true` when `--rewrite-policy` is `safe`.
+- `--detect-dual-package-hazard [off|warn|error]` Flag mixed import/require usage of dual packages; `error` exits non-zero.
+- `--dual-package-hazard-scope [file|project]` Run hazard checks per file (default) or aggregate across the project.
+- `--copy-mode [sources|full]` Temp copy strategy. `sources` (default) copies only files participating in the build (plus configs); `full` mirrors the previous whole-project copy.
+- `--verbose, -V` Verbose logging.
+- `--help, -h` Print the help text.
 
 > [!NOTE]
 > Exports keys are extensionless by design; the target `import`/`require`/`types` entries keep explicit file extensions so Node resolution remains deterministic.

docs/exports.md

@@ -153,3 +153,23 @@ Wildcard keys use the first path segment and cover folders; values are wildcarde
 - The root `.` entry uses your `main` (if set) to pick the default orientation (import vs require) and mirrors both builds when present.
 - If `main` is absent and no non-wildcard subpath exists, `.` is not promoted.
 - Windows paths are normalized with `path.posix`.
+
+## Exports config (JSON)
+
+If you want to constrain which built files become exports while keeping a conventional layout, pass `--exports-config <file>`. The file must be JSON with this shape:
+
+```json
+{
+  "entries": ["./dist/index.js", "./dist/folder/module.js"],
+  "main": "./dist/index.js"
+}
+```
+
+- `entries` (required): array of strings pointing to emitted files (relative with `./`). Only these bases are exported.
+- `main` (optional): overrides the `main` used for the root `.` entry and default orientation.
+
+Convention over configuration remains the default: if you omit `--exports-config`, `duel` scans the output and infers exports automatically.
+
+## Validation-only
+
+Use `--exports-validate` to compute and validate the exports map without writing `package.json`. Combine with `--exports` and/or `--exports-config` to emit after validation. When run alone, it logs success and leaves your package.json untouched.

docs/faq.md

@@ -15,3 +15,38 @@ Yes. `outDir` controls where Duel (and `tsc`) place emit results. The exclusion
 ## Can I avoid editing `tsconfig.json`?
 
 You could maintain separate configs (one for emit, one for checking) or lean on project references, but Duel's default workflow assumes a single package-level config. Excluding `dist/` is the simplest, least error-prone way to ensure dual builds, incremental type-checks, and workspace consumers all cooperate.
+
+## How do I detect dual package hazards?
+
+Dual packages can load twice if a project mixes `import` and `require` for the same dependency (especially when conditional exports differ). Use the built-in detector:
+
+- `--detect-dual-package-hazard [off|warn|error]` controls severity (default `warn`; `error` exits non-zero).
+- `--dual-package-hazard-scope [file|project]` scopes diagnostics per file (legacy) or across the compiled source set (recommended for monorepos/hoisted installs).
+
+Project scope runs a pre-pass before builds so hazards surface once per package, even if the conflicting usage spans multiple files.
+
+## Why might Duel fall back to unbounded source paths on Windows?
+
+Duel filters TypeScript source paths to prefer files inside your project root. On Windows, certain edge cases in path normalization can cause all paths to be incorrectly filtered out, triggering a fallback to the full unbounded list. Known scenarios include:
+
+### Extended-length / UNC-style paths
+
+`tsc` may emit paths like `\\?\C:\repo\src\file.ts` while `resolve(workingDir)` yields `C:\repo`. After normalization, these can still differ at the prefix level (`\\?\C:\repo` vs `C:\repo`), causing the root-matching logic to fail and filter out valid paths.
+
+### Junctions / symlinked working directories
+
+If your working directory is a junction or symlink (e.g., `C:\link-to-repo`) but `tsc` prints the real path (e.g., `C:\repo`), the normalized root and file paths won't share the same prefix. Every candidate fails the root check, leaving `insideRoot` empty.
+
+### Mixed drive/root representations
+
+Historically, tools can prepend UNC-style prefixes or vary drive letter formatting in ways that survive normalization. These differences make the string-prefix comparison too strict, dropping otherwise valid source files.
+
+### Debugging the fallback
+
+If you encounter this fallback in practice and need to debug it:
+
+1. Add temporary logging to compare the normalized `root` value with a sample of paths from `allPaths`.
+2. Look for mismatched prefixes such as `\\?\C:\` vs `C:\`, or junction vs realpath differences.
+3. Consider using the real path consistently (via `fs.realpathSync`) if your workflow involves symlinks or junctions.
+
+The fallback ensures real source files aren't silently dropped, but understanding the root cause can help you avoid the edge case entirely.

docs/performance-and-correctness.md

@@ -0,0 +1,41 @@
+# Performance + Correctness Guide
+
+This document outlines ways to speed up @knighted/duel while preserving the guarantees of dual ESM/CJS output and specifier correctness.
+
+## Goals
+
+- Keep dual ESM/CJS output identical to today (specifier rewrites, extension rewrites, exports generation).
+- Reduce redundant work (copying, parsing, type-checking) across runs.
+- Make optimizations opt-in or auto-detected to avoid regressions.
+
+## Low-Risk, High-Value Improvements
+
+- **Incremental builds:** Pass `--incremental` (and `--composite` where needed) to both emits and persist `.tsbuildinfo` inside the temp/shadow workspace. Reuse the same shadow dir keyed by project hash to avoid re-parsing unchanged projects.
+- **Selective copy only:** Continue skipping `node_modules` and outDir; avoid full-copy fallbacks. Prefer symlink/junction for `node_modules` to cut I/O.
+- **Parallelize setup:** Run config copy/patching, node_modules linking, and temp dir prep with `Promise.all` while the primary build initializes. Gate parallelism by CPU count to avoid thrash on small machines.
+- **Config hashing:** Only rebuild the temp workspace when tsconfig/package hash changes; otherwise reuse cached copies and `.tsbuildinfo`.
+
+## Emit Strategy Options
+
+- **Single type-check, dual emit (recommended first):** Use the TS program or solution builder API to parse/check once, then emit ESM and CJS with different `module` settings. Keeps correctness, removes the second parse/check.
+- **Fast secondary emit (opt-in):** Primary emit and declarations via `tsc`; secondary CJS via transform-only (esbuild/SWC) for speed. Guard behind a flag (e.g., `--fast-secondary`) so default remains pure `tsc`.
+- **No redundant types:** Emit declarations once (primary pass), skip `--emitDeclarationOnly` on the secondary.
+
+## TSConfig and Resolution Hygiene
+
+- Honor `include`/`exclude` when selecting files to copy/transform.
+- Add an LRU cache for module resolution when traversing project references to reduce repeated lookups.
+- Keep specifier and extension rewrite logic unchanged; validate outputs in tests after any performance change.
+
+## Validation and Safety Nets
+
+- Keep exports validation (`--exports-validate`) and specifier rewrite tests as-is; add targeted fixtures if emit paths change.
+- When using fast-secondary mode, add a compare step that diffs ESM vs CJS specifier shapes on a sample fixture set to catch regressions.
+- Measure before/after: collect timings for copy, parse/check, emit, and total wall-clock.
+
+## Rollout Suggestions
+
+- Start with incremental `.tsbuildinfo` reuse and parallelized setup (lowest risk).
+- Next, prototype single type-check + dual emit; measure on a representative monorepo.
+- Offer `--fast-secondary` as an opt-in flag; document trade-offs (no type-check on secondary path).
+- Keep a `--no-parallel` escape hatch for constrained CI runners.

docs/roadmap.md

@@ -1,5 +1,14 @@
 # Roadmap
 
-- Deprecate old flags in help output in favor of `--mode`.
 - Consider auto-enabling `globals` mode when the build would hit TypeScript 58658 scenarios, with `--mode none` as an explicit opt-out.
-- Remove deprecated flags in a major release after a migration window.
+- Decide coupling of `--rewrite-policy` with `--validate-specifiers` (fail fast when `warn|safe` + validation=false, or document decoupling).
+- Consider a `--quiet` flag to reduce log chatter alongside warnings/hazards.
+- Memoize resolver existence checks to trim repeated sync fs hits during rewrite, if profiling shows it matters.
+
+## Optimize temp-copy overhead
+
+- **Measure first:** add timing/logs (bytes copied, copy duration, hazard pre-scan duration); optional `npm run bench:copy` task.
+- **Default skips:** always exclude `node_modules`, caches (`.turbo`, `.next`, `.cache`), and `dist`/build outputs when safe (e.g., no refs relying on dist).
+- **User filters:** consider `--copy-include` / `--copy-exclude` globs to bound what is copied for very large repos.
+- **Reuse artifacts:** when project references exist, reuse existing `dist` intelligently; otherwise favor skipping `dist` to cut I/O.
+- **Avoid double work:** keep hazard aggregation single-pass; short-circuit if hazard checks are off.

docs/v4-migration.md

@@ -0,0 +1,48 @@
+# Duel v4 Migration Guide
+
+This guide highlights behavior changes introduced in v4 and how to adapt existing workflows.
+
+## Breaking/Behavioral Changes
+
+- **Specifier rewrites now default to safer behavior.** `--rewrite-policy` now defaults to `safe`, and `--validate-specifiers` is forced on when policy is `safe`. Missing targets skip rewrites and emit warnings instead of silently rewriting.
+- **Dual-package hazard detection enabled by default.** `--detect-dual-package-hazard` now defaults to `warn`, and `--dual-package-hazard-scope` defaults to `file`. You may see new warnings (or errors if configured).
+- **Build pipeline runs in a temp workspace copy.** Dual builds no longer mutate the root `package.json`; a temp copy is created with an adjusted `type`. External tools that watched in-place `package.json` edits will see different behavior.
+  - **IMPORTANT:** The temp-copy flow adds some I/O for large repos (copying sources/reference packages and running transforms there). `node_modules` is skipped; when references exist, existing `dist` may be reused. Very large projects may see modestly slower runs compared to the old in-place mutation.
+- **Project references run with `tsc -b`.** When `tsconfig.json` contains references, builds switch to TypeScript build mode. Output shape can differ from `tsc -p` for some setups.
+- **Exports tooling additions.** New flags (`--exports-config`, `--exports-validate`) are available; when used, they can emit warnings or fail on invalid configs.
+- **Deprecated flags removed.** `--modules`, `--transform-syntax`, and `--target-extension` are gone; use `--mode globals` or `--mode full` instead.
+
+## Restoring v3-like Behavior
+
+- **Specifier rewrites:** use `--rewrite-policy warn --validate-specifiers false` to continue rewriting even when targets are missing (previous behavior). To fully bypass rewrites, set `--rewrite-policy skip`.
+- **Hazard detection:** disable by passing `--detect-dual-package-hazard off` (or set scope to `project` only if you want aggregated warnings).
+- **Build/package.json side effects:** if tooling depended on in-place `package.json` mutation, update it to read outputs from the temp dual build outputs (`dist/esm` / `dist/cjs` or `outDir` variants). No flag restores the old mutation pattern.
+- **TypeScript references:** if build mode changes output undesirably, remove `references` or run your own `tsc -p` before calling `duel`.
+
+## Recommended Migration Steps
+
+1. Pick a rewrite policy:
+   - Safety-first (default): keep `--rewrite-policy safe` (default) and address any missing-target warnings by fixing paths or adding files.
+   - Legacy: add `--rewrite-policy warn --validate-specifiers false` to mimic v3 rewrites.
+2. Decide on hazard handling:
+   - Keep defaults to surface hazards.
+   - Silence: `--detect-dual-package-hazard off`.
+3. Check CI/build scripts: remove assumptions about `package.json` being mutated; consume artifacts from the generated outDir(s).
+4. Projects with TS references: expect `tsc -b`; validate output paths and adjust if needed.
+5. If using exports helpers: verify `--exports-config` files and watch for new validation warnings/errors.
+
+## New/Notable Flags
+
+- `--rewrite-policy [safe|warn|skip]` (default: `safe`)
+- `--validate-specifiers` (defaults to `true` when policy is `safe`; otherwise `false`)
+- `--detect-dual-package-hazard [off|warn|error]` (default: `warn`)
+- `--dual-package-hazard-scope [file|project]` (default: `file`)
+- `--exports-config <path>`
+- `--exports-validate`
+- `--verbose`
+
+## Quick FAQ
+
+- **Why are some rewrites skipped now?** Missing targets + `rewrite-policy safe` causes skips with warnings. Use `warn` to force rewrites or fix the missing files.
+- **Can I suppress hazard warnings?** Yes, `--detect-dual-package-hazard off`.
+- **Why isn’t package.json changed anymore?** v4 writes to a temp copy to avoid mutating your root; watch the emitted outDir instead.

eslint.config.js

@@ -18,6 +18,7 @@ export default [
     },
     rules: {
       'no-console': 'error',
+      'no-shadow': 'error',
       'n/no-process-exit': 'off',
       'n/hashbang': [
         'error',
@@ -55,4 +56,13 @@ export default [
       ],
     },
   },
+  {
+    files: ['test/unit.js'],
+    rules: {
+      'no-console': 'off',
+    },
+  },
+  {
+    ignores: ['test/__fixtures__/projectRefs/packages/**'],
+  },
 ]

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/duel",
-  "version": "3.2.5",
+  "version": "4.0.0-rc.0",
   "description": "TypeScript dual packages.",
   "type": "module",
   "main": "dist/esm/duel.js",
@@ -23,9 +23,11 @@
     "prettier": "prettier -w *.js *.md docs/*.md src/*.js test/*.js",
     "prettier:check": "prettier --check --ignore-unknown *.js *.md docs/*.md src/*.js test/*.js",
     "lint": "eslint src/*.js test/*.js",
+    "test:focus": "node --test --test-reporter=spec test/unit.js",
+    "test:unit": "c8 --reporter=text --reporter=text-summary --reporter=lcov node --test --test-reporter=spec test/unit.js",
     "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 --trace-deprecation --test --test-reporter=spec test/integration.js test/monorepos.js",
+    "test": "c8 --reporter=text --reporter=text-summary --reporter=lcov node --trace-deprecation --test --test-reporter=spec test/integration.js test/monorepos.js test/rewritePolicy.js test/unit.js",
     "build": "node src/duel.js --dirs --mode globals",
     "prepack": "npm run build",
     "prepare": "husky"
@@ -83,15 +85,15 @@
     "vite": "^7.2.4"
   },
   "dependencies": {
-    "@knighted/module": "^1.3.1",
+    "@knighted/module": "^1.4.0-rc.2",
     "find-up": "^8.0.0",
     "get-tsconfig": "^4.13.0",
     "glob": "^13.0.0",
     "read-package-up": "^12.0.0"
   },
   "lint-staged": {
     "*.{js,mjs,cjs,ts,cts,mts,jsx,tsx}": [
-      "eslint --max-warnings=0",
+      "eslint --max-warnings=0 --no-warn-ignored",
       "prettier --check --ignore-unknown"
     ],
     "*.{md,json,yml,yaml}": [