@nestia/migrate 0.10.0 → 0.11.1

package/src/utils/openapi-down-convert/RefVisitor.ts

@@ -0,0 +1,139 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Recursively walk a JSON object and invoke a callback function
+ * on each `{ "$ref" : "path" }` object found
+ */
+
+/**
+ * Represents a JSON Reference object, such as
+ * `{"$ref": "#/components/schemas/problemResponse" }`
+ */
+export interface RefObject {
+  $ref: string;
+}
+
+/**
+ * JsonNode represents a node within the OpenAPI object
+ */
+export type JsonNode = object | [] | string | boolean | null | number;
+
+/** A JSON Schema object in an API def */
+export type SchemaObject = object;
+
+/**
+ * Function signature for the visitRefObjects callback
+ */
+export type RefVisitor = (node: RefObject) => JsonNode;
+/**
+ * Function signature for the visitSchemaObjects callback
+ */
+export type SchemaVisitor = (node: SchemaObject) => SchemaObject;
+
+/**
+/**
+ * Function signature for the walkObject callback
+ */
+export type ObjectVisitor = (node: object) => JsonNode;
+
+/**
+ * Test if a JSON node is a `{ $ref: "uri" }` object
+ */
+export function isRef(node: any): boolean {
+  return (
+    node !== null &&
+    typeof node === "object" &&
+    node.hasOwnProperty("$ref") &&
+    typeof node["$ref"] === "string"
+  );
+}
+
+/**
+ * Walk a JSON object and apply `schemaCallback` when a JSON schema is found.
+ * JSON Schema objects are items in components/schemas or in an item named `schema`
+ * @param node a node in the OpenAPI document
+ * @param schemaCallback the function to call on JSON schema objects
+ * @return the modified (annotated) node
+ */
+export function visitSchemaObjects(
+  node: any,
+  schemaCallback: SchemaVisitor,
+): any {
+  const objectVisitor = (node: any): JsonNode => {
+    if (node.hasOwnProperty("schema")) {
+      const schema = node["schema"];
+      if (schema != null && typeof schema === "object") {
+        node["schema"] = schemaCallback(schema);
+      }
+    } else if (node.hasOwnProperty("schemas")) {
+      const schemas = node["schemas"];
+      if (schemas != null && typeof schemas === "object") {
+        for (const schemaName in schemas) {
+          const schema = schemas[schemaName];
+          const newSchema = schemaCallback(schema);
+          schemas[schemaName] = newSchema;
+        }
+      }
+    }
+    return node;
+  };
+  return walkObject(node, objectVisitor);
+}
+
+/**
+ * Walk a JSON object and apply `refCallback` when a JSON `{$ref: url }` is found
+ * @param node a node in the OpenAPI document
+ * @param refCallback the function to call on JSON `$ref` objects
+ * @return the modified (annotated) node
+ */
+export function visitRefObjects(node: any, refCallback: RefVisitor): any {
+  const objectVisitor = (node: object): JsonNode => {
+    if (isRef(node)) {
+      return refCallback(node as RefObject);
+    }
+    return node;
+  };
+  return walkObject(node, objectVisitor);
+}
+
+/**
+ * Walk a JSON object or array and apply objectCallback when a JSON object is found
+ * @param node a node in the OpenAPI document
+ * @param objectCallback the function to call on JSON objects
+ * @param nav tracks where we are in the original document
+ * @return the modified (annotated) node
+ */
+export function walkObject(
+  node: object,
+  objectCallback: ObjectVisitor,
+): JsonNode {
+  return walkObj(node);
+
+  function walkObj(node: any): JsonNode {
+    const object = objectCallback(node);
+    if (object !== null && typeof object === "object") {
+      const keys = [...Object.keys(node)]; // make copy since this code may re-enter objects
+      for (const key of keys) {
+        const val = node[key];
+        if (Array.isArray(val)) {
+          node[key] = walkArray(val as []);
+        } else if (val !== null && typeof val === "object") {
+          node[key] = walkObj(val);
+        }
+      }
+    }
+    return object;
+  }
+
+  function walkArray(array: JsonNode[]): JsonNode[] {
+    for (let index = 0; index < array.length; index += 1) {
+      const val = array[index] as JsonNode;
+      if (val !== null && typeof val === "object") {
+        array[index] = walkObj(val) as object;
+      } else if (Array.isArray(val)) {
+        array[index] = walkArray(val as JsonNode[]) as [];
+      }
+    }
+    return array;
+  }
+}

