@mintlify/validation 0.1.848 → 0.1.849

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export { generateFirstIncrementalSchema, generateNextIncrementalSchema, } from '
 export * from './mint-config/validateConfig.js';
 export { formatIssue } from './mint-config/formatIssue.js';
 export { upgradeToDocsConfig } from './mint-config/upgrades/upgradeToDocsConfig.js';
+export { collectOpenApiOverlayConfig, normalizeOpenApiSourceKey, type ExplicitOverlayConfig, } from './mint-config/collectOpenApiOverlays.js';
+export { overlayDocumentSchema, overlayActionSchema, overlayInfoSchema, isOverlayDocument, parseOverlayDocument, safeParseOverlayDocument, type OverlayDocument, type OverlayAction, type OverlayInfo, } from './openapi/overlay.js';
 export { convertMintDecoratedNavToDocsDecoratedNav } from './mint-config/upgrades/convertMintDecoratedNavToDocsDecoratedNav.js';
 export declare const mintConfigJsonSchema: import("zod-to-json-schema/src/parseDef.js").JsonSchema7Type & {
     $schema?: string | undefined;

package/dist/index.js

@@ -29,6 +29,8 @@ export { generateFirstIncrementalSchema, generateNextIncrementalSchema, } from '
 export * from './mint-config/validateConfig.js';
 export { formatIssue } from './mint-config/formatIssue.js';
 export { upgradeToDocsConfig } from './mint-config/upgrades/upgradeToDocsConfig.js';
+export { collectOpenApiOverlayConfig, normalizeOpenApiSourceKey, } from './mint-config/collectOpenApiOverlays.js';
+export { overlayDocumentSchema, overlayActionSchema, overlayInfoSchema, isOverlayDocument, parseOverlayDocument, safeParseOverlayDocument, } from './openapi/overlay.js';
 export { convertMintDecoratedNavToDocsDecoratedNav } from './mint-config/upgrades/convertMintDecoratedNavToDocsDecoratedNav.js';
 export const mintConfigJsonSchema = zodToJsonSchema(mintConfigSchema, 'Schema');
 export const docsConfigJsonSchema = zodToJsonSchema(docsConfigSchema, {

package/dist/mint-config/collectOpenApiOverlays.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Normalized OpenAPI source -> ordered explicit overlay refs from docs.json.
+ * An empty array means "no overlays, including auto-discovered ones".
+ */
+export type ExplicitOverlayConfig = Map<string, string[]>;
+/** Canonical source key: URLs unchanged, relative paths normalized without leading slash. */
+export declare function normalizeOpenApiSourceKey(source: string): string;
+/**
+ * Walks every `openapi` entry in a (possibly unvalidated) docs or mint config and
+ * returns the explicit overlay lists per normalized source. Throws when the same
+ * source is configured with two different lists.
+ */
+export declare function collectOpenApiOverlayConfig(docsConfig: unknown): ExplicitOverlayConfig;

package/dist/mint-config/collectOpenApiOverlays.js

@@ -0,0 +1,73 @@
+import { isAbsoluteUrl } from './isAbsoluteUrl.js';
+import { extractOpenApiEntries, } from './schemas/v2/properties/reusable/openapi.js';
+import { normalizeRelativePath } from './transforms/normalizeRelativePath.js';
+/** Canonical source key: URLs unchanged, relative paths normalized without leading slash. */
+export function normalizeOpenApiSourceKey(source) {
+    if (isAbsoluteUrl(source))
+        return source;
+    return normalizeRelativePath(source);
+}
+function isOpenApiConfigLike(value) {
+    if (typeof value === 'string')
+        return true;
+    if (Array.isArray(value)) {
+        return value.every((entry) => typeof entry === 'string' ||
+            (typeof entry === 'object' &&
+                entry !== null &&
+                'source' in entry &&
+                typeof entry.source === 'string'));
+    }
+    return (typeof value === 'object' &&
+        value !== null &&
+        'source' in value &&
+        typeof value.source === 'string');
+}
+function collectEntriesDeep(value, acc, seen) {
+    if (value === null || typeof value !== 'object')
+        return;
+    if (seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectEntriesDeep(item, acc, seen);
+        }
+        return;
+    }
+    const record = Object.fromEntries(Object.entries(value));
+    if ('openapi' in record && isOpenApiConfigLike(record.openapi)) {
+        acc.push(...extractOpenApiEntries(record.openapi));
+    }
+    for (const [key, child] of Object.entries(record)) {
+        if (key === 'openapi')
+            continue;
+        collectEntriesDeep(child, acc, seen);
+    }
+}
+/**
+ * Walks every `openapi` entry in a (possibly unvalidated) docs or mint config and
+ * returns the explicit overlay lists per normalized source. Throws when the same
+ * source is configured with two different lists.
+ */
+export function collectOpenApiOverlayConfig(docsConfig) {
+    const entries = [];
+    const seen = new Set();
+    collectEntriesDeep(docsConfig, entries, seen);
+    const explicit = new Map();
+    for (const entry of entries) {
+        if (entry.overlays == undefined)
+            continue;
+        // Collection runs on raw config before schema validation, so apply the same
+        // whitespace trimming the public openapi schema applies to these strings, and
+        // canonicalize refs so equivalent paths (overlays/a.yaml vs ./overlays/a.yaml)
+        // do not register as conflicting lists.
+        const overlays = entry.overlays.map((overlay) => normalizeOpenApiSourceKey(overlay.trim()));
+        const key = normalizeOpenApiSourceKey(entry.source.trim());
+        const existing = explicit.get(key);
+        if (existing != undefined && JSON.stringify(existing) !== JSON.stringify(overlays)) {
+            throw new Error(`OpenAPI source ${entry.source} is configured with conflicting overlay lists in docs.json: [${existing.join(', ')}] and [${overlays.join(', ')}]. Use the same overlays everywhere the source is referenced.`);
+        }
+        explicit.set(key, overlays);
+    }
+    return explicit;
+}