@mintlify/prebuild 1.0.1284 → 1.0.1286

package/dist/prebuild/categorizeFilePaths.d.ts

@@ -1,16 +1,23 @@
-import { AsyncAPIFile } from '@mintlify/common';
+import { AsyncAPIFile, type DiscoveredOverlay, type OverlayRegistry } from '@mintlify/common';
 import { OpenApiFile } from '@mintlify/models';
+import { type ExplicitOverlayConfig } from '@mintlify/validation';
 import type { InvalidSpecFile } from './invalidSpecFiles.js';
 export type PageScan = {
     frontmatter: string;
     rssCandidate: boolean;
 };
-export declare const categorizeFilePaths: (contentDirectoryPath: string, mintIgnore?: string[], disableOpenApi?: boolean, lazyPages?: boolean) => Promise<{
+export type CategorizeOverlayOptions = {
+    explicitOverlays?: ExplicitOverlayConfig;
+    localSchema?: boolean;
+};
+export declare const categorizeFilePaths: (contentDirectoryPath: string, mintIgnore?: string[], disableOpenApi?: boolean, lazyPages?: boolean, overlayOptions?: CategorizeOverlayOptions) => Promise<{
     contentFilenames: string[];
     staticFilenames: string[];
     openApiFiles: OpenApiFile[];
     asyncApiFiles: AsyncAPIFile[];
     invalidSpecFiles: InvalidSpecFile[];
+    overlayFiles: DiscoveredOverlay[];
+    overlayRegistry: OverlayRegistry;
     snippets: string[];
     snippetsV2: string[];
     fileImportsMap: Map<string, Set<string>>;

package/dist/prebuild/categorizeFilePaths.js

@@ -1,4 +1,5 @@
-import { validate, validateAsyncApi, extractImportSources, getFileCategory, isSnippetExtension, getAST, resolveImportPath, } from '@mintlify/common';
+import { validate, validateAsyncApi, applyOverlays, createOverlayRegistry, extractImportSources, getFileCategory, isSnippetExtension, getAST, parseLoadedOverlayDocument, resolveExtends, resolveOverlaysForSpec, normalizeOverlayKey, resolveImportPath, } from '@mintlify/common';
+import { isOverlayDocument, validatePathWithinCwd, } from '@mintlify/validation';
 import { readFile } from 'fs/promises';
 import yaml from 'js-yaml';
 import * as path from 'path';
@@ -61,7 +62,7 @@ const getImportSources = (content, filePath) => {
         return sources;
     }
 };
-export const categorizeFilePaths = async (contentDirectoryPath, mintIgnore = [], disableOpenApi, lazyPages) => {
+export const categorizeFilePaths = async (contentDirectoryPath, mintIgnore = [], disableOpenApi, lazyPages, overlayOptions) => {
     const allFilenames = [];
     for await (const filename of getFileList(contentDirectoryPath, contentDirectoryPath, mintIgnore)) {
         allFilenames.push(filename);
@@ -140,6 +141,10 @@ export const categorizeFilePaths = async (contentDirectoryPath, mintIgnore = [],
     const openApiFiles = [];
     const asyncApiFiles = [];
     const invalidSpecFiles = [];
+    const overlayFiles = [];
+    const openApiCandidates = [];
+    // Overlays can only be resolved once every file is known, so OpenAPI candidates are
+    // buffered and processed after the walk.
     for (const { filename, extension } of nonMdxFiles) {
         switch (extension) {
             case 'json':
@@ -161,27 +166,32 @@ export const categorizeFilePaths = async (contentDirectoryPath, mintIgnore = [],
                 }
                 if (!obj || typeof obj !== 'object')
                     break;
-                const isOpenApi = Object.keys(obj).includes('openapi');
-                const isAsyncApi = Object.keys(obj).includes('asyncapi');
-                const fileName = path.parse(filename).name;
-                if (isOpenApi && !disableOpenApi) {
+                if (isOverlayDocument(obj)) {
+                    const location = normalizeOverlayKey(filename);
                     try {
-                        const { schema: openApiDocument } = await validate(obj);
-                        if (openApiDocument) {
-                            openApiFiles.push({
-                                filename: fileName,
-                                spec: obj,
-                                originalFileLocation: filename,
-                            });
-                        }
+                        const document = parseLoadedOverlayDocument(obj, location);
+                        overlayFiles.push({
+                            location,
+                            document,
+                            resolvedExtends: document.extends == undefined
+                                ? undefined
+                                : resolveExtends(location, document.extends),
+                        });
                     }
                     catch (error) {
                         invalidSpecFiles.push({
                             originalFileLocation: filename,
                             reason: error instanceof Error ? error.message : String(error),
-                            kind: 'openapi',
+                            kind: 'overlay',
                         });
                     }
+                    break;
+                }
+                const isOpenApi = Object.keys(obj).includes('openapi');
+                const isAsyncApi = Object.keys(obj).includes('asyncapi');
+                const fileName = path.parse(filename).name;
+                if (isOpenApi && !disableOpenApi) {
+                    openApiCandidates.push({ filename, fileName, obj, str });
                 }
                 if (isAsyncApi) {
                     try {
@@ -207,12 +217,48 @@ export const categorizeFilePaths = async (contentDirectoryPath, mintIgnore = [],
                 staticFilenames.push(filename);
         }
     }
+    const overlayRegistry = createOverlayRegistry({
+        explicit: overlayOptions?.explicitOverlays,
+        discovered: overlayFiles,
+        localSchema: overlayOptions?.localSchema,
+        loadLocalDocument: async (normalizedPath) => {
+            const { resolvedPath } = validatePathWithinCwd(normalizedPath, contentDirectoryPath);
+            const contents = await readFile(resolvedPath, 'utf8');
+            return yaml.load(contents);
+        },
+    });
+    for (const { filename, fileName, obj } of openApiCandidates) {
+        try {
+            const overlays = await resolveOverlaysForSpec(overlayRegistry, filename);
+            const overlaid = overlays.length > 0 ? applyOverlays(obj, overlays) : obj;
+            if (overlaid == undefined || typeof overlaid !== 'object') {
+                throw new Error('Applying overlays produced an invalid OpenAPI document');
+            }
+            const { schema: openApiDocument } = await validate(overlaid);
+            if (openApiDocument) {
+                openApiFiles.push({
+                    filename: fileName,
+                    spec: overlaid,
+                    originalFileLocation: filename,
+                });
+            }
+        }
+        catch (error) {
+            invalidSpecFiles.push({
+                originalFileLocation: filename,
+                reason: error instanceof Error ? error.message : String(error),
+                kind: 'openapi',
+            });
+        }
+    }
     return {
         contentFilenames,
         staticFilenames,
         openApiFiles,
         asyncApiFiles,
         invalidSpecFiles,
+        overlayFiles,
+        overlayRegistry,
         snippets,
         snippetsV2,
         fileImportsMap,

package/dist/prebuild/discoverOverlayFiles.d.ts

@@ -0,0 +1,12 @@
+import { type DiscoveredOverlay, type OverlayRegistry } from '@mintlify/common';
+import { type ExplicitOverlayConfig } from '@mintlify/validation';
+/** Walks a docs directory and returns every valid OpenAPI Overlay document. */
+export declare const discoverOverlayFiles: (contentDirectoryPath: string, mintIgnore?: string[]) => Promise<DiscoveredOverlay[]>;
+/** Builds a filesystem-backed overlay registry for a docs directory. */
+export declare const buildOverlayRegistryForDirectory: (contentDirectoryPath: string, { explicitOverlays, mintIgnore, localSchema, fetchRemoteDocument, }?: {
+    explicitOverlays?: ExplicitOverlayConfig;
+    mintIgnore?: string[];
+    localSchema?: boolean;
+    /** SSRF-safe fetch override for overlay URLs; supplied by server environments. */
+    fetchRemoteDocument?: (url: string) => Promise<unknown>;
+}) => Promise<OverlayRegistry>;

package/dist/prebuild/discoverOverlayFiles.js

@@ -0,0 +1,56 @@
+import { createOverlayRegistry, normalizeOverlayKey, parseLoadedOverlayDocument, resolveExtends, } from '@mintlify/common';
+import { isOverlayDocument, validatePathWithinCwd, } from '@mintlify/validation';
+import { readFile } from 'fs/promises';
+import yaml from 'js-yaml';
+import * as path from 'path';
+import { getFileList } from '../fs/index.js';
+import { getFileExtension } from '../utils.js';
+import { addWarning } from './warnings.js';
+/** Walks a docs directory and returns every valid OpenAPI Overlay document. */
+export const discoverOverlayFiles = async (contentDirectoryPath, mintIgnore = []) => {
+    const overlayFiles = [];
+    for await (const filename of getFileList(contentDirectoryPath, contentDirectoryPath, mintIgnore)) {
+        const extension = getFileExtension(filename);
+        if (extension !== 'json' && extension !== 'yaml' && extension !== 'yml')
+            continue;
+        let obj;
+        try {
+            obj = yaml.load(await readFile(path.join(contentDirectoryPath, filename), 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!isOverlayDocument(obj))
+            continue;
+        const location = normalizeOverlayKey(filename);
+        try {
+            const document = parseLoadedOverlayDocument(obj, location);
+            overlayFiles.push({
+                location,
+                document,
+                resolvedExtends: document.extends == undefined ? undefined : resolveExtends(location, document.extends),
+            });
+        }
+        catch (error) {
+            addWarning({
+                type: 'openapi',
+                message: `Error validating OpenAPI Overlay file ${filename}: ${error}`,
+            });
+        }
+    }
+    return overlayFiles;
+};
+/** Builds a filesystem-backed overlay registry for a docs directory. */
+export const buildOverlayRegistryForDirectory = async (contentDirectoryPath, { explicitOverlays, mintIgnore, localSchema, fetchRemoteDocument, } = {}) => {
+    const discovered = await discoverOverlayFiles(contentDirectoryPath, mintIgnore);
+    return createOverlayRegistry({
+        explicit: explicitOverlays,
+        discovered,
+        fetchRemoteDocument,
+        localSchema,
+        loadLocalDocument: async (normalizedPath) => {
+            const { resolvedPath } = validatePathWithinCwd(normalizedPath, contentDirectoryPath);
+            return yaml.load(await readFile(resolvedPath, 'utf8'));
+        },
+    });
+};

package/dist/prebuild/getOpenApiFiles.d.ts

@@ -1,6 +1,11 @@
 import { OpenApiFile } from '@mintlify/models';
+import { type ExplicitOverlayConfig } from '@mintlify/validation';
 export interface GetOpenApiFilesOptions {
     mintIgnore?: string[];
     disableOpenApi?: boolean;
+    explicitOverlays?: ExplicitOverlayConfig;
+    localSchema?: boolean;
+    /** SSRF-safe fetch override for overlay URLs; supplied by server environments. */
+    fetchRemoteDocument?: (url: string) => Promise<unknown>;
 }
-export declare const getOpenApiFiles: (contentDirectoryPath: string, { mintIgnore, disableOpenApi }?: GetOpenApiFilesOptions) => Promise<OpenApiFile[]>;
+export declare const getOpenApiFiles: (contentDirectoryPath: string, { mintIgnore, disableOpenApi, explicitOverlays, localSchema, fetchRemoteDocument, }?: GetOpenApiFilesOptions) => Promise<OpenApiFile[]>;

package/dist/prebuild/getOpenApiFiles.js

@@ -1,15 +1,18 @@
-import { validate } from '@mintlify/common';
+import { applyOverlays, createOverlayRegistry, normalizeOverlayKey, parseLoadedOverlayDocument, resolveExtends, resolveOverlaysForSpec, validate, } from '@mintlify/common';
+import { isOverlayDocument, validatePathWithinCwd, } from '@mintlify/validation';
 import { readFile } from 'fs/promises';
 import yaml from 'js-yaml';
 import * as path from 'path';
 import { getFileList } from '../fs/index.js';
 import { getFileExtension } from '../utils.js';
 import { addWarning } from './warnings.js';
-export const getOpenApiFiles = async (contentDirectoryPath, { mintIgnore = [], disableOpenApi = false } = {}) => {
+export const getOpenApiFiles = async (contentDirectoryPath, { mintIgnore = [], disableOpenApi = false, explicitOverlays, localSchema, fetchRemoteDocument, } = {}) => {
     if (disableOpenApi)
         return [];
     const allFiles = getFileList(contentDirectoryPath, contentDirectoryPath, mintIgnore);
     const openApiFiles = [];
+    const overlayFiles = [];
+    const candidates = [];
     for await (const filename of allFiles) {
         const extension = getFileExtension(filename);
         if (extension !== 'json' && extension !== 'yaml' && extension !== 'yml')
@@ -19,14 +22,51 @@ export const getOpenApiFiles = async (contentDirectoryPath, { mintIgnore = [], d
         const obj = yaml.load(str);
         if (!obj || typeof obj !== 'object')
             continue;
+        if (isOverlayDocument(obj)) {
+            const location = normalizeOverlayKey(filename);
+            try {
+                const document = parseLoadedOverlayDocument(obj, location);
+                overlayFiles.push({
+                    location,
+                    document,
+                    resolvedExtends: document.extends == undefined ? undefined : resolveExtends(location, document.extends),
+                });
+            }
+            catch (error) {
+                addWarning({
+                    type: 'openapi',
+                    message: `Error validating OpenAPI Overlay file ${filename}: ${error}`,
+                });
+            }
+            continue;
+        }
         if (!Object.keys(obj).includes('openapi'))
             continue;
+        candidates.push({ filename, obj });
+    }
+    const overlayRegistry = createOverlayRegistry({
+        explicit: explicitOverlays,
+        discovered: overlayFiles,
+        localSchema,
+        fetchRemoteDocument,
+        loadLocalDocument: async (normalizedPath) => {
+            const { resolvedPath } = validatePathWithinCwd(normalizedPath, contentDirectoryPath);
+            const contents = await readFile(resolvedPath, 'utf8');
+            return yaml.load(contents);
+        },
+    });
+    for (const { filename, obj } of candidates) {
         try {
-            const { schema: openApiDocument } = await validate(obj);
+            const overlays = await resolveOverlaysForSpec(overlayRegistry, filename);
+            const overlaid = overlays.length > 0 ? applyOverlays(obj, overlays) : obj;
+            if (overlaid == undefined || typeof overlaid !== 'object') {
+                throw new Error('Applying overlays produced an invalid OpenAPI document');
+            }
+            const { schema: openApiDocument } = await validate(overlaid);
             if (openApiDocument) {
                 openApiFiles.push({
                     filename: path.parse(filename).name,
-                    spec: obj,
+                    spec: overlaid,
                     originalFileLocation: filename,
                 });
             }

package/dist/prebuild/index.d.ts

@@ -1,3 +1,10 @@
+import { type ExplicitOverlayConfig } from '@mintlify/validation';
+/**
+ * Collects explicit overlay config from the raw docs.json/mint.json, resolving config
+ * $refs first so overlays declared in referenced fragments are included. Unreadable
+ * config only warns (regular validation reports it); conflicting overlay lists throw.
+ */
+export declare const readExplicitOverlayConfig: (configPath: string | null | undefined) => Promise<ExplicitOverlayConfig | undefined>;
 export interface PrebuildResult {
     fileImportsMap: Map<string, Set<string>>;
 }
@@ -11,6 +18,7 @@ export declare const prebuild: (contentDirectoryPath: string, { localSchema, gro
     lazyPages?: boolean;
 }) => Promise<PrebuildResult | undefined>;
 export * from './categorizeFilePaths.js';
+export * from './discoverOverlayFiles.js';
 export * from './getOpenApiFiles.js';
 export * from './invalidSpecFiles.js';
 export * from '../createPage/index.js';

package/dist/prebuild/index.js

@@ -1,8 +1,39 @@
+import { collectOpenApiOverlayConfig } from '@mintlify/validation';
+import { readFile } from 'fs/promises';
+import * as path from 'path';
 import { getConfigPath, getMintIgnore } from '../utils.js';
 import { categorizeFilePaths } from './categorizeFilePaths.js';
 import { warnInvalidSpecFiles } from './invalidSpecFiles.js';
+import { resolveFileRefs } from './resolveRefs.js';
 import { update } from './update/index.js';
-import { clearWarnings, checkStrictMode } from './warnings.js';
+import { addWarning, clearWarnings, checkStrictMode } from './warnings.js';
+/**
+ * Collects explicit overlay config from the raw docs.json/mint.json, resolving config
+ * $refs first so overlays declared in referenced fragments are included. Unreadable
+ * config only warns (regular validation reports it); conflicting overlay lists throw.
+ */
+export const readExplicitOverlayConfig = async (configPath) => {
+    if (configPath == null)
+        return undefined;
+    let rawConfig;
+    try {
+        rawConfig = JSON.parse(await readFile(configPath, 'utf8'));
+    }
+    catch (error) {
+        addWarning({
+            type: 'openapi',
+            message: `Error reading OpenAPI overlay configuration from ${configPath}: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        return undefined;
+    }
+    try {
+        rawConfig = (await resolveFileRefs(rawConfig, path.dirname(configPath))).resolved;
+    }
+    catch {
+        // Broken $refs are reported by regular config validation; collect from the root file.
+    }
+    return collectOpenApiOverlayConfig(rawConfig);
+};
 export const prebuild = async (contentDirectoryPath, { localSchema, groups, disableOpenApi, disablePrefetch, strict, allowSourceRefs, lazyPages, } = {}) => {
     if (process.env.IS_MULTI_TENANT === 'true') {
         console.log('Skipping prebuild in multi-tenant mode.');
@@ -16,7 +47,11 @@ export const prebuild = async (contentDirectoryPath, { localSchema, groups, disa
         throw Error('must be run in a directory where a docs.json file exists.');
     }
     const mintIgnore = await getMintIgnore(contentDirectoryPath);
-    const { contentFilenames, staticFilenames, openApiFiles, asyncApiFiles, invalidSpecFiles, snippets, snippetsV2, fileImportsMap, pageScans, } = await categorizeFilePaths(contentDirectoryPath, mintIgnore, disableOpenApi, lazyPages);
+    const explicitOverlays = await readExplicitOverlayConfig(docsConfigPath ?? mintConfigPath);
+    const { contentFilenames, staticFilenames, openApiFiles, asyncApiFiles, invalidSpecFiles, overlayRegistry, snippets, snippetsV2, fileImportsMap, pageScans, } = await categorizeFilePaths(contentDirectoryPath, mintIgnore, disableOpenApi, lazyPages, {
+        explicitOverlays,
+        localSchema,
+    });
     await update({
         contentDirectoryPath,
         staticFilenames,
@@ -37,6 +72,7 @@ export const prebuild = async (contentDirectoryPath, { localSchema, groups, disa
         lazyPages,
         pageScans,
         fileImportsMap,
+        overlayRegistry,
     });
     // Deferred until after update so files that fail the build don't also warn
     warnInvalidSpecFiles(invalidSpecFiles);
@@ -45,6 +81,7 @@ export const prebuild = async (contentDirectoryPath, { localSchema, groups, disa
     return { fileImportsMap };
 };
 export * from './categorizeFilePaths.js';
+export * from './discoverOverlayFiles.js';
 export * from './getOpenApiFiles.js';
 export * from './invalidSpecFiles.js';
 export * from '../createPage/index.js';

package/dist/prebuild/invalidSpecFiles.d.ts

@@ -1,7 +1,7 @@
 export type InvalidSpecFile = {
     originalFileLocation: string;
     reason: string;
-    kind: 'openapi' | 'asyncapi' | 'syntax';
+    kind: 'openapi' | 'asyncapi' | 'syntax' | 'overlay';
 };
 export declare const findInvalidSpecFile: (invalidSpecFiles: InvalidSpecFile[] | undefined, reference: string) => InvalidSpecFile | undefined;
 export declare const warnInvalidSpecFiles: (invalidSpecFiles: InvalidSpecFile[] | undefined) => void;

package/dist/prebuild/invalidSpecFiles.js

@@ -7,7 +7,11 @@ export const warnInvalidSpecFiles = (invalidSpecFiles) => {
             type: 'openapi',
             message: file.kind === 'syntax'
                 ? `Error parsing ${file.originalFileLocation}: ${file.reason}`
-                : `Error validating ${file.kind === 'asyncapi' ? 'AsyncAPI' : 'OpenAPI'} file ${file.originalFileLocation}: ${file.reason}`,
+                : `Error validating ${file.kind === 'asyncapi'
+                    ? 'AsyncAPI'
+                    : file.kind === 'overlay'
+                        ? 'OpenAPI Overlay'
+                        : 'OpenAPI'} file ${file.originalFileLocation}: ${file.reason}`,
         });
     }
 };