@azure-tools/rlc-common 0.11.0

package/src/test/template.ts

@@ -0,0 +1,191 @@
+export const envContent = `
+import * as dotenv from "dotenv";
+
+dotenv.config();
+`;
+
+export const envBrowserContent = `
+import * as dotenv from "dotenv";
+
+dotenv.config();
+`;
+
+export const karmaConfig = `
+// https://github.com/karma-runner/karma-chrome-launcher
+process.env.CHROME_BIN = require("puppeteer").executablePath();
+require("dotenv").config();
+const { relativeRecordingsPath } = require("@azure-tools/test-recorder");
+process.env.RECORDINGS_RELATIVE_PATH = relativeRecordingsPath();
+
+module.exports = function (config) {
+  config.set({
+    // base path that will be used to resolve all patterns (eg. files, exclude)
+    basePath: "./",
+
+    // frameworks to use
+    // available frameworks: https://npmjs.org/browse/keyword/karma-adapter
+    frameworks: ["source-map-support", "mocha"],
+
+    plugins: [
+      "karma-mocha",
+      "karma-mocha-reporter",
+      "karma-chrome-launcher",
+      "karma-firefox-launcher",
+      "karma-env-preprocessor",
+      "karma-coverage",
+      "karma-sourcemap-loader",
+      "karma-junit-reporter",
+      "karma-source-map-support",
+    ],
+
+    // list of files / patterns to load in the browser
+    files: [
+      "dist-test/index.browser.js",
+      { pattern: "dist-test/index.browser.js.map", type: "html", included: false, served: true },
+    ],
+
+    // list of files / patterns to exclude
+    exclude: [],
+
+    // preprocess matching files before serving them to the browser
+    // available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor
+    preprocessors: {
+      "**/*.js": ["sourcemap", "env"],
+      // IMPORTANT: COMMENT following line if you want to debug in your browsers!!
+      // Preprocess source file to calculate code coverage, however this will make source file unreadable
+      // "dist-test/index.js": ["coverage"]
+    },
+
+    envPreprocessor: [
+      "TEST_MODE",
+      "ENDPOINT",
+      "AZURE_CLIENT_SECRET",
+      "AZURE_CLIENT_ID",
+      "AZURE_TENANT_ID",
+      "SUBSCRIPTION_ID",
+      "RECORDINGS_RELATIVE_PATH",
+    ],
+
+    // test results reporter to use
+    // possible values: 'dots', 'progress'
+    // available reporters: https://npmjs.org/browse/keyword/karma-reporter
+    reporters: ["mocha", "coverage", "junit"],
+
+    coverageReporter: {
+      // specify a common output directory
+      dir: "coverage-browser/",
+      reporters: [
+        { type: "json", subdir: ".", file: "coverage.json" },
+        { type: "lcovonly", subdir: ".", file: "lcov.info" },
+        { type: "html", subdir: "html" },
+        { type: "cobertura", subdir: ".", file: "cobertura-coverage.xml" },
+      ],
+    },
+
+    junitReporter: {
+      outputDir: "", // results will be saved as $outputDir/$browserName.xml
+      outputFile: "test-results.browser.xml", // if included, results will be saved as $outputDir/$browserName/$outputFile
+      suite: "", // suite will become the package name attribute in xml testsuite element
+      useBrowserName: false, // add browser name to report and classes names
+      nameFormatter: undefined, // function (browser, result) to customize the name attribute in xml testcase element
+      classNameFormatter: undefined, // function (browser, result) to customize the classname attribute in xml testcase element
+      properties: {}, // key value pair of properties to add to the <properties> section of the report
+    },
+
+    // web server port
+    port: 9876,
+
+    // enable / disable colors in the output (reporters and logs)
+    colors: true,
+
+    // level of logging
+    // possible values: config.LOG_DISABLE || config.LOG_ERROR || config.LOG_WARN || config.LOG_INFO || config.LOG_DEBUG
+    logLevel: config.LOG_INFO,
+
+    // enable / disable watching file and executing tests whenever any file changes
+    autoWatch: false,
+
+    // --no-sandbox allows our tests to run in Linux without having to change the system.
+    // --disable-web-security allows us to authenticate from the browser without having to write tests using interactive auth, which would be far more complex.
+    browsers: ["ChromeHeadlessNoSandbox"],
+    customLaunchers: {
+      ChromeHeadlessNoSandbox: {
+        base: "ChromeHeadless",
+        flags: ["--no-sandbox", "--disable-web-security"],
+      },
+    },
+
+    // Continuous Integration mode
+    // if true, Karma captures browsers, runs the tests and exits
+    singleRun: false,
+
+    // Concurrency level
+    // how many browser should be started simultaneous
+    concurrency: 1,
+
+    browserNoActivityTimeout: 60000000,
+    browserDisconnectTimeout: 10000,
+    browserDisconnectTolerance: 3,
+
+    client: {
+      mocha: {
+        // change Karma's debug.html to the mocha web reporter
+        reporter: "html",
+        timeout: "600000",
+      },
+    },
+  });
+};
+`;
+
+export const recordedClientContent = `
+import { Context } from "mocha";
+import { Recorder, RecorderStartOptions } from "@azure-tools/test-recorder";
+import "./env";
+
+const envSetupForPlayback: Record<string, string> = {
+  ENDPOINT: "https://endpoint",
+  AZURE_CLIENT_ID: "azure_client_id",
+  AZURE_CLIENT_SECRET: "azure_client_secret",
+  AZURE_TENANT_ID: "88888888-8888-8888-8888-888888888888",
+  SUBSCRIPTION_ID: "azure_subscription_id"
+};
+
+const recorderEnvSetup: RecorderStartOptions = {
+  envSetupForPlayback
+};
+
+/**
+* creates the recorder and reads the environment variables from the \`.env\` file.
+* Should be called first in the test suite to make sure environment variables are
+* read before they are being used.
+*/
+export async function createRecorder(context: Context): Promise<Recorder> {
+  const recorder = new Recorder(context.currentTest);
+  await recorder.start(recorderEnvSetup);
+  return recorder;
+}
+`;
+
+export const sampleTestContent = `
+import { Recorder } from "@azure-tools/test-recorder";
+import { assert } from "chai";
+import { createRecorder } from "./utils/recordedClient";
+import { Context } from "mocha";
+
+describe("My test", () => {
+  let recorder: Recorder;
+
+  beforeEach(async function(this: Context) {
+    recorder = await createRecorder(this);
+  });
+
+  afterEach(async function() {
+    await recorder.stop();
+  });
+
+  it("sample test", async function() {
+    assert.equal(1, 1);
+  });
+});
+`;

