purl 1.5.2 → 1.7.0

data/lib/purl/advisory_formatter.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Purl
+  # Formats security advisory lookup results for human-readable display
+  class AdvisoryFormatter
+    def initialize
+    end
+
+    # Format advisory lookup results for console output
+    #
+    # @param advisories [Array<Hash>] Array of advisory hashes from Purl::Advisory#lookup
+    # @param purl [PackageURL] Original PURL object
+    # @return [String] Formatted output string
+    def format_text(advisories, purl)
+      return "No security advisories found" if advisories.nil? || advisories.empty?
+
+      output = []
+      output << "Security Advisories for #{purl.to_s}"
+      output << "=" * 80
+      output << ""
+
+      advisories.each_with_index do |advisory, index|
+        output << format_advisory_text(advisory, index + 1)
+        output << "" unless index == advisories.length - 1
+      end
+
+      output << ""
+      output << "Total advisories found: #{advisories.length}"
+
+      output.join("\n")
+    end
+
+    # Format advisory lookup results for JSON output
+    #
+    # @param advisories [Array<Hash>] Array of advisory hashes from Purl::Advisory#lookup
+    # @param purl [PackageURL] Original PURL object
+    # @return [Hash] JSON-ready hash structure
+    def format_json(advisories, purl)
+      {
+        success: true,
+        purl: purl.to_s,
+        advisories: advisories,
+        count: advisories.length
+      }
+    end
+
+    private
+
+    def format_advisory_text(advisory, number)
+      output = []
+
+      # Header with identifiers
+      identifiers = format_identifiers(advisory)
+      output << "Advisory ##{number}: #{advisory[:title]}"
+      output << "Identifiers: #{identifiers}" if identifiers
+
+      # Severity and scoring
+      if advisory[:severity] || advisory[:cvss_score]
+        severity_line = []
+        severity_line << "Severity: #{advisory[:severity]}" if advisory[:severity]
+        if advisory[:cvss_score] && advisory[:cvss_score] > 0
+          severity_line << "CVSS Score: #{advisory[:cvss_score]}"
+        end
+        output << severity_line.join(" | ")
+      end
+
+      # Description
+      if advisory[:description]
+        output << ""
+        output << "Description:"
+        output << wrap_text(advisory[:description], 78, "  ")
+      end
+
+      # Affected packages
+      if advisory[:affected_packages] && !advisory[:affected_packages].empty?
+        output << ""
+        output << "Affected Packages:"
+        advisory[:affected_packages].each do |pkg|
+          version_info = []
+          version_info << "  Package: #{pkg[:ecosystem]}/#{pkg[:name]}"
+          version_info << "  Vulnerable: #{pkg[:vulnerable_version_range]}" if pkg[:vulnerable_version_range]
+          version_info << "  Patched: #{pkg[:first_patched_version]}" if pkg[:first_patched_version]
+          output.concat(version_info)
+        end
+      end
+
+      # Source and dates
+      output << ""
+      source_info = []
+      source_info << "Source: #{advisory[:source_kind]}" if advisory[:source_kind]
+      source_info << "Origin: #{advisory[:origin]}" if advisory[:origin]
+      source_info << "Published: #{format_date(advisory[:published_at])}" if advisory[:published_at]
+      output << source_info.join(" | ") unless source_info.empty?
+
+      if advisory[:withdrawn_at]
+        output << "Status: WITHDRAWN on #{format_date(advisory[:withdrawn_at])}"
+      end
+
+      # URLs
+      urls = []
+      urls << "Advisory URL: #{advisory[:url]}" if advisory[:url]
+      urls << "Repository: #{advisory[:repository_url]}" if advisory[:repository_url]
+      output.concat(urls) unless urls.empty?
+
+      # References
+      if advisory[:references] && !advisory[:references].empty? && advisory[:references].any? { |ref| ref.is_a?(String) && !ref.empty? }
+        output << ""
+        output << "References:"
+        advisory[:references].each do |ref|
+          output << "  - #{ref}" if ref.is_a?(String) && !ref.empty?
+        end
+      end
+
+      output.join("\n")
+    end
+
+    def format_identifiers(advisory)
+      return nil unless advisory[:identifiers] && !advisory[:identifiers].empty?
+      advisory[:identifiers].join(", ")
+    end
+
+    def format_date(date_string)
+      return nil unless date_string
+      # Keep ISO format for now, could parse and reformat if needed
+      date_string
+    end
+
+    def wrap_text(text, width, indent = "")
+      return text unless text
+
+      # Split on double newlines to preserve paragraph breaks
+      paragraphs = text.split(/\n\n+/)
+
+      wrapped_paragraphs = paragraphs.map do |paragraph|
+        # Replace single newlines within a paragraph with spaces
+        # but preserve intentional formatting (like lists)
+        paragraph = paragraph.gsub(/\n/, " ")
+
+        # Wrap the paragraph
+        words = paragraph.split(/\s+/)
+        lines = []
+        current_line = indent.dup
+
+        words.each do |word|
+          if (current_line + word).length > width
+            lines << current_line.rstrip
+            current_line = indent + word + " "
+          else
+            current_line += word + " "
+          end
+        end
+
+        lines << current_line.rstrip unless current_line.strip.empty?
+        lines.join("\n")
+      end
+
+      wrapped_paragraphs.join("\n#{indent}\n")
+    end
+  end
+end

