@nocobase/plugin-mcp-server 2.1.0-alpha.16 → 2.1.0-alpha.17

package/dist/node_modules/openapi-mcp-generator/node_modules/@apidevtools/json-schema-ref-parser/lib/refs.ts

@@ -0,0 +1,239 @@
+import { ono } from "@jsdevtools/ono";
+import $Ref from "./ref.js";
+import * as url from "./util/url.js";
+import type { JSONSchema4Type, JSONSchema6Type, JSONSchema7Type } from "json-schema";
+import type { ParserOptions } from "./options.js";
+import convertPathToPosix from "./util/convert-path-to-posix";
+import type { JSONSchema } from "./types";
+
+interface $RefsMap<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>> {
+  [url: string]: $Ref<S, O>;
+}
+/**
+ * When you call the resolve method, the value that gets passed to the callback function (or Promise) is a $Refs object. This same object is accessible via the parser.$refs property of $RefParser objects.
+ *
+ * This object is a map of JSON References and their resolved values. It also has several convenient helper methods that make it easy for you to navigate and manipulate the JSON References.
+ *
+ * See https://apitools.dev/json-schema-ref-parser/docs/refs.html
+ */
+export default class $Refs<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>> {
+  /**
+   * This property is true if the schema contains any circular references. You may want to check this property before serializing the dereferenced schema as JSON, since JSON.stringify() does not support circular references by default.
+   *
+   * See https://apitools.dev/json-schema-ref-parser/docs/refs.html#circular
+   */
+  public circular: boolean;
+
+  /**
+   * Returns the paths/URLs of all the files in your schema (including the main schema file).
+   *
+   * See https://apitools.dev/json-schema-ref-parser/docs/refs.html#pathstypes
+   *
+   * @param types (optional) Optionally only return certain types of paths ("file", "http", etc.)
+   */
+  paths(...types: (string | string[])[]): string[] {
+    const paths = getPaths(this._$refs, types.flat());
+    return paths.map((path) => {
+      return convertPathToPosix(path.decoded);
+    });
+  }
+
+  /**
+   * Returns a map of paths/URLs and their correspond values.
+   *
+   * See https://apitools.dev/json-schema-ref-parser/docs/refs.html#valuestypes
+   *
+   * @param types (optional) Optionally only return values from certain locations ("file", "http", etc.)
+   */
+  values(...types: (string | string[])[]): S {
+    const $refs = this._$refs;
+    const paths = getPaths($refs, types.flat());
+    return paths.reduce<Record<string, any>>((obj, path) => {
+      obj[convertPathToPosix(path.decoded)] = $refs[path.encoded].value;
+      return obj;
+    }, {}) as S;
+  }
+
+  /**
+   * Returns `true` if the given path exists in the schema; otherwise, returns `false`
+   *
+   * See https://apitools.dev/json-schema-ref-parser/docs/refs.html#existsref
+   *
+   * @param $ref The JSON Reference path, optionally with a JSON Pointer in the hash
+   */
+  /**
+   * Determines whether the given JSON reference exists.
+   *
+   * @param path - The path being resolved, optionally with a JSON pointer in the hash
+   * @param [options]
+   * @returns
+   */
+  exists(path: string, options: any) {
+    try {
+      this._resolve(path, "", options);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Resolves the given JSON reference and returns the resolved value.
+   *
+   * @param path - The path being resolved, with a JSON pointer in the hash
+   * @param [options]
+   * @returns - Returns the resolved value
+   */
+  get(path: string, options?: O): JSONSchema4Type | JSONSchema6Type | JSONSchema7Type {
+    return this._resolve(path, "", options)!.value;
+  }
+
+  /**
+   * Sets the value at the given path in the schema. If the property, or any of its parents, don't exist, they will be created.
+   *
+   * @param path The JSON Reference path, optionally with a JSON Pointer in the hash
+   * @param value The value to assign. Can be anything (object, string, number, etc.)
+   */
+  set(path: string, value: JSONSchema4Type | JSONSchema6Type | JSONSchema7Type) {
+    const absPath = url.resolve(this._root$Ref.path!, path);
+    const withoutHash = url.stripHash(absPath);
+    const $ref = this._$refs[withoutHash];
+
+    if (!$ref) {
+      throw ono(`Error resolving $ref pointer "${path}". \n"${withoutHash}" not found.`);
+    }
+
+    $ref.set(absPath, value);
+  }
+  /**
+   * Returns the specified {@link $Ref} object, or undefined.
+   *
+   * @param path - The path being resolved, optionally with a JSON pointer in the hash
+   * @returns
+   * @protected
+   */
+  _get$Ref(path: string) {
+    path = url.resolve(this._root$Ref.path!, path);
+    const withoutHash = url.stripHash(path);
+    return this._$refs[withoutHash];
+  }
+
+  /**
+   * Creates a new {@link $Ref} object and adds it to this {@link $Refs} object.
+   *
+   * @param path  - The file path or URL of the referenced file
+   */
+  _add(path: string) {
+    const withoutHash = url.stripHash(path);
+
+    const $ref = new $Ref<S, O>(this);
+    $ref.path = withoutHash;
+
+    this._$refs[withoutHash] = $ref;
+    this._root$Ref = this._root$Ref || $ref;
+
+    return $ref;
+  }
+
+  /**
+   * Resolves the given JSON reference.
+   *
+   * @param path - The path being resolved, optionally with a JSON pointer in the hash
+   * @param pathFromRoot - The path of `obj` from the schema root
+   * @param [options]
+   * @returns
+   * @protected
+   */
+  _resolve(path: string, pathFromRoot: string, options?: O) {
+    const absPath = url.resolve(this._root$Ref.path!, path);
+    const withoutHash = url.stripHash(absPath);
+    const $ref = this._$refs[withoutHash];
+
+    if (!$ref) {
+      throw ono(`Error resolving $ref pointer "${path}". \n"${withoutHash}" not found.`);
+    }
+
+    return $ref.resolve(absPath, options, path, pathFromRoot);
+  }
+
+  /**
+   * A map of paths/urls to {@link $Ref} objects
+   *
+   * @type {object}
+   * @protected
+   */
+  _$refs: $RefsMap<S, O> = {};
+
+  /**
+   * The {@link $Ref} object that is the root of the JSON schema.
+   *
+   * @type {$Ref}
+   * @protected
+   */
+  _root$Ref: $Ref<S, O>;
+
+  constructor() {
+    /**
+     * Indicates whether the schema contains any circular references.
+     *
+     * @type {boolean}
+     */
+    this.circular = false;
+
+    this._$refs = {};
+
+    // @ts-ignore
+    this._root$Ref = null;
+  }
+
+  /**
+   * Returns the paths of all the files/URLs that are referenced by the JSON schema,
+   * including the schema itself.
+   *
+   * @param [types] - Only return paths of the given types ("file", "http", etc.)
+   * @returns
+   */
+  /**
+   * Returns the map of JSON references and their resolved values.
+   *
+   * @param [types] - Only return references of the given types ("file", "http", etc.)
+   * @returns
+   */
+
+  /**
+   * Returns a POJO (plain old JavaScript object) for serialization as JSON.
+   *
+   * @returns {object}
+   */
+  toJSON = this.values;
+}
+
+/**
+ * Returns the encoded and decoded paths keys of the given object.
+ *
+ * @param $refs - The object whose keys are URL-encoded paths
+ * @param [types] - Only return paths of the given types ("file", "http", etc.)
+ * @returns
+ */
+function getPaths<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
+  $refs: $RefsMap<S, O>,
+  types: string[],
+) {
+  let paths = Object.keys($refs);
+
+  // Filter the paths by type
+  types = Array.isArray(types[0]) ? types[0] : Array.prototype.slice.call(types);
+  if (types.length > 0 && types[0]) {
+    paths = paths.filter((key) => {
+      return types.includes($refs[key].pathType as string);
+    });
+  }
+
+  // Decode local filesystem paths
+  return paths.map((path) => {
+    return {
+      encoded: path,
+      decoded: $refs[path].pathType === "file" ? url.toFileSystemPath(path, true) : path,
+    };
+  });
+}

package/dist/node_modules/openapi-mcp-generator/node_modules/@apidevtools/json-schema-ref-parser/lib/resolve-external.ts

@@ -0,0 +1,136 @@
+import $Ref from "./ref.js";
+import Pointer from "./pointer.js";
+import parse from "./parse.js";
+import * as url from "./util/url.js";
+import { isHandledError } from "./util/errors.js";
+import type $Refs from "./refs.js";
+import type { ParserOptions } from "./options.js";
+import type { JSONSchema } from "./types/index.js";
+import type $RefParser from "./index.js";
+
+/**
+ * Crawls the JSON schema, finds all external JSON references, and resolves their values.
+ * This method does not mutate the JSON schema. The resolved values are added to {@link $RefParser#$refs}.
+ *
+ * NOTE: We only care about EXTERNAL references here. INTERNAL references are only relevant when dereferencing.
+ *
+ * @returns
+ * The promise resolves once all JSON references in the schema have been resolved,
+ * including nested references that are contained in externally-referenced files.
+ */
+function resolveExternal<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
+  parser: $RefParser<S, O>,
+  options: O,
+) {
+  if (!options.resolve?.external) {
+    // Nothing to resolve, so exit early
+    return Promise.resolve();
+  }
+
+  try {
+    // console.log('Resolving $ref pointers in %s', parser.$refs._root$Ref.path);
+    const promises = crawl(parser.schema, parser.$refs._root$Ref.path + "#", parser.$refs, options);
+    return Promise.all(promises);
+  } catch (e) {
+    return Promise.reject(e);
+  }
+}
+
+/**
+ * Recursively crawls the given value, and resolves any external JSON references.
+ *
+ * @param obj - The value to crawl. If it's not an object or array, it will be ignored.
+ * @param path - The full path of `obj`, possibly with a JSON Pointer in the hash
+ * @param {boolean} external - Whether `obj` was found in an external document.
+ * @param $refs
+ * @param options
+ * @param seen - Internal.
+ *
+ * @returns
+ * Returns an array of promises. There will be one promise for each JSON reference in `obj`.
+ * If `obj` does not contain any JSON references, then the array will be empty.
+ * If any of the JSON references point to files that contain additional JSON references,
+ * then the corresponding promise will internally reference an array of promises.
+ */
+function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
+  obj: string | Buffer | S | undefined | null,
+  path: string,
+  $refs: $Refs<S, O>,
+  options: O,
+  seen?: Set<any>,
+  external?: boolean,
+) {
+  seen ||= new Set();
+  let promises: any = [];
+
+  if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !seen.has(obj)) {
+    seen.add(obj); // Track previously seen objects to avoid infinite recursion
+    if ($Ref.isExternal$Ref(obj)) {
+      promises.push(resolve$Ref<S, O>(obj, path, $refs, options));
+    }
+
+    const keys = Object.keys(obj) as string[];
+    for (const key of keys) {
+      const keyPath = Pointer.join(path, key);
+      const value = obj[key as keyof typeof obj] as string | JSONSchema | Buffer | undefined;
+      promises = promises.concat(crawl(value, keyPath, $refs, options, seen, external));
+    }
+  }
+
+  return promises;
+}
+
+/**
+ * Resolves the given JSON Reference, and then crawls the resulting value.
+ *
+ * @param $ref - The JSON Reference to resolve
+ * @param path - The full path of `$ref`, possibly with a JSON Pointer in the hash
+ * @param $refs
+ * @param options
+ *
+ * @returns
+ * The promise resolves once all JSON references in the object have been resolved,
+ * including nested references that are contained in externally-referenced files.
+ */
+async function resolve$Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
+  $ref: S,
+  path: string,
+  $refs: $Refs<S, O>,
+  options: O,
+) {
+  const shouldResolveOnCwd = options.dereference?.externalReferenceResolution === "root";
+  const resolvedPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, ($ref as JSONSchema).$ref!);
+  const withoutHash = url.stripHash(resolvedPath);
+
+  // $ref.$ref = url.relative($refs._root$Ref.path, resolvedPath);
+
+  // Do we already have this $ref?
+  const ref = $refs._$refs[withoutHash];
+  if (ref) {
+    // We've already parsed this $ref, so use the existing value
+    return Promise.resolve(ref.value);
+  }
+
+  // Parse the $referenced file/url
+  try {
+    const result = await parse(resolvedPath, $refs, options);
+
+    // Crawl the parsed value
+    // console.log('Resolving $ref pointers in %s', withoutHash);
+    const promises = crawl(result, withoutHash + "#", $refs, options, new Set(), true);
+
+    return Promise.all(promises);
+  } catch (err) {
+    if (!options?.continueOnError || !isHandledError(err)) {
+      throw err;
+    }
+
+    if ($refs._$refs[withoutHash]) {
+      err.source = decodeURI(url.stripHash(path));
+      err.path = url.safePointerToPath(url.getHash(path));
+    }
+
+    return [];
+  }
+}
+export default resolveExternal;

