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

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/emit-util.ts

@@ -0,0 +1,91 @@
+import { CompilerHost, getDirectoryPath, joinPaths, NoTarget, Program } from "@typespec/compiler";
+import { format } from "prettier";
+import { prettierJSONOptions, prettierTypeScriptOptions, reportDiagnostic } from "../lib.js";
+import {
+  buildSchemaTypes,
+  ContentBuilder,
+  File,
+  isAzurePackage,
+  RLCModel,
+} from "../rlc-common/index.js";
+
+export async function emitModels(rlcModels: RLCModel, program: Program) {
+  const schemaOutput = buildSchemaTypes(rlcModels);
+  const isAzureFlavor = isAzurePackage(rlcModels);
+  if (schemaOutput) {
+    const { inputModelFile, outputModelFile } = schemaOutput;
+    if (inputModelFile) {
+      await emitFile(inputModelFile, program, isAzureFlavor);
+    }
+    if (outputModelFile) {
+      await emitFile(outputModelFile, program, isAzureFlavor);
+    }
+  }
+}
+
+export async function emitContentByBuilder(
+  program: Program,
+  builderFnOrList: ContentBuilder | ContentBuilder[],
+  rlcModels: RLCModel,
+  emitterOutputDir?: string,
+) {
+  if (!Array.isArray(builderFnOrList)) {
+    builderFnOrList = [builderFnOrList];
+  }
+  const isAzureFlavor = isAzurePackage(rlcModels);
+  for (const builderFn of builderFnOrList) {
+    let contentFiles: File[] | File | undefined = builderFn(rlcModels);
+    if (!contentFiles) {
+      continue;
+    }
+    if (!Array.isArray(contentFiles)) {
+      contentFiles = [contentFiles];
+    }
+    for (const file of contentFiles) {
+      await emitFile(file, program, isAzureFlavor, emitterOutputDir);
+    }
+  }
+}
+
+async function emitFile(
+  file: File,
+  program: Program,
+  isAzureFlavor: boolean,
+  emitterOutputDir?: string,
+) {
+  if (program.compilerOptions.noEmit || program.hasError()) {
+    return;
+  }
+  const host: CompilerHost = program.host;
+  const filePath = joinPaths(emitterOutputDir ?? "", file.path);
+  const isJson = /\.json$/gi.test(filePath);
+  const isSourceCode = /\.(ts|js)$/gi.test(filePath);
+  const microsoftHeader = isAzureFlavor ? `// Copyright (c) Microsoft Corporation.\n` : "";
+  const licenseHeader = `${microsoftHeader}// Licensed under the MIT License.\n`;
+  let prettierFileContent = file.content;
+
+  if (isSourceCode) {
+    prettierFileContent = `${licenseHeader.trimStart()}\n${prettierFileContent}`;
+  }
+  // Format the contents if necessary
+  if (isJson || isSourceCode) {
+    try {
+      prettierFileContent = await format(
+        prettierFileContent,
+        isJson ? prettierJSONOptions : prettierTypeScriptOptions,
+      );
+    } catch (e) {
+      reportDiagnostic(program, {
+        code: "file-formatting-error",
+        format: {
+          filePath: filePath,
+          error: String(e),
+        },
+        target: NoTarget,
+      });
+      // Continue with unformatted content rather than crashing
+    }
+  }
+  await host.mkdirp(getDirectoryPath(filePath));
+  await host.writeFile(filePath, prettierFileContent);
+}

package/src/utils/file-system-utils.ts

@@ -0,0 +1,68 @@
+import { NoTarget, Program, resolvePath } from "@typespec/compiler";
+import { mkdir, readdir, rm, stat } from "fs/promises";
+import { reportDiagnostic } from "../lib.js";
+
+export async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await stat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function emptyDir(dirPath: string): Promise<void> {
+  let entries: string[];
+  try {
+    entries = await readdir(dirPath);
+  } catch {
+    await mkdir(dirPath, { recursive: true });
+    return;
+  }
+
+  await Promise.all(
+    entries.map((entry) => rm(resolvePath(dirPath, entry), { recursive: true, force: true })),
+  );
+}
+
+export async function clearDirectory(
+  dirPath: string,
+  excludeNames: string[] = [],
+  program?: Program,
+): Promise<void> {
+  if (!(await pathExists(dirPath))) {
+    return;
+  }
+
+  // If no exclude names, just use regular emptyDir for efficiency
+  if (excludeNames.length === 0) {
+    await emptyDir(dirPath);
+    return;
+  }
+
+  try {
+    // Get all subdirectories and files
+    const entries = await readdir(dirPath);
+
+    // Filter entries to exclude those that should be preserved
+    const filteredEntries = entries.filter((entry) => {
+      return !excludeNames.includes(entry);
+    });
+
+    // Process each entry
+    for (const entry of filteredEntries) {
+      const entryPath = resolvePath(dirPath, entry);
+      await rm(entryPath, { recursive: true, force: true });
+    }
+  } catch (error) {
+    // If there's an error, fall back to regular emptyDir
+    if (program) {
+      reportDiagnostic(program, {
+        code: "directory-traversal-error",
+        format: { directory: dirPath, error: String(error) },
+        target: NoTarget,
+      });
+    }
+    await emptyDir(dirPath);
+  }
+}