rusteerio 0.0.0-stage → 0.1.0

package/scripts/check-release.mjs

@@ -0,0 +1,235 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { gunzipSync } from 'node:zlib';
+
+export const nativeTargets = ['darwin-x64', 'darwin-arm64', 'linux-x64-gnu', 'linux-arm64-gnu', 'linux-x64-musl', 'linux-arm64-musl', 'win32-x64-msvc', 'win32-arm64-msvc'];
+const requiredFiles = ['package.json', 'LICENSE', 'README.md', 'CONTRIBUTING.md', 'RELEASING.md', 'THIRD_PARTY_NOTICES.md', 'Cargo.toml', 'Cargo.lock', 'build.rs', 'native/src/lib.rs', 'native/vendor/README.md', 'native/vendor/html5ever-0.35.0/Cargo.toml', 'native/vendor/html5ever-0.35.0/src/lib.rs', 'native/vendor/html5ever-0.35.0/LICENSE-MIT', 'native/vendor/html5ever-0.35.0/LICENSE-APACHE', 'native/vendor/markup5ever-0.35.0/Cargo.toml', 'native/vendor/markup5ever-0.35.0/lib.rs', 'native/vendor/markup5ever-0.35.0/LICENSE-MIT', 'native/vendor/markup5ever-0.35.0/LICENSE-APACHE', 'src/index.ts', 'tsconfig.json', 'tsup.config.ts', 'scripts/check-native.mjs', 'scripts/check-release.mjs', 'scripts/fix-declarations.mjs', 'scripts/generate-notices.mjs', 'scripts/notices/sources.json', 'scripts/notices/runtime.json', 'scripts/notices/cheerio-MIT.txt', 'dist/index.cjs', 'dist/index.mjs', 'dist/index.d.ts', 'dist/index.d.mts', 'dist/slim.cjs', 'dist/slim.mjs', 'dist/utils.cjs', 'dist/utils.mjs'];
+const root = fileURLToPath(new URL('../', import.meta.url));
+
+export function validateVersion(version, distTag = 'latest') {
+  assert.equal(typeof version, 'string', 'A release version is required');
+  assert.match(version, /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*))?$/, 'Use an exact semantic version without a v prefix or build metadata');
+  const prerelease = version.split('-').slice(1).join('-');
+  for (const identifier of prerelease.split('.')) assert.ok(!/^0\d+$/.test(identifier), 'Numeric prerelease identifiers cannot have leading zeroes');
+  assert.ok(distTag === 'latest' || distTag === 'next', 'The npm dist-tag must be latest or next');
+  assert.ok(!prerelease || distTag !== 'latest', 'Prereleases must use the next npm dist-tag');
+  return `v${version}`;
+}
+
+export function validateMetadata(metadata, cargo) {
+  assert.equal(metadata.name, 'rusteerio');
+  validateVersion(metadata.version, metadata.version.includes('-') ? 'next' : 'latest');
+  assert.equal(metadata.license, 'MIT');
+  assert.notEqual(metadata.private, true, 'The release package cannot be private');
+  assert.equal(metadata.author?.name, 'Context.dev team');
+  assert.equal(metadata.author?.url, 'https://context.dev');
+  assert.equal(metadata.repository?.url, 'git+https://github.com/context-dot-dev/rusteerio.git');
+  assert.equal(metadata.engines?.node, '>=20.19.0');
+  assert.equal(metadata.publishConfig?.access, 'public');
+  assert.equal(metadata.publishConfig?.registry, 'https://registry.npmjs.org/');
+  for (const key of ['dependencies', 'optionalDependencies', 'peerDependencies']) assert.deepEqual(Object.keys(metadata[key] ?? {}), [], `${key} must remain empty`);
+  for (const key of ['bundledDependencies', 'bundleDependencies']) assert.ok(!metadata[key] || Array.isArray(metadata[key]) && !metadata[key].length, `${key} must remain empty`);
+  for (const lifecycle of ['preinstall', 'install', 'postinstall']) assert.equal(metadata.scripts?.[lifecycle], undefined, `The package must not require an ${lifecycle} hook`);
+  assert.equal(cargo.match(/\[package\][\s\S]*?\nversion\s*=\s*"([^"]+)"/)?.[1], metadata.version, 'Cargo and npm versions must match');
+}
+
+/** Read ELF version requirements from SHT_GNU_verneed, rather than strings in code/data. */
+export function elfRequirements(data) {
+  const versions = new Set(), libraries = new Set(), requirements = [];
+  const table = Number(data.readBigUInt64LE(40)), entrySize = data.readUInt16LE(58), count = data.readUInt16LE(60);
+  if (!table || !count) return { versions: [], libraries: [], requirements: [] };
+  assert.ok(entrySize >= 64 && table + entrySize * count <= data.length, 'Truncated ELF section table');
+  const sections = Array.from({ length: count }, (_, index) => {
+    const at = table + index * entrySize;
+    return { type: data.readUInt32LE(at + 4), offset: Number(data.readBigUInt64LE(at + 24)), size: Number(data.readBigUInt64LE(at + 32)), link: data.readUInt32LE(at + 40) };
+  });
+  function string(section, offset) {
+    assert.ok(section && offset >= 0 && offset < section.size && section.offset + section.size <= data.length, 'Invalid ELF string table');
+    const start = section.offset + offset, end = data.indexOf(0, start);
+    assert.ok(end >= start && end < section.offset + section.size, 'Unterminated ELF symbol version');
+    return data.toString('utf8', start, end);
+  }
+  for (const section of sections) {
+    assert.ok(section.offset >= 0 && section.offset + section.size <= data.length || section.type === 8, 'Truncated ELF section');
+    if (section.type === 6) {
+      for (let at = section.offset; at + 16 <= section.offset + section.size; at += 16) {
+        if (data.readBigInt64LE(at) === 1n) libraries.add(string(sections[section.link], Number(data.readBigUInt64LE(at + 8))));
+      }
+    }
+    if (section.type !== 0x6ffffffe) continue;
+    let at = section.offset;
+    for (let visited = 0; at + 16 <= section.offset + section.size && visited < section.size / 16; visited++) {
+      const entries = data.readUInt16LE(at + 2), next = data.readUInt32LE(at + 12);
+      const library = string(sections[section.link], data.readUInt32LE(at + 4));
+      let aux = at + data.readUInt32LE(at + 8);
+      for (let index = 0; index < entries; index++) {
+        assert.ok(aux >= section.offset && aux + 16 <= section.offset + section.size, 'Truncated ELF version requirement');
+        const version = string(sections[section.link], data.readUInt32LE(aux + 8));
+        versions.add(version);
+        requirements.push({ library, version });
+        const step = data.readUInt32LE(aux + 12);
+        if (!step) break;
+        aux += step;
+      }
+      if (!next) break;
+      at += next;
+    }
+  }
+  return { versions: [...versions].sort(), libraries: [...libraries].sort(), requirements };
+}
+
+export function validateNativeBinary(name, data) {
+  assert.ok(data.length >= 64, `${name} is empty or truncated`);
+  if (name.includes('.linux-')) {
+    assert.equal(data.subarray(0, 6).toString('hex'), '7f454c460201', `${name} must be a little-endian 64-bit ELF binary`);
+    assert.equal(data.readUInt16LE(18), name.includes('-arm64-') ? 183 : 62, `${name} has the wrong CPU architecture`);
+    const { versions, libraries, requirements } = elfRequirements(data);
+    if (name.includes('-gnu.')) {
+      for (const version of versions.filter(version => version.startsWith('GLIBC_'))) {
+        const numbers = version.slice(6).split('.').map(Number);
+        assert.ok(numbers[0] < 2 || numbers[0] === 2 && numbers[1] <= 28, `${name} requires ${version}; releases must support glibc 2.28`);
+      }
+      assert.ok(!versions.some(version => version.startsWith('GLIBCXX_')), `${name} unexpectedly requires a C++ runtime`);
+    } else {
+      // Alpine's ARM64 libgcc versions its frame-registration exports as
+      // GLIBC_2.0. The version name belongs to libgcc, not a glibc dependency.
+      assert.ok(!requirements.some(({ library, version }) => version.startsWith('GLIBC_') && !(library === 'libgcc_s.so.1' && version === 'GLIBC_2.0')), `${name} links glibc instead of musl`);
+      assert.ok(!libraries.some(library => library === 'libc.so.6'), `${name} links glibc instead of musl`);
+    }
+  } else if (name.includes('.darwin-')) {
+    assert.equal(data.readUInt32LE(0), 0xfeedfacf, `${name} must be a 64-bit Mach-O binary`);
+    assert.equal(data.readUInt32LE(4), name.includes('-arm64.') ? 0x0100000c : 0x01000007, `${name} has the wrong CPU architecture`);
+  } else {
+    assert.equal(data.subarray(0, 2).toString(), 'MZ', `${name} must be a Windows PE binary`);
+    const offset = data.readUInt32LE(0x3c);
+    assert.ok(offset + 6 <= data.length, `${name} has a truncated PE header`);
+    assert.equal(data.subarray(offset, offset + 4).toString('hex'), '50450000', `${name} has an invalid PE signature`);
+    assert.equal(data.readUInt16LE(offset + 4), name.includes('-arm64-') ? 0xaa64 : 0x8664, `${name} has the wrong Windows CPU architecture`);
+  }
+}
+
+function allowedFile(path) {
+  return requiredFiles.includes(path) || /^dist\/[\w./-]+\.(?:[cm]?js|map|[cm]?ts)$/.test(path)
+    || /^(?:src\/[\w/-]+\.ts|native\/src\/[\w/-]+\.rs)$/.test(path)
+    || /^native\/vendor\/(?:(?:html5ever|markup5ever)-0\.35\.0|html5gum-0\.8\.4)\/(?:[\w./-]+\.(?:rs|c|h|html|md|toml|orig|json)|Cargo\.lock|LICENSE(?:-(?:MIT|APACHE))?)$/.test(path)
+    || /^scripts\/notices\/[\w-]+\.(?:txt|md|json)$/.test(path)
+    || nativeTargets.some(target => path === `rusteerio.${target}.node`);
+}
+
+export function validatePackageFiles(files, { allTargets = true } = {}) {
+  for (const path of files.keys()) {
+    assert.ok(!path.split('/').some(part => part === '.' || part === '..' || part === 'target' || part === 'node_modules') && !path.includes('\\'), `Unsafe package path: ${path}`);
+    assert.ok(allowedFile(path), `Unexpected package file: ${path}`);
+  }
+  for (const path of requiredFiles) assert.ok(files.get(path)?.length > 0, `Package is missing ${path}`);
+  for (const path of ['native/vendor/html5gum-0.8.4/Cargo.toml', 'native/vendor/html5gum-0.8.4/src/lib.rs', 'native/vendor/html5gum-0.8.4/LICENSE']) assert.ok(files.get(path)?.length > 0, `Package is missing ${path}`);
+  assert.match(files.get('LICENSE').toString(), /MIT License/);
+  assert.match(files.get('THIRD_PARTY_NOTICES.md').toString(), /cheerio/i);
+  assert.match(files.get('README.md').toString(), /context\.dev/i);
+  const binaries = [...files].filter(([path]) => path.endsWith('.node'));
+  assert.ok(binaries.length > 0, 'Package has no native binary');
+  if (allTargets) for (const target of nativeTargets) assert.ok(files.has(`rusteerio.${target}.node`), `Release is missing the ${target} binary`);
+  for (const [path, data] of binaries) validateNativeBinary(path, data);
+  const metadata = JSON.parse(files.get('package.json'));
+  validateMetadata(metadata, files.get('Cargo.toml').toString());
+  return metadata;
+}
+
+/** Read regular files only; links and archive paths outside package/ are rejected. */
+export function readTarball(path) {
+  const tar = gunzipSync(readFileSync(path), { maxOutputLength: 256 * 1024 * 1024 });
+  const files = new Map();
+  let extended = {};
+  const string = bytes => bytes.toString('utf8').replace(/\0.*$/s, '');
+  for (let offset = 0; offset + 512 <= tar.length;) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every(byte => byte === 0)) {
+      assert.ok(tar.subarray(offset).every(byte => byte === 0), 'Unexpected data after the tar archive terminator');
+      break;
+    }
+    const checksum = [...header].reduce((sum, value, index) => sum + (index >= 148 && index < 156 ? 32 : value), 0);
+    assert.equal(checksum, Number.parseInt(string(header.subarray(148, 156)).trim(), 8), 'Invalid tar header checksum');
+    const size = Number.parseInt(string(header.subarray(124, 136)).trim(), 8);
+    assert.ok(Number.isSafeInteger(size) && size >= 0 && offset + 512 + size <= tar.length, 'Invalid tar entry size');
+    const data = tar.subarray(offset + 512, offset + 512 + size);
+    const type = header[156];
+    let path = string(header.subarray(0, 100));
+    const prefix = string(header.subarray(345, 500));
+    if (prefix) path = `${prefix}/${path}`;
+    if (type === 120) {
+      extended = {};
+      let index = 0;
+      while (index < data.length) {
+        const space = data.indexOf(32, index);
+        const length = Number(data.subarray(index, space).toString());
+        assert.ok(space > index && Number.isSafeInteger(length) && length > space - index && index + length <= data.length, 'Invalid PAX header');
+        const entry = data.subarray(space + 1, index + length - 1).toString();
+        const separator = entry.indexOf('=');
+        assert.ok(separator > 0, 'Invalid PAX attribute');
+        extended[entry.slice(0, separator)] = entry.slice(separator + 1);
+        index += length;
+      }
+    } else if (type !== 53) {
+      assert.ok(type === 0 || type === 48, 'Package tarball must contain regular files, not links');
+      path = extended.path ?? path;
+      extended = {};
+      assert.ok(path.startsWith('package/'), `Unexpected tarball path: ${path}`);
+      path = path.slice('package/'.length);
+      assert.ok(!files.has(path), `Duplicate tarball entry: ${path}`);
+      files.set(path, data);
+    }
+    offset += 512 + Math.ceil(size / 512) * 512;
+  }
+  return files;
+}
+
+function run() {
+  const args = process.argv.slice(2);
+  const options = {};
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index];
+    if (argument === '--local') options.local = true;
+    else {
+      assert.ok(['--tarball', '--manifest', '--verify-manifest', '--commit'].includes(argument), `Unknown argument: ${argument}`);
+      assert.ok(args[index + 1], `${argument} requires a value`);
+      options[argument.slice(2)] = args[++index];
+    }
+  }
+  if (options.commit) {
+    assert.match(options.commit, /^[a-f0-9]{40}$/);
+    assert.equal(execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8' }).trim(), options.commit, 'Checkout and release commit differ');
+  }
+  let tarball = options.tarball;
+  if (tarball && !tarball.endsWith('.tgz')) {
+    const candidates = readdirSync(tarball).filter(path => path.endsWith('.tgz'));
+    assert.equal(candidates.length, 1, 'The release directory must contain exactly one npm tarball');
+    tarball = join(tarball, candidates[0]);
+  }
+  let files;
+  if (tarball) files = readTarball(tarball);
+  else {
+    const npm = process.env.npm_execpath;
+    const result = npm ? execFileSync(process.execPath, [npm, 'pack', '--dry-run', '--ignore-scripts', '--json'], { cwd: root, encoding: 'utf8' })
+      : execFileSync('npm', ['pack', '--dry-run', '--ignore-scripts', '--json'], { cwd: root, encoding: 'utf8' });
+    files = new Map(JSON.parse(result)[0].files.map(({ path }) => [path, readFileSync(join(root, path))]));
+  }
+  const metadata = validatePackageFiles(files, { allTargets: !options.local });
+  if (options.commit) for (const [path, contents] of files) {
+    if (path.startsWith('dist/') || path.endsWith('.node')) continue;
+    const committed = execFileSync('git', ['show', `${options.commit}:${path}`], { cwd: root });
+    assert.ok(committed.equals(contents), `${path} differs from the declared release commit`);
+  }
+  const manifest = { format: 1, name: metadata.name, version: metadata.version, commit: options.commit, filename: tarball ? basename(tarball) : undefined, sha256: tarball ? createHash('sha256').update(readFileSync(tarball)).digest('hex') : undefined, targets: nativeTargets.filter(target => files.has(`rusteerio.${target}.node`)) };
+  if (options.manifest) {
+    assert.ok(tarball && options.commit && !options.local, 'Release manifests require a complete tarball and exact commit');
+    writeFileSync(options.manifest, `${JSON.stringify(manifest, null, 2)}\n`);
+  }
+  if (options['verify-manifest']) assert.deepEqual(JSON.parse(readFileSync(options['verify-manifest'])), manifest, 'Release artifact does not match its tested manifest');
+  console.log(`${metadata.name}@${metadata.version}: package contents, license, source, zero npm dependencies and ${manifest.targets.length} native targets verified${options.local ? ' (local platform check)' : ''}.`);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) run();

