purl 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25661f74cff7bd498cd8b82d64887231cd1a576b8ce0ef59c5397c6d378759eb
-  data.tar.gz: 0e82bbe5c1600601b3f27a82c79d9ea579587961ae97df1f1272ce31da35877e
+  metadata.gz: ae14d9c24e0b1f4f8d76b97c59ed34d8e34090d5329ac9358bf40be4e4acdf14
+  data.tar.gz: 4ff6fa43fd388006d553bae72b4685ef228cff186b135ec335d7a6b724abb034
 SHA512:
-  metadata.gz: d95b6ca47f39eccb13394340e6a63a9acfa9c0efc8a031897e876fe0350e354ae1d1e4f45f747463e14e1060b89e455e03e3dcbedcefca3a99522fe4f4b54fa1
-  data.tar.gz: 3e5322963a75161291bead8050759a0578c07c8e2b8a732a6a3ca7180b0ffa5a099a63f9cb95785e9dcc42674f1933b10aa6acc9450f4e30ec8f233aa9bb6983
+  metadata.gz: 5f965309ce3f2dddc29065c247082f11541a8ead617c2ad398a7dbd71affd6417e7f09959d88ea59492256dec7039b458507688da9288723bda2d83942f6683f
+  data.tar.gz: eb9fd5d72ba8a6c40cafe9c736594f76d20ea40e1886af1693d54dbb36b1ba1105ed05b415b6989098b7288df79a6e9f3c3ddb7aa095eb6dad069a7755374f39

data/README.md

