feat: add license file gatherer utility

src/_helpers/mime.ts

@@ -0,0 +1,55 @@
+/*!
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+*/
+
+import {parse} from 'node:path'
+
+type MimeType = string
+
+const MIME_TEXT_PLAIN: MimeType = 'text/plain'
+
+const MAP_TEXT_EXTENSION_MIME: Readonly<Record<string, MimeType>> = {
+ '': MIME_TEXT_PLAIN,
+ // https://www.iana.org/assignments/media-types/media-types.xhtml
+ '.csv': 'text/csv',
+ '.htm': 'text/html',
+ '.html': 'text/html',
+ '.md': 'text/markdown',
+ '.txt': MIME_TEXT_PLAIN,
+ '.rst': 'text/prs.fallenstein.rst',
+ '.xml': 'text/xml', // not `application/xml` -- our scope is text!
+ // add more mime types above this line. pull-requests welcome!
+ // license-specific files
+ '.license': MIME_TEXT_PLAIN,
+ '.licence': MIME_TEXT_PLAIN
+} as const
+
+const LICENSE_FILENAME_BASE = new Set(['licence', 'license'])
+const LICENSE_FILENAME_EXT = new Set([
+ '.apache',
+ '.bsd',
+ '.gpl',
+ '.mit'
+])
+
+export function getMimeForLicenseFile(filename: string): MimeType | undefined {
+ const {name, ext} = parse(filename.toLowerCase())
+ return LICENSE_FILENAME_BASE.has(name) && LICENSE_FILENAME_EXT.has(ext)
+ ? MIME_TEXT_PLAIN
+ : MAP_TEXT_EXTENSION_MIME[ext]
+}

src/builders/index.node.ts

@@ -18,3 +18,4 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
 export * as FromNodePackageJson from './fromNodePackageJson.node'
+export * as License from './license'

src/builders/license.ts

@@ -0,0 +1,103 @@
+/*!
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+*/
+
+import type NATIVE_FS from 'node:fs'
+import type NATIVE_PATH from "node:path";
+
+import {getMimeForLicenseFile} from '../_helpers/mime'
+import {AttachmentEncoding} from '../enums/attachmentEncoding'
+import {Attachment} from '../models/attachment'
+
+
+interface FsUtils {
+ readdirSync: typeof NATIVE_FS.readdirSync
+ readFileSync: typeof NATIVE_FS.readFileSync
+ statSync: typeof NATIVE_FS.statSync
+}
+
+interface PathUtils {
+ join: typeof NATIVE_PATH.join
+}
+
+export interface FetchResult {
+ file: string
+ filePath: string
+ text: Attachment
+}
+
+const LICENSE_FILENAME_PATTERN = /^(?:UN)?LICEN[CS]E|.\.LICEN[CS]E$|^NOTICE$/i
+
+type ErrorReporter = (e:Error) => void
+
+/* eslint-disable-next-line @typescript-eslint/no-empty-function -- ack */
+function noop ():void {}
+
+export class LicenseEvidenceFetcher {
+ readonly #fs: FsUtils
+ readonly #path: PathUtils
+
+ /**
+ * `fs` and `path` can be supplied, if any compatibility-layer or drop-in replacement is used.
+ *
+ * @param options.fs - If omitted, the native `node:fs` is used.
+ * @param options.path - If omitted, the native `node:path` is used.
+ */
+ constructor(options: { fs?: FsUtils, path?: PathUtils } = {}) {
+ /* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-require-imports -- needed */
+ this.#fs = options.fs ?? require('node:fs')
+ this.#path = options.path ?? require('node:path')
+ /* eslint-enable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-require-imports */
+ }
+
+ * fetch(prefixPath: string, onError: ErrorReporter = noop): Generator<FetchResult> {
+ const files = this.#fs.readdirSync(prefixPath)
+ for (const file of files) {
+ if (!LICENSE_FILENAME_PATTERN.test(file)) {
+ continue
+ }
+ const filePath = this.#path.join(prefixPath, file)
+ if (!this.#fs.statSync(filePath).isFile()) {
+ // Ignore all directories - they are not files :-)
+ // Don't follow symlinks for security reasons!
+ continue
+ }
+ const contentType = getMimeForLicenseFile(file)
+ if (contentType === undefined) {
+ continue
+ }
+ try {
+ yield {
+ file,
+ filePath,
+ text: new Attachment(
+ this.#fs.readFileSync(filePath).toString('base64'),
+ {
+ contentType,
+ encoding: AttachmentEncoding.Base64
+ }
+ )
+ }
+ }
+ /* c8 ignore next 3 */
+ catch (e) {
+ onError(new Error(`skipped license file ${filePath}`, {cause: e}))
+ }
+ }
+ }
+}