@azure-tools/typespec-ts 0.54.0 → 0.54.2

package/src/rlc-common/metadata/package-json/build-azure-monorepo-package.ts

@@ -0,0 +1,199 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { AzurePackageInfoConfig, getAzureCommonPackageInfo } from "./azure-package-common.js";
+import { getCommonPackageScripts, getPackageCommonInfo } from "./package-common.js";
+
+export interface AzureMonorepoInfoConfig extends AzurePackageInfoConfig {
+  monorepoPackageDirectory?: string;
+  clientFilePaths: string[];
+  clientContextPaths?: string[];
+}
+
+/**
+ * Builds the package.json for an Azure package that will be hosted in the azure-sdk-for-js mono repo.
+ */
+export function buildAzureMonorepoPackage(config: AzureMonorepoInfoConfig) {
+  const packageInfo = {
+    ...getAzureMonorepoPackageInfo(config),
+    ...getAzureMonorepoDependencies(config),
+    scripts: getAzureMonorepoScripts(config),
+    ...getSampleMetadata(config),
+  };
+
+  return packageInfo;
+}
+
+/**
+ * Builds the dependencies for an Azure package that will be hosted in the azure-sdk-for-js mono repo.
+ */
+export function getAzureMonorepoDependencies(config: AzureMonorepoInfoConfig) {
+  const { hasLro, dependencies, withTests } = config;
+
+  // revert this change after sdk repo update.
+  const runtimeDeps = {
+    ...dependencies,
+    "@azure-rest/core-client": "^2.3.1",
+    ...(hasLro && {
+      "@azure/abort-controller": "^2.1.2",
+    }),
+    "@azure/core-auth": "^1.9.0",
+    ...(hasLro && {
+      "@azure/core-lro": "^3.1.0",
+    }),
+    "@azure/core-rest-pipeline": "^1.20.0",
+    "@azure/core-util": "^1.12.0",
+    "@azure/logger": "^1.2.0",
+    tslib: "^2.8.1",
+  };
+
+  const testDeps = withTests
+    ? {
+        "@vitest/browser-playwright": "catalog:testing",
+        "@vitest/coverage-istanbul": "catalog:testing",
+        dotenv: "catalog:testing",
+        playwright: "catalog:testing",
+        typescript: "catalog:",
+        vitest: "catalog:testing",
+      }
+    : {
+        typescript: "catalog:",
+      };
+
+  return {
+    dependencies: runtimeDeps,
+    devDependencies: {
+      "@azure-tools/test-credential": "workspace:^",
+      "@azure-tools/test-recorder": "workspace:^",
+      "@azure-tools/test-utils-vitest": "workspace:^",
+      "@azure/dev-tool": "workspace:^",
+      "@azure/eslint-plugin-azure-sdk": "workspace:^",
+      "@azure/identity": "catalog:internal",
+      "@types/node": "catalog:",
+      "cross-env": "catalog:",
+      eslint: "catalog:",
+      prettier: "catalog:",
+      rimraf: "catalog:",
+      ...(config.specSource === "Swagger" && {
+        autorest: "catalog:",
+      }),
+      ...testDeps,
+    },
+  };
+}
+
+/**
+ * Build the common package.json config for an Azure package that will be hosted in the azure-sdk-for-js mono repo.
+ */
+export function getAzureMonorepoPackageInfo(config: AzureMonorepoInfoConfig): Record<string, any> {
+  const commonPackageInfo = getPackageCommonInfo(config);
+  const repositoryDirectory = config.monorepoPackageDirectory ?? "sdk/";
+
+  return {
+    ...commonPackageInfo,
+    ...getAzureCommonPackageInfo(config),
+    "sdk-type": `${config.azureArm ? "mgmt" : "client"}`,
+    repository: {
+      type: "git",
+      url: "git+https://github.com/Azure/azure-sdk-for-js",
+      directory: repositoryDirectory,
+    },
+    bugs: {
+      url: "https://github.com/Azure/azure-sdk-for-js/issues",
+    },
+    ...(config.monorepoPackageDirectory && {
+      homepage: `https://github.com/Azure/azure-sdk-for-js/tree/main/${config.monorepoPackageDirectory}/README.md`,
+    }),
+    prettier: "@azure/eslint-plugin-azure-sdk/prettier.json",
+    "//metadata": getMetadataInfo(config),
+  };
+}
+
+function getSampleMetadata({ name, version, withSamples }: AzureMonorepoInfoConfig) {
+  if (!withSamples) {
+    return {};
+  }
+
+  let apiRefUrlQueryParameter: string = "";
+  if (version.includes("beta")) {
+    apiRefUrlQueryParameter = "?view=azure-node-preview";
+  }
+
+  return {
+    "//sampleConfiguration": {
+      productName: name,
+      productSlugs: ["azure"],
+      disableDocsMs: true,
+      apiRefLink: `https://learn.microsoft.com/javascript/api/${name}${apiRefUrlQueryParameter}`,
+    },
+  };
+}
+
+function addSwaggerMetadata(metadata: Record<string, any>, specSource: "Swagger" | "TypeSpec") {
+  if (specSource !== "Swagger") {
+    return;
+  }
+
+  metadata["constantPaths"].push({
+    path: "swagger/README.md",
+    prefix: "package-version",
+  });
+}
+
+function getAzureMonorepoScripts(config: AzureMonorepoInfoConfig) {
+  const esmScripts = getEsmScripts(config);
+  const skipLinting = config.azureArm && config.isModularLibrary;
+  const buildSampleScripts = config.azureArm
+    ? "tsc -p config/tsconfig.samples.json && dev-tool samples publish -f"
+    : "tsc -p config/tsconfig.samples.json";
+  return {
+    ...getCommonPackageScripts(),
+    "build:samples": config.withSamples ? buildSampleScripts : "echo skipped",
+    "check-format": `prettier --list-different --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore "src/**/*.{ts,cts,mts}" "test/**/*.{ts,cts,mts}" "*.{js,cjs,mjs,json}" ${
+      config.withSamples ? '"samples-dev/*.ts"' : ""
+    }`,
+    clean: "rimraf --glob dist dist-browser dist-esm test-dist temp types *.tgz *.log",
+    "execute:samples": config.withSamples ? "dev-tool samples run samples-dev" : "echo skipped",
+    "extract-api": "rimraf review && dev-tool run extract-api",
+    format: `prettier --write --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore "src/**/*.{ts,cts,mts}" "test/**/*.{ts,cts,mts}" "*.{js,cjs,mjs,json}" ${
+      config.withSamples ? '"samples-dev/*.ts"' : ""
+    }`,
+    "generate:client": "echo skipped",
+    "test:browser": "dev-tool run test:vitest --browser",
+    "lint:fix": skipLinting
+      ? "echo skipped"
+      : "eslint package.json src test --fix --fix-type [problem,suggestion]",
+    lint: skipLinting ? "echo skipped" : "eslint package.json src test",
+    pack: `pnpm pack 2>&1`,
+    ...esmScripts,
+    "update-snippets": "dev-tool run update-snippets",
+  };
+}
+
+function getEsmScripts({ moduleKind }: AzureMonorepoInfoConfig) {
+  if (moduleKind !== "esm") {
+    return {};
+  }
+
+  return {
+    build: "npm run clean && dev-tool run build-package && dev-tool run extract-api",
+    "test:node": "dev-tool run test:vitest",
+    test: "tsc -b --noEmit && npm run test:node && npm run test:browser",
+  };
+}
+
+function getMetadataInfo(config: AzureMonorepoInfoConfig) {
+  const metadata: Record<string, any> = {
+    constantPaths: [],
+  };
+  const paths = config.isModularLibrary ? config.clientContextPaths : config.clientFilePaths;
+  addSwaggerMetadata(metadata, config.specSource);
+  for (const path of paths ?? []) {
+    metadata["constantPaths"].push({
+      path: path,
+      prefix: "userAgentInfo",
+    });
+  }
+
+  return metadata;
+}

