@azure-tools/typespec-ts 0.53.3 → 0.54.0

package/src/rlc-common/interfaces.ts

@@ -0,0 +1,441 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+export interface RLCModel {
+  libraryName: string;
+  srcPath: string;
+  paths: Paths;
+  importInfo: ImportInfo;
+  options?: RLCOptions;
+  schemas: Schema[];
+  apiVersionInfo?: ApiVersionInfo;
+  parameters?: OperationParameter[];
+  responses?: OperationResponse[];
+  helperDetails?: HelperFunctionDetails;
+  urlInfo?: UrlInfo;
+  telemetryOptions?: TelemetryInfo;
+  sampleGroups?: RLCSampleGroup[];
+  rlcSourceDir?: string;
+}
+
+export interface ImportInfo {
+  internalImports: Imports;
+  runtimeImports: Imports;
+}
+
+export type Imports = Record<ImportType, ImportMetadata>;
+
+export type ImportType =
+  /**inner models' imports for parameter and response */
+  | "parameter"
+  | "response"
+  | "rlcIndex"
+  | "modularModel"
+  | "rlcClientFactory"
+  | "rlcClientDefinition"
+  /**common third party imports */
+  | "restClient"
+  | "coreAuth"
+  | "restPipeline"
+  | "coreUtil"
+  | "coreLogger"
+  // this is a fallback import if above imports are not available
+  // mainly used in non-branded scope
+  | "commonFallback"
+  /**azure specific imports */
+  | "azureEslintPlugin"
+  | "azureTestRecorder"
+  | "azureDevTool"
+  | "azureAbortController"
+  | "azureCoreLro"
+  | "azureCorePaging"
+  /**Internal helper imports */
+  | "serializerHelpers";
+
+export interface ImportMetadata {
+  type: ImportType;
+  specifier?: string;
+  version?: string;
+  importsSet?: Set<string>;
+}
+
+/**
+ * A group of samples in operation_id level and they are used to generate in a sample file
+ */
+export interface RLCSampleGroup {
+  filename: string;
+  clientPackageName: string;
+  defaultFactoryName: string;
+  samples: RLCSampleDetail[];
+  importedTypes?: string[];
+}
+
+/**
+ * An independent sample detail and it will be wrapped as a func
+ */
+export interface RLCSampleDetail {
+  /**
+   * metadata for comments
+   */
+  description: string;
+  originalFileLocation?: string;
+  name: string;
+  path: string;
+  defaultFactoryName: string;
+  clientParamAssignments: string[];
+  pathParamAssignments: string[];
+  methodParamAssignments: string[];
+  clientParamNames: string;
+  pathParamNames: string;
+  methodParamNames: "options" | "" | string;
+  method: string;
+  isLRO: boolean;
+  isPaging: boolean;
+  useLegacyLro: boolean;
+}
+
+export interface TelemetryInfo {
+  customRequestIdHeaderName?: string;
+}
+
+export interface PathTemplateApiVersion {
+  value: string;
+  templateName: string;
+}
+
+export interface UrlInfo {
+  endpoint?: string;
+  urlParameters?: PathParameter[];
+  apiVersionInfo?: ApiVersionInfo;
+}
+
+export interface ApiVersionInfo {
+  definedPosition?: ApiVersionPosition;
+  defaultValue?: string;
+  isCrossedVersion?: boolean;
+  required?: boolean;
+}
+
+export type ApiVersionPosition =
+  | "path"
+  | "query"
+  | "baseurl"
+  | "duplicate"
+  | "none";
+export interface HelperFunctionDetails {
+  hasPaging?: boolean;
+  hasLongRunning?: boolean;
+  clientLroOverload?: boolean;
+  pageDetails?: PagingDetails;
+  hasMultiCollection?: boolean;
+  hasPipeCollection?: boolean;
+  hasSsvCollection?: boolean;
+  hasTsvCollection?: boolean;
+  hasCsvCollection?: boolean;
+}
+
+export interface PagingDetails {
+  itemNames: string[];
+  nextLinkNames: string[];
+  isComplexPaging: boolean;
+}
+
+export type Methods = {
+  // could be more than one method if overloading
+  [key: string]: OperationMethod[];
+};
+
+export interface ResponseTypes {
+  success: string[];
+  error: string[];
+}
+
+export interface OperationMethod {
+  optionsName: string;
+  description: string;
+  hasOptionalOptions: boolean;
+  returnType: string;
+  successStatus: string[];
+  responseTypes: ResponseTypes;
+  operationName: string;
+  operationHelperDetail?: OperationHelperDetail;
+}
+export interface PathMetadata {
+  name: string;
+  pathParameters: PathParameter[];
+  methods: Methods;
+  operationGroupName: string;
+  description: string;
+}
+
+export type Paths = Record<string, PathMetadata>;
+
+export type PathParameter = {
+  oriName?: string;
+  name: string;
+  documentName?: string;
+  type: string;
+  description?: string;
+  value?: string | number | boolean;
+  wrapperType?: Schema;
+};
+
+export interface OperationHelperDetail {
+  lroDetails?: OperationLroDetail;
+  isPaging?: boolean;
+}
+
+export const OPERATION_LRO_HIGH_PRIORITY = 0,
+  OPERATION_LRO_LOW_PRIORITY = 1;
+export interface OperationLroDetail {
+  isLongRunning?: boolean;
+  logicalResponseTypes?: ResponseTypes;
+  operationLroOverload?: boolean;
+  /**
+   * This is used to sort the overload order, sorted in descending order
+   */
+  precedence?: number;
+}
+
+/**
+ * Flavor of the package to generate. If "azure", an Azure-branded package should be generated. If left undefined, a package without Azure branding will be generated.
+ */
+export type PackageFlavor = "azure" | undefined;
+
+export interface RLCOptions {
+  /**
+   * Whether to include response headers in the generated response types. If true, the generated response types will include headers as properties.
+   */
+  includeHeadersInResponse?: boolean;
+  includeShortcuts?: boolean;
+  multiClient?: boolean;
+  batch?: any[];
+  packageDetails?: PackageDetails;
+  addCredentials?: boolean;
+  /** Three possiblie values:
+   * - undefined, no credentialScopes and relevant settings would be generated
+   * - [], which means we would generate TokenCredential but no credentialScopes and relevant settings
+   * - ["..."], which means we would generate credentialScopes and relevant settings with the given values
+   */
+  credentialScopes?: string[];
+  credentialKeyHeaderName?: string;
+  customHttpAuthHeaderName?: string;
+  customHttpAuthSharedKeyPrefix?: string;
+  /**
+   * Three possible values:
+   * - undefined, the default behavior which means we would generate metadata if the package.json file is absent
+   * - true, which means we would always generate new files or override existing files
+   * - false, which means we would not generate any files no matter there exists or not
+   */
+  generateMetadata?: boolean;
+  /**
+   * Three possible values:
+   * - undefined, the default behavior which means we would generate test if there is no `test` folder
+   * - true, which means we would always generate new files or override existing files
+   * - false, which means we would not generate any files no matter there exists or not
+   */
+  generateTest?: boolean;
+  generateSample?: boolean;
+  azureSdkForJs?: boolean;
+  azureOutputDirectory?: string;
+  isTypeSpecTest?: boolean;
+  title?: string;
+  dependencyInfo?: DependencyInfo;
+  productDocLink?: string;
+  serviceInfo?: ServiceInfo;
+  azureArm?: boolean;
+  sourceFrom?: "TypeSpec" | "Swagger";
+  isModularLibrary?: boolean;
+  moduleKind?: "esm" | "cjs";
+  enableOperationGroup?: boolean;
+  flavor?: PackageFlavor;
+  enableModelNamespace?: boolean;
+  hierarchyClient?: boolean;
+  compatibilityMode?: boolean;
+  experimentalExtensibleEnums?: boolean;
+  clearOutputFolder?: boolean;
+  ignorePropertyNameNormalize?: boolean;
+  ignoreEnumMemberNameNormalize?: boolean;
+  compatibilityQueryMultiFormat?: boolean;
+  typespecTitleMap?: Record<string, string>;
+  hasSubscriptionId?: boolean;
+  compatibilityLro?: boolean;
+  ignoreNullableOnOptional?: boolean;
+  isMultiService?: boolean;
+  /**
+   * When set to true, non-model return types (arrays, scalars, enums, bytes with binary content type)
+   * will be wrapped in an XxxResponse type to maintain backward compatibility with HLC.
+   * This option defaults to true for Azure flavor and to false otherwise, unless explicitly set.
+   */
+  wrapNonModelReturn?: boolean;
+  /**
+   * When enabled, every regular (non-LRO, non-paging) operation return type is augmented with a
+   * `_response` property containing `rawResponse`, `parsedBody`, and `parsedHeaders`.
+   */
+  enableStorageCompat?: boolean;
+  /**
+   * When set to true, TypeSpec `unknown` type will be translated to `Record<string, unknown>`
+   * instead of `any` in the generated Modular SDK. This is useful when migrating from HLC
+   * where `unknown` in swagger mapped to `Record<string, unknown>`.
+   */
+  treatUnknownAsRecord?: boolean;
+  /**
+   * When set to true, generates React Native build targets (tsconfig, warp target, package.json exports).
+   * Defaults to false. Only applicable when azureSdkForJs is true.
+   */
+  generateReactNativeTarget?: boolean;
+}
+
+export interface ServiceInfo {
+  title?: string;
+  description?: string;
+}
+
+export interface DependencyInfo {
+  link: string;
+  description: string;
+}
+
+export interface File {
+  path: string;
+  content: string;
+}
+
+export enum SchemaContext {
+  /** Schema is used as an input to an operation. */
+  Input = "input",
+  /** Schema is used as an output from an operation. */
+  Output = "output",
+  /** Schema is used as an exception from an operation. */
+  Exception = "exception"
+}
+
+export interface Schema {
+  name: string;
+  type: string;
+  typeName?: string;
+  outputTypeName?: string;
+  description?: string;
+  required?: boolean;
+  default?: any;
+  readOnly?: boolean;
+  usage?: SchemaContext[];
+  alias?: string;
+  outputAlias?: string;
+  fromCore?: boolean;
+  enum?: any[];
+  isConstant?: boolean;
+}
+
+export interface ObjectSchema extends Schema {
+  properties?: Record<string, Schema>;
+  discriminatorValue?: string;
+  discriminator?: Schema;
+  isPolyParent?: boolean;
+  isMultipartBody?: boolean;
+  children?: {
+    all?: ObjectSchema[];
+    immediate?: ObjectSchema[];
+  };
+  parents?: {
+    all?: ObjectSchema[];
+    immediate?: ObjectSchema[];
+  };
+}
+
+export interface DictionarySchema extends Schema {
+  valueTypeName?: string;
+  outputValueTypeName?: string;
+  additionalProperties?: Schema;
+}
+
+export interface ArraySchema extends Schema {
+  items?: Schema;
+}
+
+export type Property = Schema;
+
+export type Parameter = Schema;
+
+export interface PackageDetails {
+  name: string;
+  scopeName?: string;
+  nameWithoutScope?: string;
+  description?: string;
+  version?: string;
+  isVersionUserProvided?: boolean;
+}
+export interface OperationParameter {
+  operationGroup: string;
+  operationName: string;
+  /**
+   * An operation with multiple request parameters means that
+   * the operation can get different values for content-type and each value
+   * may have a different type associated to it.
+   */
+  parameters: ParameterMetadatas[];
+}
+
+export interface ParameterMetadatas {
+  parameters?: ParameterMetadata[];
+  body?: ParameterBodyMetadata;
+}
+
+export interface ParameterBodyMetadata {
+  /**
+   * In case of formData we'd get multiple properties in body marked as partialBody
+   * If yes, rlc-common would prepare the whole part shape;
+   * usually false in typespec source because rlc-common doesn't have to prepare the whole part shape
+   */
+  isPartialBody?: boolean;
+  body?: ParameterBodySchema[];
+}
+
+export interface ParameterBodySchema extends Schema {
+  oriSchema?: Schema;
+}
+export interface ParameterMetadata {
+  type: "query" | "path" | "header";
+  name: string;
+  param: ParameterSchema;
+}
+
+export interface ParameterSchema extends Schema {
+  // the detailed wrapper type for the parameter and codegen needs to build this type directly
+  wrapperType?: Schema;
+}
+
+export interface OperationResponse {
+  operationGroup: string;
+  operationName: string;
+  path: string;
+  responses: ResponseMetadata[];
+  // Check if the default response is one of superset of non-default responses
+  isDefaultSupersetOfOthers?: boolean;
+}
+export interface ResponseMetadata {
+  statusCode: string;
+  description?: string;
+  headers?: ResponseHeaderSchema[];
+  body?: ResponseBodySchema;
+  predefinedName?: string;
+}
+
+export type ResponseHeaderSchema = Schema;
+export type ResponseBodySchema = Schema;
+
+export type ContentBuilder = {
+  (model: RLCModel): File | File[] | undefined;
+};
+
+export type SampleParameterPosition = "client" | "path" | "method";
+
+export type SampleParameters = Record<
+  SampleParameterPosition,
+  SampleParameter[]
+>;
+
+export interface SampleParameter {
+  name: string;
+  assignment?: string;
+  value?: string;
+}

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

