@azure-tools/rlc-common 0.11.0

package/src/helpers/shortcutMethods.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  OptionalKind,
+  MethodSignatureStructure,
+  InterfaceDeclarationStructure
+} from "ts-morph";
+import { PathMetadata, Paths } from "../interfaces.js";
+import { buildMethodDefinitions } from "./operationHelpers.js";
+import { NameType, normalizeName } from "./nameUtils.js";
+
+export function generateMethodShortcuts(
+  paths: Paths
+): OptionalKind<InterfaceDeclarationStructure>[] {
+  const keys: Record<string, OptionalKind<MethodSignatureStructure>[]> = {};
+  for (const path in paths) {
+    const groupName = paths[path].operationGroupName;
+    const definitions = buildOperationDefinitions(paths[path]);
+    if (!keys[groupName]) {
+      keys[groupName] = definitions;
+    } else {
+      keys[groupName] = [...keys[groupName], ...definitions];
+    }
+  }
+
+  const interfaces: OptionalKind<InterfaceDeclarationStructure>[] = [];
+
+  for (const interfaceName in keys) {
+    const methods = keys[interfaceName];
+    interfaces.push({
+      name: `${interfaceName}Operations`,
+      methods: methods,
+      isExported: true,
+      docs: [`Contains operations for ${interfaceName} operations`]
+    });
+  }
+
+  return interfaces;
+}
+
+function buildOperationDefinitions(
+  path: PathMetadata
+): OptionalKind<MethodSignatureStructure>[] {
+  let ops: OptionalKind<MethodSignatureStructure>[] = [];
+
+  for (const verb in path.methods) {
+    const methods = path.methods[verb];
+    for (const method of methods) {
+      const name = normalizeName(method.operationName, NameType.Property);
+      const pathParams = path.pathParameters;
+      const methodDefinitions = buildMethodDefinitions(
+        { [name]: [method] },
+        pathParams
+      );
+      ops = [...ops, ...methodDefinitions];
+    }
+  }
+  return ops;
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export * from "./interfaces.js";
+export * from "./buildClientDefinitions.js";
+export * from "./buildSchemaType.js";
+export * from "./buildClient.js";
+export * from "./helpers/nameConstructors.js";
+export * from "./buildResponseTypes.js";
+export * from "./helpers/shortcutMethods.js";
+export * from "./helpers/nameUtils.js";
+export * from "./buildParameterTypes.js";
+export * from "./buildIsUnexpectedHelper.js";
+export * from "./buildTopLevelIndexFile.js";
+export * from "./buildIndexFile.js";
+export * from "./buildPaginateHelper.js";
+export * from "./buildPollingHelper.js";
+export * from "./test/buildKarmaConfig.js";
+export * from "./test/buildEnvFile.js";
+export * from "./test/buildRecordedClient.js";
+export * from "./test/buildSampleTest.js";
+export * from "./metadata/buildReadmeFile.js";
+export * from "./metadata/buildApiExtractorConfig.js";
+export * from "./metadata/buildPackageFile.js";
+export * from "./metadata/buildRollupConfig.js";
+export * from "./metadata/buildTsConfig.js";
+export * from "./metadata/buildESLintConfig.js";
+export * from "./metadata/buildLicenseFile.js";
+export * from "./buildSerializeHelper.js";

package/src/interfaces.ts

@@ -0,0 +1,227 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+export interface RLCModel {
+  libraryName: string;
+  srcPath: string;
+  paths: Paths;
+  options?: RLCOptions;
+  schemas: Schema[];
+  apiVersionInQueryParam?: Parameter;
+  parameters?: OperationParameter[];
+  responses?: OperationResponse[];
+  importSet?: Map<ImportKind, Set<string>>;
+  annotations?: AnnotationDetails;
+  urlInfo?: UrlInfo;
+}
+
+export interface PathTemplateApiVersion {
+  value: string;
+  templateName: string;
+}
+
+export interface UrlInfo {
+  endpoint?: string;
+  urlParameters?: PathParameter[];
+  pathTemplateApiVersion?: PathTemplateApiVersion;
+}
+export interface AnnotationDetails {
+  hasPaging?: boolean;
+  hasLongRunning?: boolean;
+  pageDetails?: PagingDetails;
+  hasMultiCollection?: boolean;
+  hasPipeCollection?: boolean;
+  hasSsvCollection?: boolean;
+  hasTsvCollection?: boolean;
+}
+
+export interface PagingDetails {
+  itemNames: string[];
+  nextLinkNames: string[];
+  isComplexPaging: boolean;
+}
+
+export type Methods = {
+  [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;
+  annotations?: OperationAnnotations;
+}
+export interface PathMetadata {
+  name: string;
+  pathParameters: PathParameter[];
+  methods: Methods;
+  operationGroupName: string;
+  description: string;
+}
+
+export type Paths = Record<string, PathMetadata>;
+
+export type PathParameter = {
+  name: string;
+  type: string;
+  description?: string;
+  value?: string | number | boolean;
+};
+
+export interface OperationAnnotations {
+  isLongRunning?: boolean;
+  isPageable?: boolean;
+}
+
+export interface RLCOptions {
+  includeShortcuts?: boolean;
+  multiClient?: boolean;
+  batch?: any[];
+  packageDetails?: PackageDetails;
+  addCredentials?: boolean;
+  credentialScopes?: string[];
+  credentialKeyHeaderName?: string;
+  generateMetadata?: boolean;
+  generateTest?: boolean;
+  generateSample?: boolean;
+  azureSdkForJs?: boolean;
+  azureOutputDirectory?: string;
+  isCadlTest?: boolean;
+  title?: string;
+  dependencyInfo?: DependencyInfo;
+  productDocLink?: string;
+  serviceInfo?: ServiceInfo;
+  azureArm?: boolean;
+  sourceFrom?: "Cadl" | "Swagger";
+}
+
+export interface ServiceInfo {
+  title?: string;
+  description?: string;
+}
+
+export interface DependencyInfo {
+  link: string;
+  description: string;
+}
+
+export enum ImportKind {
+  ResponseOutput,
+  ParameterInput
+}
+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;
+}
+
+export interface ObjectSchema extends Schema {
+  properties?: Record<string, Schema>;
+  discriminatorValue?: string;
+  discriminator?: Schema;
+  isPolyParent?: boolean;
+  children?: {
+    all?: ObjectSchema[];
+    immediate?: ObjectSchema[];
+  };
+  parents?: {
+    all?: ObjectSchema[];
+    immediate?: ObjectSchema[];
+  };
+}
+
+export interface DictionarySchema extends Schema {
+  valueTypeName?: string;
+  outputValueTypeName?: string;
+}
+
+export interface Property extends Schema {}
+
+export interface Parameter extends Schema {}
+
+export interface PackageDetails {
+  name: string;
+  scopeName?: string;
+  nameWithoutScope?: string;
+  description?: string;
+  version: string;
+}
+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
+  isPartialBody?: boolean;
+  body?: ParameterBodySchema[];
+}
+
+export type ParameterBodySchema = Schema;
+export interface ParameterMetadata {
+  type: "query" | "path" | "header";
+  name: string;
+  param: Schema;
+}
+
+export interface OperationResponse {
+  operationGroup: string;
+  operationName: string;
+  responses: ResponseMetadata[];
+}
+export interface ResponseMetadata {
+  statusCode: string;
+  description?: string;
+  headers?: ResponseHeaderSchema[];
+  body?: ResponseBodySchema;
+}
+
+export type ResponseHeaderSchema = Schema;
+export type ResponseBodySchema = Schema;
+
+export type ContentBuilder = {
+  (model: RLCModel): File | undefined;
+  (model: RLCModel, hasSampleGenerated?: boolean): File | undefined;
+};