package/tsconfig-cjs.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig-common.json",
+  "compilerOptions": {
+    "sourceMap": true,
+    "module": "commonjs",
+    "outDir": "dist/",
+    "target": "es2015"
+  }
+}

package/tsconfig-common.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "declarationDir": "./types",
+    "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
+    /* Type Checking */
+    "strict": true /* Enable all strict type-checking options. */,
+    "skipLibCheck": true
+  },
+  "compileOnSave": false,
+  "exclude": ["node_modules", "dist"],
+  "include": ["src"]
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig-common.json",
+  "compilerOptions": {
+    "module": "esnext",
+    "outDir": "dist-esm/",
+    "target": "esnext",
+    "moduleResolution": "node",
+    "sourceMap": true
+  },
+  "ts-node": {
+    "esm": true
+  }
+}

package/types/buildClient.d.ts

@@ -0,0 +1,2 @@
+import { RLCModel, File } from "./interfaces.js";
+export declare function buildClient(model: RLCModel): File | undefined;

package/types/buildClientDefinitions.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildClientDefinitions(model: RLCModel): {
+    path: string;
+    content: string;
+};

package/types/buildIndexFile.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildIndexFile(model: RLCModel): {
+    path: string;
+    content: string;
+};

package/types/buildIsUnexpectedHelper.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildIsUnexpectedHelper(model: RLCModel): {
+    path: string;
+    content: string;
+} | undefined;

package/types/buildMethodShortcuts.d.ts

