@speclynx/apidom-reference 4.13.0 → 4.14.0

package/src/util/url.cjs

@@ -4,7 +4,7 @@ var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequ
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.unsanitize = exports.toFileSystemPath = exports.stripHash = exports.sanitize = exports.resolve = exports.isURI = exports.isHttpUrl = exports.isFileSystemPath = exports.hasProtocol = exports.getProtocol = exports.getHash = exports.getExtension = exports.fromFileSystemPath = exports.cwd = void 0;
+exports.unsanitize = exports.toFileSystemPath = exports.stripHash = exports.sanitize = exports.resolve = exports.isURI = exports.isHttpUrl = exports.isFileSystemPath = exports.hasProtocol = exports.getProtocol = exports.getHash = exports.getExtension = exports.getBasename = exports.fromFileSystemPath = exports.cwd = void 0;
 var _process = _interopRequireDefault(require("process"));
 var _ramda = require("ramda");
 var _ramdaAdjunct = require("ramda-adjunct");
@@ -40,25 +40,47 @@ const getProtocol = url => {
 exports.getProtocol = getProtocol;
 const hasProtocol = exports.hasProtocol = (0, _ramda.pipe)(getProtocol, _ramdaAdjunct.isNotUndefined);
 
+/**
+ * Returns the final path segment of the given URI (the part after the last
+ * `/`). Inputs are URIs, whose path separator is `/` — filesystem paths are
+ * forward-slashed by `sanitize` before reaching here.
+ */
+const getFilename = uri => uri.slice(uri.lastIndexOf('/') + 1);
+
 /**
  * Returns the lower-cased file extension of the given URL,
  * or an empty string if it has no extension.
  * @public
  */
 const getExtension = url => {
-  const lastDotPosition = url.lastIndexOf('.');
+  const fileName = getFilename(url);
+  const lastDotPosition = fileName.lastIndexOf('.');
   if (lastDotPosition >= 0) {
-    return url.substring(lastDotPosition).toLowerCase();
+    return fileName.substring(lastDotPosition).toLowerCase();
   }
   return '';
 };
 
+/**
+ * Returns the final path segment of the given URI with its file extension
+ * removed (e.g. `./schemas/Pet.json` -> `Pet`). Returns the whole segment when
+ * there is no extension, and the whole URI when there is no path segment
+ * (e.g. a URN).
+ * @public
+ */
+exports.getExtension = getExtension;
+const getBasename = uri => {
+  const fileName = getFilename(uri);
+  const extension = getExtension(uri);
+  return extension === '' ? fileName : fileName.slice(0, -extension.length);
+};
+
 /**
  * Determines whether the given path is a filesystem path.
  * This includes "file://" URLs.
  * @public
  */
-exports.getExtension = getExtension;
+exports.getBasename = getBasename;
 const isFileSystemPath = uri => {
   const protocol = getProtocol(uri);
   return (0, _ramdaAdjunct.isUndefined)(protocol) || protocol === 'file' || /^[a-zA-Z]$/.test(protocol);

package/src/util/url.mjs

@@ -33,19 +33,40 @@ export const getProtocol = url => {
  */
 export const hasProtocol = pipe(getProtocol, isNotUndefined);
 
+/**
+ * Returns the final path segment of the given URI (the part after the last
+ * `/`). Inputs are URIs, whose path separator is `/` — filesystem paths are
+ * forward-slashed by `sanitize` before reaching here.
+ */
+const getFilename = uri => uri.slice(uri.lastIndexOf('/') + 1);
+
 /**
  * Returns the lower-cased file extension of the given URL,
  * or an empty string if it has no extension.
  * @public
  */
 export const getExtension = url => {
-  const lastDotPosition = url.lastIndexOf('.');
+  const fileName = getFilename(url);
+  const lastDotPosition = fileName.lastIndexOf('.');
   if (lastDotPosition >= 0) {
-    return url.substring(lastDotPosition).toLowerCase();
+    return fileName.substring(lastDotPosition).toLowerCase();
   }
   return '';
 };
 
+/**
+ * Returns the final path segment of the given URI with its file extension
+ * removed (e.g. `./schemas/Pet.json` -> `Pet`). Returns the whole segment when
+ * there is no extension, and the whole URI when there is no path segment
+ * (e.g. a URN).
+ * @public
+ */
+export const getBasename = uri => {
+  const fileName = getFilename(uri);
+  const extension = getExtension(uri);
+  return extension === '' ? fileName : fileName.slice(0, -extension.length);
+};
+
 /**
  * Determines whether the given path is a filesystem path.
  * This includes "file://" URLs.

package/types/apidom-reference.d.ts

@@ -240,6 +240,15 @@ export declare interface FileOptions {
  */
 declare const fromFileSystemPath: (uri: string) => string;
 
+/**
+ * Returns the final path segment of the given URI with its file extension
+ * removed (e.g. `./schemas/Pet.json` -> `Pet`). Returns the whole segment when
+ * there is no extension, and the whole URI when there is no path segment
+ * (e.g. a URN).
+ * @public
+ */
+declare const getBasename: (uri: string) => string;
+
 /**
  * Returns the lower-cased file extension of the given URL,
  * or an empty string if it has no extension.
@@ -627,6 +636,7 @@ declare namespace url {
         getProtocol,
         hasProtocol,
         getExtension,
+        getBasename,
         isFileSystemPath,
         isHttpUrl,
         isURI,

package/types/bundle/strategies/openapi-2/visitor.d.ts

@@ -68,11 +68,11 @@ declare class OpenAPI2BundleVisitor {
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;
     /**
-     * Normalizes a self-file reference (e.g. `./root.json#/definitions/Pet`)
+     * Normalizes a self-reference (e.g. `./root.json#/definitions/Pet`)
      * to a bare fragment (`#/definitions/Pet`) so the bundled document stays
      * transferable. Bare fragments are returned unchanged.
      */
-    protected normalizeSelfFileRef(ref: string): string;
+    protected normalizeSelfReference(ref: string): string;
     /**
      * Handles an error according to the `bundle.continueOnError` option.
      *

package/types/bundle/strategies/openapi-3-0/visitor.d.ts

@@ -68,11 +68,11 @@ declare class OpenAPI3_0BundleVisitor {
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;
     /**
-     * Normalizes a self-file reference (e.g. `./root.json#/components/schemas/Pet`)
+     * Normalizes a self-reference (e.g. `./root.json#/components/schemas/Pet`)
      * to a bare fragment (`#/components/schemas/Pet`) so the bundled document stays
      * transferable. Bare fragments are returned unchanged.
      */
-    protected normalizeSelfFileRef(ref: string): string;
+    protected normalizeSelfReference(ref: string): string;
     /**
      * Handles an error according to the `bundle.continueOnError` option.
      *

package/types/bundle/strategies/openapi-3-1/index.d.ts

@@ -1,15 +1,19 @@
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
 import File from '../../../File.ts';
 import BundleStrategy, { BundleStrategyOptions } from '../BundleStrategy.ts';
+import OpenAPI3_1BundleVisitor from './visitor.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
 export type { default as DereferenceStrategy, DereferenceStrategyOptions, } from '../../../dereference/strategies/DereferenceStrategy.ts';
 export type { default as File, FileOptions } from '../../../File.ts';
 export type { default as Reference, ReferenceOptions } from '../../../Reference.ts';
 export type { default as ReferenceSet, ReferenceSetOptions } from '../../../ReferenceSet.ts';
+export type { OpenAPI3_1BundleVisitorOptions } from './visitor.ts';
 export type { ReferenceOptions as ApiDOMReferenceOptions, ReferenceBundleOptions as ApiDOMReferenceBundleOptions, ReferenceDereferenceOptions as ApiDOMReferenceDereferenceOptions, ReferenceParseOptions as ApiDOMReferenceParseOptions, ReferenceResolveOptions as ApiDOMReferenceResolveOptions, } from '../../../options/index.ts';
 export type { default as Parser, ParserOptions } from '../../../parse/parsers/Parser.ts';
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
 export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
 export type { default as BundleStrategy, BundleStrategyOptions } from '../BundleStrategy.ts';
+export type { ComponentNamesStrategy, ComponentNameResolver, ComponentNameResolverArgs, ComponentNameCollisionSeverity, } from '../../../options/index.ts';
 /**
  * @public
  */
@@ -21,6 +25,7 @@ export interface OpenAPI3_1BundleStrategyOptions extends Omit<BundleStrategyOpti
 declare class OpenAPI3_1BundleStrategy extends BundleStrategy {
     constructor(options?: OpenAPI3_1BundleStrategyOptions);
     canBundle(file: File): boolean;
-    bundle(file: File): Promise<ParseResultElement>;
+    bundle(file: File, options: ReferenceOptions): Promise<ParseResultElement>;
 }
+export { OpenAPI3_1BundleVisitor };
 export default OpenAPI3_1BundleStrategy;

package/types/bundle/strategies/openapi-3-1/visitor.d.ts

@@ -0,0 +1,141 @@
+import { Element, ObjectElement, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { type Path } from '@speclynx/apidom-traverse';
+import { OpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
+import Reference from '../../../Reference.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * @public
+ */
+export interface OpenAPI3_1BundleVisitorOptions {
+    readonly reference: Reference;
+    readonly options: ReferenceOptions;
+    readonly assignments?: Map<string, string>;
+    readonly reservedNames?: Map<string, Set<string>>;
+    readonly refractCache?: WeakMap<Element, Map<string, Element>>;
+}
+/**
+ * @public
+ */
+declare class OpenAPI3_1BundleVisitor {
+    protected readonly reference: Reference;
+    protected readonly options: ReferenceOptions;
+    /**
+     * The base URI (without hash) of the entry document. A reference is
+     * considered internal when it resolves to this URI and external otherwise.
+     * Derived from the shared refSet's root reference.
+     */
+    protected get entryURI(): string;
+    /**
+     * The entry parse result. Derived from the shared refSet's root reference.
+     */
+    protected get entryParseResult(): ParseResultElement;
+    /**
+     * The entry document element. Hoisted external fragments are placed into its
+     * `components` object. The `canBundle` guard guarantees it is an
+     * OpenApi3_1Element.
+     */
+    protected get entryResult(): OpenApi3_1Element;
+    /**
+     * Shared across the entry document and every external document visitor.
+     * Guarantees each external fragment is hoisted exactly once and gives us a
+     * stable internal pointer to rewrite every referencing element to.
+     */
+    protected readonly assignments: Map<string, string>;
+    /**
+     * Component names already reserved per Components Object field. Reserved
+     * before recursion so collision suffixing (`Pet`, `Pet-2`, ...) accounts for
+     * components that are still being bundled.
+     */
+    protected readonly reservedNames: Map<string, Set<string>>;
+    /**
+     * Caches refracted fragments keyed by source element and target element type.
+     * The type is part of the key because the same source can be refracted into
+     * different semantic elements depending on the referencing context (e.g. a
+     * generic object referenced once as a Parameter and once as a Response).
+     */
+    protected readonly refractCache: WeakMap<Element, Map<string, Element>>;
+    constructor({ reference, options, assignments, reservedNames, refractCache, }: OpenAPI3_1BundleVisitorOptions);
+    protected getRefracted(source: Element, type: string): Element | undefined;
+    protected setRefracted(source: Element, type: string, refracted: Element): void;
+    protected toBaseURI(uri: string): string;
+    protected toReference(uri: string): Promise<Reference>;
+    /**
+     * Normalizes a self-reference (e.g. `./root.json#/components/schemas/Pet`)
+     * to a bare fragment (`#/components/schemas/Pet`) so the bundled document stays
+     * transferable. Bare fragments are returned unchanged.
+     */
+    protected normalizeSelfReference(ref: string): string;
+    /**
+     * Handles an error according to the `bundle.continueOnError` option.
+     *
+     * For new errors: wraps in UnresolvableReferenceError with structured
+     * context. For errors already wrapped by a nested visitor: prepends the
+     * current hop to the trace.
+     *
+     * Inner/intermediate visitors always throw to let the trace accumulate. Only
+     * the entry document visitor respects continueOnError (callback/swallow/throw).
+     */
+    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    /**
+     * Lazily creates the Components Object (and the requested field within it)
+     * on the entry document, returning the field where a fragment is hoisted.
+     */
+    protected ensureComponentsField(field: string): ObjectElement;
+    /**
+     * Derives a component name from the referenced JSON Pointer's last token,
+     * falling back to the referenced file's basename.
+     */
+    protected basenameOf(jsonPointer: string, baseURI: string): string;
+    /**
+     * Computes the base component name (before collision suffixing) according to
+     * the configured naming strategy.
+     */
+    protected baseName(element: Element, field: string, jsonPointer: string, baseURI: string): string;
+    /**
+     * Computes a collision-free component name within the target field. A name is
+     * taken if it's already placed in components or reserved by a component that
+     * is still being bundled (reserved before recursion).
+     */
+    protected uniqueName(candidate: string, field: string): string;
+    /**
+     * Reports a collision-forced rename according to the configured severity.
+     * A rename means two distinct targets resolved to the same name; each keeps
+     * its own component (and origin), so report the rename per severity.
+     */
+    protected reportNameCollision(preferredName: string, componentName: string, field: string): void;
+    ReferenceElement(path: Path<Element>): Promise<void>;
+    /**
+     * Unlike OpenAPI 3.0 (which has no `components.pathItems` field and therefore
+     * inlines external Path Items in place), OpenAPI 3.1 hoists an external Path
+     * Item Object into `components.pathItems` and rewrites the referencing `$ref`
+     * to an internal pointer — mirroring how Reference Objects are bundled.
+     * Sibling fields next to the `$ref` (e.g. `summary`, `description`) are kept
+     * on the referencing element.
+     */
+    PathItemElement(path: Path<Element>): Promise<void>;
+    /**
+     * Schema Objects in OpenAPI 3.1 are a JSON Schema 2020-12 dialect, so they are
+     * bundled per the JSON Schema Compound Document rules: the external schema
+     * RESOURCE is embedded verbatim into `components.schemas` (carrying its `$id`),
+     * and the referencing `$ref` is left UNCHANGED — it keeps resolving against the
+     * embedded resource's `$id`. This mirrors the canonical hyperjump
+     * `json-schema-bundle` behavior (the whole resource is embedded once, keyed by
+     * its `$id`; references are not rewritten).
+     */
+    SchemaElement(path: Path<Element>): Promise<void>;
+    /**
+     * Example Object `externalValue` points at arbitrary external content that
+     * has no place in the Components Object. The referenced value is inlined into
+     * the Example's `value` field.
+     */
+    ExampleElement(path: Path<Element>): Promise<void>;
+    /**
+     * Link Object `operationRef` points at an Operation Object, which has no
+     * Components Object field in OpenAPI 3.1 and therefore cannot be hoisted or
+     * inlined. To keep the link resolvable from the bundled document, an external
+     * `operationRef` is rewritten to its absolute URI. Internal `operationRef`
+     * values and `operationId` links are left untouched.
+     */
+    LinkElement(path: Path<Element>): Promise<void>;
+}
+export default OpenAPI3_1BundleVisitor;

package/types/util/url.d.ts

@@ -23,6 +23,14 @@ export declare const hasProtocol: (url: string) => boolean;
  * @public
  */
 export declare const getExtension: (url: string) => string;
+/**
+ * Returns the final path segment of the given URI with its file extension
+ * removed (e.g. `./schemas/Pet.json` -> `Pet`). Returns the whole segment when
+ * there is no extension, and the whole URI when there is no path segment
+ * (e.g. a URN).
+ * @public
+ */
+export declare const getBasename: (uri: string) => string;
 /**
  * Determines whether the given path is a filesystem path.
  * This includes "file://" URLs.