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.
npm install -g node-license-validator
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.
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
node-license-validator exits with a 0 on success, a 1 on license failure, and a 2 on an error.
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.
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.
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.