@azure-tools/rlc-common 0.11.0

package/src/buildSchemaType.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project } from "ts-morph";
+import * as path from "path";
+import {
+  buildObjectAliases,
+  buildObjectInterfaces,
+  buildPolymorphicAliases
+} from "./buildObjectTypes.js";
+import { RLCModel, SchemaContext } from "./interfaces.js";
+
+/**
+ * Generates types to represent schema definitions in the swagger
+ */
+export function buildSchemaTypes(model: RLCModel) {
+  const { srcPath } = model;
+  const project = new Project();
+  let filePath = path.join(srcPath, `models.ts`);
+  const inputModelFile = generateModelFiles(model, project, filePath, [
+    SchemaContext.Input
+  ]);
+  filePath = path.join(srcPath, `outputModels.ts`);
+  const outputModelFile = generateModelFiles(model, project, filePath, [
+    SchemaContext.Output,
+    SchemaContext.Exception
+  ]);
+  return { inputModelFile, outputModelFile };
+}
+
+export function generateModelFiles(
+  model: RLCModel,
+  project: Project,
+  filePath: string,
+  schemaContext: SchemaContext[]
+) {
+  // Track models that need to be imported
+  const importedModels = new Set<string>();
+
+  const objectsDefinitions = buildObjectInterfaces(
+    model,
+    importedModels,
+    schemaContext
+  );
+
+  const objectTypeAliases = buildPolymorphicAliases(model, schemaContext);
+
+  const objectAliases = buildObjectAliases(
+    model,
+    importedModels,
+    schemaContext
+  );
+  if (
+    objectTypeAliases.length ||
+    objectsDefinitions.length ||
+    objectAliases.length
+  ) {
+    const modelsFile = project.createSourceFile(filePath, undefined, {
+      overwrite: true
+    });
+
+    modelsFile.addInterfaces(objectsDefinitions);
+    modelsFile.addTypeAliases(objectTypeAliases);
+    modelsFile.addTypeAliases(objectAliases);
+    if (importedModels.has("Paged")) {
+      modelsFile.addImportDeclarations([
+        {
+          namedImports: ["Paged"],
+          moduleSpecifier: "@azure/core-paging"
+        }
+      ]);
+      importedModels.delete("Paged");
+    }
+    if (importedModels.size > 0) {
+      modelsFile.addImportDeclarations([
+        {
+          namedImports: [...Array.from(importedModels || [])],
+          moduleSpecifier: "@azure-rest/core-client"
+        }
+      ]);
+    }
+    return { path: filePath, content: modelsFile.getFullText() };
+  }
+  return undefined;
+}

package/src/buildSerializeHelper.ts

@@ -0,0 +1,42 @@
+import { RLCModel } from "./interfaces.js";
+import * as path from "path";
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import {
+  hasMultiCollection,
+  hasPipeCollection,
+  hasSsvCollection,
+  hasTsvCollection
+} from "./helpers/operationHelpers.js";
+import {
+  buildMultiCollectionContent,
+  buildPipeCollectionContent,
+  buildSsvCollectionContent,
+  buildTsvCollectionContent
+} from "./static/serializeHelper.js";
+
+export function buildSerializeHelper(model: RLCModel) {
+  let serializeHelperContent = "";
+  if (hasMultiCollection(model)) {
+    serializeHelperContent += "\n" + buildMultiCollectionContent;
+  }
+  if (hasPipeCollection(model)) {
+    serializeHelperContent += "\n" + buildPipeCollectionContent;
+  }
+  if (hasSsvCollection(model)) {
+    serializeHelperContent += "\n" + buildSsvCollectionContent;
+  }
+  if (hasTsvCollection(model)) {
+    serializeHelperContent += "\n" + buildTsvCollectionContent;
+  }
+  if (serializeHelperContent !== "") {
+    const readmeFileContents = hbs.compile(serializeHelperContent, {
+      noEscape: true
+    });
+    const { srcPath } = model;
+    return {
+      path: path.join(srcPath, "serializeHelper.ts"),
+      content: readmeFileContents({})
+    };
+  }
+}

