@speclynx/apidom-reference 4.0.2 → 4.0.3

package/src/parse/index.cjs

@@ -0,0 +1,69 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var url = _interopRequireWildcard(require("../util/url.cjs"));
+var _File = _interopRequireDefault(require("../File.cjs"));
+var plugins = _interopRequireWildcard(require("../util/plugins.cjs"));
+var _ParseError = _interopRequireDefault(require("../errors/ParseError.cjs"));
+var _UnmatchedParserError = _interopRequireDefault(require("../errors/UnmatchedParserError.cjs"));
+var _util = require("../resolve/util.cjs");
+/**
+ * Parses the given file's contents, using the configured parser plugins.
+ */
+const parseFile = async (file, options) => {
+  const optsBoundParsers = options.parse.parsers.map(parser => {
+    const clonedParser = Object.create(parser);
+    return Object.assign(clonedParser, options.parse.parserOpts);
+  });
+  const parsers = await plugins.filter('canParse', [file, options], optsBoundParsers);
+
+  // we couldn't find any parser for this File
+  if ((0, _ramda.isEmpty)(parsers)) {
+    throw new _UnmatchedParserError.default(`Could not find a parser that can parse the file "${file.uri}"`);
+  }
+  try {
+    const {
+      plugin,
+      result
+    } = await plugins.run('parse', [file, options], parsers);
+
+    // empty files handling
+    if (!plugin.allowEmpty && result.isEmpty) {
+      return Promise.reject(new _ParseError.default(`Error while parsing file "${file.uri}": file is empty`));
+    }
+    return result;
+  } catch (error) {
+    throw new _ParseError.default(`Error while parsing file "${file.uri}"`, {
+      cause: error
+    });
+  }
+};
+
+/**
+ * Parses a file into ApiDOM.
+ */
+const parse = async (uri, options) => {
+  /**
+   * If the path is a filesystem path, then convert it to a URL.
+   *
+   * NOTE: According to the JSON Reference spec, these should already be URLs,
+   * but, in practice, many people use local filesystem paths instead.
+   * So we're being generous here and doing the conversion automatically.
+   * This is not intended to be a 100% bulletproof solution.
+   * If it doesn't work for your use-case, then use a URL instead.
+   */
+  const file = new _File.default({
+    uri: url.sanitize(url.stripHash(uri)),
+    mediaType: options.parse.mediaType
+  });
+  const data = await (0, _util.readFile)(file, options);
+  return parseFile(new _File.default({
+    ...file,
+    data
+  }), options);
+};
+var _default = exports.default = parse;

package/src/parse/index.mjs

@@ -0,0 +1,63 @@
+import { isEmpty } from 'ramda';
+import * as url from "../util/url.mjs";
+import File from "../File.mjs";
+import * as plugins from "../util/plugins.mjs";
+import ParseError from "../errors/ParseError.mjs";
+import UnmatchedParserError from "../errors/UnmatchedParserError.mjs";
+import { readFile } from "../resolve/util.mjs";
+/**
+ * Parses the given file's contents, using the configured parser plugins.
+ */
+const parseFile = async (file, options) => {
+  const optsBoundParsers = options.parse.parsers.map(parser => {
+    const clonedParser = Object.create(parser);
+    return Object.assign(clonedParser, options.parse.parserOpts);
+  });
+  const parsers = await plugins.filter('canParse', [file, options], optsBoundParsers);
+
+  // we couldn't find any parser for this File
+  if (isEmpty(parsers)) {
+    throw new UnmatchedParserError(`Could not find a parser that can parse the file "${file.uri}"`);
+  }
+  try {
+    const {
+      plugin,
+      result
+    } = await plugins.run('parse', [file, options], parsers);
+
+    // empty files handling
+    if (!plugin.allowEmpty && result.isEmpty) {
+      return Promise.reject(new ParseError(`Error while parsing file "${file.uri}": file is empty`));
+    }
+    return result;
+  } catch (error) {
+    throw new ParseError(`Error while parsing file "${file.uri}"`, {
+      cause: error
+    });
+  }
+};
+
+/**
+ * Parses a file into ApiDOM.
+ */
+const parse = async (uri, options) => {
+  /**
+   * If the path is a filesystem path, then convert it to a URL.
+   *
+   * NOTE: According to the JSON Reference spec, these should already be URLs,
+   * but, in practice, many people use local filesystem paths instead.
+   * So we're being generous here and doing the conversion automatically.
+   * This is not intended to be a 100% bulletproof solution.
+   * If it doesn't work for your use-case, then use a URL instead.
+   */
+  const file = new File({
+    uri: url.sanitize(url.stripHash(uri)),
+    mediaType: options.parse.mediaType
+  });
+  const data = await readFile(file, options);
+  return parseFile(new File({
+    ...file,
+    data
+  }), options);
+};
+export default parse;