package/dist/node_modules/openapi-mcp-generator/node_modules/@apidevtools/json-schema-ref-parser/lib/resolvers/file.ts

@@ -0,0 +1,39 @@
+import fs from "fs";
+import { ono } from "@jsdevtools/ono";
+import * as url from "../util/url.js";
+import { ResolverError } from "../util/errors.js";
+import type { JSONSchema, ResolverOptions } from "../types/index.js";
+import type { FileInfo } from "../types/index.js";
+
+export default {
+  /**
+   * The order that this resolver will run, in relation to other resolvers.
+   */
+  order: 100,
+
+  /**
+   * Determines whether this resolver can read a given file reference.
+   * Resolvers that return true will be tried, in order, until one successfully resolves the file.
+   * Resolvers that return false will not be given a chance to resolve the file.
+   */
+  canRead(file: FileInfo) {
+    return url.isFileSystemPath(file.url);
+  },
+
+  /**
+   * Reads the given file and returns its raw contents as a Buffer.
+   */
+  async read(file: FileInfo): Promise<Buffer> {
+    let path: string | undefined;
+    try {
+      path = url.toFileSystemPath(file.url);
+    } catch (err: any) {
+      throw new ResolverError(ono.uri(err, `Malformed URI: ${file.url}`), file.url);
+    }
+    try {
+      return await fs.promises.readFile(path);
+    } catch (err: any) {
+      throw new ResolverError(ono(err, `Error opening file "${path}"`), path);
+    }
+  },
+} as ResolverOptions<JSONSchema>;