package/src/rlc-common/metadata/package-json/build-azure-standalone-package.ts

@@ -0,0 +1,123 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  AzurePackageInfoConfig,
+  getAzureCommonPackageInfo,
+  getAzurePackageDependencies,
+  getAzurePackageDevDependencies,
+} from "./azure-package-common.js";
+import { getCommonPackageScripts, getPackageCommonInfo } from "./package-common.js";
+
+/**
+ * Builds the package.json for an Azure package that won't be hosted in the azure-sdk-for-js repo.
+ */
+export function buildAzureStandalonePackage(config: AzurePackageInfoConfig) {
+  const packageInfo = {
+    ...getAzureStandalonePackageInfo(config),
+    ...getAzureStandaloneDependencies(config),
+    scripts: getAzureStandaloneScripts(config),
+  };
+
+  return packageInfo;
+}
+
+function getAzureStandalonePackageInfo(config: AzurePackageInfoConfig): Record<string, any> {
+  const commonPackageInfo = getPackageCommonInfo(config);
+
+  return {
+    ...commonPackageInfo,
+    ...getAzureCommonPackageInfo(config),
+  };
+}
+
+function getAzureStandaloneDependencies(config: AzurePackageInfoConfig): Record<string, any> {
+  return {
+    dependencies: {
+      ...getAzurePackageDependencies(config),
+    },
+    devDependencies: {
+      ...getStandaloneDevDependencies(config),
+      "@microsoft/api-extractor": "^7.40.3",
+      rimraf: "^5.0.5",
+      mkdirp: "^3.0.1",
+    },
+  };
+}
+
+function getStandaloneDevDependencies(config: AzurePackageInfoConfig) {
+  return {
+    ...getAzurePackageDevDependencies(config),
+    "@microsoft/api-extractor": "^7.40.3",
+    ...getStandaloneCjsDevDependencies(config),
+  };
+}
+
+function getStandaloneCjsDevDependencies(config: AzurePackageInfoConfig) {
+  if (config.moduleKind !== "cjs") {
+    return {};
+  }
+
+  return {
+    "@rollup/plugin-commonjs": "^24.0.0",
+    "@rollup/plugin-json": "^6.0.0",
+    "@rollup/plugin-multi-entry": "^6.0.0",
+    "@rollup/plugin-node-resolve": "^13.1.3",
+    ...(config.moduleKind === "cjs" && config.withTests && { "cross-env": "^7.0.2" }),
+    rollup: "^2.66.1",
+    "rollup-plugin-sourcemaps": "^0.6.3",
+    "uglify-js": "^3.4.9",
+  };
+}
+
+function getAzureStandaloneScripts(config: AzurePackageInfoConfig): Record<string, any> {
+  const testScripts = {
+    "test:browser": "karma start --single-run",
+    "test:node": `nyc mocha -r esm --require source-map-support/register --timeout 5000000 --full-trace "dist-esm/test/{,!(browser)/**/}*.spec.js"`,
+    test: "npm run test:node && npm run test:browser",
+  };
+  return {
+    ...getCommonPackageScripts(),
+    clean: "rimraf --glob dist dist-browser dist-esm test-dist temp types *.tgz *.log",
+    ...(config.withTests && testScripts),
+    ...getCjsScripts(config),
+    ...getEsmScripts(config),
+  };
+}
+
+function getCjsScripts(config: AzurePackageInfoConfig): Record<string, any> {
+  if (config.moduleKind !== "cjs") {
+    return {};
+  }
+
+  const testScripts = {
+    "build:test": "tsc -p . && rollup -c 2>&1",
+    "build:browser": "tsc -p . && cross-env ONLY_BROWSER=true rollup -c 2>&1",
+    "build:node": "tsc -p . && cross-env ONLY_NODE=true rollup -c 2>&1",
+  };
+
+  return {
+    build:
+      "npm run clean && tsc && rollup -c 2>&1 && npm run minify && mkdirp ./review && npm run extract-api",
+    ...(config.withTests && testScripts),
+    minify:
+      "uglifyjs -c -m --comments --source-map \"content='./dist/index.js.map'\" -o ./dist/index.min.js ./dist/index.js",
+  };
+}
+
+function getEsmScripts(config: AzurePackageInfoConfig): Record<string, any> {
+  if (config.moduleKind !== "esm") {
+    return {};
+  }
+
+  const testScripts = {
+    test: "npm run clean && tshy && npm run unit-test:node && npm run unit-test:browser && npm run integration-test",
+    "test:node": "vitest -c vitest.config.ts",
+    "test:browser": "vitest -c vitest.browser.config.ts",
+  };
+
+  return {
+    build: "npm run clean && tshy && npm run extract-api",
+    ...(config.withTests && testScripts),
+  };
+}

