Refactor API Reference into a language provider registry - #1724
Merged
David Pine (IEvangelist) merged 2 commits intoSep 23, 2026
Merged
David Pine (IEvangelist) merged 2 commits into
David Pine (IEvangelist) merged 2 commits into
Conversation
The C#/TypeScript pair was baked into the resolution shape, the astro component, and diagnostic codes. Adding a new AppHost language would have meant editing every layer. Split the resolver into a small factory: * src/utils/api-reference/language-provider.ts defines the ApiLanguageProvider, PrimaryLanguageProvider, TargetLanguageProvider, ExportMapping, and PrimaryResolutionContext contracts. * csharp-provider.ts owns C# document parsing, candidate indexing, overload matching, export mapping (with pre-expanded receiver type FQNs), and C# target construction. * typescript-provider.ts owns TS route indexing and mapping resolution purely from cross-language ExportMapping data — no C# candidate leaks. * registry.ts composes one primary provider plus N target providers, drives resolution generically, and produces ApiReferenceResolution.targets keyed by provider id. * api-reference-core.ts shrinks to shared public types plus a slim buildApiReferenceIndex() that wires the default C# primary + TS target registry. Public API and diagnostic codes are unchanged. * ApiReference.astro iterates over resolution.targets instead of duplicating two ternary render blocks. CSS switches to per-language data-lang rules that scale to future languages. Adding, say, a Python target now means: implement one TargetLanguageProvider, register it in the default registry, add one CSS rule, and add one entry to the astro component's language list. No core-file edits. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot started reviewing on behalf of
David Pine (IEvangelist)
September 23, 2026 13:53
View session
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
One or more issues must be addressed before approval.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 1
Open (2)
What changed in this PR
Refactors API Reference resolution into a language-provider registry while preserving existing C#/TypeScript compatibility.
Changes:
- Adds provider contracts and C#/TypeScript implementations.
- Moves resolution orchestration into a generic registry.
- Simplifies component rendering through language iteration and per-language CSS.
| File | Description |
|---|---|
| src/frontend/src/utils/api-reference/typescript-provider.ts | Updated as part of this pull request. |
| src/frontend/src/utils/api-reference/registry.ts | Updated as part of this pull request. |
| src/frontend/src/utils/api-reference/language-provider.ts | Updated as part of this pull request. |
| src/frontend/src/utils/api-reference/csharp-provider.ts | Updated as part of this pull request. |
| src/frontend/src/utils/api-reference-core.ts | Updated as part of this pull request. |
| src/frontend/src/components/ApiReference.astro | Updated as part of this pull request. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Contributor
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
* Carry the primary member's canonical language-neutral name through
the PrimaryResolutionContext instead of taking the first mapping's
MethodName. When a member declares multiple [AspireExport] attributes
with different MethodName overrides (e.g. addWidget0/addWidget1) the
method-group reference now falls back to picking a preferred route
only if one actually matches the natural member name; otherwise it
keeps every route and the resolver flags ambiguity.
* Add tests covering the registry contract:
- method-group ambiguity when multiple MethodName exports exist,
- resolution.targets is populated by the registry (not just the
legacy csharp/typescript aliases),
- a target-owned diagnostic flows through the registry,
- a third, non-legacy 'python' target provider participates in
resolution, index building, mapping consumption, target output,
and diagnostics — verifying the abstraction end to end.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
David Pine (IEvangelist)
force-pushed
the
ievangelist-api-reference-language-factory
branch
from
September 23, 2026 15:07
6337cc7 to
e5489c1
Compare
David Pine (IEvangelist)
deleted the
ievangelist-api-reference-language-factory
branch
September 23, 2026 15:08
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #1588.
Problem
After #1588 merged, the C#/TypeScript pair was baked into every layer of the API Reference feature:
csharpandtypescriptfields.api-reference-core.tsmixed C#-specific document parsing, TS-specific route indexing, and cross-language linking in one ~965-line file.ApiReference.astrohad two ternary JSX blocks, one per language.Adding a future AppHost language (Python, etc.) would have meant editing every one of those layers.
Refactor
Split the resolver into a small factory / provider registry:
src/utils/api-reference/language-provider.ts—ApiLanguageProvider,PrimaryLanguageProvider,TargetLanguageProvider,ExportMapping,PrimaryResolutionContextcontracts.csharp-provider.ts— Owns C# document parsing, candidate indexing, overload matching, export mapping (with pre-expanded receiver type FQNs), and C# target construction.typescript-provider.ts— Owns TS route indexing and mapping resolution purely from cross-languageExportMappingdata. No C# candidate details leak in.registry.ts— Composes one primary provider + N target providers, drives resolution generically, and producesApiReferenceResolution.targetskeyed by provider id.api-reference-core.ts— Shrinks to shared public types plus a slimbuildApiReferenceIndex()that wires the default C# primary + TS target registry.ApiReference.astro— Iterates overresolution.targetsinstead of duplicating two ternary render blocks. CSS switches to per-languagedata-langrules.Adding a new language now
TargetLanguageProvider.buildApiReferenceIndex.languagesarray.No core-file edits required.
Preservation
api-reference.tsandapi-reference-core.tsunchanged.resolution.csharpandresolution.typescriptstill populated (aliases ofresolution.targets.csharp/.typescript) for source compatibility..resolve()is O(1) per language.Notes
release/13.6because Create an API Reference component #1588 landed there.pnpm build; validated viapnpm test:unit(820/820 ✅).