@callstack/licenses 0.3.2 → 1.0.0

package/src/node/utils/aboutLibrariesLicenses.ts

@@ -0,0 +1,69 @@
+import { renderLicenseExpression } from '../../licenses';
+import type { License, LicenseExpression } from '../../types';
+
+import { sha512 } from './miscUtils';
+
+type LicenseLeaf = Extract<LicenseExpression, { kind: 'license' }>;
+
+function collectLicenseLeaves(expression: LicenseExpression): LicenseLeaf[] {
+  switch (expression.kind) {
+    case 'license':
+      return [expression];
+    case 'and':
+    case 'or':
+      return [...collectLicenseLeaves(expression.left), ...collectLicenseLeaves(expression.right)];
+    case 'unknown':
+      return [];
+  }
+}
+
+function getAboutLibrariesEntries(license: License): { id?: string; name: string }[] {
+  const leavesById = new Map(collectLicenseLeaves(license.license).map((leaf) => [leaf.id, leaf]));
+
+  if (leavesById.size > 0) {
+    return [...leavesById.values()].map((leaf) => ({ id: leaf.id, name: renderLicenseExpression(leaf) }));
+  }
+
+  // Unknown License: the Raw License is the best name we have
+  if (license.rawLicense) {
+    return [{ name: license.rawLicense }];
+  }
+
+  // nothing declared, but the package ships a license text, so keep it
+  if (license.licenseFiles.length > 0) {
+    return [{ name: renderLicenseExpression(license.license) }];
+  }
+
+  return [];
+}
+
+/**
+ * One AboutLibraries license per License Identifier (or the Raw License when it is Unknown). Its name keeps
+ * a retained `+` and the License Exception; its content is the linked license file, else every unlinked text
+ * when the package has one license or exactly one unlinked text.
+ */
+export function prepareAboutLibrariesLicenses(license: License): { name: string; content: string }[] {
+  const entries = getAboutLibrariesEntries(license);
+  const unlinkedTexts = license.licenseFiles.filter((file) => !file.licenseId).map((file) => file.content);
+
+  // unlinked texts go to every license when there is only one text (it may cover all of them),
+  // or when there is only one license (it owns every text)
+  const sharedContent = entries.length === 1 || unlinkedTexts.length === 1 ? unlinkedTexts.join('\n\n') : '';
+
+  return entries.map(({ id, name }) => ({
+    name,
+    content: (id ? license.licenseFiles.find((file) => file.licenseId === id)?.content : undefined) ?? sharedContent,
+  }));
+}
+
+export function prepareAboutLibrariesLicenseField(name: string, content?: string) {
+  // 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 sanitizedName = name.replace(/[^A-Za-z0-9._-]/g, '_');
+
+  // hash the unsanitized name when there is no text, so that names differing only in sanitized characters stay distinct
+  return `${sanitizedName}_${sha512(content || name)}`;
+}

package/src/node/utils/licenseFiles.ts

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { glob } from 'glob';
+
+import type { LicenseFile } from '../../types';
+
+// `LICEN{S,C}E*` also matches code and data files such as `license.js` or `licenses.json`
+const NON_LICENSE_EXTENSIONS = new Set(['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts', '.tsx', '.jsx', '.json', '.map']);
+
+/**
+ * Reads every license file (`LICEN{S,C}E*`, `COPYING*`, case-insensitive) from the package root.
+ *
+ * A file is linked to a License Identifier by its name suffix (e.g. `LICENSE-APACHE` → `Apache-2.0`),
+ * but only when exactly one of `licenseIds` matches; otherwise it is listed without an identifier.
+ */
+export function readLicenseFiles(packageDir: string, licenseIds: string[]): LicenseFile[] {
+  return glob
+    .sync('{LICEN{S,C}E*,COPYING*}', { cwd: packageDir, absolute: true, nocase: true, nodir: true })
+    .sort()
+    .filter((file) => !NON_LICENSE_EXTENSIONS.has(path.extname(file).toLowerCase()))
+    .map((file) => {
+      const licenseId = linkLicenseId(path.basename(file), licenseIds);
+
+      return {
+        file,
+        content: fs.readFileSync(file, { encoding: 'utf-8' }),
+        ...(licenseId && { licenseId }),
+      };
+    });
+}
+
+function linkLicenseId(fileName: string, licenseIds: string[]): string | undefined {
+  const suffix = fileName
+    .replace(/\.(txt|md)$/i, '')
+    .replace(/^(licen[sc]e|copying)[-_. ]*/i, '')
+    .toLowerCase();
+
+  if (!suffix) {
+    return undefined;
+  }
+
+  const matching = licenseIds.filter((id) => {
+    const lowerId = id.toLowerCase();
+
+    return lowerId === suffix || lowerId.startsWith(`${suffix}-`);
+  });
+
+  return matching.length === 1 ? matching[0] : undefined;
+}

package/src/node/utils/licensePlistBody.ts

