@scalar/openapi-parser 0.4.0 → 0.5.0

package/dist/src/configuration.js

@@ -0,0 +1,22 @@
+import Swagger20 from '../schemas/v2.0/schema.json.js';
+import OpenApi30 from '../schemas/v3.0/schema.json.js';
+import OpenApi31 from '../schemas/v3.1/schema.json.js';
+
+const OpenApiSpecifications = {
+  "2.0": Swagger20,
+  "3.0": OpenApi30,
+  "3.1": OpenApi31
+};
+const OpenApiVersions = Object.keys(
+  OpenApiSpecifications
+);
+const ERRORS = {
+  EMPTY_OR_INVALID: "Cannot find JSON, YAML or filename in data",
+  // URI_MUST_BE_STRING: 'uri parameter or $id attribute must be a string',
+  OPENAPI_VERSION_NOT_SUPPORTED: "Cannot find supported Swagger/OpenAPI version in specification, version must be a string.",
+  INVALID_REFERENCE: "Can\u2019t resolve reference: %s",
+  EXTERNAL_REFERENCE_NOT_FOUND: "Can\u2019t resolve external reference: %s",
+  FILE_DOES_NOT_EXIST: "File does not exist: %s"
+};
+
+export { ERRORS, OpenApiSpecifications, OpenApiVersions };

package/dist/src/index.js

@@ -0,0 +1,27 @@
+export { openapi } from './pipeline.js';
+export { Validator, jsonSchemaVersions } from './lib/Validator/Validator.js';
+export { resolveReferences } from './utils/resolveReferences.js';
+export { dereference } from './utils/dereference.js';
+export { details } from './utils/details.js';
+export { escapeJsonPointer } from './utils/escapeJsonPointer.js';
+export { filter } from './utils/filter.js';
+export { getEntrypoint } from './utils/getEntrypoint.js';
+export { getListOfReferences } from './utils/getListOfReferences.js';
+export { getSegmentsFromPath } from './utils/getSegmentsFromPath.js';
+export { isFilesystem } from './utils/isFilesystem.js';
+export { isJson } from './utils/isJson.js';
+export { isObject } from './utils/isObject.js';
+export { isYaml } from './utils/isYaml.js';
+export { load } from './utils/load/load.js';
+export { fetchUrlsPlugin, fetchUrlsPluginDefaultConfiguration } from './utils/load/plugins/fetchUrlsPlugin.js';
+export { readFilesPlugin } from './utils/load/plugins/readFilesPlugin.js';
+export { normalize } from './utils/normalize.js';
+export { toJson } from './utils/toJson.js';
+export { toYaml } from './utils/toYaml.js';
+export { transformErrors } from './utils/transformErrors.js';
+export { traverse } from './utils/traverse.js';
+export { unescapeJsonPointer } from './utils/unescapeJsonPointer.js';
+export { upgrade } from './utils/upgrade.js';
+export { upgradeFromThreeToThreeOne } from './utils/upgradeFromThreeToThreeOne.js';
+export { upgradeFromTwoToThree } from './utils/upgradeFromTwoToThree.js';
+export { validate } from './utils/validate.js';

package/dist/src/lib/Validator/Validator.js

