Skip to content

Commit daaa8be

Browse files
artus9033artus9033
committed
docs: described discrepancy of license-kit & shared package default values for dev dependency mode
1 parent e595959 commit daaa8be

2 files changed

Lines changed: 37 additions & 2 deletions

File tree

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,3 +94,30 @@ The tool recognizes various license types:
9494
:::info
9595
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.
9696
:::
97+
98+
### Default `scanOptionsFactory` value
99+
100+
The default value for the optional `scanOptionsFactory` parameter in `scanPackage` & `scanDependencies` functions is set to the following:
101+
102+
```typescript
103+
{
104+
includeTransitiveDependencies: true,
105+
includeDevDependencies: false,
106+
}
107+
```
108+
109+
Which can be found in [`ScanPackageOptions.ts`](/packages/shared/src/types/ScanPackageOptions.ts).
110+
111+
:::warning
112+
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.
113+
114+
To achieve the same default behaviour as in the CLI (`root-only`), set `includeDevDependencies` to `isRoot` in the programmatic API:
115+
116+
```typescript
117+
const optionsFactory: Types.ScanPackageOptionsFactory = ({ isRoot }) => ({
118+
includeDevDependencies: isRoot,
119+
includeTransitiveDependencies: ...,
120+
});
121+
```
122+
123+
:::

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

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ Check for copyleft licenses. Exits with error code (≠ 0) if strong copyleft li
6565
| Flag / Option | Description | Default |
6666
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
6767
| `--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>`'none'`</li></ul> | `'none'` |
68+
| `--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'` |
6969
| `--root [path]` | Path to the root of your project | Current working directory |
7070
| `--error-on-weak` | Exit with error code if weak copyleft licenses are found | `false` |
7171

@@ -76,7 +76,7 @@ Generates a licenses report in the specified format. The output can be written t
7676
| Flag / Option | Description | Default |
7777
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
7878
| `--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>`'none'`</li></ul> | `'none'` |
79+
| `--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'` |
8080
| `--root [path]` | Path to the root of your project | Current working directory |
8181
| `--format [type]` | Output format, one of: `'json'`, `'about-json'` (AboutLibraries-compatible), `'text'`, `'markdown'` | `'json'` |
8282
| `--output [path]` | Where to write the output - either `'stdout'` or a path to an output file | `'stdout'` |
@@ -105,4 +105,12 @@ General options that can be passed to the CLI with after any command.
105105

106106
## Additional details
107107

108+
:::warning
109+
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`).
110+
111+
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.
112+
113+
If you want the same behaviour as in the programmatic API, you can set the `--dm` option to `none` when running the CLI.
114+
:::
115+
108116
For more notes on the mechanics of the tool, please see [core additional details section](/docs/programmatic-usage#additional-details).

0 commit comments

Comments
 (0)