crossbind 0.0.1 → 2.0.0-beta.51

package/src/utils/cppFieldBindings.js

@@ -0,0 +1,23 @@
+// SWIG's -embind backend emits functions and constructors but no member variables, so
+// public fields never reach JS from the generated bridge alone. This post-pass injects
+// embind .property lines for the value-semantics fields parseCppSurface captured - the
+// same post-processing precedent as bridgeAsyncGuard.
+
+export function buildFieldPropertyLines(cls) {
+    return (cls.fields ?? []).map((f) => `.property("${f.name}", &${cls.name}::${f.name})`);
+}
+
+export function injectFieldBindings(bridgeContent, model) {
+    let out = bridgeContent;
+    for (const cls of model.classes ?? []) {
+        const lines = buildFieldPropertyLines(cls)
+            .filter((line) => !out.includes(line));
+        if (!lines.length) continue;
+        // Lazy template match still lands on the right opener: the first `>(\s*"Name")`
+        // closes the template list even when it contains nested arguments like base<T>.
+        const opener = new RegExp(`(emscripten::class_<[\\s\\S]*?>\\s*\\(\\s*"${cls.name}"\\s*\\))`);
+        if (!opener.test(out)) continue;
+        out = out.replace(opener, `$1\n    ${lines.join('\n    ')}`);
+    }
+    return out;
+}

