fix(types): rewrite .d.mts relative specifiers to .mjs

[cuzzlor]

Summary

Follow-up to #120. emitDualDeclarations was producing .d.mts files whose relative specifiers ended in .js, which under TS's node16+ ESM resolver pairs them with the adjacent .d.ts. In a dual-published package whose root package.json has "type": "commonjs", that .d.ts is treated as CJS-flavoured — so strict-ESM consumers see type-resolution mismatches against an otherwise-valid package.

rewriteSpecifier is only ever called from the .d.mts branch of emitDualDeclarations, so the extension it emits should be .mjs, which pairs with the .d.mts twin and keeps the resolution chain in ESM throughout. The .d.cts branch is unaffected.

What changed

• src/util/copy-package-json-from-config.ts — two-character fix in rewriteSpecifier (.js → .mjs in both the file and directory branches), plus updated comments explaining the rationale.
• src/util/copy-package-json-from-config.spec.ts — updated the three existing assertions that pinned the buggy .js output, then added focused coverage for: the file case (was only exercised via the integration test), resolving when only the .d.mts twin exists, and exercising all three module-specifier shapes (from '...', bare import '...', dynamic import('...')) in one pass.
• readme.md — added a ## copy-package-json subsection covering dual-declaration emission, the per-condition exports shape, and the .mjs rewrite rules with rationale. The original feature shipped without README coverage; this fills that gap.

Discovered via

Building @makerx/graphql-apollo-server@2.0.0-beta.0 against the just-published @makerx/ts-toolkit@5.0.0-beta.0 produced .d.mts files like:

// dist/index.d.mts
export * from './plugins/index.js'   // ← resolves to dist/plugins/index.d.ts (CJS-flavoured)

Strict-NodeNext consumers downstream see mis-resolved declarations. After this fix:

// dist/index.d.mts
export * from './plugins/index.mjs'  // ← resolves to dist/plugins/index.d.mts (ESM)

Why .mjs rather than .js

Under moduleResolution: "node16"/"nodenext", TypeScript pairs each module specifier with the declaration whose extension matches the JS extension:

Specifier in .d.mts	Resolves to	Module kind in dual-publish dist
'./foo.js'	./foo.d.ts	CJS (per package.json type)
'./foo.mjs'	./foo.d.mts	ESM

Using .mjs keeps the entire declaration chain in one module kind, so ESM consumers don't accidentally pull in CJS-shaped types.

Test plan

• npm test — 17/17 pass (was 14, added 3)
• npm run build — ts-toolkit dogfoods: its own dist/index.d.mts now reads from './util/copy-package-json-from-config.mjs'
• attw --pack dist — green across node10 / node16 (CJS) / node16 (ESM) / bundler (caveat: attw doesn't actually validate this class of fix, so the byte-level inspection is the real verification)
• Rebuild a downstream dual-publish consumer (e.g. graphql-apollo-server) against this branch and confirm its .d.mts files now use .mjs specifiers without any local workaround

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Fixes dual-declaration emission so .d.mts files rewrite extensionless relative specifiers to .mjs (instead of .js), ensuring TypeScript’s node16+/NodeNext resolver pairs ESM declarations with their .d.mts twins rather than adjacent CJS-flavoured .d.ts.

Changes:

• Update rewriteSpecifier to emit .mjs (and /index.mjs) for resolved relative specifiers in .d.mts output.
• Expand/adjust unit + integration test assertions to lock in .mjs rewriting behavior and cover additional specifier shapes.
• Add README documentation for copy-package-json dual type declaration emission and the .mjs rewrite rationale.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/util/copy-package-json-from-config.ts	Switches relative specifier rewrite target from .js to .mjs for .d.mts generation and updates inline rationale/comments.
src/util/copy-package-json-from-config.spec.ts	Updates assertions to expect .mjs and adds focused tests around file/directory resolution and specifier forms.
readme.md	Documents dual declaration emission and the .mjs rewrite rules/rationale.
package.json	Bumps version to 5.0.0-beta.1.
package-lock.json	Updates lockfile version metadata to 5.0.0-beta.1.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.