feat: add rootComponentVCS configuration (#1350)

resolves #1344

---------

Signed-off-by: Jeremy Long <[email protected]>
Signed-off-by: Jan Kowalleck <[email protected]>
Co-authored-by: Jan Kowalleck <[email protected]>

Author: jeremylong

HISTORY.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 ## unreleased
 
 <!-- unreleased changes go here -->
+* Added
+  * Configuration option for `rootComponentVCS` ([#1344] via [#1350])
+
+[#1344]: https://github.com/CycloneDX/cyclonedx-webpack-plugin/issues/1344
+[#1350]: https://github.com/CycloneDX/cyclonedx-webpack-plugin/pull/1350
 
 ## 3.16.0 - 2025-01-08
 

README.md

@@ -57,6 +57,7 @@ new CycloneDxWebpackPlugin(options?: object)
 | **`rootComponentName`** | optional `{string}` | `undefined` | If `rootComponentAutodetect` is disabled, then this value is assumed as the "name" of the `package.json`. |
 | **`rootComponentVersion`** | optional `{string}` | `undefined` | If `rootComponentAutodetect` is disabled, then this value is assumed as the "version" of the `package.json`. |
 | **`rootComponentBuildSystem`** | optional `{string}` | `undefined` | Set's the URL for the RootComponent's External References' build-system. |
+| **`rootComponentVCS`** | optional `{string}` | `undefined` | If `rootComponentAutodetect` is disabled or the VCS is not defined in the package.json, then this value is used as the URL for the RootComponent's External Referencees' Version Control System. |
 | **`collectEvidence`** | `{boolean}` | `false` | Whether to collect (license) evidence and attach them to the resulting SBOM. |
 
 ### Example

examples/simple/webpack.config.js

@@ -33,6 +33,7 @@ const cycloneDxWebpackPluginOptions = {
   rootComponentName: undefined,
   rootComponentVersion: undefined,
   rootComponentBuildSystem: undefined,
+  rootComponentVCS: undefined,
   collectEvidence: true
 }
 

src/_helpers.ts

@@ -130,3 +130,17 @@ export function getMimeForLicenseFile (filename: string): MimeType | undefined {
 }
 
 // endregion MIME
+
+// region polyfills
+
+/** Polyfill for Iterator.some() */
+export function iterableSome<T> (i: Iterable<T>, t: (v: T) => boolean): boolean {
+  for (const v of i) {
+    if (t(v)) {
+      return true
+    }
+  }
+  return false
+}
+
+// endregion polyfills

src/plugin.ts

@@ -23,7 +23,7 @@ import * as normalizePackageJson from 'normalize-package-data'
 import { join as joinPath, resolve } from 'path'
 import { Compilation, type Compiler, sources } from 'webpack'
 
-import { getPackageDescription, loadJsonFile } from './_helpers'
+import { getPackageDescription, iterableSome, loadJsonFile } from './_helpers'
 import { Extractor } from './extractor'
 
 type WebpackLogger = Compilation['logger']
@@ -110,6 +110,11 @@ export interface CycloneDxWebpackPluginOptions {
    * See {@link https://cyclonedx.org/docs/1.6/json/#metadata_component_externalReferences}.
    */
   rootComponentBuildSystem?: CycloneDxWebpackPlugin['rootComponentBuildSystem']
+  /**
+   * Set the externalReference URL for the version control system for the RootComponent.
+   * See {@link https://cyclonedx.org/docs/1.6/json/#metadata_component_externalReferences}.
+   */
+  rootComponentVCS?: CycloneDxWebpackPlugin['rootComponentVCS']
 
   /**
    * Whether to collect (license) evidence and attach them to the resulting SBOM.
@@ -142,6 +147,7 @@ export class CycloneDxWebpackPlugin {
   rootComponentName: CDX.Models.Component['name'] | undefined
   rootComponentVersion: CDX.Models.Component['version'] | undefined
   rootComponentBuildSystem: CDX.Models.ExternalReference['url'] | undefined
+  rootComponentVCS: CDX.Models.ExternalReference['url'] | undefined
 
   collectEvidence: boolean
 
@@ -157,6 +163,7 @@ export class CycloneDxWebpackPlugin {
     rootComponentName = undefined,
     rootComponentVersion = undefined,
     rootComponentBuildSystem = undefined,
+    rootComponentVCS = undefined,
     collectEvidence = false
   }: CycloneDxWebpackPluginOptions = {}) {
     this.specVersion = specVersion
@@ -172,6 +179,7 @@ export class CycloneDxWebpackPlugin {
     this.rootComponentName = rootComponentName
     this.rootComponentVersion = rootComponentVersion
     this.rootComponentBuildSystem = rootComponentBuildSystem
+    this.rootComponentVCS = rootComponentVCS
     this.collectEvidence = collectEvidence
   }
 
@@ -318,7 +326,10 @@ export class CycloneDxWebpackPlugin {
 
   #addRootComponentExtRefs (component: CDX.Models.Component | undefined, logger: WebpackLogger): void {
     if (component === undefined) { return }
-    if (typeof this.rootComponentBuildSystem === 'string' && this.rootComponentBuildSystem.length > 0) {
+    if (
+      typeof this.rootComponentBuildSystem === 'string' &&
+      this.rootComponentBuildSystem.length > 0
+    ) {
       component.externalReferences.add(
         new CDX.Models.ExternalReference(
           this.rootComponentBuildSystem,
@@ -328,6 +339,23 @@ export class CycloneDxWebpackPlugin {
       )
       logger.debug('Added rootComponent BuildSystem URL:', this.rootComponentBuildSystem)
     }
+    if (
+      typeof this.rootComponentVCS === 'string' &&
+      this.rootComponentVCS.length > 0 &&
+      !iterableSome(
+        component.externalReferences,
+        ref => ref.type === CDX.Enums.ExternalReferenceType.VCS
+      )
+    ) {
+      component.externalReferences.add(
+        new CDX.Models.ExternalReference(
+          this.rootComponentVCS,
+          CDX.Enums.ExternalReferenceType.VCS,
+          { comment: 'as declared via cyclonedx-webpack-plugin config "rootComponentVCS"' }
+        )
+      )
+      logger.debug('Added rootComponent VCS URL:', this.rootComponentVCS)
+    }
   }
 
   #makeRootComponent (