@companion-module/tools 3.1.0 → 3.2.0

package/dist/license/policy.js

@@ -0,0 +1,376 @@
+import { createRequire as _createRequire } from "module";
+const __require = _createRequire(import.meta.url);
+const parse = __require("spdx-expression-parse");
+import { correctedPackageLicense } from './inventory.js';
+export class LicensePolicyError extends Error {
+    issues;
+    constructor(issues) {
+        super(`License validation failed with ${issues.length} error${issues.length === 1 ? '' : 's'}.`);
+        this.issues = issues;
+        this.name = 'LicensePolicyError';
+    }
+}
+/** Permissive licenses which may be shipped under any of the supported project licenses */
+const PERMISSIVE_DEPENDENCY_LICENSES = [
+    'MIT',
+    'MIT-0',
+    'ISC',
+    'BSD-2-Clause',
+    'BSD-3-Clause',
+    '0BSD',
+    'CC0-1.0',
+    'Unlicense',
+    'BlueOak-1.0.0',
+    'Python-2.0',
+    'Zlib',
+    'BSL-1.0',
+    // Copyleft, but only over the font itself: section 2 permits bundling and redistributing the font with any
+    // software, and the reciprocity in sections 3 to 5 only ever reaches a modified version of the font
+    'OFL-1.1',
+    // Not an SPDX identifier, SPDX has none for a public domain dedication. Recording it as CC0-1.0 or Unlicense
+    // would name a specific legal instrument the package never used, and public domain carries no obligation at all.
+    'Public-Domain',
+];
+const GPL2_DEPENDENCY_LICENSES = [
+    'GPL-2.0-only',
+    'GPL-2.0-or-later',
+    'GPL-2.0', // Deprecated SPDX id for GPL-2.0-only, still widely declared on npm
+];
+const GPL3_DEPENDENCY_LICENSES = [
+    'GPL-3.0-only',
+    'GPL-3.0-or-later',
+    'GPL-3.0', // Deprecated SPDX id for GPL-3.0-only, still widely declared on npm
+];
+// The LGPL families split by which GPL version their relicensing clause can reach. LGPL-2.x section 3 offers "version
+// 2 of the ordinary GPL or any later version", so it suits either GPL policy, while LGPL-3.0 only reaches GPL-3.0.
+const LGPL2_DEPENDENCY_LICENSES = [
+    'LGPL-2.0-only',
+    'LGPL-2.0-or-later',
+    'LGPL-2.0', // Deprecated SPDX id for LGPL-2.0-only, still widely declared on npm
+    'LGPL-2.1-only',
+    'LGPL-2.1-or-later',
+    'LGPL-2.1', // Deprecated SPDX id for LGPL-2.1-only
+];
+const LGPL3_DEPENDENCY_LICENSES = [
+    'LGPL-3.0-only',
+    'LGPL-3.0-or-later',
+    'LGPL-3.0', // Deprecated SPDX id for LGPL-3.0-only
+];
+// Each policy pins the combined work to a single GPL version, so no mix of allowed dependencies can end up
+// unlicensable. Offering GPL-2.0-or-later would break that, a GPL-2.0-only and a GPL-3.0-only dependency could then
+// both be accepted while no version satisfies both.
+const PROJECT_LICENSE_POLICIES = {
+    MIT: {
+        allowedDependencyLicenses: new Set([
+            ...PERMISSIVE_DEPENDENCY_LICENSES,
+            'Apache-2.0',
+            'CC-BY-3.0',
+            'CC-BY-4.0',
+            'MPL-2.0', // File level copyleft, allows bundling if source is available (links bundled LICENSE)
+        ]),
+        // An MIT bundle cannot offer the relinking static linking would require, but the LGPL is written to let a
+        // work under any terms use the library as a separate one, so every LGPL version is fine as an external
+        externalOnlyLicenses: new Set([...LGPL2_DEPENDENCY_LICENSES, ...LGPL3_DEPENDENCY_LICENSES]),
+    },
+    // Apache-2.0 and the CC-BY licenses are deliberately absent, they cannot be combined with GPL-2.0-only
+    'GPL-2.0-only': {
+        allowedDependencyLicenses: new Set([
+            ...PERMISSIVE_DEPENDENCY_LICENSES,
+            ...GPL2_DEPENDENCY_LICENSES,
+            // Section 3 relicenses these to GPL-2.0, so the bundle stays distributable under this policy
+            ...LGPL2_DEPENDENCY_LICENSES,
+            'MPL-2.0',
+        ]),
+        // LGPL-3.0 is absent entirely rather than external only. It is GPL-3.0 plus permissions, so it carries terms
+        // GPL-2.0 section 6 forbids adding, and linking still forms a combined work whichever way it is shipped.
+        externalOnlyLicenses: new Set(),
+    },
+    'GPL-3.0-only': {
+        allowedDependencyLicenses: new Set([
+            ...PERMISSIVE_DEPENDENCY_LICENSES,
+            ...GPL3_DEPENDENCY_LICENSES,
+            'GPL-2.0-or-later', // GPL-2.0-only is absent, only the "or later" form can be taken to GPL-3.0
+            // Both families reach GPL-3.0, the 2.x one through its "or any later version" offer
+            ...LGPL2_DEPENDENCY_LICENSES,
+            ...LGPL3_DEPENDENCY_LICENSES,
+            'Apache-2.0',
+            'MPL-2.0',
+        ]),
+        externalOnlyLicenses: new Set(),
+    },
+};
+export const SUPPORTED_PROJECT_LICENSES = Object.keys(PROJECT_LICENSE_POLICIES);
+/** Policy applied to dependencies while the project itself has no usable license declaration */
+const FALLBACK_PROJECT_LICENSE = 'MIT';
+/** Suggested to authors, as the one which can use the most of npm and be reused most freely */
+const RECOMMENDED_PROJECT_LICENSE = 'MIT';
+function isProjectLicense(declaration) {
+    return SUPPORTED_PROJECT_LICENSES.includes(declaration);
+}
+function orList(items) {
+    const remaining = [...items];
+    const last = remaining.pop();
+    return remaining.length ? `${remaining.join(', ')} or ${last}` : `${last}`;
+}
+function supportedProjectLicenseAdvice() {
+    const alternatives = SUPPORTED_PROJECT_LICENSES.filter((license) => license !== RECOMMENDED_PROJECT_LICENSE);
+    return `We recommend ${RECOMMENDED_PROJECT_LICENSE} for the widest compatibility, but also accept ${orList(alternatives)} when necessary.`;
+}
+function evaluate(node, allowedLicenses) {
+    if ('license' in node) {
+        const license = node.plus ? `${node.license}-or-later` : node.license; // "GPL-2.0+" is deprecated for "GPL-2.0-or-later"
+        return {
+            allowed: !node.exception && allowedLicenses.has(license),
+            incompatibleAnd: false,
+        };
+    }
+    const left = evaluate(node.left, allowedLicenses);
+    const right = evaluate(node.right, allowedLicenses);
+    if (node.conjunction === 'or') {
+        const allowed = left.allowed || right.allowed;
+        return {
+            allowed,
+            incompatibleAnd: !allowed && (left.incompatibleAnd || right.incompatibleAnd),
+        };
+    }
+    return {
+        allowed: left.allowed && right.allowed,
+        incompatibleAnd: left.allowed !== right.allowed || left.incompatibleAnd || right.incompatibleAnd,
+    };
+}
+/**
+ * spdx-expression-parse rejects the whole expression when any leaf is not a valid SPDX identifier, so a legacy
+ * declaration like "(MIT OR GPL)" never reaches the OR logic at all. Re-read those keeping only the boolean
+ * structure, so an unrecognised identifier becomes a license which is simply never allowed. OR then still offers a
+ * real choice, and AND still requires every branch, so nothing unknown can be accepted on its own.
+ */
+function parseLenient(declaration) {
+    const tokens = declaration.match(/\(|\)|[^\s()]+/g);
+    if (!tokens)
+        return undefined;
+    let index = 0;
+    const keyword = (token, word) => token !== undefined && token.toUpperCase() === word;
+    function parseExpression() {
+        let node = parseTerm();
+        if (!node)
+            return undefined;
+        while (keyword(tokens[index], 'OR')) {
+            index++;
+            const right = parseTerm();
+            if (!right)
+                return undefined;
+            node = { left: node, conjunction: 'or', right };
+        }
+        return node;
+    }
+    function parseTerm() {
+        let node = parseFactor();
+        if (!node)
+            return undefined;
+        while (keyword(tokens[index], 'AND')) {
+            index++;
+            const right = parseFactor();
+            if (!right)
+                return undefined;
+            node = { left: node, conjunction: 'and', right };
+        }
+        return node;
+    }
+    function parseFactor() {
+        const token = tokens[index];
+        if (token === undefined || token === ')')
+            return undefined;
+        if (token === '(') {
+            index++;
+            const node = parseExpression();
+            if (!node || tokens[index] !== ')')
+                return undefined;
+            index++;
+            return node;
+        }
+        if (keyword(token, 'AND') || keyword(token, 'OR') || keyword(token, 'WITH'))
+            return undefined;
+        index++;
+        const plus = token.endsWith('+');
+        const node = { license: plus ? token.slice(0, -1) : token };
+        if (plus)
+            node.plus = true;
+        if (keyword(tokens[index], 'WITH')) {
+            index++;
+            if (tokens[index] === undefined)
+                return undefined;
+            node.exception = tokens[index];
+            index++;
+        }
+        return node;
+    }
+    const node = parseExpression();
+    return node && index === tokens.length ? node : undefined;
+}
+function parseDeclaration(declaration) {
+    try {
+        return { node: parse(declaration), strict: true };
+    }
+    catch {
+        const node = parseLenient(declaration);
+        return node ? { node, strict: false } : undefined;
+    }
+}
+function normalizedDeclaration(packageInfo) {
+    return packageInfo.declaredLicense?.trim() ?? '';
+}
+function packageLabel(packageInfo) {
+    return `${packageInfo.name}${packageInfo.version ? `@${packageInfo.version}` : ''}`;
+}
+function displayDeclaration(declaration) {
+    return declaration.replace(/[\u0000-\u001f\u007f]/g, (character) => {
+        switch (character) {
+            case '\r':
+                return '\\r';
+            case '\n':
+                return '\\n';
+            case '\t':
+                return '\\t';
+            default:
+                return `\\u${character.codePointAt(0).toString(16).padStart(4, '0')}`;
+        }
+    });
+}
+function ambiguitySuffix(evaluation) {
+    return evaluation.incompatibleAnd
+        ? ' Both licenses may apply, making this declaration ambiguous and incompatible. Ask package author to use OR if either license may be chosen, or clarify package licensing.'
+        : '';
+}
+function packageSort(a, b) {
+    if (a.kind === 'project' && b.kind !== 'project')
+        return -1;
+    if (a.kind !== 'project' && b.kind === 'project')
+        return 1;
+    return (a.name.localeCompare(b.name) ||
+        (a.version ?? '').localeCompare(b.version ?? '') ||
+        normalizedDeclaration(a).localeCompare(normalizedDeclaration(b)) ||
+        a.kind.localeCompare(b.kind));
+}
+function issue(packageInfo, message) {
+    return {
+        packageName: packageInfo.name,
+        packageVersion: packageInfo.version,
+        packageKind: packageInfo.kind,
+        message,
+    };
+}
+/** Resolve the license the built artifact is distributed under, which selects the policy applied to its dependencies */
+export function resolveProjectLicense(inventory) {
+    const projectPackage = inventory.packages.find((packageInfo) => packageInfo.kind === 'project');
+    const declaration = projectPackage ? normalizedDeclaration(projectPackage) : '';
+    return { declaration, license: isProjectLicense(declaration) ? declaration : undefined };
+}
+function createSourceLicenseIssue(packageInfo, descriptor) {
+    const required = descriptor.requiredSourceLicense;
+    if (!required)
+        return undefined; // This project draws no distinction between its source and distribution licenses
+    const sourceLicense = packageInfo.sourceLicense?.trim() ?? '';
+    if (sourceLicense === required)
+        return undefined;
+    if (!sourceLicense) {
+        return issue(packageInfo, `Your ${descriptor.subject} source does not declare a license in package.json, but the Companion project requires ${descriptor.subject} source to be ${required} so it stays portable.`);
+    }
+    return issue(packageInfo, `Your ${descriptor.subject} source is licensed as ${displayDeclaration(sourceLicense)} in package.json, but the Companion project requires ${descriptor.subject} source to be ${required} so it stays portable. Declare the license the ${descriptor.subject} is distributed under in ${descriptor.distributionLicenseLocation} instead.`);
+}
+function createDistributionLicenseIssue(packageInfo, descriptor) {
+    const declaration = normalizedDeclaration(packageInfo);
+    if (!declaration) {
+        return issue(packageInfo, `Your ${descriptor.subject} does not declare a license in ${descriptor.distributionLicenseLocation}. ${supportedProjectLicenseAdvice()} Talk to us if you have a reason to use a different license.`);
+    }
+    if (isProjectLicense(declaration))
+        return undefined;
+    let reason = 'which is not supported';
+    try {
+        // A declaration with a conjunction is dual licensing, which a project must pick a single license from
+        if (!('license' in parse(declaration)))
+            reason = 'and dual licensing is not supported';
+    }
+    catch {
+        // Report the declaration as unsupported, even when SPDX parsing fails.
+    }
+    return issue(packageInfo, `Your ${descriptor.subject} is published under ${displayDeclaration(declaration)}, ${reason}. ${supportedProjectLicenseAdvice()} Talk to us if you have a reason to use a different license.`);
+}
+/** The distribution and source licenses may be declared in different files, and are reported independently */
+function createProjectIssues(packageInfo, descriptor) {
+    return [
+        createDistributionLicenseIssue(packageInfo, descriptor),
+        createSourceLicenseIssue(packageInfo, descriptor),
+    ].filter((projectIssue) => projectIssue !== undefined);
+}
+export function createLicensePolicyIssues(inventory, descriptor, overrides) {
+    const result = [];
+    const seen = new Set();
+    const projectLicense = resolveProjectLicense(inventory).license ?? FALLBACK_PROJECT_LICENSE;
+    const policy = PROJECT_LICENSE_POLICIES[projectLicense];
+    const bundledLicenses = policy.allowedDependencyLicenses;
+    // Identical to the bundled set where the policy has nothing which only works as an external, or where the project
+    // has no way to externalise, so that no issue is ever reported as fixable in a way which would not in fact help
+    const externalLicenses = policy.externalOnlyLicenses.size && descriptor.externaliseAdvice
+        ? new Set([...bundledLicenses, ...policy.externalOnlyLicenses])
+        : bundledLicenses;
+    for (const packageInfo of [...inventory.packages].sort(packageSort)) {
+        const declaration = normalizedDeclaration(packageInfo);
+        const identity = packageInfo.kind === 'project'
+            ? 'project'
+            : `dependency:${packageInfo.name}@${packageInfo.version ?? ''}:${declaration}`;
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        if (packageInfo.kind === 'project') {
+            result.push(...createProjectIssues(packageInfo, descriptor));
+            continue;
+        }
+        if (!declaration) {
+            result.push(issue(packageInfo, `Dependency ${packageLabel(packageInfo)} has no declared license.`));
+            continue;
+        }
+        let parsed = parseDeclaration(declaration);
+        // Only ever replaces a declaration which is not valid SPDX, so a correction can never launder a real license
+        if (!parsed || !parsed.strict) {
+            const corrected = correctedPackageLicense(overrides, packageInfo.name, packageInfo.version);
+            if (corrected)
+                parsed = parseDeclaration(corrected) ?? parsed;
+        }
+        if (!parsed) {
+            result.push(issue(packageInfo, `Dependency ${packageLabel(packageInfo)} has unparseable license declaration ${displayDeclaration(declaration)}.`));
+            continue;
+        }
+        const allowedLicenses = packageInfo.kind === 'external' ? externalLicenses : bundledLicenses;
+        const evaluation = evaluate(parsed.node, allowedLicenses);
+        if (evaluation.allowed)
+            continue;
+        // Only reachable for a bundled package, externals are already evaluated against the wider set
+        if (descriptor.externaliseAdvice && evaluate(parsed.node, externalLicenses).allowed) {
+            result.push(issue(packageInfo, `Dependency ${packageLabel(packageInfo)} has license declaration ${displayDeclaration(declaration)} which may only be shipped as an external dependency, not built into the bundle. ${descriptor.externaliseAdvice}`));
+            continue;
+        }
+        if (!parsed.strict) {
+            // Reaching here means no branch we could recognise was allowed, so the unrecognised ones are the problem
+            result.push(issue(packageInfo, `Dependency ${packageLabel(packageInfo)} has license declaration ${displayDeclaration(declaration)} which is not a valid SPDX identifier, so it cannot be checked against the ${projectLicense} license policy. Ask the package author to declare a specific SPDX license.`));
+            continue;
+        }
+        result.push(issue(packageInfo, `Dependency ${packageLabel(packageInfo)} has license declaration ${displayDeclaration(declaration)} which is not compatible with the ${projectLicense} license policy.${ambiguitySuffix(evaluation)}`));
+    }
+    return result;
+}
+export function enforceLicensePolicy(inventory, descriptor, overrides, options = {}) {
+    const issues = createLicensePolicyIssues(inventory, descriptor, overrides);
+    if (issues.length === 0)
+        return;
+    const stderr = options.stderr ?? process.stderr;
+    const prefix = options.ignoreLicenseRules ? 'LICENSE WARNING' : 'LICENSE ERROR';
+    for (const policyIssue of issues)
+        stderr.write(`${prefix}: ${policyIssue.message}\n`);
+    if (options.ignoreLicenseRules) {
+        stderr.write(`License validation ignored ${issues.length} error${issues.length === 1 ? '' : 's'} because --ignore-license-rules was provided.\n`);
+        return;
+    }
+    stderr.write(`License validation failed with ${issues.length} error${issues.length === 1 ? '' : 's'}.\n`);
+    stderr.write(`${descriptor.helpMessage}\n`);
+    throw new LicensePolicyError(issues);
+}

