feat(tcgc): support overriding method responses

.chronus/changes/replace-client-response-2026-08-06-10-49-09.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+Allow `@override` to replace a client method response and add the `replaceResponse` customization function.

packages/typespec-client-generator-core/generated-defs/Azure.ClientGenerator.Core.ts

@@ -1259,6 +1259,26 @@ export type ReorderParametersFunctionImplementation = (
   order: readonly string[],
 ) => Operation;
 
+/**
+ * Replace the method response type of an operation.
+ * This preserves the HTTP response metadata and only changes the return type
+ * of the generated client method when used with `@@override`.
+ *
+ * @param operation The operation to transform.
+ * @param response The replacement method response type.
+ * @returns A new operation with the response type replaced.
+ * @example Replace a response with void
+ * ```typespec
+ * alias DeleteResponse = replaceResponse(MyService.delete, void);
+ * @@override(MyService.delete, DeleteResponse);
+ * ```
+ */
+export type ReplaceResponseFunctionImplementation = (
+  context: FunctionContext,
+  operation: Operation,
+  response: Type,
+) => Operation;
+
 /**
  * Mark a client name as exact, preventing language emitters from applying
  * their usual casing transformations (e.g., snake_case for Python, camelCase for JavaScript).
@@ -1286,5 +1306,6 @@ export type AzureClientGeneratorCoreFunctions = {
   removeParameter: RemoveParameterFunctionImplementation;
   addParameter: AddParameterFunctionImplementation;
   reorderParameters: ReorderParametersFunctionImplementation;
+  replaceResponse: ReplaceResponseFunctionImplementation;
   exact: ExactFunctionImplementation;
 };

packages/typespec-client-generator-core/lib/functions.tsp

@@ -130,6 +130,24 @@ extern fn reorderParameters(
   order: valueof string[]
 ): Reflection.Operation;
 
+/**
+ * Replace the method response type of an operation.
+ * This preserves the HTTP response metadata and only changes the return type
+ * of the generated client method when used with `@@override`.
+ *
+ * @param operation The operation to transform.
+ * @param response The replacement method response type.
+ * @returns A new operation with the response type replaced.
+ *
+ * @example Replace a response with void
+ * ```typespec
+ * alias DeleteResponse = replaceResponse(MyService.delete, void);
+ * @@override(MyService.delete, DeleteResponse);
+ * ```
+ */
+#suppress "experimental-feature" "replaceResponse uses extern fn which is experimental but provides essential response transformation functionality"
+extern fn replaceResponse(operation: Reflection.Operation, response: unknown): Reflection.Operation;
+
 /**
  * Mark a client name as exact, preventing language emitters from applying
  * their usual casing transformations (e.g., snake_case for Python, camelCase for JavaScript).

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

@@ -240,6 +240,27 @@ export function reorderParameters(
   return cloneOperation(tk, operation, { parameters: newProperties });
 }
 
+/**
+ * Replace the method response type of an operation.
+ *
+ * The operation's HTTP response metadata is preserved; only the client method
+ * return type is changed when the operation is used with `@override`.
+ *
+ * @param context The function context provided by TypeSpec
+ * @param operation The operation to transform
+ * @param response The replacement method response type
+ * @returns A new operation with the response type replaced
+ */
+export function replaceResponse(
+  context: FunctionContext,
+  operation: Operation,
+  response: Type,
+): Operation {
+  return cloneOperation($(context.program), operation, {
+    returnType: response,
+  });
+}
+
 /**
  * Mark a client name as exact, preventing language emitters from applying
  * their usual casing transformations.
@@ -269,7 +290,10 @@ export function hasExactNameMarker(name: string): boolean {
  * @param name The name to normalize
  * @returns An object with the clean name and whether it was marked as exact
  */
