@speclynx/apidom-reference 4.0.3 → 4.0.5

package/src/parse/index.ts

@@ -1,67 +0,0 @@
-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.ts

@@ -1,80 +0,0 @@
-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.ts

@@ -1,78 +0,0 @@
-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.ts

@@ -1,76 +0,0 @@
-import { pick } from 'ramda';
-import { ParseResultElement } from '@speclynx/apidom-datamodel';
-import {
-  parse,
-  mediaTypes as ArazzoJSON1MediaTypes,
-  detect,
-} from '@speclynx/apidom-parser-adapter-arazzo-json-1';
-
-import ParserError from '../../../errors/ParserError.ts';
-import Parser, { ParserOptions } from '../Parser.ts';
-import File from '../../../File.ts';
-import type { ReferenceOptions } from '../../../options/index.ts';
-import { parseSourceDescriptions } from './source-descriptions.ts';
-export type { default as Parser, ParserOptions } from '../Parser.ts';
-export type { default as File, FileOptions } from '../../../File.ts';
-
-/**
- * @public
- */
-export interface ArazzoJSON1ParserOptions extends Omit<ParserOptions, 'name'> {}
-
-/**
- * @public
- */
-class ArazzoJSON1Parser extends Parser {
-  public refractorOpts!: object;
-
-  constructor(options?: ArazzoJSON1ParserOptions) {
-    const { fileExtensions = [], mediaTypes = ArazzoJSON1MediaTypes, ...rest } = options ?? {};
-
-    super({ ...rest, name: 'arazzo-json-1', fileExtensions, mediaTypes });
-  }
-
-  async canParse(file: File): Promise<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) {
-      return detect(file.toString());
-    }
-    return false;
-  }
-
-  async parse(file: File, options?: ReferenceOptions): Promise<ParseResultElement> {
-    const source = file.toString();
-
-    try {
-      const parserOpts = pick(['sourceMap', 'style', 'strict', 'refractorOpts'], this);
-      const parseResult = await parse(source, parserOpts);
-
-      const shouldParseSourceDescriptions =
-        options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ??
-        options?.parse?.parserOpts?.sourceDescriptions;
-      if (shouldParseSourceDescriptions) {
-        const sourceDescriptions = await parseSourceDescriptions(
-          parseResult,
-          file.uri,
-          options!,
-          this.name,
-        );
-        parseResult.push(...sourceDescriptions);
-      }
-
-      return parseResult;
-    } catch (error: unknown) {
-      throw new ParserError(`Error parsing "${file.uri}"`, { cause: error });
-    }
-  }
-}
-
-export { parseSourceDescriptions } from './source-descriptions.ts';
-
-export default ArazzoJSON1Parser;

package/src/parse/parsers/arazzo-json-1/source-descriptions.ts

