@mintlify/previewing 4.0.1461 → 4.0.1462

package/dist/packages/collect.js

@@ -0,0 +1,240 @@
+import { classifyPackageSources, extractImportSources, extractPagePackageIslands, findAndRemoveImports, findPackageSnippets, getAST, hasImports, isPackageSnippetPath, isSnippetExtension, mergePackageIslands, parseFrontmatter, replaceVariables, resolveAllImports, resolveImportPath, resolveSnippetImports, stringifyTree, } from '@mintlify/common';
+import { createPage, getFileListSync, getMintIgnore } from '@mintlify/prebuild';
+import { readFile } from 'fs/promises';
+import { extname, join, sep } from 'path';
+export const formatProblem = ({ file, line, message }) => `${file}${line === undefined ? '' : `:${line}`} ${message}`;
+const withSlash = (filename) => (filename.startsWith('/') ? filename : `/${filename}`);
+const displayPath = (filename) => filename.replace(/^\/+/, '');
+const mayImport = (content) => /\bimport\b/.test(content);
+const parseOrUndefined = (content, filename) => {
+    try {
+        return getAST(content, filename);
+    }
+    catch {
+        return undefined;
+    }
+};
+const readSources = async (docsRoot, mintIgnore) => {
+    const filenames = getFileListSync(docsRoot, docsRoot, mintIgnore)
+        .filter((filename) => isSnippetExtension(extname(filename).slice(1)))
+        .sort();
+    const sources = await Promise.all(filenames.map(async (filename) => {
+        const content = await readFile(join(docsRoot, filename), 'utf8').catch(() => undefined);
+        return content === undefined ? [] : [{ path: displayPath(filename), content }];
+    }));
+    return sources.flat();
+};
+const createLegacySnippetTreeMap = async (snippets, variables) => {
+    if (snippets.length === 0)
+        return {};
+    const { createPackageSnippetTreeMap } = await import('@mintlify/common/server-mdx');
+    return createPackageSnippetTreeMap(snippets, variables);
+};
+const resolveSnippets = async (snippets, variables, packages, onWarning) => {
+    const parsed = [];
+    for (const { filename, content } of snippets) {
+        const tree = parseOrUndefined(replaceVariables(content, variables), filename);
+        if (tree)
+            parsed.push({ ...(await findAndRemoveImports(tree)), filename });
+    }
+    return resolveSnippetImports(parsed, {
+        packages,
+        onWarning: (warning, filename) => onWarning(filename, warning.message),
+        skip: (filename) => packages.packageSnippets?.has(filename) ?? false,
+    });
+};
+export const resolvePageContent = async ({ page, docsRoot, snippets, packages, onWarning, }) => {
+    const tree = parseOrUndefined(page.content, page.filename);
+    if (!tree)
+        return undefined;
+    const importsResponse = await findAndRemoveImports(tree);
+    const content = hasImports(importsResponse)
+        ? stringifyTree(await resolveAllImports({
+            snippets,
+            fileWithImports: { ...importsResponse, filename: page.filename },
+            onWarning: (warning) => onWarning?.(warning.message),
+            packages,
+        }))
+        : page.content;
+    const { pageContent } = await createPage(displayPath(page.filename), content, docsRoot, [], [], () => { });
+    return parseFrontmatter(pageContent).body;
+};
+export class PackageIslandCollector {
+    constructor(input) {
+        this.input = input;
+        this.snippetSources = [];
+        this.snippets = [];
+        this.snippetTreeMap = {};
+        this.packageSnippets = new Set();
+        this.packageSnippetTrees = new Map();
+        this.pageEntries = new Map();
+        this.warnings = [];
+        this.providerErrors = [];
+        this.snippetErrors = [];
+        this.snippetFiles = {};
+        this.queue = Promise.resolve();
+        this.warn = (file, message) => {
+            if (!this.warnings.some((warning) => warning.message === message)) {
+                this.warnings.push({ file: displayPath(file), message });
+            }
+        };
+    }
+    get packages() {
+        return { packageNames: this.input.packageNames, packageSnippets: this.packageSnippets };
+    }
+    inheritSnippetTrees(previous) {
+        if (previous.input.docsRoot !== this.input.docsRoot)
+            return;
+        this.queue = Promise.all([this.queue, previous.queue]).then(() => {
+            this.packageSnippetTrees = new Map(previous.packageSnippetTrees);
+        });
+    }
+    collectAll() {
+        return this.enqueue(() => this.collectAllNow());
+    }
+    updatePage(filename) {
+        return this.enqueue(() => this.updatePageNow(filename));
+    }
+    enqueue(operation) {
+        const run = this.queue.then(operation);
+        this.queue = run.catch(() => { });
+        return run;
+    }
+    classify(files) {
+        return classifyPackageSources(files, {
+            packageNames: this.input.packageNames,
+            variables: this.input.variables,
+        });
+    }
+    async collectAllNow() {
+        const { docsRoot, variables, provider } = this.input;
+        const files = await readSources(docsRoot, this.input.mintIgnore ?? (await getMintIgnore(docsRoot)));
+        const classified = this.classify(files);
+        const snippetPaths = new Set([
+            ...classified.snippets.map(({ path }) => path),
+            ...classified.unparsed.flatMap(({ path, category }) => (category === 'snippet' ? path : [])),
+        ]);
+        this.snippetSources = files
+            .filter(({ path }) => snippetPaths.has(path))
+            .map(({ path, content }) => ({ filename: withSlash(path), content }));
+        this.snippetTreeMap = await createLegacySnippetTreeMap(classified.legacySnippets, variables);
+        const previousTrees = this.packageSnippetTrees;
+        const parsedTrees = new Map(classified.snippets.map(({ path, tree }) => [path, tree]));
+        this.packageSnippetTrees = new Map();
+        for (const { filename } of this.snippetSources) {
+            if (!isPackageSnippetPath(filename))
+                continue;
+            const tree = parsedTrees.get(displayPath(filename)) ?? previousTrees.get(filename);
+            if (tree)
+                this.packageSnippetTrees.set(filename, tree);
+        }
+        this.packageSnippets = findPackageSnippets([...this.packageSnippetTrees].map(([filename, tree]) => ({ filename, tree })));
+        this.warnings = [];
+        this.snippets = await resolveSnippets(this.snippetSources, variables, this.packages, this.warn);
+        const sourceErrors = new Map();
+        for (const error of classified.errors) {
+            sourceErrors.set(error.file, [...(sourceErrors.get(error.file) ?? []), error]);
+        }
+        this.pageEntries = new Map();
+        for (const page of classified.pages)
+            await this.extractPage(page, sourceErrors.get(page.path));
+        for (const { path, content, category } of classified.unparsed) {
+            if (category === 'page')
+                await this.extractPage({ path, content }, sourceErrors.get(path));
+        }
+        this.snippetErrors = classified.errors.filter(({ file }) => !this.pageEntries.has(file));
+        this.snippetFiles = {};
+        for (const path of [...this.packageSnippets].sort()) {
+            const source = this.snippetSources.find(({ filename }) => filename === path);
+            if (source)
+                this.snippetFiles[path] = source.content;
+        }
+        this.providerErrors = [];
+        if (provider !== undefined) {
+            try {
+                this.snippetFiles[provider] = await readFile(join(docsRoot, provider), 'utf8');
+            }
+            catch {
+                this.providerErrors.push({
+                    file: 'docs.json',
+                    message: `packages.provider ${provider} was not found.`,
+                });
+            }
+        }
+        return this.result();
+    }
+    async updatePageNow(filename) {
+        const path = displayPath(filename.split(sep).join('/'));
+        if (!this.pageEntries.has(path))
+            return this.collectAllNow();
+        let content;
+        try {
+            content = await readFile(join(this.input.docsRoot, path), 'utf8');
+        }
+        catch {
+            this.pageEntries.delete(path);
+            return this.result();
+        }
+        const tree = parseOrUndefined(content, withSlash(path));
+        const importsPages = (tree ? extractImportSources(tree) : []).some((source) => {
+            const resolved = resolveImportPath(source, withSlash(path));
+            return resolved !== null && this.pageEntries.has(displayPath(resolved));
+        });
+        if (importsPages)
+            return this.collectAllNow();
+        await this.extractPage({ path, content }, this.classify([{ path, content }]).errors);
+        return this.result();
+    }
+    result() {
+        const entries = [...this.pageEntries.entries()].sort(([a], [b]) => a.localeCompare(b));
+        const pages = {};
+        for (const [file, entry] of entries)
+            pages[file] = { ids: entry.ids, errors: entry.errors };
+        return {
+            islands: mergePackageIslands(entries.map(([, entry]) => entry)).islands,
+            errors: [
+                ...entries.flatMap(([, entry]) => entry.errors),
+                ...this.snippetErrors,
+                ...this.providerErrors,
+            ],
+            warnings: [...this.warnings],
+            packageSnippets: new Set(this.packageSnippets),
+            snippetFiles: { ...this.snippetFiles },
+            pages,
+        };
+    }
+    async extractPage(page, sourceErrors = []) {
+        const { path } = page;
+        const content = replaceVariables(page.content, this.input.variables);
+        const noIslands = { ids: [], islands: [], errors: sourceErrors };
+        if (!mayImport(content) && !content.includes('<Snippet')) {
+            this.pageEntries.set(path, noIslands);
+            return;
+        }
+        const body = await resolvePageContent({
+            page: { filename: withSlash(path), content: page.content },
+            docsRoot: this.input.docsRoot,
+            snippets: this.snippets,
+            packages: this.packages,
+            onWarning: (message) => this.warn(path, message),
+        });
+        if (body === undefined) {
+            this.pageEntries.set(path, noIslands);
+            return;
+        }
+        const extraction = extractPagePackageIslands({
+            path,
+            content: body,
+            packageNames: this.input.packageNames,
+            packageSnippets: this.packageSnippets,
+            variables: this.input.variables,
+            snippetTreeMap: this.snippetTreeMap,
+        });
+        this.pageEntries.set(path, {
+            ids: extraction.ids,
+            islands: extraction.islands,
+            errors: [...sourceErrors, ...extraction.errors],
+        });
+    }
+}
+export const collectPackageIslands = (input) => new PackageIslandCollector(input).collectAll();

