JavaScript package.json License Checker
This is not an official Google product.
This is a tool for checking the license of JavaScript projects. It scans the
package.json
file to check its license and recursively checks all of its
dependencies.
DISCLAIMER: This tool is NOT a replacement for legal advice or due diligence for your project's license validity. We recommend you consult a lawyer if you want legal advice.
Installation
npm install [--save-dev] js-green-licenses
If you want to install globally,
npm install -g js-green-licenses
CLI
usage: jsgl [-h] [-v] [--local <directory>] [--pr <github PR>]
[--dev] [--verbose] [<package or package@version>]
License checker for npm modules
Positional arguments:
<package or package@version>
Package name to check license for. Can include
version spec after @. E.g. foo@^1.2.3. Otherwise
latest.
Optional arguments:
-h, --help Show this help message and exit.
-v, --version Show program's version number and exit.
--local <directory>, -l <directory>
Check a local directory instead of public npm.
--pr <github PR> Check a github pull request. Must be
<owner>/<repo>/pull/<id>
--dev Also check devDependencies.
--verbose Verbose error outputs.
This tool checks licenses for 1) an already published npm package, 2) a local
directory, or 3) a GitHub pull request. For checking an npm package, you can
just pass the package name (optionally together with the version) as the
argument. To check a local directory, you should pass the --local path/to/repo
argument. To check for a GitHub PR, you should pass the --pr <owner>/<repo>/pull/<id>
argument.
If the tool finds any non-green licenses in the given package or in its dependencies, they will be printed out together with the detailed information.
If you pass --dev
, the devDependencies
will be checked as well as the
dependencies
.
jsgl
also checks sub-packages for --local
and --pr
flags when it
detects that the repository is a monorepo. It assumes a certain directory
structure for detecting whether a repository is a monorepo: the top-level
directory should have the packages
directory in it and sub-packages must
exist under that directory. In that case, all the package.json
files are
found from sub-packages and jsgl
checks all of them.
For example, when a directory foo
is like this:
foo
|
+-- packages
| |
| +-- bar
| | |
| | +-- package.json
| | |
| | +-- ...
| |
| +-- baz
| |
| +-- package.json
| |
| +-- ...
|
+-- package.json
|
+-- ...
, jsgl
checks all of foo/package.json
, foo/packages/bar/package.json
,
and foo/packages/baz/package.json
.
Configurations
You can customize how jsgl
works with the configuration file, named
js-green-licenses.json
. For example, you can specify the license list that
you would like to consider green. The license IDs must be listed in the
greenLicenses
section of the configuration file. In that case, jsgl
will
use that custom list instead of its default list.
The default green license list is:
const DEFAULT_GREEN_LICENSES = [
'AFL-2.1', 'AFL-3.0', 'APSL-2.0', 'Apache-1.1', 'Apache-2.0',
'Artistic-1.0', 'Artistic-2.0', 'BSD-2-Clause', 'BSD-3-Clause', 'BSL-1.0',
'CC-BY-1.0', 'CC-BY-2.0', 'CC-BY-2.5', 'CC-BY-3.0', 'CC-BY-4.0',
'CC0-1.0', 'CDDL-1.0', 'CDDL-1.1', 'CPL-1.0', 'EPL-1.0',
'FTL', 'IPL-1.0', 'ISC', 'LGPL-2.0', 'LGPL-2.1',
'LGPL-3.0', 'LPL-1.02', 'MIT', 'MPL-1.0', 'MPL-1.1',
'MPL-2.0', 'MS-PL', 'NCSA', 'OpenSSL', 'PHP-3.0',
'Ruby', 'Unlicense', 'W3C', 'Xnet', 'ZPL-2.0',
'Zend-2.0', 'Zlib', 'libtiff',
];
You can also whitelist some npm packages and they will be considered "green"
even when they have non-green licenses or no licenses. It's useful when
jsgl
is unable to verify the validness of a certain package's license for
some reason. For example, when a package doesn't specify its license in its
package.json
but has a separate LICENSE
file, jsgl
can't verify that.
You can whitelist that package to make jsgl
not complain about that
package.
A typical configuration file looks like this:
{
"greenLicenses": [
// Custom green licenses.
"Apache-2.0",
"MIT",
"BSD-3-Clause",
...
],
"packageWhitelist": [
/* packages considered ok */
"foo",
"bar", // inline comment
"package-with-no-license",
"package-with-okish-license",
...
]
}
The greenLicenses
section is for the custom license list and the
packageWhitelist
section is for the package whitelist.
Note that comments are allowed in js-green-licenses.json
.
The configuration file must be located in the top-level directory of a
repository for --local
and --pr
. When checking remote npm packages,
jsgl
tries to locate the configuration file in the current local directory
from which jsgl
is invoked.
It is desirable that the license names in the greenLicenses
section be
valid license IDs defined in https://spdx.org/licenses/ whenever possible.
Interface as a Library
You can also use js-green-licenses
as a library as well as a command-line
utility. Usually the LicenseChecker
class is the only one you would have to
use.
Instantiation
const opts = {
dev: false,
verbose: true,
};
const checker = new LicenseChecker(opts);
Both the dev
and the verbose
fields are optional and default to false.
When dev
is true, the devDependencies
section is checked as well as the
dependencies
section of package.json
. When verbose
is true, jsgl
generates more verbose output.
Use in Gulp
const jsgl = require('js-green-licenses');
gulp.task('check_licenses', function() {
const checker = new jsgl.LicenseChecker({
dev: true,
verbose: false,
});
checker.setDefaultHandlers();
return checker.checkLocalDirectory('.');
});
Methods
-
LicenseChecker#setDefaultHandler()
setDefaultHandlers(): void;
Sets the default event handlers that are used by the CLI. For events emitted by
LicenseChecker
, see the Events subsection. -
LicenseChecker#checkLocalDirectory()
checkLocalDirectory(directory: string): Promise<void>;
This provides the functionality of the CLI when the
--local
flag is passed. It finds and checks thepackage.json
file in thedirectory
and recursively checks its dependencies. This method also detects monorepos and checks sub-packages as well, as explained in the CLI section above.This method reads in the configuration from the
js-green-licenses.json
file in thedirectory
, if it exists. -
LicenseChecker#checkRemotePackage()
checkRemotePackage(pkg: string): Promise<void>;
This provides the functionality of the CLI when neither
--local
or--pr
is passed. It retrieves and checks thepackage.json
for the remote npm package and recursively checks its dependencies.This method reads in the configuration from the
js-green-licenses.json
file in the current directory of the Node.js process. -
LicenseChecker#checkGitHubPR()
checkGitHubPR(repo: GitHubRepository, mergeCommitSha): Promise<void>;
This provides the functionality of the CLI when the
--pr
flag is passed. It retrieves thepackage.json
file from the GitHub repository at the given commit SHA and checks its license and recursively checks its dependencies. This method also detects monorepos and checks sub-packages as well, as explained in the CLI section above.This method reads in the configuration from the
js-green-licenses.json
file in the repository, if it exists.GitHubRepository
is a helper class for interacting with the GitHub API. You can create its instance by callingLicenseChecker#prPathToGitHubRepoAndId()
. -
LicenseChecker#prPathToGitHubRepoAndId()
prPathToGitHubRepoAndId(prPath: string): { repo: GitHubRepository; prId: string; };
prPath
must be in the form,<owner>/<repo>/pull/<id>
. This method will return theGitHubRepository
instance and the PR id for theprPath
.
Events
A LicenseChecker
object emits following events during its processing.
-
non-green-license
Emitted when a package with a non-green license is detected. The argument isinterface NonGreenLicense { packageName: string; version: string; licenseName: string|null; parentPackages: string[]; }
-
package.json
Emitted for eachpackage.json
file being checked. This is emitted only when checking local repositories or GitHub repositories, but not when checking remote packages.The argument is a file path string of the corresponding
package.json
file. -
end
Emitted when the processing is done. No argument is given. -
error
Emitted when an error occurrs while processing. The argument isinterface CheckError { err: Error; packageName: string; versionSpec: string; parentPackages: string[]; }