crossbind 2.0.0-beta.73 → 2.0.0-beta.75

package/src/utils/bridgeRuntimeFixes.js

@@ -1,3 +1,25 @@
+// A const char* followed by an integer may be a byte span, with embedded NULs or no terminator.
+// Preserve its address; JavaScript can read exactly the reported length with readBuffer. The argument keeps its const for
+// callbackArgument, which takes it by reference: a callback's const std::vector<std::string> & binds to no other.
+const CALLBACK_ARGUMENT_AT = `template<size_t I, typename Tuple> auto callbackArgumentAt(Tuple values) {
+  using Arg = std::remove_reference_t<decltype(std::get<I>(values))>;
+  using A = std::remove_cv_t<Arg>;
+  if constexpr (std::is_same_v<A, const char *> && I + 1 < std::tuple_size_v<Tuple>) {
+    using Next = std::remove_cv_t<std::remove_reference_t<decltype(std::get<I + 1>(values))>>;
+    if constexpr (std::is_integral_v<Next>) return toHandle(std::get<I>(values));
+    else return callbackArgument<Arg>(std::get<I>(values));
+  } else return callbackArgument<Arg>(std::get<I>(values));
+}`;
+// The form a bridge cached before the argument kept its const still holds.
+const CALLBACK_ARGUMENT_AT_WITHOUT_CONST = `template<size_t I, typename Tuple> auto callbackArgumentAt(Tuple values) {
+  using A = std::remove_cv_t<std::remove_reference_t<decltype(std::get<I>(values))>>;
+  if constexpr (std::is_same_v<A, const char *> && I + 1 < std::tuple_size_v<Tuple>) {
+    using Next = std::remove_cv_t<std::remove_reference_t<decltype(std::get<I + 1>(values))>>;
+    if constexpr (std::is_integral_v<Next>) return toHandle(std::get<I>(values));
+    else return callbackArgument<A>(std::get<I>(values));
+  } else return callbackArgument<A>(std::get<I>(values));
+}`;
+
 // Adapt the runtime emitted by the pinned SWIG fork. Kept in the generator so cache rebuilds
 // produce the same runtime in every bridge, including builds on a remote runner.
 export default function fixBridgeRuntime(text) {
@@ -22,16 +44,7 @@ template<typename T> constexpr bool isPassedByAddress =`);
     }
     if (!text.includes('auto callbackArgumentAt(')) {
         text = '#include <tuple>\n' + text;
-        text = text.replace('#ifndef __EMSCRIPTEN__\nstruct RuntimeCallbacks {', `// A const char* followed by an integer may be a byte span, with embedded NULs or no terminator.
-// Preserve its address; JavaScript can read exactly the reported length with readBuffer.
-template<size_t I, typename Tuple> auto callbackArgumentAt(Tuple values) {
-  using A = std::remove_cv_t<std::remove_reference_t<decltype(std::get<I>(values))>>;
-  if constexpr (std::is_same_v<A, const char *> && I + 1 < std::tuple_size_v<Tuple>) {
-    using Next = std::remove_cv_t<std::remove_reference_t<decltype(std::get<I + 1>(values))>>;
-    if constexpr (std::is_integral_v<Next>) return toHandle(std::get<I>(values));
-    else return callbackArgument<A>(std::get<I>(values));
-  } else return callbackArgument<A>(std::get<I>(values));
-}
+        text = text.replace('#ifndef __EMSCRIPTEN__\nstruct RuntimeCallbacks {', `${CALLBACK_ARGUMENT_AT}
 #ifndef __EMSCRIPTEN__
 struct RuntimeCallbacks {`);
         text = text.replaceAll('template<typename R, typename... A> R invokeCallback(size_t slot, A... args) {',
@@ -44,5 +57,5 @@ struct RuntimeCallbacks {`);
 }
 template<typename F> struct Callback {`);
     }
-    return text;
+    return text.replace(CALLBACK_ARGUMENT_AT_WITHOUT_CONST, CALLBACK_ARGUMENT_AT);
 }

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/embindPointerOwners.js