package/src/metadata/buildApiExtractorConfig.ts

@@ -0,0 +1,59 @@
+// 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 generateMetadata = Boolean(model.options?.generateMetadata);
+  if (!generateMetadata) {
+    return;
+  }
+  const { generateTest, packageDetails } = model.options || {};
+  const project = new Project();
+  const config = {
+    $schema:
+      "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+    mainEntryPointFilePath: `./types${generateTest ? "/src" : ""}/index.d.ts`,
+    docModel: {
+      enabled: true
+    },
+    apiReport: {
+      enabled: true,
+      reportFolder: "./review"
+    },
+    dtsRollup: {
+      enabled: true,
+      untrimmedFilePath: "",
+      publicTrimmedFilePath: `./types/${packageDetails?.nameWithoutScope}.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/metadata/buildESLintConfig.ts

@@ -0,0 +1,34 @@
+import { Project } from "ts-morph";
+import { RLCModel } from "../interfaces.js";
+
+const esLintConfig = {
+  plugins: ["@azure/azure-sdk"],
+  extends: ["plugin:@azure/azure-sdk/azure-sdk-base"],
+  rules: {
+    "@azure/azure-sdk/ts-modules-only-named": "warn",
+    "@azure/azure-sdk/ts-apiextractor-json-types": "warn",
+    "@azure/azure-sdk/ts-package-json-types": "warn",
+    "@azure/azure-sdk/ts-package-json-engine-is-present": "warn",
+    "tsdoc/syntax": "warn"
+  }
+};
+
+export function buildEsLintConfig(model: RLCModel) {
+  const generateMetadata = Boolean(model.options?.generateMetadata);
+  if (!generateMetadata) {
+    return;
+  }
+  const project = new Project();
+  const filePath = ".eslintrc.json";
+  const configFile = project.createSourceFile(
+    ".eslintrc.json",
+    JSON.stringify(esLintConfig),
+    {
+      overwrite: true
+    }
+  );
+  return {
+    path: filePath,
+    content: configFile.getFullText()
+  };
+}

package/src/metadata/buildLicenseFile.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { RLCModel } from "../interfaces.js";
+
+const mitLicenseText = `
+The MIT License (MIT)
+
+Copyright (c) ${new Date().getFullYear()} Microsoft
+
+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(model: RLCModel) {
+  const generateMetadata = Boolean(model.options?.generateMetadata);
+  if (!generateMetadata) {
+    return;
+  }
+  return {
+    path: "LICENSE",
+    content: mitLicenseText.trim()
+  };
+}