crossbind 2.0.0-beta.73 → 2.0.0-beta.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crossbind",
-  "version": "2.0.0-beta.73",
+  "version": "2.0.0-beta.74",
   "license": "MIT",
   "homepage": "https://crossbind.dev",
   "repository": {
@@ -27,6 +27,10 @@
       "types": "./src/app/index.d.ts",
       "default": "./src/app/index.js"
     },
+    "./licenses": {
+      "types": "./src/licenses/index.d.ts",
+      "default": "./src/licenses/index.js"
+    },
     "./*": "./*"
   },
   "devDependencies": {
@@ -34,7 +38,7 @@
     "vitest": "^5.0.1"
   },
   "dependencies": {
-    "@crossbind/extension-conan": "2.0.0-beta.72",
+    "@crossbind/extension-conan": "2.0.0-beta.74",
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
@@ -51,7 +55,7 @@
     "upath": "^3.0.8"
   },
   "optionalDependencies": {
-    "@crossbind/bridge-tools": "2.0.0-beta.73"
+    "@crossbind/bridge-tools": "2.0.0-beta.74"
   },
   "keywords": [
     "webassembly",

package/src/actions/createLib.js

@@ -48,7 +48,10 @@ export default function createLib(target, fileType, options = {}) {
     // The lib dir is reused while the bridge list grows, so an early smaller nativeGlob build must not satisfy later sets: fingerprint the glob and miss on mismatch.
     const fingerprintFile = `${libdir}/crossbind-nativeglob.fingerprint`;
     // options.inputs lists what the sources compile against (a binding runtime's headers), so a change there rebuilds too.
-    const fingerprint = nativeGlob ? getFilesFingerprint([...nativeGlob, ...(options.inputs ?? [])]) : null;
+    // A header edit can leave a bridge's text as it was, so the key beside each bridge, the hash of what it was made from, counts too.
+    const fingerprint = nativeGlob
+        ? getFilesFingerprint([...nativeGlob, ...nativeGlob.map((file) => `${file}.key`), ...(options.inputs ?? [])])
+        : null;
     const fingerprintChanged = fingerprint !== null
         && (!fs.existsSync(fingerprintFile) || fs.readFileSync(fingerprintFile, { encoding: 'utf8' }) !== fingerprint);
 

package/src/actions/licenses.js

@@ -113,6 +113,32 @@ function wasiToolchainRows() {
     ];
 }
 
+// A wasm module statically links Emscripten's runtime and system libraries (its musl-based libc among them) and LLVM's
+// C++ runtime from the same toolchain image.
+function wasmToolchainRows() {
+    const shared = {
+        npmName: null, version: null, nativeVersion: null, sha256: null, licenseSelected: null, licenseText: null, isCopyleft: false,
+    };
+    return [
+        {
+            ...shared,
+            name: 'emscripten',
+            license: 'MIT OR NCSA',
+            licenseDeclared: 'MIT OR NCSA',
+            sourceUrl: 'https://github.com/emscripten-core/emscripten',
+            licenseNotes: "Emscripten's runtime and system libraries, its musl-based libc among them, statically linked into the module; license text: https://github.com/emscripten-core/emscripten/blob/main/LICENSE",
+        },
+        {
+            ...shared,
+            name: 'llvm-runtimes',
+            license: 'Apache-2.0 WITH LLVM-exception',
+            licenseDeclared: 'Apache-2.0 WITH LLVM-exception',
+            sourceUrl: 'https://github.com/llvm/llvm-project',
+            licenseNotes: "libc++, libc++abi and compiler-rt of Emscripten's LLVM, statically linked into the module; license text: https://github.com/llvm/llvm-project/blob/main/LICENSE.TXT",
+        },
+    ];
+}
+
 // The notices a build copied out of its toolchain image (a Windows addon's or app's does).
 function toolchainNoticeTexts(platform) {
     const build = state.config?.paths?.build;
@@ -160,25 +186,31 @@ function addonToolchainRows(platform) {
 const versionOf = (dir) => JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version;
 const textOf = (file) => fs.readFileSync(file, 'utf8').trim();
 
+const RUNTIME_ROW = {
+    nativeVersion: null, sha256: null, licenseSelected: null, isCopyleft: false, isRuntime: true,
+};
+
+// crossbind's own code: what an addon and an app host compile in, or the JavaScript a wasm module's glue bundles.
+function crossbindRow(notes) {
+    return {
+        ...RUNTIME_ROW,
+        name: 'crossbind',
+        npmName: 'crossbind',
+        version: versionOf(CROSSBIND_ROOT),
+        license: 'MIT',
+        licenseDeclared: 'MIT',
+        sourceUrl: 'https://github.com/crossbind/crossbind',
+        licenseNotes: notes,
+        licenseText: textOf(path.join(CROSSBIND_ROOT, 'LICENSE')),
+    };
+}
+
 // crossbind's runtime, which an addon and an app host compile in: embind-jsi, which adapts Emscripten's embind.
 function runtimeRows(jsiRoot, notes) {
-    const shared = {
-        nativeVersion: null, sha256: null, licenseSelected: null, isCopyleft: false,
-    };
     return [
+        crossbindRow(notes),
         {
-            ...shared,
-            name: 'crossbind',
-            npmName: 'crossbind',
-            version: versionOf(CROSSBIND_ROOT),
-            license: 'MIT',
-            licenseDeclared: 'MIT',
-            sourceUrl: 'https://github.com/crossbind/crossbind',
-            licenseNotes: notes,
-            licenseText: textOf(path.join(CROSSBIND_ROOT, 'LICENSE')),
-        },
-        {
-            ...shared,
+            ...RUNTIME_ROW,
             name: 'emscripten-embind',
             npmName: '@crossbind/core-embind-jsi',
             version: versionOf(jsiRoot),
@@ -420,10 +452,13 @@ async function buildRow(node) {
             sourceUrl = null;
         }
     }
-    if (!sourceUrl) sourceUrl = manifest?.homepage || null;
-
     const family = familyManifestOf(node);
-    const upstream = family?.manifest?.crossbind?.upstream?.license || null;
+    // A project's own code is at its repository; its homepage is where its docs are.
+    if (!sourceUrl) sourceUrl = repositoryUrl(family?.manifest) || repositoryUrl(manifest) || manifest?.homepage || null;
+
+    // The upstream identity scanners match a component on: the project's own name, and its CPE where NVD has one.
+    const identity = family?.manifest?.crossbind?.upstream ?? null;
+    const upstream = identity?.license || null;
     let license;
     let licenseText;
     if (upstream) {
@@ -437,6 +472,12 @@ async function buildRow(node) {
         if (isComplete) licenseText = fromSource;
         else if (shipped) licenseText = `=== ${path.basename(shipped)} ===\n\n${fs.readFileSync(shipped, 'utf8').trim()}`;
         else licenseText = readLicenseTexts(upstream.files, () => null);
+    } else if (family && family.dir !== node.paths.project) {
+        // The package the alias names holds the code: a published binary's own license field is the expression of
+        // everything it links, which this row would otherwise repeat as its own.
+        license = family.manifest.license || manifest?.license || null;
+        const own = packageLicenseFile(family.dir) ?? packageLicenseFile(node.paths.project);
+        licenseText = own ? fs.readFileSync(own, 'utf8') : null;
     } else {
         license = manifest?.license || null;
         const legacy = packageLicenseFile(node.paths.project);
@@ -444,10 +485,11 @@ async function buildRow(node) {
     }
 
     return {
-        name: node.general.name,
+        name: identity?.name ?? node.general.name,
         npmName: manifest?.name || null,
         version: manifest?.version || null,
         nativeVersion,
+        cpe: identity?.cpe ? `cpe:2.3:a:${identity.cpe}:${nativeVersion ?? '*'}:*:*:*:*:*:*:*` : null,
         license,
         licenseDeclared: upstream?.declared || null,
         licenseSelected: upstream?.selected || null,
@@ -456,9 +498,21 @@ async function buildRow(node) {
         sourceUrl,
         licenseText,
         isCopyleft: isCopyleft(license),
+        isPort: Boolean(upstream),
+        shipsData: shipsData(node),
     };
 }
 
+export function repositoryUrl(manifest) {
+    const repository = typeof manifest?.repository === 'string' ? manifest.repository : manifest?.repository?.url;
+    return repository ? repository.replace(/^git\+/, '').replace(/\.git$/, '') : null;
+}
+
+// The data a dependency declares (GDAL's and PROJ's) travels with the package that ships the module or its loader.
+function shipsData(node) {
+    return (node.targetSpecs ?? []).some((entry) => entry?.specs?.data && Object.keys(entry.specs.data).length > 0);
+}
+
 // The facts of a package source's package come from its recipe, and its texts from the licenses/ its package ships.
 function sourcePackageRow(node) {
     const { name: source, package: pkg } = node.general.packageSource;
@@ -497,9 +551,22 @@ function assertSourcesStaged() {
     });
 }
 
+// The libraries whose recipes vendor copies for some platform, which only a listing for that platform includes.
+export async function vendoringLibraries() {
+    const names = [];
+    for (const node of [state.config, ...state.config.allDependencies]) {
+        if (!node?.paths?.project || node.general?.packageSource) continue;
+        const recipe = await loadJs(node.paths.project, 'crossbind.build');
+        const isVendoring = Object.values(recipe?.bundled ?? {}).some((entries) => entries?.length > 0);
+        if (isVendoring && !names.includes(node.general.name)) names.push(node.general.name);
+    }
+    return names;
+}
+
 // platform (optional, e.g. 'wasi') additionally includes what that platform's
 // artifact statically links beyond the package graph: recipe-declared vendored
-// copies and the toolchain runtime. runtimeEnv 'node' adds the crossbind runtime an
+// copies and the toolchain runtime, and for wasm crossbind's runtime, which the
+// module's glue bundles. runtimeEnv 'node' adds the crossbind runtime an
 // addon of that platform compiles in, or without a platform the one its loader bundles;
 // runtimeEnv 'app' adds what an app's host carries.
 export default async function collectLicenseRows(platform = null, { runtimeEnv = null } = {}) {
@@ -513,12 +580,16 @@ export default async function collectLicenseRows(platform = null, { runtimeEnv =
     const nodes = [state.config, ...state.config.allDependencies]
         .filter((node, index) => node?.paths?.project
             && (node.general?.alias?.package || node.general?.packageSource || (index > 0 && node.package?.name && !node.package.private)));
+    // A project can depend on a library's packages for several platforms; the report names the one its platform links.
+    const target = platform ? state.targets?.find((t) => t.platform === platform) : null;
+    const serves = (node) => !target || node.functions?.isEnabled?.(target) !== false;
     const rows = [];
     const seen = new Set();
-    for (const node of nodes) {
-        const key = keyOf(node);
+    for (const listed of nodes) {
+        const key = keyOf(listed);
         if (seen.has(key)) continue;
         seen.add(key);
+        const node = nodes.find((other) => keyOf(other) === key && serves(other)) ?? listed;
         rows.push(node.general.packageSource ? sourcePackageRow(node) : await buildRow(node));
         // A package source's package folder is written from what its recipe produced: nothing there is run.
         if (platform && !node.general.packageSource) {
@@ -527,6 +598,7 @@ export default async function collectLicenseRows(platform = null, { runtimeEnv =
         }
     }
     if (platform === 'wasi') rows.push(...wasiToolchainRows());
+    if (platform === 'wasm') rows.push(...wasmToolchainRows(), crossbindRow("crossbind's JavaScript runtime, which the module's glue bundles"));
     if (['linux', 'linuxmusl', 'win32'].includes(platform)) rows.push(...addonToolchainRows(platform));
     if (runtimeEnv === 'node') rows.push(...nodeRuntimeRows({ isAddon: platform !== null }));
     if (runtimeEnv === 'app') {

package/src/actions/pageLicenses.js

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import state from '../state/index.js';
+import collectLicenseRows, { repositoryUrl } from './licenses.js';
+
+const FILE = 'crossbind-licenses.json';
+// crossbind/licenses, from whichever copy of crossbind the page has.
+const HELPER = /[\\/]crossbind[\\/]src[\\/]licenses[\\/]index\.js$/;
+const TEXT_FILE = /^(licen[cs]e|copying|notice|ofl)([._-].*)?$/i;
+
+// What a bundle holds: its chunks' modules, and the files its assets came from, as the font a stylesheet's url() takes.
+function bundledFiles(bundle, root) {
+    return Object.values(bundle)
+        .flatMap((output) => (output.type === 'chunk'
+            ? output.moduleIds
+            : (output.originalFileNames ?? []).map((name) => path.resolve(root, name))))
+        .map((id) => id.split('?')[0]);
+}
+
+function manifestIn(dir, manifests) {
+    const file = path.join(dir, 'package.json');
+    if (!manifests.has(file)) {
+        try {
+            manifests.set(file, fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : null);
+        } catch (error) {
+            throw new Error(`crossbind: ${file} holds no JSON: ${error.message}`, { cause: error });
+        }
+    }
+    return manifests.get(file);
+}
+
+// The package a file is in: the nearest folder up from it whose package.json names one, as a package's subfolder can
+// hold one that names none.
+function packageOf(file, manifests) {
+    if (!path.isAbsolute(file)) return null;
+    for (let dir = path.dirname(path.resolve(file)); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+        const manifest = manifestIn(dir, manifests);
+        if (manifest?.name) return { dir, manifest };
+    }
+    return null;
+}
+
+function npmEntry({ dir, manifest }) {
+    const texts = fs.readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && TEXT_FILE.test(entry.name))
+        .map((entry) => entry.name)
+        .sort()
+        .map((file) => `=== ${file} ===\n\n${fs.readFileSync(path.join(dir, file), 'utf8').trim()}`);
+    return {
+        name: manifest.name,
+        version: manifest.version ?? null,
+        license: typeof manifest.license === 'string' ? manifest.license : manifest.license?.type ?? null,
+        source: repositoryUrl(manifest) ?? manifest.homepage ?? null,
+        text: texts.length > 0 ? texts.join('\n\n') : null,
+    };
+}
+
+// The npm packages the page carries, but for the project's own code: its package and private ones.
+function npmEntriesOf(files) {
+    const manifests = new Map();
+    const project = path.resolve(state.config.paths.project);
+    const packages = new Map(files
+        .map((file) => packageOf(file, manifests))
+        .filter((found) => found && found.dir !== project && !found.manifest.private)
+        .map((found) => [found.dir, found]));
+    return [...packages.values()].map(npmEntry);
+}
+
+const nativeEntry = (row) => ({
+    name: row.name,
+    version: row.nativeVersion ?? row.version ?? null,
+    license: row.license ?? null,
+    source: row.sourceUrl ?? null,
+    text: row.licenseText ?? null,
+});
+
+// The list a page reads with crossbind/licenses, which its build writes beside it if it does: what the module links and
+// an app carries, as `crossbind licenses` lists them, and the npm packages the page's bundle holds, each once. bundle is
+// what Rollup or Vite hands generateBundle, root what its assets' original file names are relative to.
+export default async function pageLicensesAsset(bundle, { root, platform, runtimeEnv = null }) {
+    const files = bundledFiles(bundle, root);
+    if (!files.some((file) => HELPER.test(file))) return null;
+    const native = (await collectLicenseRows(platform, { runtimeEnv })).map(nativeEntry);
+    const listed = new Set();
+    const entries = [...native, ...npmEntriesOf(files)]
+        .filter(({ name, version }) => !listed.has(`${name}@${version}`) && listed.add(`${name}@${version}`))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return { fileName: FILE, source: JSON.stringify(entries) };
+}

package/src/bin.js

@@ -48,9 +48,9 @@ import { cargoHome } from './utils/runCargo.js';
 import { containerRootOf, sourceRoot } from './utils/runPackageSource.js';
 import { importSchemesOf, sourceNamesOf } from './utils/packageSources.js';
 import { cleanDepsCache } from './utils/dependencyRebuild.js';
-import collectLicenseRows from './actions/licenses.js';
+import collectLicenseRows, { vendoringLibraries } from './actions/licenses.js';
 import { formatNoticesMarkdown, formatCycloneDxSbom, validateSpdx } from './utils/licenseReport.js';
-import { SBOM_FILE, nodePackageMeta, writeNodePackageLicense } from './utils/packageLicense.js';
+import { SBOM_FILE, nodePackageMeta, shippedRows, writeNodePackageLicense } from './utils/packageLicense.js';
 import findFiles from './utils/findFiles.js';
 
 const platforms = [...new Set(state.targets.map(target => target.platform).filter(t => t))];
@@ -240,11 +240,17 @@ program.command('licenses')
         });
         const copyleftRows = rows.filter((row) => row.isCopyleft);
         if (copyleftRows.length > 0) {
-            console.log(`\n! ${copyleftRows.length} copyleft-licensed ${copyleftRows.length === 1 ? 'dependency' : 'dependencies'} (${copyleftRows.map((row) => row.name).join(', ')}) — see docs/playbooks/licensing-lgpl.md`);
+            console.log(`\n! ${copyleftRows.length} copyleft-licensed ${copyleftRows.length === 1 ? 'dependency' : 'dependencies'} (${copyleftRows.map((row) => row.name).join(', ')}) — see https://github.com/crossbind/crossbind/blob/main/docs/playbooks/licensing-lgpl.md`);
+        }
+        if ((options.notices || options.sbom) && !options.platform) {
+            const vendoring = await vendoringLibraries();
+            if (vendoring.length > 0) {
+                console.warn(`crossbind: ${vendoring.join(', ')} vendor${vendoring.length === 1 ? 's' : ''} copies of other libraries per platform; pass --platform <platform> so the notices and SBOM list them.`);
+            }
         }
         if (options.notices) {
             const file = typeof options.notices === 'string' ? options.notices : `${state.config.paths.project}/THIRD-PARTY-NOTICES.md`;
-            fs.writeFileSync(file, formatNoticesMarkdown(rows));
+            fs.writeFileSync(file, formatNoticesMarkdown(rows, nodePackageMeta(state.config)));
             logger.info(`crossbind: wrote ${file}`);
         }
         if (options.sbom) {
@@ -265,7 +271,8 @@ program.command('licenses')
             logger.info(`crossbind: wrote ${file}`);
         }
         if (options.package) {
-            const expression = writeNodePackageLicense(state.config.paths.project, { ...nodePackageMeta(state.config), rows });
+            const meta = nodePackageMeta(state.config);
+            const expression = writeNodePackageLicense(state.config.paths.project, { ...meta, rows: shippedRows(rows, meta) });
             logger.info(`crossbind: wrote LICENSE and ${SBOM_FILE} (${expression})`);
         }
         if (options.check) {

package/src/index.js

@@ -9,6 +9,7 @@ export {
 export { checkInstaller, shipApp } from './actions/appInstaller.js';
 export { findAppPageApi, resolveAppPageApi } from './utils/resolveAppHost.js';
 export { default as isAppBuild } from './utils/appBuild.js';
+export { default as pageLicensesAsset } from './actions/pageLicenses.js';
 export { default as openInSimulator, buildForSimulator } from './actions/iosSimulator.js';
 export {
     default as openOnIosDevice, buildForIosDevice, connectedIosDevice, iosDeviceAddress, iosDevServer,

package/src/licenses/index.d.ts

@@ -0,0 +1,16 @@
+/** A component a page or the app it runs in carries: a library the native module links, a part of an app's host or crossbind's runtime, or an npm package in the page's bundle. */
+export interface License {
+    /** The name its project gives it. */
+    name: string;
+    /** The version of the code the page or app carries. */
+    version: string | null;
+    /** An SPDX expression. */
+    license: string | null;
+    /** Where its code is. */
+    source: string | null;
+    /** Its license texts as it carries them, each under its file's name. */
+    text: string | null;
+}
+
+/** The components the page and its app carry, by name, from the crossbind-licenses.json a build with crossbind's Vite or Rollup plugin writes beside the page. Rejects on a dev server, which has none. */
+export function licenses(): Promise<License[]>;

package/src/licenses/index.js

@@ -0,0 +1,15 @@
+// The licenses of what a page and the app it runs in carry, from the crossbind-licenses.json a build of the page with
+// crossbind's Vite or Rollup plugin writes beside it.
+const FILE = 'crossbind-licenses.json';
+
+export async function licenses() {
+    // Vite gives the base it serves the page from; elsewhere the file is beside the page.
+    const url = new URL(`${import.meta.env?.BASE_URL ?? './'}${FILE}`, document.baseURI);
+    const response = await fetch(url);
+    // A dev server answers a file it lacks with the page.
+    const list = response.ok ? await response.json().catch(() => null) : null;
+    if (!Array.isArray(list)) {
+        throw new Error(`crossbind: ${url} holds no license list. A build of the page with crossbind's Vite or Rollup plugin writes it; the dev server has none.`);
+    }
+    return list;
+}

package/src/state/loadConfig.js

@@ -146,6 +146,8 @@ export function getFilledConfig(config, options = { isDepend: false }) {
         app: config.app || {},
         // What an app's host builds in beside its own extensions.
         extensions: config.extensions || [],
+        // The license files crossbind licenses writes: sourceTag is the git tag a published package's source is at.
+        licenses: config.licenses || {},
         package: null,
         functions: config.functions || {},
     };
@@ -153,6 +155,9 @@ export function getFilledConfig(config, options = { isDepend: false }) {
     if (!['sync', 'promise'].includes(newConfig.dts)) {
         throw new Error(`crossbind: "dts" must be 'sync' or 'promise' (got '${newConfig.dts}').`);
     }
+    if (newConfig.licenses.sourceTag !== undefined && typeof newConfig.licenses.sourceTag !== 'string') {
+        throw new Error(`crossbind: "licenses.sourceTag" must be a string such as 'v{version}' (got '${newConfig.licenses.sourceTag}').`);
+    }
     if (typeof newConfig.types !== 'boolean') {
         throw new Error(`crossbind: "types" must be true or false (got '${newConfig.types}').`);
     }

package/src/utils/cppDts.js

@@ -200,18 +200,15 @@ export function parseCppSurface(source, log = console.log) {
 
 export function emitCppDts(model, exportNames, mode = 'sync') {
     const wrap = (t) => (mode === 'promise' ? `Promise<${t}>` : t);
-    const out = ['// Generated by crossbind - do not edit. Values are usable after init().', ''];
-    const usesVector = model.classes.some((cls) => (cls.ctor?.args ?? []).concat(cls.methods.flatMap((m) => [...m.args, { type: m.ret }]))
-        .some((a) => a.type?.includes('CppVector<')));
-    if (usesVector) {
-        out.push('/** An embind std::vector proxy. Convert with Module.toArray / Module.toVector. */');
-        out.push('export interface CppVector<T> {');
-        out.push(`    size(): ${wrap('number')};`);
-        out.push(`    get(index: number): ${wrap('T')};`);
-        out.push(`    push_back(value: T): ${wrap('void')};`);
-        out.push(`    delete(): ${wrap('void')};`);
-        out.push('}');
-    }
+    const out = ['// Generated by crossbind - do not edit. Values are usable after initNative() resolves.', ''];
+    // The module's toVector and toArray take vectors on every runtime, so the proxy's type is always declared.
+    out.push('/** An embind std::vector proxy. Convert with Module.toArray / Module.toVector. */');
+    out.push('export interface CppVector<T> {');
+    out.push(`    size(): ${wrap('number')};`);
+    out.push(`    get(index: number): ${wrap('T')};`);
+    out.push(`    push_back(value: T): ${wrap('void')};`);
+    out.push(`    delete(): ${wrap('void')};`);
+    out.push('}');
     const emitted = new Set();
     for (const cls of model.classes) {
         if (!exportNames.includes(cls.name)) continue;
@@ -233,7 +230,16 @@ export function emitCppDts(model, exportNames, mode = 'sync') {
         if (!emitted.has(name)) out.push(`export declare const ${name}: any;`);
     }
     out.push('export declare let AllSymbols: Record<string, unknown>;');
-    out.push('export declare function initNative(config?: Record<string, unknown>): Promise<unknown>;');
+    // A runtime's own members (FS in a wasm build, the file helpers in a browser) differ by runtime; the index signature
+    // keeps them reachable while the members every runtime has stay typed.
+    out.push('/** What initNative resolves to: the bound classes, toVector and toArray, and the members of the runtime it runs on. */');
+    out.push('export interface NativeModule {');
+    out.push('    [name: string]: unknown;');
+    for (const name of emitted) out.push(`    ${name}: typeof ${name};`);
+    out.push(`    toVector<T>(classOrName: unknown, array?: T[]): ${wrap('CppVector<T>')};`);
+    out.push(`    toArray<T>(vector: CppVector<T> | T[]): ${wrap('T[]')};`);
+    out.push('}');
+    out.push('export declare function initNative(config?: Record<string, unknown>): Promise<NativeModule>;');
     out.push('');
     return out.join('\n');
 }

package/src/utils/licenseReport.js

@@ -1,4 +1,5 @@
 import spdxParse from 'spdx-expression-parse';
+import { lgplRows, relinkSection } from './relinking.js';
 
 const COPYLEFT_PATTERN = /\b(AGPL|LGPL|GPL|MPL|EPL|EUPL|CDDL)\b/i;
 
@@ -43,16 +44,20 @@ export function formatNoticeSections(rows) {
         });
 }
 
-export function formatNoticesMarkdown(rows) {
+// meta, the package that publishes the artifact (packageMeta), adds the relinking steps an LGPL library asks for.
+export function formatNoticesMarkdown(rows, meta = null) {
     const sections = formatNoticeSections(rows);
+    const relinked = meta?.repository ? lgplRows(rows) : [];
 
     return [
         '# Third-Party Notices',
         '',
-        'GENERATED by `crossbind licenses` from recipe metadata (contract D/E) - do not edit.',
+        'GENERATED by `crossbind licenses` - do not edit. This file states facts and is not legal advice; the',
+        'compliance assessment is yours.',
         '',
         'This artifact bundles the following native libraries through crossbind packages.',
         '',
+        ...(relinked.length ? [relinkSection({ ...meta, artifact: 'module', rows: relinked }), ''] : []),
         sections.join('\n\n'),
         '',
     ].join('\n');
@@ -89,11 +94,13 @@ export function formatCycloneDxSbom(rows, target = {}) {
         },
         components: [...rows]
             .sort((a, b) => a.name.localeCompare(b.name))
-            .map((row) => ({
+            .map((row) => ({ row, version: row.nativeVersion ?? row.version }))
+            .map(({ row, version }) => ({
                 type: 'library',
                 name: row.name,
-                ...(row.nativeVersion ? { version: row.nativeVersion } : {}),
-                ...(row.nativeVersion ? { purl: row.purl ?? `pkg:generic/${row.name}@${row.nativeVersion}` } : {}),
+                ...(version ? { version } : {}),
+                ...(version ? { purl: row.purl ?? `pkg:generic/${row.name}@${version}` } : {}),
+                ...(row.cpe ? { cpe: row.cpe } : {}),
                 ...(row.license ? { licenses: [{ expression: row.license }] } : {}),
                 ...(row.sha256 ? { hashes: [{ alg: 'SHA-256', content: row.sha256 }] } : {}),
                 ...(row.sourceUrl ? { externalReferences: [{ type: 'distribution', url: row.sourceUrl }] } : {}),

package/src/utils/packageLicense.js

@@ -1,14 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { deriveLicenseExpression, formatCycloneDxSbom, formatNoticeSections } from './licenseReport.js';
+import { lgplRows, relinkSection } from './relinking.js';
+
+export { lgplRows };
 
 export const SBOM_FILE = 'sbom.cdx.json';
 const RULE = '-'.repeat(70);
 
-export function lgplRows(rows) {
-    return rows.filter((row) => /\bLGPL\b/.test(row.license ?? ''));
-}
-
 // The LLVM exception waives the notice for runtime parts compiled into a binary; every other
 // component needs its text in the package.
 function assertTexts(name, rows) {
@@ -22,36 +21,20 @@ function assertTexts(name, rows) {
     }
 }
 
-const listOf = (names) => (names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names.at(-1)}` : names[0]);
-
-function relinkSection({ name, version, repository, projectPath, addonFile, rows }) {
-    const tag = `${name}@${version}`;
-    const repo = repository.replace(/\.git$/, '');
-    return [
-        '## Relinking the LGPL libraries',
-        '',
-        `This addon links ${listOf(rows.map((row) => row.name))} statically; their sections below give their licenses.`,
-        'You may replace them with modified versions and relink the addon:',
-        '',
-        `1. Get the corresponding source. This package was built from ${repo} at the tag ${tag}:`,
-        `   ${repo}/tree/${tag}`,
-        '   The upstream sources are the tarballs the sections below list, with their SHA-256.',
-        `2. In ${projectPath}, point the library at your modified source with a crossbind.overrides.js file`,
-        '   (docs/playbooks/override-dependencies.md in that repository).',
-        `3. Build the addon with \`pnpm install\` and \`pnpm --dir ${projectPath} build\`. Linux and Windows`,
-        '   addons build in Docker, macOS addons on a Mac.',
-        `4. The build writes ${addonFile} in ${projectPath}; it replaces the file of that name in this package.`,
-    ].join('\n');
+// What a Node-API package's license covers: an addon package what its addon links; a package without an addon crossbind's
+// JavaScript runtime, the bindings of the project's own code and the data of the libraries that declare some.
+export function shippedRows(rows, { addonFile }) {
+    return addonFile ? rows : rows.filter((row) => row.isRuntime || !row.isPort || row.shipsData);
 }
 
-export function nodePackageLicense({ name, version, repository, projectPath, addonFile = null, rows }) {
+export function nodePackageLicense({ name, version, repository, projectPath, addonFile = null, sourceTag = null, rows }) {
     assertTexts(name, rows);
     const expression = deriveLicenseExpression(rows);
     const relinked = addonFile ? lgplRows(rows) : [];
     const lines = [
         addonFile
             ? `${name} ships a Node-API addon that links the components below statically.`
-            : `${name} ships the JavaScript bindings, types and data of the components below; the addons that link them are in its platform packages.`,
+            : `${name} ships the JavaScript bindings, types and data of the components below. Each of its platform packages carries the LICENSE of the addon it holds.`,
         'The full license text of every component follows.',
         '',
         'Effective license expression (also package.json "license"):',
@@ -65,7 +48,9 @@ export function nodePackageLicense({ name, version, repository, projectPath, add
         '',
         RULE,
         '',
-        ...(relinked.length ? [relinkSection({ name, version, repository, projectPath, addonFile, rows: relinked }), '', RULE, ''] : []),
+        ...(relinked.length ? [relinkSection({
+            name, version, repository, projectPath, sourceTag, artifact: 'addon', file: addonFile, rows: relinked,
+        }), '', RULE, ''] : []),
         formatNoticeSections(rows).join('\n\n'),
         '',
     ];
@@ -91,7 +76,7 @@ export function writeNodePackageLicense(dir, meta) {
 
 // What a Node-API package's license names, from its manifest and its place in the repository it builds
 // from: an addon package's is the addon its own build writes.
-export function nodePackageMeta({ package: manifest = {}, paths }) {
+export function nodePackageMeta({ package: manifest = {}, paths, licenses }) {
     const repository = typeof manifest.repository === 'string' ? manifest.repository : (manifest.repository?.url ?? '');
     return {
         name: manifest.name,
@@ -99,5 +84,6 @@ export function nodePackageMeta({ package: manifest = {}, paths }) {
         repository,
         projectPath: path.relative(paths.base, paths.project).split(path.sep).join('/') || '.',
         addonFile: manifest.os && /\.node$/.test(manifest.main ?? '') ? manifest.main : null,
+        sourceTag: licenses?.sourceTag ?? null,
     };
 }

package/src/utils/relinking.js

@@ -0,0 +1,50 @@
+// What a package that links LGPL libraries statically tells its user: where the corresponding source is and how to
+// build the artifact again with a modified library. A Node-API addon's LICENSE and a wasm module's notices both carry it.
+export const OVERRIDE_PLAYBOOK = 'https://github.com/crossbind/crossbind/blob/main/docs/playbooks/override-dependencies.md';
+export const DEFAULT_SOURCE_TAG = '{name}@{version}';
+
+export function lgplRows(rows) {
+    return rows.filter((row) => /\bLGPL\b/.test(row.license ?? ''));
+}
+
+export const sourceTagOf = (format, name, version) => (format || DEFAULT_SOURCE_TAG)
+    .replaceAll('{name}', name)
+    .replaceAll('{version}', version);
+
+const listOf = (names) => (names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names.at(-1)}` : names[0]);
+
+const ARTIFACTS = {
+    addon: (file, projectPath) => ({
+        noun: 'addon',
+        verb: 'relink the addon',
+        where: 'Linux and Windows addons build in Docker, macOS addons on a Mac.',
+        result: `The build writes ${file} in ${projectPath}; it replaces the file of that name in this package.`,
+    }),
+    module: (_file, projectPath) => ({
+        noun: 'module',
+        verb: 'build the module again',
+        where: "The build runs in crossbind's toolchain: Docker, a remote runner or crossbind cloud.",
+        result: `The build writes the module's files in ${projectPath}/dist; they replace the files of those names in this package.`,
+    }),
+};
+
+export function relinkSection({ name, version, repository, projectPath, rows, sourceTag, artifact = 'addon', file = null }) {
+    const tag = sourceTagOf(sourceTag, name, version);
+    const repo = repository.replace(/\.git$/, '');
+    const { noun, verb, where, result } = ARTIFACTS[artifact](file, projectPath);
+    return [
+        '## Relinking the LGPL libraries',
+        '',
+        `This ${noun} links ${listOf(rows.map((row) => row.name))} statically; their sections below give their licenses.`,
+        `You may replace them with modified versions and ${verb}:`,
+        '',
+        `1. Get the corresponding source. This package was built from ${repo} at the tag ${tag}:`,
+        `   ${repo}/tree/${tag}`,
+        '   The upstream sources are the tarballs the sections below list, with their SHA-256.',
+        `2. In ${projectPath}, point the library at your modified source with a crossbind.overrides.js file`,
+        `   (${OVERRIDE_PLAYBOOK}).`,
+        `3. Build the packages the ${noun} links first, as their dist/ folders are not in git, then the ${noun} with`,
+        `   \`pnpm install\` and \`pnpm --dir ${projectPath} build\`. ${where}`,
+        `4. ${result}`,
+    ].join('\n');
+}