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-compiler-2026-6-9.md

@@ -0,0 +1,19 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+---
+
+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: {
+    /* ... */
+  },
+});
+```

.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`), 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.

.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/compiler/src/core/file-ref.ts

@@ -0,0 +1,31 @@
+/**
+ * A lazy reference to a file on disk. Unlike embedding the file content directly, a
+ * `FileRef` only describes *where* the content lives; it is resolved (read) by tooling
+ * such as `tspd` when needed. Because it does not read the file at definition time, it is
+ * safe to include in code that is bundled for the browser (e.g. the playground).
+ */
+export interface FileRef {
+  readonly kind: "file-ref";
+  /** Path to the file, relative to the package root. */
+  readonly path: string;
+}
+
+export const fileRef = {
+  /**
+   * Create a {@link FileRef} pointing to a file relative to the package root (the directory
+   * containing the library's `package.json`).
+   *
+   * @example
+   * ```ts
+   * docs: fileRef.fromPackageRoot("src/rules/my-rule.md"),
+   * ```
+   */
+  fromPackageRoot(path: string): FileRef {
+    return { kind: "file-ref", path };
+  },
+};
+
+/** Type guard for {@link FileRef}. */
+export function isFileRef(value: unknown): value is FileRef {
+  return typeof value === "object" && value !== null && (value as FileRef).kind === "file-ref";
+}

packages/compiler/src/core/types.ts

@@ -1,6 +1,7 @@
 import type { JSONSchemaType as AjvJSONSchemaType } from "ajv";
 import type { ModuleResolutionResult } from "../module-resolver/index.js";
 import type { YamlPathTarget, YamlScript } from "../yaml/types.js";
+import type { FileRef } from "./file-ref.js";
 import type { Numeric } from "./numeric.js";
 import type { Program } from "./program.js";
 import type { TokenFlags } from "./scanner.js";
@@ -2417,6 +2418,12 @@ export interface DiagnosticDefinition<M extends DiagnosticMessages> {
   readonly description?: string;
   /** Specifies the URL at which the full documentation can be accessed. */
   readonly url?: string;
+  /**
+   * Extended documentation for this diagnostic. Surfaced both in generated reference
+   * documentation and in editor tooling (e.g. completion and hover). Either raw markdown,
+   * or a {@link FileRef} pointing to a markdown file (recommended).
+   */
+  readonly docs?: string | FileRef;
 }
 
 export interface DiagnosticMessages {
@@ -2564,6 +2571,12 @@ interface LinterRuleDefinitionBase<
   description: string;
   /** Specifies the URL at which the full documentation can be accessed. */
   url?: string;
+  /**
+   * Extended documentation for this rule. Surfaced both in generated reference
+   * documentation and in editor tooling (e.g. completion and hover). Either raw markdown,
+   * or a {@link FileRef} pointing to a markdown file (recommended).
+   */
+  docs?: string | FileRef;
   /** Messages that can be reported with the diagnostic. */
   messages: DM;
   /**

packages/compiler/src/index.ts

@@ -47,6 +47,7 @@ export {
   type WriteLine,
 } from "./core/diagnostics.js";
 export { emitFile, type EmitFileOptions, type NewLine } from "./core/emitter-utils.js";
+export { fileRef, isFileRef, type FileRef } from "./core/file-ref.js";
 export { checkFormatTypeSpec, formatTypeSpec } from "./core/formatter.js";
 export {
   DiscriminatedUnion,

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

@@ -1,4 +1,4 @@
-import { Operation, createRule, paramMessage } from "@typespec/compiler";
+import { Operation, createRule, fileRef, paramMessage } from "@typespec/compiler";
 import { getRoutePath } from "../route.js";
 import { OperationContainer } from "../types.js";
 
@@ -8,6 +8,7 @@ export const opReferenceContainerRouteRule = createRule({
   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",
+  docs: fileRef.fromPackageRoot("src/rules/op-reference-container-route.md"),
   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

@@ -1,4 +1,4 @@
-import { createTypeSpecLibrary, JSONSchemaType, paramMessage } from "@typespec/compiler";
+import { createTypeSpecLibrary, fileRef, JSONSchemaType, paramMessage } from "@typespec/compiler";
 
 export type FileType = "yaml" | "json";
 export type OpenAPIVersion = "3.0.0" | "3.1.0" | "3.2.0";
@@ -321,6 +321,7 @@ export const $lib = createTypeSpecLibrary({
     },
     "invalid-server-variable": {
       severity: "error",
+      docs: fileRef.fromPackageRoot("src/diagnostics/invalid-server-variable.md"),
       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,14 @@ export const $lib = createTypeSpecLibrary({
     },
     "path-query": {
       severity: "error",
+      docs: fileRef.fromPackageRoot("src/diagnostics/path-query.md"),
       messages: {
         default: `OpenAPI does not allow paths containing a query string.`,
       },
     },
     "duplicate-header": {
       severity: "error",
+      docs: fileRef.fromPackageRoot("src/diagnostics/duplicate-header.md"),
       messages: {
         default: paramMessage`The header ${"header"} is defined across multiple content types`,
       },
@@ -371,12 +374,14 @@ export const $lib = createTypeSpecLibrary({
 
     "invalid-schema": {
       severity: "error",
+      docs: fileRef.fromPackageRoot("src/diagnostics/invalid-schema.md"),
       messages: {
         default: paramMessage`Couldn't get schema for type ${"type"}`,
       },
     },
     "union-null": {
       severity: "error",
+      docs: fileRef.fromPackageRoot("src/diagnostics/union-null.md"),
       messages: {
         default: "Cannot have a union containing only null types.",
       },
@@ -403,6 +408,7 @@ export const $lib = createTypeSpecLibrary({
     },
     "inline-cycle": {
       severity: "error",
+      docs: fileRef.fromPackageRoot("src/diagnostics/inline-cycle.md"),
       messages: {
         default: paramMessage`Cycle detected in '${"type"}'. Use @friendlyName decorator to assign an OpenAPI definition name and make it non-inline.`,
       },