package/src/utils/dependencyRebuild.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import loadJson from './loadJson.js';
+import { getOverrideKey } from './overrideDependency.js';
+import { getContentHash } from './hash.js';
+
+export function isCached(depsDir, targets, key, dep, hasIos) {
+    if (loadJson(`${depsDir}/.crossbind-rebuild.json`)?.key !== key) return false;
+    // buildLib writes this last; without it the dep is silently dropped from CMake params,
+    // so a half-written cache (killed build) must count as a miss and trigger a rebuild.
+    if (!fs.existsSync(`${depsDir}/dist/prebuilt/CMakeLists.txt`)) return false;
+    if (!targets.every((t) => fs.existsSync(`${depsDir}/dist/prebuilt/${t.path}/lib`))) return false;
+    if (hasIos && !dep.export.libName.every((n) => fs.existsSync(`${depsDir}/${n}.xcframework`))) return false;
+    return true;
+}
+
+export function getRebuildDeps(allDependencies, rebuildOption) {
+    const selector = resolveSelector(rebuildOption);
+    return allDependencies.filter((d) => {
+        if (d.rebuild || d.overrideBuild) return true;
+        if (!selector) return false;
+        if (selector === 'ALL') return true;
+        const names = [d.general?.name, d.package?.name, d.general?.alias?.package].filter(Boolean);
+        return names.some((n) => selector.includes(n));
+    });
+}
+
+function resolveSelector(rebuildOption) {
+    const raw = rebuildOption !== undefined ? rebuildOption : process.env.CROSSBIND_REBUILD_DEPS;
+    if (raw === undefined || raw === null || raw === false || raw === '') return null;
+    if (raw === true || raw === '1' || raw === 'true' || raw === 'all') return 'ALL';
+    return String(raw).split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+export function orderByDependencies(deps) {
+    const byProject = new Map(deps.map((d) => [d.paths.project, d]));
+    const result = [];
+    const visited = new Set();
+    const visit = (d) => {
+        if (visited.has(d.paths.project)) return;
+        visited.add(d.paths.project);
+        (d.allDependencies || []).forEach((sub) => {
+            const inSet = byProject.get(sub.paths.project);
+            if (inSet) visit(inSet);
+        });
+        result.push(d);
+    };
+    deps.forEach(visit);
+    return result;
+}
+
+export function cleanDepsCache(cacheDir, dirNames) {
+    const depsRoot = `${cacheDir}/deps`;
+    if (!fs.existsSync(depsRoot)) return [];
+    const all = fs.readdirSync(depsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+    const removed = dirNames?.length ? all.filter((n) => dirNames.includes(n)) : all;
+    removed.forEach((n) => {
+        fs.rmSync(`${depsRoot}/${n}`, { recursive: true, force: true });
+        fs.rmSync(`${depsRoot}/${n}.lock`, { force: true });
+    });
+    if (!dirNames?.length) fs.rmSync(depsRoot, { recursive: true, force: true });
+    return removed;
+}
+
+// Mirrors loadConfig's marker consumption: a dep counts iff its marker key equals the
+// current override key. The stamp changes exactly when the consumed set changes, so
+// callers (e.g. the RN gradle plugin) can use it as a CMake-configure cache key.
+// Which target dirs a dependency currently ships, so a prebuilt that appears (or is rebuilt)
+// after the last configure busts it too. Rebuilt-from-source deps carry a marker key; prebuilt
+// ones carry nothing, and without this they used to stay invisible to the stamp - a refreshed
+// artifact then never entered the link until the CMake cache was wiped by hand.
+function prebuiltFingerprint(dep) {
+    const dir = dep.paths?.cmakeDir;
+    // No prebuilt at all contributes nothing, so a dependency set with neither markers nor
+    // artifacts still stamps as "none".
+    if (!dir || !fs.existsSync(dir)) return null;
+    const targets = fs.readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => {
+            const stamp = fs.statSync(`${dir}/${e.name}`).mtimeMs;
+            return `${e.name}@${stamp}`;
+        })
+        .sort();
+    return `${dep.general.name}:${targets.join(',')}`;
+}
+
+export function computeDependenciesStamp(allDependencies, cacheDir) {
+    const keys = allDependencies
+        .map((d) => {
+            const marker = loadJson(`${cacheDir}/deps/${d.general.name}/.crossbind-rebuild.json`);
+            return marker?.key === getOverrideKey(d) ? marker.key : null;
+        })
+        .filter(Boolean)
+        .sort();
+    const prebuilts = allDependencies.map(prebuiltFingerprint).filter(Boolean).sort();
+    if (keys.length === 0 && prebuilts.length === 0) return 'none';
+    return getContentHash([...keys, ...prebuilts].join('|'));
+}

package/src/utils/dirLock.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import logger from './logger.js';
+
+// A dependency source build can legitimately run for a long time; anything older
+// is assumed to be a crashed process whose lock must be broken.
+const DEFAULT_STALE_MS = 60 * 60 * 1000;
+const DEFAULT_POLL_MS = 2000;
+
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+
+// Reads the PID recorded in the lock file and reports whether that process is
+// still running: 'alive' (signal delivered, or owned by another user), 'dead'
+// (no such process), or 'unknown' (missing/unparseable PID).
+export function lockHolderStatus(lockPath) {
+    let pid;
+    try {
+        pid = Number.parseInt(fs.readFileSync(lockPath, 'utf8').trim(), 10);
+    } catch {
+        return 'unknown';
+    }
+    if (!Number.isInteger(pid) || pid <= 0) return 'unknown';
+    try {
+        process.kill(pid, 0);
+        return 'alive';
+    } catch (err) {
+        if (err.code === 'ESRCH') return 'dead';
+        if (err.code === 'EPERM') return 'alive';
+        return 'unknown';
+    }
+}
+
+export default async function withDirLock(lockPath, fn, options = {}) {
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+
+    let hasWarned = false;
+    for (;;) {
+        try {
+            const fd = fs.openSync(lockPath, 'wx');
+            fs.writeSync(fd, String(process.pid));
+            fs.closeSync(fd);
+            break;
+        } catch (e) {
+            if (e.code !== 'EEXIST') throw e;
+            const status = lockHolderStatus(lockPath);
+            const mtimeMs = fs.statSync(lockPath, { throwIfNoEntry: false })?.mtimeMs;
+            const mtimeStale = mtimeMs !== undefined && Date.now() - mtimeMs > staleMs;
+            // A provably-dead holder (e.g. a Ctrl-C that skipped the finally cleanup) is broken
+            // at once; a live holder is never stolen, even past the stale window; when the holder
+            // can't be determined we fall back to the mtime age.
+            if (status === 'dead' || (status !== 'alive' && mtimeStale)) {
+                logger.info(`crossbind: breaking stale lock ${lockPath} (holder ${status}).`);
+                fs.rmSync(lockPath, { force: true });
+                continue;
+            }
+            if (!hasWarned) {
+                logger.info(`crossbind: waiting for ${lockPath} (another build is working on this dependency)…`);
+                hasWarned = true;
+            }
+            await sleep(pollMs);
+        }
+    }
+
+    try {
+        return await fn();
+    } finally {
+        fs.rmSync(lockPath, { force: true });
+    }
+}

package/src/utils/downloadAndExtractFile.js

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import fs, { mkdirSync } from 'node:fs';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+export default async function downloadAndExtractFile(url, output, sha256) {
+    if (fs.existsSync(`${output}/source`)) {
+        return false;
+    }
+    const filePath = await downloadFile(url, output);
+    verifyIntegrity(filePath, url, sha256);
+    extractArchive(filePath, url, output);
+    return true;
+}
+
+// Extraction runs through the system tar (GNU tar and bsdtar both detect gzip/bzip2/xz, and
+// every platform the engine builds on ships one). Extracting into a scratch directory keeps
+// the archive from choosing where its files land, and gives the upstream root folder - which
+// recipes address as build/source - one place to be renamed from.
+function extractArchive(filePath, url, output) {
+    const work = `${output}/.extract`;
+    fs.rmSync(work, { recursive: true, force: true });
+    mkdirSync(work, { recursive: true });
+    try {
+        const tar = spawnSync('tar', ['-xf', filePath, '-C', work], { encoding: 'utf8' });
+        if (tar.error) {
+            throw new Error(`crossbind: cannot run tar to extract ${filePath}: ${tar.error.message}`);
+        }
+        if (tar.status !== 0) {
+            throw new Error(`crossbind: extracting ${filePath} (from ${url}) failed: ${(tar.stderr || '').trim() || `tar exited ${tar.status}`}`);
+        }
+        const entries = fs.readdirSync(work, { withFileTypes: true });
+        if (entries.length === 0) {
+            throw new Error(`crossbind: downloaded archive ${filePath} is empty or not a supported archive (from ${url}).`);
+        }
+        // Release tarballs carry one root folder; anything else is treated as the root itself.
+        const root = entries.length === 1 && entries[0].isDirectory() ? `${work}/${entries[0].name}` : work;
+        fs.renameSync(root, `${output}/source`);
+    } finally {
+        fs.rmSync(work, { recursive: true, force: true });
+    }
+}
+
+// Verifies the downloaded archive against the sha256 pinned in the build recipe. A missing pin
+// is skipped (packages are pinned incrementally; check:sources flags the gaps); a MISMATCH
+// refuses the build, so a hijacked mirror or a re-tagged upstream cannot feed arbitrary C++ to
+// the compiler.
+export function verifyIntegrity(filePath, url, sha256) {
+    if (!sha256) return;
+    const actual = crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+    if (actual !== String(sha256).toLowerCase()) {
+        fs.rmSync(filePath, { force: true });
+        throw new Error(
+            `crossbind: source integrity check failed for ${url}\n`
+            + `  expected sha256: ${sha256}\n`
+            + `  actual   sha256: ${actual}\n`
+            + 'Refusing to build. If you intentionally bumped nativeVersion, update the recipe sha256.',
+        );
+    }
+}
+
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+
+// What lands here is compiled, so it may not arrive over a connection anyone can rewrite.
+// Loopback is exempt so tests can serve fixtures without a certificate.
+export function assertHttps(target, context = target) {
+    const { protocol, hostname } = new URL(target);
+    if (protocol !== 'https:' && !LOOPBACK.has(hostname)) {
+        throw new Error(`crossbind: refusing to download ${context} over ${protocol}// - upstream sources must come over https.`);
+    }
+}
+
+// fetch follows redirects itself, which release downloads rely on (github and the osgeo
+// mirrors both bounce), so the download needs no redirect library of its own.
+export async function downloadFile(url, folder) {
+    mkdirSync(folder, { recursive: true });
+    const dest = `${folder}/${path.basename(url)}`;
+    if (fs.existsSync(dest)) return dest;
+
+    assertHttps(url);
+    let response;
+    try {
+        response = await fetch(url, { headers: { 'User-Agent': 'curl/8.7.1' }, redirect: 'follow' });
+    } catch (err) {
+        throw new Error(`crossbind: cannot reach ${url}: ${err.message}`, { cause: err });
+    }
+    // A redirect chain must not be able to downgrade the transport on its last hop.
+    if (response.url) assertHttps(response.url, `${url} (redirected to ${response.url})`);
+    if (!response.ok) {
+        throw new Error(`crossbind: download failed for ${url} — HTTP ${response.status}.`);
+    }
+    try {
+        await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(dest));
+    } catch (err) {
+        // A half-written archive would fail its hash check later with a confusing message.
+        fs.rmSync(dest, { force: true });
+        throw new Error(`crossbind: download failed for ${url}: ${err.message}`, { cause: err });
+    }
+    return dest;
+}

