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