package/dist/node_modules/openapi-mcp-generator/node_modules/@apidevtools/json-schema-ref-parser/lib/resolvers/http.ts

@@ -0,0 +1,131 @@
+import { ono } from "@jsdevtools/ono";
+import * as url from "../util/url.js";
+import { ResolverError } from "../util/errors.js";
+import type { FileInfo, HTTPResolverOptions, JSONSchema } from "../types/index.js";
+
+export default {
+  /**
+   * The order that this resolver will run, in relation to other resolvers.
+   */
+  order: 200,
+
+  /**
+   * HTTP headers to send when downloading files.
+   *
+   * @example:
+   * {
+   *   "User-Agent": "JSON Schema $Ref Parser",
+   *   Accept: "application/json"
+   * }
+   */
+  headers: null,
+
+  /**
+   * HTTP request timeout (in milliseconds).
+   */
+  timeout: 60_000, // 60 seconds
+
+  /**
+   * The maximum number of HTTP redirects to follow.
+   * To disable automatic following of redirects, set this to zero.
+   */
+  redirects: 5,
+
+  /**
+   * The `withCredentials` option of XMLHttpRequest.
+   * Set this to `true` if you're downloading files from a CORS-enabled server that requires authentication
+   */
+  withCredentials: false,
+
+  /**
+   * Determines whether this resolver can read a given file reference.
+   * Resolvers that return true will be tried in order, until one successfully resolves the file.
+   * Resolvers that return false will not be given a chance to resolve the file.
+   */
+  canRead(file: FileInfo) {
+    return url.isHttp(file.url);
+  },
+
+  /**
+   * Reads the given URL and returns its raw contents as a Buffer.
+   */
+  read(file: FileInfo) {
+    const u = url.parse(file.url);
+
+    if (typeof window !== "undefined" && !u.protocol) {
+      // Use the protocol of the current page
+      u.protocol = url.parse(location.href).protocol;
+    }
+
+    return download(u, this);
+  },
+} as HTTPResolverOptions<JSONSchema>;
+
+/**
+ * Downloads the given file.
+ * @returns
+ * The promise resolves with the raw downloaded data, or rejects if there is an HTTP error.
+ */
+async function download<S extends object = JSONSchema>(
+  u: URL | string,
+  httpOptions: HTTPResolverOptions<S>,
+  _redirects?: string[],
+): Promise<Buffer> {
+  u = url.parse(u);
+  const redirects = _redirects || [];
+  redirects.push(u.href);
+
+  try {
+    const res = await get(u, httpOptions);
+    if (res.status >= 400) {
+      throw ono({ status: res.status }, `HTTP ERROR ${res.status}`);
+    } else if (res.status >= 300) {
+      if (!Number.isNaN(httpOptions.redirects) && redirects.length > httpOptions.redirects!) {
+        throw new ResolverError(
+          ono(
+            { status: res.status },
+            `Error downloading ${redirects[0]}. \nToo many redirects: \n  ${redirects.join(" \n  ")}`,
+          ),
+        );
+      } else if (!("location" in res.headers) || !res.headers.location) {
+        throw ono({ status: res.status }, `HTTP ${res.status} redirect with no location header`);
+      } else {
+        const redirectTo = url.resolve(u.href, res.headers.location as string);
+        return download(redirectTo, httpOptions, redirects);
+      }
+    } else {
+      if (res.body) {
+        const buf = await res.arrayBuffer();
+        return Buffer.from(buf);
+      }
+      return Buffer.alloc(0);
+    }
+  } catch (err: any) {
+    throw new ResolverError(ono(err, `Error downloading ${u.href}`), u.href);
+  }
+}
+
+/**
+ * Sends an HTTP GET request.
+ * The promise resolves with the HTTP Response object.
+ */
+async function get<S extends object = JSONSchema>(u: RequestInfo | URL, httpOptions: HTTPResolverOptions<S>) {
+  let controller: any;
+  let timeoutId: any;
+  if (httpOptions.timeout) {
+    controller = new AbortController();
+    timeoutId = setTimeout(() => controller.abort(), httpOptions.timeout);
+  }
+
+  const response = await fetch(u, {
+    method: "GET",
+    headers: httpOptions.headers || {},
+    credentials: httpOptions.withCredentials ? "include" : "same-origin",
+    signal: controller ? controller.signal : null,
+  });
+  if (timeoutId) {
+    clearTimeout(timeoutId);
+  }
+
+  return response;
+}