package/src/buildTopLevelIndexFile.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { NameType, normalizeName } from "./helpers/nameUtils.js";
+import { RLCModel } from "./interfaces.js";
+import { Project } from "ts-morph";
+import * as path from "path";
+import { getRelativePartFromSrcPath } from "./helpers/pathUtils.js";
+
+const batchOutputFolder: [string, string, string][] = [];
+
+export function buildTopLevelIndex(model: RLCModel) {
+  if (!model.options) {
+    return undefined;
+  }
+  const project = new Project();
+  const { srcPath } = model;
+  const { multiClient, batch } = model.options;
+  if (srcPath) {
+    const clientName = model.libraryName;
+    const moduleName = normalizeName(clientName, NameType.File);
+    const relativePath = "./" + getRelativePartFromSrcPath(srcPath);
+    batchOutputFolder.push([relativePath, clientName, moduleName]);
+  }
+  if (
+    multiClient &&
+    batch &&
+    batch.length > 1 &&
+    batchOutputFolder.length === batch.length
+  ) {
+    const indexFile = project.createSourceFile("index.ts", undefined, {
+      overwrite: true
+    });
+    const allModules: string[] = [];
+    batchOutputFolder.forEach((item) => {
+      indexFile.addImportDeclaration({
+        namespaceImport: item[1],
+        moduleSpecifier: `${item[0]}`
+      });
+      allModules.push(item[1]);
+    });
+    indexFile.addExportDeclaration({
+      namedExports: [...allModules]
+    });
+    const content = indexFile.getFullText();
+    const filePath = path.join(
+      srcPath.substring(0, srcPath.indexOf(path.sep + "src") + 4),
+      `index.ts`
+    );
+    return { path: filePath, content };
+  }
+}

package/src/helpers/nameConstructors.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { NameType, normalizeName } from "./nameUtils.js";
+
+/**
+ * Get the response type name by baseName or operatioName & statusCode
+ * @param baseResponseName
+ */
+export function getResponseTypeName(baseResponseName: string): string;
+export function getResponseTypeName(
+  operationGroup: string,
+  operationName: string,
+  statusCode: string
+): string;
+export function getResponseTypeName(
+  baseNameOrOperationGroup: string,
+  operationName?: string,
+  statusCode?: string
+): string {
+  if (operationName) {
+    baseNameOrOperationGroup = getResponseBaseName(
+      baseNameOrOperationGroup,
+      operationName!,
+      statusCode || ""
+    );
+  }
+  return normalizeName(
+    `${baseNameOrOperationGroup}Response`,
+    NameType.Interface
+  );
+}
+
+/**
+ * The prefix of all response types
+ * @param operationGroup operation group name e.g string_PutEmpty
+ * @param operationName operation name D e.g string_PutEmpty
+ * @param statusCode 2XX, 4XX, 5XX, default etc.
+ * @returns normolized base name e.g StringPutEmpty200
+ */
+export function getResponseBaseName(
+  operationGroup: string,
+  operationName: string,
+  statusCode: string
+) {
+  return normalizeName(
+    `${operationGroup}_${operationName}_${statusCode}`,
+    NameType.Interface
+  );
+}
+
+/**
+ * The prefix of all parameter relevant types
+ * @param operationName is composed with operationGroup and operationID e.g string_PutEmpty
+ * @returns
+ */
+export function getParameterBaseName(
+  operationGroup: string,
+  operationName: string
+) {
+  return normalizeName(
+    `${operationGroup}_${operationName}`,
+    NameType.Interface
+  );
+}
+
+/**
+ * Get the top-layer parameter name
+ * @param operationGroup operation group name
+ * @param operationName is composed with operationGroup and operationID e.g string_PutEmpty
+ * @returns top-layer parameter name e.g StringPutEmptParameters
+ */
+export function getParameterTypeName(baseName: string): string;
+export function getParameterTypeName(
+  operationGroup: string,
+  operationName: string
+): string;
+export function getParameterTypeName(
+  baseNameOrOperationGroup: string,
+  operationName?: string
+) {
+  if (operationName) {
+    baseNameOrOperationGroup = getParameterBaseName(
+      baseNameOrOperationGroup,
+      operationName!
+    );
+  }
+
+  return normalizeName(
+    `${baseNameOrOperationGroup}_Parameters`,
+    NameType.Interface
+  );
+}

package/src/helpers/nameUtils.ts

