@mintlify/package-builder 0.0.0-stage → 0.0.2

package/dist/local-files.d.ts

@@ -0,0 +1,11 @@
+import type { IslandSpec } from './types.js';
+export type LocalFiles = Record<string, string | Uint8Array>;
+export type LocalFilesInput = {
+    docsRoot: string;
+    islands: Pick<IslandSpec, 'module'>[];
+    snippetFiles: Record<string, string>;
+    provider?: string;
+    rejectHardLinks?: boolean;
+};
+export declare function runtimeImports(files: LocalFiles, islands: Pick<IslandSpec, 'id' | 'pagePath' | 'module'>[]): Promise<string[]>;
+export declare function collectLocalFiles(input: LocalFilesInput): LocalFiles;

package/dist/local-files.js

@@ -0,0 +1,120 @@
+import { transform } from 'esbuild';
+import { randomBytes } from 'node:crypto';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { docsPathToRelative, inside, URL_LIKE } from './bundle.js';
+const SCRIPT = /\.[cm]?[jt]sx?$/;
+const SCRIPT_SPECIFIER = /\b(?:from|import)\s*\(?\s*(['"])([^'"\n]+)\1|\brequire\s*\(\s*(['"])([^'"\n]+)\3/g;
+const CSS_SPECIFIER = /@import\s+(?:url\(\s*)?(['"]?)([^'")\s;]+)\1|\burl\(\s*(['"]?)([^'")\s]+)\3\s*\)/g;
+const LOCAL_SCRIPT_SPECIFIER = /^\.{0,2}\/(?!\/)/;
+const RUNTIME_PATH_CALL = /_(import|require)\(\s*(?:\/\*[\s\S]*?\*\/\s*)*(`\.{0,2}\/(?!\/)[^`]*?\$\{[^`]*`|(?<q>[`'"])\.{0,2}\/(?!\/)[^`'"\n]*\k<q>\s*\+[^)\n]*)/g;
+const EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.css', '.json'];
+const SCRIPT_CANDIDATES = ['', ...EXTENSIONS, ...EXTENSIONS.map((ext) => `/index${ext}`)];
+function specifiers(source, pattern) {
+    return [...source.matchAll(pattern)].flatMap((m) => m[2] ?? m[4] ?? []);
+}
+function text(content) {
+    return typeof content === 'string' ? content : new TextDecoder().decode(content);
+}
+function loaderFor(path) {
+    return path.endsWith('tsx') ? 'tsx' : path.endsWith('ts') ? 'ts' : 'jsx';
+}
+export async function runtimeImports(files, islands) {
+    const sources = [
+        ...Object.entries(files)
+            .filter(([path]) => SCRIPT.test(path))
+            .map(([path, content]) => ({ where: path, loader: loaderFor(path), source: text(content) })),
+        ...islands.map((i) => ({
+            where: `island ${i.id} (${i.pagePath})`,
+            loader: 'jsx',
+            source: i.module,
+        })),
+    ];
+    const mark = `__mint${randomBytes(8).toString('hex')}`;
+    const calls = new RegExp(mark + RUNTIME_PATH_CALL.source, 'g');
+    const found = await Promise.all(sources.map(async ({ where, loader, source }) => {
+        const code = await transform(source, {
+            loader,
+            supported: { 'dynamic-import': false },
+            define: { require: `${mark}_require` },
+        })
+            .then((r) => transform(r.code, { loader: 'js', define: { require: `${mark}_import` } }))
+            .then((r) => r.code, () => '');
+        return [...code.matchAll(calls)].map((m) => `${where}: ${m[1]}(${m[2].replace(/\s+/g, ' ')}) builds its path at runtime; import each file statically.`);
+    }));
+    return found.flat();
+}
+export function collectLocalFiles(input) {
+    const files = { ...input.snippetFiles };
+    let root;
+    try {
+        root = realpathSync(input.docsRoot);
+    }
+    catch {
+        root = undefined;
+    }
+    const read = (rel) => {
+        if (!root || rel.split('/').includes('node_modules'))
+            return undefined;
+        try {
+            const real = realpathSync(join(root, rel));
+            const stat = statSync(real);
+            const linked = input.rejectHardLinks === true && stat.nlink > 1;
+            return inside(root, real) && stat.isFile() && !linked
+                ? new Uint8Array(readFileSync(real))
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const locate = (specifier, importer) => {
+        if (specifier.startsWith('/'))
+            return docsPathToRelative(specifier.replace(/\/+$/, ''));
+        const rel = posix.normalize(posix.join(posix.dirname(importer), specifier)).replace(/\/+$/, '');
+        return rel === '.' || rel === '..' || rel.startsWith('../') ? undefined : rel;
+    };
+    const follow = (specifier, importer, candidates) => {
+        for (const spec of new Set([specifier, specifier.replace(/[?#].*$/, '')])) {
+            const rel = locate(spec, importer);
+            if (rel === undefined)
+                continue;
+            for (const suffix of candidates) {
+                const path = `/${rel}${suffix}`;
+                if (files[path] !== undefined)
+                    return path;
+                const data = read(`${rel}${suffix}`);
+                if (data) {
+                    files[path] = data;
+                    return path;
+                }
+            }
+        }
+        return undefined;
+    };
+    const roots = [
+        ...(input.provider ? [input.provider] : []),
+        ...input.islands.flatMap((i) => specifiers(i.module, SCRIPT_SPECIFIER).filter((s) => /^\/(?!\/)/.test(s))),
+    ].flatMap((specifier) => follow(specifier, '', SCRIPT_CANDIDATES) ?? []);
+    const stack = [...Object.keys(input.snippetFiles), ...roots];
+    const seen = new Set();
+    while (stack.length > 0) {
+        const path = stack.pop();
+        const rel = docsPathToRelative(path);
+        const content = files[path];
+        if (seen.has(path) || rel === undefined || content === undefined)
+            continue;
+        seen.add(path);
+        const css = rel.endsWith('.css');
+        if (!css && !SCRIPT.test(rel))
+            continue;
+        for (const specifier of specifiers(text(content), css ? CSS_SPECIFIER : SCRIPT_SPECIFIER)) {
+            if (css ? URL_LIKE.test(specifier) : !LOCAL_SCRIPT_SPECIFIER.test(specifier))
+                continue;
+            const found = follow(specifier, rel, css ? [''] : SCRIPT_CANDIDATES);
+            if (found)
+                stack.push(found);
+        }
+    }
+    return files;
+}

package/dist/lockfile.d.ts

@@ -0,0 +1,40 @@
+import { type PackageJson } from './package-json.js';
+import type { BuildDiagnostic } from './types.js';
+export declare const NPM_REGISTRY = "https://registry.npmjs.org/";
+export declare const LOCKFILE_NAMES: readonly ["package-lock.json", "pnpm-lock.yaml"];
+export type LockfileName = (typeof LOCKFILE_NAMES)[number];
+export type LockfileKind = 'npm' | 'pnpm';
+export type LockfileValidation = {
+    ok: boolean;
+    kind: LockfileKind;
+    diagnostics: BuildDiagnostic[];
+    topLevel: Record<string, string>;
+    entryCount: number;
+};
+export type FoundLockfile = {
+    fileName: LockfileName;
+    path: string;
+    content: string;
+};
+export declare function lockfileKind(fileName: LockfileName): LockfileKind;
+export declare function findLockfile(dir: string, { allowSymlink }?: {
+    allowSymlink: boolean;
+}): {
+    lockfile?: FoundLockfile;
+    diagnostics: BuildDiagnostic[];
+};
+export declare const NPMRC_COMMENT_OR_ESCAPE: RegExp;
+export declare const NPMRC_COMMENT_OR_ESCAPE_PROBLEM = "a ;, # or \\, which npm reads as a comment or escape in .npmrc";
+export declare function registryProblem(scope: string, url: string): string | undefined;
+export declare function validateRegistries(registries: Record<string, string> | undefined): BuildDiagnostic[];
+export declare function registryFor(name: string, registries: Record<string, string> | undefined): string;
+export declare function parsePnpmKey(key: string): {
+    name: string;
+    version: string;
+};
+export declare function validateLockfile(input: {
+    fileName: LockfileName;
+    content: string;
+    registries?: Record<string, string>;
+    packageJson?: PackageJson;
+}): LockfileValidation;

package/dist/lockfile.js

@@ -0,0 +1,498 @@
+import yaml from 'js-yaml';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { hasErrors } from './diagnostics.js';
+import { DEPENDENCY_FIELDS, dependencySpecs, jsonErrorPosition, } from './package-json.js';
+export const NPM_REGISTRY = 'https://registry.npmjs.org/';
+export const LOCKFILE_NAMES = ['package-lock.json', 'pnpm-lock.yaml'];
+export function lockfileKind(fileName) {
+    return fileName === 'pnpm-lock.yaml' ? 'pnpm' : 'npm';
+}
+export function findLockfile(dir, { allowSymlink } = { allowSymlink: false }) {
+    const diagnostics = [];
+    const present = LOCKFILE_NAMES.filter((name) => existsSync(join(dir, name)));
+    const [first] = present;
+    if (first === undefined) {
+        const message = existsSync(join(dir, 'yarn.lock'))
+            ? 'yarn.lock is not supported. Add a package-lock.json (npm install) or pnpm-lock.yaml next to package.json.'
+            : 'A package-lock.json or pnpm-lock.yaml is required next to package.json.';
+        diagnostics.push({ level: 'error', code: 'lockfile-missing', message });
+        return { diagnostics };
+    }
+    if (present.length > 1) {
+        diagnostics.push({
+            level: 'warning',
+            code: 'lockfile-multiple',
+            message: `Found ${present.join(' and ')}; using ${first}. Delete the one you do not use.`,
+        });
+    }
+    const path = join(dir, first);
+    if (!allowSymlink && lstatSync(path).isSymbolicLink()) {
+        diagnostics.push({
+            level: 'error',
+            code: 'lockfile-symlink',
+            message: `${first} is a symbolic link. Commit the file itself in the docs folder.`,
+        });
+        return { diagnostics };
+    }
+    return { lockfile: { fileName: first, path, content: readFileSync(path, 'utf8') }, diagnostics };
+}
+function classifySource(source) {
+    const s = source.trim().toLowerCase();
+    if (/^(git\+|git:|github:|gitlab:|bitbucket:|gist:)/.test(s)) {
+        return { code: 'lockfile-git-source', what: 'a git source' };
+    }
+    if (s.startsWith('file:'))
+        return { code: 'lockfile-file-source', what: 'a file: source' };
+    if (s.startsWith('link:') || s.startsWith('workspace:')) {
+        return { code: 'lockfile-link-source', what: 'a link: source' };
+    }
+    if (s.startsWith('http:'))
+        return { code: 'lockfile-insecure-source', what: 'an http: URL' };
+    if (s.startsWith('https:'))
+        return undefined;
+    return { code: 'lockfile-unknown-source', what: `an unsupported source (${source})` };
+}
+function scopeOf(name) {
+    if (!name.startsWith('@'))
+        return undefined;
+    const slash = name.indexOf('/');
+    return slash > 0 ? name.slice(0, slash) : undefined;
+}
+function withTrailingSlash(url) {
+    return url.endsWith('/') ? url : `${url}/`;
+}
+const SCOPE = /^@[a-z0-9-~][a-z0-9-._~]*$/;
+const PNPM_RESOLUTION_KEYS = new Set(['integrity', 'tarball']);
+const PNPM_IMPORTER_FIELDS = [
+    'dependencies',
+    'optionalDependencies',
+    'devDependencies',
+];
+function yamlErrorPosition(err) {
+    if (!(err instanceof yaml.YAMLException))
+        return '';
+    const reason = err.reason ? `: ${err.reason}` : '';
+    return `${reason} at line ${err.mark.line + 1}, column ${err.mark.column + 1}`;
+}
+export const NPMRC_COMMENT_OR_ESCAPE = /[;#\\]/;
+export const NPMRC_COMMENT_OR_ESCAPE_PROBLEM = 'a ;, # or \\, which npm reads as a comment or escape in .npmrc';
+function npmrcRewrites(value) {
+    if (value.includes('${'))
+        return '${, which npm expands from environment variables';
+    if (NPMRC_COMMENT_OR_ESCAPE.test(value))
+        return NPMRC_COMMENT_OR_ESCAPE_PROBLEM;
+    return undefined;
+}
+const MAX_REGISTRY_URL_LENGTH = 512;
+const NPMRC_KEY_END = 'which npm reads as the end of the auth token key in .npmrc';
+export function registryProblem(scope, url) {
+    if (!SCOPE.test(scope))
+        return `${scope} is not an npm scope such as @acme.`;
+    if (url.length > MAX_REGISTRY_URL_LENGTH) {
+        return `The registry for ${scope} is longer than ${MAX_REGISTRY_URL_LENGTH} characters.`;
+    }
+    if (/[\s\u0000-\u001f\u007f]/.test(url))
+        return `The registry for ${scope} contains whitespace.`;
+    const rewritten = npmrcRewrites(url);
+    if (rewritten)
+        return `The registry for ${scope} contains ${rewritten}.`;
+    if (!/^https:\/\/[^/]/.test(url)) {
+        return `The registry for ${scope} must start with https:// and then the host.`;
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return `The registry for ${scope} is not a valid URL: ${url}`;
+    }
+    if (parsed.username || parsed.password || url.includes('?') || parsed.hash) {
+        return `The registry for ${scope} must not contain credentials, a query or a fragment.`;
+    }
+    const parsedRewritten = npmrcRewrites(parsed.href);
+    if (parsedRewritten) {
+        return `The registry for ${scope} is read as ${parsed.href} and then contains ${parsedRewritten}.`;
+    }
+    if (parsed.hostname.includes('=')) {
+        return `The registry for ${scope} has an = in the host, ${NPMRC_KEY_END}.`;
+    }
+    if (parsed.pathname.includes('=')) {
+        return `The registry for ${scope} has an = in the path, ${NPMRC_KEY_END}.`;
+    }
+    return undefined;
+}
+export function validateRegistries(registries) {
+    const out = [];
+    for (const [scope, url] of Object.entries(registries ?? {})) {
+        const problem = registryProblem(scope, typeof url === 'string' ? url : String(url));
+        if (problem)
+            out.push({ level: 'error', code: 'registry-invalid', message: problem });
+    }
+    return out;
+}
+export function registryFor(name, registries) {
+    const scope = scopeOf(name);
+    const scoped = scope !== undefined ? registries?.[scope] : undefined;
+    return withTrailingSlash(scoped ?? NPM_REGISTRY);
+}
+function checkHttpsUrl(name, url, registries) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return {
+            level: 'error',
+            code: 'lockfile-unknown-source',
+            message: `${name} has an invalid URL in the lockfile: ${url}`,
+            pkg: name,
+        };
+    }
+    if (parsed.username || parsed.password) {
+        return {
+            level: 'error',
+            code: 'lockfile-credentials',
+            message: `${name} has credentials embedded in its lockfile URL. Remove them and configure the registry token in the dashboard.`,
+            pkg: name,
+        };
+    }
+    const expected = new URL(registryFor(name, registries));
+    if (parsed.protocol !== 'https:' ||
+        parsed.host !== expected.host ||
+        !parsed.pathname.startsWith(expected.pathname)) {
+        const scope = scopeOf(name);
+        const hint = scope !== undefined && registries?.[scope]
+            ? `packages.registries maps ${scope} to ${expected.href}`
+            : scope !== undefined
+                ? `add "${scope}" to packages.registries in docs.json if it comes from a private registry`
+                : 'unscoped packages must come from registry.npmjs.org';
+        return {
+            level: 'error',
+            code: 'lockfile-registry-mismatch',
+            message: `${name} resolves to ${parsed.origin}${parsed.pathname}, which is not its registry (${hint}).`,
+            pkg: name,
+        };
+    }
+    return undefined;
+}
+function sourceError(name, source, problem) {
+    return {
+        level: 'error',
+        code: problem.code,
+        message: `${name} comes from ${problem.what} (${source}). Only registry packages with integrity hashes are supported.`,
+        pkg: name,
+    };
+}
+function missingIntegrity(name) {
+    return {
+        level: 'error',
+        code: 'lockfile-missing-integrity',
+        message: `${name} has no integrity hash in the lockfile. Regenerate it with a current npm or pnpm.`,
+        pkg: name,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nameFromNpmKey(key) {
+    const idx = key.lastIndexOf('node_modules/');
+    return idx === -1 ? key : key.slice(idx + 'node_modules/'.length);
+}
+function validateNpm(content, registries) {
+    const diagnostics = [];
+    const topLevel = {};
+    let lock;
+    try {
+        lock = JSON.parse(content);
+    }
+    catch (err) {
+        diagnostics.push({
+            level: 'error',
+            code: 'lockfile-invalid',
+            message: `package-lock.json is not valid JSON${jsonErrorPosition(err, content)}.`,
+        });
+        return { diagnostics, topLevel, entryCount: 0 };
+    }
+    if (!isRecord(lock)) {
+        diagnostics.push({
+            level: 'error',
+            code: 'lockfile-invalid',
+            message: 'package-lock.json is not an object.',
+        });
+        return { diagnostics, topLevel, entryCount: 0 };
+    }
+    const version = lock.lockfileVersion;
+    if ((version !== 2 && version !== 3) || !isRecord(lock.packages)) {
+        diagnostics.push({
+            level: 'error',
+            code: 'lockfile-unsupported',
+            message: `package-lock.json lockfileVersion ${String(version)} is not supported. Regenerate it with npm 7 or later (lockfileVersion 2 or 3).`,
+        });
+        return { diagnostics, topLevel, entryCount: 0 };
+    }
+    let entryCount = 0;
+    for (const [key, raw] of Object.entries(lock.packages)) {
+        if (key === '' || !isRecord(raw))
+            continue;
+        entryCount++;
+        const entry = raw;
+        const name = typeof entry.name === 'string' ? entry.name : nameFromNpmKey(key);
+        if (!key.includes('node_modules/')) {
+            diagnostics.push({
+                level: 'error',
+                code: 'lockfile-link-source',
+                message: `${key} is a workspace package. Workspaces are not supported; publish the package to a registry.`,
+                pkg: name,
+            });
+            continue;
+        }
+        if (entry.inBundle === true) {
+            if (entry.resolved !== undefined) {
+                diagnostics.push({
+                    level: 'error',
+                    code: 'lockfile-bundled-source',
+                    message: `${name} is marked as bundled in another package but has its own source (${String(entry.resolved)}). Regenerate the lockfile with npm.`,
+                    pkg: name,
+                });
+            }
+            continue;
+        }
+        if (entry.link === true) {
+            const source = typeof entry.resolved === 'string' ? entry.resolved : 'link';
+            diagnostics.push(sourceError(name, source, { code: 'lockfile-link-source', what: 'a linked folder' }));
+            continue;
+        }
+        const isTopLevel = key.startsWith('node_modules/') && key.lastIndexOf('node_modules/') === 0;
+        if (isTopLevel && entry.dev !== true && typeof entry.version === 'string') {
+            topLevel[nameFromNpmKey(key)] = entry.version;
+        }
+        if (typeof entry.resolved === 'string') {
+            const problem = classifySource(entry.resolved);
+            if (problem) {
+                diagnostics.push(sourceError(name, entry.resolved, problem));
+                continue;
+            }
+            const hostProblem = checkHttpsUrl(name, entry.resolved, registries);
+            if (hostProblem)
+                diagnostics.push(hostProblem);
+        }
+        else if (typeof entry.version === 'string') {
+            const problem = classifySource(entry.version);
+            if (problem && problem.code !== 'lockfile-unknown-source') {
+                diagnostics.push(sourceError(name, entry.version, problem));
+                continue;
+            }
+        }
+        if (typeof entry.integrity !== 'string' || entry.integrity.length === 0) {
+            diagnostics.push(missingIntegrity(name));
+        }
+    }
+    return { diagnostics, topLevel, entryCount };
+}
+export function parsePnpmKey(key) {
+    let k = key.startsWith('/') ? key.slice(1) : key;
+    const paren = k.indexOf('(');
+    if (paren !== -1)
+        k = k.slice(0, paren);
+    const at = k.indexOf('@', k.startsWith('@') ? 1 : 0);
+    if (at === -1)
+        return { name: k, version: '' };
+    return { name: k.slice(0, at), version: k.slice(at + 1) };
+}
+function stripPeerSuffix(version) {
+    const paren = version.indexOf('(');
+    return paren === -1 ? version : version.slice(0, paren);
+}
+function validatePnpm(content, registries) {
+    const diagnostics = [];
+    const topLevel = {};
+    let lock;
+    try {
+        lock = yaml.load(content, { schema: yaml.CORE_SCHEMA });
+    }
+    catch (err) {
+        diagnostics.push({
+            level: 'error',
+            code: 'lockfile-invalid',
+            message: `pnpm-lock.yaml is not valid YAML${yamlErrorPosition(err)}.`,
+        });
+        return { diagnostics, topLevel, entryCount: 0 };
+    }
+    if (!isRecord(lock)) {
+        diagnostics.push({
+            level: 'error',
+            code: 'lockfile-invalid',
+            message: 'pnpm-lock.yaml is empty.',
+        });
+        return { diagnostics, topLevel, entryCount: 0 };
+    }
+    const lockVersion = parseFloat(String(lock.lockfileVersion));
+    if (!(lockVersion >= 6)) {
+        diagnostics.push({
+            level: 'error',
+            code: 'lockfile-unsupported',
+            message: `pnpm-lock.yaml lockfileVersion ${String(lock.lockfileVersion)} is not supported. Regenerate it with pnpm 8 or later.`,
+        });
+        return { diagnostics, topLevel, entryCount: 0 };
+    }
+    const importers = isRecord(lock.importers) ? lock.importers : { '.': lock };
+    for (const [importerPath, importer] of Object.entries(importers)) {
+        if (!isRecord(importer))
+            continue;
+        if (importerPath !== '.') {
+            diagnostics.push({
+                level: 'error',
+                code: 'lockfile-link-source',
+                message: `pnpm workspace importer ${importerPath} is not supported; only the docs folder's package.json is installed.`,
+            });
+            continue;
+        }
+        for (const field of ['dependencies', 'optionalDependencies', 'devDependencies']) {
+            const deps = importer[field];
+            if (!isRecord(deps))
+                continue;
+            for (const [name, spec] of Object.entries(deps)) {
+                const version = isRecord(spec) ? spec.version : spec;
+                if (typeof version !== 'string')
+                    continue;
+                const problem = /^(link:|file:|git|github:|http)/.test(version)
+                    ? classifySource(version)
+                    : undefined;
+                if (problem) {
+                    diagnostics.push(sourceError(name, version, problem));
+                    continue;
+                }
+                if (field !== 'devDependencies')
+                    topLevel[name] = stripPeerSuffix(version);
+            }
+        }
+    }
+    let entryCount = 0;
+    const packages = isRecord(lock.packages) ? lock.packages : {};
+    for (const [key, raw] of Object.entries(packages)) {
+        entryCount++;
+        const { name, version } = parsePnpmKey(key);
+        const entry = isRecord(raw) ? raw : {};
+        const resolution = isRecord(entry.resolution) ? entry.resolution : {};
+        const versionProblem = /^[a-z+]+:/i.test(version) ? classifySource(version) : undefined;
+        if (versionProblem) {
+            diagnostics.push(sourceError(name, version, versionProblem));
+            continue;
+        }
+        if (resolution.type === 'git' ||
+            typeof resolution.repo === 'string' ||
+            typeof resolution.commit === 'string') {
+            diagnostics.push(sourceError(name, String(resolution.repo ?? version), {
+                code: 'lockfile-git-source',
+                what: 'a git source',
+            }));
+            continue;
+        }
+        if (resolution.type === 'directory' || typeof resolution.directory === 'string') {
+            diagnostics.push(sourceError(name, String(resolution.directory ?? version), {
+                code: 'lockfile-file-source',
+                what: 'a local folder',
+            }));
+            continue;
+        }
+        const unexpected = Object.keys(resolution).filter((k) => !PNPM_RESOLUTION_KEYS.has(k));
+        if (unexpected.length > 0) {
+            diagnostics.push({
+                level: 'error',
+                code: 'lockfile-resolution-unsupported',
+                message: `${name} has an unsupported resolution in pnpm-lock.yaml (${unexpected.join(', ')}). Only registry packages with integrity hashes are supported.`,
+                pkg: name,
+            });
+            continue;
+        }
+        if (typeof resolution.tarball === 'string') {
+            const problem = classifySource(resolution.tarball);
+            if (problem) {
+                diagnostics.push(sourceError(name, resolution.tarball, problem));
+                continue;
+            }
+            const hostProblem = checkHttpsUrl(name, resolution.tarball, registries);
+            if (hostProblem)
+                diagnostics.push(hostProblem);
+        }
+        if (typeof resolution.integrity !== 'string' || resolution.integrity.length === 0) {
+            diagnostics.push(missingIntegrity(name));
+        }
+    }
+    return { diagnostics, topLevel, entryCount };
+}
+function npmRootSpecs(content) {
+    let lock;
+    try {
+        lock = JSON.parse(content);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(lock) || !isRecord(lock.packages) || !isRecord(lock.packages['']))
+        return undefined;
+    const root = lock.packages[''];
+    return Object.fromEntries(DEPENDENCY_FIELDS.map((f) => [f, dependencySpecs(root, f)]));
+}
+function pnpmRootSpecs(content) {
+    let lock;
+    try {
+        lock = yaml.load(content, { schema: yaml.CORE_SCHEMA });
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(lock))
+        return undefined;
+    const importer = isRecord(lock.importers) ? lock.importers['.'] : lock;
+    if (!isRecord(importer))
+        return {};
+    const out = {};
+    for (const field of PNPM_IMPORTER_FIELDS) {
+        const deps = importer[field];
+        out[field] = {};
+        if (!isRecord(deps))
+            continue;
+        for (const [name, spec] of Object.entries(deps)) {
+            if (isRecord(spec) && typeof spec.specifier === 'string')
+                out[field][name] = spec.specifier;
+        }
+    }
+    return out;
+}
+function rootSyncProblems(kind, fileName, content, packageJson) {
+    const lockSpecs = kind === 'npm' ? npmRootSpecs(content) : pnpmRootSpecs(content);
+    if (!lockSpecs)
+        return [];
+    const fields = kind === 'npm' ? DEPENDENCY_FIELDS : PNPM_IMPORTER_FIELDS;
+    const differing = [];
+    for (const field of fields) {
+        const wanted = dependencySpecs(packageJson, field);
+        const locked = lockSpecs[field] ?? {};
+        for (const name of new Set([...Object.keys(wanted), ...Object.keys(locked)])) {
+            if (wanted[name] !== locked[name])
+                differing.push(`${field} ${name}`);
+        }
+    }
+    if (differing.length === 0)
+        return [];
+    const command = kind === 'npm' ? 'npm install' : 'pnpm install';
+    return [
+        {
+            level: 'error',
+            code: 'lockfile-out-of-sync',
+            message: `${fileName} does not match package.json (${differing.slice(0, 5).join(', ')}${differing.length > 5 ? ', …' : ''}). Run ${command} and commit the lockfile.`,
+        },
+    ];
+}
+export function validateLockfile(input) {
+    const kind = lockfileKind(input.fileName);
+    const result = kind === 'npm'
+        ? validateNpm(input.content, input.registries)
+        : validatePnpm(input.content, input.registries);
+    if (input.packageJson && !hasErrors(result.diagnostics)) {
+        result.diagnostics.push(...rootSyncProblems(kind, input.fileName, input.content, input.packageJson));
+    }
+    return { ok: !hasErrors(result.diagnostics), kind, ...result };
+}

package/dist/package-json.d.ts

@@ -0,0 +1,14 @@
+import type { BuildDiagnostic } from './types.js';
+export type PackageJson = Record<string, unknown>;
+export declare const DEPENDENCY_FIELDS: readonly string[];
+export declare function jsonErrorPosition(err: unknown, content: string): string;
+export declare function readPackageJson(docsRoot: string, { allowSymlink }: {
+    allowSymlink: boolean;
+}): {
+    packageJson?: PackageJson;
+    diagnostics: BuildDiagnostic[];
+};
+export declare function dependencySpecs(packageJson: PackageJson, field: string): Record<string, string>;
+export declare function specProblem(spec: string): string | undefined;
+export declare function validatePackageJson(packageJson: PackageJson): BuildDiagnostic[];
+export declare function cleanPackageJson(packageJson: PackageJson): string;