package/dist/packages/errno.d.ts

@@ -0,0 +1 @@
+export declare const errnoCode: (error: unknown) => string | undefined;

package/dist/packages/errno.js

@@ -0,0 +1,3 @@
+export const errnoCode = (error) => error instanceof Error && 'code' in error && typeof error.code === 'string'
+    ? error.code
+    : undefined;

package/dist/packages/flag.d.ts

@@ -0,0 +1 @@
+export declare const isNativePackagesEnabled: () => boolean;

package/dist/packages/flag.js

@@ -0,0 +1 @@
+export const isNativePackagesEnabled = () => process.env.MINTLIFY_NATIVE_NPM_PACKAGES === '1';

package/dist/packages/index.d.ts

@@ -0,0 +1,4 @@
+export { checkPackages, describeBuild, type PackagesCheckLine, type PackagesCheckOptions, type PackagesCheckResult, } from './check.js';
+export { collectPackageIslands, PackageIslandCollector, resolvePageContent, type CollectedIslands, type CollectPackageIslandsInput, type PackageIslandProblem, type PageIslands, } from './collect.js';
+export { isNativePackagesEnabled } from './flag.js';
+export { normalizeProviderPath, readPackagesSetup, type PackagesSetup } from './setup.js';

package/dist/packages/index.js

