@azure-tools/typespec-ts 0.54.0 → 0.54.2

package/src/modular/build-root-index.ts

@@ -0,0 +1,407 @@
+import { SdkClientType, SdkServiceOperation } from "@azure-tools/typespec-client-generator-core";
+import { NoTarget } from "@typespec/compiler";
+import { join } from "path/posix";
+import { Project, SourceFile } from "ts-morph";
+import { useContext } from "../context-manager.js";
+import { resolveReference } from "../framework/reference.js";
+import { reportDiagnostic } from "../lib.js";
+import { isAzurePackage, NameType, normalizeName } from "../rlc-common/index.js";
+import { getModularClientOptions } from "../utils/client-utils.js";
+import { SdkContext } from "../utils/interfaces.js";
+import { getMethodHierarchiesMap } from "../utils/operation-util.js";
+import { partitionAndEmitExports } from "./build-subpath-index.js";
+import { getClassicalClientName } from "./helpers/naming-helpers.js";
+import { isLroOnlyOperation } from "./helpers/operation-helpers.js";
+import { ModularEmitterOptions } from "./interfaces.js";
+import {
+  CloudSettingHelpers,
+  MultipartHelpers,
+  PagingHelpers,
+  PlatformTypeHelpers,
+} from "./static-helpers-metadata.js";
+
+export function buildRootIndex(
+  context: SdkContext,
+  emitterOptions: ModularEmitterOptions,
+  rootIndexFile: SourceFile,
+  clientMap?: [string[], SdkClientType<SdkServiceOperation>],
+) {
+  if (!clientMap) {
+    // we still need to export the models if no client is provided
+    exportModels(emitterOptions, rootIndexFile);
+    exportRestErrorTypes(context, rootIndexFile);
+    return;
+  }
+  const project = useContext("outputProject");
+  const [_, client] = clientMap;
+  const srcPath = emitterOptions.modularOptions.sourceRoot;
+  const { subfolder } = getModularClientOptions(clientMap);
+  const clientName = `${getClassicalClientName(client)}`;
+  const clientFile = project.getSourceFile(
+    `${srcPath}/${subfolder && subfolder !== "" ? subfolder + "/" : ""}${normalizeName(
+      clientName,
+      NameType.File,
+    )}.ts`,
+  );
+
+  if (!clientFile) {
+    reportDiagnostic(context.program, {
+      code: "client-file-not-found",
+      format: {
+        filePath: `${srcPath}/${normalizeName(clientName, NameType.File)}.ts`,
+      },
+      target: NoTarget,
+    });
+    return; // Skip exporting this client but continue with others
+  }
+
+  exportClassicalClient(client, rootIndexFile, subfolder ?? "");
+  exportSimplePollerLike(context, clientMap, rootIndexFile, project, srcPath, subfolder);
+  exportRestoreHelpers(rootIndexFile, project, srcPath, clientName, subfolder, true);
+  exportModels(emitterOptions, rootIndexFile, clientName);
+  exportModules(rootIndexFile, project, srcPath, clientName, "api", {
+    subfolder,
+    interfaceOnly: true,
+    isTopLevel: true,
+  });
+  exportModules(rootIndexFile, project, srcPath, clientName, "classic", {
+    subfolder,
+    isTopLevel: true,
+  });
+
+  exportPagingTypes(context, rootIndexFile);
+  exportFileContentsType(context, rootIndexFile);
+  exportAzureCloudTypes(context, rootIndexFile);
+  exportRestErrorTypes(context, rootIndexFile);
+}
+
+function exportModels(
+  emitterOptions: ModularEmitterOptions,
+  rootIndexFile: SourceFile,
+  clientName: string = "",
+) {
+  // export models index file if not exists
+  const project = useContext("outputProject");
+  const srcPath = emitterOptions.modularOptions.sourceRoot;
+  const modelsExportsIndex = rootIndexFile.getExportDeclarations()?.find((i) => {
+    return i.getModuleSpecifierValue()?.startsWith(`./models/`);
+  });
+  if (!modelsExportsIndex) {
+    exportModules(rootIndexFile, project, srcPath, clientName, "models", {
+      isTopLevel: true,
+      recursive: true,
+    });
+  }
+}
+
+function exportAzureCloudTypes(context: SdkContext, rootIndexFile: SourceFile) {
+  if (context.arm) {
+    // AzureClouds is an enum (runtime value), AzureSupportedClouds is a type alias
+    addExportsToRootIndexFile(rootIndexFile, [resolveReference(CloudSettingHelpers.AzureClouds)]);
+    addExportsToRootIndexFile(
+      rootIndexFile,
+      [resolveReference(CloudSettingHelpers.AzureSupportedClouds)],
+      true,
+    );
+  }
+}
+
+function exportRestErrorTypes(context: SdkContext, rootIndexFile: SourceFile) {
+  if (!isAzurePackage({ options: context.rlcOptions })) {
+    return;
+  }
+  const existingExports = getExistingExports(rootIndexFile);
+  const namedExports = ["RestError", "isRestError"].filter((name) => !existingExports.has(name));
+  if (namedExports.length > 0) {
+    rootIndexFile.addExportDeclaration({
+      moduleSpecifier: "@azure/core-rest-pipeline",
+      namedExports,
+    });
+  }
+}
+
+/**
+ * This is a temporary solution for adding paging exports. Eventually we will have the binder generate the exports automatically.
+ */
+function exportPagingTypes(context: SdkContext, rootIndexFile: SourceFile) {
+  if (!hasPaging(context)) {
+    return;
+  }
+
+  addExportsToRootIndexFile(
+    rootIndexFile,
+    [
+      resolveReference(PagingHelpers.PageSettings),
+      resolveReference(PagingHelpers.ContinuablePage),
+      resolveReference(PagingHelpers.PagedAsyncIterableIterator),
+    ],
+    true,
+  );
+}
+
+function hasPaging(context: SdkContext): boolean {
+  return context.sdkPackage.clients.some((client) => {
+    const methodMap = getMethodHierarchiesMap(context, client);
+    for (const [_, operations] of methodMap) {
+      if (operations.some((op) => op.kind === "paging" || op.kind === "lropaging")) {
+        return true;
+      }
+    }
+    return false;
+  });
+}
+
+function exportFileContentsType(context: SdkContext, rootIndexFile: SourceFile) {
+  const hasMultipartFileParts = context.sdkPackage.models.some((x) =>
+    x.properties.some((y) => y.kind === "property" && y.serializationOptions.multipart?.isFilePart),
+  );
+
+  if (hasMultipartFileParts) {
+    addExportsToRootIndexFile(
+      rootIndexFile,
+      [
+        resolveReference(MultipartHelpers.FileContents),
+        resolveReference(PlatformTypeHelpers.NodeReadableStream),
+      ],
+      true,
+    );
+  }
+}
+
+function getExistingExports(rootIndexFile: SourceFile): Set<string> {
+  return new Set(
+    rootIndexFile
+      .getExportDeclarations()
+      .flatMap((exportDecl) =>
+        exportDecl.getNamedExports().map((namedExport) => namedExport.getName()),
+      ),
+  );
+}
+
+function getNewNamedExports(namedExports: string[], existingExports: Set<string>): string[] {
+  return namedExports.filter((namedExport) => !existingExports.has(namedExport));
+}
+
+function addExportsToRootIndexFile(
+  rootIndexFile: SourceFile,
+  namedExports: string[],
+  isTypeOnly: boolean = false,
+) {
+  const existingExports = getExistingExports(rootIndexFile);
+  const newNamedExports = getNewNamedExports(namedExports, existingExports);
+  if (newNamedExports.length > 0) {
+    rootIndexFile.addExportDeclaration({
+      isTypeOnly,
+      namedExports: newNamedExports,
+    });
+  }
+}
+
+function exportSimplePollerLike(
+  context: SdkContext,
+  clientMap: [string[], SdkClientType<SdkServiceOperation>],
+  indexFile: SourceFile,
+  project: Project,
+  srcPath: string,
+  subfolder: string = "",
+  isTopLevel: boolean = false,
+) {
+  const [_, client] = clientMap;
+
+  const methodMap = getMethodHierarchiesMap(context, client);
+  const hasLro = Array.from(methodMap.values()).some((operations) => {
+    return operations.some(isLroOnlyOperation);
+  });
+  if (!hasLro || context.rlcOptions?.compatibilityLro !== true) {
+    return;
+  }
+  const helperFile = project.getSourceFile(
+    `${srcPath}/${
+      subfolder && subfolder !== "" ? subfolder + "/" : ""
+    }static-helpers/simplePollerHelpers.ts`,
+  );
+  if (!helperFile) {
+    return;
+  }
+  const moduleSpecifier = `./${
+    isTopLevel && subfolder && subfolder !== "" ? subfolder + "/" : ""
+  }static-helpers/simplePollerHelpers.js`;
+  indexFile.addExportDeclaration({
+    isTypeOnly: true,
+    moduleSpecifier,
+    namedExports: ["SimplePollerLike"],
+  });
+}
+
+function exportRestoreHelpers(
+  indexFile: SourceFile,
+  project: Project,
+  srcPath: string,
+  clientName: string,
+  subfolder: string = "",
+  isTopLevel: boolean = false,
+) {
+  const helperFile = project.getSourceFile(
+    `${srcPath}/${subfolder && subfolder !== "" ? subfolder + "/" : ""}restorePollerHelpers.ts`,
+  );
+  if (!helperFile) {
+    return;
+  }
+  const exported = new Set(indexFile.getExportedDeclarations().keys());
+  const allEntries = [...helperFile.getExportedDeclarations().entries()];
+  const moduleSpecifier = `./${
+    isTopLevel && subfolder && subfolder !== "" ? subfolder + "/" : ""
+  }restorePollerHelpers.js`;
+  const renamer = (name: string) => (exported.has(name) ? `${name} as ${clientName}${name}` : name);
+  partitionAndEmitExports(indexFile, moduleSpecifier, allEntries, renamer);
+}
+
+function exportClassicalClient(
+  client: SdkClientType<SdkServiceOperation>,
+  indexFile: SourceFile,
+  subfolder: string,
+  isSubClient: boolean = false,
+) {
+  const clientName = client.name;
+  indexFile.addExportDeclaration({
+    namedExports: [clientName],
+    moduleSpecifier: `./${
+      subfolder && subfolder !== "" && !isSubClient ? subfolder + "/" : ""
+    }${normalizeName(clientName, NameType.File)}.js`,
+  });
+}
+
+export interface ExportModulesOptions {
+  interfaceOnly?: boolean;
+  isTopLevel?: boolean;
+  subfolder?: string;
+  recursive?: boolean;
+}
+
+function exportModules(
+  indexFile: SourceFile,
+  project: Project,
+  srcPath: string,
+  clientName: string,
+  moduleName: string,
+  options: ExportModulesOptions = {
+    interfaceOnly: false,
+    isTopLevel: false,
+    subfolder: "",
+    recursive: false,
+  },
+) {
+  const subfolder = options.subfolder ?? "";
+  let folders: string[];
+  if (options.recursive) {
+    folders = project
+      .getDirectories()
+      .filter((dir) => {
+        const formattedDir = dir.getPath().replace(/\\/g, "/");
+        const targetPath = join(srcPath, subfolder, moduleName).replace(/\\/g, "/");
+        return formattedDir.startsWith(targetPath);
+      })
+      .map((dir) => {
+        return dir.getPath().replace(/\\/g, "/");
+      });
+  } else if (options.isTopLevel && moduleName === "api") {
+    folders = project
+      .getDirectories()
+      .filter((dir) => {
+        const formattedDir = dir.getPath().replace(/\\/g, "/");
+        const targetPath = join(srcPath, subfolder, moduleName).replace(/\\/g, "/");
+        return formattedDir.startsWith(targetPath);
+      })
+      .map((dir) => {
+        return dir.getPath().replace(/\\/g, "/");
+      });
+  } else {
+    folders = [join(srcPath, subfolder, moduleName).replace(/\\/g, "/")];
+  }
+  for (const folder of folders) {
+    const apiFilePattern = join(folder, "index.ts").replace(/\\/g, "/");
+    const modelsFile = project.getSourceFile(apiFilePattern);
+    if (!modelsFile) {
+      continue;
+    }
+
+    const exported = new Set(indexFile.getExportedDeclarations().keys());
+    const serializerOrDeserializerRegex = /.*(Serializer|Deserializer)(_\d+)?$/;
+    const filteredEntries = [...modelsFile.getExportedDeclarations().entries()].filter(
+      (exDeclaration) => {
+        if (exDeclaration[0].startsWith("_")) {
+          return false;
+        }
+        return exDeclaration[1].some((ex) => {
+          if (options.interfaceOnly && ex.getKindName() !== "InterfaceDeclaration") {
+            return false;
+          }
+          if (
+            moduleName === "models" &&
+            ex.getKindName() === "FunctionDeclaration" &&
+            serializerOrDeserializerRegex.test(exDeclaration[0])
+          ) {
+            return false;
+          }
+          if (options.interfaceOnly && options.isTopLevel && exDeclaration[0].endsWith("Context")) {
+            return false;
+          }
+
+          return true;
+        });
+      },
+    );
+    const moduleSpecifier = `.${modelsFile
+      .getFilePath()
+      .replace(indexFile.getDirectoryPath(), "")
+      .replace(/\\/g, "/")
+      .replace(".ts", "")}.js`;
+    const renamer = (name: string) =>
+      exported.has(name) ? `${name} as ${clientName}${name}` : name;
+    partitionAndEmitExports(indexFile, moduleSpecifier, filteredEntries, renamer);
+  }
+}
+
+export function buildSubClientIndexFile(
+  context: SdkContext,
+  clientMap: [string[], SdkClientType<SdkServiceOperation>],
+  emitterOptions: ModularEmitterOptions,
+) {
+  const project = useContext("outputProject");
+  const [_, client] = clientMap;
+  const { subfolder } = getModularClientOptions(clientMap);
+  const srcPath = emitterOptions.modularOptions.sourceRoot;
+  const subClientIndexFile = project.createSourceFile(
+    `${srcPath}/${subfolder && subfolder !== "" ? subfolder + "/" : ""}index.ts`,
+    undefined,
+    { overwrite: true },
+  );
+  const clientName = `${getClassicalClientName(client)}`;
+  const clientFilePath = `${srcPath}/${
+    subfolder && subfolder !== "" ? subfolder + "/" : ""
+  }${normalizeName(clientName, NameType.File)}.ts`;
+  const clientFile = project.getSourceFile(clientFilePath);
+
+  if (!clientFile) {
+    reportDiagnostic(context.program, {
+      code: "client-file-not-found",
+      format: {
+        filePath: clientFilePath,
+      },
+      target: NoTarget,
+    });
+    return; // Skip exporting this client but continue with others
+  }
+
+  exportClassicalClient(client, subClientIndexFile, subfolder ?? "", true);
+  exportSimplePollerLike(context, clientMap, subClientIndexFile, project, srcPath, subfolder);
+  exportRestoreHelpers(subClientIndexFile, project, srcPath, clientName, subfolder);
+  exportModules(subClientIndexFile, project, srcPath, clientName, "api", {
+    subfolder,
+    interfaceOnly: true,
+    recursive: true,
+  });
+  exportModules(subClientIndexFile, project, srcPath, clientName, "classic", {
+    subfolder,
+  });
+}

