@qvac/sdk 0.11.0 → 0.12.0

package/dist/commands/verify/addon-source.d.ts

@@ -0,0 +1,43 @@
+export type AddonSourceKind = "bare-pack-bundle" | "node-modules";
+export interface NativeAddon {
+    name: string;
+    version?: string;
+    packageJsonPath: string;
+    packageRoot: string;
+    enginesBare?: string;
+}
+export interface AddonPackageJson {
+    name?: string;
+    version?: string;
+    addon?: boolean;
+    engines?: {
+        bare?: string;
+    };
+}
+export interface ReadAddonPackageJsonOptions {
+    packageJsonPath: string;
+    expectedName?: string;
+}
+export interface InvalidPackageJsonRecord {
+    packageJsonPath: string;
+    expectedName?: string;
+    reason: string;
+}
+export interface ReadAddonPackageJsonResult {
+    found: boolean;
+    isAddon: boolean;
+    invalid?: InvalidPackageJsonRecord;
+    addon?: NativeAddon;
+}
+export declare function readAddonPackageJson(options: ReadAddonPackageJsonOptions): Promise<ReadAddonPackageJsonResult>;
+export interface CollectDiagnostics {
+    invalidPackageJsons: InvalidPackageJsonRecord[];
+    emptyResolutions: boolean;
+}
+export declare function createCollectDiagnostics(): CollectDiagnostics;
+export declare function formatAddonId(addon: {
+    name: string;
+    version?: string;
+}): string;
+export declare function deduplicateAddons(addons: NativeAddon[]): NativeAddon[];
+//# sourceMappingURL=addon-source.d.ts.map

package/dist/commands/verify/addon-source.js

@@ -0,0 +1,75 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+export async function readAddonPackageJson(options) {
+    const { packageJsonPath, expectedName } = options;
+    let raw;
+    try {
+        raw = await fsp.readFile(packageJsonPath, "utf8");
+    }
+    catch {
+        return { found: false, isAddon: false };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            found: true,
+            isAddon: false,
+            invalid: buildInvalid(packageJsonPath, expectedName, `malformed JSON: ${reason}`),
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            found: true,
+            isAddon: false,
+            invalid: buildInvalid(packageJsonPath, expectedName, "package.json is not a JSON object"),
+        };
+    }
+    const pkg = parsed;
+    if (pkg.addon !== true) {
+        return { found: true, isAddon: false };
+    }
+    const name = pkg.name ?? expectedName;
+    if (!name) {
+        return {
+            found: true,
+            isAddon: false,
+            invalid: buildInvalid(packageJsonPath, expectedName, "addon package.json is missing a `name` field"),
+        };
+    }
+    const addon = {
+        name,
+        packageJsonPath,
+        packageRoot: path.dirname(packageJsonPath),
+    };
+    if (typeof pkg.version === "string")
+        addon.version = pkg.version;
+    if (typeof pkg.engines?.bare === "string")
+        addon.enginesBare = pkg.engines.bare;
+    return { found: true, isAddon: true, addon };
+}
+function buildInvalid(packageJsonPath, expectedName, reason) {
+    const record = { packageJsonPath, reason };
+    if (expectedName !== undefined)
+        record.expectedName = expectedName;
+    return record;
+}
+export function createCollectDiagnostics() {
+    return { invalidPackageJsons: [], emptyResolutions: false };
+}
+export function formatAddonId(addon) {
+    return `${addon.name}@${addon.version ?? "unknown"}`;
+}
+export function deduplicateAddons(addons) {
+    const byKey = new Map();
+    for (const addon of addons) {
+        const key = `${addon.name}@${addon.version ?? "unknown"}::${addon.packageRoot}`;
+        if (!byKey.has(key))
+            byKey.set(key, addon);
+    }
+    return [...byKey.values()].sort((a, b) => formatAddonId(a).localeCompare(formatAddonId(b)) ||
+        a.packageRoot.localeCompare(b.packageRoot));
+}

package/dist/commands/verify/bundle-source.d.ts

