✨ --gem-server: Configurable Gem Server URL

Added --gem-server flag to allow users to specify a custom gem server
for fetching gem metadata instead of using the hardcoded default.

# CLI changes

- Added --gem-server URL option in Cyclonedx::BomBuilder command-line parser
- Stores custom server URL in @options[:gem_server] for use during BOM generation
- When specified, passes the custom gem_server to get_gem() calls
- Defaults to gem.coop when not specified, maintaining backward compatibility

# Core implementation

- Modified Cyclonedx::BomHelpers.get_gem to accept optional gem_server parameter
  - Defaults to 'https://gem.coop' when nil
  - Strips trailing slashes from gem_server URLs for consistency
  - Constructs gem metadata API URL using provided server
- Updated get_gem call in bom_builder.rb (line 222) to pass @options[:gem_server]

# Tests

Unit tests (spec/cyclonedx/bom_helpers_spec.rb):
- Validates default behavior uses gem.coop when gem_server is not provided or nil
- Verifies custom gem server URLs are used correctly
- Tests trailing slash removal from custom server URLs
- Confirms rubygems.org works as a custom server
- Maintains existing error handling tests

Cucumber tests (features/gem_server.feature):
- Validates default gem.coop behavior when --gem-server not specified
- Tests custom gem server with https://rubygems.org
- Tests custom gem server with trailing slash normalization
- Verifies help text displays the --gem-server option

# Use cases

Users can now:
- Use private gem servers: --gem-server https://internal.company.com
- Use rubygems.org directly: --gem-server https://rubygems.org
- Use alternate public mirrors
- Default to gem.coop without any configuration change

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

Author: pboling

.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-10-30 06:45:50 UTC using RuboCop version 1.81.6.
+# on 2025-12-19 21:12:16 UTC using RuboCop version 1.81.6.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -20,36 +20,51 @@ Layout/ExtraSpacing:
   Exclude:
     - 'cyclonedx-ruby.gemspec'
 
-# Offense count: 4
+# Offense count: 1
+Lint/NoReturnInBeginEndBlocks:
+  Exclude:
+    - 'lib/cyclonedx/bom_helpers.rb'
+
+# Offense count: 1
+Lint/StructNewOverride:
+  Exclude:
+    - 'spec/cyclonedx/component_enrichment_spec.rb'
+
+# Offense count: 6
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 68
+  Max: 100
 
-# Offense count: 4
+# Offense count: 12
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 38
+  Max: 83
 
 # Offense count: 1
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 129
+  Max: 195
 
-# Offense count: 1
+# Offense count: 5
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
-  Max: 9
+  Max: 20
 
-# Offense count: 7
+# Offense count: 9
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 69
+  Max: 108
 
 # Offense count: 1
+# Configuration parameters: CountComments, CountAsOne.
+Metrics/ModuleLength:
+  Max: 175
+
+# Offense count: 5
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
-  Max: 12
+  Max: 25
 
 # Offense count: 4
 # Configuration parameters: AllowedConstants.
@@ -67,7 +82,7 @@ Style/MixinUsage:
   Exclude:
     - 'lib/cyclonedx_deprecated.rb'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports unsafe autocorrection (--autocorrect-all).
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: literals, strict
@@ -95,7 +110,7 @@ Style/RedundantRegexpEscape:
     - 'features/step_definitions/json_bom_matching.rb'
     - 'features/step_definitions/xml_bom_matching.rb'
 
-# Offense count: 41
+# Offense count: 42
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
 # SupportedStyles: single_quotes, double_quotes
@@ -114,7 +129,15 @@ Style/StringLiterals:
 Style/SymbolArray:
   EnforcedStyle: brackets
 
-# Offense count: 7
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: AllowMethodsWithArguments, AllowedMethods, AllowedPatterns, AllowComments.
+# AllowedMethods: define_method
+Style/SymbolProc:
+  Exclude:
+    - 'lib/cyclonedx/bom_helpers.rb'
+
+# Offense count: 17
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https

features/gem_server.feature

