@companion-module/tools 3.1.0 → 3.2.0

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

@@ -1,74 +1,13 @@
-import { lstat, readdir, realpath, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import * as esbuild from 'esbuild';
+import { asLicenseString, collectInstalledPackages as collectInstalledPackagesWith, collectMetafilePackages as collectMetafilePackagesWith, createLegalInventory, } from '../../license/index.js';
 import { createEsbuildOptions, loadModuleBuildDefinition } from './bundle-util.js';
 import { resolveExternalDependencies, withInstalledExternalTree } from './external-install-util.js';
-import { knownPackageLicense } from './known-package-licenses.js';
-const SHORTHAND_REPOSITORY_HOSTS = {
-    github: 'https://github.com/',
-    gitlab: 'https://gitlab.com/',
-    bitbucket: 'https://bitbucket.org/',
-};
-export function normalizeRepositoryUrl(packageJson) {
-    const repository = packageJson.repository;
-    const declared = typeof repository === 'string'
-        ? repository
-        : repository && typeof repository === 'object' && typeof repository.url === 'string'
-            ? repository.url
-            : undefined;
-    let url = declared?.trim() ?? '';
-    if (url) {
-        // npm shorthands, either "user/repo" or "<host>:user/repo"
-        if (/^[\w.-]+\/[\w.-]+$/.test(url))
-            url = `${SHORTHAND_REPOSITORY_HOSTS.github}${url}`;
-        const shorthand = /^([a-z]+):([\w.-]+\/[\w.-]+)$/.exec(url);
-        if (shorthand && SHORTHAND_REPOSITORY_HOSTS[shorthand[1]]) {
-            url = `${SHORTHAND_REPOSITORY_HOSTS[shorthand[1]]}${shorthand[2]}`;
-        }
-        url = url.replace(/^git\+/, '').replace(/^(?:git|ssh):\/\/(?:git@)?/, 'https://');
-        const scpLike = /^git@([^:]+):(.+)$/.exec(url);
-        if (scpLike)
-            url = `https://${scpLike[1]}/${scpLike[2]}`;
-        url = url.replace(/\.git$/, '');
-    }
-    if (!/^https?:\/\//.test(url))
-        url = typeof packageJson.homepage === 'string' ? packageJson.homepage.trim() : '';
-    return /^https?:\/\//.test(url) ? url : undefined;
-}
-export function normalizeInventoryPath(inputPath, ownerRoot) {
-    const relativePath = path.relative(ownerRoot, inputPath);
-    if (relativePath === '' || relativePath === '.')
-        return '.';
-    if (relativePath === '..' || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
-        return '<outside package root>';
-    }
-    return relativePath.split(path.sep).join('/');
-}
-async function readPackageJson(packageRoot) {
-    return JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
-}
-function asLicenseString(license) {
-    if (typeof license === 'string')
-        return license;
-    // npm deprecated { type, url } and arrays of it long ago, but older packages are still published with them
-    if (Array.isArray(license)) {
-        const choices = license.map(asLicenseString).filter((choice) => choice !== undefined);
-        if (!choices.length)
-            return undefined;
-        return choices.length === 1 ? choices[0] : `(${choices.join(' OR ')})`; // An array offers a choice of licenses
-    }
-    if (license && typeof license === 'object')
-        return asLicenseString(license.type);
-    return undefined;
-}
-/** Reads a package's license, preferring the current field over the deprecated plural one */
-function declaredLicenseOf(packageJson) {
-    return (asLicenseString(packageJson.license) ??
-        asLicenseString(packageJson.licenses) ??
-        // Only for packages declaring nothing at all, so this can never override what a package says about itself
-        knownPackageLicense(packageJson.name, packageJson.version));
-}
+import { MODULE_LICENSE_OVERRIDES } from './known-package-licenses.js';
+// The engine itself is generic and lives in ../../license, so that it can also be used by the rest of the Companion
+// project. These re-exports keep a single import for everything license related in the module scripts and tests.
+export { NO_LICENSE_OVERRIDES, collectPackageLegalMaterial, collectPackagesFromInputPaths, createLegalInventory, getContributingInputs, normalizeInventoryPath, normalizeLegalText, normalizeRepositoryUrl, renderLicenseFile, renderNoticeFile, writeLegalArtifacts, } from '../../license/index.js';
 async function readManifestLicense(moduleDir) {
     try {
         const manifest = JSON.parse(await readFile(path.join(moduleDir, 'companion', 'manifest.json'), 'utf8'));
@@ -78,291 +17,26 @@ async function readManifestLicense(moduleDir) {
         return undefined; // Modules without a readable manifest fall back to the package.json license
     }
 }
-async function findPackageRoot(inputPath, moduleDir) {
-    const nodeModulesDir = path.join(moduleDir, 'node_modules');
-    if (!inputPath.startsWith(`${nodeModulesDir}${path.sep}`))
-        return undefined;
-    // A package owns everything below the directory node_modules resolves it to. Its own subdirectories can hold a
-    // package.json marking their module type, sometimes with a name and version, so only this boundary identifies it.
-    const segments = inputPath.split(path.sep);
-    const rootIndex = segments.lastIndexOf('node_modules') + 1;
-    const packageRoot = segments
-        .slice(0, segments[rootIndex]?.startsWith('@') ? rootIndex + 2 : rootIndex + 1)
-        .join(path.sep);
-    try {
-        await readPackageJson(packageRoot);
-        return packageRoot;
-    }
-    catch {
-        return undefined; // Without a package.json this is not a package, so the file counts as project code
-    }
-}
-function getContributingInputs(metafile) {
-    const inputs = new Set();
-    for (const [outputPath, output] of Object.entries(metafile.outputs)) {
-        if (!outputPath.endsWith('.js'))
-            continue;
-        for (const [inputPath, input] of Object.entries(output.inputs)) {
-            if (input.bytesInOutput > 0)
-                inputs.add(inputPath);
-        }
-    }
-    return [...inputs];
-}
-function packageFromJson(kind, packageRoot, packageJson) {
+/**
+ * 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 async function moduleProjectIdentity(moduleDir) {
     return {
-        kind,
-        name: packageJson.name ?? path.basename(packageRoot),
-        version: packageJson.version,
-        declaredLicense: declaredLicenseOf(packageJson),
-        repositoryUrl: normalizeRepositoryUrl(packageJson),
-        packageRoot,
-        contributingPaths: new Set(),
+        projectRoots: [moduleDir],
+        packageRoot: moduleDir,
+        name: undefined,
+        distributionLicense: asLicenseString(await readManifestLicense(moduleDir)),
     };
 }
+/** Scans a dependency tree installed alongside a module, applying the module tooling's own license overrides */
 export async function collectInstalledPackages(nodeModulesDir) {
-    const packages = [];
-    async function scan(currentNodeModulesDir) {
-        let entries;
-        try {
-            entries = await readdir(currentNodeModulesDir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-            if (entry.name === '.bin' || entry.isSymbolicLink())
-                continue;
-            if (entry.name.startsWith('@')) {
-                if (!entry.isDirectory())
-                    continue;
-                await scanScopedPackages(path.join(currentNodeModulesDir, entry.name));
-                continue;
-            }
-            if (!entry.isDirectory())
-                continue;
-            await scanPackage(path.join(currentNodeModulesDir, entry.name));
-        }
-    }
-    async function scanScopedPackages(scopeDir) {
-        const entries = await readdir(scopeDir, { withFileTypes: true });
-        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-            if (entry.isDirectory() && !entry.isSymbolicLink())
-                await scanPackage(path.join(scopeDir, entry.name));
-        }
-    }
-    async function scanPackage(packageRoot) {
-        try {
-            packages.push(packageFromJson('external', packageRoot, await readPackageJson(packageRoot)));
-        }
-        catch {
-            return;
-        }
-        await scan(path.join(packageRoot, 'node_modules'));
-    }
-    await scan(nodeModulesDir);
-    return packages;
-}
-const MAX_LEGAL_FILE_SIZE = 1024 * 1024;
-export function normalizeLegalText(content) {
-    return content.replace(/\r\n/g, '\n').trim();
-}
-function sha256(content) {
-    return createHash('sha256').update(content).digest('hex');
-}
-function isPathInside(childPath, parentPath) {
-    const relativePath = path.relative(parentPath, childPath);
-    return (relativePath === '' ||
-        (!relativePath.startsWith(`..${path.sep}`) && relativePath !== '..' && !path.isAbsolute(relativePath)));
-}
-function legalRole(filename) {
-    if (/^(license|licence|copying)/i.test(filename))
-        return 'license';
-    if (/^notice/i.test(filename))
-        return 'notice';
-    return undefined;
+    return collectInstalledPackagesWith(nodeModulesDir, MODULE_LICENSE_OVERRIDES);
 }
-async function readLegalText(filePath, packageRoot, role) {
-    const linkStat = await lstat(filePath);
-    if (linkStat.isSymbolicLink())
-        return undefined;
-    const fileStat = await stat(filePath);
-    if (!fileStat.isFile() || fileStat.size > MAX_LEGAL_FILE_SIZE)
-        return undefined;
-    const rawContent = await readFile(filePath, 'utf8');
-    if (rawContent.includes('\0'))
-        return undefined;
-    const content = normalizeLegalText(rawContent);
-    if (!content)
-        return undefined;
-    return { role, filename: normalizeInventoryPath(filePath, packageRoot), content, sha256: sha256(content) };
-}
-function sourceLoader(filename) {
-    switch (path.extname(filename).toLowerCase()) {
-        case '.js':
-        case '.mjs':
-        case '.cjs':
-            return 'js';
-        case '.ts':
-            return 'ts';
-        case '.tsx':
-            return 'tsx';
-        default:
-            return undefined;
-    }
-}
-export async function collectPackageLegalMaterial(packageInfo) {
-    const diagnostics = [];
-    const candidateFiles = new Map();
-    for (const entry of await readdir(packageInfo.packageRoot, { withFileTypes: true })) {
-        if (!entry.isFile())
-            continue;
-        const role = legalRole(entry.name);
-        if (role)
-            candidateFiles.set(entry.name, role);
-    }
-    const seeLicenseMatch = /^SEE LICENSE IN (.+)$/i.exec(packageInfo.declaredLicense ?? '');
-    if (seeLicenseMatch) {
-        const explicitPath = path.resolve(packageInfo.packageRoot, seeLicenseMatch[1]);
-        if (!isPathInside(explicitPath, packageInfo.packageRoot)) {
-            diagnostics.push(`Ignoring license file outside package root: ${seeLicenseMatch[1]}`);
-        }
-        else {
-            candidateFiles.set(normalizeInventoryPath(explicitPath, packageInfo.packageRoot), 'license');
-        }
-    }
-    const legalTexts = [];
-    for (const [filename, role] of [...candidateFiles.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-        try {
-            const legalText = await readLegalText(path.join(packageInfo.packageRoot, filename), packageInfo.packageRoot, role);
-            if (legalText)
-                legalTexts.push(legalText);
-            else
-                diagnostics.push(`Ignoring unreadable, binary, or oversized legal file: ${filename}`);
-        }
-        catch {
-            diagnostics.push(`Ignoring unreadable legal file: ${filename}`);
-        }
-    }
-    if (!legalTexts.some((text) => text.role === 'license')) {
-        for (const sourcePath of [...packageInfo.contributingPaths].sort()) {
-            const loader = sourceLoader(sourcePath);
-            if (!loader) {
-                diagnostics.push(`Ignoring unsupported source file for legal comments: ${sourcePath}`);
-                continue;
-            }
-            try {
-                const source = await readFile(path.join(packageInfo.packageRoot, sourcePath), 'utf8');
-                const result = await esbuild.transform(source, { loader, legalComments: 'external' });
-                if (result.legalComments) {
-                    const content = normalizeLegalText(result.legalComments);
-                    if (content) {
-                        legalTexts.push({
-                            role: 'source-comment',
-                            filename: sourcePath,
-                            content,
-                            sha256: sha256(content),
-                        });
-                    }
-                }
-            }
-            catch {
-                diagnostics.push(`Ignoring unreadable source file for legal comments: ${sourcePath}`);
-            }
-        }
-    }
-    const uniqueTexts = new Map();
-    for (const legalText of legalTexts) {
-        const key = legalText.role === 'source-comment'
-            ? `${legalText.role}:${legalText.sha256}`
-            : `${legalText.role}:${legalText.filename}:${legalText.sha256}`;
-        uniqueTexts.set(key, legalText);
-    }
-    return { package: { ...packageInfo, legalTexts: [...uniqueTexts.values()] }, diagnostics };
-}
-function comparePackages(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 ?? '');
-}
-function packageName(packageInfo) {
-    return packageInfo.version ? `${packageInfo.name}@${packageInfo.version}` : packageInfo.name;
-}
-function renderLegalFile(inventory, roles) {
-    const groupedTexts = new Map();
-    for (const packageInfo of inventory.packages) {
-        for (const text of packageInfo.legalTexts) {
-            if (!roles.includes(text.role))
-                continue;
-            const group = groupedTexts.get(text.sha256) ?? { text, packages: new Map() };
-            const packageKey = `${packageInfo.kind === 'project' ? 'project' : 'dependency'}:${packageName(packageInfo)}:${packageInfo.declaredLicense ?? ''}`;
-            group.packages.set(packageKey, packageInfo);
-            groupedTexts.set(text.sha256, group);
-        }
-    }
-    if (!groupedTexts.size)
-        return undefined;
-    const sections = [...groupedTexts.values()].sort((a, b) => comparePackages([...a.packages.values()].sort(comparePackages)[0], [...b.packages.values()].sort(comparePackages)[0]));
-    const separator = '-'.repeat(80);
-    const renderedSections = sections.map((section) => {
-        const packages = [...section.packages.values()].sort(comparePackages);
-        const packageList = packages
-            .map((packageInfo) => {
-            const label = `${packageName(packageInfo)} — ${packageInfo.declaredLicense ?? 'UNKNOWN'}`;
-            // Tells recipients where to obtain the source, which MPL-2.0 and the GPL family require
-            return packageInfo.repositoryUrl ? `${label} (${packageInfo.repositoryUrl})` : label;
-        })
-            .join(', ');
-        return `Packages: ${packageList}\n${separator}\n${normalizeLegalText(section.text.content)}`;
-    });
-    return `${renderedSections.join('\n\n')}\n`;
-}
-export function renderLicenseFile(inventory) {
-    return renderLegalFile(inventory, ['license', 'source-comment']) ?? '';
-}
-export function renderNoticeFile(inventory) {
-    return renderLegalFile(inventory, ['notice']);
-}
-export async function writeLegalArtifacts(outputDir, inventory) {
-    await writeFile(path.join(outputDir, 'LICENSE'), renderLicenseFile(inventory));
-    const notice = renderNoticeFile(inventory);
-    const noticePath = path.join(outputDir, 'NOTICE');
-    if (notice)
-        await writeFile(noticePath, notice);
-    else
-        await rm(noticePath, { force: true });
-}
-const kindPriority = {
-    project: 0,
-    bundled: 1,
-    external: 2,
-};
-export async function createLegalInventory(packages) {
-    const mergedPackages = new Map();
-    for (const packageInfo of packages) {
-        const existing = mergedPackages.get(packageInfo.packageRoot);
-        if (!existing) {
-            mergedPackages.set(packageInfo.packageRoot, {
-                ...packageInfo,
-                contributingPaths: new Set(packageInfo.contributingPaths),
-            });
-            continue;
-        }
-        for (const sourcePath of packageInfo.contributingPaths)
-            existing.contributingPaths.add(sourcePath);
-        if (kindPriority[packageInfo.kind] < kindPriority[existing.kind])
-            existing.kind = packageInfo.kind;
-    }
-    const diagnostics = [];
-    const legalRecords = [];
-    for (const packageInfo of mergedPackages.values()) {
-        const material = await collectPackageLegalMaterial(packageInfo);
-        legalRecords.push(material.package);
-        diagnostics.push(...material.diagnostics);
-    }
-    return { packages: legalRecords, diagnostics };
+/** Attributes the inputs of a module's esbuild metafile, applying the module tooling's own license overrides */
+export async function collectMetafilePackages(moduleDir, metafile) {
+    return collectMetafilePackagesWith(metafile, moduleDir, await moduleProjectIdentity(moduleDir), MODULE_LICENSE_OVERRIDES);
 }
 export async function analyzeShippedLegalInventory(moduleDir) {
     const definition = await loadModuleBuildDefinition(moduleDir);
@@ -383,45 +57,3 @@ export async function analyzeShippedLegalInventory(moduleDir) {
     const inventory = await createLegalInventory(packages);
     return { ...inventory, diagnostics: [...metafilePackages.diagnostics, ...inventory.diagnostics] };
 }
-export async function collectMetafilePackages(moduleDir, metafile) {
-    const resolvedModuleDir = await realpath(moduleDir);
-    const projectPackageJson = await readPackageJson(resolvedModuleDir);
-    const packages = new Map();
-    const diagnostics = [];
-    // 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 a fallback for modules not declaring the other.
-    const projectLicense = (await readManifestLicense(resolvedModuleDir)) ?? declaredLicenseOf(projectPackageJson);
-    for (const input of getContributingInputs(metafile)) {
-        if (input.startsWith('<')) {
-            diagnostics.push(`Ignoring virtual esbuild input: ${input}`);
-            continue;
-        }
-        const inputPath = path.resolve(resolvedModuleDir, input);
-        if (!isPathInside(inputPath, resolvedModuleDir)) {
-            diagnostics.push(`Ignoring esbuild input outside module directory: ${input}`);
-            continue;
-        }
-        // Resolve ownership using logical node_modules path. Realpath would turn linked
-        // dependencies into paths outside moduleDir and incorrectly classify them as project code.
-        const packageRoot = (await findPackageRoot(inputPath, resolvedModuleDir)) ?? resolvedModuleDir;
-        const packageJson = packageRoot === resolvedModuleDir ? projectPackageJson : await readPackageJson(packageRoot);
-        const kind = packageRoot === resolvedModuleDir ? 'project' : 'bundled';
-        const key = `${kind}:${packageRoot}`;
-        let packageInfo = packages.get(key);
-        if (!packageInfo) {
-            packageInfo = {
-                kind,
-                name: packageJson.name ?? path.basename(packageRoot),
-                version: packageJson.version,
-                declaredLicense: kind === 'project' ? asLicenseString(projectLicense) : declaredLicenseOf(packageJson),
-                sourceLicense: kind === 'project' ? declaredLicenseOf(projectPackageJson) : undefined,
-                repositoryUrl: normalizeRepositoryUrl(packageJson),
-                packageRoot,
-                contributingPaths: new Set(),
-            };
-            packages.set(key, packageInfo);
-        }
-        packageInfo.contributingPaths.add(normalizeInventoryPath(inputPath, packageRoot));
-    }
-    return { packages: [...packages.values()], diagnostics };
-}

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

@@ -1,27 +1,11 @@
-import type { LegalInventory, ShippedPackageLegalRecord } from './license-util.js';
+import { type LegalInventory, type LicensePolicyDescriptor, type LicensePolicyIssue } from '../../license/index.js';
+export { LicensePolicyError, SUPPORTED_PROJECT_LICENSES, resolveProjectLicense } from '../../license/index.js';
+export type { LicensePolicyDescriptor, LicensePolicyIssue, ProjectLicense } from '../../license/index.js';
 export type ModuleType = 'connection' | 'surface';
-export interface LicensePolicyIssue {
-    packageName: string;
-    packageVersion?: string;
-    packageKind: ShippedPackageLegalRecord['kind'];
-    message: string;
-}
-type LicensePolicyOutput = Pick<NodeJS.WriteStream, 'write'>;
-export declare class LicensePolicyError extends Error {
-    readonly issues: LicensePolicyIssue[];
-    constructor(issues: LicensePolicyIssue[]);
-}
-/** Licenses a module may be declared as, each allowing a different set of dependency licenses */
-export type ProjectLicense = 'MIT' | 'GPL-2.0-only' | 'GPL-3.0-only';
-export declare const SUPPORTED_PROJECT_LICENSES: ProjectLicense[];
-/** Resolve the license the packaged module is distributed under, which selects the policy applied to its dependencies */
-export declare function resolveProjectLicense(inventory: LegalInventory): {
-    declaration: string;
-    license: ProjectLicense | undefined;
-};
+/** How the policy engine talks about a module: what it is called, where it declares its licenses, and how it ships */
+export declare const MODULE_LICENSE_POLICY: LicensePolicyDescriptor;
 export declare function createLicensePolicyIssues(inventory: LegalInventory): LicensePolicyIssue[];
 export declare function enforceLicensePolicy(inventory: LegalInventory, options?: {
     ignoreLicenseRules?: boolean;
-    stderr?: LicensePolicyOutput;
+    stderr?: Pick<NodeJS.WriteStream, 'write'>;
 }): void;
-export {};