still_active 1.6.0 → 3.0.0.rc1

data/lib/still_active/workflow.rb

@@ -1,19 +1,30 @@
 # frozen_string_literal: true
 
+require_relative "artifactory_client"
+require_relative "ceiling_reconciler"
 require_relative "deps_dev_client"
+require_relative "osv_client"
+require_relative "poison_security_correlator"
+require_relative "ecosystems_client"
+require_relative "forgejo_client"
+require_relative "github_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/constraint_helper"
+require_relative "../helpers/http_helper"
 require_relative "../helpers/libyear_helper"
 require_relative "../helpers/ruby_advisory_db"
 require_relative "../helpers/ruby_helper"
+require_relative "../helpers/runtime_ceiling_helper"
 require_relative "../helpers/version_helper"
 require_relative "../helpers/vulnerability_helper"
 require "async"
 require "async/barrier"
 require "async/semaphore"
+require "cgi"
 require "gems"
 
 module StillActive
@@ -26,9 +37,33 @@ module StillActive
         # read-only Database is shared across fibers rather than reloaded per gem.
         advisory_db = RubyAdvisoryDb.load
         catalog = StillActive.config.alternatives ? CatalogIndex.load : nil
+        # The Ruby support window (oldest-supported / latest-stable / EOL cycles)
+        # is a per-run constant, so fetch it once here rather than per gem. nil when
+        # the endoflife feed is unavailable -> the language-ceiling signal quietly
+        # sits out, exactly like a missing advisory_db. This runs OUTSIDE the
+        # per-gem rescue, so a defensive rescue keeps a best-effort enrichment from
+        # ever aborting the whole audit (the "never crash the core" contract).
+        ruby_range =
+          begin
+            RubyHelper.supported_ruby_range
+          rescue StandardError => e
+            $stderr.puts("warning: Ruby support window lookup failed: #{e.class} (#{e.message}); skipping language-ceiling checks")
+            nil
+          end
+        # Resolve the GitHub token once here, single-fibered, before the fan-out:
+        # provider_for reads it per gem across fibers and gh_cli_token shells out,
+        # so resolving eagerly keeps that off the concurrent path and guarantees
+        # every fiber sees one consistent value (token -> live GitHub, incl. private
+        # repos; only a genuinely absent token falls back to ecosyste.ms).
+        StillActive.config.github_oauth_token
         barrier = Async::Barrier.new
         semaphore = Async::Semaphore.new(StillActive.config.parallelism, parent: barrier)
         result_object = {}
+        # Memoizes each capped dep's latest version across gems for the run, so a
+        # dep pinned by several dormant gems is resolved once. Shared, single-writer
+        # under Async's cooperative scheduling (a duplicate concurrent miss just
+        # refetches the same value; it can't corrupt the map).
+        constraint_cache = {}
         total = StillActive.config.gems.size
         completed = 0
         StillActive.config.gems.each_with_object(result_object) do |gem, hash|
@@ -39,8 +74,12 @@ module StillActive
               gem_version: gem[:version],
               source_type: gem[:source_type] || :rubygems,
               source_uri: gem[:source_uri],
+              direct: gem.fetch(:direct, true),
+              dependency_path: gem[:dependency_path],
               advisory_db: advisory_db,
               catalog: catalog,
+              constraint_cache: constraint_cache,
+              ruby_range: ruby_range,
             )
           rescue Octokit::TooManyRequests
             $stderr.print("\r\e[K") if on_progress
@@ -54,7 +93,17 @@ module StillActive
           end
         end
         barrier.wait
-        result_object
+        # Whole-tree correlation, once every gem's signals are in: a ceiling's
+        # "upgrade to lift it" must not contradict a poison finding that caps the
+        # same gem below that upgrade.
+        CeilingReconciler.reconcile_ceiling_with_poison(result_object)
+        # Flag poison caps that pin a vulnerable dependency: "a dormant package is
+        # holding you on a known-vulnerable dep, below the fix." No extra fetches.
+        PoisonSecurityCorrelator.correlate(result_object)
+        # Gems are inserted as their async tasks finish, so the natural order is
+        # nondeterministic completion order. Sort by name once here so every
+        # consumer (JSON, SARIF, the baseline diff) gets a stable, diffable order.
+        result_object.sort_by { |name, _| name }.to_h
       end
       task.wait
     end
