purl 1.3.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c6c3fd2d17a4601a4c296b18ce67d41c423a5893aeb2b79cd484c0028863abd
-  data.tar.gz: 2c5e92ca69e3bb8442df158f34944fad645319cdbac5fb45875c7c8521be5d0c
+  metadata.gz: f5be58ada7f5731a371cee07f0175e020aa7a49ea7d228c88e1af4c2554d5ecc
+  data.tar.gz: 96e6ff76c5626c4c414651324eee74c4845e4fb337b93470dc534d49622facfc
 SHA512:
-  metadata.gz: 34e7c52f43f92146d605e06338f25b5d12f80f495e320901aed32206dc3e743029be9b51eb5bcd1f84ef46ca450a76ac45fa7c74da5b2506eb3d53b82db6c840
-  data.tar.gz: 7941f3f3cb65695448599c590e75ef06198fdafe4739e7587e0f7518f6e58fc948896452c38136a3c1a1e6e0d52acac4b766c2a5f2dd22d0a33f8b2e1b61feb1
+  metadata.gz: adfb3b0b945ad8787738388c3b40087ae662974ba60ff3783100ba845c8e19e8fc73c4480b3296a5df701080af31919dbea66d0c5d3803ec29e18a098da0d837
+  data.tar.gz: a96abd807ede7d4c6eaff1cb0bdd6bacdfc8723e3dad839f17ecbc7b3502edb9b24e2f32f84fec3b3c100e7ec5cd3a940229fc6421f964c9927fc370587948a3

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2025-08-06
+
+### Added
+- `versionless` convenience method to create a PackageURL without version component
+- `lookup` command to CLI for fetching package information from ecosyste.ms API with version-specific details
+- `Purl::Lookup` class for programmatic package information lookup
+- `lookup` instance method on `PackageURL` for convenient package information retrieval
+- `Purl::LookupFormatter` class for customizable lookup result formatting
+- Package maintainer information display in lookup results
+
+## [1.4.0] - 2025-01-06
+
+### Added
+- Command-line interface with parse, validate, convert, url, generate, and info commands plus JSON output support
+
 ## [1.3.1] - 2025-08-04
 
 ### Fixed

data/README.md

@@ -16,6 +16,7 @@ This library features comprehensive error handling with namespaced error types,
 
 ## Features
 
+- **Command-line interface** with parse, validate, convert, generate, and info commands plus JSON output
 - **Comprehensive PURL parsing and validation** with 37 package types (32 official + 5 additional ecosystems)
 - **Better error handling** with namespaced error classes and contextual information
 - **Bidirectional registry URL conversion** - generate registry URLs from PURLs and parse PURLs from registry URLs