package/dist/node_modules/openapi-mcp-generator/node_modules/@apidevtools/json-schema-ref-parser/lib/types/index.ts

@@ -0,0 +1,151 @@
+import type {
+  JSONSchema4,
+  JSONSchema4Object,
+  JSONSchema6,
+  JSONSchema6Object,
+  JSONSchema7,
+  JSONSchema7Object,
+} from "json-schema";
+import type $Refs from "../refs.js";
+import type { ParserOptions } from "../options";
+
+export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
+export type JSONSchemaObject = JSONSchema4Object | JSONSchema6Object | JSONSchema7Object;
+export type SchemaCallback<S extends object = JSONSchema> = (err: Error | null, schema?: S | object | null) => any;
+export type $RefsCallback<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>> = (
+  err: Error | null,
+  $refs?: $Refs<S, O>,
+) => any;
+
+/**
+ * See https://apitools.dev/json-schema-ref-parser/docs/options.html
+ */
+
+export interface HTTPResolverOptions<S extends object = JSONSchema> extends Partial<ResolverOptions<S>> {
+  /**
+   * You can specify any HTTP headers that should be sent when downloading files. For example, some servers may require you to set the `Accept` or `Referrer` header.
+   */
+  headers?: RequestInit["headers"] | null;
+
+  /**
+   * The amount of time (in milliseconds) to wait for a response from the server when downloading files. The default is 5 seconds.
+   */
+  timeout?: number;
+
+  /**
+   * The maximum number of HTTP redirects to follow per file. The default is 5. To disable automatic following of redirects, set this to zero.
+   */
+  redirects?: number;
+
+  /**
+   * Set this to `true` if you're downloading files from a CORS-enabled server that requires authentication
+   */
+  withCredentials?: boolean;
+}
+
+/**
+ * JSON Schema `$Ref` Parser comes with built-in resolvers for HTTP and HTTPS URLs, as well as local filesystem paths (when running in Node.js). You can add your own custom resolvers to support additional protocols, or even replace any of the built-in resolvers with your own custom implementation.
+ *
+ * See https://apitools.dev/json-schema-ref-parser/docs/plugins/resolvers.html
+ */
+export interface ResolverOptions<S extends object = JSONSchema> {
+  name?: string;
+  /**
+   * All resolvers have an order property, even the built-in resolvers. If you don't specify an order property, then your resolver will run last. Specifying `order: 1`, like we did in this example, will make your resolver run first. Or you can squeeze your resolver in-between some of the built-in resolvers. For example, `order: 101` would make it run after the file resolver, but before the HTTP resolver. You can see the order of all the built-in resolvers by looking at their source code.
+   *
+   * The order property and canRead property are related to each other. For each file that JSON Schema $Ref Parser needs to resolve, it first determines which resolvers can read that file by checking their canRead property. If only one resolver matches a file, then only that one resolver is called, regardless of its order. If multiple resolvers match a file, then those resolvers are tried in order until one of them successfully reads the file. Once a resolver successfully reads the file, the rest of the resolvers are skipped.
+   */
+  order?: number;
+
+  /**
+   * The `canRead` property tells JSON Schema `$Ref` Parser what kind of files your resolver can read. In this example, we've simply specified a regular expression that matches "mogodb://" URLs, but we could have used a simple boolean, or even a function with custom logic to determine which files to resolve. Here are examples of each approach:
+   */
+  canRead: boolean | RegExp | string | string[] | ((file: FileInfo) => boolean);
+
+  /**
+   * This is where the real work of a resolver happens. The `read` method accepts the same file info object as the `canRead` function, but rather than returning a boolean value, the `read` method should return the contents of the file. The file contents should be returned in as raw a form as possible, such as a string or a byte array. Any further parsing or processing should be done by parsers.
+   *
+   * Unlike the `canRead` function, the `read` method can also be asynchronous. This might be important if your resolver needs to read data from a database or some other external source. You can return your asynchronous value using either an ES6 Promise or a Node.js-style error-first callback. Of course, if your resolver has the ability to return its data synchronously, then that's fine too. Here are examples of all three approaches:
+   */
+  read:
+    | string
+    | object
+    | ((
+        file: FileInfo,
+        callback?: (error: Error | null, data: string | null) => any,
+      ) => string | Buffer | S | Promise<string | Buffer | S>);
+}
+
+export interface Plugin {
+  name?: string;
+  /**
+   * Parsers run in a specific order, relative to other parsers. For example, a parser with `order: 5` will run before a parser with `order: 10`. If a parser is unable to successfully parse a file, then the next parser is tried, until one succeeds or they all fail.
+   *
+   * You can change the order in which parsers run, which is useful if you know that most of your referenced files will be a certain type, or if you add your own custom parser that you want to run first.
+   */
+  order?: number;
+
+  /**
+   * All of the built-in parsers allow empty files by default. The JSON and YAML parsers will parse empty files as `undefined`. The text parser will parse empty files as an empty string. The binary parser will parse empty files as an empty byte array.
+   *
+   * You can set `allowEmpty: false` on any parser, which will cause an error to be thrown if a file empty.
+   */
+  allowEmpty?: boolean;
+
+  /**
+   * Specifies whether a Byte Order Mark (BOM) is allowed or not. Only applies to JSON parsing
+   *
+   * @type {boolean} @default true
+   */
+  allowBOM?: boolean;
+
+  /**
+   * The encoding that the text is expected to be in.
+   */
+  encoding?: BufferEncoding;
+  /**
+   * Determines which parsers will be used for which files.
+   *
+   * A regular expression can be used to match files by their full path. A string (or array of strings) can be used to match files by their file extension. Or a function can be used to perform more complex matching logic. See the custom parser docs for details.
+   */
+  canParse?: boolean | RegExp | string | string[] | ((file: FileInfo) => boolean);
+
+  /**
+   * This is where the real work of a parser happens. The `parse` method accepts the same file info object as the `canParse` function, but rather than returning a boolean value, the `parse` method should return a JavaScript representation of the file contents.  For our CSV parser, that is a two-dimensional array of lines and values.  For your parser, it might be an object, a string, a custom class, or anything else.
+   *
+   * Unlike the `canParse` function, the `parse` method can also be asynchronous. This might be important if your parser needs to retrieve data from a database or if it relies on an external HTTP service to return the parsed value.  You can return your asynchronous value via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or a Node.js-style error-first callback.  Here are examples of both approaches:
+   */
+  parse:
+    | ((file: FileInfo, callback?: (error: Error | null, data: string | null) => any) => unknown | Promise<unknown>)
+    | number
+    | string;
+}
+
+/**
+ * JSON Schema `$Ref` Parser supports plug-ins, such as resolvers and parsers. These plug-ins can have methods such as `canRead()`, `read()`, `canParse()`, and `parse()`. All of these methods accept the same object as their parameter: an object containing information about the file being read or parsed.
+ *
+ * The file info object currently only consists of a few properties, but it may grow in the future if plug-ins end up needing more information.
+ *
+ * See https://apitools.dev/json-schema-ref-parser/docs/plugins/file-info-object.html
+ */
+export interface FileInfo {
+  /**
+   * The full URL of the file. This could be any type of URL, including "http://", "https://", "file://", "ftp://", "mongodb://", or even a local filesystem path (when running in Node.js).
+   */
+  url: string;
+
+  /**
+   * The hash (URL fragment) of the file URL, including the # symbol. If the URL doesn't have a hash, then this will be an empty string.
+   */
+  hash: string;
+
+  /**
+   * The lowercase file extension, such as ".json", ".yaml", ".txt", etc.
+   */
+  extension: string;
+
+  /**
+   * The raw file contents, in whatever form they were returned by the resolver that read the file.
+   */
+  data: string | Buffer;
+}