twoslash-validator

# Two-slash Validator Skill Use this skill to keep aspire.dev from shipping rendered two-slash error UI. Any TypeScript diagnostic in a `twoslash` code block renders an error box on the site, so diagnostics must be fixed rather than suppressed. ## When to use this skill - Adding or editing a TypeScript code fence with the `twoslash` meta flag - Updating TypeScript AppHost examples that import `'./.aspire/modules/aspire.mjs'` - Refreshing `src/frontend/src/data/ts-modules/` or `src/frontend/src/data/twoslash/aspire.d.ts` - Investigating failures from `bun run test:unit:twoslash-blocks` - Reviewing docs changes that affect TypeScript sample rendering ## Core rule Do not add diagnostic allowlists or suppressions. A two-slash diagnostic is user-visible output on aspire.dev. Fix the docs sample, fix/regenerate the generated type surface, or remove the `twoslash` meta until the sample compiles cleanly. ## Validation workflow Run commands from the repository root unless noted. 1. Ensure dependencies are installed: ```powershell Set-Location -Path .\src\frontend bun install --frozen-lockfile ``` 2. If TypeScript API JSON changed, regenerate the two-slash declaration bundle: ```powershell bun run twoslash-types ``` 3. Run the two-slash block gate: ```powershell bun run test:unit:twoslash-blocks ``` 4. If the test fails, read every reported file, line, block number, and `ts(...)` code. Fix every diagnostic before considering the work complete. ## Fix strategy Use this order when deciding what to change: 1. **Docs sample bug:** If the TypeScript snippet calls the wrong API, uses the wrong argument shape, has a stale model name, or chains incompatible resources, fix the MDX sample. 2. **Generated type data stale:** If the sample matches the product API but `src/frontend/src/data/twoslash/aspire.d.ts` is stale, run `bun run twoslash-types` and commit the regenerated bundle. 3. **Generator type-shape gap:** If regeneration is not enough because `scripts/generate-twoslash-types.ts` loses valid SDK shape, fix the generator and regenerate `aspire.d.ts`. 4. **Feature not representable yet:** If a correct sample cannot be represented by the current two-slash type data, remove the `twoslash` meta from that block and leave the code sample visible without two-slash rendering. Do not leave a rendered diagnostic. ## What not to do - Do not reintroduce `KNOWN_TYPE_BUGS`, per-page diagnostic budgets, or equivalent allowlists. - Do not disable `TWOSLASH_ENABLED` to make the test pass. - Do not change `noErrorValidation` as a substitute for fixing diagnostics; it exists so the audit can collect all failures at once. - Do not hide failures by changing the fence language away from TypeScript unless the sample is not TypeScript. - Do not edit generated `aspire.d.ts` by hand; update the generator or source JSON and regenerate. ## Expected final checks Before finishing a two-slash-related change, run: ```powershell Set-Location -Path .\src\frontend bun run test:unit:twoslash-blocks ``` If you changed the generator, also run: ```powershell bun run test:unit:twoslash-types ```