still_active 1.6.0 → 3.0.0.rc1

data/lib/helpers/summary_helper.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "activity_helper"
+require_relative "status_helper"
+
+module StillActive
+  # Builds the JSON output's summary{} digest: the headline posture of the audit
+  # in one object, so a machine/LLM consumer reads the totals directly instead
+  # of iterating every gem. Counts are derived from the canonical per-gem fields
+  # (activity_level, archived, up_to_date, vulnerability_count) so they never
+  # drift from a separately-thresholded SARIF rule.
+  module SummaryHelper
+    ACTIVITY_LEVELS = [:ok, :stale, :critical, :archived, :unknown].freeze
+
+    extend self
+
+    def summarize(result, ruby_info: nil)
+      activity = ACTIVITY_LEVELS.to_h { |level| [level, 0] }
+      archived = up_to_date = outdated = vulnerable_gems = vulnerabilities = direct = 0
+
+      result.each_value do |data|
+        activity[ActivityHelper.activity_level(data)] += 1
+        direct += 1 if data[:direct]
+        archived += 1 if data[:archived]
+        up_to_date += 1 if data[:up_to_date] == true
+        outdated += 1 if data[:up_to_date] == false
+        count = data[:vulnerability_count].to_i
+        next unless count.positive?
+
+        vulnerable_gems += 1
+        vulnerabilities += count
+      end
+
+      summary = {
+        total_gems: result.size,
+        direct: direct,
+        transitive: result.size - direct,
+        activity: activity,
+        archived: archived,
+        up_to_date: up_to_date,
+        outdated: outdated,
+        vulnerable_gems: vulnerable_gems,
+        vulnerabilities: vulnerabilities,
+        # The single worst per-gem verdict (plus EOL Ruby), so a consumer reads
+        # one project-level posture without scanning every gem's status.
+        status: StatusHelper.project_status(result, ruby_info: ruby_info),
+      }
+      summary[:ruby_eol] = ruby_info[:eol] == true if ruby_info
+      summary
+    end
+  end
+end

data/lib/helpers/terminal_helper.rb

@@ -2,6 +2,8 @@
 
 require_relative "activity_helper"
 require_relative "ansi_helper"
+require_relative "constraint_helper"
+require_relative "summary_helper"
 require_relative "libyear_helper"
 require_relative "version_helper"
 require_relative "vulnerability_helper"
@@ -22,8 +24,7 @@ module StillActive
       lines << separator_line(widths)
       names.each_with_index do |name, i|
         lines << row_line(rows[i], widths)
-        extra = alternatives_line(result[name])
-        lines << extra if extra
+        lines.concat(sub_lines(result[name]))
       end
       lines << ""
       lines << summary_line(result)
@@ -101,7 +102,8 @@ module StillActive
       return AnsiHelper.green("0") if count.zero?
 
       severity = VulnerabilityHelper.highest_severity(data[:vulnerabilities])
-      label = severity ? "#{count} (#{severity})" : count.to_s
+      notes = [severity, ("no fix" if VulnerabilityHelper.no_fix_available?(data[:vulnerabilities]))].compact
+      label = notes.empty? ? count.to_s : "#{count} (#{notes.join(", ")})"
       AnsiHelper.red(label)
     end
 
@@ -130,6 +132,138 @@ module StillActive
         .join
     end
 
