Implement scope negation for TCGC

.chronus/changes/scope-negation-2024-10-1-10-19-14.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+Implement scope negation for TCGC decorators

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

@@ -6,6 +6,7 @@ namespace Azure.ClientGenerator.Core;
  * Changes the name of a method, parameter, property, or model generated in the client SDK
  * @param rename The rename you want applied to the object
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example
  * ```typespec
@@ -28,6 +29,7 @@ extern dec clientName(target: unknown, rename: valueof string, scope?: valueof s
  * Whether you want to generate an operation as a convenient operation.
  * @param value Whether to generate the operation as convenience method or not.
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example
  * ```typespec
@@ -41,6 +43,7 @@ extern dec convenientAPI(target: Operation, value?: valueof boolean, scope?: val
  * Whether you want to generate an operation as a protocol operation.
  * @param value Whether to generate the operation as protocol or not.
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example
  * ```typespec
@@ -54,6 +57,7 @@ extern dec protocolAPI(target: Operation, value?: valueof boolean, scope?: value
  * Create a ClientGenerator.Core client out of a namespace or interface
  * @param value Optional configuration for the service.
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example Basic client setting
  * ```typespec
@@ -82,6 +86,7 @@ extern dec client(target: Namespace | Interface, value?: Model, scope?: valueof
 /**
  * Create a ClientGenerator.Core operation group out of a namespace or interface
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example
  * ```typespec
@@ -124,6 +129,7 @@ enum Usage {
  * otherwise a warning will be added to diagnostics list.
  * @param value The usage info you want to set for this model.
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example Expand usage for model
  * ```typespec
@@ -210,6 +216,7 @@ enum Access {
  * otherwise a warning will be added to diagnostics list.
  * @param value The access info you want to set for this model or operation.
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example Set access
  * ```typespec
@@ -344,6 +351,7 @@ extern dec access(
 /**
  * Set whether a model property should be flattened or not.
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example
  * ```typespec
@@ -363,6 +371,7 @@ extern dec flattenProperty(target: ModelProperty, scope?: valueof string);
  * @param original: The original service definition
  * @param override: The override method definition that specifies the exact client method you want
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example
  * ```typespec
@@ -409,6 +418,7 @@ extern dec override(original: Operation, override: Operation, scope?: valueof st
 /**
  * Whether a model needs the custom JSON converter, this is only used for backward compatibility for csharp.
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example
  * ```typespec
@@ -423,6 +433,7 @@ extern dec useSystemTextJsonConverter(target: Model, scope?: valueof string);
 /**
  * Client parameters you would like to add to the client. By default, we apply endpoint, credential, and api-version parameters. If you add clientInitialization, we will append those to the default list of parameters.
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example
  * ```typespec
@@ -452,6 +463,7 @@ extern dec clientInitialization(
 /**
  * Alias the name of a client parameter to a different name. This permits you to have a different name for the parameter in client initialization then on individual methods and still refer to the same parameter.
  * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python". Please note that, negation scope and normal scope should not be mixed.
  *
  * @example
  * ```typespec

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

@@ -63,6 +63,7 @@ import {
   clientNameKey,
   getValidApiVersion,
   isAzureCoreTspModel,
+  negationScopesKey,
   parseEmitterName,
 } from "./internal-utils.js";
 import { createStateSymbol, reportDiagnostic } from "./lib.js";
@@ -86,6 +87,13 @@ function getScopedDecoratorData(
   if (languageScope === undefined || typeof languageScope === "string") {
     const scope = languageScope ?? context.emitterName;
     if (Object.keys(retval).includes(scope)) return retval[scope];
+
+    // if the scope is negated, we should return undefined
+    // if the scope is not negated, we should return the value for AllScopes
+    const negationScopes = retval[negationScopesKey];
+    if (negationScopes !== undefined && negationScopes.includes(scope)) {
+      return undefined;
+    }
   }
   return retval[AllScopes]; // in this case it applies to all languages
 }
@@ -113,20 +121,61 @@ function setScopedDecoratorData(
     return;
   }
 
-  // if scope specified, create or overwrite with the new value
-  const splitScopes = scope.split(",").map((s) => s.trim());
-  const targetEntry = context.program.stateMap(key).get(target);
-
-  // if target doesn't exist in decorator map, create a new entry
-  if (!targetEntry) {
-    const newObject = Object.fromEntries(splitScopes.map((scope) => [scope, value]));
+  const [negationScopes, scopes] = parseScopes(context, scope);
+  if (negationScopes !== undefined && negationScopes.length > 0) {
+    const newObject = Object.fromEntries([AllScopes].map((scope) => [scope, value]));
+    newObject[negationScopesKey] = negationScopes;
     context.program.stateMap(key).set(target, newObject);
     return;
+  } else if (scopes !== undefined && scopes.length > 0) {
+    // if scope specified, create or overwrite with the new value
+    const targetEntry = context.program.stateMap(key).get(target);
+    const newObject = Object.fromEntries(scopes.map((scope) => [scope, value]));
+
+    // if target doesn't exist in decorator map, create a new entry
+    // otherwise, overwrite existed value
+    context.program
+      .stateMap(key)
+      .set(target, !targetEntry ? newObject : { ...targetEntry, ...newObject });
+  }
+}
+
+// This function is used to parse the scopes from the decorator and return the negation scopes and normal scopes
+// When the scope is !(scope1, scope2,...), it will return [negationScopes, undefined]
+// When the scope is !scope1, !scope2, ..., it will return [negationScopes, undefined]
+// When the scope is !scope1, scope2, ..., it will report error of invalid-negation-scope
+// When the scope is scope1, scope2, ..., it will return [undefined, normalScopes]
+function parseScopes(context: DecoratorContext, scope?: LanguageScopes): [string[]?, string[]?] {
+  if (scope === undefined) {
+    return [undefined, undefined];
+  }
+
+  // handle !(scope1, scope2,...) syntax
+  const negationScopeRegex = new RegExp(/!\((.*?)\)/);
+  const negationScopeMatch = scope.match(negationScopeRegex);
+  if (negationScopeMatch) {
+    return [negationScopeMatch[1].split(",").map((s) => s.trim()), undefined];
   }
 
-  // if target exists, overwrite existed value
-  const newObject = Object.fromEntries(splitScopes.map((scope) => [scope, value]));
-  context.program.stateMap(key).set(target, { ...targetEntry, ...newObject });
+  // handle !scope1, !scope2, ... syntax and throw on the combination of negation and normal scopes
+  const splitScopes = scope.split(",").map((s) => s.trim());
+  const negationScopes = [];
+  const scopes = [];
+  for (const s of splitScopes) {
+    if (s.startsWith("!")) {
+      negationScopes.push(s.slice(1));
+    } else {
+      scopes.push(s);
+    }
+  }
+  if (negationScopes.length > 0 && scopes.length > 0) {
+    reportDiagnostic(context.program, {
+      code: "invalid-negation-scope",
+      target: context.decoratorTarget,
+    });
+    return [undefined, undefined];
+  }
+  return [negationScopes, scopes];
 }
 
 const clientKey = createStateSymbol("client");

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

@@ -51,6 +51,8 @@ export const AllScopes = Symbol.for("@azure-core/typespec-client-generator-core/
 
 export const clientNameKey = createStateSymbol("clientName");
 
+export const negationScopesKey = "negationScopes";
+
 /**
  *
  * @param emitterName Full emitter name

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

@@ -216,6 +216,12 @@ export const $lib = createTypeSpecLibrary({
         default: paramMessage`Decorator ${"decoratorName"} cannot be used twice on the same declaration with same scope.`,
       },
     },
+    "invalid-negation-scope": {
+      severity: "error",
+      messages: {
+        default: `Negation scope should not be combined with normal scope.`,
+      },
+    },
   },
 });
 

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

@@ -18,7 +18,7 @@ import {
 import { DuplicateTracker } from "@typespec/compiler/utils";
 import { createTCGCContext, getClientNameOverride } from "./decorators.js";
 import { TCGCContext } from "./interfaces.js";
-import { AllScopes, clientNameKey } from "./internal-utils.js";
+import { AllScopes, clientNameKey, negationScopesKey } from "./internal-utils.js";
 import { reportDiagnostic } from "./lib.js";
 
 export function $onValidate(program: Program) {
@@ -36,7 +36,9 @@ function getDefinedLanguageScopes(program: Program): Set<string | typeof AllScop
       languageScopes.add(AllScopes);
     }
     for (const languageScope of Object.keys(value)) {
-      languageScopes.add(languageScope);
+      if (languageScope !== negationScopesKey) {
+        languageScopes.add(languageScope);
+      }
     }
   }
   return languageScopes;