@mintlify/prebuild 1.0.1122 → 1.0.1124

package/dist/prebuild/index.d.ts

@@ -1,11 +1,12 @@
 export interface PrebuildResult {
     fileImportsMap: Map<string, Set<string>>;
 }
-export declare const prebuild: (contentDirectoryPath: string, { localSchema, groups, disableOpenApi, strict, }?: {
+export declare const prebuild: (contentDirectoryPath: string, { localSchema, groups, disableOpenApi, strict, allowSourceRefs, }?: {
     localSchema?: boolean;
     groups?: string[];
     disableOpenApi?: boolean;
     strict?: boolean;
+    allowSourceRefs?: boolean;
 }) => Promise<PrebuildResult | undefined>;
 export * from './categorizeFilePaths.js';
 export * from './getOpenApiFiles.js';

package/dist/prebuild/index.js

@@ -3,7 +3,7 @@ import { categorizeFilePaths } from './categorizeFilePaths.js';
 import { warnInvalidSpecFiles } from './invalidSpecFiles.js';
 import { update } from './update/index.js';
 import { clearWarnings, checkStrictMode } from './warnings.js';
-export const prebuild = async (contentDirectoryPath, { localSchema, groups, disableOpenApi, strict, } = {}) => {
+export const prebuild = async (contentDirectoryPath, { localSchema, groups, disableOpenApi, strict, allowSourceRefs, } = {}) => {
     if (process.env.IS_MULTI_TENANT === 'true') {
         console.log('Skipping prebuild in multi-tenant mode.');
         return;
@@ -32,6 +32,7 @@ export const prebuild = async (contentDirectoryPath, { localSchema, groups, disa
         disableOpenApi,
         strict,
         invalidSpecFiles,
+        allowSourceRefs,
     });
     // Deferred until after update so files that fail the build don't also warn
     warnInvalidSpecFiles(invalidSpecFiles);

package/dist/prebuild/update/ConfigUpdater.d.ts

@@ -1,10 +1,13 @@
 import { ConfigType } from '@mintlify/models';
+type GetConfigOptions = {
+    allowSourceRefs?: boolean;
+};
 export declare class ConfigUpdater<T> {
     private type;
     constructor(type: ConfigType);
     getConfigType(): "mint" | "docs";
-    getConfig(configPath: string, strict?: boolean, contentDirectoryPath?: string, onError?: (message: string) => void): Promise<T>;
-    validateConfigJsonString: (configContents: string, strict?: boolean, onError?: (message: string) => void) => Promise<{
+    getConfig(configPath: string, strict?: boolean, contentDirectoryPath?: string, onError?: (message: string) => void, options?: GetConfigOptions): Promise<T>;
+    validateConfigJsonString: (configContents: string, strict?: boolean, onError?: (message: string) => void, options?: GetConfigOptions) => Promise<{
         data: T;
         warnings: import("zod").ZodIssue[];
         success: true;
@@ -3469,3 +3472,4 @@ export declare const DocsConfigUpdater: ConfigUpdater<{
         instructions?: string | string[] | undefined;
     } | undefined;
 }>;
+export {};

package/dist/prebuild/update/ConfigUpdater.js

@@ -1,18 +1,74 @@
-import { validateMintConfig, validateDocsConfig, formatIssue, } from '@mintlify/validation';
+import { validateMintConfig, validateDocsConfig, validateSourceRefDocsConfig, formatIssue, } from '@mintlify/validation';
 import Chalk from 'chalk';
 import { promises as _promises } from 'fs';
 import { outputFile } from 'fs-extra';
 import { join } from 'path';
 import { resolveFileRefs } from '../resolveRefs.js';
 const { readFile } = _promises;
+const strippedSourceRef = Symbol('strippedSourceRef');
+function isSourceRef(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value.sourceRef === 'string');
+}
+function hasSourceRefs(value) {
+    if (Array.isArray(value)) {
+        return value.some(hasSourceRefs);
+    }
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if (isSourceRef(value)) {
+        return true;
+    }
+    return Object.values(value).some(hasSourceRefs);
+}
+function stripSourceRefsForLocalPreview(value) {
+    if (isSourceRef(value)) {
+        return strippedSourceRef;
+    }
+    if (Array.isArray(value)) {
+        return value
+            .map((entry) => stripSourceRefsForLocalPreview(entry))
+            .filter((entry) => entry !== strippedSourceRef);
+    }
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value)
+        .map(([key, entry]) => [key, stripSourceRefsForLocalPreview(entry)])
+        .filter(([, entry]) => entry !== strippedSourceRef));
+}
 export class ConfigUpdater {
     constructor(type) {
-        this.validateConfigJsonString = async (configContents, strict, onError) => {
+        this.validateConfigJsonString = async (configContents, strict, onError, options = {}) => {
             const configObj = this.parseConfigJson(configContents, onError);
-            return this.validateConfigObj(configObj, strict, onError);
+            return this.validateConfigObj(configObj, strict, onError, options);
         };
-        this.validateConfigObj = async (configObj, strict, onError) => {
-            const validationResults = this.type === 'mint' ? validateMintConfig(configObj) : validateDocsConfig(configObj);
+        this.validateConfigObj = async (configObj, strict, onError, options = {}) => {
+            const hasSourceRefEntries = hasSourceRefs(configObj);
+            const allowSourceRefs = this.type === 'docs' && options.allowSourceRefs;
+            if (allowSourceRefs && hasSourceRefEntries) {
+                const sourceRefValidation = validateSourceRefDocsConfig(configObj);
+                if (!sourceRefValidation.success) {
+                    const errorMsg = `🚨 Invalid ${this.type}.json:`;
+                    const issues = sourceRefValidation.error.issues.map((issue) => formatIssue(issue));
+                    if (onError) {
+                        onError(errorMsg);
+                        issues.forEach((issue) => onError(issue));
+                    }
+                    else {
+                        console.error(Chalk.red(errorMsg));
+                        issues.forEach((issue) => console.error(Chalk.red(issue)));
+                    }
+                    throw Error();
+                }
+            }
+            const validationInput = allowSourceRefs && hasSourceRefEntries
+                ? stripSourceRefsForLocalPreview(configObj)
+                : configObj;
+            const validationResults = this.type === 'mint' ? validateMintConfig(configObj) : validateDocsConfig(validationInput);
             if (!validationResults.success) {
                 const errorMsg = `🚨 Invalid ${this.type}.json:`;
                 const issues = validationResults.error.issues.map((issue) => formatIssue(issue));
@@ -26,6 +82,15 @@ export class ConfigUpdater {
                 }
                 throw Error();
             }
+            if (this.type === 'docs' && options.allowSourceRefs && hasSourceRefEntries) {
+                const warnMsg = '⚠️ sourceRef entries are resolved during multi-repository deployments and are omitted from local preview.';
+                if (onError) {
+                    onError(warnMsg);
+                }
+                else {
+                    console.warn(Chalk.yellow(warnMsg));
+                }
+            }
             if ('warnings' in validationResults && validationResults.warnings.length > 0) {
                 const warnMsg = `⚠️ Warnings found in ${this.type}.json:`;
                 const warnings = validationResults.warnings.map((issue) => formatIssue(issue));
@@ -98,7 +163,7 @@ export class ConfigUpdater {
     getConfigType() {
         return this.type;
     }
-    async getConfig(configPath, strict, contentDirectoryPath, onError) {
+    async getConfig(configPath, strict, contentDirectoryPath, onError, options = {}) {
         const configContents = await this.readConfigFile(configPath);
         const configObj = this.parseConfigJson(configContents, onError);
         let resolvedObj = configObj;
@@ -115,7 +180,7 @@ export class ConfigUpdater {
                 throw Error(msg);
             }
         }
-        const { data: config } = await this.validateConfigObj(resolvedObj, strict, onError);
+        const { data: config } = await this.validateConfigObj(resolvedObj, strict, onError, options);
         return config;
     }
 }

package/dist/prebuild/update/docsConfig/index.d.ts

@@ -2,7 +2,7 @@ import { AsyncAPIFile } from '@mintlify/common';
 import { OpenApiFile, DecoratedNavigationPage } from '@mintlify/models';
 import { DocsConfig } from '@mintlify/validation';
 import type { InvalidSpecFile } from '../../invalidSpecFiles.js';
-export declare function updateDocsConfigFile({ contentDirectoryPath, openApiFiles, asyncApiFiles, docsConfig, localSchema, disableOpenApi, strict, invalidSpecFiles, }: {
+export declare function updateDocsConfigFile({ contentDirectoryPath, openApiFiles, asyncApiFiles, docsConfig, localSchema, disableOpenApi, strict, invalidSpecFiles, allowSourceRefs, }: {
     contentDirectoryPath: string;
     openApiFiles: OpenApiFile[];
     asyncApiFiles: AsyncAPIFile[];
@@ -11,6 +11,7 @@ export declare function updateDocsConfigFile({ contentDirectoryPath, openApiFile
     disableOpenApi?: boolean;
     strict?: boolean;
     invalidSpecFiles?: InvalidSpecFile[];
+    allowSourceRefs?: boolean;
 }): Promise<{
     docsConfig: DocsConfig;
     pagesAcc: Record<string, DecoratedNavigationPage>;

package/dist/prebuild/update/docsConfig/index.js

@@ -4,13 +4,15 @@ import { generateAsyncApiDivisions } from './generateAsyncApiDivisions.js';
 import { generateOpenApiDivisions } from './generateOpenApiDivisions.js';
 import { getCustomLanguages } from './getCustomLanguages.js';
 const NOT_CORRECT_PATH_ERROR = 'must be run in a directory where a docs.json file exists.';
-export async function updateDocsConfigFile({ contentDirectoryPath, openApiFiles, asyncApiFiles, docsConfig, localSchema, disableOpenApi, strict, invalidSpecFiles, }) {
+export async function updateDocsConfigFile({ contentDirectoryPath, openApiFiles, asyncApiFiles, docsConfig, localSchema, disableOpenApi, strict, invalidSpecFiles, allowSourceRefs, }) {
     const configPath = await getConfigPath(contentDirectoryPath, 'docs');
     if (configPath == null && docsConfig == null) {
         throw Error(NOT_CORRECT_PATH_ERROR);
     }
     if (docsConfig == null && configPath) {
-        docsConfig = await DocsConfigUpdater.getConfig(configPath, strict, contentDirectoryPath);
+        docsConfig = await DocsConfigUpdater.getConfig(configPath, strict, contentDirectoryPath, undefined, {
+            allowSourceRefs,
+        });
     }
     if (docsConfig == null) {
         throw Error(NOT_CORRECT_PATH_ERROR);

package/dist/prebuild/update/index.d.ts

@@ -17,8 +17,9 @@ type UpdateArgs = {
     disableOpenApi?: boolean;
     strict?: boolean;
     invalidSpecFiles?: InvalidSpecFile[];
+    allowSourceRefs?: boolean;
 };
-export declare const update: ({ contentDirectoryPath, staticFilenames, openApiFiles, asyncApiFiles, contentFilenames, snippets, snippetV2Filenames, docsConfigPath, localSchema, groups, mintIgnore, disableOpenApi, strict, invalidSpecFiles, }: UpdateArgs) => Promise<{
+export declare const update: ({ contentDirectoryPath, staticFilenames, openApiFiles, asyncApiFiles, contentFilenames, snippets, snippetV2Filenames, docsConfigPath, localSchema, groups, mintIgnore, disableOpenApi, strict, invalidSpecFiles, allowSourceRefs, }: UpdateArgs) => Promise<{
     name: string;
     $schema: string;
     theme: "mint";

package/dist/prebuild/update/index.js

@@ -12,7 +12,7 @@ import { writeAsyncApiFiles } from './write/writeAsyncApiFiles.js';
 import { writeFiles, writeFile } from './write/writeFiles.js';
 import { writeOpenApiData } from './write/writeOpenApiData.js';
 import { writeRssFiles } from './write/writeRssFiles.js';
-export const update = async ({ contentDirectoryPath, staticFilenames, openApiFiles, asyncApiFiles, contentFilenames, snippets, snippetV2Filenames, docsConfigPath, localSchema, groups, mintIgnore, disableOpenApi, strict, invalidSpecFiles, }) => {
+export const update = async ({ contentDirectoryPath, staticFilenames, openApiFiles, asyncApiFiles, contentFilenames, snippets, snippetV2Filenames, docsConfigPath, localSchema, groups, mintIgnore, disableOpenApi, strict, invalidSpecFiles, allowSourceRefs, }) => {
     const mintConfigResult = await updateMintConfigFile(contentDirectoryPath, openApiFiles, localSchema, strict, invalidSpecFiles);
     // we used the original mint config without openapi pages injected
     // because we will do it in `updateDocsConfigFile`, this will avoid duplicated openapi pages
@@ -26,6 +26,7 @@ export const update = async ({ contentDirectoryPath, staticFilenames, openApiFil
         disableOpenApi,
         strict,
         invalidSpecFiles,
+        allowSourceRefs,
     });
     const pagePromises = readPageContents({
         contentDirectoryPath,