+    # The ↳ sub-lines under a gem row. A poison gem gets the poison receipt (which
+    # names the direct parent itself when transitive, so the generic transitive
+    # line is redundant and dropped); a direct poison gem may still get its
+    # alternatives line. A non-poison gem keeps the prior behaviour: transitive
+    # gems point at the parent (#60), direct ones offer alternatives.
+    def sub_lines(data)
+      lines = if data[:poison]
+        [poison_line(data), (data[:direct] == false ? nil : alternatives_line(data))]
+      else
+        [data[:direct] == false ? dependency_path_line(data) : alternatives_line(data)]
+      end
+      # A language-runtime ceiling is orthogonal to poison/alternatives (a gem can
+      # be maintained yet still cap your Ruby), so it always gets its own line.
+      lines << language_ceiling_line(data)
+      lines.compact
+    end
+
+    # "  ↳ ruby ceiling: <receipt>" (or "python ceiling"), coloured by tier (red =
+    # strands you on an EOL runtime, dim = an FYI cap below the latest stable).
+    # Reuses poison_colour; the runtime name comes off the finding, not hardcoded.
+    def language_ceiling_line(data)
+      ceiling = data[:language_ceiling]
+      return if ceiling.nil?
+
+      AnsiHelper.public_send(poison_colour(ceiling[:severity]), "  ↳ #{ceiling[:runtime].downcase} ceiling: #{language_ceiling_receipt(ceiling, data)}")
+    end
+
+    def language_ceiling_receipt(ceiling, data)
+      runtime = ceiling[:runtime]
+      base =
+        if ceiling[:eol_forced]
+          "requires #{runtime} #{ceiling[:requirement]}, stranding you on end-of-life #{runtime} #{ceiling[:ceiling_version]}#{eol_suffix(ceiling[:ceiling_eol_date])}"
+        else
+          "requires #{runtime} #{ceiling[:requirement]}, no #{runtime} #{ceiling[:latest_stable]} support yet"
+        end
+      "#{base}#{language_ceiling_fix_hint(ceiling, data)}"
+    end
+
+    def eol_suffix(eol_date)
+      eol_date ? " (EOL #{eol_date.strftime("%Y-%m-%d")})" : ""
+    end
+
+    # Name the actionable fix when a newer release of the gem lifts the cap; the
+    # gem's own name sits on the row directly above, so "upgrade to <latest>" reads
+    # unambiguously without repeating it.
+    def language_ceiling_fix_hint(ceiling, data)
+      return "" unless ceiling[:fixed_by_upgrade] && data[:latest_version]
+
+      "; upgrade to #{data[:latest_version]} to lift it"
+    end
+
+    # "  ↳ poison: caps <receipt>", coloured by severity tier (see poison_colour).
+    # The row is already red (poison requires a dormant gem); the sub-line tier
+    # says how urgent the cap is. Transitive gems name the direct parent that pulls
+    # the pill in, the actionable target.
+    def poison_line(data)
+      constraints = data[:constraints]
+      return if constraints.nil? || constraints.empty?
+
+      path = data[:dependency_path]
+      via = data[:direct] == false && path && path.length >= 2 ? " (via #{path.first})" : ""
+      # Colour carries the tier: red = act-now (3+ majors behind), yellow = plan,
+      # dim = a minor/FYI cap (1 behind). A security-relevant cap (it pins a
+      # vulnerable dependency below the fix) is always red -- that's the finding to
+      # act on regardless of how many majors behind it happens to be.
+      colour = data[:poison_security_relevant] ? :red : poison_colour(data[:poison_severity])
+      AnsiHelper.public_send(colour, "  ↳ poison#{via}: #{poison_receipt(constraints)}#{poison_security_suffix(data)}")
+    end
+
+    # Names the vulnerable dependency a security-relevant poison cap pins you to. When
+    # the cap holds you BELOW THE FIX (every patched version is a major it forbids) we
+    # lead with that stronger, enforced claim and name the CVE and its nearest fix --
+    # "you cannot patch this without replacing the dormant capper". Otherwise the
+    # weaker "pins vulnerable X" (the dep is vulnerable, but patchable in place).
+    def poison_security_suffix(data)
+      return "" unless data[:poison_security_relevant]
+
+      below = Array(data[:constraints]).select { |c| c[:capped_below_fix] }
+      if below.any?
+        receipts = below.map { |c| "#{c[:dependency]} below the fix (#{c[:below_fix_advisory]} fixed in #{c[:below_fix_fixed_in]})" }.uniq
+        " ⚠ pins #{receipts.join("; ")}"
+      else
+        pinned = Array(data[:constraints]).select { |c| c[:capped_dep_vulnerable] }.map { |c| c[:dependency] }.uniq
+        " ⚠ pins vulnerable #{pinned.join(", ")}"
+      end
+    end
+
+    def poison_colour(severity)
+      { critical: :red, warning: :yellow, note: :dim }.fetch(severity, :yellow)
+    end
+
+    # A worst-first "N label (X critical, Y note)" summary fragment, coloured by
+    # the worst tier present, or nil when there are none. Shared by the poison and
+    # Ruby-ceiling counts (both roll a set of tiered findings up the same way).
+    def tier_summary_part(severities, label)
+      return if severities.empty?
+
+      by_tier = severities.group_by { |severity| severity || :note }
+      present = ConstraintHelper::SEVERITY.reverse.select { |tier| by_tier[tier] } # worst-first
+      breakdown = present.map { |tier| "#{by_tier[tier].size} #{tier}" }.join(", ")
+      AnsiHelper.public_send(poison_colour(present.first), "#{label} (#{breakdown})")
+    end
+
+    # Single cap: the full receipt (requirement + latest major), since there's
+    # room. Many caps: the worst 3 by majors-behind + "+N more", a glanceable
+    # summary; the complete list stays in the JSON output.
+    def poison_receipt(constraints)
+      top = ConstraintHelper.top_findings(constraints, limit: 3)
+      return single_cap_receipt(top[:shown].first) if top[:total] == 1
+
+      parts = top[:shown].each_with_index.map do |finding, i|
+        count = finding[:majors_behind]
+        i.zero? ? "#{finding[:dependency]} (#{count} behind)" : "#{finding[:dependency]} (#{count})"
+      end
+      remaining = top[:total] - top[:shown].length
+      receipt = "caps #{parts.join(", ")}"
+      remaining.positive? ? "#{receipt} +#{remaining} more" : receipt
+    end
+
+    def single_cap_receipt(finding)
+      behind = finding[:majors_behind]
+      "caps #{finding[:dependency]} #{finding[:requirement]} " \
+        "(#{behind} major#{"s" unless behind == 1} behind, latest #{major_x(finding[:dep_latest])})"
+    end
+
+    # "8.0.1" -> "8.x": the cap is a major-level gap, so the major is the honest
+    # granularity to name as the current latest.
+    def major_x(version)
+      major = version.to_s[/\d+/]
+      major ? "#{major}.x" : version
+    end
+
     def alternatives_line(data)
       level = ActivityHelper.activity_level(data)
       return unless [:archived, :critical].include?(level)