package/src/rlc-common/metadata/package-json/build-flavorless-package.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  PackageCommonInfoConfig,
+  commonPackageDependencies,
+  getCommonPackageDevDependencies,
+  getCommonPackageScripts,
+  getPackageCommonInfo,
+} from "./package-common.js";
+
+/**
+ * Builds the package.json for a flavorless package.
+ */
+export function buildFlavorlessPackage(config: PackageCommonInfoConfig) {
+  const packageInfo = {
+    ...getFlavorlessPackageInfo(config),
+    scripts: getFlavorlessScripts(config),
+    devDependencies: {
+      ...getCommonPackageDevDependencies(config),
+      "@microsoft/api-extractor": "^7.40.3",
+      rimraf: "^5.0.5",
+      mkdirp: "^3.0.1",
+    },
+    dependencies: {
+      ...commonPackageDependencies,
+      "@typespec/ts-http-runtime": "0.1.0",
+    },
+  };
+
+  return packageInfo;
+}
+
+function getFlavorlessPackageInfo(config: PackageCommonInfoConfig): Record<string, any> {
+  const commonPackageInfo = getPackageCommonInfo(config);
+
+  return {
+    ...commonPackageInfo,
+  };
+}
+
+function getFlavorlessScripts(config: PackageCommonInfoConfig) {
+  return {
+    ...getCommonPackageScripts(),
+    ...getCjsScripts(config),
+    ...getEsmScripts(config),
+  };
+}
+
+function getCjsScripts({ moduleKind }: PackageCommonInfoConfig) {
+  if (moduleKind !== "cjs") {
+    return {};
+  }
+
+  return {
+    build: "npm run clean && tsc && npm run extract-api",
+  };
+}
+
+function getEsmScripts({ moduleKind }: PackageCommonInfoConfig) {
+  if (moduleKind !== "esm") {
+    return {};
+  }
+
+  return {
+    build: "npm run clean && tshy && npm run extract-api",
+  };
+}

