licensee

Check npm package dependency license metadata against rules.

Configuration

Licensee accepts two kinds of configuration:

1. a rule about permitted licenses
2. a package allowlist of name-and-range pairs

You can set configuration with command flags or a .licensee.json
file at the root of your package, like so:

 {
  "licenses": {
    "spdx": [
      "MIT",
      "BSD-2-Clause",
      "BSD-3-Clause",
      "Apache-2.0"
    ]
  },
  "packages": {
    "optimist": "<=0.6.1"
  },
  "corrections": false,
  "ignore": [
    {"scope": "kemitchell"},
    {"prefix": "commonform-"},
    {"author": "Kyle E. Mitchell"}
  ]
}

The licenses object adds licenses to an allowlist.
Any package with standard license metadata
that satisfies that allowlist according to
spdx-whitelisted will not cause an error.

Instead of allowlisting each license by SPDX identifier,
you can allowlist categories of licenses.

For example, you can specify a minimum Blue Oak Council license
rating---lead, bronze, silver, or gold---like so:

 {
  "licenses": {
    "blueOak": "bronze"
  }
}

You can combine categories and specific license identifiers, too:

 {
  "licenses": {
    "spdx": ["CC-BY-4.0"],
    "blueOak": "gold"
  }
}

The packages property is a map from package name to a
node-semver Semantic Versioning range. Packages whose
license metadata don't match the SPDX license expression in
licenses but have a name and version described in packages
will not cause an error.

The corrections flag toggles community corrections to npm
package license metadata. When enabled, licensee will check
against license values from npm-license-corrections when
available, and also use correct-license-metadata to try to
correct old-style licenses arrays and other unambiguous, but
invalid, metadata.

The optional ignore array instructs licensee to approve packages
without considering their license metadata. Ignore rules can take
one of three forms:

1. {"scope":"x"} ignores all packages in scope x, like @x/y.

2. {"prefix":"x"} ignores all packages whose names start with x,
   but not scoped packages whose scopes do not match, like @y/x.

3. {"author":"x"} ignores all packages whose authors' names,
   e-mail addresses, or URLs contain x.

All ignore rules are case-insensitive.

Use

To install and use licensee globally:

 npm install --global licensee
cd your-package
licensee --init
licensee

The licensee script prints a report about dependencies and their
license terms to standard output. It exits with status 0 when all
packages in ./node_modules meet the configured licensing criteria
and 1 when one or more do not.

To install it as a development dependency of your package:

 cd your-package
npm install --save-dev licensee

Consider adding licensee to your npm scripts:

 {
  "scripts": {
    "posttest": "licensee"
  }
}

To check only production dependencies, ignoring development dependencies,
use --production flag:

 {
  "scripts": {
    "posttest": "licensee --production"
  }
}

For output as newline-delimited JSON objects, for further processing:

 {
  "scripts": {
    "posttest": "licensee --ndjson"
  }
}

To skip the readout of license information:

 {
  "scripts": {
    "posttest": "licensee --quiet"
  }
}

If you want a readout of dependency information, but don't want
your continuous integration going red, you can ignore licensee's
exit code:

 {
  "scripts": {
    "posttest": "licensee || true"
  }
}

To save the readout of license information to a file:

 {
  "scripts": {
    "posttest": "licensee | tee LICENSES || true"
  }
}

Alternatively, for a readout of just packages without approved licenses:

 {
  "scripts": {
    "posttest": "licensee --errors-only"
  }
}

JavaScript Module

The package exports an asynchronous function of three arguments:

1. A configuration object in the same form as .licensee.json.

2. The path of the package to check.

3. An error-first callback that yields an array of objects, one per
   dependency.