@@ -142,6 +276,18 @@ module StillActive
       end
     end
 
+    # For a flagged transitive gem, name the direct dependency that pulls it in,
+    # the gem the user can actually act on (#60).
+    def dependency_path_line(data)
+      path = data[:dependency_path]
+      return unless path && path.length >= 2
+
+      level = ActivityHelper.activity_level(data)
+      return unless [:archived, :critical].include?(level) || data[:vulnerability_count].to_i.positive?
+
+      AnsiHelper.dim("  ↳ transitive, pulled in by #{path.first}")
+    end
+
     def ruby_summary_line(ruby_info)
       version = ruby_info[:version]
       latest = ruby_info[:latest_version]
@@ -161,29 +307,31 @@ module StillActive
       end
     end
 
+    # Reuse the same digest the JSON output emits so the human summary line can
+    # never drift from the machine one (the #63 "computed two ways" trap). The
+    # terminal keeps a coarser grouping (critical folds into stale) and adds its
+    # own yanked / total-libyear extras that the JSON digest doesn't carry.
     def summary_line(result)
-      total = result.size
-      level_counts = result.each_value.map { |d| ActivityHelper.activity_level(d) }.tally
-      version_counts = result.each_value
-        .map { |d| VersionHelper.up_to_date(version_used: d[:version_used], latest_version: d[:latest_version]) }
-        .tally
-
-      up_to_date = version_counts.fetch(true, 0)
-      outdated = version_counts.fetch(false, 0)
+      summary = SummaryHelper.summarize(result)
+      active = summary[:activity][:ok]
+      stale = summary[:activity][:stale] + summary[:activity][:critical]
+      archived = summary[:activity][:archived]
       yanked = result.each_value.count { |d| d[:version_yanked] }
-      active = level_counts.fetch(:ok, 0)
-      archived = level_counts.fetch(:archived, 0)
-      stale = level_counts.fetch(:stale, 0) + level_counts.fetch(:critical, 0)
-      vulns = result.each_value.sum { |d| d[:vulnerability_count] || 0 }
 
-      parts = [
-        "#{total} gems: #{up_to_date} up to date, #{outdated} outdated",
-      ]
+      parts = ["#{summary[:total_gems]} gems: #{summary[:up_to_date]} up to date, #{summary[:outdated]} outdated"]
       parts.last << ", #{yanked} yanked" if yanked > 0
       activity = "#{active} active, #{stale} stale"
       activity << ", #{archived} archived" if archived > 0
       parts << activity
