Consume canonical TypeScript API exports

[Adam Ratzman (adamint)]

Draft. Consumer half of microsoft/aspire#19032 — tracking #17608.

Today AtsJsonGenerator reconstructs TypeScript signatures on the site side: options-overload synthesis, C# inheritance borrowing, container-base inference, missing-declaration stubs. It's a second implementation of the TypeScript projection that lives in the wrong repo, and it drifts from what the generator actually emits. That's the bug behind #17608.

The plan is for the CLI to hand us the API surface for an exact Name@Version and for this repo to do nothing but validate, sort, dedupe, and write.

What's in the draft so far

The schema v1 contract and the fixtures, so the switchover has something to land against:

• src/schemas/typescript-api-export.ts — parser/validator, typed loader, concatenateDeclarations
• tests/fixtures/typescript-api-export/*.json — unedited aspire sdk export output for Aspire.Hosting and Aspire.Hosting.Redis
• 16 unit tests, including one that concatenates every declaration fragment and shells out to tsc --noEmit --strict with skipLibCheck off

The fixtures are deliberately raw CLI output, not hand-tidied — if the producer drifts, these tests are what catches it. That already paid off once: the augmentation ownership test here caught addRedis shipping as interface:DistributedApplicationBuilder owned by Aspire.Hosting.Redis, which collides with core's item ID. Fixed on the producer side.

Still to come on this branch

• Rewire update-ts-api.ts onto aspire sdk export and delete AtsJsonGenerator
• Reduce generate-twoslash-types.ts to validation + dedupe + write
• Drop the TypeScript half of normalize-generated-api-data.ts

Keeping it a draft until microsoft/aspire#19032 is in and there's a CLI on a feed CI can restore — the refresh workflow can't run against a sdk export that isn't published yet.

Testing

328/328 unit tests, eslint clean.

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1430. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[Copilot]

Pull request overview

Introduces a v1 “canonical TypeScript API export” contract (as produced by aspire sdk export --language typescript) into the frontend, along with fixtures and unit tests, so the site can validate/sort/dedupe/render the CLI-produced API surface instead of reconstructing TypeScript signatures locally.

Changes:

• Added typescript-api-export schema types + parser/validator + declaration concatenation helper.
• Added raw CLI output fixtures for Aspire.Hosting and Aspire.Hosting.Redis, plus unit tests validating the contract and cross-package invariants.
• Re-exported the canonical schema types from ts-modules.ts to provide a single import path for consumers during migration.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

File	Description
src/frontend/src/schemas/typescript-api-export.ts	Adds v1 schema types, validation, loader, and declaration concatenation.
src/frontend/src/utils/ts-modules.ts	Type-only re-export of canonical export types for downstream imports.
src/frontend/tests/unit/typescript-api-export.vitest.test.ts	Adds validation tests + a tsc --noEmit --strict typecheck over concatenated fragments.
src/frontend/tests/fixtures/typescript-api-export/Aspire.Hosting.Redis.api.json	Adds raw CLI export fixture for the Redis integration package.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Adam Ratzman (adamint)]

I found three contract gaps inline. I did not repeat the existing tsc stderr comment. CI is also blocked by the forbidden-words check because the raw Aspire.Hosting.api.json fixture contains app host; since the fixture is intentionally unedited, I think this either needs the producer output refreshed or the bypass label.

[David Pine (IEvangelist)]

Accuracy source: microsoft/aspire main @ 00d3ddb8ddadc3824d2086269ff05457cb497645

Summary: 23 claims checked: 17 verified, 4 verified with nuance, 2 contradicted, 0 unverifiable. The two contradictions are blocking and are called out inline. The doc-tester pass found no affected documentation routes; the PR head served successfully at http://localhost:4322/ with 0 critical issues and 0 warnings.

Phase A — Claim verification

Verified and verified-with-nuance claims

ID	Verdict	Claim and evidence
C1	Verified	aspire sdk export --language typescript exists (SdkExportCommand.cs: command/option definitions).
C2	Verified	schemaVersion is literal 1 (TypeScriptApiProjector.ExportSchemaVersion).
C3	Verified	Exported document language is lowercase typescript (TypeScriptApiProjector.cs).
C4	Verified	Package identity contains non-empty name and version (TypeScriptApiExportWriter.cs).
C5	Verified	Modules contain name, optional summary, and items; the producer currently emits one module.
C6	Verified	Items emit id, kind, name, declaration, and owningAssembly.
C7	Verified with nuance	The consumer permits missing typeId, although the producer requires and always emits it.
C8	Verified	Item examples and extends are optional string arrays.
C9	Verified with nuance	The producer also emits member-level examples; parseMember currently drops that field.
C10	Verified	Member deprecation text is serialized under deprecated.
C11	Verified	Parameters serialize as name, type, optional, and optional summary.
C12	Verified	Declarations contain non-empty id, content, and owningAssembly.
C13	Verified with nuance	The producer emits a top-level generator object; the consumer currently drops it.
C14	Verified	Method declarations use the documented TypeScript signature form.
C15	Verified	Item declarations use headers such as export interface RedisResource.
C16	Verified	Extension methods are augmentation items with package-qualified augmentation IDs.
C19	Verified	Exact repeated declarations are harmless within the consumer's dedupe behavior.
C20	Verified	Fixture declaration IDs are unique and sorted for the tested inputs.
C21	Verified with nuance	The concatenated core + Redis fixture type-checks, but this does not establish correctness for the full multi-package manifest.
C22	Verified	The type-only re-export is erased and does not introduce node:fs into page bundles.
C23	Verified	Fixture shape and field order match raw producer output, including generator.

The producer evidence is in TypeScriptApiModel.cs, TypeScriptApiExportWriter.cs, TypeScriptApiProjector.cs, AtsTypeScriptApiReferenceExporter.cs, and SdkExportCommand.cs at the SHA above.

Phase B — Doc-tester results

Documentation Test Report

Focus Area: PR #1430 — no documentation content or rendered routes changed
Date: 2026-08-25
Tester: doc-tester agent
PR ref served: 0fe13f5d23fe84a20c60815e167ee4cdeefe36c0 at http://localhost:4322/

Category	Passed	Failed	Warnings
Content Accuracy	0	0	0
Code Examples	0	0	0
CLI Commands	0	0	0
Links	0	0	0

Critical Issues

None. No documentation pages or sections changed in this PR.

Warnings

None.

Passed Checks

• The PR head served locally and / loaded successfully with the expected site title.
• The changed-file set contains only the TypeScript export schema, utility re-export, fixtures, and unit tests; there are no affected documentation routes to exercise.

Recommendations

None for rendered documentation in this PR.

Knowledge Gaps

None.