twoslash-validator

name	twoslash-validator
description	Validate and fix two-slash TypeScript examples for aspire.dev. Use when adding or editing `twoslash` code fences, TypeScript AppHost samples, generated TypeScript API data, or failures from `pnpm test:unit:twoslash-blocks`.

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 pnpm 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:

   Set-Location -Path .\src\frontend
   pnpm install --frozen-lockfile --prefer-offline
   

2. If TypeScript API JSON changed, regenerate the two-slash declaration bundle:

   pnpm twoslash-types
   

3. Run the two-slash block gate:

   pnpm 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 pnpm 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:

Set-Location -Path .\src\frontend
pnpm test:unit:twoslash-blocks

If you changed the generator, also run:

pnpm test:unit:twoslash-types