@@ -8,7 +8,7 @@ This library features comprehensive error handling with namespaced error types,
 [![Gem Version](https://badge.fury.io/rb/purl.svg)](https://rubygems.org/gems/purl)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**[Available on RubyGems](https://rubygems.org/gems/purl)**
+**[Available on RubyGems](https://rubygems.org/gems/purl)** | **[API Documentation](https://rdoc.info/github/andrew/purl)**
 
 ## Features
 

data/Rakefile

@@ -2,9 +2,20 @@
 
 require "bundler/gem_tasks"
 require "minitest/test_task"
+require "rdoc/task"
 
 Minitest::TestTask.create
 
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = "doc"
+  rdoc.title = "PURL - Package URL Library"
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
+  rdoc.options << "--line-numbers"
+  rdoc.options << "--all"
+  rdoc.options << "--charset=UTF-8"
+end
+
 task default: :test
 
 namespace :spec do
@@ -396,7 +407,14 @@ namespace :spec do
   desc "Validate JSON files against their schemas"
   task :validate_schemas do
     require "json"
-    require "json-schema"
+    
+    begin
+      require "json-schema"
+    rescue LoadError => e
+      puts "❌ json-schema gem not available: #{e.message}"
+      puts "   Install with: gem install json-schema"
+      exit 1
+    end
     
     puts "🔍 Validating JSON files against schemas..."
     puts "=" * 50

data/lib/purl/errors.rb

@@ -5,9 +5,31 @@ module Purl
   class Error < StandardError; end
 
   # Validation errors for PURL components
+  #
+  # Contains additional context about which component failed validation
+  # and what rule was violated.
+  #
+  # @example
+  #   begin
+  #     PackageURL.new(type: "123invalid", name: "test")
+  #   rescue ValidationError => e
+  #     puts e.component  # :type
+  #     puts e.rule       # "cannot start with number" 
+  #   end
   class ValidationError < Error
-    attr_reader :component, :value, :rule
+    # @return [Symbol, nil] the PURL component that failed validation
+    attr_reader :component
+    
+    # @return [Object, nil] the value that failed validation
+    attr_reader :value
+    
+    # @return [String, nil] the validation rule that was violated
+    attr_reader :rule
 
+    # @param message [String] error message
+    # @param component [Symbol, nil] component that failed validation
+    # @param value [Object, nil] value that failed validation  
+    # @param rule [String, nil] validation rule that was violated
     def initialize(message, component: nil, value: nil, rule: nil)
       super(message)
       @component = component
@@ -19,40 +41,71 @@ module Purl
   # Parsing errors for malformed PURL strings
   class ParseError < Error; end
 
-  # Specific validation errors
+  # Specific validation errors for PURL components
+  
+  # Raised when a PURL type is invalid
   class InvalidTypeError < ValidationError; end
+  
+  # Raised when a PURL name is invalid
   class InvalidNameError < ValidationError; end
+  
+  # Raised when a PURL namespace is invalid
   class InvalidNamespaceError < ValidationError; end
+  
+  # Raised when a PURL qualifier is invalid
   class InvalidQualifierError < ValidationError; end
+  
+  # Raised when a PURL version is invalid
   class InvalidVersionError < ValidationError; end
+  
+  # Raised when a PURL subpath is invalid
   class InvalidSubpathError < ValidationError; end
 
   # Parsing-specific errors
+  
+  # Raised when a PURL string doesn't start with "pkg:"
   class InvalidSchemeError < ParseError; end
+  
+  # Raised when a PURL string is malformed
   class MalformedUrlError < ParseError; end
 
   # Registry URL generation errors
+  #
+  # Contains additional context about which type caused the error.
   class RegistryError < Error
+    # @return [String, nil] the PURL type that caused the error
     attr_reader :type
 
+    # @param message [String] error message
+    # @param type [String, nil] PURL type that caused the error
     def initialize(message, type: nil)
       super(message)
       @type = type
     end
   end
 
+  # Raised when trying to generate registry URLs for unsupported types
   class UnsupportedTypeError < RegistryError
+    # @return [Array<String>] list of supported types
     attr_reader :supported_types
 
+    # @param message [String] error message
+    # @param type [String, nil] unsupported type
+    # @param supported_types [Array<String>] list of supported types
     def initialize(message, type: nil, supported_types: [])
       super(message, type: type)
       @supported_types = supported_types
     end
   end
 
+  # Raised when required registry information is missing
   class MissingRegistryInfoError < RegistryError
+    # @return [String, nil] the missing information (e.g., "namespace")
     attr_reader :missing
 
+    # @param message [String] error message
+    # @param type [String, nil] PURL type
+    # @param missing [String, nil] what information is missing
     def initialize(message, type: nil, missing: nil)
       super(message, type: type)
       @missing = missing
@@ -60,5 +113,6 @@ module Purl
   end
 
   # Legacy compatibility - matches packageurl-ruby's exception name
+  # @deprecated Use {ParseError} instead
   InvalidPackageURL = ParseError
 end

data/lib/purl/package_url.rb

@@ -3,12 +3,74 @@
 require "uri"
 
 module Purl
+  # Represents a Package URL (PURL) - a mostly universal standard to reference 
+  # a software package in a uniform way across many tools, programming languages
+  # and ecosystems.
+  #
+  # A PURL has the following components:
+  # - +type+: the package type (e.g., "gem", "npm", "maven")
+  # - +namespace+: optional namespace/scope (e.g., "@babel" for npm)
+  # - +name+: the package name (required)
+  # - +version+: optional version
+  # - +qualifiers+: optional key-value pairs
+  # - +subpath+: optional path within the package
+  #
+  # @example Creating a PackageURL
+  #   purl = PackageURL.new(
+  #     type: "gem",
+  #     name: "rails", 
+  #     version: "7.0.0"
+  #   )
+  #   puts purl.to_s  # "pkg:gem/rails@7.0.0"
+  #
+  # @example Parsing a PURL string
+  #   purl = PackageURL.parse("pkg:npm/@babel/core@7.0.0")
+  #   puts purl.namespace  # "@babel"
+  #   puts purl.name       # "core"
+  #
+  # @see https://github.com/package-url/purl-spec PURL Specification
   class PackageURL
-    attr_reader :type, :namespace, :name, :version, :qualifiers, :subpath
+    # @return [String] the package type (e.g., "gem", "npm", "maven")
+    attr_reader :type
+    
+    # @return [String, nil] the package namespace/scope
+    attr_reader :namespace
+    
+    # @return [String] the package name
+    attr_reader :name
+    
+    # @return [String, nil] the package version
+    attr_reader :version
+    
+    # @return [Hash<String, String>, nil] key-value qualifier pairs
+    attr_reader :qualifiers
+    
+    # @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/
 
+    # Create a new PackageURL instance
+    #
+    # @param type [String, Symbol] the package type (required)
+    # @param name [String] the package name (required)
+    # @param namespace [String, nil] optional namespace/scope
+    # @param version [String, nil] optional version
+    # @param qualifiers [Hash, nil] optional key-value qualifier pairs
+    # @param subpath [String, nil] optional subpath within package
+    #
+    # @raise [InvalidTypeError] if type is invalid
+    # @raise [InvalidNameError] if name is invalid
+    # @raise [ValidationError] if any component fails type-specific validation
+    #
+    # @example
+    #   purl = PackageURL.new(
+    #     type: "npm",
+    #     namespace: "@babel",
+    #     name: "core",
+    #     version: "7.0.0"
+    #   )
     def initialize(type:, name:, namespace: nil, version: nil, qualifiers: nil, subpath: nil)
       @type = validate_and_normalize_type(type)
       @name = validate_name(name)
@@ -21,6 +83,25 @@ module Purl
       validate_type_specific_rules
     end
 
+    # Parse a PURL string into a PackageURL object
+    #
+    # @param purl_string [String] 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
+    # @raise [ValidationError] if parsed components fail validation
+    #
+    # @example Basic parsing
+    #   purl = PackageURL.parse("pkg:gem/rails@7.0.0")
+    #   puts purl.type     # "gem"
+    #   puts purl.name     # "rails"
+    #   puts purl.version  # "7.0.0"
+    #
+    # @example Complex parsing with all components
+    #   purl = PackageURL.parse("pkg:npm/@babel/core@7.0.0?arch=x64#lib/index.js")
+    #   puts purl.namespace   # "@babel"
+    #   puts purl.qualifiers  # {"arch" => "x64"}
+    #   puts purl.subpath     # "lib/index.js"
     def self.parse(purl_string)
       raise InvalidSchemeError, "PURL must start with 'pkg:'" unless purl_string.start_with?("pkg:")
 
@@ -134,6 +215,13 @@ module Purl
       )
     end
 
+    # Convert the PackageURL to its canonical string representation
+    #
+    # @return [String] canonical PURL string
+    #
+    # @example
+    #   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}"
       
@@ -183,6 +271,15 @@ module Purl
       result
     end
 
+    # Convert the PackageURL to a hash representation
+    #
+    # @return [Hash<Symbol, Object>] hash with component keys and values
+    #
+    # @example
+    #   purl = PackageURL.new(type: "gem", name: "rails", version: "7.0.0")
+    #   hash = purl.to_h
+    #   # => {:type=>"gem", :namespace=>nil, :name=>"rails", :version=>"7.0.0", 
+    #   #     :qualifiers=>nil, :subpath=>nil}
     def to_h
       {
         type: type,
@@ -194,28 +291,69 @@ module Purl
       }
     end
 
+    # Compare two PackageURL objects for equality
+    #
+    # Two PURLs are equal if their canonical string representations are identical.
+    #
+    # @param other [Object] object to compare with
+    # @return [Boolean] true if equal, false otherwise
+    #
+    # @example
+    #   purl1 = PackageURL.parse("pkg:gem/rails@7.0.0")
+    #   purl2 = PackageURL.parse("pkg:gem/rails@7.0.0")
+    #   puts purl1 == purl2  # true
     def ==(other)
       return false unless other.is_a?(PackageURL)
       
       to_s == other.to_s
     end
 
+    # Generate hash code for the PackageURL
+    #
+    # @return [Integer] hash code based on canonical string representation
     def hash
       to_s.hash
     end
 
     # Pattern matching support for Ruby 2.7+
+    #
+    # Allows destructuring PackageURL in pattern matching.
+    #
+    # @return [Array] array of [type, namespace, name, version, qualifiers, subpath]
+    #
+    # @example Ruby 2.7+ pattern matching
+    #   case purl
+    #   in ["gem", nil, name, version, nil, nil]
+    #     puts "Simple gem: #{name} v#{version}"
+    #   end
     def deconstruct
       [type, namespace, name, version, qualifiers, subpath]
     end
 
+    # Pattern matching support for Ruby 2.7+ (hash patterns)
+    #
+    # @param keys [Array<Symbol>, nil] keys to extract, or nil for all keys
+    # @return [Hash<Symbol, Object>] hash with requested keys
+    #
+    # @example Ruby 2.7+ hash pattern matching
+    #   case purl
+    #   in {type: "gem", name:, version:}
+    #     puts "Gem #{name} version #{version}"
+    #   end
     def deconstruct_keys(keys)
       return to_h.slice(*keys) if keys
       to_h
     end
 
     # Create a new PackageURL with modified attributes
-    # Usage: new_purl = purl.with(version: "2.0.0", qualifiers: {"arch" => "x64"})
+    #
+    # @param changes [Hash] attributes to change
+    # @return [PackageURL] new PackageURL instance with changes applied
+    #
+    # @example
+    #   purl = PackageURL.parse("pkg:gem/rails@7.0.0")
+    #   new_purl = purl.with(version: "7.1.0", qualifiers: {"arch" => "x64"})
+    #   puts new_purl.to_s  # "pkg:gem/rails@7.1.0?arch=x64"
     def with(**changes)
       current_attrs = to_h
       new_attrs = current_attrs.merge(changes)

data/lib/purl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Purl
-  VERSION = "1.1.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,6 +39,15 @@ 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
@@ -33,26 +60,66 @@ module Purl
   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
     {
@@ -68,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 = {}
     
@@ -87,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
@@ -94,13 +172,27 @@ 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 examples for a type
+  # 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
@@ -109,6 +201,10 @@ module Purl
   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
@@ -117,6 +213,13 @@ module Purl
   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
@@ -125,6 +228,19 @@ module Purl
   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
     {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: purl
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Andrew Nesbitt