@azure-tools/typespec-ts 0.55.0-dev.1 → 0.55.0-dev.11

package/src/rlc-common/test/build-snippets.ts

@@ -0,0 +1,25 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { getClientName } from "../helpers/name-constructors.js";
+import { RLCModel } from "../interfaces.js";
+import { snippetsContent } from "./template.js";
+
+export function buildSnippets(model: RLCModel, clientName?: string) {
+  // to keep the same config for azure scope in buildReadmeFile.ts
+  if (
+    (model?.options?.packageDetails?.scopeName === "azure" ||
+      model?.options?.packageDetails?.scopeName === "azure-rest") &&
+    model.options.addCredentials
+  ) {
+    return {
+      path: "test/snippets.spec.ts",
+      content: hbs.compile(snippetsContent, { noEscape: true })({
+        clientClassName: clientName ? clientName : getClientName(model),
+        azureArm: model.options?.azureArm,
+        hasSubscriptionId: model.options.hasSubscriptionId,
+      }),
+    };
+  }
+  return undefined;
+}

package/src/rlc-common/test/template.ts

@@ -128,18 +128,11 @@ module.exports = function (config) {
 
 export const recordedClientContent = `
 
-{{#if isEsm}}
 import {
   Recorder,
   RecorderStartOptions,
   VitestTestContext,
 } from "@azure-tools/test-recorder";
-{{/if}}
-
-{{#if isCjs}}
-import { Context } from "mocha";
-import { Recorder, RecorderStartOptions } from "@azure-tools/test-recorder";
-{{/if}}
 
 const replaceableVariables: Record<string, string> = {
   SUBSCRIPTION_ID: "azure_subscription_id"
@@ -154,25 +147,14 @@ const recorderEnvSetup: RecorderStartOptions = {
  * Should be called first in the test suite to make sure environment variables are
  * read before they are being used.
  */
-{{#if isEsm}}
 export async function createRecorder(context: VitestTestContext): Promise<Recorder> {
   const recorder = new Recorder(context);
   await recorder.start(recorderEnvSetup);
   return recorder;
 }
-{{/if}}
-
-{{#if isCjs}}
-export async function createRecorder(context: Context): Promise<Recorder> {
-  const recorder = new Recorder(context.currentTest);
-  await recorder.start(recorderEnvSetup);
-  return recorder;
-}
-{{/if}}
 `;
 
 export const sampleTestContent = `
-{{#if isEsm}}
 // import { Recorder } from "@azure-tools/test-recorder";
 // import { createRecorder } from "./utils/recordedClient.js";
 import { assert, 
@@ -181,24 +163,12 @@ import { assert,
          it,
          describe
 } from "vitest";
-{{/if}}
-
-{{#if isCjs}}
-// import { Recorder } from "@azure-tools/test-recorder";
-import { assert } from "chai";
-// import { createRecorder } from "./utils/recordedClient{{#if isModularLibrary}}.js{{/if}}";
-// import { Context } from "mocha";
-{{/if}}
 
 describe("My test", () => {
   // let recorder: Recorder;
 
-  // beforeEach(async function({{#if isCjs}}this: Context{{else}}ctx{{/if}}) {
-    {{#if isEsm}}
+  // beforeEach(async function(ctx) {
     // recorder = await createRecorder(ctx);
-    {{else}}
-    // recorder = await createRecorder(this);
-    {{/if}}
   // });
 
   // afterEach(async function() {
@@ -212,15 +182,12 @@ describe("My test", () => {
 `;
 
 export const snippetsContent = `
-{{#if isModularLibrary}}
 import { {{ clientClassName }} } from "../src/index.js";
 import { DefaultAzureCredential, InteractiveBrowserCredential } from "@azure/identity";
-{{/if}}
 import { setLogLevel } from "@azure/logger";
 import { describe, it } from "vitest";
 
 describe("snippets", () => {
-{{#if isModularLibrary}}
   it("ReadmeSampleCreateClient_Node", async () => {
     {{#if azureArm}}
     {{#if hasSubscriptionId}}
@@ -254,7 +221,6 @@ describe("snippets", () => {
     const client = new {{ clientClassName }}("<endpoint>", credential);
     {{/if}}
   });
-  {{/if}}
 
   it("SetLogLevel", async () => {
     setLogLevel("info");

package/src/transform/transform-api-version-info.ts

@@ -0,0 +1,103 @@
+import {
+  getHttpOperationWithCache,
+  isApiVersion,
+  SdkClient,
+} from "@azure-tools/typespec-client-generator-core";
+import {
+  ApiVersionInfo,
+  ApiVersionPosition,
+  extractDefinedPosition,
+  extractPathApiVersion,
+  SchemaContext,
+  UrlInfo,
+} from "../rlc-common/index.js";
+import { listOperationsUnderRLCClient } from "../utils/client-utils.js";
+import { SdkContext } from "../utils/interfaces.js";
+import { getDefaultApiVersionString, getSchemaForType, trimUsage } from "../utils/model-utils.js";
+
+export function transformApiVersionInfo(
+  client: SdkClient,
+  dpgContext: SdkContext,
+  urlInfo?: UrlInfo,
+): ApiVersionInfo | undefined {
+  const queryVersionDetail = getOperationApiVersion(client, dpgContext);
+  const pathVersionDetail = extractPathApiVersion(urlInfo);
+  const isCrossedVersion =
+    queryVersionDetail || pathVersionDetail
+      ? Boolean(pathVersionDetail?.isCrossedVersion || queryVersionDetail?.isCrossedVersion)
+      : undefined;
+  const defaultValue =
+    (pathVersionDetail || queryVersionDetail) && !isCrossedVersion
+      ? (getDefaultApiVersionString(dpgContext) ??
+        pathVersionDetail?.defaultValue ??
+        queryVersionDetail?.defaultValue)
+      : undefined;
+
+  if (pathVersionDetail && queryVersionDetail) {
+    return pathVersionDetail;
+  }
+  if (pathVersionDetail && !queryVersionDetail) {
+    dpgContext.hasApiVersionInClient = true;
+  }
+  return {
+    definedPosition: extractDefinedPosition(queryVersionDetail, pathVersionDetail),
+    isCrossedVersion,
+    defaultValue,
+    required: pathVersionDetail?.required ?? queryVersionDetail?.required,
+  };
+}
+
+export function getOperationApiVersion(
+  client: SdkClient,
+  dpgContext: SdkContext,
+): ApiVersionInfo | undefined {
+  const apiVersionTypes = new Set<string>();
+  const locations = new Set<ApiVersionPosition>();
+  const required = new Set<boolean>();
+  dpgContext.hasApiVersionInClient = true;
+  let hasApiVersionInOperation: boolean;
+  for (const op of listOperationsUnderRLCClient(client)) {
+    hasApiVersionInOperation = false;
+    const route = getHttpOperationWithCache(dpgContext, op);
+    // ignore overload base operation
+    if (route.overloads && route.overloads?.length > 0) {
+      continue;
+    }
+    const params = route.parameters.parameters.filter(
+      (p) => (p.type === "query" || p.type === "path") && isApiVersion(dpgContext, p.param),
+    );
+    params.map((p) => {
+      const type = getSchemaForType(dpgContext, p.param.type, {
+        usage: [SchemaContext.Exception, SchemaContext.Input],
+        needRef: false,
+        relevantProperty: p.param,
+      });
+      required.add(!p.param.optional);
+      if (p.type === "query" || p.type === "path") {
+        locations.add(p.type);
+      }
+      const typeString = JSON.stringify(trimUsage(type));
+      apiVersionTypes.add(typeString);
+    });
+    if (apiVersionTypes.size > 1 || !dpgContext.hasApiVersionInClient) {
+      break;
+    }
+    if (params.length === 1) {
+      hasApiVersionInOperation = true;
+    }
+    if (!hasApiVersionInOperation) {
+      dpgContext.hasApiVersionInClient = false;
+    }
+  }
+  // If no api-version parameter defined return directly
+  if (apiVersionTypes.size === 0 || !dpgContext.hasApiVersionInClient) {
+    return;
+  }
+  const detail: ApiVersionInfo = {
+    definedPosition: locations.size > 1 ? "duplicate" : locations.values().next().value,
+    isCrossedVersion: apiVersionTypes.size > 1,
+    defaultValue: undefined, // We won't prompt the query versions into client one
+    required: required.values().next().value,
+  };
+  return detail;
+}

package/src/transform/transform-helper-function-details.ts

@@ -0,0 +1,79 @@
+import { getHttpOperationWithCache, SdkClient } from "@azure-tools/typespec-client-generator-core";
+import { HelperFunctionDetails } from "../rlc-common/index.js";
+import { listOperationsUnderRLCClient } from "../utils/client-utils.js";
+import { SdkContext } from "../utils/interfaces.js";
+import { getCollectionFormat } from "../utils/model-utils.js";
+import {
+  extractPageDetails,
+  getSpecialSerializeInfo,
+  hasPagingOperations,
+  hasPollingOperations,
+} from "../utils/operation-util.js";
+
+export function transformHelperFunctionDetails(
+  client: SdkClient,
+  dpgContext: SdkContext,
+): HelperFunctionDetails {
+  const serializeInfo = extractSpecialSerializeInfo(client, dpgContext);
+
+  const annotationDetails = {
+    hasLongRunning: hasPollingOperations(client, dpgContext),
+  };
+  const details = extractClientPageDetails(client, dpgContext);
+  return {
+    ...(details ?? {}),
+    ...annotationDetails,
+    ...serializeInfo,
+  };
+}
+
+function extractClientPageDetails(client: SdkClient, dpgContext: SdkContext) {
+  const program = dpgContext.program;
+  if (!hasPagingOperations(client, dpgContext)) {
+    return;
+  }
+  const nextLinks = new Set<string>(["nextLink"]);
+  const itemNames = new Set<string>(["value"]);
+  for (const op of listOperationsUnderRLCClient(client)) {
+    const route = getHttpOperationWithCache(dpgContext, op);
+    // ignore overload base operation
+    if (route.overloads && route.overloads?.length > 0) {
+      continue;
+    }
+    const pagedDetail = extractPageDetails(program, route);
+    if (pagedDetail) {
+      pagedDetail.itemNames.forEach((name) => itemNames.add(name));
+      pagedDetail.nextLinkNames.forEach((name) => nextLinks.add(name));
+    }
+  }
+  // If there are more than one options for nextLink and item names we need to generate a
+  // more complex pagination helper.
+  return {
+    hasPaging: true,
+    pageDetails: {
+      itemNames: [...itemNames],
+      nextLinkNames: [...nextLinks],
+      isComplexPaging: nextLinks.size > 1 || itemNames.size > 1,
+    },
+  };
+}
+
+function extractSpecialSerializeInfo(client: SdkClient, dpgContext: SdkContext) {
+  let hasMultiCollection = false;
+  let hasCsvCollection = false;
+  for (const op of listOperationsUnderRLCClient(client)) {
+    const route = getHttpOperationWithCache(dpgContext, op);
+    route.parameters.parameters.forEach((parameter) => {
+      const format = getCollectionFormat(dpgContext, parameter as any);
+      const serializeInfo = getSpecialSerializeInfo(dpgContext, parameter.type, format!);
+      hasMultiCollection = hasMultiCollection
+        ? hasMultiCollection
+        : serializeInfo.hasMultiCollection;
+      hasCsvCollection = hasCsvCollection ? hasCsvCollection : serializeInfo.hasCsvCollection;
+    });
+  }
+  return {
+    hasMultiCollection,
+    hasCsvCollection,
+  };
+}

package/src/transform/transform-parameters.ts

@@ -0,0 +1,321 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  SdkClient,
+  getHttpOperationWithCache,
+  isApiVersion,
+} from "@azure-tools/typespec-client-generator-core";
+import { NoTarget, Type, isVoidType } from "@typespec/compiler";
+import { HttpOperation, HttpOperationParameter, HttpOperationParameters } from "@typespec/http";
+import { reportDiagnostic } from "../lib.js";
+import {
+  ApiVersionInfo,
+  Imports,
+  ObjectSchema,
+  OperationParameter,
+  ParameterBodyMetadata,
+  ParameterMetadata,
+  Schema,
+  SchemaContext,
+} from "../rlc-common/index.js";
+import { listOperationsUnderRLCClient } from "../utils/client-utils.js";
+import { SdkContext } from "../utils/interfaces.js";
+import {
+  KnownMediaType,
+  extractMediaTypes,
+  hasMediaType,
+  isMediaTypeJsonMergePatch,
+} from "../utils/media-types.js";
+import {
+  getBodyType,
+  getCollectionFormat,
+  getFormattedPropertyDoc,
+  getImportedModelName,
+  getSchemaForType,
+  getTypeName,
+  isArrayType,
+  isBodyRequired,
+} from "../utils/model-utils.js";
+import {
+  getOperationGroupName,
+  getOperationName,
+  getSpecialSerializeInfo,
+} from "../utils/operation-util.js";
+import { getParameterSerializationInfo } from "../utils/parameter-utils.js";
+
+interface ParameterTransformationOptions {
+  apiVersionInfo?: ApiVersionInfo;
+  operationGroupName?: string;
+  operationName?: string;
+  importModels?: Set<string>;
+}
+
+export function transformToParameterTypes(
+  client: SdkClient,
+  dpgContext: SdkContext,
+  importDetails: Imports,
+  apiVersionInfo?: ApiVersionInfo,
+): OperationParameter[] {
+  const rlcParameters: OperationParameter[] = [];
+  const outputImportedSet = new Set<string>();
+  for (const op of listOperationsUnderRLCClient(client)) {
+    const route = getHttpOperationWithCache(dpgContext, op);
+    // ignore overload base operation
+    if (route.overloads && route.overloads?.length > 0) {
+      continue;
+    }
+    transformToParameterTypesForRoute(route);
+  }
+
+  if (outputImportedSet.size > 0) {
+    importDetails.parameter.importsSet = outputImportedSet;
+  }
+  function transformToParameterTypesForRoute(route: HttpOperation) {
+    const parameters = route.parameters;
+    const rlcParameter: OperationParameter = {
+      operationGroup: getOperationGroupName(dpgContext, route),
+      operationName: getOperationName(dpgContext, route.operation),
+      parameters: [],
+    };
+    const options = {
+      apiVersionInfo,
+      operationGroupName: rlcParameter.operationGroup,
+      operationName: rlcParameter.operationName,
+      importModels: outputImportedSet,
+    };
+    // transform query param
+    const queryParams = transformQueryParameters(dpgContext, parameters, options);
+    // transform path param
+    const pathParams = transformPathParameters(dpgContext, parameters, options);
+    // TODO: support cookie parameters, https://github.com/Azure/autorest.typescript/issues/2898
+    transformCookieParameters(dpgContext, parameters);
+    // transform header param including content-type
+    const headerParams = transformHeaderParameters(dpgContext, parameters, options);
+    // transform body
+    const bodyType = getBodyType(route);
+    let bodyParameter = undefined;
+    if (bodyType) {
+      bodyParameter = transformBodyParameters(
+        dpgContext,
+        parameters,
+        headerParams,
+        outputImportedSet,
+        bodyType,
+      );
+    }
+    rlcParameter.parameters.push({
+      parameters: [...queryParams, ...pathParams, ...headerParams],
+      body: bodyParameter,
+    });
+    rlcParameters.push(rlcParameter);
+  }
+  return rlcParameters;
+}
+
+function getParameterMetadata(
+  dpgContext: SdkContext,
+  paramType: "query" | "path" | "header",
+  parameter: HttpOperationParameter,
+  options: ParameterTransformationOptions,
+): ParameterMetadata {
+  const program = dpgContext.program;
+  const importedModels = options.importModels ?? new Set<string>();
+  const schemaContext = [SchemaContext.Exception, SchemaContext.Input];
+  const schema = getSchemaForType(dpgContext, parameter.param.type, {
+    usage: schemaContext,
+    needRef: false,
+    relevantProperty: parameter.param,
+  }) as Schema;
+  const name = getParameterName(parameter.name);
+  let description = getFormattedPropertyDoc(program, parameter.param, schema) ?? "";
+  const format = getCollectionFormat(dpgContext, parameter as any);
+  if (isArrayType(schema) && format) {
+    const serializeInfo = getSpecialSerializeInfo(dpgContext, parameter.type, format);
+    if (serializeInfo.hasMultiCollection || serializeInfo.hasCsvCollection) {
+      description += `${description ? "\n" : ""}This parameter could be formatted as ${serializeInfo.collectionInfo.join(
+        ", ",
+      )} collection string, we provide ${serializeInfo.descriptions.join(
+        ", ",
+      )} from serializeHelper.ts to help${
+        serializeInfo.hasMultiCollection
+          ? ", you will probably need to set skipUrlEncoding as true when sending the request"
+          : ""
+      }.`;
+    }
+    if (format === "tsv") {
+      description += `${description ? "\n" : ""}This parameter could be formatted as tsv collection string.`;
+    }
+  }
+
+  getImportedModelName(schema, schemaContext)?.forEach(importedModels.add, importedModels);
+  const serializationType = getParameterSerializationInfo(
+    dpgContext,
+    parameter,
+    schema,
+    options.operationGroupName,
+    options.operationName,
+  );
+  return {
+    type: paramType,
+    name,
+    param: {
+      name,
+      type: serializationType.typeName,
+      typeName: serializationType.typeName,
+      required: !parameter.param.optional,
+      description,
+      wrapperType: serializationType.wrapperType,
+    },
+  };
+}
+
+function getParameterName(name: string) {
+  if (name && name.toLowerCase() === "content-type") {
+    return "contentType";
+  }
+  return `"${name}"`;
+}
+
+function transformCookieParameters(dpgContext: SdkContext, parameters: HttpOperationParameters) {
+  // TODO: support cookie parameters, https://github.com/Azure/autorest.typescript/issues/2898
+  parameters.parameters
+    .filter((p) => p.type === "cookie")
+    .forEach((p) => {
+      reportDiagnostic(dpgContext.program, {
+        code: "parameter-type-not-supported",
+        format: {
+          paramName: p.name,
+          paramType: p.type,
+        },
+        target: NoTarget,
+      });
+    });
+}
+
+function transformQueryParameters(
+  dpgContext: SdkContext,
+  parameters: HttpOperationParameters,
+  options: ParameterTransformationOptions,
+): ParameterMetadata[] {
+  const queryParameters = parameters.parameters.filter(
+    (p) =>
+      p.type === "query" &&
+      !(isApiVersion(dpgContext, p.param) && options.apiVersionInfo?.definedPosition === "query"),
+  );
+  if (!queryParameters.length) {
+    return [];
+  }
+  return queryParameters.map((qp) => getParameterMetadata(dpgContext, "query", qp, options));
+}
+
+/**
+ * Only support to take the global path parameter as path parameter
+ * @returns
+ */
+function transformPathParameters(
+  dpgContext: SdkContext,
+  parameters: HttpOperationParameters,
+  options: ParameterTransformationOptions,
+) {
+  // build wrapper path parameters
+  const pathParameters = parameters.parameters.filter((p) => p.type === "path");
+  if (!pathParameters.length) {
+    return [];
+  }
+  // only need to build path parameters for wrapper type
+  const params = pathParameters
+    .map((qp) => getParameterMetadata(dpgContext, "path", qp, options))
+    .filter((p) => p.param.wrapperType);
+  return params;
+}
+
+export function transformHeaderParameters(
+  dpgContext: SdkContext,
+  parameters: HttpOperationParameters,
+  options: ParameterTransformationOptions,
+): ParameterMetadata[] {
+  const headerParameters = parameters.parameters.filter((p) => p.type === "header");
+  if (!headerParameters.length) {
+    return [];
+  }
+  return headerParameters.map((qp) => getParameterMetadata(dpgContext, "header", qp, options));
+}
+
+function transformBodyParameters(
+  dpgContext: SdkContext,
+  parameters: HttpOperationParameters,
+  headers: ParameterMetadata[],
+  importedModels: Set<string>,
+  inputBodyType?: Type,
+): ParameterBodyMetadata | undefined {
+  const bodyType = parameters.body && inputBodyType ? inputBodyType : parameters.body?.type;
+  if (!bodyType || isVoidType(bodyType)) {
+    return;
+  }
+  return transformRequestBody(dpgContext, bodyType, parameters, importedModels, headers);
+}
+
+function transformRequestBody(
+  dpgContext: SdkContext,
+  bodyType: Type,
+  parameters: HttpOperationParameters,
+  importedModels: Set<string>,
+  headers: ParameterMetadata[],
+) {
+  const contentTypes = extractMediaTypes(parameters.body?.contentTypes ?? []);
+  const schema = getSchemaForType(dpgContext, bodyType, {
+    mediaTypes: contentTypes,
+    isRequestBody: true,
+    usage: [SchemaContext.Input, SchemaContext.Exception],
+  });
+
+  const descriptions = getBodyDescriptions(dpgContext, schema, parameters);
+  const type = getRequestBodyType(schema, importedModels, headers);
+
+  return {
+    isPartialBody: false,
+    body: [
+      {
+        properties: schema.properties,
+        typeName: schema.name,
+        name: "body",
+        type,
+        required: isBodyRequired(parameters),
+        description: descriptions.join("\n\n"),
+        isMultipartBody:
+          hasMediaType(KnownMediaType.MultipartFormData, contentTypes) && contentTypes.length === 1,
+        oriSchema: schema,
+      },
+    ],
+  };
+}
+
+function getRequestBodyType(
+  bodySchema: Schema,
+  importedModels: Set<string>,
+  headers?: ParameterMetadata[],
+) {
+  const schemaUsage = [SchemaContext.Input, SchemaContext.Exception];
+  const importedNames = getImportedModelName(bodySchema, schemaUsage) ?? [];
+  importedNames.forEach(importedModels.add, importedModels);
+
+  let typeName = getTypeName(bodySchema, schemaUsage);
+  const contentTypes = headers?.filter((h) => h.name === "contentType").map((h) => h.param.type);
+  const hasMergeAndPatchType = isMediaTypeJsonMergePatch(contentTypes ?? []);
+  if (hasMergeAndPatchType && Boolean(bodySchema.name) && (bodySchema as ObjectSchema).properties) {
+    typeName = `${typeName}ResourceMergeAndPatch`;
+  }
+  return typeName;
+}
+
+function getBodyDescriptions(
+  dpgContext: SdkContext,
+  bodySchema: Schema,
+  parameters: HttpOperationParameters,
+) {
+  const description = parameters.body?.property
+    ? getFormattedPropertyDoc(dpgContext.program, parameters.body.property, bodySchema)
+    : "";
+  return description ? [description] : [];
+}