package/src/modular/build-subpath-index.ts

@@ -0,0 +1,152 @@
+import { SdkClientType, SdkServiceOperation } from "@azure-tools/typespec-client-generator-core";
+import { ModularEmitterOptions } from "./interfaces.js";
+
+import { join } from "path";
+import { Node, SourceFile } from "ts-morph";
+import { useContext } from "../context-manager.js";
+import { getModularClientOptions } from "../utils/client-utils.js";
+
+export interface buildSubpathIndexFileOptions {
+  exportIndex?: boolean;
+  interfaceOnly?: boolean;
+  recursive?: boolean;
+}
+
+export function buildSubpathIndexFile(
+  emitterOptions: ModularEmitterOptions,
+  subpath: string,
+  clientMap?: [string[], SdkClientType<SdkServiceOperation>],
+  options: buildSubpathIndexFileOptions = {},
+) {
+  const project = useContext("outputProject");
+  const subfolder = clientMap ? (getModularClientOptions(clientMap).subfolder ?? "") : "";
+  const srcPath = emitterOptions.modularOptions.sourceRoot;
+  // Skip to export these files because they are used internally.
+  const skipFiles = ["pagingHelpers.ts", "pollingHelpers.ts"];
+  let folders: string[];
+  if (options.recursive) {
+    folders = project
+      .getDirectories()
+      .filter((dir) => {
+        const formattedDir = dir.getPath().replace(/\\/g, "/");
+        const targetPath = join(srcPath, subfolder, subpath).replace(/\\/g, "/");
+        return (
+          formattedDir.startsWith(targetPath) && !project.getSourceFile(`${formattedDir}/index.ts`)
+        );
+      })
+      .map((dir) => {
+        return dir.getPath().replace(/\\/g, "/");
+      });
+  } else {
+    folders = [join(srcPath, subfolder, subpath).replace(/\\/g, "/")];
+  }
+  for (const folder of folders) {
+    const apiFilePattern = subpath === "models" ? join(folder, "models.ts") : folder;
+    const apiFiles = project.getSourceFiles().filter((file) => {
+      if (subpath === "api" && options.recursive) {
+        return file.getDirectoryPath().replace(/\\/g, "/") === apiFilePattern.replace(/\\/g, "/");
+      }
+      return file
+        .getFilePath()
+        .replace(/\\/g, "/")
+        .startsWith(
+          apiFilePattern.replace(/\\/g, "/") + (apiFilePattern.endsWith("models.ts") ? "" : "/"),
+        );
+    });
+    if (apiFiles.length === 0) {
+      continue;
+    }
+    const indexFile = project.createSourceFile(`${folder}/index.ts`);
+    for (const file of apiFiles) {
+      const filePath = file.getFilePath();
+      const serializerOrDeserializerRegex = /.*(Serializer|Deserializer)(_\d+)?$/;
+      if (!options.exportIndex && filePath.endsWith("index.ts")) {
+        continue;
+      }
+      // Skip to export these files because they are used internally.
+      if (skipFiles.some((skipFile) => filePath.endsWith(skipFile))) {
+        continue;
+      }
+      if (filePath === indexFile.getFilePath()) {
+        continue;
+      }
+
+      let filteredDeclarations = [...file.getExportedDeclarations().entries()].filter(
+        (exDeclaration) => {
+          if (exDeclaration[0].startsWith("_")) {
+            return false;
+          }
+          return exDeclaration[1].some((ex) => {
+            if (options.interfaceOnly && ex.getKindName() !== "InterfaceDeclaration") {
+              return false;
+            }
+
+            // skip exporting serializers for models
+            if (
+              subpath === "models" &&
+              ex.getKindName() === "FunctionDeclaration" &&
+              serializerOrDeserializerRegex.test(exDeclaration[0])
+            ) {
+              return false;
+            }
+
+            return true;
+          });
+        },
+      );
+      // Skip to export PagedResult and BuildPagedAsyncIteratorOptions
+      if (filePath.endsWith("pagingTypes.ts")) {
+        filteredDeclarations = filteredDeclarations.filter(
+          ([name]) => !["PagedResult", "BuildPagedAsyncIteratorOptions"].includes(name),
+        );
+      }
+      if (filteredDeclarations.length > 0) {
+        const moduleSpecifier = `.${filePath
+          .replace(indexFile.getDirectoryPath(), "")
+          .replace(/\\/g, "/")
+          .replace(".ts", "")}.js`;
+        partitionAndEmitExports(indexFile, moduleSpecifier, filteredDeclarations);
+      }
+    }
+  }
+}
+
+export function isTypeOnlyNode(node: Node): boolean {
+  const kind = node.getKindName();
+  return kind === "InterfaceDeclaration" || kind === "TypeAliasDeclaration";
+}
+
+/**
+ * Partition declaration entries into type-only and value exports in a single pass,
+ * then emit both export declarations on the index file.
+ */
+export function partitionAndEmitExports(
+  indexFile: SourceFile,
+  moduleSpecifier: string,
+  entries: [string, Node[]][],
+  mapName: (name: string) => string = (n) => n,
+): void {
+  const typeOnlyExports: string[] = [];
+  const valueExports: string[] = [];
+  for (const [name, decls] of entries) {
+    const mapped = mapName(name);
+    if (decls.every(isTypeOnlyNode)) {
+      typeOnlyExports.push(mapped);
+    } else {
+      valueExports.push(mapped);
+    }
+  }
+  if (typeOnlyExports.length > 0) {
+    indexFile.addExportDeclaration({
+      isTypeOnly: true,
+      moduleSpecifier,
+      namedExports: typeOnlyExports,
+    });
+  }
+  if (valueExports.length > 0) {
+    indexFile.addExportDeclaration({
+      moduleSpecifier,
+      namedExports: valueExports,
+    });
+  }
+}

