still_active 1.6.0 → 2.0.0

data/lib/helpers/http_helper.rb

@@ -5,8 +5,15 @@ 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", "endoflife.date", "rubygems.pkg.github.com"].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,35 +22,74 @@ 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")
@@ -54,6 +100,47 @@ module StillActive
     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,8 @@
 # frozen_string_literal: true
 
+require_relative "markdown_escape"
 require_relative "vulnerability_helper"
+require_relative "activity_helper"
 
 module StillActive
   module MarkdownHelper
@@ -91,12 +93,31 @@ 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
 
     private
 
+    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 +149,7 @@ module StillActive
     def format_license(license)
       return "-" if license.nil? || license.empty?
 
-      license
+      MarkdownEscape.cell(license)
     end
 
     def format_vulns(data)
@@ -141,14 +162,15 @@ module StillActive
       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?
+      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/ruby_helper.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "time"
+require_relative "bundler_helper"
 require_relative "http_helper"
 require_relative "libyear_helper"
 
@@ -48,10 +49,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)

data/lib/helpers/sarif_helper.rb

@@ -5,6 +5,7 @@ require "digest"
 require "time"
 require_relative "../still_active/sarif/rules"
 require_relative "lockfile_indexer"
+require_relative "activity_helper"
 
 module StillActive
   # Renders a still_active workflow result as a SARIF 2.1.0 document.
@@ -19,7 +20,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,43 +99,68 @@ 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
 
       out
     end
 
-    def vulnerability_result(name, version, vuln, location)
+    # 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 = {})
       score = vuln[:cvss3_score] || vuln[:cvss2_score]
       level = Sarif::Rules.cvss_to_level(score)
       severity = Sarif::Rules.cvss_to_security_severity(score)
@@ -146,13 +172,23 @@ module StillActive
       base = result(
         "SA003",
         name,
-        "#{name} #{version}: #{advisory_id}#{title}#{alias_suffix}.",
+        "#{name} #{version}: #{advisory_id}#{title}#{alias_suffix}#{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 +247,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/summary_helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "activity_helper"
+
+module StillActive
+  # Builds the JSON output's summary{} digest: the headline posture of the audit
+  # in one object, so a machine/LLM consumer reads the totals directly instead
+  # of iterating every gem. Counts are derived from the canonical per-gem fields
+  # (activity_level, archived, up_to_date, vulnerability_count) so they never
+  # drift from a separately-thresholded SARIF rule.
+  module SummaryHelper
+    ACTIVITY_LEVELS = [:ok, :stale, :critical, :archived, :unknown].freeze
+
+    extend self
+
+    def summarize(result, ruby_info: nil)
+      activity = ACTIVITY_LEVELS.to_h { |level| [level, 0] }
+      archived = up_to_date = outdated = vulnerable_gems = vulnerabilities = direct = 0
+
+      result.each_value do |data|
+        activity[ActivityHelper.activity_level(data)] += 1
+        direct += 1 if data[:direct]
+        archived += 1 if data[:archived]
+        up_to_date += 1 if data[:up_to_date] == true
+        outdated += 1 if data[:up_to_date] == false
+        count = data[:vulnerability_count].to_i
+        next unless count.positive?
+
+        vulnerable_gems += 1
+        vulnerabilities += count
+      end
+
+      summary = {
+        total_gems: result.size,
+        direct: direct,
+        transitive: result.size - direct,
+        activity: activity,
+        archived: archived,
+        up_to_date: up_to_date,
+        outdated: outdated,
+        vulnerable_gems: vulnerable_gems,
+        vulnerabilities: vulnerabilities,
+      }
+      summary[:ruby_eol] = ruby_info[:eol] == true if ruby_info
+      summary
+    end
+  end
+end