Add ref docs for linter rules (microsoft#2668)

Add some generated doc for the linter capability of a library.

Each linter rule can also provide a url pointing to the the full
documentation where we can get a more detailed set of examples of what
is good and what is bad.

Example for http linter 

https://tspwebsitepr.z22.web.core.windows.net/prs/2668/next/standard-library/http/reference/linter.html



![image](https://github.com/microsoft/typespec/assets/1031227/81c2dddc-fa0f-40dd-bad7-9d193f764c55)


![image](https://github.com/microsoft/typespec/assets/1031227/36652cd5-418b-43b9-bd9a-aff046cbe538)

---------

Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>

Author: timotheeguerin

common/changes/@typespec/compiler/feature-linter-ref-docs_2023-11-14-17-34.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "Linter rules can provide a url to the full documentation",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/compiler"
+}

common/changes/@typespec/http/feature-linter-ref-docs_2023-11-14-17-34.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/http",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/http"
+}

docs/standard-library/http/reference/linter.md

@@ -0,0 +1,29 @@
+---
+title: "Linter usage"
+toc_min_heading_level: 2
+toc_max_heading_level: 3
+---
+
+# Linter
+
+## Usage
+
+Add the following in `tspconfig.yaml`:
+
+```yaml
+linter:
+  extends:
+    - "@typespec/http/all"
+```
+
+## RuleSets
+
+Available ruleSets:
+
+- [`@typespec/http/all`](#@typespec/http/all)
+
+## Rules
+
+| Name                                                                                                          | Description                                                                               |
+| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [`@typespec/http/op-reference-container-route`](/standard-library/http/rules/op-reference-container-route.md) | Check for referenced (`op is`) operations which have a @route on one of their containers. |

docs/standard-library/http/rules/op-reference-container-route.md

@@ -0,0 +1,48 @@
+---
+title: "op-reference-container-route"
+---
+
+```text title="Id"
+@typespec/http/op-reference-container-route
+```
+
+Check for referenced (`op is`) operations which have a `@route` on one of their containers.
+
+When referencing an operation with `op is` only the data on the operation itself is carried over anything on parent container is lost.
+This result 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/compiler/src/core/types.ts

@@ -2022,10 +2022,17 @@ export interface LinterDefinition {
 }
 
 export interface LinterRuleDefinition<N extends string, DM extends DiagnosticMessages> {
+  /** Rule name (without the library name) */
   name: N;
+  /** Rule default severity. */
   severity: "warning";
+  /** Short description of the rule */
   description: string;
+  /** Specifies the URL at which the full documentation can be accessed. */
+  url?: string;
+  /** Messages that can be reported with the diagnostic. */
   messages: DM;
+  /** Creator */
   create(context: LinterRuleContext<DM>): SemanticNodeListener;
 }
 

packages/http/README.md

@@ -8,6 +8,30 @@ TypeSpec HTTP protocol binding
 npm install @typespec/http
 ```
 
+## Linter
+
+### Usage
+
+Add the following in `tspconfig.yaml`:
+
+```yaml
+linter:
+  extends:
+    - "@typespec/http/all"
+```
+
+### RuleSets
+
+Available ruleSets:
+
+- [`@typespec/http/all`](#@typespec/http/all)
+
+### Rules
+
+| Name                                                                                                                                           | Description                                                                               |
+| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [`@typespec/http/op-reference-container-route`](https://microsoft.github.io/typespec/standard-library/http/rules/op-reference-container-route) | Check for referenced (`op is`) operations which have a @route on one of their containers. |
+
 ## Decorators
 
 ### TypeSpec.Http

packages/http/package.json

@@ -4,6 +4,7 @@
   "author": "Microsoft Corporation",
   "description": "TypeSpec HTTP protocol binding",
   "homepage": "https://github.com/microsoft/typespec",
+  "docusaurusWebsite": "https://microsoft.github.io/typespec",
   "readme": "https://github.com/microsoft/typespec/blob/main/README.md",
   "license": "MIT",
   "repository": {

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

@@ -4,9 +4,10 @@ import { OperationContainer } from "../types.js";
 
 export const opReferenceContainerRouteRule = createRule({
   name: "op-reference-container-route",
+  severity: "warning",
   description:
     "Check for referenced (`op is`) operations which have a @route on one of their containers.",
-  severity: "warning",
+  url: "https://microsoft.github.io/typespec/standard-library/http/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/tspd/src/ref-doc/emitters/docusaurus.ts

@@ -19,7 +19,7 @@ import { MarkdownRenderer, groupByNamespace } from "./markdown.js";
  * Render doc to a markdown using docusaurus addons.
  */
 export function renderToDocusaurusMarkdown(refDoc: TypeSpecRefDoc): Record<string, string> {
-  const renderer = new DocusaurusRenderer();
+  const renderer = new DocusaurusRenderer(refDoc);
   const files: Record<string, string> = {
     "index.mdx": renderIndexFile(renderer, refDoc),
   };
@@ -43,6 +43,10 @@ export function renderToDocusaurusMarkdown(refDoc: TypeSpecRefDoc): Record<strin
   if (emitter) {
     files["emitter.md"] = emitter;
   }
+  const linter = renderLinter(renderer, refDoc);
+  if (linter) {
+    files["linter.md"] = linter;
+  }
 
   return files;
 }
@@ -231,8 +235,31 @@ function renderEmitter(
 
   return renderMarkdowDoc(content);
 }
+function renderLinter(
+  renderer: DocusaurusRenderer,
+  refDoc: TypeSpecLibraryRefDoc
+): string | undefined {
+  if (refDoc.linter === undefined) {
+    return undefined;
+  }
+  const content: MarkdownDoc = [
+    "---",
+    `title: "Linter usage"`,
+    "toc_min_heading_level: 2",
+    "toc_max_heading_level: 3",
+    "---",
+    renderer.linterUsage(refDoc),
+  ];
+
+  return renderMarkdowDoc(content);
+}
 
 export class DocusaurusRenderer extends MarkdownRenderer {
+  #refDoc: TypeSpecLibraryRefDoc;
+  constructor(refDoc: TypeSpecLibraryRefDoc) {
+    super();
+    this.#refDoc = refDoc;
+  }
   headingTitle(item: NamedTypeRefDoc): string {
     // Set an explicit anchor id.
     return `${inlinecode(item.name)} {#${item.id}}`;
@@ -259,4 +286,14 @@ export class DocusaurusRenderer extends MarkdownRenderer {
       ])
     );
   }
