WorkRoot/WRNexusJS
2
0
Fork 0
Code Issues Pull Requests Actions 27 Packages Projects Releases Wiki Activity

docs: correct the api block spec's type-enforcement mechanism

Browse Source 
Assertions in a .d.ts are inert under skipLibCheck: true, which the root
tsconfig sets. Proven during implementation by forcing skipLibCheck: false,
where the same assertion fires as TS2344. They move to a generated .ts file,
which skipLibCheck does not exempt.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Clintchiz
2026-08-19 15:58:05 +05:30
co-authored by Claude Opus 5
parent 419614d9d1
commit a2698fb51a
1 changed files with 12 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-08-19-typed-api-block-design.md
+12 -4
View File
@@ -42,7 +42,7 @@ These are implementation facts, not gaps in documentation:
| Execution | Decided by the enclosing mode, not a modifier |
| Request values | Declared fields, supplied at the call site |
| Type source | Route contract when available, declared types otherwise (with a warning) |
| Type enforcement | `tsc`, via assertions generated into `wrnexus.generated.d.ts` |
| Type enforcement | `tsc`, via assertions generated into `wrnexus.generated.api-checks.ts` |
| Failure | `error {}` converts a failure to a value; without it, the call rejects |
## Syntax
@@ -112,8 +112,16 @@ concrete case.
`wrnexus build` never invokes `tsc`. **Generated build artifacts are not type-checked.** Compiling
the block into a typed client and expecting `tsc` to catch mismatches would therefore check nothing.
What _is_ type-checked is `app/types/wrnexus.generated.d.ts`, which lives under `app/`. Enforcement
goes there.
What _is_ type-checked is application source under `app/`. Enforcement goes there.
**Corrected 2026-08-19, during implementation.** This section originally placed the assertions in
`app/types/wrnexus.generated.d.ts`. That is inert: the root `tsconfig.json` sets
`skipLibCheck: true`, which exempts the _contents_ of every `.d.ts`, so an assertion written there
can never raise a `tsc` error. Proven by forcing `skipLibCheck: false`, under which the same
assertion fires as `TS2344`. The reasoning was right and the file was wrong. Per-block assertions
are emitted into a real `.ts` file instead — `app/types/wrnexus.generated.api-checks.ts` — which
`skipLibCheck` does not exempt and which `include: ["app"]` compiles. The helper types stay in the
`.d.ts`, where being declarations is correct.
### Three pieces
@@ -126,7 +134,7 @@ type ApiInput<P extends ApiRoute, M> = ApiContracts[P][M]["input"];
type ApiOutput<P extends ApiRoute, M> = ApiContracts[P][M]["output"];
```
**2. Per-block assertions**, generated into the same file. `wrnexus generate types` already parses
**2. Per-block assertions**, generated into `app/types/wrnexus.generated.api-checks.ts`. `wrnexus generate types` already parses
`.wrn` sources to build the route list, so it can read each block's declared fields and emit:
```ts