purl 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29fc6866f5fbc457ae2e2f29842be73ce8b6a3c5025e6478253294a0ba001443
-  data.tar.gz: a345a99fddde1570eba0a38238848fd92c03b6e314835dc1bc18f98f589c11f8
+  metadata.gz: 02a4895e51ce7c9ace65a53d97fd8d4c5d288d7137daa71c9e8b8a778595e6cb
+  data.tar.gz: 55d348a442e23a0ffddc2b236bc1be22c9cf29d8eac0ce3ff289ce637e1ba6f5
 SHA512:
-  metadata.gz: a4196a9cee395fac223edccf0524c7eb297ada80411d658aa6c1ae6827248c48608b41fee66d616b9c5b3f8281d0099dbfaeb223f05b2cfac930bad9067b4c11
-  data.tar.gz: c0580ccb98f4dfb9516879049294c6feb553539d25d43a9f44fef35b9c60bb22857264e934148c11a2532e72149a43c919a0d00bdec4c3e12a965928e17ae140
+  metadata.gz: 4f8ff4ff13c1184c4b1adf6950fc1d04acedb8ce2cbbf4d62f2430455567e98f8b153b5493732919e1921a55132a2f3f51b61157b6eba85e207e6675d8675771
+  data.tar.gz: 9f203b73ef705fe70a27de5aae3b85558bd34204a2362a7429c441dc7f66d4a5ae403741fcb36471ab33e972868e4d31e6121a5eeaf23fb88832e3d38fec1e9c

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-01-02
+
+### Added
+- Download URL generation for 18 package ecosystems
+  - `download_url` instance method on `PackageURL` for getting artifact download URLs
+  - `supports_download_url?` method to check if download URL generation is supported
+  - `Purl.download_supported_types` to list all types with download URL support
+  - `download` command in CLI for getting download URLs from PURLs
+- Supported types: bioconductor, bitbucket, cargo, clojars, cran, elm, gem, github, gitlab, golang, hackage, hex, luarocks, maven, npm, nuget, pub, swift
+- Support for `repository_url` qualifier to use custom registries for downloads
+- Support for custom base URLs via parameter override
+
 ## [1.6.0] - 2025-10-24
 
 ### Added

data/README.md

@@ -16,10 +16,11 @@ This library features comprehensive error handling with namespaced error types,
 
 ## Features
 
-- **Command-line interface** with parse, validate, convert, generate, info, lookup, and advisories commands plus JSON output
+- **Command-line interface** with parse, validate, convert, download, 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
+- **Download URL generation** for 18 package ecosystems (gem, npm, cargo, maven, etc.)
 - **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
@@ -69,6 +70,7 @@ 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 download <purl-string>           # Get download URL for package version
 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
@@ -150,6 +152,26 @@ $ purl --json url "pkg:gem/rails@7.0.0"
 }
 ```
 
+#### Get Download URL
+```bash
+$ purl download "pkg:gem/rails@7.0.0"
+https://rubygems.org/downloads/rails-7.0.0.gem
+
+$ purl download "pkg:npm/@babel/core@7.20.0"
+https://registry.npmjs.org/@babel/core/-/core-7.20.0.tgz
+
+$ purl download "pkg:cargo/serde@1.0.152"
+https://static.crates.io/crates/serde/serde-1.0.152.crate
+
+$ purl --json download "pkg:maven/org.apache.commons/commons-lang3@3.12.0"
+{
+  "success": true,
+  "purl": "pkg:maven/org.apache.commons/commons-lang3@3.12.0",
+  "download_url": "https://repo.maven.apache.org/maven2/org/apache/commons/commons-lang3/3.12.0/commons-lang3-3.12.0.jar",
+  "type": "maven"
+}
+```
+
 #### Generate a PURL
 ```bash
 $ purl generate --type gem --name rails --version 7.0.0