@@ -65,8 +114,9 @@ module StillActive
 
     private
 
-    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 }
+    def gem_info(gem_name:, result_object:, gem_version: nil, source_type: :rubygems, source_uri: nil, direct: true, dependency_path: nil, advisory_db: nil, catalog: nil, constraint_cache: {}, ruby_range: nil)
+      result_object[gem_name] = { source_type: source_type, direct: direct }
+      result_object[gem_name][:dependency_path] = dependency_path if dependency_path
       result_object[gem_name][:version_used] = gem_version if gem_version
 
       case source_type
@@ -79,25 +129,29 @@ module StillActive
           result_object: result_object,
           source_uri: source_uri,
           advisory_db: advisory_db,
+          ruby_range: ruby_range,
         )
       end
 
       attach_alternatives(gem_name: gem_name, result_object: result_object, catalog: catalog)
+      # Poison-pill enrichment runs last and only on the rubygems path (git/path
+      # gems aren't in the registry). Placed after alternatives so a stray fetch
+      # error can never cost the gem its other, already-assembled signals.
+      unless [:path, :git].include?(source_type)
+        attach_constraints(gem_name: gem_name, result_object: result_object, cache: constraint_cache)
+      end
     end
 
-    def gem_info_rubygems(gem_name:, gem_version:, result_object:, source_uri:, advisory_db: nil)
+    def gem_info_rubygems(gem_name:, gem_version:, result_object:, source_uri:, advisory_db: nil, ruby_range: nil)
       vs = versions(gem_name: gem_name, source_uri: source_uri)
