@qvac/sdk 0.10.2 → 0.12.0

package/dist/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/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