@@ -0,0 +1,40 @@
+Feature: Custom Gem Server
+
+The `cyclonedx-ruby` command should allow users to specify a custom gem server
+to fetch gem metadata from, instead of using the default gem.coop server.
+
+Scenario: Use default gem server (gem.coop)
+  Given I use a fixture named "simple"
+  And I run `cyclonedx-ruby --path .`
+  Then the output should contain:
+  """
+  5 gems were written to BOM located at ./bom.xml
+  """
+  And a file named "bom.xml" should exist
+  And the generated XML BOM file "bom.xml" matches "bom.xml.expected"
+
+Scenario: Use custom gem server
+  Given I use a fixture named "simple"
+  And I run `cyclonedx-ruby --path . --gem-server https://rubygems.org`
+  Then the output should contain:
+  """
+  5 gems were written to BOM located at ./bom.xml
+  """
+  And a file named "bom.xml" should exist
+
+Scenario: Use custom gem server with trailing slash
+  Given I use a fixture named "simple"
+  And I run `cyclonedx-ruby --path . --gem-server https://rubygems.org/`
+  Then the output should contain:
+  """
+  5 gems were written to BOM located at ./bom.xml
+  """
+  And a file named "bom.xml" should exist
+
+Scenario: Help shows gem-server option
+  Given I run `cyclonedx-ruby --help`
+  Then the output should contain:
+  """
+  --gem-server URL             Gem server URL to fetch gem metadata (default: https://gem.coop)
+  """
+

features/help.feature

@@ -16,5 +16,6 @@ Scenario: Generate help on demand
           --validate 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)
