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 = [
  '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:

{
  "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

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 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()

  checkRemotePackage(pkg: string): Promise<void>;

  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()

  checkGitHubPR(repo: GitHubRepository, mergeCommitSha): Promise<void>;

  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()

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

  prPath must be in the form, <owner>/<repo>/pull/<id>. 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

  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

  interface CheckError {
    err: Error;
    packageName: string;
    versionSpec: string;
    parentPackages: string[];
  }