Support get common models for specific api version (#700)

#### Config
1. A new option `api-version` will be added to the TCGC context and
should be configed in languages' `tspconfig.yaml` file.
2. If the `api-version` is not set or set to `latest`, then all returns
of TCGC APIs will be the information of latest API version.
3. If the `api-version` is set to a specific version, then all returns
of TCGC APIs will be the information of that API version. If the version
is not existed, then a diagnostic warning will be passed to emitter and
will fallback to latest version.
5. If the `api-version` is set to `all`, then the returns of TCGC APIs
will be the information of all API versions. Next part will describe how
the versioning infomation is included in TCGC common models.

---------

Co-authored-by: iscai-msft <[email protected]>

.chronus/changes/tcgc_api_version-2024-3-19-17-15-30.md

@@ -0,0 +1,7 @@
+---
+changeKind: breaking
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+support get common models for specific api version, default to latest api version which may include breaking changes

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

@@ -24,9 +24,11 @@ import {
   isTemplateDeclaration,
   isTemplateDeclarationOrInstance,
   listServices,
+  projectProgram,
   validateDecoratorUniqueOnNode,
 } from "@typespec/compiler";
 import { isHeader } from "@typespec/http";
+import { buildVersionProjections, getVersions } from "@typespec/versioning";
 import {
   AccessFlags,
   LanguageScopes,
@@ -205,22 +207,82 @@ function hasExplicitClientOrOperationGroup(context: TCGCContext): boolean {
   );
 }
 
+function serviceVersioningProjection(context: TCGCContext, client: SdkClient) {
+  if (!context.__service_projection) {
+    context.__service_projection = new Map();
+  }
+
+  let projectedService;
+  let projectedProgram;
+
+  if (context.__service_projection.has(client.service)) {
+    [projectedService, projectedProgram] = context.__service_projection.get(client.service)!;
+  } else {
+    const allApiVersions = getVersions(context.program, client.service)[1]
+      ?.getVersions()
+      .map((x) => x.value);
+    if (!allApiVersions) return;
+    let apiVersion = context.apiVersion;
+    if (
+      apiVersion === "latest" ||
+      apiVersion === undefined ||
+      !allApiVersions.includes(apiVersion)
+    ) {
+      apiVersion = allApiVersions[allApiVersions.length - 1];
+    }
+    if (apiVersion === undefined) return;
+    const versionProjections = buildVersionProjections(context.program, client.service).filter(
+      (v) => apiVersion === v.version
+    );
+    if (versionProjections.length !== 1)
+      throw new Error("Version projects should only contain one element");
+    const projectedVersion = versionProjections[0];
+    if (projectedVersion.projections.length > 0) {
+      projectedProgram = context.program = projectProgram(
+        context.originalProgram,
+        projectedVersion.projections
+      );
+    }
+    projectedService = projectedProgram
+      ? (projectedProgram.projector.projectedTypes.get(client.service) as Namespace)
+      : client.service;
+    context.__service_projection.set(client.service, [projectedService, projectedProgram]);
+  }
+
+  if (client.service !== client.type) {
+    client.type = projectedProgram
+      ? (projectedProgram.projector.projectedTypes.get(client.type) as Interface)
+      : client.type;
+  } else {
+    client.type = projectedService;
+  }
+  client.service = projectedService;
+}
+
 /**
  * List all the clients.
  *
  * @param context TCGCContext
  * @returns Array of clients
  */
 export function listClients(context: TCGCContext): SdkClient[] {
+  if (context.__rawClients) return context.__rawClients;
+
   const explicitClients = [...listScopedDecoratorData(context, clientKey)];
   if (explicitClients.length > 0) {
+    if (context.apiVersion !== "all") {
+      for (const client of explicitClients as SdkClient[]) {
+        serviceVersioningProjection(context, client);
+      }
+    }
+    context.__rawClients = explicitClients;
     return explicitClients;
   }
 
   // if there is no explicit client, we will treat namespaces with service decorator as clients
   const services = listServices(context.program);
 
-  return services.map((service) => {
+  const clients = services.map((service) => {
     let originalName = service.type.name;
     const clientNameOverride = getClientNameOverride(context, service.type);
     if (clientNameOverride) {
@@ -237,8 +299,14 @@ export function listClients(context: TCGCContext): SdkClient[] {
       type: service.type,
       arm: isArm(service.type),
       crossLanguageDefinitionId: `${getNamespaceFullName(service.type)}.${clientName}`,
-    };
+    } as SdkClient;
   });
+
+  if (context.apiVersion !== "all") {
+    clients.map((client) => serviceVersioningProjection(context, client));
+  }
+  context.__rawClients = clients;
+  return clients;
 }
 
 const operationGroupKey = createStateSymbol("operationGroup");
@@ -523,6 +591,8 @@ export function createSdkContext<
     packageName: context.options["package-name"],
     flattenUnionAsEnum: context.options["flatten-union-as-enum"] ?? true,
     diagnostics: diagnostics.diagnostics,
+    apiVersion: context.options["api-version"],
+    originalProgram: context.program,
   };
   sdkContext.experimental_sdkPackage = getSdkPackage(sdkContext);
   if (sdkContext.diagnostics) {

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

@@ -35,6 +35,7 @@ export interface SdkEmitterOptions {
   "filter-out-core-models"?: boolean;
   "package-name"?: string;
   "flatten-union-as-enum"?: boolean;
+  "api-version"?: string;
 }
 
 export interface SdkClient {

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

@@ -5,6 +5,7 @@ import {
   Namespace,
   Operation,
   Program,
+  ProjectedProgram,
   Type,
   Union,
   createDiagnosticCollector,
@@ -19,6 +20,7 @@ import { HttpOperation, HttpStatusCodeRange } from "@typespec/http";
 import { getAddedOnVersions, getRemovedOnVersions, getVersions } from "@typespec/versioning";
 import {
   SdkBuiltInKinds,
+  SdkClient,
   SdkEnumType,
   SdkHttpResponse,
   SdkModelPropertyType,
@@ -128,7 +130,8 @@ export function getAvailableApiVersions(context: TCGCContext, type: Type): strin
   let addedCounter = 0;
   let removeCounter = 0;
   const retval: string[] = [];
-  for (const version of apiVersions) {
+  for (let i = 0; i < apiVersions.length; i++) {
+    const version = apiVersions[i];
     if (addedCounter < addedOnVersions.length && version === addedOnVersions[addedCounter]) {
       added = true;
       addedCounter++;
@@ -137,7 +140,17 @@ export function getAvailableApiVersions(context: TCGCContext, type: Type): strin
       added = false;
       removeCounter++;
     }
-    if (added) retval.push(version);
+    if (added) {
+      // only add version smaller than config
+      if (
+        context.apiVersion === undefined ||
+        context.apiVersion === "latest" ||
+        context.apiVersion === "all" ||
+        apiVersions.indexOf(context.apiVersion) >= i
+      ) {
+        retval.push(version);
+      }
+    }
   }
   return retval;
 }
@@ -260,13 +273,18 @@ export interface TCGCContext {
   knownScalars?: Record<string, SdkBuiltInKinds>;
   diagnostics: readonly Diagnostic[];
   __subscriptionIdParameter?: SdkParameter;
+  __rawClients?: SdkClient[];
+  apiVersion?: string;
+  __service_projection?: Map<Namespace, [Namespace, ProjectedProgram | undefined]>;
+  originalProgram: Program;
 }
 
 export function createTCGCContext(program: Program): TCGCContext {
   return {
     program,
     emitterName: "__TCGC_INTERNAL__",
     diagnostics: [],
+    originalProgram: program,
   };
 }