purl 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a3bf4cd374d69577598e05fa94658b7768c94b3522314a3382d1f9b872b203b
-  data.tar.gz: e1ddc0ec9b9ec7d675c9eeff8527af612610bcce7bc344313fe5c79a4975bd7d
+  metadata.gz: f5be58ada7f5731a371cee07f0175e020aa7a49ea7d228c88e1af4c2554d5ecc
+  data.tar.gz: 96e6ff76c5626c4c414651324eee74c4845e4fb337b93470dc534d49622facfc
 SHA512:
-  metadata.gz: 6a4e84903907467f13205f4f9c31c29e67945f83c87d68f577008598d50da3f702d98b1c0e115a5c4a441a2babfdae6b6463da5e125f5f1630476d983a116849
-  data.tar.gz: b6e45ef48f2fb2d52eea945b658a24a3e3cc4236c7656ba21b8287bb5eb7b662d7adf9d46148771b48cfcb884f5f3fcce0bbbaffb54f3d7126a3d4f1f5f297a8
+  metadata.gz: adfb3b0b945ad8787738388c3b40087ae662974ba60ff3783100ba845c8e19e8fc73c4480b3296a5df701080af31919dbea66d0c5d3803ec29e18a098da0d837
+  data.tar.gz: a96abd807ede7d4c6eaff1cb0bdd6bacdfc8723e3dad839f17ecbc7b3502edb9b24e2f32f84fec3b3c100e7ec5cd3a940229fc6421f964c9927fc370587948a3

data/CHANGELOG.md

@@ -7,6 +7,16 @@ 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

data/exe/purl

@@ -3,6 +3,8 @@
 
 require "optparse"
 require "json"
+require "net/http"
+require "uri"
 require_relative "../lib/purl"
 
 class PurlCLI
@@ -40,6 +42,8 @@ class PurlCLI
       url_command(args)
     when "info"
       info_command(args)
+    when "lookup"
+      lookup_command(args)
     when "--help", "-h", "help"
       puts usage
       exit 0
@@ -66,6 +70,7 @@ class PurlCLI
         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
 
@@ -80,6 +85,7 @@ class PurlCLI
         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
 
@@ -417,6 +423,49 @@ class PurlCLI
     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 = {

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.4.0"
+  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.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Andrew Nesbitt
@@ -44,6 +44,8 @@ files:
 - 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