package/scripts/fix-declarations.mjs

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import { readFileSync, writeFileSync } from 'node:fs';
+import ts from 'typescript';
+
+// The declaration bundler can drop `type` when re-exporting classes or enums.
+// Keep the public entry points faithful to source `export type` statements.
+const typeOnly = new Set(['Cheerio', 'ElementType']);
+for (const entry of ['index', 'slim']) {
+  for (const extension of ['d.ts', 'd.mts']) {
+    const file = new URL(`../dist/${entry}.${extension}`, import.meta.url);
+    let text = readFileSync(file, 'utf8');
+    const source = ts.createSourceFile(file.pathname, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const edits = [];
+    const found = new Set();
+    for (const statement of source.statements) {
+      if (!ts.isExportDeclaration(statement) || !statement.exportClause || !ts.isNamedExports(statement.exportClause)) continue;
+      for (const specifier of statement.exportClause.elements) {
+        if (!typeOnly.has(specifier.name.text)) continue;
+        found.add(specifier.name.text);
+        if (!statement.isTypeOnly && !specifier.isTypeOnly) edits.push(specifier.getStart(source));
+      }
+    }
+    assert.deepEqual([...found].sort(), [...typeOnly].sort(), `${entry}.${extension} must expose its intended type exports`);
+    for (const position of edits.sort((left, right) => right - left)) text = text.slice(0, position) + 'type ' + text.slice(position);
+    if (edits.length) writeFileSync(file, text);
+  }
+}

package/scripts/generate-notices.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const output = join(root, 'THIRD_PARTY_NOTICES.md');
+const cacheDir = join(root, 'scripts', 'notices');
+const check = process.argv.includes('--check');
+const args = process.argv.slice(2);
+if (args.some((arg) => arg !== '--check')) throw new Error('Usage: node scripts/generate-notices.mjs [--check]');
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+const read = (path) => readFileSync(path, 'utf8').replace(/\r\n?/g, '\n');
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const legalName = /^(?:licen[cs]e(?:[-_.].*)?|unlicense|copying(?:[-_.].*)?|copyright(?:[-_.].*)?|notice(?:[-_.].*)?|authors(?:[-_.].*)?)$/i;
+const metadata = JSON.parse(execFileSync(process.env.CARGO || 'cargo', [
+  'metadata', '--locked', '--format-version', '1',
+], { cwd: root, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 }));
+const vendored = new Set(['html5ever@0.35.0', 'markup5ever@0.35.0', 'html5gum@0.8.4']);
+for (const pkg of metadata.packages) {
+  if (!pkg.source && pkg.name !== 'rusteerio' && !vendored.has(`${pkg.name}@${pkg.version}`)) throw new Error(`Review notices for the new local dependency ${pkg.name}@${pkg.version}`);
+}
+const packages = metadata.packages.filter((pkg) => pkg.source || vendored.has(`${pkg.name}@${pkg.version}`))
+  .sort((a, b) => compare(a.name, b.name) || compare(a.version, b.version));
+const byName = new Map(packages.map((pkg) => [`${pkg.name}@${pkg.version}`, pkg]));
+const supplements = JSON.parse(read(join(cacheDir, 'sources.json')));
+if (supplements.schemaVersion !== 1) throw new Error('Unsupported supplemental notice schema');
+const runtime = JSON.parse(read(join(cacheDir, 'runtime.json')));
+if (runtime.schemaVersion !== 1) throw new Error('Unsupported Rust runtime notice schema');
+if (check) {
+  const rustc = execFileSync(process.env.RUSTC || 'rustc', ['--version'], { encoding: 'utf8' }).trim();
+  const version = /^rustc (\d+\.\d+\.\d+)/.exec(rustc)?.[1];
+  if (!version || !runtime.releases[version]) throw new Error(`Review and add standard-library notices before releasing with ${rustc}`);
+}
+
+for (const [file, entry] of Object.entries(supplements.cache)) {
+  if (sha256(read(join(cacheDir, file))) !== entry.sha256) throw new Error(`Supplemental notice checksum mismatch: ${file}`);
+}
+for (const key of Object.keys(supplements.packages)) {
+  if (!byName.has(key)) throw new Error(`Remove or review stale supplemental notices for ${key}`);
+}
+
+function legalFiles(dir, base = dir, insideLegalDir = false) {
+  const files = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === '.git' || entry.name === 'target') continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...legalFiles(path, base, insideLegalDir || /^(?:licen[cs]es?|notices?)$/i.test(entry.name)));
+    else if (entry.isFile() && (insideLegalDir || legalName.test(entry.name))) files.push(relative(base, path).replaceAll('\\', '/'));
+  }
+  return files.sort(compare);
+}
+
+function crateSource(pkg, path) {
+  return `https://docs.rs/crate/${pkg.name}/${pkg.version}/source/${path}`;
+}
+
+const texts = new Map();
+function notice(name, source, text) {
+  if (!text.trim()) throw new Error(`Empty notice: ${name}`);
+  const digest = sha256(text);
+  if (!texts.has(digest)) texts.set(digest, text);
+  return { name, source, digest };
+}
+
+function cachedNotice(entry) {
+  if (!supplements.cache[entry.cache]?.sources.includes(entry.source)) throw new Error(`Unknown notice provenance for ${entry.cache}`);
+  return notice(entry.name, entry.source, read(join(cacheDir, entry.cache)));
+}
+
+function packageNotices(pkg) {
+  const dir = dirname(pkg.manifest_path);
+  const files = legalFiles(dir);
+  if (pkg.license_file) {
+    const path = relative(dir, resolve(dir, pkg.license_file)).replaceAll('\\', '/');
+    if (!files.includes(path)) files.push(path);
+  }
+  const notices = files.sort(compare).map((file) => notice(file, crateSource(pkg, file), read(join(dir, file))));
+  const extra = supplements.packages[`${pkg.name}@${pkg.version}`];
+  for (const entry of extra?.notices || []) {
+    if (entry.cache) {
+      notices.push(cachedNotice(entry));
+    } else {
+      const sourcePackage = entry.package ? byName.get(entry.package) : pkg;
+      if (!sourcePackage) throw new Error(`Missing supplemental source package ${entry.package}`);
+      let text = read(join(dirname(sourcePackage.manifest_path), entry.file));
+      if (entry.startLine) text = text.split('\n').slice(entry.startLine - 1, entry.endLine).join('\n') + '\n';
+      notices.push(notice(entry.name, crateSource(sourcePackage, entry.file), text));
+    }
+  }
+  if (!pkg.license) throw new Error(`Review missing license expression for ${pkg.name}@${pkg.version}`);
+  if (!notices.length) throw new Error(`No license notices found for ${pkg.name}@${pkg.version}; add a reviewed supplemental source`);
+  return { notices, reason: extra?.reason };
+}
+
+const upstreamLicense = notice('Cheerio MIT LICENSE',
+  'https://github.com/cheeriojs/cheerio/blob/e3c7aaf9ed64fe3cb9a181e58a41c0fdd6dbfbfc/LICENSE',
+  read(join(cacheDir, 'cheerio-MIT.txt')));
+const vendoredCheerioLicense = join(root, 'test', 'upstream', 'LICENSE');
+if (existsSync(vendoredCheerioLicense) && read(vendoredCheerioLicense) !== read(join(cacheDir, 'cheerio-MIT.txt'))) {
+  throw new Error('Vendored Cheerio license differs from the pinned upstream notice');
+}
+const records = packages.map((pkg) => ({ pkg, ...packageNotices(pkg) }));
+const runtimeReleases = Object.entries(runtime.releases).sort(([a], [b]) => compare(a, b))
+  .map(([version, entry]) => ({ version, ...entry, notices: entry.notices.map(cachedNotice) }));
+const runtimePackages = Object.entries(runtime.packages).sort(([a], [b]) => compare(a, b))
+  .map(([key, entry]) => ({ key, ...entry, notices: entry.notices.map(cachedNotice) }));
+const parts = [
+  '# Third-party notices',
+  '',
+  'This file preserves third-party license and attribution notices for the Rust native addon and the upstream Cheerio compatibility tests. Rusteerio itself is distributed under its MIT LICENSE. Third-party components retain their own licenses.',
+  '',
+  'Generated by `node scripts/generate-notices.mjs` from `cargo metadata --locked`, crate license files, and the pinned supplemental sources recorded in `scripts/notices/sources.json`. It includes build dependencies and dependencies for all target platforms; a particular binary may use a subset. Identical notice texts are reproduced once and referenced below. The html5ever, markup5ever and html5gum crates contain local observer-hook and opt-in UTF-16 transport patches; their complete patched source and original notices are included in `native/vendor`. Other dependency source files are unmodified.',
+  '',
+  `Cargo.lock SHA-256: \`${sha256(readFileSync(join(root, 'Cargo.lock')))}\`.`,
+  '',
+  '## Source availability',
+  '',
+  'The native addon includes code from packages licensed under MPL-2.0. The complete, unmodified Source Code Form of each dependency is available without charge from the version-specific source download links below. These downloads contain the corresponding upstream source and notices. MPL-covered source remains available under MPL-2.0, whose full text is included in this file. The MIT license for Rusteerio does not restrict rights granted by third-party source licenses.',
+  '',
+  'The locally patched html5ever and markup5ever components are licensed under MIT OR Apache-2.0; html5gum is licensed under MIT. Their upstream archives are linked below; the exact patched Source Code Form is shipped in the npm package under `native/vendor` and maintained in [this repository](https://github.com/context-dot-dev/rusteerio/tree/main/native/vendor). See `native/vendor/README.md` for the patch scope. Their original license and copyright files remain intact.',
+  '',
+  '## Cheerio compatibility tests',
+  '',
+  'The vendored compatibility suite and fixtures come from Cheerio 1.2.0, commit `e3c7aaf9ed64fe3cb9a181e58a41c0fdd6dbfbfc`. Implementation imports are redirected to Rusteerio. Their original MIT notice is retained in `test/upstream/LICENSE` and reproduced here.',
+  '',
+  `- [${upstreamLicense.name}](#notice-${upstreamLicense.digest.slice(0, 16)}) — [upstream source](${upstreamLicense.source})`,
+  '',
+  `## Rust dependencies (${records.length} locked packages)`,
+];
+for (const { pkg, notices, reason } of records) {
+  parts.push('', `### ${pkg.name} ${pkg.version}`, '', `Declared license: \`${pkg.license}\`.`, '',
+    `Source: [${pkg.name} ${pkg.version} source archive](https://crates.io/api/v1/crates/${pkg.name}/${pkg.version}/download).`);
+  if (reason) parts.push('', reason);
+  if (!pkg.source) {
+    const sourcePath = relative(root, dirname(pkg.manifest_path)).replaceAll('\\', '/');
+    if (sourcePath !== `native/vendor/${pkg.name}-${pkg.version}`) throw new Error(`Unexpected vendored dependency path: ${sourcePath}`);
+    parts.push('', `Locally patched source: \`${sourcePath}\` (included in the npm package). Original upstream licenses are retained.`);
+  }
+  parts.push('');
+  for (const entry of notices) parts.push(`- [${entry.name}](#notice-${entry.digest.slice(0, 16)}) — [notice source](${entry.source})`);
+}
+parts.push('', '## Rust standard-library runtime', '',
+  `The native addon builds used Rust ${runtimeReleases.map((entry) => entry.version).join(' and ')}. These curated notices preserve their standard-library copyright declarations, in-tree exceptions, compiler-builtins license, and the union of packages in their standard-library lockfiles. The lockfiles include dependencies for other targets and tests; a shipped binary uses a subset. New compiler releases require reviewing and refreshing this runtime notice snapshot.`, '',
+  'The runtime snapshots in `scripts/notices/runtime.json` and their exact cached notice texts are independent of the local compiler used to regenerate this document. They contain no copied HTML documentation.');
+for (const entry of runtimeReleases) {
+  parts.push('', `### Rust ${entry.version}`, '', `[Standard-library source](${entry.source}); [upstream lockfile](${entry.lockSource}); [upstream copyright metadata](${entry.annotationsSource}).`, '',
+    `Upstream standard-library Cargo.lock SHA-256: \`${entry.lockSha256}\`.`, '');
+  for (const text of entry.notices) parts.push(`- [${text.name}](#notice-${text.digest.slice(0, 16)}) — [notice source](${text.source})`);
+  parts.push('', 'In-tree attributions from the upstream copyright metadata:', '');
+  for (const item of entry.inTreeAttributions) {
+    parts.push(`- \`${item.path}\` — \`${item.spdx}\`; ${item.copyright.join('; ')}.`);
+  }
+  parts.push('', `Standard-library locked packages: ${entry.packages.map((key) => `\`${key}\``).join(', ')}.`);
+}
+parts.push('', '### Standard-library dependency notices');
+for (const entry of runtimePackages) {
+  parts.push('', `#### ${entry.name} ${entry.version}`, '', `Declared license: \`${entry.license}\`. [Unmodified source archive](${entry.source}).`, '',
+    `Source archive SHA-256 from the upstream lockfile: \`${entry.checksum}\`.`, '');
+  for (const text of entry.notices) parts.push(`- [${text.name}](#notice-${text.digest.slice(0, 16)}) — [notice source](${text.source})`);
+}
+parts.push('', '## Full license and attribution texts');
+for (const [digest, text] of [...texts].sort(([a], [b]) => compare(a, b))) {
+  const fence = '`'.repeat(Math.max(3, ...[...text.matchAll(/`+/g)].map((match) => match[0].length + 1)));
+  parts.push('', `<a id="notice-${digest.slice(0, 16)}"></a>`, '', `### Notice ${digest.slice(0, 16)}`, '', `${fence}text`, text.replace(/\n$/, ''), fence);
+}
+const generated = parts.join('\n') + '\n';
+if (check) {
+  if (!existsSync(output) || read(output) !== generated) throw new Error('THIRD_PARTY_NOTICES.md is stale. Run npm run notices:generate and commit the updated file.');
+  console.log(`Third-party notices match ${records.length} locked Rust packages and Cheerio 1.2.0.`);
+} else {
+  writeFileSync(output, generated);
+  console.log(`Generated THIRD_PARTY_NOTICES.md for ${records.length} locked Rust packages and Cheerio 1.2.0.`);
+}

package/scripts/notices/README.md

@@ -0,0 +1,13 @@
+# License notice inputs
+
+`npm run notices:generate` reads the full, locked Cargo dependency graph and copies license, notice, copyright, and attribution files from Cargo's local crate sources. Run `cargo fetch --locked` first on a fresh checkout. `npm run notices:check` compares the generated artifact without changing it. Neither command compiles code or changes the lockfile.
+
+Some published crates omit their repository-level license files. `sources.json` records the exact package versions, primary upstream source URLs, SHA-256 checksums, and cached text used for those exceptions. Napi and html5ever repository commits come from each published crate's `.cargo_vcs_info.json`. The Neon and Xray MIT notices preserve origins credited in the upstream napi README files. A dependency update must review these version-specific exceptions; stale entries or missing notices fail generation.
+
+For `fxhash` and `mac`, the published source declares an Apache-2.0 alternative without shipping the full license. Their original source/README notice is retained together with the standard Apache-2.0 text published in the locked `bitflags` crate. `selectors` ships its MPL-2.0 source notice without the full license; the identical license terms are reproduced from the locked `cssparser` crate. The generator also includes nested license files, including the Unicode notice in `regex-syntax`.
+
+Cached texts are upstream legal notices, including original public author and copyright attributions. Preserve those attributions when refreshing the cache. The generated artifact intentionally contains no local registry paths, timestamps, or machine identifiers.
+
+`runtime.json` separately records reviewed standard-library notices for Rust 1.96.1, 1.97.1, and 1.99.0, the releases used for the existing native builds. Their original `COPYRIGHT`, `LICENSE-MIT`, `LICENSE-APACHE`, `library/compiler-builtins/LICENSE.txt`, `license-metadata.json`, and `library/Cargo.lock` were obtained from the corresponding upstream release tags. Only standard-library in-tree attributions are retained from the copyright metadata. Published dependency source archives were checked against those lockfile checksums before retaining their legal notices. The union includes other targets and test dependencies so platform-specific subsets remain covered. Identical legal texts are cached once as `runtime-<digest>.txt`; no HTML documentation or Rust implementation sources are copied here. The check command rejects a compiler release that has no reviewed runtime notice snapshot.
+
+To review another compiler release, obtain those same small upstream metadata/license files, collect each external standard-library package's original notices from its checksum-verified archive, and update `runtime.json` plus the checksum/provenance entries in `sources.json`. Packages that omit standalone licenses use their pinned upstream repository notices. `r-efi` and `r-efi-alloc` offer an Apache-2.0 alternative; the cache preserves their original AUTHORS and licensing statements together with that complete license text. Regenerate the artifact and review the changed notices before shipping binaries built with the new compiler.

package/scripts/notices/cheerio-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 The Cheerio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/scripts/notices/html5ever-AUTHORS.txt

@@ -0,0 +1,20 @@
+This software was written by the following people:
+
+Adam Roben <adam@roben.org>
+Akos Kiss <akiss@inf.u-szeged.hu>
+Wojciech "Zarazek" Wiśniewski <balagane@op.pl>
+Chris Paris <cap@chrisparis.org>
+Clark Gaebel <cgaebel@mozilla.com>
+Daniel Fath <daniel.fath7@gmail.com>
+Huon Wilson <dbau.pp+github@gmail.com>
+glennw <glennw@users.noreply.github.com>
+Josh Matthews <josh@joshmatthews.net>
+György Andrasek <jurily@gmail.com>
+Keegan McAllister <kmcallister@mozilla.com>
+Eunchong Yu <kroisse@gmail.com>
+Manish Goregaokar <manishsmail@gmail.com>
+Chris Morgan <me@chrismorgan.info>
+Mátyás Mustoha <mmatyas@inf.u-szeged.hu>
+Patrick Walton <pcwalton@mimiga.net>
+Renato Zannon <renato@rrsz.com.br>
+Simon Sapin <simon.sapin@exyr.org>

package/scripts/notices/html5ever-COPYRIGHT.txt

@@ -0,0 +1,8 @@
+This project is Copyright 2014-2017 , The html5ever Project Developers (given in
+the file AUTHORS).
+
+Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+http://www.apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
+http://opensource.org/licenses/MIT>, at your option. All files in the project
+carrying such notice may not be copied, modified, or distributed except
+according to those terms.