package/src/modular/emit-logger-file.ts

@@ -0,0 +1,23 @@
+import { useContext } from "../context-manager.js";
+import { ModularEmitterOptions } from "./interfaces.js";
+
+export function emitLoggerFile(emitterOptions: ModularEmitterOptions, srcPath: string = "src") {
+  const project = useContext("outputProject");
+  if (emitterOptions.options.flavor !== "azure") {
+    return;
+  }
+
+  const sourceFile = project.createSourceFile(`${srcPath}/logger.ts`, "", {
+    overwrite: true,
+  });
+
+  sourceFile.addImportDeclaration({
+    namedImports: ["createClientLogger"],
+    moduleSpecifier: "@azure/logger",
+  });
+
+  const name =
+    emitterOptions.options.packageDetails?.nameWithoutScope ??
+    emitterOptions.options.packageDetails?.name;
+  sourceFile.addStatements(`export const logger = createClientLogger("${name}");`);
+}

package/src/modular/emit-models-options.ts

@@ -0,0 +1,56 @@
+import * as path from "path";
+
+import { ModularEmitterOptions } from "./interfaces.js";
+
+import { SdkClientType, SdkServiceOperation } from "@azure-tools/typespec-client-generator-core";
+import { useContext } from "../context-manager.js";
+import { NameType, normalizeName } from "../rlc-common/index.js";
+import { getModularClientOptions } from "../utils/client-utils.js";
+import { SdkContext } from "../utils/interfaces.js";
+import { getMethodHierarchiesMap } from "../utils/operation-util.js";
+import { buildOperationOptions } from "./build-operations.js";
+
+// ====== UTILITIES ======
+
+export function buildApiOptions(
+  context: SdkContext,
+  clientMap: [string[], SdkClientType<SdkServiceOperation>],
+  emitterOptions: ModularEmitterOptions,
+) {
+  const project = useContext("outputProject");
+  const [_, client] = clientMap;
+  const modelOptionsFiles = [];
+  const { subfolder } = getModularClientOptions(clientMap);
+  const methodMap = getMethodHierarchiesMap(context, client);
+  for (const [prefixKey, operations] of methodMap) {
+    const prefixes = prefixKey.split("/");
+    const modelOptionsFile = project.createSourceFile(
+      path.join(
+        emitterOptions.modularOptions.sourceRoot,
+        subfolder ?? "",
+        `api`,
+        ...prefixes.map((p) => normalizeName(p, NameType.File)),
+        "options.ts",
+      ),
+      undefined,
+      {
+        overwrite: true,
+      },
+    );
+    operations.forEach((o) => {
+      buildOperationOptions(context, [prefixes, o], modelOptionsFile);
+    });
+    modelOptionsFile
+      .getImportDeclarations()
+      .filter((id) => {
+        return id.isModuleSpecifierRelative() && !id.getModuleSpecifierValue().endsWith(".js");
+      })
+      .map((id) => {
+        id.setModuleSpecifier(id.getModuleSpecifierValue() + ".js");
+        return id;
+      });
+    modelOptionsFiles.push(modelOptionsFile);
+  }
+
+  return modelOptionsFiles;
+}