feat(tspd): auto-generate linter rule and diagnostic reference pages

[tadelesh]

Fixes #11141

Auto-generate a reference documentation page per linter rule and per diagnostic with tspd, so these pages stop being hand-written and drift-prone.

Note

This PR is scoped to the tspd documentation generation. The referenceDocs.baseUrl url auto-generation and the language server hover that surfaces these docs at a reported error are split into a follow-up PR.

Compiler

• docs field on diagnostics and linter rules. Both createRule and diagnostic definitions accept a docs field for extended documentation:

  export const myRule = createRule({
    name: "my-rule",
    severity: "warning",
    description: "Short description.",
    docs: fileRef.fromPackageRoot("src/rules/my-rule.md"),
    messages: {
      /* ... */
    },
  });

  The value is string | FileRef: either inline markdown, or a FileRef created via fileRef.fromPackageRoot("..."). A FileRef is a plain { kind, path } data object read lazily by tooling, so it is safe to include in code bundled for the browser (e.g. the playground). Because the docs live on the definition, they are available at compile time, not just to tspd.

tspd

tspd doc now renders:

• one page per rule -> reference/rules/<name>.md
• one page per diagnostic -> reference/diagnostics/<code>.md (each shows its severity)
• a documentation-missing warning for every rule/diagnostic without docs.

Pilots

Content is faithfully migrated from the hand-written pages, which are then deleted:

• @typespec/http — the op-reference-container-route rule.
• @typespec/openapi3 — 6 diagnostics (path-query, duplicate-header, inline-cycle, invalid-schema, invalid-server-variable, union-null); the old hand-written emitters/openapi3/diagnostics.md is replaced by the generated pages under reference/diagnostics/.

Validation

• Built compiler, tspd, http, openapi3; regen is stable (running it twice produces no diff).
• lint green for the touched packages; the op-reference-container-route rule tests pass.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/compiler@11221

npm i https://pkg.pr.new/@typespec/http@11221

npm i https://pkg.pr.new/@typespec/openapi3@11221

npm i https://pkg.pr.new/@typespec/tspd@11221

commit: f614bf9

[github-actions]

All changed packages have been documented.

• ✅ @typespec/compiler
• ✅ @typespec/http
• ✅ @typespec/openapi3
• ✅ @typespec/tspd

Show changes

@typespec/openapi3 - internal ✏️

Provide extended documentation for several diagnostics (path-query, duplicate-header, inline-cycle, invalid-schema, invalid-server-variable, union-null) via co-located markdown files.

@typespec/compiler - feature ✏️

Add a docs field to linter rule and diagnostic definitions to provide extended reference documentation. The value can be an inline markdown string or a FileRef created with fileRef.fromPackageRoot("src/rules/my-rule.md"), which is read lazily by tooling so it stays safe to bundle for the browser.,> ,> ts,> export const myRule = createRule({,> name: "my-rule",,> severity: "warning",,> description: "Short description.",,> docs: fileRef.fromPackageRoot("src/rules/my-rule.md"),,> messages: {,> /* ... */,> },,> });,>

@typespec/tspd - feature ✏️

tspd doc now generates a documentation page per linter rule (reference/rules/<name>.md) and per diagnostic (reference/diagnostics/<code>.md), sourced from the docs field on the rule and diagnostic definitions. A documentation-missing warning is reported for any linter rule or diagnostic that does not provide documentation.

@typespec/http - internal ✏️

Provide extended documentation for the op-reference-container-route linter rule via a co-located markdown file.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[tadelesh]

@timotheeguerin updated the PR to the latest approach (option 2 from your review): diagnostics and linter rules take a docs?: string | FileRef field. docs is either inline markdown or fileRef.fromPackageRoot("src/rules/<name>.md") — a lazy { kind, path } reference read by tooling, never at import time, so it stays browser/playground-safe. tspd renders a page per rule/diagnostic from it, and because it lives on the definition it is also available at compile time (editor hover). Pilots are the http op-reference-container-route rule and 6 openapi3 diagnostics (old hand-written page removed). Would appreciate your review.

[tadelesh]

Follow-up review fixes (latest in 7758081):

• publish every markdown file referenced by FileRef in the HTTP/OpenAPI3 packages;
• only auto-generate a reference URL when docs exists, so we never link to a page that isn't generated (an explicit url still takes precedence);
• resolve the hover documentation by reusing the library the compiler already loaded (new @internal Program.getLoadedLibraryInfo) instead of re-resolving/reloading the package, so hoisted and import-only layouts work for free;
• on hover, reuse the diagnostics from the last full compile (matched by source location, the same way the squiggles are) instead of maintaining a separate diagnostic index;
• log documentation read failures instead of silently swallowing them.

Added regression coverage for URL generation / explicit-URL preservation and for inline and FileRef docs (including a hoisted dependency) plus the no-dead-link case. The compiler server suite passes.

[tadelesh]

Per discussion with @timotheeguerin, this PR is now scoped to just the tspd documentation generation (the docs field + FileRef, and tspd rendering a page per rule/diagnostic). The referenceDocs.baseUrl url auto-generation and the language-server hover that surfaces these docs at a reported error have been split out into a follow-up PR.

[timotheeguerin]

just perf tweak and I think otherwise this looks good