still_active 2.0.0 → 3.0.0.rc2

data/lib/helpers/constraint_helper.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module StillActive
+  # Reads a declared dependency constraint (the requirement string a package
+  # publishes for one of its runtime deps, e.g. "~> 4.2", "< 5.0", "= 1.2.3") and
+  # answers how much it caps you: is there an upper bound, and how many majors
+  # behind the dependency's current latest does it hold you?
+  #
+  # This is the constraint half of the poison-pill signal (constraint-tightness x
+  # maintenance-state): a dormant package that caps a still-evolving dep below its
+  # latest major holds your tree hostage with no hope of the cap lifting. A fixed
+  # cap gets more poisonous purely with time, as the capped dep ships new majors
+  # while the cap stays frozen.
+  #
+  # Grammar is coarse but cross-ecosystem: Ruby pessimistic (~>), pip compatible
+  # (~=), semver caret/tilde (^ ~), exact (= == ===), and plain </<=. Precision is
+  # at the MAJOR level, which is all the signal needs ("N majors behind").
+  module ConstraintHelper
+    extend self
+
+    # The constraint kinds that make a dep a poison-pill candidate: an upper bound
+    # that blocks upgrades, or an exact pin that freezes the whole tree. A
+    # `:permissive` constraint is neither. Shared with the workflow so the poison
+    # definition lives in one place.
+    POISON_KINDS = [:ceiling, :exact_pin].freeze
+
+    # An exact pin: = / == / === before a digit (NOT >= or <=).
+    EXACT_PIN = /\A={1,3}\s*v?\d/
+    # A bare version with no operator (npm/cargo exact form), e.g. "1.2.3", "v1".
+    BARE_VERSION = /\Av?\d+(?:\.\d+)*\z/
+    # Operator + version at the head of a clause.
+    CLAUSE = /\A(===?|=|<=|<|~>|~=|\^|~)?\s*v?(\d+(?:\.\d+)*)/
+    # Whitespace that separates npm AND clauses (">=1.2.0 <2.0.0"), i.e. a space
+    # before an operator. It won't split a Ruby clause like "~> 4.2" (the space
+    # there precedes a digit, not an operator). The quantifier is POSSESSIVE
+    # (`\s++`, not `\s+`): a lookahead after a greedy `\s+` backtracks once per
+    # trailing space, which is quadratic on a long run of spaces (ReDoS on the
+    # lockfile-derived requirement string). Possessive matching never backtracks.
+    AND_SEPARATOR = /\s++(?=[<>=~^])/
+    # A real declared requirement ("< 5.0, >= 4.0.1", "^1 || ^2 || ^3") is short.
+    # Anything past this is not a parseable constraint, so cap the input up front:
+    # it bounds every regex below to linear work and refuses to mint a pill from
+    # garbage (an over-long string reads as permissive, never a false ceiling).
+    MAX_REQUIREMENT_LENGTH = 256
+
+    # => { kind: :permissive|:ceiling|:exact_pin, majors_behind: Integer }
+    def analyze(requirement:, dep_latest:)
+      return { kind: :permissive, majors_behind: 0 } if requirement.to_s.length > MAX_REQUIREMENT_LENGTH
+
+      # `||` is an OR-range (npm): satisfied by ANY branch, so an unbounded branch
+      # lifts the cap entirely and the effective ceiling is the LOOSEST branch.
+      # Reading only the first branch would invent a false pill on the common
+      # `^2.0.0 || ^3.0.0` "supports several majors" form.
+      branches = requirement.to_s.split("||").map { |branch| clauses_of(branch) }
+      branches = [[]] if branches.empty?
+      ceilings = branches.map { |clauses| branch_ceiling(clauses) }
+      latest_major = major(dep_latest)
+
+      return { kind: :permissive, majors_behind: 0 } if ceilings.any?(&:nil?)
+
+      behind = latest_major ? [latest_major - ceilings.max, 0].max : 0
+      kind = branches.all? { |clauses| all_exact?(clauses) } ? :exact_pin : :ceiling
+      { kind: kind, majors_behind: behind }
+    end
+
+    # Severity tiers for a compatibility ceiling, worst-last (mirrors
+    # StatusHelper::SEVERITY -- an ordinal set compared by index, never a numeric
+    # composite). :note is FYI, :warning is review-and-plan, :critical is act-now.
+    SEVERITY = [:note, :warning, :critical].freeze
+
+    # Tier one ceiling finding. Magnitude-driven: the real-project dogfood showed
+    # Ruby findings are bimodal -- 1 major behind is trivial (a done gem pinning an
+    # old minor), 3+ is a genuine upgrade wall (e.g. capping actionmailer below
+    # Rails 6). Popularity was rejected as an input (it ranks the framework blocker
+    # below a utility) and a vulnerable-gem escalator was rejected (that is the
+    # vulnerability finding's job, not the cap's).
+    def constraint_severity(finding)
+      # A runtime ceiling that strands you on an end-of-life Ruby is act-now: no
+      # patched runtime is reachable. This short-circuit lets the language-ceiling
+      # signal (which carries no majors_behind) reuse the same tierer as poison.
+      return :critical if finding[:eol_forced]
+
+      case finding[:majors_behind]
+      when 2 then :warning
+      when 3.. then :critical
+      else :note
+      end
+    end
+
+    # The worst tier across a gem's CEILING findings (exact-pins are a milder
+    # hazard, not poison, and don't carry a tier), or nil when there are none.
+    def worst_severity(findings)
+      tiers = findings.filter_map { constraint_severity(_1) if _1[:kind] == :ceiling }
+      tiers.max_by { SEVERITY.index(_1) }
+    end
+
+    # For the --fail-if-poison[=TIER] gate: is `severity` at or above `threshold`?
+    def severity_at_or_above?(severity, threshold)
+      return false if severity.nil?
+
+      SEVERITY.index(severity) >= SEVERITY.index(threshold)
+    end
+
+    # True when `version` sits at or below the highest major the cap allows -- i.e.
+    # you could upgrade the capped dep to it WITHOUT breaking the cap. The ceiling
+    # major is recovered from the poison finding itself (dep_latest minus
+    # majors_behind), at the same major precision the poison signal already uses, so
+    # a fix that lands OUTSIDE the cap ("below the fix") is detected without
+    # re-parsing the raw requirement and its pre/dev-release quirks (`< 5.0.0dev`).
+    #
+    # Precision is MAJOR-level by design, and that errs deliberately toward reachable:
+    # a within-major cap (`~> 4.2.1`, `< 5.5`) reads a same-major fix (4.9.0, 5.29.6)
+    # as reachable even though the cap forbids it. So a genuinely-stuck within-major
+    # cap is UNDER-reported (downgraded to the still-visible "vulnerable" tier), never
+    # falsely promoted -- when this DOES return false for every fix, the below-the-fix
+    # claim is sound (every fix is in a strictly higher major than the cap allows).
+    # Unparseable/absent inputs read false (never claims reachable when we can't tell).
+    def reachable_within_cap?(finding, version)
+      fix_major = major(version)
+      latest_major = major(finding[:dep_latest])
+      behind = finding[:majors_behind]
+      return false if fix_major.nil? || latest_major.nil? || behind.nil?
+
+      fix_major <= latest_major - behind
+    end
+
+    # The poison condition: a below-latest ceiling or exact pin. A permissive
+    # constraint, or a cap at/above the dep's latest major, is not a pill.
+    def poison_ceiling?(requirement:, dep_latest:)
+      result = analyze(requirement: requirement, dep_latest: dep_latest)
+      POISON_KINDS.include?(result[:kind]) && result[:majors_behind].positive?
+    end
+
+    # Build the poison-pill receipts for a package's declared runtime deps. Each
+    # `dep` is { package_name:, requirements: }; the block resolves a dep name to
+    # its current latest version string (or nil when unresolvable, which drops the
+    # dep rather than guessing). Returns only the below-latest ceilings and exact
+    # pins, each as a self-contained receipt. Shared by the native Bundler path and
+    # the cross-ecosystem lens, which differ only in how they resolve dep_latest.
+    def poison_findings(deps)
+      deps.filter_map do |dep|
+        dep_latest = yield(dep[:package_name])
+        next if dep_latest.nil?
+
+        result = analyze(requirement: dep[:requirements], dep_latest: dep_latest)
+        next unless POISON_KINDS.include?(result[:kind]) && result[:majors_behind].positive?
+
+        {
+          dependency: dep[:package_name],
+          requirement: dep[:requirements],
+          dep_latest: dep_latest,
+          majors_behind: result[:majors_behind],
+          kind: result[:kind],
+        }
+      end
+    end
+
+    # Select the worst `limit` findings for a display receipt, plus the full count
+    # so a renderer can say "+N more" / "N total". Worst-first by majors_behind,
+    # ties broken by dependency name so the output is stable and diffable. Shared
+    # by the terminal and markdown renderers so the selection can't drift.
+    def top_findings(findings, limit: 3)
+      ranked = findings.sort_by { |f| [-f[:majors_behind], f[:dependency].to_s] }
+      { shown: ranked.first(limit), total: findings.length }
+    end
+
+    private
+
+    # Split one OR-branch into its AND clauses: comma-separated (Ruby/pip) or
+    # space-separated (npm ">=1.2.0 <2.0.0").
+    def clauses_of(branch)
+      branch.split(",").flat_map { |part| part.strip.split(AND_SEPARATOR) }.map(&:strip).reject(&:empty?)
+    end
+
+    # The tightest ceiling major within one AND-branch, or nil when the branch has
+    # no upper bound at all (a lone lower bound = permissive, lifts the OR cap).
+    def branch_ceiling(clauses)
+      clauses.filter_map { |clause| clause_ceiling_major(clause) }.min
+    end
+
+    def all_exact?(clauses)
+      !clauses.empty? && clauses.all? { |clause| clause.match?(EXACT_PIN) || clause.match?(BARE_VERSION) }
+    end
+
+    def clause_ceiling_major(clause)
+      match = clause.match(CLAUSE)
+      return unless match
+
+      operator = match[1]
+      major_of = major(match[2])
+      case operator
+      # `< X.0.0` excludes major X entirely (max usable major is X-1); `< X.Y`
+      # with a non-zero minor still allows major X.
+      when "<" then all_zero_after_major?(match[2]) ? major_of - 1 : major_of
+      when "<=", "~>", "~=", "^", "~", "=", "==", "===", nil then major_of
+      end # `>`/`>=` fall through to nil: a lower bound imposes no ceiling
+    end
+
+    def all_zero_after_major?(version)
+      version.split(".").drop(1).all? { |part| part.to_i.zero? }
+    end
+
+    def major(version)
+      digits = version.to_s[/\d+/]
+      digits&.to_i
+    end
+  end
+end

