refactor: validate specifiers and rewrite policy. (#103)

knightedcodemonkey · web-flow · commit ecef606085ea · 2026-01-03T22:12:36.000-06:00
diff --git a/README.md b/README.md
@@ -128,7 +128,6 @@ These are the CLI options `duel` supports to work alongside your project's `tsco
 - `--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, -H [off|warn|error]` Flag mixed import/require usage of dual packages; `error` exits non-zero. If project-scope checks lack file paths, or file-scope checks return pathless diagnostics, Duel falls back to file-scope reporting during transforms so diagnostics include locations.
 - `--dual-package-hazard-allowlist <pkg>[,<pkg>...]` Comma-separated packages to ignore when reporting dual package hazards (e.g., `react`).
 - `--dual-package-hazard-scope [file|project]` Run hazard checks per file (default) or aggregate across the project.
diff --git a/docs/faq.md b/docs/faq.md
@@ -4,15 +4,15 @@
 
 Duel emits JavaScript and declaration files into `dist/`, and the same `tsconfig.json` is reused for both emitting and type-checking. In workspace setups, sibling packages often import `@scope/pkg` via its package exports, so TypeScript resolves into the generated `.d.ts` files inside `dist/`. When `tsc` later tries to emit, it refuses to overwrite files it now treats as inputs (TS5055). Adding `"exclude": ["dist"]` keeps build artifacts out of the compilation so Duel can regenerate them safely.
 
-## Why is this mostly a workspace issue?
+### Why is this mostly a workspace issue?
 
 Single-package projects seldom import their own published outputs, but monorepos routinely do. When another package in the workspace references `@scope/pkg`, TypeScript follows that path right back into the freshly built `dist/` directory. Without the exclusion, the repo ends up both producing and consuming those artifacts during the same build, confusing the compiler.
 
-## Do I still need `"outDir": "dist"` if I exclude it?
+### Do I still need `"outDir": "dist"` if I exclude it?
 
 Yes. `outDir` controls where Duel (and `tsc`) place emit results. The exclusion only affects what the compiler considers source inputs; it does not change the emit destination.
 
-## Can I avoid editing `tsconfig.json`?
+### 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.
 
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -1,8 +1,8 @@
 # Roadmap
 
 - Consider auto-enabling `globals` mode when the build would hit TypeScript 58658 scenarios, with `--mode none` as an explicit opt-out.
-- 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.
+- Revisit a gated `--validate-specifiers` flag for advanced workflows that need explicit validation separate from rewrite policy.
 - Memoize resolver existence checks to trim repeated sync fs hits during rewrite, if profiling shows it matters.
 - Optionally prune stale `_duel_*` temp workspaces on startup (behind env flag and skipped in CI) to keep project roots tidy.
 - Deprecate `copyMode=full` (announce as compatibility-only, plan removal if unused) and favor the selective copy path by default.
diff --git a/docs/v4-migration.md b/docs/v4-migration.md
@@ -4,7 +4,7 @@ This guide highlights behavior changes introduced in v4 and how to adapt existin
 
 ## 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.
+- **Specifier rewrites now default to safer behavior.** `--rewrite-policy` now defaults to `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.
@@ -18,7 +18,7 @@ This guide highlights behavior changes introduced in v4 and how to adapt existin
 
 ## 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`.
+- **Specifier rewrites:** use `--rewrite-policy warn` 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`.
@@ -27,7 +27,7 @@ This guide highlights behavior changes introduced in v4 and how to adapt existin
 
 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.
+   - Legacy: set `--rewrite-policy warn` to mimic v3 rewrites.
 2. Decide on hazard handling:
    - Keep defaults to surface hazards.
    - Silence: `--detect-dual-package-hazard off`.
@@ -38,9 +38,9 @@ This guide highlights behavior changes introduced in v4 and how to adapt existin
 ## 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`)
+- `--dual-package-hazard-allowlist <pkg1,pkg2>`
 - `--exports-config <path>`
 - `--exports-validate`
 - `--verbose`
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@knighted/duel",
-  "version": "4.0.0-rc.6",
+  "version": "4.0.0-rc.7",
   "description": "TypeScript dual packages.",
   "type": "module",
   "main": "dist/esm/duel.js",
