https://github.com/google/js-green-licenses
JavaScript package.json License Checker
https://github.com/google/js-green-licenses
Last synced: about 1 year ago
JSON representation
JavaScript package.json License Checker
- Host: GitHub
- URL: https://github.com/google/js-green-licenses
- Owner: google
- License: apache-2.0
- Created: 2017-12-21T17:15:27.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-06-20T19:36:09.000Z (almost 2 years ago)
- Last Synced: 2025-03-18T13:05:41.873Z (about 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 1.8 MB
- Stars: 179
- Watchers: 3
- Forks: 27
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-typescript - js-green-licenses - JavaScript package.json License Checker. (Table of Contents / Node Modules)
README
# 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.
### Instantiation
```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.
### Use in Gulp
```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('.');
});
```
### Methods
* `LicenseChecker#setDefaultHandler()`
```typescript
setDefaultHandlers(): void;
```
Sets the default event handlers that are used by the CLI. For events
emitted by `LicenseChecker`, see the [*Events*](#hd-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](#cli)
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](#cli) 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`.
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