-      repo_info = repository_info(gem_name: gem_name, versions: vs)
-      commit_date = last_commit_date(
-        source: repo_info[:source],
-        repository_owner: repo_info[:owner],
-        repository_name: repo_info[:name],
-      )
-      archived = repo_archived(
+      repo_info = repository_info(gem_name: gem_name, versions: vs, source_uri: source_uri)
+      signals = repo_signals(
         source: repo_info[:source],
         repository_owner: repo_info[:owner],
         repository_name: repo_info[:name],
       )
+      commit_date = signals[:last_commit_date]
+      archived = signals[:archived]
       last_release = VersionHelper.find_version(versions: vs, pre_release: false)
       last_pre_release = VersionHelper.find_version(versions: vs, pre_release: true)
       deps_dev = fetch_deps_dev_info(
@@ -122,8 +176,17 @@ module StillActive
         result_object[gem_name][:ruby_gems_url] = "https://rubygems.org/gems/#{gem_name}"
       end
 
+      if StillActive.config.unreleased_commits
+        result_object[gem_name][:unreleased_commits] = unreleased_commits(
+          source: repo_info[:source],
+          repository_owner: repo_info[:owner],
+          repository_name: repo_info[:name],
+          version: VersionHelper.gem_version(version_hash: last_release),
+        )
+      end
+
+      version_used = gem_version ? VersionHelper.find_version(versions: vs, version_string: gem_version) : nil
       if gem_version
-        version_used = VersionHelper.find_version(versions: vs, version_string: gem_version)
         result_object[gem_name].merge!({
           up_to_date: VersionHelper.up_to_date(
             version_used: version_used,
@@ -140,6 +203,75 @@ module StillActive
           ),
         })
       end
+
+      # A version pinned to a now-yanked release has no resolvable ruby_version to
+      # judge, and `pinned: !version_used.nil?` would otherwise fall through to the
+      # latest version's cap and attach IT to the locked gem -- a false ceiling on a
+      # version we can't actually read. Skip; the yanked lock is already flagged.
+      yanked_lock = !gem_version.nil? && version_used.nil? && !vs.empty?
+      unless yanked_lock
+        attach_ruby_ceiling(
+          gem_data: result_object[gem_name],
+          used_ruby_requirement: canonical_ruby_requirement(vs, version_used),
+          latest_ruby_requirement: canonical_ruby_requirement(vs, last_release),
+          pinned: !version_used.nil?,
+          ruby_range: ruby_range,
+        )
+      end
+    end
+
+    # The ruby_version to judge a language ceiling against, read from the canonical
+    # `ruby` (source) platform entry of a version rather than whichever variant the
+    # registry happens to list first. Native gems ship a permissive `ruby` platform
+    # plus precompiled per-platform variants that cap ruby_version to the ABIs they
+    # were built for; the source platform is the gem's true Ruby support (it can be
+    # compiled on a newer Ruby), so a precompiled variant's tighter cap must not be
+    # read as the gem's ceiling. (Flagging that a project's LOCKED precompiled
+    # variant lacks a newer-Ruby build is a distinct, narrower signal, and needs the
+    # locked platform, which isn't threaded here yet.)
+    def canonical_ruby_requirement(versions, version_hash)
+      number = version_hash && version_hash["number"]
+      return if number.nil?
+
+      entries = versions.select { |version| version["number"] == number }
+      chosen = entries.find { |version| version["platform"] == "ruby" || version["platform"].nil? } || entries.first
+      VersionHelper.ruby_requirement(version_hash: chosen)
+    end
+
+    # Language-runtime ceiling: the sibling of poison. A gem's resolved version
+    # declares a `ruby_version` that caps the runtime -- either onto an end-of-life
+    # Ruby (critical: no patched runtime is reachable) or below the latest stable
+    # (note: a compatibility ceiling to plan around / a place to contribute Ruby-N
+    # support). Unlike poison this is NOT gated on dormancy: a cap is a fact of the
+    # resolved version whether or not the gem is maintained. Best-effort: a nil
+    # range (endoflife feed down) or absent ruby_version yields no finding.
+    def attach_ruby_ceiling(gem_data:, used_ruby_requirement:, latest_ruby_requirement:, pinned:, ruby_range:)
+      return if ruby_range.nil?
+
+      # Analyze the version actually in the tree. Fall back to latest ONLY when
+      # there's no pinned version (a latest-only audit), never when the pinned
+      # version merely declares no ruby_version: an absent cap runs on any Ruby, so
+      # projecting a newer release's cap back onto it would mint a false ceiling.
+      requirement = pinned ? used_ruby_requirement : latest_ruby_requirement
+      finding = RuntimeCeilingHelper.analyze(requirement: requirement, support_window: ruby_range)
+      return if finding.nil?
+
+      finding[:fixed_by_upgrade] = ruby_ceiling_lifted_by_upgrade?(used_req: used_ruby_requirement, latest_req: latest_ruby_requirement, ruby_range: ruby_range)
+      # The runtime this cap is against, so the shared renderers (terminal, md,
+      # SARIF) name it without hardcoding "Ruby". The Python SBOM path attaches the
+      # same shape with runtime "Python"; everything downstream is runtime-neutral.
+      finding[:runtime] = "Ruby"
+      gem_data[:language_ceiling] = finding
+    end
+
+    # Does bumping the gem to its latest lift the ceiling? True only when the cap
+    # is on the resolved (older) version and the latest version declares no ceiling
+    # of its own -- the actionable "upgrade the gem" case (e.g. CFPropertyList
+    # 3.0.9's `< 3.2` cap, gone by 4.0.0). False when already on latest.
+    def ruby_ceiling_lifted_by_upgrade?(used_req:, latest_req:, ruby_range:)
+      return false if used_req.nil? || used_req == latest_req
+
+      RuntimeCeilingHelper.analyze(requirement: latest_req, support_window: ruby_range).nil?
     end
 
     def gem_info_non_rubygems(gem_name:, gem_version:, result_object:, source_uri: nil, advisory_db: nil)
@@ -147,19 +279,31 @@ module StillActive
       source, owner, name = repo_info.values_at(:source, :owner, :name)
       deps_dev = gem_version ? fetch_deps_dev_info(gem_name: gem_name, version: gem_version, advisory_db: advisory_db) : {}
 
-      # Fall back to repo-derived project_id for scorecard when deps.dev doesn't have the version
-      deps_dev[:scorecard_score] ||= DepsDevClient.project_scorecard(project_id: repo_info[:project_id])&.dig(:score)
+      # Fall back to repo-derived project_id for scorecard when deps.dev doesn't
+      # have the version. Use ||= so a maintained score already found via the
+      # version's scorecard is never clobbered by a nil from the repo fallback
+      # (0.0 is truthy, so a measured "unmaintained" is preserved too).
+      if deps_dev[:scorecard_score].nil?
+        fallback = DepsDevClient.project_scorecard(project_id: repo_info[:project_id])
+        deps_dev[:scorecard_score] ||= fallback&.dig(:score)
+        deps_dev[:scorecard_maintained] ||= fallback&.dig(:maintained)
+      end
 
+      signals = repo_signals(source:, repository_owner: owner, repository_name: name)
       result_object[gem_name].merge!({
         repository_url: repo_info[:url],
-        last_commit_date: last_commit_date(source:, repository_owner: owner, repository_name: name),
-        archived: repo_archived(source:, repository_owner: owner, repository_name: name),
+        last_commit_date: signals[:last_commit_date],
+        archived: signals[:archived],
         **deps_dev,
       })
     end
 
     def attach_alternatives(gem_name:, result_object:, catalog:)
       return if catalog.nil?
+      # Direct-only by design: "replace gem X with better-maintained Y" is
+      # incoherent for a transitive gem the user never chose (#60). The
+      # path-to-parent points them at the direct gem they can actually swap.
+      return unless result_object[gem_name][:direct]
       return unless [:archived, :critical].include?(ActivityHelper.activity_level(result_object[gem_name]))
 
       leads = AlternativesHelper.leads_for(gem_name: gem_name, index: catalog)
@@ -168,15 +312,74 @@ module StillActive
       nil # cosmetic best-effort: lead-fetching must never break the core audit
     end
 
+    # Poison-pill detection. A dormant gem that declares a runtime constraint
+    # capping a still-evolving dep BELOW that dep's current latest major holds the
+    # tree hostage: the cap will never lift because nobody is shipping the gem, and
+    # it gets more poisonous with time as the capped dep keeps releasing majors.
+    #
+    # Gated on dormancy so a MAINTAINED gem with a cap is never flagged (it'll bump
+    # the cap) -- that gate is the whole discipline of the signal. Each surviving
+    # finding carries its receipt (caps X; latest Y; N majors behind). Best-effort
+    # and non-raising: every underlying call degrades to []/nil on failure, so a
+    # lookup miss just means "no constraints known", never a dropped gem.
+    def attach_constraints(gem_name:, result_object:, cache:)
+      gem_data = result_object[gem_name]
+      # The locked version if the caller pinned one (that's the requirement set
+      # actually in their tree), else the gem's latest.
+      version = gem_data[:version_used] || gem_data[:latest_version]
+      return if version.nil?
+      return unless [:critical, :archived].include?(ActivityHelper.activity_level(gem_data))
+
+      declared = EcosystemsClient.declared_dependencies(name: gem_name, version: version)
+      constraints = ConstraintHelper.poison_findings(declared) do |dep_name|
+        resolve_latest_version(dep_name, result_object: result_object, cache: cache)
+      end
+      return if constraints.empty?
+
+      gem_data[:constraints] = constraints
+      # Poison = a version ceiling that blocks upgrades. An exact-pin below latest
+      # is a milder resolution hazard: still surfaced in constraints, but it may be
+      # deliberate, so it doesn't earn the poison label on its own.
+      gem_data[:poison] = constraints.any? { |constraint| constraint[:kind] == :ceiling }
+      gem_data[:poison_severity] = ConstraintHelper.worst_severity(constraints) if gem_data[:poison]
+    end
+
+    # The capped dep's current latest stable version, for the majors-behind math.
+    # Reuse the tree's already-computed latest_version when the dep is itself in
+    # the audit (no extra request); otherwise fetch and memoize per run, so a dep
+    # capped by several dormant gems is looked up once. Only a RESOLVED version is
+    # cached: an unresolved lookup returns nil whether the dep is genuinely absent
+    # or rubygems.org was momentarily rate-limited, and caching the transient case
+    # would drop the pill for every later gem capping the same dep. So a miss is
+    # re-attempted rather than remembered.
+    def resolve_latest_version(dep_name, result_object:, cache:)
+      cache[dep_name] ||= result_object[dep_name]&.dig(:latest_version) || fetch_latest_version(dep_name)
+    end
+
+    def fetch_latest_version(dep_name)
+      latest = VersionHelper.find_version(versions: versions(gem_name: dep_name), pre_release: false)
+      VersionHelper.gem_version(version_hash: latest)
+    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))
       advisory_keys = info&.dig(:advisory_keys) || []
