Skip to content

Commit a836940

Browse files
artus9033artus9033
authored
feat: license-kit dependency scan config - transitive & dev dependencies; adjusted behaviour for --error-on-weak (#47)
* feat: dependency scanning configuration for transitive & development dependencies * docs: updated license-kit options listing in docs * feat: updated license-kit help options listing & formatting * feat: license-kit --dev-deps-mode flag set to 'root-only' by default * docs: described discrepancy of license-kit & shared package default values for dev dependency mode * docs: update CLI's default --dev-deps-mode value in README.md * feat: adjust CLI copyleft command behaviour depending on --error-on-weak, adjusted exit codes & help * docs: updated docs with exit adjusted codes
1 parent b644f22 commit a836940

10 files changed

Lines changed: 345 additions & 109 deletions

File tree

‎.changeset/curly-lines-stay.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'license-kit': minor
3+
---
4+
5+
Feature: flags for dependency scanning configuration for transitive & development dependencies

‎docs/docs/docs/programmatic-usage.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,30 @@ The tool recognizes various license types:
9595
:::info
9696
If a monorepo package is private, its name and license won't be included in the license list, but its dependencies will still be scanned and included.
9797
:::
98+
99+
### Default `scanOptionsFactory` value
100+
101+
The default value for the optional `scanOptionsFactory` parameter in `scanPackage` & `scanDependencies` functions is set to the following:
102+
103+
```typescript
104+
{
105+
includeTransitiveDependencies: true,
106+
includeDevDependencies: false,
107+
}
108+
```
109+
110+
Which can be found in [`ScanPackageOptions.ts`](/packages/shared/src/types/ScanPackageOptions.ts).
111+
112+
:::warning
113+
This default `includeDevDependencies` behaviour is different from the default values of `license-kit` CLI's equivalent flag `--dev-deps-mode`, which is set to `root-only` by default.
114+
115+
To achieve the same default behaviour as in the CLI (`root-only`), set `includeDevDependencies` to `isRoot` in the programmatic API:
116+
117+
```typescript
118+
const optionsFactory: Types.ScanPackageOptionsFactory = ({ isRoot }) => ({
119+
includeDevDependencies: isRoot,
120+
includeTransitiveDependencies: ...,
121+
});
122+
```
123+
124+
:::

‎docs/docs/docs/standalone-cli.mdx‎

Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -60,22 +60,32 @@ npx license-kit copyleft --help
6060

6161
#### Command: `copyleft`
6262

63-
Check for copyleft licenses. Exits with error code (≠ 0) if strong copyleft licenses are found.
63+
Check for copyleft licenses. Exits with error code (≠ 0) if strong copyleft licenses are found. Can be configured to exit with non-zero exit code if weak copyleft licenses are found as well.
6464

65-
| Flag / Option | Description | Default |
66-
| --------------- | -------------------------------------------------------- | ------------------------- |
67-
| --root \<path\> | Path to the root of your project | Current working directory |
68-
| --error-on-weak | Exit with error code if weak copyleft licenses are found | `false` |
65+
Exit codes:
66+
67+
- `0` - no copyleft licenses found
68+
- `1` - strong copyleft licenses found
69+
- `2` - weak copyleft licenses found (if `--error-on-weak` is set)
70+
71+
| Flag / Option | Description | Default |
72+
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
73+
| `--tm, --transitive-deps-mode [mode]` | Controls, which transitive dependencies are included: <ul><li>`'all'`</li> <li>`'from-external-only'` (only transitive dependencies of direct dependencies specified by non-workspace:... specifiers)</li> <li>`'from-workspace-only'` (only transitive dependencies of direct dependencies specified by `workspace:` specifier)</li> <li>`'none'`</li></ul> | `'all'` |
74+
| `--dm, --dev-deps-mode [mode]` | <ul><li>`'root-only'` (only direct devDependencies from the scanned project's root package.json)</li> <li>`'none'`</li></ul> | `'root-only'` |
75+
| `--root [path]` | Path to the root of your project | Current working directory |
76+
| `--error-on-weak` | Exit with error code if weak copyleft licenses are found | `false` |
6977

7078
#### Command: `report`
7179

7280
Generates a licenses report in the specified format. The output can be written to `stdout` (default) or a file.
7381

74-
| Flag / Option | Description | Default |
75-
| ----------------- | --------------------------------------------------------------------------------------------------- | ------------------------- |
76-
| --root \<path\> | Path to the root of your project | Current working directory |
77-
| --format \<type\> | Output format, one of: `'json'`, `'about-json'` (AboutLibraries-compatible), `'text'`, `'markdown'` | `'json'` |
78-
| --output \<path\> | Where to write the output - either `'stdout'` or a path to an output file | `'stdout'` |
82+
| Flag / Option | Description | Default |
83+
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
84+
| `--tm, --transitive-deps-mode [mode]` | Controls, which transitive dependencies are included: <ul><li>`'all'`</li> <li>`'from-external-only'` (only transitive dependencies of direct dependencies specified by non-workspace:... specifiers)</li> <li>`'from-workspace-only'` (only transitive dependencies of direct dependencies specified by `workspace:` specifier)</li> <li>`'none'`</li></ul> | `'all'` |
85+
| `--dm, --dev-deps-mode [mode]` | <ul><li>`'root-only'` (only direct devDependencies from the scanned project's root package.json)</li> <li>`'none'`</li></ul> | `'root-only'` |
86+
| `--root [path]` | Path to the root of your project | Current working directory |
87+
| `--format [type]` | Output format, one of: `'json'`, `'about-json'` (AboutLibraries-compatible), `'text'`, `'markdown'` | `'json'` |
88+
| `--output [path]` | Where to write the output - either `'stdout'` or a path to an output file | `'stdout'` |
7989

8090
#### Command: `help`
8191

@@ -101,4 +111,12 @@ General options that can be passed to the CLI with after any command.
101111

102112
## Additional details
103113

114+
:::warning
115+
While the `--dev-deps-mode` option is set to `root-only` by default in the CLI, the programmatic API package has a default value for the optional `scanOptionsFactory` that has `includeDevDependencies` set to `false` by default (equivalent of CLI's `none`).
116+
117+
The reason for this discrepancy is to provide default behaviour backwards compatibility & consistency for the shared package while maintaining usability of the CLI. Sometimes bundlers do not take into account the fact the a dependency is a `devDependency`, which results in them being bundled. Therefore, the CLI by default aggregates their licenses as well.
118+
119+
If you want the same behaviour as in the programmatic API, you can set the `--dm` option to `none` when running the CLI.
120+
:::
121+
104122
For more notes on the mechanics of the tool, please see [core additional details section](/docs/programmatic-usage#additional-details).

‎packages/license-kit/README.md‎

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -54,22 +54,32 @@ npx license-kit copyleft --help
5454

5555
#### Command: `copyleft`
5656

57-
Check for copyleft licenses. Exits with error code (≠ 0) if strong copyleft licenses are found.
57+
Check for copyleft licenses. Exits with error code (≠ 0) if strong copyleft licenses are found. Can be configured to exit with non-zero exit code if weak copyleft licenses are found as well.
5858

59-
| Flag / Option | Description | Default |
60-
| --------------- | -------------------------------------------------------- | ------------------------- |
61-
| --root <path> | Path to the root of your project | Current working directory |
62-
| --error-on-weak | Exit with error code if weak copyleft licenses are found | `false` |
59+
Exit codes:
60+
61+
- `0` - no copyleft licenses found
62+
- `1` - strong copyleft licenses found
63+
- `2` - weak copyleft licenses found (if `--error-on-weak` is set)
64+
65+
| Flag / Option | Description | Default |
66+
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
67+
| `--tm, --transitive-deps-mode [mode]` | Controls, which transitive dependencies are included: <ul><li>`'all'`</li> <li>`'from-external-only'` (only transitive dependencies of direct dependencies specified by non-workspace:... specifiers)</li> <li>`'from-workspace-only'` (only transitive dependencies of direct dependencies specified by `workspace:` specifier)</li> <li>`'none'`</li></ul> | `'all'` |
68+
| `--dm, --dev-deps-mode [mode]` | <ul><li>`'root-only'` (only direct devDependencies from the scanned project's root package.json)</li> <li>`'root-only'`</li></ul> | `'none'` |
69+
| `--root [path]` | Path to the root of your project | Current working directory |
70+
| `--error-on-weak` | Exit with error code if weak copyleft licenses are found | `false` |
6371

6472
#### Command: `report`
6573

6674
Generates a licenses report in the specified format. The output can be written to `stdout` (default) or a file.
6775

68-
| Flag / Option | Description | Default |
69-
| --------------- | --------------------------------------------------------------------------------------------------- | ------------------------- |
70-
| --root <path> | Path to the root of your project | Current working directory |
71-
| --format <type> | Output format, one of: `'json'`, `'about-json'` (AboutLibraries-compatible), `'text'`, `'markdown'` | `'json'` |
72-
| --output <path> | Where to write the output - either `'stdout'` or a path to an output file | `'stdout'` |
76+
| Flag / Option | Description | Default |
77+
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
78+
| `--tm, --transitive-deps-mode [mode]` | Controls, which transitive dependencies are included: <ul><li>`'all'`</li> <li>`'from-external-only'` (only transitive dependencies of direct dependencies specified by non-workspace:... specifiers)</li> <li>`'from-workspace-only'` (only transitive dependencies of direct dependencies specified by `workspace:` specifier)</li> <li>`'none'`</li></ul> | `'all'` |
79+
| `--dm, --dev-deps-mode [mode]` | <ul><li>`'root-only'` (only direct devDependencies from the scanned project's root package.json)</li> <li>`'root-only'`</li></ul> | `'none'` |
80+
| `--root [path]` | Path to the root of your project | Current working directory |
81+
| `--format [type]` | Output format, one of: `'json'`, `'about-json'` (AboutLibraries-compatible), `'text'`, `'markdown'` | `'json'` |
82+
| `--output [path]` | Where to write the output - either `'stdout'` or a path to an output file | `'stdout'` |
7383

7484
#### Command: `help`
7585

‎packages/license-kit/src/constants.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,13 @@ export const WEAK_COPYLEFT_LICENSES = [
4747
'MPL-1.1',
4848
'MPL-2.0',
4949
];
50+
51+
/**
52+
* The characters printed as prefix of any sublisting in a help message decsribing usage of flags or commands;
53+
* \t cannot be used on its own since it would break Commander.js's auto-alignment of help listing items,
54+
* therefore U+2063 invisible separator (which is a non-whitespace character is used before a \t)
55+
*/
56+
export const NON_TAB_HELP_LISTING_SUBLIST_OFFSET = '\u2063\t';
57+
58+
export const ERROR_EMOJI = '❌';
59+
export const WARNING_EMOJI = '⚠️';

0 commit comments

Comments
 (0)