From 3ebe97e033a10845549185cf4626ffb98d66f146 Mon Sep 17 00:00:00 2001 From: "shumeiko.it" Date: Sun, 1 Nov 2026 00:30:06 +0100 Subject: [PATCH] build: add a license gate for shipped npm packages and Rust crates (P2.3) scripts/check-licenses.mjs (npm run check:licenses) reads the production dependency closures of the sidecar (@waggle/server minus the packages stage-sidecar-deps.mjs never ships) and the web UI (apps/web) from package-lock.json and fails on GPL, AGPL, SSPL, missing and unknown licenses. It allows permissive licenses plus MPL-2.0 and lists named exceptions with reasons; LGPL libvips and node-webpmux, the OFL fonts and the unlicensed buffers package are marked as pending the licensing review. app/src-tauri/deny.toml applies the same allowlist to the Tauri crates with cargo-deny; the npm check fails when the two lists drift apart. A new CI job runs both, with cargo-deny 0.18.3 installed and cached in CI. scripts/license-inventory.mjs holds the shared closure logic. --- .github/workflows/ci.yml | 32 ++++ app/src-tauri/deny.toml | 38 +++++ package.json | 1 + scripts/check-licenses.mjs | 287 +++++++++++++++++++++++++++++++ scripts/check-licenses.test.ts | 58 +++++++ scripts/license-inventory.mjs | 304 +++++++++++++++++++++++++++++++++ 6 files changed, 720 insertions(+) create mode 100644 app/src-tauri/deny.toml create mode 100644 scripts/check-licenses.mjs create mode 100644 scripts/check-licenses.test.ts create mode 100644 scripts/license-inventory.mjs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2a4038d..0aff43c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -91,6 +91,38 @@ jobs: run: npm audit --audit-level=high continue-on-error: true + # License gate (P2.3). The npm check reads the shipped closures from + # package-lock.json, so it needs no install. cargo-deny checks the crates of + # the desktop shell against app/src-tauri/deny.toml; it is pinned, cached, + # and fetches the crates itself. + licenses: + runs-on: ubuntu-latest + env: + CARGO_DENY_VERSION: 0.18.3 + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 22.23.2 + + - name: Licenses — shipped npm packages + run: npm run check:licenses + + - name: Cache cargo-deny + id: cargo-deny-cache + uses: actions/cache@v4 + with: + path: ~/.cargo/bin/cargo-deny + key: ${{ runner.os }}-cargo-deny-${{ env.CARGO_DENY_VERSION }} + + - name: Install cargo-deny + if: steps.cargo-deny-cache.outputs.cache-hit != 'true' + run: cargo install cargo-deny --locked --version "$CARGO_DENY_VERSION" + + - name: Licenses — Rust crates (cargo-deny) + run: cargo deny --manifest-path app/src-tauri/Cargo.toml check licenses + # ADVISORY / NON-BLOCKING. `continue-on-error: true` means a red e2e run does # NOT block merges — by design. These specs are broad product/audit journeys # (full-product-audit, power-user-stress, competitive-benchmarks, …) that are diff --git a/app/src-tauri/deny.toml b/app/src-tauri/deny.toml new file mode 100644 index 0000000..86c4f73 --- /dev/null +++ b/app/src-tauri/deny.toml @@ -0,0 +1,38 @@ +# cargo-deny license gate for the desktop shell. +# +# cargo deny --manifest-path app/src-tauri/Cargo.toml check licenses +# +# Same policy as scripts/check-licenses.mjs for the npm packages: the allow +# list below must match ALLOWED_LICENSES there (that script fails when they +# differ). Crates that need anything else get a named entry in `exceptions` +# with the reason in a comment. + +[graph] +# The v1 desktop platforms (docs/oss/adr/README.md). +targets = [ + "x86_64-pc-windows-msvc", + "aarch64-apple-darwin", + "x86_64-apple-darwin", + "x86_64-unknown-linux-gnu", +] + +[licenses] +allow = [ + "0BSD", + "Apache-2.0", + "BSD-2-Clause", + "BSD-3-Clause", + "BlueOak-1.0.0", + "CC0-1.0", + "ISC", + "MIT", + "MPL-2.0", + "Python-2.0", + "Unicode-3.0", + "Unlicense", + "Zlib", +] +confidence-threshold = 0.93 +# The allow list is shared with the npm check, so not every entry is used here. +unused-allowed-license = "allow" +exceptions = [] diff --git a/package.json b/package.json index 260b25c..3077e9c 100644 --- a/package.json +++ b/package.json @@ -27,6 +27,7 @@ "build:www": "npm run build -w apps/www", "lint": "eslint .", "check:deps": "node scripts/check-workspace-deps.mjs", + "check:licenses": "node scripts/check-licenses.mjs", "lint:no-invalid-snapshots": "node scripts/check-no-invalid-snapshots.mjs", "ux:contrast": "node scripts/ux-gates/contrast-tokens.mjs", "ux:color-guard": "node scripts/ux-gates/text-color-guard.mjs", diff --git a/scripts/check-licenses.mjs b/scripts/check-licenses.mjs new file mode 100644 index 0000000..24f1284 --- /dev/null +++ b/scripts/check-licenses.mjs @@ -0,0 +1,287 @@ +#!/usr/bin/env node +/** + * License gate for the npm packages that ship in the community edition. + * + * Reads the production dependency closures of the sidecar and the web UI from + * package-lock.json (see scripts/license-inventory.mjs), so it needs no + * `npm install`. Every package must declare a license expression that the + * allowlist satisfies, or match a named exception below. GPL, AGPL, SSPL, + * missing and unknown licenses fail. + * + * The Rust crates of the desktop shell are checked by cargo-deny with the same + * allowlist (app/src-tauri/deny.toml); this script fails when the two lists + * drift apart. Node.js and the npm CLI that bundle-node.mjs downloads are not + * in package-lock.json and are not checked here (THIRD_PARTY_NOTICES.md lists them). + * + * Usage: node scripts/check-licenses.mjs [--verbose] + */ +import fs from 'node:fs'; +import path from 'node:path'; +import { pathToFileURL } from 'node:url'; +import { ROOT, npmArtifacts, npmClosure, readLockfilePackages, uniqueVersions } from './license-inventory.mjs'; + +/** SPDX identifiers that may ship in an MIT-licensed distribution. Keep in sync with app/src-tauri/deny.toml. */ +export const ALLOWED_LICENSES = [ + '0BSD', + 'Apache-2.0', + 'BSD-2-Clause', + 'BSD-3-Clause', + 'BlueOak-1.0.0', + 'CC0-1.0', + 'ISC', + 'MIT', + 'MPL-2.0', + 'Python-2.0', + 'Unicode-3.0', + 'Unlicense', + 'Zlib', +]; + +/** + * Named exceptions. An exception applies only while the package still declares + * exactly `license` in package-lock.json (null: no license declared), so a + * license change needs a new review. `pending` marks exceptions that wait for + * the licensing review (pending decision Q6); the gate prints them on every run. + */ +export const EXCEPTIONS = [ + { + packages: ['@img/sharp-libvips-*'], + license: 'LGPL-3.0-or-later', + pending: true, + reason: 'Prebuilt libvips for sharp, required by @huggingface/transformers (embeddings). ' + + 'Shipped unmodified as a separate shared library in resources/node_modules and loaded ' + + 'at runtime; LGPL obligations are listed in THIRD_PARTY_NOTICES.md.', + }, + { + packages: ['@img/sharp-win32-x64'], + license: 'Apache-2.0 AND LGPL-3.0-or-later', + pending: true, + reason: 'sharp binding for Windows; the package carries the libvips DLLs (LGPL-3.0-or-later). ' + + 'Shipped unmodified in resources/node_modules, same terms as @img/sharp-libvips-*.', + }, + { + packages: ['node-webpmux'], + license: 'LGPL-3.0-or-later', + pending: true, + reason: 'Required dependency of whatsapp-web.js (ADR-0005). Kept external to service.js and ' + + 'shipped unmodified as a separate package in resources/node_modules.', + }, + { + packages: ['@fontsource-variable/hanken-grotesk', '@fontsource-variable/jetbrains-mono'], + license: 'OFL-1.1', + pending: true, + reason: 'Fonts bundled into the web UI. OFL-1.1 allows bundling with software if the ' + + 'license ships with the fonts and the fonts are not sold on their own.', + }, + { + packages: ['buffers'], + license: null, + pending: true, + reason: 'buffers 0.1.1 (exceljs > unzipper > binary > buffers) has no license field, file or ' + + 'README statement. Unlicensed code; needs a decision or a dependency change.', + }, + { + packages: ['posthog-js'], + license: 'SEE LICENSE IN LICENSE', + reason: 'The LICENSE file is Apache-2.0, with MIT for files taken from Sentry, Metro and Expo.', + }, + { + packages: ['duck'], + license: 'BSD', + reason: 'The LICENSE file is the BSD-2-Clause text.', + }, + { + packages: ['chainsaw', 'traverse'], + license: 'MIT/X11', + reason: '"MIT/X11" is the MIT license (traverse ships the MIT text; chainsaw has no license file).', + }, + { + packages: ['png-js'], + license: null, + reason: 'No license field; the LICENSE file is the MIT text.', + }, + { + packages: ['async'], + license: null, + reason: 'async 0.2.10 (whatsapp-web.js > fluent-ffmpeg > async) declares MIT in the legacy ' + + '"licenses" field and ships the MIT text.', + }, +]; + +const COPYLEFT = /^(?:A?GPL|LGPL|SSPL|EUPL|OSL|CC-BY-SA|CPAL)/i; +const LICENSE_ID = /^(?:[A-Za-z0-9][A-Za-z0-9.+-]*|LicenseRef-[A-Za-z0-9.-]+)$/; + +/** Parse an SPDX license expression. Throws on anything that is not one. */ +export function parseLicenseExpression(expression) { + const tokens = expression.replace(/[()]/g, ' $& ').trim().split(/\s+/).filter(Boolean); + let position = 0; + const peek = () => tokens[position]; + const isOperator = (token, operator) => token !== undefined && token.toUpperCase() === operator; + + function parseAtom() { + const token = tokens[position++]; + if (token === '(') { + const inner = parseOr(); + if (tokens[position++] !== ')') throw new Error(`missing ")" in "${expression}"`); + return inner; + } + if (token === undefined || !LICENSE_ID.test(token) || ['AND', 'OR', 'WITH'].includes(token.toUpperCase())) { + throw new Error(`"${expression}" is not an SPDX expression`); + } + if (isOperator(peek(), 'WITH')) { + position++; + const exception = tokens[position++]; + if (!exception || !LICENSE_ID.test(exception)) throw new Error(`bad WITH clause in "${expression}"`); + return { license: token, exception }; + } + return { license: token }; + } + function parseAnd() { + let left = parseAtom(); + while (isOperator(peek(), 'AND')) { + position++; + left = { and: [left, parseAtom()] }; + } + return left; + } + function parseOr() { + let left = parseAnd(); + while (isOperator(peek(), 'OR')) { + position++; + left = { or: [left, parseAnd()] }; + } + return left; + } + + const tree = parseOr(); + if (position !== tokens.length) throw new Error(`"${expression}" is not an SPDX expression`); + return tree; +} + +function satisfied(node, allowed) { + if (node.or) return node.or.some((child) => satisfied(child, allowed)); + if (node.and) return node.and.every((child) => satisfied(child, allowed)); + // An exception only adds permissions, so an allowed license stays allowed with it. + return allowed.has(node.license) || allowed.has(`${node.license} WITH ${node.exception}`); +} + +function leaves(node) { + if (node.or) return node.or.flatMap(leaves); + if (node.and) return node.and.flatMap(leaves); + return [node.license]; +} + +/** + * Classify one declared license. + * Returns { status: 'allowed' | 'missing' | 'invalid' | 'denied', copyleft, alternatives }. + */ +export function evaluateLicense(expression, allowed = new Set(ALLOWED_LICENSES)) { + if (expression === null || expression === undefined || expression.trim() === '') { + return { status: 'missing', copyleft: false, alternatives: [] }; + } + let tree; + try { + tree = parseLicenseExpression(expression); + } catch { + return { status: 'invalid', copyleft: false, alternatives: [] }; + } + const ids = leaves(tree); + const copyleft = ids.some((id) => COPYLEFT.test(id)); + if (satisfied(tree, allowed)) { + // Dual-licensed packages pass on their permissive option; report the rest. + return { status: 'allowed', copyleft, alternatives: ids.filter((id) => !allowed.has(id)) }; + } + return { status: 'denied', copyleft, alternatives: [] }; +} + +function matchesPattern(name, pattern) { + return pattern.endsWith('*') ? name.startsWith(pattern.slice(0, -1)) : name === pattern; +} + +export function findException(pkg, exceptions = EXCEPTIONS) { + return exceptions.find( + (exception) => exception.license === pkg.license + && exception.packages.some((pattern) => matchesPattern(pkg.name, pattern)), + ); +} + +/** The `allow` list of the [licenses] table in a cargo-deny config. */ +export function readDenyAllowList(denyToml) { + const section = /^\[licenses\]\s*$([\s\S]*?)(?=^\[)/m.exec(`${denyToml}\n[`); + const allow = section && /^allow\s*=\s*\[([\s\S]*?)\]/m.exec(section[1]); + if (!allow) throw new Error('app/src-tauri/deny.toml has no [licenses] allow list'); + return [...allow[1].replace(/#.*$/gm, '').matchAll(/"([^"]+)"/g)].map((match) => match[1]); +} + +function main() { + const verbose = process.argv.includes('--verbose'); + const packages = readLockfilePackages(); + const failures = []; + const usedExceptions = new Map(); + const dualLicensed = new Map(); + + for (const artifact of npmArtifacts()) { + const { packages: closure, unresolved } = npmClosure(packages, artifact); + for (const missing of unresolved) { + failures.push(`${artifact.title}: required dependency is not in package-lock.json: ${missing}`); + } + const shipped = uniqueVersions(closure.values()); + for (const pkg of shipped) { + const result = evaluateLicense(pkg.license); + const id = `${pkg.name}@${pkg.version}`; + if (result.status === 'allowed') { + if (result.alternatives.length > 0) dualLicensed.set(id, pkg.license); + continue; + } + const exception = findException(pkg); + if (exception) { + if (!usedExceptions.has(exception)) usedExceptions.set(exception, new Set()); + usedExceptions.get(exception).add(`${id} (${artifact.title})`); + continue; + } + const label = { + missing: 'no license declared', + invalid: `not an SPDX expression: "${pkg.license}"`, + denied: `${pkg.license}${result.copyleft ? ' (copyleft)' : ''} is not on the allowlist`, + }[result.status]; + failures.push(`${artifact.title}: ${id}: ${label}\n path: ${pkg.via.join(' > ')}`); + } + if (verbose) console.log(`[check-licenses] ${artifact.title}: ${shipped.length} third-party packages`); + } + + const denyPath = path.join(ROOT, 'app', 'src-tauri', 'deny.toml'); + const denyAllow = readDenyAllowList(fs.readFileSync(denyPath, 'utf8')); + const missingInDeny = ALLOWED_LICENSES.filter((id) => !denyAllow.includes(id)); + const extraInDeny = denyAllow.filter((id) => !ALLOWED_LICENSES.includes(id)); + if (missingInDeny.length > 0 || extraInDeny.length > 0) { + failures.push( + 'app/src-tauri/deny.toml allow list differs from ALLOWED_LICENSES' + + `${missingInDeny.length ? `; missing: ${missingInDeny.join(', ')}` : ''}` + + `${extraInDeny.length ? `; extra: ${extraInDeny.join(', ')}` : ''}`, + ); + } + + for (const [exception, hits] of usedExceptions) { + if (!exception.pending && !verbose) continue; + const tag = exception.pending ? 'pending licensing review' : 'exception'; + console.warn(`[check-licenses] ${tag}: ${exception.license ?? 'no license'}: ${[...hits].sort().join(', ')}`); + console.warn(` ${exception.reason}`); + } + for (const exception of EXCEPTIONS.filter((entry) => !usedExceptions.has(entry))) { + console.warn(`[check-licenses] unused exception for ${exception.packages.join(', ')}; remove it`); + } + if (verbose) { + for (const [id, license] of [...dualLicensed].sort()) { + console.log(`[check-licenses] dual-licensed, used under the allowed option: ${id} (${license})`); + } + } + + if (failures.length > 0) { + console.error(`[check-licenses] FAILED: ${failures.length} problem(s)`); + for (const failure of failures) console.error(` - ${failure}`); + process.exit(1); + } + console.log('[check-licenses] OK: every shipped npm package is allowed or a named exception'); +} + +if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) main(); diff --git a/scripts/check-licenses.test.ts b/scripts/check-licenses.test.ts new file mode 100644 index 0000000..7cc6c94 --- /dev/null +++ b/scripts/check-licenses.test.ts @@ -0,0 +1,58 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import { describe, expect, it } from 'vitest'; +import { + ALLOWED_LICENSES, + evaluateLicense, + findException, + readDenyAllowList, +} from './check-licenses.mjs'; + +describe('evaluateLicense', () => { + it('allows listed licenses and expressions the allowlist satisfies', () => { + expect(evaluateLicense('MIT').status).toBe('allowed'); + expect(evaluateLicense('(MIT AND Zlib)').status).toBe('allowed'); + expect(evaluateLicense('(MIT OR Apache-2.0) AND Unicode-3.0').status).toBe('allowed'); + expect(evaluateLicense('Apache-2.0 WITH LLVM-exception').status).toBe('allowed'); + }); + + it('passes dual-licensed packages on their permissive option and reports the other one', () => { + const result = evaluateLicense('(MIT OR GPL-3.0-or-later)'); + expect(result.status).toBe('allowed'); + expect(result.alternatives).toEqual(['GPL-3.0-or-later']); + }); + + it('denies copyleft licenses, alone or in a conjunction', () => { + for (const expression of ['GPL-3.0-only', 'AGPL-3.0-or-later', 'SSPL-1.0', 'MIT AND LGPL-3.0-or-later']) { + const result = evaluateLicense(expression); + expect(result.status, expression).toBe('denied'); + expect(result.copyleft, expression).toBe(true); + } + expect(evaluateLicense('GPL-2.0-only WITH Classpath-exception-2.0').status).toBe('denied'); + }); + + it('flags missing and non-SPDX licenses', () => { + expect(evaluateLicense(null).status).toBe('missing'); + expect(evaluateLicense(' ').status).toBe('missing'); + for (const expression of ['SEE LICENSE IN LICENSE', 'MIT/X11', 'Apache 2.0', '(MIT', 'MIT OR']) { + expect(evaluateLicense(expression).status, expression).toBe('invalid'); + } + expect(evaluateLicense('BSD').status).toBe('denied'); + }); +}); + +describe('findException', () => { + it('matches by name pattern and the exact declared license', () => { + expect(findException({ name: '@img/sharp-libvips-linux-x64', license: 'LGPL-3.0-or-later' })).toBeDefined(); + expect(findException({ name: '@img/sharp-libvips-linux-x64', license: 'GPL-3.0-only' })).toBeUndefined(); + expect(findException({ name: 'async', license: null })).toBeDefined(); + expect(findException({ name: 'async', license: 'GPL-3.0-only' })).toBeUndefined(); + }); +}); + +describe('deny.toml', () => { + it('uses the same allowlist as the npm check', () => { + const denyToml = fs.readFileSync(path.join(__dirname, '..', 'app', 'src-tauri', 'deny.toml'), 'utf8'); + expect([...readDenyAllowList(denyToml)].sort()).toEqual([...ALLOWED_LICENSES].sort()); + }); +}); diff --git a/scripts/license-inventory.mjs b/scripts/license-inventory.mjs new file mode 100644 index 0000000..392b0c4 --- /dev/null +++ b/scripts/license-inventory.mjs @@ -0,0 +1,304 @@ +/** + * Inventory of the third-party code that ships in the community edition. + * + * Shared by scripts/generate-third-party-notices.mjs and scripts/check-licenses.mjs. + * Works offline: npm packages come from package-lock.json, Rust crates from + * `cargo metadata --offline`. + * + * What ships: + * - Sidecar: build-sidecar.mjs bundles @waggle/server into + * app/src-tauri/resources/service.js, and stage-sidecar-deps.mjs copies the + * packages it keeps external into resources/node_modules. Both follow the + * production dependencies of @waggle/server, so the sidecar is modelled as + * that closure minus the packages stage-sidecar-deps.mjs never ships (SKIP). + * - Web UI: Vite bundles apps/web and its production dependencies. + * - Desktop shell: the Rust crates of app/src-tauri, following normal + * dependencies (proc-macro crates included); build and dev dependencies do + * not end up in the binary and are left out. + * + * The npm closures follow `dependencies`, `optionalDependencies`, required + * `peerDependencies` and the vendored `file:` devDependencies of workspace + * packages, and keep platform packages for the v1 platforms only. + * They are a superset of what the bundlers keep: modules that tree-shaking + * drops are still listed. + */ +import fs from 'node:fs'; +import path from 'node:path'; +import { execFileSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; + +export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); + +/** v1 platforms (docs/oss/adr/README.md): Windows x64, macOS arm64 and x64, Linux x64. */ +export const NPM_TARGETS = [ + { os: 'win32', cpu: 'x64' }, + { os: 'darwin', cpu: 'arm64' }, + { os: 'darwin', cpu: 'x64' }, + { os: 'linux', cpu: 'x64' }, +]; +export const RUST_TARGETS = [ + 'x86_64-pc-windows-msvc', + 'aarch64-apple-darwin', + 'x86_64-apple-darwin', + 'x86_64-unknown-linux-gnu', +]; + +const FIRST_PARTY_KEY = /^(?:apps|packages)\/[^/]+$/; +const LICENSE_FILE = /^(?:(?:mit|apache|bsd)[-_.])?(?:licen[cs]e|copying|notice|copyright|unlicense)(?:$|[-_.])/i; + +/** Packages that stage-sidecar-deps.mjs never ships, read from its SKIP set. */ +export function sidecarSkippedPackages(root = ROOT) { + const source = fs.readFileSync(path.join(root, 'scripts', 'stage-sidecar-deps.mjs'), 'utf8'); + const match = /const SKIP = new Set\(\[([^\]]*)\]\)/.exec(source); + if (!match) throw new Error('Could not find the SKIP set in scripts/stage-sidecar-deps.mjs'); + return new Set([...match[1].replace(/\/\/.*$/gm, '').matchAll(/'([^']+)'/g)].map((m) => m[1])); +} + +/** The npm-based artifacts, each rooted at a workspace package. */ +export function npmArtifacts(root = ROOT) { + return [ + { + id: 'sidecar', + title: 'Sidecar', + workspace: 'packages/server', + ships: 'app/src-tauri/resources/service.js and resources/node_modules', + skip: sidecarSkippedPackages(root), + }, + { + id: 'web', + title: 'Web UI', + workspace: 'apps/web', + ships: 'the apps/web bundle that the sidecar and the desktop shell serve', + skip: new Set(), + }, + ]; +} + +export function readLockfilePackages(root = ROOT) { + const lock = JSON.parse(fs.readFileSync(path.join(root, 'package-lock.json'), 'utf8')); + if (!lock.packages || lock.lockfileVersion < 2) { + throw new Error('package-lock.json must be lockfileVersion 2 or later'); + } + return lock.packages; +} + +function matchesPlatformList(list, value) { + if (!Array.isArray(list) || list.length === 0) return true; + if (list.includes(`!${value}`)) return false; + const positive = list.filter((entry) => !entry.startsWith('!')); + return positive.length === 0 || positive.includes(value); +} + +function installsOn(entry, target) { + return matchesPlatformList(entry.os, target.os) && matchesPlatformList(entry.cpu, target.cpu); +} + +/** True when an npm package installs on at least one v1 platform. */ +export function installsOnSupportedPlatform(entry) { + return NPM_TARGETS.some((target) => installsOn(entry, target)); +} + +function nameFromKey(key) { + const index = key.lastIndexOf('node_modules/'); + return index === -1 ? null : key.slice(index + 'node_modules/'.length); +} + +/** Resolve `name` from the package at `fromKey` the way Node walks node_modules. */ +function resolveKey(packages, fromKey, name) { + let dir = fromKey; + for (;;) { + const candidate = dir ? `${dir}/node_modules/${name}` : `node_modules/${name}`; + if (packages[candidate]) return candidate; + if (!dir) return null; + const parent = path.posix.dirname(dir); + dir = parent === '.' ? '' : parent; + } +} + +function runtimeDependencies(entry, firstParty) { + const deps = new Map(); + for (const name of Object.keys(entry.dependencies ?? {})) deps.set(name, false); + // Vendored packages (`file:` specs, e.g. vendor/pptxgenjs in @waggle/agent) are + // devDependencies so the npm package can stage its own copy, but the bundlers + // inline them from source. + if (firstParty) { + for (const [name, spec] of Object.entries(entry.devDependencies ?? {})) { + if (String(spec).startsWith('file:')) deps.set(name, false); + } + } + for (const name of Object.keys(entry.optionalDependencies ?? {})) deps.set(name, true); + const peerMeta = entry.peerDependenciesMeta ?? {}; + for (const name of Object.keys(entry.peerDependencies ?? {})) { + if (!peerMeta[name]?.optional && !deps.has(name)) deps.set(name, false); + } + return deps; +} + +/** + * Production dependency closure of one artifact. + * Returns third-party packages keyed by lockfile path, each with the shortest + * dependency path from the artifact's workspace package. + */ +export function npmClosure(packages, artifact) { + const rootEntry = packages[artifact.workspace]; + if (!rootEntry) throw new Error(`${artifact.workspace} is not in package-lock.json`); + const rootName = rootEntry.name ?? artifact.workspace; + const result = new Map(); + const unresolved = []; + const visited = new Set([artifact.workspace]); + const queue = [{ key: artifact.workspace, via: [rootName] }]; + + while (queue.length > 0) { + const { key, via } = queue.shift(); + for (const [depName, optional] of runtimeDependencies(packages[key], FIRST_PARTY_KEY.test(key))) { + if (artifact.skip.has(depName)) continue; + const found = resolveKey(packages, key, depName); + const target = found && packages[found].link ? packages[found].resolved : found; + const entry = target ? packages[target] : undefined; + if (!entry) { + if (!optional) unresolved.push(`${via.join(' > ')} > ${depName}`); + continue; + } + if (visited.has(target) || !installsOnSupportedPlatform(entry)) continue; + visited.add(target); + const name = entry.name ?? nameFromKey(target) ?? depName; + const chain = [...via, name]; + if (!FIRST_PARTY_KEY.test(target)) { + result.set(target, { + key: target, + name, + version: entry.version ?? '', + license: typeof entry.license === 'string' ? entry.license.trim() : null, + resolved: entry.resolved ?? null, + platformSpecific: !NPM_TARGETS.every((platform) => installsOn(entry, platform)), + os: entry.os ?? null, + cpu: entry.cpu ?? null, + via: chain, + }); + } + queue.push({ key: target, via: chain }); + } + } + return { packages: result, unresolved }; +} + +/** npm installs several copies of one version at different paths; keep each version once, sorted. */ +export function uniqueVersions(packages) { + const seen = new Map(); + for (const pkg of packages) { + const id = `${pkg.name}@${pkg.version}`; + if (!seen.has(id) || pkg.via.length < seen.get(id).via.length) seen.set(id, pkg); + } + return [...seen.values()].sort( + (a, b) => a.name.localeCompare(b.name) || a.version.localeCompare(b.version, undefined, { numeric: true }), + ); +} + +/** The package.json of an installed package, or null when it is not installed here. */ +export function readInstalledManifest(root, key) { + try { + return JSON.parse(fs.readFileSync(path.join(root, key, 'package.json'), 'utf8')); + } catch { + return null; + } +} + +/** License declared by an installed manifest, including the legacy object and array forms. */ +export function manifestLicense(manifest) { + if (!manifest) return null; + const { license, licenses } = manifest; + if (typeof license === 'string' && license.trim()) return license.trim(); + if (license && typeof license.type === 'string') return license.type; + if (Array.isArray(licenses) && licenses.length > 0) { + const types = licenses.map((entry) => (typeof entry === 'string' ? entry : entry?.type)).filter(Boolean); + if (types.length === 1) return types[0]; + if (types.length > 1) return `(${types.join(' OR ')})`; + } + return null; +} + +/** License and notice files at the top of a package or crate directory. */ +export function readLicenseFiles(dir, extraFiles = []) { + if (!dir || !fs.existsSync(dir)) return []; + const names = fs.readdirSync(dir, { withFileTypes: true }) + .filter((entry) => entry.isFile() && LICENSE_FILE.test(entry.name)) + .map((entry) => entry.name); + for (const extra of extraFiles) { + const relative = path.relative(dir, path.resolve(dir, extra)); + if (!names.includes(relative) && fs.existsSync(path.join(dir, relative))) names.push(relative); + } + return names.sort().map((file) => ({ + file, + text: fs.readFileSync(path.join(dir, file), 'utf8').replace(/\r\n?/g, '\n').trim(), + })); +} + +/** + * Rust crates linked into the desktop shell, per supported target. + * Targets whose crates are not in the local cargo cache cannot be resolved + * offline; they are returned in `unresolvedTargets` instead of failing. + */ +export function rustCrates(root = ROOT) { + const manifestPath = path.join(root, 'app', 'src-tauri', 'Cargo.toml'); + const crates = new Map(); + const unresolvedTargets = []; + for (const target of RUST_TARGETS) { + let metadata; + try { + metadata = JSON.parse(execFileSync( + 'cargo', + [ + 'metadata', '--format-version', '1', '--offline', '--locked', + '--filter-platform', target, '--manifest-path', manifestPath, + ], + { encoding: 'utf8', maxBuffer: 512 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] }, + )); + } catch (error) { + const detail = String(error.stderr || error.message).trim().split('\n')[0]; + unresolvedTargets.push({ target, reason: detail }); + continue; + } + const byId = new Map(metadata.packages.map((pkg) => [pkg.id, pkg])); + const nodes = new Map(metadata.resolve.nodes.map((node) => [node.id, node])); + const rootId = metadata.resolve.root; + const seen = new Set([rootId]); + const stack = [rootId]; + while (stack.length > 0) { + for (const dep of nodes.get(stack.pop()).deps) { + // Build and dev dependencies do not end up in the shipped binary. + if (!dep.dep_kinds.some((kind) => kind.kind === null)) continue; + if (seen.has(dep.pkg)) continue; + seen.add(dep.pkg); + stack.push(dep.pkg); + } + } + seen.delete(rootId); + for (const id of seen) { + const pkg = byId.get(id); + const key = `${pkg.name}@${pkg.version}`; + if (!crates.has(key)) { + crates.set(key, { + key, + name: pkg.name, + version: pkg.version, + license: pkg.license ?? null, + licenseFile: pkg.license_file ?? null, + repository: pkg.repository ?? null, + source: pkg.source ?? null, + dir: path.dirname(pkg.manifest_path), + targets: new Set(), + }); + } + crates.get(key).targets.add(target); + } + } + return { crates, unresolvedTargets }; +} + +/** The Node.js version that scripts/bundle-node.mjs ships with the desktop sidecar. */ +export function bundledNodeVersion(root = ROOT) { + const source = fs.readFileSync(path.join(root, 'scripts', 'bundle-node.mjs'), 'utf8'); + const match = /const DESKTOP_NODE_VERSION = '([^']+)'/.exec(source); + if (!match) throw new Error('Could not find DESKTOP_NODE_VERSION in scripts/bundle-node.mjs'); + return match[1]; +}