spdx-checker

Check npm dependencies for license compatibility issues

A minimal, fast CLI tool that scans your project dependencies and checks their licenses for compatibility with your project's license. Identifies incompatible licenses, missing licenses, and high-risk GPL packages.

Features

• Scan all dependencies - recursively checks all installed packages in node_modules
• License compatibility checking - validates licenses against a compatibility matrix
• High-risk license detection - flags GPL/AGPL packages for review
• SPDX expression support - handles "MIT OR Apache-2.0" style licenses
• Fast - scans projects with hundreds of dependencies in seconds
• Beautiful output - formatted table with color-coded severity levels
• JSON export - machine-readable output with --json flag

Installation

npm install -g spdx-checker

Or run directly without installing:

npx spdx-checker

Usage

Scan current project

spdx-checker

Scan a specific project

spdx-checker /path/to/project

Verbose output

spdx-checker --verbose

JSON output

spdx-checker --json

Example Output

────────────────────────────────────────────
Compliance Report
────────────────────────────────────────────

Project License: MIT
Dependencies Checked: 245
Issues Found: 2

⚠ 2 potential compatibility issues found

────────────────────────────────────────────
Compatibility Issues
────────────────────────────────────────────

Package             License    Issue
──────────────────────────────────────────────────
some-gpl-lib        GPL-3.0    [error] GPL-3.0 is not compatible with MIT
proprietary-tool    UNLICENSED [warning] No license specified

✗ Found 1 error(s)
⚠ Found 1 warning(s)

Configuration

Create a spdx-checker.config.json in your project root to customize behavior:

{
  "ignorePackages": ["internal-package"],
  "allowedHighRiskLicenses": ["GPL-2.0"]
}

License Compatibility Matrix

The tool includes a default compatibility matrix that handles common scenarios:

Permissive Licenses

• MIT: Compatible with MIT, Apache-2.0, BSD-3-Clause, ISC, BSD-2-Clause, MPL-2.0
• Apache-2.0: Compatible with MIT, Apache-2.0, BSD-3-Clause, ISC
• BSD-3-Clause: Compatible with MIT, Apache-2.0, BSD-3-Clause, ISC, BSD-2-Clause
• ISC: Compatible with most permissive licenses

Copyleft Licenses

• GPL-2.0: Only compatible with GPL-2.0, AGPL-2.0 (viral)
• GPL-3.0: Only compatible with GPL-3.0, AGPL-3.0 (viral)

Special Cases

• UNLICENSED: Flags as warning - review required
• PROPRIETARY: Flags as warning - review required
• Dual-licensed (e.g., "MIT OR Apache-2.0"): Compatible if any option matches

How It Works

1. Reads your project's package.json to determine your project license
2. Scans node_modules to find all installed dependencies
3. Checks each dependency's license field against the compatibility matrix
4. Reports issues grouped by severity (error, warning, info)
5. Returns appropriate exit code (0 for success, 1 for errors)

Common Issues

"No license specified"

Some packages don't specify a license. Review the package's repository or LICENSE file:

cd node_modules/package-name && cat LICENSE

"GPL not compatible with MIT"

GPL licenses are "viral" and require derivative works to also be GPL. Consider:

• Replacing with a permissive alternative
• Checking if the package offers an exception
• Using the package only in development (npm install --save-dev)

"node_modules not found"

Run npm install first to install dependencies.

API Usage

import { LicenseGuard, Scanner, Checker, Reporter } from 'spdx-checker';

const guard = new LicenseGuard();
await guard.check('./my-project', { verbose: true });

// Or use components separately
const scanner = new Scanner();
const deps = scanner.scanDependencies('./my-project');

const checker = new Checker();
const result = checker.check(deps, 'MIT');

const reporter = new Reporter();
console.log(reporter.formatDetailed(result));

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT