purl 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae14d9c24e0b1f4f8d76b97c59ed34d8e34090d5329ac9358bf40be4e4acdf14
-  data.tar.gz: 4ff6fa43fd388006d553bae72b4685ef228cff186b135ec335d7a6b724abb034
+  metadata.gz: 519631a904ead8452084959edb20711e684c0fc9c0b0a848ff6775f86bc31675
+  data.tar.gz: cb82893be40a50ae28651b78ed293dd0303b6cc926b81985fe256d32f0b0fea7
 SHA512:
-  metadata.gz: 5f965309ce3f2dddc29065c247082f11541a8ead617c2ad398a7dbd71affd6417e7f09959d88ea59492256dec7039b458507688da9288723bda2d83942f6683f
-  data.tar.gz: eb9fd5d72ba8a6c40cafe9c736594f76d20ea40e1886af1693d54dbb36b1ba1105ed05b415b6989098b7288df79a6e9f3c3ddb7aa095eb6dad069a7755374f39
+  metadata.gz: 5ef9defb2759c124020aa5d6ba88eb281e0bd1fbf256cafdd3ba7c4e17bca09aec0286fe2851b74e12313062a5d3e38a76db85376b60d3f645e9f4720e0cb2b8
+  data.tar.gz: 6399a94cf6bd5bd92fa6e5da30f7f9c6e056982728bc5828ead26e9d8c9c17b5beedbe4bdababebc0bee701bdeaf27f4ffa7b84e54a451d45e7dea7c9575c9b7

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "purl-spec"]
+	path = purl-spec
+	url = https://github.com/package-url/purl-spec.git

data/CHANGELOG.md

@@ -7,6 +7,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2025-07-27
+
+### Added
+- Default registry URLs for 10 additional package types:
+  - `golang`: https://pkg.go.dev (Go package discovery site)
+  - `luarocks`: https://luarocks.org (Lua package repository)
+  - `clojars`: https://clojars.org (Clojure package repository)
+  - `elm`: https://package.elm-lang.org (Elm package catalog)
+  - `deno`: https://deno.land (Deno module registry)
+  - `homebrew`: https://formulae.brew.sh (Homebrew package browser)
+  - `bioconductor`: https://bioconductor.org (R bioinformatics packages)
+  - `huggingface`: https://huggingface.co (Machine learning models)
+  - `swift`: https://swiftpackageindex.com (Swift package index)
+  - `conan`: https://conan.io/center (C/C++ package center)
+
+### Enhanced
+- Registry configuration support for newly added package types
+- Updated test suite to validate all new default registries
+- Improved package type coverage with comprehensive registry URL mapping
+
+### Configuration
+- Updated `purl-types.json` to version 1.2.0 with enhanced registry configurations
+- Added specialized registry handling for Go's unique import path structure
+
+## [1.1.2] - 2025-07-25
+
+### Added
+- Comprehensive benchmarking rake tasks for performance analysis
+  - `rake benchmark:parse` - PURL parsing performance benchmarks
+  - `rake benchmark:types` - Package type parsing comparison
+  - `rake benchmark:registry` - Registry URL generation benchmarks
+  - `rake benchmark:all` - Run all benchmarks
+
+### Improved
+- **26% improvement in parsing throughput** (~175K PURLs/second)
+- **8% improvement in string conversion performance** (~315K conversions/second)
+- **7% improvement in object creation** (~280K objects/second)
+- Optimized string operations in parse method with conditional regex application
+- Reduced string allocations in `to_s` method using array joining
+- Cached compiled regexes with `.freeze` for better performance
+- Lower memory allocation pressure in high-throughput scenarios
+
+## [1.1.1] - 2025-07-25
+
+### Added
+- Comprehensive RDoc documentation for all classes and methods
+- RDoc task in Rakefile with proper configuration
+- API documentation link in README
+
+### Fixed
+- Add bigdecimal gem dependency to resolve potential loading issues
+- Improve JSON schema loading error handling
+
+## [1.1.0] - 2025-07-25
+
+### Added
+- JSON schema validation for configuration files (`purl-types.json` and `test-suite-data.json`)
+- New rake tasks: `spec:validate_schemas` and `spec:validate_examples`
+- Examples for all package types in configuration
+- Default registry URLs for package types
+- Enhanced reverse parsing support for additional package types
+- `with` method for creating modified PURL objects (immutable pattern)
+- FUNDING.yml for project sponsorship support
+
+### Enhanced
+- Improved README documentation with custom registry examples
+- Enhanced test coverage for new functionality
+- Better compliance test output formatting
+- Comprehensive package type examples and validation
+
+### Documentation
+- Updated documentation to remove emoji and enhance readability
+- Added comprehensive examples for custom registry usage
+- Enhanced API documentation throughout
+
 ## [1.0.0] - 2025-01-24
 
 ### Added