data/lib/purl/download_url.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Purl
+  class DownloadURL
+    DOWNLOAD_PATTERNS = {
+      "gem" => {
+        base_url: "https://rubygems.org/downloads",
+        pattern: ->(purl) { "#{purl.name}-#{purl.version}.gem" }
+      },
+      "npm" => {
+        base_url: "https://registry.npmjs.org",
+        pattern: ->(purl) do
+          # npm: /{name}/-/{basename}-{version}.tgz
+          # For scoped packages: /@scope/name/-/name-version.tgz
+          basename = purl.name.split("/").last
+          if purl.namespace
+            "#{purl.namespace}/#{purl.name}/-/#{basename}-#{purl.version}.tgz"
+          else
+            "#{purl.name}/-/#{purl.name}-#{purl.version}.tgz"
+          end
+        end
+      },
+      "cargo" => {
+        base_url: "https://static.crates.io/crates",
+        pattern: ->(purl) { "#{purl.name}/#{purl.name}-#{purl.version}.crate" }
+      },
+      "nuget" => {
+        base_url: "https://api.nuget.org/v3-flatcontainer",
+        pattern: ->(purl) do
+          name_lower = purl.name.downcase
+          "#{name_lower}/#{purl.version}/#{name_lower}.#{purl.version}.nupkg"
+        end
+      },
+      "hex" => {
+        base_url: "https://repo.hex.pm/tarballs",
+        pattern: ->(purl) { "#{purl.name}-#{purl.version}.tar" }
+      },
+      "hackage" => {
+        base_url: "https://hackage.haskell.org/package",
+        pattern: ->(purl) { "#{purl.name}-#{purl.version}/#{purl.name}-#{purl.version}.tar.gz" }
+      },
+      "pub" => {
+        base_url: "https://pub.dev/packages",
+        pattern: ->(purl) { "#{purl.name}/versions/#{purl.version}.tar.gz" }
+      },
+      "golang" => {
+        base_url: "https://proxy.golang.org",
+        pattern: ->(purl) do
+          # Go module proxy requires encoding capital letters as !lowercase
+          full_path = purl.namespace ? "#{purl.namespace}/#{purl.name}" : purl.name
+          encoded = full_path.gsub(/[A-Z]/) { |s| "!#{s.downcase}" }
+          "#{encoded}/@v/#{purl.version}.zip"
+        end
+      },
+      "maven" => {
+        base_url: "https://repo.maven.apache.org/maven2",
+        pattern: ->(purl) do
+          # Maven: /{group_path}/{artifact}/{version}/{artifact}-{version}.jar
+          # group_id uses dots, path uses slashes
+          group_path = purl.namespace.gsub(".", "/")
+          "#{group_path}/#{purl.name}/#{purl.version}/#{purl.name}-#{purl.version}.jar"
+        end
+      },
+      "cran" => {
+        base_url: "https://cran.r-project.org/src/contrib",
+        pattern: ->(purl) { "#{purl.name}_#{purl.version}.tar.gz" }
+      },
+      "bioconductor" => {
+        base_url: "https://bioconductor.org/packages/release/bioc/src/contrib",
+        pattern: ->(purl) { "#{purl.name}_#{purl.version}.tar.gz" }
+      },
+      "clojars" => {
+        base_url: "https://repo.clojars.org",
+        pattern: ->(purl) do
+          # Clojars uses maven-style paths
+          # namespace is group_id, name is artifact_id
+          # If no namespace, group_id = artifact_id
+          group_id = purl.namespace || purl.name
+          artifact_id = purl.name
+          group_path = group_id.gsub(".", "/")
+          "#{group_path}/#{artifact_id}/#{purl.version}/#{artifact_id}-#{purl.version}.jar"
+        end
+      },
+      "elm" => {
+        base_url: "https://github.com",
+        pattern: ->(purl) do
+          # Elm packages are hosted on GitHub
+          # namespace/name format maps to GitHub user/repo
+          return nil unless purl.namespace
+          "#{purl.namespace}/#{purl.name}/archive/#{purl.version}.zip"
+        end
+      },
+      "github" => {
+        base_url: "https://github.com",
+        pattern: ->(purl) do
+          return nil unless purl.namespace
+          "#{purl.namespace}/#{purl.name}/archive/refs/tags/#{purl.version}.tar.gz"
+        end
+      },
+      "gitlab" => {
+        base_url: "https://gitlab.com",
+        pattern: ->(purl) do
+          return nil unless purl.namespace
+          "#{purl.namespace}/#{purl.name}/-/archive/#{purl.version}/#{purl.name}-#{purl.version}.tar.gz"
+        end
+      },
+      "bitbucket" => {
+        base_url: "https://bitbucket.org",
+        pattern: ->(purl) do
+          return nil unless purl.namespace
+          "#{purl.namespace}/#{purl.name}/get/#{purl.version}.tar.gz"
+        end
+      },
+      "luarocks" => {
+        base_url: "https://luarocks.org/manifests",
+        pattern: ->(purl) do
+          return nil unless purl.namespace
+          "#{purl.namespace}/#{purl.name}-#{purl.version}.src.rock"
+        end
+      },
+      "swift" => {
+        base_url: nil,
+        pattern: ->(purl) do
+          # Swift namespace is like "github.com/owner", name is repo
+          # e.g. pkg:swift/github.com/Alamofire/Alamofire@5.6.4
+          return nil unless purl.namespace
+          parts = purl.namespace.split("/", 2)
+          host = parts[0]
+          owner = parts[1]
+          return nil unless host && owner
+
+          case host
+          when "github.com"
+            "https://github.com/#{owner}/#{purl.name}/archive/refs/tags/#{purl.version}.tar.gz"
+          when "gitlab.com"
+            "https://gitlab.com/#{owner}/#{purl.name}/-/archive/#{purl.version}/#{purl.name}-#{purl.version}.tar.gz"
+          when "bitbucket.org"
+            "https://bitbucket.org/#{owner}/#{purl.name}/get/#{purl.version}.tar.gz"
+          end
+        end
+      },
+      "composer" => {
+        base_url: nil,
+        pattern: ->(purl) { nil },
+        note: "Composer packages are downloaded from source repositories, not Packagist"
+      },
+      "cocoapods" => {
+        base_url: nil,
+        pattern: ->(purl) { nil },
+        note: "CocoaPods packages are downloaded from source repositories"
+      }
+    }.freeze
+
+    def self.generate(purl, base_url: nil)
+      new(purl).generate(base_url: base_url)
+    end
+
+    # Types that require a namespace for download URLs
+    NAMESPACE_REQUIRED_TYPES = %w[maven elm github gitlab bitbucket luarocks swift].freeze
+
+    def self.supported_types
+      DOWNLOAD_PATTERNS.keys.select do |k|
+        pattern = DOWNLOAD_PATTERNS[k]
+        # Skip types with notes (they're not really supported)
+        next false if pattern[:note]
+
+        # Test with appropriate namespace for types that need it
+        namespace = if NAMESPACE_REQUIRED_TYPES.include?(k)
+          k == "swift" ? "github.com/test" : "test"
+        end
+        begin
+          result = pattern[:pattern].call(Purl::PackageURL.new(type: k, name: "test", version: "1.0", namespace: namespace))
+          !result.nil?
+        rescue
+          false
+        end
+      end.sort
+    end
+
+    def self.supports?(type)
+      pattern = DOWNLOAD_PATTERNS[type.to_s.downcase]
+      return false unless pattern
+      # Types with base_url are supported, or types that return full URLs (like swift)
+      return true if pattern[:base_url]
+      # Check if this type returns full URLs by testing with a sample
+      return false if pattern[:note] # Has a note means it's not really supported
+      true
+    end
+
+    def initialize(purl)
+      @purl = purl
+    end
+
+    def generate(base_url: nil)
+      unless @purl.version
+        raise MissingVersionError.new(
+          "Download URL requires a version",
+          type: @purl.type
+        )
+      end
+
+      pattern_config = DOWNLOAD_PATTERNS[@purl.type.downcase]
+
+      unless pattern_config
+        raise UnsupportedTypeError.new(
+          "No download URL pattern defined for type '#{@purl.type}'. Supported types: #{self.class.supported_types.join(", ")}",
+          type: @purl.type,
+          supported_types: self.class.supported_types
+        )
+      end
+
+      # Check for repository_url qualifier in the PURL
+      qualifier_base_url = @purl.qualifiers&.dig("repository_url")
+
+      # Generate the path/URL from the pattern
+      path = pattern_config[:pattern].call(@purl)
+
+      if path.nil?
+        raise UnsupportedTypeError.new(
+          "Could not generate download URL for '#{@purl.type}'. #{pattern_config[:note]}",
+          type: @purl.type,
+          supported_types: self.class.supported_types
+        )
+      end
+
+      # If the pattern returns a full URL, use it directly
+      return path if path.start_with?("http://", "https://")
+
+      # For relative paths, we need a base_url
+      effective_base_url = base_url || qualifier_base_url || pattern_config[:base_url]
+
+      unless effective_base_url
+        raise UnsupportedTypeError.new(
+          "Download URLs are not available for type '#{@purl.type}'. #{pattern_config[:note]}",
+          type: @purl.type,
+          supported_types: self.class.supported_types
+        )
+      end
+
+      "#{effective_base_url}/#{path}"
+    end
+
+    attr_reader :purl
+  end
+
+  # Error for missing version
+  class MissingVersionError < Error
+    attr_reader :type
+
+    def initialize(message, type: nil)
+      @type = type
+      super(message)
+    end
+  end
+
+  # Add download URL generation methods to PackageURL
+  class PackageURL
+    def download_url(base_url: nil)
+      DownloadURL.generate(self, base_url: base_url)
+    end
+
+    def supports_download_url?
+      DownloadURL.supports?(type)
+    end
+  end
+end