@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project } from "ts-morph";
+import { RLCModel } from "../interfaces.js";
+
+export function buildApiExtractorConfig(model: RLCModel) {
+  const { packageDetails, isModularLibrary, generateTest, azureSdkForJs } =
+    model.options || {};
+  const project = new Project();
+
+  let mainEntryPointFilePath = "dist/esm/index.d.ts";
+
+  if (model.options?.moduleKind === "cjs") {
+    mainEntryPointFilePath = `./types${
+      generateTest || isModularLibrary ? "/src" : ""
+    }/index.d.ts`;
+  }
+
+  const config = azureSdkForJs
+    ? {
+        extends: "../../../api-extractor-base.json"
+      }
+    : {
+        $schema:
+          "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+        mainEntryPointFilePath,
+        docModel: {
+          enabled: true
+        },
+        apiReport: {
+          enabled: true,
+          reportFolder: "./review"
+        },
+        dtsRollup: {
+          enabled: true,
+          untrimmedFilePath: "",
+          publicTrimmedFilePath: `dist/${
+            packageDetails?.nameWithoutScope ?? packageDetails?.name
+          }.d.ts`
+        },
+        messages: {
+          tsdocMessageReporting: {
+            default: {
+              logLevel: "none"
+            }
+          },
+          extractorMessageReporting: {
+            "ae-missing-release-tag": {
+              logLevel: "none"
+            },
+            "ae-unresolved-link": {
+              logLevel: "none"
+            }
+          }
+        }
+      };
+
+  const filePath = "api-extractor.json";
+  const configFile = project.createSourceFile(
+    filePath,
+    JSON.stringify(config),
+    {
+      overwrite: true
+    }
+  );
+  return {
+    path: filePath,
+    content: configFile.getFullText()
+  };
+}

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

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { RLCModel } from "../interfaces.js";
+
+function getPackageVersion(model: RLCModel): string {
+  return model.options?.packageDetails?.version ?? "1.0.0-beta.1";
+}
+
+export function buildChangelogFile(model: RLCModel) {
+  const version = getPackageVersion(model);
+  const content = `# Release History
+
+## ${version} (Unreleased)
+
+### Features Added
+
+### Breaking Changes
+
+### Bugs Fixed
+
+### Other Changes
+`;
+
+  return {
+    path: "CHANGELOG.md",
+    content
+  };
+}

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

