@mintlify/package-builder 0.0.0-stage → 0.0.3

package/dist/package-json.js

@@ -0,0 +1,170 @@
+import { lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import semver from 'semver';
+export const DEPENDENCY_FIELDS = [
+    'dependencies',
+    'optionalDependencies',
+    'devDependencies',
+    'peerDependencies',
+];
+const STRIPPED_FIELDS = ['packageManager', 'devEngines'];
+const DIST_TAG = /^[a-z][a-z0-9._-]*$/i;
+const OVERRIDE_REFERENCE = /^\$[@a-z0-9][a-z0-9._/@-]*$/i;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function jsonErrorPosition(err, content) {
+    const match = err instanceof Error ? /position (\d+)/.exec(err.message) : null;
+    if (!match?.[1])
+        return '';
+    const before = content.slice(0, Number(match[1]));
+    const line = before.split('\n').length;
+    const column = before.length - before.lastIndexOf('\n');
+    return ` at line ${line}, column ${column}`;
+}
+export function readPackageJson(docsRoot, { allowSymlink }) {
+    const path = join(docsRoot, 'package.json');
+    let isSymlink;
+    try {
+        isSymlink = lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return {
+            diagnostics: [
+                {
+                    level: 'error',
+                    code: 'package-json-missing',
+                    message: `No package.json in ${docsRoot}.`,
+                },
+            ],
+        };
+    }
+    if (isSymlink && !allowSymlink) {
+        return {
+            diagnostics: [
+                {
+                    level: 'error',
+                    code: 'package-json-symlink',
+                    message: 'package.json is a symbolic link. Commit the file itself in the docs folder.',
+                },
+            ],
+        };
+    }
+    const content = readFileSync(path, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        return {
+            diagnostics: [
+                {
+                    level: 'error',
+                    code: 'package-json-invalid',
+                    message: `package.json is not valid JSON${jsonErrorPosition(err, content)}.`,
+                },
+            ],
+        };
+    }
+    if (!isRecord(parsed)) {
+        return {
+            diagnostics: [
+                { level: 'error', code: 'package-json-invalid', message: 'package.json is not an object.' },
+            ],
+        };
+    }
+    return { packageJson: parsed, diagnostics: [] };
+}
+export function dependencySpecs(packageJson, field) {
+    const deps = packageJson[field];
+    const out = {};
+    if (!isRecord(deps))
+        return out;
+    for (const [name, spec] of Object.entries(deps))
+        if (typeof spec === 'string')
+            out[name] = spec;
+    return out;
+}
+export function specProblem(spec) {
+    const s = spec.trim();
+    if (s.toLowerCase().startsWith('npm:'))
+        return 'is an npm alias, which is not supported';
+    if (semver.validRange(s) !== null)
+        return undefined;
+    if (DIST_TAG.test(s))
+        return undefined;
+    return 'is not a version or version range from a registry';
+}
+function specError(where, name, spec, problem) {
+    return {
+        level: 'error',
+        code: 'package-spec-unsupported',
+        message: `${where} ${name} "${spec}" ${problem}. Only packages published to npm or a private registry are supported.`,
+        pkg: name,
+    };
+}
+function overrideProblems(value, path, out) {
+    if (typeof value === 'string') {
+        const problem = OVERRIDE_REFERENCE.test(value) ? undefined : specProblem(value);
+        if (problem)
+            out.push(specError('overrides', path, value, problem));
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    for (const [key, nested] of Object.entries(value)) {
+        overrideProblems(nested, key === '.' ? path : `${path} > ${key}`, out);
+    }
+}
+export function validatePackageJson(packageJson) {
+    const out = [];
+    for (const field of DEPENDENCY_FIELDS) {
+        for (const [name, spec] of Object.entries(dependencySpecs(packageJson, field))) {
+            const problem = specProblem(spec);
+            if (problem)
+                out.push(specError(field, name, spec, problem));
+        }
+    }
+    if (isRecord(packageJson.overrides)) {
+        for (const [name, value] of Object.entries(packageJson.overrides)) {
+            overrideProblems(value, name, out);
+        }
+    }
+    const pnpm = packageJson.pnpm;
+    if (isRecord(pnpm)) {
+        if (pnpm.patchedDependencies !== undefined) {
+            out.push({
+                level: 'error',
+                code: 'package-patches-unsupported',
+                message: 'pnpm.patchedDependencies is not supported. Publish a patched version instead.',
+            });
+        }
+        if (isRecord(pnpm.overrides)) {
+            for (const [name, value] of Object.entries(pnpm.overrides)) {
+                overrideProblems(value, `pnpm.overrides ${name}`, out);
+            }
+        }
+        if (isRecord(pnpm.packageExtensions)) {
+            for (const [target, extension] of Object.entries(pnpm.packageExtensions)) {
+                if (!isRecord(extension))
+                    continue;
+                for (const field of ['dependencies', 'optionalDependencies', 'peerDependencies']) {
+                    for (const [name, spec] of Object.entries(dependencySpecs(extension, field))) {
+                        const problem = specProblem(spec);
+                        if (problem)
+                            out.push(specError(`pnpm.packageExtensions ${target}`, name, spec, problem));
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}
+export function cleanPackageJson(packageJson) {
+    const cleaned = {};
+    for (const [key, value] of Object.entries(packageJson)) {
+        if (!STRIPPED_FIELDS.includes(key))
+            cleaned[key] = value;
+    }
+    return `${JSON.stringify(cleaned, null, 2)}\n`;
+}

package/dist/package-manager.d.ts

@@ -0,0 +1,17 @@
+export type PackageManager = 'npm' | 'pnpm';
+export type SpawnHost = {
+    platform: NodeJS.Platform;
+    execPath: string;
+    env: NodeJS.ProcessEnv;
+    isFile(path: string): boolean;
+};
+export type PackageManagerCommand = {
+    ok: true;
+    command: string;
+    args: string[];
+} | {
+    ok: false;
+    message: string;
+};
+export declare function currentHost(): SpawnHost;
+export declare function resolvePackageManager(pm: PackageManager, host?: SpawnHost): PackageManagerCommand;

package/dist/package-manager.js

@@ -0,0 +1,87 @@
+import { statSync } from 'node:fs';
+import { win32 } from 'node:path';
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function currentHost() {
+    return { platform: process.platform, execPath: process.execPath, env: process.env, isFile };
+}
+const EXEC_PATH_ENTRY = {
+    npm: /^npm-cli\.js$/i,
+    pnpm: /^pnpm\.(c?js|mjs|exe)$/i,
+};
+const NPM_CLI = 'node_modules/npm/bin/npm-cli.js';
+const SHIM_TARGETS = {
+    npm: [NPM_CLI],
+    pnpm: [
+        'node_modules/pnpm/pnpm.exe',
+        'node_modules/@pnpm/exe/pnpm.exe',
+        'node_modules/pnpm/bin/pnpm.cjs',
+        'node_modules/pnpm/bin/pnpm.mjs',
+        'node_modules/corepack/dist/pnpm.js',
+    ],
+};
+function shimRoot(dir) {
+    const parent = win32.dirname(dir);
+    const inBin = win32.basename(dir).toLowerCase() === '.bin' &&
+        win32.basename(parent).toLowerCase() === 'node_modules';
+    return inBin ? win32.dirname(parent) : dir;
+}
+function envValue(env, name) {
+    const key = Object.keys(env).find((k) => k.toUpperCase() === name.toUpperCase());
+    return key === undefined ? undefined : env[key];
+}
+function entryCommand(host, entry) {
+    return /\.exe$/i.test(entry)
+        ? { ok: true, command: entry, args: [] }
+        : { ok: true, command: host.execPath, args: [entry] };
+}
+function resolveOnWindows(pm, host) {
+    const execPathEntry = envValue(host.env, 'npm_execpath');
+    if (execPathEntry &&
+        win32.isAbsolute(execPathEntry) &&
+        EXEC_PATH_ENTRY[pm].test(win32.basename(execPathEntry)) &&
+        host.isFile(execPathEntry)) {
+        return entryCommand(host, execPathEntry);
+    }
+    const dirs = (envValue(host.env, 'PATH') ?? '')
+        .split(';')
+        .map((dir) => dir.trim().replace(/^"(.*)"$/, '$1'))
+        .filter((dir) => dir && win32.isAbsolute(dir));
+    for (const dir of dirs) {
+        const exe = win32.join(dir, `${pm}.exe`);
+        if (host.isFile(exe))
+            return { ok: true, command: exe, args: [] };
+        if (!host.isFile(win32.join(dir, `${pm}.cmd`)))
+            continue;
+        const root = shimRoot(dir);
+        for (const target of SHIM_TARGETS[pm]) {
+            const entry = win32.join(root, target);
+            if (host.isFile(entry))
+                return entryCommand(host, entry);
+        }
+    }
+    if (pm === 'npm') {
+        const bundled = win32.join(win32.dirname(host.execPath), NPM_CLI);
+        if (host.isFile(bundled))
+            return entryCommand(host, bundled);
+        return {
+            ok: false,
+            message: `Could not find npm. On Windows npm runs as node npm-cli.js, without a shell, and no npm-cli.js was found from PATH or next to ${host.execPath}.`,
+        };
+    }
+    return {
+        ok: false,
+        message: 'Could not find pnpm. On Windows pnpm runs without a shell, so it needs pnpm.exe on PATH or a pnpm.cmd from npm, Corepack or node_modules/.bin next to its pnpm.exe, pnpm.cjs or pnpm.mjs.',
+    };
+}
+export function resolvePackageManager(pm, host = currentHost()) {
+    if (host.platform !== 'win32')
+        return { ok: true, command: pm, args: [] };
+    return resolveOnWindows(pm, host);
+}

package/dist/react.d.ts

@@ -0,0 +1,37 @@
+import type { Metafile, Plugin } from 'esbuild';
+import type { BuildDiagnostic } from './types.js';
+export declare const SKIP_PLUGINS = "mint-skip";
+export type ReactInfo = {
+    version: string;
+    domVersion: string;
+    reactDir: string;
+    reactDomDir: string;
+};
+export declare const REACT_SPECIFIER: RegExp;
+export declare function isSkipped(pluginData: unknown): boolean;
+export declare const skipData: {
+    "mint-skip": boolean;
+};
+export declare function readReactInfo(installRoot: string): {
+    info?: ReactInfo;
+    diagnostics: BuildDiagnostic[];
+};
+export declare function checkReactVersions(version: string, domVersion: string): BuildDiagnostic[];
+export declare function packageOfPath(path: string): {
+    name: string;
+    dir: string;
+} | undefined;
+export type ReplacedReact = {
+    pkg: string;
+    dir: string;
+    version?: string;
+};
+export declare function singleReactPlugin(opts: {
+    installRoot: string;
+    onReplaced: (replaced: ReplacedReact) => void;
+}): Plugin;
+export declare const NAMESPACED: RegExp;
+export declare function checkDuplicateReact(metafile: Metafile, absWorkingDir: string, label: string): BuildDiagnostic[];
+export declare function reactPackageDirs(metafile: Metafile, absWorkingDir: string): Record<string, string[]>;
+export declare function scanRemovedApis(metafile: Metafile, absWorkingDir: string, reactVersion: string): BuildDiagnostic[];
+export declare function checkPeerRanges(metafile: Metafile, absWorkingDir: string, info: Pick<ReactInfo, 'version' | 'domVersion'>): BuildDiagnostic[];

package/dist/react.js

@@ -0,0 +1,264 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { majorOf, satisfies } from './semver.js';
+export const SKIP_PLUGINS = 'mint-skip';
+export const REACT_SPECIFIER = /^(react|react-dom)(\/.*)?$/;
+export function isSkipped(pluginData) {
+    return (typeof pluginData === 'object' &&
+        pluginData !== null &&
+        pluginData[SKIP_PLUGINS] === true);
+}
+export const skipData = { [SKIP_PLUGINS]: true };
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readReactInfo(installRoot) {
+    const diagnostics = [];
+    const dirs = {};
+    const versions = {};
+    for (const name of ['react', 'react-dom']) {
+        const dir = join(installRoot, 'node_modules', name);
+        const pkg = existsSync(dir) ? readJson(join(dir, 'package.json')) : undefined;
+        if (!pkg || typeof pkg.version !== 'string') {
+            diagnostics.push({
+                level: 'error',
+                code: 'react-missing',
+                message: `${name} is not installed. Add react and react-dom (18.x or 19.x) to package.json dependencies.`,
+                pkg: name,
+            });
+            continue;
+        }
+        dirs[name] = realpathSync(dir);
+        versions[name] = pkg.version;
+    }
+    const version = versions['react'];
+    const domVersion = versions['react-dom'];
+    const reactDir = dirs['react'];
+    const reactDomDir = dirs['react-dom'];
+    if (!version || !domVersion || !reactDir || !reactDomDir)
+        return { diagnostics };
+    return { info: { version, domVersion, reactDir, reactDomDir }, diagnostics };
+}
+export function checkReactVersions(version, domVersion) {
+    const out = [];
+    const major = majorOf(version);
+    const domMajor = majorOf(domVersion);
+    for (const [name, v, m] of [
+        ['react', version, major],
+        ['react-dom', domVersion, domMajor],
+    ]) {
+        if (m === undefined || m < 18) {
+            out.push({
+                level: 'error',
+                code: 'react-unsupported-version',
+                message: `${name} ${v} is not supported. Islands need React 18.x or 19.x.`,
+                pkg: name,
+            });
+        }
+    }
+    if (out.length > 0 || version === domVersion)
+        return out;
+    if (major !== domMajor || (major !== undefined && major >= 19)) {
+        out.push({
+            level: 'error',
+            code: 'react-version-mismatch',
+            message: `react ${version} and react-dom ${domVersion} must be the exact same version (React ${major}.x throws "Incompatible React versions" at render). Pin both to the same version.`,
+            pkg: 'react-dom',
+        });
+    }
+    else {
+        out.push({
+            level: 'warning',
+            code: 'react-version-mismatch',
+            message: `react ${version} and react-dom ${domVersion} differ. React 18 tolerates this, but pin both to the same version.`,
+            pkg: 'react-dom',
+        });
+    }
+    return out;
+}
+export function packageOfPath(path) {
+    const normalized = path.replace(/\\/g, '/');
+    const withSlash = normalized.startsWith('/') ? normalized : `/${normalized}`;
+    const idx = withSlash.lastIndexOf('/node_modules/');
+    if (idx === -1)
+        return undefined;
+    const rest = withSlash.slice(idx + '/node_modules/'.length);
+    const parts = rest.split('/');
+    const name = rest.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+    if (!name)
+        return undefined;
+    const dir = withSlash.slice(0, idx + '/node_modules/'.length) + name;
+    return { name, dir: normalized.startsWith('/') ? dir : dir.slice(1) };
+}
+export function singleReactPlugin(opts) {
+    return {
+        name: 'mint-single-react',
+        setup(build) {
+            build.onResolve({ filter: REACT_SPECIFIER }, async (args) => {
+                if (isSkipped(args.pluginData))
+                    return undefined;
+                const aliased = await build.resolve(args.path, {
+                    kind: args.kind,
+                    resolveDir: opts.installRoot,
+                    pluginData: skipData,
+                });
+                if (aliased.errors.length > 0) {
+                    return {
+                        errors: [
+                            {
+                                text: `Could not resolve "${args.path}" from the docs project's node_modules. Add react and react-dom to package.json dependencies.`,
+                            },
+                        ],
+                    };
+                }
+                if (/[\\/]node_modules[\\/]/.test(args.importer)) {
+                    const natural = await build.resolve(args.path, {
+                        kind: args.kind,
+                        resolveDir: args.resolveDir,
+                        pluginData: skipData,
+                    });
+                    const naturalPkg = natural.errors.length === 0 ? packageOfPath(natural.path) : undefined;
+                    const aliasedPkg = packageOfPath(aliased.path);
+                    const importerPkg = packageOfPath(args.importer);
+                    if (naturalPkg && aliasedPkg && importerPkg && naturalPkg.dir !== aliasedPkg.dir) {
+                        const nested = readJson(join(naturalPkg.dir, 'package.json'));
+                        opts.onReplaced({
+                            pkg: importerPkg.name,
+                            dir: naturalPkg.dir,
+                            version: typeof nested?.version === 'string' ? nested.version : undefined,
+                        });
+                    }
+                }
+                return { path: aliased.path, sideEffects: aliased.sideEffects };
+            });
+        },
+    };
+}
+export const NAMESPACED = /^(?![A-Za-z]:[\\/])[^\\/]+:/;
+function inputPackages(metafile, absWorkingDir) {
+    const byDir = new Map();
+    for (const input of Object.keys(metafile.inputs)) {
+        if (NAMESPACED.test(input))
+            continue;
+        const pkg = packageOfPath(input);
+        if (!pkg)
+            continue;
+        const dir = resolve(absWorkingDir, pkg.dir);
+        const declared = readJson(join(dir, 'package.json'))?.name;
+        const name = typeof declared === 'string' ? declared : pkg.name;
+        const entry = byDir.get(dir) ?? { name, dir, files: [] };
+        entry.files.push(resolve(absWorkingDir, input));
+        byDir.set(dir, entry);
+    }
+    return [...byDir.values()];
+}
+const REACT_BUILD = /^(react|react-dom(?:-[a-z]+)*)\.(production|development|profiling)(\.min)?\.js$/;
+function vendoredBuild(file, name) {
+    const built = REACT_BUILD.exec(basename(file))?.[1];
+    if (built === undefined)
+        return false;
+    return name === 'react' ? built === 'react' : built.startsWith('react-dom');
+}
+export function checkDuplicateReact(metafile, absWorkingDir, label) {
+    const out = [];
+    const pkgs = inputPackages(metafile, absWorkingDir);
+    for (const name of ['react', 'react-dom']) {
+        const reactDirs = pkgs.filter((p) => p.name === name).map((p) => p.dir);
+        const vendored = pkgs
+            .filter((p) => p.name !== 'react' && p.name !== 'react-dom')
+            .filter((p) => p.files.some((file) => vendoredBuild(file, name)))
+            .map((p) => `${p.dir} (bundled into ${p.name})`);
+        const dirs = [...reactDirs, ...vendored];
+        if (dirs.length > 1) {
+            out.push({
+                level: 'error',
+                code: 'react-duplicate',
+                message: `The ${label} bundle contains ${dirs.length} copies of ${name}: ${dirs.join(', ')}. Islands need exactly one React.`,
+                pkg: name,
+            });
+        }
+    }
+    return out;
+}
+export function reactPackageDirs(metafile, absWorkingDir) {
+    const pkgs = inputPackages(metafile, absWorkingDir);
+    return {
+        react: pkgs.filter((p) => p.name === 'react').map((p) => p.dir),
+        'react-dom': pkgs.filter((p) => p.name === 'react-dom').map((p) => p.dir),
+    };
+}
+const REACT_OWN_PACKAGES = new Set(['react', 'react-dom', 'scheduler', 'react-is']);
+const REMOVED_APIS = [
+    { pattern: /\bfindDOMNode\b/, api: 'findDOMNode' },
+    {
+        pattern: /\b(?:ReactDOM|ReactDom|_reactDom)\.(?:render|hydrate|unmountComponentAtNode)\s*\(/,
+        api: 'ReactDOM.render',
+    },
+    { pattern: /\.defaultProps\s*=(?!=)/, api: '.defaultProps =' },
+];
+export function scanRemovedApis(metafile, absWorkingDir, reactVersion) {
+    const major = majorOf(reactVersion);
+    if (major === undefined || major < 19)
+        return [];
+    const out = [];
+    for (const pkg of inputPackages(metafile, absWorkingDir)) {
+        if (REACT_OWN_PACKAGES.has(pkg.name))
+            continue;
+        const found = new Set();
+        for (const file of pkg.files) {
+            let src;
+            try {
+                src = readFileSync(file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            for (const { pattern, api } of REMOVED_APIS) {
+                if (!found.has(api) && pattern.test(src))
+                    found.add(api);
+            }
+            if (found.size === REMOVED_APIS.length)
+                break;
+        }
+        if (found.size > 0) {
+            out.push({
+                level: 'warning',
+                code: 'react-removed-api',
+                message: `${pkg.name} uses APIs that React ${major} removed (${[...found].join(', ')}). It may crash or render wrong output; pin React 18 if it does.`,
+                pkg: pkg.name,
+            });
+        }
+    }
+    return out;
+}
+export function checkPeerRanges(metafile, absWorkingDir, info) {
+    const out = [];
+    const installed = { react: info.version, 'react-dom': info.domVersion };
+    for (const pkg of inputPackages(metafile, absWorkingDir)) {
+        if (REACT_OWN_PACKAGES.has(pkg.name))
+            continue;
+        const json = readJson(join(pkg.dir, 'package.json'));
+        const peers = json?.peerDependencies;
+        if (typeof peers !== 'object' || peers === null)
+            continue;
+        for (const [peer, version] of Object.entries(installed)) {
+            const range = peers[peer];
+            if (typeof range !== 'string')
+                continue;
+            if (satisfies(version, range) === false) {
+                out.push({
+                    level: 'warning',
+                    code: 'react-peer-range',
+                    message: `${pkg.name}@${String(json?.version ?? '?')} declares peer ${peer}@"${range}", which excludes the installed ${peer} ${version}.`,
+                    pkg: pkg.name,
+                });
+            }
+        }
+    }
+    return out;
+}

package/dist/render.d.ts

@@ -0,0 +1,37 @@
+export declare const ISLAND_RENDER_TIMEOUT_MS = 3000;
+export type RenderRequest = {
+    id: string;
+    prefix: string;
+};
+export declare function permissionArgs(readable: string[], flags?: ReadonlySet<string>): string[];
+export declare function disabledModuleArgs(flags?: ReadonlySet<string>): string[];
+export declare function sandboxAvailable(flags?: ReadonlySet<string>): boolean;
+export declare const ISLAND_RENDER_MEMORY_LIMIT_BYTES: number;
+export declare function sandboxArgs(args: string[], probe: () => Promise<boolean>, platform?: NodeJS.Platform): Promise<string[]>;
+export type RenderOutcome = {
+    id: string;
+    ok: true;
+    html: string;
+    second?: string;
+    ssrMs: number;
+    importMs: number;
+    errors: string[];
+    warnings: string[];
+} | {
+    id: string;
+    ok: false;
+    error: string;
+    errors: string[];
+    warnings: string[];
+};
+type RenderOptions = {
+    serverDir: string;
+    islands: RenderRequest[];
+    timeoutMs?: number;
+    memoryLimitBytes?: number;
+    requireSandbox?: boolean;
+    platform?: NodeJS.Platform;
+};
+export declare function renderEach(opts: RenderOptions): AsyncGenerator<RenderOutcome>;
+export declare function renderIslands(opts: RenderOptions): Promise<RenderOutcome[]>;
+export {};