package/src/utils/familyManifest.js

@@ -0,0 +1,17 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+// Upstream truth (license, provenance identity) lives on the FAMILY package (contract D);
+// variants depend on their family.
+export default function familyManifestOf(node) {
+    const familyName = node.general?.alias?.package;
+    if (!familyName || !node.paths?.project) return null;
+    try {
+        const req = createRequire(path.join(node.paths.project, 'package.json'));
+        const manifestPath = req.resolve(`${familyName}/package.json`);
+        return { manifest: JSON.parse(fs.readFileSync(manifestPath, 'utf8')), dir: path.dirname(manifestPath) };
+    } catch {
+        return null;
+    }
+}

package/src/utils/findFiles.js

@@ -0,0 +1,5 @@
+import { glob } from 'glob';
+
+export default function findFiles(regex, options = {}) {
+    return glob.sync(regex, { absolute: true, posix: true, follow: true, ...options }).map(p => p.replace('//?/', ''));
+}

package/src/utils/fixPackageName.js

@@ -0,0 +1,7 @@
+export default function fixPackageName(name) {
+    if (!name) {
+        return null;
+    }
+
+    return name.replace(/[^a-zA-Z0-9-_]+/g, '');
+}

package/src/utils/flattenConfigForTable.js

@@ -0,0 +1,75 @@
+const isPlainObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+
+// Object maps with at least this many object-valued entries (e.g. allDependencyPaths,
+// keyed per target) collapse to their key list instead of exploding into rows.
+const LARGE_MAP_MIN_KEYS = 8;
+
+function relativizePath(value, base) {
+    if (base && typeof value === 'string' && value.startsWith(`${base}/`)) {
+        return value.slice(base.length + 1);
+    }
+    return value;
+}
+
+function truncateMiddle(value, max) {
+    if (typeof value !== 'string' || value.length <= max) return value;
+    const head = Math.ceil((max - 1) / 2);
+    const tail = Math.floor((max - 1) / 2);
+    return `${value.slice(0, head)}…${value.slice(value.length - tail)}`;
+}
+
+function formatScalar(value, base, maxLen) {
+    if (typeof value === 'function') return '[Function]';
+    if (typeof value === 'string') return truncateMiddle(relativizePath(value, base), maxLen);
+    return value;
+}
+
+// Flattens a resolved crossbind config into a { 'dotted.key': displayValue } map so
+// console.table renders a readable two-column view instead of one column per
+// nested sub-key. Paths are shown relative to base and long values truncated in
+// the middle; dependency arrays collapse to names, large per-target maps collapse
+// to their keys, and other structures recurse with dotted/indexed keys.
+export default function flattenConfigForTable(config, { base = null, maxDepth = 5, maxValueLength = 80 } = {}) {
+    const out = {};
+
+    const walk = (value, prefix, depth) => {
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                out[prefix] = '[]';
+            } else if (value.every((v) => v === null || typeof v !== 'object')) {
+                out[prefix] = truncateMiddle(value.map((v) => relativizePath(v, base)).join(', '), maxValueLength);
+            } else {
+                const names = value.map((v) => v?.general?.name ?? v?.package?.name).filter(Boolean);
+                if (names.length === value.length) {
+                    out[prefix] = names.join(', ');
+                } else if (depth <= 0) {
+                    out[prefix] = `<${value.length} items>`;
+                } else {
+                    value.forEach((v, i) => walk(v, `${prefix}.${i}`, depth - 1));
+                }
+            }
+            return;
+        }
+
+        if (!isPlainObject(value)) {
+            out[prefix] = formatScalar(value, base, maxValueLength);
+            return;
+        }
+
+        const keys = Object.keys(value);
+        const isLargeObjectMap = prefix !== '' && keys.length >= LARGE_MAP_MIN_KEYS
+            && keys.every((k) => isPlainObject(value[k]));
+        if (keys.length === 0) {
+            out[prefix] = '{}';
+        } else if (isLargeObjectMap) {
+            out[prefix] = truncateMiddle(keys.join(', '), maxValueLength);
+        } else if (depth <= 0) {
+            out[prefix] = '{…}';
+        } else {
+            keys.forEach((k) => walk(value[k], prefix ? `${prefix}.${k}` : k, depth - 1));
+        }
+    };
+
+    walk(config, '', maxDepth);
+    return out;
+}

