Skip to content

Commit eb4bf24

Browse files
bnbbnb
committed
feat: add npm license RFC
1 parent ae8c9ba commit eb4bf24

File tree

1 file changed

+93
-0
lines changed

1 file changed

+93
-0
lines changed

‎accepted/0028-npm-license.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Add license reporting to npm
2+
3+
## Summary
4+
5+
It should be possible to get a full report of the licenses from all dependencies. This report should include the license as defined in `package.json` in addition to including a path to any relevant `LICENSE`-ish files within the project. Additionally, end-users should be able to have an allowlist and blocklist of "acceptable" licenses, a way to allow modules with licenses outside of that list that have been triaged, and have a way to install such a list.
6+
7+
## Motivation
8+
9+
{{Why are we doing this? What pain points does this resolve? What use cases does it support? What is the expected outcome? Use real, concrete examples to make your case!}}
10+
11+
License reporting is something that there seems to be a non-trivial amount of ecosystem tooling around - largely built by folks at large corps or by companies that focus on dependencies as a core part of their business in some way - without having any kind of official recognition beyond the "license" property being displayed on the package view of npmjs.com.
12+
13+
Given that this is something that a non-trivial number of users care about _and_ that the state of the ecosystem is relatively fragmented, there's an opportunity to include license tooling as a first-class tool within the ecosystem and both help incrementally improve the ecosystem's awareness/practices around this in addtion to providing blessed built-in tooling that can help resolve a problem the ecosystem is pretty consistently having to build their own tooling for.
14+
15+
## Detailed Explanation
16+
17+
- It should be possible to get a full report of the licenses from all dependencies.
18+
- This should be runnable from a single command: `npm audit licenses`
19+
- Offline (default)
20+
- This report should collect all licenses via the `license` properties from `package.json` files in `node_modules`.
21+
- Online (`--online`)
22+
- This report should have an `--online` mode that will resolve the dependency tree and fetch the entire dependency tree's licenses without needing the modules on disk.
23+
- Output
24+
- This report should default to a pretty printed human-readable version.
25+
- This report should be able to be output as JSON with a `--json` flag.
26+
- It should be possible to define a set of allowed, blocked, and ignored licenses
27+
- Location
28+
- This should be able to be defined both in `package.json` or something like `audit.json`.
29+
- Contents
30+
- These lists should an be in a `licenses` object with three properties - `allow` (array), `block` (array), and `ignore` (object).
31+
- If in `package.json`, `licenses` should be a subproperty of `audit`.
32+
- If in `audit.json`, `licenses` should be a top level property.
33+
- In `licenses`, `allow` should be an array of values that would _ideally_ be SPDX License Identifiers or SPDX License Expressions but in reality will not end up always being that.
34+
- In `licenses`, `block` should be an array of values that would _ideally_ be SPDX License Identifiers or SPDX License Expressions but in reality will not end up always being that.
35+
- In `licenses`, `ignore` should be an object with two properties - `licenses` and `modules`.
36+
- `licenses` is a list of license values (parsed from `license` in dependencies' `package.json`) to _ignore_ from any kind of checking.
37+
- `modules` is a list of modules (parsed from `name` in dependencies' `package.json`) to _ignore_ from any kind of checking.
38+
- Behavior on `npm install`
39+
- If a `block` property exists, npm should not install any modules on-disk that have a value in `license` that matches any of the values in `block`.
40+
- All blocked modules and the path they were introduced through should be reported as an `error` or `warn`.
41+
- It should be possible to triage licenses that are on disk (in `node_modules`) or would be resolved in the dependency tree
42+
- This should be accomplished through `npm audit licenses triage`
43+
- Offline (default)
44+
- This report should collect all licenses via the `license` properties from `package.json` files in `node_modules`, filtering out any licenses that are in `allow` and `block` in addition to any licenses or modules in `ignore`, and provide the user the option to `allow`, `block`, or `ignore` the license, one by one.
45+
- Online (`--online`)
46+
- This report should collect all licenses via the `license` properties from `package.json` files from a resolved dependency tree without needing the modules on disk, filtering out any licenses that are in `allow` and `block` in addition to any licenses or modules in `ignore`, and provide the user the option to `allow`, `block`, or `ignore` the license, one by one.
47+
48+
## Rationale and Alternatives
49+
50+
There are a wide array of tools in the ecosystem that have been built to paper over the lack of license tooling in npm and the JavaScript ecosystem. There's clearly a desire/need for license tooling, and including it directly in npm would help drive both improved experiences for developers and overall best practices.
51+
52+
Alternatives considered:
53+
54+
- Distinct command within the CLI, outside of audit (`npm license` or `npm compliance`).
55+
- Discarded this as it would potentially create further fragmentation where it's potentially unnecessary.
56+
- Leave it to the ecosystem.
57+
- This has been the state of the world for about a decade, and there's still been no excessively positive tooling that's come up and solved all the problems that exist in this space while achieving widespread adoption.
58+
59+
## Implementation
60+
61+
{{Give a high-level overview of implementation requirements and concerns. Be specific about areas of code that need to change, and what their potential effects are. Discuss which repositories and sub-components will be affected, and what its overall code effect might be.}}
62+
63+
{{THIS SECTION IS REQUIRED FOR RATIFICATION -- you can skip it if you don't know the technical details when first submitting the proposal, but it must be there before it's accepted}}
64+
65+
## Prior Art
66+
67+
Paid tooling:
68+
69+
- https://fossa.com/ - OSS license checking as service. Gives the service for free to impactful OSS projects.
70+
- https://help.sonatype.com/repomanager3/formats/npm-registry#npmRegistry-npmaudit - Private registry product extension. Enterprise use case, relatively widely used by megacorps.
71+
- https://jfrog.com/xray/ - Private registry product extension. Enterprise use case, relatively widely used by megacorps.
72+
- https://docs.nodesource.com/ncmv2/docs#compliance - Extension of the public registry as an Electron app/web service. Was killed pre-acquisition. Company publicly stated they had relatively large enterprise customers.
73+
74+
Open-source tooling:
75+
76+
- https://www.npmjs.com/package/license-checker - relatively widely used and similar-ish to what's proposed. Also a requirable module.
77+
- https://www.npmjs.com/package/licensee - similar-ish to what's proposed. Potentially already used by npm?
78+
- https://www.npmjs.com/package/license-report - similar-ish to what's proposed.
79+
- https://www.npmjs.com/package/nlf - similar-ish to what's proposed. Also a requirable module.
80+
- https://www.npmjs.com/package/npm-license - similar-ish to what's proposed.
81+
- https://www.npmjs.com/package/delice - similar-ish to what's proposed.
82+
83+
## Unresolved Questions and Bikeshedding
84+
85+
- command naming
86+
- property naming
87+
- package.json/audit.json/both
88+
- interactive triage
89+
- should it exist?
90+
- what's the DX?
91+
- log levels of different parts of the proposal
92+
93+
{{THIS SECTION SHOULD BE REMOVED BEFORE RATIFICATION}}

0 commit comments

Comments
 (0)