feat: add license file gatherer utility

package.json

@@ -187,7 +187,7 @@
  "test:lint": "tsc --noEmit",
  "test:standard": "npm --prefix tools/code-style exec -- eslint .",
  "cs-fix": "npm --prefix tools/code-style exec -- eslint --fix .",
- "api-doc": "run-p --aggregate-output -lc api-doc:*",
+ "api-doc": "run-p --aggregate-output -lc api-doc:\\*",
  "api-doc:node": "npm --prefix tools/docs-gen exec -- typedoc --options ./typedoc.node.json",
  "api-doc:web": "npm --prefix tools/docs-gen exec -- typedoc --options ./typedoc.web.json"
  }

src/_helpers/mime.node.ts

@@ -0,0 +1,57 @@
+/*!
+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 as parsePath } from 'node:path'
+
+type MimeType = string
+
+const MIMETYPE_TEXT_PLAIN: MimeType = 'text/plain'
+
+const MAP_TEXT_EXTENSION_MIMETYPE: Readonly<Record<string, MimeType>> = {
+ '': MIMETYPE_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': MIMETYPE_TEXT_PLAIN,
+ '.rst': 'text/prs.fallenstein.rst',
+ '.rtf': 'application/rtf', // our scope is text, yes, but RTF is binary - so we should base64 encode it ...
+ '.xml': 'text/xml', // not `application/xml` -- our scope is text!
+ // add more mime types above this line. pull-requests welcome!
+ // license-specific files
+ '.license': MIMETYPE_TEXT_PLAIN,
+ '.licence': MIMETYPE_TEXT_PLAIN,
+} as const
+
+const LICENSE_FILENAME_BASE: Readonly<Set<string>> = new Set(['licence', 'license'])
+const LICENSE_FILENAME_EXT: Readonly<Set<string>> = new Set([
+ '.apache',
+ '.bsd',
+ '.gpl',
+ '.mit',
+ // to be continued ... pullrequests welcome
+])
+
+export function guessMimeTypeForLicenseFile (filename: string): MimeType | undefined {
+ const {name, ext} = parsePath(filename.toLowerCase())
+ return LICENSE_FILENAME_BASE.has(name) && LICENSE_FILENAME_EXT.has(ext)
+ ? MIMETYPE_TEXT_PLAIN
+ : MAP_TEXT_EXTENSION_MIMETYPE[ext]
+}

src/utils/index.node.ts

@@ -21,6 +21,7 @@ export * from './index.common'
 
 // region node-specifics
 
+export * as LicenseUtility from './licenseUtility.node'
 export * as NpmjsUtility from './npmjsUtility.node'
 
 // endregion node-specifics

src/utils/licenseUtility.node.ts

@@ -0,0 +1,104 @@
+/*!
+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 { Stats } from 'node:fs'
+
+import { guessMimeTypeForLicenseFile } from '../_helpers/mime.node'
+import { AttachmentEncoding } from '../enums/attachmentEncoding'
+import { Attachment } from '../models/attachment'
+
+/*
+ * this module tries to be as compatible as possible - it only uses basic methods that are known to be working in all FS-abstraction-layers.
+ * In addition, we use type-vars for all PathLikes, so downstream users can utilize their implementations accordingly.
+ */
+
+export interface FsUtils<P extends string> {
+ readdirSync: (path: P ) => P[]
+ readFileSync: (path: P) => Buffer
+ statSync: (path: P) => Stats
+}
+
+export interface PathUtils<P extends string> {
+ join: (...paths: P[]) => P
+}
+
+export interface FileAttachment<P extends string> {
+ filePath: P
+ file: P
+ text: Attachment
+}
+
+const LICENSE_FILENAME_PATTERN = /^(?:UN)?LICEN[CS]E|.\.LICEN[CS]E$|^NOTICE$/i
+
+export type ErrorReporter = (e:Error) => any
+
+export class LicenseEvidenceGatherer<P extends string = string> {
+ readonly #fs: FsUtils<P>
+ readonly #path: PathUtils<P>
+
+ /* eslint-disable tsdoc/syntax -- we want to use the dot-syntax - https://github.com/microsoft/tsdoc/issues/19 */
+ /**
+ * `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.
+ */
+ /* eslint-enable tsdoc/syntax */
+ constructor (options: { fs?: FsUtils<P>, path?: PathUtils<P> } = {}) {
+ /* 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 */
+ }
+
+ * getFileAttachments (prefixPath: P, onError: ErrorReporter = noop): Generator<FileAttachment<P>> {
+ const files = this.#fs.readdirSync(prefixPath) // may throw
+ 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 = guessMimeTypeForLicenseFile(file)
+ if (contentType === undefined) {
+ continue
+ }
+ try {
+ yield { filePath, file, text: new Attachment(
+ // since we cannot be sure weather the file content is text-only, or maybe binary,
+ // we tend to base64 everything, regardless of the detected encoding.
+ this.#fs.readFileSync(filePath) // may throw
+ .toString('base64'),
+ { contentType, encoding: AttachmentEncoding.Base64 }
+ ) }
+ } catch (cause) {
+ onError(new Error(`skipped license file ${filePath}`, {cause}))
+ }
+ }
+ }
+}
+
+
+
+/* eslint-disable-next-line @typescript-eslint/no-empty-function -- ack */
+function noop ():void {}

tests/unit/_helpers.mime.node.spec.js

@@ -0,0 +1,42 @@
+/*!
+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.
+*/
+
+const assert = require('node:assert')
+
+const { suite, test } = require('mocha')
+
+const {
+ guessMimeTypeForLicenseFile
+} = require('../../dist.node/_helpers/mime.node.js')
+
+suite('unit: _helpers.mime.getMimeForLicenseFile', () => {
+ for (const [fileName, expected] of [
+ ['LICENCE', 'text/plain'],
+ ['site.html', 'text/html'],
+ ['license.md', 'text/markdown'],
+ ['info.xml', 'text/xml'],
+ ['UNKNOWN', 'text/plain'],
+ ['LICENCE.MIT', 'text/plain']
+ ]) {
+ test(fileName, () => {
+ const value = guessMimeTypeForLicenseFile(fileName)
+ assert.strictEqual(value, expected)
+ })
+ }
+})