[tcgc] add functions to help with override story

.chronus/changes/tcgc-addReplaceDecorator-2026-2-2-16-3-32.md

@@ -0,0 +1,13 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+Add experimental extern functions for operation transformations:
+- `replaceParameter`: Replace a parameter in an operation
+- `removeParameter`: Remove a parameter from an operation
+- `addParameter`: Add a new parameter to an operation
+- `reorderParameters`: Reorder parameters of an operation according to a specified order
+
+These functions enable composable transformations that work with `@@override` to customize method signatures in client SDKs.

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

@@ -3,6 +3,7 @@ import type {
   DecoratorValidatorCallbacks,
   Enum,
   EnumMember,
+  FunctionContext,
   Interface,
   Model,
   ModelProperty,
@@ -1128,3 +1129,130 @@ export type AzureClientGeneratorCoreDecorators = {
   clientDoc: ClientDocDecorator;
   clientOption: ClientOptionDecorator;
 };
+
+/**
+ * Replace a parameter in an operation with a new parameter definition.
+ * This function creates a new operation with the specified parameter replaced,
+ * enabling composable transformations without mutating the original operation.
+ *
+ * @param operation The operation to transform.
+ * @param selector The parameter to replace, specified either by name (string) or by direct reference (ModelProperty).
+ * @param replacement The replacement parameter.
+ * @returns A new operation with the parameter replaced.
+ * @example Making an optional parameter required
+ * ```typespec
+ * model RequiredMaxResults {
+ *   maxResults: int32;
+ * }
+ *
+ * @@override(KeyVault.getSecrets, replaceParameter(KeyVault.getSecrets, "maxResults", RequiredMaxResults.maxResults));
+ * ```
+ * @example Chaining transformations
+ * ```typespec
+ * alias Step1 = replaceParameter(MyService.myOp, "oldParam", NewParams.newParam);
+ * @@override(MyService.myOp, replaceParameter(Step1, "anotherParam", NewParams.anotherParam));
+ * ```
+ */
+export type ReplaceParameterFunctionImplementation = (
+  context: FunctionContext,
+  operation: Operation,
+  selector: string | unknown,
+  replacement: ModelProperty,
+) => Operation;
+
+/**
+ * Remove a parameter from an operation.
+ * This function creates a new operation with the specified parameter removed,
+ * enabling composable transformations without mutating the original operation.
+ *
+ * Note: When used with `@@override`, only optional parameters can be removed. Attempting to
+ * remove a required parameter will result in an `override-parameters-mismatch` error.
+ *
+ * @param operation The operation to transform.
+ * @param selector The parameter to remove, specified either by name (string) or by direct reference (ModelProperty).
+ * @returns A new operation with the parameter removed.
+ * @example Removing an optional parameter
+ * ```typespec
+ * @@override(KeyVault.getSecrets, removeParameter(KeyVault.getSecrets, "maxResults"));
+ * ```
+ * @example Chaining with other transformations
+ * ```typespec
+ * alias Step1 = removeParameter(MyService.myOp, "unwantedParam");
+ * @@override(MyService.myOp, addParameter(Step1, NewParams.newParam));
+ * ```
+ */
+export type RemoveParameterFunctionImplementation = (
+  context: FunctionContext,
+  operation: Operation,
+  selector: string | unknown,
+) => Operation;
+
+/**
+ * Add a new parameter to an operation.
+ * This function creates a new operation with the additional parameter appended,
+ * enabling composable transformations without mutating the original operation.
+ *
+ * @param operation The operation to transform.
+ * @param parameter The parameter to add to the operation.
+ * @returns A new operation with the parameter added.
+ * @example Adding a required parameter
+ * ```typespec
+ * model ExtraParams {
+ *   @header tracingId: string;
+ * }
+ *
+ * @@override(MyService.myOp, addParameter(MyService.myOp, ExtraParams.tracingId));
+ * ```
+ * @example Chaining with replaceParameter
+ * ```typespec
+ * model NewParams {
+ *   oldParam: string;  // make required
+ *   newParam: int32;
+ * }
+ *
+ * alias Step1 = replaceParameter(MyService.myOp, "oldParam", NewParams.oldParam);
+ * @@override(MyService.myOp, addParameter(Step1, NewParams.newParam));
+ * ```
+ */
+export type AddParameterFunctionImplementation = (
+  context: FunctionContext,
+  operation: Operation,
+  parameter: ModelProperty,
+) => Operation;
+
+/**
+ * Reorder parameters of an operation according to the specified order.
+ * This function creates a new operation with parameters reordered as specified,
+ * enabling control over the parameter order in generated client SDK methods.
+ *
+ * @param operation The operation to transform.
+ * @param order An array of parameter names specifying the desired order. All parameters must be included.
+ * @returns A new operation with parameters reordered.
+ * @example Reordering parameters
+ * ```typespec
+ * @service
+ * namespace MyService;
+ *
+ * op myOp(a: string, b: string, c: string): void;
+ *
+ * // Reorder to put 'c' first, then 'a', then 'b'
+ * @@override(MyService.myOp, reorderParameters(MyService.myOp, #["c", "a", "b"]));
+ * ```
+ * @example Chaining with other transformations
+ * ```typespec
+ * alias Step1 = addParameter(MyService.myOp, NewParams.newParam);
+ * @@override(MyService.myOp, reorderParameters(Step1, #["newParam", "existingParam"]));
+ * ```
+ */
+export type ReorderParametersFunctionImplementation = (
+  context: FunctionContext,
+  operation: Operation,
+  order: readonly string[],
+) => Operation;
+
+export type AzureClientGeneratorCoreFunctions = {
+  replaceParameter: ReplaceParameterFunctionImplementation;
+  removeParameter: RemoveParameterFunctionImplementation;
+  addParameter: AddParameterFunctionImplementation;
+  reorderParameters: ReorderParametersFunctionImplementation;
+};

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

@@ -1,10 +1,18 @@
 // An error in the imports would mean that the decorator is not exported or
 // doesn't have the right name.
 
-import { $decorators } from "@azure-tools/typespec-client-generator-core";
-import type { AzureClientGeneratorCoreDecorators } from "./Azure.ClientGenerator.Core.js";
+import { $decorators, $functions } from "@azure-tools/typespec-client-generator-core";
+import type {
+  AzureClientGeneratorCoreDecorators,
+  AzureClientGeneratorCoreFunctions,
+} from "./Azure.ClientGenerator.Core.js";
 
 /**
  * An error here would mean that the exported decorator is not using the same signature. Make sure to have export const $decName: DecNameDecorator = (...) => ...
  */
 const _decs: AzureClientGeneratorCoreDecorators = $decorators["Azure.ClientGenerator.Core"];
+
+/**
+ * An error here would mean that the exported function is not using the same signature. Make sure to have export const $funcName: FuncNameFunction = (...) => ...
+ */
+const _funcs: AzureClientGeneratorCoreFunctions = $functions["Azure.ClientGenerator.Core"];

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

@@ -0,0 +1,131 @@
+using Reflection;
+
+namespace Azure.ClientGenerator.Core;
+
+/**
+ * Replace a parameter in an operation with a new parameter definition.
+ * This function creates a new operation with the specified parameter replaced,
+ * enabling composable transformations without mutating the original operation.
+ *
+ * @param operation The operation to transform.
+ * @param selector The parameter to replace, specified either by name (string) or by direct reference (ModelProperty).
+ * @param replacement The replacement parameter.
+ * @returns A new operation with the parameter replaced.
+ *
+ * @example Making an optional parameter required
+ * ```typespec
+ * model RequiredMaxResults {
+ *   maxResults: int32;
+ * }
+ *
+ * @@override(KeyVault.getSecrets, replaceParameter(KeyVault.getSecrets, "maxResults", RequiredMaxResults.maxResults));
+ * ```
+ *
+ * @example Chaining transformations
+ * ```typespec
+ * alias Step1 = replaceParameter(MyService.myOp, "oldParam", NewParams.newParam);
+ * @@override(MyService.myOp, replaceParameter(Step1, "anotherParam", NewParams.anotherParam));
+ * ```
+ */
+#suppress "experimental-feature" "replaceParameter uses extern fn which is experimental but provides essential parameter transformation functionality"
+extern fn replaceParameter(
+  operation: Reflection.Operation,
+  selector: valueof string | Reflection.ModelProperty,
+  replacement: Reflection.ModelProperty
+): Reflection.Operation;
+
+/**
+ * Remove a parameter from an operation.
+ * This function creates a new operation with the specified parameter removed,
+ * enabling composable transformations without mutating the original operation.
+ *
+ * Note: When used with `@@override`, only optional parameters can be removed. Attempting to
+ * remove a required parameter will result in an `override-parameters-mismatch` error.
+ *
+ * @param operation The operation to transform.
+ * @param selector The parameter to remove, specified either by name (string) or by direct reference (ModelProperty).
+ * @returns A new operation with the parameter removed.
+ *
+ * @example Removing an optional parameter
+ * ```typespec
+ * @@override(KeyVault.getSecrets, removeParameter(KeyVault.getSecrets, "maxResults"));
+ * ```
+ *
+ * @example Chaining with other transformations
+ * ```typespec
+ * alias Step1 = removeParameter(MyService.myOp, "unwantedParam");
+ * @@override(MyService.myOp, addParameter(Step1, NewParams.newParam));
+ * ```
+ */
+#suppress "experimental-feature" "removeParameter uses extern fn which is experimental but provides essential parameter transformation functionality"
+extern fn removeParameter(
+  operation: Reflection.Operation,
+  selector: valueof string | Reflection.ModelProperty
+): Reflection.Operation;
+
+/**
+ * Add a new parameter to an operation.
+ * This function creates a new operation with the additional parameter appended,
+ * enabling composable transformations without mutating the original operation.
+ *
+ * @param operation The operation to transform.
+ * @param parameter The parameter to add to the operation.
+ * @returns A new operation with the parameter added.
+ *
+ * @example Adding a required parameter
+ * ```typespec
+ * model ExtraParams {
+ *   @header tracingId: string;
+ * }
+ *
+ * @@override(MyService.myOp, addParameter(MyService.myOp, ExtraParams.tracingId));
+ * ```
+ *
+ * @example Chaining with replaceParameter
+ * ```typespec
+ * model NewParams {
+ *   oldParam: string;  // make required
+ *   newParam: int32;
+ * }
+ *
+ * alias Step1 = replaceParameter(MyService.myOp, "oldParam", NewParams.oldParam);
+ * @@override(MyService.myOp, addParameter(Step1, NewParams.newParam));
+ * ```
+ */
+#suppress "experimental-feature" "addParameter uses extern fn which is experimental but provides essential parameter transformation functionality"
+extern fn addParameter(
+  operation: Reflection.Operation,
+  parameter: Reflection.ModelProperty
+): Reflection.Operation;
+
+/**
+ * Reorder parameters of an operation according to the specified order.
+ * This function creates a new operation with parameters reordered as specified,
+ * enabling control over the parameter order in generated client SDK methods.
+ *
+ * @param operation The operation to transform.
+ * @param order An array of parameter names specifying the desired order. All parameters must be included.
+ * @returns A new operation with parameters reordered.
+ *
+ * @example Reordering parameters
+ * ```typespec
+ * @service
+ * namespace MyService;
+ *
+ * op myOp(a: string, b: string, c: string): void;
+ *
+ * // Reorder to put 'c' first, then 'a', then 'b'
+ * @@override(MyService.myOp, reorderParameters(MyService.myOp, #["c", "a", "b"]));
+ * ```
+ *
+ * @example Chaining with other transformations
+ * ```typespec
+ * alias Step1 = addParameter(MyService.myOp, NewParams.newParam);
+ * @@override(MyService.myOp, reorderParameters(Step1, #["newParam", "existingParam"]));
+ * ```
+ */
+#suppress "experimental-feature" "reorderParameters uses extern fn which is experimental but provides essential parameter transformation functionality"
+extern fn reorderParameters(
+  operation: Reflection.Operation,
+  order: valueof string[]
+): Reflection.Operation;

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

@@ -1,4 +1,5 @@
 import "./decorators.tsp";
+import "./functions.tsp";
 import "./augmentCore.tsp";
 import "./legacy.tsp";
 import "../dist/src/tsp-index.js";