@@ -0,0 +1,4 @@
+import { ReservedName } from "./helpers/nameUtils.js";
+import { Paths } from "./interfaces.js";
+export declare const REST_CLIENT_RESERVED: ReservedName[];
+export declare function buildMethodShortcutImplementation(paths: Paths): Record<string, string[]>;

package/types/buildObjectTypes.d.ts

@@ -0,0 +1,15 @@
+import { InterfaceDeclarationStructure, PropertySignatureStructure, TypeAliasDeclarationStructure } from "ts-morph";
+import { Parameter, Property, RLCModel, SchemaContext } from "./interfaces.js";
+/**
+ * Generates interfaces for ObjectSchemas
+ */
+export declare function buildObjectInterfaces(model: RLCModel, importedModels: Set<string>, schemaUsage: SchemaContext[]): InterfaceDeclarationStructure[];
+export declare function buildObjectAliases(model: RLCModel, importedModels: Set<string>, schemaUsage: SchemaContext[]): TypeAliasDeclarationStructure[];
+export declare function buildPolymorphicAliases(model: RLCModel, schemaUsage: SchemaContext[]): TypeAliasDeclarationStructure[];
+/**
+ * Builds a Typescript property or parameter signature
+ * @param property - Property or parameter to get the Typescript signature for
+ * @param importedModels - Set to track the models that need to be imported
+ * @returns a PropertySignatureStructure for the property.
+ */
+export declare function getPropertySignature(property: Property | Parameter, schemaUsage: SchemaContext[], importedModels: Set<string>): PropertySignatureStructure;

package/types/buildPaginateHelper.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildPaginateHelper(model: RLCModel): {
+    path: string;
+    content: any;
+} | undefined;

package/types/buildParameterTypes.d.ts

@@ -0,0 +1,13 @@
+import { ParameterMetadatas, RLCModel } from "./interfaces.js";
+export declare function buildParameterTypes(model: RLCModel): {
+    path: string;
+    content: string;
+} | undefined;
+export declare function buildBodyTypeAlias(parameters: ParameterMetadatas): {
+    name: string;
+    type: string;
+    isExported: boolean;
+    docs?: {
+        description: string;
+    }[] | undefined;
+} | undefined;

package/types/buildPollingHelper.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildPollingHelper(model: RLCModel): {
+    path: string;
+    content: any;
+} | undefined;

package/types/buildResponseTypes.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildResponseTypes(model: RLCModel): {
+    path: string;
+    content: string;
+} | undefined;

package/types/buildSchemaType.d.ts

@@ -0,0 +1,19 @@
+import { Project } from "ts-morph";
+import { RLCModel, SchemaContext } from "./interfaces.js";
+/**
+ * Generates types to represent schema definitions in the swagger
+ */
+export declare function buildSchemaTypes(model: RLCModel): {
+    inputModelFile: {
+        path: string;
+        content: string;
+    } | undefined;
+    outputModelFile: {
+        path: string;
+        content: string;
+    } | undefined;
+};
+export declare function generateModelFiles(model: RLCModel, project: Project, filePath: string, schemaContext: SchemaContext[]): {
+    path: string;
+    content: string;
+} | undefined;

package/types/buildSerializeHelper.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildSerializeHelper(model: RLCModel): {
+    path: string;
+    content: any;
+} | undefined;

package/types/buildTopLevelIndexFile.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildTopLevelIndex(model: RLCModel): {
+    path: string;
+    content: string;
+} | undefined;

