@qvac/sdk 0.18.2 → 0.19.0

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

@@ -0,0 +1,125 @@
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import semver from 'semver';
+import { formatAddonId } from './addon-source.js';
+const RUNTIME_PACKAGES = [
+    { source: 'bare-runtime', packageName: 'bare-runtime' },
+    { source: 'bare', packageName: 'bare' }
+];
+export async function resolveBareRuntime(options) {
+    if (options.explicitVersion) {
+        // Caller (verifyBundle) pre-validates explicitVersion via normalizeVersion.
+        return {
+            resolved: true,
+            runtime: {
+                version: normalizeVersion(options.explicitVersion),
+                source: options.explicitSource ?? 'flag'
+            }
+        };
+    }
+    const tried = [];
+    for (const candidate of RUNTIME_PACKAGES) {
+        const pkgJsonPath = path.join(options.projectRoot, 'node_modules', candidate.packageName, 'package.json');
+        tried.push(pkgJsonPath);
+        const version = await tryReadRuntimeVersion(pkgJsonPath);
+        if (version) {
+            return {
+                resolved: true,
+                runtime: { version, source: candidate.source }
+            };
+        }
+    }
+    return {
+        resolved: false,
+        error: {
+            reason: 'Unable to detect installed Bare runtime version',
+            triedPaths: tried
+        }
+    };
+}
+async function tryReadRuntimeVersion(pkgJsonPath) {
+    let raw;
+    try {
+        raw = await fsp.readFile(pkgJsonPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const version = parsed['version'];
+    return typeof version === 'string' ? normalizeVersion(version) : null;
+}
+export function normalizeVersion(value) {
+    const coerced = semver.coerce(value, { includePrerelease: true });
+    return coerced ? coerced.version : null;
+}
+export function formatConfigLabel(projectRoot, configPath) {
+    if (!configPath)
+        return 'qvac.config';
+    const rel = path.relative(projectRoot, configPath);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+        return configPath;
+    return rel;
+}
+export function checkAbi(options) {
+    const { addons, runtime } = options;
+    const addonsWithEngines = addons.filter((addon) => addon.enginesBare !== undefined);
+    if (addonsWithEngines.length === 0)
+        return [];
+    const issues = [];
+    const checkable = [];
+    for (const addon of addonsWithEngines) {
+        const range = addon.enginesBare;
+        if (!range)
+            continue;
+        if (!semver.validRange(range)) {
+            issues.push({
+                code: 'malformed-engines-bare',
+                level: 'warning',
+                addon: formatAddonId(addon),
+                enginesBare: range,
+                message: `${formatAddonId(addon)} declares engines.bare "${range}", which is ` +
+                    'not a valid semver range. ABI check skipped for this addon. ' +
+                    'Report this to the addon maintainer.'
+            });
+            continue;
+        }
+        checkable.push({ addon, range });
+    }
+    if (checkable.length === 0)
+        return issues;
+    if (!runtime.resolved) {
+        issues.push({
+            code: 'unknown-runtime-version',
+            level: 'warning',
+            message: `${runtime.error.reason}. ABI checks skipped for ${checkable.length} ` +
+                `addon${checkable.length === 1 ? '' : 's'}. ` +
+                'Pass bareRuntimeVersion to enable strict ABI verification.',
+            triedPaths: runtime.error.triedPaths
+        });
+        return issues;
+    }
+    for (const { addon, range } of checkable) {
+        if (semver.satisfies(runtime.runtime.version, range))
+            continue;
+        issues.push({
+            code: 'abi-mismatch',
+            level: 'error',
+            addon: formatAddonId(addon),
+            enginesBare: range,
+            runtimeVersion: runtime.runtime.version,
+            message: `${formatAddonId(addon)} requires bare ${range}, ` +
+                `runtime is ${runtime.runtime.version} (from ${runtime.runtime.source}).`
+        });
+    }
+    return issues;
+}

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

@@ -0,0 +1,12 @@
+import { type CollectDiagnostics, type NativeAddon } from './addon-source.js';
+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/src/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/src/commands/verify/index.d.ts

@@ -0,0 +1,59 @@
+import { type AddonSourceKind, type NativeAddon } from './addon-source.js';
+import { type MissingPrebuildIssue } from './prebuilds.js';
+import { type AbiIssue, type BareRuntimeResolution } from './abi.js';
+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/src/commands/verify/index.js

@@ -0,0 +1,372 @@
+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/src/commands/verify/node-modules-source.d.ts

@@ -0,0 +1,11 @@
+import { type CollectDiagnostics, type NativeAddon } from './addon-source.js';
+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