@mintlify/previewing 4.0.1462 → 4.0.1463

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/previewing",
-  "version": "4.0.1462",
+  "version": "4.0.1463",
   "description": "Preview Mintlify docs locally",
   "engines": {
     "node": ">=18.0.0"
@@ -86,5 +86,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "d7f4b348efcebe273004ba634700ac4018560404"
+  "gitHead": "688752e942ccb49213dddf7fa163b025016a48eb"
 }

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

@@ -1,254 +0,0 @@
-import fse from 'fs-extra';
-import { mkdtemp, rm } from 'fs/promises';
-import { tmpdir } from 'os';
-import { basename, join } from 'path';
-import { checkPackages } from '../packages/check.js';
-const PAGE = `import { LineChart } from "recharts";
-
-<LineChart width={400} height={200} data={[{ v: 1 }]} />
-`;
-const result = (input) => {
-    const id = input.islands[0]?.id ?? '';
-    return {
-        ok: true,
-        manifest: {
-            version: 1,
-            builderVersion: '0.0.1',
-            buildId: 'f'.repeat(32),
-            depsHash: 'd'.repeat(64),
-            islandsHash: 'e'.repeat(64),
-            react: { version: '18.3.1', domVersion: '18.3.1' },
-            packages: { react: { version: '18.3.1' }, recharts: { version: '2.15.4' } },
-            css: [],
-            clientAccess: {
-                version: 1,
-                files: { [`client/islands/${id}.js`]: [id] },
-                globalFiles: [],
-            },
-            islands: {
-                [id]: { entry: `client/islands/${id}.js`, prefix: `mi-${id}-`, html: '<svg/>', ssrMs: 2 },
-            },
-            files: [
-                { path: `client/islands/${id}.js`, bytes: 2048, gzipBytes: 512, integrity: 'sha384-abc' },
-            ],
-            diagnostics: [
-                { level: 'warning', code: 'peer-range', message: 'peer warning', pkg: 'recharts' },
-            ],
-        },
-        stats: {
-            installMs: 400,
-            bundleMs: 300,
-            renderMs: 100,
-            totalMs: 850,
-            clientBytes: 2048,
-            clientGzipBytes: 512,
-            serverBytes: 4096,
-            islandClientGzipBytes: { [id]: 512 },
-            reactDirs: { react: [], 'react-dom': [] },
-        },
-        localFiles: [],
-        missingLocalFiles: [],
-    };
-};
-describe('checkPackages', () => {
-    let docsRoot;
-    beforeEach(async () => {
-        docsRoot = await mkdtemp(join(tmpdir(), 'packages-check-'));
-        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(docsRoot, { recursive: true, force: true });
-    });
-    it('builds with npm ci in a temp folder and prints hashes, sizes and diagnostics', async () => {
-        let input;
-        const check = await checkPackages({
-            docsRoot,
-            build: async (received) => {
-                input = received;
-                await fse.ensureDir(received.outDir);
-                return result(received);
-            },
-        });
-        expect(input?.installer).toBe('npm-ci');
-        expect(input?.islands).toHaveLength(1);
-        expect(await fse.pathExists(input?.outDir ?? '')).toBe(false);
-        expect(check.ok).toBe(true);
-        const text = check.lines.map((line) => `${line.level} ${line.message}`);
-        expect(text.some((line) => /[0-9a-f]{32}|sha384-|client\/islands/.test(line))).toBe(false);
-        expect(text).toEqual(expect.arrayContaining([
-            'info 1 package component on 1 page',
-            'info installed react 18.3.1, react-dom 18.3.1, recharts 2.15.4',
-            'info install 400 ms, bundle 300 ms, render 100 ms, total 850 ms',
-            'info 0.5 KB of browser JS (gzip) across all pages',
-            'info charts.mdx: <LineChart> from recharts, 0.5 KB JS (gzip), renders on the server',
-            'warning recharts: peer warning',
-        ]));
-    });
-    it('keeps the output when --out is given', async () => {
-        const out = join(docsRoot, '..', `${basename(docsRoot)}-out`);
-        await checkPackages({
-            docsRoot,
-            outDir: out,
-            build: async (received) => {
-                await fse.ensureDir(received.outDir);
-                return result(received);
-            },
-        });
-        expect(await fse.pathExists(out)).toBe(true);
-        await rm(out, { recursive: true, force: true });
-    });
-    it('refuses to replace a non-empty --out folder unless forced', async () => {
-        const out = join(docsRoot, '..', `${basename(docsRoot)}-keep`);
-        await fse.outputFile(join(out, 'notes.txt'), 'keep me');
-        const build = vi.fn(async (received) => {
-            await fse.emptyDir(received.outDir);
-            return result(received);
-        });
-        try {
-            const check = await checkPackages({ docsRoot, outDir: out, build });
-            expect(build).not.toHaveBeenCalled();
-            expect(check.ok).toBe(false);
-            expect(check.lines).toEqual([
-                {
-                    level: 'error',
-                    message: expect.stringContaining(`${out} already exists and is not an empty folder`),
-                },
-            ]);
-            expect(await fse.readFile(join(out, 'notes.txt'), 'utf8')).toBe('keep me');
-            const forced = await checkPackages({ docsRoot, outDir: out, force: true, build });
-            expect(build).toHaveBeenCalledTimes(1);
-            expect(forced.ok).toBe(true);
-        }
-        finally {
-            await rm(out, { recursive: true, force: true });
-        }
-    });
-    it('refuses an --out path that is a file', async () => {
-        const out = join(docsRoot, 'charts.mdx');
-        const build = vi.fn();
-        const check = await checkPackages({ docsRoot, outDir: out, build });
-        expect(build).not.toHaveBeenCalled();
-        expect(check.ok).toBe(false);
-        expect(check.lines[0]?.message).toContain(`${out} already exists and is not an empty folder`);
-        expect(await fse.readFile(out, 'utf8')).toBe(PAGE);
-    });
-    it('builds the package components that <Snippet file> injects', async () => {
-        await fse.outputFile(join(docsRoot, 'charts.mdx'), '<Snippet file="chart.mdx" />\n');
-        await fse.outputFile(join(docsRoot, '_snippets/chart.mdx'), PAGE);
-        const build = vi.fn(async (received) => result(received));
-        const check = await checkPackages({ docsRoot, build });
-        expect(build.mock.calls[0]?.[0].islands).toEqual([
-            expect.objectContaining({ pagePath: 'charts', kind: 'inline' }),
-        ]);
-        expect(check.lines).toContainEqual({
-            level: 'info',
-            message: '1 package component on 1 page',
-        });
-    });
-    it('fails before building when a page has island errors', async () => {
-        await fse.outputFile(join(docsRoot, 'bad.mdx'), PAGE.replace('/>', 'onClick={() => {}} />'));
-        const build = vi.fn();
-        const check = await checkPackages({ docsRoot, build });
-        expect(build).not.toHaveBeenCalled();
-        expect(check.ok).toBe(false);
-        expect(check.lines.some((line) => line.level === 'error' && line.message.startsWith('bad.mdx:3'))).toBe(true);
-    });
-    it('fails before building when a snippet a page imports has errors', async () => {
-        await fse.outputFile(join(docsRoot, 'charts.mdx'), 'import { Chart } from "/snippets/chart.jsx";\n\n<Chart />\n');
-        await fse.outputFile(join(docsRoot, 'snippets/chart.jsx'), 'import { LineChart } from "recharts";\n\nexport const Chart = () => <LineChart\n');
-        const build = vi.fn();
-        const check = await checkPackages({ docsRoot, build });
-        expect(build).not.toHaveBeenCalled();
-        expect(check.ok).toBe(false);
-        expect(check.lines.some((line) => line.level === 'error' && line.message.startsWith('snippets/chart.jsx'))).toBe(true);
-    });
-    it('reports a docs.json that does not parse instead of a missing packages key', async () => {
-        const raw = '{ "name": "Docs", "packages": {}, }';
-        await fse.outputFile(join(docsRoot, 'docs.json'), raw);
-        const parserMessage = (() => {
-            try {
-                JSON.parse(raw);
-                return '';
-            }
-            catch (error) {
-                return error instanceof Error ? error.message : String(error);
-            }
-        })();
-        const build = vi.fn();
-        const check = await checkPackages({ docsRoot, build });
-        expect(build).not.toHaveBeenCalled();
-        expect(check.ok).toBe(false);
-        expect(check.lines).toEqual([
-            { level: 'error', message: `docs.json could not be loaded: ${parserMessage}` },
-        ]);
-    });
-    it.each([
-        ['', 'docs.json could not be loaded: Unexpected end of JSON input'],
-        ['["packages"]', 'docs.json is not a JSON object'],
-    ])('fails on docs.json %j without building', async (raw, message) => {
-        await fse.outputFile(join(docsRoot, 'docs.json'), raw);
-        const build = vi.fn();
-        expect(await checkPackages({ docsRoot, build })).toEqual({
-            ok: false,
-            lines: [{ level: 'error', message }],
-        });
-        expect(build).not.toHaveBeenCalled();
-    });
-    it.each([
-        ['', 'package.json is not valid JSON: Unexpected end of JSON input'],
-        ['{ "dependencies": ', 'package.json is not valid JSON: Unexpected end of JSON input'],
-        ['["recharts"]', 'package.json is not a JSON object'],
-        ['null', 'package.json is not a JSON object'],
-    ])('fails on package.json %j without building', async (raw, message) => {
-        await fse.outputFile(join(docsRoot, 'package.json'), raw);
-        const build = vi.fn();
-        expect(await checkPackages({ docsRoot, build })).toEqual({
-            ok: false,
-            lines: [{ level: 'error', message }],
-        });
-        expect(build).not.toHaveBeenCalled();
-    });
-    it.each([
-        ['a string', 'nope', ['docs.json packages: Expected object, received string']],
-        ['null', null, ['docs.json packages: Expected object, received null']],
-        ['an array', [], ['docs.json packages: Expected object, received array']],
-        [
-            'an http registry',
-            { registries: { '@acme': 'http://npm.acme.com/' } },
-            [
-                'docs.json packages.registries.@acme: Registry URLs must start with `https://` and then the host',
-            ],
-        ],
-        [
-            'a provider without a leading slash',
-            { provider: 'snippets/provider.jsx' },
-            [
-                'docs.json packages.provider: Provider path must start with `/`, such as `/snippets/provider.jsx`',
-            ],
-        ],
-        [
-            'a provider outside the docs',
-            { provider: '../provider.jsx', isolation: 'none' },
-            [
-                'docs.json packages.provider: Provider path cannot contain `..` segments',
-                "docs.json packages.isolation: Invalid enum value. Expected 'page' | 'frame', received 'none'",
-            ],
-        ],
-    ])('fails on %s for packages with only the schema errors and no build', async (_, packages, errors) => {
-        await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages });
-        const build = vi.fn();
-        expect(await checkPackages({ docsRoot, build })).toEqual({
-            ok: false,
-            lines: errors.map((message) => ({ level: 'error', message })),
-        });
-        expect(build).not.toHaveBeenCalled();
-    });
-    it('fails without a packages key', async () => {
-        await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs' });
-        const check = await checkPackages({ docsRoot, build: vi.fn() });
-        expect(check.ok).toBe(false);
-        expect(check.lines[0]?.message).toContain('has no "packages" key');
-    });
-});