@@ -1,280 +0,0 @@
-import {
-  Element,
-  ParseResultElement,
-  AnnotationElement,
-  isArrayElement,
-  isStringElement,
-} from '@speclynx/apidom-datamodel';
-import {
-  isArazzoSpecification1Element,
-  isSourceDescriptionElement,
-} from '@speclynx/apidom-ns-arazzo-1';
-import { isSwaggerElement } from '@speclynx/apidom-ns-openapi-2';
-import { isOpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';
-import { isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
-import { toValue } from '@speclynx/apidom-core';
-
-import File from '../../../File.ts';
-import * as url from '../../../util/url.ts';
-import type { ReferenceOptions } from '../../../options/index.ts';
-import { merge as mergeOptions } from '../../../options/util.ts';
-import parse from '../../index.ts';
-
-// shared key for recursion state (works across JSON/YAML parsers)
-const ARAZZO_RECURSION_KEY = 'arazzo-1';
-
-interface ParseSourceDescriptionContext {
-  baseURI: string;
-  options: ReferenceOptions;
-  currentDepth: number;
-  visitedUrls: Set<string>;
-}
-
-/**
- * Parses a single source description element.
- * Returns ParseResultElement on success, or undefined if skipped.
- */
-async function parseSourceDescription(
-  sourceDescription: Element,
-  ctx: ParseSourceDescriptionContext,
-): Promise<ParseResultElement> {
-  const parseResult = new ParseResultElement();
-
-  if (!isSourceDescriptionElement(sourceDescription)) {
-    const annotation = new AnnotationElement(
-      'Element is not a valid SourceDescriptionElement. Skipping',
-    );
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // set class and metadata from source description element
-  parseResult.classes.push('source-description');
-  if (isStringElement(sourceDescription.name))
-    parseResult.setMetaProperty('name', toValue(sourceDescription.name) as string);
-  if (isStringElement(sourceDescription.type))
-    parseResult.setMetaProperty('type', toValue(sourceDescription.type) as string);
-
-  const sourceDescriptionURI = toValue(sourceDescription.url);
-  if (typeof sourceDescriptionURI !== 'string') {
-    const annotation = new AnnotationElement(
-      'Source description URL is missing or not a string. Skipping',
-    );
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // normalize URI for consistent cycle detection and cache key matching
-  const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
-  parseResult.setMetaProperty('retrievalURI', retrievalURI);
-
-  // skip if already visited (cycle detection)
-  if (ctx.visitedUrls.has(retrievalURI)) {
-    const annotation = new AnnotationElement(
-      `Source description "${retrievalURI}" has already been visited. Skipping to prevent cycle`,
-    );
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-  ctx.visitedUrls.add(retrievalURI);
-
-  try {
-    const sourceDescriptionParseResult = await parse(
-      retrievalURI,
-      mergeOptions(ctx.options, {
-        parse: {
-          mediaType: 'text/plain', // allow parser plugin detection
-          parserOpts: {
-            // nested documents should parse all their source descriptions
-            // (parent's name filter doesn't apply to nested documents)
-            sourceDescriptions: true,
-            [ARAZZO_RECURSION_KEY]: {
-              sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsVisitedUrls: ctx.visitedUrls,
-            },
-          },
-        },
-      }),
-    );
-    // merge parsed result into our parse result
-    for (const item of sourceDescriptionParseResult) {
-      parseResult.push(item);
-    }
-  } catch (error: unknown) {
-    // create error annotation instead of failing entire parse
-    const message = error instanceof Error ? error.message : String(error);
-    const annotation = new AnnotationElement(
-      `Error parsing source description "${retrievalURI}": ${message}`,
-    );
-    annotation.classes.push('error');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // only allow OpenAPI and Arazzo as source descriptions
-  const { api: sourceDescriptionAPI } = parseResult;
-  const isOpenApi =
-    isSwaggerElement(sourceDescriptionAPI) ||
-    isOpenApi3_0Element(sourceDescriptionAPI) ||
-    isOpenApi3_1Element(sourceDescriptionAPI);
-  const isArazzo = isArazzoSpecification1Element(sourceDescriptionAPI);
-
-  if (!isOpenApi && !isArazzo) {
-    const annotation = new AnnotationElement(
-      `Source description "${retrievalURI}" is not an OpenAPI or Arazzo document`,
-    );
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // validate declared type matches actual parsed type
-  const declaredType = toValue(sourceDescription.type);
-  if (typeof declaredType === 'string') {
-    if (declaredType === 'openapi' && !isOpenApi) {
-      const annotation = new AnnotationElement(
-        `Source description "${retrievalURI}" declared as "openapi" but parsed as Arazzo document`,
-      );
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    } else if (declaredType === 'arazzo' && !isArazzo) {
-      const annotation = new AnnotationElement(
-        `Source description "${retrievalURI}" declared as "arazzo" but parsed as OpenAPI document`,
-      );
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    }
-  }
-
-  return parseResult;
-}
-
-/**
- * Parses source descriptions from an Arazzo document's ParseResult.
- *
- * Each source description result is attached to its corresponding
- * SourceDescriptionElement's meta as 'parseResult' for easy access,
- * regardless of success or failure. On failure, the ParseResultElement
- * contains annotations explaining what went wrong.
- *
- * @param parseResult - ParseResult containing an Arazzo specification
- * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
- * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
- *   in `parse.parserOpts` to filter which source descriptions to process.
- * @param parserName - Parser name for options lookup (defaults to 'arazzo-json-1')
- * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
- *   (each with class 'source-description' and metadata: name, type, retrievalURI).
- *   May return early with a single-element array containing a warning annotation when:
- *   - The API is not an Arazzo specification
- *   - The sourceDescriptions field is missing or not an array
- *   - Maximum parse depth is exceeded (error annotation)
- *   Returns an empty array when no source description names match the filter.
- *
- * @example
- * ```typescript
- * import { toValue } from '@speclynx/apidom-core';
- * import { options, mergeOptions } from '@speclynx/apidom-reference';
- * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
- *
- * // Parse all source descriptions
- * const results = await parseSourceDescriptions(parseResult, uri, options);
- *
- * // Filter by name
- * const filtered = await parseSourceDescriptions(parseResult, uri, mergeOptions(options, {
- *   parse: { parserOpts: { sourceDescriptions: ['petStore'] } }
- * }));
- *
- * // Access parsed document from source description element
- * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
- * const parsedDoc = sourceDesc.meta.get('parseResult');
- * const retrievalURI = toValue(parsedDoc.meta.get('retrievalURI'));
- * ```
- *
- * @public
- */
-export async function parseSourceDescriptions(
-  parseResult: ParseResultElement,
-  parseResultRetrievalURI: string,
-  options: ReferenceOptions,
-  parserName: string = 'arazzo-json-1',
-): Promise<ParseResultElement[]> {
-  const { api } = parseResult;
-  const file = new File({ uri: url.sanitize(url.stripHash(parseResultRetrievalURI)) });
-  const results: ParseResultElement[] = [];
-
-  /**
-   * Validate prerequisites for parsing source descriptions.
-   * Return warning annotations if validation fails.
-   */
-  if (!isArazzoSpecification1Element(api)) {
-    const annotation = new AnnotationElement(
-      'Cannot parse source descriptions: API is not an Arazzo specification',
-    );
-    annotation.classes.push('warning');
-    return [new ParseResultElement([annotation])];
-  }
-  if (!isArrayElement(api.sourceDescriptions)) {
-    const annotation = new AnnotationElement(
-      'Cannot parse source descriptions: sourceDescriptions field is missing or not an array',
-    );
-    annotation.classes.push('warning');
-    return [new ParseResultElement([annotation])];
-  }
-
-  // user config: parser-specific options take precedence over global parserOpts
-  const maxDepth =
-    options?.parse?.parserOpts?.[parserName]?.sourceDescriptionsMaxDepth ??
-    options?.parse?.parserOpts?.sourceDescriptionsMaxDepth ??
-    +Infinity;
-
-  // recursion state comes from shared key (works across JSON/YAML)
-  const sharedOpts = options?.parse?.parserOpts?.[ARAZZO_RECURSION_KEY] ?? {};
-  const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
-  const visitedUrls: Set<string> = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
-
-  // add current file to visited URLs to prevent cycles
-  visitedUrls.add(file.uri);
-
-  if (currentDepth >= maxDepth) {
-    const annotation = new AnnotationElement(
-      `Maximum parse depth of ${maxDepth} has been exceeded by file "${file.uri}"`,
-    );
-    annotation.classes.push('error');
-    const parseResult = new ParseResultElement([annotation]);
-    parseResult.classes.push('source-description');
-    return [parseResult];
-  }
-
-  const ctx: ParseSourceDescriptionContext = {
-    baseURI: file.uri,
-    options,
-    currentDepth,
-    visitedUrls,
-  };
-
-  // determine which source descriptions to parse (array filters by name)
-  const sourceDescriptionsOption =
-    options?.parse?.parserOpts?.[parserName]?.sourceDescriptions ??
-    options?.parse?.parserOpts?.sourceDescriptions;
-
-  const sourceDescriptions = Array.isArray(sourceDescriptionsOption)
-    ? api.sourceDescriptions.filter((sd) => {
-        if (!isSourceDescriptionElement(sd)) return false;
-        const name = toValue(sd.name);
-        return typeof name === 'string' && sourceDescriptionsOption.includes(name);
-      })
-    : api.sourceDescriptions;
-
-  // process sequentially to ensure proper cycle detection with shared visitedUrls
-  for (const sourceDescription of sourceDescriptions) {
-    const sourceDescriptionParseResult = await parseSourceDescription(sourceDescription, ctx);
-    // always attach result (even on failure - contains annotations)
-    sourceDescription.meta.set('parseResult', sourceDescriptionParseResult);
-    results.push(sourceDescriptionParseResult);
-  }
-
-  return results;
-}

package/src/parse/parsers/arazzo-yaml-1/index.ts

@@ -1,77 +0,0 @@
-import { pick } from 'ramda';
-import { ParseResultElement } from '@speclynx/apidom-datamodel';
-import {
-  parse,
-  mediaTypes as ArazzoYAML1MediaTypes,
-  detect,
-} from '@speclynx/apidom-parser-adapter-arazzo-yaml-1';
-
-import ParserError from '../../../errors/ParserError.ts';
-import Parser, { ParserOptions } from '../Parser.ts';
-import File from '../../../File.ts';
-import type { ReferenceOptions } from '../../../options/index.ts';
-import { parseSourceDescriptions } from './source-descriptions.ts';
-
-export type { default as Parser, ParserOptions } from '../Parser.ts';
-export type { default as File, FileOptions } from '../../../File.ts';
-
-/**
- * @public
- */
-export interface ArazzoYAML1ParserOptions extends Omit<ParserOptions, 'name'> {}
-
-/**
- * @public
- */
-class ArazzoYAML1Parser extends Parser {
-  public refractorOpts!: object;
-
-  constructor(options?: ArazzoYAML1ParserOptions) {
-    const { fileExtensions = [], mediaTypes = ArazzoYAML1MediaTypes, ...rest } = options ?? {};
-
-    super({ ...rest, name: 'arazzo-yaml-1', fileExtensions, mediaTypes });
-  }
-
-  async canParse(file: File): Promise<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) {
-      return detect(file.toString());
-    }
-    return false;
-  }
-
-  async parse(file: File, options?: ReferenceOptions): Promise<ParseResultElement> {
-    const source = file.toString();
-
-    try {
-      const parserOpts = pick(['sourceMap', 'style', 'strict', 'refractorOpts'], this);
-      const parseResult = await parse(source, parserOpts);
-
-      const shouldParseSourceDescriptions =
-        options?.parse?.parserOpts?.[this.name]?.sourceDescriptions ??
-        options?.parse?.parserOpts?.sourceDescriptions;
-      if (shouldParseSourceDescriptions) {
-        const sourceDescriptions = await parseSourceDescriptions(
-          parseResult,
-          file.uri,
-          options!,
-          this.name,
-        );
-        parseResult.push(...sourceDescriptions);
-      }
-
-      return parseResult;
-    } catch (error: unknown) {
-      throw new ParserError(`Error parsing "${file.uri}"`, { cause: error });
-    }
-  }
-}
-
-export { parseSourceDescriptions } from './source-descriptions.ts';
-
-export default ArazzoYAML1Parser;

package/src/parse/parsers/arazzo-yaml-1/source-descriptions.ts

@@ -1,16 +0,0 @@
-import { ParseResultElement } from '@speclynx/apidom-datamodel';
-
-import { parseSourceDescriptions as parseSourceDescriptionsBase } from '../arazzo-json-1/source-descriptions.ts';
-import type { ReferenceOptions } from '../../../options/index.ts';
-
-/**
- * @public
- */
-export const parseSourceDescriptions = (
-  parseResult: ParseResultElement,
-  parseResultRetrievalURI: string,
-  options: ReferenceOptions,
-  parserName: string = 'arazzo-yaml-1',
-): Promise<ParseResultElement[]> => {
-  return parseSourceDescriptionsBase(parseResult, parseResultRetrievalURI, options, parserName);
-};