fix: replace auto-detected root component with user-provided one

Previously, disabling root component auto-detection while specifying a root component left the
auto-detected root in the BOM, with dependencies still attached to it (issue #1418).

This change ensures that all instances of the auto-detected root are replaced by the
user-provided component using a `componentSubstitutionMap` during component generation.
Also introduced a new `RichComponentBuilder` to centralize handling of component creation, BOM reference initialization,
and PURL assignment, moving relevant logic out of `Extractor`.

Regression tests were added for that particular case

Signed-off-by: Maxim Bagryantsev <[email protected]>

Author: max619

src/extractor.ts

@@ -17,39 +17,31 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
-import { dirname } from 'node:path'
-
-import * as CDX from '@cyclonedx/cyclonedx-library'
+import type * as CDX from '@cyclonedx/cyclonedx-library'
 import type { Compilation, Module } from 'webpack'
 
+import type {
+  PackageDescription} from './_helpers'
 import {
   getPackageDescription,
-  isNonNullable,
-  normalizePackageManifest,
-  type PackageDescription,
-  structuredClonePolyfill} from './_helpers'
+  isNonNullable} from './_helpers'
+import type {RichComponentBuilder} from './richComponentBuilder'
 
 type WebpackLogger = Compilation['logger']
 
 export class Extractor {
   readonly #compilation: Compilation
-  readonly #componentBuilder: CDX.Builders.FromNodePackageJson.ComponentBuilder
-  readonly #purlFactory: CDX.Factories.FromNodePackageJson.PackageUrlFactory
-  readonly #leGatherer: CDX.Utils.LicenseUtility.LicenseEvidenceGatherer
+  readonly #componentBuilder: RichComponentBuilder
 
   constructor (
     compilation: Compilation,
-    componentBuilder: CDX.Builders.FromNodePackageJson.ComponentBuilder,
-    purlFactory: CDX.Factories.FromNodePackageJson.PackageUrlFactory,
-    leFetcher: CDX.Utils.LicenseUtility.LicenseEvidenceGatherer
+    componentBuilder: RichComponentBuilder,
   ) {
     this.#compilation = compilation
     this.#componentBuilder = componentBuilder
-    this.#purlFactory = purlFactory
-    this.#leGatherer = leFetcher
   }
 
-  generateComponents (modules: Iterable<Module>, collectEvidence: boolean, logger?: WebpackLogger): Iterable<CDX.Models.Component> {
+  generateComponents (modules: Iterable<Module>, componentSubstitutionMap: Map<string, CDX.Models.Component>, collectEvidence: boolean, logger?: WebpackLogger): Iterable<CDX.Models.Component> {
     const pkgs: Record<string, CDX.Models.Component | undefined> = {}
     const components = new Map<Module, CDX.Models.Component>()
 
@@ -68,7 +60,7 @@ export class Extractor {
       if (component === undefined) {
         logger?.log('try to build new Component from PkgPath:', pkg.path)
         try {
-          component = this.makeComponent(pkg, collectEvidence, logger)
+          component = this.#makeComponent(pkg, componentSubstitutionMap, collectEvidence, logger)
         } catch (err) {
           logger?.debug('unexpected error:', err)
           logger?.warn('skipped Component from PkgPath', pkg.path)
@@ -90,39 +82,21 @@ export class Extractor {
   /**
    * @throws {@link Error} when no component could be fetched
    */
-  makeComponent (pkg: PackageDescription, collectEvidence: boolean, logger?: WebpackLogger): CDX.Models.Component {
-    try {
-      // work with a deep copy, because `normalizePackageManifest()` might modify the data
-      /* eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- ach */
-      const _packageJson = structuredClonePolyfill(pkg.packageJson)
-      normalizePackageManifest(_packageJson)
-      pkg.packageJson = _packageJson
-    } catch (e) {
-      logger?.warn('normalizePackageJson from PkgPath', pkg.path, 'failed:', e)
-    }
-
-    const component = this.#componentBuilder.makeComponent(
-      /* @ts-expect-error TS2559 */
-      pkg.packageJson as PackageDescription) /* eslint-disable-line  @typescript-eslint/no-unsafe-type-assertion -- ack */
-
-    if (component === undefined) {
-      throw new Error(`failed building Component from PkgPath ${pkg.path}`)
+  #makeComponent(pkg: PackageDescription, componentSubstitutionMap: Map<string, CDX.Models.Component>, collectEvidence: boolean, logger?: WebpackLogger): CDX.Models.Component
+  {
+    const newComponent = this.#componentBuilder.makeComponent(pkg, collectEvidence, logger)
+    if(newComponent === undefined) {
+      throw Error(`failed building Component from PkgPath ${pkg.path}`)
     }
 
-    component.licenses.forEach(l => {
-      l.acknowledgement = CDX.Enums.LicenseAcknowledgement.Declared
-    })
-
-    if (collectEvidence) {
-      component.evidence = new CDX.Models.ComponentEvidence({
-        licenses: new CDX.Models.LicenseRepository(this.getLicenseEvidence(dirname(pkg.path), logger))
-      })
+    if(newComponent.bomRef.value !== undefined) {
+      const remappedComponent = componentSubstitutionMap.get(newComponent.bomRef.value)
+      if(remappedComponent !== undefined) {
+        return remappedComponent
+      }
     }
 
-    component.purl = this.#purlFactory.makeFromComponent(component)
-    component.bomRef.value = component.purl?.toString()
-
-    return component
+    return newComponent
   }
 
   #linkDependencies (modulesComponents: Map<Module, CDX.Models.Component>): void {
@@ -135,25 +109,4 @@ export class Extractor {
       }
     }
   }
-
-  public * getLicenseEvidence (packageDir: string, logger?: WebpackLogger): Generator<CDX.Models.License> {
-    const files = this.#leGatherer.getFileAttachments(
-      packageDir,
-      (error: Error): void => {
-        /* c8 ignore next 2 */
-        logger?.info(error.message)
-        logger?.debug(error.message, error)
-      }
-    )
-    try {
-      for (const {file, text} of files) {
-        yield new CDX.Models.NamedLicense(`file: ${file}`, { text })
-      }
-    }
-    /* c8 ignore next 3 */
-    catch (e) {
-      // generator will not throw before first `.nest()` is called ...
-      logger?.warn('collecting license evidence in', packageDir, 'failed:', e)
-    }
-  }
 }

src/plugin.ts

@@ -31,6 +31,7 @@ import {
   type PackageDescription
 } from './_helpers'
 import { Extractor } from './extractor'
+import { RichComponentBuilder } from './richComponentBuilder'
 
 type WebpackLogger = Compilation['logger']
 
@@ -211,10 +212,12 @@ export class CycloneDxWebpackPlugin {
     const cdxLicenseFactory = new CDX.Factories.LicenseFactory()
     const cdxPurlFactory = new CDX.Factories.FromNodePackageJson.PackageUrlFactory('npm')
     const cdxComponentBuilder = new CDX.Builders.FromNodePackageJson.ComponentBuilder(cdxExternalReferenceFactory, cdxLicenseFactory)
+    const richComponentBuilder = new RichComponentBuilder(cdxComponentBuilder, cdxPurlFactory, new CDX.Utils.LicenseUtility.LicenseEvidenceGatherer())
 
     const bom = new CDX.Models.Bom()
     bom.metadata.lifecycles.add(CDX.Enums.LifecyclePhase.Build)
-    bom.metadata.component = this.#makeRootComponent(compilation.compiler.context, cdxComponentBuilder, logger.getChildLogger('RootComponentBuilder'))
+    const rootComponents = this.#makeRootComponents(compilation.compiler.context, richComponentBuilder, logger.getChildLogger('RootComponentBuilder'))
+    bom.metadata.component = rootComponents?.rootComponent
 
     const serializeOptions: CDX.Serialize.Types.SerializerOptions & CDX.Serialize.Types.NormalizerOptions = {
       sortLists: this.reproducibleResults,
@@ -255,23 +258,22 @@ export class CycloneDxWebpackPlugin {
       }
     }
 
+    const componentSubstitutionMap = new Map<string, CDX.Models.Component>()
+    if(rootComponents !== undefined && rootComponents.autoDetectedRootComponent !== rootComponents.rootComponent && rootComponents.autoDetectedRootComponent.bomRef.value !== undefined) {
+      componentSubstitutionMap.set(rootComponents.autoDetectedRootComponent.bomRef.value, rootComponents.rootComponent)
+    }
     compilation.hooks.afterOptimizeTree.tap(
       pluginName,
       (_, modules) => {
         const thisLogger = logger.getChildLogger('ComponentFetcher')
         const extractor = new Extractor(
           compilation,
-          cdxComponentBuilder,
-          cdxPurlFactory,
-          new CDX.Utils.LicenseUtility.LicenseEvidenceGatherer()
+          richComponentBuilder
         )
 
         thisLogger.log('generating components...')
-        for (const component of extractor.generateComponents(modules, this.collectEvidence, thisLogger.getChildLogger('Extractor'))) {
-          if (bom.metadata.component !== undefined &&
-            bom.metadata.component.group === component.group &&
-            bom.metadata.component.name === component.name &&
-            bom.metadata.component.version === component.version
+        for (const component of extractor.generateComponents(modules, componentSubstitutionMap, this.collectEvidence, thisLogger.getChildLogger('Extractor'))) {
+          if (bom.metadata.component !== undefined && component.bomRef.value !== undefined && bom.metadata.component.bomRef.value === component.bomRef.value
           ) {
             // metadata matches this exact component.
             // -> so the component is actually treated as the root component.
@@ -376,23 +378,30 @@ export class CycloneDxWebpackPlugin {
     }
   }
 
-  #makeRootComponent (
+  #makeRootComponents (
     path: string,
-    builder: CDX.Builders.FromNodePackageJson.ComponentBuilder,
+    builder: RichComponentBuilder,
     logger: WebpackLogger
-  ): CDX.Models.Component | undefined {
-    /* eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- expected */
+  ): {rootComponent: CDX.Models.Component, autoDetectedRootComponent: CDX.Models.Component} | undefined {
+    const autoDetectedComponent = getPackageDescription(path)
     const thisPackageJson = this.rootComponentAutodetect
-      ? getPackageDescription(path)?.packageJson
-      : { name: this.rootComponentName, version: this.rootComponentVersion }
+      ? autoDetectedComponent
+      : { path, packageJson: { name: this.rootComponentName, version: this.rootComponentVersion } }
     if (thisPackageJson === undefined) { return undefined }
     normalizePackageManifest(
-       
       thisPackageJson,
       w => { logger.debug('normalizePackageJson from PkgPath', path, 'caused:', w) }
     )
-     
-    return builder.makeComponent(thisPackageJson)
+    const rootComponent = builder.makeComponent(thisPackageJson, false, logger)
+    const autoDetectedRootComponent =
+                autoDetectedComponent === thisPackageJson ?
+                  rootComponent :
+                  autoDetectedComponent !== undefined ?
+                    builder.makeComponent(autoDetectedComponent, false, logger) :
+                    undefined
+
+    if(rootComponent === undefined || autoDetectedRootComponent === undefined) { return undefined }
+    return { rootComponent, autoDetectedRootComponent }
   }
 
   #finalizeBom (

src/richComponentBuilder.ts

@@ -0,0 +1,105 @@
+/*!
+This file is part of CycloneDX Webpack plugin.
+
+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 { dirname } from 'node:path'
+
+import * as CDX from '@cyclonedx/cyclonedx-library'
+import type { Compilation } from 'webpack'
+
+import type { PackageDescription} from './_helpers'
+import { normalizePackageManifest, structuredClonePolyfill } from './_helpers'
+
+
+type WebpackLogger = Compilation['logger']
+
+export class RichComponentBuilder
+{
+    readonly #componentBuilder : CDX.Builders.FromNodePackageJson.ComponentBuilder
+    readonly #purlFactory : CDX.Factories.FromNodePackageJson.PackageUrlFactory
+    readonly #leGatherer: CDX.Utils.LicenseUtility.LicenseEvidenceGatherer
+
+    constructor(
+      componentBuilder: CDX.Builders.FromNodePackageJson.ComponentBuilder,
+      purlFactory: CDX.Factories.FromNodePackageJson.PackageUrlFactory,
+      leFetcher: CDX.Utils.LicenseUtility.LicenseEvidenceGatherer
+     )
+    {
+        this.#componentBuilder = componentBuilder
+        this.#purlFactory = purlFactory
+        this.#leGatherer = leFetcher
+    }
+
+  makeComponent (pkg: PackageDescription, collectEvidence: boolean, logger?: WebpackLogger): CDX.Models.Component | undefined {
+    try {
+      // work with a deep copy, because `normalizePackageManifest()` might modify the data
+      /* eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- ach */
+      const _packageJson = structuredClonePolyfill(pkg.packageJson)
+      normalizePackageManifest(_packageJson)
+      pkg.packageJson = _packageJson
+    /* c8 ignore next 3 */
+    } catch (e) {
+      logger?.warn('normalizePackageJson from PkgPath', pkg.path, 'failed:', e)
+    }
+
+    const component = this.#componentBuilder.makeComponent(
+      /* @ts-expect-error TS2559 */
+      pkg.packageJson as PackageDescription) /* eslint-disable-line  @typescript-eslint/no-unsafe-type-assertion -- ack */
+
+    if (component === undefined) {
+        return undefined
+    }
+
+    component.licenses.forEach(l => {
+      l.acknowledgement = CDX.Enums.LicenseAcknowledgement.Declared
+    })
+
+    if (collectEvidence) {
+      component.evidence = new CDX.Models.ComponentEvidence({
+        licenses: new CDX.Models.LicenseRepository(this.getLicenseEvidence(dirname(pkg.path), logger))
+      })
+    }
+
+    component.purl = this.#purlFactory.makeFromComponent(component)
+    component.bomRef.value = component.purl?.toString()
+
+    return component
+  }
+
+
+  private * getLicenseEvidence (packageDir: string, logger?: WebpackLogger): Generator<CDX.Models.License> {
+    const files = this.#leGatherer.getFileAttachments(
+      packageDir,
+      (error: Error): void => {
+        /* c8 ignore next 2 */
+        logger?.info(error.message)
+        logger?.debug(error.message, error)
+      }
+    )
+    try {
+      for (const {file, text} of files) {
+        yield new CDX.Models.NamedLicense(`file: ${file}`, { text })
+      }
+    }
+    /* c8 ignore next 3 */
+    catch (e) {
+      // generator will not throw before first `.nest()` is called ...
+      logger?.warn('collecting license evidence in', packageDir, 'failed:', e)
+    }
+  }
+}