still_active 2.0.0 → 3.0.0.rc1

data/lib/helpers/sarif_helper.rb

@@ -6,6 +6,7 @@ require "time"
 require_relative "../still_active/sarif/rules"
 require_relative "lockfile_indexer"
 require_relative "activity_helper"
+require_relative "constraint_helper"
 
 module StillActive
   # Renders a still_active workflow result as a SARIF 2.1.0 document.
@@ -137,9 +138,101 @@ module StillActive
         out << mark_suppressed(result("SA007", name, "#{name} #{version}: this version has been yanked from RubyGems.", location), name, :yanked)
       end
 
+      if data[:poison] && !Array(data[:constraints]).empty?
+        # Level tracks the poison tier (critical->error, ...); a plain majors-behind
+        # tier change keeps the (rule_id, gem_name) fingerprint so it doesn't re-alert.
+        # But an escalation up the tiers (maintenance -> security-relevant -> below the
+        # fix) adds a fingerprint dimension so a past dismissal of a weaker tier can't
+        # silently mute the stronger one -- the transition a human must see.
+        state = if data[:poison_below_fix]
+          "below_fix"
+        elsif data[:poison_security_relevant]
+          "security"
+        else
+          "maintenance"
+        end
+        out << mark_suppressed(result("SA008", name, poison_message(name, version, data), location, level: poison_level(data), fp_extra: state), name, :poison)
+      end
+
+      if data[:language_ceiling]
+        # Level tracks the ceiling tier: critical (EOL-forced) -> error, note
+        # (latest-not-yet) -> note. Fingerprint is (rule_id, gem_name, state) where
+        # state is the eol_forced boolean: cosmetic churn (which patch, which
+        # latest) doesn't re-alert, but a note -> EOL-forced escalation (a supported
+        # runtime went EOL) mints a NEW alert so a past dismissal of the note can't
+        # silently mute the critical -- that transition is exactly the one a human
+        # must see.
+        state = data[:language_ceiling][:eol_forced] ? "eol_forced" : "latest_not_yet"
+        out << mark_suppressed(result("SA009", name, language_ceiling_message(name, version, data), location, level: language_ceiling_level(data), fp_extra: state), name, :language_ceiling)
+      end
+
       out
     end
 
