@qvac/sdk 0.19.0 → 0.20.0

package/dist/src/commands/verify/bundle-source.js

@@ -1,6 +1,18 @@
 import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_HOSTS } from '../bundle/constants.js';
 import { buildNestedPathIndex, extractBarePackHeader, extractPackedString } from '../bundle/manifest.js';
 import { deduplicateAddons, readAddonPackageJson } from './addon-source.js';
+/** bare-pack resolves a linked native addon to this prefix instead of a module path. */
+const LINKED_PREFIX = 'linked:';
+/** Reserved resolution key naming the package.json that owns a module. */
+const PACKAGE_KEY = '#package';
+/** Export conditions that name a platform. */
+const PLATFORMS = new Set(DEFAULT_HOSTS.map(platformOf));
+/** `win32-x64` -> `win32`, `ios-arm64-simulator` -> `ios`. */
+function platformOf(host) {
+    return host.split('-')[0] ?? host;
+}
 export class InvalidBundleSourceError extends Error {
     bundlePath;
     constructor(bundlePath, cause) {
@@ -13,7 +25,7 @@ export class InvalidBundleSourceError extends Error {
     }
 }
 export async function collectAddonsFromBundle(options) {
-    const { bundlePath, projectRoot, diagnostics } = options;
+    const { bundlePath, projectRoot, hosts, diagnostics } = options;
     let bundleText;
     try {
         bundleText = await fsp.readFile(bundlePath, 'utf8');
@@ -22,10 +34,14 @@ export async function collectAddonsFromBundle(options) {
         throw new InvalidBundleSourceError(bundlePath, error);
     }
     let resolutions;
+    let main;
+    let imports;
     try {
         const packed = extractPackedString(bundleText);
         const header = extractBarePackHeader(packed);
         resolutions = header.resolutions ?? {};
+        main = header.main;
+        imports = header.imports ?? {};
     }
     catch (error) {
         throw new InvalidBundleSourceError(bundlePath, error);
@@ -34,6 +50,14 @@ export async function collectAddonsFromBundle(options) {
         diagnostics.emptyResolutions = true;
     }
     const pathsByPackage = buildNestedPathIndex(resolutions, projectRoot);
+    const analysed = analyseLinkedHosts({
+        resolutions,
+        main,
+        imports,
+        hosts: hosts ?? [],
+        projectRoot,
+        pathsByPackage
+    });
     const addons = [];
     for (const [pkgName, candidates] of pathsByPackage) {
         for (const candidate of candidates) {
@@ -42,6 +66,8 @@ export async function collectAddonsFromBundle(options) {
                 expectedName: pkgName
             });
             if (result.isAddon && result.addon) {
+                if (analysed !== null)
+                    result.addon.linkedHosts = analysed.get(candidate) ?? [];
                 addons.push(result.addon);
             }
             else if (result.invalid !== undefined && diagnostics !== undefined) {
@@ -51,3 +77,131 @@ export async function collectAddonsFromBundle(options) {
     }
     return deduplicateAddons(addons);
 }
+/**
+ * `mapLinkedHosts`, rejected unless its keys line up with the paths the path
+ * index found. A disagreement would read as "nothing is linked" and drop every
+ * prebuild check, so require an overlap before trusting the map.
+ */
+function analyseLinkedHosts(options) {
+    const { pathsByPackage, ...mapOptions } = options;
+    const linkedHosts = mapLinkedHosts(mapOptions);
+    if (linkedHosts === null)
+        return null;
+    for (const candidates of pathsByPackage.values()) {
+        for (const candidate of candidates) {
+            if (linkedHosts.has(candidate))
+                return linkedHosts;
+        }
+    }
+    return null;
+}
+/**
+ * Which of `hosts` link each package's addon, keyed by the owning package.json.
+ * A host counts only when the bundle both reaches a module of that package on
+ * its platform *and* resolves a `linked:` addon there.
+ *
+ * Both halves are needed because bare-pack emits two graph shapes: for a single
+ * host it resolves conditions eagerly, dropping the binding module of a package
+ * whose platform export is a JS stub; for several hosts it keeps every branch
+ * and links a name per host, so only reachability separates the platforms.
+ *
+ * Null leaves every host checked, as if no analysis had run.
+ */
+function mapLinkedHosts(options) {
+    const { resolutions, main, imports, hosts, projectRoot } = options;
+    if (hosts.length === 0)
+        return null;
+    if (main === undefined || !Object.prototype.hasOwnProperty.call(resolutions, main))
+        return null;
+    // `main` is the only root we walk; an import map could reach past it.
+    if (Object.keys(imports).length > 0)
+        return null;
+    const linked = new Map();
+    const ownersByPlatform = new Map();
+    for (const host of hosts) {
+        const platform = platformOf(host);
+        let owners = ownersByPlatform.get(platform);
+        if (owners === undefined) {
+            owners = linkedOwnersOn(resolutions, main, platform, projectRoot);
+            ownersByPlatform.set(platform, owners);
+        }
+        if (owners === null)
+            return null;
+        for (const owner of owners) {
+            let forOwner = linked.get(owner);
+            if (forOwner === undefined) {
+                forOwner = new Set();
+                linked.set(owner, forOwner);
+            }
+            forOwner.add(host);
+        }
+    }
+    return new Map([...linked].map(([owner, forOwner]) => [owner, [...forOwner].sort()]));
+}
+/**
+ * package.json paths of the addons linked on `platform`, walking from `main`.
+ * Null if a linked module names no owning package.
+ */
+function linkedOwnersOn(resolutions, main, platform, projectRoot) {
+    const owners = new Set();
+    const seen = new Set();
+    const stack = [main];
+    while (stack.length > 0) {
+        const module = stack.pop();
+        if (seen.has(module))
+            continue;
+        seen.add(module);
+        const edges = asRecord(resolutions[module]);
+        if (edges === null)
+            continue;
+        let linksAddon = false;
+        for (const [specifier, target] of Object.entries(edges)) {
+            if (specifier === PACKAGE_KEY)
+                continue;
+            for (const resolved of targetsOn(target, platform)) {
+                if (resolved.startsWith(LINKED_PREFIX))
+                    linksAddon = true;
+                else
+                    stack.push(resolved);
+            }
+        }
+        if (!linksAddon)
+            continue;
+        const owner = edges[PACKAGE_KEY];
+        if (typeof owner !== 'string')
+            return null;
+        owners.add(path.join(projectRoot, owner));
+    }
+    return owners;
+}
+/**
+ * Every target a specifier can resolve to on `platform`, first-match-wins: this
+ * platform or `default` settles it, another platform is ruled out. A condition
+ * the host cannot decide (`require`, `bare`, ...) is kept and the scan goes on,
+ * so reachability is over- rather than under-reported.
+ */
+function targetsOn(target, platform) {
+    if (typeof target === 'string')
+        return [target];
+    const conditions = asRecord(target);
+    if (conditions === null)
+        return [];
+    const targets = [];
+    for (const [condition, value] of Object.entries(conditions)) {
+        if (PLATFORMS.has(condition)) {
+            if (condition !== platform)
+                continue;
+            targets.push(...targetsOn(value, platform));
+            break;
+        }
+        targets.push(...targetsOn(value, platform));
+        if (condition === 'default')
+            break;
+    }
+    return targets;
+}
+function asRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    return value;
+}

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

@@ -126,6 +126,7 @@ export async function verifyBundle(options) {
                 ? await collectAddonsFromBundle({
                     bundlePath: resolvedAddonsSource,
                     projectRoot,
+                    hosts,
                     diagnostics
                 })
                 : await collectAddonsFromNodeModules({

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

@@ -11,6 +11,29 @@ export interface CheckPrebuildsOptions {
     addon: NativeAddon;
     hosts: string[];
 }
+/**
+ * One place an addon's prebuild for a host may live. `platformPackage` is set
+ * when the directory belongs to a per-platform prebuild package rather than
+ * the addon package itself.
+ */
+export interface PrebuildLocation {
+    hostDir: string;
+    platformPackage?: string;
+}
+/**
+ * Directories to search for an addon's `<host>` prebuild, in precedence order:
+ *
+ * 1. `<packageRoot>/prebuilds/<host>` — the fat layout every addon used to
+ *    publish, and where source builds and `linked:` checkouts still land.
+ * 2. `<platformRoot>/addon/prebuilds/<host>` — the per-platform package the
+ *    addon's `#host-addon` map names for this host, when that package is
+ *    installed. Each platform package embeds an inner `addon/` package named
+ *    after the meta addon so the `.bare` file keeps its name.
+ *
+ * A local `prebuilds/` always wins, matching the precedence the addons apply
+ * in their own `binding.js` (`require.addon()` first, platform package second).
+ */
+export declare function resolvePrebuildLocations(addon: NativeAddon, host: string): Promise<PrebuildLocation[]>;
 export declare function checkPrebuilds(options: CheckPrebuildsOptions): Promise<MissingPrebuildIssue[]>;
 export declare function listBarePrebuildFiles(hostDir: string): Promise<string[]>;
 //# sourceMappingURL=prebuilds.d.ts.map

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

@@ -1,26 +1,142 @@
 import { promises as fsp } from 'node:fs';
 import path from 'node:path';
 import { formatAddonId } from './addon-source.js';
+import { HOST_ADDON_IMPORT, resolveAddonPlatformPackage } from '../../expo/plugins/patches/qvac-platform-addons.js';
+const PREBUILDS_DIR = 'prebuilds';
+const PLATFORM_ADDON_DIR = 'addon';
+/**
+ * Directories to search for an addon's `<host>` prebuild, in precedence order:
+ *
+ * 1. `<packageRoot>/prebuilds/<host>` — the fat layout every addon used to
+ *    publish, and where source builds and `linked:` checkouts still land.
+ * 2. `<platformRoot>/addon/prebuilds/<host>` — the per-platform package the
+ *    addon's `#host-addon` map names for this host, when that package is
+ *    installed. Each platform package embeds an inner `addon/` package named
+ *    after the meta addon so the `.bare` file keeps its name.
+ *
+ * A local `prebuilds/` always wins, matching the precedence the addons apply
+ * in their own `binding.js` (`require.addon()` first, platform package second).
+ */
+export async function resolvePrebuildLocations(addon, host) {
+    const locations = [
+        { hostDir: path.join(addon.packageRoot, PREBUILDS_DIR, host) }
+    ];
+    const platformPackage = await platformPackageForHost(addon, host);
+    if (platformPackage === null)
+        return locations;
+    const platformRoot = await findInstalledPackage(await realPackageRoot(addon.packageRoot), platformPackage);
+    if (platformRoot !== null) {
+        locations.push({
+            hostDir: path.join(platformRoot, PLATFORM_ADDON_DIR, PREBUILDS_DIR, host),
+            platformPackage
+        });
+    }
+    return locations;
+}
+/**
+ * The directory the addon really lives in. Under pnpm's isolated layout
+ * `node_modules/@qvac/tts-ggml` is a symlink into the virtual store
+ * (`node_modules/.pnpm/<id>/node_modules/@qvac/tts-ggml`), and the addon's
+ * dependencies — its platform package included — are linked next to it in
+ * that store directory rather than at the project's top-level `node_modules`.
+ * Node resolves from the real path, so the platform-package search starts
+ * there too. An unresolvable path (a fixture, a bundle path that no longer
+ * exists) is searched as given.
+ */
+async function realPackageRoot(packageRoot) {
+    try {
+        return await fsp.realpath(packageRoot);
+    }
+    catch {
+        return path.resolve(packageRoot);
+    }
+}
 export async function checkPrebuilds(options) {
     const { addon, hosts } = options;
     const issues = [];
     for (const host of hosts) {
-        const hostDir = path.join(addon.packageRoot, 'prebuilds', host);
-        const present = (await listBarePrebuildFiles(hostDir)).length > 0;
-        if (!present) {
-            issues.push({
-                code: 'missing-prebuild',
-                level: 'error',
-                addon: formatAddonId(addon),
-                host,
-                packageRoot: addon.packageRoot,
-                message: `${formatAddonId(addon)} is missing a prebuild for ${host} ` +
-                    `(expected ${path.join(hostDir, '*.bare')}).`
-            });
-        }
+        if (addon.linkedHosts !== undefined && !addon.linkedHosts.includes(host))
+            continue;
+        const locations = await resolvePrebuildLocations(addon, host);
+        if (await anyLocationHasPrebuild(locations))
+            continue;
+        issues.push({
+            code: 'missing-prebuild',
+            level: 'error',
+            addon: formatAddonId(addon),
+            host,
+            packageRoot: addon.packageRoot,
+            message: await describeMissingPrebuild(addon, host, locations)
+        });
     }
     return issues;
 }
+async function anyLocationHasPrebuild(locations) {
+    for (const location of locations) {
+        if ((await listBarePrebuildFiles(location.hostDir)).length > 0)
+            return true;
+    }
+    return false;
+}
+async function describeMissingPrebuild(addon, host, locations) {
+    const expected = locations.map((location) => path.join(location.hostDir, '*.bare'));
+    const platformPackage = await platformPackageForHost(addon, host);
+    const searchedPlatformPackage = locations.some((location) => location.platformPackage === platformPackage);
+    return (`${formatAddonId(addon)} is missing a prebuild for ${host} ` +
+        `(expected ${expected.join(' or ')}).` +
+        missingPlatformPackageHint(addon, platformPackage, searchedPlatformPackage));
+}
+function missingPlatformPackageHint(addon, platformPackage, searchedPlatformPackage) {
+    if (platformPackage === null || searchedPlatformPackage)
+        return '';
+    const pin = addon.version === undefined ? platformPackage : `"${platformPackage}": "${addon.version}"`;
+    return (` Add this exact dependency to package.json (same version as ${addon.name})` +
+        ` and reinstall: ${pin}`);
+}
+async function platformPackageForHost(addon, host) {
+    return resolveAddonPlatformPackage(addon.name, await readHostAddonMap(addon), host);
+}
+async function readHostAddonMap(addon) {
+    try {
+        const raw = await fsp.readFile(path.join(addon.packageRoot, 'package.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return undefined;
+        const imports = parsed.imports;
+        return imports?.[HOST_ADDON_IMPORT];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Locates `packageName` the way Node's resolver would from `fromDir`: in
+ * `<dir>/node_modules/<packageName>` for `fromDir` and each of its ancestors.
+ * Covers a hoisted platform package next to the meta package, one nested
+ * under the meta package's own `node_modules`, and — given the meta package's
+ * real path — the sibling link pnpm places in its virtual-store directory.
+ */
+async function findInstalledPackage(fromDir, packageName) {
+    let dir = path.resolve(fromDir);
+    for (;;) {
+        const candidate = path.join(dir, 'node_modules', packageName);
+        if (await isPackageDir(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+async function isPackageDir(dir) {
+    try {
+        const stat = await fsp.stat(path.join(dir, 'package.json'));
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
 export async function listBarePrebuildFiles(hostDir) {
     let entries;
     try {

package/dist/src/commands/verify/resource-collectors.js

@@ -15,7 +15,8 @@ const DEFAULT_MEASUREMENT_DEPENDENCIES = {
 export async function acceptResourceCollectorPackaging(options) {
     const addons = await collectAddonsFromBundle({
         bundlePath: options.bundlePath,
-        projectRoot: options.projectRoot
+        projectRoot: options.projectRoot,
+        hosts: options.hosts
     });
     const collectors = new Map(addons
         .filter((addon) => isResourceCollectorPackage(addon.name))

package/dist/src/expo/plugins/patches/qvac-platform-addons.d.ts

@@ -0,0 +1,23 @@
+export declare const HOST_ADDON_IMPORT = "#host-addon";
+export interface PlatformAddonRoot {
+    dir: string;
+    pkg: {
+        name?: string;
+        version?: string;
+        addon?: boolean;
+    };
+}
+export declare function resolvePlatformAddonRoots(projectRoot: string, addonNames: string[], platform: string): PlatformAddonRoot[];
+/**
+ * Package `#host-addon` names for `host`, if that name belongs to `metaName`.
+ * `host` is a Bare host (`android-arm64`, `ios-arm64-simulator`, `darwin-arm64`)
+ * or a mobile build target (`android`, `ios`).
+ */
+export declare function resolveAddonPlatformPackage(metaName: string, hostAddon: unknown, host: string): string | null;
+/**
+ * First package name a `#host-addon` map points at for `host`.
+ * Android nests the package under its architecture; iOS is a flat list.
+ * A platform-only `android` target uses arm64, matching the current mobile host.
+ */
+export declare function resolvePlatformPackageName(hostAddon: unknown, host: string): string | null;
+//# sourceMappingURL=qvac-platform-addons.d.ts.map

package/dist/src/expo/plugins/patches/qvac-platform-addons.js

@@ -0,0 +1,94 @@
+/**
+ * Resolves split-addon platform packages from the meta package's `#host-addon`
+ * map. Linker, verify, and the missing-prebuild error all call this module so
+ * the slice name cannot drift from what the addon actually imports.
+ *
+ * Keep this file free of `@/` imports: the compiled JS is copied next to the
+ * patched `link.mjs` as `qvac-platform-addons.mjs`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export const HOST_ADDON_IMPORT = '#host-addon';
+const DEFAULT_ANDROID_CPU = 'arm64';
+export function resolvePlatformAddonRoots(projectRoot, addonNames, platform) {
+    const roots = [];
+    for (const name of addonNames) {
+        const root = resolvePlatformAddonRoot(projectRoot, name, platform);
+        if (root !== null)
+            roots.push(root);
+    }
+    return roots;
+}
+function resolvePlatformAddonRoot(projectRoot, metaName, platform) {
+    const metaManifest = readManifest(packageDir(projectRoot, metaName));
+    if (metaManifest === null)
+        return null;
+    const platformPackage = resolveAddonPlatformPackage(metaName, metaManifest.imports?.[HOST_ADDON_IMPORT], platform);
+    if (platformPackage === null)
+        return null;
+    const addonDir = path.join(packageDir(projectRoot, platformPackage), 'addon');
+    const addonManifest = readManifest(addonDir);
+    if (addonManifest === null || addonManifest.addon !== true)
+        return null;
+    if (!fs.existsSync(path.join(addonDir, 'prebuilds')))
+        return null;
+    return { dir: addonDir, pkg: addonManifest };
+}
+function packageDir(projectRoot, packageName) {
+    return path.join(projectRoot, 'node_modules', ...packageName.split('/'));
+}
+function readManifest(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Package `#host-addon` names for `host`, if that name belongs to `metaName`.
+ * `host` is a Bare host (`android-arm64`, `ios-arm64-simulator`, `darwin-arm64`)
+ * or a mobile build target (`android`, `ios`).
+ */
+export function resolveAddonPlatformPackage(metaName, hostAddon, host) {
+    const name = resolvePlatformPackageName(hostAddon, host);
+    if (name === null)
+        return null;
+    if (!name.startsWith(`${metaName}-`))
+        return null;
+    return name;
+}
+/**
+ * First package name a `#host-addon` map points at for `host`.
+ * Android nests the package under its architecture; iOS is a flat list.
+ * A platform-only `android` target uses arm64, matching the current mobile host.
+ */
+export function resolvePlatformPackageName(hostAddon, host) {
+    if (typeof host !== 'string' || host.length === 0)
+        return null;
+    const separator = host.indexOf('-');
+    const platform = separator === -1 ? host : host.slice(0, separator);
+    const cpu = separator === -1 ? '' : host.slice(separator + 1);
+    const branch = readBranch(hostAddon, platform);
+    const direct = packageName(branch);
+    if (direct !== null)
+        return direct;
+    const cpuKey = cpu.length > 0 ? cpu : DEFAULT_ANDROID_CPU;
+    return packageName(readBranch(branch, cpuKey));
+}
+function packageName(candidate) {
+    const name = Array.isArray(candidate) ? candidate[0] : candidate;
+    if (typeof name !== 'string' || name.startsWith('.'))
+        return null;
+    return name;
+}
+function readBranch(value, key) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    if (!Object.hasOwn(value, key))
+        return undefined;
+    return value[key];
+}

package/dist/src/expo/plugins/withMobileBundle.d.ts

@@ -1,4 +1,13 @@
 import type { ExpoConfig } from 'expo/config';
+/**
+ * Desktop-only spawn path, deferred so bare-pack does not walk `bare-process`
+ * -> `bare-posix` (no `android-arm64` prebuild). Mobile advisory uses
+ * in-process `@qvac/model-fit` (`fitParams`), not this subprocess.
+ */
+declare const MOBILE_UNSUPPORTED_MODULES: string[];
+type MobilePlatform = 'android' | 'ios';
+declare const MOBILE_HOSTS_BY_PLATFORM: Record<MobilePlatform, string[]>;
+/** Every mobile host, in platform order. The bundle covers all of them. */
 declare const MOBILE_HOSTS: string[];
 type BareKitLinkerPaths = {
     android: string | null;
@@ -11,6 +20,7 @@ type BareKitLinkerPaths = {
  * Uses `qvac.config.*` if present.
  */
 declare function withMobileBundle(config: ExpoConfig): ExpoConfig;
+declare function mobileHostsForPlatform(platform: string): string[];
 /** Runs the patched iOS linker after bundleSdk has written the current addons manifest. */
 declare function runIOSAddonLinker(linkerPath: string): Promise<void>;
 /**
@@ -18,7 +28,7 @@ declare function runIOSAddonLinker(linkerPath: string): Promise<void>;
  * the paths for each platform that was successfully patched.
  */
 declare function patchBareKitLinkers(projectRoot: string, qvacSdkPath: string): BareKitLinkerPaths;
-export { MOBILE_HOSTS, patchBareKitLinkers, runIOSAddonLinker };
-export type { BareKitLinkerPaths };
+export { MOBILE_HOSTS, MOBILE_HOSTS_BY_PLATFORM, MOBILE_UNSUPPORTED_MODULES, mobileHostsForPlatform, patchBareKitLinkers, runIOSAddonLinker };
+export type { BareKitLinkerPaths, MobilePlatform };
 export default withMobileBundle;
 //# sourceMappingURL=withMobileBundle.d.ts.map