Node-license-validator

This module is a programmatic and command line tool to help you validate the licenses of your dependencies against an allowed list. It is suitable for use in a build process. It utilizes nlf, semver, and spdx.

Installation

Global command

npm install -g node-license-validator

Package local

npm install --save node-license-validator

For easy access, modify package.json to include it as a script:

{
  "scripts": {
    "nlv": "node-license-validator"
  }
}

And run it with npm run nlv -- --allow-licenses [etc]. Note that you need npm >= 2.0 to pass arguments in this way to scripts.

Command line usage

Courtesy of yargs:

Usage: node-license-validator [dirname] [options]

Options:
  -h, --help        Show help.                                                                                                     [boolean]
  -q, --quiet       Don't output anything.                                                                                         [boolean]
  -v, --verbose     Detailed list of package licenses.                                                                             [boolean]
  --dir             Base directory of package to validate. Defaults to current working directory.
  --list-licenses   Don't validate; just list the licenses in use.                                                                 [boolean]
  --warn            Only print invalid licenses, don't exit with error                                            [boolean] [default: false]
  --allow-licenses  A list of licenses to allow. Validation will fail if a package is present that is not licensed under any of the licenses
                    in this list.                                                                                                    [array]
  --allow-packages  A list of packages to allow. Can be used to allow packages for which the license is not detected correctly (can happen
                    with old package.json formats). Optionally may use package.json-style semver directives to match a version or range of
                    versions.                                                                                                        [array]
  -d, --deep        Perform a deep search against all sub-dependencies.                                           [boolean] [default: false]
  -p, --production  Only traverse dependencies, no dev-dependencies                                               [boolean] [default: false]

Examples:
  node-license-validator ~/project --allow-licenses WTFPL ISC MIT  Allow the WTFPL, ISC, and MIT licenses.
  node-license-validator ~/project --allow-packages convict        Allow the package 'convict'.
  node-license-validator ~/project --allow-packages pg@^3.6.0      Allow the package 'pg' (3.6.0 and up, but not 4.0.0 or higher).

Sample successful output:

$ node-license-validator --allow-licenses ISC MIT BSD-3-Clause
Identified licenses: BSD-3-Clause,ISC,MIT
All licenses ok.

Verbose output:

$ node-license-validator -v --allow-licenses ISC MIT BSD-3-Clause
Identified licenses: BSD-3-Clause,ISC,MIT
- [email protected]: BSD-3-Clause
- [email protected]: MIT
- [email protected]: MIT
- [email protected]: MIT
- [email protected]: ISC
- [email protected]: ISC
- [email protected]: ISC
- [email protected]: MIT
- [email protected]: MIT
- [email protected]: MIT
All licenses ok.

Failure output:

$ node-license-validator -v --allow-licenses ISC MIT
Invalid license: [email protected]: BSD-3-Clause

Exit codes

node-license-validator exits with a 0 on success, a 1 on license failure, and a 2 on an error.

Programmatic usage

All arguments are required (including the licenses and packages arrays, even if empty)

var nlv = require('node-license-validator');
nlv(packageDir, {
    licenses: [ 'MIT', 'ISC' ],
    packages: [ ]
}, function (err, data) {
    // ...
});

data will contain an object that looks like this:

{
    packages: {
        '[email protected]': 'BSD-3-Clause, Apache-2.0',
        '[email protected]': 'MIT',
        '[email protected]': 'ISC'
    },
    licenses: [ 'MIT', 'ISC' ],
    invalids: [ '[email protected]' ]
}

packages contains an object mapping the exact module names and versions that are installed to the licenses they specify. If node-license-validator was unable to validate a module's license(s), the license string will include any and all possible licenses that could be found (by nlf) for that module. If a module was valid, the license string will be the first license or spdx rule that was acceptable.

licenses is just a convenience that collects the set of distinct licenses represented by the target module's dependencies.

invalids contains a list of module references for all dependencies that failed to validate.

Specifying licenses

This is fairly straightforward but there are some details. node-license-validator first attempts to interpret allowed licenses as spdx license IDs, as expected by the latest package.json documentation. When the inspected dependency's license specification is a valid SPDX license expression, and at least one of the allowed licenses is a valid SPDX license ID, they are compared to determine compatibility.

If the SPDX check fails, a plain string comparison is attempted between the dependency's specified license(s) and the complete list of allowed licenses.

If both license checks fail, the dependency is checked against the exceptions (below); if this check also fails, the dependency fails validation.

Caveat: if nlv cannot determine any license for a package, it will specify the license as Unknown. It is valid to add this as an acceptable license, but not advisable.

Specifying exceptions

If for some reason nlv is unable to parse a module's package.json, or if you want to allow a specific module without allowing its license globally, you may specify allowed packages individually. You do this with the --allow-packages command line switch or the packages options key. Allowed packages are strings that contain either a package name or an npm install-compatible package specification. For example, you can specify pg@^3.6.0 or convict or @scope/private-module.