-      deps_dev_vulns = advisory_keys.filter_map { |id| DepsDevClient.advisory_detail(advisory_id: id) }
+      # The keys ARE the evidence the version is vulnerable; the detail fetch only
+      # enriches CVSS/title. A failed enrichment (429/timeout/5xx -> nil) must not
+      # drop the advisory and read a known-vulnerable gem as clean, so an
+      # un-enriched key still contributes a minimal advisory (mirrors EcosystemLens;
+      # ruby-advisory-db then fills the score on merge when it also carries it).
+      deps_dev_vulns = advisory_keys.map { |id| DepsDevClient.advisory_detail(advisory_id: id) || { id: id, source: "deps.dev" } }
       radb_vulns = RubyAdvisoryDb.advisories_for(database: advisory_db, gem_name: gem_name, version: version)
       vulnerabilities = VulnerabilityHelper.merge_advisories(deps_dev: deps_dev_vulns, ruby_advisory_db: radb_vulns)
+      # Enrich with OSV: a real GHSA severity label (deps.dev can't score a CVSS-4-only
+      # advisory) and the fixed-version ranges the "capped below the fix" signal needs.
+      # Native path is rubygems.
+      OsvClient.enrich(vulnerabilities, ecosystem: :rubygems, name: gem_name)
       {
         scorecard_score: scorecard&.dig(:score),
+        scorecard_maintained: scorecard&.dig(:maintained),
         vulnerability_count: vulnerabilities.length,
         vulnerabilities: vulnerabilities,
       }
