@callstack/licenses 0.3.2 → 1.0.0

package/build/node/utils/packageUtils.js

@@ -3,40 +3,56 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.legacyDefaultScanPackageOptionsFactory = void 0;
+exports.legacyDefaultScanPackageOptionsFactory = exports.readLicenseFiles = exports.buildLicensePlistBody = exports.prepareAboutLibrariesLicenses = exports.prepareAboutLibrariesLicenseField = void 0;
 exports.getPackageJsonPath = getPackageJsonPath;
 exports.resolvePackageJsonFromEntry = resolvePackageJsonFromEntry;
 exports.findPackageRoot = findPackageRoot;
 exports.normalizePackageName = normalizePackageName;
-exports.prepareAboutLibrariesLicenseField = prepareAboutLibrariesLicenseField;
 exports.parseAuthorField = parseAuthorField;
 exports.parseLicenseField = parseLicenseField;
 exports.parseRepositoryFieldToUrl = parseRepositoryFieldToUrl;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const repositoryUtils_1 = require("../../utils/repositoryUtils");
-const miscUtils_1 = require("./miscUtils");
-function getPackageJsonPath(dependency, root) {
+var aboutLibrariesLicenses_1 = require("./aboutLibrariesLicenses");
+Object.defineProperty(exports, "prepareAboutLibrariesLicenseField", { enumerable: true, get: function () { return aboutLibrariesLicenses_1.prepareAboutLibrariesLicenseField; } });
+Object.defineProperty(exports, "prepareAboutLibrariesLicenses", { enumerable: true, get: function () { return aboutLibrariesLicenses_1.prepareAboutLibrariesLicenses; } });
+var licensePlistBody_1 = require("./licensePlistBody");
+Object.defineProperty(exports, "buildLicensePlistBody", { enumerable: true, get: function () { return licensePlistBody_1.buildLicensePlistBody; } });
+var licenseFiles_1 = require("./licenseFiles");
+Object.defineProperty(exports, "readLicenseFiles", { enumerable: true, get: function () { return licenseFiles_1.readLicenseFiles; } });
+function getPackageJsonPath(dependency, root, projectRoot = process.cwd()) {
     const rootsToSearch = [
         ...(root ? [root] : []), // provided for purpose of nested node_modules resolution inside a package dir, in a subdirectory inside the root node_modules dir
-        process.cwd(), // fallback - root node_modules directory home
+        projectRoot, // fallback - root node_modules directory home
     ]; // in order of priority (left-to-right)
     try {
         return require.resolve(`${dependency}/package.json`, { paths: rootsToSearch });
     }
     catch (error) {
         for (const root of rootsToSearch) {
-            const pkgJsonInNodeModules = path_1.default.join(root, 'node_modules', dependency, 'package.json');
-            if (fs_1.default.existsSync(pkgJsonInNodeModules)) {
+            const pkgJsonInNodeModules = findPackageJsonInNodeModules(dependency, root);
+            if (pkgJsonInNodeModules) {
                 return pkgJsonInNodeModules;
             }
         }
-        return resolvePackageJsonFromEntry(dependency); // final fallback
+        return resolvePackageJsonFromEntry(dependency, rootsToSearch); // final fallback
     }
 }
-function resolvePackageJsonFromEntry(dependency) {
+function findPackageJsonInNodeModules(dependency, startDir) {
+    for (let currentDir = startDir;; currentDir = path_1.default.dirname(currentDir)) {
+        if (path_1.default.basename(currentDir) !== 'node_modules') {
+            const pkgJsonInNodeModules = path_1.default.join(currentDir, 'node_modules', dependency, 'package.json');
+            if (fs_1.default.existsSync(pkgJsonInNodeModules))
+                return fs_1.default.realpathSync(pkgJsonInNodeModules);
+        }
+        if (currentDir === path_1.default.dirname(currentDir))
+            return null;
+    }
+}
+function resolvePackageJsonFromEntry(dependency, paths) {
     try {
-        const entryPath = require.resolve(dependency);
+        const entryPath = require.resolve(dependency, paths ? { paths } : undefined);
         const packageDir = findPackageRoot(entryPath);
         if (!packageDir)
             return null;
@@ -58,18 +74,6 @@ function findPackageRoot(entryPath) {
 function normalizePackageName(packageName) {
     return packageName.replace('/', '_');
 }
-function prepareAboutLibrariesLicenseField(license) {
-    if (!license.type) {
-        return '';
-    }
-    // The returned value is used as a filename under `android/config/licenses/`.
-    // Legacy/compound SPDX expressions like `MIT/X11` or `(MIT OR Apache-2.0)` would
-    // otherwise produce paths containing `/`, `(` or spaces, which causes the writer
-    // to either fail with ENOENT (when a `/` is interpreted as a subdirectory) or
-    // to produce names that are invalid on some filesystems.
-    const sanitizedType = license.type.replace(/[^A-Za-z0-9._-]/g, '_');
-    return `${sanitizedType}_${(0, miscUtils_1.sha512)(license.content ?? sanitizedType)}`;
-}
 function parseAuthorField(json) {
     if (typeof json.author === 'object' && typeof json.author.name === 'string') {
         return json.author.name;
@@ -78,13 +82,21 @@ function parseAuthorField(json) {
         return json.author;
     }
 }
+/**
+ * Reads the Raw License from package.json: the `license` string, the legacy `license: { type }` object,
+ * or the legacy `licenses: [{ type }, …]` array, whose types are joined with ` OR `.
+ */
 function parseLicenseField(json) {
-    if (typeof json.license === 'object' && typeof json.license.type === 'string') {
+    if (typeof json.license === 'object' && typeof json.license?.type === 'string') {
         return json.license.type;
     }
     if (typeof json.license === 'string') {
         return json.license;
     }
+    if (Array.isArray(json.licenses)) {
+        const types = json.licenses.flatMap((entry) => typeof entry?.type === 'string' && entry.type.trim() !== '' ? [entry.type] : []);
+        return types.length > 0 ? types.join(' OR ') : undefined;
+    }
 }
 function parseRepositoryFieldToUrl(json) {
     if (typeof json.repository === 'object' && typeof json.repository.url === 'string') {

package/build/types/AboutLibrariesLikePackageInfo.d.ts

@@ -3,5 +3,5 @@ import type { AboutLibrariesLicenseJsonPayload } from './AboutLibrariesLicenseJs
 export type AboutLibrariesLikePackageInfo = {
     normalizedPackageNameWithVersion: string;
     libraryJsonPayload: AboutLibrariesLibraryJsonPayload;
-    licenseJsonPayload: AboutLibrariesLicenseJsonPayload;
+    licenseJsonPayloads: AboutLibrariesLicenseJsonPayload[];
 };

package/build/types/License.d.ts

@@ -1,4 +1,6 @@
 import type { DependencyType } from './DependencyType';
+import type { LicenseExpression } from './LicenseExpression';
+import type { LicenseFile } from './LicenseFile';
 import type { ParentPackageInfo } from './ParentPackageInfo';
 import type { ScanPackageCallContext } from './ScanPackageCallContext';
 export type License = {
@@ -6,14 +8,20 @@ export type License = {
     name: string;
     /** Package author */
     author?: string;
-    /** Package license contents */
-    content?: string;
     /** Package description */
     description?: string;
-    /** License file path */
-    file?: string;
-    /** License type */
-    type?: string;
+    /**
+     * Raw License: the license declaration exactly as written in package.json;
+     * for the legacy `licenses: [{ type }]` array, the types joined with ` OR `;
+     * `null` if the package declares no license
+     */
+    rawLicense: string | null;
+    /** Parsed License Expression of {@link License.rawLicense} */
+    license: LicenseExpression;
+    /** Canonical SPDX License Identifiers found in {@link License.license}; empty for an Unknown License */
+    licenseIds: string[];
+    /** Every license file found in the package root, each linked to its License Identifier where unambiguous */
+    licenseFiles: LicenseFile[];
     /** Package repository URL */
     url?: string;
     /** The resolved version that was actually installed */

package/build/types/LicenseAnalysisResult.d.ts

@@ -1,5 +1,12 @@
 import type { LicenseCategory } from '../licenses/LicenseCategory';
 import type { LicenseStats } from './LicenseStats';
 export interface LicenseAnalysisResult extends LicenseStats {
+    /**
+     * Mapping of package key (`<package-name>@<package-version>`) to the License Category of that package
+     */
     categorizedLicenses: Record<string, LicenseCategory>;
+    /**
+     * Mapping of rendered License Expression to its License Category; has the same keys as {@link LicenseStats.byLicense}
+     */
+    categoryByLicense: Record<string, LicenseCategory>;
 }

package/build/types/LicenseExpression.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Structured meaning of a package's Raw License, following the SPDX License Expression
+ * syntax (SPDX spec v3.0.1, Annex B).
+ *
+ * The tree is binary: `A OR B OR C` is represented as `A OR (B OR C)`.
+ *
+ * @see https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/
+ */
+export type LicenseExpression = 
+/**
+ * A single license, identified by its SPDX License Identifier (e.g. `MIT`).
+ * - `id` is canonical: deprecated identifiers are upgraded and `+` is absorbed into `-or-later` when such an identifier exists
+ * - `declaredId` and `plus` record what was written
+ * - `exception` is the License Exception attached with `WITH`
+ */
+{
+    kind: 'license';
+    id: string;
+    declaredId: string;
+    plus?: boolean;
+    exception?: string;
+}
+/** Dual License: the licensee may comply with either operand */
+ | {
+    kind: 'or';
+    left: LicenseExpression;
+    right: LicenseExpression;
+}
+/** Both operands apply and must be complied with simultaneously */
+ | {
+    kind: 'and';
+    left: LicenseExpression;
+    right: LicenseExpression;
+}
+/** Unknown License: missing, unparseable, or not a license grant; `raw` keeps the original value */
+ | {
+    kind: 'unknown';
+    raw: string | null;
+};

package/build/types/LicenseExpression.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/LicenseFile.d.ts

@@ -0,0 +1,8 @@
+export type LicenseFile = {
+    /** License file path */
+    file: string;
+    /** License file contents */
+    content: string;
+    /** License Identifier the file was unambiguously linked to by its name, if any */
+    licenseId?: string;
+};

package/build/types/LicenseFile.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/LicenseStats.d.ts

@@ -9,7 +9,7 @@ export interface LicenseStats {
      */
     byCategory: Record<LicenseCategory, number>;
     /**
-     * Mapping of license name to count of packages with that license
+     * Mapping of rendered License Expression to count of packages with that expression
      */
     byLicense: Record<string, number>;
     /**

package/build/types/ScanDependenciesOptions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Additional options for scanning dependencies of a project
+ */
+export type ScanDependenciesOptions = {
+    /**
+     * Paths to other project directories whose dependencies are scanned too,
+     * e.g. monorepo workspaces the app does not depend on;
+     * relative paths are resolved against the real directory (with symlinks resolved) of the scanned `package.json`;
+     * each of them must be a directory with a `package.json`, otherwise an error is thrown
+     */
+    additionalProjectRoots?: readonly string[];
+};

package/build/types/ScanDependenciesOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/index.d.ts

@@ -5,8 +5,11 @@ export * from './AboutLibrariesLicenseJsonPayload';
 export * from './LicensePlistPayload';
 export * from './AboutLibrariesLikePackageInfo';
 export * from './ScanPackageOptions';
+export * from './ScanDependenciesOptions';
 export * from './ScanPackageCallContext';
 export * from './DependencyType';
 export * from './ParentPackageInfo';
 export * from './LicenseAnalysisResult';
 export * from './LicenseStats';
+export * from './LicenseExpression';
+export * from './LicenseFile';

package/build/types/index.js

@@ -21,8 +21,11 @@ __exportStar(require("./AboutLibrariesLicenseJsonPayload"), exports);
 __exportStar(require("./LicensePlistPayload"), exports);
 __exportStar(require("./AboutLibrariesLikePackageInfo"), exports);
 __exportStar(require("./ScanPackageOptions"), exports);
+__exportStar(require("./ScanDependenciesOptions"), exports);
 __exportStar(require("./ScanPackageCallContext"), exports);
 __exportStar(require("./DependencyType"), exports);
 __exportStar(require("./ParentPackageInfo"), exports);
 __exportStar(require("./LicenseAnalysisResult"), exports);
 __exportStar(require("./LicenseStats"), exports);
+__exportStar(require("./LicenseExpression"), exports);
+__exportStar(require("./LicenseFile"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@callstack/licenses",
-  "version": "0.3.2",
+  "version": "1.0.0",
   "description": "API package that exposes functionalities for programmatic scanning of licenses in Node.js projects.",
   "browser": "./build/index.js",
   "main": "./build/node/index.js",
@@ -64,14 +64,17 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "glob": "^7.1.3"
+    "glob": "^13.0.0",
+    "spdx-exceptions": "^2.1.0",
+    "spdx-expression-parse": "^5.0.0",
+    "spdx-license-ids": "^3.0.24"
   },
   "devDependencies": {
-    "@babel/core": "7.27.4",
-    "@babel/preset-env": "7.27.2",
-    "@babel/preset-typescript": "7.27.1",
-    "@types/glob": "^8.1.0",
+    "@babel/core": "^7.29.7",
+    "@babel/preset-env": "^7.29.7",
+    "@babel/preset-typescript": "^7.29.7",
     "@types/jest": "^29.5.5",
+    "@types/spdx-expression-parse": "^4.0.0",
     "babel-jest": "^29.7.0",
     "jest": "^29.7.0",
     "rimraf": "^6.0.1",

package/src/constants/licenses.ts

@@ -1,20 +1,27 @@
 /**
  * https://spdx.org/licenses
+ *
+ * Canonical License Identifiers, as produced by parsing a License Expression: deprecated identifiers are upgraded
+ * (`GPL-2.0` becomes `GPL-2.0-only`) and `+` is absorbed (`GPL-2.0+` becomes `GPL-2.0-or-later`), so neither form is listed.
+ * The exception are deprecated identifiers with a built-in License Exception, which have no `-only` form.
  */
 
 export const STRONG_COPYLEFT_LICENSES = new Set([
-  'GPL',
-  'GPL-1.0',
-  'GPL-1.0+',
-  'GPL-2.0',
-  'GPL-2.0+',
+  'GPL-1.0-only',
+  'GPL-1.0-or-later',
   'GPL-2.0-only',
   'GPL-2.0-or-later',
-  'GPL-3.0',
-  'GPL-3.0+',
+  'GPL-2.0-with-autoconf-exception',
+  'GPL-2.0-with-bison-exception',
+  'GPL-2.0-with-classpath-exception',
+  'GPL-2.0-with-font-exception',
+  'GPL-2.0-with-GCC-exception',
+  'GPL-3.0-with-autoconf-exception',
+  'GPL-3.0-with-GCC-exception',
   'GPL-3.0-only',
   'GPL-3.0-or-later',
-  'AGPL-3.0',
+  'AGPL-1.0-only',
+  'AGPL-1.0-or-later',
   'AGPL-3.0-only',
   'AGPL-3.0-or-later',
   'EUPL-1.0',
@@ -32,17 +39,10 @@ export const WEAK_COPYLEFT_LICENSES = new Set([
   'CDDL-1.1',
   'EPL-1.0',
   'EPL-2.0',
-  'LGPL',
-  'LGPL-2.0',
-  'LGPL-2.0+',
   'LGPL-2.0-only',
   'LGPL-2.0-or-later',
-  'LGPL-2.1',
-  'LGPL-2.1+',
   'LGPL-2.1-only',
   'LGPL-2.1-or-later',
-  'LGPL-3.0',
-  'LGPL-3.0+',
   'LGPL-3.0-only',
   'LGPL-3.0-or-later',
   'MPL-1.1',

package/src/licenses/OrPolicy.ts

@@ -0,0 +1,23 @@
+/**
+ * Enumerates all valid OR Policy values
+ *
+ * @see {@link OrPolicy}
+ */
+export const validOrPolicies = ['most-restrictive', 'least-restrictive'] as const;
+
+/**
+ * Rule for which operand of a Dual License (`A OR B`) determines its License Category:
+ * - 'most-restrictive' (the most restrictive operand)
+ * - 'least-restrictive' (the least restrictive operand; matches SPDX's "choice" meaning of OR)
+ *
+ * Never applies to AND, which always takes the most restrictive operand.
+ */
+export type OrPolicy = (typeof validOrPolicies)[number];
+
+/**
+ * OR Policy used when none is given: a Dual License takes its most restrictive operand,
+ * as a conservative default for compliance checks.
+ *
+ * @see {@link OrPolicy}
+ */
+export const DEFAULT_OR_POLICY: OrPolicy = 'most-restrictive';

package/src/licenses/index.ts

@@ -1,3 +1,6 @@
 export * from './LicenseCategory';
 export * from './descriptions';
 export * from './licenseAnalysis';
+export * from './OrPolicy';
+export * from './licenseExpression';
+export * from './licenseClassification';

package/src/licenses/licenseAnalysis.ts

@@ -1,40 +1,27 @@
-import { STRONG_COPYLEFT_LICENSES_LOWERCASE, WEAK_COPYLEFT_LICENSES_LOWERCASE } from '../constants/licenses';
 import type { AggregatedLicensesMapping } from '../types';
 import type { LicenseAnalysisResult } from '../types/LicenseAnalysisResult';
 
 import { LicenseCategory } from './LicenseCategory';
+import type { OrPolicy } from './OrPolicy';
+import { DEFAULT_OR_POLICY } from './OrPolicy';
 import { getGraphStateInfo } from './descriptions';
-
-/**
- * Categorizes a license based on its copyleft characteristics.
- * @param licenseType the license type
- * @returns the license category
- */
-export function categorizeLicense(licenseType?: string): LicenseCategory {
-  if (!licenseType || licenseType === 'unknown') {
-    return LicenseCategory.UNKNOWN;
-  }
-
-  // check for strong copyleft licenses
-  if (STRONG_COPYLEFT_LICENSES_LOWERCASE.has(licenseType.toLowerCase())) {
-    return LicenseCategory.STRONG_COPYLEFT;
-  }
-
-  // check for weak copyleft licenses
-  if (WEAK_COPYLEFT_LICENSES_LOWERCASE.has(licenseType.toLowerCase())) {
-    return LicenseCategory.WEAK_COPYLEFT;
-  }
-
-  // everything else is considered permissive
-  return LicenseCategory.PERMISSIVE;
-}
+import { classifyLicenseExpression } from './licenseClassification';
+import { renderLicenseExpression } from './licenseExpression';
 
 /**
  * Analyzes license data and returns comprehensive statistics.
+ *
+ * Each package is classified by its License Expression and grouped by the rendered expression,
+ * so a Dual License such as `MIT OR Apache-2.0` is counted under one key.
+ *
  * @param report the licenses report data
+ * @param orPolicy the OR Policy used to classify Dual Licenses; defaults to {@link DEFAULT_OR_POLICY}
  * @returns the license analysis result
  */
-export function analyzeLicenses(report: AggregatedLicensesMapping): LicenseAnalysisResult {
+export function analyzeLicenses(
+  report: AggregatedLicensesMapping,
+  orPolicy: OrPolicy = DEFAULT_OR_POLICY,
+): LicenseAnalysisResult {
   const byCategory: Record<LicenseCategory, number> = {
     [LicenseCategory.STRONG_COPYLEFT]: 0,
     [LicenseCategory.WEAK_COPYLEFT]: 0,
@@ -43,21 +30,19 @@ export function analyzeLicenses(report: AggregatedLicensesMapping): LicenseAnaly
   };
 
   const byLicense: Record<string, number> = {};
+  const categoryByLicense: Record<string, LicenseCategory> = {};
   const categorizedLicenses: Record<string, LicenseCategory> = {};
 
   Object.entries(report).forEach(([packageKey, license]) => {
-    const licenseType = license.type;
-    const category = categorizeLicense(licenseType);
+    const category = classifyLicenseExpression(license.license, orPolicy);
+    const renderedLicense = renderLicenseExpression(license.license);
 
     // stats by category
     byCategory[category]++;
 
     // stats by specific license
-    {
-      const key = licenseType ?? 'unknown';
-
-      byLicense[key] = (byLicense[key] ?? 0) + 1;
-    }
+    byLicense[renderedLicense] = (byLicense[renderedLicense] ?? 0) + 1;
+    categoryByLicense[renderedLicense] = category;
 
     // memoization for lookup
     categorizedLicenses[packageKey] = category;
@@ -71,6 +56,7 @@ export function analyzeLicenses(report: AggregatedLicensesMapping): LicenseAnaly
     total,
     byCategory,
     byLicense,
+    categoryByLicense,
     description,
     categoriesPresence,
     categorizedLicenses,

package/src/licenses/licenseClassification.ts

@@ -0,0 +1,173 @@
+import { STRONG_COPYLEFT_LICENSES_LOWERCASE, WEAK_COPYLEFT_LICENSES_LOWERCASE } from '../constants';
+import type { LicenseExpression } from '../types';
+
+import { LicenseCategory } from './LicenseCategory';
+import type { OrPolicy } from './OrPolicy';
+import { DEFAULT_OR_POLICY } from './OrPolicy';
+
+const CATEGORY_RANK: Record<LicenseCategory, number> = {
+  [LicenseCategory.PERMISSIVE]: 0,
+  [LicenseCategory.WEAK_COPYLEFT]: 1,
+  [LicenseCategory.STRONG_COPYLEFT]: 2,
+  [LicenseCategory.UNKNOWN]: 3,
+};
+
+const OR_COMPARISON_STRATEGY: Record<OrPolicy, (a: LicenseCategory, b: LicenseCategory) => LicenseCategory> = {
+  'most-restrictive': takeMoreRestrictive,
+  'least-restrictive': takeLessRestrictive,
+};
+
+/**
+ * Categorizes a canonical License Identifier from a parsed License Expression.
+ * Not for raw strings: an identifier outside the copyleft tables is assumed permissive,
+ * which is only safe because the parser rejects unrecognised identifiers.
+ */
+function categorizeLicenseId(licenseId: string): LicenseCategory {
+  if (STRONG_COPYLEFT_LICENSES_LOWERCASE.has(licenseId.toLowerCase())) {
+    return LicenseCategory.STRONG_COPYLEFT;
+  }
+
+  if (WEAK_COPYLEFT_LICENSES_LOWERCASE.has(licenseId.toLowerCase())) {
+    return LicenseCategory.WEAK_COPYLEFT;
+  }
+
+  return LicenseCategory.PERMISSIVE;
+}
+
+/**
+ * Classifies a License Expression into a License Category.
+ *
+ * Categories are ordered permissive < weak copyleft < strong copyleft < unknown:
+ * - a license takes the category of its License Identifier;
+ * - an Unknown License is unknown;
+ * - AND always takes its most restrictive operand;
+ * - OR takes the operand chosen by the OR Policy.
+ *
+ * @param expression the License Expression to classify
+ * @param orPolicy the OR Policy applied to every OR in the expression; defaults to {@link DEFAULT_OR_POLICY}
+ * @returns the License Category of the whole expression
+ * @example
+ * classifyLicenseExpression(parseLicenseExpression('MIT OR GPL-3.0-only'), 'least-restrictive');
+ * // LicenseCategory.PERMISSIVE
+ */
+export function classifyLicenseExpression(
+  expression: LicenseExpression,
+  orPolicy: OrPolicy = DEFAULT_OR_POLICY,
+): LicenseCategory {
+  switch (expression.kind) {
+    case 'license':
+      return isLicenseRef(expression.id) ? LicenseCategory.UNKNOWN : categorizeLicenseId(expression.id);
+    case 'unknown':
+      return LicenseCategory.UNKNOWN;
+    case 'and':
+      return takeMoreRestrictive(
+        classifyLicenseExpression(expression.left, orPolicy),
+        classifyLicenseExpression(expression.right, orPolicy),
+      );
+    case 'or':
+      return OR_COMPARISON_STRATEGY[orPolicy](
+        classifyLicenseExpression(expression.left, orPolicy),
+        classifyLicenseExpression(expression.right, orPolicy),
+      );
+  }
+}
+
+/** The copyleft that cannot be avoided for a License Expression, see {@link classifyUnavoidableCopyleft} */
+export interface UnavoidableCopyleft {
+  /** The known copyleft that must be complied with, never unknown; permissive when no known operand requires copyleft */
+  category: LicenseCategory;
+  /** `true` when an Unknown operand could require more than `category`, so `category` is only a lower bound */
+  unidentified: boolean;
+}
+
+/**
+ * Decides which copyleft cannot be avoided for a License Expression under an OR Policy.
+ *
+ * Unknown operands are ignored, so a custom license next to a copyleft one cannot hide the copyleft:
+ * - AND requires the most restrictive known operand;
+ * - OR with an Unknown operand requires what the other operand requires;
+ * - OR with two known operands follows the OR Policy;
+ * - an expression with no known operand requires no copyleft.
+ *
+ * Ignoring an Unknown operand can also understate the result (`MIT AND LicenseRef-Custom`, or an expression
+ * that is wholly Unknown), so the result says when that happened: `unidentified` is `true` when an Unknown operand
+ * could require more than the category under the OR Policy and the category is not already strong copyleft,
+ * the most restrictive known category. `MIT OR LicenseRef-Custom` is only unidentified under the most restrictive OR Policy.
+ *
+ * @param expression the License Expression to check
+ * @param orPolicy the OR Policy applied to every OR in the expression; defaults to {@link DEFAULT_OR_POLICY}
+ * @returns the known copyleft category, and whether an Unknown operand leaves it unidentified
+ * @example
+ * classifyUnavoidableCopyleft(parseLicenseExpression('GPL-3.0-only AND LicenseRef-Custom'));
+ * // { category: LicenseCategory.STRONG_COPYLEFT, unidentified: false }
+ * @example
+ * classifyUnavoidableCopyleft(parseLicenseExpression('MIT AND LicenseRef-Custom'));
+ * // { category: LicenseCategory.PERMISSIVE, unidentified: true }
+ */
+export function classifyUnavoidableCopyleft(
+  expression: LicenseExpression,
+  orPolicy: OrPolicy = DEFAULT_OR_POLICY,
+): UnavoidableCopyleft {
+  const category = findKnownCopyleft(expression, orPolicy) ?? LicenseCategory.PERMISSIVE;
+
+  return {
+    category,
+    unidentified: category !== LicenseCategory.STRONG_COPYLEFT && hasUnknownOperand(expression, orPolicy),
+  };
+}
+
+/**
+ * Whether an Unknown operand could require more than {@link findKnownCopyleft} found under the OR Policy.
+ *
+ * An OR with a known operand only has this risk under the most restrictive OR Policy: under the least restrictive
+ * one the known operand can always be chosen instead of the Unknown one.
+ */
+function hasUnknownOperand(expression: LicenseExpression, orPolicy: OrPolicy): boolean {
+  switch (expression.kind) {
+    case 'unknown':
+      return true;
+    case 'license':
+      return classifyLicenseExpression(expression, orPolicy) === LicenseCategory.UNKNOWN;
+    case 'and':
+      return hasUnknownOperand(expression.left, orPolicy) || hasUnknownOperand(expression.right, orPolicy);
+    case 'or':
+      return orPolicy === 'least-restrictive'
+        ? hasUnknownOperand(expression.left, orPolicy) && hasUnknownOperand(expression.right, orPolicy)
+        : hasUnknownOperand(expression.left, orPolicy) || hasUnknownOperand(expression.right, orPolicy);
+  }
+}
+
+/** Like {@link classifyUnavoidableCopyleft}, but `null` when no operand has a known category */
+function findKnownCopyleft(expression: LicenseExpression, orPolicy: OrPolicy): LicenseCategory | null {
+  if (expression.kind === 'unknown') {
+    return null;
+  }
+
+  if (expression.kind === 'license') {
+    const category = classifyLicenseExpression(expression, orPolicy);
+
+    return category === LicenseCategory.UNKNOWN ? null : category;
+  }
+
+  const left = findKnownCopyleft(expression.left, orPolicy);
+  const right = findKnownCopyleft(expression.right, orPolicy);
+
+  if (left === null || right === null) {
+    return left ?? right;
+  }
+
+  return expression.kind === 'and' ? takeMoreRestrictive(left, right) : OR_COMPARISON_STRATEGY[orPolicy](left, right);
+}
+
+/** A custom license reference, optionally qualified by a document: `LicenseRef-X` or `DocumentRef-Y:LicenseRef-X` */
+function isLicenseRef(id: string): boolean {
+  return /^(DocumentRef-[^:]+:)?LicenseRef-/.test(id);
+}
+
+function takeMoreRestrictive(a: LicenseCategory, b: LicenseCategory): LicenseCategory {
+  return CATEGORY_RANK[a] >= CATEGORY_RANK[b] ? a : b;
+}
+
+function takeLessRestrictive(a: LicenseCategory, b: LicenseCategory): LicenseCategory {
+  return CATEGORY_RANK[a] <= CATEGORY_RANK[b] ? a : b;
+}