purl 1.5.2 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02f6f258696c085108708cd45f9424357176d9efb2edecac7dac70e85bb2b98a
-  data.tar.gz: 14e4f7a9ad77af4f4ea3d3a6a26041db433271515db710b94129f46af90318c3
+  metadata.gz: 29fc6866f5fbc457ae2e2f29842be73ce8b6a3c5025e6478253294a0ba001443
+  data.tar.gz: a345a99fddde1570eba0a38238848fd92c03b6e314835dc1bc18f98f589c11f8
 SHA512:
-  metadata.gz: 623efd5ec3004f5a8ba188a067a894fd2a666ce2607de4c0243151342504446a551e081834e1692d5c52d24db8aaa37b2aa70c80a22969caf8235205661aa3cb
-  data.tar.gz: 7fa445d38884d3df2537da649fcdcde0ea5a6c57b504d446f2e9c17b8544f160637ea8c8deb1da3879387954ef7384a36a85fbcfd51223f330955ba3ae46ab08
+  metadata.gz: a4196a9cee395fac223edccf0524c7eb297ada80411d658aa6c1ae6827248c48608b41fee66d616b9c5b3f8281d0099dbfaeb223f05b2cfac930bad9067b4c11
+  data.tar.gz: c0580ccb98f4dfb9516879049294c6feb553539d25d43a9f44fef35b9c60bb22857264e934148c11a2532e72149a43c919a0d00bdec4c3e12a965928e17ae140

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2025-10-24
+
+### Added
+- `advisories` command to CLI for looking up security advisories from advisories.ecosyste.ms API
+- `advisories` instance method on `PackageURL` for programmatic advisory retrieval
+
+### Changed
+- Updated to PURL specification v1.1
+
 ## [1.5.2] - 2025-08-06
 
 ### Fixed

data/README.md

@@ -16,10 +16,12 @@ 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
+- **Command-line interface** with parse, validate, convert, generate, info, lookup, and advisories 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
+- **Security advisory lookup** - query security advisories from advisories.ecosyste.ms
+- **Package information lookup** - query package metadata from ecosyste.ms
 - **Type-specific validation** for conan, cran, and swift packages
 - **Registry URL generation** for 20 package ecosystems (npm, gem, maven, pypi, etc.)
 - **Rails-style route patterns** for registry URL templates
@@ -69,6 +71,8 @@ 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
+purl lookup <purl-string>             # Look up package information from ecosyste.ms
+purl advisories <purl-string>         # Look up security advisories from advisories.ecosyste.ms
 ```
 
 ### JSON Output
@@ -78,6 +82,8 @@ All commands support JSON output with the `--json` flag:
 ```bash
 purl --json parse "pkg:gem/rails@7.0.0"
 purl --json info gem
+purl --json lookup "pkg:cargo/rand"
+purl --json advisories "pkg:npm/lodash@4.17.19"
 ```
 
 ### Command Examples
@@ -182,6 +188,104 @@ Total types: 37
 Registry supported: 20
 ```
 
+#### Look Up Package Information
+```bash
+$ purl lookup "pkg:cargo/rand"
+Package: rand (cargo)
+Description: Random number generators and other randomness functionality.
+Homepage: https://rust-random.github.io/book
+Repository: https://github.com/rust-random/rand
+License: MIT OR Apache-2.0
+Downloads: 145,678,901
+Latest Version: 0.8.5
+Published: 2023-01-13T17:47:01.870Z
+
+$ purl --json lookup "pkg:cargo/rand@0.8.5"
+{
+  "success": true,
+  "purl": "pkg:cargo/rand@0.8.5",
+  "package": {
+    "name": "rand",
+    "ecosystem": "cargo",
+    "description": "Random number generators and other randomness functionality.",
+    "homepage": "https://rust-random.github.io/book",
+    "repository_url": "https://github.com/rust-random/rand",
+    "registry_url": "https://crates.io/crates/rand",
+    "licenses": "MIT OR Apache-2.0",
+    "latest_version": "0.8.5",
+    "latest_version_published_at": "2023-01-13T17:47:01.870Z",
+    "versions_count": 89,
+    "maintainers": [
+      {
+        "login": "dhardy",
+        "name": "Diggory Hardy"
+      }
+    ]
+  },
+  "version": {
+    "number": "0.8.5",
+    "published_at": "2023-01-13T17:47:01.870Z",
+    "registry_url": "https://crates.io/crates/rand/0.8.5",
+    "downloads": 5678901,
+    "size": 102400
+  }
+}
+```
+
+#### Look Up Security Advisories
+```bash
+$ purl advisories "pkg:npm/lodash@4.17.19"
+Security Advisories for pkg:npm/lodash@4.17.19
+================================================================================
+
+Advisory #1: Regular Expression Denial of Service (ReDoS) in lodash
+Identifiers: GHSA-x5rq-j2xg-h7qm, CVE-2019-1010266
+Severity: MODERATE
+
+Description:
+  lodash prior to 4.7.11 is affected by: CWE-400: Uncontrolled Resource
+  Consumption. The impact is: Denial of service. The component is: Date
+  handler. The attack vector is: Attacker provides very long strings, which
+  the library attempts to match using a regular expression. The fixed version
+  is: 4.7.11.
+
+Affected Packages:
+  Package: npm/lodash
+  Vulnerable: >= 4.7.0, < 4.17.11
+  Patched: 4.17.11
+
+Source: github | Origin: UNSPECIFIED | Published: 2019-07-19T16:13:07.000Z
+Advisory URL: https://github.com/advisories/GHSA-x5rq-j2xg-h7qm
+
+Total advisories found: 3
+
+$ purl --json advisories "pkg:npm/lodash@4.17.19"
+{
+  "success": true,
+  "purl": "pkg:npm/lodash@4.17.19",
+  "advisories": [
+    {
+      "id": "MDE2OlNlY3VyaXR5QWR2aXNvcnlHSFNBLXg1cnEtajJ4Zy1oN3Ft",
+      "title": "Regular Expression Denial of Service (ReDoS) in lodash",
+      "description": "lodash prior to 4.7.11 is affected by...",
+      "severity": "MODERATE",
+      "url": "https://github.com/advisories/GHSA-x5rq-j2xg-h7qm",
+      "published_at": "2019-07-19T16:13:07.000Z",
+      "affected_packages": [
+        {
+          "ecosystem": "npm",
+          "name": "lodash",
+          "vulnerable_version_range": ">= 4.7.0, < 4.17.11",
+          "first_patched_version": "4.17.11"
+        }
+      ],
+      "identifiers": ["GHSA-x5rq-j2xg-h7qm", "CVE-2019-1010266"]
+    }
+  ],
+  "count": 3
+}
+```
+
 ### Generate Options
 
 The `generate` command supports all PURL components:
