@callstack/licenses 0.3.2 → 1.0.0

package/src/licenses/licenseExpression.ts

@@ -0,0 +1,200 @@
+import spdxExceptionIds from 'spdx-exceptions/index.json';
+import parse from 'spdx-expression-parse';
+import deprecatedSpdxLicenseIds from 'spdx-license-ids/deprecated.json';
+import spdxLicenseIds from 'spdx-license-ids/index.json';
+
+import type { LicenseExpression } from '../types';
+
+const SPDX_LICENSE_IDS = new Set(spdxLicenseIds);
+const DEPRECATED_SPDX_LICENSE_IDS = new Set(deprecatedSpdxLicenseIds);
+
+const CANONICAL_ID_BY_LOWERCASE = new Map(
+  [...spdxLicenseIds, ...deprecatedSpdxLicenseIds, ...spdxExceptionIds].map((id) => [id.toLowerCase(), id]),
+);
+
+const SPDX_OPERATORS = new Set(['and', 'or', 'with']);
+
+/**
+ * Unambiguous spellings that are not valid SPDX License Expressions, keyed by the lowercase, trimmed value.
+ * Ambiguous values (`BSD`, `GPL`, `LGPL`) are deliberately absent: guessing a variant or version changes the legal meaning.
+ */
+const LICENSE_ALIASES = new Map([
+  ['apache 2.0', 'Apache-2.0'],
+  ['apache-2', 'Apache-2.0'],
+  ['apache license 2.0', 'Apache-2.0'],
+  ['mit/x11', 'MIT'],
+  ['mit license', 'MIT'],
+]);
+
+/**
+ * Parses a Raw License into a License Expression, following the SPDX License Expression syntax.
+ *
+ * Never throws: a missing or unparseable value becomes an Unknown License that keeps the original value.
+ *
+ * @param rawLicense the license declaration as written in package.json, or `null` if absent
+ * @returns the parsed License Expression
+ * @example
+ * parseLicenseExpression('MIT OR Apache-2.0');
+ * // { kind: 'or', left: { kind: 'license', id: 'MIT', declaredId: 'MIT' }, right: { kind: 'license', id: 'Apache-2.0', declaredId: 'Apache-2.0' } }
+ */
+export function parseLicenseExpression(rawLicense: string | null): LicenseExpression {
+  if (rawLicense === null) {
+    return { kind: 'unknown', raw: rawLicense };
+  }
+
+  const parsed =
+    tryParse(rawLicense) ??
+    tryParse(LICENSE_ALIASES.get(rawLicense.trim().toLowerCase())) ??
+    tryParse(fixIdentifierCase(rawLicense));
+
+  return parsed ?? { kind: 'unknown', raw: rawLicense };
+}
+
+function tryParse(rawLicense: string | undefined): LicenseExpression | undefined {
+  if (rawLicense === undefined) {
+    return undefined;
+  }
+
+  try {
+    return mapSpdxParsedValueToLicenseExpression(parse(rawLicense));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Rewrites every identifier and operator to its canonical spelling (SPDX Annex B.2: identifiers are case-insensitive).
+ * Tokens that match no known identifier are left as written, so the re-parse rejects them.
+ */
+function fixIdentifierCase(rawLicense: string): string {
+  return rawLicense.replace(/[^\s()]+/g, (token) => {
+    if (SPDX_OPERATORS.has(token.toLowerCase())) {
+      return token.toUpperCase();
+    }
+
+    const plus = token.endsWith('+') ? '+' : '';
+    const id = plus ? token.slice(0, -1) : token;
+    const canonicalId =
+      CANONICAL_ID_BY_LOWERCASE.get(id.toLowerCase()) ??
+      (/^licenseref-/i.test(id) ? `LicenseRef-${id.slice('LicenseRef-'.length)}` : id);
+
+    return `${canonicalId}${plus}`;
+  });
+}
+
+function mapSpdxParsedValueToLicenseExpression(spdxParsedValue: parse.Info): LicenseExpression {
+  if ('conjunction' in spdxParsedValue) {
+    return {
+      kind: spdxParsedValue.conjunction,
+      left: mapSpdxParsedValueToLicenseExpression(spdxParsedValue.left),
+      right: mapSpdxParsedValueToLicenseExpression(spdxParsedValue.right),
+    };
+  }
+
+  const { license: declaredId, plus, exception } = spdxParsedValue;
+
+  return {
+    kind: 'license',
+    id: normalizeLicenseId(declaredId, plus === true),
+    declaredId,
+    ...(plus && { plus: true }),
+    ...(exception && { exception }),
+  };
+}
+
+/**
+ * Upgrades a declared License Identifier to its canonical form:
+ * - with `+`, to the `-or-later` identifier when one exists;
+ * - a deprecated identifier, to its `-only` identifier when one exists.
+ */
+function normalizeLicenseId(declaredId: string, plus: boolean): string {
+  if (plus && SPDX_LICENSE_IDS.has(`${declaredId}-or-later`)) {
+    return `${declaredId}-or-later`;
+  }
+
+  if (!plus && DEPRECATED_SPDX_LICENSE_IDS.has(declaredId) && SPDX_LICENSE_IDS.has(`${declaredId}-only`)) {
+    return `${declaredId}-only`;
+  }
+
+  return declaredId;
+}
+
+/**
+ * Collects the License Identifiers mentioned in a License Expression, regardless of how they are combined.
+ *
+ * @param expression the License Expression to flatten
+ * @returns the License Identifiers in order of first appearance, without duplicates; empty for an Unknown License
+ * @example
+ * collectLicenseIds(parseLicenseExpression('(MIT OR ISC) AND (MIT OR Apache-2.0)'));
+ * // ['MIT', 'ISC', 'Apache-2.0']
+ */
+export function collectLicenseIds(expression: LicenseExpression): string[] {
+  switch (expression.kind) {
+    case 'license':
+      return [expression.id];
+    case 'and':
+    case 'or':
+      return [...new Set([...collectLicenseIds(expression.left), ...collectLicenseIds(expression.right)])];
+    case 'unknown':
+      return [];
+  }
+}
+
+/**
+ * Renders a License Expression to a string, following the SPDX License Expression syntax.
+ *
+ * Adds only the parentheses required by SPDX precedence and by the right-nesting of operator chains,
+ * so that parsing the result gives back the same tree. An Unknown License renders as its original value
+ * (or `unknown` when absent) and is not expected to parse back to the same tree.
+ *
+ * @param expression the License Expression to render
+ * @returns the rendered License Expression
+ * @example
+ * renderLicenseExpression(parseLicenseExpression('(MIT OR Apache-2.0) AND ISC'));
+ * // '(MIT OR Apache-2.0) AND ISC'
+ */
+export function renderLicenseExpression(expression: LicenseExpression): string {
+  switch (expression.kind) {
+    case 'unknown':
+      return expression.raw ?? 'unknown';
+    case 'or':
+    case 'and': {
+      const left = renderOperand(expression.left, expression.kind, 'left');
+      const right = renderOperand(expression.right, expression.kind, 'right');
+
+      return `${left} ${expression.kind.toUpperCase()} ${right}`;
+    }
+
+    case 'license':
+      return renderLicenseLeaf(expression);
+  }
+}
+
+function renderLicenseLeaf(leaf: Extract<LicenseExpression, { kind: 'license' }>): string {
+  // `+` is already absorbed into an `-or-later` identifier
+  const plus = leaf.plus && !leaf.id.endsWith('-or-later') ? '+' : '';
+  const exception = leaf.exception ? ` WITH ${leaf.exception}` : '';
+
+  return `${leaf.id}${plus}${exception}`;
+}
+
+function renderOperand(
+  operand: LicenseExpression,
+  parentKind: 'or' | 'and',
+  operandPosition: 'left' | 'right',
+): string {
+  const rendered = renderLicenseExpression(operand);
+
+  return shouldAddParenthesis(operand, parentKind, operandPosition) ? `(${rendered})` : rendered;
+}
+
+function shouldAddParenthesis(
+  childExpression: LicenseExpression,
+  parentKind: 'or' | 'and',
+  childPosition: 'left' | 'right',
+): boolean {
+  return (
+    (parentKind === 'and' && childExpression.kind === 'or') ||
+    (childPosition === 'left' && parentKind === childExpression.kind)
+  );
+}

package/src/node/common.ts

@@ -1,25 +1,150 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import glob from 'glob';
+import { glob } from 'glob';
 
+import { collectLicenseIds, parseLicenseExpression } from '../licenses';
 import type {
   AboutLibrariesLibraryJsonPayload,
   AboutLibrariesLicenseJsonPayload,
   AboutLibrariesLikePackageInfo,
   AggregatedLicensesMapping,
   DependencyType,
+  License,
   LicensePlistPayload,
   ParentPackageInfo,
+  ScanDependenciesOptions,
   ScanPackageCallContext,
   ScanPackageOptionsFactory,
 } from '../types';
 import { YamlUtils } from '../utils';
 
+import { mergeLicensesMappings } from './mergeLicensesMappings';
 import { PackageUtils } from './utils';
 
 type InternalScanGroupSpecifier = { packages: [depName: string, depVersion: string][]; dependencyType: DependencyType };
 
+/**
+ * Finds the root directory of the package that a directory belongs to - the closest directory (itself or a parent)
+ * containing a `package.json` with a `name` field. Nested `package.json` files without a name
+ * (e.g. `lib/commonjs/package.json` containing only `{ "type": "commonjs" }`) are skipped.
+ *
+ * Works for packages installed in `node_modules` as well as for workspace / linked packages,
+ * which are referenced by their real path (outside `node_modules`)
+ *
+ * @param startDir Absolute path to the directory to start the search from, e.g. the directory of a module file
+ * @returns Path to the package root directory or `null` if the directory does not belong to any named package
+ */
+export function findPackageRoot(startDir: string): string | null {
+  let dir = startDir;
+
+  // `path.dirname` of the filesystem root returns the root itself, which ends the loop
+  while (path.dirname(dir) !== dir) {
+    if (hasNamedPackageJson(dir)) {
+      return dir;
+    }
+
+    dir = path.dirname(dir);
+  }
+
+  return hasNamedPackageJson(dir) ? dir : null;
+}
+
+/**
+ * Checks whether a directory contains a valid `package.json` with a `name` field
+ *
+ * @param dir Path to the directory to check
+ */
+function hasNamedPackageJson(dir: string): boolean {
+  const packageJsonPath = path.join(dir, 'package.json');
+
+  if (!fs.existsSync(packageJsonPath)) {
+    return false;
+  }
+
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, { encoding: 'utf-8' }));
+
+    return Boolean(packageJson.name);
+  } catch {
+    // invalid package.json - treat it as not a package root
+    return false;
+  }
+}
+
+/**
+ * Collects license information for a given list of package directories, e.g. the packages found in the Metro dependency graph.
+ * Unlike {@link scanDependencies}, it does not scan dependencies of the packages - the list is expected to be complete.
+ *
+ * @param packageRoots Paths to the root directories of the packages (directories containing `package.json`)
+ * @returns Aggregated licenses object containing the given packages and their license information
+ */
+export function scanPackageRoots(packageRoots: string[]): AggregatedLicensesMapping {
+  const result: AggregatedLicensesMapping = {};
+
+  for (const packageRoot of packageRoots) {
+    const packageJsonPath = path.join(packageRoot, 'package.json');
+
+    if (!fs.existsSync(packageJsonPath)) {
+      console.warn(`[react-native-legal] skipping ${packageRoot} could not find package.json`);
+      continue;
+    }
+
+    try {
+      const packageJson = require(path.resolve(packageJsonPath));
+
+      if (!packageJson.name || packageJson.private === true) {
+        continue;
+      }
+
+      const licenseInfo = readPackageLicenseInfo(packageJsonPath);
+
+      result[`${licenseInfo.name}@${licenseInfo.version}`] = {
+        ...licenseInfo,
+        dependencyType: 'dependency',
+        requiredVersion: licenseInfo.version,
+        parentPackages: [],
+      };
+    } catch (error) {
+      console.warn(`[react-native-legal] could not process package.json in ${packageRoot}`);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Reads license information of a single package, based only on its own files
+ * (package.json and LICENSE file), without any context of how the package was found
+ *
+ * @param packageJsonPath Path to the package.json file of the package
+ */
+function readPackageLicenseInfo(
+  packageJsonPath: string,
+): Pick<
+  License,
+  'name' | 'author' | 'description' | 'rawLicense' | 'license' | 'licenseIds' | 'licenseFiles' | 'url' | 'version'
+> {
+  const packageJson = require(path.resolve(packageJsonPath));
+
+  const rawLicense = PackageUtils.parseLicenseField(packageJson) ?? null;
+  const license = parseLicenseExpression(rawLicense);
+  const licenseIds = collectLicenseIds(license);
+  const licenseFiles = PackageUtils.readLicenseFiles(path.dirname(packageJsonPath), licenseIds);
+
+  return {
+    name: packageJson.name,
+    author: PackageUtils.parseAuthorField(packageJson),
+    description: packageJson.description,
+    rawLicense,
+    license,
+    licenseIds,
+    licenseFiles,
+    url: PackageUtils.parseRepositoryFieldToUrl(packageJson),
+    version: packageJson.version,
+  };
+}
+
 /**
  * Scans a single package and its dependencies for license information
  *
@@ -43,7 +168,8 @@ function scanPackage(
     dependencyType,
     parentPackageRequiredVersion,
     parentPackageResolvedVersion,
-  }: ScanPackageCallContext,
+    projectRoot,
+  }: InternalScanPackageCallContext,
 ) {
   const requiredVersionPackageKey = `${packageName}@${requiredVersion}`;
 
@@ -62,7 +188,7 @@ function scanPackage(
   processedPackages.add(requiredVersionPackageKey);
 
   try {
-    const localPackageJsonPath = PackageUtils.getPackageJsonPath(packageName, parentPackageRoot);
+    const localPackageJsonPath = PackageUtils.getPackageJsonPath(packageName, parentPackageRoot, projectRoot);
 
     if (!localPackageJsonPath) {
       // do not warn if the package is an optional dependency, it's normal it may not be installed
@@ -76,14 +202,6 @@ function scanPackage(
     const localPackageJson = require(path.resolve(localPackageJsonPath));
 
     if (localPackageJson.private !== true) {
-      const licenseFiles = glob.sync('LICEN{S,C}E{.md,}', {
-        cwd: path.dirname(localPackageJsonPath),
-        absolute: true,
-        nocase: true,
-        nodir: true,
-        ignore: '**/{__tests__,__fixtures__,__mocks__}/**',
-      });
-
       const resolvedVersionPackageKey = `${packageName}@${localPackageJson.version}`;
 
       let parentPackageInfo: ParentPackageInfo | undefined;
@@ -102,14 +220,8 @@ function scanPackage(
         ];
       } else {
         result[resolvedVersionPackageKey] = {
+          ...readPackageLicenseInfo(localPackageJsonPath),
           name: packageName,
-          author: PackageUtils.parseAuthorField(localPackageJson),
-          content: licenseFiles?.[0] ? fs.readFileSync(licenseFiles[0], { encoding: 'utf-8' }) : undefined,
-          file: licenseFiles?.[0] ? licenseFiles[0] : undefined,
-          description: localPackageJson.description,
-          type: PackageUtils.parseLicenseField(localPackageJson),
-          url: PackageUtils.parseRepositoryFieldToUrl(localPackageJson),
-          version: localPackageJson.version,
           requiredVersion,
           parentPackages: parentPackageInfo ? [parentPackageInfo] : [],
           parentPackageRequiredVersion,
@@ -159,6 +271,7 @@ function scanPackage(
           parentPackageName: packageName,
           parentPackageRequiredVersion: requiredVersion,
           parentPackageResolvedVersion: localPackageJson.version,
+          projectRoot,
         });
       }
     }
@@ -169,22 +282,63 @@ function scanPackage(
 
 type DependencyMapping = Record<string, string>;
 type MaybeDependencyMapping = DependencyMapping | undefined;
+type InternalScanPackageCallContext = ScanPackageCallContext & { projectRoot: string };
 
 /**
  * Scans `package.json` and searches for all packages under `dependencies` field. Supports monorepo projects.
  *
  * @param appPackageJsonPath Path to the `package.json` file of the application
  * @param scanOptionsFactory Factory function to create scan options for dependencies; defaults to {@link PackageUtils.legacyDefaultScanPackageOptionsFactory}
+ * @param options Additional options, see {@link ScanDependenciesOptions}
  * @returns Aggregated licenses object containing all scanned dependencies and their license information
  */
 export function scanDependencies(
   appPackageJsonPath: string,
   scanOptionsFactory: ScanPackageOptionsFactory = PackageUtils.legacyDefaultScanPackageOptionsFactory,
+  options: ScanDependenciesOptions = {},
+): AggregatedLicensesMapping {
+  const { additionalProjectRoots = [] } = options;
+
+  if (
+    !Array.isArray(additionalProjectRoots) ||
+    additionalProjectRoots.some(
+      (additionalProjectRoot) => typeof additionalProjectRoot !== 'string' || !additionalProjectRoot,
+    )
+  ) {
+    throw new TypeError('[react-native-legal] additionalProjectRoots must be an array of non-empty paths');
+  }
+
+  const appRoot = fs.realpathSync(path.dirname(path.resolve(appPackageJsonPath)));
+  const additionalPackageJsonPaths = additionalProjectRoots.map((additionalProjectRoot) => {
+    const packageJsonPath = path.join(path.resolve(appRoot, additionalProjectRoot), 'package.json');
+
+    if (!fs.existsSync(packageJsonPath)) {
+      throw new Error(
+        `[react-native-legal] additional project root "${additionalProjectRoot}" is not a directory with a package.json (${packageJsonPath} not found)`,
+      );
+    }
+
+    return packageJsonPath;
+  });
+
+  return mergeLicensesMappings(
+    scanProjectDependencies(appPackageJsonPath, scanOptionsFactory),
+    ...additionalPackageJsonPaths.map((packageJsonPath) =>
+      scanProjectDependencies(packageJsonPath, scanOptionsFactory),
+    ),
+  );
+}
+
+function scanProjectDependencies(
+  projectPackageJsonPath: string,
+  scanOptionsFactory: ScanPackageOptionsFactory,
 ): AggregatedLicensesMapping {
-  const appPackageJson = require(path.resolve(appPackageJsonPath));
-  const dependencies: MaybeDependencyMapping = appPackageJson.dependencies;
-  const devDependencies: MaybeDependencyMapping = appPackageJson.devDependencies;
-  const optionalDependencies: MaybeDependencyMapping = appPackageJson.optionalDependencies;
+  const projectPackageJson = require(path.resolve(projectPackageJsonPath));
+  // real path, so that `node_modules` directories of the project's parent directories are found even if the project is reached through a symlink
+  const projectRoot = fs.realpathSync(path.dirname(path.resolve(projectPackageJsonPath)));
+  const dependencies: MaybeDependencyMapping = projectPackageJson.dependencies;
+  const devDependencies: MaybeDependencyMapping = projectPackageJson.devDependencies;
+  const optionalDependencies: MaybeDependencyMapping = projectPackageJson.optionalDependencies;
   const result: AggregatedLicensesMapping = {};
   const processedPackages = new Set<string>();
 
@@ -208,6 +362,7 @@ export function scanDependencies(
     for (const [depName, depVersion] of packages) {
       scanPackage(depName, depVersion as string, processedPackages, result, scanOptionsFactory, {
         dependencyType,
+        projectRoot,
       });
     }
   }
@@ -236,13 +391,17 @@ export function generateLicensePlistNPMOutput(licenses: AggregatedLicensesMappin
       renames[normalizedPackageNameWithVersion] = license.name;
     }
 
-    const relativeLicenseFile = license.file ? path.relative(iosProjectPath, license.file) : undefined;
+    // LicensePlist holds one `file`/`body` per package: a single license file is referenced directly,
+    // otherwise every license text is concatenated into the body under a per-license heading
+    const singleLicenseFile = license.licenseFiles.length === 1 ? license.licenseFiles[0].file : undefined;
 
     return {
       name: normalizedPackageNameWithVersion,
       version: license.version,
       ...(license.url && { source: license.url }),
-      ...(license.file ? { file: relativeLicenseFile } : { body: license.content ?? license.type ?? 'UNKNOWN' }),
+      ...(singleLicenseFile
+        ? { file: path.relative(iosProjectPath, singleLicenseFile) }
+        : { body: PackageUtils.buildLicensePlistBody(license) }),
     } as LicensePlistPayload;
   });
 
@@ -341,45 +500,34 @@ export function writeLicensePlistNPMOutput(
  * @see {@link writeAboutLibrariesNPMOutput}
  */
 export function generateAboutLibrariesNPMOutput(licenses: AggregatedLicensesMapping): AboutLibrariesLikePackageInfo[] {
-  return Object.entries(licenses)
-    .map(([packageKey, license]) => {
-      return {
-        artifactVersion: license.version,
-        content: license.content ?? '',
-        description: license.description ?? '',
-        developers: [{ name: license.author ?? '', organisationUrl: '' }],
-        licenses: [PackageUtils.prepareAboutLibrariesLicenseField(license)],
-        name: license.name,
-        tag: '',
-        type: license.type,
-        uniqueId: PackageUtils.normalizePackageName(packageKey),
-        website: license.url,
-      };
-    })
-    .map((jsonPayload) => {
-      const libraryJsonPayload: AboutLibrariesLibraryJsonPayload = {
-        artifactVersion: jsonPayload.artifactVersion,
-        description: jsonPayload.description,
-        developers: jsonPayload.developers,
-        licenses: jsonPayload.licenses,
-        name: jsonPayload.name,
-        tag: jsonPayload.tag,
-        uniqueId: jsonPayload.uniqueId,
-        website: jsonPayload.website,
-      };
-      const licenseJsonPayload: AboutLibrariesLicenseJsonPayload = {
-        content: jsonPayload.content,
-        hash: jsonPayload.licenses[0],
-        name: jsonPayload.type ?? '',
-        url: '',
-      };
+  return Object.entries(licenses).map(([packageKey, license]) => {
+    const uniqueId = PackageUtils.normalizePackageName(packageKey);
+    const licenseJsonPayloads: AboutLibrariesLicenseJsonPayload[] = PackageUtils.prepareAboutLibrariesLicenses(
+      license,
+    ).map(({ name, content }) => ({
+      content,
+      hash: PackageUtils.prepareAboutLibrariesLicenseField(name, content),
+      name,
+      url: '',
+    }));
+
+    const libraryJsonPayload: AboutLibrariesLibraryJsonPayload = {
+      artifactVersion: license.version,
+      description: license.description ?? '',
+      developers: [{ name: license.author ?? '', organisationUrl: '' }],
+      licenses: licenseJsonPayloads.map(({ hash }) => hash),
+      name: license.name,
+      tag: '',
+      uniqueId,
+      website: license.url,
+    };
 
-      return {
-        normalizedPackageNameWithVersion: jsonPayload.uniqueId,
-        libraryJsonPayload,
-        licenseJsonPayload,
-      };
-    });
+    return {
+      normalizedPackageNameWithVersion: uniqueId,
+      libraryJsonPayload,
+      licenseJsonPayloads,
+    };
+  });
 }
 
 /**
@@ -427,17 +575,20 @@ export function writeAboutLibrariesNPMOutput(
     aboutLibrariesLikeOutput = generateAboutLibrariesNPMOutput(licenses);
   }
 
-  aboutLibrariesLikeOutput.forEach(({ normalizedPackageNameWithVersion, libraryJsonPayload, licenseJsonPayload }) => {
+  aboutLibrariesLikeOutput.forEach(({ normalizedPackageNameWithVersion, libraryJsonPayload, licenseJsonPayloads }) => {
     const libraryJsonFilePath = path.join(
       aboutLibrariesConfigLibrariesDirPath,
       `${normalizedPackageNameWithVersion}.json`,
     );
-    const licenseJsonFilePath = path.join(aboutLibrariesConfigLicensesDirPath, `${licenseJsonPayload.hash}.json`);
 
     fs.writeFileSync(libraryJsonFilePath, JSON.stringify(libraryJsonPayload));
 
-    if (!fs.existsSync(licenseJsonFilePath)) {
-      fs.writeFileSync(licenseJsonFilePath, JSON.stringify(licenseJsonPayload));
+    for (const licenseJsonPayload of licenseJsonPayloads) {
+      const licenseJsonFilePath = path.join(aboutLibrariesConfigLicensesDirPath, `${licenseJsonPayload.hash}.json`);
+
+      if (!fs.existsSync(licenseJsonFilePath)) {
+        fs.writeFileSync(licenseJsonFilePath, JSON.stringify(licenseJsonPayload));
+      }
     }
   });
 }

package/src/node/index.ts

@@ -1,3 +1,4 @@
 export * from './common';
+export * from './mergeLicensesMappings';
 export * from './utils';
 export * from '../';

package/src/node/mergeLicensesMappings.ts

@@ -0,0 +1,32 @@
+import type { AggregatedLicensesMapping } from '../types';
+
+import { MiscUtils } from './utils';
+
+/**
+ * Combines licenses mappings, e.g. from scans of several project roots, into one.
+ *
+ * @param mappings Licenses mappings to combine; a package version present in several of them keeps the entry from the first one, with the parent packages of all of them
+ * @returns A new licenses mapping that shares no objects with the mappings passed in
+ */
+export function mergeLicensesMappings(...mappings: AggregatedLicensesMapping[]): AggregatedLicensesMapping {
+  const result: AggregatedLicensesMapping = {};
+
+  for (const mapping of mappings) {
+    for (const [packageKey, license] of Object.entries(mapping)) {
+      const existingLicense = result[packageKey];
+
+      if (!existingLicense) {
+        result[packageKey] = structuredClone({ ...license, parentPackages: license.parentPackages ?? [] });
+        continue;
+      }
+
+      for (const parentPackage of license.parentPackages ?? []) {
+        if (!MiscUtils.arrayIncludesObject(existingLicense.parentPackages, parentPackage)) {
+          existingLicense.parentPackages.push(structuredClone(parentPackage));
+        }
+      }
+    }
+  }
+
+  return result;
+}