package/src/utils/getAbsolutePath.js

@@ -0,0 +1,14 @@
+import upath from 'upath';
+
+export default function getAbsolutePath(projectPath, path) {
+    if (!path) {
+        return null;
+    }
+    if (upath.isAbsolute(path)) {
+        return upath.resolve(path);
+    }
+    if (projectPath) {
+        return upath.resolve(upath.join(upath.resolve(projectPath), path));
+    }
+    return upath.resolve(path);
+}

package/src/utils/getCMakeListsFilePath.js

@@ -0,0 +1,17 @@
+import getParentPath from './getParentPath.js';
+import findFiles from './findFiles.js';
+
+export default function getCMakeListsFilePath(basePath = process.cwd()) {
+    let temp = findFiles('CMakeLists.txt', { cwd: basePath });
+    if (temp.length === 0) {
+        temp = findFiles('*/CMakeLists.txt', { cwd: basePath, ignore: ['node_modules/*', 'dist/*', 'build/*'] });
+    }
+
+    if (temp.length > 0) return temp[0];
+    return getCliCMakeListsFile();
+}
+
+export function getCliCMakeListsFile() {
+    const cliPath = getParentPath(getParentPath(import.meta.url));
+    return `${cliPath}/assets/cmake/CMakeLists.txt`;
+}

