@hey-api/json-schema-ref-parser 0.0.0-next-20260212230650

package/src/resolvers/url.ts

@@ -0,0 +1,99 @@
+import { ono } from '@jsdevtools/ono';
+
+import type { FileInfo } from '../types';
+import { ResolverError } from '../util/errors';
+import { resolve } from '../util/url';
+
+export const sendRequest = async ({
+  fetchOptions,
+  redirects = [],
+  timeout = 60_000,
+  url,
+}: {
+  fetchOptions?: RequestInit;
+  redirects?: string[];
+  timeout?: number;
+  url: URL | string;
+}): Promise<{
+  fetchOptions?: RequestInit;
+  response: Response;
+}> => {
+  url = new URL(url);
+  redirects.push(url.href);
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+  }, timeout);
+  const response = await fetch(url, {
+    signal: controller.signal,
+    ...fetchOptions,
+  });
+  clearTimeout(timeoutId);
+
+  if (response.status >= 300 && response.status <= 399) {
+    if (redirects.length > 5) {
+      throw new ResolverError(
+        ono(
+          { status: response.status },
+          `Error requesting ${redirects[0]}. \nToo many redirects: \n  ${redirects.join(' \n  ')}`,
+        ),
+      );
+    }
+
+    if (!('location' in response.headers) || !response.headers.location) {
+      throw ono(
+        { status: response.status },
+        `HTTP ${response.status} redirect with no location header`,
+      );
+    }
+
+    return sendRequest({
+      fetchOptions,
+      redirects,
+      timeout,
+      url: resolve(url.href, response.headers.location as string),
+    });
+  }
+
+  return { fetchOptions, response };
+};
+
+export const urlResolver = {
+  handler: async ({
+    arrayBuffer,
+    fetch: _fetch,
+    file,
+  }: {
+    arrayBuffer?: ArrayBuffer;
+    fetch?: RequestInit;
+    file: FileInfo;
+  }): Promise<void> => {
+    let data = arrayBuffer;
+
+    if (!data) {
+      try {
+        const { fetchOptions, response } = await sendRequest({
+          fetchOptions: {
+            method: 'GET',
+            ..._fetch,
+          },
+          url: file.url,
+        });
+
+        if (response.status >= 400) {
+          // gracefully handle HEAD method not allowed
+          if (response.status !== 405 || fetchOptions?.method !== 'HEAD') {
+            throw ono({ status: response.status }, `HTTP ERROR ${response.status}`);
+          }
+        }
+
+        data = response.body ? await response.arrayBuffer() : new ArrayBuffer(0);
+      } catch (error: any) {
+        throw new ResolverError(ono(error, `Error requesting ${file.url}`), file.url);
+      }
+    }
+
+    file.data = Buffer.from(data!);
+  },
+};

package/src/types/index.ts

@@ -0,0 +1,58 @@
+import type {
+  JSONSchema4,
+  JSONSchema4Object,
+  JSONSchema6,
+  JSONSchema6Object,
+  JSONSchema7,
+  JSONSchema7Object,
+} from 'json-schema';
+
+export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
+export type JSONSchemaObject = JSONSchema4Object | JSONSchema6Object | JSONSchema7Object;
+
+export interface Plugin {
+  /**
+   * Can this parser be used to process this file?
+   */
+  canHandle: (file: FileInfo) => boolean;
+  /**
+   * This is where the real work of a parser happens. The `parse` method accepts the same file info object as the `canHandle` 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 `canHandle` 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:
+   */
+  handler: (
+    file: FileInfo,
+  ) =>
+    | string
+    | Buffer
+    | JSONSchema
+    | Promise<{ data: Buffer }>
+    | Promise<string | Buffer | JSONSchema>;
+  name: 'binary' | 'file' | 'http' | 'json' | 'text' | 'yaml';
+}
+
+/**
+ * JSON Schema `$Ref` Parser supports plug-ins, such as resolvers and parsers. These plug-ins can have methods such as `canHandle()`, `read()`, `canHandle()`, 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 raw file contents, in whatever form they were returned by the resolver that read the file.
+   */
+  data: string | Buffer;
+  /**
+   * The lowercase file extension, such as ".json", ".yaml", ".txt", etc.
+   */
+  extension: 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 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;
+}

