@mintlify/previewing 4.0.1462 → 4.0.1464

package/dist/__tests__/listener-graphql-packages.test.js

@@ -0,0 +1,68 @@
+import { mkdir, rm } from 'fs/promises';
+import { join } from 'path';
+import { CMD_EXEC_PATH } from '../constants.js';
+import listener from '../local-preview/listener/index.js';
+import { notifyPackageInputChange } from '../local-preview/packages/index.js';
+const watcher = vi.hoisted(() => ({
+    handlers: {},
+}));
+vi.mock('../constants.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    const { mkdtempSync } = await import('fs');
+    const { tmpdir } = await import('os');
+    const { join } = await import('path');
+    const root = mkdtempSync(join(tmpdir(), 'listener-graphql-'));
+    return {
+        ...actual,
+        CMD_EXEC_PATH: join(root, 'docs'),
+        CLIENT_PATH: join(root, 'client'),
+        NEXT_PROPS_PATH: join(root, 'client', 'src', '_props'),
+        NEXT_PUBLIC_PATH: join(root, 'client', 'public'),
+    };
+});
+vi.mock('chokidar', () => {
+    const watch = () => {
+        const instance = {
+            on: (event, handler) => {
+                watcher.handlers[event] = handler;
+                return instance;
+            },
+            close: async () => { },
+        };
+        return instance;
+    };
+    return { default: { watch }, watch };
+});
+vi.mock('@mintlify/prebuild', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        getMintIgnore: vi.fn().mockResolvedValue([]),
+        prebuild: vi.fn().mockResolvedValue(undefined),
+    };
+});
+vi.mock('../local-preview/listener/referencedFiles.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        shouldRegenerateGraphqlSource: (filename) => filename === 'schema.graphql',
+    };
+});
+vi.mock('../local-preview/packages/index.js', () => ({
+    notifyPackageInputChange: vi.fn(),
+    writePackageBuildProps: vi.fn(),
+}));
+beforeAll(async () => {
+    await mkdir(CMD_EXEC_PATH, { recursive: true });
+});
+afterAll(async () => {
+    await rm(join(CMD_EXEC_PATH, '..'), { recursive: true, force: true });
+});
+it('tells the packages runtime about a saved GraphQL source', async () => {
+    const triggerRefresh = vi.fn();
+    listener(triggerRefresh, {});
+    await vi.waitFor(() => expect(watcher.handlers.change).toBeDefined());
+    await watcher.handlers.change?.('schema.graphql');
+    expect(triggerRefresh).toHaveBeenCalledOnce();
+    expect(notifyPackageInputChange).toHaveBeenCalledWith('schema.graphql', null);
+});

package/dist/__tests__/listener-package-manifest.test.d.ts

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

package/dist/__tests__/listener-package-manifest.test.js

