Skip to content

feat: license-kit dependency scan config - transitive & dev dependencies; adjusted behaviour for --error-on-weak #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
artus9033 merged 8 commits into from
Jun 18, 2025
Merged

feat: license-kit dependency scan config - transitive & dev dependencies; adjusted behaviour for --error-on-weak #47

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3f9541e
feat: dependency scanning configuration for transitive & development …
artus9033 Jun 14, 2025
4c7b7ad
docs: updated license-kit options listing in docs
artus9033 Jun 17, 2025
8d7db33
feat: updated license-kit help options listing & formatting
artus9033 Jun 17, 2025
167773b
feat: license-kit --dev-deps-mode flag set to 'root-only' by default
artus9033 Jun 17, 2025
a1990c7
docs: described discrepancy of license-kit & shared package default v…
artus9033 Jun 17, 2025
b3a64bb
docs: update CLI's default --dev-deps-mode value in README.md
artus9033 Jun 17, 2025
fb3d410
feat: adjust CLI copyleft command behaviour depending on --error-on-w…
artus9033 Jun 18, 2025
d68c88c
docs: updated docs with exit adjusted codes
artus9033 Jun 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/curly-lines-stay.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'license-kit': minor
---

Feature: flags for dependency scanning configuration for transitive & development dependencies
27 changes: 27 additions & 0 deletions docs/docs/docs/programmatic-usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,3 +95,30 @@ The tool recognizes various license types:
:::info
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.
:::

### Default `scanOptionsFactory` value

The default value for the optional `scanOptionsFactory` parameter in `scanPackage` & `scanDependencies` functions is set to the following:

```typescript
{
includeTransitiveDependencies: true,
includeDevDependencies: false,
}
```

Which can be found in [`ScanPackageOptions.ts`](/packages/shared/src/types/ScanPackageOptions.ts).

:::warning
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.

To achieve the same default behaviour as in the CLI (`root-only`), set `includeDevDependencies` to `isRoot` in the programmatic API:

```typescript
const optionsFactory: Types.ScanPackageOptionsFactory = ({ isRoot }) => ({
includeDevDependencies: isRoot,
includeTransitiveDependencies: ...,
});
```

:::
38 changes: 28 additions & 10 deletions docs/docs/docs/standalone-cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,22 +60,32 @@ npx license-kit copyleft --help

#### Command: `copyleft`

Check for copyleft licenses. Exits with error code (≠ 0) if strong copyleft licenses are found.
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.

| Flag / Option | Description | Default |
| --------------- | -------------------------------------------------------- | ------------------------- |
| --root \<path\> | Path to the root of your project | Current working directory |
| --error-on-weak | Exit with error code if weak copyleft licenses are found | `false` |
Exit codes:

- `0` - no copyleft licenses found
- `1` - strong copyleft licenses found
- `2` - weak copyleft licenses found (if `--error-on-weak` is set)

| Flag / Option | Description | Default |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
| `--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'` |
| `--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'` |
| `--root [path]` | Path to the root of your project | Current working directory |
| `--error-on-weak` | Exit with error code if weak copyleft licenses are found | `false` |

#### Command: `report`

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

| Flag / Option | Description | Default |
| ----------------- | --------------------------------------------------------------------------------------------------- | ------------------------- |
| --root \<path\> | Path to the root of your project | Current working directory |
| --format \<type\> | Output format, one of: `'json'`, `'about-json'` (AboutLibraries-compatible), `'text'`, `'markdown'` | `'json'` |
| --output \<path\> | Where to write the output - either `'stdout'` or a path to an output file | `'stdout'` |
| Flag / Option | Description | Default |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
| `--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'` |
| `--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'` |
| `--root [path]` | Path to the root of your project | Current working directory |
| `--format [type]` | Output format, one of: `'json'`, `'about-json'` (AboutLibraries-compatible), `'text'`, `'markdown'` | `'json'` |
| `--output [path]` | Where to write the output - either `'stdout'` or a path to an output file | `'stdout'` |

#### Command: `help`

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

## Additional details

:::warning
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`).

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.

If you want the same behaviour as in the programmatic API, you can set the `--dm` option to `none` when running the CLI.
:::

For more notes on the mechanics of the tool, please see [core additional details section](/docs/programmatic-usage#additional-details).
30 changes: 20 additions & 10 deletions packages/license-kit/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,22 +54,32 @@ npx license-kit copyleft --help

#### Command: `copyleft`

Check for copyleft licenses. Exits with error code (≠ 0) if strong copyleft licenses are found.
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.

| Flag / Option | Description | Default |
| --------------- | -------------------------------------------------------- | ------------------------- |
| --root <path> | Path to the root of your project | Current working directory |
| --error-on-weak | Exit with error code if weak copyleft licenses are found | `false` |
Exit codes:

- `0` - no copyleft licenses found
- `1` - strong copyleft licenses found
- `2` - weak copyleft licenses found (if `--error-on-weak` is set)

| Flag / Option | Description | Default |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
| `--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'` |
| `--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'` |
| `--root [path]` | Path to the root of your project | Current working directory |
| `--error-on-weak` | Exit with error code if weak copyleft licenses are found | `false` |

#### Command: `report`

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

| Flag / Option | Description | Default |
| --------------- | --------------------------------------------------------------------------------------------------- | ------------------------- |
| --root <path> | Path to the root of your project | Current working directory |
| --format <type> | Output format, one of: `'json'`, `'about-json'` (AboutLibraries-compatible), `'text'`, `'markdown'` | `'json'` |
| --output <path> | Where to write the output - either `'stdout'` or a path to an output file | `'stdout'` |
| Flag / Option | Description | Default |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
| `--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'` |
| `--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'` |
| `--root [path]` | Path to the root of your project | Current working directory |
| `--format [type]` | Output format, one of: `'json'`, `'about-json'` (AboutLibraries-compatible), `'text'`, `'markdown'` | `'json'` |
| `--output [path]` | Where to write the output - either `'stdout'` or a path to an output file | `'stdout'` |

#### Command: `help`

Expand Down
10 changes: 10 additions & 0 deletions packages/license-kit/src/constants.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,13 @@ export const WEAK_COPYLEFT_LICENSES = [
'MPL-1.1',
'MPL-2.0',
];

/**
* The characters printed as prefix of any sublisting in a help message decsribing usage of flags or commands;
* \t cannot be used on its own since it would break Commander.js's auto-alignment of help listing items,
* therefore U+2063 invisible separator (which is a non-whitespace character is used before a \t)
*/
export const NON_TAB_HELP_LISTING_SUBLIST_OFFSET = '\u2063\t';

export const ERROR_EMOJI = '❌';
export const WARNING_EMOJI = '⚠️';
Loading
Loading