package/src/parse/index.ts

@@ -0,0 +1,67 @@
+import { isEmpty } from 'ramda';
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+
+import * as url from '../util/url.ts';
+import File from '../File.ts';
+import * as plugins from '../util/plugins.ts';
+import Parser from './parsers/Parser.ts';
+import ParseError from '../errors/ParseError.ts';
+import UnmatchedParserError from '../errors/UnmatchedParserError.ts';
+import { readFile } from '../resolve/util.ts';
+import type { ReferenceOptions } from '../options/index.ts';
+
+/**
+ * Parses the given file's contents, using the configured parser plugins.
+ */
+const parseFile = async (file: File, options: ReferenceOptions): Promise<ParseResultElement> => {
+  const optsBoundParsers = options.parse.parsers.map((parser) => {
+    const clonedParser = Object.create(parser);
+    return Object.assign(clonedParser, options.parse.parserOpts);
+  });
+
+  const parsers: Parser[] = await plugins.filter('canParse', [file, options], optsBoundParsers);
+
+  // we couldn't find any parser for this File
+  if (isEmpty(parsers)) {
+    throw new UnmatchedParserError(`Could not find a parser that can parse the file "${file.uri}"`);
+  }
+
+  try {
+    const { plugin, result } = await plugins.run('parse', [file, options], parsers);
+
+    // empty files handling
+    if (!plugin.allowEmpty && result.isEmpty) {
+      return Promise.reject(
+        new ParseError(`Error while parsing file "${file.uri}": file is empty`),
+      );
+    }
+
+    return result;
+  } catch (error: any) {
+    throw new ParseError(`Error while parsing file "${file.uri}"`, { cause: error });
+  }
+};
+
+/**
+ * Parses a file into ApiDOM.
+ */
+const parse = async (uri: string, options: ReferenceOptions): Promise<ParseResultElement> => {
+  /**
+   * If the path is a filesystem path, then convert it to a URL.
+   *
+   * NOTE: According to the JSON Reference spec, these should already be URLs,
+   * but, in practice, many people use local filesystem paths instead.
+   * So we're being generous here and doing the conversion automatically.
+   * This is not intended to be a 100% bulletproof solution.
+   * If it doesn't work for your use-case, then use a URL instead.
+   */
+  const file = new File({
+    uri: url.sanitize(url.stripHash(uri)),
+    mediaType: options.parse.mediaType,
+  });
+  const data = await readFile(file, options);
+
+  return parseFile(new File({ ...file, data }), options);
+};
+
+export default parse;

package/src/parse/parsers/Parser.cjs