@@ -185,12 +388,24 @@ module StillActive
     def versions(gem_name:, source_uri: nil)
       if github_packages_uri?(source_uri)
         fetch_github_packages_versions(gem_name: gem_name, source_uri: source_uri)
+      elsif ArtifactoryClient.artifactory_uri?(source_uri)
+        ArtifactoryClient.versions(gem_name: gem_name, source_uri: source_uri)
+      elsif unqueryable_private_source?(source_uri)
+        warn_unqueryable_private_source(gem_name: gem_name, source_uri: source_uri)
+        []
       else
         Gems.versions(gem_name)
       end
     rescue Gems::NotFound
       []
-    rescue Errno::ECONNRESET, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout, SocketError => e
+    # Gems::GemError is the `gems` library's catch-all for any non-success,
+    # non-404 response -- crucially a 429 rate-limit or a 5xx. Left unrescued it
+    # escapes to the per-gem rescue in #call and strips the gem of ALL its signals
+    # (not just versions), blaming a generic "error occurred". The poison-pill
+    # enrichment adds extra version lookups that make a 429 likelier, so a
+    # best-effort feature must not be able to degrade an unrelated gem's core data:
+    # degrade to "no versions known" here, exactly like Gems::NotFound.
+    rescue Gems::GemError, *HttpHelper::TRANSPORT_ERRORS => e
       $stderr.puts("warning: rubygems.org versions lookup failed for #{gem_name}: #{e.class} (#{e.message})")
       []
     end
@@ -201,10 +416,36 @@ module StillActive
       false
     end
 