diff --git a/src/duel.js b/src/duel.js
@@ -84,7 +84,6 @@ const duel = async args => {
       exportsConfig,
       exportsValidate,
       rewritePolicy,
-      validateSpecifiers,
       detectDualPackageHazard,
       dualPackageHazardAllowlist,
       dualPackageHazardScope,
@@ -884,7 +883,6 @@ const duel = async args => {
           dualPackageHazardAllowlist: [...hazardAllowlist],
           onDiagnostics: handleRewriteDiagnostic,
           rewritePolicy,
-          validateSpecifiers,
           onWarn: message => logWarn(message),
           onRewrite: (from, to) => logVerbose(`Rewrote specifiers in ${from} -> ${to}`),
         })
@@ -907,7 +905,6 @@ const duel = async args => {
             dualPackageHazardAllowlist: [...hazardAllowlist],
             onDiagnostics: handleRewriteDiagnostic,
             rewritePolicy,
-            validateSpecifiers,
             onWarn: message => logWarn(message),
             onRewrite: (from, to) => logVerbose(`Rewrote specifiers in ${from} -> ${to}`),
           })
diff --git a/src/init.js b/src/init.js
@@ -50,10 +50,6 @@ const cliOptions = [
     value: '[safe|warn|skip]',
     desc: 'Control specifier rewriting behavior.',
   },