@@ -0,0 +1,86 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project } from "ts-morph";
+import { RLCModel } from "../interfaces.js";
+
+const eslintConfig = `import azsdkEslint from "@azure/eslint-plugin-azure-sdk";
+
+export default azsdkEslint.config([
+  {
+    rules: {
+      "@azure/azure-sdk/ts-modules-only-named": "warn",
+      "@azure/azure-sdk/ts-package-json-types": "warn",
+      "@azure/azure-sdk/ts-package-json-engine-is-present": "warn",
+      "tsdoc/syntax": "warn"
+    }
+  }
+]);
+`;
+
+const esLintConfigEsm = `import azsdkEslint from "@azure/eslint-plugin-azure-sdk";
+
+export default azsdkEslint.config([
+  {
+    rules: {
+      "@azure/azure-sdk/ts-modules-only-named": "warn",
+      "@azure/azure-sdk/ts-package-json-types": "warn",
+      "@azure/azure-sdk/ts-package-json-engine-is-present": "warn",
+      "@azure/azure-sdk/ts-package-json-files-required": "off",
+      "@azure/azure-sdk/ts-package-json-main-is-cjs": "off",
+      "tsdoc/syntax": "warn"
+    }
+  }
+]);
+`;
+
+const esLintConfigEsmAzureSdk = `import azsdkEslint from "@azure/eslint-plugin-azure-sdk";
+
+export default [
+  ...azsdkEslint.config([
+    {
+      rules: {
+        "@azure/azure-sdk/ts-modules-only-named": "warn",
+        "@azure/azure-sdk/ts-package-json-types": "warn",
+        "@azure/azure-sdk/ts-package-json-engine-is-present": "warn",
+        "@azure/azure-sdk/ts-package-json-files-required": "off",
+        "@azure/azure-sdk/ts-package-json-main-is-cjs": "off",
+        "tsdoc/syntax": "warn"
+      }
+    },
+  ]),
+  {
+    files: ["src/**/*.ts", "src/**/*.mts", "test/**/*.ts"],
+    languageOptions: {
+      parserOptions: {
+        projectService: false,
+        project: "./config/tsconfig.lint.json",
+      },
+    },
+  },
+];
+`;
+
+export function buildEsLintConfig(model: RLCModel) {
+  if (model.options?.flavor !== "azure") {
+    return;
+  }
+  const project = new Project();
+  const filePath = "eslint.config.mjs";
+
+  let template: string;
+  if (model.options?.moduleKind === "esm") {
+    template = model.options?.azureSdkForJs
+      ? esLintConfigEsmAzureSdk
+      : esLintConfigEsm;
+  } else {
+    template = eslintConfig;
+  }
+  const configFile = project.createSourceFile("eslint.config.mjs", template, {
+    overwrite: true
+  });
+  return {
+    path: filePath,
+    content: configFile.getFullText()
+  };
+}

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

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+const mitLicenseText = `
+Copyright (c) Microsoft Corporation.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+`;
+
+export function buildLicenseFile() {
+  return {
+    path: "LICENSE",
+    content: mitLicenseText.trim()
+  };
+}