📝 Document the TypeScript 5.0 type floor

Consumers need TypeScript >= 5.0: the emitted declarations use const type
parameters and keep relative .ts specifiers, both of which resolve only on
TS >= 5.0. That also makes the emitted .ts specifiers a non-issue, so the
backlog item is closed without a .d.ts post-step: TS <= 4.9 cannot parse
the declarations anyway. The README/CONTRIBUTING wording now says the
rewrite applies to the JavaScript output, not to the declarations.
This commit is contained in:
tmu committed 2026-09-11 19:58:36 +00:00
1 parent e7a058d608
commit a0dd187042
3 files changed
+8 -6

No files matched your search

+5 -4
View File
@@ -16,7 +16,7 @@ Setup:
- `verify = check + test:unit`; `check:tsc` uses the root config (`noEmit: true`), so `tsconfig.build.json` is only exercised by `build`
- a broken build config (bad `rootDir`, emit-option typo) passes `verify` and only fails in CI
✔ Confirmed no change: `verify` is the local quick source-correctness check; the emit path is gated by CI's `build` job (`npm run build`), so adding `build` locally only adds inner-loop friction @done
☐ Fix `.ts` extensions in emitted `.d.ts`
✔ Fix `.ts` extensions in emitted `.d.ts` @done
- emitted JS rewrites `./pattern.ts` → `./pattern.js`, but `dist/*.d.ts` still imports `"./pattern.ts"` / `"./match.ts"`
- resolves under TS7, but a portability risk for older resolvers/bundlers; `attw` does not catch it
- HANDOVER (setup-phase review, unfixed — emit work deferred out of that session):
@@ -24,9 +24,10 @@ Setup:
- `npm run build` + `publish:publint` + `publish:attw` + a packed-consumer `tsc -p` all pass today, so this is a portability/robustness fix, not a broken-build fix — don't expect a red gate to confirm it works
- the durable proof is a consumer-resolution typecheck that asserts types still flow (a deliberately-wrong assignment must error), not just exit 0 — TS7 resolution silently tolerates the `.ts` form, so a green run alone proves nothing
- two directions: (a) post-process the `.d.ts` imports to `.js` in the build, or (b) stop emitting relative `.ts` on the declaration surface (e.g. build-only source or an internal barrel). Either way reconcile the README/CONTRIBUTING sentence claiming the option yields "conventional ESM imports" for consumers
☐ Fix the declaration emit (`.d.ts` post-step) or stop using relative `.ts` in the declaration surface
☐ Reconcile the README/CONTRIBUTING claim that `rewriteRelativeImportExtensions` yields "conventional ESM imports"
☐ Add a consumer-resolution test to the suite (durable guard; `attw` currently misses it)
- resolution: no code change. TypeScript >= 5.0 resolves the `.ts` specifier in shipped declarations in `node10`/`node16`/`nodenext`/`bundler` (verified across TS 4.7–7.0 with a consumer `@ts-expect-error` type guard). TS <= 4.9 rejects it, but also cannot parse the `<const L extends …>` already emitted in `dist/pattern.d.ts` (const type parameters, a TS 5.0 feature), so no consumer that can use the package is affected; the effective floor is now documented in README § Requirements
✘ Post-process the declaration emit to `.js`, or restructure to avoid relative `.ts` on the declaration surface @cancelled
✔ Reconcile the README/CONTRIBUTING claim that `rewriteRelativeImportExtensions` yields "conventional ESM imports"; document the TS >= 5.0 floor @done
✘ Add a consumer-resolution test (moot without a fix; `attw` still misses this class of issue) @cancelled
✔ Resolve sourcemap sources for consumers @done
- `dist/*.map` `sources` are `../src/*.ts`, but `src` is not in `files`, so debuggers get missing sources
- HANDOVER (setup-phase review, unfixed — emit work deferred out of that session):