✨ --enrich-components

# CLI and wiring

- Updated Cyclonedx::BomBuilder to add:
  - CLI: --enrich-components to opt-in enrichment.
  - Pass include_enrichment to build_bom(...).
- Note: This does not alter default outputs; enrichment only applies with the flag.

# JSON and XML emission

- Updated Cyclonedx::BomHelpers:
  - build_bom supports include_enrichment and passes it to both JSON and XML builders.
  - build_json_bom adds bom-ref and publisher via BomComponent when include_enrichment: true.
  - build_bom_xml adds:
    - bom-ref attribute on <component> using purl.
    - <publisher>first_author</publisher> if authors are present (first item split on commas/ampersands).
  - Added a small _get helper to read properties from either Hash or OpenStruct-like objects.

# Component shape

- Updated Cyclonedx::BomComponent:
  - Added optional keyword parameter include_enrichment: false to hash_val.
  - When true, include:
    - "bom-ref": purl (if present)
    - "publisher": first author (if present)
  - Made property access robust across Hash/OpenStruct.
  - Ensured hashes is an array with an object { alg, content } as expected by existing specs.

# Tests

- Added spec/cyclonedx/component_enrichment_spec.rb:
  - Verifies JSON has bom-ref and publisher when include_enrichment: true and omits them otherwise.
  - Verifies XML has bom-ref attribute and <publisher> when include_enrichment: true and omits otherwise.

Signed-off-by: Peter H. Boling <[email protected]>

Author: pboling

features/help.feature

@@ -16,5 +16,6 @@ Scenario: Generate help on demand
           --validate                   Validate the produced BOM against the selected CycloneDX schema
           --validate-file PATH         Validate an existing BOM file instead of generating one
           --include-metadata           Include metadata.tools identifying cyclonedx-ruby as the producer
