libyear-rb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 780ffd231f0123d3d93b819886b7ec1bf90100c93a53b9a87eb3ff9028178392
-  data.tar.gz: 7b4405cfbde73ffa056506087378ff45b794fe93c102933ccb202209e087c7db
+  metadata.gz: 199716d9e9d674a6b897277931b9cecaa3a762807da3341ff13bdd3b865d1587
+  data.tar.gz: e430a6dbb744e921f27a3218e1c31eaa5de9726beece1a07e7dfdc6890013d27
 SHA512:
-  metadata.gz: 282f83a4874582c3d835cc8d9c5fb89eb7ac6e27c122fc4f8e82e9e10da007970e9806de21ca8e64d7ae1766cca222356f4f68737923845a940c0def7a9fb6df
-  data.tar.gz: d3da23dc71125df5adeb55769624d82ead4642b97ac23c1931c355c264b4c803066758c625666c6a8b68f364d827a6029c2912508e45819ef3b6b575f0d2397a
+  metadata.gz: 43697c73f71080fceeec2b4c433f326b693c17e47a9b2496e714ae9e58b1ee74f7a0efbeec7dbd70ea329ed09646e81b248df0ba01dc7d1372ebd7845f0aab33
+  data.tar.gz: 1c7be9d76720da7a6992f7b0d028d0e6d7285209c80d657a8fba2611a831a7e1203265bff85cfa8d0e8aa6c399fc6f9aa487415fc39c555575391a67cccfed5c

data/.github/workflows/release.yml

@@ -2,8 +2,9 @@ name: Release Gem
 
 on:
   push:
-    tags:
-      - 'v*'
+    branches: main
+    paths: lib/libyear_rb/version.rb
+  workflow_dispatch:
 
 jobs:
   release:

data/CHANGELOG.md

@@ -2,7 +2,26 @@
 
 ## [Unreleased]
 
-## [0.1.0] - 2025-01-09
+## [0.2.0] - 2026-08-19
+
+### Added
+
+- The report can now be generated in JSON with the `--format json` flag
+- The `--sort` flag orders the output by column values (default: `libyear,name`)
+- The `--[no-]indirect` flag includes (default) or excludes indirect dependencies in the output
+- A library API (`LibyearRb::Runner`) has been extracted for programmatic/scripting use
+
+### Changed
+
+- All results are now sent to formatters, so the report can include both outdated and up-to-date gems
+- Gem version metadata is fetched in parallel with per-host worker pools
+
+### Fixed
+
+- When `XDG_CACHE_HOME` is set, the cache directory resolves as a `Pathname` instead of a `String`
+- Fetch failures are rescued per dependency, so one error no longer crashes the report
+
+## [0.1.0] - 2026-01-09
 
 ### Added
 

data/README.md

@@ -1,42 +1,37 @@
 # libyear-rb
 
-A simple measure of dependency freshness for Ruby apps.
-
-```bash
-$ libyear-rb
-Gem                  Current Current Date Latest   Latest Date Versions Days Years
-.................... ....... ............ ........ ........... ........ .... .....
-addressable          2.8.7   2024-06-21   2.8.8    2025-11-25         1  522  1.43
-bigdecimal           3.3.1   2025-10-09   4.0.1    2025-12-17         4   69  0.19
-rails                7.0.0   2021-12-15   7.2.0    2024-08-10        15  968  2.65
-System is 4.27 libyears behind
-Total releases behind: 20
-```
-
-`libyear-rb` tells you how out-of-date your Gemfile.lock is, in libyears (the time between your installed version and the newest version).
-
-## Features
-
-- Analyzes Gemfile.lock to measure dependency freshness
-- Reports libyears (time behind) and version distance (releases behind)
-- Supports any RubyGems.org-compatible gem server (private gem servers, mirrors, etc.)
-- Historical analysis with `--as-of` to see what your dependencies looked like at a specific date
-- Caches API responses to minimize network requests
+A measure of dependency freshness for Gemfile.lock. Tells you how out-of-date your dependencies are, in [libyears](https://libyear.com/) by comparing the release date of the locked version to the latest available version.
 
 ## Installation
 
+To use the CLI, install the gem:
+
 ```bash
 gem install libyear-rb
 ```
 
-Or add to your Gemfile:
+```bash
+mise install gem:libyear-rb
+```
+
+To use programmatically, add to your Gemfile:
 
 ```ruby
 gem "libyear-rb"
 ```
 
+```ruby
+require "bundler/inline"
+gemfile do
+  source "https://rubygems.org"
+  gem "libyear-rb"
+end
+```
+
 ## Usage
 
+### As a CLI
+
 Run `libyear-rb` in a directory with a Gemfile.lock, or provide a path:
 
 ```bash
@@ -44,65 +39,118 @@ libyear-rb                      # Uses ./Gemfile.lock
 libyear-rb path/to/Gemfile.lock # Uses specified lockfile
 ```
 
-### Options
+```
+Gem                  Current Current Date Latest   Latest Date Versions Days Years
+.................... ....... ............ ........ ........... ........ .... .....
+addressable          2.8.7   2024-06-21   2.8.8    2025-11-25         1  522  1.43
+bigdecimal           3.3.1   2025-10-09   4.0.1    2025-12-17         4   69  0.19
+rails                7.0.0   2021-12-15   7.2.0    2024-08-10        15  968  2.65
+System is 4.27 libyears behind
+Total releases behind: 20
+```
+
+Options:
 
 ```
---as-of DATE    Analyze dependencies as of the given date (YYYY-MM-DD)
---verbose       Run with verbose logs
---help          Show help
---version       Show version
+--as-of DATE        Only consider versions released before DATE (YYYY-MM-DD)
+--format FORMATTER  Choose an output formatter (plaintext, json) (default: plaintext)
+--sort SPEC         Sort by comma-separated columns (default: libyear,name)
+--[no-]indirect     Include indirect dependencies in output (on by default)
+--verbose           Run with logs
+--help              Show help
+--version           Show version
+```
+
+#### Sorting
+
+The `--sort` flag accepts a comma-separated list of columns. Each column has a
+fixed direction: `name` is ascending, while `latest-date`, `versions`, and
+`libyear` are descending. Later columns are used to break ties.
+
+```bash
+libyear-rb --sort versions,name   # most releases behind first, then by name
+libyear-rb --sort libyear         # most libyears behind first
 ```
 
-### Historical Analysis
+#### Formatters
 
-You can analyze what your dependencies looked like at a specific point in time:
+- `plaintext` (default) — prints a human-readable table to stdout, listing only outdated gems.
+- `json` — prints a machine-readable JSON document to stdout, listing every gem along with a summary.
 
 ```bash
-libyear-rb --as-of 2024-01-01
+libyear-rb --format json
+```
+
+### As a Library
+
+```ruby
+require "libyear_rb"
+
+results = LibyearRb::Runner.new.run(File.read("Gemfile.lock"))
+
+results.each do |r|
+  puts "#{r.name}: #{r.version_distance} versions, #{r.libyear_in_days} days behind"
+end
+```
+
+Configure the cache or logger before use:
+
+```ruby
+LibyearRb.cache = LibyearRb::FileCache.new(skip_cache: true)
+LibyearRb.logger = Logger.new($stderr)
 ```
 
 ## Private Gem Servers
 
-`libyear-rb` supports any gem server with a RubyGems.org-compatible API. It uses your configured gem sources from `~/.gemrc` or environment, so private gems hosted on servers like Gemfury, Artifactory, or self-hosted solutions work automatically.
+`libyear-rb` supports any gem server with a RubyGems.org-compatible API. It uses your configured gem sources from `~/.gemrc` (`gem sources`) or environment, so private gems hosted on servers like Gemfury, Artifactory, or self-hosted solutions work automatically.
 
 ## Caching
 
 To reduce API requests and improve performance, `libyear-rb` caches gem version metadata for 24 hours.
 
-**Cache location:**
-- Uses `$XDG_CACHE_HOME/libyear-rb/` if `XDG_CACHE_HOME` is set
-- Otherwise defaults to `~/.cache/libyear-rb/`
-
-Cache files are organized by gem source host, so metadata from different gem servers is stored separately.
+Cache location:
+- Gem info is cached under `$XDG_CACHE_HOME/libyear-rb/` (or `~/.cache/libyear-rb/` if `XDG_CACHE_HOME` is not set), with a subdirectory for each gem host.
 
-**To skip the cache:**
+To skip the cache:
 ```bash
 SKIP_CACHE=1 libyear-rb
 ```
 
-**To clear the cache:**
+To clear the cache:
 ```bash
 rm -rf ~/.cache/libyear-rb
 ```
 
-## Alternatives
+## Development
 
-Other Ruby tools for measuring dependency freshness:
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. 
 
-- [libyear-bundler](https://github.com/jaredbeck/libyear-bundler) - The original Ruby libyear implementation. Supports additional metrics like major/minor/patch version deltas and JSON output.
-- [bundler-audit](https://github.com/rubysec/bundler-audit) - Focuses on security vulnerabilities rather than freshness, but useful for dependency health.
-- [bundle outdated](https://bundler.io/man/bundle-outdated.1.html) - Built into Bundler. Shows outdated gems but doesn't calculate libyears.
+### Commands
 
-## Development
+```bash
+# Setup development environment
+bin/setup
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt.
+# Run tests
+rake test
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+# Run linter
+rake rubocop
+
+# Install gem locally
+bundle exec rake install
+```
 
 ## Acknowledgements
 
 The concept of libyear comes from the technical report "Measuring Dependency Freshness in Software Systems" by J. Cox, E. Bouwers, M. van Eekelen and J. Visser (ICSE 2015).
 
+## Alternatives
+
+- [libyear-bundler](https://github.com/jaredbeck/libyear-bundler) - The original Ruby libyear implementation. Supports additional metrics like major/minor/patch version deltas and JSON output.
+- [bundler-audit](https://github.com/rubysec/bundler-audit) - Focuses on security vulnerabilities rather than freshness.
+- [bundle outdated](https://bundler.io/man/bundle-outdated.1.html) - Built into Bundler. Shows outdated gems but doesn't calculate libyears.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/exe/libyear-rb

@@ -2,5 +2,9 @@
 # frozen_string_literal: true
 
 require "libyear_rb"
+require "libyear_rb/cli"
+
+$stdout.sync = true
+$stderr.sync = true
 
 LibyearRb::CLI.new(ARGV).run

data/lib/libyear_rb/cli.rb

@@ -8,38 +8,26 @@ module LibyearRb
   class CLI
     def initialize(argv = ARGV)
       @argv = argv.dup
-      @options = {}
+      @options = {
+        formatter: Formatter.for("plaintext"),
+        indirect: true,
+        sorters: Sorter.parse(Sorter::DEFAULT_SPEC)
+      }
       parse_options!
     end
 
     def run
+      LibyearRb.logger = Logger.new($stderr) if @options[:verbose]
+
       lockfile_contents = read_lockfile
-      logger = build_logger
-
-      lockfile_parser = LockfileParser.new
-      gem_info_fetcher = GemInfoFetcher.new
-      dependency_analyzer = DependencyAnalyzer.new(logger: logger)
-      reporter = PlaintextReporter.new
-
-      runner = Runner.new(
-        lockfile_parser: lockfile_parser,
-        gem_info_fetcher: gem_info_fetcher,
-        dependency_analyzer: dependency_analyzer,
-        reporter: reporter,
-        logger: logger
-      )
-
-      runner.run(lockfile_contents, as_of: @options[:as_of])
+      results = Runner.new.run(lockfile_contents, as_of: @options[:as_of])
+      sorted_results = Sorter.sort(results, @options.fetch(:sorters))
+
+      @options.fetch(:formatter).new(indirect: @options.fetch(:indirect)).generate(sorted_results)
     end
 
     private
 
-    def build_logger
-      return nil unless @options[:verbose]
-
-      Logger.new($stderr)
-    end
-
     def parse_options!
       OptionParser.new do |opts|
         opts.banner = "Usage: libyear-rb [Gemfile.lock] [options]"
@@ -63,6 +51,25 @@ module LibyearRb
           exit 1
         end
 
+        opts.on("-f", "--format FORMATTER", "Choose an output formatter (#{Formatter::NAMES.join(", ")}) (default: plaintext).") do |name|
+          @options[:formatter] = Formatter.for(name)
+        rescue ArgumentError => e
+          warn e.message
+          exit 1
+        end
+
+        opts.on("--sort SPEC",
+          "Sort by comma-separated columns (#{Sorter::COLUMNS.keys.join(", ")}) (default: #{Sorter::DEFAULT_SPEC}).") do |spec|
+          @options[:sorters] = Sorter.parse(spec)
+        rescue Sorter::InvalidSpec => e
+          warn e.message
+          exit 1
+        end
+
+        opts.on("--[no-]indirect", "Include indirect dependencies in output (on by default).") do |value|
+          @options[:indirect] = value
+        end
+
         opts.on("--verbose", "Run with verbose logs") do
           @options[:verbose] = true
         end

data/lib/libyear_rb/dependency_analyzer.rb

@@ -2,15 +2,11 @@
 
 module LibyearRb
   class DependencyAnalyzer
-    def initialize(logger: nil)
-      @logger = logger
-    end
-
-    def calculate_dependency_freshness(gem_name, gem_version, versions_metadata)
-      current_version_info = versions_metadata.find { |version| version.number == gem_version }
+    def self.freshness(spec, versions_metadata)
+      current_version_info = versions_metadata.find { |version| version.number == spec.version }
 
       if current_version_info.nil?
-        @logger&.warn("Skipping #{gem_name}: installed version #{gem_version} not found in metadata")
+        LibyearRb.logger.warn("Skipping #{spec.name}: installed version #{spec.version} not found in metadata")
         return
       end
 
@@ -23,10 +19,6 @@ module LibyearRb
       latest_version = latest_version_info.number
       current_version = current_version_info.number
 
-      if latest_version == current_version
-        return nil
-      end
-
       latest_release_date = latest_version_info.created_at
       current_release_date = current_version_info.created_at
 
@@ -34,14 +26,14 @@ module LibyearRb
       libyear_in_days = [(latest_release_date - current_release_date).to_i, 0].max
 
       Result.new(
-        name: gem_name,
-        current_version: gem_version,
+        name: spec.name,
+        current_version: spec.version,
         current_version_release_date: current_release_date,
         latest_version: latest_version,
         latest_version_release_date: latest_release_date,
         version_distance: version_distance,
         libyear_in_days: libyear_in_days,
-        is_direct: true
+        is_direct: spec.direct
       )
     end
   end

data/lib/libyear_rb/file_cache.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module LibyearRb
+  class FileCache
+    CACHE_EXPIRATION = 86_400 # 24 hours in seconds
+    CACHE_DIR_ROOT = ENV.fetch("XDG_CACHE_HOME", File.join(Dir.home, ".cache"))
+    CACHE_DIR_DEFAULT = File.join(CACHE_DIR_ROOT, "libyear-rb")
+    SKIP_CACHE = ENV.fetch("SKIP_CACHE", "0") == "1"
+
+    attr_reader :cache_dir
+
+    def initialize(cache_dir: CACHE_DIR_DEFAULT, skip_cache: SKIP_CACHE)
+      @cache_dir = Pathname.new(cache_dir)
+      @skip_cache = skip_cache
+    end
+
+    def fetch(remote_host, gem_name)
+      return yield if @skip_cache
+
+      path = cache_file_path(remote_host, gem_name)
+      if cache_valid?(path)
+        JSON.parse(path.read)
+      else
+        data = yield
+        return data if data.empty?
+
+        path.dirname.mkpath
+        path.write(JSON.dump(data))
+        path.utime(Time.now, Time.now)
+        data
+      end
+    end
+
+    private
+
+    def cache_valid?(path)
+      return false unless path.exist?
+
+      cache_age = Time.now - path.mtime
+      cache_age < CACHE_EXPIRATION
+    end
+
+    def cache_file_path(remote_host, gem_name)
+      host_key = remote_host.gsub(/\W/, "_")
+      cache_dir.join(host_key, "#{gem_name}.json")
+    end
+  end
+end

data/lib/libyear_rb/formatters/formatter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module LibyearRb
+  class Formatter
+    NAMES = %w[plaintext json].freeze
+
+    class << self
+      def for(name)
+        case name
+        when "plaintext"
+          require "libyear_rb/formatters/plaintext_formatter"
+          PlaintextFormatter
+        when "json"
+          require "libyear_rb/formatters/json_formatter"
+          JsonFormatter
+        else
+          raise ArgumentError, "Unknown formatter: #{name.inspect}. Available formatters: #{NAMES.join(", ")}."
+        end
+      end
+    end
+
+    def initialize(io: $stdout, indirect: true)
+      @io = io
+      @indirect = indirect
+    end
+
+    def generate(results)
+      raise NotImplementedError, "Subclasses must implement the generate method"
+    end
+  end
+end

data/lib/libyear_rb/formatters/json_formatter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LibyearRb
+  class JsonFormatter < Formatter
+    def generate(results)
+      total_days = results.sum { |r| r.libyear_in_days || 0 }
+      total_versions = results.sum { |r| r.version_distance || 0 }
+
+      visible_results = @indirect ? results : results.select(&:is_direct)
+
+      payload = {
+        gems: visible_results.map { |result| gem_hash(result) },
+        summary: {
+          libyears_behind: (total_days / 365.0).round(2),
+          total_releases_behind: total_versions
+        }
+      }
+
+      @io.puts JSON.pretty_generate(payload)
+    end
+
+    private
+
+    def gem_hash(result)
+      {
+        name: result.name.to_s,
+        current_version: result.current_version&.to_s,
+        current_version_release_date: result.current_version_release_date&.strftime("%Y-%m-%d"),
+        latest_version: result.latest_version&.to_s,
+        latest_version_release_date: result.latest_version_release_date&.strftime("%Y-%m-%d"),
+        version_distance: result.version_distance,
+        libyear_in_days: result.libyear_in_days,
+        direct: result.is_direct
+      }
+    end
+  end
+end

data/lib/libyear_rb/{reporters/plaintext_reporter.rb → formatters/plaintext_formatter.rb}

@@ -1,25 +1,29 @@
 # frozen_string_literal: true
 
 module LibyearRb
-  class PlaintextReporter < Reporter
+  class PlaintextFormatter < Formatter
     UNKNOWN = "Unknown"
     COLUMN_BUFFER = 3
     HEADERS = ["Gem", "Current", "Current Date", "Latest", "Latest Date", "Versions", "Days", "Years"].freeze
 
     def generate(results)
-      rows = results.sort_by(&:name).filter_map do |result|
-        row_for(result) unless result.version_distance.zero?
+      total_days = results.sum { |r| r.libyear_in_days || 0 }
+      total_versions = results.sum { |r| r.version_distance || 0 }
+
+      visible_results = @indirect ? results : results.select(&:is_direct)
+      visible_results = visible_results.reject do |result|
+        result.version_distance.zero?
       end
 
-      return if rows.empty?
+      return if visible_results.empty?
+
+      rows = visible_results.map { |result| row_for(result) }
 
       widths = calculate_widths(rows)
       @io.puts format_row(HEADERS, widths)
       @io.puts divider(widths)
       rows.each { |row| @io.puts format_row(row, widths) }
 
-      total_days = results.sum { |r| r.libyear_in_days || 0 }
-      total_versions = results.sum { |r| r.version_distance || 0 }
       @io.puts "System is %.2f libyears behind" % (total_days / 365.0)
       @io.puts "Total releases behind: #{total_versions}"
     end

data/lib/libyear_rb/gem_info_fetcher.rb

@@ -1,80 +1,52 @@
 # frozen_string_literal: true
 
-require "gems"
 require "date"
+require "gems"
 require "rubygems"
 
 module LibyearRb
   class GemInfoFetcher
-    include GemInfoCacher
-
-    RATE_LIMIT = 10 # https://guides.rubygems.org/rubygems-org-rate-limits/
-    RATE_LIMIT_INTERVAL = 1.0 / RATE_LIMIT
-
-    def initialize
-      @gem_source_clients = {}
-      @last_request_time = Hash.new { |hash, key| hash[key] = Time.now - RATE_LIMIT_INTERVAL }
+    def initialize(remote_host, rate_limiter: -> {})
+      @remote_host = remote_host
+      @rate_limiter = rate_limiter
+      source = Gem.sources.each_source.find { |s| s.uri.host == remote_host }
+      if source
+        uri = source.uri
+        @client = Gems::Client.new(
+          host: uri.origin + uri.request_uri,
+          username: uri.user,
+          password: uri.password
+        )
+      end
     end
 
-    def gem_versions_for(gem_name, remote_host)
-      client = client_for(remote_host)
-      return [] unless client
+    def versions_for(gem_name)
+      return [] unless @client
 
-      raw_versions = fetch_raw_versions(client, remote_host, gem_name)
-      build_versions(gem_name, raw_versions)
+      raw = fetch_raw(gem_name)
+      parse_versions(gem_name, raw)
     end
 
     private
 
-    def fetch_raw_versions(client, remote_host, gem_name)
-      with_cache(remote_host, gem_name) do
-        wait_for_rate_limit(remote_host)
-
-        client.versions(gem_name)
+    def fetch_raw(gem_name)
+      LibyearRb.cache.fetch(@remote_host, gem_name) do
+        @rate_limiter.call
+        Array(@client.versions(gem_name))
       rescue Gems::GemError, Gems::NotFound
         []
       end
     end
 
-    def build_versions(gem_name, raw_versions)
-      Array(raw_versions)
-        .map do |attributes|
-          GemVersion.new(
-            name: gem_name,
-            number: Gem::Version.new(attributes["number"]),
-            created_at: Date.parse(attributes["created_at"]),
-            prerelease?: attributes["prerelease"]
-          )
-        end
-    end
-
-    def client_for(remote_host)
-      return @gem_source_clients[remote_host] if @gem_source_clients.key?(remote_host)
-
-      client = nil
-      source = sources.find { |gem_source| gem_source.uri.host == remote_host }
-
-      if source
-        uri = source.uri
-        client = Gems::Client.new(
-          host: (uri.origin + uri.request_uri),
-          username: uri.user,
-          password: uri.password
+    def parse_versions(gem_name, raw_versions)
+      Array(raw_versions).map do |attrs|
+        GemVersion.new(
+          name: gem_name,
+          number: Gem::Version.new(attrs["number"]),
+          created_at: Date.parse(attrs["created_at"]),
+          prerelease?: attrs["prerelease"]
         )
       end
-
-      @gem_source_clients[remote_host] = client
-    end
-
-    def sources
-      @sources ||= Gem.sources.each_source.to_a
-    end
-
-    def wait_for_rate_limit(remote_host)
-      now = Time.now
-      elapsed = now - @last_request_time[remote_host]
-      sleep(RATE_LIMIT_INTERVAL - elapsed) if elapsed < RATE_LIMIT_INTERVAL
-      @last_request_time[remote_host] = Time.now
     end
   end
 end

data/lib/libyear_rb/lockfile_parser.rb

@@ -25,6 +25,10 @@ module LibyearRb
     VERSION_LINE = /^   ?([^ ].+)$/
     BUNDLED_VERSION = /^   ?([^ ].+)$/
 
+    def self.parse(lockfile_content)
+      new.parse(lockfile_content)
+    end
+
     def parse(lockfile_content)
       lines = lockfile_content.lines(chomp: true)
 
@@ -58,6 +62,13 @@ module LibyearRb
         end
       end
 
+      direct_names = dependencies.map(&:name)
+      sources = sources.map do |source|
+        source.with(specs: source.specs.map { |spec|
+          spec.with(direct: direct_names.include?(spec.name))
+        })
+      end
+
       Lockfile.new(
         sources: sources,
         platforms: platforms,

data/lib/libyear_rb/models.rb

@@ -3,7 +3,11 @@
 module LibyearRb
   Lockfile = Data.define(:sources, :platforms, :dependencies, :ruby_version, :bundled_with)
   Source = Data.define(:type, :remote, :revision, :specs, :options)
-  Spec = Data.define(:name, :version, :dependencies)
+  Spec = Data.define(:name, :version, :dependencies, :direct) do
+    def initialize(name:, version:, dependencies: [], direct: false)
+      super
+    end
+  end
   Dependency = Data.define(:name, :version_requirements)
   Platform = Data.define(:name)
   RubyVersion = Data.define(:version, :engine, :patchlevel)

data/lib/libyear_rb/runner.rb

@@ -4,44 +4,80 @@ require "uri"
 
 module LibyearRb
   class Runner
-    def initialize(lockfile_parser:, gem_info_fetcher:, dependency_analyzer:, reporter:, logger: nil)
-      @lockfile_parser = lockfile_parser
-      @gem_info_fetcher = gem_info_fetcher
-      @dependency_analyzer = dependency_analyzer
-      @reporter = reporter
-      @logger = logger
-    end
+    MAX_WORKERS_PER_HOST = 10
+    RATE_LIMIT = 10 # requests per second per host
 
     def run(lockfile_contents, as_of: nil)
-      results = []
-      lockfile = @lockfile_parser.parse(lockfile_contents)
-      lockfile.sources.each do |source|
-        unless source.type == :gem && !source.remote.nil?
-          @logger&.warn("Skipping source #{source.type}: unsupported source type or missing remote")
-          next
-        end
+      specs_by_host = parse_specs(lockfile_contents)
+      threads = []
+      replenishers = []
 
-        remote_host = URI.parse(source.remote).host
+      specs_by_host.each do |host, specs|
+        token_queue = Thread::SizedQueue.new(RATE_LIMIT)
+        rate_limiter = -> { token_queue.pop }
 
-        source.specs.each do |spec|
-          gem_name = spec.name
-          gem_version = spec.version
-          versions_metadata = @gem_info_fetcher.gem_versions_for(gem_name, remote_host)
-            .reject { |version| as_of && version.created_at > as_of }
-            .sort_by(&:number)
-            .reverse
+        work_queue = Thread::Queue.new
+        specs.each { |spec| work_queue << spec }
+        work_queue.close
 
-          if versions_metadata.empty?
-            @logger&.warn("Skipping #{gem_name}: no version metadata from #{remote_host}")
-            next
+        replenishers << Thread.new do
+          loop do
+            sleep(1.0 / RATE_LIMIT)
+            token_queue << :token
           end
+        end
 
-          result = @dependency_analyzer.calculate_dependency_freshness(gem_name, gem_version, versions_metadata)
-          results << result if result
+        [specs.size, MAX_WORKERS_PER_HOST].min.times do
+          threads << Thread.new do
+            fetcher = GemInfoFetcher.new(host, rate_limiter: rate_limiter)
+            thread_results = []
+            while (spec = work_queue.pop)
+              begin
+                versions = fetcher.versions_for(spec.name)
+                thread_results << [spec, versions]
+              rescue => e
+                LibyearRb.logger.error("Error fetching #{spec.name}: #{e.message}")
+              end
+            end
+            thread_results
+          end
         end
       end
-      @reporter.generate(results)
-      results
+
+      spec_versions = threads.flat_map(&:value)
+      spec_versions.filter_map { |spec, versions| analyze(spec, versions, as_of: as_of) }
+    rescue Exception # rubocop:disable Lint/RescueException
+      threads.each { |t| t.kill unless t == Thread.current }
+      raise
+    ensure
+      replenishers.each(&:kill)
+    end
+
+    private
+
+    def parse_specs(lockfile_contents)
+      lockfile = LockfileParser.parse(lockfile_contents)
+      lockfile.sources
+        .select { |source| source.type == :gem && source.remote }
+        .group_by { |source| URI.parse(source.remote).host }
+        .transform_values { |sources| sources.flat_map(&:specs).uniq(&:name) }
+    end
+
+    def analyze(spec, versions, as_of:)
+      filtered = versions
+        .reject { |v| as_of && v.created_at > as_of }
+        .sort_by(&:number)
+        .reverse
+
+      if filtered.empty?
+        LibyearRb.logger.warn("Skipping #{spec.name}: no version metadata")
+        return nil
+      end
+
+      DependencyAnalyzer.freshness(spec, filtered)
+    rescue => e
+      LibyearRb.logger.error("Error processing #{spec.name}: #{e.message}")
+      nil
     end
   end
 end

data/lib/libyear_rb/sorter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module LibyearRb
+  SortColumn = Data.define(:field, :direction) do
+    def compare(a, b)
+      av = a.public_send(field)
+      bv = b.public_send(field)
+      return 0 if av.nil? && bv.nil?
+      return 1 if av.nil?
+      return -1 if bv.nil?
+      (direction == :desc) ? bv <=> av : av <=> bv
+    end
+  end
+
+  module Sorter
+    DEFAULT_SPEC = "libyear,name"
+
+    COLUMNS = {
+      "name" => SortColumn.new(field: :name, direction: :asc),
+      "latest-date" => SortColumn.new(field: :latest_version_release_date, direction: :desc),
+      "versions" => SortColumn.new(field: :version_distance, direction: :desc),
+      "libyear" => SortColumn.new(field: :libyear_in_days, direction: :desc)
+    }.freeze
+
+    InvalidSpec = Class.new(ArgumentError)
+
+    class << self
+      def parse(spec)
+        spec.to_s.split(",").map do |part|
+          column = part.strip
+          unless COLUMNS.key?(column)
+            raise InvalidSpec, "Unknown sort column: #{column.inspect}. Available columns: #{COLUMNS.keys.join(", ")}."
+          end
+          COLUMNS.fetch(column)
+        end
+      end
+
+      def sort(results, sorters)
+        results.sort do |a, b|
+          cmp = 0
+          sorters.each do |sorter|
+            cmp = sorter.compare(a, b)
+            break unless cmp.zero?
+          end
+          cmp
+        end
+      end
+    end
+  end
+end

data/lib/libyear_rb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LibyearRb
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/libyear_rb.rb

@@ -3,14 +3,27 @@
 require_relative "libyear_rb/version"
 require_relative "libyear_rb/models"
 require_relative "libyear_rb/lockfile_parser"
-require_relative "libyear_rb/gem_info_cacher"
+require_relative "libyear_rb/file_cache"
 require_relative "libyear_rb/gem_info_fetcher"
 require_relative "libyear_rb/dependency_analyzer"
-require_relative "libyear_rb/reporters/reporter"
-require_relative "libyear_rb/reporters/plaintext_reporter"
+require_relative "libyear_rb/formatters/formatter"
+require_relative "libyear_rb/sorter"
 require_relative "libyear_rb/runner"
-require_relative "libyear_rb/cli"
+
+require "logger"
 
 module LibyearRb
   class Error < StandardError; end
+
+  class << self
+    attr_writer :logger, :cache
+
+    def logger
+      @logger ||= Logger.new(File::NULL)
+    end
+
+    def cache
+      @cache ||= FileCache.new
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libyear-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Thomas Countz
@@ -14,14 +14,14 @@ dependencies:
   name: gems
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
@@ -62,13 +62,15 @@ files:
 - lib/libyear_rb.rb
 - lib/libyear_rb/cli.rb
 - lib/libyear_rb/dependency_analyzer.rb
-- lib/libyear_rb/gem_info_cacher.rb
+- lib/libyear_rb/file_cache.rb
+- lib/libyear_rb/formatters/formatter.rb
+- lib/libyear_rb/formatters/json_formatter.rb
+- lib/libyear_rb/formatters/plaintext_formatter.rb
 - lib/libyear_rb/gem_info_fetcher.rb
 - lib/libyear_rb/lockfile_parser.rb
 - lib/libyear_rb/models.rb
-- lib/libyear_rb/reporters/plaintext_reporter.rb
-- lib/libyear_rb/reporters/reporter.rb
 - lib/libyear_rb/runner.rb
+- lib/libyear_rb/sorter.rb
 - lib/libyear_rb/version.rb
 homepage: https://github.com/thomascountz/libyear-rb
 licenses:
@@ -93,7 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.16
 specification_version: 4
 summary: A simple measure of dependency freshness
 test_files: []

data/lib/libyear_rb/gem_info_cacher.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "fileutils"
-
-module LibyearRb
-  module GemInfoCacher
-    CACHE_EXPIRATION = 86_400 # 24 hours in seconds
-
-    def with_cache(remote_host, gem_name, &block)
-      if ENV["SKIP_CACHE"] == "1"
-        return block.call
-      end
-
-      cache_file = cache_path(remote_host, gem_name)
-      if cache_valid?(cache_file)
-        JSON.parse(File.read(cache_file))
-      else
-        block.call.tap do |data|
-          return [] unless data
-
-          FileUtils.mkdir_p(File.dirname(cache_file))
-          File.write(cache_file, JSON.dump(data))
-          File.utime(Time.now, Time.now, cache_file)
-        end
-      end
-    end
-
-    private
-
-    def cache_valid?(cache_file)
-      return false unless File.exist?(cache_file)
-
-      cache_age = Time.now - File.mtime(cache_file)
-      cache_age < CACHE_EXPIRATION
-    end
-
-    def cache_dir
-      ENV["XDG_CACHE_HOME"] || File.join(Dir.home, ".cache")
-    end
-
-    def cache_path(remote_host, gem_name)
-      host_key = remote_host.gsub(/[^a-zA-Z0-9]/, "_")
-      File.join(cache_dir, "libyear-rb", host_key, "#{gem_name}.json")
-    end
-  end
-end

data/lib/libyear_rb/reporters/reporter.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module LibyearRb
-  class Reporter
-    def initialize(io: $stdout)
-      @io = io
-    end
-
-    def generate(dependency_freshness)
-      raise NotImplementedError, "Subclasses must implement the generate method"
-    end
-  end
-end