Add --at flag to outdated command for historical version checks

Author: andrew

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## [Unreleased]
 
+- `--at` flag for `outdated` command to check what was outdated at a specific date or git ref
 - Auto-upgrade outdated database schemas instead of erroring
 - Fix `outdated` command suggesting downgrades when current version is newer than registry
 

README.md

@@ -268,11 +268,15 @@ Shows dependencies sorted by how long since they were last changed in your repo.
 git pkgs outdated               # show packages with newer versions available
 git pkgs outdated --major       # only major version updates
 git pkgs outdated --minor       # minor and major updates (skip patch)
+git pkgs outdated --at v2.0     # what was outdated when we released v2.0?
+git pkgs outdated --at 2024-03-01  # what was outdated on this date?
 git pkgs outdated --stateless   # no database needed
 ```
 
 Checks package registries (via [ecosyste.ms](https://packages.ecosyste.ms/)) to find dependencies with newer versions available. Major updates are shown in red, minor in yellow, patch in cyan.
 
+The `--at` flag enables time travel: pass a date (YYYY-MM-DD) or any git ref (tag, branch, commit SHA) to see what was outdated at that point in time. When given a git ref, it uses the commit's date.
+
 ### Check licenses
 
 ```bash

lib/git/pkgs/commands/outdated.rb

@@ -17,6 +17,13 @@ def initialize(args)
           @options = parse_options
         end
 
+        def parse_date(value)
+          Time.parse(value)
+        rescue ArgumentError
+          # Not a date, will try as git ref in run()
+          value
+        end
+
         def parse_options
           options = {}
 
@@ -51,6 +58,10 @@ def parse_options
               options[:stateless] = true
             end
 
+            opts.on("--at=DATE", "Show what was outdated at DATE (YYYY-MM-DD)") do |v|
+              options[:at] = parse_date(v)
+            end
+
             opts.on("-h", "--help", "Show this help") do
               puts opts
               exit
@@ -73,6 +84,8 @@ def run
             deps = get_dependencies_with_database(repo)
           end
 
+          resolve_at_option(repo) if @options[:at]
+
           if deps.empty?
             empty_result "No dependencies found"
             return
@@ -102,14 +115,19 @@ def run
             }
           end.uniq { |p| p[:purl] }
 
-          enrich_packages(packages_to_check.map { |p| p[:purl] })
+          purls = packages_to_check.map { |p| p[:purl] }
+
+          if @options[:at]
+            enrich_version_history(purls)
+          else
+            enrich_packages(purls)
+          end
 
           outdated = []
           packages_to_check.each do |pkg|
-            db_pkg = Models::Package.first(purl: pkg[:purl])
-            next unless db_pkg&.latest_version
+            latest = get_latest_version(pkg[:purl])
+            next unless latest
 
-            latest = db_pkg.latest_version
             current = pkg[:current_version]
 
             next if current == latest
@@ -141,6 +159,62 @@ def run
           end
         end
 
+        def resolve_at_option(repo)
+          return if @options[:at].is_a?(Time)
+
+          ref = @options[:at].to_s
+          begin
+            sha = repo.rev_parse(ref)
+            commit = repo.lookup(sha)
+            @options[:at] = commit.time
+          rescue Rugged::ReferenceError, Rugged::InvalidError
+            $stderr.puts "Invalid git ref or date: #{ref}. Use YYYY-MM-DD or a valid git ref."
+            exit 1
+          end
+        end
+
+        def get_latest_version(purl)
+          if @options[:at]
+            version = Models::Version.latest_as_of(package_purl: purl, date: @options[:at])
+            version&.version_string
+          else
+            db_pkg = Models::Package.first(purl: purl)
+            db_pkg&.latest_version
+          end
+        end
+
+        def enrich_version_history(purls)
+          client = EcosystemsClient.new
+
+          Spinner.with_spinner("Fetching version history...") do
+            purls.each do |purl|
+              existing_count = Models::Version.where(package_purl: purl)
+                .where(Sequel.~(published_at: nil))
+                .count
+              next if existing_count > 0
+
+              versions = client.lookup_all_versions(purl)
+              next unless versions
+
+              versions.each do |v|
+                next unless v["number"] && v["published_at"]
+
+                version_purl = "#{purl}@#{v["number"]}"
+                version = Models::Version.find_or_create_by_purl(
+                  purl: version_purl,
+                  package_purl: purl
+                )
+                version.update(
+                  published_at: Time.parse(v["published_at"]),
+                  enriched_at: Time.now
+                )
+              end
+            end
+          end
+        rescue EcosystemsClient::ApiError => e
+          $stderr.puts "Warning: Could not fetch version history: #{e.message}" unless Git::Pkgs.quiet
+        end
+
         def enrich_packages(purls)
           packages_by_purl = {}
           purls.each do |purl|

lib/git/pkgs/ecosystems_client.rb

@@ -78,6 +78,36 @@ def bulk_lookup_versions(purls)
         results
       end
 
+      # Lookup all versions for a package by purl.
+      # Returns version history with published_at dates.
+      #
+      # @param purl [String] package URL without version (e.g., "pkg:gem/rails")
+      # @return [Array<Hash>, nil] array of version data or nil if not found
+      def lookup_all_versions(purl)
+        parsed = Purl.parse(purl)
+        base_url = parsed.ecosystems_package_api_url
+        return nil unless base_url
+
+        fetch_all_pages("#{base_url}/versions")
+      rescue Purl::Error
+        nil
+      end
+
+      # Batch lookup all versions for multiple packages.
+      # Currently fetches each package individually.
+      # Designed for future batch API support.
+      #
+      # @param purls [Array<String>] array of package URLs without versions
+      # @return [Hash<String, Array<Hash>>] hash keyed by purl with version arrays
+      def bulk_lookup_all_versions(purls)
+        results = {}
+        purls.each do |purl|
+          data = lookup_all_versions(purl)
+          results[purl] = data if data
+        end
+        results
+      end
+
       private
 
       def fetch_url(url)
@@ -87,6 +117,24 @@ def fetch_url(url)
         execute_request(uri, request)
       end
 
+      def fetch_all_pages(base_url, per_page: 100)
+        results = []
+        page = 1
+
+        loop do
+          url = "#{base_url}?page=#{page}&per_page=#{per_page}"
+          data = fetch_url(url)
+          break unless data.is_a?(Array) && data.any?
+
+          results.concat(data)
+          break if data.length < per_page
+
+          page += 1
+        end
+
+        results.empty? ? nil : results
+      end
+
       def get(path)
         uri = URI("#{API_BASE}#{path}")
         request = Net::HTTP::Get.new(uri)

lib/git/pkgs/models/version.rb

@@ -50,6 +50,29 @@ def self.find_or_create_by_purl(purl:, package_purl:)
 
           create(purl: purl, package_purl: package_purl)
         end
+
+        # Find the latest version of a package that was published before a given date.
+        # Compares versions using semantic versioning.
+        #
+        # @param package_purl [String] base purl without version
+        # @param date [Time] cutoff date
+        # @return [Version, nil] the latest version as of that date
+        def self.latest_as_of(package_purl:, date:)
+          candidates = where(package_purl: package_purl)
+            .where { published_at <= date }
+            .where(Sequel.~(published_at: nil))
+            .all
+
+          return nil if candidates.empty?
+
+          candidates.max_by { |v| parse_semver(v.version_string) }
+        end
+
+        def self.parse_semver(version)
+          cleaned = version.to_s.sub(/^v/i, "")
+          parts = cleaned.split(".").first(3).map(&:to_i)
+          parts + [0] * (3 - parts.length)
+        end
       end
     end
   end

test/git/pkgs/test_ecosystems_client.rb

@@ -116,4 +116,73 @@ def test_api_error_on_timeout
       @client.bulk_lookup(["pkg:gem/rails"])
     end
   end
+
+  def test_lookup_all_versions
+    stub_request(:get, "https://packages.ecosyste.ms/api/v1/registries/rubygems.org/packages/rails/versions?page=1&per_page=100")
+      .to_return(
+        status: 200,
+        body: [
+          { "number" => "7.0.0", "published_at" => "2021-12-15T00:00:00Z" },
+          { "number" => "7.1.0", "published_at" => "2023-10-05T00:00:00Z" }
+        ].to_json,
+        headers: { "Content-Type" => "application/json" }
+      )
+
+    versions = @client.lookup_all_versions("pkg:gem/rails")
+
+    assert_equal 2, versions.size
+    assert_equal "7.0.0", versions[0]["number"]
+    assert_equal "7.1.0", versions[1]["number"]
+  end
+
+  def test_lookup_all_versions_paginates
+    stub_request(:get, "https://packages.ecosyste.ms/api/v1/registries/rubygems.org/packages/rails/versions?page=1&per_page=100")
+      .to_return(
+        status: 200,
+        body: (1..100).map { |i| { "number" => "1.0.#{i}" } }.to_json,
+        headers: { "Content-Type" => "application/json" }
+      )
+
+    stub_request(:get, "https://packages.ecosyste.ms/api/v1/registries/rubygems.org/packages/rails/versions?page=2&per_page=100")
+      .to_return(
+        status: 200,
+        body: [{ "number" => "2.0.0" }].to_json,
+        headers: { "Content-Type" => "application/json" }
+      )
+
+    versions = @client.lookup_all_versions("pkg:gem/rails")
+
+    assert_equal 101, versions.size
+  end
+
+  def test_lookup_all_versions_returns_nil_for_not_found
+    stub_request(:get, %r{packages.ecosyste.ms/api/v1/registries/rubygems.org/packages/nonexistent/versions})
+      .to_return(status: 404)
+
+    result = @client.lookup_all_versions("pkg:gem/nonexistent")
+
+    assert_nil result
+  end
+
+  def test_bulk_lookup_all_versions
+    stub_request(:get, %r{packages.ecosyste.ms/api/v1/registries/rubygems.org/packages/rails/versions})
+      .to_return(
+        status: 200,
+        body: [{ "number" => "7.1.0", "published_at" => "2023-10-05T00:00:00Z" }].to_json,
+        headers: { "Content-Type" => "application/json" }
+      )
+
+    stub_request(:get, %r{packages.ecosyste.ms/api/v1/registries/npmjs.org/packages/lodash/versions})
+      .to_return(
+        status: 200,
+        body: [{ "number" => "4.17.21", "published_at" => "2021-02-20T00:00:00Z" }].to_json,
+        headers: { "Content-Type" => "application/json" }
+      )
+
+    results = @client.bulk_lookup_all_versions(["pkg:gem/rails", "pkg:npm/lodash"])
+
+    assert_equal 2, results.size
+    assert_equal 1, results["pkg:gem/rails"].size
+    assert_equal 1, results["pkg:npm/lodash"].size
+  end
 end