@@ -0,0 +1,62 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Parser {
+  name;
+
+  /**
+   * Whether to allow "empty" files. This includes zero-byte files.
+   */
+  allowEmpty;
+
+  /**
+   * Whether to generate source map during parsing.
+   */
+  sourceMap;
+
+  /**
+   * Whether to capture format-specific style information for round-trip preservation.
+   */
+  style;
+
+  /**
+   * Whether to use strict parsing (native JSON.parse/YAML instead of tree-sitter).
+   */
+  strict;
+
+  /**
+   * List of supported file extensions.
+   */
+  fileExtensions;
+
+  /**
+   * List of supported media types.
+   */
+  mediaTypes;
+  constructor({
+    name,
+    allowEmpty = true,
+    sourceMap = false,
+    style = false,
+    strict = true,
+    fileExtensions = [],
+    mediaTypes = []
+  }) {
+    this.name = name;
+    this.allowEmpty = allowEmpty;
+    this.sourceMap = sourceMap;
+    this.style = style;
+    this.strict = strict;
+    this.fileExtensions = fileExtensions;
+    this.mediaTypes = mediaTypes;
+  }
+}
+var _default = exports.default = Parser;

package/src/parse/parsers/Parser.mjs

@@ -0,0 +1,58 @@
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Parser {
+  name;
+
+  /**
+   * Whether to allow "empty" files. This includes zero-byte files.
+   */
+  allowEmpty;
+
+  /**
+   * Whether to generate source map during parsing.
+   */
+  sourceMap;
+
+  /**
+   * Whether to capture format-specific style information for round-trip preservation.
+   */
+  style;
+
+  /**
+   * Whether to use strict parsing (native JSON.parse/YAML instead of tree-sitter).
+   */
+  strict;
+
+  /**
+   * List of supported file extensions.
+   */
+  fileExtensions;
+
+  /**
+   * List of supported media types.
+   */
+  mediaTypes;
+  constructor({
+    name,
+    allowEmpty = true,
+    sourceMap = false,
+    style = false,
+    strict = true,
+    fileExtensions = [],
+    mediaTypes = []
+  }) {
+    this.name = name;
+    this.allowEmpty = allowEmpty;
+    this.sourceMap = sourceMap;
+    this.style = style;
+    this.strict = strict;
+    this.fileExtensions = fileExtensions;
+    this.mediaTypes = mediaTypes;
+  }
+}
+export default Parser;

package/src/parse/parsers/Parser.ts

@@ -0,0 +1,80 @@
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+
+import File from '../../File.ts';
+import type { ReferenceOptions } from '../../options/index.ts';
+
+/**
+ * @public
+ */
+export interface ParserOptions {
+  readonly name: string;
+  readonly allowEmpty?: boolean;
+  readonly sourceMap?: boolean;
+  readonly style?: boolean;
+  readonly strict?: boolean;
+  readonly fileExtensions?: string[];
+  readonly mediaTypes?: string[];
+}
+
+/**
+ * @public
+ */
+abstract class Parser {
+  public readonly name: string;
+
+  /**
+   * Whether to allow "empty" files. This includes zero-byte files.
+   */
+  public allowEmpty: boolean;
+
+  /**
+   * Whether to generate source map during parsing.
+   */
+  public sourceMap: boolean;
+
+  /**
+   * Whether to capture format-specific style information for round-trip preservation.
+   */
+  public style: boolean;
+
+  /**
+   * Whether to use strict parsing (native JSON.parse/YAML instead of tree-sitter).
+   */
+  public strict: boolean;
+
+  /**
+   * List of supported file extensions.
+   */
+  public fileExtensions: string[];
+
+  /**
+   * List of supported media types.
+   */
+  public mediaTypes: string[];
+
+  constructor({
+    name,
+    allowEmpty = true,
+    sourceMap = false,
+    style = false,
+    strict = true,
+    fileExtensions = [],
+    mediaTypes = [],
+  }: ParserOptions) {
+    this.name = name;
+    this.allowEmpty = allowEmpty;
+    this.sourceMap = sourceMap;
+    this.style = style;
+    this.strict = strict;
+    this.fileExtensions = fileExtensions;
+    this.mediaTypes = mediaTypes;
+  }
+
+  abstract canParse(file: File, options?: ReferenceOptions): boolean | Promise<boolean>;
+  abstract parse(
+    file: File,
+    options?: ReferenceOptions,
+  ): ParseResultElement | Promise<ParseResultElement>;
+}
+
+export default Parser;

