@eclipse-che/license-tool

Node.js library for dependency license analysis of npm and Yarn projects. Uses the ClearlyDefined HTTP API to resolve licenses—no Java, no containers required.

Features

• Pure Node.js: No Java/JAR—uses ClearlyDefined HTTP API
• npm & Yarn support: npm (package-lock.json), Yarn v1, Yarn 3+
• SPDX-based license policy: Approves MIT, Apache-2.0, BSD, ISC, EPL-2.0, and more
• Use as library or CLI: Programmatic API and npx @eclipse-che/license-tool command
• Eclipse IP compliance: Optional JAR fallback for full IPLab/CQ integration

Eclipse IP Compliance

By default, this tool uses the ClearlyDefined HTTP API as its primary license data source. For full Eclipse IP Team compliance (CQ status, IPLab integration), use the --jar option to enable fallback to the official Eclipse Dash License Tool JAR, which queries the Eclipse Foundation's internal IP database.

Supported Package Managers

Package Manager	Lock File
npm	package-lock.json
Yarn v1	yarn.lock (Yarn < 2)
Yarn 3+	yarn.lock (Yarn >= 3) — parsed directly, no plugins required

Requirements

• Node.js >= 20.0.0

Installation

npm install @eclipse-che/license-tool
# or
yarn add @eclipse-che/license-tool

Where is it Published?

This library is available on npm.

You can find the published package here:
npm: @eclipse-che/license-tool

Quick Start

CLI

# Generate prod.md and dev.md in .deps/ (default)
npx @eclipse-che/license-tool

# Check only — fails if existing .deps files are outdated
npx @eclipse-che/license-tool --check

# Target a specific project directory
npx @eclipse-che/license-tool /path/to/project

# Tune batch size for ClearlyDefined API calls
npx @eclipse-che/license-tool --batch 200

# Auto-request harvest for unresolved dependencies
npx @eclipse-che/license-tool --harvest

# JAR fallback for unresolved dev dependencies
npx @eclipse-che/license-tool --jar /path/to/dash-licenses.jar

CLI Options

Option	Description	Default
[projectPath]	Path to project directory	current working directory
--generate	(Re)generate dependency files	default mode
--check	Check only, do not write any files	false
--batch <n>	Batch size for ClearlyDefined API requests	500
--harvest	Request harvest for unresolved deps from ClearlyDefined	false
--jar <path>	Path to Eclipse dash-licenses.jar for fallback on unresolved dev deps	—
--debug	Copy tmp files for inspection	false
--help	Show help message	—

Downloading the Eclipse Dash JAR

The --jar option enables fallback to the official Eclipse Dash License Tool for unresolved dependencies.

Why use it? The Eclipse Dash JAR queries the Eclipse Foundation's internal IP database (IPLab), which contains additional approval data not available through the public ClearlyDefined API. This can resolve dependencies that appear as "restricted" or "unresolved" when using only the HTTP backend.

Requirements: Java 11 or higher must be installed.

Download:

# Download dash-licenses JAR (1.1.0)
curl -Lo dash-licenses.jar https://repo.eclipse.org/repository/dash-maven2/org/eclipse/dash/org.eclipse.dash.licenses/1.1.0/org.eclipse.dash.licenses-1.1.0.jar

Resources:

• Project page: https://projects.eclipse.org/projects/technology.dash
• Downloads: https://projects.eclipse.org/projects/technology.dash/downloads

How it works:

1. Processes unresolved dev dependencies through the Eclipse IP database
2. Adds newly approved items to .deps/EXCLUDED/dev.md
3. Regenerates dev.md with the updated approvals

Important: Once dependencies are added to the EXCLUDED files, you don't need to use --jar on every run. The EXCLUDED files act as a permanent cache of approved dependencies. Only re-run with --jar when you have new unresolved dev dependencies or want to refresh approvals from the Eclipse IP database.

Auto-Harvesting with ClearlyDefined

The --harvest flag enables automatic harvest requests for unresolved dependencies through the ClearlyDefined API.

Why use it? When ClearlyDefined doesn't have license information for a package, you can request it to "harvest" the license data from the source repository. This process extracts license files and headers automatically.

How it works:

1. For each unresolved dependency, check if it was already harvested (GET /harvest/{coordinate})
2. If not harvested, request a new harvest (POST /harvest)
3. ClearlyDefined queues the harvest job (typically completes in minutes to hours)
4. Re-run npx @eclipse-che/license-tool after harvest completes to pick up new license data

Example:

# Request harvest for unresolved dependencies
npx @eclipse-che/license-tool --harvest

# Wait for harvest to complete, then re-run
npx @eclipse-che/license-tool

See docs/harvest.md for detailed documentation.

Library

import { generate } from '@eclipse-che/license-tool';

const result = await generate({
  projectPath: '/path/to/project',
  batchSize: 500,
  check: false,
  debug: false,
  harvest: false,
  jarPath: '/path/to/dash-licenses.jar', // optional
});

if (result.exitCode === 0) {
  console.log('Licenses OK');
} else {
  console.error(result.error);
}

Output Files

Generated in .deps/:

File	Description
prod.md	Production dependencies
dev.md	Development dependencies
problems.md	Unresolved or restricted dependencies
EXCLUDED/prod.md	Manually excluded production deps
EXCLUDED/dev.md	Manually excluded dev deps

API

generate(config: LibraryConfig): Promise<LibraryResult>

Option	Type	Default	Description
projectPath	string	required	Path to project directory (must contain package.json and a lock file)
batchSize	number	500	Batch size for ClearlyDefined API requests
check	boolean	false	Check only — do not write any files
debug	boolean	false	Copy tmp directory for inspection
harvest	boolean	false	Request harvest for unresolved dependencies from ClearlyDefined
jarPath	string	—	Path to Eclipse dash-licenses.jar; runs JAR fallback for unresolved dev deps, adds approved items to EXCLUDED, and regenerates dev.md

Returns Promise<{ exitCode: 0 | 1; error?: string }>.

Project Structure

@eclipse-che/license-tool/
├── src/
│   ├── library.ts           # Main library API
│   ├── cli.ts               # CLI entry point
│   ├── backends/            # License resolution (ClearlyDefined)
│   ├── document/            # Document generation
│   ├── helpers/             # Shared utilities
│   └── package-managers/    # npm, yarn, yarn3
├── dist/                    # Built output
└── package.json

Development

npm install
npm run build
npm test
npm run lint

Scripts

Script	Description
npm run build	Compile TypeScript with webpack
npm test	Run all tests
npm run test:unit	Run unit tests only
npm run test:e2e	Run end-to-end tests
npm run lint	Run ESLint
npm run header:check	Check license headers
npm run type-check	TypeScript type check (no emit)

Risks and Limitations

• ClearlyDefined coverage: Newly published packages may not be indexed yet; use --jar or --harvest to resolve them
• Approval rules: Maintain src/backends/license-policy.ts per Eclipse licenses as needed

Related Projects

• ClearlyDefined — License data source
• Eclipse Dash License Tool — Original Java tool

License

EPL-2.0