# 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:

```json
{
  "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][metadata]
that satisfies that allowlist according to
[spdx-whitelisted][allowed] will not cause an error.

[parse]: https://www.npmjs.com/package/spdx-expression-parse
[allowed]: https://www.npmjs.com/package/spdx-whitelisted

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:

[license rating]: https://blueoakcouncil.org/list

```json
{
  "licenses": {
    "blueOak": "bronze"
  }
}
```

You can combine categories and specific license identifiers, too:

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

The `packages` property is a map from package name to a
[node-semver][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.

[metadata]: https://docs.npmjs.com/files/package.json#license
[semver]: https://www.npmjs.com/package/semver

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.

[npm-license-corrections]: https://www.npmjs.com/package/npm-license-corrections

[correct-license-metadata]: https://www.npmjs.com/package/correct-license-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:

```bash
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:

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

Consider adding `licensee` to your npm scripts:

```json
{
  "scripts": {
    "posttest": "licensee"
  }
}
```

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

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

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

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

To skip the readout of license information:

```json
{
  "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:

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

To save the readout of license information to a file:

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

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

```json
{
  "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.