@@ -0,0 +1,42 @@
+// A pointer a member function or property hands out can point into the object it was called on, as a getter of a
+// member behind a unique_ptr does, or name that object, as a fluent call does. JavaScript frees the object once
+// nothing reaches its handle (utils/embindObjectLifetime.js), and the pointer then reads freed memory. The handle of
+// such a pointer holds a clone of the object's handle, on the count the pointer's clones share, so the object goes
+// with the last of them. Only a raw pointer, a NativePointer and an emscripten::val can borrow: a copy and a smart
+// pointer hold what they point at. Static methods and free functions have no object to hold.
+
+const HELPERS = 'function crossbindMayBorrow(type){if(!type)return false;if(type.name==="emscripten::val")return true;'
+    + 'var cls=type.registeredClass;return!!cls&&!type.isReference&&(!type.isSmartPointer||cls.name==="NativePointer")}'
+    + 'function crossbindKeepOwner(value,owner){var $$=value&&value.$$;var held=owner&&owner.$$;'
+    + 'if(!$$||!$$.count||$$.count.owner||!held||!held.ptr||held.preservePointerOnDelete||$$.count===held.count)return value;'
+    + 'if($$.smartPtr?$$.ptrType.registeredClass.name==="NativePointer":!$$.count.owned)$$.count.owner=owner.clone();return value}'
+    + 'function crossbindKeepsOwner(fn,type){if(!crossbindMayBorrow(type))return fn;'
+    + 'var kept=function(...args){var owner=this;var value=fn.apply(owner,args);'
+    + 'return value instanceof Promise?value.then(resolved=>crossbindKeepOwner(resolved,owner)):crossbindKeepOwner(value,owner)};'
+    + 'Object.defineProperty(kept,"name",{value:fn.name});return kept}';
+
+// The release glue spells each on one line, the debug glue with spaces and quoted property names. A release glue
+// names embind's registrations by the minified keys of the wasm imports, so a glue that registers class methods is
+// known by the pure virtual check of the method registration, and one that registers properties by the getter's
+// `this` check.
+const CRAFT = /function craftInvokerFunction\s*\(/;
+const MEMBER = /(var memberFunction\s*=\s*)(craftInvokerFunction\(\s*humanName,\s*argTypes,\s*classType,\s*rawInvoker,\s*context(?:,\s*isAsync)?\s*\))(\s*;)/g;
+const GETTER = /return (getterReturnType(?:\.fromWireType|\[['"]fromWireType['"]\])\(\s*getter\(\s*getterContext,\s*ptr\s*\)\s*\))/g;
+const METHODS = /pureVirtualFunctions\.push\(\s*methodName\s*\)/;
+const PROPERTIES = /humanName\s*\+\s*['"] getter['"]/;
+
+const count = (text, pattern) => text.match(pattern)?.length ?? 0;
+
+// Returns the rewritten glue and whether it binds class methods or properties this rewrite does not recognise.
+export function keepPointerOwners(glue) {
+    const hasMethods = METHODS.test(glue);
+    const hasProperties = PROPERTIES.test(glue);
+    if (!hasMethods && !hasProperties) return { text: glue, missed: false };
+    const recognised = CRAFT.test(glue) && (!hasMethods || count(glue, MEMBER) === 1) && (!hasProperties || count(glue, GETTER) === 1);
+    if (!recognised) return { text: glue, missed: true };
+    const text = glue
+        .replace(CRAFT, (craft) => `${HELPERS}${craft}`)
+        .replace(MEMBER, (_, assign, call, end) => `${assign}crossbindKeepsOwner(${call},argTypes[0])${end}`)
+        .replace(GETTER, (_, read) => `return crossbindKeepOwner(${read},this)`);
+    return { text, missed: false };
+}

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');
+}

package/src/utils/swigInterface.js

@@ -65,7 +65,7 @@ export function interfaceIncludes(headerPath, prelude = []) {
 // wraps just the imported header. The ignored declarations follow the macros, so the retry without macros keeps them.
 export function buildInterfaceContent({
     moduleName, headerPath, prelude = [], completing = [], swigMacros = [], ignored = [], constants = [], preamble = [], functions = ALL_NAMES,
-    extras = [],
+    classes = ALL_NAMES, extras = [],
 }) {
     const includes = [...new Set([...interfaceIncludes(headerPath, prelude), ...completing])]
         .map((header) => `#include "${header}"`)
@@ -89,7 +89,7 @@ ${extraBlock}%{
 ${includes}
 %}
 
-${everyConstant ? '' : constantRequests(constants)}${functionRequests(functions)}%feature("shared_ptr");
+${everyConstant ? '' : constantRequests(constants)}${functionRequests(functions)}${classRequests(classes)}%feature("shared_ptr");
 %feature("polymorphic_shared_ptr");
 
 ${macros}${ignores}${preambleBlock}${everyConstant ? constantRequests(constants) : ''}%include "${headerPath}"
@@ -104,17 +104,32 @@ function constantRequests(constants) {
     return constants.length ? `${constants.map((name) => `%feature("embind:constant") ${name};`).join('\n')}\n\n` : '';
 }
 
-// SWIG ignores every global function, then wraps the listed names again: class members, enums and constants stay. The
-// package's own ignores come after, since SWIG applies the later of two renames of a name.
+// SWIG ignores every global function, then wraps the listed names again: class members, enums and constants stay. A
+// function declared through a function typedef (OpenSSL's `OSSL_provider_init_fn OSSL_provider_init;`) reads as a
+// variable, so global variables are ignored too, as rule 10 binds a mutable one only when imported. The package's own
+// ignores come after, since SWIG applies the later of two renames of a name.
 function functionRequests(functions) {
     if (functions === ALL_NAMES) return '';
     const names = [...new Set(functions)].sort();
-    return `%rename($ignore, %$isfunction, %$isglobal) "";\n${names.map((name) => `%rename("%s") ${name};\n`).join('')}\n`;
+    return `%rename($ignore, %$isfunction, %$isglobal) "";\n%rename($ignore, %$isvariable, %$isglobal) "";\n${names.map((name) => `%rename("%s") ${name};\n`).join('')}\n`;
 }
 
-// Editor declarations need the whole header even when the compiled bridge selects functions by import.
+// SWIG ignores every class, then wraps the classes the app's imports reach (see typeClosure.js) again. A class outside
+// any namespace is wrapped as a class only, so a C function sharing its name (struct stat and stat()) stays out; SWIG
+// matches a namespace's class by its full name only without that condition.
+function classRequests(classes) {
+    if (classes === ALL_NAMES) return '';
+    const lines = [...new Set(classes)].sort()
+        .map((name) => (name.includes('::') ? `%rename("%s") ${name};\n` : `%rename("%s", %$isclass) ${name};\n`));
+    return `%rename($ignore, %$isclass) "";\n${lines.join('')}\n`;
+}
+
+// Editor declarations and SWIG's parse for the bindings plan need the whole header even when the compiled bridge
+// selects functions and classes by import.
 export function interfaceWithAllFunctions(content) {
-    return content.replace(/%rename\(\$ignore, %\$isfunction, %\$isglobal\) "";\n(?:%rename\("%s"\) [A-Za-z_]\w*;\n)*\n/g, '');
+    return content
+        .replace(/%rename\(\$ignore, %\$isfunction, %\$isglobal\) "";\n(?:%rename\(\$ignore, %\$isvariable, %\$isglobal\) "";\n)?(?:%rename\("%s"\) [A-Za-z_]\w*;\n)*\n/g, '')
+        .replace(/%rename\(\$ignore, %\$isclass\) "";\n(?:%rename\("%s"(?:, %\$isclass)?\) [A-Za-z_][\w:]*;\n)*\n/g, '');
 }
 
 export function withoutSwigMacros(content) {

package/src/utils/typeClosure.js

@@ -0,0 +1,170 @@
+import { ALL_NAMES } from './headerImports.js';
+
+// SWIG's own parse of a header (swig -xml), read for the classes a bridge has to register. embind registers each class
+// once, in the bridge of the header defining it, and a binding naming a class no bridge registers fails only when it is
+// called. So a header binds the classes its imported names reach: through their signatures, the bases of those classes
+// and the signatures of their public members, in this header and in the headers defining them.
+
+// SWIG leaves `>` unescaped inside attribute values (std::vector<(T)>), so a tag ends only outside a quoted value.
+const TAG = /<(\/?)([A-Za-z_][\w-]*)((?:\s+[\w:-]+="[^"]*")*)\s*(\/?)>/g;
+const ATTRIBUTE = /([\w:-]+)="([^"]*)"/g;
+const NAME = /[A-Za-z_]\w*(?:::[A-Za-z_]\w*)*/g;
+const ENTITIES = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+// SWIG's type strings spell pointers, references, qualifiers, functions and arrays as p. r. z. q(...). f(...). a(...).
+const NOT_TYPES = new Set([
+    'p', 'r', 'z', 'q', 'f', 'a', 'const', 'volatile', 'struct', 'class', 'union', 'enum', 'typename',
+    'unsigned', 'signed', 'char', 'short', 'int', 'long', 'float', 'double', 'void', 'bool', 'wchar_t', 'size_t',
+]);
+const EMPTY_TREE = { types: new Map(), values: new Map(), enumerators: new Map() };
+
+const decode = (text) => text.replace(/&(lt|gt|amp|quot|apos);/g, (entity, name) => ENTITIES[name]);
+
+function parse(xml) {
+    const root = { tag: 'root', attributes: {}, children: [] };
+    const open = [root];
+    for (const [, closing, tag, rest, selfClosing] of xml.matchAll(TAG)) {
+        if (closing) {
+            open.pop();
+            continue;
+        }
+        const attributes = Object.fromEntries([...rest.matchAll(ATTRIBUTE)].map(([, key, value]) => [key, decode(value)]));
+        const node = { tag, attributes, children: [] };
+        open.at(-1).children.push(node);
+        if (!selfClosing) open.push(node);
+    }
+    return root;
+}
+
+// A node's own attributes are the <attribute> elements of its first <attributelist>.
+const listOf = (node) => node.children.find((child) => child.tag === 'attributelist')?.children ?? [];
+const attributesOf = (node) => Object.fromEntries(listOf(node).filter((child) => child.tag === 'attribute')
+    .map((child) => [child.attributes.name, child.attributes.value]));
+const basesOf = (node) => listOf(node).filter((child) => child.tag === 'baselist')
+    .flatMap((list) => list.children.filter((child) => child.tag === 'base').map((base) => base.attributes.name));
+const parametersOf = (node) => listOf(node).filter((child) => child.tag === 'parmlist')
+    .flatMap((list) => list.children.filter((child) => child.tag === 'parm').map((parm) => attributesOf(parm).type ?? ''));
+
+// What a header declares: its classes, enums and typedefs by qualified name, each with the type strings it uses, its free
+// functions and variables by name, and the enum of each enumerator. SWIG binds no nested class and no member a class
+// keeps private, so neither reaches anything.
+export function readSwigTree(xml) {
+    const types = new Map();
+    const values = new Map();
+    const enumerators = new Map();
+    // C names a struct and its typedef alike (`typedef struct PJ_INFO PJ_INFO;` ahead of `struct PJ_INFO {...}`), and the
+    // name stands for the struct.
+    const declare = (name, entry) => {
+        if (!types.has(name) || (types.get(name).kind === 'typedef' && entry.kind !== 'typedef')) types.set(name, entry);
+    };
+    const visit = (node, namespace, owner) => {
+        // %$isclass leaves class templates alone, so the selection does too.
+        if (node.tag === 'template') return;
+        const own = node.tag === 'root' ? {} : attributesOf(node);
+        const isPublic = own.access !== 'private' && own.access !== 'protected';
+        // SWIG spells a class or enum by its full name; a typedef inside a namespace or class may be spelled without it.
+        const qualified = (name) => (name.includes('::') || !namespace.length ? name : [...namespace, name].join('::'));
+        if (node.tag === 'namespace') {
+            node.children.forEach((child) => visit(child, own.name ? [...namespace, own.name] : namespace, null));
+        } else if (node.tag === 'class') {
+            if (!own.name || !isPublic || own.nested === '1') return;
+            const name = qualified(own.name);
+            // The name SWIG binds it under: a C struct's typedef name (X509V3_CONF_METHOD for X509V3_CONF_METHOD_st).
+            const bound = own.sym_name ?? own['sym:name'] ?? own.tdname ?? name.split('::').at(-1);
+            const entry = { kind: 'class', scope: name.split('::'), bases: basesOf(node), uses: [], bound };
+            declare(name, entry);
+            node.children.forEach((child) => visit(child, namespace, entry));
+        } else if (node.tag === 'enum') {
+            if (!own.name || !isPublic) return;
+            const name = owner && !own.name.includes('::') ? [...owner.scope, own.name].join('::') : qualified(own.name);
+            declare(name, { kind: 'enum', scope: name.split('::'), bases: [], uses: [] });
+            node.children.filter((child) => child.tag === 'enumitem').forEach((item) => {
+                const enumerator = attributesOf(item).name;
+                if (enumerator && !enumerators.has(enumerator)) enumerators.set(enumerator, name);
+            });
+        } else if (node.tag === 'cdecl') {
+            if (!own.name || !isPublic || own.storage === 'friend') return;
+            const uses = [own.type ?? '', own.decl ?? '', ...parametersOf(node)];
+            if (own.storage === 'typedef') {
+                const name = owner ? [...owner.scope, own.name].join('::') : qualified(own.name);
+                declare(name, { kind: 'typedef', scope: name.split('::'), bases: [], uses });
+            } else if (owner) {
+                owner.uses.push(...uses);
+            } else {
+                // An import of an overloaded name binds every overload.
+                values.set(own.name, [...(values.get(own.name) ?? []), ...uses]);
+            }
+        } else if (node.tag === 'constructor') {
+            if (owner && isPublic) owner.uses.push(own.decl ?? '', ...parametersOf(node));
+        } else {
+            node.children.forEach((child) => visit(child, namespace, owner));
+        }
+    };
+    visit(parse(xml), [], null);
+    return { types, values, enumerators };
+}
+
+// The classes and enums `names` reach from `header`, by qualified name, each with its kind and the header defining it.
+// `treeOf` reads a header's parse; a name no header read so far declares is looked up through `definingHeader`, whose
+// header is read in turn. ALL_NAMES starts from everything the header declares, as a header bound whole does.
+export function typeClosure(header, names, { treeOf, definingHeader }) {
+    const trees = new Map();
+    const read = (file) => {
+        if (!trees.has(file)) trees.set(file, treeOf(file) ?? EMPTY_TREE);
+        return trees.get(file);
+    };
+    const root = read(header);
+    const lookedUp = new Set();
+    const inTrees = (candidates, wanted) => {
+        for (const candidate of candidates) {
+            for (const [file, tree] of trees) {
+                const entry = tree.types.get(candidate);
+                if (entry && wanted(entry)) return { name: candidate, file, entry };
+            }
+        }
+        return null;
+    };
+    const isClassOrEnum = (entry) => entry.kind !== 'typedef';
+    // A class or enum wins over a typedef of the same name, even one another header declares first (a forward header's
+    // `typedef struct Foo Foo;`), so a header that may define the name is read before a typedef stands for it.
+    const find = (candidates) => {
+        const found = inTrees(candidates, isClassOrEnum);
+        if (found) return found;
+        for (const candidate of candidates) {
+            if (lookedUp.has(candidate)) continue;
+            lookedUp.add(candidate);
+            const file = definingHeader(candidate);
+            if (file && !trees.has(file)) read(file);
+        }
+        return inTrees(candidates, isClassOrEnum) ?? inTrees(candidates, () => true);
+    };
+    const queue = [];
+    const reach = (text, scope) => {
+        for (const [name] of text.matchAll(NAME)) {
+            if (!NOT_TYPES.has(name)) queue.push({ name, scope });
+        }
+    };
+    const start = names === ALL_NAMES ? [...root.values.keys(), ...root.types.keys()] : names;
+    for (const name of start) {
+        if (root.values.has(name)) root.values.get(name).forEach((use) => reach(use, []));
+        else queue.push({ name: root.enumerators.get(name) ?? name, scope: [] });
+    }
+    const reached = new Map();
+    const visited = new Set();
+    while (queue.length) {
+        const { name, scope } = queue.pop();
+        // As in C++ lookup, a name used inside a class or namespace is tried there first.
+        const candidates = [...scope.map((_, depth) => [...scope.slice(0, scope.length - depth), name].join('::')), name];
+        const found = find(candidates);
+        if (!found || visited.has(found.name)) continue;
+        visited.add(found.name);
+        const { entry } = found;
+        if (entry.kind === 'class') reached.set(found.name, { kind: entry.kind, header: found.file, bound: entry.bound });
+        else if (entry.kind === 'enum') reached.set(found.name, { kind: entry.kind, header: found.file });
+        const enclosing = entry.scope.slice(0, -1);
+        // SWIG binds an enum declared in a class only with that class.
+        if (entry.kind === 'enum' && enclosing.length) queue.push({ name: enclosing.join('::'), scope: [] });
+        entry.bases.forEach((base) => queue.push({ name: base, scope: enclosing }));
+        entry.uses.forEach((use) => reach(use, entry.kind === 'class' ? entry.scope : enclosing));
+    }
+    return reached;
+}