still_active 1.6.0 → 3.0.0.rc1

data/lib/helpers/http_helper.rb

@@ -1,12 +1,34 @@
 # frozen_string_literal: true
 
 require "net/http"
+require "openssl"
 require "json"
 
 module StillActive
   module HttpHelper
-    TRUSTED_HOSTS = ["github.com", "gitlab.com", "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.
+    # A source URL is lockfile-derived and a `*.jfrog.io` host is attacker-
+    # registerable, so without a cap a hostile or broken source could stream a
+    # multi-GB body and OOM the process. 16 MiB leaves generous headroom for a
+    # gem with thousands of versions while bounding worst-case memory.
+    MAX_BODY_BYTES = 16 * 1024 * 1024
 
     extend self
 
@@ -15,45 +37,125 @@ module StillActive
       uri.path = path
       uri.query = URI.encode_www_form(params) unless params.empty?
 
+      request_json(uri, headers) { |target| Net::HTTP::Get.new(target) }
+    end
+
+    def post_json(base_uri, path, body:, headers: {})
+      uri = base_uri.dup
+      uri.path = path
+
+      request_json(uri, headers) do |target|
+        request = Net::HTTP::Post.new(target)
+        request.body = body
+        request
+      end
+    end
+
+    private
+
+    # Two URIs share an origin when scheme, host, and port all match. URI fills
+    # in the default port (443 for https), so the bare and explicit forms of the
+    # same origin compare equal.
+    def same_origin?(a, b)
+      a.scheme == b.scheme && a.host == b.host && a.port == b.port
+    end
+
+    # Runs the request, following up to MAX_REDIRECTS trusted-host redirects,
+    # and returns the parsed JSON (or nil). The block is yielded each URI and
+    # returns the request object, so GET and POST share the redirect/auth/cap
+    # logic.
+    def request_json(uri, headers)
       MAX_REDIRECTS.times do
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = true
         http.open_timeout = 10
         http.read_timeout = 10
 
-        request = Net::HTTP::Get.new(uri)
+        request = yield(uri)
         headers.each { |key, value| request[key] = value }
 
-        response = http.request(request)
+        outcome, payload = perform(http, request, uri)
+        case outcome
+        when :done
+          return payload
+        when :stop
+          return
+        when :redirect
+          location = payload["Location"]
+          if location.nil? || location.empty?
+            $stderr.puts("warning: #{uri.host}#{uri.path} returned HTTP #{payload.code} with no Location header")
+            return
+          end
 
-        if response.is_a?(Net::HTTPRedirection)
-          redirect_uri = uri + response["Location"]
+          redirect_uri = uri + location
           unless TRUSTED_HOSTS.include?(redirect_uri.host)
             $stderr.puts("warning: #{uri.host}#{uri.path} redirected to untrusted host #{redirect_uri.host}, skipping")
             return
           end
+          # We dial every request over TLS (use_ssl = true). A redirect that
+          # downgrades to http is either a misconfiguration or a downgrade
+          # attempt; refuse it rather than silently dialing http-over-TLS.
+          unless redirect_uri.scheme == "https"
+            $stderr.puts("warning: #{uri.host}#{uri.path} redirected to non-https #{redirect_uri.scheme} target, skipping")
+            return
+          end
           $stderr.puts("warning: #{uri.host}#{uri.path} redirected to #{redirect_uri.host}#{redirect_uri.path} (stale metadata?)")
-          headers = {} if redirect_uri.host != uri.host
+          # Auth is scoped to an origin (scheme + host + port), not just a host:
+          # a different port is a different service and must not inherit the token.
+          headers = {} unless same_origin?(uri, redirect_uri)
           uri = redirect_uri
-          next
-        end
-
-        unless response.is_a?(Net::HTTPSuccess)
-          $stderr.puts("warning: #{uri.host}#{uri.path} returned HTTP #{response.code}") unless response.is_a?(Net::HTTPNotFound)
-          return
         end
-
-        return JSON.parse(response.body)
       end
 
       $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
       $stderr.puts("warning: #{uri.host}#{uri.path} returned invalid JSON: #{e.message}")
       nil
+    rescue URI::InvalidURIError => e
+      $stderr.puts("warning: #{uri.host}#{uri.path} returned an invalid redirect Location: #{e.message}")
+      nil
+    end
+
+    # Issues the request in streaming form so the body is read against a size
+    # cap rather than buffered whole. Returns one of:
+    #   [:redirect, response]  a 3xx, for the caller to follow
+    #   [:stop, nil]           non-success (warns unless 404), or body over cap
+    #   [:done, parsed]        a 2xx with parsed JSON
+    # Redirect and non-success bodies are never read: returning from the block
+    # unwinds through Net::HTTP, which closes the connection without draining
+    # the body, so a huge error/redirect body can't OOM us either.
+    def perform(http, request, uri)
+      http.request(request) do |response|
+        return [:redirect, response] if response.is_a?(Net::HTTPRedirection)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          $stderr.puts("warning: #{uri.host}#{uri.path} returned HTTP #{response.code}") unless response.is_a?(Net::HTTPNotFound)
+          return [:stop, nil]
+        end
+
+        body = read_capped_body(response, uri)
+        return [:stop, nil] if body.nil?
+
+        return [:done, JSON.parse(body)]
+      end
+    end
+
+    # Reads the body in chunks, abandoning the read (returns nil) as soon as it
+    # exceeds MAX_BODY_BYTES so an oversized body is never fully materialized.
+    def read_capped_body(response, uri)
+      body = +""
+      response.read_body do |chunk|
+        body << chunk
+        if body.bytesize > MAX_BODY_BYTES
+          $stderr.puts("warning: #{uri.host}#{uri.path} response exceeded #{MAX_BODY_BYTES} bytes, skipping")
+          return nil
+        end
+      end
+      body
     end
   end
 end

data/lib/helpers/lockfile_dependency_parser.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module StillActive
+  # Side-effect-free Gemfile.lock parser: extracts each top-level dependency's
+  # name, version, and source (type + URI) straight from the lockfile text.
+  #
+  # We deliberately do NOT load the Gemfile (evaluating it is arbitrary code
+  # execution when the audited project is untrusted, e.g. CI on a pull request)
+  # and do NOT use Bundler::LockfileParser. The latter is not side-effect-free:
+  # a `PLUGIN SOURCE` block runs `Bundler::Plugin.from_lock` at parse time,
+  # which resolves against the on-disk plugin registry and can raise or activate
+  # an installed plugin. (Bundler's own `@gemfile_parse` guard that neutralizes
+  # this is set only inside `Bundler::Plugin.gemfile_install`, never for a
+  # standalone parse.) This mirrors what OSV-Scanner and Trivy do for the same
+  # threat model, and what `LockfileIndexer` already does here. Refs #37.
+  module LockfileDependencyParser
+    extend self
+
+    # `dependencies` holds the names listed under this spec in the lockfile (its
+    # resolved runtime deps). For a local path gem (a gemspec project or engine)
+    # these are the gems it ships, which Bundler does not surface in the
+    # DEPENDENCIES section, so they are what #41 needs to reach.
+    Spec = Struct.new(:name, :version, :source_type, :source_uri, :dependencies, keyword_init: true)
+
+    # Lockfile source blocks and the source_type each maps to. PLUGIN SOURCE is
+    # recognized as a block (so its lines are consumed as inert data, not
+    # mis-read as specs) but yields no auditable gems.
+    SOURCE_TYPES = { "GEM" => :rubygems, "GIT" => :git, "PATH" => :path }.freeze
+    PLUGIN_SOURCE = "PLUGIN SOURCE"
+
+    # A section header sits at column 0; Bundler emits them in SCREAMING form.
+    SECTION_HEADER = /\A[A-Z]/
+    # A top-level spec is indented exactly 4 spaces: `    name (1.2.3)` or, for a
+    # platform gem, `    name (1.2.3-x86_64-linux)`. Nested deps (6 spaces) and
+    # the `specs:`/`remote:` option lines (2 spaces) do not match. We do NOT
+    # anchor the end of the line: Bundler's grammar allows an optional trailing
+    # checksum on a spec line, and an audit tool must never silently drop a gem
+    # because of unexpected trailing content (that would be a false-negative
+    # evasion on a hand-crafted lockfile).
+    SPEC_LINE = /\A {4}(\S+) \(([^-)]+)(?:-[^)]*)?\)/
+    REMOTE_LINE = /\A {2}remote: (.+)\z/
+    # A spec's nested runtime dep is indented exactly 6 spaces: `      name` or
+    # `      name (~> 1.0)`.
+    NESTED_DEP_LINE = /\A {6}([^\s(!]+)/
+    # A DEPENDENCIES entry is indented 2 spaces: `  name`, `  name (~> 1.0)`, or
+    # `  name!` (the `!` marks a pinned git/path source).
+    DEPENDENCY_LINE = /\A {2}([^\s(!]+)/
+
+    # Parses lockfile text into { specs:, direct:, plugin_source? }.
+    # `specs` is every locked top-level spec (a Spec per gem); `direct` is the
+    # names from the DEPENDENCIES section; `plugin_source?` flags that a
+    # PLUGIN SOURCE block was present (and skipped).
+    def parse(content)
+      # A hand-edited or re-encoded lockfile can carry a leading UTF-8 BOM.
+      # Section headers anchor at column 0 (\A), so a BOM glued to "GEM" would
+      # drop the entire first block: a silent false-negative, the exact evasion
+      # this parser is written to avoid.
+      content = content.delete_prefix("")
+      specs = []
+      direct = []
+      section = nil
+      source_type = nil
+      remote = nil
+      current_spec = nil
+      plugin_source = false
+
+      content.each_line do |raw|
+        line = raw.chomp
+
+        if line.match?(SECTION_HEADER)
+          section = line
+          source_type = SOURCE_TYPES[line]
+          remote = nil
+          current_spec = nil
+          plugin_source ||= (line == PLUGIN_SOURCE)
+          next
+        end
+
+        case section
+        when "GEM", "GIT", "PATH"
+          if (m = REMOTE_LINE.match(line))
+            remote ||= m[1] # first remote wins, matching Bundler's remotes.first
+          elsif (m = SPEC_LINE.match(line))
+            current_spec = Spec.new(name: m[1], version: m[2], source_type: source_type, source_uri: remote, dependencies: [])
+            specs << current_spec
+          elsif current_spec && (m = NESTED_DEP_LINE.match(line))
+            current_spec.dependencies << m[1]
+          end
+        when "DEPENDENCIES"
+          if (m = DEPENDENCY_LINE.match(line))
+            direct << m[1]
+          end
+        end
+      end
+
+      { specs: specs, direct: direct, plugin_source?: plugin_source }
+    end
+  end
+end

data/lib/helpers/lockfile_indexer.rb

@@ -24,6 +24,9 @@ module StillActive
     # top-level entry wins. Lines outside GEM/GIT/PATH/PLUGIN SOURCE blocks
     # are ignored.
     def gem_line_index(content)
+      # Strip a leading UTF-8 BOM so a "GEM" first line still matches the
+      # column-0 block header; otherwise every gem falls back to line 1.
+      content = content.delete_prefix("")
       index = {}
       in_block = false
       content.each_line.with_index(1) do |line, lineno|

data/lib/helpers/markdown_escape.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module StillActive
+  # Escaping for untrusted metadata (gem names, licences, versions, repo URLs,
+  # advisory ids) rendered into GitHub-Flavored Markdown. These values come
+  # from registry/repo metadata, a Gemfile/lockfile, a --baseline file, or
+  # --gems input, so they can contain markdown-structural characters. Centralised
+  # so the table renderer (MarkdownHelper) and the diff renderer
+  # (DiffMarkdownHelper) can't drift apart on what's safe.
+  module MarkdownEscape
+    extend self
+
+    # Table cell: a literal "|" or newline would forge columns or break the row.
+    # Backslash is escaped first so it can't escape a following delimiter.
+    def cell(text)
+      return text if text.nil?
+
+      text.to_s.gsub(/[\\|\r\n]/, "\\" => "\\\\", "|" => "\\|", "\r" => " ", "\n" => " ")
+    end
+
+    # Link text additionally must not contain "[" or "]", which could forge or
+    # truncate the link.
+    def link_text(text)
+      return text if text.nil?
+
+      cell(text).gsub(/[\[\]]/, "[" => "\\[", "]" => "\\]")
+    end
+
+    # Link destination: percent-encode the characters that would break out of a
+    # "(...)" destination or the table row. Lossless for legitimate http(s) URLs.
+    def url(value)
+      return value if value.nil?
+
+      value.to_s.gsub(/[|() \t\r\n]/, "|" => "%7C", "(" => "%28", ")" => "%29", " " => "%20", "\t" => "%09", "\r" => "%0D", "\n" => "%0A")
+    end
+
+    # Inline (non-table) free text in a bullet list: neutralise newlines (which
+    # would break the list) and brackets/backslash (which could forge a link).
+    def inline(text)
+      return text if text.nil?
+
+      text.to_s.gsub(/[\\\[\]\r\n]/, "\\" => "\\\\", "[" => "\\[", "]" => "\\]", "\r" => " ", "\n" => " ")
+    end
+
+    # Wrap arbitrary text in an inline code span safely. A backtick in the text
+    # would otherwise close the span early, so use a backtick fence longer than
+    # the longest run in the content (and pad when it starts/ends with one), per
+    # the GFM code-span rules. Newlines collapse to spaces.
+    def code_span(text)
+      content = text.to_s.tr("\r\n", "  ")
+      return "`#{content}`" unless content.include?("`")
+
+      fence = "`" * (content.scan(/`+/).map(&:length).max + 1)
+      pad = content.start_with?("`") || content.end_with?("`") ? " " : ""
+      "#{fence}#{pad}#{content}#{pad}#{fence}"
+    end
+  end
+end

data/lib/helpers/markdown_helper.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "markdown_escape"
 require_relative "vulnerability_helper"
+require_relative "activity_helper"
+require_relative "constraint_helper"
 
 module StillActive
   module MarkdownHelper
@@ -91,12 +94,146 @@ module StillActive
       return "" if flagged.empty?
 
       lines = ["", "**Alternatives** (Ruby Toolbox leads, verify fit):"]
-      flagged.each { |name, data| lines << "- `#{name}`: #{data[:alternatives].join(", ")}" }
+      flagged.each { |name, data| lines << "- #{MarkdownEscape.code_span(name)}: #{MarkdownEscape.inline(data[:alternatives].join(", "))}" }
+      lines.join("\n")
+    end
+
+    # Flagged transitive gems can't be swapped directly; name the direct
+    # dependency that pulls each one in so the finding becomes actionable (#60).
+    def transitive_section(result)
+      flagged = result.select do |_name, data|
+        data[:direct] == false && Array(data[:dependency_path]).length >= 2 && transitive_flagged?(data)
+      end
+      return "" if flagged.empty?
+
+      lines = ["", "**Transitive findings** (pulled in by a direct dependency):"]
+      flagged.each do |name, data|
+        lines << "- #{MarkdownEscape.code_span(name)} via #{MarkdownEscape.code_span(data[:dependency_path].first)}"
+      end
+      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
+
     def version_with_date(text:, url:, date:)
       version_part = markdown_url(text: text, url: url)
       return if version_part.nil?
@@ -128,7 +265,7 @@ module StillActive
     def format_license(license)
       return "-" if license.nil? || license.empty?
 
-      license
+      MarkdownEscape.cell(license)
     end
 
     def format_vulns(data)
@@ -140,15 +277,17 @@ 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]
-      parts << ids.join(", ") unless ids.empty?
+      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
 
     def markdown_url(text:, url:)
-      return text if url.nil?
+      safe_text = MarkdownEscape.link_text(text)
+      return safe_text if url.nil?
 
-      "[#{text}](#{url})"
+      "[#{safe_text}](#{MarkdownEscape.url(url)})"
     end
 
     def year_month(time_object)

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