+    def language_ceiling_level(data)
+      { critical: "error", warning: "warning", note: "note" }.fetch(data[:language_ceiling][:severity], "note")
+    end
+
+    def language_ceiling_message(name, version, data)
+      ceiling = data[:language_ceiling]
+      runtime = ceiling[:runtime]
+      body =
+        if ceiling[:eol_forced]
+          eol = ceiling[:ceiling_eol_date]
+          eol_part = eol ? " (EOL #{format_date(eol)})" : ""
+          "stranding you on end-of-life #{runtime} #{ceiling[:ceiling_version]}#{eol_part}"
+        else
+          "no #{runtime} #{ceiling[:latest_stable]} support yet"
+        end
+      fix = ceiling[:fixed_by_upgrade] && data[:latest_version] ? "; upgrade to #{data[:latest_version]} to lift it" : ""
+      "#{name} #{version}: requires #{runtime} #{ceiling[:requirement]}, #{body}#{fix}#{transitive_suffix(data)}."
+    end
+
+    # The poison receipt for a Code Scanning alert: the worst 3 caps (shared
+    # ranking via ConstraintHelper.top_findings so it can't drift from the other
+    # renderers) with the exact latest version (a machine-read alert wants the
+    # precise version, not the "8.x" the terminal abbreviates to), plus "+N more"
+    # and the transitive parent. Note result() fingerprints on (rule_id, gem_name)
+    # only, so this volatile detail never re-alerts a finding the user triaged.
+    def poison_level(data)
+      # A security-relevant cap (a dormant dep pins a known-vulnerable dependency
+      # below its fix) escalates to error regardless of majors-behind: it's a real
+      # security finding, not the maintenance-tier signal poison usually is.
+      return "error" if data[:poison_security_relevant]
+
+      { critical: "error", warning: "warning", note: "note" }.fetch(data[:poison_severity], "warning")
+    end
+
+    def poison_message(name, version, data)
+      top = ConstraintHelper.top_findings(Array(data[:constraints]), limit: 3)
+      caps = top[:shown].map do |finding|
+        behind = finding[:majors_behind]
+        "#{finding[:dependency]} #{finding[:requirement]} (#{behind} major#{"s" unless behind == 1} behind, latest #{finding[:dep_latest]})"
+      end
+      remaining = top[:total] - top[:shown].length
+      caps << "+#{remaining} more" if remaining.positive?
+      "#{name} #{version}: caps #{caps.join("; ")}#{transitive_suffix(data)}#{poison_security_note(data)}."
+    end
+
+    # Spells out the security escalation for a code-scanning alert. Only claims
+    # "below the fix" (with the CVE and its nearest fix, a version the cap forbids)
+    # when that is actually established. Otherwise we say only that the dep is
+    # known-vulnerable, WITHOUT asserting patchability: this branch also covers a
+    # HIGH advisory with no released fix at all (class C), which is not patchable in
+    # place, so an "(patchable in place)" claim here would be false on the worst case.
+    def poison_security_note(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]}, outside the cap)" }.uniq
+        " -- pins #{receipts.join("; ")}"
+      else
+        pinned = Array(data[:constraints]).select { |c| c[:capped_dep_vulnerable] }.map { |c| c[:dependency] }.uniq
+        " -- pins known-vulnerable #{pinned.join(", ")}"
+      end
+    end
+
     # Attaches a SARIF native suppressions[] entry when this finding is covered
     # by a whole-gem --ignore or a granular .still_active.yml suppression, so a
     # GitHub code-scanning consumer renders it dismissed rather than open. The
@@ -161,18 +254,27 @@ module StillActive
     end
 
     def vulnerability_result(name, version, vuln, location, data = {})
-      score = vuln[:cvss3_score] || vuln[:cvss2_score]
-      level = Sarif::Rules.cvss_to_level(score)
+      # Level tracks the resolved severity LABEL (a real CVSS score OR OSV's GHSA
+      # label), so a CVSS-4-only HIGH -- which deps.dev returns as cvss3Score 0 --
+      # exports as error, not a note/warning a code-scanning gate reads as
+      # informational. The security-severity NUMBER stays tied to a real CVSS score
+      # (effective_score): a label-only advisory carries no invented number rather
+      # than a fabricated 7.0. A confirmed-but-unscored advisory still fails closed.
+      score = VulnerabilityHelper.effective_score(vuln)
+      level = Sarif::Rules.severity_to_level(VulnerabilityHelper.advisory_severity(vuln))
       severity = Sarif::Rules.cvss_to_security_severity(score)
       advisory_id = vuln[:id] || Array(vuln[:aliases]).first || "unknown"
       aliases = Array(vuln[:aliases]).first(3).join(", ")
       alias_suffix = aliases.empty? ? "" : " [#{aliases}]"
       title = vuln[:title] ? ": #{vuln[:title]}" : ""
