still_active 2.0.0 → 3.0.0.rc1

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

data/lib/helpers/pep440_helper.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module StillActive
+  # Translates a PEP 440 `requires_python` specifier into a RubyGems requirement
+  # STRING, so the generic RuntimeCeilingHelper can reason about a Python runtime
+  # ceiling with no core change -- the same way Ruby's `ruby_version` already
+  # feeds it. PEP 440 and RubyGems disagree on two operators that matter here:
+  #
+  #   - `~=` (compatible release) is a syntax error to Gem::Requirement, so a
+  #     naive parse raises and the ceiling is silently missed. It maps cleanly to
+  #     RubyGems `~>` for the major.minor.patch shapes `requires_python` uses.
+  #   - `== X.*` / `== X.Y.*` prefix wildcards are likewise unparseable and map to
+  #     a pessimistic `~>` over the prefix.
+  #
+  # `!=` exclusions are dropped: a hole-punch can never create an upper bound, so
+  # it cannot be a runtime ceiling, and dropping it can only ADMIT more runtimes
+  # (fewer findings) -- conservative, never a false ceiling. Anything that still
+  # won't parse degrades to a dropped clause (or nil overall), never a raise: this
+  # feeds the core audit and must fail safe, matching RuntimeCeilingHelper's
+  # best-effort contract.
+  module Pep440Helper
+    extend self
+
+    # Match ConstraintHelper / RuntimeCeilingHelper: bound pathological registry
+    # input before it reaches Gem::Requirement's own regex.
+    MAX_SPECIFIER_LENGTH = 256
+
+    # Operator, then the version as a run of non-space chars. `\s*(\S+)` (not
+    # `\s*(.+)`) keeps the two groups over disjoint character classes so there's no
+    # polynomial backtracking on pathological input like "<" + many spaces (a PEP
+    # 440 version never contains internal spaces, so this loses nothing).
+    CLAUSE_PATTERN = /\A(===|==|~=|!=|<=|>=|<|>)\s*(\S+)\z/
+
+    # => a comma-joined RubyGems requirement string, or nil when nothing usable
+    # survives translation. The caller feeds the string to RuntimeCeilingHelper,
+    # which splits and splats it exactly like a `ruby_version` string.
+    def to_gem_requirement_string(specifier)
+      spec = specifier.to_s
+      return if spec.strip.empty? || spec.length > MAX_SPECIFIER_LENGTH
+
+      clauses = spec.split(",").filter_map { |clause| translate_clause(clause.strip) }
+      return if clauses.empty?
+
+      clauses.join(", ")
+    end
+
+    private
+
+    def translate_clause(clause)
+      match = CLAUSE_PATTERN.match(clause)
+      return if match.nil?
+
+      operator = match[1]
+      version = match[2].strip
+
+      case operator
+      when "!=" then nil # hole-punch: never an upper bound, drop it
+      when "~=" then compatible_release(version)
+      when "==", "===" then equality(version)
+      else comparison(operator, version)
+      end
+    end
+
+    # `~= X.Y[.Z]` is `>= X.Y[.Z], == X.Y.*` which is exactly RubyGems `~> X.Y[.Z]`.
+    def compatible_release(version)
+      return unless parseable?(version)
+
+      "~> #{version}"
+    end
+
+    def equality(version)
+      if version.end_with?(".*")
+        prefix_match(version.delete_suffix(".*"))
+      elsif parseable?(version)
+        "= #{version}"
+      end
+    end
+
+    # `== P.*` matches every release whose version starts with prefix P, i.e.
+    # `>= P, < P-with-last-segment-incremented`. RubyGems spells that as `~> P.0`
+    # (append one segment so the pessimistic bump lands on P's last segment):
+    #   ==3.*   -> ~> 3.0   (>=3, <4)
+    #   ==3.7.* -> ~> 3.7.0 (>=3.7, <3.8)
+    def prefix_match(prefix)
+      return unless parseable?(prefix)
+
+      "~> #{prefix}.0"
+    end
+
+    def comparison(operator, version)
+      return unless parseable?(version)
+
+      "#{operator} #{version}"
+    end
+
+    def parseable?(version)
+      Gem::Version.correct?(version)
+    end
+  end
+end

data/lib/helpers/python_helper.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "endoflife_helper"
+
+module StillActive
+  # Python's calibration for the language-runtime ceiling: the thin sibling of
+  # RubyHelper.supported_ruby_range. Python declares its runtime constraint as a
+  # PEP 440 `requires_python` specifier (translate with Pep440Helper before
+  # handing it to RuntimeCeilingHelper), and its release calendar lives in the
+  # same endoflife.date feed. Everything ecosystem-neutral is in EndoflifeHelper;
+  # Python only chooses the feed path.
+  module PythonHelper
+    extend self
+
+    def supported_python_range
+      EndoflifeHelper.support_window(feed_path: "/api/python.json")
+    end
+  end
+end

data/lib/helpers/ruby_advisory_db.rb

@@ -13,6 +13,9 @@ module StillActive
     extend self
 
     STALE_AFTER_SECONDS = 30 * 24 * 60 * 60 # 30 days
+    # Requirement operators whose safe versions are OLDER than the flaw, i.e. not a
+    # forward fix a consumer can upgrade to. Anything else ("> X" etc.) is.
+    OLDER_THAN_FLAW_OPERATORS = ["<", "<="].freeze
 
     # bundler-audit's Database#check_gem expects an object responding to
     # #name and #version (a Gem::Version).
@@ -66,12 +69,32 @@ module StillActive
         cvss3_score: details[:cvss_v3],
         cvss3_vector: nil,
         cvss2_score: details[:cvss_v2],
+        # No safe version a consumer can upgrade TO: the correlation bundler-audit
+        # + `bundle outdated` can't produce alone. A factual read of the DB.
+        no_fix_available: no_forward_fix?(advisory),
         source: "ruby-advisory-db",
       }
     end
 
     private
 
+    # True when the advisory records no version the consumer can move forward to.
+    # Mirrors bundler-audit's own `!patched? && !unaffected?` rather than only the
+    # patched half: a clean release shipped AFTER a backdoored/yanked version is
+    # recorded in unaffected_versions as a "> X" range, not in patched_versions
+    # (the CVE-2019-15224 bootstrap-sass pattern). Be conservative -- only a purely
+    # older-than-the-flaw safe range ("< X") counts as no-forward-fix -- so we never
+    # claim "no fix" while a later safe release exists.
+    def no_forward_fix?(advisory)
+      return false unless advisory.patched_versions.empty?
+
+      advisory.unaffected_versions.all? { |requirement| older_than_flaw_only?(requirement) }
+    end
+
+    def older_than_flaw_only?(requirement)
+      requirement.requirements.all? { |operator, _| OLDER_THAN_FLAW_OPERATORS.include?(operator) }
+    end
+
     # nil for versions Gem::Version can't parse (e.g. a git sha); such a "version"
     # has nothing to match in the advisory DB, so the caller returns [].
     def parse_version(version)

data/lib/helpers/ruby_helper.rb

@@ -2,6 +2,7 @@
 
 require "time"
 require_relative "bundler_helper"
+require_relative "endoflife_helper"
 require_relative "http_helper"
 require_relative "libyear_helper"
 
@@ -24,15 +25,15 @@ module StillActive
       return if latest_cycle.nil?
 
       latest_version = latest_cycle["latest"]
-      latest_release_date = parse_date(latest_cycle["releaseDate"])
-      current_release_date = parse_date(current_cycle&.dig("releaseDate"))
+      latest_release_date = EndoflifeHelper.parse_date(latest_cycle["releaseDate"])
+      current_release_date = EndoflifeHelper.parse_date(current_cycle&.dig("releaseDate"))
       eol_value = current_cycle&.dig("eol")
 
       {
         version: current,
         release_date: current_release_date,
-        eol_date: parse_eol(eol_value),
-        eol: eol_reached?(eol_value),
+        eol_date: EndoflifeHelper.parse_eol(eol_value),
+        eol: EndoflifeHelper.eol_reached?(eol_value),
         latest_version: latest_version,
         latest_release_date: latest_release_date,
         libyear: LibyearHelper.gem_libyear(
@@ -42,6 +43,14 @@ module StillActive
       }
     end
 
+    # The runtime facts a per-gem language ceiling is measured against, sourced
+    # from the shared endoflife.date support-window builder. Ruby only picks the
+    # feed; the ecosystem-neutral logic (support floor, latest stable, grace
+    # window, cycle normalization) lives in EndoflifeHelper.
+    def supported_ruby_range
+      EndoflifeHelper.support_window(feed_path: "/api/ruby.json")
+    end
+
     private
 
     def current_ruby_version
@@ -68,25 +77,5 @@ module StillActive
       major_minor = version.split(".")[0..1].join(".")
       cycles.find { |c| c["cycle"] == major_minor }
     end
-
-    def parse_date(date_string)
-      return if date_string.nil?
-
-      Time.parse(date_string)
-    end
-
-    def parse_eol(value)
-      case value
-      when String then parse_date(value)
-      end
-    end
-
-    def eol_reached?(value)
-      case value
-      when true then true
-      when false then false
-      when String then Time.parse(value) <= Time.now
-      end
-    end
   end
 end

data/lib/helpers/runtime_ceiling_helper.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "constraint_helper"
+
+module StillActive
+  # The language-runtime sibling of the poison-pill signal, kept deliberately
+  # generic: it reads a constraint a package declares on its RUNTIME (the version
+  # range it can run on) and, given that runtime's support window, answers how much
+  # the constraint holds you back. Ruby (`ruby_version`) is the first consumer, but
+  # nothing here is Ruby-specific: the same core serves any runtime with an
+  # end-of-life calendar (Python's `requires_python`, etc.). The runtime-specific
+  # parts -- where the constraint string comes from, and how the support window is
+  # built -- live in the calibration layer (RubyHelper.supported_ruby_range) and
+  # the workflow boundary, exactly as poison keeps ConstraintHelper generic and
+  # pushes ecosystem resolution to the lens.
+  #
+  # Two tiers, mirroring the severity model:
+  #   - EOL-forced (critical): the constraint admits no still-supported runtime,
+  #     stranding you on an end-of-life release with no security patches. A genuine
+  #     upgrade blocker (e.g. a gem's `ruby_version < 3.2` caps at the EOL Ruby 3.1).
+  #   - latest-not-yet (note): runs on a supported runtime but caps below the latest
+  #     stable. An FYI ceiling to plan around, or a place to contribute support for
+  #     the newest release before you invest.
+  #
+  # A bare floor (`>= 3.1`) or a requires-newer constraint (`>= 4.1`, `~> 5.0`) is
+  # NOT a ceiling: it raises the minimum, it doesn't cap you onto a dead release.
+  # The distinction is drawn against the live EOL cycles, not the operator alone.
+  module RuntimeCeilingHelper
+    extend self
+
+    # Gem::Requirement caps input via a regex; a registry-derived string could be
+    # pathological. Bound it up front like ConstraintHelper does.
+    MAX_REQUIREMENT_LENGTH = 256
+
+    # => { requirement:, eol_forced:, severity:, ... } or nil when there's no
+    # ceiling. `support_window` is a { oldest_supported:, latest_stable:, cycles: }
+    # hash of Gem::Versions plus normalized EOL cycles (see supported_ruby_range).
+    def analyze(requirement:, support_window:)
+      return if support_window.nil?
+
+      req = safe_requirement(requirement)
+      return if req.nil? || !capping?(req)
+
+      supported_allowed = support_window[:cycles].reject { |c| c[:eol] }.select { |c| req.satisfied_by?(c[:version]) }
+
+      if supported_allowed.empty?
+        eol_forced_finding(req, requirement, support_window)
+      elsif !support_window[:latest_stable].nil? && !req.satisfied_by?(support_window[:latest_stable]) && !support_window[:latest_stable_fresh]
+        # Runs on a supported runtime but not the latest stable. Suppressed while
+        # the latest stable is still within its grace window (see supported_ruby_
+        # range): right after a runtime ships, "doesn't support it yet" indicts the
+        # release calendar, not the gem. After the window it is a real note.
+        latest_not_yet_finding(requirement, support_window)
+      end
+    end
+
+    private
+
+    # A ceiling exists only if the constraint has an upper bound. A pure lower
+    # bound (`>`, `>=`) can never strand you on an old release, so skip it before
+    # any cycle math (this is also what keeps `>= 4.1` requires-newer out). Exact
+    # pins (`=`) are excluded deliberately: pinning a runtime to an exact patch is
+    # pathological (unheard of in practice) and can't be matched against the
+    # major.minor EOL cycles anyway, so we don't fabricate support for it.
+    CAPPING_OPERATORS = ["<", "<=", "~>"].freeze
+
+    def capping?(req)
+      req.requirements.any? { |operator, _version| CAPPING_OPERATORS.include?(operator) }
+    end
+
+    def eol_forced_finding(req, requirement, support_window)
+      # No supported release is admitted. Only a genuine cap (admits some EOL
+      # release) is EOL-forced; a requires-newer floor admits nothing at or below
+      # the oldest supported and is not our concern.
+      allowed_eol = support_window[:cycles].select { |c| c[:eol] && req.satisfied_by?(c[:version]) }
+      return if allowed_eol.empty?
+
+      ceiling = allowed_eol.max_by { |c| c[:version] }
+      finding = {
+        requirement: requirement,
+        eol_forced: true,
+        ceiling_version: ceiling[:version].to_s,
+        ceiling_eol_date: ceiling[:eol_date],
+        oldest_supported: support_window[:oldest_supported].to_s,
+        latest_stable: support_window[:latest_stable].to_s,
+      }
+      finding.merge(severity: ConstraintHelper.constraint_severity(finding))
+    end
+
+    def latest_not_yet_finding(requirement, support_window)
+      finding = {
+        requirement: requirement,
+        eol_forced: false,
+        oldest_supported: support_window[:oldest_supported].to_s,
+        latest_stable: support_window[:latest_stable].to_s,
+      }
+      finding.merge(severity: ConstraintHelper.constraint_severity(finding))
+    end
+
+    # Registries render a floor+ceiling requirement as a single comma-joined string
+    # (e.g. ">= 2.5, < 3.2" -- common for `ruby_version`/`required_ruby_version`).
+    # Gem::Requirement.new can't parse that one-string form (it raises), so split
+    # into clauses and splat, preserving BOTH bounds. Reading only the string as-is
+    # would drop the `< 3.2` ceiling and silently miss the very case this exists to
+    # catch. Best-effort: a genuinely malformed clause degrades to nil (no finding),
+    # never a raised exception that could break the core audit.
+    def safe_requirement(requirement)
+      return if requirement.nil? || requirement.to_s.length > MAX_REQUIREMENT_LENGTH
+
+      clauses = requirement.to_s.split(",").map(&:strip).reject(&:empty?)
+      return if clauses.empty?
+
+      Gem::Requirement.new(*clauses)
+    rescue ArgumentError
+      # Covers Gem::Requirement::BadRequirementError (a subclass) plus any other
+      # malformed-input ArgumentError, so a pathological registry string degrades
+      # to "no ceiling" and never breaks the core audit.
+      nil
+    end
+  end
+end