@@ -0,0 +1,18 @@
+import path from 'path';
+
+import { renderLicenseExpression } from '../../licenses';
+import type { License } from '../../types';
+
+/**
+ * LicensePlist body: every license text under a per-license heading (plain text, as LicensePlist shows
+ * bodies verbatim); the rendered License Expression when there is no text.
+ */
+export function buildLicensePlistBody(license: License) {
+  if (license.licenseFiles.length === 0) {
+    return renderLicenseExpression(license.license);
+  }
+
+  return license.licenseFiles
+    .map(({ file, content, licenseId }) => `=== ${licenseId ?? path.basename(file)} ===\n\n${content.trim()}`)
+    .join('\n\n');
+}

package/src/node/utils/packageUtils.ts

@@ -1,35 +1,49 @@
 import fs from 'fs';
 import path from 'path';
 
-import type { License, ScanPackageOptionsFactory } from '../../types';
+import type { ScanPackageOptionsFactory } from '../../types';
 import { normalizeRepositoryUrl } from '../../utils/repositoryUtils';
 
-import { sha512 } from './miscUtils';
+export { prepareAboutLibrariesLicenseField, prepareAboutLibrariesLicenses } from './aboutLibrariesLicenses';
+export { buildLicensePlistBody } from './licensePlistBody';
+export { readLicenseFiles } from './licenseFiles';
 
-export function getPackageJsonPath(dependency: string, root?: string) {
+export function getPackageJsonPath(dependency: string, root?: string, projectRoot: string = 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.join(root, 'node_modules', dependency, 'package.json');
+      const pkgJsonInNodeModules = findPackageJsonInNodeModules(dependency, root);
 
-      if (fs.existsSync(pkgJsonInNodeModules)) {
+      if (pkgJsonInNodeModules) {
         return pkgJsonInNodeModules;
       }
     }
 
-    return resolvePackageJsonFromEntry(dependency); // final fallback
+    return resolvePackageJsonFromEntry(dependency, rootsToSearch); // final fallback
   }
 }
 
-export function resolvePackageJsonFromEntry(dependency: string) {
+function findPackageJsonInNodeModules(dependency: string, startDir: string) {
+  for (let currentDir = startDir; ; currentDir = path.dirname(currentDir)) {
+    if (path.basename(currentDir) !== 'node_modules') {
+      const pkgJsonInNodeModules = path.join(currentDir, 'node_modules', dependency, 'package.json');
+
+      if (fs.existsSync(pkgJsonInNodeModules)) return fs.realpathSync(pkgJsonInNodeModules);
+    }
+
+    if (currentDir === path.dirname(currentDir)) return null;
+  }
+}
+
+export function resolvePackageJsonFromEntry(dependency: string, paths?: string[]) {
   try {
-    const entryPath = require.resolve(dependency);
+    const entryPath = require.resolve(dependency, paths ? { paths } : undefined);
     const packageDir = findPackageRoot(entryPath);
 
     if (!packageDir) return null;
@@ -54,21 +68,6 @@ export function normalizePackageName(packageName: string): string {
   return packageName.replace('/', '_');
 }
 
-export function prepareAboutLibrariesLicenseField(license: 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}_${sha512(license.content ?? sanitizedType)}`;
-}
-
 export function parseAuthorField(json: { author: string | { name: string } }) {
   if (typeof json.author === 'object' && typeof json.author.name === 'string') {
     return json.author.name;
@@ -79,14 +78,26 @@ export function parseAuthorField(json: { author: string | { name: string } }) {
   }
 }
 
-export function parseLicenseField(json: { license: string | { type: string } }) {
-  if (typeof json.license === 'object' && typeof json.license.type === 'string') {
+/**
+ * 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 `.
+ */
+export function parseLicenseField(json: { license?: string | { type: string }; licenses?: Array<{ 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;
+  }
 }
 
 export function parseRepositoryFieldToUrl(json: { repository: string | { url?: string } }) {

package/src/types/AboutLibrariesLikePackageInfo.ts

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

package/src/types/License.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';
 
@@ -9,17 +11,24 @@ export type License = {
   /** Package author */
   author?: string;
 
-  /** Package license contents */
-  content?: string;
-
   /** Package description */
   description?: string;
 
-  /** License file path */
-  file?: 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[];
 
-  /** License type */
-  type?: string;
+  /** Every license file found in the package root, each linked to its License Identifier where unambiguous */
+  licenseFiles: LicenseFile[];
 
   /** Package repository URL */
   url?: string;

package/src/types/LicenseAnalysisResult.ts

@@ -3,5 +3,13 @@ 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/src/types/LicenseExpression.ts

@@ -0,0 +1,22 @@
+/**
+ * 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/src/types/LicenseFile.ts

@@ -0,0 +1,10 @@
+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/src/types/LicenseStats.ts

@@ -12,7 +12,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/src/types/ScanDependenciesOptions.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/src/types/index.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';