data/lib/purl/lookup.rb

@@ -3,6 +3,7 @@
 require "net/http"
 require "uri"
 require "json"
+require "timeout"
 
 module Purl
   # Provides lookup functionality for packages using the ecosyste.ms API
@@ -32,28 +33,45 @@ module Purl
     def package_info(purl)
       purl_obj = purl.is_a?(PackageURL) ? purl : PackageURL.parse(purl.to_s)
       
-      # Make API request to ecosyste.ms
+      # Try package lookup first
       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
+      if 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
+        
+        return result
+      end
       
-      package_data = response_data[0]
+      # If no package found, try repository lookup
+      repo_uri = URI("https://repos.ecosyste.ms/api/v1/repositories/lookup")
+      repo_uri.query = URI.encode_www_form({ purl: purl_obj.to_s })
       
-      result = {
-        purl: purl_obj.to_s,
-        package: extract_package_info(package_data)
-      }
+      repo_data = make_request(repo_uri)
       
-      # 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
+      if repo_data
+        result = {
+          purl: purl_obj.to_s,
+          repository: extract_repository_info(repo_data)
+        }
+        
+        return result
       end
       
-      result
+      nil
     end
 
     # Look up version information for a specific version of a package
@@ -102,7 +120,7 @@ module Purl
       end
     rescue JSON::ParserError => e
       raise LookupError, "Failed to parse API response: #{e.message}"