@@ -46,7 +47,175 @@ Or install it yourself as:
 gem install purl
 ```
 
-## Usage
+## Command Line Interface
+
+The purl gem includes a command-line interface that provides convenient access to all parsing, validation, conversion, and generation functionality.
+
+### Installation
+
+The CLI is automatically available after installing the gem:
+
+```bash
+gem install purl
+purl --help
+```
+
+### Available Commands
+
+```bash
+purl parse <purl-string>              # Parse and display PURL components
+purl validate <purl-string>           # Validate a PURL (exit code indicates success)
+purl convert <registry-url>           # Convert registry URL to PURL
+purl url <purl-string>                # Convert PURL to registry URL
+purl generate [options]               # Generate PURL from components
+purl info [type]                      # Show information about PURL types
+```
+
+### JSON Output
+
+All commands support JSON output with the `--json` flag:
+
+```bash
+purl --json parse "pkg:gem/rails@7.0.0"
+purl --json info gem
+```
+
+### Command Examples
+
+#### Parse a PURL
+```bash
+$ purl parse "pkg:gem/rails@7.0.0"
+Valid PURL: pkg:gem/rails@7.0.0
+Components:
+  Type:       gem
+  Namespace:  (none)
+  Name:       rails
+  Version:    7.0.0
+  Qualifiers: (none)
+  Subpath:    (none)
+
+$ purl --json parse "pkg:npm/@babel/core@7.0.0"
+{
+  "success": true,
+  "purl": "pkg:npm/%40babel/core@7.0.0",
+  "components": {
+    "type": "npm",
+    "namespace": "@babel",
+    "name": "core",
+    "version": "7.0.0",
+    "qualifiers": {},
+    "subpath": null
+  }
+}
+```
+
+#### Validate a PURL
+```bash
+$ purl validate "pkg:gem/rails@7.0.0"
+Valid PURL
+
+$ purl validate "invalid-purl"
+Invalid PURL: PURL must start with 'pkg:'
+```
+
+#### Convert Registry URL to PURL
+```bash
+$ purl convert "https://rubygems.org/gems/rails"
+pkg:gem/rails
+
+$ purl convert "https://www.npmjs.com/package/@babel/core"
+pkg:npm/@babel/core
+```
+
+#### Convert PURL to Registry URL
+```bash
+$ purl url "pkg:gem/rails@7.0.0"
+https://rubygems.org/gems/rails
+
+$ purl url "pkg:npm/@babel/core@7.0.0"
+https://www.npmjs.com/package/@babel/core
+
+$ purl --json url "pkg:gem/rails@7.0.0"
+{
+  "success": true,
+  "purl": "pkg:gem/rails@7.0.0",
+  "registry_url": "https://rubygems.org/gems/rails",
+  "type": "gem"
+}
+```
+
+#### Generate a PURL
+```bash
+$ purl generate --type gem --name rails --version 7.0.0
+pkg:gem/rails@7.0.0
+
+$ purl generate --type npm --namespace @babel --name core --version 7.0.0 --qualifiers "arch=x64,os=linux"
+pkg:npm/%40babel/core@7.0.0?arch=x64&os=linux
+```
+
+#### Show Type Information
+```bash
+$ purl info gem
+Type: gem
+Known: Yes
+Description: RubyGems
+Default registry: https://rubygems.org
+Registry URL generation: Yes
+Reverse parsing: Yes
+Examples:
+  pkg:gem/ruby-advisory-db-check@0.12.4
+  pkg:gem/rails@7.0.4
+  pkg:gem/bundler@2.3.26
+Registry URL patterns:
+  https://rubygems.org/gems/:name
+  https://rubygems.org/gems/:name/versions/:version
+
+$ purl info  # Shows all types
+Known PURL types:
+
+  alpm
+    Description: Arch Linux packages
+    Registry support: No
+    Reverse parsing: No
+  ...
+Total types: 37
+Registry supported: 20
+```
+
+### Generate Options
+
+The `generate` command supports all PURL components:
+
+```bash
+purl generate --help
+Usage: purl generate [options]
+    --type TYPE                      Package type (required)
+    --name NAME                      Package name (required)
+    --namespace NAMESPACE            Package namespace
+    --version VERSION                Package version
+    --qualifiers QUALIFIERS          Qualifiers as key=value,key2=value2
+    --subpath SUBPATH                Package subpath
+    -h, --help                       Show this help
+```
+
+### Exit Codes
+
+The CLI uses standard exit codes:
+- `0` - Success
+- `1` - Error (invalid PURL, unsupported operation, etc.)
+
+This makes the CLI suitable for use in scripts and CI/CD pipelines:
+
+```bash
+if purl validate "pkg:gem/rails@7.0.0"; then
+  echo "Valid PURL"
+else
+  echo "Invalid PURL"
+  exit 1
+fi
+```
+
+## Library Usage
 
 ### Basic PURL Parsing
 

data/exe/purl

@@ -0,0 +1,484 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require "net/http"
+require "uri"
+require_relative "../lib/purl"
+
+class PurlCLI
+  def self.run(args = ARGV)
+    new.run(args)
+  end
+
+  def initialize
+    @json_output = false
+  end
+
+  def run(args)
+    if args.empty?
+      puts usage
+      exit 1
+    end
+
+    # Check for global --json flag
+    if args.include?("--json")
+      @json_output = true
+      args.delete("--json")
+    end
+
+    command = args.shift
+    case command
+    when "parse"
+      parse_command(args)
+    when "validate"
+      validate_command(args)
+    when "convert"
+      convert_command(args)
+    when "generate"
+      generate_command(args)
+    when "url"
+      url_command(args)
+    when "info"
+      info_command(args)
+    when "lookup"
+      lookup_command(args)
+    when "--help", "-h", "help"
+      puts usage
+      exit 0
+    when "--version", "-v"
+      puts Purl::VERSION
+      exit 0
+    else
+      puts "Unknown command: #{command}"
+      puts usage
+      exit 1
+    end
+  end
+
+  private
+
+  def usage
+    <<~USAGE
+      purl - Parse, validate, convert and generate Package URLs (PURLs)
+
+      Usage:
+        purl [--json] parse <purl-string>     Parse and display PURL components
+        purl [--json] validate <purl-string>  Validate a PURL (exit code indicates success)
+        purl [--json] convert <registry-url>  Convert registry URL to PURL
+        purl [--json] url <purl-string>       Convert PURL to registry URL
+        purl [--json] generate [options]      Generate PURL from components
+        purl [--json] info [type]             Show information about PURL types
+        purl [--json] lookup <purl-string>    Look up package information from ecosyste.ms
+        purl --version                        Show version
+        purl --help                           Show this help
+
+      Global Options:
+        --json                                Output results in JSON format
+
+      Examples:
+        purl parse "pkg:gem/rails@7.0.0"
+        purl --json parse "pkg:gem/rails@7.0.0"
+        purl validate "pkg:npm/@babel/core@7.0.0"
+        purl convert "https://rubygems.org/gems/rails"
+        purl url "pkg:gem/rails@7.0.0"
+        purl generate --type gem --name rails --version 7.0.0
+        purl --json info gem
+        purl lookup "pkg:cargo/rand"
+    USAGE
+  end
+
+  def parse_command(args)
+    if args.empty?
+      output_error("PURL string required")
+      exit 1
+    end
+
+    purl_string = args[0]
+    
+    begin
+      purl = Purl.parse(purl_string)
+      
+      if @json_output
+        result = {
+          success: true,
+          purl: purl.to_s,
+          components: {
+            type: purl.type,
+            namespace: purl.namespace,
+            name: purl.name,
+            version: purl.version,
+            qualifiers: purl.qualifiers || {},
+            subpath: purl.subpath
+          }
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Valid PURL: #{purl.to_s}"
+        puts "Components:"
+        puts "  Type:       #{purl.type}"
+        puts "  Namespace:  #{purl.namespace || '(none)'}"
+        puts "  Name:       #{purl.name}"
+        puts "  Version:    #{purl.version || '(none)'}"
+        
+        if purl.qualifiers && !purl.qualifiers.empty?
+          puts "  Qualifiers:"
+          purl.qualifiers.each do |key, value|
+            puts "    #{key}: #{value}"
+          end
+        else
+          puts "  Qualifiers: (none)"
+        end
+        
+        puts "  Subpath:    #{purl.subpath || '(none)'}"
+      end
+    rescue Purl::Error => e
+      output_error("Error parsing PURL: #{e.message}")
+      exit 1
+    end
+  end
+
+  def validate_command(args)
+    if args.empty?
+      output_error("PURL string required")
+      exit 1
+    end
+
+    purl_string = args[0]
+    
+    begin
+      purl = Purl.parse(purl_string)
+      if @json_output
+        result = {
+          success: true,
+          valid: true,
+          purl: purl.to_s,
+          message: "Valid PURL"
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Valid PURL"
+      end
+      exit 0
+    rescue Purl::Error => e
+      if @json_output
+        result = {
+          success: false,
+          valid: false,
+          purl: purl_string,
+          error: e.message
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Invalid PURL: #{e.message}"
+      end
+      exit 1
+    end
+  end
+
+  def convert_command(args)
+    if args.empty?
+      output_error("Registry URL required")
+      exit 1
+    end
+
+    registry_url = args[0]
+    
+    begin
+      purl = Purl.from_registry_url(registry_url)
+      if @json_output
+        result = {
+          success: true,
+          registry_url: registry_url,
+          purl: purl.to_s,
+          components: {
+            type: purl.type,
+            namespace: purl.namespace,
+            name: purl.name,
+            version: purl.version,
+            qualifiers: purl.qualifiers || {},
+            subpath: purl.subpath
+          }
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts purl.to_s
+      end
+    rescue Purl::Error => e
+      if @json_output
+        result = {
+          success: false,
+          registry_url: registry_url,
+          error: e.message
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Error converting URL: #{e.message}"
+      end
+      exit 1
+    end
+  end
+
+  def url_command(args)
+    if args.empty?
+      output_error("PURL string required")
+      exit 1
+    end
+
+    purl_string = args[0]
+    
+    begin
+      purl = Purl.parse(purl_string)
+      
+      unless purl.supports_registry_url?
+        if @json_output
+          result = {
+            success: false,
+            purl: purl_string,
+            error: "Registry URL generation not supported for type '#{purl.type}'"
+          }
+          puts JSON.pretty_generate(result)
+        else
+          puts "Error: Registry URL generation not supported for type '#{purl.type}'"
+        end
+        exit 1
+      end
+      
+      registry_url = purl.registry_url
+      
+      if @json_output
+        result = {
+          success: true,
+          purl: purl.to_s,
+          registry_url: registry_url,
+          type: purl.type
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts registry_url
+      end
+    rescue Purl::Error => e
+      if @json_output
+        result = {
+          success: false,
+          purl: purl_string,
+          error: e.message
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Error: #{e.message}"
+      end
+      exit 1
+    end
+  end
+
+  def generate_command(args)
+    options = {}
+    OptionParser.new do |opts|
+      opts.banner = "Usage: purl generate [options]"
+      
+      opts.on("--type TYPE", "Package type (required)") do |v|
+        options[:type] = v
+      end
+      
+      opts.on("--name NAME", "Package name (required)") do |v|
+        options[:name] = v
+      end
+      
+      opts.on("--namespace NAMESPACE", "Package namespace") do |v|
+        options[:namespace] = v
+      end
+      
+      opts.on("--version VERSION", "Package version") do |v|
+        options[:version] = v
+      end
+      
+      opts.on("--qualifiers QUALIFIERS", "Qualifiers as key=value,key2=value2") do |v|
+        qualifiers = {}
+        v.split(",").each do |pair|
+          key, value = pair.split("=", 2)
+          if key && value
+            qualifiers[key.strip] = value.strip
+          end
+        end
+        options[:qualifiers] = qualifiers unless qualifiers.empty?
+      end
+      
+      opts.on("--subpath SUBPATH", "Package subpath") do |v|
+        options[:subpath] = v
+      end
+      
+      opts.on("-h", "--help", "Show this help") do
+        puts opts
+        exit 0
+      end
+    end.parse!(args)
+
+    unless options[:type] && options[:name]
+      output_error("--type and --name are required")
+      puts "Use 'purl generate --help' for more information" unless @json_output
+      exit 1
+    end
+
+    begin
+      purl = Purl::PackageURL.new(**options)
+      if @json_output
+        result = {
+          success: true,
+          purl: purl.to_s,
+          components: {
+            type: purl.type,
+            namespace: purl.namespace,
+            name: purl.name,
+            version: purl.version,
+            qualifiers: purl.qualifiers || {},
+            subpath: purl.subpath
+          }
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts purl.to_s
+      end
+    rescue Purl::Error => e
+      if @json_output
+        result = {
+          success: false,
+          error: e.message,
+          options: options
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Error generating PURL: #{e.message}"
+      end
+      exit 1
+    end
+  end
+
+  def info_command(args)
+    if args.empty?
+      # Show all types
+      all_info = Purl.all_type_info
+      metadata = Purl.types_config_metadata
+      
+      if @json_output
+        result = {
+          success: true,
+          types: all_info,
+          metadata: metadata
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Known PURL types:"
+        puts
+        
+        all_info.each do |type, info|
+          puts "  #{type}"
+          puts "    Description: #{info[:description] || 'No description available'}"
+          puts "    Registry support: #{info[:registry_url_generation] ? 'Yes' : 'No'}"
+          puts "    Reverse parsing: #{info[:reverse_parsing] ? 'Yes' : 'No'}"
+          puts
+        end
+        
+        puts "Total types: #{metadata[:total_types]}"
+        puts "Registry supported: #{metadata[:registry_supported_types]}"
+      end
+    else
+      # Show specific type info
+      type = args[0]
+      info = Purl.type_info(type)
+      
+      if @json_output
+        result = {
+          success: true,
+          type: info
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Type: #{info[:type]}"
+        puts "Known: #{info[:known] ? 'Yes' : 'No'}"
+        puts "Description: #{info[:description] || 'No description available'}"
+        
+        if info[:default_registry]
+          puts "Default registry: #{info[:default_registry]}"
+        end
+        
+        puts "Registry URL generation: #{info[:registry_url_generation] ? 'Yes' : 'No'}"
+        puts "Reverse parsing: #{info[:reverse_parsing] ? 'Yes' : 'No'}"
+        
+        if info[:examples] && !info[:examples].empty?
+          puts "Examples:"
+          info[:examples].each do |example|
+            puts "  #{example}"
+          end
+        end
+        
+        if info[:route_patterns] && !info[:route_patterns].empty?
+          puts "Registry URL patterns:"
+          info[:route_patterns].each do |pattern|
+            puts "  #{pattern}"
+          end
+        end
+      end
+    end
+  end
+
+  def lookup_command(args)
+    if args.empty?
+      output_error("PURL string required")
+      exit 1
+    end
+
+    purl_string = args[0]
+    
+    begin
+      # Validate PURL first
+      purl = Purl.parse(purl_string)
+      
+      # Use the library lookup method
+      info = purl.lookup(user_agent: "purl-ruby-cli/#{Purl::VERSION}")
+      
+      # Use formatter to generate output
+      formatter = Purl::LookupFormatter.new
+      
+      if @json_output
+        result = formatter.format_json(info, purl)
+        puts JSON.pretty_generate(result)
+        exit 1 unless result[:success]
+      else
+        if info
+          puts formatter.format_text(info, purl)
+        else
+          puts "Package not found in ecosyste.ms database"
+          exit 1
+        end
+      end
+      
+    rescue Purl::Error => e
+      output_error("Invalid PURL: #{e.message}")
+      exit 1
+    rescue Purl::LookupError => e
+      output_error("Lookup failed: #{e.message}")
+      exit 1
+    rescue StandardError => e
+      output_error("Lookup failed: #{e.message}")
+      exit 1
+    end
+  end
+
+  def output_error(message)
+    if @json_output
+      result = {
+        success: false,
+        error: message
+      }
+      puts JSON.pretty_generate(result)
+    else
+      puts "Error: #{message}"
+    end
+  end
+end
+
+if __FILE__ == $0
+  PurlCLI.run
+end

data/lib/purl/lookup.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Purl
+  # Provides lookup functionality for packages using the ecosyste.ms API
+  class Lookup
+    ECOSYSTE_MS_API_BASE = "https://packages.ecosyste.ms/api/v1"
+    
+    # Initialize a new Lookup instance
+    #
+    # @param user_agent [String] User agent string for API requests
+    # @param timeout [Integer] Request timeout in seconds
+    def initialize(user_agent: nil, timeout: 10)
+      @user_agent = user_agent || "purl-ruby/#{Purl::VERSION}"
+      @timeout = timeout
+    end
+
+    # Look up package information for a given PURL
+    #
+    # @param purl [String, PackageURL] PURL string or PackageURL object
+    # @return [Hash, nil] Package information hash or nil if not found
+    # @raise [LookupError] if the lookup fails due to network or API errors
+    #
+    # @example
+    #   lookup = Purl::Lookup.new
+    #   info = lookup.package_info("pkg:cargo/rand@0.9.2")
+    #   puts info[:package][:name]  # => "rand"
+    #   puts info[:version][:published_at] if info[:version]  # => "2025-07-20T17:47:01.870Z"
+    def package_info(purl)
+      purl_obj = purl.is_a?(PackageURL) ? purl : PackageURL.parse(purl.to_s)
+      
+      # Make API request to ecosyste.ms
+      uri = URI("#{ECOSYSTE_MS_API_BASE}/packages/lookup")
+      uri.query = URI.encode_www_form({ purl: purl_obj.to_s })
+      
+      response_data = make_request(uri)
+      
+      return nil unless response_data.is_a?(Array) && response_data.length > 0
+      
+      package_data = response_data[0]
+      
+      result = {
+        purl: purl_obj.to_s,
+        package: extract_package_info(package_data)
+      }
+      
+      # If PURL has a version and we have a versions_url, fetch version-specific details
+      if purl_obj.version && package_data["versions_url"]
+        version_info = fetch_version_info(package_data["versions_url"], purl_obj.version)
+        result[:version] = version_info if version_info
+      end
+      
+      result
+    end
+
+    # Look up version information for a specific version of a package
+    #
+    # @param purl [String, PackageURL] PURL string or PackageURL object (must include version)
+    # @return [Hash, nil] Version information hash or nil if not found
+    # @raise [LookupError] if the lookup fails due to network or API errors
+    # @raise [ArgumentError] if the PURL doesn't include a version
+    #
+    # @example
+    #   lookup = Purl::Lookup.new
+    #   version_info = lookup.version_info("pkg:cargo/rand@0.9.2")
+    #   puts version_info[:published_at]  # => "2025-07-20T17:47:01.870Z"
+    def version_info(purl)
+      purl_obj = purl.is_a?(PackageURL) ? purl : PackageURL.parse(purl.to_s)
+      
+      raise ArgumentError, "PURL must include a version" unless purl_obj.version
+      
+      # First get the package info to get the versions_url
+      package_result = package_info(purl_obj.versionless)
+      return nil unless package_result && package_result[:package][:versions_url]
+      
+      fetch_version_info(package_result[:package][:versions_url], purl_obj.version)
+    end
+
+    private
+
+    def make_request(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+      
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = @user_agent
+      
+      response = http.request(request)
+      
+      case response.code.to_i
+      when 200
+        JSON.parse(response.body)
+      when 404
+        nil
+      else
+        raise LookupError, "API request failed with status #{response.code}"
+      end
+    rescue JSON::ParserError => e
+      raise LookupError, "Failed to parse API response: #{e.message}"
+    rescue Net::TimeoutError, Net::OpenTimeout, Net::ReadTimeout => e
+      raise LookupError, "Request timeout: #{e.message}"
+    rescue StandardError => e
+      raise LookupError, "Lookup failed: #{e.message}"
+    end
+
+    def extract_package_info(package_data)
+      {
+        name: package_data["name"],
+        ecosystem: package_data["ecosystem"],
+        description: package_data["description"],
+        homepage: package_data["homepage"],
+        repository_url: package_data["repository_url"],
+        registry_url: package_data["registry_url"],
+        licenses: package_data["licenses"],
+        latest_version: package_data["latest_release_number"],
+        latest_version_published_at: package_data["latest_release_published_at"],
+        versions_count: package_data["versions_count"],
+        keywords: package_data["keywords_array"],
+        install_command: package_data["install_command"],
+        documentation_url: package_data["documentation_url"],
+        maintainers: extract_maintainers(package_data["maintainers"]),
+        versions_url: package_data["versions_url"]
+      }
+    end
+
+    def fetch_version_info(versions_url, version)
+      return nil unless versions_url && version
+      
+      begin
+        uri = URI("#{versions_url}/#{URI.encode_www_form_component(version)}")
+        data = make_request(uri)
+        
+        return nil unless data
+        
+        # Extract relevant version information
+        version_info = {
+          number: data["number"],
+          published_at: data["published_at"],
+          version_url: data["version_url"],
+          download_url: data["download_url"],
+          registry_url: data["registry_url"],
+          documentation_url: data["documentation_url"],
+          install_command: data["install_command"]
+        }
+        
+        # Add metadata if available
+        if data["metadata"]
+          metadata = data["metadata"]
+          version_info[:downloads] = metadata["downloads"] if metadata["downloads"]
+          version_info[:size] = metadata["crate_size"] || metadata["size"] if metadata["crate_size"] || metadata["size"]
+          version_info[:yanked] = metadata["yanked"] if metadata.key?("yanked")
+          
+          if metadata["published_by"] && metadata["published_by"].is_a?(Hash)
+            published_by = metadata["published_by"]
+            if published_by["name"] && published_by["login"]
+              version_info[:published_by] = "#{published_by["name"]} (#{published_by["login"]})"
+            elsif published_by["login"]
+              version_info[:published_by] = published_by["login"]
+            end
+          end
+        end
+        
+        version_info
+      rescue StandardError
+        # Don't fail if version lookup fails
+        nil
+      end
+    end
+
+    def extract_maintainers(maintainers_data)
+      return nil unless maintainers_data && maintainers_data.is_a?(Array)
+      
+      maintainers_data.map do |maintainer|
+        {
+          login: maintainer["login"],
+          name: maintainer["name"],
+          url: maintainer["url"]
+        }.compact # Remove nil values
+      end
+    end
+  end
+
+  # Error raised when package lookup fails
+  class LookupError < Error
+    def initialize(message)
+      super(message)
+    end
+  end
+end

data/lib/purl/lookup_formatter.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Purl
+  # Formats package lookup results for human-readable display
+  class LookupFormatter
+    def initialize
+    end
+
+    # Format package lookup results for console output
+    #
+    # @param lookup_result [Hash] Result from Purl::Lookup#package_info
+    # @param purl [PackageURL] Original PURL object
+    # @return [String] Formatted output string
+    def format_text(lookup_result, purl)
+      return "Package not found" unless lookup_result
+
+      package = lookup_result[:package]
+      version_info = lookup_result[:version]
+      
+      output = []
+      
+      # Package header
+      output << "Package: #{package[:name]} (#{package[:ecosystem]})"
+      output << "#{package[:description]}" if package[:description]
+      
+      # Keywords - add without extra spacing, the blank line before Version Info will handle spacing
+      if package[:keywords] && !package[:keywords].empty?
+        output << "Keywords: #{package[:keywords].join(", ")}"
+      end
+      
+      # Version Information section
+      output << ""
+      output << "Version Information:"
+      if package[:latest_version]
+        output << "  Latest: #{package[:latest_version]}"
+        output << "  Published: #{package[:latest_version_published_at]}" if package[:latest_version_published_at]
+      end
+      output << "  Total versions: #{format_number(package[:versions_count])}" if package[:versions_count]
+      
+      # Links section
+      output << ""
+      output << "Links:"
+      output << "  Homepage: #{package[:homepage]}" if package[:homepage]
+      output << "  Repository: #{package[:repository_url]}" if package[:repository_url]
+      output << "  Registry: #{package[:registry_url]}" if package[:registry_url]
+      output << "  Documentation: #{package[:documentation_url]}" if package[:documentation_url]
+      
+      # Package Info section
+      if package[:licenses] || package[:install_command] || package[:maintainers]
+        output << ""
+        output << "Package Info:"
+        output << "  License: #{package[:licenses]}" if package[:licenses]
+        output << "  Install: #{package[:install_command]}" if package[:install_command]
+        
+        if package[:maintainers] && !package[:maintainers].empty?
+          output << "  Maintainers:"
+          package[:maintainers].each do |maintainer|
+            if maintainer[:name] && maintainer[:login]
+              output << "    #{maintainer[:name]} (#{maintainer[:login]})"
+            elsif maintainer[:login]
+              output << "    #{maintainer[:login]}"
+            end
+          end
+        end
+      end
+      
+      # Version-specific details
+      if version_info
+        output << ""
+        output << "Specific Version (#{purl.version}):"
+        output << "  Published: #{version_info[:published_at]}" if version_info[:published_at]
+        output << "  Published by: #{version_info[:published_by]}" if version_info[:published_by]
+        output << "  Downloads: #{format_number(version_info[:downloads])}" if version_info[:downloads]
+        output << "  Size: #{format_number(version_info[:size])} bytes" if version_info[:size]
+        output << "  Yanked: #{version_info[:yanked] ? 'Yes' : 'No'}" if version_info.key?(:yanked)
+        
+        if version_info[:registry_url] || version_info[:documentation_url] || version_info[:download_url]
+          output << "  Version Links:"
+          output << "    Registry: #{version_info[:registry_url]}" if version_info[:registry_url]
+          output << "    Documentation: #{version_info[:documentation_url]}" if version_info[:documentation_url]
+          output << "    Download: #{version_info[:download_url]}" if version_info[:download_url]
+          output << "    API: #{version_info[:version_url]}" if version_info[:version_url]
+        end
+      end
+      
+      output.join("\n")
+    end
+
+    # Format package lookup results for JSON output
+    #
+    # @param lookup_result [Hash] Result from Purl::Lookup#package_info
+    # @param purl [PackageURL] Original PURL object
+    # @return [Hash] JSON-ready hash structure
+    def format_json(lookup_result, purl)
+      return {
+        success: false,
+        purl: purl.to_s,
+        error: "Package not found in ecosyste.ms database"
+      } unless lookup_result
+
+      result = {
+        success: true,
+        purl: purl.to_s,
+        package: lookup_result[:package]
+      }
+      
+      result[:version] = lookup_result[:version] if lookup_result[:version]
+      
+      result
+    end
+
+    private
+
+    def format_number(num)
+      return num.to_s unless num.is_a?(Numeric)
+      num.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+    end
+  end
+end

data/lib/purl/package_url.rb

@@ -360,6 +360,36 @@ module Purl
       self.class.new(**new_attrs)
     end
 
+    # Create a new PackageURL without the version component
+    #
+    # @return [PackageURL] new PackageURL instance with version set to nil
+    #
+    # @example
+    #   purl = PackageURL.parse("pkg:gem/rails@7.0.0")
+    #   versionless = purl.versionless
+    #   puts versionless.to_s  # "pkg:gem/rails"
+    def versionless
+      with(version: nil)
+    end
+
+    # Look up package information using the ecosyste.ms API
+    #
+    # @param user_agent [String] User agent string for API requests
+    # @param timeout [Integer] Request timeout in seconds
+    # @return [Hash, nil] Package information hash or nil if not found
+    # @raise [LookupError] if the lookup fails due to network or API errors
+    #
+    # @example
+    #   purl = PackageURL.parse("pkg:cargo/rand@0.9.2")
+    #   info = purl.lookup
+    #   puts info[:package][:name]  # => "rand"
+    #   puts info[:version][:published_at] if info[:version]  # => "2025-07-20T17:47:01.870Z"
+    def lookup(user_agent: nil, timeout: 10)
+      require_relative "lookup"
+      lookup_client = Lookup.new(user_agent: user_agent, timeout: timeout)
+      lookup_client.package_info(self)
+    end
+
     private
 
     def validate_and_normalize_type(type)

data/lib/purl/version.rb

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

data/lib/purl.rb

@@ -4,6 +4,8 @@ require_relative "purl/version"
 require_relative "purl/errors"
 require_relative "purl/package_url"
 require_relative "purl/registry_url"
+require_relative "purl/lookup"
+require_relative "purl/lookup_formatter"
 
 # The main PURL (Package URL) module providing functionality to parse,
 # validate, and generate package URLs according to the PURL specification.
@@ -21,6 +23,12 @@ require_relative "purl/registry_url"
 #   purl = Purl.from_registry_url("https://rubygems.org/gems/rails")
 #   puts purl.to_s     # "pkg:gem/rails"
 #
+# @example Package information lookup
+#   purl = Purl.parse("pkg:cargo/rand@0.9.2")
+#   info = purl.lookup
+#   puts info[:package][:description]
+#   puts info[:version][:published_at] if info[:version]
+#
 # @see https://github.com/package-url/purl-spec PURL Specification
 module Purl
   # Base error class for all PURL-related errors

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: purl
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Andrew Nesbitt
@@ -28,7 +28,8 @@ description: |-
   It supports 37 package types (32 official + 5 additional ecosystems) and is fully compliant with the official PURL specification test suite.
 email:
 - andrewnez@gmail.com
-executables: []
+executables:
+- purl
 extensions: []
 extra_rdoc_files: []
 files:
@@ -40,8 +41,11 @@ files:
 - README.md
 - Rakefile
 - SECURITY.md
+- exe/purl
 - lib/purl.rb
 - lib/purl/errors.rb
+- lib/purl/lookup.rb
+- lib/purl/lookup_formatter.rb
 - lib/purl/package_url.rb
 - lib/purl/registry_url.rb
 - lib/purl/version.rb