issue diagnostic for a templated model with a template parameter that is not used.

.chronus/changes/fix181-2025-0-6-16-32-31.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+---
+
+Support diagnostics for unused template parameter

packages/compiler/src/core/checker.ts

@@ -300,6 +300,9 @@ export interface Checker {
   /** @internal */
   getTypeOrValueForNode(node: Node): Type | Value | null;
 
+  /** @internal */
+  getTemplateParameterUsageMap(): Map<TemplateParameterDeclarationNode, boolean>;
+
   readonly errorType: ErrorType;
   readonly voidType: VoidType;
   readonly neverType: NeverType;
@@ -401,6 +404,11 @@ export function createChecker(program: Program, resolver: NameResolver): Checker
 
   let evalContext: EvalContext | undefined = undefined;
 
+  /**
+   * Tracking the template parameters used or not.
+   */
+  const templateParameterUsageMap = new Map<TemplateParameterDeclarationNode, boolean>();
+
   const checker: Checker = {
     getTypeForNode,
     checkProgram,
@@ -433,6 +441,7 @@ export function createChecker(program: Program, resolver: NameResolver): Checker
     getValueForNode,
     getTypeOrValueForNode,
     getValueExactType,
+    getTemplateParameterUsageMap,
     isTypeAssignableTo: undefined!,
   };
   const relation = createTypeRelationChecker(program, checker);
@@ -441,6 +450,10 @@ export function createChecker(program: Program, resolver: NameResolver): Checker
   const projectionMembers = createProjectionMembers(checker);
   return checker;
 
+  function getTemplateParameterUsageMap(): Map<TemplateParameterDeclarationNode, boolean> {
+    return templateParameterUsageMap;
+  }
+
   function wrapInstantiationDiagnostic(
     diagnostic: Diagnostic,
     templateMapper?: TypeMapper,
@@ -1066,6 +1079,10 @@ export function createChecker(program: Program, resolver: NameResolver): Checker
     const grandParentNode = parentNode.parent;
     const links = getSymbolLinks(node.symbol);
 
+    if (!templateParameterUsageMap.has(node)) {
+      templateParameterUsageMap.set(node, false);
+    }
+
     if (pendingResolutions.has(getNodeSym(node), ResolutionKind.Constraint)) {
       if (mapper === undefined) {
         reportCheckerDiagnostic(
@@ -1112,7 +1129,6 @@ export function createChecker(program: Program, resolver: NameResolver): Checker
         );
       }
     }
-
     return mapper ? mapper.getMappedType(type) : type;
   }
 
@@ -1516,6 +1532,20 @@ export function createChecker(program: Program, resolver: NameResolver): Checker
     node: TypeReferenceNode | MemberExpressionNode | IdentifierNode,
     mapper: TypeMapper | undefined,
     instantiateTemplates = true,
+  ): Type | Value | IndeterminateEntity | null {
+    const entity = checkTypeOrValueReferenceSymbolWorker(sym, node, mapper, instantiateTemplates);
+
+    if (entity !== null && isType(entity) && entity.kind === "TemplateParameter") {
+      templateParameterUsageMap.set(entity.node, true);
+    }
+    return entity;
+  }
+
+  function checkTypeOrValueReferenceSymbolWorker(
+    sym: Sym,
+    node: TypeReferenceNode | MemberExpressionNode | IdentifierNode,
+    mapper: TypeMapper | undefined,
+    instantiateTemplates = true,
   ): Type | Value | IndeterminateEntity | null {
     if (sym.flags & SymbolFlags.Const) {
       return getValueForNode(sym.declarations[0], mapper);

packages/compiler/src/core/compiler-code-fixes/remove-unused-template-parameter.codefix.ts

@@ -0,0 +1,44 @@
+import { defineCodeFix, getSourceLocation } from "../diagnostics.js";
+import { TemplateParameterDeclarationNode } from "../types.js";
+
+/**
+ * Quick fix that remove unused template parameter.
+ */
+export function removeUnusedTemplateParameterCodeFix(node: TemplateParameterDeclarationNode) {
+  return defineCodeFix({
+    id: "remove-unused-template-parameter",
+    label: `Remove unused template parameter ${node.id.sv}`,
+    fix: (context) => {
+      let location = getSourceLocation(node);
+      const parent = node.parent;
+      if (parent) {
+        const length = parent.templateParameters.length;
+        if (length === 1) {
+          location = {
+            file: location.file,
+            pos: parent.templateParametersRange.pos,
+            end: parent.templateParametersRange.end,
+          };
+        } else {
+          const index = parent.templateParameters.findIndex((param) => param === node);
+          if (index !== -1) {
+            if (index !== parent.templateParameters.length - 1) {
+              location = {
+                file: location.file,
+                pos: location.pos,
+                end: parent.templateParameters[index + 1].pos,
+              };
+            } else {
+              location = {
+                file: location.file,
+                pos: parent.templateParameters[index - 1].end,
+                end: location.end,
+              };
+            }
+          }
+        }
+      }
+      return context.replaceText(location, "");
+    },
+  });
+}

packages/compiler/src/core/linter-rules/unused-template-parameter.rule.ts

@@ -0,0 +1,37 @@
+import { removeUnusedTemplateParameterCodeFix } from "../compiler-code-fixes/remove-unused-template-parameter.codefix.js";
+import { createLinterRule, paramMessage } from "../library.js";
+
+export const builtInLinterRule_UnusedTemplateParameter = `unused-template-parameter`;
+
+/** @internal */
+export function createUnusedTemplateParameterLinterRule() {
+  return createLinterRule({
+    name: builtInLinterRule_UnusedTemplateParameter,
+    severity: "warning",
+    description: "Linter rules for unused template parameter.",
+    messages: {
+      default: paramMessage`Templates should use all specified parameters, and parameter '${"parameterName"}' does not exist in type '${"type"}'. Consider removing this parameter.`,
+    },
+    create(context) {
+      return {
+        root: (_root) => {
+          const templateParameters = context.program.checker
+            .getTemplateParameterUsageMap()
+            .entries();
+          for (const [templateParameter, used] of templateParameters) {
+            if (!used) {
+              context.reportDiagnostic({
+                format: {
+                  parameterName: templateParameter.id.sv,
+                  type: templateParameter.parent?.symbol.name ?? "",
+                },
+                target: templateParameter,
+                codefixes: [removeUnusedTemplateParameterCodeFix(templateParameter)],
+              });
+            }
+          }
+        },
+      };
+    },
+  });
+}

packages/compiler/src/core/linter-rules/unused-using.rule.ts

@@ -0,0 +1,39 @@
+import { removeUnusedCodeCodeFix } from "../compiler-code-fixes/remove-unused-code.codefix.js";
+import { createLinterRule, paramMessage } from "../library.js";
+import { NameResolver } from "../name-resolver.js";
+import { IdentifierNode, MemberExpressionNode, SyntaxKind } from "../types.js";
+
+export const builtInLinterRule_UnusedUsing = `unused-using`;
+
+/** @internal */
+export function createUnusedUsingLinterRule(nameResolver: NameResolver) {
+  return createLinterRule({
+    name: builtInLinterRule_UnusedUsing,
+    severity: "warning",
+    description: "Linter rules for unused using statement.",
+    messages: {
+      default: paramMessage`'using ${"code"}' is declared but never be used.`,
+    },
+    create(context) {
+      return {
+        root: (_root) => {
+          const getUsingName = (node: MemberExpressionNode | IdentifierNode): string => {
+            if (node.kind === SyntaxKind.MemberExpression) {
+              return `${getUsingName(node.base)}${node.selector}${node.id.sv}`;
+            } else {
+              // identifier node
+              return node.sv;
+            }
+          };
+          nameResolver.getUnusedUsings().forEach((target) => {
+            context.reportDiagnostic({
+              format: { code: getUsingName(target.name) },
+              target,
+              codefixes: [removeUnusedCodeCodeFix(target)],
+            });
+          });
+        },
+      };
+    },
+  });
+}

packages/compiler/src/core/linter.ts

@@ -1,26 +1,24 @@
-import { removeUnusedCodeCodeFix } from "./compiler-code-fixes/remove-unused-code.codefix.js";
 import { DiagnosticCollector, compilerAssert, createDiagnosticCollector } from "./diagnostics.js";
 import { getLocationContext } from "./helpers/location-context.js";
-import { createLinterRule, defineLinter, paramMessage } from "./library.js";
+import { defineLinter } from "./library.js";
+import { createUnusedTemplateParameterLinterRule } from "./linter-rules/unused-template-parameter.rule.js";
+import { createUnusedUsingLinterRule } from "./linter-rules/unused-using.rule.js";
 import { createDiagnostic } from "./messages.js";
 import { NameResolver } from "./name-resolver.js";
 import type { Program } from "./program.js";
 import { EventEmitter, mapEventEmitterToNodeListener, navigateProgram } from "./semantic-walker.js";
 import {
   Diagnostic,
   DiagnosticMessages,
-  IdentifierNode,
   LinterDefinition,
   LinterResolvedDefinition,
   LinterRule,
   LinterRuleContext,
   LinterRuleDiagnosticReport,
   LinterRuleSet,
-  MemberExpressionNode,
   NoTarget,
   RuleRef,
   SemanticNodeListener,
-  SyntaxKind,
 } from "./types.js";
 
 type LinterLibraryInstance = { linter: LinterResolvedDefinition };
@@ -267,7 +265,6 @@ export function createLinterRuleContext<N extends string, DM extends DiagnosticM
 }
 
 export const builtInLinterLibraryName = `@typespec/compiler`;
-export const builtInLinterRule_UnusedUsing = `unused-using`;
 export function createBuiltInLinterLibrary(nameResolver: NameResolver): LinterLibraryInstance {
   const builtInLinter: LinterResolvedDefinition = resolveLinterDefinition(
     builtInLinterLibraryName,
@@ -276,42 +273,11 @@ export function createBuiltInLinterLibrary(nameResolver: NameResolver): LinterLi
   return { linter: builtInLinter };
 }
 function createBuiltInLinter(nameResolver: NameResolver): LinterDefinition {
-  const unusedUsingLinterRule = createUnusedUsingLinterRule();
+  const unusedUsingLinterRule = createUnusedUsingLinterRule(nameResolver);
+
+  const unusedTemplateParameterLinterRule = createUnusedTemplateParameterLinterRule();
 
   return defineLinter({
-    rules: [unusedUsingLinterRule],
+    rules: [unusedUsingLinterRule, unusedTemplateParameterLinterRule],
   });
-
-  function createUnusedUsingLinterRule() {
-    return createLinterRule({
-      name: builtInLinterRule_UnusedUsing,
-      severity: "warning",
-      description: "Linter rules for unused using statement.",
-      messages: {
-        default: paramMessage`'using ${"code"}' is declared but never be used.`,
-      },
-      create(context) {
-        return {
-          root: (_root) => {
-            const getUsingName = (node: MemberExpressionNode | IdentifierNode): string => {
-              if (node.kind === SyntaxKind.MemberExpression) {
-                return `${getUsingName(node.base)}${node.selector}${node.id.sv}`;
-              } else {
-                // identifier node
-                return node.sv;
-              }
-            };
-            nameResolver.getUnusedUsings().forEach((target) => {
-              context.reportDiagnostic({
-                messageId: "default",
-                format: { code: getUsingName(target.name) },
-                target,
-                codefixes: [removeUnusedCodeCodeFix(target)],
-              });
-            });
-          },
-        };
-      },
-    });
-  }
 }

packages/compiler/src/core/name-resolver.ts

@@ -126,6 +126,12 @@ export interface NameResolver {
   /** Return augment decorator nodes that are bound to this symbol */
   getAugmentDecoratorsForSym(symbol: Sym): AugmentDecoratorStatementNode[];
 
+  /** Return template parameters which are not used. */
+  getUnusedTemplateParameterDeclarationNodes(): Set<TemplateParameterDeclarationNode>;
+
+  /** Set unused template parameter */
+  setUnusedTemplateParameterDeclarationNode(node: TemplateParameterDeclarationNode): void;
+
   /**
    * Resolve the member expression using the given symbol as base.
    * This can be used to follow the name resolution for template instance which are not statically linked.
@@ -190,6 +196,11 @@ export function createResolver(program: Program): NameResolver {
   const nullSym = createSymbol(undefined, "null", SymbolFlags.None);
   const augmentDecoratorsForSym = new Map<Sym, AugmentDecoratorStatementNode[]>();
 
+  /**
+   * Tracking the template parameters that are not used.
+   */
+  const unusedTemplateParameterDeclarationNodes = new Set<TemplateParameterDeclarationNode>();
+
   return {
     symbols: { global: globalNamespaceSym, null: nullSym },
     resolveProgram() {
@@ -233,6 +244,8 @@ export function createResolver(program: Program): NameResolver {
 
     getAugmentDecoratorsForSym,
     getUnusedUsings,
+    getUnusedTemplateParameterDeclarationNodes,
+    setUnusedTemplateParameterDeclarationNode,
   };
 
   function getUnusedUsings(): UsingStatementNode[] {
@@ -268,6 +281,14 @@ export function createResolver(program: Program): NameResolver {
     return mergedSymbols.get(sym) || sym;
   }
 
+  function setUnusedTemplateParameterDeclarationNode(node: TemplateParameterDeclarationNode): void {
+    if (!node) return;
+    unusedTemplateParameterDeclarationNodes.add(node);
+  }
+
+  function getUnusedTemplateParameterDeclarationNodes(): Set<TemplateParameterDeclarationNode> {
+    return unusedTemplateParameterDeclarationNodes;
+  }
   /**
    * @internal
    */

packages/compiler/src/server/compile-service.ts

@@ -19,7 +19,9 @@ import {
   joinPaths,
   parse,
 } from "../core/index.js";
-import { builtInLinterLibraryName, builtInLinterRule_UnusedUsing } from "../core/linter.js";
+import { builtInLinterRule_UnusedTemplateParameter } from "../core/linter-rules/unused-template-parameter.rule.js";
+import { builtInLinterRule_UnusedUsing } from "../core/linter-rules/unused-using.rule.js";
+import { builtInLinterLibraryName } from "../core/linter.js";
 import { compile as compileProgram } from "../core/program.js";
 import { doIO, loadFile, resolveTspMain } from "../utils/misc.js";
 import { serverOptions } from "./constants.js";
@@ -119,6 +121,17 @@ export function createCompileService({
       options.linterRuleSet.enable[unusedUsingRule] = true;
     }
 
+    // add linter rule for unused template parameter if user didn't configure it explicitly
+    const unusedTemplateParameterRule = `${builtInLinterLibraryName}/${builtInLinterRule_UnusedTemplateParameter}`;
+    if (
+      options.linterRuleSet?.enable?.[unusedTemplateParameterRule] === undefined &&
+      options.linterRuleSet?.disable?.[unusedTemplateParameterRule] === undefined
+    ) {
+      options.linterRuleSet ??= {};
+      options.linterRuleSet.enable ??= {};
+      options.linterRuleSet.enable[unusedTemplateParameterRule] = true;
+    }
+
     log({ level: "debug", message: `compiler options resolved`, detail: options });
 
     if (!fileService.upToDate(document)) {