package/src/utils/getOsUserAndGroupId.js

@@ -0,0 +1,11 @@
+import os from 'node:os';
+
+let osUserAndGroupId;
+export default function getOsUserAndGroupId() {
+    const userInfo = os.userInfo();
+    if (!osUserAndGroupId) {
+        const isInvalid = userInfo.uid === -1 && userInfo.gid === -1;
+        osUserAndGroupId = isInvalid ? '0:0' : `${userInfo.uid}:${userInfo.gid}`;
+    }
+    return osUserAndGroupId;
+}

package/src/utils/getParentPath.js

@@ -0,0 +1,12 @@
+import * as url from 'node:url';
+import upath from 'upath';
+
+export default function getParentPath(importUrl) {
+    let input = importUrl;
+    try {
+        input = url.fileURLToPath(input);
+    } catch (e) { /* empty */ }
+    const filename = upath.normalize(input);
+    const temp = filename.split('/'); temp.pop();
+    return temp.join('/');
+}

package/src/utils/hash.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+
+export function getFileHash(path) {
+    const data = fs.readFileSync(path);
+    return getContentHash(data);
+    /* return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        const rs = fs.createReadStream(path);
+        rs.on('error', reject);
+        rs.on('data', (chunk) => hash.update(chunk));
+        rs.on('end', () => resolve(hash.digest('hex')));
+    }); */
+}
+
+export function getContentHash(content) {
+    const hash = createHash('sha256');
+    hash.update(content);
+    return hash.digest('hex');
+}
+
+// Order-insensitive fingerprint of a file LIST (path + content per entry).
+// Used as the Bridge lib cache key: the same lib dir is reused while the
+// bridge set grows, so a lib built from a different set must not satisfy the
+// cache. Missing files fingerprint as such instead of throwing.
+export function getFilesFingerprint(paths) {
+    return getContentHash(
+        (paths || [])
+            .map((path) => `${path}:${fs.existsSync(path) ? getFileHash(path) : 'missing'}`)
+            .sort()
+            .join('\n'),
+    );
+}