@@ -0,0 +1,103 @@
+import { validate } from '@mintlify/common';
+import { mkdir, rm, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { CMD_EXEC_PATH, NEXT_PROPS_PATH } from '../constants.js';
+import listener from '../local-preview/listener/index.js';
+import { notifyPackageInputChange } from '../local-preview/packages/index.js';
+import * as logs from '../logging-state.js';
+const watcher = vi.hoisted(() => ({
+    handlers: {},
+}));
+vi.mock('../constants.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    const { mkdtempSync } = await import('fs');
+    const { tmpdir } = await import('os');
+    const { join } = await import('path');
+    const root = mkdtempSync(join(tmpdir(), 'listener-manifest-'));
+    return {
+        ...actual,
+        CMD_EXEC_PATH: join(root, 'docs'),
+        CLIENT_PATH: join(root, 'client'),
+        NEXT_PROPS_PATH: join(root, 'client', 'src', '_props'),
+        NEXT_PUBLIC_PATH: join(root, 'client', 'public'),
+    };
+});
+vi.mock('chokidar', () => {
+    const watch = () => {
+        const instance = {
+            on: (event, handler) => {
+                watcher.handlers[event] = handler;
+                return instance;
+            },
+            close: async () => { },
+        };
+        return instance;
+    };
+    return { default: { watch }, watch };
+});
+vi.mock('@mintlify/common', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, validate: vi.fn().mockRejectedValue(new Error('not an OpenAPI spec')) };
+});
+vi.mock('@mintlify/prebuild', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        getMintIgnore: vi.fn().mockResolvedValue([]),
+        discoverOverlayFiles: vi.fn().mockResolvedValue([]),
+    };
+});
+vi.mock('../local-preview/packages/index.js', () => ({
+    notifyPackageInputChange: vi.fn(),
+    writePackageBuildProps: vi.fn(),
+}));
+const addChangeLogSpy = vi.spyOn(logs, 'addChangeLog');
+const triggerRefresh = vi.fn();
+const change = async (filename) => {
+    listener(triggerRefresh, {});
+    await vi.waitFor(() => expect(watcher.handlers.change).toBeDefined());
+    await watcher.handlers.change?.(filename);
+};
+const edited = (filename) => expect(addChangeLogSpy).toHaveBeenCalledWith(expect.objectContaining({ props: expect.objectContaining({ filename }) }));
+const manifest = { name: 'docs', dependencies: { recharts: '2.15.0' } };
+beforeAll(async () => {
+    await mkdir(join(CMD_EXEC_PATH, 'snippets'), { recursive: true });
+    await mkdir(NEXT_PROPS_PATH, { recursive: true });
+    await writeFile(join(CMD_EXEC_PATH, 'package.json'), JSON.stringify(manifest));
+    await writeFile(join(CMD_EXEC_PATH, 'snippets', 'package.json'), JSON.stringify(manifest));
+    await writeFile(join(NEXT_PROPS_PATH, 'customLanguages.json'), '[]');
+});
+afterAll(async () => {
+    await rm(join(CMD_EXEC_PATH, '..'), { recursive: true, force: true });
+});
+beforeEach(() => {
+    vi.clearAllMocks();
+    watcher.handlers = {};
+});
+afterEach(() => {
+    vi.unstubAllEnvs();
+});
+describe('listener package manifest changes', () => {
+    it('treats a root package.json as a potential OpenAPI spec when the flag is off', async () => {
+        vi.stubEnv('MINTLIFY_NATIVE_NPM_PACKAGES', undefined);
+        await change('package.json');
+        expect(notifyPackageInputChange).toHaveBeenCalledWith('package.json', 'potentialJsonOpenApiSpec');
+        expect(validate).toHaveBeenCalledWith(manifest);
+        expect(triggerRefresh).toHaveBeenCalledOnce();
+        edited('package.json');
+    });
+    it('leaves a root package.json to the packages runtime when the flag is on', async () => {
+        vi.stubEnv('MINTLIFY_NATIVE_NPM_PACKAGES', '1');
+        await change('package.json');
+        expect(notifyPackageInputChange).toHaveBeenCalledWith('package.json', 'potentialJsonOpenApiSpec');
+        expect(validate).not.toHaveBeenCalled();
+        expect(triggerRefresh).not.toHaveBeenCalled();
+        edited('package.json');
+    });
+    it('still parses a nested package.json when the flag is on', async () => {
+        vi.stubEnv('MINTLIFY_NATIVE_NPM_PACKAGES', '1');
+        await change(join('snippets', 'package.json'));
+        expect(validate).toHaveBeenCalledWith(manifest);
+        expect(triggerRefresh).toHaveBeenCalledOnce();
+    });
+});

package/dist/__tests__/packages-builder.test.d.ts

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

package/dist/__tests__/packages-builder.test.js