@@ -408,6 +430,42 @@ purl = Purl.parse("pkg:npm/@babel/core@7.0.0")
 puts purl.registry_url                # => "https://www.npmjs.com/package/@babel/core"
 ```
 
+### Download URL Generation
+
+Generate direct download URLs for package artifacts:
+
+```ruby
+# Generate download URLs from PURLs
+purl = Purl.parse("pkg:gem/rails@7.0.0")
+puts purl.download_url  # => "https://rubygems.org/downloads/rails-7.0.0.gem"
+
+# Check if download URL generation is supported
+puts purl.supports_download_url?  # => true
+
+# NPM with scoped packages
+purl = Purl.parse("pkg:npm/@babel/core@7.20.0")
+puts purl.download_url  # => "https://registry.npmjs.org/@babel/core/-/core-7.20.0.tgz"
+
+# Maven packages
+purl = Purl.parse("pkg:maven/org.apache.commons/commons-lang3@3.12.0")
+puts purl.download_url  # => "https://repo.maven.apache.org/maven2/org/apache/commons/commons-lang3/3.12.0/commons-lang3-3.12.0.jar"
+
+# Custom registry via repository_url qualifier
+purl = Purl.parse("pkg:npm/lodash@4.17.21?repository_url=https://npm.mycompany.com")
+puts purl.download_url  # => "https://npm.mycompany.com/lodash/-/lodash-4.17.21.tgz"
+
+# Custom registry via parameter
+purl = Purl.parse("pkg:gem/rails@7.0.0")
+puts purl.download_url(base_url: "https://gems.internal.com/downloads")
+# => "https://gems.internal.com/downloads/rails-7.0.0.gem"
+
+# Get list of supported types
+puts Purl.download_supported_types
+# => ["bioconductor", "bitbucket", "cargo", "clojars", "cran", "elm", "gem",
+#     "github", "gitlab", "golang", "hackage", "hex", "luarocks", "maven",
+#     "npm", "nuget", "pub", "swift"]
+```
+
 ### Reverse Parsing: Registry URLs to PURLs
 
 ```ruby
@@ -501,6 +559,7 @@ puts Purl.known_types.include?("gem") # => true
 puts Purl.known_type?("gem")                    # => true
 puts Purl.registry_supported_types              # => ["cargo", "gem", "maven", "npm", ...]
 puts Purl.reverse_parsing_supported_types       # => ["bioconductor", "cargo", "clojars", ...]
+puts Purl.download_supported_types              # => ["cargo", "gem", "maven", "npm", ...]
 
 # Get default registry for a type
 puts Purl.default_registry("gem")               # => "https://rubygems.org"
@@ -520,6 +579,7 @@ puts info[:default_registry]          # => "https://rubygems.org"
 puts info[:examples]                  # => ["pkg:gem/rails@7.0.4", ...]
 puts info[:registry_url_generation]   # => true
 puts info[:reverse_parsing]           # => true
