feat(compiler): auto-generate reference url and surface docs on hover#11287
Open
tadelesh wants to merge 9 commits into
Open
feat(compiler): auto-generate reference url and surface docs on hover#11287tadelesh wants to merge 9 commits into
tadelesh wants to merge 9 commits into
Conversation
Add an optional docs field (raw markdown, loaded from a co-located .md file) to linter rule (createRule) and diagnostic (createTypeSpecLibrary) definitions. tspd renders a page per rule (reference/rules/<name>.md) and per diagnostic (reference/diagnostics/<code>.md) plus a diagnostics index, and reports documentation-missing for undocumented rules/diagnostics. Migrates @typespec/http op-reference-container-route and @typespec/openapi3 path-query as pilots. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Address review feedback: - Add a docs field (string | FileRef) to linter rule and diagnostic definitions in the compiler; docs are read lazily by tspd so definitions stay browser-bundle safe. - Always report documentation-missing for any linter rule or diagnostic without docs, instead of gating the check. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ules Add a referenceDocs.baseUrl field to the library definition. When set, the compiler auto-fills the url of each diagnostic and linter rule that does not specify one explicitly (diagnostics -> <base>/diagnostics/<code>, rules -> <base>/rules/<name>), so the editor and CLI get a documentation link without hardcoding a url per item. Migrate @typespec/http and @typespec/openapi3 to declare referenceDocs and drop the hardcoded rule url. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…e server When hovering over a reported error, the language server now renders the extended documentation of the corresponding diagnostic or linter rule (its docs field, inline markdown or a FileRef read lazily) together with a link to the generated reference page when a documentation url is available. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…e-diagnostic-docs # Conflicts: # packages/compiler/test/server/get-hover.test.ts
Publish FileRef markdown assets and avoid generating reference links for undocumented diagnostics/rules. On hover, reuse the diagnostics from the last full compile (matched by source location the same way squiggles are) to show the extended documentation of the diagnostic/rule under the cursor, resolved by reusing the library already loaded by the compiler instead of re-resolving and reloading it. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: de8537de-5e61-4a0d-b2de-59ec12c15dc4
…ver into a follow-up PR This PR now only contains the tspd documentation generation (the \docs\ field + \FileRef\, and tspd rendering a page per rule/diagnostic). The \ eferenceDocs.baseUrl\ url auto-generation and the language server hover that surfaces the docs are moved to a separate PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: de8537de-5e61-4a0d-b2de-59ec12c15dc4
Builds on the tspd documentation generation. Add `referenceDocs.baseUrl` to the library definition so the compiler auto-fills the `url` of documented diagnostics/rules that don't set one (an explicit url still wins), and make the language server render a diagnostic/rule's `docs` (plus a documentation link) when hovering over a reported error, resolving the library via a new `@internal` Program.getLoadedLibraryInfo. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: de8537de-5e61-4a0d-b2de-59ec12c15dc4
tadelesh
requested review from
RodgeFu,
bterlson,
catalinaperalta,
iscai-msft,
markcowl,
timotheeguerin and
witemple-msft
as code owners
July 17, 2026 03:49
microsoft-github-policy-service
Bot
added
compiler:core
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
1 participant
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 #11221 (stacked on top of it). Builds on the
tspddocumentation generation to make the samedocsavailable in the editor.Note
Base is
tadelesh/auto-gen-rule-diagnostic-docs(#11221). Review/merge that first; this PR's diff is just the url + hover delta.Compiler
Auto-generated reference
url. The library definition passed tocreateTypeSpecLibraryacceptsreferenceDocs.baseUrl. When set, the compiler auto-fills theurlof any documented diagnostic/rule that does not specify one:${baseUrl}/diagnostics/<code>${baseUrl}/rules/<name>This gives every documented diagnostic/rule a clickable code link in the editor without hardcoding a url per item, while avoiding links to pages that are not generated. An explicit
urlstill takes precedence.Language server hover. Hovering over a reported error now renders the extended
docsof the corresponding diagnostic/rule as markdown, plus a "See documentation" link when a url is available. The LSPDiagnosticmessage is plain-text only (there is no markdown field on it), so hover is the only channel that can show rich docs inline at an error. Since emitter/linter diagnostics only exist in the full compile, the hover reuses the diagnostics from the last full compile — matched by source location the same way the squiggles are — and resolves each one'sdocsthrough a new@internalProgram.getLoadedLibraryInfothat loads the library's default entry via the compiler's own (cached) entrypoint loader. That default entry is where the linter export lives, whereas the entry.tspfiles import (thetypespeccondition) may only expose the library definition.Pilots
@typespec/http— theop-reference-container-routerule declaresreferenceDocs.baseUrland drops its hardcodedurl(now auto-generated).@typespec/openapi3— declaresreferenceDocs.baseUrlso its 6 documented diagnostics get auto-generated urls.src/**/*.mdso installed libraries can resolveFileRefdocs at runtime (used by the hover).Validation
compiler,http,openapi3; the compiler server suite (including the URL and hover tests) and theop-reference-container-routerule tests pass.