package/src/parse/parsers/apidom-json/index.cjs

@@ -0,0 +1,70 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _ParserError = _interopRequireDefault(require("../../../errors/ParserError.cjs"));
+var _Parser = _interopRequireDefault(require("../Parser.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class ApiDOMJSONParser extends _Parser.default {
+  namespace;
+  ['apidom-json'];
+  constructor(options) {
+    const {
+      fileExtensions = [],
+      mediaTypes = ['application/vnd.apidom', 'application/vnd.apidom+json'],
+      namespace = new _apidomDatamodel.Namespace(),
+      ...rest
+    } = options ?? {};
+    super({
+      ...rest,
+      name: 'apidom-json',
+      fileExtensions,
+      mediaTypes
+    });
+    this.namespace = namespace;
+  }
+  canParse(file) {
+    const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
+    const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
+    if (!hasSupportedFileExtension) return false;
+    if (hasSupportedMediaType) return true;
+    if (!hasSupportedMediaType) {
+      try {
+        return this.namespace.fromRefract(JSON.parse(file.toString())) && true;
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+  parse(file) {
+    const source = file.toString();
+    const namespace = this['apidom-json']?.namespace ?? this.namespace;
+
+    // allow empty files
+    if (this.allowEmpty && source.trim() === '') {
+      return new _apidomDatamodel.ParseResultElement();
+    }
+    try {
+      const element = namespace.fromRefract(JSON.parse(source));
+      if (!(0, _apidomDatamodel.isParseResultElement)(element)) {
+        element.classes.push('result');
+        return new _apidomDatamodel.ParseResultElement([element]);
+      }
+      return element;
+    } catch (error) {
+      throw new _ParserError.default(`Error parsing "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+var _default = exports.default = ApiDOMJSONParser;

package/src/parse/parsers/apidom-json/index.mjs

@@ -0,0 +1,64 @@
+import { Namespace, ParseResultElement, isParseResultElement } from '@speclynx/apidom-datamodel';
+import ParserError from "../../../errors/ParserError.mjs";
+import Parser from "../Parser.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class ApiDOMJSONParser extends Parser {
+  namespace;
+  ['apidom-json'];
+  constructor(options) {
+    const {
+      fileExtensions = [],
+      mediaTypes = ['application/vnd.apidom', 'application/vnd.apidom+json'],
+      namespace = new Namespace(),
+      ...rest
+    } = options ?? {};
+    super({
+      ...rest,
+      name: 'apidom-json',
+      fileExtensions,
+      mediaTypes
+    });
+    this.namespace = namespace;
+  }
+  canParse(file) {
+    const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
+    const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
+    if (!hasSupportedFileExtension) return false;
+    if (hasSupportedMediaType) return true;
+    if (!hasSupportedMediaType) {
+      try {
+        return this.namespace.fromRefract(JSON.parse(file.toString())) && true;
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+  parse(file) {
+    const source = file.toString();
+    const namespace = this['apidom-json']?.namespace ?? this.namespace;
+
+    // allow empty files
+    if (this.allowEmpty && source.trim() === '') {
+      return new ParseResultElement();
+    }
+    try {
+      const element = namespace.fromRefract(JSON.parse(source));
+      if (!isParseResultElement(element)) {
+        element.classes.push('result');
+        return new ParseResultElement([element]);
+      }
+      return element;
+    } catch (error) {
+      throw new ParserError(`Error parsing "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+export default ApiDOMJSONParser;

package/src/parse/parsers/apidom-json/index.ts

@@ -0,0 +1,78 @@
+import { Namespace, ParseResultElement, isParseResultElement } from '@speclynx/apidom-datamodel';
+
+import ParserError from '../../../errors/ParserError.ts';
+import Parser, { ParserOptions } from '../Parser.ts';
+import File from '../../../File.ts';
+
+export type { default as Parser, ParserOptions } from '../Parser.ts';
+export type { default as File, FileOptions } from '../../../File.ts';
+
+/**
+ * @public
+ */
+export interface ApiDOMJSONParserOptions extends Omit<ParserOptions, 'name'> {
+  readonly namespace?: Namespace;
+}
+
+/**
+ * @public
+ */
+class ApiDOMJSONParser extends Parser {
+  public namespace: Namespace;
+
+  public ['apidom-json']!: { namespace?: Namespace };
+
+  constructor(options?: ApiDOMJSONParserOptions) {
+    const {
+      fileExtensions = [],
+      mediaTypes = ['application/vnd.apidom', 'application/vnd.apidom+json'],
+      namespace = new Namespace(),
+      ...rest
+    } = options ?? {};
+
+    super({ ...rest, name: 'apidom-json', fileExtensions, mediaTypes });
+    this.namespace = namespace;
+  }
+
+  canParse(file: File): boolean {
+    const hasSupportedFileExtension =
+      this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
+    const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
+
+    if (!hasSupportedFileExtension) return false;
+    if (hasSupportedMediaType) return true;
+    if (!hasSupportedMediaType) {
+      try {
+        return this.namespace.fromRefract(JSON.parse(file.toString())) && true;
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+
+  parse(file: File): ParseResultElement {
+    const source = file.toString();
+    const namespace = this['apidom-json']?.namespace ?? this.namespace;
+
+    // allow empty files
+    if (this.allowEmpty && source.trim() === '') {
+      return new ParseResultElement();
+    }
+
+    try {
+      const element = namespace.fromRefract(JSON.parse(source));
+
+      if (!isParseResultElement(element)) {
+        element.classes.push('result');
+        return new ParseResultElement([element]);
+      }
+
+      return element;
+    } catch (error: unknown) {
+      throw new ParserError(`Error parsing "${file.uri}"`, { cause: error });
+    }
+  }
+}
+
+export default ApiDOMJSONParser;

package/src/parse/parsers/arazzo-json-1/index.cjs

@@ -0,0 +1,62 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _apidomParserAdapterArazzoJson = require("@speclynx/apidom-parser-adapter-arazzo-json-1");
+var _ParserError = _interopRequireDefault(require("../../../errors/ParserError.cjs"));
+var _Parser = _interopRequireDefault(require("../Parser.cjs"));
+var _sourceDescriptions = require("./source-descriptions.cjs");
+exports.parseSourceDescriptions = _sourceDescriptions.parseSourceDescriptions;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class ArazzoJSON1Parser extends _Parser.default {
+  refractorOpts;
+  constructor(options) {
+    const {
+      fileExtensions = [],
+      mediaTypes = _apidomParserAdapterArazzoJson.mediaTypes,
+      ...rest
+    } = options ?? {};
+    super({
+      ...rest,
+      name: 'arazzo-json-1',
+      fileExtensions,
+      mediaTypes
+    });
+  }
+  async canParse(file) {
+    const hasSupportedFileExtension = this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
+    const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
+    if (!hasSupportedFileExtension) return false;
+    if (hasSupportedMediaType) return true;
+    if (!hasSupportedMediaType) {
+      return (0, _apidomParserAdapterArazzoJson.detect)(file.toString());
+    }
+    return false;
+  }
+  async parse(file, options) {
+    const source = file.toString();
+    try {
+      const parserOpts = (0, _ramda.pick)(['sourceMap', 'style', 'strict', 'refractorOpts'], this);
+      const parseResult = await (0, _apidomParserAdapterArazzoJson.parse)(source, parserOpts);
+      const shouldParseSourceDescriptions = options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ?? options?.parse?.parserOpts?.sourceDescriptions;
+      if (shouldParseSourceDescriptions) {
+        const sourceDescriptions = await (0, _sourceDescriptions.parseSourceDescriptions)(parseResult, file.uri, options, this.name);
+        parseResult.push(...sourceDescriptions);
+      }
+      return parseResult;
+    } catch (error) {
+      throw new _ParserError.default(`Error parsing "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+var _default = exports.default = ArazzoJSON1Parser;