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

.chronus/changes/diagnostic-docs-openapi3-2026-6-9.md

@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/openapi3"
+---
+
+Provide extended documentation for several diagnostics (`path-query`, `duplicate-header`, `inline-cycle`, `invalid-schema`, `invalid-server-variable`, `union-null`) via co-located markdown files.

.chronus/changes/rule-diagnostic-docs-tspd-2026-6-9.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/tspd"
+---
+
+`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.

.chronus/changes/rule-docs-http-2026-6-9.md

@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/http"
+---
+
+Provide extended documentation for the `op-reference-container-route` linter rule via a co-located markdown file.

packages/http/README.md

@@ -26,9 +26,9 @@ Available ruleSets:
 
 ## Rules
 
-| Name                                                                                                                        | Description                                                                               |
-| --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| [`@typespec/http/op-reference-container-route`](https://typespec.io/docs/libraries/http/rules/op-reference-container-route) | Check for referenced (`op is`) operations which have a @route on one of their containers. |
+| Name                                                                                                                                  | Description                                                                               |
+| ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [`@typespec/http/op-reference-container-route`](https://typespec.io/docs/libraries/http/reference/rules/op-reference-container-route) | Check for referenced (`op is`) operations which have a @route on one of their containers. |
 
 ## Decorators
 

packages/http/src/rules/op-reference-container-route.md

@@ -0,0 +1,38 @@
+When referencing an operation with `op is`, only the data on the operation itself is carried over; anything on the parent container is lost.
+This results in unexpected behavior where information is lost.
+As a best practice the route should be provided on the operation itself.
+
+#### ❌ Incorrect
+
+```tsp
+namespace Library {
+  @route("/pets")
+  interface Pets {
+    @route("/read") read(): string;
+  }
+}
+
+@service
+namespace Service {
+  interface PetStore {
+    readPet is Library.Pets.read;
+  }
+}
+```
+
+#### ✅ Correct
+
+```tsp
+namespace Library {
+  interface Pets {
+    @route("/pets/read") read(): string;
+  }
+}
+
+@service
+namespace Service {
+  interface PetStore {
+    readPet is Library.Pets.read;
+  }
+}
+```

packages/http/src/rules/op-reference-container-route.ts

@@ -7,7 +7,7 @@ export const opReferenceContainerRouteRule = createRule({
   severity: "warning",
   description:
     "Check for referenced (`op is`) operations which have a @route on one of their containers.",
-  url: "https://typespec.io/docs/libraries/http/rules/op-reference-container-route",
+  url: "https://typespec.io/docs/libraries/http/reference/rules/op-reference-container-route",
   messages: {
     default: paramMessage`Operation ${"opName"} references an operation which has a @route prefix on its namespace or interface: "${"routePrefix"}".  This operation will not carry forward the route prefix so the final route may be different than the referenced operation.`,
   },

packages/openapi3/src/diagnostics/duplicate-header.md

@@ -0,0 +1,22 @@
+This diagnostic is issued when a response header is defined more than once for a response of a specific status code.
+
+To fix this issue, ensure that each response header is defined only once for each status code.
+
+### Example
+
+```yaml
+responses:
+  "200":
+    description: Successful response
+    headers:
+      X-Rate-Limit:
+        description: The number of allowed requests in the current period
+        schema:
+          type: integer
+      X-Rate-Limit:
+        description: The number of allowed requests in the current period
+        schema:
+          type: integer
+```
+
+In this example, the `X-Rate-Limit` header is defined twice for the `200` status code. To fix this issue, remove the duplicate header definition.

packages/openapi3/src/diagnostics/inline-cycle.md

@@ -0,0 +1,19 @@
+This diagnostic is issued when a cyclic reference is detected within inline schemas.
+
+To fix this issue, refactor the schemas to remove the cyclic reference.
+
+### Example
+
+```yaml
+components:
+  schemas:
+    Node:
+      type: object
+      properties:
+        value:
+          type: string
+        next:
+          $ref: "#/components/schemas/Node"
+```
+
+In this example, the `Node` schema references itself, creating a cyclic reference. To fix this issue, refactor the schema to remove the cyclic reference.

packages/openapi3/src/diagnostics/invalid-schema.md

@@ -0,0 +1,20 @@
+This diagnostic is issued when a schema is invalid according to the OpenAPI v3 specification.
+
+To fix this issue, review your TypeSpec definitions to ensure they map to valid OpenAPI schemas.
+
+### Example
+
+```yaml
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        age:
+          type: integer
+          format: "int" # Invalid format
+```
+
+In this example, the `format` value for the `age` property is invalid. To fix this issue, provide a valid format value such as `int32` or `int64`.

packages/openapi3/src/diagnostics/invalid-server-variable.md

@@ -0,0 +1,14 @@
+This diagnostic is issued when a variable in the `@server` decorator is not defined as a string type.
+Since server variables are substituted into the server URL which is a string, all variables must have string values.
+
+To fix this issue, make sure all server variables are of a type that is assignable to `string`.
+
+### Example
+
+```typespec
+@server("{protocol}://{host}/api/{version}", "Custom endpoint", {
+  protocol: "http" | "https",
+  host: string,
+  version: 1, // Should be a string: "1"
+})
+```

packages/openapi3/src/diagnostics/path-query.md

@@ -0,0 +1,26 @@
+This diagnostic is issued when the OpenAPI emitter finds an `@route` decorator that specifies a path that contains a query parameter. This is not permitted by the OpenAPI v3 specification, which requires query parameters to be defined separately.
+
+To fix this issue, redesign the API to only use paths without query parameters, and define query parameters using the `@query` decorator.
+
+### Example
+
+Instead of:
+
+```typespec
+@route("/users?filter={filter}")
+op getUsers(filter: string): User[];
+```
+
+Use:
+
+```typespec
+@route("/users")
+op getUsers(@query filter?: string): User[];
+```
+
+Alternatively, you can leverage TypeSpec's support for URI templates:
+
+```typespec
+@route("/users{?filter}")
+op getUsers(filter?: string): User[];
+```

packages/openapi3/src/diagnostics/union-null.md

@@ -0,0 +1,3 @@
+This diagnostic is issued when the result of model composition is effectively a `null` schema which cannot be represented in OpenAPI.
+
+To fix this issue, review your model compositions to ensure they produce valid schemas with actual properties or types.

packages/openapi3/src/lib.ts

@@ -321,6 +321,7 @@ export const $lib = createTypeSpecLibrary({
     },
     "invalid-server-variable": {
       severity: "error",
+      description: "A variable in the `@server` decorator is not assignable to `string`.",
       messages: {
         default: paramMessage`Server variable '${"propName"}' must be assignable to 'string'. It must either be a string, enum of string or union of strings.`,
       },
@@ -352,12 +353,15 @@ export const $lib = createTypeSpecLibrary({
     },
     "path-query": {
       severity: "error",
+      description: "An `@route` path contains a query parameter, which OpenAPI v3 does not allow.",
       messages: {
         default: `OpenAPI does not allow paths containing a query string.`,
       },
     },
     "duplicate-header": {
       severity: "error",
+      description:
+        "A response header is defined more than once for a response of a specific status code.",
       messages: {
         default: paramMessage`The header ${"header"} is defined across multiple content types`,
       },
@@ -371,12 +375,15 @@ export const $lib = createTypeSpecLibrary({
 
     "invalid-schema": {
       severity: "error",
+      description: "A schema is invalid according to the OpenAPI v3 specification.",
       messages: {
         default: paramMessage`Couldn't get schema for type ${"type"}`,
       },
     },
     "union-null": {
       severity: "error",
+      description:
+        "The result of model composition is effectively a `null` schema, which cannot be represented in OpenAPI.",
       messages: {
         default: "Cannot have a union containing only null types.",
       },
@@ -403,6 +410,7 @@ export const $lib = createTypeSpecLibrary({
     },
     "inline-cycle": {
       severity: "error",
+      description: "A cyclic reference was detected within inline schemas.",
       messages: {
         default: paramMessage`Cycle detected in '${"type"}'. Use @friendlyName decorator to assign an OpenAPI definition name and make it non-inline.`,
       },

packages/tspd/src/ref-doc/emitters/starlight.ts

@@ -1,5 +1,6 @@
 import {
   DeprecationNotice,
+  DiagnosticRefDoc,
   LinterRuleRefDoc,
   NamedTypeRefDoc,
   RefDocEntity,
@@ -12,8 +13,10 @@ import {
   MarkdownSection,
   codeblock,
   inlinecode,
+  link,
   renderMarkdowDoc,
   section,
+  table,
 } from "../utils/markdown.js";
 import { MarkdownRenderer, groupByNamespace } from "./markdown.js";
 
@@ -54,7 +57,23 @@ export function renderToAstroStarlightMarkdown(
   }
   const linter = renderLinter(renderer, refDoc);
   if (linter) {
-    files["linter.md"] = linter;
+    // Use the rule directory's index so the per-rule pages nest under it in the sidebar.
+    files["rules/index.md"] = linter;
+  }
+
+  for (const rule of refDoc.linter?.rules ?? []) {
+    files[`rules/${rule.rule.name}.md`] = renderRule(rule);
+  }
+
+  const diagnosticsIndex = renderDiagnostics(refDoc);
+  if (diagnosticsIndex) {
+    // Use the diagnostics directory's index so the per-diagnostic pages nest under it.
+    files["diagnostics/index.md"] = diagnosticsIndex;
+    for (const diagnostic of refDoc.diagnostics ?? []) {
+      if (diagnostic.doc) {
+        files[`diagnostics/${diagnostic.name}.md`] = renderDiagnostic(diagnostic);
+      }
+    }
   }
 
   // Render sub-exports
@@ -277,7 +296,63 @@ function renderLinter(
     "---",
     renderer.linterUsage(refDoc),
   ];
+  return renderMarkdowDoc(content, 2);
+}
+
+function renderRule(rule: LinterRuleRefDoc): string {
+  const content: MarkdownDoc = [
+    "---",
+    `title: "${rule.rule.name}"`,
+    "---",
+    "",
+    codeblock(rule.name, 'text title="Id"'),
+    "",
+    rule.rule.description,
+  ];
+  if (rule.doc) {
+    content.push("", rule.doc);
+  }
+  return renderMarkdowDoc(content, 2);
+}
+
+function renderDiagnostics(refDoc: TypeSpecLibraryRefDoc): string | undefined {
+  const diagnostics = refDoc.diagnostics;
+  // Only generate the diagnostics reference once a library has started documenting its
+  // diagnostics (at least one has `docs`). This keeps libraries that haven't opted in yet
+  // from getting an empty/auto index page.
+  if (diagnostics === undefined || !diagnostics.some((d) => d.doc)) {
+    return undefined;
+  }
+  const sorted = [...diagnostics].sort((a, b) => a.name.localeCompare(b.name, "en"));
+  const rows: string[][] = [["Code", "Severity", "Description"]];
+  for (const diagnostic of sorted) {
+    const label = inlinecode(diagnostic.id);
+    const codeCell = diagnostic.doc ? link(label, `./${diagnostic.name}.md`) : label;
+    rows.push([codeCell, diagnostic.severity, diagnostic.description ?? ""]);
+  }
+  const content: MarkdownDoc = [
+    "---",
+    `title: "Diagnostics"`,
+    "---",
+    "",
+    "The following diagnostics can be reported by this library.",
+    "",
+    table(rows),
+  ];
+  return renderMarkdowDoc(content, 2);
+}
 
+function renderDiagnostic(diagnostic: DiagnosticRefDoc): string {
+  const content: MarkdownDoc = [
+    "---",
+    `title: "${diagnostic.name}"`,
+    "---",
+    "",
+    codeblock(diagnostic.id, 'text title="Id"'),
+  ];
+  if (diagnostic.doc) {
+    content.push("", diagnostic.doc);
+  }
   return renderMarkdowDoc(content, 2);
 }
 
@@ -430,7 +505,8 @@ export class StarlightRenderer extends MarkdownRenderer {
   }
 
   linterRuleLink(rule: LinterRuleRefDoc) {
-    return `../rules/${rule.rule.name}.md`;
+    // The linter usage page is the `rules/` directory index, so rule pages are siblings.
+    return `./${rule.rule.name}.md`;
   }
 
   deprecationNotice(notice: DeprecationNotice): MarkdownDoc {