still_active 1.6.0 → 3.0.0.rc1

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

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "time"
+require_relative "bundler_helper"
+require_relative "endoflife_helper"
 require_relative "http_helper"
 require_relative "libyear_helper"
 
@@ -23,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(
@@ -41,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
@@ -48,10 +58,10 @@ module StillActive
     end
 
     def lockfile_ruby_version
-      gemfile = ENV["BUNDLE_GEMFILE"]
-      return unless gemfile
-
-      lockfile_path = "#{gemfile}.lock"
+      # Use the configured gemfile (honours --gemfile) rather than the ambient
+      # BUNDLE_GEMFILE, which only happened to work when BundlerHelper set it as
+      # a side-effect. Refs #42.
+      lockfile_path = BundlerHelper.lockfile_path_for(File.expand_path(StillActive.config.gemfile_path))
       return unless File.exist?(lockfile_path)
 
       content = File.read(lockfile_path)
@@ -67,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

@@ -5,6 +5,8 @@ require "digest"
 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.
@@ -19,7 +21,7 @@ module StillActive
 
     LIBYEAR_THRESHOLD = 1.0
     SCORECARD_LOW_THRESHOLD = 4.0
-    ABANDONED_SECONDS = 2 * 365 * 24 * 60 * 60 # 2 years
+    SECONDS_PER_YEAR = 365 * 24 * 60 * 60 # for the human-readable "in N years"
 
     # result: same hash StillActive::Workflow.call returns (gem_name => gem_data)
     # ruby_info: optional Ruby freshness hash (or nil)
@@ -98,61 +100,197 @@ module StillActive
       location = location_for(name, line_index, lockfile_uri)
 
       if data[:archived]
-        out << result("SA001", name, "#{name} #{version}: upstream repository is archived#{repo_suffix(data)}#{alternatives_suffix(data)}.", location)
+        out << mark_suppressed(result("SA001", name, "#{name} #{version}: upstream repository is archived#{repo_suffix(data)}#{alternatives_suffix(data)}#{transitive_suffix(data)}.", location), name, :activity)
       end
 
       unless data[:archived]
-        last_commit = parse_time(data[:last_commit_date])
-        if last_commit && last_commit < (Time.now - ABANDONED_SECONDS)
-          years = ((Time.now - last_commit) / (365 * 24 * 60 * 60)).round(1)
-          out << result(
-            "SA002",
+        if ActivityHelper.activity_level(data) == :critical
+          activity = ActivityHelper.last_activity(data)
+          years = ((Time.now - activity[:date]) / SECONDS_PER_YEAR).round(1)
+          noun = activity[:kind] == :release ? "no release" : "no commits"
+          out << mark_suppressed(
+            result(
+              "SA002",
+              name,
+              "#{name} #{version}: #{noun} in #{years} years (last #{activity[:date].utc.strftime("%Y-%m-%d")})#{alternatives_suffix(data)}#{transitive_suffix(data)}.",
+              location,
+            ),
             name,
-            "#{name} #{version}: no commits in #{years} years (last #{last_commit.utc.strftime("%Y-%m-%d")})#{alternatives_suffix(data)}.",
-            location,
+            :activity,
           )
         end
       end
 
       Array(data[:vulnerabilities]).each do |vuln|
-        out << vulnerability_result(name, version, vuln, location)
+        out << vulnerability_result(name, version, vuln, location, data)
       end
 
       if data[:libyear] && data[:libyear] > LIBYEAR_THRESHOLD
         latest = data[:latest_version] ? " behind #{data[:latest_version]}" : ""
-        out << result("SA004", name, "#{name} #{version}: #{data[:libyear]} libyears#{latest}.", location)
+        out << mark_suppressed(result("SA004", name, "#{name} #{version}: #{data[:libyear]} libyears#{latest}#{transitive_suffix(data)}.", location), name, :libyear)
       end
 
       if data[:scorecard_score] && data[:scorecard_score] < SCORECARD_LOW_THRESHOLD
-        out << result("SA005", name, "#{name} #{version}: OpenSSF Scorecard #{data[:scorecard_score]}/10 (low).", location)
+        out << mark_suppressed(result("SA005", name, "#{name} #{version}: OpenSSF Scorecard #{data[:scorecard_score]}/10 (low).", location), name, :scorecard)
       end
 
       if data[:version_yanked]
-        out << result("SA007", name, "#{name} #{version}: this version has been yanked from RubyGems.", location)
+        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 vulnerability_result(name, version, vuln, location)
-      score = vuln[:cvss3_score] || vuln[:cvss2_score]
-      level = Sarif::Rules.cvss_to_level(score)
+    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
+    # suppression's reason rides along as the justification.
+    def mark_suppressed(result_hash, gem_name, signal, advisory: nil, aliases: [])
+      config = StillActive.config
+      if config.ignored_gems.include?(gem_name)
+        result_hash["suppressions"] = [{ "kind" => "external", "justification" => "ignored via --ignore" }]
+        return result_hash
+      end
+
+      entry = config.suppressions.match(gem: gem_name, signal: signal, advisory: advisory, aliases: aliases)
+      return result_hash unless entry
+
+      suppression = { "kind" => "external" }
+      suppression["justification"] = entry.reason if entry.reason
+      result_hash["suppressions"] = [suppression]
+      result_hash
+    end
+
+    def vulnerability_result(name, version, vuln, location, data = {})
+      # 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}.",
+        "#{name} #{version}: #{advisory_id}#{title}#{alias_suffix}#{no_fix}#{transitive_suffix(data)}.",
         location,
         level: level,
         fp_extra: advisory_id,
       )
       base["properties"] = { "security-severity" => severity } if severity
-      base
+      mark_suppressed(base, name, :vulnerability, advisory: vuln[:id], aliases: Array(vuln[:aliases]))
+    end
+
+    # Names the direct dependency a transitive flagged gem rides in on, so a
+    # code-scanning consumer gets the actionable "replace your direct gem" hop
+    # instead of an un-actionable transitive finding (#60).
+    def transitive_suffix(data)
+      path = data[:dependency_path]
+      return "" unless data[:direct] == false && path && path.length >= 2
+
+      " (transitive, pulled in by #{path.first})"
     end
 
     def ruby_eol_result(ruby_info, ruby_line, lockfile_uri)
@@ -211,17 +349,8 @@ module StillActive
       Sarif::Rules.all.index { |r| r[:id] == rule_id }
     end
 
-    def parse_time(value)
-      return value if value.is_a?(Time)
-      return if value.nil?
-
-      Time.parse(value.to_s)
-    rescue ArgumentError, TypeError, RangeError
-      nil
-    end
-
     def format_date(value)
-      t = parse_time(value)
+      t = ActivityHelper.parse_time(value)
       t ? t.utc.strftime("%Y-%m-%d") : value.to_s
     end
 

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