package/src/util/convert-path-to-posix.ts

@@ -0,0 +1,8 @@
+export default function convertPathToPosix(filePath: string): string {
+  // Extended-length paths on Windows should not be converted
+  if (filePath.startsWith('\\\\?\\')) {
+    return filePath;
+  }
+
+  return filePath.replaceAll('\\', '/');
+}

package/src/util/errors.ts

@@ -0,0 +1,155 @@
+import { Ono } from '@jsdevtools/ono';
+
+import type { $RefParser } from '..';
+import type $Ref from '../ref';
+import type { JSONSchema } from '../types';
+import { getHash, stripHash, toFileSystemPath } from './url';
+
+export type JSONParserErrorType =
+  | 'EUNKNOWN'
+  | 'EPARSER'
+  | 'EUNMATCHEDPARSER'
+  | 'ETIMEOUT'
+  | 'ERESOLVER'
+  | 'EUNMATCHEDRESOLVER'
+  | 'EMISSINGPOINTER'
+  | 'EINVALIDPOINTER';
+
+export class JSONParserError extends Error {
+  public readonly name: string;
+  public readonly message: string;
+  public source: string | undefined;
+  public path: Array<string | number> | null;
+  public readonly code: JSONParserErrorType;
+  public constructor(message: string, source?: string) {
+    super();
+
+    this.code = 'EUNKNOWN';
+    this.name = 'JSONParserError';
+    this.message = message;
+    this.source = source;
+    this.path = null;
+
+    Ono.extend(this);
+  }
+
+  get footprint() {
+    return `${this.path}+${this.source}+${this.code}+${this.message}`;
+  }
+}
+
+export class JSONParserErrorGroup<S extends object = JSONSchema> extends Error {
+  files: $RefParser;
+
+  constructor(parser: $RefParser) {
+    super();
+
+    this.files = parser;
+    this.name = 'JSONParserErrorGroup';
+    this.message = `${this.errors.length} error${
+      this.errors.length > 1 ? 's' : ''
+    } occurred while reading '${toFileSystemPath(parser.$refs._root$Ref!.path)}'`;
+
+    Ono.extend(this);
+  }
+
+  static getParserErrors<S extends object = JSONSchema>(parser: $RefParser) {
+    const errors = [];
+
+    for (const $ref of Object.values(parser.$refs._$refs) as $Ref<S>[]) {
+      if ($ref.errors) {
+        errors.push(...$ref.errors);
+      }
+    }
+
+    return errors;
+  }
+
+  get errors(): Array<
+    | JSONParserError
+    | InvalidPointerError
+    | ResolverError
+    | ParserError
+    | MissingPointerError
+    | UnmatchedParserError
+    | UnmatchedResolverError
+  > {
+    return JSONParserErrorGroup.getParserErrors<S>(this.files);
+  }
+}
+
+export class ParserError extends JSONParserError {
+  code = 'EPARSER' as JSONParserErrorType;
+  name = 'ParserError';
+  constructor(message: any, source: any) {
+    super(`Error parsing ${source}: ${message}`, source);
+  }
+}
+
+export class UnmatchedParserError extends JSONParserError {
+  code = 'EUNMATCHEDPARSER' as JSONParserErrorType;
+  name = 'UnmatchedParserError';
+
+  constructor(source: string) {
+    super(`Could not find parser for "${source}"`, source);
+  }
+}
+
+export class ResolverError extends JSONParserError {
+  code = 'ERESOLVER' as JSONParserErrorType;
+  name = 'ResolverError';
+  ioErrorCode?: string;
+  constructor(ex: Error | any, source?: string) {
+    super(ex.message || `Error reading file "${source}"`, source);
+    if ('code' in ex) {
+      this.ioErrorCode = String(ex.code);
+    }
+  }
+}
+
+export class UnmatchedResolverError extends JSONParserError {
+  code = 'EUNMATCHEDRESOLVER' as JSONParserErrorType;
+  name = 'UnmatchedResolverError';
+  constructor(source: any) {
+    super(`Could not find resolver for "${source}"`, source);
+  }
+}
+
+export class MissingPointerError extends JSONParserError {
+  code = 'EMISSINGPOINTER' as JSONParserErrorType;
+  name = 'MissingPointerError';
+  constructor(token: string, path: string) {
+    super(
+      `Missing $ref pointer "${getHash(path)}". Token "${token}" does not exist.`,
+      stripHash(path),
+    );
+  }
+}
+
+export class TimeoutError extends JSONParserError {
+  code = 'ETIMEOUT' as JSONParserErrorType;
+  name = 'TimeoutError';
+  constructor(timeout: number) {
+    super(`Dereferencing timeout reached: ${timeout}ms`);
+  }
+}
+
+export class InvalidPointerError extends JSONParserError {
+  code = 'EUNMATCHEDRESOLVER' as JSONParserErrorType;
+  name = 'InvalidPointerError';
+  constructor(pointer: string, path: string) {
+    super(`Invalid $ref pointer "${pointer}". Pointers must begin with "#/"`, stripHash(path));
+  }
+}
+
+export function isHandledError(err: any): err is JSONParserError {
+  return err instanceof JSONParserError || err instanceof JSONParserErrorGroup;
+}
+
+export function normalizeError(err: any) {
+  if (err.path === null) {
+    err.path = [];
+  }
+
+  return err;
+}