-    rescue Net::TimeoutError, Net::OpenTimeout, Net::ReadTimeout => e
+    rescue Timeout::Error, Net::OpenTimeout, Net::ReadTimeout => e
       raise LookupError, "Request timeout: #{e.message}"
     rescue StandardError => e
       raise LookupError, "Lookup failed: #{e.message}"
@@ -183,6 +201,29 @@ module Purl
         }.compact # Remove nil values
       end
     end
+
+    def extract_repository_info(repo_data)
+      {
+        name: repo_data["name"],
+        full_name: repo_data["full_name"],
+        host: repo_data["host"],
+        description: repo_data["description"],
+        homepage: repo_data["homepage"],
+        url: repo_data["url"],
+        language: repo_data["language"],
+        license: repo_data["license"],
+        fork: repo_data["fork"],
+        archived: repo_data["archived"],
+        stars: repo_data["stargazers_count"],
+        forks: repo_data["forks_count"],
+        open_issues: repo_data["open_issues_count"],
+        default_branch: repo_data["default_branch"],
+        pushed_at: repo_data["pushed_at"],
+        created_at: repo_data["created_at"],
+        updated_at: repo_data["updated_at"],
+        topics: repo_data["topics"]
+      }
+    end
   end
 
   # Error raised when package lookup fails

