docs: include license checking page (#860)

Author: alestiago

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<int> {
       ...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.''',
       );
     }
 

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/

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