+    # A rubygems-type source that isn't public rubygems.org and that we have no
+    # client for (Gemfury, Gemstash, geminabox, a private mirror). We must NOT
+    # fall through to Gems.versions, which always hits public rubygems.org: that
+    # would silently report a public name-collision's data, or blanks, as if it
+    # were the private gem's. github_packages/artifactory are handled above, so
+    # anything left with a non-rubygems.org host is unqueryable. Refs #43.
+    def unqueryable_private_source?(source_uri)
+      return false unless source_uri.is_a?(String)
+
+      # Hostnames are case-insensitive; a trailing dot (FQDN form) is equivalent.
+      host = URI(source_uri).host&.downcase&.chomp(".")
+      return false if host.nil?
+
+      host != "rubygems.org" && !host.end_with?(".rubygems.org")
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def warn_unqueryable_private_source(gem_name:, source_uri:)
+      host = URI(source_uri).host
+      $stderr.puts(
+        "warning: #{gem_name} resolves from a private source (#{host}) still_active cannot query; " \
+          "reporting no version/latest/libyear data for it rather than substituting public rubygems.org data",
+      )
+    end
+
     def fetch_github_packages_versions(gem_name:, source_uri:)
       base = URI(source_uri.chomp("/"))
       namespace_path = base.path
-      path = "#{namespace_path}/api/v1/gems/#{gem_name}/versions.json"
+      path = "#{namespace_path}/api/v1/gems/#{CGI.escape(gem_name)}/versions.json"
       token = StillActive.config.github_oauth_token
       headers = token ? { "Authorization" => "Bearer #{token}" } : {}
       HttpHelper.get_json(base, path, headers: headers) || []
@@ -214,32 +455,47 @@ module StillActive
       valid_repository_url =
         [source_uri, *installed_gem_urls(gem_name: gem_name)].find { |url| Repository.valid?(url: url) }
       repo = Repository.url_with_owner_and_name(url: valid_repository_url)
-      project_id = if repo[:url]
-        host = repo[:source] == :gitlab ? "gitlab.com" : "github.com"
-        "#{host}/#{repo[:owner]}/#{repo[:name]}"
-      end
-      repo.merge(project_id: project_id)
+      repo.merge(project_id: deps_dev_project_id(repo))
     end
 
     def repository_info_from_installed_gem(gem_name:)
       valid_repository_url =
         installed_gem_urls(gem_name: gem_name).find { |url| Repository.valid?(url: url) }
       repo = Repository.url_with_owner_and_name(url: valid_repository_url)
-      project_id = if repo[:url]
-        host = repo[:source] == :gitlab ? "gitlab.com" : "github.com"
-        "#{host}/#{repo[:owner]}/#{repo[:name]}"
-      end
-      repo.merge(project_id: project_id)
+      repo.merge(project_id: deps_dev_project_id(repo))
+    end
+
+    # deps.dev scorecards index github.com and gitlab.com only. A Forgejo/Codeberg
+    # repo has no deps.dev project, so leave its project_id nil rather than minting
+    # a bogus github.com/owner/name that would fetch the wrong (or no) scorecard.
+    DEPS_DEV_HOST_BY_SOURCE = { github: "github.com", gitlab: "gitlab.com" }.freeze
+
+    def deps_dev_project_id(repo)
+      host = DEPS_DEV_HOST_BY_SOURCE[repo[:source]]
+      return unless repo[:url] && host
+
+      "#{host}/#{repo[:owner]}/#{repo[:name]}"
     end
 
-    def repository_info(gem_name:, versions:)
+    def repository_info(gem_name:, versions:, source_uri: nil)
       valid_repository_url =
         installed_gem_urls(gem_name: gem_name).find { |url| Repository.valid?(url: url) } ||
         rubygems_versions_repository_url(versions: versions).find { |url| Repository.valid?(url: url) } ||
-        rubygems_gem_repository_url(gem_name: gem_name).find { |url| Repository.valid?(url: url) }
+        public_rubygems_repository_url(gem_name: gem_name, source_uri: source_uri)
       Repository.url_with_owner_and_name(url: valid_repository_url)
     end
 
+    # Locally-installed gem metadata and the gem's own version payload are
+    # source-accurate. This public rubygems.org Gems.info lookup is the last
+    # resort, and is skipped for an unqueryable private source: otherwise a
+    # public name-collision's repo/archived/last-commit data would stand in for
+    # the private gem, the same substitution #43 prevents for versions.
+    def public_rubygems_repository_url(gem_name:, source_uri:)
+      return if unqueryable_private_source?(source_uri)
+
+      rubygems_gem_repository_url(gem_name: gem_name).find { |url| Repository.valid?(url: url) }
+    end
+
     def installed_gem_urls(gem_name:)
       info = Gem::Dependency.new(gem_name).matching_specs.first
       return [] if info.nil?
