@mintlify/previewing 4.0.1152 → 4.0.1153

package/dist/__tests__/resolve-page-imports.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/resolve-page-imports.test.js

@@ -0,0 +1,48 @@
+import { findAndRemoveImports, stringifyTree } from '@mintlify/common';
+import { preparseMdxTree } from '@mintlify/prebuild';
+import fse from 'fs-extra';
+import { mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+const testPaths = vi.hoisted(() => ({
+    cmd: '',
+    public: '',
+}));
+vi.mock('../constants.js', () => ({
+    get CMD_EXEC_PATH() {
+        return testPaths.cmd;
+    },
+    get NEXT_PUBLIC_PATH() {
+        return testPaths.public;
+    },
+}));
+vi.mock('../local-preview/listener/utils.js', () => ({
+    getCurrentVariables: vi.fn(async () => ({ name: 'Ada' })),
+    handleParseError: vi.fn(),
+}));
+import { resolvePageImports } from '../local-preview/listener/resolve-page-imports.js';
+describe('resolvePageImports', () => {
+    let root;
+    beforeEach(async () => {
+        root = await mkdtemp(join(tmpdir(), 'resolve-page-imports-'));
+        testPaths.cmd = join(root, 'docs');
+        testPaths.public = join(root, 'public');
+        await fse.ensureDir(testPaths.cmd);
+        await fse.ensureDir(testPaths.public);
+    });
+    afterEach(async () => {
+        await rm(root, { recursive: true, force: true });
+    });
+    it('resolves newly imported source snippets with variables and nested imports', async () => {
+        await fse.outputFile(join(testPaths.cmd, 'nested.mdx'), 'export const Nested = () => <span>{{name}}</span>;');
+        await fse.outputFile(join(testPaths.cmd, 'snippet.mdx'), "import { Nested } from './nested.mdx';\n\n<Nested />");
+        const pageContent = "import Snippet from './snippet.mdx';\n\n<Snippet />";
+        const tree = await preparseMdxTree(pageContent, testPaths.cmd, join(testPaths.cmd, 'page.mdx'), vi.fn());
+        const importsResponse = await findAndRemoveImports(tree);
+        const resolvedTree = await resolvePageImports({ ...importsResponse, filename: 'page.mdx' });
+        const resolvedContent = stringifyTree(resolvedTree);
+        expect(resolvedContent).toContain('Ada');
+        expect(resolvedContent).not.toContain('{{name}}');
+        expect(resolvedContent).not.toContain("import { Nested } from './nested.mdx'");
+    });
+});

package/dist/__tests__/shouldRegenerateNavForPage.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { shouldRegenerateNavForPage } from '../local-preview/listener/utils.js';
+import { seedFrontmatterHashForPage, shouldRegenerateNavForPage, } from '../local-preview/listener/utils.js';
 describe('shouldRegenerateNavForPage', () => {
     let frontmatterHashes;
     beforeEach(() => {
@@ -30,6 +30,13 @@ describe('shouldRegenerateNavForPage', () => {
         const result = await shouldRegenerateNavForPage('test.mdx', updatedContent, frontmatterHashes);
         expect(result).toBe(false);
     });
+    it('should return false for a content-only change after seeding frontmatter', async () => {
+        const originalContent = `---\ntitle: "Test Page"\ndescription: "A test page"\n---\n# Original Content`;
+        const updatedContent = `---\ntitle: "Test Page"\ndescription: "A test page"\n---\n# Updated Content`;
+        seedFrontmatterHashForPage('test.mdx', originalContent, frontmatterHashes);
+        const result = await shouldRegenerateNavForPage('test.mdx', updatedContent, frontmatterHashes);
+        expect(result).toBe(false);
+    });
     it('should handle files with no frontmatter', async () => {
         const contentNoFrontmatter = '# Just a heading\n\nSome content';
         await shouldRegenerateNavForPage('test.mdx', contentNoFrontmatter, frontmatterHashes);

package/dist/local-preview/listener/index.d.ts

@@ -3,5 +3,6 @@ declare const listener: (triggerRefresh: () => void, options?: {
     localSchema?: boolean;
     groups?: string[];
 }) => void;
-export { initializeImportCache };
+declare const initializeFrontmatterHashCache: () => Promise<void>;
+export { initializeFrontmatterHashCache, initializeImportCache };
 export default listener;

package/dist/local-preview/listener/index.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { findAndRemoveImports, hasImports, getFileCategory, validate, stringifyTree, isMintIgnored, replaceVariables, } from '@mintlify/common';
-import { createPage, MintConfigUpdater, DocsConfigUpdater, preparseMdxTree, prebuild, } from '@mintlify/prebuild';
+import { createPage, getFileListSync, MintConfigUpdater, DocsConfigUpdater, preparseMdxTree, prebuild, } from '@mintlify/prebuild';
 import Chalk from 'chalk';
 import chokidar from 'chokidar';
 import { promises as _promises } from 'fs';
@@ -18,10 +18,28 @@ import { initializeImportCache, updateImportCacheForFile, removeFromImportCache,
 import { hasTrackedReferencedFile, refreshTrackedReferencedFiles } from './referencedFiles.js';
 import { regenerateAllSnippets } from './regenerateAllSnippets.js';
 import { resolveAllImports } from './resolveAllImports.js';
+import { resolvePageImports } from './resolve-page-imports.js';
 import { updateCustomLanguages, updateGeneratedNav, updateOpenApiFiles, upsertOpenApiFile, } from './update.js';
-import { getCurrentVariables, getMintIgnoreGlobs, handleParseError, isFileSizeValid, isJsonValid, shouldRegenerateNavForPage, suppressParseError, } from './utils.js';
+import { getCurrentVariables, getMintIgnoreGlobs, handleParseError, isFileSizeValid, isJsonValid, seedFrontmatterHashForPage, shouldRegenerateNavForPage, suppressParseError, } from './utils.js';
 const { readFile } = _promises;
 const frontmatterHashes = new Map();
+const SLOW_UPDATE_LOG_THRESHOLD_MS = 1000;
+const getElapsedMs = (startTime) => {
+    return Number((process.hrtime.bigint() - startTime) / 1000000n);
+};
+const formatElapsedSeconds = (durationMs) => {
+    return `${(durationMs / 1000).toFixed(2)}s`;
+};
+const shouldLogUpdateTiming = (durationMs) => {
+    return process.env.DEV_TIMING === 'true' || durationMs >= SLOW_UPDATE_LOG_THRESHOLD_MS;
+};
+const addUpdateTimingLog = (filename, category, durationMs) => {
+    if (!shouldLogUpdateTiming(durationMs)) {
+        return;
+    }
+    const categoryLabel = category == null ? 'uncategorized' : category;
+    addChangeLog(_jsx(InfoLog, { message: `processed ${filename} in ${formatElapsedSeconds(durationMs)} (${categoryLabel})` }));
+};
 const listener = (triggerRefresh, options = {}) => {
     const mintIgnoreGlobs = getMintIgnoreGlobs();
     chokidar
@@ -47,7 +65,9 @@ const onAddEvent = async (filename, triggerRefresh, options) => {
         return;
     }
     try {
+        const startTime = process.hrtime.bigint();
         const category = await onUpdateEvent(filename, triggerRefresh, options);
+        addUpdateTimingLog(filename, category, getElapsedMs(startTime));
         if (category !== undefined) {
             addChangeLog(_jsx(AddedLog, { filename: filename }));
         }
@@ -61,7 +81,9 @@ const onChangeEvent = async (filename, triggerRefresh, options) => {
         return;
     }
     try {
+        const startTime = process.hrtime.bigint();
         const category = await onUpdateEvent(filename, triggerRefresh, options);
+        addUpdateTimingLog(filename, category, getElapsedMs(startTime));
         if (category !== undefined) {
             addChangeLog(_jsx(EditedLog, { filename: filename }));
         }
@@ -77,6 +99,7 @@ const onUnlinkEvent = async (filename, triggerRefresh, options) => {
     try {
         const importedFiles = getImportedFilesFromCache();
         const potentialCategory = getFileCategory(filename, { importedFiles });
+        frontmatterHashes.delete(filename);
         if (hasTrackedReferencedFile(filename)) {
             try {
                 const { mintConfig, openApiFiles, docsConfig } = await getDocsState(handleParseError);
@@ -136,6 +159,7 @@ const onUnlinkEvent = async (filename, triggerRefresh, options) => {
                     await fse.emptyDir(NEXT_PROPS_PATH);
                     const prebuildResult = await prebuild(CMD_EXEC_PATH, options);
                     await initializeImportCache(CMD_EXEC_PATH, prebuildResult?.fileImportsMap);
+                    await initializeFrontmatterHashCache();
                     await refreshTrackedReferencedFiles();
                 }
                 catch (err) {
@@ -193,6 +217,21 @@ const validateConfigFiles = async () => {
         console.error('⚠️ Error validating configuration files:', error);
     }
 };
+const initializeFrontmatterHashCache = async () => {
+    frontmatterHashes.clear();
+    const importedFiles = getImportedFilesFromCache();
+    const pageFilenames = getFileListSync(CMD_EXEC_PATH).filter((file) => {
+        return getFileCategory(file, { importedFiles }) === 'page';
+    });
+    await Promise.all(pageFilenames.map(async (filename) => {
+        try {
+            const filePath = pathUtil.join(CMD_EXEC_PATH, filename);
+            const contentStr = (await readFile(filePath)).toString();
+            seedFrontmatterHashForPage(filename, contentStr, frontmatterHashes, suppressParseError);
+        }
+        catch { }
+    }));
+};
 /**
  * This function is called when a file is added or changed
  * @param filename
@@ -244,7 +283,7 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
             const tree = await preparseMdxTree(contentStr, CMD_EXEC_PATH, filePath, suppressParseError);
             const importsResponse = await findAndRemoveImports(tree);
             if (hasImports(importsResponse)) {
-                contentStr = stringifyTree(await resolveAllImports({ ...importsResponse, filename }));
+                contentStr = stringifyTree(await resolvePageImports({ ...importsResponse, filename }));
             }
             const { pageContent } = await createPage(filename, contentStr, CMD_EXEC_PATH, [], [], handleParseError);
             await fse.outputFile(targetPath, pageContent, {
@@ -311,6 +350,7 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
                 await fse.emptyDir(NEXT_PROPS_PATH);
                 const prebuildResult = await prebuild(CMD_EXEC_PATH, options);
                 await initializeImportCache(CMD_EXEC_PATH, prebuildResult?.fileImportsMap);
+                await initializeFrontmatterHashCache();
                 await refreshTrackedReferencedFiles();
             }
             catch (err) {
@@ -377,5 +417,5 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
     triggerRefresh();
     return category;
 };
-export { initializeImportCache };
+export { initializeFrontmatterHashCache, initializeImportCache };
 export default listener;

package/dist/local-preview/listener/resolve-page-imports.d.ts

@@ -0,0 +1,3 @@
+import type { FileWithImports } from '@mintlify/common';
+import type { Root } from 'mdast';
+export declare const resolvePageImports: (fileWithImports: FileWithImports) => Promise<Root>;

package/dist/local-preview/listener/resolve-page-imports.js

@@ -0,0 +1,98 @@
+import { findAndRemoveImports, hasImports, optionallyAddLeadingSlash, optionallyRemoveLeadingSlash, replaceVariables, resolveAllImports as baseResolveAllImports, resolveImportPath, topologicalSort, } from '@mintlify/common';
+import { preparseMdxTree } from '@mintlify/prebuild';
+import fse from 'fs-extra';
+import { join } from 'path';
+import { CMD_EXEC_PATH, NEXT_PUBLIC_PATH } from '../../constants.js';
+import { getCurrentVariables, handleParseError } from './utils.js';
+const getImportSourcePath = async (filename) => {
+    const generatedPath = join(NEXT_PUBLIC_PATH, filename);
+    if (await fse.pathExists(generatedPath)) {
+        return {
+            baseDir: NEXT_PUBLIC_PATH,
+            path: generatedPath,
+        };
+    }
+    const originalPath = join(CMD_EXEC_PATH, filename);
+    if (await fse.pathExists(originalPath)) {
+        return {
+            baseDir: CMD_EXEC_PATH,
+            path: originalPath,
+        };
+    }
+    return null;
+};
+const parseSnippetWithImports = async ({ filename, variables, snippetsByFilename, }) => {
+    const normalizedFilename = optionallyAddLeadingSlash(filename);
+    if (snippetsByFilename.has(normalizedFilename)) {
+        return;
+    }
+    const importSource = await getImportSourcePath(optionallyRemoveLeadingSlash(normalizedFilename));
+    if (importSource == null) {
+        return;
+    }
+    const content = replaceVariables((await fse.readFile(importSource.path)).toString(), variables);
+    const tree = await preparseMdxTree(content, importSource.baseDir, importSource.path, handleParseError);
+    const importData = await findAndRemoveImports(tree);
+    const fileWithImports = {
+        filename: normalizedFilename,
+        ...importData,
+    };
+    snippetsByFilename.set(normalizedFilename, fileWithImports);
+    await Promise.all(Object.keys(importData.importMap).map(async (source) => {
+        const resolvedPath = resolveImportPath(source, normalizedFilename);
+        if (resolvedPath == null) {
+            return;
+        }
+        await parseSnippetWithImports({
+            filename: resolvedPath,
+            variables,
+            snippetsByFilename,
+        });
+    }));
+};
+const resolveSnippetImports = async (snippetsByFilename) => {
+    const graph = {};
+    for (const snippet of snippetsByFilename.values()) {
+        graph[snippet.filename] = Object.keys(snippet.importMap)
+            .map((source) => resolveImportPath(source, snippet.filename))
+            .filter((resolvedPath) => {
+            return resolvedPath != null && snippetsByFilename.has(resolvedPath);
+        });
+    }
+    const orderedFilenames = topologicalSort(graph).reverse();
+    const resolvedSnippets = [];
+    for (const filename of orderedFilenames) {
+        const snippet = snippetsByFilename.get(filename);
+        if (snippet == null) {
+            continue;
+        }
+        const tree = hasImports(snippet)
+            ? await baseResolveAllImports({
+                snippets: resolvedSnippets,
+                fileWithImports: snippet,
+            })
+            : snippet.tree;
+        resolvedSnippets.push({ filename: snippet.filename, tree });
+    }
+    return resolvedSnippets;
+};
+export const resolvePageImports = async (fileWithImports) => {
+    const variables = await getCurrentVariables();
+    const snippetsByFilename = new Map();
+    await Promise.all(Object.keys(fileWithImports.importMap).map(async (source) => {
+        const resolvedPath = resolveImportPath(source, fileWithImports.filename);
+        if (resolvedPath == null) {
+            return;
+        }
+        await parseSnippetWithImports({
+            filename: resolvedPath,
+            variables,
+            snippetsByFilename,
+        });
+    }));
+    const snippets = await resolveSnippetImports(snippetsByFilename);
+    return await baseResolveAllImports({
+        snippets,
+        fileWithImports,
+    });
+};

package/dist/local-preview/listener/utils.d.ts

@@ -8,6 +8,7 @@ export declare const isJsonValid: (filePath: string) => {
     error?: string;
 };
 export declare const shouldRegenerateNavForPage: (filename: string, contentStr: string, frontmatterHashes: Map<string, string>, onError?: (message: string) => void) => Promise<boolean>;
+export declare const seedFrontmatterHashForPage: (filename: string, contentStr: string, frontmatterHashes: Map<string, string>, onError?: (message: string) => void) => boolean;
 export declare function normalizePathForComparison(filePath: string): string;
 export declare const handleParseError: (message: string) => void;
 export declare const suppressParseError: () => void;

package/dist/local-preview/listener/utils.js

@@ -45,16 +45,8 @@ export const isJsonValid = (filePath) => {
 };
 export const shouldRegenerateNavForPage = async (filename, contentStr, frontmatterHashes, onError) => {
     try {
-        const { attributes: currentFrontmatter } = parseFrontmatter(contentStr);
         const prevFrontmatterHash = frontmatterHashes.get(filename);
-        const currentFrontmatterHash = crypto
-            .createHash('md5')
-            .update(JSON.stringify(currentFrontmatter))
-            .digest('hex');
-        if (!prevFrontmatterHash) {
-            frontmatterHashes.set(filename, currentFrontmatterHash);
-            return true;
-        }
+        const currentFrontmatterHash = getFrontmatterHash(contentStr);
         if (currentFrontmatterHash !== prevFrontmatterHash) {
             frontmatterHashes.set(filename, currentFrontmatterHash);
             return true;
@@ -73,6 +65,26 @@ export const shouldRegenerateNavForPage = async (filename, contentStr, frontmatt
         return true;
     }
 };
+export const seedFrontmatterHashForPage = (filename, contentStr, frontmatterHashes, onError) => {
+    try {
+        frontmatterHashes.set(filename, getFrontmatterHash(contentStr));
+        return true;
+    }
+    catch (error) {
+        const message = `Error parsing frontmatter for ${filename}, skipping initial nav cache: ${error instanceof Error ? error.message : String(error)}`;
+        if (onError) {
+            onError(message);
+        }
+        else {
+            console.warn(message);
+        }
+        return false;
+    }
+};
+const getFrontmatterHash = (contentStr) => {
+    const { attributes: currentFrontmatter } = parseFrontmatter(contentStr);
+    return crypto.createHash('md5').update(JSON.stringify(currentFrontmatter)).digest('hex');
+};
 export function normalizePathForComparison(filePath) {
     return optionallyAddLeadingSlash(filePath).toLowerCase();
 }

package/dist/local-preview/run.js

@@ -7,7 +7,7 @@ import { CMD_EXEC_PATH, NEXT_PUBLIC_PATH } from '../constants.js';
 import { addLog, removeLastLog } from '../logging-state.js';
 import { LaunchLog, UpdateLog } from '../logs.js';
 import { maybeFixMissingWindowsEnvVar } from '../util.js';
-import listener, { initializeImportCache } from './listener/index.js';
+import listener, { initializeFrontmatterHashCache, initializeImportCache } from './listener/index.js';
 import { refreshTrackedReferencedFiles } from './listener/referencedFiles.js';
 import { getLocalNetworkIp } from './network.js';
 import { setupNext } from './setupNext.js';
@@ -145,6 +145,7 @@ export const run = async (argv) => {
         process.on('SIGTERM', onExit);
     });
     await initializeImportCache(CMD_EXEC_PATH, argv.fileImportsMap);
+    await initializeFrontmatterHashCache();
     await refreshTrackedReferencedFiles();
     listener(onChange);
 };