package/src/util/is-windows.ts

@@ -0,0 +1,2 @@
+const isWindowsConst = /^win/.test(globalThis.process ? globalThis.process.platform : '');
+export const isWindows = () => isWindowsConst;

package/src/util/plugins.ts

@@ -0,0 +1,55 @@
+import type { FileInfo, JSONSchema, Plugin } from '../types';
+
+export interface PluginResult {
+  error?: any;
+  plugin: Pick<Plugin, 'handler'>;
+  result?: string | Buffer | JSONSchema;
+}
+
+/**
+ * Runs the specified method of the given plugins, in order, until one of them returns a successful result.
+ * Each method can return a synchronous value, a Promise, or call an error-first callback.
+ * If the promise resolves successfully, or the callback is called without an error, then the result
+ * is immediately returned and no further plugins are called.
+ * If the promise rejects, or the callback is called with an error, then the next plugin is called.
+ * If ALL plugins fail, then the last error is thrown.
+ */
+export async function run(plugins: Pick<Plugin, 'handler'>[], file: FileInfo) {
+  let index = 0;
+  let lastError: PluginResult;
+  let plugin: Pick<Plugin, 'handler'>;
+
+  return new Promise<PluginResult>((resolve, reject) => {
+    const runNextPlugin = async () => {
+      plugin = plugins[index++]!;
+
+      if (!plugin) {
+        // there are no more functions, re-throw the last error
+        return reject(lastError);
+      }
+
+      try {
+        const result = await plugin.handler(file);
+
+        if (result !== undefined) {
+          return resolve({
+            plugin,
+            result,
+          });
+        }
+
+        if (index === plugins.length) {
+          throw new Error('No promise has been returned.');
+        }
+      } catch (e) {
+        lastError = {
+          error: e,
+          plugin,
+        };
+        runNextPlugin();
+      }
+    };
+
+    runNextPlugin();
+  });
+}

package/src/util/url.ts