@@ -0,0 +1,12 @@
+import { type CollectDiagnostics, type NativeAddon } from "./addon-source";
+export declare class InvalidBundleSourceError extends Error {
+    bundlePath: string;
+    constructor(bundlePath: string, cause: unknown);
+}
+export interface CollectAddonsFromBundleOptions {
+    bundlePath: string;
+    projectRoot: string;
+    diagnostics?: CollectDiagnostics;
+}
+export declare function collectAddonsFromBundle(options: CollectAddonsFromBundleOptions): Promise<NativeAddon[]>;
+//# sourceMappingURL=bundle-source.d.ts.map

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

@@ -0,0 +1,53 @@
+import { promises as fsp } from "node:fs";
+import { buildNestedPathIndex, extractBarePackHeader, extractPackedString, } from "../bundle/manifest.js";
+import { deduplicateAddons, readAddonPackageJson, } from "./addon-source.js";
+export class InvalidBundleSourceError extends Error {
+    bundlePath;
+    constructor(bundlePath, cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        super(`Bundle at ${bundlePath} could not be parsed as a bare-pack bundle.\n\n` +
+            `  Reason: ${reason}\n\n` +
+            "  Make sure the path points to a worker.bundle.js generated by bundleSdk.");
+        this.name = "InvalidBundleSourceError";
+        this.bundlePath = bundlePath;
+    }
+}
+export async function collectAddonsFromBundle(options) {
+    const { bundlePath, projectRoot, diagnostics } = options;
+    let bundleText;
+    try {
+        bundleText = await fsp.readFile(bundlePath, "utf8");
+    }
+    catch (error) {
+        throw new InvalidBundleSourceError(bundlePath, error);
+    }
+    let resolutions;
+    try {
+        const packed = extractPackedString(bundleText);
+        const header = extractBarePackHeader(packed);
+        resolutions = header.resolutions ?? {};
+    }
+    catch (error) {
+        throw new InvalidBundleSourceError(bundlePath, error);
+    }
+    if (diagnostics !== undefined && Object.keys(resolutions).length === 0) {
+        diagnostics.emptyResolutions = true;
+    }
+    const pathsByPackage = buildNestedPathIndex(resolutions, projectRoot);
+    const addons = [];
+    for (const [pkgName, candidates] of pathsByPackage) {
+        for (const candidate of candidates) {
+            const result = await readAddonPackageJson({
+                packageJsonPath: candidate,
+                expectedName: pkgName,
+            });
+            if (result.isAddon && result.addon) {
+                addons.push(result.addon);
+            }
+            else if (result.invalid !== undefined && diagnostics !== undefined) {
+                diagnostics.invalidPackageJsons.push(result.invalid);
+            }
+        }
+    }
+    return deduplicateAddons(addons);
+}

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

@@ -0,0 +1,59 @@
+import { type AddonSourceKind, type NativeAddon } from "./addon-source";
+import { type MissingPrebuildIssue } from "./prebuilds";
+import { type AbiIssue, type BareRuntimeResolution } from "./abi";
+export interface VerifyBundleOptions {
+    projectRoot: string;
+    addonsSource: string;
+    hosts: string[];
+    bareRuntimeVersion?: string;
+    configPath?: string;
+}
+export interface InvalidSourceIssue {
+    code: 'invalid-source';
+    level: 'error';
+    message: string;
+    addonsSource: string;
+}
+export interface InvalidRuntimeVersionIssue {
+    code: 'invalid-runtime-version';
+    level: 'error';
+    message: string;
+    providedValue: string;
+    source: 'flag' | 'config';
+}
+export interface ConfigLoadFailedIssue {
+    code: 'config-load-failed';
+    level: 'warning';
+    message: string;
+    configPath: string;
+    reason: string;
+}
+export interface InvalidPackageJsonIssue {
+    code: 'invalid-package-json';
+    level: 'warning';
+    message: string;
+    packageJsonPath: string;
+    expectedName?: string;
+    reason: string;
+}
+export interface EmptyBundleResolutionsIssue {
+    code: 'empty-bundle-resolutions';
+    level: 'warning';
+    message: string;
+    bundlePath: string;
+}
+export type VerifyBundleIssue = MissingPrebuildIssue | AbiIssue | InvalidSourceIssue | InvalidRuntimeVersionIssue | ConfigLoadFailedIssue | InvalidPackageJsonIssue | EmptyBundleResolutionsIssue;
+export interface VerifyBundleResult {
+    addonsSource: string;
+    resolvedAddonsSource: string;
+    sourceKind: AddonSourceKind | null;
+    hosts: string[];
+    runtime: BareRuntimeResolution | null;
+    addons: NativeAddon[];
+    issues: VerifyBundleIssue[];
+}
+export declare function verifyBundle(options: VerifyBundleOptions): Promise<VerifyBundleResult>;
+export declare function hasErrors(result: VerifyBundleResult): boolean;
+export declare function hasWarnings(result: VerifyBundleResult): boolean;
+export declare function formatVerifyBundleResult(result: VerifyBundleResult): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/verify/index.js

