purl 1.0.0 → 1.1.1

data/lib/purl/registry_url.rb

@@ -24,29 +24,85 @@ module Purl
     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]
+      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"]
+      
+      # Build reverse regex from template or use legacy format
+      reverse_regex = nil
+      if config["reverse_regex"]
+        if config["reverse_regex"].start_with?("/") && default_registry
+          # Domain-agnostic pattern - combine with default registry domain
+          domain_pattern = default_registry.sub(/^https?:\/\//, '').gsub('.', '\\.')
+          reverse_regex = Regexp.new("^https?://#{domain_pattern}" + config["reverse_regex"])
+        else
+          # Legacy full pattern
+          reverse_regex = Regexp.new(config["reverse_regex"])
+        end
+      end
+      
       {
-        base_url: config["base_url"],
-        route_patterns: config["route_patterns"] || [],
-        reverse_regex: config["reverse_regex"] ? Regexp.new(config["reverse_regex"]) : nil,
-        pattern: build_generation_lambda(type, config),
-        reverse_parser: config["reverse_regex"] ? build_reverse_parser(type, config) : nil
+        base_url: config["base_url"] || (default_registry ? default_registry + config["path_template"]&.split('/:').first : nil),
+        route_patterns: route_patterns,
+        reverse_regex: reverse_regex,
+        pattern: build_generation_lambda(type, config, default_registry),
+        reverse_parser: reverse_regex ? build_reverse_parser(type, config) : nil
       }
     end
 
-    def self.build_generation_lambda(type, config)
+    # Load types config (needed for accessing default_registry)
+    def self.load_types_config
+      @types_config ||= begin
+        config_path = File.join(__dir__, "..", "..", "purl-types.json")
+        require "json"
+        JSON.parse(File.read(config_path))
+      end
+    end
+
+    def self.build_generation_lambda(type, config, default_registry = nil)
+      # Use base_url from config, or build from default_registry + path_template base
+      if config["base_url"]
+        base_url = config["base_url"]
+      elsif default_registry && config["path_template"]
+        # Extract the base path from the template (everything before first :parameter)
+        base_path = config["path_template"].split('/:').first
+        base_url = default_registry + base_path
+      else
+        return nil
+      end
       case type
       when "npm"
         ->(purl) do
           if purl.namespace
-            "#{config["base_url"]}/#{purl.namespace}/#{purl.name}"
+            "#{base_url}/#{purl.namespace}/#{purl.name}"
           else
-            "#{config["base_url"]}/#{purl.name}"
+            "#{base_url}/#{purl.name}"
           end
         end
       when "composer", "maven", "swift"
         ->(purl) do
           if purl.namespace
-            "#{config["base_url"]}/#{purl.namespace}/#{purl.name}"
+            "#{base_url}/#{purl.namespace}/#{purl.name}"
           else
             raise MissingRegistryInfoError.new(
               "#{type.capitalize} packages require a namespace",
@@ -58,42 +114,42 @@ module Purl
       when "golang"
         ->(purl) do
           if purl.namespace
-            "#{config["base_url"]}/#{purl.namespace}/#{purl.name}"
+            "#{base_url}/#{purl.namespace}/#{purl.name}"
           else
-            "#{config["base_url"]}/#{purl.name}"
+            "#{base_url}/#{purl.name}"
           end
         end
       when "pypi"
-        ->(purl) { "#{config["base_url"]}/#{purl.name}/" }
+        ->(purl) { "#{base_url}/#{purl.name}/" }
       when "hackage"
         ->(purl) do
           if purl.version
-            "#{config["base_url"]}/#{purl.name}-#{purl.version}"
+            "#{base_url}/#{purl.name}-#{purl.version}"
           else
-            "#{config["base_url"]}/#{purl.name}"
+            "#{base_url}/#{purl.name}"
           end
         end
       when "deno"
         ->(purl) do
           if purl.version
-            "#{config["base_url"]}/#{purl.name}@#{purl.version}"
+            "#{base_url}/#{purl.name}@#{purl.version}"
           else
-            "#{config["base_url"]}/#{purl.name}"
+            "#{base_url}/#{purl.name}"
           end
         end
       when "clojars"
         ->(purl) do
           if purl.namespace
-            "#{config["base_url"]}/#{purl.namespace}/#{purl.name}"
+            "#{base_url}/#{purl.namespace}/#{purl.name}"
           else
-            "#{config["base_url"]}/#{purl.name}"
+            "#{base_url}/#{purl.name}"
           end
         end
       when "elm"
         ->(purl) do
           if purl.namespace
             version = purl.version || "latest"
-            "#{config["base_url"]}/#{purl.namespace}/#{purl.name}/#{version}"
+            "#{base_url}/#{purl.namespace}/#{purl.name}/#{version}"
           else
             raise MissingRegistryInfoError.new(
               "Elm packages require a namespace",
@@ -103,7 +159,7 @@ module Purl
           end
         end
       else
-        ->(purl) { "#{config["base_url"]}/#{purl.name}" }
+        ->(purl) { "#{base_url}/#{purl.name}" }
       end
     end
 
@@ -177,6 +233,67 @@ module Purl
           version = match[3] unless match[3] == "latest"
           { type: type, namespace: namespace, name: name, version: version }
         end
+      when "cocoapods"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "composer"
+        ->(match) do
+          namespace = match[1]
+          name = match[2]
+          { type: type, namespace: namespace, name: name, version: nil }
+        end
+      when "conda"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "cpan"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "hex"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "nuget"
+        ->(match) do
+          name = match[1]
+          version = match[2] # from /version pattern
+          { type: type, namespace: nil, name: name, version: version }
+        end
+      when "pub"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "swift"
+        ->(match) do
+          namespace = match[1]
+          name = match[2]
+          { type: type, namespace: namespace, name: name, version: nil }
+        end
+      when "bioconductor"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "clojars"
+        ->(match) do
+          if match[1] && match[2]
+            # Has namespace: clojars.org/namespace/name
+            namespace = match[1]
+            name = match[2]
+          else
+            # No namespace: clojars.org/name
+            namespace = nil
+            name = match[1] || match[2]
+          end
+          { type: type, namespace: namespace, name: name, version: nil }
+        end
       else
         ->(match) do
           { type: type, namespace: nil, name: match[1], version: nil }
@@ -187,8 +304,8 @@ module Purl
     # Registry patterns loaded from JSON configuration
     REGISTRY_PATTERNS = load_registry_patterns.freeze
 
-    def self.generate(purl)
-      new(purl).generate
+    def self.generate(purl, base_url: nil)
+      new(purl).generate(base_url: base_url)
     end
 
     def self.supported_types
@@ -199,9 +316,49 @@ module Purl
       REGISTRY_PATTERNS.key?(type.to_s.downcase)
     end
 
-    def self.from_url(registry_url)
-      # Try to parse the registry URL back into a PURL
-      REGISTRY_PATTERNS.each do |type, config|
+    def self.from_url(registry_url, type: nil)
+      # If type is specified, try that specific type first with domain-agnostic parsing
+      if type
+        normalized_type = type.to_s.downcase
+        config = REGISTRY_PATTERNS[normalized_type]
+        
+        if config && config[:reverse_regex] && config[:reverse_parser]
+          # Create a domain-agnostic version of the regex by replacing the base domain
+          original_regex = config[:reverse_regex].source
+          
+          # For simplified JSON patterns that start with /, create domain-agnostic regex
+          domain_agnostic_regex = nil
+          if original_regex.start_with?("/")
+            # Domain-agnostic pattern - match any domain with this path
+            domain_agnostic_regex = Regexp.new("^https?://[^/]+" + original_regex)
+          else
+            # Legacy full regex pattern
+            if original_regex =~ /\^https?:\/\/[^\/]+(.+)$/
+              path_pattern = $1
+              # Create domain-agnostic regex that matches any domain with the same path structure
+              domain_agnostic_regex = Regexp.new("^https?://[^/]+" + path_pattern)
+            end
+          end
+            
+          if domain_agnostic_regex
+            match = registry_url.match(domain_agnostic_regex)
+            if match
+              parsed_data = config[:reverse_parser].call(match)
+              return PackageURL.new(
+                type: parsed_data[:type],
+                namespace: parsed_data[:namespace],
+                name: parsed_data[:name],
+                version: parsed_data[:version]
+              )
+            end
+          end
+        end
+        
+        # If specified type didn't work, fall through to normal domain-matching logic
+      end
+      
+      # Try to parse the registry URL back into a PURL using domain matching
+      REGISTRY_PATTERNS.each do |registry_type, config|
         next unless config[:reverse_regex] && config[:reverse_parser]
         
         match = registry_url.match(config[:reverse_regex])
@@ -216,8 +373,15 @@ module Purl
         end
       end
       
+      error_message = if type
+        "Unable to parse registry URL: #{registry_url} as type '#{type}'. " +
+        "URL structure doesn't match expected pattern for this type."
+      else
+        "Unable to parse registry URL: #{registry_url}. No matching pattern found."
+      end
+      
       raise UnsupportedTypeError.new(
-        "Unable to parse registry URL: #{registry_url}. No matching pattern found.",
+        error_message,
         supported_types: REGISTRY_PATTERNS.keys.select { |k| REGISTRY_PATTERNS[k][:reverse_regex] }
       )
     end
@@ -247,7 +411,7 @@ module Purl
       @purl = purl
     end
 
-    def generate
+    def generate(base_url: nil)
       pattern_config = REGISTRY_PATTERNS[@purl.type.downcase]
       
       unless pattern_config
@@ -259,7 +423,13 @@ module Purl
       end
 
       begin
-        pattern_config[:pattern].call(@purl)
+        if base_url
+          # Use custom base URL with the same URL structure
+          generate_with_custom_base_url(base_url, pattern_config)
+        else
+          # Use default base URL
+          pattern_config[:pattern].call(@purl)
+        end
       rescue MissingRegistryInfoError
         raise
       rescue => e
@@ -267,23 +437,87 @@ module Purl
       end
     end
 
-    def generate_with_version
-      base_url = generate
+    def generate_with_version(base_url: nil)
+      registry_url = generate(base_url: base_url)
       
       case @purl.type.downcase
       when "npm"
-        @purl.version ? "#{base_url}/v/#{@purl.version}" : base_url
+        @purl.version ? "#{registry_url}/v/#{@purl.version}" : registry_url
       when "pypi"
-        @purl.version ? "#{base_url}#{@purl.version}/" : base_url
+        @purl.version ? "#{registry_url}#{@purl.version}/" : registry_url
       when "gem"
-        @purl.version ? "#{base_url}/versions/#{@purl.version}" : base_url
+        @purl.version ? "#{registry_url}/versions/#{@purl.version}" : registry_url
       when "maven"
-        @purl.version ? "#{base_url}/#{@purl.version}" : base_url
+        @purl.version ? "#{registry_url}/#{@purl.version}" : registry_url
       when "nuget"
-        @purl.version ? "#{base_url}/#{@purl.version}" : base_url
+        @purl.version ? "#{registry_url}/#{@purl.version}" : registry_url
       else
         # For other types, just return the base URL since version-specific URLs vary
-        base_url
+        registry_url
+      end
+    end
+
+    private
+
+    def generate_with_custom_base_url(custom_base_url, pattern_config)
+      
+      # Replace the base URL in the pattern lambda
+      case @purl.type.downcase
+      when "npm"
+        if @purl.namespace
+          "#{custom_base_url}/#{@purl.namespace}/#{@purl.name}"
+        else
+          "#{custom_base_url}/#{@purl.name}"
+        end
+      when "composer", "maven", "swift"
+        if @purl.namespace
+          "#{custom_base_url}/#{@purl.namespace}/#{@purl.name}"
+        else
+          raise MissingRegistryInfoError.new(
+            "#{@purl.type.capitalize} packages require a namespace",
+            type: @purl.type,
+            missing: "namespace"
+          )
+        end
+      when "golang"
+        if @purl.namespace
+          "#{custom_base_url}/#{@purl.namespace}/#{@purl.name}"
+        else
+          "#{custom_base_url}/#{@purl.name}"
+        end
+      when "pypi"
+        "#{custom_base_url}/#{@purl.name}/"
+      when "hackage"
+        if @purl.version
+          "#{custom_base_url}/#{@purl.name}-#{@purl.version}"
+        else
+          "#{custom_base_url}/#{@purl.name}"
+        end
+      when "deno"
+        if @purl.version
+          "#{custom_base_url}/#{@purl.name}@#{@purl.version}"
+        else
+          "#{custom_base_url}/#{@purl.name}"
+        end
+      when "clojars"
+        if @purl.namespace
+          "#{custom_base_url}/#{@purl.namespace}/#{@purl.name}"
+        else
+          "#{custom_base_url}/#{@purl.name}"
+        end
+      when "elm"
+        if @purl.namespace
+          version = @purl.version || "latest"
+          "#{custom_base_url}/#{@purl.namespace}/#{@purl.name}/#{version}"
+        else
+          raise MissingRegistryInfoError.new(
+            "Elm packages require a namespace",
+            type: @purl.type,
+            missing: "namespace"
+          )
+        end
+      else
+        "#{custom_base_url}/#{@purl.name}"
       end
     end
 
@@ -294,12 +528,12 @@ module Purl
 
   # Add registry URL generation methods to PackageURL
   class PackageURL
-    def registry_url
-      RegistryURL.generate(self)
+    def registry_url(base_url: nil)
+      RegistryURL.generate(self, base_url: base_url)
     end
 
-    def registry_url_with_version
-      RegistryURL.new(self).generate_with_version
+    def registry_url_with_version(base_url: nil)
+      RegistryURL.new(self).generate_with_version(base_url: base_url)
     end
 
     def supports_registry_url?

data/lib/purl/version.rb

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

data/lib/purl.rb

@@ -5,7 +5,25 @@ require_relative "purl/errors"
 require_relative "purl/package_url"
 require_relative "purl/registry_url"
 
+# The main PURL (Package URL) module providing functionality to parse,
+# validate, and generate package URLs according to the PURL specification.
+#
+# A Package URL is a mostly universal standard to reference a software package
+# in a uniform way across many tools, programming languages and ecosystems.
+#
+# @example Basic usage
+#   purl = Purl.parse("pkg:gem/rails@7.0.0")
+#   puts purl.type     # "gem"
+#   puts purl.name     # "rails"
+#   puts purl.version  # "7.0.0"
+#
+# @example Registry URL conversion
+#   purl = Purl.from_registry_url("https://rubygems.org/gems/rails")
+#   puts purl.to_s     # "pkg:gem/rails"
+#
+# @see https://github.com/package-url/purl-spec PURL Specification
 module Purl
+  # Base error class for all PURL-related errors
   class Error < StandardError; end
   
   # Load PURL types configuration from JSON file
@@ -21,41 +39,95 @@ module Purl
   KNOWN_TYPES = load_types_config["types"].keys.sort.freeze
   
   # Convenience method for parsing PURL strings
+  #
+  # @param purl_string [String] a PURL string starting with "pkg:"
+  # @return [PackageURL] parsed package URL object
+  # @raise [InvalidSchemeError] if string doesn't start with "pkg:"
+  # @raise [MalformedUrlError] if string is malformed
+  #
+  # @example
+  #   purl = Purl.parse("pkg:gem/rails@7.0.0")
+  #   puts purl.name  # "rails"
   def self.parse(purl_string)
     PackageURL.parse(purl_string)
   end
 
   # Convenience method for parsing registry URLs back to PURLs
-  def self.from_registry_url(registry_url)
-    RegistryURL.from_url(registry_url)
+  # @param registry_url [String] The registry URL to parse
+  # @param type [String, Symbol, nil] Optional type hint for custom domains
+  def self.from_registry_url(registry_url, type: nil)
+    RegistryURL.from_url(registry_url, type: type)
   end
 
   # Returns all known PURL types
+  #
+  # @return [Array<String>] sorted array of known PURL type names
+  #
+  # @example
+  #   types = Purl.known_types
+  #   puts types.include?("gem")  # true
   def self.known_types
     KNOWN_TYPES.dup
   end
 
   # Returns types that have registry URL support
+  #
+  # @return [Array<String>] sorted array of types that can generate registry URLs
+  #
+  # @example
+  #   types = Purl.registry_supported_types
+  #   puts types.include?("npm")  # true if npm has registry support
   def self.registry_supported_types
     RegistryURL.supported_types
   end
 
   # Returns types that support reverse parsing from registry URLs
+  #
+  # @return [Array<String>] sorted array of types that can parse registry URLs back to PURLs
+  #
+  # @example
+  #   types = Purl.reverse_parsing_supported_types
+  #   puts types.include?("gem")  # true if gem has reverse parsing support
   def self.reverse_parsing_supported_types
     RegistryURL.supported_reverse_types
   end
 
   # Check if a type is known/valid
+  #
+  # @param type [String, Symbol] the type to check
+  # @return [Boolean] true if type is known, false otherwise
+  #
+  # @example
+  #   Purl.known_type?("gem")     # true
+  #   Purl.known_type?("unknown") # false
   def self.known_type?(type)
     KNOWN_TYPES.include?(type.to_s.downcase)
   end
 
-  # Get type information including registry support
+  # Get comprehensive type information including registry support
+  #
+  # @param type [String, Symbol] the type to get information for
+  # @return [Hash] hash containing type information with keys:
+  #   - +:type+: normalized type name
+  #   - +:known+: whether type is known
+  #   - +:description+: human-readable description
+  #   - +:default_registry+: default registry URL
+  #   - +:examples+: array of example PURLs
+  #   - +:registry_url_generation+: whether registry URL generation is supported
+  #   - +:reverse_parsing+: whether reverse parsing is supported
+  #   - +:route_patterns+: array of URL patterns for this type
+  #
+  # @example
+  #   info = Purl.type_info("gem")
+  #   puts info[:description]  # "Ruby gems from RubyGems.org"
   def self.type_info(type)
     normalized_type = type.to_s.downcase
     {
       type: normalized_type,
       known: known_type?(normalized_type),
+      description: type_description(normalized_type),
+      default_registry: default_registry(normalized_type),
+      examples: type_examples(normalized_type),
       registry_url_generation: RegistryURL.supports?(normalized_type),
       reverse_parsing: RegistryURL.supported_reverse_types.include?(normalized_type),
       route_patterns: RegistryURL.route_patterns_for(normalized_type)
@@ -63,6 +135,13 @@ module Purl
   end
 
   # Get comprehensive information about all types
+  #
+  # @return [Hash<String, Hash>] hash mapping type names to their information
+  # @see #type_info for structure of individual type information
+  #
+  # @example
+  #   all_info = Purl.all_type_info
+  #   gem_info = all_info["gem"]
   def self.all_type_info
     result = {}
     
@@ -82,6 +161,10 @@ module Purl
   end
 
   # Get type configuration from JSON
+  #
+  # @param type [String, Symbol] the type to get configuration for
+  # @return [Hash, nil] configuration hash or nil if type not found
+  # @api private
   def self.type_config(type)
     config = load_types_config["types"][type.to_s.downcase]
     return nil unless config
@@ -89,13 +172,39 @@ module Purl
     config.dup # Return a copy to prevent modification
   end
 
-  # Get description for a type
+  # Get human-readable description for a type
+  #
+  # @param type [String, Symbol] the type to get description for
+  # @return [String, nil] description string or nil if not available
+  #
+  # @example
+  #   desc = Purl.type_description("gem")
+  #   puts desc  # "Ruby gems from RubyGems.org"
   def self.type_description(type)
     config = type_config(type)
     config ? config["description"] : nil
   end
 
+  # Get example PURLs for a type
+  #
+  # @param type [String, Symbol] the type to get examples for
+  # @return [Array<String>] array of example PURL strings
+  #
+  # @example
+  #   examples = Purl.type_examples("gem")
+  #   puts examples.first  # "pkg:gem/rails@7.0.0"
+  def self.type_examples(type)
+    config = type_config(type)
+    return [] unless config
+    
+    config["examples"] || []
+  end
+
   # Get registry configuration for a type
+  #
+  # @param type [String, Symbol] the type to get registry config for
+  # @return [Hash, nil] registry configuration hash or nil if not available
+  # @api private
   def self.registry_config(type)
     config = type_config(type)
     return nil unless config
@@ -103,7 +212,35 @@ module Purl
     config["registry_config"]
   end
 
+  # Get default registry URL for a type
+  #
+  # @param type [String, Symbol] the type to get default registry for
+  # @return [String, nil] default registry URL or nil if not available
+  #
+  # @example
+  #   registry = Purl.default_registry("gem")
+  #   puts registry  # "https://rubygems.org"
+  def self.default_registry(type)
+    config = type_config(type)
+    return nil unless config
+    
+    config["default_registry"]
+  end
+
   # Get metadata about the types configuration
+  #
+  # @return [Hash] metadata hash with keys:
+  #   - +:version+: configuration version
+  #   - +:description+: configuration description
+  #   - +:source+: source of the configuration
+  #   - +:last_updated+: when configuration was last updated
+  #   - +:total_types+: total number of types
+  #   - +:registry_supported_types+: number of types with registry support
+  #   - +:types_with_default_registry+: number of types with default registry
+  #
+  # @example
+  #   metadata = Purl.types_config_metadata
+  #   puts "Total types: #{metadata[:total_types]}"
   def self.types_config_metadata
     config = load_types_config
     {
@@ -112,7 +249,8 @@ module Purl
       source: config["source"],
       last_updated: config["last_updated"],
       total_types: config["types"].keys.length,
-      registry_supported_types: config["types"].select { |_, v| v["registry_config"] }.keys.length
+      registry_supported_types: config["types"].select { |_, v| v["registry_config"] }.keys.length,
+      types_with_default_registry: config["types"].select { |_, v| v["default_registry"] }.keys.length
     }
   end
 end