-      parts << "#{vulns} vulnerabilities"
+      parts << "#{summary[:vulnerabilities]} vulnerabilities"
+      poison_tiers = result.each_value.select { |data| data[:poison] }.map { |data| data[:poison_severity] }
+      poison_part = tier_summary_part(poison_tiers, "#{poison_tiers.size} poison-#{poison_tiers.size == 1 ? "pill" : "pills"}")
+      parts << poison_part if poison_part
+      ceilings = result.each_value.filter_map { |data| data[:language_ceiling] }
+      runtimes = ceilings.map { |ceiling| ceiling[:runtime] }.uniq
+      runtime_label = runtimes.size == 1 ? runtimes.first : "language"
+      ceiling_part = tier_summary_part(ceilings.map { |ceiling| ceiling[:severity] }, "#{ceilings.size} #{runtime_label} ceiling#{"s" unless ceilings.size == 1}")
+      parts << ceiling_part if ceiling_part
       total_libyear = LibyearHelper.total_libyear(result)
       parts << "#{total_libyear.round(1)} libyears behind" if total_libyear > 0
       parts.join(" · ")

data/lib/helpers/version_helper.rb

@@ -12,7 +12,13 @@ module StillActive
       elsif !version_string.nil?
         versions&.find { |v| v["number"] == version_string }
       else
-        versions&.find { |v| v["prerelease"] == pre_release }
+        # The "latest" of a kind: pick the highest by version rather than trust
+        # the source's ordering. RubyGems happens to return newest-first, but
+        # GitHub Packages and other sources don't, and a wrong "latest" cascades
+        # into up_to_date and libyear.
+        versions
+          &.select { |v| v["prerelease"] == pre_release }
+          &.max_by { |v| to_gem_version(v["number"]) || Gem::Version.new("0") }
       end
     end
 
@@ -38,6 +44,15 @@ module StillActive
       Time.parse(release_date) unless release_date.nil?
     end
 
+    # The version's declared Ruby requirement (the `ruby_version` field in the
+    # RubyGems versions payload, e.g. ">= 3.2", "< 3.2"), or nil when absent. This
+    # is the language-runtime ceiling's raw input; note it is `ruby_version`, not
+    # the gemspec's `required_ruby_version`.
+    def ruby_requirement(version_hash:)
+      requirement = version_hash&.dig("ruby_version")
+      requirement unless requirement.nil? || requirement.empty?
+    end
+
     # SPDX license identifier(s) from the RubyGems versions payload.
     # Comma-joined when a gem declares more than one. nil when unknown.
     def license(version_hash:)

data/lib/helpers/vulnerability_helper.rb

@@ -6,20 +6,77 @@ module StillActive
 
     SEVERITY_ORDER = ["low", "medium", "high", "critical"].freeze
 
+    # OSV's GHSA severity labels, mapped to our order. deps.dev stores only CVSS 3.x, so
+    # a CVSS-4-only advisory returns cvss3Score 0 (unscored); OSV's
+    # `database_specific.severity` reads correctly for it and rescues a real HIGH from
+    # fail-closed noise. GitHub uses MODERATE where we use medium.
+    OSV_LABELS = { "critical" => "critical", "high" => "high", "moderate" => "medium", "medium" => "medium", "low" => "low" }.freeze
+
     def highest_severity(vulnerabilities)
       return if vulnerabilities.nil? || vulnerabilities.empty?
 