package/dist/packages/check.d.ts

@@ -1,25 +0,0 @@
-import type { BuildDiagnostic, BuildResult, BuildStats, PackageBuildManifest } from '@mintlify/package-builder';
-import { type CollectedIslands } from './collect.js';
-export type PackagesCheckLine = {
-    level: 'info' | 'warning' | 'error';
-    message: string;
-};
-export type PackagesCheckResult = {
-    ok: boolean;
-    lines: PackagesCheckLine[];
-    collected?: CollectedIslands;
-    manifest?: PackageBuildManifest;
-    stats?: BuildStats;
-};
-export type PackagesCheckOptions = {
-    docsRoot: string;
-    outDir?: string;
-    force?: boolean;
-    build?: (input: Parameters<typeof import('@mintlify/package-builder').build>[0]) => Promise<BuildResult>;
-};
-export declare const formatDiagnostic: ({ pkg, message }: BuildDiagnostic) => string;
-export declare const describeBuild: ({ manifest, stats }: {
-    manifest: PackageBuildManifest;
-    stats: BuildStats;
-}, collected: CollectedIslands) => PackagesCheckLine[];
-export declare const checkPackages: ({ docsRoot, outDir, force, build, }: PackagesCheckOptions) => Promise<PackagesCheckResult>;

package/dist/packages/check.js

