mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(sdk): enforce dormant public type tests (#3424)
## Description
The TypeScript SDK's public type assertions were not enforced: Vitest
treated `expectTypeOf` calls as runtime no-ops, and the source tsconfig
excluded the tests. This enables Vitest type checking with a dedicated
tsconfig, renames the type test to `types.test-d.ts`, and corrects the
stale `compress` options assertion to include `tokenBudget`.
`CompressResult.messages` remains `any[]`: the universal API returns the
input format, which can be Anthropic, Gemini, or Vercel rather than
OpenAI. The final change does not narrow that public result contract.
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- **`sdk/typescript/vitest.config.ts`** — enable `test.typecheck` with a
dedicated tsconfig so `vitest run` type-checks `expectTypeOf` assertions
instead of no-oping them.
- **`sdk/typescript/tsconfig.typecheck.json`** (new) — typecheck-only
tsconfig that includes the test type-files. Required: the root
`tsconfig.json` excludes `test/`, so without it vitest's typecheck
silently reports "no errors" even for a deliberately wrong assertion.
- **`sdk/typescript/test/types.test.ts` → `test/types.test-d.ts`** —
renamed to vitest's type-test convention so typecheck collects it. It is
the only file using `expectTypeOf`; the runtime suite is unchanged.
- **Stale assertion fixed** — `HeadroomClientInterface["compress"]`
params corrected from `{ model?: string }` to `{ model?: string;
tokenBudget?: number }` to match `src/types.ts`.
- **`CompressResult["messages"]` assertion** — kept at `any[]` with a
comment explaining the format-preserving return (an earlier revision
narrowed it to `OpenAIMessage[]`; reverted per review). No `src/`
change.
## Testing
- [x] Unit tests pass (`npm test` — vitest, now including typecheck)
- [x] Type checking passes (`npm run typecheck` — tsc --noEmit on src)
- [x] Build passes (`npm run build` — tsup)
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ cd sdk/typescript && npm test # vitest run, typecheck.enabled
Testing types with tsc and vue-tsc is an experimental feature.
Test Files 18 passed | 5 skipped (23)
Tests 294 passed | 33 skipped (327)
Type Errors no errors
Duration 2.28s (typecheck 1.33s)
$ npm run typecheck # tsc --noEmit on src
(clean, no errors)
$ npm run build # tsup
(ESM + CJS + DTS built successfully)
```
Maintainer re-validation on `159a646` (isolated `npm ci
--ignore-scripts`, macOS): 294 passed, 33 skipped, no type-test errors;
`npm run typecheck` and `npm run build` pass.
## Real Behavior Proof
- Environment: Node v22.16.0 on Windows 11 (author) and macOS
(maintainer re-validation); `sdk/typescript` with an isolated `npm ci
--ignore-scripts`.
- Exact command / steps: `cd sdk/typescript && npm ci --ignore-scripts
&& npm test && npm run typecheck && npm run build`.
- Observed result: Vitest executes `types.test-d.ts` (blocks tagged `✓
TS`) and reports no type errors; runtime tests pass; tsc and the
ESM/CJS/DTS build succeed. Negative probe: temporarily changing the
assertion to `tokenBudget?: string` makes `npm test` FAIL
(`TypeCheckError ... test/types.test-d.ts:177:7`, `Type Errors 1
failed`, non-zero exit); restoring it returns to `Type Errors: no
errors`, 294 passed.
- Not tested: live provider requests. The change affects test
enforcement only; there is no runtime code path.
## Runtime Rollout Safety
- Rollout-managed feature(s): None; test enforcement only.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: No runtime behavior or public
result-type narrowing.
- Kill switch / disable path: Revert the test configuration change.
- Unsafe override required: No.
- Qualification impact: Type assertions now participate in `npm test`.
- Rollback path: Revert this PR; no persisted-state changes.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)
## Screenshots (if applicable)
N/A
## Additional Notes
- Body restored to the PR template after the governance bot flagged the
condensed version (missing `Changes Made`, template checkboxes absent).
Content matches the twice-approved revision; no source changes.
- The dedicated `tsconfig.typecheck.json` is load-bearing: with
`typecheck.enabled` alone, vitest resolved the root `tsconfig.json`
(which excludes `test/`) and reported "no errors" even for a
deliberately absurd probe assertion.
- No dedicated vitest CI job exists, so enforcement primarily protects
local development; it still stops the public-API type assertions from
silently rotting the way the `compress` one already had.
---------
Co-authored-by: Jerrett Davis <mxjerrett@gmail.com>
This commit is contained in:
co-authored by
Jerrett Davis
parent
ca54c2aba1
commit
95cbbb8158
@@ -72,7 +72,12 @@ export interface CompressOptions {
|
||||
}
|
||||
|
||||
export interface CompressResult {
|
||||
/** Compressed messages in the same format as input. */
|
||||
/**
|
||||
* Compressed messages in the same format as input. Typed `any[]` because the
|
||||
* universal `compress()` returns messages in the *input* format — it calls
|
||||
* `fromOpenAI(messages, inputFormat)`, so for Anthropic/Vercel/Gemini input
|
||||
* these are not OpenAI-shaped. See the note on `HeadroomClient.compress`.
|
||||
*/
|
||||
messages: any[];
|
||||
tokensBefore: number;
|
||||
tokensAfter: number;
|
||||
|
||||
@@ -123,7 +123,10 @@ describe("CompressOptions", () => {
|
||||
describe("CompressResult", () => {
|
||||
it("has all required fields with correct types", () => {
|
||||
expectTypeOf<CompressResult>().toHaveProperty("messages");
|
||||
expectTypeOf<CompressResult["messages"]>().toEqualTypeOf<OpenAIMessage[]>();
|
||||
// Intentionally `any[]`: the universal compress() returns messages in the
|
||||
// input format (via fromOpenAI), so this field is not OpenAI-shaped in
|
||||
// general — asserting OpenAIMessage[] would misrepresent non-OpenAI results.
|
||||
expectTypeOf<CompressResult["messages"]>().toEqualTypeOf<any[]>();
|
||||
expectTypeOf<CompressResult["tokensBefore"]>().toBeNumber();
|
||||
expectTypeOf<CompressResult["tokensAfter"]>().toBeNumber();
|
||||
expectTypeOf<CompressResult["tokensSaved"]>().toBeNumber();
|
||||
@@ -173,7 +176,7 @@ describe("HeadroomClientInterface", () => {
|
||||
|
||||
it("compress accepts messages and optional options", () => {
|
||||
expectTypeOf<HeadroomClientInterface["compress"]>().parameters.toEqualTypeOf<
|
||||
[OpenAIMessage[], ({ model?: string } | undefined)?]
|
||||
[OpenAIMessage[], ({ model?: string; tokenBudget?: number } | undefined)?]
|
||||
>();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"rootDir": ".",
|
||||
"noEmit": true
|
||||
},
|
||||
"include": ["src", "test/**/*.test-d.ts"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
@@ -4,5 +4,9 @@ export default defineConfig({
|
||||
test: {
|
||||
globals: true,
|
||||
environment: "node",
|
||||
typecheck: {
|
||||
enabled: true,
|
||||
tsconfig: "./tsconfig.typecheck.json",
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user