@@ -0,0 +1,88 @@
+import fse from 'fs-extra';
+import { mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+const notFound = (code, message = "Cannot find package '@mintlify/package-builder' imported from /cli/dist/index.js") => Object.assign(new Error(message), { code });
+vi.mock('../packages/builder.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        loadPackageBuilder: () => actual.loadPackageBuilder(() => Promise.reject(notFound('ERR_MODULE_NOT_FOUND'))),
+    };
+});
+import { PackagesDev } from '../local-preview/packages/dev.js';
+import { PACKAGE_BUILDER_MISSING } from '../packages/builder.js';
+const actualLoad = async () => (await vi.importActual('../packages/builder.js'))
+    .loadPackageBuilder;
+const PAGE = `import { LineChart } from "recharts";
+
+<LineChart width={400} height={200} data={[{ v: 1 }]} />
+`;
+describe('loadPackageBuilder', () => {
+    it.each(['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'])('explains how to get npm packages back on %s', async (code) => {
+        const load = await actualLoad();
+        await expect(load(() => Promise.reject(notFound(code)))).rejects.toThrow(PACKAGE_BUILDER_MISSING);
+    });
+    it('passes other errors through', async () => {
+        const error = Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' });
+        const load = await actualLoad();
+        await expect(load(() => Promise.reject(error))).rejects.toBe(error);
+    });
+    it('passes through a missing dependency of an installed builder', async () => {
+        const error = notFound('ERR_MODULE_NOT_FOUND', "Cannot find package 'entities' imported from /cli/node_modules/@mintlify/package-builder/dist/sanitize.js");
+        const load = await actualLoad();
+        await expect(load(() => Promise.reject(error))).rejects.toBe(error);
+    });
+    it('loads the builder when it is installed', async () => {
+        const load = await actualLoad();
+        expect(typeof (await load()).build).toBe('function');
+    });
+    it('pins the builder version from this workspace so releases publish them together', async () => {
+        const packageJson = (path) => fse.readJson(fileURLToPath(new URL(`../../../${path}/package.json`, import.meta.url)));
+        const previewing = await packageJson('previewing');
+        const builder = await packageJson('package-builder');
+        expect(previewing.optionalDependencies['@mintlify/package-builder']).toBe(builder.version);
+    });
+});
+describe('without @mintlify/package-builder installed', () => {
+    let root;
+    let docsRoot;
+    beforeEach(async () => {
+        root = await mkdtemp(join(tmpdir(), 'packages-builder-'));
+        docsRoot = join(root, 'docs');
+        await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+        await fse.outputJson(join(docsRoot, 'package.json'), { dependencies: { recharts: '2.15.4' } });
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), PAGE);
+    });
+    afterEach(async () => {
+        await rm(root, { recursive: true, force: true });
+    });
+    it('reports the reinstall hint in mint dev and shows it on package components', async () => {
+        const failed = vi.fn();
+        const dev = new PackagesDev({
+            docsRoot,
+            buildsDir: join(root, 'builds'),
+            propsPath: join(root, 'props'),
+            onRebuilt: () => { },
+            reporter: {
+                building: () => { },
+                built: () => { },
+                failed,
+                missingNodeModules: () => { },
+                islandErrors: () => { },
+                configError: () => { },
+            },
+            debounceMs: 0,
+            pollMs: 10,
+        });
+        try {
+            await dev.init();
+            expect(failed).toHaveBeenCalledWith([PACKAGE_BUILDER_MISSING], []);
+            expect(dev.getStatus()).toEqual({ state: 'failed', message: PACKAGE_BUILDER_MISSING });
+        }
+        finally {
+            await dev.close();
+        }
+    });
+});

package/dist/__tests__/packages-collect.test.d.ts

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

package/dist/__tests__/packages-collect.test.js