+
+  linterRuleLink(url: string) {
+    const homepage = (this.#refDoc.packageJson as any).docusaurusWebsite;
+    if (homepage && url.includes(homepage)) {
+      const fromRoot = url.replace(homepage, "");
+      return `${fromRoot}.md`;
+    } else {
+      return url;
+    }
+  }
 }

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

@@ -1,15 +1,18 @@
 import { resolvePath } from "@typespec/compiler";
 import { readFile } from "fs/promises";
+import { stringify } from "yaml";
 import {
   DecoratorRefDoc,
   EmitterOptionRefDoc,
   EnumRefDoc,
   ExampleRefDoc,
   InterfaceRefDoc,
+  LinterRuleRefDoc,
   ModelRefDoc,
   NamedTypeRefDoc,
   NamespaceRefDoc,
   OperationRefDoc,
+  ReferencableElement,
   ScalarRefDoc,
   TemplateParameterRefDoc,
   TypeSpecRefDoc,
@@ -20,6 +23,7 @@ import {
   MarkdownDoc,
   codeblock,
   inlinecode,
+  link,
   renderMarkdowDoc,
   section,
   table,
@@ -56,6 +60,10 @@ export async function renderReadme(refDoc: TypeSpecRefDoc, projectRoot: string)
     content.push(renderer.emitterUsage(refDoc));
   }
 
+  if (refDoc.linter) {
+    content.push(renderer.linterUsage(refDoc));
+  }
+
   if (refDoc.namespaces.some((x) => x.decorators.length > 0)) {
     content.push(section("Decorators", renderer.decoratorsSection(refDoc, { includeToc: true })));
   }
@@ -85,7 +93,7 @@ export class MarkdownRenderer {
     return inlinecode(item.name);
   }
 
-  anchorId(item: NamedTypeRefDoc): string {
+  anchorId(item: ReferencableElement): string {
     return `${item.name.toLowerCase().replace(/ /g, "-")}`;
   }
 
@@ -233,7 +241,7 @@ export class MarkdownRenderer {
     });
   }
 
-  toc(items: NamedTypeRefDoc[], filename?: string) {
+  toc(items: ReferencableElement[], filename?: string) {
     return items.map(
       (item) => ` - [${inlinecode(item.name)}](${filename ?? ""}#${this.anchorId(item)})`
     );
@@ -270,4 +278,37 @@ export class MarkdownRenderer {
     }
     return section("Emitter options", content);
   }
+
+  linterUsage(refDoc: TypeSpecRefDoc) {
+    if (refDoc.linter === undefined) {
+      return [];
+    }
+    const setupExample = stringify({
+      linter: refDoc.linter.ruleSets
+        ? { extends: [refDoc.linter.ruleSets[0].name] }
+        : { rules: {} },
+    });
+    return section("Linter", [
+      section("Usage", ["Add the following in `tspconfig.yaml`:", codeblock(setupExample, "yaml")]),
+      refDoc.linter.ruleSets
+        ? section("RuleSets", ["Available ruleSets:", this.toc(refDoc.linter.ruleSets)])
+        : [],
+      section("Rules", this.linterRuleToc(refDoc.linter.rules)),
+    ]);
+  }
+
+  linterRuleToc(rules: LinterRuleRefDoc[]) {
+    return table([
+      ["Name", "Description"],
+      ...rules.map((rule) => {
+        const name = inlinecode(rule.name);
+        const nameCell = rule.rule.url ? link(name, this.linterRuleLink(rule.rule.url)) : name;
+        return [nameCell, rule.rule.description];
+      }),
+    ]);
+  }
+
+  linterRuleLink(url: string) {
+    return url;
+  }
 }