@@ -0,0 +1,94 @@
+import Ajv04 from 'ajv-draft-04';
+import addFormats from 'ajv-formats';
+import Ajv2020 from 'ajv/dist/2020';
+import { ERRORS, OpenApiVersions, OpenApiSpecifications } from '../../configuration.js';
+import { details } from '../../utils/details.js';
+import { resolveReferences } from '../../utils/resolveReferences.js';
+import { transformErrors } from '../../utils/transformErrors.js';
+
+const jsonSchemaVersions = {
+  "http://json-schema.org/draft-04/schema#": Ajv04,
+  "https://json-schema.org/draft/2020-12/schema": Ajv2020
+};
+class Validator {
+  constructor() {
+    // Object with function *or* object { errors: string }
+    this.ajvValidators = {};
+  }
+  /**
+   * Checks whether a specification is valid and all references can be resolved.
+   */
+  async validate(filesystem) {
+    const entrypoint = filesystem.find((file) => file.isEntrypoint);
+    const specification = entrypoint?.specification;
+    this.specification = specification;
+    if (this.specification?.info && !this.specification.info.version) {
+      this.specification.info.version = "0.0.1";
+    }
+    try {
+      if (specification === void 0 || specification === null) {
+        return {
+          valid: false,
+          errors: transformErrors(entrypoint, ERRORS.EMPTY_OR_INVALID)
+        };
+      }
+      const { version, specificationType, specificationVersion } = details(specification);
+      this.version = version;
+      this.specificationVersion = specificationVersion;
+      this.specificationType = specificationType;
+      if (!version) {
+        return {
+          valid: false,
+          errors: transformErrors(
+            entrypoint,
+            ERRORS.OPENAPI_VERSION_NOT_SUPPORTED
+          )
+        };
+      }
+      const validateSchema = await this.getAjvValidator(version);
+      const schemaResult = validateSchema(specification);
+      if (validateSchema.errors) {
+        if (validateSchema.errors.length > 0) {
+          return {
+            valid: false,
+            errors: transformErrors(entrypoint, validateSchema.errors)
+          };
+        }
+      }
+      const resolvedReferences = resolveReferences(filesystem);
+      return {
+        valid: schemaResult && resolvedReferences.valid,
+        errors: [...schemaResult.errors ?? [], ...resolvedReferences.errors],
+        schema: resolvedReferences.schema
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        errors: transformErrors(entrypoint, error.message ?? error)
+      };
+    }
+  }
+  /**
+   * Ajv JSON schema validator
+   */
+  async getAjvValidator(version) {
+    if (this.ajvValidators[version]) {
+      return this.ajvValidators[version];
+    }
+    const schema = OpenApiSpecifications[version];
+    const AjvClass = jsonSchemaVersions[schema.$schema];
+    const ajv = new AjvClass({
+      // Ajv is a bit too strict in its strict validation of OpenAPI schemas.
+      // Switch strict mode off.
+      strict: false
+    });
+    addFormats(ajv);
+    if (version === "3.1") {
+      ajv.addFormat("media-range", true);
+    }
+    return this.ajvValidators[version] = ajv.compile(schema);
+  }
+}
+Validator.supportedVersions = OpenApiVersions;
+
+export { Validator, jsonSchemaVersions };

package/dist/src/pipeline.js

