[TCGC] Add operation-not-in-client diagnostic for missing operations in @client definitions (#4273)

When `@client` is used to customize client structure, new operations
added to the service namespace can be silently omitted if the client
customization isn't updated. This adds a warning diagnostic to catch
that.

### Changes

- **New diagnostic `operation-not-in-client`** in `lib.ts` — warns on
service operations not covered by any `@client` definition
- **Validation in `prepareClientAndOperationCache`** (`cache.ts`) —
after building the client→operation mapping, walks all service
namespaces to find uncovered operations. Follows `sourceOperation`
chains so `op foo is Service.foo` patterns are recognized as coverage.
- **6 test cases** covering: no `@client` (no-op), full coverage,
missing ops at namespace/nested-namespace/interface level, and direct
`@client` on service namespace

### Behavior

Only fires when explicit `@client` decorators exist. Skips template
declarations, out-of-scope operations, and `omitOperation` targets.
Reports on the original service operation.

```typespec
@service
namespace MyService {
  op opA(): void;
  op opB(): void; // ⚠️ warning: not included in any @client definition
}

// client.tsp
@client({service: MyService, name: "MyServiceClient"})
namespace MyCustomClient {
  op customOpA is MyService.opA;
  // forgot opB
}
```

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: tadelesh <1726438+tadelesh@users.noreply.github.com>
Co-authored-by: Chenjie Shi <tadelesh.shi@live.cn>

Author: Copilot

.chronus/changes/tcgc-operation-not-in-client-2026-04-16-06-30-00.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+Add `operation-not-in-client` diagnostic to warn when service operations are not included in any `@client` definition.

packages/typespec-client-generator-core/src/cache.ts

@@ -1,5 +1,6 @@
 import {
   Enum,
+  getNamespaceFullName,
   Interface,
   isService,
   isTemplateDeclaration,
@@ -124,6 +125,25 @@ export function prepareClientAndOperationCache(context: TCGCContext): void {
     queue.push(...client.subClients);
   }
 
+  // Check that all service operations are included in client hierarchy when explicit @client is used
+  if (context.__explicitClients!.size > 0) {
+    // Collect all service operations that are covered by client operations
+    // (including through sourceOperation chain)
+    const coveredServiceOps = new Set<Operation>();
+    for (const clientOp of context.__operationToClientCache!.keys()) {
+      let current: Operation | undefined = clientOp;
+      while (current) {
+        coveredServiceOps.add(current);
+        current = current.sourceOperation;
+      }
+    }
+
+    // For each service namespace, check all operations are covered
+    for (const service of servicesNs) {
+      checkUncoveredOperations(context, service, coveredServiceOps);
+    }
+  }
+
   // omit empty clients
   const needKeep = (client: SdkClient): boolean => {
     if (context.__explicitClients!.has(client) && !client.autoMergeService) return true;
@@ -604,6 +624,51 @@ function createSubClient(
   return subClient;
 }
 
+/**
+ * Check for service operations that are not included in any @client definition.
+ * Recursively walks the namespace and its children to find uncovered operations.
+ */
+function checkUncoveredOperations(
+  context: TCGCContext,
+  ns: Namespace,
+  coveredOps: Set<Operation>,
+): void {
+  for (const op of ns.operations.values()) {
+    if (isTemplateDeclarationOrInstance(op) || !isInScope(context, op)) continue;
+    if (context.program.stateMap(omitOperation).get(op)) continue;
+    if (!coveredOps.has(op)) {
+      reportDiagnostic(context.program, {
+        code: "operation-not-in-client",
+        format: {
+          operationName: op.name,
+          namespaceName: getNamespaceFullName(ns),
+        },
+        target: op,
+      });
+    }
+  }
+  for (const childNs of ns.namespaces.values()) {
+    checkUncoveredOperations(context, childNs, coveredOps);
+  }
+  for (const iface of ns.interfaces.values()) {
+    if (isTemplateDeclaration(iface)) continue;
+    for (const op of iface.operations.values()) {
+      if (isTemplateDeclarationOrInstance(op) || !isInScope(context, op)) continue;
+      if (context.program.stateMap(omitOperation).get(op)) continue;
+      if (!coveredOps.has(op)) {
+        reportDiagnostic(context.program, {
+          code: "operation-not-in-client",
+          format: {
+            operationName: op.name,
+            namespaceName: getNamespaceFullName(iface.namespace ?? ns),
+          },
+          target: op,
+        });
+      }
+    }
+  }
+}
+
 function isArm(service: Namespace[] | Namespace): boolean {
   if (Array.isArray(service)) {
     return service.some((s) => isArm(s));

packages/typespec-client-generator-core/src/lib.ts

@@ -544,6 +544,12 @@ export const $lib = createTypeSpecLibrary({
         default: "Auto-merging service client must be empty.",
       },
     },
+    "operation-not-in-client": {
+      severity: "warning",
+      messages: {
+        default: paramMessage`Operation "${"operationName"}" under namespace "${"namespaceName"}" is not included in any @client definition.`,
+      },
+    },
   },
   emitter: {
     options: TCGCEmitterOptionsSchema,

packages/typespec-client-generator-core/test/clients/structure.test.ts

@@ -3102,3 +3102,158 @@ it("validation: @clientLocation string target with multiple separate root client
     },
   ]);
 });
+
+it("validation: no diagnostic when no @client is used", async () => {
+  const { program } = await SimpleTester.compile(`
+    @service
+    namespace MyService {
+      @route("/a")
+      op opA(): void;
+
+      @route("/b")
+      interface SubOps {
+        op opB(): void;
+      }
+    }
+  `);
+  await createSdkContextForTester(program);
+  const operationNotInClient = program.diagnostics.filter(
+    (d) => d.code === "@azure-tools/typespec-client-generator-core/operation-not-in-client",
+  );
+  strictEqual(operationNotInClient.length, 0);
+});
+
+it("validation: no diagnostic when all operations are covered by @client", async () => {
+  const { program } = await SimpleBaseTester.compile(
+    createClientCustomizationInput(
+      `
+      @service
+      namespace MyService {
+        @route("/a")
+        op opA(): void;
+      }
+    `,
+      `
+      @client({service: MyService, name: "MyServiceClient"})
+      namespace MyCustomClient {
+        op customOpA is MyService.opA;
+      }
+    `,
+    ),
+  );
+  await createSdkContextForTester(program);
+  const operationNotInClient = program.diagnostics.filter(
+    (d) => d.code === "@azure-tools/typespec-client-generator-core/operation-not-in-client",
+  );
+  strictEqual(operationNotInClient.length, 0);
+});
+
+it("validation: diagnostic when operation is missing from @client definition", async () => {
+  const { program } = await SimpleBaseTester.compile(
+    createClientCustomizationInput(
+      `
+      @service
+      namespace MyService {
+        @route("/a")
+        op opA(): void;
+
+        @route("/b")
+        op opB(): void;
+      }
+    `,
+      `
+      @client({service: MyService, name: "MyServiceClient"})
+      namespace MyCustomClient {
+        op customOpA is MyService.opA;
+      }
+    `,
+    ),
+  );
+  await createSdkContextForTester(program);
+  expectDiagnostics(program.diagnostics, [
+    {
+      code: "@azure-tools/typespec-client-generator-core/operation-not-in-client",
+      message: `Operation "opB" under namespace "MyService" is not included in any @client definition.`,
+    },
+  ]);
+});
+
+it("validation: diagnostic for operations in nested namespace not covered by @client", async () => {
+  const { program } = await SimpleBaseTester.compile(
+    createClientCustomizationInput(
+      `
+      @service
+      namespace MyService {
+        @route("/a")
+        op opA(): void;
+
+        namespace SubGroup {
+          @route("/b")
+          op opB(): void;
+        }
+      }
+    `,
+      `
+      @client({service: MyService, name: "MyServiceClient"})
+      namespace MyCustomClient {
+        op customOpA is MyService.opA;
+      }
+    `,
+    ),
+  );
+  await createSdkContextForTester(program);
+  expectDiagnostics(program.diagnostics, [
+    {
+      code: "@azure-tools/typespec-client-generator-core/operation-not-in-client",
+      message: `Operation "opB" under namespace "MyService.SubGroup" is not included in any @client definition.`,
+    },
+  ]);
+});
+
+it("validation: diagnostic for operations in interface not covered by @client", async () => {
+  const { program } = await SimpleBaseTester.compile(
+    createClientCustomizationInput(
+      `
+      @service
+      namespace MyService {
+        @route("/a")
+        op opA(): void;
+
+        interface SubOps {
+          @route("/b")
+          op opB(): void;
+        }
+      }
+    `,
+      `
+      @client({service: MyService, name: "MyServiceClient"})
+      namespace MyCustomClient {
+        op customOpA is MyService.opA;
+      }
+    `,
+    ),
+  );
+  await createSdkContextForTester(program);
+  expectDiagnostics(program.diagnostics, [
+    {
+      code: "@azure-tools/typespec-client-generator-core/operation-not-in-client",
+      message: `Operation "opB" under namespace "MyService" is not included in any @client definition.`,
+    },
+  ]);
+});
+
+it("validation: no diagnostic when @client is applied directly to service namespace", async () => {
+  const { program } = await SimpleTester.compile(`
+    @client({service: MyService})
+    @service
+    namespace MyService {
+      @route("/a")
+      op opA(): void;
+    }
+  `);
+  await createSdkContextForTester(program);
+  const operationNotInClient = program.diagnostics.filter(
+    (d) => d.code === "@azure-tools/typespec-client-generator-core/operation-not-in-client",
+  );
+  strictEqual(operationNotInClient.length, 0);
+});