data/README.md

@@ -10,6 +10,10 @@ This library features comprehensive error handling with namespaced error types,
 
 **[Available on RubyGems](https://rubygems.org/gems/purl)** | **[API Documentation](https://rdoc.info/github/andrew/purl)**
 
+## Related Libraries
+
+- **[Vers](https://github.com/andrew/vers)** - A Ruby library for working with version ranges that supports the VERS specification
+
 ## Features
 
 - **Comprehensive PURL parsing and validation** with 37 package types (32 official + 5 additional ecosystems)
@@ -381,6 +385,25 @@ rake spec:types
 rake spec:verify_types
 ```
 
+### Testing Against Official Specification
+
+This library includes the official [purl-spec](https://github.com/package-url/purl-spec) repository as a git submodule for testing and validation:
+
+```bash
+# Initialize submodule (first time only)
+git submodule update --init --recursive
+
+# Update submodule to latest spec
+git submodule update --remote purl-spec
+```
+
+The tests use files from the submodule to:
+- **Schema validation**: Validate our `purl-types.json` against the official schema in `purl-spec/schemas/`
+- **Type compliance**: Ensure our supported types match the official types in `purl-spec/types/`
+- **Test data**: Access official test cases and examples from `purl-spec/tests/`
+
+The submodule is automatically updated weekly via Dependabot, ensuring tests stay current with the latest specification changes. When the submodule updates, you can review and merge the PR to adopt new spec requirements.
+
 ### Rake Tasks
 
 - `rake spec:update` - Fetch latest test cases from official PURL spec repository

data/Rakefile

@@ -562,3 +562,240 @@ namespace :spec do
     end
   end
 end
+
+namespace :benchmark do
+  desc "Run PURL parsing benchmarks"
+  task :parse do
+    require "benchmark"
+    require "json"
+    require_relative "lib/purl"
+    
+    puts "🚀 PURL Parsing Benchmarks"
+    puts "=" * 50
+    
+    # Load sample PURLs from purl-types.json
+    purl_types_data = JSON.parse(File.read(File.join(__dir__, "purl-types.json")))
+    sample_purls = []
+    
+    purl_types_data["types"].each do |type_name, type_config|
+      examples = type_config["examples"]
+      sample_purls.concat(examples) if examples&.is_a?(Array)
+    end
+    
+    # Add some complex PURLs for stress testing
+    complex_purls = [
+      "pkg:npm/@babel/core@7.20.0?arch=x64&dev=true#lib/index.js",
+      "pkg:maven/org.apache.commons/commons-lang3@3.12.0?classifier=sources",
+      "pkg:composer/symfony/console@5.4.0?extra=test&dev=true#src/Application.php",
+      "pkg:gem/rails@7.0.0?platform=ruby&env=production#app/controllers/application_controller.rb"
+    ]
+    sample_purls.concat(complex_purls)
+    
+    puts "📊 Sample size: #{sample_purls.length} PURLs"
+    puts "📦 Package types: #{purl_types_data['types'].keys.length}"
+    puts
+    
+    # Benchmark parsing
+    puts "🔍 Parsing Performance:"
+    parsing_time = Benchmark.realtime do
+      sample_purls.each { |purl| Purl.parse(purl) }
+    end
+    
+    puts "   Total time: #{(parsing_time * 1000).round(2)}ms"
+    puts "   Average per PURL: #{(parsing_time * 1000 / sample_purls.length).round(3)}ms"
+    puts "   PURLs per second: #{(sample_purls.length / parsing_time).round(0)}"
+    puts
+    
+    # Benchmark creation
+    puts "🔧 Object Creation Performance:"
+    creation_time = Benchmark.realtime do
+      1000.times do
+        Purl::PackageURL.new(
+          type: "gem",
+          namespace: "rails",
+          name: "rails",
+          version: "7.0.0",
+          qualifiers: {"arch" => "x64"},
+          subpath: "app/models/user.rb"
+        )
+      end
+    end
+    
+    puts "   1000 objects: #{(creation_time * 1000).round(2)}ms"
+    puts "   Average per object: #{(creation_time * 1000 / 1000).round(3)}ms"
+    puts "   Objects per second: #{(1000 / creation_time).round(0)}"
+    puts
+    
+    # Benchmark to_s conversion
+    puts "🔤 String Conversion Performance:"
+    test_purl = Purl.parse("pkg:npm/@babel/core@7.20.0?arch=x64#lib/index.js")
+    
+    string_time = Benchmark.realtime do
+      10000.times { test_purl.to_s }
+    end
+    
+    puts "   10,000 conversions: #{(string_time * 1000).round(2)}ms"
+    puts "   Average per conversion: #{(string_time * 1000 / 10000).round(4)}ms"
+    puts "   Conversions per second: #{(10000 / string_time).round(0)}"
+    puts
+    
+    # Memory usage estimation
+    puts "💾 Memory Usage Estimation:"
+    purl_objects = sample_purls.map { |purl| Purl.parse(purl) }
+    
+    # Rough estimation based on object count and typical Ruby object overhead
+    estimated_memory = purl_objects.length * 200  # ~200 bytes per PURL object estimate
+    puts "   #{purl_objects.length} PURL objects: ~#{estimated_memory} bytes"
+    puts "   Average per object: ~200 bytes"
+    puts
+    
+    # Test different complexity levels
+    puts "🎯 Complexity Benchmarks:"
+    
+    complexity_tests = {
+      "Simple" => "pkg:gem/rails@7.0.0",
+      "With namespace" => "pkg:npm/@babel/core@7.0.0", 
+      "With qualifiers" => "pkg:cargo/rand@0.7.2?arch=x86_64&os=linux",
+      "With subpath" => "pkg:maven/org.springframework/spring-core@5.3.0#org/springframework/core/SpringVersion.class",
+      "Full complexity" => "pkg:npm/@babel/core@7.20.0?arch=x64&dev=true&os=linux#lib/parser/index.js"
+    }
+    
+    complexity_tests.each do |level, purl_string|
+      time = Benchmark.realtime do
+        1000.times { Purl.parse(purl_string) }
+      end
+      puts "   #{level.ljust(15)}: #{(time * 1000 / 1000).round(4)}ms per parse"
+    end
+    
+    puts
+    puts "✅ Benchmark completed!"
+  end
+  
+  desc "Compare parsing performance across package types"
+  task :types do
+    require "benchmark"
+    require "json"
+    require_relative "lib/purl"
+    
+    puts "📊 Package Type Parsing Comparison"
+    puts "=" * 50
+    
+    purl_types_data = JSON.parse(File.read(File.join(__dir__, "purl-types.json")))
+    
+    # Benchmark each type with its examples
+    type_benchmarks = {}
+    
+    purl_types_data["types"].each do |type_name, type_config|
+      examples = type_config["examples"]
+      next unless examples&.is_a?(Array) && examples.any?
+      
+      time = Benchmark.realtime do
+        100.times do
+          examples.each { |purl| Purl.parse(purl) }
+        end
+      end
+      
+      avg_time_per_purl = time / (100 * examples.length)
+      type_benchmarks[type_name] = {
+        time: avg_time_per_purl,
+        examples_count: examples.length
+      }
+    end
+    
+    # Sort by performance (fastest first)
+    sorted_benchmarks = type_benchmarks.sort_by { |_, data| data[:time] }
+    
+    puts "🏆 Performance Rankings (fastest to slowest):"
+    puts "   Rank Type         Avg Time/Parse  Examples"
+    puts "   " + "-" * 45
+    
+    sorted_benchmarks.each_with_index do |(type, data), index|
+      rank = (index + 1).to_s.rjust(2)
+      time_str = "#{(data[:time] * 1000).round(4)}ms".rjust(10)
+      examples_str = data[:examples_count].to_s.rjust(8)
+      
+      puts "   #{rank}.  #{type.ljust(12)} #{time_str}    #{examples_str}"
+    end
+    
+    fastest = sorted_benchmarks.first
+    slowest = sorted_benchmarks.last
+    
+    puts
+    puts "📈 Performance Summary:"
+    puts "   Fastest: #{fastest[0]} (#{(fastest[1][:time] * 1000).round(4)}ms)"
+    puts "   Slowest: #{slowest[0]} (#{(slowest[1][:time] * 1000).round(4)}ms)"
+    puts "   Ratio: #{(slowest[1][:time] / fastest[1][:time]).round(1)}x difference"
+    puts
+    puts "✅ Type comparison completed!"
+  end
+  
+  desc "Benchmark registry URL generation"
+  task :registry do
+    require "benchmark"
+    require "json"
+    require_relative "lib/purl"
+    
+    puts "🌐 Registry URL Generation Benchmarks"
+    puts "=" * 50
+    
+    # Get PURLs that support registry URL generation
+    registry_purls = []
+    Purl.registry_supported_types.each do |type|
+      examples = Purl.type_examples(type)
+      registry_purls.concat(examples) if examples.any?
+    end
+    
+    puts "📊 Testing with #{registry_purls.length} registry-supported PURLs"
+    puts
+    
+    # Parse all PURLs first
+    parsed_purls = registry_purls.map { |purl| Purl.parse(purl) }
+    
+    # Benchmark registry URL generation
+    puts "🔗 URL Generation Performance:"
+    url_time = Benchmark.realtime do
+      parsed_purls.each { |purl| purl.registry_url }
+    end
+    
+    puts "   Total time: #{(url_time * 1000).round(2)}ms"
+    puts "   Average per URL: #{(url_time * 1000 / parsed_purls.length).round(3)}ms"
+    puts "   URLs per second: #{(parsed_purls.length / url_time).round(0)}"
+    puts
+    
+    # Benchmark versioned URL generation
+    puts "🏷️  Versioned URL Performance:"
+    versioned_time = Benchmark.realtime do
+      parsed_purls.each { |purl| purl.registry_url_with_version }
+    end
+    
+    puts "   Total time: #{(versioned_time * 1000).round(2)}ms"
+    puts "   Average per URL: #{(versioned_time * 1000 / parsed_purls.length).round(3)}ms"
+    puts "   URLs per second: #{(parsed_purls.length / versioned_time).round(0)}"
+    puts
+    
+    # Compare parsing vs URL generation
+    parsing_time = Benchmark.realtime do
+      registry_purls.each { |purl| Purl.parse(purl) }
+    end
+    
+    puts "⚖️  Performance Comparison:"
+    puts "   Parsing: #{(parsing_time * 1000 / registry_purls.length).round(3)}ms per PURL"
+    puts "   URL generation: #{(url_time * 1000 / parsed_purls.length).round(3)}ms per PURL"
+    puts "   Versioned URLs: #{(versioned_time * 1000 / parsed_purls.length).round(3)}ms per PURL"
+    
+    ratio = url_time / parsing_time
+    puts "   URL gen vs parsing: #{ratio.round(2)}x #{ratio > 1 ? 'slower' : 'faster'}"
+    
+    puts
+    puts "✅ Registry URL benchmarks completed!"
+  end
+  
+  desc "Run all benchmarks"
+  task all: [:parse, :types, :registry] do
+    puts
+    puts "🎉 All benchmarks completed!"
+    puts "   Use 'rake benchmark:parse' for parsing performance"
+    puts "   Use 'rake benchmark:types' for type comparison"  
+    puts "   Use 'rake benchmark:registry' for URL generation"
+  end
+end

data/lib/purl/package_url.rb

@@ -48,8 +48,8 @@ module Purl
     # @return [String, nil] subpath within the package
     attr_reader :subpath
 
-    VALID_TYPE_CHARS = /\A[a-zA-Z0-9\.\+\-]+\z/
-    VALID_QUALIFIER_KEY_CHARS = /\A[a-zA-Z0-9\.\-_]+\z/
+    VALID_TYPE_CHARS = /\A[a-zA-Z0-9\.\+\-]+\z/.freeze
+    VALID_QUALIFIER_KEY_CHARS = /\A[a-zA-Z0-9\.\-_]+\z/.freeze
 
     # Create a new PackageURL instance
     #
@@ -107,7 +107,7 @@ module Purl
 
       # Remove the pkg: prefix and any leading slashes (they're not significant)
       remainder = purl_string[4..-1]
-      remainder = remainder.sub(/\A\/+/, "")
+      remainder = remainder.sub(/\A\/+/, "") if remainder.start_with?("/")
       
       # Split off qualifiers (query string) first
       if remainder.include?("?")
@@ -223,17 +223,17 @@ module Purl
     #   purl = PackageURL.new(type: "gem", name: "rails", version: "7.0.0")
     #   puts purl.to_s  # "pkg:gem/rails@7.0.0"
     def to_s
-      result = "pkg:#{type.downcase}"
+      parts = ["pkg:", type.downcase]
       
       if namespace
         # Encode namespace parts, but preserve the structure
         namespace_parts = namespace.split("/").map do |part|
           URI.encode_www_form_component(part)
         end
-        result += "/#{namespace_parts.join("/")}"
+        parts << "/" << namespace_parts.join("/")
       end
       
-      result += "/#{URI.encode_www_form_component(name)}"
+      parts << "/" << URI.encode_www_form_component(name)
       
       if version
         # Special handling for version encoding - don't encode colon in certain contexts
@@ -244,7 +244,7 @@ module Purl
         else
           URI.encode_www_form_component(version)
         end
-        result += "@#{encoded_version}"
+        parts << "@" << encoded_version
       end
       
       if subpath
@@ -253,7 +253,7 @@ module Purl
         normalized_subpath = self.class.normalize_subpath(subpath)
         if normalized_subpath
           subpath_parts = normalized_subpath.split("/").map { |part| URI.encode_www_form_component(part) }
-          result += "##{subpath_parts.join("/")}"
+          parts << "#" << subpath_parts.join("/")
         end
       end
       
@@ -265,10 +265,10 @@ module Purl
           encoded_value = value.to_s  # Don't encode values to match canonical form
           "#{encoded_key}=#{encoded_value}"
         end
-        result += "?#{query_parts.join("&")}"
+        parts << "?" << query_parts.join("&")
       end
       
-      result
+      parts.join
     end
 
     # Convert the PackageURL to a hash representation
@@ -532,14 +532,15 @@ module Purl
     end
 
     def validate_conan_specific_rules
-      # For conan packages, if a namespace is present WITHOUT any qualifiers, 
-      # it's ambiguous (test case 30)
-      if @namespace && (@qualifiers.nil? || (@qualifiers["user"].nil? && @qualifiers["channel"].nil?))
+      # For conan packages, if a namespace is present WITHOUT any qualifiers at all, 
+      # it's ambiguous. However, any qualifiers (including build settings) make it unambiguous.
+      # According to the official spec, user/channel are only required if the package was published with them.
+      if @namespace && (@qualifiers.nil? || @qualifiers.empty?)
         raise ValidationError.new(
-          "Conan PURLs with namespace require 'user' and/or 'channel' qualifiers to be unambiguous",
+          "Conan PURLs with namespace require qualifiers to be unambiguous",
           component: :qualifiers,
           value: @qualifiers,
-          rule: "conan packages with namespace need user/channel qualifiers"
+          rule: "conan packages with namespace need qualifiers for disambiguation"
         )
       end
       

data/lib/purl/registry_url.rb

@@ -5,7 +5,7 @@ module Purl
     # Load registry patterns from JSON configuration
     def self.load_registry_patterns
       @registry_patterns ||= begin
-        # Load JSON config directly to avoid circular dependency
+        # Load extended registry configs
         config_path = File.join(__dir__, "..", "..", "purl-types.json")
         require "json"
         config = JSON.parse(File.read(config_path))
@@ -16,37 +16,19 @@ module Purl
           next unless type_config["registry_config"]
           
           registry_config = type_config["registry_config"]
-          patterns[type] = build_pattern_config(type, registry_config)
+          patterns[type] = build_pattern_config(type, registry_config, type_config)
         end
         
         patterns
       end
     end
 
-    def self.build_pattern_config(type, config)
-      # Get the default registry for this type from parent config
-      type_config = load_types_config["types"][type]
+    def self.build_pattern_config(type, config, type_config)
+      # Get the default registry for this type from the extended config
       default_registry = type_config["default_registry"]
       
-      # Build full URLs from templates if we have a default registry
-      route_patterns = []
-      if default_registry
-        # Add all template variations
-        if config["path_template"]
-          route_patterns << default_registry + config["path_template"]
-        end
-        if config["namespace_path_template"]
-          route_patterns << default_registry + config["namespace_path_template"]
-        end
-        if config["version_path_template"]
-          route_patterns << default_registry + config["version_path_template"]
-        end
-        if config["namespace_version_path_template"]
-          route_patterns << default_registry + config["namespace_version_path_template"]
-        end
-      end
-      # Fall back to legacy route_patterns if available
-      route_patterns = config["route_patterns"] if route_patterns.empty? && config["route_patterns"]
+      # Use route_patterns directly from our extended registry config
+      route_patterns = config["route_patterns"] || []
       
       # Build reverse regex from template or use legacy format
       reverse_regex = nil

data/lib/purl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Purl
-  VERSION = "1.1.1"
+  VERSION = "1.2.0"
 end