-export function normalizeExactName(name: string): { name: string; isExactName: boolean } {
+export function normalizeExactName(name: string): {
+  name: string;
+  isExactName: boolean;
+} {
   if (name.startsWith(EXACT_NAME_PREFIX)) {
     return { name: name.slice(EXACT_NAME_PREFIX.length), isExactName: true };
   }

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

@@ -167,7 +167,7 @@ function getSdkPagingServiceMethod<TServiceOperation extends SdkServiceOperation
   const diagnostics = createDiagnosticCollector();
 
   const baseServiceMethod = diagnostics.pipe(
-    getSdkBasicServiceMethod<TServiceOperation>(context, operation, client),
+    getSdkBasicServiceMethod<TServiceOperation>(context, operation, client, false),
   );
 
   // If the response body type itself is nullable (e.g., {@body body: Type | null}), unwrap it for paging/LRO processing
@@ -327,7 +327,10 @@ export function getPropertySegmentsFromModelOrParameters(
   source: SdkModelType | SdkMethodParameter[],
   predicate: (property: SdkMethodParameter | SdkModelPropertyType) => boolean,
 ): (SdkMethodParameter | SdkModelPropertyType)[] | undefined {
-  const queue: { model: SdkModelType; path: (SdkMethodParameter | SdkModelPropertyType)[] }[] = [];
+  const queue: {
+    model: SdkModelType;
+    path: (SdkMethodParameter | SdkModelPropertyType)[];
+  }[] = [];
 
   if (!Array.isArray(source)) {
     if (source.baseModel) {
@@ -607,8 +610,12 @@ function getSdkMethodResponse(
   operation: Operation,
   sdkOperation: SdkServiceOperation,
   client: SdkClientType<SdkServiceOperation>,
+  useResponseOverride = true,
 ): SdkMethodResponse {
   const responses = sdkOperation.responses;
+  const responseOverride = useResponseOverride
+    ? getOverriddenClientMethod(context, operation)?.returnType
+    : undefined;
 
   const allResponseBodies: SdkType[] = [];
   let containsResponseWithoutBody = false;
@@ -622,7 +629,11 @@ function getSdkMethodResponse(
 
   const responseTypes = new Set<string>(allResponseBodies.map((x) => getHashForType(x)));
   let type: SdkType | undefined = undefined;
-  if (getResponseAsBool(context, operation)) {
+  if (responseOverride && isNeverOrVoidType(responseOverride)) {
+    type = undefined;
+  } else if (responseOverride) {
+    type = ignoreDiagnostics(getClientTypeWithDiagnostics(context, responseOverride, operation));
+  } else if (getResponseAsBool(context, operation)) {
     type = getSdkBuiltInType(context, $(context.program).builtin.boolean);
   } else {
     if (responseTypes.size > 1) {
@@ -678,6 +689,7 @@ export function getSdkBasicServiceMethod<TServiceOperation extends SdkServiceOpe
   context: TCGCContext,
   operation: Operation,
   client: SdkClientType<TServiceOperation>,
+  useResponseOverride = true,
 ): [SdkServiceMethod<TServiceOperation>, readonly Diagnostic[]] {
   const diagnostics = createDiagnosticCollector();
   const methodParameters: SdkMethodParameter[] = [];
@@ -722,7 +734,13 @@ export function getSdkBasicServiceMethod<TServiceOperation extends SdkServiceOpe
   const serviceOperation = diagnostics.pipe(
     getSdkServiceOperation<TServiceOperation>(context, operation, methodParameters, client),
   );
-  const response = getSdkMethodResponse(context, operation, serviceOperation, client);
+  const response = getSdkMethodResponse(
+    context,
+    operation,
+    serviceOperation,
+    client,
+    useResponseOverride,
+  );
   const name = getLibraryName(context, operation);
   return diagnostics.wrap({
     __raw: operation,
@@ -749,12 +767,13 @@ function getSdkServiceMethod<TServiceOperation extends SdkServiceOperation>(
   operation: Operation,
   client: SdkClientType<TServiceOperation>,
 ): [SdkServiceMethod<TServiceOperation>, readonly Diagnostic[]] {
-  const lro = getTcgcLroMetadata(context, operation, client);
+  const clientOperation = getOverriddenClientMethod(context, operation) ?? operation;
+  const lro = getTcgcLroMetadata(context, clientOperation, client);
   // `@disablePageable` disables paging even for operations with @list
-  const pagingDisabled = getDisablePageable(context, operation);
+  const pagingDisabled = getDisablePageable(context, clientOperation);
   const paging =
     !pagingDisabled &&
-    (isList(context.program, operation) || getMarkAsPageable(context, operation));
+    (isList(context.program, clientOperation) || getMarkAsPageable(context, clientOperation));
   if (lro && paging) {
     return getSdkLroPagingServiceMethod<TServiceOperation>(context, operation, client);
   } else if (paging) {

packages/typespec-client-generator-core/src/tsp-index.ts

@@ -39,6 +39,7 @@ import {
   removeParameter,
   reorderParameters,
   replaceParameter,
+  replaceResponse,
 } from "./functions.js";
 
 export { $lib } from "./lib.js";
@@ -91,6 +92,7 @@ export const $functions: Record<string, AzureClientGeneratorCoreFunctions> = {
     removeParameter: removeParameter as AzureClientGeneratorCoreFunctions["removeParameter"],
     addParameter: addParameter as AzureClientGeneratorCoreFunctions["addParameter"],
     reorderParameters: reorderParameters as AzureClientGeneratorCoreFunctions["reorderParameters"],
+    replaceResponse: replaceResponse as AzureClientGeneratorCoreFunctions["replaceResponse"],
     exact: exact as AzureClientGeneratorCoreFunctions["exact"],
   },
 };