@@ -268,40 +524,35 @@ module StillActive
       []
     end
 
-    def repo_archived(source:, repository_owner:, repository_name:)
+    # The repo-signal provider for a source, or nil for an unhandled host. Every
+    # provider answers archived/last_commit_date; richer signals (e.g.
+    # commits_since_release) are duck-typed and dispatched by respond_to?, so a
+    # provider opts into them by defining the method, with no base class and no
+    # assumption that every source supports every signal.
+    def provider_for(source)
       case source
-      when :github
-        repo = StillActive.config.github_client.repository("#{repository_owner}/#{repository_name}")
-        repo&.archived
-      when :gitlab
-        GitlabClient.archived(owner: repository_owner, name: repository_name)
+      # Without a GitHub token, the live API caps at 60 req/hr -- unusable past a
+      # handful of gems. Fall back to ecosyste.ms (5000 anonymous) so a large
+      # Gemfile still resolves. With a token, the live API stays primary (freshest,
+      # and it carries commits_since_release, which ecosyste.ms doesn't).
+      when :github then StillActive.config.github_oauth_token ? GithubClient : EcosystemsClient
+      when :gitlab then GitlabClient
+      when :forgejo then ForgejoClient
       end
-    rescue Octokit::Error, Faraday::Error => e
-      $stderr.puts("warning: archived check failed for #{repository_owner}/#{repository_name}: #{e.class}")
-      nil
     end
 
-    def last_commit_date(source:, repository_owner:, repository_name:)
-      case source
-      when :github
-        commit = StillActive.config.github_client.commits("#{repository_owner}/#{repository_name}", per_page: 1)&.first
-        date = commit&.commit&.author&.date
-        case date
-        when Time then date
-        when String
-          begin
-            Time.parse(date)
-          rescue ArgumentError
-            $stderr.puts("warning: could not parse commit date for #{repository_owner}/#{repository_name}: #{date.inspect}")
-            nil
-          end
-        end
-      when :gitlab
-        GitlabClient.last_commit_date(owner: repository_owner, name: repository_name)
-      end
-    rescue Octokit::Error, Faraday::Error => e
-      $stderr.puts("warning: last commit check failed for #{repository_owner}/#{repository_name}: #{e.class}")
-      nil
+    # One provider call yields both archived and the last-activity date (the
+    # repo object carries both), so a gem's repo signals cost a single request
+    # instead of two. Returns {} for an unhandled host.
+    def repo_signals(source:, repository_owner:, repository_name:)
+      provider_for(source)&.repo_signals(owner: repository_owner, name: repository_name) || {}
+    end
+
+    def unreleased_commits(source:, repository_owner:, repository_name:, version:)
+      provider = provider_for(source)
+      return unless provider.respond_to?(:commits_since_release)
+
+      provider.commits_since_release(owner: repository_owner, name: repository_name, version: version)
     end
   end
 end

data/lib/still_active.rb

@@ -3,6 +3,9 @@
 require_relative "still_active/version"
 require_relative "still_active/errors"
 require_relative "still_active/config"
+require_relative "still_active/sbom_reader"
+require_relative "still_active/ecosystem_lens"
+require_relative "still_active/sbom_workflow"
 require_relative "still_active/cli"
 
 # Octokit depends on Faraday and emits a deprecation warning at load time

data/still_active.gemspec

@@ -8,15 +8,22 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Sean Floyd"]
   spec.email         = ["contact@seanfloyd.dev"]
 
