UNPKG

7.92 kBTypeScriptView Raw
1/**
2 * The MIT License (MIT)
3 *
4 * Copyright (c) 2016-2024 Mickael Jeanroy
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in all
14 * copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24
25import type {Plugin} from 'rollup';
26
27type FilePath = string;
28type FileEncoding = string;
29type FactoryFn<T> = () => T;
30type Factory<T> = T | FactoryFn<T>;
31
32/**
33 * A person, as described in NPM documentation.
34 *
35 * @see https://docs.npmjs.com/cli/v7/configuring-npm/package-json#people-fields-author-contributors
36 */
37export interface Person {
38 /**
39 * Person Name.
40 */
41 readonly name: string;
42
43 /**
44 * Person Email.
45 */
46 readonly email: string | null;
47
48 /**
49 * Person URL.
50 */
51 readonly url: string | null;
52
53 /**
54 * Turns the person into a formatted string
55 * @returns formatted person info
56 */
57 text: () => string;
58}
59
60/**
61 * @see {@link https://github.com/mjeanroy/rollup-plugin-license#comment-style}
62 */
63export type CommentStyle = 'regular' | 'ignored' | 'slash' | 'none';
64
65/**
66 * Banner content descriptor.
67 */
68interface BannerContentOptions {
69 /**
70 * File to get banner content from.
71 */
72 file: FilePath;
73
74 /**
75 * File encoding.
76 * @default utf-8
77 */
78 encoding?: FileEncoding;
79}
80
81/**
82 * Banner content, can be:
83 * - A raw string, evaluated as a (lodash) template.
84 * - A file description, the content being read and evaluated as a (lodash) template.
85 */
86type BannerContent = string | BannerContentOptions;
87
88/**
89 * Data injected during banner "rendering" (i.e evaluated as template
90 * model).
91 */
92interface BannerContentData {
93 [key: string]: any;
94}
95
96/**
97 * Banner Options.
98 */
99interface BannerOptions {
100 content: Factory<BannerContent>;
101 commentStyle?: CommentStyle;
102 data?: Factory<BannerContentData>;
103}
104
105export type Banner = string | BannerOptions;
106
107/**
108 * Dependency Repository Description.
109 */
110interface DependencyRepository {
111 /**
112 * Repository URL.
113 */
114 readonly url: string;
115
116 /**
117 * Repository Type (git, svn, etc.).
118 */
119 readonly type: string;
120}
121
122/**
123 * Dependency information is derived from the package.json file
124 */
125export interface Dependency {
126 /**
127 * Dependency Name.
128 */
129 readonly name: string | null;
130
131 /**
132 * Dependency Maintainers list.
133 */
134 readonly maintainers: string[];
135
136 /**
137 * Dependency Version.
138 */
139 readonly version: string | null;
140
141 /**
142 * Dependency Description.
143 */
144 readonly description: string | null;
145
146 /**
147 * Dependency Repository Location.
148 */
149 readonly repository: string | DependencyRepository | null;
150
151 /**
152 * Repository Public Homepage.
153 */
154 readonly homepage: string | null;
155
156 /**
157 * If dependency is private.
158 */
159 readonly private: boolean;
160
161 /**
162 * SPDX License short ID.
163 */
164 readonly license: string | null;
165
166 /**
167 * Full License file text.
168 */
169 readonly licenseText: string | null;
170
171 /**
172 * Full notice file text.
173 */
174 readonly noticeText: string | null;
175
176 /**
177 * Author information.
178 */
179 readonly author: Person | null;
180
181 /**
182 * Dependency Contributes list.
183 */
184 readonly contributors: Person[];
185
186 /**
187 * Turns the dependency into a formatted string
188 * @returns formatted dependency license info
189 */
190 text: () => string;
191}
192
193/**
194 * SPDX Licence Identifier.
195 */
196type SpdxId = string;
197
198/**
199 * Function checking dependency license validity.
200 */
201type ThirdPartyDependencyValidatorFn = (Dependency: Dependency) => boolean;
202
203type ThirdPartyValidator = SpdxId | ThirdPartyDependencyValidatorFn;
204
205interface ThirdPartyAllowOptions {
206 /**
207 * Testing if the license if valid
208 */
209 test: ThirdPartyValidator;
210
211 /**
212 * Fail if a dependency does not specify any licenses
213 * @default false
214 */
215 failOnUnlicensed?: boolean;
216
217 /**
218 * Fail if a dependency specify a license that does not match given requirement
219 * @default false
220 */
221 failOnViolation?: boolean;
222}
223
224/**
225 * Output generator: may write a file to disk, or something else as long as it is a
226 * synchronous operation.
227 */
228type ThirdPartyOutputGeneratorFn = (dependencies: Dependency[]) => void;
229
230/**
231 * Template as a raw string.
232 */
233type ThirdPartyOutputTemplate = string;
234
235/**
236 * Template function.
237 */
238type ThirdPartyOutputTemplateFn = (dependencies: Dependency[]) => void;
239
240/**
241 * Third Party output options object.
242 */
243interface ThirdPartyOutputOptions {
244 /**
245 * Name of file to write licenses to
246 */
247 file: FilePath;
248
249 /**
250 * @default utf-8
251 */
252 encoding?: FileEncoding;
253
254 /**
255 * Template function that can be defined to customize report output.
256 *
257 * @example
258 * template(dependencies) {
259 * return dependencies.map((dependency) => (
260 * `${dependency.name}:${dependency.version} -- ${dependency.license}`).join('\n')
261 * );
262 * },
263 *
264 * // Lodash template that can be defined to customize report output
265 * template: `
266 * <% _.forEach(dependencies, function (dependency) { %>
267 * <%= dependency.name %>:<%= dependency.version%> -- <%= dependency.license %>
268 * <% }) %>
269 * `
270 */
271 template?: ThirdPartyOutputTemplate | ThirdPartyOutputTemplateFn;
272}
273
274type ThirdPartyOutput = FilePath | ThirdPartyOutputGeneratorFn | ThirdPartyOutputOptions;
275
276interface ThirdPartyOptions {
277 /**
278 * Output for third party report.
279 */
280 output: ThirdPartyOutput | ThirdPartyOutput[];
281
282 /**
283 * If private dependencies should be checked (`private: true` in package.json)
284 * @default false
285 */
286 includePrivate?: boolean;
287
288 /**
289 * If "self" should be checked and included in the output.
290 * In this context, "self" means the package being built.
291 * @default false
292 */
293 includeSelf?: boolean;
294
295 /**
296 * Ensures that dependencies does not violate any license restriction.
297 *
298 * For example, suppose you want to limit dependencies with MIT or Apache-2.0
299 * licenses, simply define the restriction:
300 *
301 * @example
302 * {
303 * allow: '(MIT OR Apache-2.0)'
304 * }
305 *
306 * allow(dependency) {
307 * return dependency.license === 'MIT';
308 * }
309 */
310 allow?: ThirdPartyValidator | ThirdPartyAllowOptions;
311
312 /**
313 * Track each dependency version as a different dependency.
314 * Particularly useful when a dependency changed its licensing between versions.
315 * Default is `false` far backward compatibility.
316 */
317 multipleVersions?: boolean;
318}
319
320export type ThirdParty = ThirdPartyOutputGeneratorFn | ThirdPartyOptions;
321
322export interface Options {
323 sourcemap?: boolean | string;
324
325 /**
326 * Debug mode
327 * @default false
328 */
329 debug?: boolean;
330
331 /**
332 * Current Working Directory
333 * @default process.cwd()
334 */
335 cwd?: string;
336
337 /**
338 * License banner to place at the top of your bundle
339 */
340 banner?: Factory<Banner>;
341
342 /**
343 * For third party dependencies.
344 * Creates a file containing a summary of all dependencies can be generated
345 * automatically
346 */
347 thirdParty?: ThirdParty;
348}
349
350declare function rollupPluginLicense(options: Options): Plugin;
351
352export default rollupPluginLicense;