@azure-tools/typespec-ts 0.54.1 → 0.54.2

package/src/transform/transfrom-rlc-options.ts

@@ -0,0 +1,461 @@
+import { getHttpOperationWithCache } from "@azure-tools/typespec-client-generator-core";
+import { getDoc, NoTarget, Program } from "@typespec/compiler";
+import { getAuthentication } from "@typespec/http";
+import { EmitterOptions, reportDiagnostic } from "../lib.js";
+import { getClientParameters } from "../modular/helpers/client-helpers.js";
+import {
+  NameType,
+  normalizeName,
+  PackageDetails,
+  PackageFlavor,
+  pascalCase,
+  RLCOptions,
+  ServiceInfo,
+} from "../rlc-common/index.js";
+import { getRLCClients, listOperationsUnderRLCClient } from "../utils/client-utils.js";
+import { getSupportedHttpAuth } from "../utils/credential-utils.js";
+import { SdkContext } from "../utils/interfaces.js";
+import { getDefaultService } from "../utils/model-utils.js";
+import { detectModelConflicts } from "../utils/namespace-utils.js";
+import { getOperationName } from "../utils/operation-util.js";
+
+export function transformRLCOptions(
+  emitterOptions: EmitterOptions,
+  dpgContext: SdkContext,
+): RLCOptions {
+  // Extract the options from emitter option
+  const options = extractRLCOptions(
+    dpgContext,
+    emitterOptions,
+    dpgContext.generationPathDetail?.rootDir ?? "",
+  );
+  const batch = getRLCClients(dpgContext, options.isModularLibrary);
+  options.batch = batch;
+  return options;
+}
+function extractRLCOptions(
+  dpgContext: SdkContext,
+  emitterOptions: EmitterOptions,
+  generationRootDir: string,
+): RLCOptions {
+  const program = dpgContext.program;
+  // Compute isModularLibrary early - defaults to true unless explicitly set to false
+  const isModularLibrary = emitterOptions["is-modular-library"] !== false;
+  const includeShortcuts = getIncludeShortcuts(emitterOptions);
+  const packageDetails = getPackageDetails(program, emitterOptions, isModularLibrary);
+  const flavor = getFlavor(emitterOptions, packageDetails);
+  const moduleKind = getModuleKind(emitterOptions);
+  const serviceInfo = getServiceInfo(program, isModularLibrary);
+  const includeHeadersInResponse = emitterOptions["include-headers-in-response"] === true;
+  const azureSdkForJs = getAzureSdkForJs(emitterOptions, flavor);
+  const generateMetadata = getGenerateMetadata(emitterOptions);
+  const generateTest = getGenerateTest(emitterOptions, flavor);
+  const generateSample = getGenerateSample(dpgContext, emitterOptions);
+  const credentialInfo = getCredentialInfo(program, emitterOptions, isModularLibrary);
+  const azureOutputDirectory = getAzureOutputDirectory(generationRootDir);
+  const enableOperationGroup = getEnableOperationGroup(
+    dpgContext,
+    emitterOptions,
+    isModularLibrary,
+  );
+  const enableModelNamespace = getEnableModelNamespace(dpgContext, emitterOptions);
+  const hierarchyClient = getHierarchyClient(emitterOptions);
+  const clearOutputFolder = getClearOutputFolder(emitterOptions);
+  const multiClient = emitterOptions["multi-client"];
+  const isTypeSpecTest = emitterOptions["is-typespec-test"];
+  const title = emitterOptions.title;
+  const dependencyInfo = emitterOptions["dependency-info"];
+  const productDocLink = emitterOptions["product-doc-link"];
+  const compatibilityMode = emitterOptions["compatibility-mode"];
+  const compatibilityLro = emitterOptions["compatibility-lro"];
+  const experimentalExtensibleEnums = emitterOptions["experimental-extensible-enums"];
+  const ignorePropertyNameNormalize = emitterOptions["ignore-property-name-normalize"];
+  const ignoreEnumMemberNameNormalize = emitterOptions["ignore-enum-member-name-normalize"];
+  const compatibilityQueryMultiFormat = emitterOptions["compatibility-query-multi-format"];
+  const enableStorageCompat = emitterOptions["enable-storage-compat"] === true;
+  const treatUnknownAsRecord = emitterOptions["treat-unknown-as-record"] === true;
+  const typespecTitleMap = emitterOptions["typespec-title-map"];
+  const generateReactNativeTarget = emitterOptions["generate-react-native-target"] === true;
+  const hasSubscriptionId = getSubscriptionId(dpgContext);
+  const ignoreNullableOnOptional = getIgnoreNullableOnOptional(emitterOptions, flavor);
+  const wrapNonModelReturn = getWrapNonModelReturn(emitterOptions, flavor);
+  const isMultiService = (dpgContext.allServiceNamespaces?.length ?? 0) > 1;
+
+  return {
+    ...credentialInfo,
+    includeHeadersInResponse,
+    flavor,
+    moduleKind,
+    includeShortcuts,
+    packageDetails,
+    generateMetadata,
+    generateTest,
+    generateSample,
+    azureSdkForJs,
+    serviceInfo,
+    azureOutputDirectory,
+    sourceFrom: "TypeSpec",
+    enableOperationGroup,
+    enableModelNamespace,
+    hierarchyClient,
+    azureArm: dpgContext.arm,
+    clearOutputFolder,
+    multiClient,
+    isTypeSpecTest,
+    title,
+    dependencyInfo,
+    productDocLink,
+    isModularLibrary,
+    compatibilityMode,
+    compatibilityLro,
+    experimentalExtensibleEnums,
+    ignorePropertyNameNormalize,
+    compatibilityQueryMultiFormat,
+    typespecTitleMap,
+    ignoreEnumMemberNameNormalize,
+    hasSubscriptionId,
+    ignoreNullableOnOptional,
+    wrapNonModelReturn,
+    isMultiService,
+    enableStorageCompat,
+    treatUnknownAsRecord,
+    generateReactNativeTarget,
+  };
+}
+
+function processAuth(program: Program, isModularLibrary: boolean) {
+  const serviceNs = getDefaultService(program, isModularLibrary)?.type;
+  if (!serviceNs) {
+    return undefined;
+  }
+  const authorization = getAuthentication(program, serviceNs);
+  if (!authorization || !authorization.options) {
+    return undefined;
+  }
+  const securityInfo: RLCOptions = {};
+  for (const auth of getSupportedHttpAuth(program, authorization)) {
+    switch (auth.type) {
+      case "http":
+        securityInfo.addCredentials = true;
+        securityInfo.customHttpAuthHeaderName = "Authorization";
+        // If it is basic or bearer auth we should generate it as Basic or Bearer
+        securityInfo.customHttpAuthSharedKeyPrefix = ["basic", "bearer"].includes(
+          auth.scheme.toLowerCase(),
+        )
+          ? pascalCase(auth.scheme)
+          : auth.scheme;
+        break;
+      case "apiKey":
+        if (auth.in === "cookie") {
+          return undefined;
+        }
+        securityInfo.addCredentials = true;
+        securityInfo.credentialKeyHeaderName = auth.name;
+        break;
+      case "oauth2": {
+        const flow = auth.flows[0];
+        if (flow === undefined || !flow.scopes) {
+          return undefined;
+        }
+        securityInfo.addCredentials = true;
+        if (!securityInfo.credentialScopes) {
+          securityInfo.credentialScopes = [];
+        }
+        if (flow.scopes.length === 0) {
+          reportDiagnostic(program, {
+            code: "no-credential-scopes",
+            target: NoTarget,
+          });
+        }
+        // ignore the user_impersonation scope
+        if (
+          flow.scopes.length === 1 &&
+          flow.scopes[0] &&
+          flow.scopes[0].value.toLowerCase() === "user_impersonation"
+        ) {
+          return securityInfo;
+        }
+        securityInfo.credentialScopes.push(
+          ...flow.scopes.map((item) => {
+            return item.value;
+          }),
+        );
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return securityInfo;
+}
+
+function getEnableOperationGroup(
+  dpgContext: SdkContext,
+  emitterOptions: EmitterOptions,
+  isModularLibrary: boolean,
+) {
+  if (
+    emitterOptions["enable-operation-group"] === true ||
+    emitterOptions["enable-operation-group"] === false
+  ) {
+    return emitterOptions["enable-operation-group"];
+  }
+  // Only detect if existing name conflicts if customers don't set hierarchyClient to true
+  return detectIfNameConflicts(dpgContext, isModularLibrary);
+}
+
+function getEnableModelNamespace(dpgContext: SdkContext, emitterOptions: EmitterOptions) {
+  if (
+    emitterOptions["enable-model-namespace"] === true ||
+    emitterOptions["enable-model-namespace"] === false
+  ) {
+    return emitterOptions["enable-model-namespace"];
+  }
+  // Detect if existing name conflicts if customers didn't set the option explicitly
+  return detectModelConflicts(dpgContext);
+}
+
+function getHierarchyClient(emitterOptions: EmitterOptions) {
+  if (emitterOptions["hierarchy-client"] === true || emitterOptions["hierarchy-client"] === false) {
+    return emitterOptions["hierarchy-client"];
+  }
+  // enable hierarchy client by default if customers didn't set the option explicitly
+  return true;
+}
+
+function getClearOutputFolder(emitterOptions: EmitterOptions) {
+  return emitterOptions["clear-output-folder"] ? true : false;
+}
+
+function detectIfNameConflicts(dpgContext: SdkContext, isModularLibrary: boolean) {
+  const clients = getRLCClients(dpgContext, isModularLibrary);
+  for (const client of clients) {
+    // only consider it's conflict when there are conflicts in the same client
+    const nameSet = new Set<string>();
+    for (const op of listOperationsUnderRLCClient(client)) {
+      const route = getHttpOperationWithCache(dpgContext, op);
+      const name = getOperationName(dpgContext, route.operation);
+      if (nameSet.has(name)) {
+        return true;
+      } else {
+        nameSet.add(name);
+      }
+    }
+  }
+
+  // No conflicts if we didn't detect any
+  return false;
+}
+
+function getIgnoreNullableOnOptional(
+  emitterOptions: EmitterOptions,
+  flavor: PackageFlavor,
+): boolean {
+  // If explicitly set in options, use that value
+  if (emitterOptions["ignore-nullable-on-optional"] !== undefined) {
+    return Boolean(emitterOptions["ignore-nullable-on-optional"]);
+  }
+  // Default to true for Azure services (same as HLC behavior)
+  return flavor === "azure";
+}
+
+function getWrapNonModelReturn(emitterOptions: EmitterOptions, flavor: PackageFlavor): boolean {
+  // If explicitly set in options, use that value
+  if (emitterOptions["wrap-non-model-return"] !== undefined) {
+    return Boolean(emitterOptions["wrap-non-model-return"]);
+  }
+  // Default to true for Azure services to maintain HLC backward compatibility
+  return flavor === "azure";
+}
+
+function getIncludeShortcuts(emitterOptions: EmitterOptions) {
+  return Boolean(emitterOptions["include-shortcuts"]);
+}
+
+function getModuleKind(emitterOptions: EmitterOptions) {
+  return emitterOptions["module-kind"] ?? "esm";
+}
+
+function getFlavor(emitterOptions: EmitterOptions, packageDetails?: PackageDetails): PackageFlavor {
+  const flavor = emitterOptions.flavor;
+
+  if (flavor !== undefined) {
+    if (flavor.toLowerCase() === "azure") {
+      return "azure";
+    } else {
+      return undefined;
+    }
+  }
+
+  const branded = emitterOptions.branded;
+  if (branded !== undefined) {
+    return branded ? "azure" : undefined;
+  }
+
+  const scopeName = packageDetails?.scopeName;
+  if (
+    scopeName !== undefined &&
+    (scopeName.startsWith("azure") || scopeName.startsWith("msinternal"))
+  ) {
+    return "azure";
+  } else {
+    return undefined;
+  }
+}
+function buildPackageDetails(
+  program: Program,
+  emitterOptions: EmitterOptions,
+  isModularLibrary: boolean,
+): PackageDetails {
+  const defaultDetail = {
+    name: "@msinternal/unamedpackage",
+    nameWithoutScope: "unamedpackage",
+    version: "1.0.0-beta.1",
+  };
+  const isVersionUserProvided = Boolean(emitterOptions["package-details"]?.version);
+  const packageDetails: PackageDetails = {
+    ...emitterOptions["package-details"],
+    name:
+      emitterOptions["package-details"]?.name ??
+      normalizeName(
+        emitterOptions?.title ?? getDefaultService(program, isModularLibrary)?.title ?? "",
+        NameType.Class,
+      ),
+    version: emitterOptions["package-details"]?.version ?? "1.0.0-beta.1",
+    isVersionUserProvided,
+  };
+  if (emitterOptions["package-details"]?.name) {
+    const nameParts = emitterOptions["package-details"]?.name.split("/");
+    if (nameParts.length === 2) {
+      packageDetails.nameWithoutScope = nameParts[1];
+      packageDetails.scopeName = nameParts[0]?.replace("@", "");
+    }
+  }
+  return packageDetails ?? defaultDetail;
+}
+
+function getPackageDetails(
+  program: Program,
+  emitterOptions: EmitterOptions,
+  isModularLibrary: boolean,
+): PackageDetails {
+  return buildPackageDetails(program, emitterOptions, isModularLibrary);
+}
+
+function getServiceInfo(program: Program, isModularLibrary: boolean): ServiceInfo {
+  const defaultService = getDefaultService(program, isModularLibrary);
+  return {
+    title: defaultService?.title,
+    description: defaultService && getDoc(program, defaultService.type),
+  };
+}
+
+function getAzureSdkForJs(emitterOptions: EmitterOptions, flavor: PackageFlavor) {
+  return flavor !== "azure"
+    ? false
+    : emitterOptions["azure-sdk-for-js"] === undefined ||
+        emitterOptions["azure-sdk-for-js"] === null
+      ? true
+      : Boolean(emitterOptions["azure-sdk-for-js"]);
+}
+
+function getGenerateMetadata(emitterOptions: EmitterOptions) {
+  if (
+    emitterOptions["generate-metadata"] === undefined ||
+    emitterOptions["generate-metadata"] === null
+  ) {
+    return undefined;
+  }
+  return Boolean(emitterOptions["generate-metadata"]);
+}
+
+/**
+ * In azure scope, by default we generate test.
+ * @param emitterOptions
+ * @returns
+ */
+function getGenerateTest(emitterOptions: EmitterOptions, flavor: PackageFlavor) {
+  // Disable generateTest if azureSdkForJS is false
+  if (!getAzureSdkForJs(emitterOptions, flavor)) {
+    return false;
+  }
+  return emitterOptions["generate-test"];
+}
+
+/**
+ * In azure scope, by default we generate test.
+ * @param emitterOptions
+ * @returns
+ */
+function getGenerateSample(dpgContext: SdkContext, emitterOptions: EmitterOptions) {
+  if (dpgContext.arm && emitterOptions["generate-sample"] === undefined) {
+    return true;
+  }
+  if (
+    emitterOptions["generate-sample"] === undefined ||
+    emitterOptions["generate-sample"] === null
+  ) {
+    return undefined;
+  }
+  return Boolean(emitterOptions["generate-sample"]);
+}
+
+export function getCredentialInfo(
+  program: Program,
+  emitterOptions: EmitterOptions,
+  isModularLibrary: boolean = true,
+) {
+  const securityInfo = processAuth(program, isModularLibrary);
+  const addCredentials =
+    emitterOptions["add-credentials"] === false
+      ? false
+      : securityInfo
+        ? securityInfo.addCredentials
+        : emitterOptions["add-credentials"];
+  const credentialScopes =
+    securityInfo && securityInfo.credentialScopes
+      ? securityInfo.credentialScopes
+      : emitterOptions["credential-scopes"];
+  const credentialKeyHeaderName =
+    securityInfo && securityInfo.credentialKeyHeaderName
+      ? securityInfo.credentialKeyHeaderName
+      : emitterOptions["credential-key-header-name"];
+  const customHttpAuthHeaderName =
+    securityInfo && securityInfo.customHttpAuthHeaderName
+      ? securityInfo.customHttpAuthHeaderName
+      : emitterOptions["custom-http-auth-header-name"];
+  const customHttpAuthSharedKeyPrefix =
+    securityInfo && securityInfo.customHttpAuthSharedKeyPrefix
+      ? securityInfo.customHttpAuthSharedKeyPrefix
+      : emitterOptions["custom-http-auth-shared-key-prefix"];
+  return {
+    addCredentials,
+    credentialScopes,
+    credentialKeyHeaderName,
+    customHttpAuthHeaderName,
+    customHttpAuthSharedKeyPrefix,
+  };
+}
+
+function getAzureOutputDirectory(emitterOutputDir: string): string | undefined {
+  const sdkFolder = emitterOutputDir;
+  const sdkReletivePath = sdkFolder?.replace(/\/$/, "").split("/").slice(-3).join("/");
+  return sdkReletivePath?.substring(0, 3) === "sdk" ? sdkReletivePath : undefined;
+}
+
+export function getSubscriptionId(dpgContext: SdkContext) {
+  //TODO Need consider multi-client cases, skip multi-client cases check for now
+  if (dpgContext.rlcOptions?.multiClient) {
+    return;
+  }
+  for (const client of dpgContext.sdkPackage.clients) {
+    if (
+      getClientParameters(client, dpgContext)
+        .map((item) => item.name)
+        .includes("subscriptionId")
+    ) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/utils/cross-language-def.ts

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { UsageFlags } from "@azure-tools/typespec-client-generator-core";
+import { transformModularEmitterOptions } from "../modular/build-modular-options.js";
+import { NameType, normalizeName } from "../rlc-common/index.js";
+import { SdkContext } from "./interfaces.js";
+import { getMethodHierarchiesMap } from "./operation-util.js";
+
+export function generateCrossLanguageDefinitionFile(dpgContext: SdkContext): {
+  CrossLanguagePackageId: string;
+  CrossLanguageDefinitionId: Record<string, string>;
+} {
+  const modularSourcesRoot = dpgContext.generationPathDetail?.modularSourcesDir ?? "src";
+  const emitterOptions = transformModularEmitterOptions(dpgContext, modularSourcesRoot, {
+    casing: "camel",
+  });
+  const packageName = emitterOptions.options?.packageDetails?.name ?? "package-name";
+  const CrossLanguageDefinitionId: Record<string, string> = {};
+
+  for (const model of dpgContext.sdkPackage.models) {
+    CrossLanguageDefinitionId[`${packageName}!${model.name}:interface`] =
+      model.crossLanguageDefinitionId;
+  }
+  for (const enm of dpgContext.sdkPackage.enums) {
+    // Skip api version enum for multi-service scenarios since each service may have different versions
+    if (dpgContext.rlcOptions?.isMultiService && enm.usage === UsageFlags.ApiVersionEnum) {
+      continue;
+    }
+    CrossLanguageDefinitionId[`${packageName}!Known${enm.name}:enum`] =
+      enm.crossLanguageDefinitionId;
+  }
+  for (const union of dpgContext.sdkPackage.unions) {
+    CrossLanguageDefinitionId[`${packageName}!${union.name}:type`] =
+      union.crossLanguageDefinitionId;
+  }
+
+  for (const subClient of dpgContext.sdkPackage.clients) {
+    const clientName = emitterOptions.options?.typespecTitleMap?.[subClient.name] ?? subClient.name;
+    const methodMap = getMethodHierarchiesMap(dpgContext, subClient);
+    for (const [prefixKey, operations] of methodMap) {
+      const prefixes = prefixKey.split("/");
+      if (prefixKey === "") {
+        for (const operation of operations) {
+          const { name } = operation;
+          const operationName = `${packageName}!${clientName}#${name}:member(1)`;
+          CrossLanguageDefinitionId[operationName] = operation.crossLanguageDefinitionId;
+        }
+      } else {
+        // e,g., @azure/ai-client!ConnectionsOperations#getConnectionWithSecrets:member": "Azure.AI.Projects.Connections.getConnectionWithSecrets"
+        const rawGroupName = normalizeName(prefixes[0] ?? "", NameType.Interface);
+        const propertyType = `${normalizeName(rawGroupName, NameType.OperationGroup)}Operations`;
+        for (const operation of operations) {
+          const { name } = operation;
+          const operationName = `${packageName}!${propertyType}#${name}:member`;
+          CrossLanguageDefinitionId[operationName] = operation.crossLanguageDefinitionId;
+        }
+      }
+    }
+  }
+
+  return {
+    CrossLanguagePackageId: dpgContext.sdkPackage.crossLanguagePackageId,
+    CrossLanguageDefinitionId,
+  };
+}

package/src/utils/import-helper.ts

@@ -0,0 +1,59 @@
+import { dirname, relative, resolve } from "path";
+import { SourceFile } from "ts-morph";
+import { useContext } from "../context-manager.js";
+
+/**
+ * Adds a named import to a TypeScript source file if it does not already exist.
+ * Utilizes a global symbol map context to resolve module paths and ensure the import is correctly referenced.
+ *
+ * @param {string} symbol The name of the export to import.
+ * @param {SourceFile} currentFile The ts-morph SourceFile object where the import will be added.
+ */
+export function addImportBySymbol(symbol: string, currentFile: SourceFile) {
+  // Retrieve the global map of symbols to their source files.
+  const symbolMap = useContext("symbolMap");
+
+  // Attempt to resolve the file path for the given symbol.
+  const modulePath = symbolMap.get(symbol)?.getFilePath();
+  if (!modulePath) {
+    return;
+  }
+
+  // Resolve absolute path and compute a relative path from the current file to the module.
+  const moduleAbsolutePath = resolve(modulePath);
+  const relativeImportPath = getRelativeImportPath(currentFile.getFilePath(), moduleAbsolutePath)
+    .replace(/\\/g, "/")
+    .replace(/\.ts$/, ".js");
+
+  // Check if the import declaration already exists and if it includes the symbol.
+  const existing = currentFile.getImportDeclaration(
+    (i) => i.getModuleSpecifierValue() === relativeImportPath,
+  );
+
+  if (existing) {
+    const sameImport = existing.getNamedImports().some((i) => i.getName() === symbol);
+
+    if (!sameImport) {
+      existing.addNamedImport(symbol);
+    }
+  } else {
+    currentFile.addImportDeclaration({
+      moduleSpecifier: relativeImportPath,
+      namedImports: [symbol],
+    });
+  }
+}
+
+/**
+ * Computes a relative import path suitable for TypeScript imports given two file paths.
+ * Ensures the returned path starts with './' if necessary to be recognized as a relative module.
+ *
+ * @param {string} from The file path to import from.
+ * @param {string} to The file path to import to.
+ * @returns {string} The relative path adjusted for import syntax.
+ */
+function getRelativeImportPath(from: string, to: string) {
+  const relativePath = relative(dirname(from), to);
+  // Adjust the path format to TypeScript module syntax
+  return relativePath.startsWith(".") ? relativePath : "./" + relativePath;
+}

package/src/utils/interfaces.ts

@@ -1,7 +1,7 @@
 import { SdkContext as TCGCSdkContext } from "@azure-tools/typespec-client-generator-core";
 import { ModelProperty, Namespace } from "@typespec/compiler";
 import { RLCOptions, SchemaContext } from "../rlc-common/index.js";
-import { KnownMediaType } from "./mediaTypes.js";
+import { KnownMediaType } from "./media-types.js";
 
 export interface SdkContext extends TCGCSdkContext {
   rlcOptions?: RLCOptions;