@@ -419,6 +523,42 @@ puts info[:reverse_parsing]           # => true
 puts info[:route_patterns]            # => ["https://rubygems.org/gems/:name", ...]
 ```
 
+### Security Advisory Lookup
+
+Look up security advisories for packages using the advisories.ecosyste.ms API:
+
+```ruby
+# Look up advisories for a package
+purl = Purl.parse("pkg:npm/lodash@4.17.19")
+advisories = purl.advisories
+
+# Display advisory information
+advisories.each do |advisory|
+  puts "Title: #{advisory[:title]}"
+  puts "Severity: #{advisory[:severity]}"
+  puts "Description: #{advisory[:description]}"
+  puts "URL: #{advisory[:url]}"
+
+  # Show affected packages
+  advisory[:affected_packages].each do |pkg|
+    puts "  Package: #{pkg[:ecosystem]}/#{pkg[:name]}"
+    puts "  Vulnerable: #{pkg[:vulnerable_version_range]}"
+    puts "  Patched: #{pkg[:first_patched_version]}" if pkg[:first_patched_version]
+  end
+
+  # Show identifiers (CVE, GHSA, etc.)
+  puts "Identifiers: #{advisory[:identifiers].join(', ')}"
+  puts
+end
+
+# Look up advisories for any version of a package
+purl = Purl.parse("pkg:npm/lodash")
+all_advisories = purl.advisories
+
+# Use custom user agent and timeout
+advisories = purl.advisories(user_agent: "my-app/1.0", timeout: 5)
+```
+
 ### Error Handling
 
 ```ruby

data/exe/purl

@@ -44,6 +44,8 @@ class PurlCLI
       info_command(args)
     when "lookup"
       lookup_command(args)
+    when "advisories"
+      advisories_command(args)
     when "--help", "-h", "help"
       puts usage
       exit 0
@@ -64,18 +66,19 @@ class PurlCLI
       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
+        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 [--json] advisories <purl-string>  Look up security advisories from advisories.ecosyste.ms
+        purl --version                          Show version
+        purl --help                             Show this help
 
       Global Options:
-        --json                                Output results in JSON format
+        --json                                  Output results in JSON format
 
       Examples:
         purl parse "pkg:gem/rails@7.0.0"
@@ -86,6 +89,7 @@ class PurlCLI
         purl generate --type gem --name rails --version 7.0.0
         purl --json info gem
         purl lookup "pkg:cargo/rand"
+        purl advisories "pkg:npm/lodash@4.17.20"
     USAGE
   end
 
@@ -430,17 +434,17 @@ class PurlCLI
     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)
@@ -453,15 +457,52 @@ class PurlCLI
           exit 1
         end
       end
-      
+
+    rescue Purl::LookupError => e
+      output_error("Lookup failed: #{e.message}")
+      exit 1
     rescue Purl::Error => e
       output_error("Invalid PURL: #{e.message}")
       exit 1
-    rescue Purl::LookupError => e
+    rescue StandardError => e
       output_error("Lookup failed: #{e.message}")
       exit 1
+    end
+  end
+
+  def advisories_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 advisories method
+      advisories = purl.advisories(user_agent: "purl-ruby-cli/#{Purl::VERSION}")
+
+      # Use formatter to generate output
+      formatter = Purl::AdvisoryFormatter.new
+
+      if @json_output
+        result = formatter.format_json(advisories, purl)
+        puts JSON.pretty_generate(result)
+      else
+        puts formatter.format_text(advisories, purl)
+      end
+
+    rescue Purl::AdvisoryError => e
+      output_error("Advisory lookup failed: #{e.message}")
+      exit 1
+    rescue Purl::Error => e
+      output_error("Invalid PURL: #{e.message}")
+      exit 1
     rescue StandardError => e