-  {
-    long: 'validate-specifiers',
-    desc: 'Validate rewritten specifiers against outputs.',
-  },
   {
     long: 'detect-dual-package-hazard',
     short: 'H',
@@ -143,10 +139,6 @@ const init = async args => {
           type: 'string',
           default: 'safe',
         },
-        'validate-specifiers': {
-          type: 'boolean',
-          default: false,
-        },
         'detect-dual-package-hazard': {
           type: 'string',
           short: 'H',
@@ -197,7 +189,6 @@ const init = async args => {
       'exports-config': exportsConfig,
       'exports-validate': exportsValidate,
       'rewrite-policy': rewritePolicy,
-      'validate-specifiers': validateSpecifiers,
       'detect-dual-package-hazard': detectDualPackageHazard,
       'dual-package-hazard-allowlist': dualPackageHazardAllowlist,
       'dual-package-hazard-scope': dualPackageHazardScope,
@@ -311,7 +302,6 @@ const init = async args => {
 
       let modulesFinal = false
       let transformSyntaxFinal = false
-      const validateSpecifiersFinal = rewritePolicy === 'safe' ? true : validateSpecifiers
 
       if (mode) {
         if (mode === 'none') {
@@ -335,7 +325,6 @@ const init = async args => {
         exportsConfig,
         exportsValidate,
         rewritePolicy,
-        validateSpecifiers: validateSpecifiersFinal,
         detectDualPackageHazard,
         dualPackageHazardAllowlist: hazardAllowlist,
         dualPackageHazardScope,
diff --git a/src/resolver.js b/src/resolver.js
@@ -83,11 +83,12 @@ const rewriteSpecifiersAndExtensions = async (filenames, options = {}) => {
     dualPackageHazardScope,
     onDiagnostics,
     rewritePolicy = 'safe',
-    validateSpecifiers = false,
+    validateSpecifiers,
     onRewrite = () => {},
     onWarn = () => {},
   } = options
-
+  const validateSpecifiersFinal =
+    validateSpecifiers ?? (rewritePolicy === 'skip' ? false : true)
   const rewrites = []
 
   for (const filename of filenames) {
@@ -183,7 +184,7 @@ const rewriteSpecifiersAndExtensions = async (filenames, options = {}) => {
         return next
       }
 
-      if (validateSpecifiers) {
+      if (validateSpecifiersFinal) {
         const fileDir = dirname(filename)
         const base = collapsed.replace(/\.js$/, '')
         const candidates = []
diff --git a/test/rewritePolicy.js b/test/rewritePolicy.js
@@ -32,7 +32,6 @@ describe('rewrite-policy', () => {
       target: 'commonjs',
       ext: '.cjs',
       rewritePolicy: 'safe',
-      validateSpecifiers: true,
       onWarn: msg => warnings.push(msg),
     })
 
@@ -52,7 +51,6 @@ describe('rewrite-policy', () => {
       target: 'commonjs',
       ext: '.cjs',
       rewritePolicy: 'warn',
-      validateSpecifiers: true,
       onWarn: msg => warnings.push(msg),
     })
 
@@ -72,7 +70,6 @@ describe('rewrite-policy', () => {
       target: 'commonjs',
       ext: '.cjs',
       rewritePolicy: 'skip',
-      validateSpecifiers: true,
       onWarn: msg => warnings.push(msg),
     })
 
diff --git a/test/unit.js b/test/unit.js
@@ -31,6 +31,7 @@ import {
   maybeLinkNodeModules,
   runExportsValidationBlock,
 } from '../src/util.js'
+import { init } from '../src/init.js'
 import { rewriteSpecifiersAndExtensions } from '../src/resolver.js'
 
 const makeTmp = () => mkdtempSync(join(os.tmpdir(), 'duel-unit-'))
@@ -701,9 +702,11 @@ describe('duel internals', () => {
     it('rewrites js maps when present and keeps sourceMappingURL in sync', async () => {
       const tmp = makeTmp()
       const file = join(tmp, 'a.js')
+      const dep = join(tmp, 'dep.js')
       const mapFile = `${file}.map`
       const source = 'import "./dep.js"\n//# sourceMappingURL=a.js.map\n'
       writeFileSync(file, source)
+      writeFileSync(dep, 'export const y = 1;')
       writeFileSync(
         mapFile,
         JSON.stringify({
@@ -896,4 +899,77 @@ describe('duel internals', () => {
     assert.deepEqual(filterDualPackageDiagnostics(null), [])
     assert.deepEqual(filterDualPackageDiagnostics(undefined), [])
   })
+
+  it('prints help and returns false when --help is passed', async () => {
+    const result = await init(['--help'])
+
+    assert.equal(result, false)
+  })
+
+  it('errors on invalid rewrite-policy value', async () => {
+    const result = await init(['--rewrite-policy', 'invalid'])
+
+    assert.equal(result, false)
+  })
+
+  it('errors on invalid hazard detection value', async () => {
+    const result = await init(['--detect-dual-package-hazard', 'nope'])
+
+    assert.equal(result, false)
+  })
+
+  it('errors on invalid copy-mode value', async () => {
+    const result = await init(['--copy-mode', 'weird'])
+
+    assert.equal(result, false)
+  })
+
+  it('errors on invalid mode value', async () => {
+    const result = await init(['--mode', 'super'])
+
+    assert.equal(result, false)
+  })
+
+  it('errors on empty hazard allowlist string', async () => {
+    const result = await init([
+      '--project',
+      'tsconfig.json',
+      '--dual-package-hazard-allowlist',
+      ' , , ',
+    ])
+
+    assert.equal(result, false)
+  })
+
+  it('errors when project directory lacks tsconfig', async () => {
+    const tmp = makeTmp()
+
+    try {
+      const result = await init(['--project', tmp])
+      assert.equal(result, false)
+    } finally {
+      rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it('errors when project file is missing', async () => {
+    const missing = join(makeTmp(), 'missing', 'tsconfig.json')
+
+    const result = await init(['--project', missing])
+
+    assert.equal(result, false)
+  })
+
+  it('errors when no package.json can be found', async () => {
+    const tmp = makeTmp()
+    const tsconfigPath = join(tmp, 'tsconfig.json')
+    writeFileSync(tsconfigPath, JSON.stringify({ compilerOptions: { outDir: 'dist' } }))
+
+    try {
+      const result = await init(['--project', tsconfigPath])
+      assert.equal(result, false)
+    } finally {
+      rmSync(tmp, { recursive: true, force: true })
+    }
+  })
 })

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@knighted/duel",`
`3`		`- "version": "4.0.0-rc.6",`
	`3`	`+ "version": "4.0.0-rc.7",`
`4`	`4`	`"description": "TypeScript dual packages.",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "dist/esm/duel.js",`