codepunkt/rollup-license-plugin
GitHub: codepunkt/rollup-license-plugin
一款面向 Rollup 和 Vite 构建流程的第三方许可证合规管理插件，自动发现依赖并生成物料清单，同时支持对不合规许可证中断构建。
Stars: 32 | Forks: 10
rollup-license-plugin
管理 Rollup 和 Vite 构建中的第三方许可证合规性
主要功能 •
安装说明 •
使用方法 •
可用选项 •
示例
# 主要功能
该插件会提取有关 rollup 或 vite 输出中所有 npm/yarn/pnpm 包的_开源许可证信息_，并帮助你识别和解决开源许可证策略中的问题。
- 发现 rollup 或 vite 构建中使用的每一个 node_module
- 查明其适用的许可证
- 取消包含不可接受许可证的构建
- 将内部包排除在扫描范围之外
- 创建自定义的清单（通常称为_物料清单_），格式可以是 `json`、`html`、`csv` 或其他格式
# 安装说明
将 `rollup-license-plugin` 作为开发依赖安装到你的当前项目中：
```
npm install -D rollup-license-plugin
```
# 使用方法
通过将 `rollup-license-plugin` 添加到 `plugins` 数组中，在你的 rollup 或 vite 配置中使用它。
### Rollup
```
import { createRollupLicensePlugin } from 'rollup-license-plugin';
export default {
plugins: [
createRollupLicensePlugin()
]
}
```
### Vite
```
import { defineConfig } from 'vite'
import { createViteLicensePlugin } from 'rollup-license-plugin'
export default defineConfig({
plugins: [
createViteLicensePlugin()
],
})
```
进一步的代码示例将只展示 `createRollupLicensePlugin`，但只需改为引入 `createViteLicensePlugin`，它们同样适用于 Vite。
# 可用选项
选项以 `Object` 的形式传递给 `createRollupLicensePlugin` 和 `createViteLicensePlugin` 方法：
```
createRollupLicensePlugin({
outputFilename: 'thirdPartyNotice.json'
})
```
可用选项包括：
| 名称 | 描述 |
| :------------- | :----------------------------------------------------------------------------------------------------------------------- |
| **`additionalFiles`** | 默认值：`{}`。定义此插件基于其默认输出应生成的附加文件的对象（例如，除了生成的 json 之外，还可以生成许可证的 html 表示形式）。键代表文件名，值是接收包数组作为参数的函数，并应返回写入附加文件的内容。这些函数可以是异步的或返回一个 Promise。 |
| **`excludedPackageTest`** | 用于在处理过程中排除某些包的方法。它会被每个包的 `packageName`（字符串）和 `version`（字符串）调用，如果返回 true，则排除该包。 |
| **`licenseOverrides`** | 默认值：`{}`。包含要覆盖的许可证的对象。键的格式为 `
@`，值为有效的 [spdx 许可证表达式](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60)。当许可证信息不明确且经过手动检查时，这会很有用。 |
| **`outputFilename`** | 默认值：`oss-licenses.json`。将要生成的输出文件的路径。相对于 bundle 输出目录。将此设置为 `false` 可禁用默认输出文件。 |
| **`replenishDefaultLicenseTexts`** | 默认值：`false`。启用此选项后，对于未找到许可证文本的包，将从 spdx.org 获取默认的许可证文本。 |
| **`unacceptableLicenseTest`** | 用于将某些许可证标识符定义为不可接受的方法。它会被每个包的 `licenseIdentifier`（字符串）调用，当遇到不可接受的许可证并导致构建失败时应返回 true。 |
| **`includePackages`** | 默认值：`() => []`。用于定义应始终包含在输出中的包的方法。它必须返回一个包含这些包绝对路径的数组。此函数可以是异步的或返回一个 Promise。
### 带有自定义选项的示例
此示例将结果写入输出目录中名为 `meta/licenses.json` 的文件，每当遇到给定的许可证之一时就会失败，并覆盖包 `fuse.js@3.2.1` 的许可证。
```
createRollupLicensePlugin({
excludedPackageTest: (packageName, version) => {
return packageName.startsWith('@internal/')
},
licenseOverrides: {
// has "Apache" in package.json, but Apache-2.0 text in LICENSE file
'fuse.js@3.2.1': 'Apache-2.0'
},
outputFilename: 'meta/licenses.json',
unacceptableLicenseTest: (licenseIdentifier) => {
return ['GPL', 'AGPL', 'LGPL', 'NGPL'].includes(licenseIdentifier)
}
})
```
# 默认输出
输出文件是位于 rollup 或 vite 构建输出目录中的 `oss-licenses.json` 文件。它包含一个被认定为属于构建输出一部分的包数组，并列出了每个包的几项与许可证相关的详细信息：
| 名称 | 描述 |
| :------------- | :-------------------------------- |
| **`name`** | 包名 |
| **`version`** | 包版本 |
| **`author`** | `package.json` 中列出的作者 _(如果有)_ |
| **`repository`** | `package.json` 中列出的仓库 URL _(如果有)_ |
| **`source`** | npm registry 上的包 tarball URL |
| **`license`** | `package.json` 中列出的许可证。如果这不是一个有效的 [spdx 许可证表达式](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60)，此插件将通知你。然后你可以告知包维护者此问题，并通过针对特定包名和版本组合的 `licenseOverrides` 选项来临时解决此问题。 |
| **`licenseText`** | 从包根目录下匹配 `/^licen[cs]e/i` 的文件中读取的许可证文本 |
### 输出文件示例
```
[
{
"name": "fbjs",
"version": "0.8.17",
"repository": "https://github.com/facebook/fbjs",
"source": "https://registry.npmjs.org/fbjs/-/fbjs-0.8.17.tgz",
"license": "MIT",
"licenseText": "..."
},
{
"name": "object-assign",
"version": "4.1.1",
"author": "Sindre Sorhus",
"repository": "https://github.com/sindresorhus/object-assign",
"source": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
"license": "MIT",
"licenseText": "..."
},
{
"name": "react-dom",
"version": "16.4.2",
"repository": "https://github.com/facebook/react",
"source": "https://registry.npmjs.org/react-dom/-/react-dom-16.4.2.tgz",
"license": "MIT",
"licenseText": "..."
},
{
"name": "react",
"version": "16.4.2",
"repository": "https://github.com/facebook/react",
"source": "https://registry.npmjs.org/react/-/react-16.4.2.tgz",
"license": "MIT",
"licenseText": "..."
}
]
```
# 示例
## _additionalFiles_ 示例
当设置了 `additionalFiles` 选项时，上述显示的输出会作为一个数组传递给每个配置过的附加文件的转换函数。
这样，输出就可以被格式化为你需要的任何格式，然后写入到一个或多个附加文件中。
### 以 CSV 格式导出的包列表
```
createRollupLicensePlugin({
additionalFiles: {
'oss-licenses.csv': (packages) => {
const keys = ['name', 'version', 'license']
return [
'"sep=,"',
keys.join(','),
...packages.map(p => keys.map(key => `="${p[key]}"`).join(',')),
].join('\n')
}
}
})
```
### 包列表及附加摘要
```
createRollupLicensePlugin({
additionalFiles: {
'oss-summary.json': packages => {
const licenseCount = packages.reduce(
(prev, { license }) => ({
...prev,
[license]: prev[license] ? prev[license] + 1 : 1,
}),
{}
)
return JSON.stringify(licenseCount, null, 2)
},
},
})
```
标签：MITM代理, Rollup插件, Vite插件, 依赖管理, 前端构建工具, 开源合规, 数据可视化, 自动化攻击, 许可证管理, 跌倒检测, 软件物料清单