@@ -0,0 +1,371 @@
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { resolveConfigFileInProject, loadConfigFromPath, } from "../../client/config-loader/resolve-config.node.js";
+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 { checkAbi, formatConfigLabel, normalizeVersion, resolveBareRuntime, } from "./abi.js";
+export async function verifyBundle(options) {
+    const { projectRoot, addonsSource, hosts, bareRuntimeVersion, configPath } = options;
+    const resolvedAddonsSource = path.isAbsolute(addonsSource)
+        ? addonsSource
+        : path.resolve(projectRoot, addonsSource);
+    if (hosts.length === 0) {
+        return {
+            addonsSource,
+            resolvedAddonsSource,
+            sourceKind: null,
+            hosts,
+            runtime: null,
+            addons: [],
+            issues: [
+                {
+                    code: 'invalid-source',
+                    level: 'error',
+                    addonsSource,
+                    message: 'At least one host is required.'
+                }
+            ]
+        };
+    }
+    let invalidRuntimeVersion = null;
+    if (bareRuntimeVersion !== undefined && normalizeVersion(bareRuntimeVersion) === null) {
+        invalidRuntimeVersion = {
+            code: 'invalid-runtime-version',
+            level: 'error',
+            providedValue: bareRuntimeVersion,
+            source: 'flag',
+            message: `bareRuntimeVersion "${bareRuntimeVersion}" is not a valid semver. ` +
+                'Use a version like 1.15.0 (with optional v-prefix and pre-release tag) or omit it to use auto-detection.'
+        };
+    }
+    let configRuntimeVersion;
+    let resolvedConfigPath = null;
+    let configLoadFailed = null;
+    try {
+        resolvedConfigPath = await resolveConfigFileInProject(projectRoot, configPath ?? undefined);
+        if (resolvedConfigPath !== null) {
+            const config = await loadConfigFromPath(resolvedConfigPath);
+            if (typeof config.bareRuntimeVersion === "string") {
+                configRuntimeVersion = config.bareRuntimeVersion;
+            }
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (configPath !== undefined) {
+            return {
+                addonsSource,
+                resolvedAddonsSource,
+                sourceKind: null,
+                hosts,
+                runtime: null,
+                addons: [],
+                issues: [
+                    {
+                        code: 'invalid-source',
+                        level: 'error',
+                        addonsSource,
+                        message: `Failed to load config from '${configPath}': ${message}`
+                    }
+                ]
+            };
+        }
+        if (resolvedConfigPath !== null) {
+            configLoadFailed = {
+                code: 'config-load-failed',
+                level: 'warning',
+                configPath: resolvedConfigPath,
+                reason: message,
+                message: `Found ${formatConfigLabel(projectRoot, resolvedConfigPath)} but failed to load it: ${message}. ` +
+                    'Falling back to auto-detection for Bare runtime; the project-pinned ' +
+                    '`bareRuntimeVersion` is being ignored. Fix the config file or pass `configPath` explicitly to surface it as an error.'
+            };
+        }
+    }
+    if (invalidRuntimeVersion === null &&
+        bareRuntimeVersion === undefined &&
+        configRuntimeVersion !== undefined &&
+        normalizeVersion(configRuntimeVersion) === null) {
+        invalidRuntimeVersion = {
+            code: 'invalid-runtime-version',
+            level: 'error',
+            providedValue: configRuntimeVersion,
+            source: 'config',
+            message: `\`bareRuntimeVersion\` in ${formatConfigLabel(projectRoot, resolvedConfigPath ?? undefined)} ` +
+                `"${configRuntimeVersion}" is not a valid semver. ` +
+                'Use a version like 1.15.0 (with optional v-prefix and pre-release tag), or remove the field to use auto-detection.'
+        };
+    }
+    const sourceKind = await detectSourceKind(resolvedAddonsSource);
+    if (sourceKind === null) {
+        return {
+            addonsSource,
+            resolvedAddonsSource,
+            sourceKind: null,
+            hosts,
+            runtime: null,
+            addons: [],
+            issues: [
+                {
+                    code: 'invalid-source',
+                    level: 'error',
+                    addonsSource,
+                    message: `--addons-source ${addonsSource} is not a readable file or directory ` +
+                        `(resolved to ${resolvedAddonsSource}).`
+                }
+            ]
+        };
+    }
+    const diagnostics = createCollectDiagnostics();
+    let addons;
+    try {
+        addons = sourceKind === 'bare-pack-bundle'
+            ? await collectAddonsFromBundle({
+                bundlePath: resolvedAddonsSource,
+                projectRoot,
+                diagnostics
+            })
+            : await collectAddonsFromNodeModules({
+                nodeModulesRoot: resolvedAddonsSource,
+                diagnostics
+            });
+    }
+    catch (error) {
+        if (error instanceof InvalidBundleSourceError ||
+            error instanceof InvalidNodeModulesSourceError) {
+            return {
+                addonsSource,
+                resolvedAddonsSource,
+                sourceKind,
+                hosts,
+                runtime: null,
+                addons: [],
+                issues: [
+                    {
+                        code: 'invalid-source',
+                        level: 'error',
+                        addonsSource,
+                        message: error.message
+                    }
+                ]
+            };
+        }
+        throw error;
+    }
+    const issues = [];
+    if (configLoadFailed !== null)
+        issues.push(configLoadFailed);
+    if (invalidRuntimeVersion !== null)
+        issues.push(invalidRuntimeVersion);
+    issues.push(...buildInvalidPackageJsonIssues(diagnostics.invalidPackageJsons));
+    if (sourceKind === 'bare-pack-bundle' && diagnostics.emptyResolutions) {
+        issues.push({
+            code: 'empty-bundle-resolutions',
+            level: 'warning',
+            bundlePath: resolvedAddonsSource,
+            message: `Bundle at ${resolvedAddonsSource} has no resolutions in its bare-pack header ` +
+                '(0 packages discoverable). The verifier cannot inspect any addons in this bundle; ' +
+                '`Native addon verification passed` would be vacuous. Regenerate the bundle via ' +
+                '`qvac bundle sdk` and re-run, or check for a corrupted/empty bundle file.'
+        });
+    }
+    for (const addon of addons) {
+        const prebuildIssues = await checkPrebuilds({ addon, hosts });
+        issues.push(...prebuildIssues);
+    }
+    let runtime = null;
+    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';
+        }
+        runtime = await resolveBareRuntime(runtimeOptions);
+        issues.push(...checkAbi({ addons, runtime }));
+    }
+    return {
+        addonsSource,
+        resolvedAddonsSource,
+        sourceKind,
+        hosts,
+        runtime,
+        addons,
+        issues
+    };
+}
+function buildInvalidPackageJsonIssues(records) {
+    return records.map((record) => {
+        const issue = {
+            code: 'invalid-package-json',
+            level: 'warning',
+            packageJsonPath: record.packageJsonPath,
+            reason: record.reason,
+            message: `Skipping ${record.expectedName ?? record.packageJsonPath}: ` +
+                `${record.reason}. The package is being treated as a non-addon; if it ships ` +
+                'native code, the verifier cannot check its prebuilds or ABI. ' +
+                'Fix the package.json or remove the package.'
+        };
+        if (record.expectedName !== undefined)
+            issue.expectedName = record.expectedName;
+        return issue;
+    });
+}
+async function detectSourceKind(resolvedAddonsSource) {
+    try {
+        const stat = await fsp.stat(resolvedAddonsSource);
+        if (stat.isFile())
+            return 'bare-pack-bundle';
+        if (stat.isDirectory())
+            return 'node-modules';
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function hasErrors(result) {
+    return result.issues.some((issue) => issue.level === 'error');
+}
+export function hasWarnings(result) {
+    return result.issues.some((issue) => issue.level === 'warning');
+}
+export function formatVerifyBundleResult(result) {
+    const sections = [];
+    const hostList = result.hosts.join(', ');
+    if (result.issues.length === 0) {
+        sections.push(`Native addon verification passed for ${result.addons.length} ` +
+            `addon${result.addons.length === 1 ? '' : 's'} across ${result.hosts.length} ` +
+            `host${result.hosts.length === 1 ? '' : 's'}: ${hostList}`);
+        if (result.addons.length > 0) {
+            sections.push('');
+            sections.push('  Verified addons:');
+            for (const addon of result.addons) {
+                sections.push(`    - ${formatAddonId(addon)}`);
+            }
+        }
+        return sections.join('\n');
+    }
+    if (hasErrors(result)) {
+        sections.push('Native addon verification failed:');
+    }
+    else {
+        sections.push('Native addon verification produced warnings:');
+    }
+    sections.push('');
+    sections.push(...formatMissingPrebuilds(result.issues));
+    sections.push(...formatAbiMismatches(result.issues));
+    sections.push(...formatInvalidRuntimeVersions(result.issues));
+    sections.push(...formatMalformedEnginesBare(result.issues));
+    sections.push(...formatConfigLoadFailed(result.issues));
+    sections.push(...formatInvalidPackageJsons(result.issues));
+    sections.push(...formatEmptyBundleResolutions(result.issues));
+    sections.push(...formatUnknownRuntime(result.issues));
+    sections.push(...formatInvalidSources(result.issues));
+    return sections.join('\n').trimEnd();
+}
+function formatConfigLoadFailed(issues) {
+    const matches = issues.filter((issue) => issue.code === 'config-load-failed');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Config load failed:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatMissingPrebuilds(issues) {
+    const matches = issues.filter((issue) => issue.code === 'missing-prebuild');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Missing prebuild:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.addon} for ${issue.host}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatAbiMismatches(issues) {
+    const matches = issues.filter((issue) => issue.code === 'abi-mismatch');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  ABI mismatch:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.addon} 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)
+        return [];
+    const lines = ['  Unknown runtime version:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatMalformedEnginesBare(issues) {
+    const matches = issues.filter((issue) => issue.code === 'malformed-engines-bare');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Malformed engines.bare:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatInvalidSources(issues) {
+    const matches = issues.filter((issue) => issue.code === 'invalid-source');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Invalid source:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatInvalidRuntimeVersions(issues) {
+    const matches = issues.filter((issue) => issue.code === 'invalid-runtime-version');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Invalid Bare runtime version:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatInvalidPackageJsons(issues) {
+    const matches = issues.filter((issue) => issue.code === 'invalid-package-json');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Invalid package.json (skipped):'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatEmptyBundleResolutions(issues) {
+    const matches = issues.filter((issue) => issue.code === 'empty-bundle-resolutions');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Empty bundle resolutions:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}

package/dist/commands/verify/node-modules-source.d.ts

@@ -0,0 +1,11 @@
+import { type CollectDiagnostics, type NativeAddon } from "./addon-source";
+export declare class InvalidNodeModulesSourceError extends Error {
+    nodeModulesPath: string;
+    constructor(nodeModulesPath: string, cause: unknown);
+}
+export interface CollectAddonsFromNodeModulesOptions {
+    nodeModulesRoot: string;
+    diagnostics?: CollectDiagnostics;
+}
+export declare function collectAddonsFromNodeModules(options: CollectAddonsFromNodeModulesOptions): Promise<NativeAddon[]>;
+//# sourceMappingURL=node-modules-source.d.ts.map