+puts info[:download_url_generation]   # => true
 puts info[:route_patterns]            # => ["https://rubygems.org/gems/:name", ...]
 ```
 
@@ -610,6 +670,26 @@ The library supports 37 package types (32 official + 5 additional ecosystems):
 **Reverse Parsing (20 types):**
 - `bioconductor`, `cargo`, `clojars`, `cocoapods`, `composer`, `conda`, `cpan`, `deno`, `elm`, `gem`, `golang`, `hackage`, `hex`, `homebrew`, `maven`, `npm`, `nuget`, `pub`, `pypi`, `swift`
 
+**Download URL Generation (18 types):**
+- `bioconductor` - bioconductor.org/packages/release/bioc/src/contrib
+- `bitbucket` - bitbucket.org archive downloads
+- `cargo` - static.crates.io/crates
+- `clojars` - repo.clojars.org (Maven-style)
+- `cran` - cran.r-project.org/src/contrib
+- `elm` - GitHub archive downloads
+- `gem` - rubygems.org/downloads
+- `github` - GitHub archive downloads
+- `gitlab` - GitLab archive downloads
+- `golang` - proxy.golang.org
+- `hackage` - hackage.haskell.org/package
+- `hex` - repo.hex.pm/tarballs
+- `luarocks` - luarocks.org/manifests
+- `maven` - repo.maven.apache.org/maven2
+- `npm` - registry.npmjs.org
+- `nuget` - api.nuget.org/v3-flatcontainer
+- `pub` - pub.dev/packages
+- `swift` - GitHub/GitLab/Bitbucket (derived from namespace)
+
 **All 37 Supported Types:**
 `alpm`, `apk`, `bioconductor`, `bitbucket`, `bitnami`, `cargo`, `clojars`, `cocoapods`, `composer`, `conan`, `conda`, `cpan`, `cran`, `deb`, `deno`, `docker`, `elm`, `gem`, `generic`, `github`, `golang`, `hackage`, `hex`, `homebrew`, `huggingface`, `luarocks`, `maven`, `mlflow`, `npm`, `nuget`, `oci`, `pub`, `pypi`, `qpkg`, `rpm`, `swid`, `swift`
 

data/exe/purl

@@ -40,6 +40,8 @@ class PurlCLI
       generate_command(args)
     when "url"
       url_command(args)
+    when "download"
+      download_command(args)
     when "info"
       info_command(args)
     when "lookup"
@@ -70,6 +72,7 @@ class PurlCLI
         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] download <purl-string>    Get download URL for package version
         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
@@ -277,6 +280,73 @@ class PurlCLI
     end
   end
 
+  def download_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_download_url?
+        if @json_output
+          result = {
+            success: false,
+            purl: purl_string,
+            error: "Download URL generation not supported for type '#{purl.type}'",
+            supported_types: Purl.download_supported_types
+          }
+          puts JSON.pretty_generate(result)
+        else
+          puts "Error: Download URL generation not supported for type '#{purl.type}'"
+          puts "Supported types: #{Purl.download_supported_types.join(', ')}"
+        end
+        exit 1
+      end
+
+      download_url = purl.download_url
+
+      if @json_output
+        result = {
+          success: true,
+          purl: purl.to_s,
+          download_url: download_url,
+          type: purl.type
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts download_url
+      end
+    rescue Purl::MissingVersionError => e
+      if @json_output
+        result = {
+          success: false,
+          purl: purl_string,
+          error: "Version required for download URL"
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Error: Version required for download URL"
+      end
+      exit 1
+    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|

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/version.rb

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

data/lib/purl.rb

@@ -4,6 +4,7 @@ require_relative "purl/version"
 require_relative "purl/errors"
 require_relative "purl/package_url"
 require_relative "purl/registry_url"
+require_relative "purl/download_url"
 require_relative "purl/lookup"
 require_relative "purl/lookup_formatter"
 require_relative "purl/advisory"
@@ -102,6 +103,17 @@ module Purl
     RegistryURL.supported_reverse_types
   end
 
+  # Returns types that have download URL support
+  #
+  # @return [Array<String>] sorted array of types that can generate download URLs
+  #
+  # @example
+  #   types = Purl.download_supported_types
+  #   puts types.include?("gem")  # true if gem has download URL support
+  def self.download_supported_types
+    DownloadURL.supported_types
+  end
+
   # Check if a type is known/valid
   #
   # @param type [String, Symbol] the type to check
@@ -140,6 +152,7 @@ module Purl
       examples: type_examples(normalized_type),
       registry_url_generation: RegistryURL.supports?(normalized_type),
       reverse_parsing: RegistryURL.supported_reverse_types.include?(normalized_type),
+      download_url_generation: DownloadURL.supports?(normalized_type),
       route_patterns: RegistryURL.route_patterns_for(normalized_type)
     }
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: purl
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Andrew Nesbitt
@@ -45,6 +45,7 @@ files:
 - lib/purl.rb
 - lib/purl/advisory.rb
 - lib/purl/advisory_formatter.rb
+- lib/purl/download_url.rb
 - lib/purl/errors.rb
 - lib/purl/lookup.rb
 - lib/purl/lookup_formatter.rb
@@ -74,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.1
 specification_version: 4
 summary: Parse and convert package urls (purls)
 test_files: []