package/src/utils/openapi-down-convert/converter.ts

@@ -0,0 +1,527 @@
+/** OpenAPI Down Converted - convert an OAS document from OAS 3.1 to OAS 3.0 */
+import {
+  JsonNode,
+  SchemaObject,
+  SchemaVisitor,
+  visitRefObjects,
+  visitSchemaObjects,
+  walkObject,
+} from "./RefVisitor";
+
+/** Lightweight OAS document top-level fields */
+interface OpenAPI3 {
+  openapi: string;
+  info: object;
+  paths: object;
+  components: object;
+  tags: object;
+}
+
+/** Options for the converter instantiation */
+export interface ConverterOptions {
+  /** if `true`, log conversion transformations to stderr  */
+  verbose?: boolean;
+  /** if `true`, remove `id` values in schema examples, to bypass
+   * [Spectral issue 2081](https://github.com/stoplightio/spectral/issues/2081)
+   */
+  deleteExampleWithId?: boolean;
+  /** If `true`, replace a `$ref` object that has siblings into an `allOf` */
+  allOfTransform?: boolean;
+
+  /**
+   * The authorizationUrl for openIdConnect -> oauth2 transformation
+   */
+  authorizationUrl?: string;
+  /** The tokenUrl for openIdConnect -> oauth2 transformation */
+  tokenUrl?: string;
+  /** Name of YAML/JSON file with scope descriptions.
+   * This is a simple map in the format
+   * `{ scope1: "description of scope1", ... }`
+   */
+  scopeDescriptionFile?: string;
+  /** Earlier versions of the tool converted $comment to x-comment
+   * in JSON Schemas. The tool now deletes $comment values by default.
+   * Use this option to preserve the conversion and not delete
+   * comments.
+   */
+  convertSchemaComments?: boolean;
+}
+
+export class Converter {
+  private openapi30: OpenAPI3;
+  private verbose = false;
+  private deleteExampleWithId = false;
+  private allOfTransform = false;
+  private authorizationUrl: string;
+  /** The tokenUrl for openIdConnect -> oauth2 transformation */
+  private tokenUrl: string;
+  private scopeDescriptions = undefined;
+  private convertSchemaComments = false;
+  private returnCode = 0;
+
+  /**
+   * Construct a new Converter
+   * @throws Error if the scopeDescriptionFile (if specified) cannot be read or parsed as YAML/JSON
+   */
+  constructor(openapiDocument: object, options?: ConverterOptions) {
+    this.openapi30 = Converter.deepClone(openapiDocument) as OpenAPI3;
+    this.verbose = Boolean(options?.verbose);
+    this.deleteExampleWithId = Boolean(options?.deleteExampleWithId);
+    this.allOfTransform = Boolean(options?.allOfTransform);
+    this.authorizationUrl =
+      options?.authorizationUrl || "https://www.example.com/oauth2/authorize";
+    this.tokenUrl = options?.tokenUrl || "https://www.example.com/oauth2/token";
+    this.loadScopeDescriptions(options?.scopeDescriptionFile);
+    this.convertSchemaComments = !!options?.convertSchemaComments;
+  }
+
+  /** Load the scopes.yaml file and save in this.scopeDescriptions
+   * @throws Error if the file cannot be read or parsed as YAML/JSON
+   */
+  private loadScopeDescriptions(scopeDescriptionFile?: string) {
+    if (!scopeDescriptionFile) {
+      return;
+    }
+  }
+
+  /**
+   * Log a message  to console.warn stream if verbose is true
+   * @param message parameters for console.warn
+   */
+  private log(...message: any[]) {
+    if (this.verbose) {
+      this.warn(...message);
+    }
+  }
+
+  /**
+   * Log a message  to console.warn stream. Prefix the message string with `Warning: `
+   * if it does not already have that text.
+   * @param message parameters for console.warn
+   */
+  private warn(...message: any[]) {
+    if (!message[0].startsWith("Warning")) {
+      message[0] = `Warning: ${message[0]}`;
+    }
+    console.warn(...message);
+  }
+
+  /**
+   * Log an error message to `console.error` stream. Prefix the message string with `Error: `
+   * if it does not already start with `'Error'`. Increments the `returnCode`, causing
+   * the CLI to throw an Error when done.
+   * @param message parameters for `console.error`
+   */
+  private error(...message: any[]) {
+    if (!message[0].startsWith("Error")) {
+      message[0] = `Error: ${message[0]}`;
+    }
+    this.returnCode++;
+    console.error(...message);
+  }
+
+  /**
+   * Convert the OpenAPI document to 3.0
+   * @returns the converted document. The input is not modified.
+   */
+  public convert(): object {
+    this.log("Converting from OpenAPI 3.1 to 3.0");
+    this.openapi30.openapi = "3.0.3";
+    this.removeLicenseIdentifier();
+    this.convertSchemaRef();
+    this.simplifyNonSchemaRef();
+    if (this.scopeDescriptions) {
+      this.convertSecuritySchemes();
+    }
+    this.convertJsonSchemaExamples();
+    this.convertJsonSchemaContentEncoding();
+    this.convertJsonSchemaContentMediaType();
+    this.convertConstToEnum();
+    this.convertNullableTypeArray();
+    this.removeWebhooksObject();
+    this.removeUnsupportedSchemaKeywords();
+    if (this.convertSchemaComments) {
+      this.renameSchema$comment();
+    } else {
+      this.deleteSchema$comment();
+    }
+    if (this.returnCode > 0) {
+      throw new Error("Cannot down convert this OpenAPI definition.");
+    }
+    return this.openapi30;
+  }
+
+  /**
+   * OpenAPI 3.1 uses JSON Schema 2020-12 which allows schema `examples`;
+   * OpenAPI 3.0 uses JSON Scheme Draft 7 which only allows `example`.
+   * Replace all `examples` with `example`, using `examples[0]`
+   */
+  convertJsonSchemaExamples() {
+    const schemaVisitor: SchemaVisitor = (schema: any): SchemaObject => {
+      for (const key in schema) {
+        const subSchema = schema[key];
+        if (subSchema !== null && typeof subSchema === "object") {
+          if (key === "examples") {
+            const examples = schema["examples"];
+            if (Array.isArray(examples) && examples.length > 0) {
+              delete schema["examples"];
+              const first = examples[0];
+              if (
+                this.deleteExampleWithId &&
+                first != null &&
+                typeof first === "object" &&
+                first.hasOwnProperty("id")
+              ) {
+                this.log(
+                  `Deleted schema example with \`id\` property:\n${this.json(examples)}`,
+                );
+              } else {
+                schema["example"] = first;
+                this.log(
+                  `Replaces examples with examples[0]. Old examples:\n${this.json(examples)}`,
+                );
+              }
+              // TODO: Add an else here to check example for `id` and delete the example if this.deleteExampleWithId
+              // We've put most of those in `examples` so this is probably not needed, but it would be more robust.
+            }
+          } else {
+            schema[key] = walkObject(subSchema, schemaVisitor);
+          }
+        }
+      }
+      return schema;
+    };
+    visitSchemaObjects(this.openapi30, schemaVisitor);
+  }
+
+  private walkNestedSchemaObjects(schema: any, schemaVisitor: any) {
+    for (const key in schema) {
+      const subSchema = schema[key];
+      if (subSchema !== null && typeof subSchema === "object") {
+        schema[key] = walkObject(subSchema, schemaVisitor);
+      }
+    }
+    return schema;
+  }
+
+  /**
+   * OpenAPI 3.1 uses JSON Schema 2020-12 which allows `const`
+   * OpenAPI 3.0 uses JSON Scheme Draft 7 which only allows `enum`.
+   * Replace all `const: value` with `enum: [ value ]`
+   */
+  convertConstToEnum() {
+    const schemaVisitor: SchemaVisitor = (schema: any): SchemaObject => {
+      if (schema["const"]) {
+        const constant = schema["const"];
+        delete schema["const"];
+        schema["enum"] = [constant];
+        this.log(`Converted const: ${constant} to enum`);
+      }
+      return this.walkNestedSchemaObjects(schema, schemaVisitor);
+    };
+    visitSchemaObjects(this.openapi30, schemaVisitor);
+  }
+
+  /**
+   * Convert 2-element type arrays containing 'null' to
+   * string type and `nullable: true`
+   */
+  convertNullableTypeArray() {
+    const schemaVisitor: SchemaVisitor = (schema: any): SchemaObject => {
+      if (schema.hasOwnProperty("type")) {
+        const schemaType = schema["type"];
+        if (
+          Array.isArray(schemaType) &&
+          schemaType.length === 2 &&
+          schemaType.includes("null")
+        ) {
+          const nonNull = schemaType.filter((_) => _ !== "null")[0];
+          schema["type"] = nonNull;
+          schema["nullable"] = true;
+          this.log(`Converted schema type array to nullable`);
+        }
+      }
+      return this.walkNestedSchemaObjects(schema, schemaVisitor);
+    };
+    visitSchemaObjects(this.openapi30, schemaVisitor);
+  }
+
+  removeWebhooksObject() {
+    if (Object.hasOwnProperty.call(this.openapi30, "webhooks")) {
+      this.log(`Deleted webhooks object`);
+      delete (this.openapi30 as any)["webhooks"];
+    }
+  }
+  removeUnsupportedSchemaKeywords() {
+    const keywordsToRemove = [
+      "$id",
+      "$schema",
+      "unevaluatedProperties",
+      "contentMediaType",
+      "patternProperties",
+    ];
+    const schemaVisitor: SchemaVisitor = (schema: any): SchemaObject => {
+      keywordsToRemove.forEach((key) => {
+        if (schema.hasOwnProperty(key)) {
+          delete schema[key];
+          this.log(`Removed unsupported schema keyword ${key}`);
+        }
+      });
+      return this.walkNestedSchemaObjects(schema, schemaVisitor);
+    };
+    visitSchemaObjects(this.openapi30, schemaVisitor);
+  }
+
+  renameSchema$comment() {
+    const schemaVisitor: SchemaVisitor = (schema: any): SchemaObject => {
+      if (schema.hasOwnProperty("$comment")) {
+        schema["x-comment"] = schema["$comment"];
+        delete schema["$comment"];
+        this.log(`schema $comment renamed to x-comment`);
+      }
+      return this.walkNestedSchemaObjects(schema, schemaVisitor);
+    };
+    visitSchemaObjects(this.openapi30, schemaVisitor);
+  }
+
+  private deleteSchema$comment() {
+    const schemaVisitor: SchemaVisitor = (schema: any): SchemaObject => {
+      if (schema.hasOwnProperty("$comment")) {
+        const comment = schema["$comment"];
+        delete schema["$comment"];
+        this.log(`schema $comment deleted: ${comment}`);
+      }
+      return this.walkNestedSchemaObjects(schema, schemaVisitor);
+    };
+    visitSchemaObjects(this.openapi30, schemaVisitor);
+  }
+
+  /**
+   * Convert
+   * ```
+   * contentMediaType: 'application/octet-stream'
+   * ```
+   * to
+   * ```
+   * format: binary
+   * ```
+   * in `type: string` schemas.
+   * Warn if schema has a `format` already and it is not `binary`.
+   */
+  convertJsonSchemaContentMediaType() {
+    const schemaVisitor: SchemaVisitor = (schema: any): SchemaObject => {
+      if (
+        schema.hasOwnProperty("type") &&
+        schema["type"] === "string" &&
+        schema.hasOwnProperty("contentMediaType") &&
+        schema["contentMediaType"] === "application/octet-stream"
+      ) {
+        if (schema.hasOwnProperty("format")) {
+          if (schema["format"] === "binary") {
+            this.log(
+              `Deleted schema contentMediaType: application/octet-stream (leaving format: binary)`,
+            );
+            delete schema["contentMediaType"];
+          } else {
+            this.error(
+              `Unable to down-convert schema with contentMediaType: application/octet-stream to format: binary because the schema already has a format (${schema["format"]})`,
+            );
+          }
+        } else {
+          delete schema["contentMediaType"];
+          schema["format"] = "binary";
+          this.log(
+            `Converted schema contentMediaType: application/octet-stream to format: binary`,
+          );
+        }
+      }
+      return this.walkNestedSchemaObjects(schema, schemaVisitor);
+    };
+    visitSchemaObjects(this.openapi30, schemaVisitor);
+  }
+
+  /**
+   * Convert
+   * ```
+   * contentEncoding: base64
+   * ```
+   * to
+   * ```
+   * format: byte
+   * ```
+   * in `type: string` schemas. It is an error if the schema has a `format` already
+   * and it is not `byte`.
+   */
+  convertJsonSchemaContentEncoding() {
+    const schemaVisitor: SchemaVisitor = (schema: any): SchemaObject => {
+      if (
+        schema.hasOwnProperty("type") &&
+        schema["type"] === "string" &&
+        schema.hasOwnProperty("contentEncoding")
+      ) {
+        if (schema["contentEncoding"] === "base64") {
+          if (schema.hasOwnProperty("format")) {
+            if (schema["format"] === "byte") {
+              this.log(
+                `Deleted schema contentEncoding: base64 (leaving format: byte)`,
+              );
+              delete schema["contentEncoding"];
+            } else {
+              this.error(
+                `Unable to down-convert schema contentEncoding: base64 to format: byte because the schema already has a format (${schema["format"]})`,
+              );
+            }
+          } else {
+            delete schema["contentEncoding"];
+            schema["format"] = "byte";
+            this.log(
+              `Converted schema: 'contentEncoding: base64' to 'format: byte'`,
+            );
+          }
+        } else {
+          this.error(
+            `Unable to down-convert contentEncoding: ${schema["contentEncoding"]}`,
+          );
+        }
+      }
+      return this.walkNestedSchemaObjects(schema, schemaVisitor);
+    };
+    visitSchemaObjects(this.openapi30, schemaVisitor);
+  }
+
+  private json(x: any) {
+    return JSON.stringify(x, null, 2);
+  }
+
+  /**
+   * OpenAPI 3.1 defines a new `openIdConnect` security scheme.
+   * Down-convert the scheme to `oauth2` / authorization code flow.
+   * Collect all the scopes used in any security requirements within
+   * operations and add them to the scheme. Also define the
+   * URLs to the `authorizationUrl` and `tokenUrl` of `oauth2`.
+   */
+  convertSecuritySchemes() {
+    const oauth2Scopes = (schemeName: string): object => {
+      const scopes = {} as any;
+      const paths: any = this.openapi30?.paths ?? {};
+      for (const path in paths) {
+        for (const op in paths[path]) {
+          if (op === "parameters") {
+            continue;
+          }
+          const operation = paths[path][op];
+          const sec = operation?.security as object[];
+          sec.forEach((s: any) => {
+            const requirement = s?.[schemeName] as string[];
+            if (requirement) {
+              requirement.forEach((scope) => {
+                scopes[scope] =
+                  this.scopeDescriptions?.[scope] ??
+                  `TODO: describe the '${scope}' scope`;
+              });
+            }
+          });
+        }
+      }
+      return scopes;
+    };
+    const schemes =
+      (this.openapi30?.components as any)?.["securitySchemes"] ?? {};
+    for (const schemeName in schemes) {
+      const scheme = schemes[schemeName];
+      const type = scheme.type;
+      if (type === "openIdConnect") {
+        this.log(
+          `Converting openIdConnect security scheme to oauth2/authorizationCode`,
+        );
+        scheme.type = "oauth2";
+        const openIdConnectUrl = scheme.openIdConnectUrl;
+        scheme.description = `OAuth2 Authorization Code Flow. The client may
+          GET the OpenID Connect configuration JSON from \`${openIdConnectUrl}\`
+          to get the correct \`authorizationUrl\` and \`tokenUrl\`.`;
+        delete scheme.openIdConnectUrl;
+        const scopes = oauth2Scopes(schemeName);
+        scheme.flows = {
+          authorizationCode: {
+            // TODO: add options for these URLs
+            authorizationUrl: this.authorizationUrl,
+            tokenUrl: this.tokenUrl,
+            scopes: scopes,
+          },
+        };
+      }
+    }
+  }
+
+  /**
+   * Find remaining OpenAPI 3.0 [Reference Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)
+   * and down convert them to [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) objects
+   * with _only_ a `$ref` property.
+   */
+  simplifyNonSchemaRef() {
+    visitRefObjects(this.openapi30, (node: any): JsonNode => {
+      if (Object.keys(node).length === 1) {
+        return node;
+      } else {
+        this.log(
+          `Down convert reference object to JSON Reference:\n${JSON.stringify(node, null, 3)}`,
+        );
+        Object.keys(node)
+          .filter((key) => key !== "$ref")
+          .forEach((key) => delete node[key]);
+        return node;
+      }
+    });
+  }
+
+  removeLicenseIdentifier() {
+    if ((this.openapi30 as any)?.["info"]?.["license"]?.["identifier"]) {
+      this.log(
+        `Removed info.license.identifier: ${(this.openapi30 as any)["info"]["license"]["identifier"]}`,
+      );
+      delete (this.openapi30 as any)["info"]["license"]["identifier"];
+    }
+  }
+
+  // This transformation ends up breaking openapi-generator
+  // SDK gen (typescript-axios, typescript-angular)
+  // so it is disabled unless the `allOfTransform` option is `true`.
+
+  convertSchemaRef() {
+    /**
+     * In a JSON Schema, replace `{ blah blah, $ref: "uri"}`
+     * with `{ blah blah, allOf: [ $ref: "uri" ]}`
+     * @param object an object that may contain JSON schemas (directly
+     * or in sub-objects)
+     */
+    const simplifyRefObjectsInSchemas = (
+      object: SchemaObject,
+    ): SchemaObject => {
+      return visitRefObjects(object, (node: any): JsonNode => {
+        if (Object.keys(node).length === 1) {
+          return node;
+        } else {
+          this.log(
+            `Converting JSON Schema $ref ${this.json(node)} to allOf: [ $ref ]`,
+          );
+          node["allOf"] = [{ $ref: node.$ref }];
+          delete node.$ref;
+          return node;
+        }
+      });
+    };
+
+    if (this.allOfTransform) {
+      visitSchemaObjects(
+        this.openapi30,
+        (schema: SchemaObject): SchemaObject => {
+          return simplifyRefObjectsInSchemas(schema);
+        },
+      );
+    }
+  }
+
+  public static deepClone(obj: object): object {
+    return JSON.parse(JSON.stringify(obj)); // kinda simple way to clone, but it works...
+  }
+}

package/lib/utils/SwaggerExplorer.js

@@ -1,2 +0,0 @@
-"use strict";
-//# sourceMappingURL=SwaggerExplorer.js.map

package/lib/utils/SwaggerExplorer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"SwaggerExplorer.js","sourceRoot":"","sources":["../../src/utils/SwaggerExplorer.ts"],"names":[],"mappings":""}