@azure-tools/typespec-ts 0.11.0

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 {
+  Client,
+  DpgContext,
+  listOperationGroups,
+  listOperationsInOperationGroup,
+  OperationGroup
+} 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?: OperationGroup) {
+  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: Client,
+  dpgContext: DpgContext
+) {
+  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: Client,
+  dpgContext: DpgContext
+) {
+  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,224 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  Client,
+  DpgContext,
+  getDefaultApiVersion
+} 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,
+  Type,
+  BooleanLiteral,
+  StringLiteral,
+  NumericLiteral,
+  ModelProperty,
+  listServices,
+  NoTarget,
+  Service,
+  getDoc,
+  getService
+} from "@typespec/compiler";
+import { getServers } from "@typespec/http";
+import { join } from "path";
+import {
+  getFormattedPropertyDoc,
+  getSchemaForType,
+  getTypeName
+} 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 { isApiVersion } from "@azure-tools/typespec-client-generator-core";
+import { reportDiagnostic } from "../lib.js";
+import { transformApiVersionParam } from "./transformApiVersionParam.js";
+
+export async function transformRLCModel(
+  program: Program,
+  emitterOptions: RLCOptions,
+  client: Client,
+  emitterOutputDir: string,
+  dpgContext: DpgContext
+): Promise<RLCModel> {
+  const options: RLCOptions = transformRLCOptions(
+    program,
+    emitterOptions,
+    emitterOutputDir,
+    dpgContext
+  );
+  const srcPath = join(
+    emitterOutputDir ?? "",
+    "src",
+    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 apiVersionInQueryParam = transformApiVersionParam(
+    client,
+    program,
+    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);
+  return {
+    srcPath,
+    libraryName,
+    paths,
+    options,
+    schemas,
+    responses,
+    importSet,
+    apiVersionInQueryParam,
+    parameters,
+    annotations,
+    urlInfo
+  };
+}
+
+export function transformUrlInfo(
+  program: Program,
+  dpgContext: DpgContext
+): 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,
+                " " /* sperator*/
+              )) ??
+            getFormattedPropertyDoc(program, type, schema, " " /* sperator*/),
+          value: getDefaultValue(
+            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 };
+}
+
+export function getDefaultValue(
+  program: Program,
+  dpgContext: DpgContext,
+  param?: ModelProperty
+) {
+  const otherDefaultValue = param?.default;
+  const serviceNamespace = getDefaultService(program)?.type;
+  if (!serviceNamespace) {
+    return undefined;
+  }
+  const defaultApiVersion =
+    getDefaultApiVersion(dpgContext, serviceNamespace)?.value ??
+    getService(program, serviceNamespace)?.version;
+  if (param && isApiVersion(dpgContext, param) && defaultApiVersion) {
+    return defaultApiVersion;
+  } else if (isLiteralValue(otherDefaultValue)) {
+    return otherDefaultValue.value;
+  }
+  return undefined;
+}
+
+function isLiteralValue(
+  type?: Type
+): type is StringLiteral | NumericLiteral | BooleanLiteral {
+  if (!type) {
+    return false;
+  }
+
+  if (
+    type.kind === "Boolean" ||
+    type.kind === "String" ||
+    type.kind === "Number"
+  ) {
+    return type.value !== undefined;
+  }
+
+  return false;
+}
+
+export function getDefaultService(program: Program): Service | undefined {
+  const services = listServices(program);
+  if (!services || services.length === 0) {
+    reportDiagnostic(program, {
+      code: "no-service-defined",
+      target: NoTarget
+    });
+  }
+  if (services.length > 1) {
+    reportDiagnostic(program, {
+      code: "more-than-one-service",
+      target: NoTarget
+    });
+  }
+  return services[0];
+}

package/src/transform/transformAnnotationDetails.ts

@@ -0,0 +1,231 @@
+import { PagedResultMetadata } from "@azure-tools/typespec-azure-core";
+import {
+  Client,
+  DpgContext,
+  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: Client,
+  dpgContext: DpgContext
+): 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: Client,
+  dpgContext: DpgContext
+) {
+  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: Client,
+  dpgContext: DpgContext
+) {
+  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
+  };
+}