-  spec.summary       = "Audit your Ruby dependencies for maintenance health, outdated versions, vulnerabilities, and abandoned gems."
-  spec.description   = "Analyses your Gemfile for dependency health: checks if gems are actively maintained " \
-    "(last commit dates via GitHub and GitLab, release dates), outdated versions, archived repos, " \
-    "OpenSSF Scorecard security scores, known vulnerabilities via deps.dev, and libyear drift. " \
-    "Ruby version freshness with EOL detection. " \
-    "Handles rubygems, git, path, and GitHub Packages sources. " \
-    "Outputs coloured terminal tables, markdown, or JSON. " \
-    "CI quality gates with --fail-if-critical, --fail-if-warning, --fail-if-vulnerable, --fail-if-outdated, and --ignore. " \
-    "A comprehensive alternative to running bundle outdated, bundler-audit, and libyear-bundler separately."
+  spec.summary       = "Audit your dependencies for maintenance health, abandonment, and below-the-fix vulnerabilities. " \
+    "Ruby gems natively; npm, PyPI, Cargo, Go, Maven, and NuGet via a CycloneDX SBOM."
+  spec.description   = "Analyses your Gemfile.lock for dependency health across the full transitive graph: " \
+    "whether each gem is actively maintained (last activity on GitHub, GitLab, or Codeberg/Forgejo, plus " \
+    "release recency), outdated versions, archived repos, OpenSSF Scorecard scores, known vulnerabilities " \
+    "(deps.dev and OSV, merged with ruby-advisory-db, flagging advisories with no fix and pins that sit below " \
+    "the fix), poison-pill compatibility ceilings, and libyear drift. Ruby version freshness with EOL detection. " \
+    "The same maintenance lens travels cross-ecosystem: point --sbom at a CycloneDX SBOM to assess npm, PyPI, " \
+    "Cargo, Go, Maven, and NuGet packages via deps.dev and ecosyste.ms. " \
+    "Handles rubygems, git, path, GitHub Packages, and JFrog Artifactory sources. " \
+    "Outputs coloured terminal tables, markdown, JSON (with a versioned, contract-tested schema), " \
+    "SARIF for GitHub code scanning, and a CycloneDX SBOM. " \
+    "CI quality gates (--fail-if-critical / -warning / -vulnerable / -outdated / -poison / -language-ceiling) " \
+    "with granular, committed suppression via .still_active.yml. " \
+    "Complements bundle outdated, bundler-audit, and libyear-bundler by adding the maintenance signal they " \
+    "don't, and folds their version, CVE, and libyear checks into one report."
   spec.homepage      = "https://github.com/SeanLF/still_active"
   spec.license       = "MIT"
   spec.required_ruby_version = ">= 3.3.0"
@@ -24,6 +31,7 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "#{spec.homepage}#readme"
   spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
   spec.metadata["rubygems_mfa_required"] = "true"
 
@@ -51,7 +59,24 @@ Gem::Specification.new do |spec|
   # carry an artificial floor.
   spec.add_runtime_dependency("async", ">= 2.2")
   spec.add_runtime_dependency("bundler", ">= 2.0")
+  # cvss-suite (CVSS v4.0 base-score from an OSV vector, for the CVSS-4-only advisory
+  # deps.dev can't score) is an OPTIONAL dependency, NOT declared here: it exact-pins
+  # bundler and caps bigdecimal, the poison-pill pattern still_active flags, so we
+  # won't force it on users or trip our own audit. CvssHelper soft-requires it; absent,
+  # the OSV/GHSA severity label still carries gating + level and the number is skipped.
+  # Install cvss-suite (or run the distribution that bundles it) to light up the number.
   spec.add_runtime_dependency("faraday-retry")
   spec.add_runtime_dependency("gems")
   spec.add_runtime_dependency("octokit")
+  # Spec-compliant package-URL parsing for SBOM ingestion (decodes npm scopes,
+  # maven group:artifact, qualifiers). 0.1 is the verified floor; the official
+  # package-url org gem (vetted via still_active itself: maintained, no advisories).
+  spec.add_runtime_dependency("packageurl-ruby", ">= 0.1.0")
+  # node-semver range satisfaction for the npm/cargo below-the-fix signal: deciding
+  # whether a CVE's fixed version escapes a package's declared constraint needs
+  # PATCH precision (their fixes are mostly same-major patch bumps), and hand-rolling
+  # node-semver's prerelease + caret-on-0.x rules is the correctness minefield this
+  # composes away. Vetted via still_active itself: maintained (2026 release), MIT,
+  # zero runtime dependencies. cargo reuses it behind a bare-version->caret shim.
+  spec.add_runtime_dependency("semantic_range", ">= 3.0")
 end