data/lib/purl/lookup_formatter.rb

@@ -14,6 +14,45 @@ module Purl
     def format_text(lookup_result, purl)
       return "Package not found" unless lookup_result
 
+      if lookup_result[:package]
+        format_package_text(lookup_result, purl)
+      elsif lookup_result[:repository]
+        format_repository_text(lookup_result, purl)
+      else
+        "No information found"
+      end
+    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
+      }
+      
+      if lookup_result[:package]
+        result[:package] = lookup_result[:package]
+        result[:version] = lookup_result[:version] if lookup_result[:version]
+      elsif lookup_result[:repository]
+        result[:repository] = lookup_result[:repository]
+      end
+      
+      result
+    end
+
+    private
+
+    def format_package_text(lookup_result, purl)
       package = lookup_result[:package]
       version_info = lookup_result[:version]
       
@@ -86,27 +125,44 @@ module Purl
       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]
-      }
+    def format_repository_text(lookup_result, purl)
+      repository = lookup_result[:repository]
+      
+      output = []
       
-      result[:version] = lookup_result[:version] if lookup_result[:version]
+      # Repository header - map to package-like format
+      output << "Package: #{repository[:name]} (repository)"
+      output << "#{repository[:description]}" if repository[:description]
       
-      result
+      # Repository stats section (maps to version info)
+      output << ""
+      output << "Version Information:"
+      output << "  Default branch: #{repository[:default_branch]}" if repository[:default_branch]
+      output << "  Last updated: #{repository[:pushed_at]}" if repository[:pushed_at]
+      output << "  Created: #{repository[:created_at]}" if repository[:created_at]
+      
+      # Links section
+      output << ""
+      output << "Links:"
+      output << "  Homepage: #{repository[:homepage]}" if repository[:homepage]
+      output << "  Repository: #{repository[:url]}" if repository[:url]
+      
+      # Package Info section (repository stats)
+      output << ""
+      output << "Package Info:"
+      output << "  Language: #{repository[:language]}" if repository[:language]
+      output << "  License: #{repository[:license]}" if repository[:license]
+      output << "  Stars: #{format_number(repository[:stars])}" if repository[:stars]
+      output << "  Forks: #{format_number(repository[:forks])}" if repository[:forks]
+      output << "  Open issues: #{format_number(repository[:open_issues])}" if repository[:open_issues]
+      output << "  Fork: #{repository[:fork] ? 'Yes' : 'No'}" if !repository[:fork].nil?
+      output << "  Archived: #{repository[:archived] ? 'Yes' : 'No'}" if !repository[:archived].nil?
+      
+      if repository[:topics] && !repository[:topics].empty?
+        output << "  Topics: #{repository[:topics].join(", ")}"
+      end
+      
+      output.join("\n")
     end
 
     private

data/lib/purl/package_url.rb

@@ -390,6 +390,23 @@ module Purl
       lookup_client.package_info(self)
     end
 
+    # Look up security advisories using the advisories.ecosyste.ms API
+    #
+    # @param user_agent [String] User agent string for API requests
+    # @param timeout [Integer] Request timeout in seconds
+    # @return [Array<Hash>] Array of advisory hashes, empty if none found
+    # @raise [AdvisoryError] if the lookup fails due to network or API errors
+    #
+    # @example
+    #   purl = PackageURL.parse("pkg:npm/lodash@4.17.20")
+    #   advisories = purl.advisories
+    #   advisories.each { |adv| puts adv[:title] }
+    def advisories(user_agent: nil, timeout: 10)
+      require_relative "advisory"
+      advisory_client = Advisory.new(user_agent: user_agent, timeout: timeout)
+      advisory_client.lookup(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.5.2"
+  VERSION = "1.7.0"
 end