@qvac/sdk 0.20.1 → 0.21.0

package/dist/src/commands/verify/engines-advice.js

@@ -0,0 +1,271 @@
+import semver from 'semver';
+import { detectPackageManager } from '../host-prebuilds/package-manager.js';
+import { formatRuntimeSource } from './abi.js';
+import { findReactNativeBareKitUpgrade, NETWORK_TIMEOUT_MS, REACT_NATIVE_BARE_KIT } from './bare-kit-runtime.js';
+import { REACT_NATIVE_BARE_KIT_RUNTIMES } from './bare-kit-runtimes.js';
+const REGISTRY_URL = 'https://registry.npmjs.org';
+/** The registry's abbreviated metadata lists `engines` per version at a fraction of the full size. */
+const ABBREVIATED_METADATA_TYPE = 'application/vnd.npm.install-v1+json';
+export async function fetchPackageMetadata(name) {
+    const url = `${REGISTRY_URL}/${encodeURIComponent(name)}`;
+    const response = await fetch(url, {
+        headers: { accept: ABBREVIATED_METADATA_TYPE },
+        signal: AbortSignal.timeout(NETWORK_TIMEOUT_MS)
+    });
+    if (!response.ok)
+        throw new Error(`GET ${url} returned HTTP ${response.status}`);
+    return (await response.json());
+}
+export function formatOverrideSnippet(manager, name, version, parents) {
+    let manifest;
+    switch (manager) {
+        case 'pnpm':
+            manifest = {
+                pnpm: {
+                    overrides: Object.fromEntries(parents.length > 0 ? parents.map((p) => [`${p}>${name}`, version]) : [[name, version]])
+                }
+            };
+            break;
+        case 'yarn':
+            manifest = {
+                resolutions: Object.fromEntries(parents.length > 0 ? parents.map((p) => [`${p}/${name}`, version]) : [[name, version]])
+            };
+            break;
+        case 'bun':
+            // bun only supports top-level overrides.
+            manifest = { overrides: { [name]: version } };
+            break;
+        default:
+            manifest = {
+                overrides: Object.fromEntries(parents.length > 0 ? parents.map((p) => [p, { [name]: version }]) : [[name, version]])
+            };
+    }
+    return JSON.stringify(manifest, null, 2).replace(/\{\n\s+("[^"\n]+": "[^"\n]+")\n\s+\}/g, '{ $1 }');
+}
+function groupFailures(failures) {
+    const byName = new Map();
+    for (const failure of failures) {
+        let entry = byName.get(failure.name);
+        if (entry === undefined) {
+            entry = { versions: new Set(), ranges: new Set() };
+            byName.set(failure.name, entry);
+        }
+        if (failure.version !== undefined)
+            entry.versions.add(failure.version);
+        entry.ranges.add(failure.enginesBare);
+    }
+    return byName;
+}
+function findParents(name, packages) {
+    const seen = new Set();
+    const parents = [];
+    for (const record of packages) {
+        const range = record.dependencies[name];
+        if (range === undefined)
+            continue;
+        const key = `${record.name}\0${range}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        parents.push({ name: record.name, range });
+    }
+    return parents.sort((a, b) => a.name.localeCompare(b.name));
+}
+function runsOn(runtimeVersion, engines) {
+    const range = engines?.bare;
+    if (typeof range !== 'string')
+        return true;
+    return semver.validRange(range) !== null && semver.satisfies(runtimeVersion, range);
+}
+/**
+ * Newest release that runs on the runtime and that every parent accepts,
+ * else one that at least one parent accepts. Without known parents, only the
+ * installed release line (`^installed`) is considered. A version no
+ * dependent accepts would only trade one failure for another, so none is
+ * suggested then.
+ */
+export function pickOverrideVersion(metadata, runtimeVersion, installedVersions, parentRanges) {
+    const compatible = Object.entries(metadata.versions)
+        .filter(([version, manifest]) => {
+        if (semver.valid(version) === null || semver.prerelease(version) !== null)
+            return false;
+        return runsOn(runtimeVersion, manifest.engines);
+    })
+        .map(([version]) => version)
+        .sort(semver.rcompare);
+    if (parentRanges.length > 0) {
+        const acceptedByAll = compatible.find((version) => parentRanges.every((range) => semver.satisfies(version, range)));
+        if (acceptedByAll !== undefined)
+            return acceptedByAll;
+        return (compatible.find((version) => parentRanges.some((range) => semver.satisfies(version, range))) ?? null);
+    }
+    const lines = installedVersions.filter((v) => semver.valid(v) !== null).map(releaseLine);
+    return (compatible.find((version) => lines.some((range) => semver.satisfies(version, range))) ?? null);
+}
+/** Versions `^version` would treat as compatible, including older ones: 1.4.0 -> 1.x, 0.20.3 -> 0.20.x. */
+function releaseLine(version) {
+    const major = semver.major(version);
+    const minor = semver.minor(version);
+    if (major > 0)
+        return `${major}.x`;
+    if (minor > 0)
+        return `0.${minor}.x`;
+    return `0.0.${semver.patch(version)}`;
+}
+function requiredBareVersion(ranges) {
+    let required = null;
+    for (const range of ranges) {
+        const min = semver.validRange(range) === null ? null : semver.minVersion(range);
+        if (min !== null && (required === null || semver.gt(min.version, required))) {
+            required = min.version;
+        }
+    }
+    return required ?? 'unknown';
+}
+function newestTableEntry() {
+    const versions = Object.keys(REACT_NATIVE_BARE_KIT_RUNTIMES).sort(semver.rcompare);
+    const newest = versions[0];
+    return newest === undefined
+        ? null
+        : { version: newest, ...REACT_NATIVE_BARE_KIT_RUNTIMES[newest] };
+}
+function buildUpgrade(runtime, ranges, requiredBare) {
+    if (runtime.source === 'react-native-bare-kit' && runtime.packageVersion !== undefined) {
+        const target = findReactNativeBareKitUpgrade(runtime.packageVersion, ranges);
+        if (target !== null) {
+            return {
+                upgrade: {
+                    packageName: REACT_NATIVE_BARE_KIT,
+                    from: runtime.packageVersion,
+                    to: target.version,
+                    bare: target.bare
+                },
+                upgradeHint: `Upgrade ${REACT_NATIVE_BARE_KIT} to ${target.version} or newer ` +
+                    `(embeds bare-kit ${target.bareKit}, Bare ${target.bare}).`
+            };
+        }
+        const newest = newestTableEntry();
+        return {
+            upgrade: null,
+            upgradeHint: `No ${REACT_NATIVE_BARE_KIT} release in the built-in table embeds Bare ${requiredBare} or newer` +
+                (newest === null
+                    ? '.'
+                    : `; the newest known, ${newest.version}, embeds Bare ${newest.bare}. Check for a newer release.`)
+        };
+    }
+    if (runtime.source === 'bare-runtime' || runtime.source === 'bare') {
+        return {
+            upgrade: null,
+            upgradeHint: `Upgrade ${runtime.source} to ${requiredBare} or newer.`
+        };
+    }
+    return {
+        upgrade: null,
+        upgradeHint: `The runtime version comes from ${runtime.source}; raise it to ${requiredBare} or newer if the target runtime allows it.`
+    };
+}
+export async function buildEnginesAdvice(options) {
+    const { projectRoot, hosts, runtime, failures, packages, network = true, onProgress, fetchPackageMetadata: fetchOne = fetchPackageMetadata } = options;
+    const grouped = groupFailures(failures);
+    const allRanges = [...grouped.values()].flatMap((entry) => [...entry.ranges]);
+    const requiredBare = requiredBareVersion(allRanges);
+    const { manager: packageManager } = await detectPackageManager(projectRoot);
+    const names = [...grouped.keys()].sort();
+    if (network && names.length > 0) {
+        onProgress?.(`Looking up releases of ${names.join(', ')} on registry.npmjs.org that run on Bare ` +
+            `${runtime.version} (${names.length} request${names.length === 1 ? '' : 's'}, timeout ${NETWORK_TIMEOUT_MS / 1000}s)...`);
+    }
+    const overrides = await Promise.all(names.map(async (name) => {
+        const entry = grouped.get(name);
+        const installedVersions = [...entry.versions].sort();
+        const parents = findParents(name, packages);
+        const override = {
+            name,
+            installedVersions,
+            enginesBare: [...entry.ranges].sort(),
+            version: null,
+            parents: parents.map((parent) => ({ ...parent, satisfied: false })),
+            snippet: null
+        };
+        if (!network) {
+            override.lookupSkipped = true;
+            return override;
+        }
+        try {
+            const metadata = await fetchOne(name);
+            override.version = pickOverrideVersion(metadata, runtime.version, installedVersions, parents.map((parent) => parent.range));
+        }
+        catch (error) {
+            override.lookupError = error instanceof Error ? error.message : String(error);
+            return override;
+        }
+        const version = override.version;
+        if (version === null)
+            return override;
+        override.parents = parents.map((parent) => ({
+            ...parent,
+            satisfied: semver.satisfies(version, parent.range)
+        }));
+        // Scoping only matters when some dependent must keep its current copy.
+        const accepting = override.parents.filter((parent) => parent.satisfied);
+        override.snippet = formatOverrideSnippet(packageManager, name, version, accepting.length === override.parents.length ? [] : accepting.map((parent) => parent.name));
+        return override;
+    }));
+    return {
+        hosts,
+        runtime,
+        requiredBare,
+        ...buildUpgrade(runtime, allRanges, requiredBare),
+        overrides,
+        packageManager
+    };
+}
+const MANIFEST_FIELD = {
+    npm: '"overrides"',
+    pnpm: '"pnpm.overrides"',
+    yarn: '"resolutions"',
+    bun: '"overrides"'
+};
+export function formatEnginesAdvice(advice) {
+    const lines = [
+        `  Fix for ${advice.hosts.join(', ')}:`,
+        `    Runtime: Bare ${advice.runtime.version} (from ${formatRuntimeSource(advice.runtime)})`,
+        ...advice.overrides.map((override) => `    Requires: ${override.name}@${override.installedVersions.join(', ') || 'unknown'} needs Bare ${override.enginesBare.join(' and ')}`),
+        `    Option 1: ${advice.upgradeHint}`
+    ];
+    for (const override of advice.overrides) {
+        const installed = override.installedVersions.join(', ') || 'unknown';
+        if (override.lookupSkipped === true) {
+            lines.push(`    Option 2 (${override.name}): pin an older release; run again with network lookups ` +
+                'enabled (without --offline) to find one that runs on this Bare.');
+            continue;
+        }
+        if (override.version === null) {
+            const acceptedBy = override.parents.length === 0
+                ? ` on the ${installed} release line`
+                : ` that ${override.parents.map((p) => `${p.name} (${p.range})`).join(', ')} accept${override.parents.length === 1 ? 's' : ''}`;
+            lines.push(`    Option 2 (${override.name}): no release that runs on Bare ${advice.runtime.version}${acceptedBy} was found` +
+                (override.lookupError === undefined
+                    ? '; upgrade the runtime.'
+                    : ` (${override.lookupError}).`));
+            continue;
+        }
+        const field = advice.packageManager === null
+            ? '"overrides" (npm/bun), "pnpm.overrides" or "resolutions" (yarn)'
+            : MANIFEST_FIELD[advice.packageManager];
+        lines.push(`    Option 2 (${override.name}): pin ${installed} -> ${override.version} with ${field} in your app's package.json:`);
+        for (const line of (override.snippet ?? '').split('\n'))
+            lines.push(`      ${line}`);
+        const rejected = override.parents.filter((parent) => !parent.satisfied);
+        if (rejected.length > 0) {
+            lines.push(`      ${rejected.map((p) => `${p.name} (${p.range})`).join(', ')} ` +
+                `${rejected.length === 1 ? 'does' : 'do'} not accept ${override.version}; ` +
+                'those copies are left as they are.');
+        }
+        if (advice.packageManager === 'bun' && override.parents.length > 0) {
+            lines.push('      bun applies overrides to every copy in the tree.');
+        }
+    }
+    lines.push('');
+    return lines;
+}