data/lib/helpers/cvss_helper.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module StillActive
+  # Computes a CVSS score from a vector string, across v2/v3/v4. deps.dev stores only
+  # CVSS 3.x, so a CVSS-4-only advisory (the flagship protobuf case) arrives with no
+  # numeric score; OSV carries the v4 vector, and this turns it into the number the
+  # SARIF security-severity and CycloneDX rating want.
+  #
+  # cvss-suite is an OPTIONAL, undeclared dependency: it over-constrains its own deps
+  # (an exact `bundler` pin, a `bigdecimal ~> 3.1` cap), the poison-pill pattern
+  # still_active itself flags, so hard-requiring it would force that liability on every
+  # user and trip our own audit. CvssHelper soft-requires it; install cvss-suite (or run
+  # the distribution that bundles it) to light it up.
+  #
+  # Returns cvss-suite's `overall_score`: for the base-only vectors OSV publishes that
+  # IS the base score, but a vector carrying threat/environmental metrics would fold
+  # those in -- which is why the severity band floors at the authoritative GHSA label
+  # (VulnerabilityHelper.advisory_severity) and this number never lowers it: the label
+  # drives gating and SARIF level, the number only sharpens display. Fails safe: an
+  # absent gem or an absent/unparseable vector yields nil, never a crash.
+  module CvssHelper
+    extend self
+
+    def score(vector)
+      return unless available?
+      return if vector.nil? || vector.to_s.empty?
+
+      cvss = CvssSuite.new(vector.to_s)
+      cvss.valid? ? cvss.overall_score : nil
+    rescue StandardError => e
+      # We only reach here with cvss-suite loaded (available?), so a raise is the
+      # installed gem failing this call site -- an incompatible version, a renamed
+      # `overall_score` -- not a bad vector, which cvss-suite reports via valid?.
+      # Fail safe to nil (the number is display-only, never gates), but don't
+      # swallow it: an opted-in-but-broken scorer that emitted nothing would read
+      # as "no advisories are scored". Warn once per run (not per advisory),
+      # matching OsvClient.enrich rather than staying silent.
+      warn_scorer_failed(e)
+      nil
+    end
+
+    # Memoized soft-require: true once cvss-suite loads, false when it isn't installed.
+    def available?
+      return @available unless @available.nil?
+
+      @available = begin
+        require "cvss_suite"
+        true
+      rescue LoadError
+        false
+      end
+    end
+
+    private
+
+    def warn_scorer_failed(error)
+      return if @warned
+
+      @warned = true
+      $stderr.puts("warning: cvss-suite scoring failed: #{error.class} (#{error.message}); CVSS numbers unavailable this run, check your cvss-suite version")
+    end
+  end
+end

