@mintlify/common 1.0.1131 → 1.0.1133

package/dist/openapi/overlay/overlayRegistry.d.ts

@@ -0,0 +1,47 @@
+import { type OverlayDocument } from '@mintlify/validation';
+import type { LoadedOverlay } from './applyOverlay.js';
+/** An overlay file discovered by walking the docs repository. */
+export type DiscoveredOverlay = {
+    /** Normalized repo location of the overlay file (no leading slash). */
+    location: string;
+    document: OverlayDocument;
+    /** Normalized spec key from `extends`; undefined means the overlay is never applied. */
+    resolvedExtends?: string;
+};
+export type OverlayRegistry = {
+    /** Normalized spec source -> ordered overlay refs explicitly configured in docs.json. */
+    explicit: Map<string, string[]>;
+    /** Auto-discovered overlays (applied only to specs with no explicit list). */
+    discovered: DiscoveredOverlay[];
+    /** Loads an explicitly referenced overlay by local path or https URL. */
+    loadOverlay: (ref: string) => Promise<LoadedOverlay>;
+};
+/** Canonical lookup key: URLs unchanged, paths posix-normalized without a leading slash. */
+export declare function normalizeOverlayKey(reference: string): string;
+/** Resolves an overlay's `extends` against the overlay file's own location. */
+export declare function resolveExtends(overlayLocation: string, extendsValue: string): string;
+export type CreateOverlayRegistryOptions = {
+    /** Explicit overlay lists from docs.json, keyed by normalized spec source. */
+    explicit?: Map<string, string[]>;
+    /** Overlay files discovered in the repository. */
+    discovered?: DiscoveredOverlay[];
+    /** Reads a local overlay file by normalized repo path. */
+    loadLocalDocument?: (normalizedPath: string) => Promise<unknown>;
+    /** Allow http:// overlay URLs (CLI --local-schema). */
+    localSchema?: boolean;
+    /**
+     * Overrides fetching and parsing of overlay URLs. Hosted environments substitute an
+     * SSRF-safe fetch that blocks private, loopback, and metadata targets across redirects.
+     */
+    fetchRemoteDocument?: (url: string) => Promise<unknown>;
+};
+/** Validates a parsed value as an Overlay document, JSON-normalizing YAML values. */
+export declare function parseLoadedOverlayDocument(value: unknown, location: string): OverlayDocument;
+export declare function createOverlayRegistry({ explicit, discovered, loadLocalDocument, localSchema, fetchRemoteDocument, }: CreateOverlayRegistryOptions): OverlayRegistry;
+/**
+ * Resolves the ordered list of overlays to apply to a spec:
+ * - an explicit `overlays` list in docs.json wins (an empty list disables everything)
+ * - otherwise auto-discovered overlays whose `extends` resolves to this spec apply, in
+ *   alphabetical order of the overlay file's location.
+ */
+export declare function resolveOverlaysForSpec(registry: OverlayRegistry, specLocation: string): Promise<LoadedOverlay[]>;

package/dist/openapi/overlay/overlayRegistry.js

@@ -0,0 +1,107 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { parseOverlayDocument } from '@mintlify/validation';
+import { isAbsoluteUrl } from '../../isAbsoluteUrl.js';
+import { fetchYamlDocument } from '../fetchYamlDocument.js';
+import { toJsonValue } from './jsonValue.js';
+/** Canonical lookup key: URLs unchanged, paths posix-normalized without a leading slash. */
+export function normalizeOverlayKey(reference) {
+    if (isAbsoluteUrl(reference))
+        return reference;
+    return normalizePathSegments(reference.split('/'));
+}
+function normalizePathSegments(segments) {
+    const resolved = [];
+    for (const segment of segments) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..') {
+            resolved.pop();
+            continue;
+        }
+        resolved.push(segment);
+    }
+    return resolved.join('/');
+}
+/** Resolves an overlay's `extends` against the overlay file's own location. */
+export function resolveExtends(overlayLocation, extendsValue) {
+    if (isAbsoluteUrl(extendsValue))
+        return extendsValue;
+    if (extendsValue.startsWith('/')) {
+        return normalizeOverlayKey(extendsValue);
+    }
+    const directorySegments = normalizeOverlayKey(overlayLocation).split('/').slice(0, -1);
+    return normalizePathSegments([...directorySegments, ...extendsValue.split('/')]);
+}
+/** Validates a parsed value as an Overlay document, JSON-normalizing YAML values. */
+export function parseLoadedOverlayDocument(value, location) {
+    const jsonValue = toJsonValue(value, `Overlay document ${location}`);
+    return parseOverlayDocument(jsonValue);
+}
+const isAllowedOverlayUrl = (reference, localSchema) => {
+    if (reference.startsWith('https:'))
+        return true;
+    return localSchema === true && reference.startsWith('http:');
+};
+export function createOverlayRegistry({ explicit = new Map(), discovered = [], loadLocalDocument, localSchema, fetchRemoteDocument, }) {
+    const cache = new Map();
+    const discoveredByLocation = new Map(discovered.map((overlay) => [overlay.location, overlay]));
+    const loadOverlay = (ref) => {
+        const key = normalizeOverlayKey(ref);
+        const cached = cache.get(key);
+        if (cached)
+            return cached;
+        const promise = (() => __awaiter(this, void 0, void 0, function* () {
+            if (isAbsoluteUrl(key)) {
+                if (!isAllowedOverlayUrl(key, localSchema)) {
+                    throw new Error(`Overlay URL ${ref} must use https. http:// overlay URLs are only supported with the CLI option --local-schema.`);
+                }
+                const raw = fetchRemoteDocument
+                    ? yield fetchRemoteDocument(key)
+                    : yield fetchYamlDocument(key);
+                return { document: parseLoadedOverlayDocument(raw, key), location: key };
+            }
+            const alreadyDiscovered = discoveredByLocation.get(key);
+            if (alreadyDiscovered) {
+                return { document: alreadyDiscovered.document, location: alreadyDiscovered.location };
+            }
+            if (!loadLocalDocument) {
+                throw new Error(`Overlay file ${ref} was not found in the repository`);
+            }
+            const raw = yield loadLocalDocument(key);
+            if (raw == undefined) {
+                throw new Error(`Overlay file ${ref} was not found in the repository`);
+            }
+            return { document: parseLoadedOverlayDocument(raw, key), location: key };
+        }))();
+        cache.set(key, promise);
+        return promise;
+    };
+    return { explicit, discovered, loadOverlay };
+}
+/**
+ * Resolves the ordered list of overlays to apply to a spec:
+ * - an explicit `overlays` list in docs.json wins (an empty list disables everything)
+ * - otherwise auto-discovered overlays whose `extends` resolves to this spec apply, in
+ *   alphabetical order of the overlay file's location.
+ */
+export function resolveOverlaysForSpec(registry, specLocation) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const key = normalizeOverlayKey(specLocation);
+        const explicitRefs = registry.explicit.get(key);
+        if (explicitRefs !== undefined) {
+            return Promise.all(explicitRefs.map((ref) => registry.loadOverlay(ref)));
+        }
+        return registry.discovered
+            .filter((overlay) => overlay.resolvedExtends === key)
+            .sort((a, b) => (a.location < b.location ? -1 : a.location > b.location ? 1 : 0))
+            .map((overlay) => ({ document: overlay.document, location: overlay.location }));
+    });
+}