diff --git a/lib/src/commands/packages/commands/check/commands/licenses.dart b/lib/src/commands/packages/commands/check/commands/licenses.dart index 9aa605433..10c53bcd6 100644 --- a/lib/src/commands/packages/commands/check/commands/licenses.dart +++ b/lib/src/commands/packages/commands/check/commands/licenses.dart @@ -18,6 +18,12 @@ const pubspecLockBasename = 'pubspec.lock'; Uri pubLicenseUri(String packageName) => Uri.parse('https://pub.dev/packages/$packageName/license'); +/// The URI for the very_good_cli license documentation page. +@visibleForTesting +final licenseDocumentationUri = Uri.parse( + 'https://cli.vgv.dev/docs/commands/check_licenses', +); + /// Defines a [Map] with dependencies as keys and their licenses as values. /// /// If a dependency's license failed to be retrieved its license will be `null`. @@ -111,8 +117,12 @@ class PackagesCheckLicensesCommand extends Command { ...forbiddenLicenses, ]); if (invalidLicenses.isNotEmpty) { + final documentationLink = link( + uri: licenseDocumentationUri, + message: 'documentation', + ); _logger.warn( - '''Some licenses failed to be recognized: ${invalidLicenses.stringify()}. Refer to the documentation for a list of valid licenses.''', + '''Some licenses failed to be recognized: ${invalidLicenses.stringify()}. Refer to the $documentationLink for a list of valid licenses.''', ); } diff --git a/site/docs/commands/check_licenses.md b/site/docs/commands/check_licenses.md new file mode 100644 index 000000000..9caf64492 --- /dev/null +++ b/site/docs/commands/check_licenses.md @@ -0,0 +1,109 @@ +--- +sidebar_position: 3 +--- + +# Check licenses 👨‍⚖️ + +Very Good CLI offers a simple and straightforward license checker for dependencies hosted by [Dart's package manager][pub]. Allowing developers to easily keep track of the rights and restrictions external dependencies might impose on their projects. + +## Quick Start 🚀 + +To get started, install [Very Good CLI](https://cli.vgv.dev/docs/overview#quick-start-) and run the following command within your Dart or Flutter project: + +```sh +very_good packages check licenses +``` + +:::info +The license checker requires an internet connection to fetch the data from [Dart's package manager][pub]. +::: + +## Arguments ⚙️ + +### `allowed` + +Only allows the use of certain licenses. The command will exit with an error and log the list of all the dependencies that have an unlisted license. + +#### Example usage: + +```sh +very_good packages check licenses --allowed=MIT,BSD-3-Clause + +# ✓ Retrieved 6 licenses from 6 packages of type: BSD-3-Clause (3), MIT (1), unknown (1) and Apache-2.0 (1). +# 2 dependencies have banned licenses: html (unknown) and universal_io (Apache-2.0). +``` + +:::info +A comprehensive list of all the licenses allowed as options is available within the [_Supported licenses_](#supported-licenses-💳) section of this document. +::: + +### `forbidden` + +Deny the use of certain licenses. The command will exit with an error and log the list of all the dependencies that have a blocked license. + +#### Example usage: + +```sh +very_good packages check licenses --forbidden=unknown,Apache-2.0 + +# ✓ Retrieved 6 licenses from 6 packages of type: BSD-3-Clause (3), MIT (1), unknown (1) and Apache-2.0 (1). +# 2 dependencies have banned licenses: html (unknown) and universal_io (Apache-2.0). +``` + +:::warning +The `allowed` and `forbidden` options can't be used at the same time. Typical organization usage dictates which licenses are allowed or forbidden, hence optimizing for that use case. +::: + +### `dependency-type` + +The type of dependencies to check licenses for. There are three available types: + +- [`direct-dev`](https://dart.dev/tools/pub/dependencies#dev-dependencies): Another package that your package needs during development. +- [`direct-main`](https://dart.dev/tools/pub/dependencies): Another package that your package needs to work. +- [`transitive`](https://dart.dev/tools/pub/glossary#transitive-dependency): A dependency that your package indirectly uses because one of its dependencies requires it. + +When unspecified, it defaults to `direct-main`. + +#### Example usage: + +```sh +very_good packages check licenses --dependency-type=direct-main,transitive + +# ✓ Retrieved 83 licenses from 82 packages of type: BSD-3-Clause (65), MIT (15), unknown (1), BSD-2-Clause (1) and Apache-2.0 (1). +``` + +:::info +The license checker only requires a [lockfile](https://dart.dev/tools/pub/glossary#lockfile) to gather dependencies. The lockfile is generated automatically for you by [pub][pub] when you run `pub get`, `pub upgrade`, or `pub downgrade`. +::: + +### `skip-packages` + +Skips packages from having their licenses checked. Skipped packages will not be checked against `allowed` or `forbidden` licenses. + +#### Example usage: + +```sh +very_good packages check licenses --skip-packages=html,universal_io + +# ✓ Retrieved 4 licenses from 4 packages of type: BSD-3-Clause (3) and MIT (1). +``` + +### `ignore-retrieval-failures` + +Disregard licenses that failed to be retrieved. Avoids terminating if the license of a dependency could not be retrieved; this may happen if something went wrong when fetching information from [pub][pub]. + +#### Example usage: + +```sh +very_good packages check licenses --ignore-retrieval-failures + +# ✓ Retrieved 6 licenses from 6 packages of type: BSD-3-Clause (3), MIT (1), unknown (1) and Apache-2.0 (1). +``` + +## Supported licenses 💳 + +The license detection is processed by [Dart's package analyzer](https://pub.dev/packages/pana), which reports commonly found licenses (SPDX licenses). The list of accepted licenses can be seen in the [SPDX GitHub repository](https://github.com/spdx/license-list-data/tree/main/text) or in the [SPDX License enumeration](https://github.com/VeryGoodOpenSource/very_good_cli/blob/main/lib/src/pub_license/spdx_license.gen.dart). Therefore, when specifying a license within arguments it must strictly match with the SPDX license name. + +If a license file is incorrectly formatted or is not a commonly found license, then it might be reported as `unknown`. If the former is true, we suggest notifying the package maintainer about the issue. + +[pub]: https://pub.dev/ diff --git a/test/src/commands/packages/commands/check/commands/licenses_test.dart b/test/src/commands/packages/commands/check/commands/licenses_test.dart index 940a6743b..f9927cbb1 100644 --- a/test/src/commands/packages/commands/check/commands/licenses_test.dart +++ b/test/src/commands/packages/commands/check/commands/licenses_test.dart @@ -661,8 +661,12 @@ void main() { ], ); - const warningMessage = - '''Some licenses failed to be recognized: $invalidLicense. Refer to the documentation for a list of valid licenses.'''; + final documentationLink = link( + uri: licenseDocumentationUri, + message: 'documentation', + ); + final warningMessage = + '''Some licenses failed to be recognized: $invalidLicense. Refer to the $documentationLink for a list of valid licenses.'''; verify( () => logger.warn(warningMessage), ).called(1); @@ -813,8 +817,12 @@ void main() { ], ); - const warningMessage = - '''Some licenses failed to be recognized: $invalidLicense. Refer to the documentation for a list of valid licenses.'''; + final documentationLink = link( + uri: licenseDocumentationUri, + message: 'documentation', + ); + final warningMessage = + '''Some licenses failed to be recognized: $invalidLicense. Refer to the $documentationLink for a list of valid licenses.'''; verify( () => logger.warn(warningMessage), ).called(1);