@cyclonedx/cyclonedx-library 8.3.0 → 8.4.0-rc.0

package/README.md

@@ -79,6 +79,7 @@ written in _TypeScript_ and compiled for the target.
     * `Vulnerability`, `VulnerabilityRepository`
 * Utilities for the following use cases:
   * Generate valid random SerialNumbers for `Bom.serialNumber`
+  * Gather license evidences from files (for _Node.js_ only)
 * Factories for the following use cases:
   * Create data models from any license descriptor string
   * Create `PackageURL` from `Component` data models

package/dist.d/_helpers/mime.node.d.ts

@@ -0,0 +1,22 @@
+/*!
+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.
+*/
+type MimeType = string;
+export declare function guessMimeTypeForLicenseFile(filename: string): MimeType | undefined;
+export {};
+//# sourceMappingURL=mime.node.d.ts.map

package/dist.d/_helpers/mime.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.node.d.ts","sourceRoot":"","sources":["../../src/_helpers/mime.node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;EAiBE;AAIF,KAAK,QAAQ,GAAG,MAAM,CAAA;AA8BtB,wBAAgB,2BAA2B,CAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAKnF"}

package/dist.d/utils/index.node.d.ts

@@ -17,5 +17,6 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 export * from './index.common';
+export * as LicenseUtility from './licenseUtility.node';
 export * as NpmjsUtility from './npmjsUtility.node';
 //# sourceMappingURL=index.node.d.ts.map

package/dist.d/utils/index.node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.node.d.ts","sourceRoot":"","sources":["../../src/utils/index.node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;EAiBE;AAEF,cAAc,gBAAgB,CAAA;AAI9B,OAAO,KAAK,YAAY,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.node.d.ts","sourceRoot":"","sources":["../../src/utils/index.node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;EAiBE;AAEF,cAAc,gBAAgB,CAAA;AAI9B,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,YAAY,MAAM,qBAAqB,CAAA"}

