Report unused suppressions (#10805)

<img width="299" height="143" alt="image"
src="https://github.com/user-attachments/assets/d401c48a-ac99-47f2-b2c3-ecf0a170bdbe"
/>

Author: timotheeguerin

.chronus/changes/unused-suppression-diagnostics-2026-05-26.md

@@ -0,0 +1,12 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+---
+
+Dim unused `#suppress` directives for available compiler and library diagnostics in editor scenarios.
+
+```typespec
+#suppress "deprecated" "old suppression"
+model Widget {}
+```

packages/compiler/src/core/messages.ts

@@ -1145,4 +1145,5 @@ const diagnostics = {
 } as const;
 
 export type CompilerDiagnostics = TypeOfDiagnostics<typeof diagnostics>;
+export const compilerDiagnosticCodes = new Set(Object.keys(diagnostics));
 export const { createDiagnostic, reportDiagnostic } = createDiagnosticCreator(diagnostics);

packages/compiler/src/core/program.ts

@@ -41,11 +41,14 @@ import {
 } from "./source-loader.js";
 import { createStateAccessors } from "./state-accessors.js";
 import { ComplexityStats, RuntimeStats, Stats } from "./stats.js";
+import {
+  SuppressionTracker,
+  createSuppressionTracker,
+  findDirectiveSuppressingOnNode,
+} from "./suppression-tracking.js";
 import {
   CompilerHost,
   Diagnostic,
-  Directive,
-  DirectiveExpressionNode,
   EmitContext,
   EmitterFunc,
   Entity,
@@ -64,7 +67,6 @@ import {
   Sym,
   SymbolFlags,
   SymbolTable,
-  SyntaxKind,
   TemplateInstanceTarget,
   Tracer,
   Type,
@@ -118,6 +120,8 @@ export interface Program {
 
   /** @internal */
   reportDuplicateSymbols(symbols: SymbolTable | undefined): void;
+  /** @internal */
+  readonly suppressionTracker: SuppressionTracker | undefined;
 
   getGlobalNamespaceType(): Namespace;
 
@@ -218,9 +222,11 @@ async function createProgram(
   const emitters: EmitterRef[] = [];
   const requireImports = new Map<string, string>();
   const complexityStats: ComplexityStats = {} as any;
-  let sourceResolution: SourceResolution;
+  let sourceResolution: SourceResolution = undefined!;
   let error = false;
   let continueToNextStage = true;
+  // eslint-disable-next-line prefer-const -- reassigned after source resolution
+  let suppressionTracker: SuppressionTracker | undefined;
 
   const logger = createLogger({ sink: host.logSink });
   const tracer = createTracer(logger, { filter: options.trace });
@@ -250,6 +256,9 @@ async function createProgram(
     reportDiagnostic,
     reportDiagnostics,
     reportDuplicateSymbols,
+    get suppressionTracker() {
+      return suppressionTracker;
+    },
     hasError() {
       return error;
     },
@@ -295,6 +304,8 @@ async function createProgram(
   // let GC reclaim old program, we do not reuse it beyond this point.
   oldProgram = undefined;
 
+  suppressionTracker = createSuppressionTracker(sourceResolution);
+
   const resolver = (program.resolver = createResolver(program));
   runtimeStats.resolver = perf.time(() => resolver.resolveProgram());
 
@@ -821,6 +832,7 @@ async function createProgram(
     if (suppressing) {
       if (diagnostic.severity === "error") {
         // Cannot suppress errors.
+        suppressionTracker?.markUsed(suppressing.node);
         diagnostics.push({
           severity: "error",
           code: "suppress-error",
@@ -830,59 +842,13 @@ async function createProgram(
 
         return false;
       } else {
+        suppressionTracker?.markUsed(suppressing.node);
         return true;
       }
     }
     return false;
   }
 
-  function findDirectiveSuppressingOnNode(code: string, node: Node): Directive | undefined {
-    let current: Node | undefined = node;
-    do {
-      if (current.directives) {
-        const directive = findDirectiveSuppressingCode(code, current.directives);
-        if (directive) {
-          return directive;
-        }
-      }
-    } while ((current = current.parent));
-    return undefined;
-  }
-
-  /**
-   * Returns the directive node that is suppressing this code.
-   * @param code Code to check for suppression.
-   * @param directives List of directives.
-   * @returns Directive suppressing this code if found, `undefined` otherwise
-   */
-  function findDirectiveSuppressingCode(
-    code: string,
-    directives: readonly DirectiveExpressionNode[],
-  ): Directive | undefined {
-    for (const directive of directives.map((x) => parseDirective(x))) {
-      if (directive.name === "suppress") {
-        if (directive.code === code) {
-          return directive;
-        }
-      }
-    }
-    return undefined;
-  }
-
-  function parseDirective(node: DirectiveExpressionNode): Directive {
-    const args = node.arguments.map((x) => {
-      return x.kind === SyntaxKind.Identifier ? x.sv : x.value;
-    });
-    switch (node.target.sv) {
-      case "suppress":
-        return { name: "suppress", code: args[0], message: args[1], node };
-      case "deprecated":
-        return { name: "deprecated", message: args[0], node };
-      default:
-        throw new Error("Unexpected directive name.");
-    }
-  }
-
   function getNode(target: Node | Entity | Sym | TemplateInstanceTarget): Node | undefined {
     if (!("kind" in target) && !("valueKind" in target) && !("entityKind" in target)) {
       // TemplateInstanceTarget

packages/compiler/src/core/suppression-tracking.ts

@@ -0,0 +1,192 @@
+import { defineCodeFix, getSourceLocation } from "./diagnostics.js";
+import { builtInLinterLibraryName } from "./linter.js";
+import { compilerDiagnosticCodes } from "./messages.js";
+import { visitChildren } from "./parser.js";
+import { SourceResolution } from "./source-loader.js";
+import {
+  CodeFix,
+  Directive,
+  DirectiveExpressionNode,
+  Node,
+  SuppressDirective,
+  SyntaxKind,
+} from "./types.js";
+
+export interface UnusedSuppression {
+  directive: SuppressDirective;
+}
+
+export interface SuppressionTracker {
+  markUsed(directiveNode: DirectiveExpressionNode): void;
+  getUnusedSuppressions(): UnusedSuppression[];
+}
+
+export function createSuppressionTracker(sourceResolution: SourceResolution): SuppressionTracker {
+  const suppressions = collectSuppressions(sourceResolution);
+
+  return {
+    markUsed(directiveNode) {
+      const suppression = suppressions.get(directiveNode);
+      if (suppression) {
+        suppression.used = true;
+      }
+    },
+    getUnusedSuppressions() {
+      const unused: UnusedSuppression[] = [];
+      for (const suppression of suppressions.values()) {
+        if (suppression.used) {
+          continue;
+        }
+
+        const availability = getSuppressionSourceAvailability(
+          suppression.directive.code,
+          sourceResolution,
+        );
+        if (availability === "unavailable") {
+          continue;
+        }
+
+        unused.push({ directive: suppression.directive });
+      }
+      return unused;
+    },
+  };
+}
+
+interface SuppressionRecord {
+  directive: SuppressDirective;
+  used: boolean;
+}
+
+function collectSuppressions(
+  sourceResolution: SourceResolution,
+): Map<DirectiveExpressionNode, SuppressionRecord> {
+  const suppressions = new Map<DirectiveExpressionNode, SuppressionRecord>();
+  for (const script of sourceResolution.sourceFiles.values()) {
+    if (sourceResolution.locationContexts.get(script.file)?.type !== "project") {
+      continue;
+    }
+
+    visit(script);
+  }
+
+  return suppressions;
+
+  function visit(node: Node) {
+    for (const directiveNode of node.directives ?? []) {
+      const directive = parseDirective(directiveNode);
+      if (directive?.name === "suppress") {
+        suppressions.set(directive.node, { directive, used: false });
+      }
+    }
+
+    visitChildren(node, visit);
+  }
+}
+
+function getSuppressionSourceAvailability(
+  code: string,
+  sourceResolution: SourceResolution,
+): "available" | "unavailable" {
+  if (
+    compilerDiagnosticCodes.has(code) ||
+    matchesDiagnosticSource(code, builtInLinterLibraryName)
+  ) {
+    return "available";
+  }
+
+  for (const libraryName of sourceResolution.loadedLibraries.keys()) {
+    if (matchesDiagnosticSource(code, libraryName)) {
+      return "available";
+    }
+  }
+
+  return "unavailable";
+}
+
+function matchesDiagnosticSource(code: string, source: string): boolean {
+  return code.startsWith(`${source}/`);
+}
+
+export function findDirectiveSuppressingOnNode(code: string, node: Node): Directive | undefined {
+  let current: Node | undefined = node;
+  do {
+    if (current.directives) {
+      const directive = findDirectiveSuppressingCode(code, current.directives);
+      if (directive) {
+        return directive;
+      }
+    }
+  } while ((current = current.parent));
+  return undefined;
+}
+
+/**
+ * Returns the directive node that is suppressing this code.
+ * @param code Code to check for suppression.
+ * @param directives List of directives.
+ * @returns Directive suppressing this code if found, `undefined` otherwise
+ */
+export function findDirectiveSuppressingCode(
+  code: string,
+  directives: readonly DirectiveExpressionNode[],
+): Directive | undefined {
+  for (const directiveNode of directives) {
+    const directive = parseDirective(directiveNode);
+    if (directive?.name === "suppress") {
+      if (directive.code === code) {
+        return directive;
+      }
+    }
+  }
+  return undefined;
+}
+
+export function parseDirective(node: DirectiveExpressionNode): Directive | undefined {
+  const args = node.arguments.map((x) => {
+    return x.kind === SyntaxKind.Identifier ? x.sv : x.value;
+  });
+  switch (node.target.sv) {
+    case "suppress":
+      if (typeof args[0] !== "string") {
+        return undefined;
+      }
+      return { name: "suppress", code: args[0], message: args[1] ?? "", node };
+    case "deprecated":
+      if (typeof args[0] !== "string") {
+        return undefined;
+      }
+      return { name: "deprecated", message: args[0], node };
+    default:
+      return undefined;
+  }
+}
+
+export function createRemoveUnusedSuppressionCodeFix(node: DirectiveExpressionNode): CodeFix {
+  return defineCodeFix({
+    id: "remove-unused-suppression",
+    label: "Remove unused suppression",
+    fix: (context) => {
+      const location = getSourceLocation(node);
+      const text = location.file.text;
+      const lineStart = text.lastIndexOf("\n", location.pos - 1) + 1;
+      const textBeforeDirective = text.slice(lineStart, location.pos);
+
+      if (textBeforeDirective.trim() !== "") {
+        return context.replaceText(location, "");
+      }
+
+      let end = location.end;
+      while (end < text.length && (text[end] === " " || text[end] === "\t")) {
+        end++;
+      }
+      if (text[end] === "\r" && text[end + 1] === "\n") {
+        end += 2;
+      } else if (text[end] === "\n" || text[end] === "\r") {
+        end++;
+      }
+
+      return context.replaceText({ ...location, pos: lineStart, end }, "");
+    },
+  });
+}

packages/compiler/src/server/serverlib.ts

@@ -72,6 +72,7 @@ import {
 import { type Program } from "../core/program.js";
 import { skipTrivia, skipWhiteSpace } from "../core/scanner.js";
 import { createSourceFile, getSourceFileKindFromExt } from "../core/source-file.js";
+import { createRemoveUnusedSuppressionCodeFix } from "../core/suppression-tracking.js";
 import {
   AugmentDecoratorStatementNode,
   CodeFixEdit,
@@ -844,6 +845,38 @@ export function createServer(
       }
     }
 
+    // Report unused suppressions as hints with faded-out styling
+    for (const { directive } of program.suppressionTracker?.getUnusedSuppressions() ?? []) {
+      const unusedSuppressionDiagnostic: Diagnostic = {
+        code: "unused-suppression",
+        severity: "warning",
+        message: `Suppression for "${directive.code}" is unused.`,
+        target: directive.node,
+        codefixes: [createRemoveUnusedSuppressionCodeFix(directive.node)],
+      };
+      const results = convertDiagnosticToLsp(
+        fileService,
+        program,
+        document,
+        unusedSuppressionDiagnostic,
+      );
+      for (const [diagnostic, diagDocument] of results) {
+        diagnostic.tags = [DiagnosticTag.Unnecessary];
+        diagnostic.severity = DiagnosticSeverity.Hint;
+        diagnostic.data = {
+          id: diagnosticIdCounter++,
+          file: diagDocument.uri,
+        };
+        const diagnostics = diagnosticMap.get(diagDocument);
+        compilerAssert(
+          diagnostics,
+          "Diagnostic reported against a source file that was not added to the program.",
+        );
+        diagnostics.push(diagnostic);
+        newDiagnosticIndex.set(diagnostic.data.id, unusedSuppressionDiagnostic);
+      }
+    }
+
     // Atomically swap the diagnostic index so that in-flight code action resolves
     // referencing old diagnostic IDs can still find their entries until new diagnostics are sent.
     currentDiagnosticIndex = newDiagnosticIndex;