@@ -0,0 +1,387 @@
+import { findAndRemoveImports, getAST, parseFrontmatter, stringifyTree } from '@mintlify/common';
+import { getMdx } from '@mintlify/common/server-mdx';
+import { createPage, preparseMdxTree } from '@mintlify/prebuild';
+import fse from 'fs-extra';
+import { mkdtemp, readdir, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join, sep } 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('@mintlify/common', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, getAST: vi.fn(actual.getAST) };
+});
+vi.mock('../local-preview/listener/utils.js', () => ({
+    getCurrentVariables: vi.fn(async () => ({ brand: 'Acme' })),
+    handleParseError: vi.fn(),
+}));
+import { resolvePageImports } from '../local-preview/listener/resolve-page-imports.js';
+import { setPackageImportOptions } from '../local-preview/packages/state.js';
+import { collectPackageIslands, PackageIslandCollector } from '../packages/collect.js';
+import { readPackagesSetup } from '../packages/setup.js';
+const CHARTS = `---
+title: Charts
+---
+
+import { LineChart, Line } from "recharts";
+import { RevenueChart } from "/snippets/revenue.jsx";
+
+export const data = [{ v: 1 }, { v: 3 }];
+
+# {{brand}} charts
+
+<LineChart width={400} height={200} data={data}>
+  <Line dataKey="v" isAnimationActive={false} />
+</LineChart>
+
+<Note>
+  <RevenueChart currency="USD" />
+</Note>
+`;
+const BROKEN = `import { LineChart } from "recharts";
+
+Intro.
+
+<LineChart width={400} height={200} onClick={() => {}} />
+`;
+const UNDECLARED = `import { debounce } from "lodash";
+
+Nothing here.
+`;
+const REVENUE = `import { BarChart, Bar } from "recharts";
+import { formatMoney } from "./format.js";
+
+export const RevenueChart = ({ currency }) => (
+  <BarChart width={300} height={150} data={[{ v: 1 }]}>
+    <Bar dataKey="v" name={formatMoney(1, currency)} />
+  </BarChart>
+);
+`;
+const BAR_SNIPPET = `import { BarChart, Bar } from "recharts";
+
+<BarChart width={300} height={150} data={[{ v: 1 }]}>
+  <Bar dataKey="v" name="{{brand}} revenue" />
+</BarChart>
+`;
+const LINE_SNIPPET = `<LineChart width={400} height={200} data={[{ v: 2 }]}>
+  <Line dataKey="v" isAnimationActive={false} />
+</LineChart>
+`;
+const writeDocs = async (root) => {
+    await fse.outputJson(join(root, 'docs.json'), {
+        name: 'Docs',
+        packages: { provider: '/snippets\\provider.jsx' },
+        variables: { brand: 'Acme' },
+    });
+    await fse.outputJson(join(root, 'package.json'), {
+        dependencies: { react: '18.3.1', 'react-dom': '18.3.1', recharts: '2.15.4' },
+    });
+    await fse.outputFile(join(root, 'charts.mdx'), CHARTS);
+    await fse.outputFile(join(root, 'guides/broken.mdx'), BROKEN);
+    await fse.outputFile(join(root, 'undeclared.mdx'), UNDECLARED);
+    await fse.outputFile(join(root, 'plain.mdx'), '# Plain\n');
+    await fse.outputFile(join(root, 'snippets/revenue.jsx'), REVENUE);
+    await fse.outputFile(join(root, 'snippets/format.js'), 'export const formatMoney = (v) => `$${v}`;\n');
+    await fse.outputFile(join(root, 'snippets/provider.jsx'), 'export const Provider = ({ children }) => children;\n');
+};
+const localSnippets = async () => {
+    const dir = join(testPaths.cmd, '_snippets');
+    if (!(await fse.pathExists(dir)))
+        return [];
+    const names = (await readdir(dir, { recursive: true })).filter((name) => name.endsWith('.mdx'));
+    return Promise.all(names.map(async (name) => ({
+        snippetFileLocation: name.split(sep).join('/'),
+        content: await fse.readFile(join(dir, name), 'utf8'),
+    })));
+};
+const compileLikeMintDev = async (filename, packageBuild) => {
+    const sourcePath = join(testPaths.cmd, filename);
+    let content = await fse.readFile(sourcePath, 'utf8');
+    const tree = await preparseMdxTree(content, testPaths.cmd, sourcePath);
+    const importsResponse = await findAndRemoveImports(tree);
+    content = stringifyTree(await resolvePageImports({ ...importsResponse, filename }));
+    const { pageContent } = await createPage(filename, content, testPaths.cmd, [], []);
+    return getMdx({
+        path: filename.replace(/\.mdx$/, ''),
+        content: parseFrontmatter(pageContent).body,
+        metadata: {},
+        snippets: await localSnippets(),
+        subdomain: 'local',
+        codeStyling: undefined,
+        tailwindSelectors: [],
+        variables: { brand: 'Acme' },
+        packageBuild,
+    });
+};
+describe('collectPackageIslands', () => {
+    let root;
+    beforeEach(async () => {
+        root = await mkdtemp(join(tmpdir(), 'packages-collect-'));
+        testPaths.cmd = join(root, 'docs');
+        testPaths.public = join(root, 'public');
+        await fse.ensureDir(testPaths.public);
+        await writeDocs(testPaths.cmd);
+    });
+    afterEach(async () => {
+        setPackageImportOptions(undefined);
+        await rm(root, { recursive: true, force: true });
+    });
+    it('reads the packages setup and normalizes the provider path', async () => {
+        const setup = await readPackagesSetup(testPaths.cmd);
+        expect(setup?.packages.provider).toBe('/snippets/provider.jsx');
+        expect(setup?.packageNames).toEqual(new Set(['react', 'react-dom', 'recharts']));
+        expect(setup?.variables).toEqual({ brand: 'Acme' });
+        expect(setup?.errors).toEqual([]);
+    });
+    it('returns undefined without a packages key', async () => {
+        await fse.outputJson(join(testPaths.cmd, 'docs.json'), { name: 'Docs' });
+        expect(await readPackagesSetup(testPaths.cmd)).toBeUndefined();
+    });
+    it('returns undefined without a docs.json and rejects one that does not parse', async () => {
+        await fse.outputFile(join(testPaths.cmd, 'docs.json'), '{ "packages": {}, }');
+        await expect(readPackagesSetup(testPaths.cmd)).rejects.toThrow(/^docs\.json could not be loaded: \S/);
+        await fse.outputJson(join(testPaths.cmd, 'docs.json'), ['packages']);
+        await expect(readPackagesSetup(testPaths.cmd)).rejects.toThrow('docs.json is not a JSON object');
+        await fse.remove(join(testPaths.cmd, 'docs.json'));
+        expect(await readPackagesSetup(testPaths.cmd)).toBeUndefined();
+    });
+    it('parses only the pages that can hold package components', async () => {
+        vi.mocked(getAST).mockClear();
+        const collected = await collectPackageIslands({
+            docsRoot: testPaths.cmd,
+            packageNames: new Set(['recharts']),
+            variables: { brand: 'Acme' },
+        });
+        expect(collected.pages['plain.mdx']).toEqual({ ids: [], errors: [] });
+        const parsed = vi.mocked(getAST).mock.calls.map(([, file]) => file);
+        expect(parsed).toContain('/charts.mdx');
+        expect(parsed).not.toContain('/plain.mdx');
+    });
+    it('collects inline and snippet islands, errors and warnings across pages', async () => {
+        const setup = await readPackagesSetup(testPaths.cmd);
+        const collected = await collectPackageIslands({
+            docsRoot: testPaths.cmd,
+            packageNames: setup?.packageNames ?? new Set(),
+            variables: setup?.variables,
+            provider: setup?.packages.provider,
+        });
+        expect(collected.packageSnippets).toEqual(new Set(['/snippets/revenue.jsx']));
+        expect(Object.keys(collected.snippetFiles).sort()).toEqual([
+            '/snippets/provider.jsx',
+            '/snippets/revenue.jsx',
+        ]);
+        expect(collected.snippetFiles['/snippets/revenue.jsx']).toBe(REVENUE);
+        expect(collected.islands.map((island) => island.kind)).toEqual(['inline', 'snippet']);
+        expect(collected.pages['charts.mdx']?.ids).toEqual(collected.islands.map((i) => i.id));
+        expect(collected.pages['plain.mdx']?.ids).toEqual([]);
+        expect(collected.errors).toEqual([
+            expect.objectContaining({ file: 'guides/broken.mdx', line: 5 }),
+            {
+                file: 'undeclared.mdx',
+                line: 1,
+                message: `imports "lodash", which isn't listed in package.json dependencies.`,
+            },
+        ]);
+        expect(collected.warnings).toEqual([
+            expect.objectContaining({
+                file: 'undeclared.mdx',
+                message: expect.stringContaining('lodash'),
+            }),
+        ]);
+    });
+    it('resolves relatively imported snippets before the snippets that import them', async () => {
+        await fse.outputFile(join(testPaths.cmd, 'snippets/a-outer.mdx'), 'import Inner from "./b-inner.mdx";\n\n<Inner />\n');
+        await fse.outputFile(join(testPaths.cmd, 'snippets/b-inner.mdx'), 'import { RevenueChart } from "./revenue.jsx";\n\n<RevenueChart currency="EUR" />\n');
+        await fse.outputFile(join(testPaths.cmd, 'nested.mdx'), 'import Outer from "/snippets/a-outer.mdx";\n\n<Outer />\n');
+        const setup = await readPackagesSetup(testPaths.cmd);
+        const collected = await collectPackageIslands({
+            docsRoot: testPaths.cmd,
+            packageNames: setup?.packageNames ?? new Set(),
+            variables: setup?.variables,
+        });
+        const [id] = collected.pages['nested.mdx']?.ids ?? [];
+        expect(collected.islands.find((island) => island.id === id)?.kind).toBe('snippet');
+        expect(collected.warnings).not.toContainEqual(expect.objectContaining({ file: 'snippets/a-outer.mdx' }));
+    });
+    it('produces the island ids that mint dev compiles for the page', async () => {
+        const setup = await readPackagesSetup(testPaths.cmd);
+        const collected = await collectPackageIslands({
+            docsRoot: testPaths.cmd,
+            packageNames: setup?.packageNames ?? new Set(),
+            variables: setup?.variables,
+        });
+        setPackageImportOptions({
+            packageNames: setup?.packageNames ?? new Set(),
+            packageSnippets: collected.packageSnippets,
+        });
+        const islands = Object.fromEntries(collected.islands.map((island) => [
+            island.id,
+            { prefix: `mi-${island.id}-`, html: '<svg></svg>' },
+        ]));
+        const compiled = await compileLikeMintDev('charts.mdx', {
+            baseUrl: '/_mintlify/pkg/abc',
+            islands,
+            packageNames: [...(setup?.packageNames ?? [])],
+            packageSnippets: [...collected.packageSnippets],
+        });
+        expect(Object.keys(compiled.mdxExtracts.islands ?? {})).toEqual(collected.pages['charts.mdx']?.ids);
+        expect(compiled.mdxExtracts.packageBaseUrl).toBe('/_mintlify/pkg/abc');
+        expect(compiled.mdxSource.compiledSource).not.toMatch(/LineChart|RevenueChart/);
+    });
+    it('extracts the package components that <Snippet file> injects with the ids mint dev compiles', async () => {
+        await fse.outputFile(join(testPaths.cmd, '_snippets/bar.mdx'), BAR_SNIPPET);
+        await fse.outputFile(join(testPaths.cmd, '_snippets/line.mdx'), LINE_SNIPPET);
+        await fse.outputFile(join(testPaths.cmd, 'revenue.mdx'), '# Revenue\n\n<Snippet file="bar.mdx" />\n');
+        await fse.outputFile(join(testPaths.cmd, 'trend.mdx'), 'import { LineChart, Line } from "recharts";\n\n<Snippet file="line.mdx" />\n');
+        const setup = await readPackagesSetup(testPaths.cmd);
+        const collector = new PackageIslandCollector({
+            docsRoot: testPaths.cmd,
+            packageNames: setup?.packageNames ?? new Set(),
+            variables: setup?.variables,
+        });
+        const collected = await collector.collectAll();
+        setPackageImportOptions({
+            packageNames: setup?.packageNames ?? new Set(),
+            packageSnippets: collected.packageSnippets,
+        });
+        const islands = Object.fromEntries(collected.islands.map((island) => [
+            island.id,
+            { prefix: `mi-${island.id}-`, html: '<svg></svg>' },
+        ]));
+        const packageBuild = {
+            baseUrl: '/_mintlify/pkg/abc',
+            islands,
+            packageNames: [...(setup?.packageNames ?? [])],
+            packageSnippets: [...collected.packageSnippets],
+        };
+        expect(collected.pages['revenue.mdx']).toEqual({ ids: [expect.any(String)], errors: [] });
+        expect(collected.pages['trend.mdx']).toEqual({ ids: [expect.any(String)], errors: [] });
+        const [barId] = collected.pages['revenue.mdx']?.ids ?? [];
+        expect(collected.islands.find((island) => island.id === barId)?.module).toContain('Acme revenue');
+        for (const page of ['revenue.mdx', 'trend.mdx']) {
+            const compiled = await compileLikeMintDev(page, packageBuild);
+            expect(compiled.parseFailed).toBeUndefined();
+            expect(Object.keys(compiled.mdxExtracts.islands ?? {})).toEqual(collected.pages[page]?.ids);
+            expect(compiled.mdxSource.compiledSource).not.toMatch(/BarChart|LineChart/);
+        }
+        expect((await collector.updatePage('revenue.mdx')).pages['revenue.mdx']?.ids).toEqual([barId]);
+    });
+    it('resolves <Snippet file> imports against the snippet file with the ids mint dev compiles', async () => {
+        const component = (name) => `import { BarChart, Bar } from "recharts";\n\nexport const ${name} = () => (\n  <BarChart width={300} height={150} data={[{ v: 1 }]}>\n    <Bar dataKey="v" name="${name}" />\n  </BarChart>\n);\n`;
+        await fse.outputFile(join(testPaths.cmd, 'snippets/chart.jsx'), component('Chart'));
+        await fse.outputFile(join(testPaths.cmd, 'snippets/inner.jsx'), component('Inner'));
+        await fse.outputFile(join(testPaths.cmd, 'snippets/wrong.jsx'), component('Wrong'));
+        await fse.outputFile(join(testPaths.cmd, '_snippets/charts/x.mdx'), 'import { Chart } from "../../snippets/chart.jsx";\n\n<Chart />\n\n<Snippet file="charts/inner/y.mdx" />\n');
+        await fse.outputFile(join(testPaths.cmd, '_snippets/charts/inner/y.mdx'), 'import { Inner } from "../../../snippets/inner.jsx";\n\n<Inner />\n');
+        await fse.outputFile(join(testPaths.cmd, '_snippets/charts/w.mdx'), 'import { Wrong } from "../snippets/wrong.jsx";\n\n<Wrong />\n');
+        await fse.outputFile(join(testPaths.cmd, 'guides/deep/nested/page.mdx'), '# Nested\n\n<Snippet file="charts/x.mdx" />\n');
+        await fse.outputFile(join(testPaths.cmd, 'guides/wrong.mdx'), '# Wrong\n\n<Snippet file="charts/w.mdx" />\n');
+        const setup = await readPackagesSetup(testPaths.cmd);
+        const collected = await collectPackageIslands({
+            docsRoot: testPaths.cmd,
+            packageNames: setup?.packageNames ?? new Set(),
+            variables: setup?.variables,
+        });
+        setPackageImportOptions({
+            packageNames: setup?.packageNames ?? new Set(),
+            packageSnippets: collected.packageSnippets,
+        });
+        const packageBuild = {
+            baseUrl: '/_mintlify/pkg/abc',
+            islands: Object.fromEntries(collected.islands.map((island) => [
+                island.id,
+                { prefix: `mi-${island.id}-`, html: '<svg></svg>' },
+            ])),
+            packageNames: [...(setup?.packageNames ?? [])],
+            packageSnippets: [...collected.packageSnippets],
+        };
+        const modules = (page) => (collected.pages[page]?.ids ?? []).map((id) => collected.islands.find((island) => island.id === id)?.module);
+        expect(modules('guides/deep/nested/page.mdx')).toEqual([
+            expect.stringContaining('/snippets/chart.jsx'),
+            expect.stringContaining('/snippets/inner.jsx'),
+        ]);
+        expect(collected.pages['guides/wrong.mdx']).toEqual({ ids: [], errors: [] });
+        for (const page of ['guides/deep/nested/page.mdx', 'guides/wrong.mdx']) {
+            const compiled = await compileLikeMintDev(page, packageBuild);
+            expect(compiled.parseFailed).toBeUndefined();
+            expect(Object.keys(compiled.mdxExtracts.islands ?? {})).toEqual(collected.pages[page]?.ids);
+        }
+    });
+    it('reports a <Snippet file> cycle on the page instead of expanding it forever', async () => {
+        await fse.outputFile(join(testPaths.cmd, '_snippets/note.mdx'), 'Note\n');
+        await fse.outputFile(join(testPaths.cmd, '_snippets/a.mdx'), 'A\n\n<Snippet file="b.mdx" />\n');
+        await fse.outputFile(join(testPaths.cmd, '_snippets/b.mdx'), 'B\n\n<Snippet file="a.mdx" />\n');
+        await fse.outputFile(join(testPaths.cmd, 'loop.mdx'), '# Loop\n\n<Snippet file="a.mdx" />\n');
+        const setup = await readPackagesSetup(testPaths.cmd);
+        const collected = await collectPackageIslands({
+            docsRoot: testPaths.cmd,
+            packageNames: setup?.packageNames ?? new Set(),
+            variables: setup?.variables,
+        });
+        expect(collected.pages['loop.mdx']).toEqual({
+            ids: [],
+            errors: [
+                {
+                    file: 'loop.mdx',
+                    message: '<Snippet file="a.mdx"> includes itself (a.mdx -> b.mdx -> a.mdx).',
+                },
+            ],
+        });
+        expect(collected.pages['charts.mdx']?.errors).toEqual([]);
+    });
+    it('falls back to the snippet trees of a collector for the same docs root only', async () => {
+        const setup = await readPackagesSetup(testPaths.cmd);
+        const input = { packageNames: setup?.packageNames ?? new Set() };
+        const previous = new PackageIslandCollector({ ...input, docsRoot: testPaths.cmd });
+        expect((await previous.collectAll()).packageSnippets).toContain('/snippets/revenue.jsx');
+        const otherRoot = join(root, 'other');
+        await fse.copy(testPaths.cmd, otherRoot);
+        for (const docsRoot of [testPaths.cmd, otherRoot]) {
+            await fse.outputFile(join(docsRoot, 'snippets/revenue.jsx'), REVENUE.replace('</BarChart>', ''));
+        }
+        const same = new PackageIslandCollector({ ...input, docsRoot: testPaths.cmd });
+        same.inheritSnippetTrees(previous);
+        const other = new PackageIslandCollector({ ...input, docsRoot: otherRoot });
+        other.inheritSnippetTrees(previous);
+        expect((await same.collectAll()).packageSnippets).toContain('/snippets/revenue.jsx');
+        expect((await other.collectAll()).packageSnippets).not.toContain('/snippets/revenue.jsx');
+    });
+    it('inherits snippet trees once the previous collector finishes its queued updates', async () => {
+        const setup = await readPackagesSetup(testPaths.cmd);
+        const input = { docsRoot: testPaths.cmd, packageNames: setup?.packageNames ?? new Set() };
+        const revenue = join(testPaths.cmd, 'snippets/revenue.jsx');
+        const previous = new PackageIslandCollector(input);
+        expect((await previous.collectAll()).packageSnippets).toContain('/snippets/revenue.jsx');
+        await fse.remove(revenue);
+        const deleted = previous.collectAll();
+        const next = new PackageIslandCollector(input);
+        next.inheritSnippetTrees(previous);
+        expect((await deleted).packageSnippets).not.toContain('/snippets/revenue.jsx');
+        await fse.outputFile(revenue, REVENUE.replace('</BarChart>', ''));
+        expect((await next.collectAll()).packageSnippets).not.toContain('/snippets/revenue.jsx');
+    });
+    it('updates one page without re-reading the rest', async () => {
+        const setup = await readPackagesSetup(testPaths.cmd);
+        const collector = new PackageIslandCollector({
+            docsRoot: testPaths.cmd,
+            packageNames: setup?.packageNames ?? new Set(),
+        });
+        const before = await collector.collectAll();
+        await fse.outputFile(join(testPaths.cmd, 'charts.mdx'), CHARTS.replace('<Line dataKey="v"', '<Line dataKey="v" strokeWidth={3}'));
+        await fse.outputFile(join(testPaths.cmd, 'plain.mdx'), BROKEN);
+        const after = await collector.updatePage('charts.mdx');
+        expect(after.pages['charts.mdx']?.ids[0]).not.toBe(before.pages['charts.mdx']?.ids[0]);
+        expect(after.pages['charts.mdx']?.ids[1]).toBe(before.pages['charts.mdx']?.ids[1]);
+        expect(after.pages['plain.mdx']?.ids).toEqual([]);
+        expect(after.islands).toHaveLength(2);
+        await fse.remove(join(testPaths.cmd, 'charts.mdx'));
+        expect((await collector.updatePage('charts.mdx')).islands).toEqual([]);
+    });
+});

package/dist/__tests__/packages-dev-snippets.test.d.ts

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