The problem
The documentation block check compares a block's redeclared types against the package's real exported types, read out of the built dist. If that build is incomplete, the check silently gets weaker instead of failing.
Measured, not inferred. Removing a single non-entry declaration file from @opensaas/stack-rag's build:
- its exported type count drops from 18 to 5
- 13 aliases resolve to a symbol named
unknown, so those names leave the exported-type map entirely
- a block that genuinely redeclares one of them goes from FAIL to compiling
- the shadow tally falls from 4 to 1
The compiler reports zero diagnostics in either state, so nothing signals that the comparison basis was gutted.
A red herring rides along: in the observed run the check still went red, but for a stale fixture entry rather than for a failing block — pointing an investigator at the fixtures rather than at the build.
Why it matters more than its size
This check's entire value is that a red result means something. A partial build turns it into a check that passes because it has nothing left to compare against, which is worse than not running it — a green result is now evidence of nothing, and reads as evidence of something.
It is also easy to hit. Any interrupted or filtered build, any caching mistake, any change to which files a package emits.
The defence, already verified
An exported alias whose target symbol has no declarations means the build is incomplete. Detecting that found 13 hits against the broken build and zero against the intact one.
Abort on it, the way the script already aborts when its entry points are missing. It needs no fixture, and no change to the compiler's library-skipping option.
This was investigated and deliberately not implemented on #1324, which was already several rounds deep on other soundness fixes.
Context
_Generated by Claude Code
The problem
The documentation block check compares a block's redeclared types against the package's real exported types, read out of the built
dist. If that build is incomplete, the check silently gets weaker instead of failing.Measured, not inferred. Removing a single non-entry declaration file from
@opensaas/stack-rag's build:unknown, so those names leave the exported-type map entirelyThe compiler reports zero diagnostics in either state, so nothing signals that the comparison basis was gutted.
A red herring rides along: in the observed run the check still went red, but for a stale fixture entry rather than for a failing block — pointing an investigator at the fixtures rather than at the build.
Why it matters more than its size
This check's entire value is that a red result means something. A partial build turns it into a check that passes because it has nothing left to compare against, which is worse than not running it — a green result is now evidence of nothing, and reads as evidence of something.
It is also easy to hit. Any interrupted or filtered build, any caching mistake, any change to which files a package emits.
The defence, already verified
An exported alias whose target symbol has no declarations means the build is incomplete. Detecting that found 13 hits against the broken build and zero against the intact one.
Abort on it, the way the script already aborts when its entry points are missing. It needs no fixture, and no change to the compiler's library-skipping option.
This was investigated and deliberately not implemented on #1324, which was already several rounds deep on other soundness fixes.
Context
_Generated by Claude Code