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, so these pages stop being hand-written and drift-prone.

What's included

• @typespec/tspd: tspd doc now renders
  • one page per rule -> reference/rules/<name>.md
  • one page per diagnostic -> reference/diagnostics/<code>.md + a diagnostics index
  • and reports a documentation-missing warning for rules/diagnostics without docs (only for libraries that have started documenting, to avoid noise).
• Pilots (migrated the hand-written pages into the new system and deleted them):
  • @typespec/http — op-reference-container-route rule.
  • @typespec/openapi3 — 6 diagnostics (path-query, duplicate-header, inline-cycle, invalid-schema, invalid-server-variable, union-null).
  • @typespec/openapi — 2 diagnostics (duplicate-type-name, invalid-extension-key) that were previously (mis-)documented on the openapi3 page.

How docs are authored

Extended docs are authored as a co-located markdown file, read from source by tspd at doc-generation time using a precise per-item convention:

• rules -> src/rules/<rule-name>.md
• diagnostics -> src/diagnostics/<code>.md

tspd reads exactly that one file per rule/diagnostic (no src/**/*.md glob), so a stray .md in src is never picked up. The library itself never loads the file at runtime, so nothing extra ends up in the browser/playground bundle. A library only gets a generated diagnostics index/pages once it has at least one documented item.

Validation

• Built compiler, tspd, http, openapi, openapi3; regen is stable (running it twice produces no diff).
• regen-ing libraries with no documented diagnostics (e.g. json-schema) produces no new files.
• lint green for the touched packages; op-reference-container-route rule tests pass; openapi api-extractor passes ($lib re-exported as @internal so tspd can enumerate diagnostics).

[pkg-pr-new]

Open in StackBlitz

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

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

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

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

commit: 1a02a89

[github-actions]

All changed packages have been documented.

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

Show changes

@typespec/openapi - internal ✏️

Provide extended documentation for the duplicate-type-name and invalid-extension-key diagnostics via co-located markdown files.

@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/tspd - feature ✏️

tspd doc now generates a documentation page per linter rule (reference/rules/<name>.md) and per diagnostic (reference/diagnostics/<code>.md) plus a diagnostics index, sourced from the docs field on the definitions. A documentation-missing warning is now also reported for linter rules and diagnostics without 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