package/src/utils/inputStamp.js

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import upath from 'upath';
+import findFiles from './findFiles.js';
+import { getContentHash, getFileHash } from './hash.js';
+
+const EXCLUDED_DIRS = ['node_modules', '.crossbind', 'android', 'ios', 'build', 'dist', '.git'];
+
+export function collectInputFiles(roots, exts, extraFiles = []) {
+    // A single-entry brace set ({js}) is not brace-expanded by glob; use a plain suffix then.
+    const pattern = exts.length === 1 ? `**/*.${exts[0]}` : `**/*.{${exts.join(',')}}`;
+    const files = new Set();
+    [...new Set(roots)].forEach((root) => {
+        findFiles(pattern, {
+            cwd: root,
+            ignore: EXCLUDED_DIRS.map((dir) => `**/${dir}/**`),
+        }).forEach((file) => files.add(file));
+        const packageJson = upath.join(root, 'package.json');
+        if (fs.existsSync(packageJson)) files.add(packageJson);
+    });
+    extraFiles.forEach((file) => files.add(upath.normalize(file)));
+    return [...files].filter((file) => fs.existsSync(file)).sort();
+}
+
+export function computeInputStamp(roots, exts, extraFiles, salt) {
+    const lines = collectInputFiles(roots, exts, extraFiles).map((file) => `${file}:${getFileHash(file)}`);
+    lines.push(salt);
+    return getContentHash(lines.join('\n'));
+}

package/src/utils/licenseReport.js