@@ -0,0 +1,265 @@
+import path, { join, win32 } from 'node:path';
+
+import convertPathToPosix from './convert-path-to-posix';
+import { isWindows } from './is-windows';
+
+const forwardSlashPattern = /\//g;
+const protocolPattern = /^(\w{2,}):\/\//i;
+
+// RegExp patterns to URL-encode special characters in local filesystem paths
+const urlEncodePatterns = [
+  [/\?/g, '%3F'],
+  [/#/g, '%23'],
+] as [RegExp, string][];
+
+// RegExp patterns to URL-decode special characters for local filesystem paths
+const urlDecodePatterns = [/%23/g, '#', /%24/g, '$', /%26/g, '&', /%2C/g, ',', /%40/g, '@'];
+
+/**
+ * Returns resolved target URL relative to a base URL in a manner similar to that of a Web browser resolving an anchor tag HREF.
+ *
+ * @returns
+ */
+export function resolve(from: string, to: string) {
+  const fromUrl = new URL(convertPathToPosix(from), 'resolve://');
+  const resolvedUrl = new URL(convertPathToPosix(to), fromUrl);
+  const endSpaces = to.match(/(\s*)$/)?.[1] || '';
+  if (resolvedUrl.protocol === 'resolve:') {
+    // `from` is a relative URL.
+    const { hash, pathname, search } = resolvedUrl;
+    return pathname + search + hash + endSpaces;
+  }
+  return resolvedUrl.toString() + endSpaces;
+}
+
+/**
+ * Returns the current working directory (in Node) or the current page URL (in browsers).
+ *
+ * @returns
+ */
+export function cwd() {
+  if (typeof window !== 'undefined') {
+    return location.href;
+  }
+
+  const path = process.cwd();
+
+  const lastChar = path.slice(-1);
+  if (lastChar === '/' || lastChar === '\\') {
+    return path;
+  } else {
+    return path + '/';
+  }
+}
+
+/**
+ * Returns the protocol of the given URL, or `undefined` if it has no protocol.
+ *
+ * @param path
+ * @returns
+ */
+export function getProtocol(path: string | undefined) {
+  const match = protocolPattern.exec(path || '');
+  if (match) {
+    return match[1]!.toLowerCase();
+  }
+  return undefined;
+}
+
+/**
+ * Returns the lowercased file extension of the given URL,
+ * or an empty string if it has no extension.
+ *
+ * @param path
+ * @returns
+ */
+export function getExtension(path: any) {
+  const lastDot = path.lastIndexOf('.');
+  if (lastDot > -1) {
+    return stripQuery(path.substr(lastDot).toLowerCase());
+  }
+  return '';
+}
+
+/**
+ * Removes the query, if any, from the given path.
+ *
+ * @param path
+ * @returns
+ */
+export function stripQuery(path: any) {
+  const queryIndex = path.indexOf('?');
+  if (queryIndex > -1) {
+    path = path.substr(0, queryIndex);
+  }
+  return path;
+}
+
+/**
+ * Returns the hash (URL fragment), of the given path.
+ * If there is no hash, then the root hash ("#") is returned.
+ *
+ * @param path
+ * @returns
+ */
+export function getHash(path: undefined | string) {
+  if (!path) {
+    return '#';
+  }
+  const hashIndex = path.indexOf('#');
+  if (hashIndex > -1) {
+    return path.substring(hashIndex);
+  }
+  return '#';
+}
+
+/**
+ * Removes the hash (URL fragment), if any, from the given path.
+ *
+ * @param path
+ * @returns
+ */
+export function stripHash(path?: string | undefined) {
+  if (!path) {
+    return '';
+  }
+  const hashIndex = path.indexOf('#');
+  if (hashIndex > -1) {
+    path = path.substring(0, hashIndex);
+  }
+  return path;
+}
+
+/**
+ * Determines whether the given path is a filesystem path.
+ * This includes "file://" URLs.
+ *
+ * @param path
+ * @returns
+ */
+export function isFileSystemPath(path: string | undefined) {
+  // @ts-ignore
+  if (typeof window !== 'undefined' || (typeof process !== 'undefined' && process.browser)) {
+    // We're running in a browser, so assume that all paths are URLs.
+    // This way, even relative paths will be treated as URLs rather than as filesystem paths
+    return false;
+  }
+
+  const protocol = getProtocol(path);
+  return protocol === undefined || protocol === 'file';
+}
+
+/**
+ * Converts a filesystem path to a properly-encoded URL.
+ *
+ * This is intended to handle situations where JSON Schema $Ref Parser is called
+ * with a filesystem path that contains characters which are not allowed in URLs.
+ *
+ * @example
+ * The following filesystem paths would be converted to the following URLs:
+ *
+ *    <"!@#$%^&*+=?'>.json              ==>   %3C%22!@%23$%25%5E&*+=%3F\'%3E.json
+ *    C:\\My Documents\\File (1).json   ==>   C:/My%20Documents/File%20(1).json
+ *    file://Project #42/file.json      ==>   file://Project%20%2342/file.json
+ *
+ * @param path
+ * @returns
+ */
+export function fromFileSystemPath(path: string) {
+  // Step 1: On Windows, replace backslashes with forward slashes,
+  // rather than encoding them as "%5C"
+  if (isWindows()) {
+    const projectDir = cwd();
+    const upperPath = path.toUpperCase();
+    const projectDirPosixPath = convertPathToPosix(projectDir);
+    const posixUpper = projectDirPosixPath.toUpperCase();
+    const hasProjectDir = upperPath.includes(posixUpper);
+    const hasProjectUri = upperPath.includes(posixUpper);
+    const isAbsolutePath =
+      win32.isAbsolute(path) ||
+      path.startsWith('http://') ||
+      path.startsWith('https://') ||
+      path.startsWith('file://');
+
+    if (!(hasProjectDir || hasProjectUri || isAbsolutePath) && !projectDir.startsWith('http')) {
+      path = join(projectDir, path);
+    }
+    path = convertPathToPosix(path);
+  }
+
+  // Step 2: `encodeURI` will take care of MOST characters
+  path = encodeURI(path);
+
+  // Step 3: Manually encode characters that are not encoded by `encodeURI`.
+  // This includes characters such as "#" and "?", which have special meaning in URLs,
+  // but are just normal characters in a filesystem path.
+  for (const pattern of urlEncodePatterns) {
+    path = path.replace(pattern[0], pattern[1]);
+  }
+
+  return path;
+}
+
+/**
+ * Converts a URL to a local filesystem path.
+ */
+export function toFileSystemPath(path: string | undefined, keepFileProtocol?: boolean): string {
+  // Step 1: `decodeURI` will decode characters such as Cyrillic characters, spaces, etc.
+  path = decodeURI(path!);
+
+  // Step 2: Manually decode characters that are not decoded by `decodeURI`.
+  // This includes characters such as "#" and "?", which have special meaning in URLs,
+  // but are just normal characters in a filesystem path.
+  for (let i = 0; i < urlDecodePatterns.length; i += 2) {
+    path = path.replace(urlDecodePatterns[i]!, urlDecodePatterns[i + 1] as string);
+  }
+
+  // Step 3: If it's a "file://" URL, then format it consistently
+  // or convert it to a local filesystem path
+  let isFileUrl = path.substr(0, 7).toLowerCase() === 'file://';
+  if (isFileUrl) {
+    // Strip-off the protocol, and the initial "/", if there is one
+    path = path[7] === '/' ? path.substr(8) : path.substr(7);
+
+    // insert a colon (":") after the drive letter on Windows
+    if (isWindows() && path[1] === '/') {
+      path = path[0] + ':' + path.substr(1);
+    }
+
+    if (keepFileProtocol) {
+      // Return the consistently-formatted "file://" URL
+      path = 'file:///' + path;
+    } else {
+      // Convert the "file://" URL to a local filesystem path.
+      // On Windows, it will start with something like "C:/".
+      // On Posix, it will start with "/"
+      isFileUrl = false;
+      path = isWindows() ? path : '/' + path;
+    }
+  }
+
+  // Step 4: Normalize Windows paths (unless it's a "file://" URL)
+  if (isWindows() && !isFileUrl) {
+    // Replace forward slashes with backslashes
+    path = path.replace(forwardSlashPattern, '\\');
+
+    // Capitalize the drive letter
+    if (path.substr(1, 2) === ':\\') {
+      path = path[0]!.toUpperCase() + path.substr(1);
+    }
+  }
+
+  return path;
+}
+
+export function relative(from: string, to: string) {
+  if (!isFileSystemPath(from) || !isFileSystemPath(to)) {
+    return resolve(from, to);
+  }
+
+  const fromDir = path.dirname(stripHash(from));
+  const toPath = stripHash(to);
+
+  const result = path.relative(fromDir, toPath);
+  return result + getHash(to);
+}