JavaScript package.json License Checker

[![npm Version][npm-image]][npm-url]
[![CI][actions-image]][actions-url]
[![Dependency Status][david-image]][david-url]
[![Known Vulnerabilities][snyk-image]][snyk-url]
[![Code Style: Google][gts-image]][gts-url]

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

``shell
npm install [--save-dev] js-green-licenses
`

If you want to install globally,

`shell
npm install -g js-green-licenses
`

CLI

`
usage: jsgl [-h] [-v] [--local ] [--pr ]
[--dev] [--verbose] []

License checker for npm modules

Positional arguments:

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 , -l
Check a local directory instead of public npm.
--pr Check a github pull request. Must be
//pull/
--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
//pull/ 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:
`javascript
const DEFAULT_GREEN_LICENSES = [
'0BSD', '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 allowlist 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 allowlist that package to make jsgl not complain about that
package.

A typical configuration file looks like this:
`javascript
{
"greenLicenses": [
// Custom green licenses.
"Apache-2.0",
"MIT",
"BSD-3-Clause",
...
],
"packageAllowlist": [
/ 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
packageAllowlist section is for the package allowlist.

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.

$3

`javascript
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.

$3

`javascript
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('.');
});
`

$3

* LicenseChecker#setDefaultHandler()

`typescript
setDefaultHandlers(): void;
`

Sets the default event handlers that are used by the CLI. For events
emitted by LicenseChecker, see the Events subsection.

* LicenseChecker#checkLocalDirectory()

`typescript
checkLocalDirectory(directory: string): Promise;
`

This provides the functionality of the CLI when the --local flag is
passed. It finds and checks the package.json file in the directory 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 directory, if it exists.

* LicenseChecker#checkRemotePackage()

`typescript
checkRemotePackage(pkg: string): Promise;
`

This provides the functionality of the CLI when neither --local or
--pr is passed. It retrieves and checks the package.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()

`typescript
checkGitHubPR(repo: GitHubRepository, mergeCommitSha): Promise;
`

This provides the functionality of the CLI when the --pr flag is
passed. It retrieves the package.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 calling
LicenseChecker#prPathToGitHubRepoAndId().

* LicenseChecker#prPathToGitHubRepoAndId()

`typescript
prPathToGitHubRepoAndId(prPath: string): {
repo: GitHubRepository;
prId: string;
};
`

prPath must be in the form, //pull/. This method
will return the GitHubRepository instance and the PR id for the
prPath.

$3

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 is
`typescript
interface NonGreenLicense {
packageName: string;
version: string;
licenseName: string|null;
parentPackages: string[];
}
`

* package.json
Emitted for each package.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 is
`typescript
interface CheckError {
err: Error;
packageName: string;
versionSpec: string;
parentPackages: string[];
}
``

[actions-image]: https://github.com/google/js-green-licenses/workflows/ci/badge.svg
[actions-url]: https://github.com/google/js-green-licenses/actions
[codecov-url]: https://codecov.io/gh/google/js-green-licenses
[david-image]: https://david-dm.org/google/js-green-licenses.svg
[david-url]: https://david-dm.org/google/js-green-licenses
[gts-image]: https://img.shields.io/badge/code%20style-google-blueviolet.svg
[gts-url]: https://github.com/google/gts
[npm-image]: https://img.shields.io/npm/v/js-green-licenses.svg
[npm-url]: https://npmjs.org/package/js-green-licenses
[snyk-image]: https://snyk.io/test/github/google/js-green-licenses/badge.svg
[snyk-url]: https://snyk.io/test/github/google/js-green-licenses