[tcgc] add @clientOption decorator

.chronus/changes/tcgc-clientOptions-2026-0-22-16-26-53.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+Add `@clientOption` flag for experimental, language-specific flags

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

@@ -944,6 +944,36 @@ export type ClientDocDecorator = (
   scope?: string,
 ) => DecoratorValidatorCallbacks | void;
 
+/**
+ * Pass experimental flags or options to emitters without requiring TCGC reshipping.
+ * This decorator is intended for temporary workarounds or experimental features and requires
+ * suppression to acknowledge its experimental nature.
+ *
+ * **Warning**: This decorator always emits a warning that must be suppressed, and an additional
+ * warning if no scope is provided (since options are typically language-specific).
+ *
+ * @param target The type you want to apply the option to.
+ * @param name The name of the option (e.g., "enableFeatureFoo").
+ * @param value The value of the option. Can be any type; emitters will cast as needed.
+ * @param scope Specifies the target language emitters that the decorator should apply. If not set, the decorator will be applied to all language emitters by default.
+ * You can use "!" to exclude specific languages, for example: !(java, python) or !java, !python.
+ * @example Apply an experimental option for Python
+ * ```typespec
+ * #suppress "@azure-tools/typespec-client-generator-core/client-option"
+ * @clientOption("enableFeatureFoo", true, "python")
+ * model MyModel {
+ *   prop: string;
+ * }
+ * ```
+ */
+export type ClientOptionDecorator = (
+  context: DecoratorContext,
+  target: Type,
+  name: string,
+  value: Type,
+  scope?: string,
+) => DecoratorValidatorCallbacks | void;
+
 export type AzureClientGeneratorCoreDecorators = {
   clientName: ClientNameDecorator;
   convenientAPI: ConvenientAPIDecorator;
@@ -965,4 +995,5 @@ export type AzureClientGeneratorCoreDecorators = {
   responseAsBool: ResponseAsBoolDecorator;
   clientLocation: ClientLocationDecorator;
   clientDoc: ClientDocDecorator;
+  clientOption: ClientOptionDecorator;
 };

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

@@ -1022,3 +1022,28 @@ extern dec clientDoc(
   mode: EnumMember,
   scope?: valueof string
 );
+
+/**
+ * Pass experimental flags or options to emitters without requiring TCGC reshipping.
+ * This decorator is intended for temporary workarounds or experimental features and requires
+ * suppression to acknowledge its experimental nature.
+ *
+ * **Warning**: This decorator always emits a warning that must be suppressed, and an additional
+ * warning if no scope is provided (since options are typically language-specific).
+ *
+ * @param target The type you want to apply the option to.
+ * @param name The name of the option (e.g., "enableFeatureFoo").
+ * @param value The value of the option. Can be any type; emitters will cast as needed.
+ * @param scope Specifies the target language emitters that the decorator should apply. If not set, the decorator will be applied to all language emitters by default.
+ * You can use "!" to exclude specific languages, for example: !(java, python) or !java, !python.
+ *
+ * @example Apply an experimental option for Python
+ * ```typespec
+ * #suppress "@azure-tools/typespec-client-generator-core/client-option"
+ * @clientOption("enableFeatureFoo", true, "python")
+ * model MyModel {
+ *   prop: string;
+ * }
+ * ```
+ */
+extern dec clientOption(target: unknown, name: valueof string, value: unknown, scope?: valueof string);

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

@@ -2,4 +2,5 @@ export const defaultDecoratorsAllowList = [
   "TypeSpec\\.Xml\\..*",
   "Azure\\.Core\\.@useFinalStateVia",
   "Autorest\\.@example",
+  "Azure\\.ClientGenerator\\.Core\\.@clientOption",
 ];

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

@@ -45,6 +45,7 @@ import {
   ClientInitializationDecorator,
   ClientNameDecorator,
   ClientNamespaceDecorator,
+  ClientOptionDecorator,
   ConvenientAPIDecorator,
   DeserializeEmptyStringAsNullDecorator,
   OperationGroupDecorator,
@@ -1851,3 +1852,36 @@ export function isInScope(context: TCGCContext, entity: Operation | ModelPropert
   }
   return true;
 }
+
+export const clientOptionKey = createStateSymbol("ClientOption");
+
+/**
+ * `@clientOption` decorator implementation.
+ * Pass experimental flags or options to emitters without requiring TCGC reshipping.
+ * The decorator data is stored as {name, value} and exposed via the decorators array.
+ */
+export const $clientOption: ClientOptionDecorator = (
+  context: DecoratorContext,
+  target: Type,
+  name: string,
+  value: Type,
+  scope?: LanguageScopes,
+) => {
+  // Always emit warning that this is experimental
+  reportDiagnostic(context.program, {
+    code: "client-option",
+    target: target,
+  });
+
+  // Emit additional warning if scope is not provided
+  if (scope === undefined) {
+    reportDiagnostic(context.program, {
+      code: "client-option-requires-scope",
+      target: target,
+    });
+  }
+
+  // Store the option data - each decorator application is stored separately
+  // The decorator info will be exposed via the decorators array on SDK types
+  setScopedDecoratorData(context, $clientOption, clientOptionKey, target, { name, value }, scope);
+};

packages/typespec-client-generator-core/src/internal-utils.ts

@@ -402,6 +402,14 @@ export function getTypeDecorators(
             getDecoratorArgValue(context, decorator.args[i].jsValue, type, decoratorName),
           );
         }
+
+        // Filter by scope - only include decorators that match the current emitter or have no scope
+        const scopeArg = decoratorInfo.arguments["scope"];
+        if (scopeArg !== undefined && scopeArg !== context.emitterName) {
+          // Skip this decorator if it has a scope that doesn't match the current emitter
+          continue;
+        }
+
         retval.push(decoratorInfo);
       }
     }

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

@@ -482,6 +482,20 @@ export const $lib = createTypeSpecLibrary({
         default: "All services must have the same server and auth definitions.",
       },
     },
+    "client-option": {
+      severity: "warning",
+      messages: {
+        default:
+          "@clientOption is experimental and should only be used for temporary workarounds. This usage must be suppressed.",
+      },
+    },
+    "client-option-requires-scope": {
+      severity: "warning",
+      messages: {
+        default:
+          "@clientOption should be applied with a specific language scope since it is highly likely this is language-specific.",
+      },
+    },
   },
   emitter: {
     options: TCGCEmitterOptionsSchema,

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

@@ -12,6 +12,7 @@ import {
   $clientLocation,
   $clientName,
   $clientNamespace,
+  $clientOption,
   $convenientAPI,
   $deserializeEmptyStringAsNull,
   $flattenProperty,
@@ -55,6 +56,7 @@ export const $decorators = {
     responseAsBool: $responseAsBool,
     clientDoc: $clientDoc,
     clientLocation: $clientLocation,
+    clientOption: $clientOption,
   } satisfies AzureClientGeneratorCoreDecorators,
 
   "Azure.ClientGenerator.Core.Legacy": {