still_active 2.0.0 → 3.0.0.rc2

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

data/lib/helpers/sarif_helper.rb

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

data/lib/helpers/semver_satisfaction.rb

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

data/lib/helpers/status_helper.rb

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

data/lib/helpers/summary_helper.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "activity_helper"
+require_relative "status_helper"
 
 module StillActive
   # Builds the JSON output's summary{} digest: the headline posture of the audit
@@ -40,6 +41,9 @@ module StillActive
         outdated: outdated,
         vulnerable_gems: vulnerable_gems,
         vulnerabilities: vulnerabilities,
+        # The single worst per-gem verdict (plus EOL Ruby), so a consumer reads
+        # one project-level posture without scanning every gem's status.
+        status: StatusHelper.project_status(result, ruby_info: ruby_info),
       }
       summary[:ruby_eol] = ruby_info[:eol] == true if ruby_info
       summary