♻️ Tighten the development/ prose
Same decisions, rationale, rejected alternatives and known issues, said with less padding: ~5,530 -> ~4,730 words (-15%). Every fact from the first draft is kept; only the wording, duplicated lead-ins and restated context are cut.
This commit is contained in:
1 parent
7ea84b66fa
commit
74c39e1346
7 files changed
+341
-409
No files matched your search
+13
-15
@@ -1,8 +1,7 @@
|
||||
# Testing
|
||||
|
||||
For this library the types _are_ the feature — narrowing, `exhaustive()`
|
||||
returns, the `Matcher<T>` contract — so a runtime-only test loop would verify
|
||||
the wrong thing. The contributor-facing commands are in
|
||||
For this library the types _are_ the feature, so a runtime-only test loop would
|
||||
verify the wrong thing. The commands are in
|
||||
[CONTRIBUTING.md](../CONTRIBUTING.md); this file records why the loop is shaped
|
||||
the way it is.
|
||||
|
||||
@@ -10,17 +9,17 @@ the way it is.
|
||||
|
||||
The rules — the loop and the pairing rule — are in
|
||||
[CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).
|
||||
What follows is why the loop is type-driven and what was rejected.
|
||||
What follows is why and what was rejected.
|
||||
|
||||
#### Decision (2026-09)
|
||||
|
||||
Test-driven development is _type_-driven here: the compile-time expectation is
|
||||
written before the runtime assertion, and both before the implementation.
|
||||
The compile-time expectation is written before the runtime assertion, and both
|
||||
before the implementation.
|
||||
|
||||
#### Why
|
||||
|
||||
- A runtime-only test can pass while the type is wrong, and a type-level library
|
||||
would then ship a broken feature that its tests bless.
|
||||
- A runtime-only test can pass while the type is wrong, so a type-level library
|
||||
would ship a broken feature its tests bless.
|
||||
- The type error is a more precise spec than a failing assertion, because it
|
||||
states the exact expected type before the logic exists.
|
||||
|
||||
@@ -31,17 +30,16 @@ written before the runtime assertion, and both before the implementation.
|
||||
- Testing the type only: it would not catch handler wiring, `exhaustive()`
|
||||
throwing, or the `otherwise` fallback (see `src/index.test.ts`).
|
||||
|
||||
The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are
|
||||
listed in
|
||||
The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are in
|
||||
[CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
|
||||
`c8` uses V8 coverage, so the `--strip-types` source is instrumented without a
|
||||
build step. The runner relies on the `.ts` import-extension convention (see
|
||||
build step, and the runner relies on the `.ts` import-extension convention (see
|
||||
[tooling.md](./tooling.md#source-imports-use-ts-extensions)).
|
||||
|
||||
## Known issues
|
||||
|
||||
- The type-aware linter misidentifies `expectTypeOf()` as a floating promise,
|
||||
so `src/index.test.ts` carries a file-level `oxlint-disable
|
||||
typescript/no-floating-promises` with an explanatory comment. This is a known
|
||||
false positive, not a rule we want off project-wide (see
|
||||
- The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so
|
||||
`src/index.test.ts` carries a file-level `oxlint-disable
|
||||
typescript/no-floating-promises` with an explanatory comment. It is a known
|
||||
false positive, not a rule worth disabling project-wide (see
|
||||
[tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).
|
||||
Reference in new issue
Block a user