-      max_score = vulnerabilities.filter_map { |v| v[:cvss3_score] || v[:cvss2_score] }.max
-      return if max_score.nil?
+      vulnerabilities
+        .filter_map { |v| advisory_severity(v) }
+        .max_by { |label| SEVERITY_ORDER.index(label) }
+    end
+
+    # One advisory's severity label ("low".."critical"), or nil when genuinely unscored.
+    # The authoritative GHSA/OSV label is a FLOOR: a real CVSS number sharpens precision
+    # and can RAISE the band, but never lowers it below the label. This matters because
+    # the OSV-derived score is cvss-suite's overall_score, which folds in any
+    # threat/environmental metrics a vector carries (and can diverge from GHSA at a band
+    # edge) -- on a fail-closed, no-false-positive tool a computed number must not
+    # silently demote a GHSA-HIGH finding out of a severity gate. With only one of the
+    # two present, that one stands.
+    def advisory_severity(vulnerability)
+      from_score = (score = effective_score(vulnerability)) ? severity_label(score) : nil
+      from_label = OSV_LABELS[vulnerability[:osv_severity].to_s.downcase]
+      return from_score || from_label if from_score.nil? || from_label.nil?
+
+      [from_score, from_label].max_by { |label| SEVERITY_ORDER.index(label) }
+    end
+
+    # Unknown = no CVSS score AND no OSV label. A freshly disclosed CVE often has
+    # neither yet, and the cross-ecosystem lens emits a minimal advisory when
+    # detail-fetch fails. The CVSS-4-only case (deps.dev returns cvss3Score 0, its
+    # "no 3.x score" sentinel, for two HIGH protobuf GHSAs scored CVSS 4.0) is no
+    # longer unknown once OSV enrichment attaches the GHSA severity label -- that's
+    # the whole point of the enrichment: a real HIGH stops failing closed as unscored.
+    # A truly unknown advisory still fails closed on a gate.
+    def unknown_severity?(vulnerability)
+      advisory_severity(vulnerability).nil?
+    end
 
-      severity_label(max_score)
+    # True when at least one advisory has no fixed version available -- the gem
+    # can't be upgraded out of the vulnerability. Only ruby-advisory-db sets this
+    # today; a deps.dev-only advisory leaves it nil (unknown), which reads false.
+    def no_fix_available?(vulnerabilities)
+      Array(vulnerabilities).any? { |vulnerability| vulnerability[:no_fix_available] }
+    end
+
+    # The best real CVSS score for an advisory, or nil when none is usable. Prefers
+    # deps.dev's v3/v2, then the score OSV enrichment computed from a v4 (or v3)
+    # vector. A score of 0 is treated as absent: deps.dev only stores CVSS 3.x, so a
+    # CVSS-4-only advisory (e.g. two HIGH protobuf GHSAs) comes back with cvss3Score
+    # 0 -- its "no 3.x score" sentinel, not a genuine severity of zero (which
+    # published advisories never carry) -- and the OSV v4 score fills that gap. Every
+    # consumer of a numeric score (severity labels, SARIF level, CycloneDX rating)
+    # routes through here so a 0 can't masquerade as "low" and silently clear a gate.
+    def effective_score(vulnerability)
+      [vulnerability[:cvss3_score], vulnerability[:cvss2_score], vulnerability[:osv_cvss_score]].find { |score| score&.positive? }
     end
 
     def severity_at_or_above?(vulnerabilities, threshold)
-      highest = highest_severity(vulnerabilities)
-      return false if highest.nil?
+      return false if vulnerabilities.nil? || vulnerabilities.empty?
+
+      # Fail closed on an unscored advisory: a confirmed advisory we can't score
+      # could be anything up to critical (and fresh CVEs commonly lack a score),
+      # so passing it as "below threshold" would silently clear a severity gate on
+      # a real finding. The user accepts a specific advisory via a suppression if
+      # they've reviewed it. Only when every advisory is scored do we compare.
+      return true if vulnerabilities.any? { |vulnerability| unknown_severity?(vulnerability) }
 
-      SEVERITY_ORDER.index(highest) >= SEVERITY_ORDER.index(threshold)
+      SEVERITY_ORDER.index(highest_severity(vulnerabilities)) >= SEVERITY_ORDER.index(threshold)
     end
 
     # Combines advisories from deps.dev and ruby-advisory-db (via bundler-audit),
@@ -44,7 +101,11 @@ module StillActive
     private
 
     def identifiers(advisory)
-      [advisory[:id], *advisory[:aliases]].compact
+      # Coerce to strings: advisory ids/aliases are strings, but deps.dev's ALPHA API
+      # could drift and hand back a non-string alias, and a mixed array makes the
+      # union's `.sort` (in combine!) raise -- which escapes to the per-gem rescue that
+      # strips ALL the gem's signals, reading a known-vulnerable gem as clean.
+      [advisory[:id], *advisory[:aliases]].compact.map(&:to_s)
     end
 
     # Folds a ruby-advisory-db advisory into a matching deps.dev advisory in place:
@@ -56,6 +117,11 @@ module StillActive
       into[:title] ||= from[:title]
       into[:url] ||= from[:url]
       into[:aliases] = (identifiers(into) | identifiers(from)).reject { |id| id == into[:id] }.sort
+      # ruby-advisory-db is the sole authority for fix availability; its
+      # determination wins whenever it has one (deps.dev leaves the key absent
+      # today, but this fails safe if that ever changes: a radb "no fix" can't be
+      # overridden by a stale/absent deps.dev value on a security-adjacent field).
+      into[:no_fix_available] = from[:no_fix_available] unless from[:no_fix_available].nil?
       into[:source] = "merged"
     end
 

data/lib/still_active/artifactory_client.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "bundler"
+require "cgi"
+require "json"
+require "uri"
+require_relative "../helpers/http_helper"
+
+module StillActive
+  module ArtifactoryClient
+    extend self
+
+    def artifactory_uri?(uri)
+      # Hostnames are case-insensitive, so downcase before the suffix check; an
+      # uppercase jfrog host would otherwise be misread as an unqueryable source.
+      uri.is_a?(String) && URI(uri).host&.downcase&.end_with?(".jfrog.io")
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def versions(gem_name:, source_uri:)
+      headers = auth_headers(gem_name: gem_name, source_uri: source_uri)
+      vs = RubygemsClient.versions(gem_name: gem_name, source_uri: source_uri, headers: headers)
+      return vs unless vs.empty?
+
+      AqlClient.versions(gem_name: gem_name, source_uri: source_uri, headers: headers)
+    rescue Errno::ECONNRESET, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout, SocketError
+      []
+    end
+
+    private
+
+    def credentials(gem_name:, source_uri:)
+      host = URI(source_uri).host
+      bundler = Bundler.settings[source_uri] || Bundler.settings[host]
+      return bundler if bundler && !bundler.empty?
+
+      global = StillActive.config.artifactory_token
+      return unless global
+
+      configured_host = StillActive.config.artifactory_host
+      unless configured_host && host&.casecmp?(configured_host)
+        warn_unauthorized_host(gem_name: gem_name, host: host)
+        return
+      end
+
+      global
+    end
+
+    def warn_unauthorized_host(gem_name:, host:)
+      $stderr.puts(
+        "warning: an Artifactory token is set but #{host} (source for #{gem_name}) is not an authorized host, " \
+          "so the token will not be sent. " \
+          "To allow it, set --artifactory-host=#{host} or STILL_ACTIVE_ARTIFACTORY_HOST=#{host}",
+      )
+    end
+
+    def auth_headers(gem_name:, source_uri:)
+      creds = credentials(gem_name: gem_name, source_uri: source_uri)
+      return {} unless creds
+
+      if creds.include?(":")
+        user, pass = creds.split(":", 2).map { |part| CGI.unescape(part) }
+        { "Authorization" => "Basic #{["#{user}:#{pass}"].pack("m0")}" }
+      else
+        { "Authorization" => "Bearer #{creds}" }
+      end
+    end
+
+    # Artifactory's Rubygems-compatible API
+    module RubygemsClient
+      extend self
+
+      def versions(gem_name:, source_uri:, headers: {})
+        base = URI(source_uri.chomp("/"))
+        path = "#{base.path}/api/v1/versions/#{encode(gem_name)}.json"
+        HttpHelper.get_json(base, path, headers: headers) || []
+      end
+
+      private
+
+      def encode(value)
+        CGI.escape(value)
+      end
+    end
+
+    # AQL stands for Artifactory Query Language
+    # https://docs.jfrog.com/artifactory/docs/artifactory-query-language
+    module AqlClient
+      extend self
+
+      SOURCE_URL_PATTERN = %r{\A(https?://[^/]+\.jfrog\.io/[^/]+)/api/gems/([^/]+)/?\z}
+      AQL_PATH = "/api/search/aql"
+
+      def versions(gem_name:, source_uri:, headers: {})
+        artifactory_base, repo_key = parse_source_url(source_uri)
+        return [] if artifactory_base.nil?
+
+        base = URI(artifactory_base)
+        path = "#{base.path}#{AQL_PATH}"
+        query = {
+          "name" => { "$match" => "#{gem_name}-*.gem" },
+          "repo" => repo_key,
+        }
+        body = %(items.find(#{JSON.generate(query)}).include("repo", "path", "name", "created"))
+        response = HttpHelper.post_json(base, path, body: body, headers: headers.merge("Content-Type" => "text/plain"))
+        return [] if response.nil?
+
+        results = response["results"] || []
+        build_version_hashes(results: results, gem_name: gem_name)
+      end
+
+      private
+
+      def parse_source_url(source_uri)
+        match = source_uri.match(SOURCE_URL_PATTERN)
+        unless match
+          $stderr.puts("warning: unrecognized Artifactory source URL for AQL fallback: #{source_uri}")
+          return [nil, nil]
+        end
+
+        [match[1], match[2]]
+      end
+
+      def build_version_hashes(results:, gem_name:)
+        results
+          .filter_map do |item|
+            version = extract_version(item["name"], gem_name)
+            next if version.nil?
+
+            {
+              "number" => version,
+              "created_at" => item["created"],
+              "prerelease" => Gem::Version.new(version).prerelease?,
+            }
+          end
+          .uniq { |h| h["number"] }
+          .sort_by { |h| Gem::Version.new(h["number"]) }
+          .reverse
+      end
+
+      def extract_version(filename, gem_name)
+        prefix = "#{gem_name}-"
+        return unless filename&.end_with?(".gem") && filename.start_with?(prefix)
+
+        version_part = filename[prefix.length..-5]
+        return if version_part.nil? || version_part.empty?
+
+        parse_version_from_filename_tail(version_part)
+      end
+
+      # Given the portion of a `.gem` filename after `name-`, returns the
+      # leading semver (e.g. `7.0.0` from `7.0.0-x86_64-linux`). Ignores
+      # unrelated artifacts that share a prefix (e.g. `datadog-ruby_core_source`
+      # when the gem name is `datadog`).
+      def parse_version_from_filename_tail(version_part)
+        segments = version_part.split("-")
+        segments.length.times do |i|
+          candidate = segments[0, i + 1].join("-")
+          return candidate if Gem::Version.correct?(candidate)
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/still_active/ceiling_reconciler.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module StillActive
+  # Whole-tree correlation between the two capping signals, run once after the
+  # fan-out (native or SBOM) has assembled every package's findings. A language
+  # ceiling that says "upgrade <package> to lift it" is wrong if the same tree
+  # poisons <package> below that upgrade (a dormant dependency caps it): the
+  # report must never advise an upgrade its own poison finding says is impossible.
+  # All data is already in the assembled result, so this is one pass, no fetches.
+  # "The correlation layer must correlate."
+  module CeilingReconciler
+    extend self
+
+    def reconcile_ceiling_with_poison(result_object)
+      # Qualify each capped dependency by the ecosystem that declares the cap. A
+      # capped dep resolves in its parent's ecosystem, so a poison finding on a
+      # `pypi` package caps a `pypi` dependency. A mixed SBOM has two flat-
+      # resolution ecosystems (rubygems + pypi), so a bare-name match alone would
+      # let a rubygems poison-cap on "foo" wrongly block a pypi "foo"'s ceiling.
+      # Native results carry no :ecosystem (all rubygems) -> nil on both sides,
+      # still consistent.
+      capped = result_object.each_value
+        .flat_map do |data|
+          Array(data[:constraints])
+            .select { |constraint| constraint[:majors_behind].to_i.positive? }
+            .map { |constraint| "#{data[:ecosystem]}/#{constraint[:dependency]}" }
+        end
+        .uniq
+      result_object.each do |key, data|
+        ceiling = data[:language_ceiling]
+        next unless ceiling && ceiling[:fixed_by_upgrade]
+
+        # Native results are keyed by the bare gem name; SBOM results are keyed by
+        # "ecosystem/name@version" and carry the bare name in :name.
+        package_name = data[:name] || key
+        next unless capped.include?("#{data[:ecosystem]}/#{package_name}")
+
+        ceiling[:fixed_by_upgrade] = false
+        ceiling[:upgrade_blocked] = true
+      end
+    end
+  end
+end