package/dist/src/commands/verify/index.d.ts

@@ -1,12 +1,29 @@
 import { type AddonSourceKind, type NativeAddon } from './addon-source.js';
 import { type MissingPrebuildIssue } from './prebuilds.js';
 import { type AbiIssue, type BareRuntimeResolution } from './abi.js';
+import { type FetchText, type ProgressFn } from './bare-kit-runtime.js';
+import { type EnginesAdvice, type FetchPackageMetadata } from './engines-advice.js';
 export interface VerifyBundleOptions {
     projectRoot: string;
     addonsSource: string;
     hosts: string[];
     bareRuntimeVersion?: string;
     configPath?: string;
+    /**
+     * Allow GitHub and npm registry requests: GitHub for a react-native-bare-kit
+     * release newer than the built-in table, the registry only after a mismatch
+     * is found, to suggest an override. Defaults to true.
+     */
+    network?: boolean;
+    /** Called before any step that waits on the network. */
+    onProgress?: ProgressFn;
+    /** Test seams for the network lookups. */
+    fetchText?: FetchText;
+    fetchPackageMetadata?: FetchPackageMetadata;
+}
+export interface RuntimeGroup {
+    hosts: string[];
+    resolution: BareRuntimeResolution;
 }
 export interface InvalidSourceIssue {
     code: 'invalid-source';
@@ -48,9 +65,14 @@ export interface VerifyBundleResult {
     resolvedAddonsSource: string;
     sourceKind: AddonSourceKind | null;
     hosts: string[];
+    /** Runtime of the first entry in `runtimes`: the mobile one when any host is mobile. */
     runtime: BareRuntimeResolution | null;
+    /** Mobile and desktop hosts run different Bare builds, so each is resolved separately. */
+    runtimes?: RuntimeGroup[];
     addons: NativeAddon[];
     issues: VerifyBundleIssue[];
+    /** How to fix each runtime that fails an engines.bare range. */
+    advice?: EnginesAdvice[];
 }
 export declare function verifyBundle(options: VerifyBundleOptions): Promise<VerifyBundleResult>;
 export declare function hasErrors(result: VerifyBundleResult): boolean;

package/dist/src/commands/verify/index.js

@@ -4,8 +4,10 @@ import { resolveConfigFileInProject, loadConfigFromPath } from '../../client/con
 import { createCollectDiagnostics, formatAddonId } from './addon-source.js';
 import { collectAddonsFromBundle, InvalidBundleSourceError } from './bundle-source.js';
 import { collectAddonsFromNodeModules, InvalidNodeModulesSourceError } from './node-modules-source.js';
-import { checkPrebuilds } from './prebuilds.js';
+import { checkPrebuilds, isMobileHost } from './prebuilds.js';
 import { checkAbi, formatConfigLabel, normalizeVersion, resolveBareRuntime } from './abi.js';
+import { isReactNativeBareKitInstalled, resolveMobileBareRuntime } from './bare-kit-runtime.js';
+import { buildEnginesAdvice, formatEnginesAdvice } from './engines-advice.js';
 export async function verifyBundle(options) {
     const { projectRoot, addonsSource, hosts, bareRuntimeVersion, configPath } = options;
     const resolvedAddonsSource = path.isAbsolute(addonsSource)
@@ -119,6 +121,9 @@ export async function verifyBundle(options) {
         };
     }
     const diagnostics = createCollectDiagnostics();
+    if (sourceKind === 'node-modules') {
+        options.onProgress?.(`Scanning ${resolvedAddonsSource} for native addons and engines.bare...`);
+    }
     let addons;
     try {
         addons =
@@ -178,20 +183,57 @@ export async function verifyBundle(options) {
         issues.push(...prebuildIssues);
     }
     let runtime = null;
+    let runtimes;
+    const advice = [];
     if (invalidRuntimeVersion === null) {
-        const runtimeOptions = { projectRoot };
-        if (bareRuntimeVersion !== undefined) {
-            runtimeOptions.explicitVersion = bareRuntimeVersion;
-            runtimeOptions.explicitSource = 'flag';
-        }
-        else if (configRuntimeVersion !== undefined) {
-            runtimeOptions.explicitVersion = configRuntimeVersion;
-            runtimeOptions.explicitSource = 'config';
+        const explicit = bareRuntimeVersion !== undefined
+            ? { version: bareRuntimeVersion, source: 'flag' }
+            : configRuntimeVersion !== undefined
+                ? { version: configRuntimeVersion, source: 'config' }
+                : null;
+        runtimes = await resolveRuntimeGroups({
+            projectRoot,
+            hosts,
+            explicit,
+            network: options.network,
+            onProgress: options.onProgress,
+            fetchText: options.fetchText
+        });
+        runtime = runtimes[0]?.resolution ?? null;
+        const packages = enginesPackages(diagnostics.packages);
+        const seen = new Set();
+        for (const group of runtimes) {
+            const groupIssues = checkAbi({
+                addons: addonsLinkedOn(addons, group.hosts),
+                runtime: group.resolution,
+                packages
+            }).filter((issue) => {
+                if (seen.has(issue.message))
+                    return false;
+                seen.add(issue.message);
+                return true;
+            });
+            issues.push(...groupIssues);
+            const failures = groupIssues.flatMap((issue) => issue.code === 'abi-mismatch' || issue.code === 'engines-mismatch'
+                ? [
+                    failureOf(issue.code === 'abi-mismatch' ? issue.addon : issue.package, issue.enginesBare)
+                ]
+                : []);
+            if (failures.length > 0 && group.resolution.resolved) {
+                advice.push(await buildEnginesAdvice({
+                    projectRoot,
+                    hosts: group.hosts,
+                    runtime: group.resolution.runtime,
+                    failures,
+                    packages: diagnostics.packages,
+                    network: options.network,
+                    onProgress: options.onProgress,
+                    fetchPackageMetadata: options.fetchPackageMetadata
+                }));
+            }
         }
-        runtime = await resolveBareRuntime(runtimeOptions);
-        issues.push(...checkAbi({ addons, runtime }));
     }
-    return {
+    const result = {
         addonsSource,
         resolvedAddonsSource,
         sourceKind,
@@ -200,6 +242,85 @@ export async function verifyBundle(options) {
         addons,
         issues
     };
+    if (runtimes !== undefined)
+        result.runtimes = runtimes;
+    if (advice.length > 0)
+        result.advice = advice;
+    return result;
+}
+/** `name@version` ids as built by `formatAddonId`; scoped names keep their leading `@`. */
+function failureOf(id, enginesBare) {
+    const at = id.lastIndexOf('@');
+    if (at <= 0)
+        return { name: id, enginesBare };
+    const version = id.slice(at + 1);
+    return version === 'unknown'
+        ? { name: id.slice(0, at), enginesBare }
+        : { name: id.slice(0, at), version, enginesBare };
+}
+/**
+ * Addons a runtime group loads: those the bundle links on one of its hosts.
+ * Without link information (`linkedHosts` unset), every addon counts, as in
+ * `checkPrebuilds`.
+ */
+function addonsLinkedOn(addons, hosts) {
+    return addons.filter((addon) => addon.linkedHosts === undefined || addon.linkedHosts.some((host) => hosts.includes(host)));
+}
+function enginesPackages(records) {
+    const byId = new Map();
+    for (const record of records) {
+        if (record.isAddon || record.enginesBare === undefined)
+            continue;
+        const id = `${record.name}@${record.version ?? 'unknown'}`;
+        if (byId.has(id))
+            continue;
+        const pkg = { name: record.name, enginesBare: record.enginesBare };
+        if (record.version !== undefined)
+            pkg.version = record.version;
+        byId.set(id, pkg);
+    }
+    return [...byId.values()];
+}
+/**
+ * Mobile hosts run the Bare build inside react-native-bare-kit; desktop hosts
+ * run `bare-runtime` (or `bare`). An explicit version applies to every host.
+ * Without react-native-bare-kit installed, mobile hosts fall back to the
+ * desktop detection so projects that only bundle for mobile keep a runtime.
+ */
+async function resolveRuntimeGroups(options) {
+    const { projectRoot, hosts, explicit } = options;
+    if (explicit !== null) {
+        return [
+            {
+                hosts,
+                resolution: await resolveBareRuntime({
+                    projectRoot,
+                    explicitVersion: explicit.version,
+                    explicitSource: explicit.source
+                })
+            }
+        ];
+    }
+    const mobileHosts = hosts.filter(isMobileHost);
+    const desktopHosts = hosts.filter((host) => !isMobileHost(host));
+    const groups = [];
+    if (mobileHosts.length > 0) {
+        groups.push({
+            hosts: mobileHosts,
+            resolution: isReactNativeBareKitInstalled(projectRoot)
+                ? await resolveMobileBareRuntime({
+                    projectRoot,
+                    network: options.network,
+                    onProgress: options.onProgress,
+                    fetchText: options.fetchText
+                })
+                : await resolveBareRuntime({ projectRoot })
+        });
+    }
+    if (desktopHosts.length > 0) {
+        groups.push({ hosts: desktopHosts, resolution: await resolveBareRuntime({ projectRoot }) });
+    }
+    return groups;
 }
 function buildInvalidPackageJsonIssues(records) {
     return records.map((record) => {
@@ -262,6 +383,9 @@ export function formatVerifyBundleResult(result) {
     sections.push('');
     sections.push(...formatMissingPrebuilds(result.issues));
     sections.push(...formatAbiMismatches(result.issues));
+    sections.push(...formatEnginesMismatches(result.issues));
+    for (const advice of result.advice ?? [])
+        sections.push(...formatEnginesAdvice(advice));
     sections.push(...formatInvalidRuntimeVersions(result.issues));
     sections.push(...formatMalformedEnginesBare(result.issues));
     sections.push(...formatConfigLoadFailed(result.issues));
@@ -288,7 +412,9 @@ function formatMissingPrebuilds(issues) {
         return [];
     const lines = ['  Missing prebuild:'];
     for (const issue of matches) {
-        lines.push(`    - ${issue.addon} for ${issue.host}`);
+        const pin = issue.platformPackage;
+        const needs = pin === undefined ? '' : ` (needs "${pin.name}": "${pin.version}" in package.json)`;
+        lines.push(`    - ${issue.addon} for ${issue.host}${needs}`);
     }
     lines.push('');
     return lines;
@@ -305,6 +431,18 @@ function formatAbiMismatches(issues) {
     lines.push('');
     return lines;
 }
+function formatEnginesMismatches(issues) {
+    const matches = issues.filter((issue) => issue.code === 'engines-mismatch');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  engines.bare mismatch:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.package} requires bare ${issue.enginesBare}, ` +
+            `runtime is ${issue.runtimeVersion}`);
+    }
+    lines.push('');
+    return lines;
+}
 function formatUnknownRuntime(issues) {
     const matches = issues.filter((issue) => issue.code === 'unknown-runtime-version');
     if (matches.length === 0)

package/dist/src/commands/verify/node-modules-source.js

@@ -1,6 +1,6 @@
 import { promises as fsp } from 'node:fs';
 import path from 'node:path';
-import { deduplicateAddons, readAddonPackageJson } from './addon-source.js';
+import { createLimiter, deduplicateAddons, FS_CONCURRENCY, readAddonPackageJson } from './addon-source.js';
 export class InvalidNodeModulesSourceError extends Error {
     nodeModulesPath;
     constructor(nodeModulesPath, cause) {
@@ -14,63 +14,67 @@ export class InvalidNodeModulesSourceError extends Error {
 }
 export async function collectAddonsFromNodeModules(options) {
     const { nodeModulesRoot, diagnostics } = options;
+    const limit = createLimiter(FS_CONCURRENCY);
+    const results = await walkNodeModules(nodeModulesRoot, limit, true);
     const addons = [];
-    await walkNodeModules(nodeModulesRoot, addons, diagnostics, true);
+    for (const result of results) {
+        if (result.record !== undefined && diagnostics !== undefined) {
+            diagnostics.packages.push(result.record);
+        }
+        if (result.isAddon && result.addon) {
+            addons.push(result.addon);
+        }
+        else if (result.invalid !== undefined && diagnostics !== undefined) {
+            diagnostics.invalidPackageJsons.push(result.invalid);
+        }
+    }
     return deduplicateAddons(addons);
 }
-async function walkNodeModules(nodeModulesDir, addons, diagnostics, isRoot) {
+/**
+ * Directory reads run in parallel under `limit`; results are concatenated in
+ * directory-entry order so the output does not depend on I/O timing.
+ */
+async function walkNodeModules(nodeModulesDir, limit, isRoot) {
     let entries;
     try {
-        entries = await fsp.readdir(nodeModulesDir, { withFileTypes: true });
+        entries = await limit(() => fsp.readdir(nodeModulesDir, { withFileTypes: true }));
     }
     catch (error) {
         if (isRoot)
             throw new InvalidNodeModulesSourceError(nodeModulesDir, error);
-        return;
-    }
-    for (const entry of entries) {
-        if (entry.name.startsWith('.'))
-            continue;
-        if (!isPackageEntry(entry))
-            continue;
-        if (entry.name.startsWith('@')) {
-            await walkScopeDirectory(path.join(nodeModulesDir, entry.name), addons, diagnostics);
-            continue;
-        }
-        await visitPackageDirectory(path.join(nodeModulesDir, entry.name), entry.name, addons, diagnostics);
+        return [];
     }
+    const visits = entries
+        .filter((entry) => !entry.name.startsWith('.') && isPackageEntry(entry))
+        .map((entry) => entry.name.startsWith('@')
+        ? walkScopeDirectory(path.join(nodeModulesDir, entry.name), limit)
+        : visitPackageDirectory(path.join(nodeModulesDir, entry.name), entry.name, limit));
+    return (await Promise.all(visits)).flat();
 }
-async function walkScopeDirectory(scopeDir, addons, diagnostics) {
+async function walkScopeDirectory(scopeDir, limit) {
     const scope = path.basename(scopeDir);
     let entries;
     try {
-        entries = await fsp.readdir(scopeDir, { withFileTypes: true });
+        entries = await limit(() => fsp.readdir(scopeDir, { withFileTypes: true }));
     }
     catch {
-        return;
-    }
-    for (const entry of entries) {
-        if (entry.name.startsWith('.'))
-            continue;
-        if (!isPackageEntry(entry))
-            continue;
-        await visitPackageDirectory(path.join(scopeDir, entry.name), `${scope}/${entry.name}`, addons, diagnostics);
+        return [];
     }
+    const visits = entries
+        .filter((entry) => !entry.name.startsWith('.') && isPackageEntry(entry))
+        .map((entry) => visitPackageDirectory(path.join(scopeDir, entry.name), `${scope}/${entry.name}`, limit));
+    return (await Promise.all(visits)).flat();
 }
 function isPackageEntry(entry) {
     return entry.isDirectory() || entry.isSymbolicLink();
 }
-async function visitPackageDirectory(packageDir, packageName, addons, diagnostics) {
-    const result = await readAddonPackageJson({
-        packageJsonPath: path.join(packageDir, 'package.json'),
-        expectedName: packageName
-    });
-    if (result.isAddon && result.addon) {
-        addons.push(result.addon);
-    }
-    else if (result.invalid !== undefined && diagnostics !== undefined) {
-        diagnostics.invalidPackageJsons.push(result.invalid);
-    }
-    const nestedNodeModules = path.join(packageDir, 'node_modules');
-    await walkNodeModules(nestedNodeModules, addons, diagnostics, false);
+async function visitPackageDirectory(packageDir, packageName, limit) {
+    const [result, nested] = await Promise.all([
+        limit(() => readAddonPackageJson({
+            packageJsonPath: path.join(packageDir, 'package.json'),
+            expectedName: packageName
+        })),
+        walkNodeModules(path.join(packageDir, 'node_modules'), limit, false)
+    ]);
+    return [result, ...nested];
 }

package/dist/src/commands/verify/prebuilds.d.ts

@@ -6,7 +6,20 @@ export interface MissingPrebuildIssue {
     host: string;
     message: string;
     packageRoot: string;
+    /**
+     * The per-platform package to declare for this mobile host, at the exact
+     * version it must be installed at. Set when the addon's `#host-addon` map
+     * names one and it is either not installed or installed at another version.
+     * Never set for desktop hosts, whose platform packages install as the
+     * addon's os/cpu-filtered optionalDependencies.
+     */
+    platformPackage?: PlatformPackagePin;
 }
+export interface PlatformPackagePin {
+    name: string;
+    version: string;
+}
+export declare function isMobileHost(host: string): boolean;
 export interface CheckPrebuildsOptions {
     addon: NativeAddon;
     hosts: string[];
@@ -19,6 +32,12 @@ export interface CheckPrebuildsOptions {
 export interface PrebuildLocation {
     hostDir: string;
     platformPackage?: string;
+    /**
+     * The installed platform package's version when it differs from the
+     * addon's. Platform packages are version-locked to their addon, so a
+     * prebuild in a mismatched one does not count.
+     */
+    mismatchedVersion?: string;
 }
 /**
  * Directories to search for an addon's `<host>` prebuild, in precedence order: