still_active 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 186f947f74db917e368e84dde7810495ae047720e9483dade42543028059530d
-  data.tar.gz: 756e3bc581887835db75fcc175ff3654c832c2e81550e1c9447a9f753c37339d
+  metadata.gz: 6e5e5e599cdd630ec6e916800c4abd7df4a3c9d37e24122e80d8859accb1c4e3
+  data.tar.gz: 0cb0dfd2c761612f665a9d2f4e0ba20f47bf8b082c42281af09b8429335aa2a9
 SHA512:
-  metadata.gz: 96ed9789ee0d1901d4e01beed98c094d22f800e32c23a447edb8cc11da9a751a2d6d94ca318bfee3748cce2329a0f79a5fcbc6850be18769296b3ffac07bdd19
-  data.tar.gz: b70bac1b02082583f41b49ab2521f01c436eba2275fa437adfe29de96b14a08554e0ae05e34a73dff181130f88127ac352831bb7d0698da9231b5574697c7e13
+  metadata.gz: 571797c9863bf6597e7c9474e8cf718019925d37d163002e9d594b137458ca0a6be155dfb7a5069777afe83963fb4dc595026a69c8237ce1aa7d024eb254be99
+  data.tar.gz: 4e7ba6a7777973b6fe7f1fa54fc1fad00a06639da18944f0bc89befd6a3e794b1d55eeaca62f33b193bebb54cdb2d6d85c63ae48a73adc722e58a3f194c0aeae

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [1.6.0] - 2026-06-08
+
+### Added
+
+- `--alternatives` surfaces up to three maintained alternative gems for any dependency still_active flags as archived or critically abandoned, drawn from the [rubytoolbox/catalog](https://github.com/rubytoolbox/catalog) category data and ranked by total RubyGems downloads. Presented as **leads to verify, not vetted recommendations** — same Ruby Toolbox category does not guarantee a drop-in replacement — reflecting that Ruby has no authoritative successor metadata the way npm (`deprecate`), Go (`// Deprecated:`), or NuGet (alternate-package) do. Opt-in and best-effort: the catalog is fetched once and cached under `XDG_CACHE_HOME` with a 7-day TTL, any fetch/parse failure degrades to silence, and nothing here can block a run or affect `--fail-if-*` exit codes. Leads render in terminal (a dimmed sub-line), markdown (an Alternatives section), JSON (an additive `alternatives` array), and SARIF (appended to the SA001/SA002 result messages); CycloneDX is unchanged. With the flag off, terminal output shows a one-line discoverability hint on flagged gems. Silent when the catalog has no entry for the gem (the common case for niche/long-tail gems). Closes #28.
+
+### Changed
+
+- The `async` runtime dependency now requires `>= 2.2` (previously unconstrained). 2.2.0 is the verified real minimum — earlier 2.x releases hit a fiber-scheduler `io_read` bug under still_active's concurrent fan-out. A new CI job installs every runtime dependency at its declared gemspec floor and runs the suite on the minimum supported Ruby, so an under-set floor now fails loudly instead of silently.
+
 ## [1.5.0] - 2026-05-23
 
 ### Added

data/README.md

@@ -53,6 +53,8 @@ The bolded rows are the gap `still_active` fills: nobody else answers "is the ma
 gem install still_active
 ```
 
+**Requires an actively-maintained Ruby.** The gemspec's `required_ruby_version` floor tracks Ruby's [EOL schedule](https://endoflife.date/ruby); running a maintenance auditor on an unmaintained runtime would be a bit rich. You don't have to run it *on* the Ruby you're auditing, though: still_active reports on the version your project pins in `Gemfile.lock`, so run it from any current Ruby (locally, in CI, or via the [`still_active-action`](https://github.com/SeanLF/still_active-action)) and it will still flag an EOL target.
+
 ## Quick Start
 
 ```bash
@@ -99,6 +101,7 @@ Usage: still_active [options]
         --terminal                   Coloured terminal output (default in TTY)
         --markdown                   Markdown table output
         --json                       JSON output (default when piped)
+        --alternatives               Suggest maintained alternatives (Ruby Toolbox leads) for archived/critical gems
         --sarif[=PATH]               SARIF 2.1.0 output for GitHub Code Scanning
         --cyclonedx[=PATH]           CycloneDX SBOM output (stdout, or a file path)
         --cyclonedx-version=VERSION  CycloneDX spec version: 1.6 (default) or 1.7
@@ -339,6 +342,20 @@ Activity is determined by the most recent signal across last commit date, latest
 - **stale**: last activity between 1 and 3 years ago (configurable with `--warning-range-end`)
 - **critical**: last activity over 3 years ago
 
+### Alternative gem leads (opt-in)
+
+When a gem is flagged archived or critical, `--alternatives` surfaces up to three maintained gems from the same [Ruby Toolbox](https://www.ruby-toolbox.com) category, ranked by total downloads:
+
+```bash
+still_active --gems=paperclip --alternatives
+```
+
+```text
+↳ leads (Ruby Toolbox): shrine · carrierwave · kt-paperclip (verify fit)
+```
+
+These are **leads, not recommendations**: same-category does not mean drop-in replacement, so verify fit before switching. Ruby has no authoritative "use instead" metadata (unlike npm `deprecate`, Go's `// Deprecated:`, or NuGet's alternate-package field), so this is a best-effort heuristic. It is silent when the catalog has no entry for the gem, and the feature never blocks or fails a run. Leads appear in terminal, markdown, JSON, and SARIF output. When the flag is off, terminal output shows a one-line hint on flagged gems that the option exists (other formats stay silent).
+
 ### Data sources
 
 - **Versions, release dates, and licenses** from [RubyGems.org](https://rubygems.org) or [GitHub Packages](https://docs.github.com/en/packages)
@@ -346,6 +363,7 @@ Activity is determined by the most recent signal across last commit date, latest
 - **OpenSSF Scorecard**, **vulnerability counts**, and **CVSS severity** from Google's [deps.dev](https://deps.dev) API
 - **Additional advisories** from [ruby-advisory-db](https://github.com/rubysec/ruby-advisory-db), merged in when `bundler-audit` is installed alongside (run `bundle audit update` to keep its checkout current)
 - **Ruby version freshness** from [endoflife.date](https://endoflife.date)
+- **Alternative gem leads** (with `--alternatives`) from the [rubytoolbox/catalog](https://github.com/rubytoolbox/catalog) category data
 
 ### Configuration defaults
 

data/lib/helpers/alternatives_helper.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "gems"
+
+module StillActive
+  # Turns a gem's catalog siblings into ranked "leads" -- the most-downloaded
+  # still-published alternatives. Best-effort: a failed lookup drops that
+  # candidate, never the feature.
+  module AlternativesHelper
+    extend self
+
+    MAX_SIBLINGS_CONSIDERED = 40 # bound the download lookups for huge categories
+    DEFAULT_LIMIT = 3
+
+    def leads_for(gem_name:, index:, limit: DEFAULT_LIMIT)
+      return [] if index.nil?
+
+      # Bound the per-gem download lookups so a huge category can't trigger
+      # dozens of HTTP calls. This is a catalog-order prefix, so a very large
+      # category could leave a popular sibling past the cap out of the ranking;
+      # acceptable for best-effort leads where we only ever surface a few.
+      # (CatalogIndex already reduces owner/repo slugs to their gem-name tail,
+      # so every entry here is a plain name rankable by downloads.)
+      siblings = (index[gem_name] || []).first(MAX_SIBLINGS_CONSIDERED)
+      return [] if siblings.empty?
+
+      siblings
+        .filter_map { |name| (count = downloads(name)) && [name, count] }
+        .max_by(limit) { |_name, count| count }
+        .map(&:first)
+    end
+
+    private
+
+    def downloads(gem_name)
+      info = Gems.info(gem_name)
+      info && info["downloads"]
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/helpers/catalog_index.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "zlib"
+require "rubygems/package"
+require "yaml"
+require "json"
+require "open-uri"
+
+module StillActive
+  # Optional source of "alternative gem" leads: the rubytoolbox/catalog repo
+  # (MIT) mapped to gem -> co-category siblings. Fetched once and cached; every
+  # path is best-effort, returning nil/empty so a miss just means no leads.
+  module CatalogIndex
+    extend self
+
+    REPO = "rubytoolbox/catalog"
+    CACHE_TTL_SECONDS = 7 * 24 * 60 * 60
+    MAX_DOWNLOAD_BYTES = 25 * 1024 * 1024 # the catalog is ~50 KB; cap to avoid surprises
+
+    # Returns { gem => [siblings] } or nil. Never raises.
+    def load
+      cached = read_cache
+      return cached if cached
+
+      blob = download
+      index = build_index(blob)
+      write_cache(index)
+      index
+    rescue StandardError => e
+      warn("still_active: could not load Ruby Toolbox catalog for alternatives (#{e.class}); skipping leads")
+      nil
+    end
+
+    # Parse a gzipped catalog tarball into { gem_name => [sibling gem names] }.
+    def build_index(tar_gz_blob)
+      categories = []
+
+      reader = Gem::Package::TarReader.new(Zlib::GzipReader.new(StringIO.new(tar_gz_blob)))
+      reader.each do |entry|
+        next unless entry.file?
+        next unless entry.full_name.match?(%r{/catalog/.+\.ya?ml$})
+        next if File.basename(entry.full_name) == "_meta.yml"
+
+        data = YAML.safe_load(entry.read)
+        next unless data.is_a?(Hash) && data["projects"].is_a?(Array)
+
+        categories << data["projects"].map { |p| p.to_s.split("/").last }
+      end
+
+      build_siblings(categories)
+    end
+
+    private
+
+    def cache_path
+      base = ENV["XDG_CACHE_HOME"]
+      base = File.join(Dir.home, ".cache") if base.nil? || base.empty?
+      File.join(base, "still_active", "catalog-siblings.json")
+    end
+
+    def read_cache
+      path = cache_path
+      return unless File.exist?(path)
+      return if Time.now - File.mtime(path) > CACHE_TTL_SECONDS
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      nil
+    end
+
+    def write_cache(index)
+      path = cache_path
+      require "fileutils"
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.dump(index))
+    rescue SystemCallError
+      nil # an unwritable cache dir must not break the feature
+    end
+
+    def download
+      url = StillActive.config.github_client.archive_link(REPO, format: "tarball", ref: "main")
+      URI.open(url) { |io| io.read(MAX_DOWNLOAD_BYTES) } # rubocop:disable Security/Open
+    end
+
+    def build_siblings(categories)
+      siblings = Hash.new { |h, k| h[k] = [] }
+
+      categories.each do |members|
+        members.each do |gem_name|
+          siblings[gem_name].concat(members - [gem_name])
+        end
+      end
+
+      siblings.transform_values(&:uniq)
+    end
+  end
+end

data/lib/helpers/markdown_helper.rb

@@ -84,6 +84,17 @@ module StillActive
       "| #{cells.join(" | ")} |"
     end
 
+    def alternatives_section(result)
+      flagged = result.select do |_name, data|
+        data[:alternatives] && !data[:alternatives].empty?
+      end
+      return "" if flagged.empty?
+
+      lines = ["", "**Alternatives** (Ruby Toolbox leads, verify fit):"]
+      flagged.each { |name, data| lines << "- `#{name}`: #{data[:alternatives].join(", ")}" }
+      lines.join("\n")
+    end
+
     private
 
     def version_with_date(text:, url:, date:)

data/lib/helpers/sarif_helper.rb

@@ -98,7 +98,7 @@ module StillActive
       location = location_for(name, line_index, lockfile_uri)
 
       if data[:archived]
-        out << result("SA001", name, "#{name} #{version}: upstream repository is archived#{repo_suffix(data)}.", location)
+        out << result("SA001", name, "#{name} #{version}: upstream repository is archived#{repo_suffix(data)}#{alternatives_suffix(data)}.", location)
       end
 
       unless data[:archived]
@@ -108,7 +108,7 @@ module StillActive
           out << result(
             "SA002",
             name,
-            "#{name} #{version}: no commits in #{years} years (last #{last_commit.utc.strftime("%Y-%m-%d")}).",
+            "#{name} #{version}: no commits in #{years} years (last #{last_commit.utc.strftime("%Y-%m-%d")})#{alternatives_suffix(data)}.",
             location,
           )
         end
@@ -228,5 +228,12 @@ module StillActive
     def repo_suffix(data)
       data[:repository_url] ? " (#{data[:repository_url]})" : ""
     end
+
+    def alternatives_suffix(data)
+      leads = data[:alternatives]
+      return "" if leads.nil? || leads.empty?
+
+      " Consider: #{leads.join(", ")}"
+    end
   end
 end

data/lib/helpers/terminal_helper.rb

@@ -13,13 +13,18 @@ module StillActive
     HEADERS = ["Name", "Version", "Activity", "OpenSSF", "Vulns", "License"].freeze
 
     def render(result, ruby_info: nil)
-      rows = result.keys.sort.map { |name| build_row(name, result[name]) }
+      names = result.keys.sort
+      rows = names.map { |name| build_row(name, result[name]) }
       widths = column_widths(rows)
 
       lines = []
       lines << header_line(widths)
       lines << separator_line(widths)
-      rows.each { |row| lines << row_line(row, widths) }
+      names.each_with_index do |name, i|
+        lines << row_line(rows[i], widths)
+        extra = alternatives_line(result[name])
+        lines << extra if extra
+      end
       lines << ""
       lines << summary_line(result)
       lines << ruby_summary_line(ruby_info) if ruby_info
@@ -125,6 +130,18 @@ module StillActive
         .join
     end
 
+    def alternatives_line(data)
+      level = ActivityHelper.activity_level(data)
+      return unless [:archived, :critical].include?(level)
+
+      leads = data[:alternatives]
+      if leads && !leads.empty?
+        AnsiHelper.dim("  ↳ leads (Ruby Toolbox): #{leads.join(" · ")} (verify fit)")
+      elsif !StillActive.config.alternatives
+        AnsiHelper.dim("  ↳ run with --alternatives for maintained replacements")
+      end
+    end
+
     def ruby_summary_line(ruby_info)
       version = ruby_info[:version]
       latest = ruby_info[:latest_version]

data/lib/still_active/cli.rb

@@ -190,6 +190,8 @@ module StillActive
 
         puts MarkdownHelper.markdown_table_body_line(gem_name: name, data: gem_data)
       end
+      alternatives = MarkdownHelper.alternatives_section(result)
+      puts alternatives unless alternatives.empty?
       if ruby_info
         puts ""
         puts MarkdownHelper.ruby_line(ruby_info)

data/lib/still_active/config.rb

@@ -7,7 +7,8 @@ require "open3"
 module StillActive
   class Config
     attr_writer :github_oauth_token, :gitlab_token, :gemfile_path
-    attr_accessor :baseline_path,
+    attr_accessor :alternatives,
+      :baseline_path,
       :critical_warning_emoji,
       :cyclonedx_path,
       :cyclonedx_version,
@@ -28,6 +29,7 @@ module StillActive
       :warning_range_end
 
     def initialize
+      @alternatives = false
       @fail_if_critical = false
       @fail_if_outdated = nil
       @fail_if_vulnerable = nil

data/lib/still_active/options.rb

@@ -64,6 +64,7 @@ module StillActive
       opts.on("--terminal", "Coloured terminal output (default in TTY)") { StillActive.config { |config| config.output_format = :terminal } }
       opts.on("--markdown", "Markdown table output") { StillActive.config { |config| config.output_format = :markdown } }
       opts.on("--json", "JSON output (default when piped)") { StillActive.config { |config| config.output_format = :json } }
+      opts.on("--alternatives", "Suggest maintained alternatives (Ruby Toolbox leads) for archived/critical gems") { StillActive.config { |config| config.alternatives = true } }
       opts.on("--sarif[=PATH]", "SARIF 2.1.0 output for GitHub Code Scanning (default path: still_active.sarif.json; '-' for stdout). Overrides --terminal/--markdown/--json.") do |value|
         StillActive.config { |config| config.sarif_path = value || "still_active.sarif.json" }
       end

data/lib/still_active/version.rb

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

data/lib/still_active/workflow.rb

@@ -3,6 +3,9 @@
 require_relative "deps_dev_client"
 require_relative "gitlab_client"
 require_relative "repository"
+require_relative "../helpers/activity_helper"
+require_relative "../helpers/alternatives_helper"
+require_relative "../helpers/catalog_index"
 require_relative "../helpers/libyear_helper"
 require_relative "../helpers/ruby_advisory_db"
 require_relative "../helpers/ruby_helper"
@@ -22,6 +25,7 @@ module StillActive
         # Load the optional ruby-advisory-db once, before the fan-out, so the
         # read-only Database is shared across fibers rather than reloaded per gem.
         advisory_db = RubyAdvisoryDb.load
+        catalog = StillActive.config.alternatives ? CatalogIndex.load : nil
         barrier = Async::Barrier.new
         semaphore = Async::Semaphore.new(StillActive.config.parallelism, parent: barrier)
         result_object = {}
@@ -36,6 +40,7 @@ module StillActive
               source_type: gem[:source_type] || :rubygems,
               source_uri: gem[:source_uri],
               advisory_db: advisory_db,
+              catalog: catalog,
             )
           rescue Octokit::TooManyRequests
             $stderr.print("\r\e[K") if on_progress
@@ -60,7 +65,7 @@ module StillActive
 
     private
 
-    def gem_info(gem_name:, result_object:, gem_version: nil, source_type: :rubygems, source_uri: nil, advisory_db: nil)
+    def gem_info(gem_name:, result_object:, gem_version: nil, source_type: :rubygems, source_uri: nil, advisory_db: nil, catalog: nil)
       result_object[gem_name] = { source_type: source_type }
       result_object[gem_name][:version_used] = gem_version if gem_version
 
@@ -76,6 +81,8 @@ module StillActive
           advisory_db: advisory_db,
         )
       end
+
+      attach_alternatives(gem_name: gem_name, result_object: result_object, catalog: catalog)
     end
 
     def gem_info_rubygems(gem_name:, gem_version:, result_object:, source_uri:, advisory_db: nil)
@@ -151,6 +158,16 @@ module StillActive
       })
     end
 
+    def attach_alternatives(gem_name:, result_object:, catalog:)
+      return if catalog.nil?
+      return unless [:archived, :critical].include?(ActivityHelper.activity_level(result_object[gem_name]))
+
+      leads = AlternativesHelper.leads_for(gem_name: gem_name, index: catalog)
+      result_object[gem_name][:alternatives] = leads unless leads.empty?
+    rescue StandardError
+      nil # cosmetic best-effort: lead-fetching must never break the core audit
+    end
+
     def fetch_deps_dev_info(gem_name:, version:, advisory_db: nil)
       info = DepsDevClient.version_info(gem_name: gem_name, version: version)
       scorecard = DepsDevClient.project_scorecard(project_id: info&.dig(:project_id))

data/still_active.gemspec

@@ -45,7 +45,11 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency("rubocop-rspec")
   spec.add_development_dependency("rubocop-shopify")
 
-  spec.add_runtime_dependency("async")
+  # 2.0/2.1 ship a scheduler that breaks our fan-out (io_read); 2.2 is the
+  # verified floor (checked against Ruby 3.3 in Docker). octokit/faraday-retry/
+  # gems work down to ancient versions, so they stay unpinned rather than
+  # carry an artificial floor.
+  spec.add_runtime_dependency("async", ">= 2.2")
   spec.add_runtime_dependency("bundler", ">= 2.0")
   spec.add_runtime_dependency("faraday-retry")
   spec.add_runtime_dependency("gems")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: still_active
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Sean Floyd
@@ -127,14 +127,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -211,9 +211,11 @@ files:
 - README.md
 - bin/still_active
 - lib/helpers/activity_helper.rb
+- lib/helpers/alternatives_helper.rb
 - lib/helpers/ansi_helper.rb
 - lib/helpers/bot_context.rb
 - lib/helpers/bundler_helper.rb
+- lib/helpers/catalog_index.rb
 - lib/helpers/cyclonedx_helper.rb
 - lib/helpers/diff_markdown_helper.rb
 - lib/helpers/emoji_helper.rb