Add url property to diagnostic (#4442)

fix [#4142](#4142)
Every diagnostic can now define a url pointing to a documentation with
more information on how you might have this diagnostic and how to
resolve it

.chronus/changes/diagnostic-url-2024-8-13-19-59-26.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+---
+
+Library diagnostic can now define a `description` and `url` that links to a more detailed doc for this diagnostic

docs/standard-library/diags/triple-quote-indent.md

@@ -0,0 +1,25 @@
+---
+title: triple-quote-indent
+---
+
+Triple quoted strings must all be at least indented to the same level as closing `"""`.
+
+#### ❌ Incorrect
+
+```tsp
+const a = """
+one
+  two
+  """;
+```
+
+#### ✅ Correct
+
+```tsp
+const a = """
+  one
+    two
+  """;
+```
+
+This would result in the following string `"one\n  two\n"`.

packages/compiler/src/core/diagnostic-creator.ts

@@ -1,3 +1,4 @@
+import { mutate } from "../utils/misc.js";
 import type { Program } from "./program.js";
 import type {
   Diagnostic,
@@ -56,8 +57,11 @@ export function createDiagnosticCreator<T extends { [code: string]: DiagnosticMe
       message: messageStr,
       target: diagnostic.target,
     };
+    if (diagnosticDef.url) {
+      mutate(result).url = diagnosticDef.url;
+    }
     if (diagnostic.codefixes) {
-      (result as any).codefixes = diagnostic.codefixes;
+      mutate(result).codefixes = diagnostic.codefixes;
     }
     return result;
   }

packages/compiler/src/core/logger/console-sink.ts

@@ -30,7 +30,7 @@ function hyperlink(text: string, url: string | undefined, options: FormatLogOpti
 }
 
 export function formatLog(log: ProcessedLog, options: FormatLogOptions): string {
-  const code = log.code ? hyperlink(color(options, ` ${log.code}`, pc.gray), log.url, options) : "";
+  const code = log.code ? ` ${hyperlink(color(options, log.code, pc.gray), log.url, options)}` : "";
   const level = formatLevel(options, log.level);
   const content = `${level}${code}: ${log.message}`;
   const location = log.sourceLocation;

packages/compiler/src/core/messages.ts

@@ -64,6 +64,9 @@ const diagnostics = {
 
   "triple-quote-indent": {
     severity: "error",
+    description:
+      "Report when a triple-quoted string has lines with less indentation as the closing triple quotes.",
+    url: "https://typespec.io/docs/standard-library/diags/triple-quote-indent",
     messages: {
       default:
         "All lines in triple-quoted string lines must have the same indentation as closing triple quotes.",

packages/compiler/src/core/types.ts

@@ -2352,9 +2352,35 @@ export type DiagnosticFormat<
     ? { format: Record<A[number], string> }
     : Record<string, unknown>;
 
+/**
+ * Declare a diagnostic that can be reported by the library.
+ *
+ * @example
+ *
+ * ```ts
+ * unterminated: {
+ *   severity: "error",
+ *   description: "Unterminated token.",
+ *   url: "https://example.com/docs/diags/unterminated",
+ *   messages: {
+ *     default: paramMessage`Unterminated ${"token"}.`,
+ *   },
+ * },
+ * ```
+ */
 export interface DiagnosticDefinition<M extends DiagnosticMessages> {
+  /**
+   * Diagnostic severity.
+   * - `warning` - Suppressable, should be used to represent potential issues but not blocking.
+   * - `error` - Non-suppressable, should be used to represent failure to move forward.
+   */
   readonly severity: "warning" | "error";
+  /** Messages that can be reported with the diagnostic. */
   readonly messages: M;
+  /** Short description of the diagnostic */
+  readonly description?: string;
+  /** Specifies the URL at which the full documentation can be accessed. */
+  readonly url?: string;
 }
 
 export interface DiagnosticMessages {

packages/website/sidebars.ts

@@ -115,6 +115,16 @@ const sidebars: SidebarsConfig = {
       items: [
         "standard-library/built-in-decorators",
         "standard-library/built-in-data-types",
+        {
+          type: "category",
+          label: "Diagnostics",
+          items: [
+            {
+              type: "autogenerated",
+              dirName: `standard-library/diags`,
+            },
+          ],
+        },
         {
           type: "autogenerated",
           dirName: `standard-library/reference`,