data/lib/helpers/cyclonedx_helper.rb

@@ -142,15 +142,31 @@ module StillActive
     end
 
     def rating(advisory)
-      score = advisory[:cvss3_score] || advisory[:cvss2_score]
+      # effective_score drops deps.dev's cvss3=0 sentinel; an unscored advisory
+      # gets no numeric rating (honest) rather than a masquerading 0.0. A CVSS-4-only
+      # advisory now carries the OSV-computed v4 score, so it gets a real rating too.
+      score = VulnerabilityHelper.effective_score(advisory)
       return if score.nil?
 
-      method = advisory[:cvss3_score] ? "CVSSv3" : "CVSSv2"
-      rating = { "score" => score, "severity" => VulnerabilityHelper.highest_severity([advisory]) || "unknown", "method" => method }
-      rating["vector"] = advisory[:cvss3_vector] if advisory[:cvss3_vector]
+      rating = { "score" => score, "severity" => VulnerabilityHelper.highest_severity([advisory]) || "unknown", "method" => rating_method(advisory) }
+      vector = advisory[:cvss3_vector] || advisory[:cvss_vector]
+      rating["vector"] = vector if vector
       rating
     end
 
+    # Names the CVSS version behind the score so a v4-derived rating isn't mislabelled
+    # CVSSv2. deps.dev's v3/v2 win; otherwise the OSV-enriched vector's version.
+    def rating_method(advisory)
+      return "CVSSv3" if advisory[:cvss3_score]&.positive?
+      return "CVSSv2" if advisory[:cvss2_score]&.positive?
+
+      case advisory[:cvss_version]
+      when "4.0" then "CVSSv4"
+      when "2.0" then "CVSSv2"
+      else "CVSSv3"
+      end
+    end
+
     def boolean_property(value)
       return if value.nil?
 

data/lib/helpers/diff_markdown_helper.rb

@@ -19,13 +19,14 @@ module StillActive
       unknown: nil,
     }.freeze
 
-    def render(diff)
+    def render(diff, accepted: [])
       sections = [
         "## still_active diff",
         "",
-        summary_line(diff),
+        summary_line(diff, accepted),
         "",
         regressions_section(diff.regressions),
+        accepted_section(accepted),
         added_section(diff.added),
         removed_section(diff.removed),
         bumps_section(diff.bumped),
@@ -38,14 +39,16 @@ module StillActive
 
     private
 
-    def summary_line(diff)
-      [
+    def summary_line(diff, accepted)
+      parts = [
         ["regressions", diff.regressions.size],
         ["added", diff.added.size],
         ["removed", diff.removed.size],
         ["bumped", diff.bumped.size],
         ["signal-changes", diff.signal_changes.size],
-      ].map { |label, n| "#{n} #{label}" }.join(" · ")
+      ]
+      parts << ["accepted", accepted.size] unless accepted.empty?
+      parts.map { |label, n| "#{n} #{label}" }.join(" · ")
     end
 
     def regressions_section(regressions)
@@ -55,6 +58,19 @@ module StillActive
       section("Regressions (CI-failable)", lines)
     end
 
+    # Regressions a committed .still_active.yml knowingly accepts: shown so the
+    # acceptance is visible in the PR comment, but excluded from the CI-failable
+    # count above.
+    def accepted_section(accepted)
+      return "" if accepted.empty?
+
+      lines = accepted.map do |a|
+        reason = a.reason ? " — #{MarkdownEscape.inline(a.reason)}" : ""
+        "- **#{a.regression.kind}** #{MarkdownEscape.code_span(a.regression.gem)}#{reason}"
+      end
+      section("Accepted (suppressed via .still_active.yml)", lines)
+    end
+
     def added_section(added)
       return "" if added.empty?
 

data/lib/helpers/endoflife_helper.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "http_helper"
+
+module StillActive
+  # The ecosystem-neutral support-window builder over an endoflife.date feed.
+  # Given a feed path (`/api/ruby.json`, `/api/python.json`, ...) it returns the
+  # runtime facts a per-package language ceiling is measured against: the oldest
+  # cycle still receiving security releases, the latest stable release, a
+  # grace-window flag, and the normalized cycle list. RubyHelper and PythonHelper
+  # are thin calibration wrappers that only choose the feed path, exactly as
+  # RuntimeCeilingHelper keeps the ceiling math generic and pushes the runtime
+  # specifics to the edges. RubyHelper#ruby_freshness also reuses the cycle-date
+  # parsing here so there is one home for reading this best-effort feed.
+  #
+  # Everything degrades on bad third-party data rather than raising: the window is
+  # fetched once outside the per-package rescue, so an unguarded raise would abort
+  # the whole audit. A single malformed field must cost at most the finding it
+  # feeds, never the whole signal.
+  module EndoflifeHelper
+    extend self
+
+    ENDOFLIFE_URI = URI("https://endoflife.date/")
+
+    # How long a newly-released runtime gets before packages are held accountable
+    # for not yet declaring support for it. Below this, a latest-not-yet ceiling
+    # is about the release calendar, not the package, so the note is suppressed.
+    LATEST_STABLE_GRACE_SECONDS = 90 * 24 * 60 * 60
+
+    # => { oldest_supported:, latest_stable:, latest_stable_fresh:, cycles: } of
+    # Gem::Versions plus normalized EOL cycles, or nil when the feed is
+    # unavailable, empty, or every known cycle is EOL (no supported floor to
+    # compare against). `latest_stable` is nil when the newest cycle's `latest` is
+    # malformed -- see below.
+    def support_window(feed_path:)
+      cycles = fetch_cycles(feed_path)
+      return if cycles.nil? || cycles.empty?
+
+      normalized = cycles.filter_map { |cycle| normalize_cycle(cycle) }
+      supported = normalized.reject { |cycle| cycle[:eol] }
+      return if supported.empty?
+
+      # A malformed/preview `latest` on the newest cycle must not sink the whole
+      # window: latest_stable feeds only the latest-not-yet NOTE, whereas the
+      # EOL-forced CRITICAL depends solely on the cycles' eol flags. Degrade it to
+      # nil (the note is then suppressed) rather than returning nil, which would
+      # silently disable criticals too.
+      latest = cycles.first["latest"]
+      latest_stable = latest && Gem::Version.correct?(latest) ? Gem::Version.new(latest) : nil
+
+      {
+        oldest_supported: supported.map { |cycle| cycle[:version] }.min,
+        latest_stable: latest_stable,
+        latest_stable_fresh: !latest_stable.nil? && latest_stable_fresh?(cycles.first),
+        cycles: normalized,
+      }
+    end
+
+    # A best-effort date parse over this feed's values: nil for a missing OR
+    # malformed date, never a raise. endoflife.date is third-party data; a garbled
+    # date on one cycle must degrade that cycle, not abort the run.
+    def parse_date(date_string)
+      return if date_string.nil?
+
+      Time.parse(date_string)
+    rescue ArgumentError
+      nil
+    end
+
+    def parse_eol(value)
+      case value
+      when String then parse_date(value)
+      end
+    end
+
+    # true / false when the eol date is known, nil when it's absent or malformed
+    # (so callers can decide how to treat "unknown"). Routes through parse_date, so
+    # a garbled eol string degrades to nil rather than raising.
+    def eol_reached?(value)
+      case value
+      when true then true
+      when false then false
+      when String
+        parsed = parse_date(value)
+        parsed.nil? ? nil : parsed <= Time.now
+      end
+    end
+
+    private
+
+    def fetch_cycles(feed_path)
+      HttpHelper.get_json(ENDOFLIFE_URI, feed_path)
+    end
+
+    def normalize_cycle(cycle)
+      version = cycle["cycle"]
+      return unless version && Gem::Version.correct?(version)
+
+      {
+        version: Gem::Version.new(version),
+        eol: eol_reached?(cycle["eol"]) == true,
+        eol_date: parse_eol(cycle["eol"]),
+      }
+    end
+
+    def latest_stable_fresh?(latest_cycle)
+      released = parse_date(latest_cycle["releaseDate"])
+      return false if released.nil?
+
+      (Time.now - released) < LATEST_STABLE_GRACE_SECONDS
+    end
+  end
+end

data/lib/helpers/http_helper.rb

@@ -1,11 +1,26 @@
 # frozen_string_literal: true
 
 require "net/http"
+require "openssl"
 require "json"
 
 module StillActive
   module HttpHelper
-    TRUSTED_HOSTS = ["github.com", "gitlab.com", "codeberg.org", "api.deps.dev", "endoflife.date", "rubygems.pkg.github.com"].freeze
+    TRUSTED_HOSTS = ["github.com", "gitlab.com", "codeberg.org", "api.deps.dev", "api.osv.dev", "endoflife.date", "rubygems.pkg.github.com", "repos.ecosyste.ms", "packages.ecosyste.ms", "pypi.org"].freeze
+    # Transport-level failures ("host unreachable / connection broke", not an HTTP
+    # error status). Every network entry point degrades to a safe empty result on
+    # these rather than letting one escape and vanish a gem from the audit.
+    # SystemCallError is the superclass of the whole Errno::* family (EHOSTUNREACH,
+    # ENETUNREACH, ETIMEDOUT, EPIPE, ECONNREFUSED, ECONNRESET, ...), so we don't
+    # have to enumerate each one and miss the next.
+    TRANSPORT_ERRORS = [
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      SocketError,
+      SystemCallError,
+      OpenSSL::SSL::SSLError,
+      EOFError,
+    ].freeze
     MAX_REDIRECTS = 3
     # Ceiling on a single response body. These are metadata endpoints (version
     # lists, scorecards, advisories); legitimate responses are well under this.
@@ -94,7 +109,7 @@ module StillActive
 
       $stderr.puts("warning: #{uri.host}#{uri.path} too many redirects")
       nil
-    rescue Net::OpenTimeout, Net::ReadTimeout, SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+    rescue *TRANSPORT_ERRORS => e
       $stderr.puts("warning: #{uri.host}#{uri.path} failed: #{e.class} (#{e.message})")
       nil
     rescue JSON::ParserError => e

data/lib/helpers/markdown_helper.rb

@@ -3,6 +3,7 @@
 require_relative "markdown_escape"
 require_relative "vulnerability_helper"
 require_relative "activity_helper"
+require_relative "constraint_helper"
 
 module StillActive
   module MarkdownHelper
@@ -112,8 +113,123 @@ module StillActive
       lines.join("\n")
     end
 
+    # A dormant dep that caps your tree below its latest major (the poison-pill
+    # signal). Consistent with the other finding sections: worst caps + total, the
+    # direct parent named for a transitive pill. The full cap list is in the JSON.
+    def poison_section(result)
+      # Require constraints present, not just the poison flag, so an unexpected
+      # empty set can't emit a dangling "- `gem` caps" bullet (symmetric with the
+      # terminal's poison_line guard).
+      flagged = result.select { |_name, data| data[:poison] && !Array(data[:constraints]).empty? }
+      return "" if flagged.empty?
+
+      lines = ["", "**Poison-pill findings** (dormant deps capping your tree below its latest major):"]
+      # Worst-first so the act-now findings lead, then by magnitude for a stable,
+      # triage-friendly order.
+      ranked = flagged.sort_by do |name, data|
+        [
+          poison_rank(data), # below-the-fix leads, then security-relevant, then the rest
+          -ConstraintHelper::SEVERITY.index(data[:poison_severity] || :note),
+          -Array(data[:constraints]).map { |c| c[:majors_behind].to_i }.max,
+          name.to_s,
+        ]
+      end
+      ranked.each do |name, data|
+        lines << "- **#{data[:poison_severity] || :note}** #{poison_gem_ref(name, data)} caps #{poison_caps(data[:constraints])}#{poison_security_marker(data)}"
+      end
+      lines.join("\n")
+    end
+
+    # Ranks poison findings for the report: a cap that holds you BELOW THE FIX first
+    # (unpatchable without replacing the capper), then a merely security-relevant cap
+    # (vulnerable but patchable in place), then everything else.
+    def poison_rank(data)
+      return 0 if data[:poison_below_fix]
+      return 1 if data[:poison_security_relevant]
+
+      2
+    end
+
+    # A prominent marker naming the known-vulnerable dependency a security-relevant
+    # cap pins you to. Leads with the stronger BELOW-THE-FIX claim (the CVE and its
+    # nearest fix, a version the cap forbids) when it applies, else the weaker
+    # "vulnerable but patchable" form.
+    def poison_security_marker(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
+
+    # The language-runtime ceiling: a resolved version whose declared runtime
+    # constraint (Ruby `ruby_version`, Python `requires_python`) caps the runtime
+    # onto an EOL release (critical) or below the latest stable (note). Ranked
+    # worst-first with a tier label, mirroring the poison section.
+    def language_ceiling_section(result)
+      flagged = result.select { |_name, data| data[:language_ceiling] }
+      return "" if flagged.empty?
+
+      lines = ["", "**Runtime ceiling findings** (a resolved version capping the language runtime it can run on):"]
+      ranked = flagged.sort_by { |name, data| [-ConstraintHelper::SEVERITY.index(data[:language_ceiling][:severity] || :note), name.to_s] }
+      ranked.each do |name, data|
+        ceiling = data[:language_ceiling]
+        lines << "- **#{ceiling[:severity] || :note}** #{MarkdownEscape.code_span(name)} #{language_ceiling_receipt(ceiling, data)}"
+      end
+      lines.join("\n")
+    end
+
     private
 
+    def language_ceiling_receipt(ceiling, data)
+      runtime = ceiling[:runtime]
+      req = MarkdownEscape.code_span(ceiling[:requirement])
+      base =
+        if ceiling[:eol_forced]
+          eol = ceiling[:ceiling_eol_date]
+          eol_part = eol ? " (EOL #{eol.strftime("%Y-%m-%d")})" : ""
+          "requires #{runtime} #{req}, stranding you on end-of-life #{runtime} #{ceiling[:ceiling_version]}#{eol_part}"
+        else
+          "requires #{runtime} #{req}, no #{runtime} #{ceiling[:latest_stable]} support yet"
+        end
+      fix = ceiling[:fixed_by_upgrade] && data[:latest_version] ? "; upgrade to #{data[:latest_version]} to lift it" : ""
+      "#{base}#{fix}"
+    end
+
+    def poison_gem_ref(name, data)
+      ref = MarkdownEscape.code_span(name)
+      path = data[:dependency_path]
+      # Transitive pill: name the direct parent the user can actually act on (#60).
+      return ref unless data[:direct] == false && Array(path).length >= 2
+
+      "#{ref} via #{MarkdownEscape.code_span(path.first)}"
+    end
+
+    # The worst 3 caps; the first carries the full receipt (requirement + latest
+    # major), the rest just the gap, and "— N total" when there are more.
+    def poison_caps(constraints)
+      top = ConstraintHelper.top_findings(Array(constraints), limit: 3)
+      parts = top[:shown].each_with_index.map do |finding, i|
+        dep = MarkdownEscape.code_span(finding[:dependency])
+        req = MarkdownEscape.code_span(finding[:requirement])
+        behind = finding[:majors_behind]
+        i.zero? ? "#{dep} #{req} (#{behind} major#{"s" unless behind == 1} behind, latest #{poison_major(finding[:dep_latest])})" : "#{dep} #{req} (#{behind})"
+      end
+      joined = parts.join(", ")
+      top[:total] > 1 ? "#{joined} — #{top[:total]} total" : joined
+    end
+
+    # "8.0.1" -> "8.x": the cap is a major-level gap.
+    def poison_major(version)
+      major = version.to_s[/\d+/]
+      major ? "#{major}.x" : version
+    end
+
     def transitive_flagged?(data)
       [:archived, :critical].include?(ActivityHelper.activity_level(data)) || data[:vulnerability_count].to_i.positive?
     end
@@ -161,7 +277,8 @@ module StillActive
       severity = VulnerabilityHelper.highest_severity(vulnerabilities)
       ids = vulnerabilities.flat_map { |v| [v[:id], *v[:aliases]] }.compact.uniq.first(3)
 
-      parts = [severity ? "#{count} (#{severity})" : count.to_s]
+      notes = [severity, ("no fix" if VulnerabilityHelper.no_fix_available?(vulnerabilities))].compact
+      parts = [notes.empty? ? count.to_s : "#{count} (#{notes.join(", ")})"]
       parts << MarkdownEscape.cell(ids.join(", ")) unless ids.empty?
       parts.join(" ")
     end