Skip to content

Generate the canonical polyglot AppHost API reference - #1637

Open
David Pine (IEvangelist) wants to merge 6 commits into
ievangelist-core-diagnostics-prfrom
ievangelist-canonical-apphost-api
Open

Generate the canonical polyglot AppHost API reference#1637
David Pine (IEvangelist) wants to merge 6 commits into
ievangelist-core-diagnostics-prfrom
ievangelist-canonical-apphost-api

Conversation

@IEvangelist

@IEvangelist David Pine (IEvangelist) commented Sep 9, 2026

Copy link
Copy Markdown
Member

Stack 4/5. Depends on #1636.

This change generates the canonical polyglot AppHost API reference:

  • 117 semantic package modules containing 4,384 ATS items and five language projections
  • source-drift locking and a deterministic updater
  • an aggregated AppHost language support matrix
  • canonical /reference/api/apphost/** HTML and Markdown routes
  • a 3,633-entry legacy TypeScript URL compatibility inventory
  • a support-aware integration gallery
  • exact projected AppHost API labels for container images

Python, Go, Java, and Rust remain disabled until stack 5.

Validation:

  • 36 generator tests passed
  • focused frontend/API validation passed for AppHost API, API Markdown, integration cards, container images, and diagnostics language coverage
  • git diff --check passed
  • no local production build was run

@IEvangelist David Pine (IEvangelist) mentioned this pull request Sep 9, 2026
Open
@IEvangelist
David Pine (IEvangelist) force-pushed the ievangelist-canonical-apphost-api branch from 2b10e77 to 4e285f4 Compare September 9, 2026 19:57
@IEvangelist
David Pine (IEvangelist) added this pull request to stack #1639 September 9, 2026 20:02
@IEvangelist
David Pine (IEvangelist) force-pushed the ievangelist-canonical-apphost-api branch from 4e285f4 to 089cd61 Compare September 9, 2026 20:14
@IEvangelist
David Pine (IEvangelist) force-pushed the ievangelist-canonical-apphost-api branch from 089cd61 to be9a304 Compare September 9, 2026 20:28
@IEvangelist
David Pine (IEvangelist) force-pushed the ievangelist-canonical-apphost-api branch from be9a304 to ff0e82a Compare September 9, 2026 21:08
@aspire-repo-bot

aspire-repo-bot Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Frontend HTML artifact ready

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

VS Code: Open PR #1637 artifacts

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

@IEvangelist
David Pine (IEvangelist) force-pushed the ievangelist-canonical-apphost-api branch from ff0e82a to 4170bc2 Compare September 9, 2026 21:29
@IEvangelist
David Pine (IEvangelist) force-pushed the ievangelist-canonical-apphost-api branch from 4170bc2 to fa2dd4a Compare September 9, 2026 21:44
Copilot AI lite review requested due to automatic review settings September 9, 2026 22:11
@IEvangelist
David Pine (IEvangelist) force-pushed the ievangelist-canonical-apphost-api branch from fa2dd4a to 5772bfc Compare September 9, 2026 22:11
Copilot AI reviewed Sep 9, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The AppHost API language auto-correction dispatch can be missed on first load, leaving URL/localStorage unsynchronized.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Generates and wires up the canonical polyglot AppHost API reference for aspire.dev, including new semantic module data, a language-support matrix, canonical /reference/api/apphost/** routes, and legacy TypeScript route compatibility via redirects/aliases.

Changes:

  • Adds AtsJsonGenerator test coverage for upstream drift locking, generation script contract, and projection adapter golden outputs.
  • Introduces support-matrix aggregation in AtsJsonGenerator and integrates it into the CLI tool surface.
  • Migrates frontend API reference UX/routes to the canonical AppHost tree, adds legacy TypeScript redirect/alias plumbing, and updates unit/e2e tests accordingly.
File summaries
File Description
tests/AtsJsonGenerator.Tests/UpstreamDriftTests.cs Verifies pinned upstream lock + aggregate hash stability.
tests/AtsJsonGenerator.Tests/Golden/typescript.golden Golden output for TS projection adapter.
tests/AtsJsonGenerator.Tests/Golden/rust.golden Golden output for Rust projection adapter.
tests/AtsJsonGenerator.Tests/Golden/python.golden Golden output for Python projection adapter.
tests/AtsJsonGenerator.Tests/Golden/java.golden Golden output for Java projection adapter.
tests/AtsJsonGenerator.Tests/Golden/go.golden Golden output for Go projection adapter.
tests/AtsJsonGenerator.Tests/GenerationScriptContractTests.cs Locks contract for PowerShell generator args/env handling.
tests/AtsJsonGenerator.Tests/AtsJsonGenerator.Tests.csproj Copies fixtures/golden + tool artifacts to test output.
tests/AtsJsonGenerator.Tests/AdapterGoldenTests.cs Ensures adapter projections match golden baselines.
src/tools/AtsJsonGenerator/upstream-sources.lock.json Adds pinned upstream blob lock manifest.
src/tools/AtsJsonGenerator/SupportMatrixCommand.cs Adds CLI command to generate language support matrix JSON.
src/tools/AtsJsonGenerator/Program.cs Registers support subcommand.
src/tools/AtsJsonGenerator/Helpers/SupportMatrixAggregator.cs Aggregates per-module data into support matrix model.
src/tools/AtsJsonGenerator/BatchGenerateCommand.cs Adds dump provenance args + renames --version to --package-version.
src/frontend/tests/unit/validate-generated-api-data.vitest.test.ts Extends validation tests for semantic modules + support matrix.
src/frontend/tests/unit/twoslash-types-generator.vitest.test.ts Updates fixture shape/env vars for apphost-modules.
src/frontend/tests/unit/page-metadata.vitest.test.ts Updates generated-route OG metadata assertions for apphost routes.
src/frontend/tests/unit/normalize-generated-api-data.vitest.test.ts Updates normalization expectations for semantic projections.
src/frontend/tests/unit/integration-card-language-support.vitest.test.ts Adds tests for support-aware integration language pills.
src/frontend/tests/unit/diagnostics-language.vitest.test.ts Switches diagnostics scan to apphost-modules semantic shape.
src/frontend/tests/unit/custom-components.vitest.test.ts Adjusts expected integration card language markup.
src/frontend/tests/unit/container-images-language-support.vitest.test.ts Adds tests for projected container API labels per language.
src/frontend/tests/unit/api-reference-routes.vitest.test.ts Adds apphost markdown-route recognition coverage.
src/frontend/tests/e2e/ts-api-search.spec.ts Migrates TS API search e2e to apphost landing + lang param.
src/frontend/tests/e2e/site-search.spec.ts Updates search dialog API buttons behavior for generated languages.
src/frontend/tests/e2e/og-metadata.spec.ts Migrates generated API OG fallback coverage to apphost routes.
src/frontend/tests/e2e/api-markdown-routes.spec.ts Adds canonical apphost markdown routes + legacy TS redirect test.
src/frontend/src/utils/apphost-typescript-route-aliases.ts Adds helpers for legacy TS route alias manifest + targets.
src/frontend/src/utils/apphost-api-sidebar.ts Adds sidebar builder for apphost API tree.
src/frontend/src/utils/apphost-api-search.ts Builds apphost search index across languages + member routes.
src/frontend/src/utils/apphost-api-search-stats.ts Adds stats helpers for apphost search landing UI.
src/frontend/src/utils/apphost-api-routes.ts Adds slugging + top-level/member routing helpers for apphost.
src/frontend/src/utils/apphost-api-markdown.ts Adds Markdown renderers for apphost module/item/member pages.
src/frontend/src/pages/reference/api/typescript/[module]/[item]/[member].md.ts Converts legacy TS markdown member route into redirect.
src/frontend/src/pages/reference/api/typescript/[module]/[item].md.ts Converts legacy TS markdown item route into redirect.
src/frontend/src/pages/reference/api/typescript/[module].md.ts Converts legacy TS markdown module route into redirect.
src/frontend/src/pages/reference/api/typescript.md.ts Converts legacy TS markdown index into redirect.
src/frontend/src/pages/reference/api/apphost/index.astro Adds canonical apphost API landing/search page.
src/frontend/src/pages/reference/api/apphost/[module]/index.astro Adds canonical module overview page.
src/frontend/src/pages/reference/api/apphost/[module]/[item]/index.astro Adds canonical item page with per-language projections + members list.
src/frontend/src/pages/reference/api/apphost/[module]/[item]/[member]/index.astro Adds canonical member page with per-language projections.
src/frontend/src/pages/reference/api/apphost/[module]/[item]/[member].md.ts Adds canonical member Markdown route.
src/frontend/src/pages/reference/api/apphost/[module]/[item].md.ts Adds canonical item Markdown route.
src/frontend/src/pages/reference/api/apphost/[module].md.ts Adds canonical module Markdown route.
src/frontend/src/pages/reference/api/apphost.md.ts Adds canonical apphost index Markdown route.
src/frontend/src/middleware.ts Expands nested markdown redirect matcher to include apphost.
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Umami.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Squad.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.SqlServer.Extensions.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Rust.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Redis.Extensions.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Python.Extensions.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.PowerShell.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.PostgreSQL.Extensions.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.MySql.Extensions.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.MongoDB.Extensions.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Keycloak.Extensions.13.5.1-beta.748.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Flyway.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Elasticsearch.Extensions.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.DuckDB.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Deno.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Dbx.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Bun.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/CommunityToolkit.Aspire.Hosting.Adminer.13.5.0.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/Aspire.Hosting.Dotnet.13.5.3-preview.1.26425.3.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/Aspire.Hosting.Browsers.13.5.3-preview.1.26425.3.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/Aspire.Hosting.Blazor.13.5.3-preview.1.26425.3.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/Aspire.Hosting.Azure.Search.13.5.3.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/Aspire.Hosting.Azure.OperationalInsights.13.5.3.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/Aspire.Hosting.Azure.FrontDoor.13.5.3-preview.1.26425.3.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/data/ts-modules/Aspire.Hosting.Azure.ApplicationInsights.13.5.3.json Removes legacy TS module JSON (migration to semantic modules).
src/frontend/src/content.config.ts Defines semantic apphostModules collection + schema validation.
src/frontend/src/components/starlight/Sidebar.astro Treats typescript/apphost as the same API grouping for sidebar logic.
src/frontend/src/components/starlight/Search.astro Replaces TS API button with generated-language AppHost API buttons.
src/frontend/src/components/IntegrationCard.astro Filters language pills based on per-package semantic support.
src/frontend/src/components/api-reference/MemberCardBase.astro Expands lang union to generated languages for highlighting.
src/frontend/src/components/api-reference/inpage-search-sync.ts Exports class for direct imports while keeping window binding.
src/frontend/src/components/api-reference/AppHostProjection.astro Renders a single item projection for a selected language.
src/frontend/src/components/api-reference/AppHostApiLanguageSelector.astro Adds generated-language pivot selector for apphost API pages.
src/frontend/scripts/update-ts-api.ts Regenerates semantic apphost-modules data and support matrix.
src/frontend/scripts/normalize-generated-api-data.ts Normalizes terminology in apphost-modules + support matrix.
src/frontend/package.json Adds update:apphost-api and aliases update:ts-api.
src/frontend/config/sidebar/reference.topics.ts Renames sidebar link to “Search AppHost APIs” and points to new route.
.github/workflows/update-release-branch.yml Includes apphost-modules + support matrix in generated outputs.
.github/workflows/update-integration-data.yml Includes apphost-modules + support matrix in integration update outputs.
.gitattributes Enforces LF + stable whitespace handling for golden files.
Review details
  • Files reviewed: 32/327 changed files
  • Comments generated: 1
  • Review effort level: Lite

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

Comment thread src/frontend/src/components/api-reference/AppHostApiLanguageSelector.astro
@IEvangelist
Generate semantic polyglot AppHost API data
76d232d 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
Add canonical polyglot AppHost API routes
e103756 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
Project container image API labels
2e09bc7 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
Read diagnostics APIs from semantic modules
26ccdb6 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
Test static API redirect compatibility
e991613 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
Defer AppHost API language sync
0ab55b2 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
David Pine (IEvangelist) force-pushed the ievangelist-canonical-apphost-api branch from c0ce5dc to 0ab55b2 Compare September 10, 2026 13:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Lite
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@eerhardt Eric Erhardt (eerhardt) Awaiting requested review from eerhardt
@aaronpowell Aaron Powell (aaronpowell) Awaiting requested review from aaronpowell
@JamesNK James Newton-King (JamesNK) Awaiting requested review from JamesNK

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@IEvangelist