+          --enrich-components          Include bom-ref and publisher fields on components (uses purl and first author)
       -h, --help                       Show help message
   """

features/metadata_tools.feature

@@ -11,13 +11,18 @@ Feature: Include metadata.tools in BOM
     And the file "bom.json" should contain:
     """
     "metadata": {
-      "tools": [
-        {
-          "vendor": "CycloneDX",
-          "name": "cyclonedx-ruby"
-        }
-      ]
-    }
+    """
+    And the file "bom.json" should contain:
+    """
+    "tools": [
+    """
+    And the file "bom.json" should contain:
+    """
+    "vendor": "CycloneDX"
+    """
+    And the file "bom.json" should contain:
+    """
+    "name": "cyclonedx-ruby"
     """
 
   Scenario: JSON metadata BOM validates against schema
@@ -40,10 +45,22 @@ Feature: Include metadata.tools in BOM
     And the file "bom.xml" should contain:
     """
     <metadata>
-      <tools>
-        <tool>
-          <vendor>CycloneDX</vendor>
-          <name>cyclonedx-ruby</name>
+    """
+    And the file "bom.xml" should contain:
+    """
+    <tools>
+    """
+    And the file "bom.xml" should contain:
+    """
+    <tool>
+    """
+    And the file "bom.xml" should contain:
+    """
+    <vendor>CycloneDX</vendor>
+    """
+    And the file "bom.xml" should contain:
+    """
+    <name>cyclonedx-ruby</name>
     """
 
   Scenario: XML metadata BOM validates against schema

lib/cyclonedx/bom_builder.rb

@@ -31,7 +31,7 @@ def self.build(path)
       end
 
       specs_list
-      bom = build_bom(@gems, @bom_output_format, @spec_version, include_metadata: @options[:include_metadata])
+      bom = build_bom(@gems, @bom_output_format, @spec_version, include_metadata: @options[:include_metadata], include_enrichment: @options[:enrich_components])
 
       begin
         @logger.info("Changing directory to the original working directory located at #{original_working_directory}")
@@ -108,6 +108,9 @@ def self.setup(path)
         opts.on('--include-metadata', 'Include metadata.tools identifying cyclonedx-ruby as the producer') do
           @options[:include_metadata] = true
         end
+        opts.on('--enrich-components', 'Include bom-ref and publisher fields on components (uses purl and first author)') do
+          @options[:enrich_components] = true
+        end
         opts.on_tail('-h', '--help', 'Show help message') do
           puts opts
           exit

lib/cyclonedx/bom_component.rb

@@ -6,43 +6,71 @@ class BomComponent
     HASH_ALG = 'SHA-256'.freeze
 
     def initialize(gem)
-      @name = gem['name']
-      @version = gem['version']
-      @description = gem['description']
-      @hash = gem['hash']
-      @purl = gem['purl']
       @gem = gem
+      @name = fetch('name')
+      @version = fetch('version')
+      @description = fetch('description')
+      @hash = fetch('hash')
+      @purl = fetch('purl')
     end
 
-    def hash_val
+    def hash_val(include_enrichment: false)
       component_hash = {
         "type": DEFAULT_TYPE,
         "name": @name,
         "version": @version,
         "description": @description,
         "purl": @purl,
         "hashes": [
+          {
             "alg": HASH_ALG,
             "content": @hash
+          }
         ]
       }
 
-      if @gem['license_id']
+      if include_enrichment
+        # Add bom-ref using the purl when present
+        component_hash[:"bom-ref"] = @purl if @purl && !@purl.to_s.empty?
+        # Add publisher using first author if present
+        author = fetch('author')
+        if author && !author.to_s.strip.empty?
+          first_author = author.to_s.split(/[,&]/).first.to_s.strip
+          component_hash[:publisher] = first_author unless first_author.empty?
+        end
+      end
+
+      if fetch('license_id')
         component_hash[:"licenses"] = [
-          "license": {
-            "id": @gem['license_id']
+          {
+            "license": {
+              "id": fetch('license_id')
+            }
           }
         ]
-      elsif @gem['license_name']
+      elsif fetch('license_name')
         component_hash[:"licenses"] = [
-          "license": {
-            "name": @gem['license_name']
+          {
+            "license": {
+              "name": fetch('license_name')
+            }
           }
         ]
       end
 
       [component_hash]
+    end
+
+    private
 
+    def fetch(key)
+      if @gem.respond_to?(:[]) && @gem[key]
+        @gem[key]
+      elsif @gem.respond_to?(key)
+        @gem.public_send(key)
+      else
+        nil
+      end
     end
   end
 end

lib/cyclonedx/bom_helpers.rb

@@ -58,15 +58,26 @@ def tool_identity
       }
     end
 
-    def build_bom(gems, format, spec_version, include_metadata: false)
+    # Safe accessor for Hash or OpenStruct-like objects
+    def _get(obj, key)
+      if obj.respond_to?(:[]) && obj[key]
+        obj[key]
+      elsif obj.respond_to?(key)
+        obj.public_send(key)
+      else
+        nil
+      end
+    end
+
+    def build_bom(gems, format, spec_version, include_metadata: false, include_enrichment: false)
       if format == 'json'
-        build_json_bom(gems, spec_version, include_metadata: include_metadata)
+        build_json_bom(gems, spec_version, include_metadata: include_metadata, include_enrichment: include_enrichment)
       else
-        build_bom_xml(gems, spec_version, include_metadata: include_metadata)
+        build_bom_xml(gems, spec_version, include_metadata: include_metadata, include_enrichment: include_enrichment)
       end
     end
 
-    def build_json_bom(gems, spec_version, include_metadata: false)
+    def build_json_bom(gems, spec_version, include_metadata: false, include_enrichment: false)
       bom_hash = {
         "bomFormat": "CycloneDX",
         "specVersion": spec_version,
@@ -85,13 +96,13 @@ def build_json_bom(gems, spec_version, include_metadata: false)
       end
 
       gems.each do |gem|
-        bom_hash[:components] += BomComponent.new(gem).hash_val()
+        bom_hash[:components] += BomComponent.new(gem).hash_val(include_enrichment: include_enrichment)
       end
 
       JSON.pretty_generate(bom_hash)
     end
 
-    def build_bom_xml(gems, spec_version, include_metadata: false)
+    def build_bom_xml(gems, spec_version, include_metadata: false, include_enrichment: false)
       builder = Nokogiri::XML::Builder.new(encoding: 'UTF-8') do |xml|
         attributes = { 'xmlns' => cyclonedx_xml_namespace(spec_version), 'version' => '1', 'serialNumber' => random_urn_uuid }
         xml.bom(attributes) do
@@ -110,31 +121,46 @@ def build_bom_xml(gems, spec_version, include_metadata: false)
 
           xml.components do
             gems.each do |gem|
-              xml.component('type' => 'library') do
-                xml.name gem['name']
-                xml.version gem['version']
-                xml.description gem['description']
+              comp_attrs = { 'type' => 'library' }
+              if include_enrichment
+                # Add bom-ref attribute using purl if available
+                ref = _get(gem, 'purl')
+                comp_attrs['bom-ref'] = ref if ref && !ref.to_s.empty?
+              end
+              xml.component(comp_attrs) do
+                xml.name _get(gem, 'name')
+                xml.version _get(gem, 'version')
+                xml.description _get(gem, 'description')
                 xml.hashes  do
-                  xml.hash_ gem['hash'], alg: 'SHA-256'
+                  xml.hash_ _get(gem, 'hash'), alg: 'SHA-256'
                 end
-                if gem['license_id']
+                if _get(gem, 'license_id')
                   xml.licenses do
                     xml.license do
-                      xml.id gem['license_id']
+                      xml.id _get(gem, 'license_id')
                     end
                   end
-                elsif gem['license_name']
+                elsif _get(gem, 'license_name')
                   xml.licenses do
                     xml.license do
-                      xml.name gem['license_name']
+                      xml.name _get(gem, 'license_name')
                     end
                   end
                 end
                 # The globally scoped legacy `Object#purl` method breaks the Nokogiri builder context
                 # Fortunately Nokogiri has a built-in workaround, adding an underscore to the method name.
                 # The resulting XML tag is still `<purl>`.
                 # Globally scoped legacy `Object#purl` will be removed in v2.0.0, and this hack can be removed then.
-                xml.purl_ gem['purl']
+                xml.purl_ _get(gem, 'purl')
+
+                if include_enrichment
+                  # Add optional publisher element if author info exists
+                  author = _get(gem, 'author')
+                  if author && !author.to_s.strip.empty?
+                    first_author = author.to_s.split(/[,&]/).first.to_s.strip
+                    xml.publisher first_author unless first_author.empty?
+                  end
+                end
               end
             end
           end

spec/cyclonedx/component_enrichment_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'nokogiri'
+require_relative '../../lib/cyclonedx/bom_helpers'
+
+RSpec.describe 'component enrichment' do
+  let(:spec_version) { '1.7' }
+  let(:gem_obj) do
+    # Use OpenStruct-like object by simple Struct for deterministic methods
+    Struct.new(:name, :version, :description, :hash, :purl, :author, :license_id, :license_name)
+          .new('sample', '1.0.0', 'desc', 'abc123', 'pkg:gem/[email protected]', 'Alice, Bob', nil, nil)
+  end
+
+  it 'adds bom-ref and publisher for JSON when include_enrichment is true' do
+    json = Cyclonedx::BomHelpers.build_json_bom([gem_obj], spec_version, include_enrichment: true)
+    data = JSON.parse(json)
+    comp = data['components'].first
+    expect(comp['bom-ref']).to eq('pkg:gem/[email protected]')
+    expect(comp['publisher']).to eq('Alice')
+  end
+
+  it 'does not add enrichment fields when flag is false' do
+    json = Cyclonedx::BomHelpers.build_json_bom([gem_obj], spec_version, include_enrichment: false)
+    data = JSON.parse(json)
+    comp = data['components'].first
+    expect(comp).not_to have_key('bom-ref')
+    expect(comp).not_to have_key('publisher')
+  end
+
+  it 'adds bom-ref attribute and publisher element for XML when include_enrichment is true' do
+    xml = Cyclonedx::BomHelpers.build_bom_xml([gem_obj], spec_version, include_enrichment: true)
+    doc = Nokogiri::XML(xml)
+    ns = { 'c' => Cyclonedx::BomHelpers.cyclonedx_xml_namespace(spec_version) }
+    comp = doc.at_xpath('/c:bom/c:components/c:component', ns)
+    expect(comp['bom-ref']).to eq('pkg:gem/[email protected]')
+    expect(doc.at_xpath('/c:bom/c:components/c:component/c:publisher', ns)&.text).to eq('Alice')
+  end
+
+  it 'omits enrichment fields in XML when flag is false' do
+    xml = Cyclonedx::BomHelpers.build_bom_xml([gem_obj], spec_version, include_enrichment: false)
+    doc = Nokogiri::XML(xml)
+    ns = { 'c' => Cyclonedx::BomHelpers.cyclonedx_xml_namespace(spec_version) }
+    comp = doc.at_xpath('/c:bom/c:components/c:component', ns)
+    expect(comp['bom-ref']).to be_nil
+    expect(doc.at_xpath('/c:bom/c:components/c:component/c:publisher', ns)).to be_nil
+  end
+end
+