@mintlify/prebuild 1.0.1335 → 1.0.1337

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

@@ -2,6 +2,7 @@ import { isSdkFrontmatterValue } from '@mintlify/common';
 import { type DecoratedNavigationPage, type ResolvedSdkTarget, type SdkTarget } from '@mintlify/models';
 import { type SdkFormat, type SdkReference } from '@mintlify/scraping';
 import type { DocsConfig } from '@mintlify/validation';
+import type { PageScan } from '../../categorizeFilePaths.js';
 import { type LoadRemoteFileOptions } from './loadRemoteGraphqlSdl.js';
 type SdkConfig = {
     format: SdkFormat;
@@ -48,7 +49,7 @@ export declare function composeSdkFrontmatterPage(args: {
     inherited?: SdkConfig;
 }): Promise<GeneratedSdkPage | undefined>;
 export { isSdkFrontmatterValue };
-export declare function readContainedMarkdown(contentRoot: string, slug: string): Promise<{
+export declare function readContainedMarkdown(contentRoot: string, slug: string, pageScans?: ReadonlyMap<string, PageScan>): Promise<{
     content: string;
     extension: '.mdx' | '.md';
 } | undefined>;

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

@@ -1,4 +1,4 @@
-import { isSdkFrontmatterValue, parseFrontmatter, parseSdkTargetFromMetadata, } from '@mintlify/common';
+import { isSdkFrontmatterValue, parseFrontmatter, parseSdkTargetFromMetadata, toPosixPath, } from '@mintlify/common';
 import { generateSdkReference, renderSdkTarget, } from '@mintlify/scraping';
 import { Unzip, UnzipInflate } from 'fflate';
 import fse from 'fs-extra';
@@ -296,7 +296,7 @@ function stripFrontmatter(content) {
     return content.slice(end + 4).replace(/^\n+/, '');
 }
 export { isSdkFrontmatterValue };
-export async function readContainedMarkdown(contentRoot, slug) {
+export async function readContainedMarkdown(contentRoot, slug, pageScans) {
     for (const extension of ['.mdx', '.md']) {
         const filePath = path.resolve(contentRoot, `${slug}${extension}`);
         const relativePath = path.relative(contentRoot, filePath);
@@ -314,7 +314,9 @@ export async function readContainedMarkdown(contentRoot, slug) {
             path.isAbsolute(realRelative)) {
             continue;
         }
-        return { content: await fse.readFile(realFilePath, 'utf8'), extension };
+        // Reuse cached headers only after validating the file's real path containment.
+        const frontmatter = pageScans?.get(`/${toPosixPath(relativePath)}`)?.frontmatter;
+        return { content: frontmatter ?? (await fse.readFile(realFilePath, 'utf8')), extension };
     }
     return undefined;
 }

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

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

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

@@ -1,60 +1,14 @@
-import { parseFrontmatter } from '@mintlify/common';
-import fse from 'fs-extra';
 import { getConfigPath } from '../../../utils.js';
 import { DocsConfigUpdater } from '../ConfigUpdater.js';
+import { scanSdkFrontmatterMetadata } from '../read/read-sdk-page-metadata.js';
 import { generateAsyncApiDivisions } from './generateAsyncApiDivisions.js';
 import { assertNoGeneratedRouteCollisions } from './generatedRouteCollisions.js';
 import { generateGraphqlDivisionsFromDocsConfig, loadGraphqlSdlSource, writeGraphqlArtifacts, } from './generateGraphqlDivisions.js';
 import { generateOpenApiDivisions } from './generateOpenApiDivisions.js';
-import { generateSdkDivisionsFromDocsConfig, loadSdkReferenceSource, readContainedMarkdown, writeSdkArtifacts, } from './generateSdkDivisions.js';
+import { generateSdkDivisionsFromDocsConfig, loadSdkReferenceSource, writeSdkArtifacts, } from './generateSdkDivisions.js';
 import { getCustomLanguages } from './getCustomLanguages.js';
 const NOT_CORRECT_PATH_ERROR = 'must be run in a directory where a docs.json file exists.';
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function collectNavigationPageSlugs(value, slugs = new Set()) {
-    if (typeof value === 'string') {
-        slugs.add(value.replace(/^\//, '').replace(/\.mdx?$/, ''));
-        return slugs;
-    }
-    if (Array.isArray(value)) {
-        value.forEach((entry) => collectNavigationPageSlugs(entry, slugs));
-        return slugs;
-    }
-    if (!isPlainObject(value))
-        return slugs;
-    if ('root' in value)
-        collectNavigationPageSlugs(value.root, slugs);
-    if ('pages' in value)
-        collectNavigationPageSlugs(value.pages, slugs);
-    if ('groups' in value)
-        collectNavigationPageSlugs(value.groups, slugs);
-    for (const key of ['tabs', 'anchors', 'dropdowns', 'versions', 'languages', 'products', 'menu']) {
-        if (key in value)
-            collectNavigationPageSlugs(value[key], slugs);
-    }
-    return slugs;
-}
-async function scanSdkFrontmatterMetadata(contentDirectoryPath, navigation) {
-    const contentRoot = await fse.realpath(contentDirectoryPath);
-    const metadataBySlug = {};
-    await Promise.all([...collectNavigationPageSlugs(navigation)].map(async (slug) => {
-        try {
-            const file = await readContainedMarkdown(contentRoot, slug);
-            if (file === undefined)
-                return;
-            const { attributes } = parseFrontmatter(file.content);
-            if (attributes.sdk !== undefined) {
-                metadataBySlug[slug] = { sdk: attributes.sdk };
-            }
-        }
-        catch {
-            // ignore unreadable/invalid frontmatter during scan
-        }
-    }));
-    return metadataBySlug;
-}
-export async function updateDocsConfigFile({ contentDirectoryPath, openApiFiles, asyncApiFiles, docsConfig, localSchema, disableOpenApi, strict, invalidSpecFiles, allowSourceRefs, overlayRegistry, }) {
+export async function updateDocsConfigFile({ contentDirectoryPath, openApiFiles, asyncApiFiles, docsConfig, localSchema, disableOpenApi, strict, invalidSpecFiles, allowSourceRefs, overlayRegistry, pageScans, }) {
     const configPath = await getConfigPath(contentDirectoryPath, 'docs');
     if (configPath == null && docsConfig == null) {
         throw Error(NOT_CORRECT_PATH_ERROR);
@@ -79,7 +33,7 @@ export async function updateDocsConfigFile({ contentDirectoryPath, openApiFiles,
             flushWrites: async () => { },
         };
     const { newDocsConfig: docsConfigWithAsyncApiPages, pagesAcc: pagesAccWithAsyncApiPages, asyncApiFiles: newAsyncApiFiles, flushWrites: flushAsyncApiWrites, } = await generateAsyncApiDivisions(docsConfigWithOpenApiPages, asyncApiFiles, undefined, localSchema, pagesAccWithGraphqlPages, true, true);
-    const pageMetadataBySlug = await scanSdkFrontmatterMetadata(contentDirectoryPath, docsConfigWithAsyncApiPages.navigation);
+    const pageMetadataBySlug = await scanSdkFrontmatterMetadata(contentDirectoryPath, docsConfigWithAsyncApiPages.navigation, pageScans);
     const sdkResult = await generateSdkDivisionsFromDocsConfig(docsConfigWithAsyncApiPages, (config) => loadSdkReferenceSource(config, contentDirectoryPath), { pageMetadataBySlug });
     const { newDocsConfig: docsConfigWithSdkPages, pagesAcc: pagesAccWithSdkPages } = sdkResult;
     const sdkRoutes = { label: 'SDK', pages: pagesAccWithSdkPages };

package/dist/prebuild/update/index.js

@@ -74,6 +74,7 @@ export const update = async ({ contentDirectoryPath, staticFilenames, openApiFil
         invalidSpecFiles,
         allowSourceRefs,
         overlayRegistry,
+        pageScans,
     });
     let contentFilenamesToParse = contentFilenames;
     if (lazyPages) {

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

@@ -1,7 +1,8 @@
 import type { DecoratedNavigationPage } from '@mintlify/models';
+export declare const createGeneratedGraphqlRouteIndex: (pagesAcc: Record<string, DecoratedNavigationPage>) => Map<string, string>;
 /**
  * When user MDX doesn't explicitly set title/description, preserve the
  * auto-generated values (e.g. from OpenAPI schemas) that already exist
  * in pagesAcc. Mutates pageMetadata and pagesAcc in place.
  */
-export declare const preserveAutoGeneratedMetadata: (contentStr: string, slug: string, pageMetadata: DecoratedNavigationPage, pagesAcc: Record<string, DecoratedNavigationPage>) => void;
+export declare const preserveAutoGeneratedMetadata: (contentStr: string, slug: string, pageMetadata: DecoratedNavigationPage, pagesAcc: Record<string, DecoratedNavigationPage>, graphqlRoutes?: Map<string, string>) => void;

package/dist/prebuild/update/preserveAutoGeneratedMetadata.js

@@ -1,14 +1,26 @@
 import { parseFrontmatter } from '@mintlify/common';
 import { getGeneratedRouteKey } from './docsConfig/generatedRouteCollisions.js';
+export const createGeneratedGraphqlRouteIndex = (pagesAcc) => {
+    const routes = new Map();
+    for (const [slug, metadata] of Object.entries(pagesAcc)) {
+        if (metadata.graphql != null) {
+            const routeKey = getGeneratedRouteKey(slug);
+            if (!routes.has(routeKey))
+                routes.set(routeKey, slug);
+        }
+    }
+    return routes;
+};
 /**
  * When user MDX doesn't explicitly set title/description, preserve the
  * auto-generated values (e.g. from OpenAPI schemas) that already exist
  * in pagesAcc. Mutates pageMetadata and pagesAcc in place.
  */
-export const preserveAutoGeneratedMetadata = (contentStr, slug, pageMetadata, pagesAcc) => {
-    const graphqlCollision = Object.entries(pagesAcc).find(([existingSlug, metadata]) => metadata.graphql != null && getGeneratedRouteKey(existingSlug) === getGeneratedRouteKey(slug));
-    if (graphqlCollision) {
-        throw new Error(`User page route "${slug}" collides with generated GraphQL route "${graphqlCollision[0]}"`);
+export const preserveAutoGeneratedMetadata = (contentStr, slug, pageMetadata, pagesAcc, graphqlRoutes = createGeneratedGraphqlRouteIndex(pagesAcc)) => {
+    const routeKey = getGeneratedRouteKey(slug);
+    const graphqlCollision = graphqlRoutes.get(routeKey);
+    if (graphqlCollision !== undefined) {
+        throw new Error(`User page route "${slug}" collides with generated GraphQL route "${graphqlCollision}"`);
     }
     const existing = pagesAcc[slug];
     if (existing) {
@@ -24,4 +36,6 @@ export const preserveAutoGeneratedMetadata = (contentStr, slug, pageMetadata, pa
         catch { }
     }
     pagesAcc[slug] = pageMetadata;
+    if (pageMetadata.graphql != null)
+        graphqlRoutes.set(routeKey, slug);
 };

package/dist/prebuild/update/read/read-page-metadata.js

@@ -1,7 +1,7 @@
 import { getDecoratedNavPageAndSlug, parseFrontmatter } from '@mintlify/common';
 import { promises as _promises } from 'fs';
 import { join } from 'path';
-import { preserveAutoGeneratedMetadata } from '../preserveAutoGeneratedMetadata.js';
+import { createGeneratedGraphqlRouteIndex, preserveAutoGeneratedMetadata, } from '../preserveAutoGeneratedMetadata.js';
 const { readFile } = _promises;
 const SCAN_CONCURRENCY = 16;
 const hasRssFrontmatter = (contentStr) => {
@@ -15,11 +15,12 @@ const hasRssFrontmatter = (contentStr) => {
 export const scanPageMetadata = async ({ contentDirectoryPath, openApiFiles, asyncApiFiles, contentFilenames, pagesAcc, pageScans, }) => {
     const rssCandidateFilenames = [];
     const queue = [...contentFilenames];
+    const graphqlRoutes = createGeneratedGraphqlRouteIndex(pagesAcc);
     const scanFile = async (filename) => {
         const scan = pageScans?.get(filename);
         const contentStr = scan?.frontmatter ?? (await readFile(join(contentDirectoryPath, filename), 'utf8'));
         const { slug, pageMetadata } = getDecoratedNavPageAndSlug(filename, contentStr, openApiFiles, asyncApiFiles);
-        preserveAutoGeneratedMetadata(contentStr, slug, pageMetadata, pagesAcc);
+        preserveAutoGeneratedMetadata(contentStr, slug, pageMetadata, pagesAcc, graphqlRoutes);
         const rssCandidate = scan
             ? scan.rssCandidate || hasRssFrontmatter(contentStr)
             : contentStr.includes('<Update') || hasRssFrontmatter(contentStr);

package/dist/prebuild/update/read/read-sdk-page-metadata.d.ts

@@ -0,0 +1,5 @@
+import type { DocsConfig } from '@mintlify/validation';
+import type { PageScan } from '../../categorizeFilePaths.js';
+export declare function scanSdkFrontmatterMetadata(contentDirectoryPath: string, navigation: DocsConfig['navigation'], pageScans?: ReadonlyMap<string, PageScan>): Promise<Record<string, {
+    sdk?: unknown;
+}>>;

package/dist/prebuild/update/read/read-sdk-page-metadata.js

@@ -0,0 +1,54 @@
+import { parseFrontmatter } from '@mintlify/common';
+import fse from 'fs-extra';
+import { readContainedMarkdown } from '../docsConfig/generateSdkDivisions.js';
+const SDK_SCAN_CONCURRENCY = 16;
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function collectNavigationPageSlugs(value, slugs = new Set()) {
+    if (typeof value === 'string') {
+        slugs.add(value.replace(/^\//, '').replace(/\.mdx?$/, ''));
+        return slugs;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry) => collectNavigationPageSlugs(entry, slugs));
+        return slugs;
+    }
+    if (!isPlainObject(value))
+        return slugs;
+    if ('root' in value)
+        collectNavigationPageSlugs(value.root, slugs);
+    if ('pages' in value)
+        collectNavigationPageSlugs(value.pages, slugs);
+    if ('groups' in value)
+        collectNavigationPageSlugs(value.groups, slugs);
+    for (const key of ['tabs', 'anchors', 'dropdowns', 'versions', 'languages', 'products', 'menu']) {
+        if (key in value)
+            collectNavigationPageSlugs(value[key], slugs);
+    }
+    return slugs;
+}
+export async function scanSdkFrontmatterMetadata(contentDirectoryPath, navigation, pageScans) {
+    const contentRoot = await fse.realpath(contentDirectoryPath);
+    const metadataBySlug = {};
+    const slugs = collectNavigationPageSlugs(navigation);
+    // Workers share an iterator so large navigation trees don't enqueue every file at once.
+    const queue = slugs.values();
+    await Promise.all(Array.from({ length: Math.min(SDK_SCAN_CONCURRENCY, slugs.size) }, async () => {
+        for (const slug of queue) {
+            try {
+                const file = await readContainedMarkdown(contentRoot, slug, pageScans);
+                if (file === undefined)
+                    continue;
+                const { attributes } = parseFrontmatter(file.content);
+                if (attributes.sdk !== undefined) {
+                    metadataBySlug[slug] = { sdk: attributes.sdk };
+                }
+            }
+            catch {
+                // Ignore unreadable/invalid frontmatter during the scan.
+            }
+        }
+    }));
+    return metadataBySlug;
+}

package/dist/prebuild/update/read/readContent.js

@@ -4,13 +4,14 @@ import { outputFile } from 'fs-extra';
 import { join } from 'path';
 import { preparseMdxTree } from '../../../createPage/preparseMdx/index.js';
 import { warnOnParseError } from '../../warnings.js';
-import { preserveAutoGeneratedMetadata } from '../preserveAutoGeneratedMetadata.js';
+import { createGeneratedGraphqlRouteIndex, preserveAutoGeneratedMetadata, } from '../preserveAutoGeneratedMetadata.js';
 const { readFile } = _promises;
 const PAGE_PARSE_CONCURRENCY = 8;
 export const readPageContents = async ({ contentDirectoryPath, openApiFiles, asyncApiFiles, contentFilenames, pagesAcc, }) => {
     const filesWithImports = [];
     const mdxFilesWithNoImports = [];
     const remainingFilenames = [...contentFilenames];
+    const graphqlRoutes = createGeneratedGraphqlRouteIndex(pagesAcc);
     const processFile = async (filename) => {
         const sourcePath = join(contentDirectoryPath, filename);
         const targetPath = join('src', '_props', filename);
@@ -34,7 +35,7 @@ export const readPageContents = async ({ contentDirectoryPath, openApiFiles, asy
                 return;
             }
             const { slug, pageMetadata } = getDecoratedNavPageAndSlug(filename, contentStr, openApiFiles, asyncApiFiles);
-            preserveAutoGeneratedMetadata(contentStr, slug, pageMetadata, pagesAcc);
+            preserveAutoGeneratedMetadata(contentStr, slug, pageMetadata, pagesAcc, graphqlRoutes);
             // Only RSS candidates are needed by later phases (writeRssFiles). All
             // other import-free pages are written and dropped immediately so peak
             // memory does not grow with the number of pages.

package/dist/prebuild/update/resolveImportsAndWriteFiles.js

@@ -2,7 +2,7 @@ import { resolveAllImports, hasImports, findAndRemoveImports, getDecoratedNavPag
 import { outputFile } from 'fs-extra';
 import { join } from 'path';
 import { addWarning } from '../warnings.js';
-import { preserveAutoGeneratedMetadata } from './preserveAutoGeneratedMetadata.js';
+import { createGeneratedGraphqlRouteIndex, preserveAutoGeneratedMetadata, } from './preserveAutoGeneratedMetadata.js';
 export const resolveImportsAndWriteFiles = async ({ openApiFiles, asyncApiFiles, pagesAcc, snippetsV2, filesWithImports, }) => {
     const snippetsWithResolvedImports = await resolveImportsInSnippets(snippetsV2);
     const writeSnippetsWithImportsPromises = await writeSnippets(snippetsWithResolvedImports);
@@ -50,6 +50,7 @@ const writeSnippets = async (snippetsWithImports) => snippetsWithImports.map(asy
     });
 });
 const resolveImportsInPages = async ({ openApiFiles, asyncApiFiles, snippetsWithResolvedImports, filesWithImports, pagesAcc, }) => {
+    const graphqlRoutes = createGeneratedGraphqlRouteIndex(pagesAcc);
     const filesWithResolvedImportsPromises = filesWithImports.map(async (fileWithImports) => {
         const tree = await resolveAllImports({
             snippets: snippetsWithResolvedImports,
@@ -58,7 +59,7 @@ const resolveImportsInPages = async ({ openApiFiles, asyncApiFiles, snippetsWith
         });
         const contentStr = stringifyTree(tree);
         const { slug, pageMetadata } = getDecoratedNavPageAndSlug(fileWithImports.filename, contentStr, openApiFiles, asyncApiFiles);
-        preserveAutoGeneratedMetadata(contentStr, slug, pageMetadata, pagesAcc);
+        preserveAutoGeneratedMetadata(contentStr, slug, pageMetadata, pagesAcc, graphqlRoutes);
         const targetPath = join('src', '_props', fileWithImports.filename);
         return {
             targetPath,