+          --gem-server URL             Gem server URL to fetch gem metadata (default: https://gem.coop)
       -h, --help                       Show help message
   """

lib/cyclonedx/bom_builder.rb

@@ -77,8 +77,6 @@ def self.infer_format_from_path(path)
       File.extname(path).downcase == '.json' ? 'json' : 'xml'
     end
 
-    private
-
     def self.setup(path)
       @options = {}
       OptionParser.new do |opts|
@@ -108,6 +106,9 @@ def self.setup(path)
         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('--gem-server URL', 'Gem server URL to fetch gem metadata (default: https://gem.coop)') do |gem_server|
+          @options[:gem_server] = gem_server
+        end
         opts.on_tail('-h', '--help', 'Show help message') do
           puts opts
           exit
@@ -192,20 +193,20 @@ def self.setup(path)
 
       @logger.info("BOM will be written to #{@bom_file_path}") if @project_path
 
-      if @project_path
-        begin
-          # Use absolute path so it's correct regardless of current working directory
-          gemfile_path = File.join(@project_path, 'Gemfile.lock')
-          # Compute display path for logs: './Gemfile.lock' when provided path is '.', else '<provided>/Gemfile.lock'
-          display_gemfile_path = (@provided_path == '.' ? './Gemfile.lock' : File.join(@provided_path, 'Gemfile.lock'))
-          @logger.info("Parsing specs from #{display_gemfile_path}...")
-          gemfile_contents = File.read(gemfile_path)
-          @specs = Bundler::LockfileParser.new(gemfile_contents).specs
-          @logger.info('Specs successfully parsed!')
-        rescue StandardError => e
-          @logger.error("Unable to parse specs from #{gemfile_path}. #{e.message}: #{Array(e.backtrace).join("\n")}")
-          abort
-        end
+      return unless @project_path
+
+      begin
+        # Use absolute path so it's correct regardless of current working directory
+        gemfile_path = File.join(@project_path, 'Gemfile.lock')
+        # Compute display path for logs: './Gemfile.lock' when provided path is '.', else '<provided>/Gemfile.lock'
+        display_gemfile_path = (@provided_path == '.' ? './Gemfile.lock' : File.join(@provided_path, 'Gemfile.lock'))
+        @logger.info("Parsing specs from #{display_gemfile_path}...")
+        gemfile_contents = File.read(gemfile_path)
+        @specs = Bundler::LockfileParser.new(gemfile_contents).specs
+        @logger.info('Specs successfully parsed!')
+      rescue StandardError => e
+        @logger.error("Unable to parse specs from #{gemfile_path}. #{e.message}: #{Array(e.backtrace).join("\n")}")
+        abort
       end
     end
 
@@ -216,7 +217,7 @@ def self.specs_list
         object.name = dependency.name
         object.version = dependency.version
         object.purl = purl(object.name, object.version)
-        gem = get_gem(object.name, object.version, @logger)
+        gem = get_gem(object.name, object.version, @logger, @options[:gem_server])
         next if gem.nil?
 
         if gem['licenses']&.length&.positive?

lib/cyclonedx/bom_component.rb

@@ -31,7 +31,7 @@ def hash_val(include_enrichment: false)
 
       if include_enrichment
         # Add bom-ref using the purl when present
-        component_hash[:"bom-ref"] = @purl if @purl && !@purl.to_s.empty?
+        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?
@@ -41,18 +41,18 @@ def hash_val(include_enrichment: false)
       end
 
       if fetch('license_id')
-        component_hash[:"licenses"] = [
+        component_hash[:licenses] = [
           {
-            "license": {
-              "id": fetch('license_id')
+            license: {
+              id: fetch('license_id')
             }
           }
         ]
       elsif fetch('license_name')
-        component_hash[:"licenses"] = [
+        component_hash[:licenses] = [
           {
-            "license": {
-              "name": fetch('license_name')
+            license: {
+              name: fetch('license_name')
             }
           }
         ]
@@ -68,8 +68,6 @@ def fetch(key)
         @gem[key]
       elsif @gem.respond_to?(key)
         @gem.public_send(key)
-      else
-        nil
       end
     end
   end

lib/cyclonedx/bom_helpers.rb

@@ -63,8 +63,6 @@ def _get(obj, key)
         obj[key]
       elsif obj.respond_to?(key)
         obj.public_send(key)
-      else
-        nil
       end
     end
 
@@ -172,7 +170,7 @@ def build_bom_xml(gems, spec_version, include_metadata: false, include_enrichmen
     # Validate content against the selected CycloneDX schema (local files, offline)
     # Returns [true, nil] on success; [false, "message"] on failure
     def validate_bom_content(content, format, spec_version)
-      schema_dir = File.expand_path("../../schema", __dir__)
+      schema_dir = File.expand_path('../../schema', __dir__)
       case format
       when 'json'
         schema_path = File.join(schema_dir, "bom-#{spec_version}.schema.json")
@@ -193,6 +191,7 @@ def validate_bom_content(content, format, spec_version)
           data = JSON.parse(content)
           errors = schemer.validate(data).to_a
           return [true, nil] if errors.empty?
+
           # Build a compact error message
           msgs = errors.first(5).map do |e|
             path = Array(e['data_pointer']).join
@@ -208,12 +207,13 @@ def validate_bom_content(content, format, spec_version)
         schema_path = File.join(schema_dir, "bom-#{spec_version}.xsd")
         begin
           # Use local XML catalog to resolve imports like http://cyclonedx.org/schema/spdx
-          previous_catalog = ENV['XML_CATALOG_FILES']
+          previous_catalog = ENV.fetch('XML_CATALOG_FILES', nil)
           ENV['XML_CATALOG_FILES'] = File.join(schema_dir, 'xmlcatalog.xml')
           xsd = Nokogiri::XML::Schema(File.read(schema_path))
           doc = Nokogiri::XML(content) { |cfg| cfg.nonet }
           errors = xsd.validate(doc)
           return [true, nil] if errors.empty?
+
           [false, "XML schema validation failed: #{errors.first.message}"]
         rescue Errno::ENOENT
           [false, "XML schema not found at #{schema_path}"]
@@ -225,8 +225,11 @@ def validate_bom_content(content, format, spec_version)
       end
     end
 
-    def get_gem(name, version, logger)
-      url = "https://gem.coop/api/v1/versions/#{name}.json"
+    def get_gem(name, version, logger, gem_server = nil)
+      gem_server ||= 'https://gem.coop'
+      # Remove trailing slash if present
+      gem_server = gem_server.chomp('/')
+      url = "#{gem_server}/api/v1/versions/#{name}.json"
       begin
         RestClient.proxy = ENV.fetch('http_proxy', nil)
         response = RestClient::Request.execute(method: :get, url: url, read_timeout: 2, open_timeout: 2)