-      output_error("Lookup failed: #{e.message}")
+      output_error("Advisory lookup failed: #{e.message}")
       exit 1
     end
   end

data/lib/purl/advisory.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "timeout"
+
+module Purl
+  # Provides advisory lookup functionality for packages using the advisories.ecosyste.ms API
+  class Advisory
+    ADVISORIES_API_BASE = "https://advisories.ecosyste.ms/api/v1"
+
+    # Initialize a new Advisory 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 security advisories for a given PURL
+    #
+    # @param purl [String, PackageURL] PURL string or PackageURL object
+    # @return [Array<Hash>, nil] Array of advisory hashes or nil if none found
+    # @raise [AdvisoryError] if the lookup fails due to network or API errors
+    #
+    # @example
+    #   advisory = Purl::Advisory.new
+    #   advisories = advisory.lookup("pkg:npm/lodash@4.17.20")
+    #   advisories.each { |adv| puts adv[:title] }
+    def lookup(purl)
+      purl_obj = purl.is_a?(PackageURL) ? purl : PackageURL.parse(purl.to_s)
+
+      # Query advisories API
+      uri = URI("#{ADVISORIES_API_BASE}/advisories/lookup")
+      uri.query = URI.encode_www_form({ purl: purl_obj.to_s })
+
+      response_data = make_request(uri)
+
+      if response_data.is_a?(Array) && response_data.length > 0
+        advisories = response_data.map { |advisory_data| extract_advisory_info(advisory_data) }
+
+        # Filter by version if specified
+        if purl_obj.version
+          advisories = filter_by_version(advisories, purl_obj.version)
+        end
+
+        return advisories
+      end
+
+      []
+    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
+        []
+      else
+        raise AdvisoryError, "API request failed with status #{response.code}"
+      end
+    rescue JSON::ParserError => e
+      raise AdvisoryError, "Failed to parse API response: #{e.message}"
+    rescue Timeout::Error, Net::OpenTimeout, Net::ReadTimeout => e
+      raise AdvisoryError, "Request timeout: #{e.message}"
+    rescue StandardError => e
+      raise AdvisoryError, "Advisory lookup failed: #{e.message}"
+    end
+
+    def extract_advisory_info(advisory_data)
+      {
+        id: advisory_data["uuid"],
+        title: advisory_data["title"],
+        description: advisory_data["description"],
+        severity: advisory_data["severity"],
+        cvss_score: advisory_data["cvss_score"],
+        cvss_vector: advisory_data["cvss_vector"],
+        url: advisory_data["url"],
+        repository_url: advisory_data["repository_url"],
+        published_at: advisory_data["published_at"],
+        updated_at: advisory_data["updated_at"],
+        withdrawn_at: advisory_data["withdrawn_at"],
+        source_kind: advisory_data["source_kind"],
+        origin: advisory_data["origin"],
+        classification: advisory_data["classification"],
+        affected_packages: extract_affected_packages(advisory_data["packages"]),
+        references: advisory_data["references"],
+        identifiers: advisory_data["identifiers"]
+      }.compact
+    end
+
+    def extract_affected_packages(packages)
+      return [] unless packages && packages.is_a?(Array)
+
+      packages.map do |pkg|
+        version_info = pkg["versions"]&.first || {}
+        {
+          ecosystem: pkg["ecosystem"],
+          name: pkg["package_name"],
+          purl: pkg["purl"],
+          vulnerable_version_range: version_info["vulnerable_version_range"],
+          first_patched_version: version_info["first_patched_version"]
+        }.compact
+      end
+    end
+
+    def filter_by_version(advisories, version)
+      # For now, return all advisories if version is specified
+      # More sophisticated version range matching could be added later
+      advisories
+    end
+  end
+
+  # Error raised when advisory lookup fails
+  class AdvisoryError < Error
+    def initialize(message)
+      super(message)
+    end
+  end
+end

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/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.6.0"
 end

data/lib/purl.rb

@@ -6,6 +6,8 @@ require_relative "purl/package_url"
 require_relative "purl/registry_url"
 require_relative "purl/lookup"
 require_relative "purl/lookup_formatter"
+require_relative "purl/advisory"
+require_relative "purl/advisory_formatter"
 
 # The main PURL (Package URL) module providing functionality to parse,
 # validate, and generate package URLs according to the PURL specification.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: purl
 version: !ruby/object:Gem::Version
-  version: 1.5.2
+  version: 1.6.0
 platform: ruby
 authors:
 - Andrew Nesbitt
@@ -43,6 +43,8 @@ files:
 - SECURITY.md
 - exe/purl
 - lib/purl.rb
+- lib/purl/advisory.rb
+- lib/purl/advisory_formatter.rb
 - lib/purl/errors.rb
 - lib/purl/lookup.rb
 - lib/purl/lookup_formatter.rb