package/types/helpers/nameConstructors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Get the response type name by baseName or operatioName & statusCode
+ * @param baseResponseName
+ */
+export declare function getResponseTypeName(baseResponseName: string): string;
+export declare function getResponseTypeName(operationGroup: string, operationName: string, statusCode: string): string;
+/**
+ * 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 declare function getResponseBaseName(operationGroup: string, operationName: string, statusCode: string): string;
+/**
+ * The prefix of all parameter relevant types
+ * @param operationName is composed with operationGroup and operationID e.g string_PutEmpty
+ * @returns
+ */
+export declare function getParameterBaseName(operationGroup: string, operationName: string): string;
+/**
+ * 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 declare function getParameterTypeName(baseName: string): string;
+export declare function getParameterTypeName(operationGroup: string, operationName: string): string;

package/types/helpers/nameUtils.d.ts

@@ -0,0 +1,25 @@
+export interface ReservedName {
+    name: string;
+    reservedFor: NameType[];
+}
+export declare enum NameType {
+    Class = 0,
+    File = 1,
+    Interface = 2,
+    Property = 3,
+    Parameter = 4,
+    Operation = 5,
+    OperationGroup = 6
+}
+export declare enum CasingConvention {
+    Pascal = 0,
+    Camel = 1
+}
+export declare function guardReservedNames(name: string, nameType: NameType, customReservedNames?: ReservedName[]): string;
+export declare function normalizeName(name: string, nameType: NameType, shouldGuard?: boolean, customReservedNames?: ReservedName[], casingOverride?: CasingConvention): string;
+export declare function getModelsName(title: string): string;
+export declare function getMappersName(title: string): string;
+export declare function pascalCase(str: string): string;
+export declare function camelCase(str: string, options?: {
+    uppercaseThreshold?: number;
+}): string;

package/types/helpers/operationHelpers.d.ts

@@ -0,0 +1,13 @@
+import { MethodSignatureStructure, OptionalKind, ParameterDeclarationStructure } from "ts-morph";
+import { Methods, PathParameter, RLCModel } from "../interfaces.js";
+export declare function buildMethodDefinitions(methods: Methods, pathParams?: PathParameter[]): OptionalKind<MethodSignatureStructure>[];
+export declare function getPathParamDefinitions(pathParams: PathParameter[]): OptionalKind<ParameterDeclarationStructure>[];
+export declare function hasPagingOperations(model: RLCModel): boolean;
+export declare function hasPollingOperations(model: RLCModel): boolean;
+export declare function hasMultiCollection(model: RLCModel): boolean;
+export declare function hasPipeCollection(model: RLCModel): boolean;
+export declare function hasSsvCollection(model: RLCModel): boolean;
+export declare function hasTsvCollection(model: RLCModel): boolean;
+export declare function hasUnexpectedHelper(model: RLCModel): boolean;
+export declare function hasInputModels(model: RLCModel): boolean;
+export declare function hasOutputModels(model: RLCModel): boolean;

package/types/helpers/pathUtils.d.ts

@@ -0,0 +1 @@
+export declare function getRelativePartFromSrcPath(srcPath: string): string;

package/types/helpers/schemaHelpers.d.ts

@@ -0,0 +1,4 @@
+import { Schema } from "../interfaces.js";
+export declare function isDictionarySchema(schema: Schema): boolean;
+export declare function isObjectSchema(schema: Schema): boolean;
+export declare function isConstantSchema(schema: Schema): boolean;

package/types/helpers/shortcutMethods.d.ts

@@ -0,0 +1,3 @@
+import { OptionalKind, InterfaceDeclarationStructure } from "ts-morph";
+import { Paths } from "../interfaces.js";
+export declare function generateMethodShortcuts(paths: Paths): OptionalKind<InterfaceDeclarationStructure>[];

package/types/index.d.ts

@@ -0,0 +1,26 @@
+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/types/interfaces.d.ts

@@ -0,0 +1,200 @@
+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 declare 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 declare type Paths = Record<string, PathMetadata>;
+export declare 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 declare enum ImportKind {
+    ResponseOutput = 0,
+    ParameterInput = 1
+}
+export interface File {
+    path: string;
+    content: string;
+}
+export declare 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 {
+    isPartialBody?: boolean;
+    body?: ParameterBodySchema[];
+}
+export declare 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 declare type ResponseHeaderSchema = Schema;
+export declare type ResponseBodySchema = Schema;
+export declare type ContentBuilder = {
+    (model: RLCModel): File | undefined;
+    (model: RLCModel, hasSampleGenerated?: boolean): File | undefined;
+};

package/types/metadata/buildApiExtractorConfig.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "../interfaces.js";
+export declare function buildApiExtractorConfig(model: RLCModel): {
+    path: string;
+    content: string;
+} | undefined;

package/types/metadata/buildESLintConfig.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "../interfaces.js";
+export declare function buildEsLintConfig(model: RLCModel): {
+    path: string;
+    content: string;
+} | undefined;