@azure-tools/typespec-ts 0.11.0-alpha.20230413.3

package/src/operationUtil.ts

@@ -0,0 +1,203 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { NameType, normalizeName } from "@azure-tools/rlc-common";
+import {
+  DecoratedType,
+  ignoreDiagnostics,
+  Model,
+  Program,
+  Type
+} from "@typespec/compiler";
+import {
+  getHttpOperation,
+  HttpOperation,
+  HttpOperationResponse,
+  StatusCode
+} from "@typespec/http";
+import {
+  getPagedResult,
+  PagedResultMetadata
+} from "@azure-tools/typespec-azure-core";
+import {
+  SdkClient,
+  SdkContext,
+  listOperationGroups,
+  listOperationsInOperationGroup,
+  SdkOperationGroup
+} from "@azure-tools/typespec-client-generator-core";
+
+export function getNormalizedOperationName(
+  route: HttpOperation,
+  includeGroupName = true
+) {
+  return includeGroupName
+    ? normalizeName(
+        `${route.container?.name}_${route.operation.name}`,
+        NameType.Interface
+      )
+    : normalizeName(`${route.operation.name}`, NameType.Interface);
+}
+
+export function getOperationStatuscode(
+  response: HttpOperationResponse
+): string {
+  switch (response.statusCode) {
+    case "*":
+      return "default";
+    default:
+      return `${response.statusCode}`;
+  }
+}
+
+// FIXME: this is the placeholder function to extract the operationGroupName
+export function getOperationGroupName(operationGroup?: SdkOperationGroup) {
+  return operationGroup?.type.name ?? "";
+}
+
+export function isDefaultStatusCode(statusCode: StatusCode) {
+  return statusCode === "*";
+}
+
+export function isDefinedStatusCode(statusCode: StatusCode) {
+  return statusCode !== "*";
+}
+
+export function isBinaryPayload(body: Type, contentType: string) {
+  contentType = `"${contentType}"`;
+  if (
+    body.kind === "Scalar" &&
+    body.name === "bytes" &&
+    contentType !== `"application/json"` &&
+    contentType !== `"text/plain"` &&
+    contentType !== `"application/json" | "text/plain"` &&
+    contentType !== `"text/plain" | "application/json"`
+  ) {
+    return true;
+  }
+  return false;
+}
+
+export function isLongRunningOperation(
+  program: Program,
+  operation: HttpOperation
+) {
+  program;
+  for (const resp of operation.responses) {
+    if (!resp.responses || !resp.responses.length) {
+      continue;
+    }
+    if (hasDecorator(operation.operation, "$pollingOperation")) {
+      return true;
+    }
+    for (const unit of resp.responses) {
+      for (const [_, header] of Object.entries(unit.headers!)) {
+        if (hasDecorator(header, "$pollingLocation")) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+function hasDecorator(type: DecoratedType, name: string): boolean {
+  return type.decorators.find((it) => it.decorator.name === name) !== undefined;
+}
+
+export function hasPollingOperations(
+  program: Program,
+  client: SdkClient,
+  dpgContext: SdkContext
+) {
+  const operationGroups = listOperationGroups(dpgContext, client);
+  for (const operationGroup of operationGroups) {
+    const operations = listOperationsInOperationGroup(
+      dpgContext,
+      operationGroup
+    );
+    for (const op of operations) {
+      const route = ignoreDiagnostics(getHttpOperation(program, op));
+      if (isLongRunningOperation(program, route)) {
+        return true;
+      }
+    }
+  }
+  const clientOperations = listOperationsInOperationGroup(dpgContext, client);
+  for (const clientOp of clientOperations) {
+    const route = ignoreDiagnostics(getHttpOperation(program, clientOp));
+    if (isLongRunningOperation(program, route)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function isPagingOperation(program: Program, operation: HttpOperation) {
+  for (const response of operation.responses) {
+    const paged = extractPagedMetadataNested(program, response.type as Model);
+    if (paged) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function hasPagingOperations(
+  program: Program,
+  client: SdkClient,
+  dpgContext: SdkContext
+) {
+  const operationGroups = listOperationGroups(dpgContext, client);
+  for (const operationGroup of operationGroups) {
+    const operations = listOperationsInOperationGroup(
+      dpgContext,
+      operationGroup
+    );
+    for (const op of operations) {
+      const route = ignoreDiagnostics(getHttpOperation(program, op));
+      if (isPagingOperation(program, route)) {
+        return true;
+      }
+    }
+  }
+  const clientOperations = listOperationsInOperationGroup(dpgContext, client);
+  for (const clientOp of clientOperations) {
+    const route = ignoreDiagnostics(getHttpOperation(program, clientOp));
+    if (isPagingOperation(program, route)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function extractPagedMetadataNested(
+  program: Program,
+  type: Model
+): PagedResultMetadata | undefined {
+  // This only works for `is Page<T>` not `extends Page<T>`.
+  let paged = getPagedResult(program, type);
+  if (paged) {
+    return paged;
+  }
+  if (type.baseModel) {
+    paged = getPagedResult(program, type.baseModel);
+  }
+  if (paged) {
+    return paged;
+  }
+  const templateArguments = type.templateArguments;
+  if (templateArguments) {
+    for (const argument of templateArguments) {
+      const modelArgument = argument as Model;
+      if (modelArgument) {
+        paged = extractPagedMetadataNested(program, modelArgument);
+        if (paged) {
+          return paged;
+        }
+      }
+    }
+  }
+  return paged;
+}

package/src/transform/transform.ts

@@ -0,0 +1,154 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  SdkClient,
+  SdkContext
+} from "@azure-tools/typespec-client-generator-core";
+import {
+  ImportKind,
+  NameType,
+  normalizeName,
+  OperationParameter,
+  OperationResponse,
+  PathParameter,
+  Paths,
+  RLCModel,
+  RLCOptions,
+  Schema,
+  UrlInfo
+} from "@azure-tools/rlc-common";
+import { Program, getDoc } from "@typespec/compiler";
+import { getServers } from "@typespec/http";
+import { join } from "path";
+import {
+  getDefaultService,
+  getFormattedPropertyDoc,
+  getSchemaForType,
+  getTypeName,
+  predictDefaultValue
+} from "../modelUtils.js";
+import { transformAnnotationDetails } from "./transformAnnotationDetails.js";
+import { transformToParameterTypes } from "./transformParameters.js";
+import { transformPaths } from "./transformPaths.js";
+import { transformToResponseTypes } from "./transformResponses.js";
+import { transformSchemas } from "./transformSchemas.js";
+import { transformRLCOptions } from "./transfromRLCOptions.js";
+import { transformApiVersionInfo } from "./transformApiVersionInfo.js";
+
+export async function transformRLCModel(
+  program: Program,
+  emitterOptions: RLCOptions,
+  client: SdkClient,
+  emitterOutputDir: string,
+  dpgContext: SdkContext
+): Promise<RLCModel> {
+  const options: RLCOptions = transformRLCOptions(
+    program,
+    emitterOptions,
+    emitterOutputDir,
+    dpgContext
+  );
+  const srcPath = join(
+    emitterOutputDir ?? "",
+    "src",
+    // When generating modular library, RLC has to go under rest folder
+    options.isModularLibrary ? "rest" : "",
+    options.batch && options.batch.length > 1
+      ? normalizeName(client.name.replace("Client", ""), NameType.File)
+      : ""
+  );
+  const libraryName = normalizeName(
+    options.batch && options.batch.length > 1
+      ? client.name
+      : options?.title ?? getDefaultService(program)?.title ?? "",
+    NameType.Class
+  );
+  const importSet = new Map<ImportKind, Set<string>>();
+  const paths: Paths = transformPaths(program, client, dpgContext);
+  const schemas: Schema[] = transformSchemas(program, client, dpgContext);
+
+  const responses: OperationResponse[] = transformToResponseTypes(
+    program,
+    importSet,
+    client,
+    dpgContext
+  );
+  const parameters: OperationParameter[] = transformToParameterTypes(
+    program,
+    importSet,
+    client,
+    dpgContext
+  );
+  const annotations = transformAnnotationDetails(program, client, dpgContext);
+  const urlInfo = transformUrlInfo(program, dpgContext);
+  const apiVersionInfo = transformApiVersionInfo(
+    client,
+    program,
+    dpgContext,
+    urlInfo
+  );
+  return {
+    srcPath,
+    libraryName,
+    paths,
+    options,
+    schemas,
+    responses,
+    importSet,
+    apiVersionInfo,
+    parameters,
+    annotations,
+    urlInfo
+  };
+}
+
+export function transformUrlInfo(
+  program: Program,
+  dpgContext: SdkContext
+): UrlInfo | undefined {
+  const serviceNs = getDefaultService(program)?.type;
+  let endpoint = undefined;
+  const urlParameters: PathParameter[] = [];
+  if (serviceNs) {
+    const host = getServers(program, serviceNs);
+    if (host?.[0]?.url) {
+      endpoint = host[0].url;
+    }
+    if (host && host?.[0] && host?.[0]?.parameters) {
+      // Currently we only support one parameter in the servers definition
+      for (const key of host[0].parameters.keys()) {
+        const property = host?.[0]?.parameters.get(key);
+        const type = property?.type;
+
+        if (!type) {
+          continue;
+        }
+
+        const schema = getSchemaForType(program, type);
+        urlParameters.push({
+          name: key,
+          type: getTypeName(schema),
+          description:
+            (getDoc(program, property) &&
+              getFormattedPropertyDoc(program, property, schema, " ")) ??
+            getFormattedPropertyDoc(program, type, schema, " " /* sperator*/),
+          value: predictDefaultValue(
+            program,
+            dpgContext,
+            host?.[0]?.parameters.get(key)
+          )
+        });
+      }
+    }
+  }
+  // Set the default value if missing endpoint parameter
+  if (endpoint == undefined && urlParameters.length === 0) {
+    endpoint = "{endpoint}";
+    urlParameters.push({
+      name: "endpoint",
+      type: "string"
+    });
+  }
+  return { endpoint, urlParameters };
+}

package/src/transform/transformAnnotationDetails.ts

@@ -0,0 +1,231 @@
+import { PagedResultMetadata } from "@azure-tools/typespec-azure-core";
+import {
+  SdkClient,
+  SdkContext,
+  listOperationGroups,
+  listOperationsInOperationGroup
+} from "@azure-tools/typespec-client-generator-core";
+import { AnnotationDetails } from "@azure-tools/rlc-common";
+import { ignoreDiagnostics, Model, Program, Type } from "@typespec/compiler";
+import { getHttpOperation, HttpOperation } from "@typespec/http";
+import {
+  hasPagingOperations,
+  extractPagedMetadataNested,
+  hasPollingOperations
+} from "../operationUtil.js";
+import { getSpecialSerializeInfo } from "./transformParameters.js";
+
+export function transformAnnotationDetails(
+  program: Program,
+  client: SdkClient,
+  dpgContext: SdkContext
+): AnnotationDetails | undefined {
+  // Extract paged metadata from Azure.Core.Page
+  const annotationDetails = {
+    hasLongRunning: hasPollingOperations(program, client, dpgContext)
+  };
+  const details = extractPageDetailFromCore(program, client, dpgContext);
+  const serializeInfo = extractSpecialSerializeInfo(
+    program,
+    client,
+    dpgContext
+  );
+  if (details) {
+    return {
+      ...details,
+      ...annotationDetails,
+      ...serializeInfo
+    };
+  }
+  // TODO: Remove this when @pageable is finally removed.
+  const nextLinks = new Set<string>();
+  const operationGroups = listOperationGroups(dpgContext, client);
+  for (const operationGroup of operationGroups) {
+    const operations = listOperationsInOperationGroup(
+      dpgContext,
+      operationGroup
+    );
+    for (const op of operations) {
+      const route = ignoreDiagnostics(getHttpOperation(program, op));
+      if (getPageable(program, route.operation)) {
+        const nextLinkName =
+          getPageable(program, route.operation) || "nextLink";
+        if (nextLinkName) {
+          nextLinks.add(nextLinkName);
+        }
+      }
+    }
+  }
+  const clientOperations = listOperationsInOperationGroup(dpgContext, client);
+  for (const clientOp of clientOperations) {
+    const route = ignoreDiagnostics(getHttpOperation(program, clientOp));
+    if (getPageable(program, route.operation)) {
+      const nextLinkName = getPageable(program, route.operation) || "nextLink";
+      if (nextLinkName) {
+        nextLinks.add(nextLinkName);
+      }
+    }
+  }
+  if (nextLinks.size === 0) {
+    return {
+      ...annotationDetails,
+      ...serializeInfo
+    };
+  }
+  return {
+    ...annotationDetails,
+    hasPaging: true,
+    pageDetails: {
+      itemNames: ["value"],
+      nextLinkNames: [...nextLinks],
+      isComplexPaging: nextLinks.size > 1
+    },
+    ...serializeInfo
+  };
+}
+const pageableOperationsKey = Symbol("pageable");
+export function getPageable(
+  program: Program,
+  entity: Type
+): string | undefined {
+  return program.stateMap(pageableOperationsKey).get(entity);
+}
+
+function extractPageDetailFromCore(
+  program: Program,
+  client: SdkClient,
+  dpgContext: SdkContext
+) {
+  if (!hasPagingOperations(program, client, dpgContext)) {
+    return;
+  }
+  const nextLinks = new Set<string>();
+  const itemNames = new Set<string>();
+  // Add default values
+  nextLinks.add("nextLink");
+  itemNames.add("value");
+  const operationGroups = listOperationGroups(dpgContext, client);
+  for (const operationGroup of operationGroups) {
+    const operations = listOperationsInOperationGroup(
+      dpgContext,
+      operationGroup
+    );
+    for (const op of operations) {
+      const route = ignoreDiagnostics(getHttpOperation(program, op));
+      extractPageDetailFromCoreForRoute(route);
+    }
+  }
+  const clientOperations = listOperationsInOperationGroup(dpgContext, client);
+  for (const clientOp of clientOperations) {
+    const route = ignoreDiagnostics(getHttpOperation(program, clientOp));
+    extractPageDetailFromCoreForRoute(route);
+  }
+
+  function extractPageDetailFromCoreForRoute(route: HttpOperation) {
+    for (const response of route.responses) {
+      const paged = extractPagedMetadataNested(program, response.type as Model);
+      if (paged) {
+        const nextLinkName = parseNextLinkName(paged);
+        if (nextLinkName) {
+          nextLinks.add(nextLinkName);
+        }
+        const itemName = parseItemName(paged);
+        if (itemName) {
+          itemNames.add(itemName);
+        }
+        // Once we find paged metadata, we don't need to processs any further.
+        continue;
+      }
+    }
+  }
+  // If there are more than one options for nextLink and item names we need to generate a
+  // more complex pagination helper.
+  const isComplexPaging = nextLinks.size > 1 || itemNames.size > 1;
+  return {
+    hasPaging: true,
+    pageDetails: {
+      itemNames: [...itemNames],
+      nextLinkNames: [...nextLinks],
+      isComplexPaging
+    }
+  };
+}
+
+function parseNextLinkName(paged: PagedResultMetadata): string | undefined {
+  const pathComponents = paged.nextLinkPath?.split(".");
+  if (pathComponents) {
+    // TODO: This logic breaks down if there actually is a dotted path.
+    return pathComponents[pathComponents.length - 1];
+  }
+  return undefined;
+}
+
+function parseItemName(paged: PagedResultMetadata): string | undefined {
+  const pathComponents = paged.itemsPath?.split(".");
+  if (pathComponents) {
+    // TODO: This logic breaks down if there actually is a dotted path.
+    return pathComponents[pathComponents.length - 1];
+  }
+  return undefined;
+}
+
+function extractSpecialSerializeInfo(
+  program: Program,
+  client: SdkClient,
+  dpgContext: SdkContext
+) {
+  let hasMultiCollection = false;
+  let hasPipeCollection = false;
+  let hasTsvCollection = false;
+  let hasSsvCollection = false;
+  const operationGroups = listOperationGroups(dpgContext, client);
+  for (const operationGroup of operationGroups) {
+    const operations = listOperationsInOperationGroup(
+      dpgContext,
+      operationGroup
+    );
+    for (const op of operations) {
+      const route = ignoreDiagnostics(getHttpOperation(program, op));
+      route.parameters.parameters.forEach((parameter) => {
+        const serializeInfo = getSpecialSerializeInfo(parameter);
+        hasMultiCollection = hasMultiCollection
+          ? hasMultiCollection
+          : serializeInfo.hasMultiCollection;
+        hasPipeCollection = hasPipeCollection
+          ? hasPipeCollection
+          : serializeInfo.hasPipeCollection;
+        hasTsvCollection = hasTsvCollection
+          ? hasTsvCollection
+          : serializeInfo.hasTsvCollection;
+        hasSsvCollection = hasSsvCollection
+          ? hasSsvCollection
+          : serializeInfo.hasSsvCollection;
+      });
+    }
+  }
+  const clientOperations = listOperationsInOperationGroup(dpgContext, client);
+  for (const clientOp of clientOperations) {
+    const route = ignoreDiagnostics(getHttpOperation(program, clientOp));
+    route.parameters.parameters.forEach((parameter) => {
+      const serializeInfo = getSpecialSerializeInfo(parameter);
+      hasMultiCollection = hasMultiCollection
+        ? hasMultiCollection
+        : serializeInfo.hasMultiCollection;
+      hasPipeCollection = hasPipeCollection
+        ? hasPipeCollection
+        : serializeInfo.hasPipeCollection;
+      hasTsvCollection = hasTsvCollection
+        ? hasTsvCollection
+        : serializeInfo.hasTsvCollection;
+      hasSsvCollection = hasSsvCollection
+        ? hasSsvCollection
+        : serializeInfo.hasSsvCollection;
+    });
+  }
+  return {
+    hasMultiCollection,
+    hasPipeCollection,
+    hasTsvCollection,
+    hasSsvCollection
+  };
+}

package/src/transform/transformApiVersionInfo.ts

@@ -0,0 +1,108 @@
+import {
+  SdkClient,
+  SdkContext,
+  isApiVersion,
+  listOperationGroups,
+  listOperationsInOperationGroup
+} from "@azure-tools/typespec-client-generator-core";
+import { ignoreDiagnostics, Program } from "@typespec/compiler";
+import {
+  ApiVersionInfo,
+  UrlInfo,
+  extractPathApiVersion,
+  extractDefinedPosition
+} from "@azure-tools/rlc-common";
+import { getHttpOperation } from "@typespec/http";
+import {
+  getEnrichedDefaultApiVersion,
+  getSchemaForType,
+  trimUsage
+} from "../modelUtils.js";
+
+export function transformApiVersionInfo(
+  client: SdkClient,
+  program: Program,
+  dpgContext: SdkContext,
+  urlInfo?: UrlInfo
+): ApiVersionInfo | undefined {
+  const queryVersionDetail = getOperationQueryApiVersion(
+    client,
+    program,
+    dpgContext
+  );
+  const pathVersionDetail = extractPathApiVersion(urlInfo);
+  const isCrossedVersion =
+    pathVersionDetail?.isCrossedVersion || queryVersionDetail?.isCrossedVersion;
+  let defaultValue =
+    getEnrichedDefaultApiVersion(program, dpgContext) ??
+    pathVersionDetail?.defaultValue ??
+    queryVersionDetail?.defaultValue;
+
+  // Clear the default value if there exists cross version
+  if (isCrossedVersion) {
+    defaultValue = undefined;
+  }
+
+  return {
+    definedPosition: extractDefinedPosition(
+      queryVersionDetail,
+      pathVersionDetail
+    ),
+    isCrossedVersion,
+    defaultValue
+  };
+}
+
+function getOperationQueryApiVersion(
+  client: SdkClient,
+  program: Program,
+  dpgContext: SdkContext
+): ApiVersionInfo | undefined {
+  const operationGroups = listOperationGroups(dpgContext, client);
+  const apiVersionTypes = new Set<string>();
+  for (const operationGroup of operationGroups) {
+    const operations = listOperationsInOperationGroup(
+      dpgContext,
+      operationGroup
+    );
+    for (const op of operations) {
+      const route = ignoreDiagnostics(getHttpOperation(program, op));
+      const params = route.parameters.parameters.filter(
+        (p) => p.type === "query" && isApiVersion(dpgContext, p)
+      );
+      params.map((p) => {
+        const type = getSchemaForType(program, p.param.type);
+        const typeString = JSON.stringify(trimUsage(type));
+        apiVersionTypes.add(typeString);
+      });
+      if (apiVersionTypes.size > 1) {
+        break;
+      }
+    }
+  }
+  const clientOperations = listOperationsInOperationGroup(dpgContext, client);
+  for (const clientOp of clientOperations) {
+    const route = ignoreDiagnostics(getHttpOperation(program, clientOp));
+    const params = route.parameters.parameters.filter(
+      (p) => p.type === "query" && isApiVersion(dpgContext, p)
+    );
+    params.map((p) => {
+      const type = getSchemaForType(program, p.param.type);
+      const typeString = JSON.stringify(trimUsage(type));
+      apiVersionTypes.add(typeString);
+    });
+    if (apiVersionTypes.size > 1) {
+      break;
+    }
+  }
+  // If no api-version parameter defined return directly
+  if (apiVersionTypes.size === 0) {
+    return;
+  }
+  const detail: ApiVersionInfo = {
+    definedPosition: "query",
+    isCrossedVersion: apiVersionTypes.size > 1,
+    defaultValue: undefined // We won't prompt the query versions into client one
+  };
+  return detail;
+}