npm package: @rio-cloud/rio-license-checker
Description: Helps checking third-party libraries' licenses according to RIO guidelines.
Author: TB Digital Services GmbH
Latest version: 1.2.2

# [@rio-cloud/rio-license-checker](https://www.npmjs.com/package/@rio-cloud/rio-license-checker)

Helps checking third-party libraries' licenses according to RIO guidelines.

## Usage

```shell
# general usage information
npx @rio-cloud/rio-license-checker help

# information on the default "run-check" command
npx @rio-cloud/rio-license-checker help run-check

# information on the "download-whitelist" command
npx @rio-cloud/rio-license-checker help download-whitelist

# information on the "upload-report" command
npx @rio-cloud/rio-license-checker help upload-report
```

The `run-check` command is the default command. The command name is optional:

```shell
npx @rio-cloud/rio-license-checker run-check -a rio-example -s example-service -t npm-frontend
# is the same as
npx @rio-cloud/rio-license-checker -a rio-example -s example-service -t npm-frontend
```

## Automatic mode (a.k.a. `run-check`)

1. Downloads the appropriate license whitelist that's curated by the RIO Security Guild from a central location.
2. Orchestrates a 3rd-party license checking tool to inspect your project's dependencies.
   * If any dependency is found with non-compliant license information, this tool will exit with a non-zero code.
   * If all dependencies are okay: generate a report file containing the list of dependencies, their versions, and their
     respective license information.
3. Uploads the report to a central location (optional; this is only done when the `--upload` flag is set). 

### `gradle`

* The underlying license report tool is [hierynomus/license-gradle-plugin](https://github.com/hierynomus/license-gradle-plugin).
* You need to *include & configure the plugin in your `build.gradle.kts`*.
* The output of the plugin is compared with the whitelist programmatically (as we used to do in the `build.gradle.kts`).
* For subprojects, you need a separate invocation of the license checker, where the directory points to the subproject.
    * Currently, only subprojects directly below the root project are supported (limited by where the checker looks for
      the gradle wrapper).
    * When doing so, take care to specify a different service name to prevent overwriting the license report of the root
      project.
    * Please see below for examples.

```shell
npx @rio-cloud/rio-license-checker -a rio-example -s example-service -t gradle
npx @rio-cloud/rio-license-checker -a rio-example -s example-service_sub-project -t gradle -d ./sub-project
```

### `npm-frontend` and `npm-backend`

* The underlying license checker tool is [license-checker-rseidelsohn](https://www.npmjs.com/package/license-checker-rseidelsohn).
* The license checker generates a report and compares the licenses to the passed whitelist.
* The application's own package is automatically excluded from the report, as it (usually) does not have a license.
* For testability reasons, we cannot use the programmatic interface of the tool. Instead, we call it as a subprocess via
  `zx`.
* You can exclude dependencies by creating a `oss-licenses-ignore-packages.txt` file in the project directory.
* Note that this will _statically_ inspect the dependencies as defined in your `package.json`. Especially for frontends,
  this might not be accurate enough. Check out the "manual" type for `npm-frontend-bundled` below.

## `download-whitelist`

To just download the appropriate whitelist file as-is without any processing or running the check, you can use the
`download-whitelist` command:

```shell
npx @rio-cloud/rio-license-checker download-whitelist -t npm-frontend-bundled
```

Note that this will only work when the current session has access to AWS.

Also note that this only supports the "npm-frontend-bundled" type at the moment, which will save the whitelist as
`frontend-license-whitelist.json` in the project directory.

This command supports a `directory` and `verbose` option, as well. Check out the usage docs for more info.

## `upload-report`

If your license check is handled by another tool during the build, you can use the `upload-report` command to upload the
report output from a given file.

```shell
npx @rio-cloud/rio-license-checker upload-report -a rio-example -s example-service -t npm-frontend-bundled -r ./build/libraries.json
```

Note that this only supports the "npm-frontend-bundled" type at the moment.

This command supports a `verbose` option, as well. Check out the usage docs for more info.