@azure-tools/rlc-common 1.0.0-beta.1

package/src/interfaces.ts

@@ -0,0 +1,212 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+export interface RLCModel {
+  libraryName: string;
+  srcPath: string;
+  paths: Paths;
+  options?: RLCOptions;
+  schemas: Schema[];
+  apiVersionParam?: Parameter;
+  parameters?: OperationParameter[];
+  responses?: OperationResponse[];
+  importSet?: Map<ImportKind, Set<string>>;
+  annotations?: AnnotationDetails;
+  urlInfo?: UrlInfo;
+}
+
+export interface UrlInfo {
+  endpoint?: string;
+  urlParameters?: PathParameter[];
+}
+export interface AnnotationDetails {
+  hasPaging?: boolean;
+  hasLongRunning?: boolean;
+  pageDetails?: PagingDetails;
+}
+
+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;
+};
+
+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;
+}
+
+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[];
+}
+
+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()
+  };
+}

package/src/metadata/buildPackageFile.ts

@@ -0,0 +1,271 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project } from "ts-morph";
+import {
+  hasPagingOperations,
+  hasPollingOperations
+} from "../helpers/operationHelpers.js";
+import { RLCModel } from "../interfaces.js";
+
+export function buildPackageFile(model: RLCModel, hasSamplesGenerated = false) {
+  const generateMetadata = Boolean(model.options?.generateMetadata);
+  if (!generateMetadata) {
+    return;
+  }
+  const project = new Project();
+  const filePath = "package.json";
+  const packageJsonContents = restLevelPackage(model, hasSamplesGenerated);
+  // return direclty if no content generated
+  if (!packageJsonContents) {
+    return;
+  }
+
+  const packageFile = project.createSourceFile(
+    filePath,
+    JSON.stringify(packageJsonContents),
+    {
+      overwrite: true
+    }
+  );
+  return {
+    path: filePath,
+    content: packageFile.getFullText()
+  };
+}
+
+/**
+ * This function defines the REST Level client package.json file
+ * or High Level Client
+ */
+function restLevelPackage(model: RLCModel, hasSamplesGenerated: boolean) {
+  if (!model.options || !model.options.packageDetails) {
+    return;
+  }
+
+  const {
+    packageDetails,
+    generateTest,
+    generateSample,
+    azureOutputDirectory,
+    azureSdkForJs,
+    isCadlTest
+  } = model.options;
+
+  const clientPackageName = packageDetails.name;
+  let apiRefUrlQueryParameter: string = "";
+  if (packageDetails.version.includes("beta")) {
+    apiRefUrlQueryParameter = "?view=azure-node-preview";
+  }
+  const description = packageDetails.description;
+  const hasPaging = hasPagingOperations(model);
+  const hasLRO = hasPollingOperations(model);
+  const packageInfo: Record<string, any> = {
+    name: `${packageDetails.name}`,
+    "sdk-type": "client",
+    author: "Microsoft Corporation",
+    version: `${packageDetails.version}`,
+    description:
+      `${packageDetails.description}` ||
+      `A generated SDK for ${model.libraryName}.`,
+    keywords: ["node", "azure", "cloud", "typescript", "browser", "isomorphic"],
+    license: "MIT",
+    main: "dist/index.js",
+    module: generateTest ? "./dist-esm/src/index.js" : "./dist-esm/index.js",
+    types: `./types/${packageDetails.nameWithoutScope}.d.ts`,
+    repository: "github:Azure/azure-sdk-for-js",
+    bugs: {
+      url: "https://github.com/Azure/azure-sdk-for-js/issues"
+    },
+    files: [
+      "dist/",
+      generateTest ? "dist-esm/src/" : "dist-esm/",
+      `types/${packageDetails.nameWithoutScope}.d.ts`,
+      "README.md",
+      "LICENSE",
+      "review/*"
+    ],
+    engines: {
+      node: ">=14.0.0"
+    },
+    scripts: {
+      audit:
+        "node ../../../common/scripts/rush-audit.js && rimraf node_modules package-lock.json && npm i --package-lock-only 2>&1 && npm audit",
+      "build:browser": "echo skipped.",
+      "build:node": "echo skipped.",
+      "build:samples": "echo skipped.",
+      "build:test": "echo skipped.",
+      "build:debug": "echo skipped.",
+      "check-format":
+        'prettier --list-different --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore "src/**/*.ts" "test/**/*.ts" "samples-dev/**/*.ts" "*.{js,json}"',
+      clean:
+        "rimraf dist dist-browser dist-esm test-dist temp types *.tgz *.log",
+      "execute:samples": "echo skipped",
+      "extract-api":
+        "rimraf review && mkdirp ./review && api-extractor run --local",
+      format:
+        'prettier --write --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore "src/**/*.ts" "test/**/*.ts" "samples-dev/**/*.ts" "*.{js,json}"',
+      "generate:client":
+        "autorest --typescript swagger/README.md && npm run format",
+      "integration-test:browser": "echo skipped",
+      "integration-test:node": "echo skipped",
+      "integration-test": "echo skipped",
+      "lint:fix":
+        "eslint package.json api-extractor.json src test --ext .ts --fix --fix-type [problem,suggestion]",
+      lint: "eslint package.json api-extractor.json src test --ext .ts",
+      pack: "npm pack 2>&1",
+      "test:browser": "echo skipped",
+      "test:node": "echo skipped",
+      test: 'echo "Error: no test specified" && exit 1',
+      "unit-test": "echo skipped",
+      "unit-test:node": "echo skipped",
+      "unit-test:browser": "echo skipped"
+    },
+    sideEffects: false,
+    autoPublish: false,
+    dependencies: {
+      "@azure/core-auth": "^1.3.0",
+      "@azure-rest/core-client": "1.0.0-beta.10",
+      "@azure/core-rest-pipeline": "^1.8.0",
+      "@azure/logger": "^1.0.0",
+      tslib: "^2.2.0",
+      ...(hasPaging && {
+        "@azure/core-paging": "^1.2.0"
+      }),
+      ...(hasLRO && {
+        "@azure/core-lro": "^2.2.0"
+      })
+    },
+    devDependencies: {
+      "@microsoft/api-extractor": "^7.31.1",
+      autorest: "latest",
+      "@types/node": "^14.0.0",
+      dotenv: "^8.2.0",
+      eslint: "^8.0.0",
+      mkdirp: "^1.0.4",
+      prettier: "2.2.1",
+      rimraf: "^3.0.0",
+      "source-map-support": "^0.5.9",
+      typescript: "~4.6.0"
+    }
+  };
+
+  if (azureOutputDirectory) {
+    packageInfo.homepage = `https://github.com/Azure/azure-sdk-for-js/tree/main/${azureOutputDirectory}/README.md`;
+  }
+
+  if (azureSdkForJs) {
+    packageInfo["//metadata"] = {
+      constantPaths: [
+        {
+          path: "swagger/README.md",
+          prefix: "package-version"
+        }
+      ]
+    };
+    packageInfo.scripts["build"] =
+      "npm run clean && tsc -p . && dev-tool run bundle && mkdirp ./review && api-extractor run --local";
+    packageInfo.scripts["build:debug"] =
+      "tsc -p . && dev-tool run bundle && api-extractor run --local";
+    packageInfo.scripts["build:browser"] = "tsc -p . && dev-tool run bundle";
+    packageInfo.scripts["build:node"] = "tsc -p . && dev-tool run bundle";
+    packageInfo.devDependencies["@azure/dev-tool"] = "^1.0.0";
+    packageInfo.devDependencies["@azure/eslint-plugin-azure-sdk"] = "^3.0.0";
+  } else {
+    packageInfo.scripts["build"] =
+      "npm run clean && tsc && rollup -c 2>&1 && npm run minify && mkdirp ./review && npm run extract-api";
+    packageInfo.scripts[
+      "minify"
+    ] = `uglifyjs -c -m --comments --source-map "content='./dist/index.js.map'" -o ./dist/index.min.js ./dist/index.js`;
+    packageInfo.devDependencies["@rollup/plugin-commonjs"] = "^21.0.1";
+    packageInfo.devDependencies["@rollup/plugin-json"] = "^4.1.0";
+    packageInfo.devDependencies["@rollup/plugin-multi-entry"] = "^4.1.0";
+    packageInfo.devDependencies["@rollup/plugin-node-resolve"] = "^13.1.3";
+    packageInfo.devDependencies["rollup"] = "^2.66.1";
+    packageInfo.devDependencies["rollup-plugin-sourcemaps"] = "^0.6.3";
+    packageInfo.devDependencies["uglify-js"] = "^3.4.9";
+  }
+
+  if (isCadlTest) {
+    packageInfo["type"] = "module";
+  }
+
+  if (generateTest) {
+    packageInfo.module = `./dist-esm/src/index.js`;
+    packageInfo.devDependencies["@azure-tools/test-credential"] = "^1.0.0";
+    packageInfo.devDependencies["@azure/identity"] = "^2.0.1";
+    packageInfo.devDependencies["@azure-tools/test-recorder"] = "^2.0.0";
+    packageInfo.devDependencies["mocha"] = "^7.1.1";
+    packageInfo.devDependencies["mocha-junit-reporter"] = "^1.18.0";
+    packageInfo.devDependencies["cross-env"] = "^7.0.2";
+    packageInfo.devDependencies["@types/chai"] = "^4.2.8";
+    packageInfo.devDependencies["chai"] = "^4.2.0";
+    packageInfo.devDependencies["cross-env"] = "^7.0.2";
+    packageInfo.devDependencies["karma-chrome-launcher"] = "^3.0.0";
+    packageInfo.devDependencies["karma-coverage"] = "^2.0.0";
+    packageInfo.devDependencies["karma-edge-launcher"] = "^0.4.2";
+    packageInfo.devDependencies["karma-env-preprocessor"] = "^0.1.1";
+    packageInfo.devDependencies["karma-firefox-launcher"] = "^1.1.0";
+    packageInfo.devDependencies["karma-ie-launcher"] = "^1.0.0";
+    packageInfo.devDependencies["karma-junit-reporter"] = "^2.0.1";
+    packageInfo.devDependencies["karma-mocha-reporter"] = "^2.2.5";
+    packageInfo.devDependencies["karma-mocha"] = "^2.0.1";
+    packageInfo.devDependencies["karma-source-map-support"] = "~1.4.0";
+    packageInfo.devDependencies["karma-sourcemap-loader"] = "^0.3.8";
+    packageInfo.devDependencies["karma"] = "^6.2.0";
+    packageInfo.devDependencies["nyc"] = "^14.0.0";
+    packageInfo.devDependencies["source-map-support"] = "^0.5.9";
+    packageInfo.scripts["test"] =
+      "npm run clean && npm run build:test && npm run unit-test";
+    packageInfo.scripts["test:node"] =
+      "npm run clean && npm run build:test && npm run unit-test:node";
+    packageInfo.scripts["test:browser"] =
+      "npm run clean && npm run build:test && npm run unit-test:browser";
+    packageInfo.scripts["build:browser"] =
+      "tsc -p . && cross-env ONLY_BROWSER=true rollup -c 2>&1";
+    packageInfo.scripts["build:node"] =
+      "tsc -p . && cross-env ONLY_NODE=true rollup -c 2>&1";
+    packageInfo.scripts["build:test"] = "tsc -p . && rollup -c 2>&1";
+    packageInfo.scripts["unit-test"] =
+      "npm run unit-test:node && npm run unit-test:browser";
+    packageInfo.scripts["unit-test:node"] =
+      'mocha -r esm --require ts-node/register --reporter ../../../common/tools/mocha-multi-reporter.js --timeout 1200000 --full-trace "test/{,!(browser)/**/}*.spec.ts"';
+    packageInfo.scripts["unit-test:browser"] = "karma start --single-run";
+    packageInfo.scripts["integration-test:browser"] =
+      "karma start --single-run";
+    packageInfo.scripts["integration-test:node"] =
+      'nyc mocha -r esm --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js --timeout 5000000 --full-trace "dist-esm/test/{,!(browser)/**/}*.spec.js"';
+    packageInfo.scripts["integration-test"] =
+      "npm run integration-test:node && npm run integration-test:browser";
+    if (azureSdkForJs) {
+      packageInfo.scripts["build:test"] = "tsc -p . && dev-tool run bundle";
+      packageInfo.scripts["integration-test:browser"] =
+        "dev-tool run test:browser";
+      packageInfo.scripts["unit-test:browser"] = "dev-tool run test:browser";
+      packageInfo.scripts["unit-test:node"] =
+        "dev-tool run test:node-ts-input -- --timeout 1200000 --exclude 'test/**/browser/*.spec.ts' 'test/**/*.spec.ts'";
+      packageInfo.scripts["integration-test:node"] =
+        "dev-tool run test:node-js-input -- --timeout 5000000 'dist-esm/test/**/*.spec.js'";
+    }
+
+    packageInfo["browser"] = {
+      "./dist-esm/test/public/utils/env.js":
+        "./dist-esm/test/public/utils/env.browser.js"
+    };
+  }
+
+  if (generateSample && hasSamplesGenerated) {
+    packageInfo["//sampleConfiguration"] = {
+      productName: model.options.serviceInfo?.title ?? model.libraryName,
+      productSlugs: ["azure"],
+      disableDocsMs: true,
+      apiRefLink: `https://docs.microsoft.com/javascript/api/${clientPackageName}${apiRefUrlQueryParameter}`
+    };
+    if (azureSdkForJs) {
+      packageInfo.scripts["execute:samples"] =
+        "dev-tool samples run samples-dev";
+    }
+  }
+
+  return packageInfo;
+}