package/dist/scripts/build-connection.js

@@ -3,17 +3,19 @@
 import 'zx/globals';
 import { buildPackage } from './lib/build-util.js';
 import { LicensePolicyError } from './lib/license-warning-util.js';
-import { ignoreLicenseRules } from './lib/cli-options.js';
+import { PrebuildCoverageError } from './lib/prebuild-check-util.js';
+import { ignoreLicenseRules, ignorePrebuildRules } from './lib/cli-options.js';
 if (process.platform === 'win32') {
     usePowerShell(); // to enable powershell
 }
 if (argv.help) {
-    console.log('Usage: companion-module-build [--dev] [--prerelease] [--ignore-license-rules]');
+    console.log('Usage: companion-module-build [--dev] [--prerelease] [--ignore-license-rules] [--ignore-prebuild-rules]');
     console.log('Builds the companion connection module');
     console.log('  --dev: Build in development mode. This will not minify the code, making it easier to debug.');
     console.log('  --prerelease: Build in prerelease mode. This gets added as metadata to the manifest');
     console.log('  --output <filename>: Output to a specific filename, without a file extension');
     console.log('  --ignore-license-rules: Report license policy issues as warnings instead of failing');
+    console.log('  --ignore-prebuild-rules: Report native libraries missing binaries for a required platform as warnings instead of failing');
     process.exit(0);
 }
 const { validateManifest } = await import('@companion-module/base/manifest').catch((e) => {
@@ -22,10 +24,11 @@ const { validateManifest } = await import('@companion-module/base/manifest').cat
 try {
     await buildPackage('@companion-module/base', validateManifest, 'connection', '>=1.4.0 <3.0.0', {
         ignoreLicenseRules: ignoreLicenseRules(argv),
+        ignorePrebuildRules: ignorePrebuildRules(argv),
     });
 }
 catch (e) {
-    if (e instanceof LicensePolicyError)
+    if (e instanceof LicensePolicyError || e instanceof PrebuildCoverageError)
         process.exitCode = 1;
     else
         throw e;

package/dist/scripts/build-surface.js

@@ -3,27 +3,30 @@
 import 'zx/globals';
 import { buildPackage } from './lib/build-util.js';
 import { LicensePolicyError } from './lib/license-warning-util.js';
-import { ignoreLicenseRules } from './lib/cli-options.js';
+import { PrebuildCoverageError } from './lib/prebuild-check-util.js';
+import { ignoreLicenseRules, ignorePrebuildRules } from './lib/cli-options.js';
 if (process.platform === 'win32') {
     usePowerShell(); // to enable powershell
 }
 if (argv.help) {
-    console.log('Usage: companion-surface-build [--dev] [--prerelease] [--ignore-license-rules]');
+    console.log('Usage: companion-surface-build [--dev] [--prerelease] [--ignore-license-rules] [--ignore-prebuild-rules]');
     console.log('Builds the companion surface module');
     console.log('  --dev: Build in development mode. This will not minify the code, making it easier to debug.');
     console.log('  --prerelease: Build in prerelease mode. This gets added as metadata to the manifest');
     console.log('  --output <filename>: Output to a specific filename, without a file extension');
     console.log('  --ignore-license-rules: Report license policy issues as warnings instead of failing');
+    console.log('  --ignore-prebuild-rules: Report native libraries missing binaries for a required platform as warnings instead of failing');
     process.exit(0);
 }
 const { validateSurfaceManifest } = await import('@companion-surface/base');
 try {
     await buildPackage('@companion-surface/base', validateSurfaceManifest, 'surface', '>=1.0.0 <2.0.0', {
         ignoreLicenseRules: ignoreLicenseRules(argv),
+        ignorePrebuildRules: ignorePrebuildRules(argv),
     });
 }
 catch (e) {
-    if (e instanceof LicensePolicyError)
+    if (e instanceof LicensePolicyError || e instanceof PrebuildCoverageError)
         process.exitCode = 1;
     else
         throw e;

package/dist/scripts/lib/build-util.d.ts

@@ -9,4 +9,5 @@ export declare function enforceLegalInventory(inventory: LegalInventory, options
 }): void;
 export declare function buildPackage<M>(frameworkPackageName: string, validateManifest: (manifest: M, looseChecks: boolean) => void, moduleType: ModuleType, versionRange: string, options?: {
     ignoreLicenseRules?: boolean;
+    ignorePrebuildRules?: boolean;
 }): Promise<void>;

package/dist/scripts/lib/build-util.js

@@ -10,6 +10,7 @@ import { collectInstalledPackages, collectMetafilePackages, createLegalInventory
 import { createEsbuildOptions, loadModuleBuildDefinition } from './bundle-util.js';
 import { resolveExternalDependencies } from './external-install-util.js';
 import { enforceLicensePolicy } from './license-warning-util.js';
+import { checkPrebuildCoverage, enforcePrebuildCoverage } from './prebuild-check-util.js';
 function toSanitizedDirname(name) {
     return name.replace(/[^a-zA-Z0-9-\.]/g, '-').replace(/[-+]/g, '-');
 }
@@ -176,6 +177,9 @@ export async function buildPackage(frameworkPackageName, validateManifest, modul
             }
         }
     }
+    // Ensure every native library has binaries for all the platforms we need to support
+    const prebuildReport = await checkPrebuildCoverage(packageBaseDir);
+    enforcePrebuildCoverage(prebuildReport, { ignorePrebuildRules: options.ignorePrebuildRules });
     const shippedPackages = [...metafilePackages.packages];
     if (Object.keys(packageJson.dependencies).length) {
         shippedPackages.push(...(await collectInstalledPackages(path.join(packageBaseDir, 'node_modules'))));
@@ -185,7 +189,7 @@ export async function buildPackage(frameworkPackageName, validateManifest, modul
         console.warn(`License inventory: ${diagnostic}`);
     }
     await writeLegalArtifacts(packageBaseDir, legalInventory);
-    enforceLegalInventory(legalInventory, options);
+    enforceLegalInventory(legalInventory, { ignoreLicenseRules: options.ignoreLicenseRules });
     // Create tgz of the build
     let tgzFile = toSanitizedDirname(`${manifestJson.id}-${manifestJson.version}`);
     if (typeof argv['output'] === 'string') {

package/dist/scripts/lib/cli-options.d.ts

@@ -1 +1,2 @@
 export declare function ignoreLicenseRules(argv: Record<string, unknown>): boolean;
+export declare function ignorePrebuildRules(argv: Record<string, unknown>): boolean;

package/dist/scripts/lib/cli-options.js

@@ -2,3 +2,7 @@ export function ignoreLicenseRules(argv) {
     const value = argv['ignore-license-rules'];
     return value === true || value === 'true';
 }
+export function ignorePrebuildRules(argv) {
+    const value = argv['ignore-prebuild-rules'];
+    return value === true || value === 'true';
+}

package/dist/scripts/lib/known-package-licenses.d.ts

@@ -1,3 +1,4 @@
+import type { LicenseOverrides } from '../../license/index.js';
 /**
  * Packages which ship no license declaration in their package.json, but whose license has been confirmed by reading
  * what they publish. Only add an entry after checking that version yourself, and record where the license was found.
@@ -6,7 +7,6 @@
  * so an entry can never hide what a package says about itself.
  */
 export declare const KNOWN_PACKAGE_LICENSES: Record<string, string>;
-export declare function knownPackageLicense(name: string | undefined, version: string | undefined): string | undefined;
 /**
  * Packages which declare a license that is not a valid SPDX expression, mapped to what the license text they publish
  * actually is. Unlike KNOWN_PACKAGE_LICENSES this overrides what a package says about itself, so it is only consulted
@@ -16,4 +16,5 @@ export declare function knownPackageLicense(name: string | undefined, version: s
  * Keys are exact `name@version`, so a later release declaring something different is unaffected.
  */
 export declare const CORRECTED_PACKAGE_LICENSES: Record<string, string>;
-export declare function correctedPackageLicense(name: string | undefined, version: string | undefined): string | undefined;
+/** The overrides the module tooling applies. Other consumers of the engine carry their own. */
+export declare const MODULE_LICENSE_OVERRIDES: LicenseOverrides;

package/dist/scripts/lib/known-package-licenses.js

@@ -41,11 +41,6 @@ export const KNOWN_PACKAGE_LICENSES = {
     // license, "MIT License", in the published tarball, https://github.com/fabiospampinato/stubborn-fs
     'stubborn-fs@1.2.5': 'MIT',
 };
-export function knownPackageLicense(name, version) {
-    if (!name || !version)
-        return undefined;
-    return KNOWN_PACKAGE_LICENSES[`${name}@${version}`];
-}
 /**
  * Packages which declare a license that is not a valid SPDX expression, mapped to what the license text they publish
  * actually is. Unlike KNOWN_PACKAGE_LICENSES this overrides what a package says about itself, so it is only consulted
@@ -71,8 +66,8 @@ export const CORRECTED_PACKAGE_LICENSES = {
     // clause forbidding use of the Dojo Foundation's name to endorse derived products, https://github.com/kriszyp/json-schema
     'json-schema@0.2.3': '(AFL-2.1 OR BSD-3-Clause)',
 };
-export function correctedPackageLicense(name, version) {
-    if (!name || !version)
-        return undefined;
-    return CORRECTED_PACKAGE_LICENSES[`${name}@${version}`];
-}
+/** The overrides the module tooling applies. Other consumers of the engine carry their own. */
+export const MODULE_LICENSE_OVERRIDES = {
+    knownPackageLicenses: KNOWN_PACKAGE_LICENSES,
+    correctedPackageLicenses: CORRECTED_PACKAGE_LICENSES,
+};

package/dist/scripts/lib/license-util.d.ts

@@ -1,55 +1,16 @@
 import * as esbuild from 'esbuild';
-export type ShippedPackageKind = 'project' | 'bundled' | 'external';
-export interface ShippedPackage {
-    kind: ShippedPackageKind;
-    name: string;
-    version?: string;
-    declaredLicense?: string;
-    /** Only for the project, the package.json license of its own source, which declaredLicense distributes it under */
-    sourceLicense?: string;
-    /** Where recipients can obtain the source of this package, as required by MPL-2.0 and the GPL family */
-    repositoryUrl?: string;
-    packageRoot: string;
-    contributingPaths: Set<string>;
-}
-export interface MetafilePackageCollection {
-    packages: ShippedPackage[];
-    diagnostics: string[];
-}
-export interface LegalText {
-    role: 'license' | 'notice' | 'source-comment';
-    filename: string;
-    content: string;
-    sha256: string;
-}
-export interface ShippedPackageLegalRecord extends ShippedPackage {
-    legalTexts: LegalText[];
-}
-export interface PackageLegalMaterial {
-    package: ShippedPackageLegalRecord;
-    diagnostics: string[];
-}
-export interface LegalInventory {
-    packages: ShippedPackageLegalRecord[];
-    diagnostics: string[];
-}
-type PackageJson = {
-    name?: string;
-    version?: string;
-    license?: unknown;
-    licenses?: unknown;
-    repository?: unknown;
-    homepage?: unknown;
-};
-export declare function normalizeRepositoryUrl(packageJson: PackageJson): string | undefined;
-export declare function normalizeInventoryPath(inputPath: string, ownerRoot: string): string;
+import { type LegalInventory, type PackageCollection, type ProjectIdentity, type ShippedPackage } from '../../license/index.js';
+export { NO_LICENSE_OVERRIDES, collectPackageLegalMaterial, collectPackagesFromInputPaths, createLegalInventory, getContributingInputs, normalizeInventoryPath, normalizeLegalText, normalizeRepositoryUrl, renderLicenseFile, renderNoticeFile, writeLegalArtifacts, } from '../../license/index.js';
+export type { LegalInventory, LegalText, LicenseOverrides, PackageLegalMaterial, ProjectIdentity, ShippedPackage, ShippedPackageKind, ShippedPackageLegalRecord, } from '../../license/index.js';
+export type { PackageCollection, PackageCollection as MetafilePackageCollection } from '../../license/index.js';
+/**
+ * How a module identifies itself to the engine. The manifest license is what the packaged module is distributed as,
+ * which is what its dependencies must fit. package.json only licenses the module's own source, so it is the fallback
+ * for modules not declaring the other.
+ */
+export declare function moduleProjectIdentity(moduleDir: string): Promise<ProjectIdentity>;
+/** Scans a dependency tree installed alongside a module, applying the module tooling's own license overrides */
 export declare function collectInstalledPackages(nodeModulesDir: string): Promise<ShippedPackage[]>;
-export declare function normalizeLegalText(content: string): string;
-export declare function collectPackageLegalMaterial(packageInfo: ShippedPackage): Promise<PackageLegalMaterial>;
-export declare function renderLicenseFile(inventory: LegalInventory): string;
-export declare function renderNoticeFile(inventory: LegalInventory): string | undefined;
-export declare function writeLegalArtifacts(outputDir: string, inventory: LegalInventory): Promise<void>;
-export declare function createLegalInventory(packages: ShippedPackage[]): Promise<LegalInventory>;
+/** Attributes the inputs of a module's esbuild metafile, applying the module tooling's own license overrides */
+export declare function collectMetafilePackages(moduleDir: string, metafile: esbuild.Metafile): Promise<PackageCollection>;
 export declare function analyzeShippedLegalInventory(moduleDir: string): Promise<LegalInventory>;
-export declare function collectMetafilePackages(moduleDir: string, metafile: esbuild.Metafile): Promise<MetafilePackageCollection>;
-export {};