@@ -1,132 +0,0 @@
-import { mkdtemp, readdir, rm } from 'fs/promises';
-import { tmpdir } from 'os';
-import { join, resolve } from 'path';
-import { loadPackageBuilder } from './builder.js';
-import { collectPackageIslands, formatProblem } from './collect.js';
-import { errnoCode } from './errno.js';
-import { DocsJsonError, readPackagesSetup } from './setup.js';
-const kb = (bytes) => `${(bytes / 1024).toFixed(1)} KB`;
-const ms = (value) => `${Math.round(value)} ms`;
-const occupied = async (dir) => {
-    try {
-        return (await readdir(dir)).length > 0;
-    }
-    catch (error) {
-        return errnoCode(error) !== 'ENOENT';
-    }
-};
-export const formatDiagnostic = ({ pkg, message }) => `${pkg ? `${pkg}: ` : ''}${message}`;
-const describeImports = (island) => {
-    const byPackage = new Map();
-    for (const { local, pkg } of island?.imports ?? []) {
-        byPackage.set(pkg, [...(byPackage.get(pkg) ?? []), `<${local}>`]);
-    }
-    return [...byPackage].map(([pkg, names]) => `${names.join(', ')} from ${pkg}`).join('; ');
-};
-export const describeBuild = ({ manifest, stats }, collected) => {
-    const info = (message) => ({ level: 'info', message });
-    const specs = new Map(collected.islands.map((island) => [island.id, island]));
-    const lines = [
-        info(`installed ${[
-            `react ${manifest.react.version || '?'}`,
-            `react-dom ${manifest.react.domVersion || '?'}`,
-            ...Object.entries(manifest.packages)
-                .filter(([name]) => name !== 'react' && name !== 'react-dom')
-                .map(([name, { version }]) => `${name} ${version}`),
-        ].join(', ')}`),
-        info(`install ${ms(stats.installMs)}, bundle ${ms(stats.bundleMs)}, render ${ms(stats.renderMs)}, total ${ms(stats.totalMs)}`),
-        info(`${kb(stats.clientGzipBytes)} of browser JS (gzip) across all pages`),
-    ];
-    for (const [page, { ids }] of Object.entries(collected.pages)) {
-        for (const id of new Set(ids)) {
-            const island = manifest.islands[id];
-            if (!island)
-                continue;
-            const gzip = stats.islandClientGzipBytes[id];
-            const parts = [
-                describeImports(specs.get(id)) || 'package component',
-                ...(gzip === undefined ? [] : [`${kb(gzip)} JS (gzip)`]),
-                island.html !== undefined ? 'renders on the server' : 'renders in the browser only',
-            ];
-            lines.push(info(`${page}: ${parts.join(', ')}`));
-        }
-    }
-    for (const d of manifest.diagnostics) {
-        lines.push({ level: d.level, message: formatDiagnostic(d) });
-    }
-    return lines;
-};
-export const checkPackages = async ({ docsRoot, outDir, force, build, }) => {
-    if (outDir && !force && (await occupied(resolve(outDir)))) {
-        return {
-            ok: false,
-            lines: [
-                {
-                    level: 'error',
-                    message: `${resolve(outDir)} already exists and is not an empty folder; use an empty folder or pass --force to replace it.`,
-                },
-            ],
-        };
-    }
-    let setup;
-    try {
-        setup = await readPackagesSetup(docsRoot);
-    }
-    catch (error) {
-        if (!(error instanceof DocsJsonError))
-            throw error;
-        return { ok: false, lines: error.problems.map((message) => ({ level: 'error', message })) };
-    }
-    if (!setup) {
-        return {
-            ok: false,
-            lines: [{ level: 'error', message: `${join(docsRoot, 'docs.json')} has no "packages" key.` }],
-        };
-    }
-    const lines = setup.errors.map((message) => ({ level: 'error', message }));
-    if (setup.packageJsonError)
-        return { ok: false, lines };
-    const collected = await collectPackageIslands({
-        docsRoot,
-        packageNames: setup.packageNames,
-        variables: setup.variables,
-        provider: setup.packages.provider,
-    });
-    const pageCount = Object.values(collected.pages).filter(({ ids }) => ids.length > 0).length;
-    lines.push({
-        level: 'info',
-        message: `${collected.islands.length} package component${collected.islands.length === 1 ? '' : 's'} on ${pageCount} page${pageCount === 1 ? '' : 's'}`,
-    });
-    for (const warning of collected.warnings) {
-        lines.push({ level: 'warning', message: formatProblem(warning) });
-    }
-    for (const error of collected.errors) {
-        lines.push({ level: 'error', message: formatProblem(error) });
-    }
-    if (lines.some((line) => line.level === 'error'))
-        return { ok: false, lines, collected };
-    const run = build ?? (await loadPackageBuilder()).build;
-    const target = outDir ? resolve(outDir) : await mkdtemp(join(tmpdir(), 'mint-packages-check-'));
-    try {
-        const result = await run({
-            docsRoot,
-            packages: setup.packages,
-            islands: collected.islands,
-            snippetFiles: collected.snippetFiles,
-            outDir: target,
-            installer: 'npm-ci',
-        });
-        lines.push(...describeBuild(result, collected));
-        return {
-            ok: result.ok,
-            lines,
-            collected,
-            manifest: result.manifest,
-            stats: result.stats,
-        };
-    }
-    finally {
-        if (!outDir)
-            await rm(target, { recursive: true, force: true });
-    }
-};