package/src/rlc-common/metadata/package-json/package-common.ts

@@ -0,0 +1,235 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export interface PackageCommonInfoConfig {
+  name: string;
+  nameWithoutScope?: string;
+  version: string;
+  description: string;
+  moduleKind: "esm" | "cjs";
+  withTests: boolean;
+  withSamples: boolean;
+  exports?: Record<string, any>;
+  dependencies?: Record<string, string>;
+  azureArm?: boolean;
+  isModularLibrary?: boolean;
+  azureSdkForJs?: boolean;
+  /**
+   * When true, generates React Native build targets (dist/react-native, exports condition).
+   * Defaults to false. Only applicable when azureSdkForJs is true.
+   */
+  generateReactNativeTarget?: boolean;
+}
+
+/**
+ * Common package.json config for a package.
+ */
+export function getPackageCommonInfo(config: PackageCommonInfoConfig) {
+  const { name, version, description } = config;
+
+  return {
+    name,
+    version,
+    description,
+    engines: {
+      node: ">=20.0.0",
+    },
+    sideEffects: false,
+    autoPublish: false,
+    ...getEntryPointInformation(config),
+  };
+}
+
+export const commonPackageDependencies = {
+  tslib: "^2.6.2",
+};
+
+export function getCommonPackageDevDependencies(config: PackageCommonInfoConfig) {
+  return {
+    "@types/node": "^20.0.0",
+    eslint: "^9.9.0",
+    typescript: "~5.8.2",
+    ...getEsmDevDependencies(config),
+  };
+}
+
+function getEsmDevDependencies({ moduleKind, azureSdkForJs }: PackageCommonInfoConfig) {
+  if (moduleKind !== "esm") {
+    return {};
+  }
+  // Azure monorepo packages use warp (invoked via dev-tool), no tshy needed
+  if (azureSdkForJs) {
+    return {};
+  }
+  return {
+    tshy: "^2.0.0",
+  };
+}
+
+function getEntryPointInformation(config: PackageCommonInfoConfig) {
+  return {
+    ...getCjsEntrypointInformation(config),
+    ...getEsmEntrypointInformation(config),
+  };
+}
+
+function getCjsEntrypointInformation({
+  name,
+  nameWithoutScope,
+  moduleKind,
+  withTests,
+  withSamples,
+}: PackageCommonInfoConfig) {
+  if (moduleKind !== "cjs") {
+    return;
+  }
+
+  const types =
+    withTests || withSamples
+      ? `./types/src/${nameWithoutScope ?? name}.d.ts`
+      : `./types/${nameWithoutScope ?? name}.d.ts`;
+  const main = withTests || withSamples ? "dist/src/index.js" : "dist/index.js";
+  return {
+    main,
+    module: withTests || withSamples ? "./dist-esm/src/index.js" : "./dist-esm/index.js",
+    types,
+  };
+}
+
+function getEsmEntrypointInformation(config: PackageCommonInfoConfig) {
+  if (config.moduleKind !== "esm") {
+    return;
+  }
+
+  // Azure monorepo packages use warp instead of tshy
+  if (config.azureSdkForJs) {
+    const result: Record<string, any> = {
+      type: "module",
+      main: "./dist/commonjs/index.js",
+      module: "./dist/esm/index.js",
+      types: "./dist/commonjs/index.d.ts",
+      browser: "./dist/browser/index.js",
+      imports: {
+        "#platform/*": {
+          browser: "./src/*-browser.mts",
+          default: "./src/*.ts",
+        } as Record<string, string>,
+      },
+      exports: resolveWarpExports(config.exports, config.generateReactNativeTarget),
+    };
+
+    if (config.generateReactNativeTarget) {
+      result["react-native"] = "./dist/react-native/index.js";
+      (result["imports"]["#platform/*"] as Record<string, string>)["react-native"] =
+        "./src/*-react-native.mts";
+      // Reorder so react-native comes before default
+      const importsEntry = result["imports"]["#platform/*"] as Record<string, string>;
+      result["imports"]["#platform/*"] = {
+        browser: importsEntry["browser"],
+        "react-native": importsEntry["react-native"],
+        default: importsEntry["default"],
+      };
+    }
+
+    return result;
+  }
+
+  // Non-monorepo packages use tshy which manages polyfill resolution
+  // via esmDialects — do NOT add imports here.
+  const result: Record<string, any> = {
+    tshy: getTshyConfig(config),
+    type: "module",
+    browser: "./dist/browser/index.js",
+  };
+
+  if (config.generateReactNativeTarget) {
+    result["react-native"] = "./dist/react-native/index.js";
+  }
+
+  return result;
+}
+
+/**
+ * Resolve source-level exports to dist-level exports for warp.
+ * Converts { ".": "./src/index.ts" } to the nested condition map with
+ * browser/import/require conditions pointing to dist/ paths.
+ */
+export function resolveWarpExports(
+  sourceExports?: Record<string, any>,
+  includeReactNative?: boolean,
+): Record<string, any> {
+  const exports: Record<string, any> = {};
+  const allExports: Record<string, string> = {
+    "./package.json": "./package.json",
+    ".": "./src/index.ts",
+    ...sourceExports,
+  };
+
+  for (const [subpath, sourcePath] of Object.entries(allExports)) {
+    // Pass-through entries (e.g. "./package.json": "./package.json")
+    if (!/\.ts$/.test(sourcePath)) {
+      exports[subpath] = sourcePath;
+      continue;
+    }
+
+    // Convert source path to dist path: "./src/foo/index.ts" -> "foo/index"
+    const relPath = sourcePath.replace(/^\.\/src\//, "").replace(/\.ts$/, "");
+
+    const exportEntry: Record<string, any> = {
+      browser: {
+        types: `./dist/browser/${relPath}.d.ts`,
+        default: `./dist/browser/${relPath}.js`,
+      },
+    };
+
+    if (includeReactNative) {
+      exportEntry["react-native"] = {
+        types: `./dist/react-native/${relPath}.d.ts`,
+        default: `./dist/react-native/${relPath}.js`,
+      };
+    }
+
+    exportEntry["import"] = {
+      types: `./dist/esm/${relPath}.d.ts`,
+      default: `./dist/esm/${relPath}.js`,
+    };
+
+    exportEntry["require"] = {
+      types: `./dist/commonjs/${relPath}.d.ts`,
+      default: `./dist/commonjs/${relPath}.js`,
+    };
+
+    exports[subpath] = exportEntry;
+  }
+
+  return exports;
+}
+
+export function getTshyConfig(config: PackageCommonInfoConfig) {
+  const { exports = {} } = config;
+  const esmDialects = config.generateReactNativeTarget ? ["browser", "react-native"] : ["browser"];
+  const tshyConfig: Record<string, any> = {
+    exports: {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts",
+      ...exports,
+    },
+    dialects: ["esm", "commonjs"],
+    esmDialects,
+    selfLink: false,
+  };
+  if (config.azureSdkForJs) {
+    tshyConfig["project"] = "../../../tsconfig.src.build.json";
+  }
+  return tshyConfig;
+}
+
+export function getCommonPackageScripts() {
+  return {
+    clean: "rimraf --glob dist dist-browser dist-esm test-dist temp types *.tgz *.log",
+    "extract-api": "rimraf review && mkdirp ./review && api-extractor run --local",
+    pack: "npm pack 2>&1",
+    lint: "eslint package.json api-extractor.json src",
+    "lint:fix": "eslint package.json api-extractor.json src --fix --fix-type [problem,suggestion]",
+  };
+}

package/src/rlc-common/test/build-karma-config.ts

@@ -0,0 +1,12 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { RLCModel } from "../interfaces.js";
+import { karmaConfig } from "./template.js";
+
+export function buildKarmaConfigFile(_model: RLCModel) {
+  return {
+    path: "karma.conf.js",
+    content: hbs.compile(karmaConfig, { noEscape: true })({}),
+  };
+}

package/src/rlc-common/test/build-recorded-client.ts

@@ -0,0 +1,18 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { RLCModel } from "../interfaces.js";
+import { recordedClientContent } from "./template.js";
+
+export function buildRecordedClientFile(model: RLCModel) {
+  const recordedClientFileContents = hbs.compile(recordedClientContent, {
+    noEscape: true,
+  });
+  return {
+    path: "test/public/utils/recordedClient.ts",
+    content: recordedClientFileContents({
+      isEsm: model.options?.moduleKind === "esm",
+      isCjs: model.options?.moduleKind === "cjs",
+    }),
+  };
+}

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

@@ -0,0 +1,15 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { RLCModel } from "../interfaces.js";
+import { sampleTestContent } from "./template.js";
+
+export function buildSampleTest(model: RLCModel) {
+  return {
+    path: "test/public/sampleTest.spec.ts",
+    content: hbs.compile(sampleTestContent, { noEscape: true })({
+      isEsm: model.options?.moduleKind === "esm",
+      isCjs: model.options?.moduleKind === "cjs",
+    }),
+  };
+}