@@ -0,0 +1,227 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export interface ReservedName {
+  name: string;
+  reservedFor: NameType[];
+}
+
+export enum NameType {
+  Class,
+  File,
+  Interface,
+  Property,
+  Parameter,
+  Operation,
+  OperationGroup
+}
+
+const Newable = [NameType.Class, NameType.Interface, NameType.OperationGroup];
+
+const ReservedModelNames: ReservedName[] = [
+  { name: "any", reservedFor: [NameType.Parameter] },
+  { name: "as", reservedFor: [NameType.Parameter] },
+  { name: "boolean", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "break", reservedFor: [NameType.Parameter] },
+  { name: "case", reservedFor: [NameType.Parameter] },
+  { name: "catch", reservedFor: [NameType.Parameter] },
+  { name: "class", reservedFor: [NameType.Parameter] },
+  { name: "const", reservedFor: [NameType.Parameter] },
+  { name: "constructor", reservedFor: [NameType.Parameter] },
+  { name: "continue", reservedFor: [NameType.Parameter] },
+  { name: "date", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "debugger", reservedFor: [NameType.Parameter] },
+  { name: "declare", reservedFor: [NameType.Parameter] },
+  { name: "default", reservedFor: [NameType.Parameter] },
+  { name: "delete", reservedFor: [NameType.Parameter] },
+  { name: "do", reservedFor: [NameType.Parameter] },
+  { name: "else", reservedFor: [NameType.Parameter] },
+  { name: "enum", reservedFor: [NameType.Parameter] },
+  { name: "error", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "export", reservedFor: [NameType.Parameter] },
+  { name: "extends", reservedFor: [NameType.Parameter] },
+  { name: "false", reservedFor: [NameType.Parameter] },
+  { name: "finally", reservedFor: [NameType.Parameter] },
+  { name: "for", reservedFor: [NameType.Parameter] },
+  { name: "from", reservedFor: [NameType.Parameter] },
+  { name: "function", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "get", reservedFor: [NameType.Parameter] },
+  { name: "if", reservedFor: [NameType.Parameter] },
+  { name: "implements", reservedFor: [NameType.Parameter] },
+  { name: "import", reservedFor: [NameType.Parameter] },
+  { name: "in", reservedFor: [NameType.Parameter] },
+  { name: "instanceof", reservedFor: [NameType.Parameter] },
+  { name: "interface", reservedFor: [NameType.Parameter] },
+  { name: "let", reservedFor: [NameType.Parameter] },
+  { name: "module", reservedFor: [NameType.Parameter] },
+  { name: "new", reservedFor: [NameType.Parameter] },
+  { name: "null", reservedFor: [NameType.Parameter] },
+  { name: "number", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "of", reservedFor: [NameType.Parameter] },
+  { name: "package", reservedFor: [NameType.Parameter] },
+  { name: "private", reservedFor: [NameType.Parameter] },
+  { name: "protected", reservedFor: [NameType.Parameter] },
+  { name: "public", reservedFor: [NameType.Parameter] },
+  { name: "requestoptions", reservedFor: [NameType.Parameter] },
+  { name: "require", reservedFor: [NameType.Parameter] },
+  { name: "return", reservedFor: [NameType.Parameter] },
+  { name: "set", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "static", reservedFor: [NameType.Parameter] },
+  { name: "string", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "super", reservedFor: [NameType.Parameter] },
+  { name: "switch", reservedFor: [NameType.Parameter] },
+  { name: "symbol", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "this", reservedFor: [NameType.Parameter] },
+  { name: "throw", reservedFor: [NameType.Parameter] },
+  { name: "true", reservedFor: [NameType.Parameter] },
+  { name: "try", reservedFor: [NameType.Parameter] },
+  { name: "type", reservedFor: [NameType.Parameter] },
+  { name: "typeof", reservedFor: [NameType.Parameter] },
+  { name: "var", reservedFor: [NameType.Parameter] },
+  { name: "void", reservedFor: [NameType.Parameter] },
+  { name: "while", reservedFor: [NameType.Parameter] },
+  { name: "with", reservedFor: [NameType.Parameter] },
+  { name: "yield", reservedFor: [NameType.Parameter] },
+  { name: "arguments", reservedFor: [NameType.Parameter] }
+];
+
+export enum CasingConvention {
+  Pascal,
+  Camel
+}
+
+export function guardReservedNames(
+  name: string,
+  nameType: NameType,
+  customReservedNames: ReservedName[] = []
+): string {
+  const suffix = getSuffix(nameType);
+  return [...ReservedModelNames, ...customReservedNames]
+    .filter((r) => r.reservedFor.includes(nameType))
+    .find((r) => r.name === name.toLowerCase())
+    ? `${name}${suffix}`
+    : name;
+}
+
+function getSuffix(nameType?: NameType) {
+  switch (nameType) {
+    case NameType.File:
+    case NameType.Operation:
+    case NameType.Property:
+      return "";
+    case NameType.OperationGroup:
+      return "Operations";
+    case NameType.Parameter:
+      return "Param";
+    case NameType.Class:
+    case NameType.Interface:
+    default:
+      return "Model";
+  }
+}
+
+export function normalizeName(
+  name: string,
+  nameType: NameType,
+  shouldGuard?: boolean,
+  customReservedNames: ReservedName[] = [],
+  casingOverride?: CasingConvention
+): string {
+  if (name.startsWith("$DO_NOT_NORMALIZE$")) {
+    return name.replace("$DO_NOT_NORMALIZE$", "");
+  }
+  const casingConvention = casingOverride ?? getCasingConvention(nameType);
+  const sanitizedName = sanitizeName(name);
+  const parts = getNameParts(sanitizedName);
+  const [firstPart, ...otherParts] = parts;
+  const normalizedFirstPart = toCasing(firstPart, casingConvention);
+  const normalizedParts = (otherParts || [])
+    .map((part) =>
+      part === "null" ? part : toCasing(part, CasingConvention.Pascal)
+    )
+    .join("");
+
+  const normalized = checkBeginning(`${normalizedFirstPart}${normalizedParts}`);
+  return shouldGuard
+    ? guardReservedNames(normalized, nameType, customReservedNames)
+    : normalized;
+}
+
+function checkBeginning(name: string): string {
+  if (name.startsWith("@")) {
+    return name.substring(1);
+  }
+  return name;
+}
+
+function sanitizeName(name: string): string {
+  // Remove \, " and ' from name string
+  return name.replace(/["'\\]+/g, "");
+}
+
+export function getModelsName(title: string): string {
+  const spaceRemovedTitle = title.replace(/ /g, "");
+  return `${spaceRemovedTitle.replace("Client", "")}Models`;
+}
+
+export function getMappersName(title: string): string {
+  const spaceRemovedTitle = title.replace(/ /g, "");
+  return `${spaceRemovedTitle.replace("Client", "")}Mappers`;
+}
+
+function getCasingConvention(nameType: NameType) {
+  switch (nameType) {
+    case NameType.Class:
+    case NameType.Interface:
+    case NameType.OperationGroup:
+      return CasingConvention.Pascal;
+    case NameType.File:
+    case NameType.Property:
+    case NameType.Operation:
+    case NameType.Parameter:
+      return CasingConvention.Camel;
+  }
+}
+
+/**
+ * TODO: Improve this function to handle cases such as TEST -> test. Current basic implementation
+ * results in TEST -> test or Test (depending on the CasingConvention). We should switch to relay
+ * on Modeler four namer for this once it is stable
+ */
+function toCasing(str: string, casing: CasingConvention): string {
+  let value = str;
+  if (value === value.toUpperCase()) {
+    value = str.toLowerCase();
+  }
+
+  const firstChar =
+    casing === CasingConvention.Pascal
+      ? value.charAt(0).toUpperCase()
+      : value.charAt(0).toLocaleLowerCase();
+  return `${firstChar}${value.substring(1)}`;
+}
+
+function getNameParts(name: string) {
+  const parts = name.split(/[-._ ]+/);
+
+  return parts.length > 0 ? parts : [name];
+}
+
+export function pascalCase(str: string) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+export function camelCase(
+  str: string,
+  options: { uppercaseThreshold?: number } = {}
+) {
+  const { uppercaseThreshold = 4 } = options;
+  const thresholdRegex = new RegExp(
+    `^(?<![A-Z])[A-Z]{1,${uppercaseThreshold}}(?![A-Z])`
+  );
+  if (!thresholdRegex.test(str)) {
+    return str;
+  }
+
+  return str.charAt(0).toLocaleLowerCase() + str.slice(1);
+}

package/src/helpers/operationHelpers.ts

@@ -0,0 +1,119 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  MethodSignatureStructure,
+  OptionalKind,
+  ParameterDeclarationStructure
+} from "ts-morph";
+import {
+  Methods,
+  ObjectSchema,
+  PathParameter,
+  RLCModel,
+  SchemaContext
+} from "../interfaces.js";
+import { NameType, normalizeName, pascalCase } from "./nameUtils.js";
+import { isObjectSchema } from "./schemaHelpers.js";
+
+export function buildMethodDefinitions(
+  methods: Methods,
+  pathParams: PathParameter[] = []
+): OptionalKind<MethodSignatureStructure>[] {
+  const methodDefinitions: OptionalKind<MethodSignatureStructure>[] = [];
+  for (const key of Object.keys(methods)) {
+    const verbMethods = methods[key];
+
+    for (const method of verbMethods) {
+      const description = method.description;
+      const areAllOptional = method.hasOptionalOptions;
+
+      methodDefinitions.push({
+        name: key,
+        ...(description && { docs: [{ description }] }),
+        parameters: [
+          ...getPathParamDefinitions(pathParams),
+          {
+            name: "options",
+            hasQuestionToken: areAllOptional,
+            type: pascalCase(method.optionsName)
+          }
+        ],
+        returnType: `StreamableMethod<${method.returnType}>`
+      });
+    }
+  }
+
+  return methodDefinitions;
+}
+
+export function getPathParamDefinitions(
+  pathParams: PathParameter[]
+): OptionalKind<ParameterDeclarationStructure>[] {
+  return pathParams.map(({ name, type, description }) => {
+    return {
+      name: normalizeName(name, NameType.Parameter),
+      type,
+      description
+    };
+  });
+}
+
+export function hasPagingOperations(model: RLCModel) {
+  return Boolean(model.annotations?.hasPaging);
+}
+
+export function hasPollingOperations(model: RLCModel) {
+  return Boolean(model.annotations?.hasLongRunning);
+}
+
+export function hasMultiCollection(model: RLCModel) {
+  return Boolean(model.annotations?.hasMultiCollection);
+}
+
+export function hasPipeCollection(model: RLCModel) {
+  return Boolean(model.annotations?.hasPipeCollection);
+}
+
+export function hasSsvCollection(model: RLCModel) {
+  return Boolean(model.annotations?.hasSsvCollection);
+}
+
+export function hasTsvCollection(model: RLCModel) {
+  return Boolean(model.annotations?.hasTsvCollection);
+}
+
+export function hasUnexpectedHelper(model: RLCModel) {
+  const pathDictionary = model.paths;
+  for (const details of Object.values(pathDictionary)) {
+    for (const methodDetails of Object.values(details.methods)) {
+      const successTypes = methodDetails[0].responseTypes.success;
+      const errorTypes = methodDetails[0].responseTypes.error;
+
+      if (successTypes.length > 0 && errorTypes.length > 0 && !!errorTypes[0]) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function hasInputModels(model: RLCModel) {
+  return hasSchemaContextObject(model, [SchemaContext.Input]);
+}
+export function hasOutputModels(model: RLCModel) {
+  return hasSchemaContextObject(model, [
+    SchemaContext.Output,
+    SchemaContext.Exception
+  ]);
+}
+
+function hasSchemaContextObject(model: RLCModel, schemaUsage: SchemaContext[]) {
+  const objectSchemas: ObjectSchema[] = (model.schemas ?? []).filter(
+    (o) =>
+      isObjectSchema(o) &&
+      (o as ObjectSchema).usage?.some((u) => schemaUsage.includes(u))
+  );
+
+  return objectSchemas.length > 0;
+}

package/src/helpers/pathUtils.ts

@@ -0,0 +1,9 @@
+import * as path from "path";
+
+export function getRelativePartFromSrcPath(srcPath: string) {
+  const sep = srcPath.includes(path.sep + "src") ? path.sep : "/";
+  const relativePart = srcPath.substring(srcPath.indexOf(sep + "src") + 4);
+  return relativePart.startsWith(sep)
+    ? relativePart.substring(1)
+    : relativePart;
+}

package/src/helpers/schemaHelpers.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Schema } from "../interfaces.js";
+
+export function isDictionarySchema(schema: Schema) {
+  if (schema.type === "dictionary") {
+    return true;
+  }
+  return false;
+}
+
+export function isObjectSchema(schema: Schema) {
+  if (schema.type === "object") {
+    return true;
+  }
+  return false;
+}
+
+export function isConstantSchema(schema: Schema) {
+  if (schema.type === "constant") {
+    return true;
+  }
+  return false;
+}