@@ -0,0 +1,131 @@
+import { makeFilesystem } from './utils/makeFilesystem.js';
+import { upgrade } from './utils/upgrade.js';
+import { validate } from './utils/validate.js';
+import { dereference } from './utils/dereference.js';
+import { filter } from './utils/filter.js';
+import { getEntrypoint } from './utils/getEntrypoint.js';
+import { details } from './utils/details.js';
+import { toJson } from './utils/toJson.js';
+import { toYaml } from './utils/toYaml.js';
+import { load } from './utils/load/load.js';
+
+function openapi() {
+  return {
+    load: loadAction
+  };
+}
+function loadAction(specification, options) {
+  const queue = {
+    specification,
+    tasks: [
+      {
+        action: load,
+        options
+      }
+    ]
+  };
+  return {
+    get: () => getAction(queue),
+    files: () => filesAction(queue),
+    details: () => detailsAction(queue),
+    filter: (callback) => filterAction(queue, callback),
+    upgrade: () => upgradeAction(queue),
+    validate: () => validateAction(queue),
+    dereference: () => dereferenceAction(queue),
+    toJson: () => toJsonAction(queue),
+    toYaml: () => toYamlAction(queue)
+  };
+}
+function upgradeAction(queue) {
+  queue.tasks.push({
+    action: upgrade
+  });
+  return {
+    get: () => getAction(queue),
+    files: () => filesAction(queue),
+    details: () => detailsAction(queue),
+    filter: (callback) => filterAction(queue, callback),
+    validate: () => validateAction(queue),
+    dereference: () => dereferenceAction(queue),
+    toJson: () => toJsonAction(queue),
+    toYaml: () => toYamlAction(queue)
+  };
+}
+async function validateAction(queue) {
+  const filesystem = await workThroughQueue(queue);
+  return {
+    ...await validate(filesystem),
+    filter: (callback) => filterAction(queue, callback),
+    get: () => getAction(queue),
+    files: () => filesAction(queue),
+    details: () => detailsAction(queue),
+    dereference: () => dereferenceAction(queue),
+    toJson: () => toJsonAction(queue),
+    toYaml: () => toYamlAction(queue)
+  };
+}
+function dereferenceAction(queue) {
+  queue.tasks.push({
+    action: dereference
+  });
+  return {
+    get: () => getAction(queue),
+    files: () => filesAction(queue),
+    filter: (callback) => filterAction(queue, callback),
+    toJson: () => toJsonAction(queue),
+    toYaml: () => toYamlAction(queue)
+  };
+}
+function filterAction(queue, callback) {
+  queue.tasks.push({
+    action: filter,
+    options: callback
+  });
+  return {
+    get: () => getAction(queue),
+    files: () => filesAction(queue),
+    details: () => detailsAction(queue),
+    filter: () => filterAction(queue, callback),
+    upgrade: () => upgradeAction(queue),
+    validate: () => validateAction(queue),
+    dereference: () => dereferenceAction(queue),
+    toJson: () => toJsonAction(queue),
+    toYaml: () => toYamlAction(queue)
+  };
+}
+async function getAction(queue) {
+  const filesystem = await workThroughQueue(queue);
+  return getEntrypoint(filesystem).specification;
+}
+async function filesAction(queue) {
+  return await workThroughQueue(queue);
+}
+async function detailsAction(queue) {
+  const filesystem = await workThroughQueue(queue);
+  return details(getEntrypoint(filesystem).specification);
+}
+async function toJsonAction(queue) {
+  const filesystem = await workThroughQueue(queue);
+  return toJson(getEntrypoint(filesystem).specification);
+}
+async function toYamlAction(queue) {
+  const filesystem = await workThroughQueue(queue);
+  return toYaml(getEntrypoint(filesystem).specification);
+}
+async function workThroughQueue(queue) {
+  let specification = queue.specification;
+  for (const { action, options } of queue.tasks) {
+    if (typeof action !== "function") {
+      console.warn("[queue] The given action is not a function:", action);
+      continue;
+    }
+    if (action.constructor.name === "AsyncFunction") {
+      specification = await action(specification, options);
+    } else {
+      specification = action(specification, options);
+    }
+  }
+  return makeFilesystem(specification);
+}
+
+export { openapi };

package/dist/src/polyfills/path.js

@@ -0,0 +1,83 @@
+function normalizeArray(parts, allowAboveRoot) {
+  var up = 0;
+  for (var i = parts.length - 1; i >= 0; i--) {
+    var last = parts[i];
+    if (last === ".") {
+      parts.splice(i, 1);
+    } else if (last === "..") {
+      parts.splice(i, 1);
+      up++;
+    } else if (up) {
+      parts.splice(i, 1);
+      up--;
+    }
+  }
+  if (allowAboveRoot) {
+    for (; up--; up) {
+      parts.unshift("..");
+    }
+  }
+  return parts;
+}
+var splitPathRe = /^(\/?|)([\s\S]*?)((?:\.{1,2}|[^\/]+?|)(\.[^.\/]*|))(?:[\/]*)$/;
+var splitPath = function(filename) {
+  return splitPathRe.exec(filename).slice(1);
+};
+function normalize(path) {
+  var isPathAbsolute = isAbsolute(path), trailingSlash = substr(path, -1) === "/";
+  path = normalizeArray(
+    filter(path.split("/"), function(p) {
+      return !!p;
+    }),
+    !isPathAbsolute
+  ).join("/");
+  if (!path && !isPathAbsolute) {
+    path = ".";
+  }
+  if (path && trailingSlash) {
+    path += "/";
+  }
+  return (isPathAbsolute ? "/" : "") + path;
+}
+function isAbsolute(path) {
+  return path.charAt(0) === "/";
+}
+function join(...paths) {
+  return normalize(
+    filter(paths, function(p, index) {
+      if (typeof p !== "string") {
+        throw new TypeError("Arguments to path.join must be strings");
+      }
+      return p;
+    }).join("/")
+  );
+}
+function dirname(path) {
+  var result = splitPath(path), root = result[0], dir = result[1];
+  if (!root && !dir) {
+    return ".";
+  }
+  if (dir) {
+    dir = dir.substr(0, dir.length - 1);
+  }
+  return root + dir;
+}
+function filter(xs, f) {
+  if (xs.filter)
+    return xs.filter(f);
+  var res = [];
+  for (var i = 0; i < xs.length; i++) {
+    if (f(xs[i], i, xs))
+      res.push(xs[i]);
+  }
+  return res;
+}
+var substr = "ab".substr(-1) === "b" ? function(str, start, len) {
+  return str.substr(start, len);
+} : function(str, start, len) {
+  if (start < 0)
+    start = str.length + start;
+  return str.substr(start, len);
+};
+
+export { dirname, isAbsolute, join, normalize };