@@ -0,0 +1,4 @@
+export { checkPackages, describeBuild, } from './check.js';
+export { collectPackageIslands, PackageIslandCollector, resolvePageContent, } from './collect.js';
+export { isNativePackagesEnabled } from './flag.js';
+export { normalizeProviderPath, readPackagesSetup } from './setup.js';

package/dist/packages/setup.d.ts

@@ -0,0 +1,16 @@
+import { type PackagesConfig } from '@mintlify/validation';
+export type PackagesSetup = {
+    packages: PackagesConfig;
+    packageNames: Set<string>;
+    variables?: Record<string, string>;
+    errors: string[];
+    packageJsonError?: string;
+};
+export declare class DocsJsonError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+export declare class InvalidPackagesError extends DocsJsonError {
+}
+export declare const normalizeProviderPath: (provider: string) => string;
+export declare const readPackagesSetup: (docsRoot: string) => Promise<PackagesSetup | undefined>;

package/dist/packages/setup.js

@@ -0,0 +1,77 @@
+import { parsePackageJsonDependencies } from '@mintlify/common';
+import { getConfigObj } from '@mintlify/prebuild';
+import { packagesSchema } from '@mintlify/validation';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { errnoCode } from './errno.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export class DocsJsonError extends Error {
+    constructor(problems) {
+        super(problems.join('\n'));
+        this.problems = problems;
+    }
+}
+export class InvalidPackagesError extends DocsJsonError {
+}
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+const readText = async (path) => {
+    try {
+        return { content: await readFile(path, 'utf8') };
+    }
+    catch (error) {
+        if (errnoCode(error) === 'ENOENT')
+            return {};
+        return { error: `could not be read: ${messageOf(error)}` };
+    }
+};
+export const normalizeProviderPath = (provider) => `/${provider.replace(/\\/g, '/').replace(/^\/+/, '')}`;
+const readVariables = (value) => {
+    if (!isRecord(value))
+        return undefined;
+    const variables = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry === 'string')
+            variables[key] = entry;
+    }
+    return variables;
+};
+export const readPackagesSetup = async (docsRoot) => {
+    let docsConfig;
+    try {
+        docsConfig = await getConfigObj(docsRoot, 'docs');
+    }
+    catch (error) {
+        throw new DocsJsonError([`docs.json could not be loaded: ${messageOf(error)}`]);
+    }
+    if (docsConfig === null)
+        return undefined;
+    if (!isRecord(docsConfig))
+        throw new DocsJsonError(['docs.json is not a JSON object']);
+    if (!('packages' in docsConfig))
+        return undefined;
+    const parsed = packagesSchema.safeParse(docsConfig.packages);
+    if (!parsed.success) {
+        throw new InvalidPackagesError(parsed.error.issues.map((issue) => `docs.json ${['packages', ...issue.path].join('.')}: ${issue.message}`));
+    }
+    const packages = parsed.data;
+    if (packages.provider !== undefined)
+        packages.provider = normalizeProviderPath(packages.provider);
+    const errors = [];
+    const packageJson = await readText(join(docsRoot, 'package.json'));
+    const dependencies = packageJson.content === undefined
+        ? undefined
+        : parsePackageJsonDependencies(packageJson.content);
+    const problem = packageJson.error ?? dependencies?.error;
+    const packageJsonError = problem && `package.json ${problem}`;
+    if (packageJsonError)
+        errors.push(packageJsonError);
+    else if (!dependencies)
+        errors.push('docs.json sets "packages" but there is no package.json next to it.');
+    return {
+        packages,
+        packageNames: dependencies?.error ? new Set() : (dependencies?.packageNames ?? new Set()),
+        variables: readVariables(docsConfig.variables),
+        errors,
+        ...(packageJsonError && { packageJsonError }),
+    };
+};