@@ -0,0 +1,94 @@
+import spdxParse from 'spdx-expression-parse';
+
+const COPYLEFT_PATTERN = /\b(AGPL|LGPL|GPL|MPL|EPL|EUPL|CDDL)\b/i;
+
+export function isCopyleft(expression) {
+    return COPYLEFT_PATTERN.test(expression || '');
+}
+
+export function validateSpdx(expression) {
+    if (!expression || typeof expression !== 'string') {
+        return { isValid: false, error: 'missing license field' };
+    }
+    try {
+        spdxParse(expression);
+        return { isValid: true };
+    } catch (e) {
+        return { isValid: false, error: e.message };
+    }
+}
+
+export function formatNoticeSections(rows) {
+    return [...rows]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((row) => {
+            const lines = [`## ${row.name}${row.license ? ` — ${row.license}` : ''}`, ''];
+            if (row.npmName) lines.push(`- package: ${row.npmName}${row.version ? `@${row.version}` : ''}`);
+            if (row.nativeVersion) lines.push(`- native version: ${row.nativeVersion}`);
+            if (row.sourceUrl) lines.push(`- source: ${row.sourceUrl}${row.sha256 ? ` (sha256: ${row.sha256})` : ''}`);
+            if (row.licenseSelected) lines.push(`- license election: ${row.licenseSelected} (declared: ${row.licenseDeclared})`);
+            else if (/\bOR\b/.test(row.license || '')) lines.push(`- no license election recorded; the declared expression applies${row.licenseText ? ' and all texts are included' : ' (texts linked above)'}`);
+            if (row.licenseNotes) lines.push(`- note: ${row.licenseNotes}`);
+            if (row.licenseText) lines.push('', '```', row.licenseText.trim(), '```');
+            return lines.join('\n');
+        });
+}
+
+export function formatNoticesMarkdown(rows) {
+    const sections = formatNoticeSections(rows);
+
+    return [
+        '# Third-Party Notices',
+        '',
+        'GENERATED by `crossbind licenses` from recipe metadata (contract D/E) - do not edit.',
+        '',
+        'This artifact bundles the following native libraries through crossbind packages.',
+        '',
+        sections.join('\n\n'),
+        '',
+    ].join('\n');
+}
+
+// K4 companion: a -bin artifact statically links every row, so its npm license
+// field is the AND of all effective component licenses - derived, never typed.
+export function deriveLicenseExpression(rows) {
+    const missing = rows.filter((row) => !row.license);
+    if (missing.length > 0) {
+        throw new Error(`crossbind: cannot derive a license expression - rows without a license: ${missing.map((row) => row.name).join(', ')}`);
+    }
+    const parts = [...new Set(rows.map((row) => (/\s/.test(row.license) ? `(${row.license})` : row.license)))]
+        .sort((a, b) => a.localeCompare(b));
+    const expression = parts.join(' AND ');
+    const { isValid, error } = validateSpdx(expression);
+    if (!isValid) {
+        throw new Error(`crossbind: derived license expression is not valid SPDX (${error}): ${expression}`);
+    }
+    return expression;
+}
+
+export function formatCycloneDxSbom(rows, target = {}) {
+    return `${JSON.stringify({
+        bomFormat: 'CycloneDX',
+        specVersion: '1.5',
+        version: 1,
+        metadata: {
+            component: {
+                type: 'library',
+                name: target.name || 'unknown',
+                ...(target.version ? { version: target.version } : {}),
+            },
+        },
+        components: [...rows]
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((row) => ({
+                type: 'library',
+                name: row.name,
+                ...(row.nativeVersion ? { version: row.nativeVersion } : {}),
+                ...(row.nativeVersion ? { purl: `pkg:generic/${row.name}@${row.nativeVersion}` } : {}),
+                ...(row.license ? { licenses: [{ expression: row.license }] } : {}),
+                ...(row.sha256 ? { hashes: [{ alg: 'SHA-256', content: row.sha256 }] } : {}),
+                ...(row.sourceUrl ? { externalReferences: [{ type: 'distribution', url: row.sourceUrl }] } : {}),
+                ...(row.licenseSelected ? { properties: [{ name: 'crossbind:license-declared', value: row.licenseDeclared }] } : {}),
+            })),
+    }, null, 2)}\n`;
+}

package/src/utils/linkLayout.js

@@ -0,0 +1,34 @@
+// Assembles the lib section of the emcc link line. --whole-archive is applied
+// only where symbol retention genuinely needs it: always the Bridge archive
+// (its embind registrations live in static initializers that no symbol
+// references), plus any archive opted in via config - `wholeArchive: true` on
+// the project (legacy everything-wholesale layout) or on a dependency's own
+// config, or names listed in the project's `wholeArchiveDependencies`.
+// Everything else links normally so wasm-ld keeps just the referenced call
+// graph instead of every archive member.
+
+export function libNameOf(libPath) {
+    const base = libPath.split('/').pop();
+    const match = /^lib(.+)\.a$/.exec(base);
+    return match ? match[1] : base;
+}
+
+export function buildLinkLibArgs(libs, { wholeArchiveAll = false, wholeArchiveNames = new Set(), wrapLast = true } = {}) {
+    const args = [];
+    let wrapped = false;
+    libs.forEach((lib, index) => {
+        // wrapLast covers the Bridge archive convention; wasi command links
+        // have no bridge (main() is the GC root), so they pass false.
+        const isBridge = wrapLast && index === libs.length - 1;
+        const wantWrap = wholeArchiveAll || isBridge || wholeArchiveNames.has(libNameOf(lib));
+        if (wantWrap !== wrapped) {
+            args.push(wantWrap ? '-Wl,--whole-archive' : '-Wl,--no-whole-archive');
+            wrapped = wantWrap;
+        }
+        args.push(lib);
+    });
+    if (wrapped) {
+        args.push('-Wl,--no-whole-archive');
+    }
+    return args;
+}