package/dist/src/utils/betterAjvErrors/helpers.js

@@ -0,0 +1,89 @@
+import { getErrors, isRequiredError, isAnyOfError, isEnumError, getSiblings, notUndefined, concatAll, getChildren } from './utils.js';
+import EnumValidationError from './validation-errors/enum.js';
+import DefaultValidationError from './validation-errors/default.js';
+import UnevaluatedPropValidationError from './validation-errors/unevaluated-prop.js';
+import RequiredValidationError from './validation-errors/required.js';
+import PatternValidationError from './validation-errors/pattern.js';
+import AdditionalPropValidationError from './validation-errors/additional-prop.js';
+
+const JSON_POINTERS_REGEX = /\/[\w_-]+(\/\d+)?/g;
+function makeTree(ajvErrors = []) {
+  const root = { children: {} };
+  ajvErrors.forEach((ajvError) => {
+    const instancePath = typeof ajvError.instancePath !== "undefined" ? ajvError.instancePath : ajvError.dataPath;
+    const paths = instancePath === "" ? [""] : instancePath.match(JSON_POINTERS_REGEX);
+    if (paths) {
+      paths.reduce((obj, path, i) => {
+        obj.children[path] = obj.children[path] || { children: {}, errors: [] };
+        if (i === paths.length - 1) {
+          obj.children[path].errors.push(ajvError);
+        }
+        return obj.children[path];
+      }, root);
+    }
+  });
+  return root;
+}
+function filterRedundantErrors(root, parent, key) {
+  getErrors(root).forEach((error) => {
+    if (isRequiredError(error)) {
+      root.errors = [error];
+      root.children = {};
+    }
+  });
+  if (getErrors(root).some(isAnyOfError)) {
+    if (Object.keys(root.children).length > 0) {
+      delete root.errors;
+    }
+  }
+  if (root.errors && root.errors.length && getErrors(root).every(isEnumError)) {
+    if (getSiblings(parent)(root).filter(notUndefined).some(getErrors)) {
+      delete parent.children[key];
+    }
+  }
+  Object.entries(root.children).forEach(
+    ([k, child]) => filterRedundantErrors(child, root, k)
+  );
+}
+function createErrorInstances(root, options) {
+  const errors = getErrors(root);
+  if (errors.length && errors.every(isEnumError)) {
+    const uniqueValues = new Set(
+      concatAll([])(errors.map((e) => e.params.allowedValues))
+    );
+    const allowedValues = [...uniqueValues];
+    const error = errors[0];
+    return [
+      new EnumValidationError(
+        {
+          ...error,
+          params: { allowedValues }
+        },
+        options
+      )
+    ];
+  }
+  return concatAll(
+    errors.reduce((ret, error) => {
+      switch (error.keyword) {
+        case "additionalProperties":
+          return ret.concat(new AdditionalPropValidationError(error, options));
+        case "pattern":
+          return ret.concat(new PatternValidationError(error, options));
+        case "required":
+          return ret.concat(new RequiredValidationError(error, options));
+        case "unevaluatedProperties":
+          return ret.concat(new UnevaluatedPropValidationError(error, options));
+        default:
+          return ret.concat(new DefaultValidationError(error, options));
+      }
+    }, [])
+  )(getChildren(root).map((child) => createErrorInstances(child, options)));
+}
+function prettify(ajvErrors, options) {
+  const tree = makeTree(ajvErrors || []);
+  filterRedundantErrors(tree);
+  return createErrorInstances(tree, options);
+}
+
+export { createErrorInstances, prettify as default, filterRedundantErrors, makeTree };