package/dist.d/utils/licenseUtility.node.d.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.
+*/
+/**
+ * This module tries to be as compatible as possible, it only uses basic methods that are known to be working in all FileSystem abstraction-layers.
+ * In addition, we use type parameters for all `PathLike`s, so downstream users can utilize their implementations accordingly.
+ *
+ * @module
+ */
+import type { Stats } from 'node:fs';
+import { Attachment } from '../models/attachment';
+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;
+}
+export type ErrorReporter = (e: Error) => any;
+export declare class LicenseEvidenceGatherer<P extends string = string> {
+    #private;
+    /**
+     * `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<P>;
+        path?: PathUtils<P>;
+    });
+    getFileAttachments(prefixPath: P, onError?: ErrorReporter): Generator<FileAttachment<P>>;
+}
+//# sourceMappingURL=licenseUtility.node.d.ts.map

package/dist.d/utils/licenseUtility.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"licenseUtility.node.d.ts","sourceRoot":"","sources":["../../src/utils/licenseUtility.node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;EAiBE;AAEF;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAIpC,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEjD,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,MAAM;IACvC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAC,EAAE,CAAA;IAC9B,YAAY,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAA;IACjC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,KAAK,CAAA;CAC7B;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,MAAM;IACzC,IAAI,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,MAAM;IAC9C,QAAQ,EAAE,CAAC,CAAA;IACX,IAAI,EAAE,CAAC,CAAA;IACP,IAAI,EAAE,UAAU,CAAA;CACjB;AAID,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,EAAC,KAAK,KAAK,GAAG,CAAA;AAE5C,qBAAa,uBAAuB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;;IAK5D;;;;;OAKG;gBACU,OAAO,GAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;KAAO;IAQjE,kBAAkB,CAAE,UAAU,EAAE,CAAC,EAAE,OAAO,GAAE,aAAoB,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;CA6BlG"}

package/dist.node/_helpers/mime.node.js

@@ -0,0 +1,50 @@
+"use strict";
+/*!
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.guessMimeTypeForLicenseFile = guessMimeTypeForLicenseFile;
+const node_path_1 = require("node:path");
+const MIMETYPE_TEXT_PLAIN = 'text/plain';
+const MAP_TEXT_EXTENSION_MIMETYPE = {
+    '': MIMETYPE_TEXT_PLAIN,
+    '.csv': 'text/csv',
+    '.htm': 'text/html',
+    '.html': 'text/html',
+    '.md': 'text/markdown',
+    '.txt': MIMETYPE_TEXT_PLAIN,
+    '.rst': 'text/prs.fallenstein.rst',
+    '.rtf': 'application/rtf',
+    '.xml': 'text/xml',
+    '.license': MIMETYPE_TEXT_PLAIN,
+    '.licence': MIMETYPE_TEXT_PLAIN,
+};
+const LICENSE_FILENAME_BASE = new Set(['licence', 'license']);
+const LICENSE_FILENAME_EXT = new Set([
+    '.apache',
+    '.bsd',
+    '.gpl',
+    '.mit',
+]);
+function guessMimeTypeForLicenseFile(filename) {
+    const { name, ext } = (0, node_path_1.parse)(filename.toLowerCase());
+    return LICENSE_FILENAME_BASE.has(name) && LICENSE_FILENAME_EXT.has(ext)
+        ? MIMETYPE_TEXT_PLAIN
+        : MAP_TEXT_EXTENSION_MIMETYPE[ext];
+}
+//# sourceMappingURL=mime.node.js.map

package/dist.node/_helpers/mime.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.node.js","sourceRoot":"","sources":["../../src/_helpers/mime.node.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;EAiBE;;AAkCF,kEAKC;AArCD,yCAA8C;AAI9C,MAAM,mBAAmB,GAAa,YAAY,CAAA;AAElD,MAAM,2BAA2B,GAAuC;IACtE,EAAE,EAAE,mBAAmB;IAEvB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,WAAW;IACpB,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,mBAAmB;IAC3B,MAAM,EAAE,0BAA0B;IAClC,MAAM,EAAE,iBAAiB;IACzB,MAAM,EAAE,UAAU;IAGlB,UAAU,EAAE,mBAAmB;IAC/B,UAAU,EAAE,mBAAmB;CACvB,CAAA;AAEV,MAAM,qBAAqB,GAA2B,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAA;AACrF,MAAM,oBAAoB,GAA0B,IAAI,GAAG,CAAC;IAC1D,SAAS;IACT,MAAM;IACN,MAAM;IACN,MAAM;CAEP,CAAC,CAAA;AAEF,SAAgB,2BAA2B,CAAE,QAAgB;IAC3D,MAAM,EAAC,IAAI,EAAE,GAAG,EAAC,GAAG,IAAA,iBAAS,EAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAA;IACrD,OAAO,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC;QACrE,CAAC,CAAC,mBAAmB;QACrB,CAAC,CAAC,2BAA2B,CAAC,GAAG,CAAC,CAAA;AACtC,CAAC"}

package/dist.node/utils/index.node.js

@@ -54,7 +54,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NpmjsUtility = void 0;
+exports.NpmjsUtility = exports.LicenseUtility = void 0;
 __exportStar(require("./index.common"), exports);
+exports.LicenseUtility = __importStar(require("./licenseUtility.node"));
 exports.NpmjsUtility = __importStar(require("./npmjsUtility.node"));
 //# sourceMappingURL=index.node.js.map

package/dist.node/utils/index.node.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.node.js","sourceRoot":"","sources":["../../src/utils/index.node.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;EAiBE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEF,iDAA8B;AAI9B,oEAAmD"}
+{"version":3,"file":"index.node.js","sourceRoot":"","sources":["../../src/utils/index.node.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;EAiBE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEF,iDAA8B;AAI9B,wEAAuD;AACvD,oEAAmD"}

package/dist.node/utils/licenseUtility.node.js

@@ -0,0 +1,59 @@
+"use strict";
+/*!
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LicenseEvidenceGatherer = void 0;
+const mime_node_1 = require("../_helpers/mime.node");
+const attachmentEncoding_1 = require("../enums/attachmentEncoding");
+const attachment_1 = require("../models/attachment");
+const LICENSE_FILENAME_PATTERN = /^(?:UN)?LICEN[CS]E|.\.LICEN[CS]E$|^NOTICE$/i;
+class LicenseEvidenceGatherer {
+    #fs;
+    #path;
+    constructor(options = {}) {
+        this.#fs = options.fs ?? require('node:fs');
+        this.#path = options.path ?? require('node:path');
+    }
+    *getFileAttachments(prefixPath, onError = noop) {
+        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()) {
+                continue;
+            }
+            const contentType = (0, mime_node_1.guessMimeTypeForLicenseFile)(file);
+            if (contentType === undefined) {
+                continue;
+            }
+            try {
+                yield { filePath, file, text: new attachment_1.Attachment(this.#fs.readFileSync(filePath)
+                        .toString('base64'), { contentType, encoding: attachmentEncoding_1.AttachmentEncoding.Base64 }) };
+            }
+            catch (cause) {
+                onError(new Error(`skipped license file ${filePath}`, { cause }));
+            }
+        }
+    }
+}
+exports.LicenseEvidenceGatherer = LicenseEvidenceGatherer;
+function noop() { }
+//# sourceMappingURL=licenseUtility.node.js.map

package/dist.node/utils/licenseUtility.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"licenseUtility.node.js","sourceRoot":"","sources":["../../src/utils/licenseUtility.node.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;EAiBE;;;AAWF,qDAAmE;AACnE,oEAAgE;AAChE,qDAAiD;AAkBjD,MAAM,wBAAwB,GAAG,6CAA6C,CAAA;AAI9E,MAAa,uBAAuB;IACzB,GAAG,CAAY;IACf,KAAK,CAAc;IAS5B,YAAa,UAAoD,EAAE;QAEjE,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC,CAAA;QAC3C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IAEnD,CAAC;IAGD,CAAE,kBAAkB,CAAE,UAAa,EAAE,UAAyB,IAAI;QAChE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,UAAU,CAAC,CAAA;QAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzC,SAAQ;YACV,CAAC;YACD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;YAClD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;gBAG1C,SAAQ;YACV,CAAC;YACD,MAAM,WAAW,GAAG,IAAA,uCAA2B,EAAC,IAAI,CAAC,CAAA;YACrD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC9B,SAAQ;YACV,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,uBAAU,CAGxC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,CAAC;yBAC1B,QAAQ,CAAC,QAAQ,CAAC,EACvB,EAAE,WAAW,EAAE,QAAQ,EAAE,uCAAkB,CAAC,MAAM,EAAE,CACrD,EAAE,CAAA;YACP,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,KAAK,CAAC,wBAAwB,QAAQ,EAAE,EAAE,EAAC,KAAK,EAAC,CAAC,CAAC,CAAA;YACjE,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAhDD,0DAgDC;AAGD,SAAS,IAAI,KAAU,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyclonedx/cyclonedx-library",
-  "version": "8.3.0",
+  "version": "8.4.0-rc.0",
   "description": "Core functionality of CycloneDX for JavaScript (Node.js or WebBrowser).",
   "license": "Apache-2.0",
   "keywords": [
@@ -97,6 +97,7 @@
     "c8": "^10",
     "deepmerge": "^4.2.2",
     "fast-glob": "^3.3.1",
+    "memfs": "4.17.2",
     "mocha": "11.5.0",
     "npm-run-all2": "^8",
     "rimraf": "^6",
@@ -106,12 +107,15 @@
     "webpack-cli": "6.0.1",
     "webpack-node-externals": "3.0.0"
   },
-  "browser": "./dist.web/lib.js",
   "types": "./dist.d/index.node.d.ts",
+  "browser": "./dist.web/lib.js",
   "main": "./dist.node/index.node.js",
   "exports": {
     ".": {
-      "types": "./dist.d/index.node.d.ts",
+      "types": {
+        "browser": "./dist.d/index.web.d.ts",
+        "default": "./dist.d/index.node.d.ts"
+      },
       "browser": "./dist.web/lib.js",
       "default": "./dist.node/index.node.js"
     },
@@ -187,7 +191,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"
   }

package/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]
+}

package/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

package/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.
+*/
+
+/**
+ * This module tries to be as compatible as possible, it only uses basic methods that are known to be working in all FileSystem abstraction-layers.
+ * In addition, we use type parameters for all `PathLike`s, so downstream users can utilize their implementations accordingly.
+ *
+ * @module
+ */
+
+import type { Stats } from 'node:fs'
+
+import { guessMimeTypeForLicenseFile } from '../_helpers/mime.node'
+import { AttachmentEncoding } from '../enums/attachmentEncoding'
+import { Attachment } from '../models/attachment'
+
+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.
+   */
+  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 */
+  }
+  /* eslint-enable tsdoc/syntax */
+
+  * 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 {}

package/tsconfig.json

@@ -102,7 +102,8 @@
 
     /* Completeness */
     "skipDefaultLibCheck": false,                      /* Skip type checking .d.ts files that are included with TypeScript. */
-    "skipLibCheck": false                                 /* Skip type checking all .d.ts files. */
+    // needed for https://github.com/oozcitak/util/issues/13
+    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
   },
   "exclude": [
     "node_modules",