License Scanner

A high-performance npm package that scans project dependencies to detect and report their licenses. Uses a Go binary for fast scanning wrapped in a Node.js package for easy integration.

Installation

npm install @stefanoa1/license-scanner

or

pnpm install @stefanoa1/license-scanner

Or any other package install method should be covered.

It supports Node.js >= v16.

Usage

Package.json Usage

You can add this to your scripts as (the scope on the package.json file is not needed once installed):

{
  "scripts": {
    "scan-licenses": "license-scanner --format html --output report.html",
  }
}

Then, run:

  npm run scan-licenses

CLI Usage

With npx (scope @stefanoa1 is needed on npx):

# Basic scan - outputs clean JSON to terminal by default
npx @stefanoa1/license-scanner

# Save results to file
npx @stefanoa1/license-scanner --output report.json

# Generate HTML report
npx @stefanoa1/license-scanner --format html --output report.html

# Enable verbose logging for debugging
npx @stefanoa1/license-scanner --verbose

# Scan production dependencies only
npx @stefanoa1/license-scanner --prod-only

# Skip license summary
npx @stefanoa1/license-scanner --no-summary

# Scan specific directory
npx @stefanoa1/license-scanner /path/to/project

CLI Options

Option	Short	Description
--verbose	-v	Enable verbose logging for debugging
--prod-only		Scan production dependencies only
--format <format>		Output format (json, html) [default: json]
--output <file>		Output file path
--no-summary		Skip license summary
--help	-h	Show help message

Programmatic Usage

const { scanLicenses } = require('@stefanoa1/license-scanner');

// Scan current directory
const result = await scanLicenses('.');

console.log(result.summary);
// {
//   totalDependencies: 245,
//   uniqueLicenses: ["MIT", "Apache-2.0", "BSD-3-Clause"],
//   riskLevel: "low",
//   conflicts: [],
//   recommendations: ["All licenses are permissive and compatible"]
// }

console.log(result.dependencies);
// [
//   {
//     name: "react",
//     version: "18.2.0",
//     license: "MIT",
//     confidence: 1.0,
//     source: "package.json"
//   }
// ]

Features

• ⚡ High Performance: Go-powered core for fast file system traversal and pattern matching
• 🔍 Multi-Source Detection: Analyzes package.json files, LICENSE files, and lock files
• 📊 Confidence Scoring: Rates license detection confidence from 0.0 to 1.0
• 🌍 Cross-Platform: Works on Linux, macOS, and Windows
• 📦 Multiple Package Managers: Supports npm, yarn, and pnpm
• 🎯 Zero Dependencies: No runtime dependencies for fast installation
• 📈 Comprehensive Reports: Detailed license analysis with compatibility insights
• 🛠️ Clean Output: Outputs clean JSON by default, with optional verbose logging

Supported Package Managers

• npm (package-lock.json)
• yarn (yarn.lock)
• pnpm (pnpm-lock.yaml)

(bun support coming soon)

Confidence Scoring System

• 1.0: Explicit license field in package.json
• 0.9: LICENSE file with clear license pattern match (e.g., MIT, Apache-2.0)
• 0.8: LICENSE file with recognizable license text patterns
• 0.2: LICENSE file exists but patterns not recognized
• 0.0: No license information found

Supported License Types

• MIT, Apache-2.0, GPL-2.0/3.0, BSD-2/3-Clause, ISC
• Handles both string and object license fields
• Recognizes common license variations (e.g., "apache2", "gplv3")

Output Example

{
  "summary": {
    "totalDependencies": 69,
    "uniqueLicenses": ["MIT", "Apache-2.0"],
    "riskLevel": "low",
    "conflicts": [],
    "recommendations": ["All licenses are permissive and compatible"]
  },
  "dependencies": [
    {
      "name": "lodash",
      "version": "4.17.21",
      "license": "MIT",
      "confidence": 1.0,
      "source": "package.json"
    },
    {
      "name": "express",
      "version": "4.18.2",
      "license": "MIT",
      "confidence": 1.0,
      "source": "package.json"
    }
  ]
}