package/dist/src/utils/betterAjvErrors/index.js

@@ -0,0 +1,15 @@
+import prettify from './helpers.js';
+
+function betterAjvErrors(schema, data, errors, options = {}) {
+  const { indent = null, json = null } = options;
+  const jsonRaw = json || JSON.stringify(data, null, indent);
+  const customErrorToStructure = (error) => error.getError();
+  const customErrors = prettify(errors, {
+    data,
+    schema,
+    jsonRaw
+  });
+  return customErrors.map(customErrorToStructure);
+}
+
+export { betterAjvErrors };

package/dist/src/utils/betterAjvErrors/utils.js

@@ -0,0 +1,17 @@
+const eq = (x) => (y) => x === y;
+const not = (fn) => (x) => !fn(x);
+const getValues = (o) => Object.values(o);
+const notUndefined = (x) => x !== void 0;
+const isXError = (x) => (error) => error.keyword === x;
+const isRequiredError = isXError("required");
+const isAnyOfError = isXError("anyOf");
+const isEnumError = isXError("enum");
+const getErrors = (node) => node && node.errors || [];
+const getChildren = (node) => node && getValues(node.children) || [];
+const getSiblings = (parent) => (node) => getChildren(parent).filter(not(eq(node)));
+const concatAll = (
+  /* ::<T> */
+  (xs) => (ys) => ys.reduce((zs, z) => zs.concat(z), xs)
+);
+
+export { concatAll, getChildren, getErrors, getSiblings, isAnyOfError, isEnumError, isRequiredError, notUndefined };

package/dist/src/utils/betterAjvErrors/validation-errors/additional-prop.js

@@ -0,0 +1,18 @@
+import BaseValidationError from './base.js';
+
+class AdditionalPropValidationError extends BaseValidationError {
+  constructor(...args) {
+    super(...args);
+    this.name = "AdditionalPropValidationError";
+    this.options.isIdentifierLocation = true;
+  }
+  getError() {
+    const { params } = this.options;
+    return {
+      message: `Property ${params.additionalProperty} is not expected to be here`,
+      path: this.instancePath
+    };
+  }
+}
+
+export { AdditionalPropValidationError as default };

package/dist/src/utils/betterAjvErrors/validation-errors/base.js

@@ -0,0 +1,23 @@
+class BaseValidationError {
+  // eslint-disable-next-line default-param-last
+  constructor(options = { isIdentifierLocation: false }, { data, schema, jsonAst, jsonRaw }) {
+    this.options = options;
+    this.data = data;
+    this.schema = schema;
+    this.jsonAst = jsonAst;
+    this.jsonRaw = jsonRaw;
+  }
+  /**
+   * @return {string}
+   */
+  get instancePath() {
+    return typeof this.options.instancePath !== "undefined" ? this.options.instancePath : this.options.dataPath;
+  }
+  getError() {
+    throw new Error(
+      `Implement the 'getError' method inside ${this.constructor.name}!`
+    );
+  }
+}
+
+export { BaseValidationError as default };

package/dist/src/utils/betterAjvErrors/validation-errors/default.js

@@ -0,0 +1,18 @@
+import BaseValidationError from './base.js';
+
+class DefaultValidationError extends BaseValidationError {
+  constructor(...args) {
+    super(...args);
+    this.name = "DefaultValidationError";
+    this.options.isSkipEndLocation = true;
+  }
+  getError() {
+    const { keyword, message } = this.options;
+    return {
+      message: `${keyword} ${message}`,
+      path: this.instancePath
+    };
+  }
+}
+
+export { DefaultValidationError as default };

package/dist/src/utils/betterAjvErrors/validation-errors/enum.js

@@ -0,0 +1,41 @@
+import pointer from 'jsonpointer';
+import leven from 'leven';
+import BaseValidationError from './base.js';
+
+class EnumValidationError extends BaseValidationError {
+  constructor(...args) {
+    super(...args);
+    this.name = "EnumValidationError";
+  }
+  getError() {
+    const { message, params } = this.options;
+    const bestMatch = this.findBestMatch();
+    const allowedValues = params.allowedValues.join(", ");
+    const output = {
+      message: `${message}: ${allowedValues}`,
+      path: this.instancePath
+    };
+    if (bestMatch !== null) {
+      output.suggestion = `Did you mean ${bestMatch}?`;
+    }
+    return output;
+  }
+  findBestMatch() {
+    const {
+      params: { allowedValues }
+    } = this.options;
+    const currentValue = this.instancePath === "" ? this.data : pointer.get(this.data, this.instancePath);
+    if (!currentValue) {
+      return null;
+    }
+    const bestMatch = allowedValues.map((value) => ({
+      value,
+      weight: leven(value, currentValue.toString())
+    })).sort(
+      (x, y) => x.weight > y.weight ? 1 : x.weight < y.weight ? -1 : 0
+    )[0];
+    return allowedValues.length === 1 || bestMatch.weight < bestMatch.value.length ? bestMatch.value : null;
+  }
+}
+
+export { EnumValidationError as default };

package/dist/src/utils/betterAjvErrors/validation-errors/pattern.js

@@ -0,0 +1,18 @@
+import BaseValidationError from './base.js';
+
+class PatternValidationError extends BaseValidationError {
+  constructor(...args) {
+    super(...args);
+    this.name = "PatternValidationError";
+    this.options.isIdentifierLocation = true;
+  }
+  getError() {
+    const { params, propertyName } = this.options;
+    return {
+      message: `Property "${propertyName}" must match pattern ${params.pattern}`,
+      path: this.instancePath
+    };
+  }
+}
+
+export { PatternValidationError as default };

package/dist/src/utils/betterAjvErrors/validation-errors/required.js

@@ -0,0 +1,17 @@
+import BaseValidationError from './base.js';
+
+class RequiredValidationError extends BaseValidationError {
+  constructor(...args) {
+    super(...args);
+    this.name = "RequiredValidationError";
+  }
+  getError() {
+    const { message } = this.options;
+    return {
+      message: `${message}`,
+      path: this.instancePath
+    };
+  }
+}
+
+export { RequiredValidationError as default };

package/dist/src/utils/betterAjvErrors/validation-errors/unevaluated-prop.js

@@ -0,0 +1,18 @@
+import BaseValidationError from './base.js';
+
+class UnevaluatedPropValidationError extends BaseValidationError {
+  constructor(...args) {
+    super(...args);
+    this.name = "UnevaluatedPropValidationError";
+    this.options.isIdentifierLocation = true;
+  }
+  getError() {
+    const { params } = this.options;
+    return {
+      message: `Property ${params.unevaluatedProperty} is not expected to be here`,
+      path: this.instancePath
+    };
+  }
+}
+
+export { UnevaluatedPropValidationError as default };

package/dist/src/utils/dereference.js

@@ -0,0 +1,18 @@
+import { details } from './details.js';
+import { getEntrypoint } from './getEntrypoint.js';
+import { makeFilesystem } from './makeFilesystem.js';
+import { resolveReferences } from './resolveReferences.js';
+
+async function dereference(value) {
+  const filesystem = makeFilesystem(value);
+  const entrypoint = getEntrypoint(filesystem);
+  const result = resolveReferences(filesystem);
+  return {
+    specification: entrypoint.specification,
+    errors: result.errors,
+    schema: result.schema,
+    ...details(entrypoint.specification)
+  };
+}
+
+export { dereference };