still_active 1.6.0 → 3.0.0.rc1

data/lib/helpers/catalog_index.rb

@@ -80,7 +80,10 @@ module StillActive
 
     def download
       url = StillActive.config.github_client.archive_link(REPO, format: "tarball", ref: "main")
-      URI.open(url) { |io| io.read(MAX_DOWNLOAD_BYTES) } # rubocop:disable Security/Open
+      # URI(url).open (not URI.open/Kernel#open) so a "|cmd" string can never be
+      # treated as a shell command — the URL is a constant-repo archive link, but
+      # this keeps the open path injection-proof regardless.
+      URI.parse(url).open { |io| io.read(MAX_DOWNLOAD_BYTES) }
     end
 
     def build_siblings(categories)

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

@@ -55,7 +55,7 @@ module StillActive
       component = { "type" => "library", "name" => name }
       component["version"] = version if version
       component["bom-ref"] = bom_ref(name, data)
-      component["purl"] = purl(name, version) if data[:source_type] == :rubygems && version
+      component["purl"] = purl(name, version, data[:source_type]) if version
       component["licenses"] = licenses(data[:license]) if data[:license]
       if data[:repository_url]
         component["externalReferences"] = [{ "type" => "vcs", "url" => data[:repository_url] }]
@@ -67,13 +67,19 @@ module StillActive
 
     def bom_ref(name, data)
       version = data[:version_used]
-      return purl(name, version) if data[:source_type] == :rubygems && version
+      return purl(name, version, data[:source_type]) if version
 
-      "#{data[:source_type]}-source:#{name}@#{version || "unknown"}"
+      "#{data[:source_type]}-source:#{name}@unknown"
     end
 
-    def purl(name, version)
-      "pkg:gem/#{name}@#{version}"
+    # Datadog SCA (and strict CycloneDX consumers) hard-reject a versioned
+    # library component with no purl, so every gem with a version needs one.
+    # A path gem is local and not on rubygems, so it gets pkg:generic to avoid
+    # false-matching a public gem of the same name; git/rubygems-sourced gems
+    # get pkg:gem so a fork still matches the upstream gem's advisories.
+    def purl(name, version, source_type)
+      type = source_type == :path ? "generic" : "gem"
+      "pkg:#{type}/#{name}@#{version}"
     end
 
     # VersionHelper joins multiple SPDX ids with ", " for terminal/markdown
@@ -93,12 +99,22 @@ module StillActive
       }.filter_map { |name, value| { "name" => name, "value" => value } unless value.nil? }
     end
 
+    # The Ruby interpreter. CycloneDX's "platform" type fits semantically, but
+    # nothing consumes it and strict SCA validators (Datadog) only accept
+    # "library" + a purl. We follow Syft's convention for an unmanaged runtime:
+    # type "library", purl pkg:generic/ruby@<ver>, plus a CPE — the CPE is what
+    # actually lets a matcher (NVD/Grype) hit interpreter CVEs, since no purl
+    # type maps the Ruby runtime in OSV. The EOL/libyear signals stay as
+    # still_active properties.
     def ruby_component(ruby_info)
+      version = ruby_info[:version]
       {
-        "type" => "platform",
+        "type" => "library",
         "name" => "ruby",
-        "version" => ruby_info[:version],
-        "bom-ref" => "platform:ruby@#{ruby_info[:version]}",
+        "version" => version,
+        "bom-ref" => "pkg:generic/ruby@#{version}",
+        "purl" => "pkg:generic/ruby@#{version}",
+        "cpe" => "cpe:2.3:a:ruby-lang:ruby:#{version}:*:*:*:*:*:*:*",
         "properties" => [
           { "name" => "still_active:eol", "value" => boolean_property(ruby_info[:eol]) },
           { "name" => "still_active:libyear", "value" => ruby_info[:libyear]&.to_s },
@@ -126,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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "markdown_escape"
+
 module StillActive
   # Renders a StillActive::Diff::Result as PR-comment-friendly markdown.
   # Section taxonomy mirrors GitHub's dependency-review-action so reviewers
@@ -17,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),
@@ -36,23 +39,38 @@ 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)
       return "" if regressions.empty?
 
-      lines = regressions.map { |r| "- **#{r.kind}** `#{r.gem}` — #{r.detail}" }
+      lines = regressions.map { |r| "- **#{r.kind}** #{MarkdownEscape.code_span(r.gem)} — #{MarkdownEscape.inline(r.detail)}" }
       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?
 
@@ -63,7 +81,7 @@ module StillActive
     def removed_section(removed)
       return "" if removed.empty?
 
-      lines = removed.map { |r| "- `#{r.name}` (was #{(r.data || {})["version_used"] || "?"})" }
+      lines = removed.map { |r| "- #{MarkdownEscape.code_span(r.name)} (was #{MarkdownEscape.inline((r.data || {})["version_used"] || "?")})" }
       section("Removed", lines)
     end
 
@@ -88,9 +106,9 @@ module StillActive
       lines = []
       if ruby[:version_changed]
         eol_suffix = ruby[:newly_eol] ? " (now EOL)" : ""
-        lines << "- Ruby `#{ruby[:from]}` → `#{ruby[:to]}`#{eol_suffix}"
+        lines << "- Ruby #{MarkdownEscape.code_span(ruby[:from])} → #{MarkdownEscape.code_span(ruby[:to])}#{eol_suffix}"
       elsif ruby[:newly_eol]
-        lines << "- Ruby `#{ruby[:to]}` is now EOL"
+        lines << "- Ruby #{MarkdownEscape.code_span(ruby[:to])} is now EOL"
       end
       section("Ruby", lines)
     end
@@ -108,30 +126,31 @@ module StillActive
         (data["archived"] ? "archived" : nil),
         data["libyear"] && "#{data["libyear"]}y behind",
       ].compact
-      "`#{added.name}` (#{bits.join(", ")})"
+      "#{MarkdownEscape.code_span(added.name)} (#{MarkdownEscape.inline(bits.join(", "))})"
     end
 
     def format_bump(bump)
       label = BUMP_KIND_LABELS[bump.kind]
       suffix = label ? " (#{label})" : ""
-      "- `#{bump.name}` #{bump.before_version} → #{bump.after_version}#{suffix}"
+      "- #{MarkdownEscape.code_span(bump.name)} #{MarkdownEscape.inline(bump.before_version)} → #{MarkdownEscape.inline(bump.after_version)}#{suffix}"
     end
 
     def format_signal_change_lines(sc)
+      name = MarkdownEscape.code_span(sc.name)
       sc.changes.filter_map do |ch|
         case ch[:kind]
         when :archived
-          "- `#{sc.name}` — archived (false → true)"
+          "- #{name} — archived (false → true)"
         when :new_vulnerability
-          ids = Array(ch[:ids]).join(", ")
-          "- `#{sc.name}` — new vulnerability (#{ch[:from]} → #{ch[:to]}#{" — #{ids}" unless ids.empty?})"
+          ids = MarkdownEscape.inline(Array(ch[:ids]).join(", "))
+          "- #{name} — new vulnerability (#{MarkdownEscape.inline(ch[:from])} → #{MarkdownEscape.inline(ch[:to])}#{" — #{ids}" unless ids.empty?})"
         when :scorecard_dropped
           note = ch[:crossed_good] ? " (crossed 7.0)" : ""
-          "- `#{sc.name}` — scorecard #{ch[:from]} → #{ch[:to]}#{note}"
+          "- #{name} — scorecard #{MarkdownEscape.inline(ch[:from])} → #{MarkdownEscape.inline(ch[:to])}#{note}"
         when :version_yanked
-          "- `#{sc.name}` — version yanked from rubygems"
+          "- #{name} — version yanked from rubygems"
         when :libyear_worsened
-          "- `#{sc.name}` — libyear #{ch[:from]} → #{ch[:to]} (+#{ch[:delta]}y; same pinned version)"
+          "- #{name} — libyear #{MarkdownEscape.inline(ch[:from])} → #{MarkdownEscape.inline(ch[:to])} (+#{ch[:delta]}y; same pinned version)"
         end
       end
     end

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