+      # ruby-advisory-db records no safe version: upgrading can't clear it, which
+      # is the actionable distinction from an ordinary (patchable) advisory.
+      no_fix = vuln[:no_fix_available] ? " (no fixed version available)" : ""
 
       base = result(
         "SA003",
         name,
-        "#{name} #{version}: #{advisory_id}#{title}#{alias_suffix}#{transitive_suffix(data)}.",
+        "#{name} #{version}: #{advisory_id}#{title}#{alias_suffix}#{no_fix}#{transitive_suffix(data)}.",
         location,
         level: level,
         fp_extra: advisory_id,

data/lib/helpers/semver_satisfaction.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "semantic_range"
+
+module StillActive
+  # Does a concrete version satisfy a declared requirement, at PATCH precision,
+  # for npm and cargo? This is the primitive the cross-ecosystem below-the-fix
+  # signal needs: a CVE's fix is usually a same-major patch bump, so "can this fix
+  # be reached within the package's constraint" cannot be answered by the coarse,
+  # major-precision ConstraintHelper. node-semver's caret/tilde/OR/prerelease rules
+  # are a correctness minefield, so we lean on the semantic_range gem (a node-semver
+  # port) rather than reimplement them.
+  #
+  # npm ranges are node-semver as-is. cargo's VersionReq agrees with node-semver on
+  # every operator form, and diverges on ANY operator-less bare version: cargo treats
+  # a bare version as a caret (`1.2.3` = `^1.2.3`, `1.2` = `^1.2` = `>=1.2.0 <2.0.0`,
+  # `1` = `^1`), while node-semver reads a bare full version as an exact pin and a
+  # partial `1.2` as the narrower `1.2.x` (`<1.3.0`). Per the Cargo Book's caret
+  # table, node-semver's caret expands identically to cargo's for every one of these
+  # forms, so the whole shim is: prefix `^` to a bare version before evaluating.
+  # Getting it wrong (e.g. leaving `1.2` unshimmed) reads a reachable fix as
+  # unreachable and fabricates a below-the-fix security finding.
+  module SemverSatisfaction
+    extend self
+
+    # An operator-less bare version, 1 to 3 numeric components, optional prerelease
+    # and/or build tail (`1`, `1.2`, `1.2.3`, `0.10.38`, `1.2.3-alpha+001`). cargo
+    # reads any of these as a caret; node-semver does not, so cargo shims them.
+    BARE_VERSION = /\A\s*v?\d+(?:\.\d+){0,2}(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\s*\z/
+
+    # Does `version` satisfy `requirement`? true / false when decidable; nil when the
+    # requirement or version isn't valid semver for the ecosystem, or the ecosystem
+    # isn't one we model. The tri-state is deliberate (hence a plain verb, not a
+    # `?` predicate): semantic_range returns false for garbage, and a false would read
+    # as "the fix can't be reached" in a wall test and fabricate a below-the-fix flag.
+    # The caller must treat nil as "cannot establish a wall", never as unreachable.
+    def evaluate(requirement:, version:, ecosystem:)
+      range = range_for(requirement, ecosystem)
+      return if range.nil? # undecidable: unmodelled ecosystem or unparseable requirement
+      return if SemanticRange.valid(version.to_s).nil? # undecidable: unparseable version
+
+      SemanticRange.satisfies?(version.to_s, range)
+    end
+
+    private
+
+    # The node-semver range string for this ecosystem's requirement, or nil if it
+    # isn't a valid range (or the ecosystem is unmodelled). cargo's bare-version
+    # caret is applied BEFORE validation so the shimmed form is what gets checked.
+    def range_for(requirement, ecosystem)
+      requirement = requirement.to_s.strip
+      # A blank requirement is missing data (a failed extraction), NOT a package that
+      # allows any version: semantic_range reads "" as `*` (matches everything), which
+      # would be a false-confident answer. Keep it undecidable, like a blank version.
+      return if requirement.empty?
+
+      case ecosystem
+      when :npm then SemanticRange.valid_range(requirement)
+      when :cargo then SemanticRange.valid_range(cargo_normalize(requirement))
+      end
+    end
+
+    # `requirement` arrives already stripped from range_for.
+    def cargo_normalize(requirement)
+      requirement.match?(BARE_VERSION) ? "^#{requirement}" : requirement
+    end
+  end
+end

data/lib/helpers/status_helper.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "activity_helper"
+
+module StillActive
+  # Collapses a gem's several maintenance signals into one categorical verdict,
+  # so a machine/LLM consumer (or another tool's report) can display and threshold
+  # a single value instead of re-deriving it from activity_level + archived +
+  # vulnerability_count. This is deliberately NOT a numeric composite: an earlier
+  # 0-100 score was removed because a weighted average let missing data read as
+  # "perfect health". Here, :unknown stays :unknown -- absence of data is never
+  # rendered as :ok.
+  module StatusHelper
+    extend self
+
+    # Worst-first lifecycle verdict. The key distinction (from the "done gems"
+    # critique and validated against the maintenance-tooling landscape): a clean,
+    # long-dormant gem is :legacy ("done", low risk), NOT a problem -- whereas a
+    # dormant or archived gem carrying an unpatched advisory is :dead (no one is
+    # going to fix it, migrate). :unknown is least severe -- an absence, not a
+    # finding -- so missing data never reads as :ok.
+    SEVERITY = [:unknown, :ok, :legacy, :stale, :archived, :vulnerable, :dead].freeze
+
+    # Returns :dead, :vulnerable, :archived, :legacy, :stale, :ok, or :unknown.
+    def gem_status(gem_data)
+      vulnerable = gem_data[:vulnerability_count].to_i.positive?
+
+      # A pinned version the registry can't resolve (yanked, typo, or nonexistent)
+      # has no version-specific data to judge, so package-level health must not read
+      # it as :ok. Absence of data is :unknown, never a false all-clear. Guarded on
+      # `!vulnerable` so a detected advisory always wins, in case a future source
+      # ever attaches one to an otherwise-unresolved version.
+      return :unknown if gem_data[:version_unresolved] && !vulnerable
+
+      level = ActivityHelper.activity_level(gem_data)
+
+      if vulnerable
+        # A vulnerability in a dormant or archived gem won't be patched -> :dead;
+        # in an actively-released gem a fix is plausible -> :vulnerable.
+        return [:critical, :archived].include?(level) ? :dead : :vulnerable
+      end
+
+      case level
+      when :archived
+        # archived != EOL: a repo archived while the gem still publishes recent
+        # releases (development moved to a monorepo) isn't dead -- let the
+        # releases speak, but keep :stale so the archived repo stays a yellow flag.
+        ActivityHelper.release_recency_level(gem_data) == :ok ? :stale : :archived
+      when :critical then :legacy # long-dormant but clean: feature-complete, not a fire
+      else level # :stale / :ok / :unknown
+      end
+    end
+
+    # The single worst gem status across the audit. An EOL Ruby floors the
+    # project at :vulnerable (the runtime itself is a live, actionable risk).
+    # :unknown only wins when nothing better is known.
+    def project_status(result, ruby_info: nil)
+      statuses = result.each_value.map { |data| gem_status(data) }
+      statuses << :vulnerable if ruby_info&.dig(:eol) == true
+      return :unknown if statuses.empty?
+
+      # Every value gem_status returns is in SEVERITY today; if a future status
+      # isn't, rank it most-severe so it surfaces in the rollup rather than being
+      # silently masked by a milder finding.
+      statuses.max_by { |status| SEVERITY.index(status) || SEVERITY.length }
+    end
+  end
+end

data/lib/helpers/summary_helper.rb

@@ -1,6 +1,7 @@
 # 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
@@ -40,6 +41,9 @@ module StillActive
         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

data/lib/helpers/terminal_helper.rb

@@ -2,6 +2,7 @@
 
 require_relative "activity_helper"
 require_relative "ansi_helper"
+require_relative "constraint_helper"
 require_relative "summary_helper"
 require_relative "libyear_helper"
 require_relative "version_helper"
@@ -23,11 +24,7 @@ module StillActive
       lines << separator_line(widths)
       names.each_with_index do |name, i|
         lines << row_line(rows[i], widths)
-        data = result[name]
-        # Transitive gems can't be swapped directly, so point at the direct
-        # parent instead of suggesting alternatives for them (#60).
-        extra = data[:direct] == false ? dependency_path_line(data) : alternatives_line(data)
-        lines << extra if extra
+        lines.concat(sub_lines(result[name]))
       end
       lines << ""
       lines << summary_line(result)
@@ -105,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
 
@@ -134,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)
@@ -194,6 +324,14 @@ module StillActive
       activity << ", #{archived} archived" if archived > 0
       parts << activity
       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

@@ -44,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/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