still_active 1.4.2 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32a0544a8668d86b73edc4296a246b875e3c5bfbc5016544ea2b1133e1332bb8
-  data.tar.gz: bdbbaa17281dac2425cbe96a386164ae608566b3a4dd594e7e8d3d262a10f206
+  metadata.gz: 6e5e5e599cdd630ec6e916800c4abd7df4a3c9d37e24122e80d8859accb1c4e3
+  data.tar.gz: 0cb0dfd2c761612f665a9d2f4e0ba20f47bf8b082c42281af09b8429335aa2a9
 SHA512:
-  metadata.gz: a63140b613dc6eb0f7fe618a4845db833524993c00ab6773699dbbd150fead81ff5f74fad283444d6d84d5aa07ef79f8cba7ab055ae3e81d720bcbeaee52f800
-  data.tar.gz: 00f898a6edefc7405e4e5d9a35b37c803b185b1e4e7edcbb76c8faf7eb9e93ef3e18660b1719b9db5b6d9961a4300dc1c3b017cd366bb195f6ea3e33b0f584bc
+  metadata.gz: 571797c9863bf6597e7c9474e8cf718019925d37d163002e9d594b137458ca0a6be155dfb7a5069777afe83963fb4dc595026a69c8237ce1aa7d024eb254be99
+  data.tar.gz: 4e7ba6a7777973b6fe7f1fa54fc1fad00a06639da18944f0bc89befd6a3e794b1d55eeaca62f33b193bebb54cdb2d6d85c63ae48a73adc722e58a3f194c0aeae

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [1.6.0] - 2026-06-08
+
+### Added
+
+- `--alternatives` surfaces up to three maintained alternative gems for any dependency still_active flags as archived or critically abandoned, drawn from the [rubytoolbox/catalog](https://github.com/rubytoolbox/catalog) category data and ranked by total RubyGems downloads. Presented as **leads to verify, not vetted recommendations** — same Ruby Toolbox category does not guarantee a drop-in replacement — reflecting that Ruby has no authoritative successor metadata the way npm (`deprecate`), Go (`// Deprecated:`), or NuGet (alternate-package) do. Opt-in and best-effort: the catalog is fetched once and cached under `XDG_CACHE_HOME` with a 7-day TTL, any fetch/parse failure degrades to silence, and nothing here can block a run or affect `--fail-if-*` exit codes. Leads render in terminal (a dimmed sub-line), markdown (an Alternatives section), JSON (an additive `alternatives` array), and SARIF (appended to the SA001/SA002 result messages); CycloneDX is unchanged. With the flag off, terminal output shows a one-line discoverability hint on flagged gems. Silent when the catalog has no entry for the gem (the common case for niche/long-tail gems). Closes #28.
+
+### Changed
+
+- The `async` runtime dependency now requires `>= 2.2` (previously unconstrained). 2.2.0 is the verified real minimum — earlier 2.x releases hit a fiber-scheduler `io_read` bug under still_active's concurrent fan-out. A new CI job installs every runtime dependency at its declared gemspec floor and runs the suite on the minimum supported Ruby, so an under-set floor now fails loudly instead of silently.
+
+## [1.5.0] - 2026-05-23
+
+### Added
+
+- `--cyclonedx[=PATH]` emits a CycloneDX SBOM (stdout by default, or to a file) so the dependency graph plus still_active's signals flow into Trivy / Dependency-Track / Snyk. Emits **1.6 by default** — the version mainstream consumers ingest today (`cyclonedx-core-java` / Dependency-Track and `cyclonedx-go` / Trivy both cap at 1.6 as of 2026) — with `--cyclonedx-version=1.7` to opt into the latest. Gem name/version/purl/licenses map to native fields; maintenance signals (archived, OpenSSF score, libyear, last commit, yanked) ride in `still_active:`-namespaced `properties`; vulnerabilities map to the top-level `vulnerabilities[]`. The `serialNumber` is content-derived (two SBOMs of the same lockfile are byte-identical apart from the generation timestamp), so SBOMs diff cleanly.
+- Dependabot/Renovate awareness: when a run is detected as bot-authored (primarily via the PR author in the GitHub event payload — `pull_request.user.login`, the same authoritative signal `dependabot/fetch-metadata` uses, which unlike `GITHUB_ACTOR` survives a human re-running the workflow — falling back to `GITHUB_ACTOR`, a `dependabot/`/`renovate/` branch, or the commit subject including Dependabot's default unprefixed `Bump X from Y to Z`), output leads with a narrative header (markdown/terminal/baseline-diff: "Dependabot bump: rack 2.0.0 → 2.0.6") and JSON gains a top-level additive `pr_context` (`{ bot, bumps: [{ gem, from, to }] }`). Bump extraction tolerates any configured `commit-message.prefix`/scope (`chore(deps):`, `deps:`, …) once the bot is confirmed, while detection stays conservative to avoid false positives on human commits. Best-effort: false negatives lose only the narrative, never a finding; SARIF is unaffected. See `docs/schema.md`.
+- A warning is emitted when mutually-exclusive output flags are combined (`--baseline`/`--sarif`/`--cyclonedx`), naming which one wins, and when `--cyclonedx-version` is set without `--cyclonedx`.
+- Dual-source vulnerability data: when `bundler-audit` is installed (with a current `bundle audit update` checkout), still_active reads the `rubysec/ruby-advisory-db` advisories through bundler-audit's own loader and merges them with deps.dev results, deduplicating on shared identifiers. Each advisory carries a `source` field (`deps.dev`, `ruby-advisory-db`, or `merged`); deps.dev is preferred for CVSS/title/vector and ruby-advisory-db fills gaps. Opt-in by composition — no second source unless `bundler-audit` is present; falls back silently to deps.dev only otherwise (with a one-line hint to run `bundle audit update`). Closes the "why do bundler-audit and still_active disagree?" gap. See `docs/schema.md` and `docs/rules.md` (SA003).
+- Gem license surfaced from the RubyGems versions payload we already fetch (no extra request). Shows as a `License` column in terminal and markdown output and as an additive `license` field (SPDX identifier, comma-joined when a gem declares more than one) on the JSON per-gem record. `nil`/`-` for git/path sources where no RubyGems metadata exists. See `docs/schema.md`. Read-only metadata only — license *policy* (allow/deny gating) stays the domain of `license_finder`.
+
 ## [1.4.2] - 2026-05-22
 
 ### Fixed

data/README.md

@@ -4,6 +4,8 @@
 
 `bundle outdated` tells you version drift. `bundler-audit` catches known CVEs. Neither tells you whether anyone is still working on the thing. `still_active` checks maintenance activity, version freshness, security scores, vulnerabilities, libyear drift, and archived repos for every gem in your Gemfile.
 
+Findings ship as **terminal / markdown / JSON / SARIF / CycloneDX** — SARIF lands in your GitHub Security tab and as inline PR annotations on `Gemfile.lock`; CycloneDX feeds Trivy / Dependency-Track / Snyk. PR mode (`--baseline=FILE`) reports only what got worse since main, so reviewers see one line ("`vcr` newly archived") instead of an absolute snapshot of every dep.
+
 [![Gem Version](https://badge.fury.io/rb/still_active.svg)](https://badge.fury.io/rb/still_active)
 [![GitHub Action](https://img.shields.io/badge/Marketplace-still__active--action-2ea44f?logo=github)](https://github.com/marketplace/actions/still_active)
 ![Code Quality analysis](https://github.com/SeanLF/still_active/actions/workflows/codeql-analysis.yml/badge.svg)
@@ -11,15 +13,15 @@
 ![Rubocop analysis](https://github.com/SeanLF/still_active/actions/workflows/rubocop-analysis.yml/badge.svg)
 
 ```
-Name                    Version          Activity  OpenSSF  Vulns
-───────────────────────────────────────────────────────────────────
-async                   2.36.0 (latest)  ok        7.1/10   0
-backbone-rails          1.2.3 (latest)   archived  3.6/10   0
-bootstrap-slider-rails  9.8.0 (latest)   critical  -        0
-gitlab-markup           2.0.0 (latest)   ok        -        0
-local_gem               0.1.0 (path)     -         -        0
-nested_form             0.3.2 (git)      archived  3.3/10   0
-remotipart              1.4.4 (git)      critical  3.1/10   0
+Name                    Version          Activity  OpenSSF  Vulns  License
+──────────────────────────────────────────────────────────────────────────────
+async                   2.36.0 (latest)  ok        7.1/10   0      MIT
+backbone-rails          1.2.3 (latest)   archived  3.6/10   0      MIT
+bootstrap-slider-rails  9.8.0 (latest)   critical  -        0      MIT
+gitlab-markup           2.0.0 (latest)   ok        -        0      MIT
+local_gem               0.1.0 (path)     -         -        0      -
+nested_form             0.3.2 (git)      archived  3.3/10   0      MIT
+remotipart              1.4.4 (git)      critical  3.1/10   0      MIT
 
 7 gems: 4 up to date, 0 outdated · 2 active, 2 stale, 2 archived · 0 vulnerabilities
 Ruby 4.0.1 (latest)
@@ -32,7 +34,7 @@ Ruby 4.0.1 (latest)
 |                              | `bundle outdated` | `bundler-audit`        | `libyear-bundler` | **`still_active`**       |
 | ---------------------------- | ----------------- | ---------------------- | ----------------- | ------------------------ |
 | Outdated versions            | Yes               | -                      | Yes               | Yes                      |
-| Known vulnerabilities (CVEs) | -                 | Yes (ruby-advisory-db) | -                 | Yes (deps.dev)           |
+| Known vulnerabilities (CVEs) | -                 | Yes (ruby-advisory-db) | -                 | Yes (deps.dev + ruby-advisory-db) |
 | Libyear drift                | -                 | -                      | Yes               | Yes                      |
 | **Last commit activity**     | -                 | -                      | -                 | **Yes**                  |
 | **Archived repo detection**  | -                 | -                      | -                 | **Yes**                  |
@@ -41,9 +43,9 @@ Ruby 4.0.1 (latest)
 | **Ruby version freshness**   | -                 | -                      | -                 | **Yes** (EOL + libyear)  |
 | GitLab support               | -                 | -                      | -                 | Yes                      |
 | CI quality gates             | -                 | Exit code              | -                 | Yes (4 flags)            |
-| Output formats               | Text              | Text                   | Text              | Terminal, JSON, Markdown |
+| Output formats               | Text              | Text                   | Text              | Terminal, JSON, Markdown, SARIF, CycloneDX |
 
-The bolded rows are the gap `still_active` fills: nobody else answers "is the maintainer still around?" The CVE column is worth a closer look: `bundler-audit` and `still_active` use **different data sources** (`ruby-advisory-db` vs `deps.dev`), so coverage isn't identical. If you care about CVEs in CI, keep running `bundler-audit` alongside `still_active`.
+The bolded rows are the gap `still_active` fills: nobody else answers "is the maintainer still around?" The CVE column is worth a closer look: `bundler-audit` reads `ruby-advisory-db` and `still_active` reads `deps.dev`, which sometimes diverge. **If `bundler-audit` is installed alongside `still_active`, we read its `ruby-advisory-db` checkout too and merge the results** (deduplicated, each advisory tagged with its `source`) — so running both no longer means reconciling two different vuln counts by hand.
 
 ## Installation
 
@@ -51,6 +53,8 @@ The bolded rows are the gap `still_active` fills: nobody else answers "is the ma
 gem install still_active
 ```
 
+**Requires an actively-maintained Ruby.** The gemspec's `required_ruby_version` floor tracks Ruby's [EOL schedule](https://endoflife.date/ruby); running a maintenance auditor on an unmaintained runtime would be a bit rich. You don't have to run it *on* the Ruby you're auditing, though: still_active reports on the version your project pins in `Gemfile.lock`, so run it from any current Ruby (locally, in CI, or via the [`still_active-action`](https://github.com/SeanLF/still_active-action)) and it will still flag an EOL target.
+
 ## Quick Start
 
 ```bash
@@ -97,7 +101,10 @@ Usage: still_active [options]
         --terminal                   Coloured terminal output (default in TTY)
         --markdown                   Markdown table output
         --json                       JSON output (default when piped)
+        --alternatives               Suggest maintained alternatives (Ruby Toolbox leads) for archived/critical gems
         --sarif[=PATH]               SARIF 2.1.0 output for GitHub Code Scanning
+        --cyclonedx[=PATH]           CycloneDX SBOM output (stdout, or a file path)
+        --cyclonedx-version=VERSION  CycloneDX spec version: 1.6 (default) or 1.7
         --baseline=PATH              Compare current state to baseline JSON; emit markdown deltas
         --github-oauth-token=TOKEN   GitHub OAuth token to make API calls
         --gitlab-token=TOKEN         GitLab personal access token for API calls
@@ -141,6 +148,7 @@ still_active --json --gemfile=spec/still_active/edge_case_gemfile/Gemfile
       "archived": false,
       "scorecard_score": 7.1,
       "vulnerability_count": 0,
+      "license": "MIT",
       "libyear": 0.0
     },
     "nested_form": {
@@ -174,15 +182,25 @@ still_active --json --gemfile=spec/still_active/edge_case_gemfile/Gemfile
 still_active --markdown
 ```
 
-| activity | up to date? | OpenSSF | vulns | name                                                         | version used                                                               | latest version                                                             | latest pre-release | last commit                                           | libyear |
-| -------- | ----------- | ------- | ----- | ------------------------------------------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------- | ------- |
-|          | ✅          | 7.1/10  | ✅    | [async](https://github.com/socketry/async)                   | [2.36.0](https://rubygems.org/gems/async/versions/2.36.0) (2026/01)        | [2.36.0](https://rubygems.org/gems/async/versions/2.36.0) (2026/01)        | ❓                 | [2026/01](https://github.com/socketry/async)          | 0.0y    |
-| 🚩       | ✅          | 3.6/10  | ✅    | [backbone-rails](https://github.com/aflatter/backbone-rails) | [1.2.3](https://rubygems.org/gems/backbone-rails/versions/1.2.3) (2016/02) | [1.2.3](https://rubygems.org/gems/backbone-rails/versions/1.2.3) (2016/02) | ❓                 | [2016/02](https://github.com/aflatter/backbone-rails) | 0.0y    |
-| ❓       | ❓          | ❓      | ✅    | local_gem                                                    | 0.1.0 (path)                                                               | ❓                                                                         | ❓                 | ❓                                                    | -       |
-| 🚩       | ❓          | 3.3/10  | ✅    | [nested_form](https://github.com/ryanb/nested_form)          | 0.3.2 (git)                                                                | ❓                                                                         | ❓                 | [2021/12](https://github.com/ryanb/nested_form)       | -       |
+| activity | up to date? | OpenSSF | vulns | name                                                         | version used                                                               | latest version                                                             | latest pre-release | last commit                                           | libyear | license |
+| -------- | ----------- | ------- | ----- | ------------------------------------------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------- | ------- | ------- |
+|          | ✅          | 7.1/10  | ✅    | [async](https://github.com/socketry/async)                   | [2.36.0](https://rubygems.org/gems/async/versions/2.36.0) (2026/01)        | [2.36.0](https://rubygems.org/gems/async/versions/2.36.0) (2026/01)        | ❓                 | [2026/01](https://github.com/socketry/async)          | 0.0y    | MIT     |
+| 🚩       | ✅          | 3.6/10  | ✅    | [backbone-rails](https://github.com/aflatter/backbone-rails) | [1.2.3](https://rubygems.org/gems/backbone-rails/versions/1.2.3) (2016/02) | [1.2.3](https://rubygems.org/gems/backbone-rails/versions/1.2.3) (2016/02) | ❓                 | [2016/02](https://github.com/aflatter/backbone-rails) | 0.0y    | MIT     |
+| ❓       | ❓          | ❓      | ✅    | local_gem                                                    | 0.1.0 (path)                                                               | ❓                                                                         | ❓                 | ❓                                                    | -       | -       |
+| 🚩       | ❓          | 3.3/10  | ✅    | [nested_form](https://github.com/ryanb/nested_form)          | 0.3.2 (git)                                                                | ❓                                                                         | ❓                 | [2021/12](https://github.com/ryanb/nested_form)       | -       | MIT     |
 
 **Ruby 4.0.1** (latest) ✅
 
+**CycloneDX** -- a standards-track SBOM so your dependency graph and still_active's signals flow into Trivy, Dependency-Track, or Snyk:
+
+```bash
+still_active --cyclonedx                 # CycloneDX 1.6 to stdout
+still_active --cyclonedx=sbom.json       # write to a file
+still_active --cyclonedx --cyclonedx-version=1.7
+```
+
+Emits **1.6 by default** — the version mainstream consumers ingest today (`cyclonedx-core-java`/Dependency-Track and `cyclonedx-go`/Trivy both cap at 1.6 as of 2026); `--cyclonedx-version=1.7` opts into the latest. Gem name/version/`purl`/licenses and vulnerabilities map to native CycloneDX fields; maintenance signals with no native home (archived, OpenSSF score, libyear, last commit, yanked) ride in `still_active:`-namespaced `properties`. The `serialNumber` is content-derived, so two SBOMs of the same lockfile differ only by their generation timestamp.
+
 ### SARIF output (GitHub Code Scanning)
 
 Emit findings as SARIF 2.1.0 — they show up in the GitHub Security tab and as inline annotations on `Gemfile.lock` in pull requests.
@@ -245,6 +263,53 @@ In CI, capture a baseline on main and compare on PR branches. Exits 1 if any reg
 
 The diff supersedes `--sarif`, `--terminal`, `--markdown`, and `--json` when set.
 
+When a run is detected as Dependabot- or Renovate-authored (via `GITHUB_ACTOR`, a `dependabot/`/`renovate/` branch, or the commit subject), the report leads with a one-line narrative — "Dependabot bump: `rack` 2.0.0 → 2.0.6" — and `--json` gains a top-level `pr_context`. Detection is best-effort and conservative: it never produces a false positive on an ordinary commit, and a miss costs only the narrative line.
+
+### Alongside `dependency-review-action`
+
+GitHub's first-party [`dependency-review-action`](https://github.com/actions/dependency-review-action) runs server-side on PRs and surfaces **vulnerabilities, licenses, and OpenSSF Scorecard** scores from GitHub's dependency-graph diff. It does not surface maintenance signals — last-commit activity, archived repos, libyear, Ruby EOL, or yanked versions — and is GitHub.com / GHES only. `still_active` is the complement, not a replacement:
+
+|                              | `dependency-review-action`         | `still_active`                              |
+| ---------------------------- | ---------------------------------- | ------------------------------------------- |
+| Platform                     | GitHub.com / GHES only             | Any CI                                      |
+| Languages                    | Multi (GitHub dep graph)           | Ruby                                        |
+| Vulnerabilities              | GHSA                               | deps.dev + ruby-advisory-db (merged)        |
+| Licenses                     | Yes (allow/deny gating)            | Surfaced (no gating)                        |
+| OpenSSF Scorecard            | Yes (display)                      | Yes (display + threshold)                   |
+| **Last-commit activity**     | -                                  | **Yes**                                     |
+| **Archived repo detection**  | -                                  | **Yes**                                     |
+| **Libyear drift**            | -                                  | **Yes**                                     |
+| **Ruby EOL detection**       | -                                  | **Yes**                                     |
+| **Yanked version detection** | -                                  | **Yes**                                     |
+| Diff vs base                 | Native (GitHub API)                | `--baseline=FILE`                           |
+| Output                       | Inline PR annotations              | Terminal / Markdown / JSON / SARIF / CycloneDX |
+
+Run both: let `dependency-review-action` gate CVEs and licenses, and `still_active` add the maintenance lens on the same PR.
+
+```yaml
+on: pull_request
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high
+          show-openssf-scorecard: true
+
+  maintenance-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with: { ruby-version: ".ruby-version", bundler-cache: true }
+      - uses: SeanLF/still_active-action@v0
+        with:
+          fail-if-critical: true
+```
+
 ### CI quality gating
 
 Use exit-code flags to fail CI pipelines based on dependency status:
@@ -277,12 +342,28 @@ Activity is determined by the most recent signal across last commit date, latest
 - **stale**: last activity between 1 and 3 years ago (configurable with `--warning-range-end`)
 - **critical**: last activity over 3 years ago
 
+### Alternative gem leads (opt-in)
+
+When a gem is flagged archived or critical, `--alternatives` surfaces up to three maintained gems from the same [Ruby Toolbox](https://www.ruby-toolbox.com) category, ranked by total downloads:
+
+```bash
+still_active --gems=paperclip --alternatives
+```
+
+```text
+↳ leads (Ruby Toolbox): shrine · carrierwave · kt-paperclip (verify fit)
+```
+
+These are **leads, not recommendations**: same-category does not mean drop-in replacement, so verify fit before switching. Ruby has no authoritative "use instead" metadata (unlike npm `deprecate`, Go's `// Deprecated:`, or NuGet's alternate-package field), so this is a best-effort heuristic. It is silent when the catalog has no entry for the gem, and the feature never blocks or fails a run. Leads appear in terminal, markdown, JSON, and SARIF output. When the flag is off, terminal output shows a one-line hint on flagged gems that the option exists (other formats stay silent).
+
 ### Data sources
 
-- **Versions and release dates** from [RubyGems.org](https://rubygems.org) or [GitHub Packages](https://docs.github.com/en/packages)
+- **Versions, release dates, and licenses** from [RubyGems.org](https://rubygems.org) or [GitHub Packages](https://docs.github.com/en/packages)
 - **Last commit date and archived status** from the [GitHub](https://docs.github.com/en/rest) or [GitLab](https://docs.gitlab.com/ee/api/) API
 - **OpenSSF Scorecard**, **vulnerability counts**, and **CVSS severity** from Google's [deps.dev](https://deps.dev) API
+- **Additional advisories** from [ruby-advisory-db](https://github.com/rubysec/ruby-advisory-db), merged in when `bundler-audit` is installed alongside (run `bundle audit update` to keep its checkout current)
 - **Ruby version freshness** from [endoflife.date](https://endoflife.date)
+- **Alternative gem leads** (with `--alternatives`) from the [rubytoolbox/catalog](https://github.com/rubytoolbox/catalog) category data
 
 ### Configuration defaults
 

data/lib/helpers/alternatives_helper.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "gems"
+
+module StillActive
+  # Turns a gem's catalog siblings into ranked "leads" -- the most-downloaded
+  # still-published alternatives. Best-effort: a failed lookup drops that
+  # candidate, never the feature.
+  module AlternativesHelper
+    extend self
+
+    MAX_SIBLINGS_CONSIDERED = 40 # bound the download lookups for huge categories
+    DEFAULT_LIMIT = 3
+
+    def leads_for(gem_name:, index:, limit: DEFAULT_LIMIT)
+      return [] if index.nil?
+
+      # Bound the per-gem download lookups so a huge category can't trigger
+      # dozens of HTTP calls. This is a catalog-order prefix, so a very large
+      # category could leave a popular sibling past the cap out of the ranking;
+      # acceptable for best-effort leads where we only ever surface a few.
+      # (CatalogIndex already reduces owner/repo slugs to their gem-name tail,
+      # so every entry here is a plain name rankable by downloads.)
+      siblings = (index[gem_name] || []).first(MAX_SIBLINGS_CONSIDERED)
+      return [] if siblings.empty?
+
+      siblings
+        .filter_map { |name| (count = downloads(name)) && [name, count] }
+        .max_by(limit) { |_name, count| count }
+        .map(&:first)
+    end
+
+    private
+
+    def downloads(gem_name)
+      info = Gems.info(gem_name)
+      info && info["downloads"]
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/helpers/bot_context.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module StillActive
+  # Best-effort detection of a Dependabot/Renovate-authored run, so --baseline
+  # reports can lead with a narrative ("Dependabot bump: rack 2.0.0 → 2.0.6")
+  # instead of an unattributed list. Detection is heuristic: false negatives are
+  # fine (we just lose the narrative), false positives are not, so the subject
+  # patterns are anchored and require the literal bump/update keyword.
+  module BotContext
+    extend self
+
+    # Dependabot's *default* subject is "Bump X from Y to Z" (capitalized, no
+    # prefix). The `from … to …` skeleton rarely occurs in human commits, so it
+    # is safe unprefixed. The conventional-commit prefix only appears when configured.
+    DEPENDABOT_SUBJECT = /\A(?:build\(deps(?:-dev)?\):\s*)?bump (\S+) from (\S+) to (\S+)/i
+
+    # Renovate's default is "Update dependency X to vN.…" — note the **required**
+    # `v`+digit version. Matching a bare "to <word>" would false-positive on ordinary
+    # commits ("Update README to mention SARIF"), so we anchor on the v-prefixed
+    # version. False negatives (a no-`v` Renovate config) are acceptable; false
+    # positives are not. The `v` is consumed, so the captured version excludes it.
+    RENOVATE_SUBJECT = /\A(?:(?:chore|fix|build)\(deps(?:-dev)?\):\s*)?update (?:dependency )?(\S+) to v(\d[\w.\-]*)/i
+
+    # Unanchored variants used only to EXTRACT the bump *after* a bot is already
+    # confirmed (via GITHUB_ACTOR / branch / the anchored subject above). Because
+    # detection has already happened, these can ignore whatever commit-message
+    # prefix or scope Dependabot/Renovate is configured with and just find the
+    # "bump X from Y to Z" / "update X to vN" skeleton anywhere in the subject.
+    DEPENDABOT_BUMP = /bump (\S+) from (\S+) to (\S+)/i
+    RENOVATE_BUMP = /update (?:dependency )?(\S+) to v(\d[\w.\-]*)/i
+
+    # Returns { bot: "dependabot" | "renovate", bumps: [{ gem:, from:, to: }] }
+    # or nil when no bot signal is present. `bumps` is parsed from the head
+    # commit subject; a grouped or unparseable subject yields an empty list.
+    def detect(env: ENV, head_subject: head_commit_subject)
+      bot = detect_bot(env: env, head_subject: head_subject)
+      return if bot.nil?
+
+      { bot: bot, bumps: bumps_from(bot, head_subject) }
+    end
+
+    # A one-line, format-agnostic narrative for the detected context.
+    def summary(context)
+      label = context[:bot] == "renovate" ? "Renovate" : "Dependabot"
+      bumps = context[:bumps]
+
+      case bumps.length
+      when 0 then "#{label} dependency update"
+      when 1 then single_bump_summary(label, bumps.first)
+      else "#{label}: #{bumps.length} dependency updates"
+      end
+    end
+
+    private
+
+    def detect_bot(env:, head_subject:)
+      # The PR author from the event payload is the authoritative signal — it's
+      # what `dependabot/fetch-metadata` keys on, and unlike GITHUB_ACTOR it
+      # doesn't flip to a human who re-runs the workflow or pushes to the branch.
+      login = pr_author_login(env)
+      return "dependabot" if login == "dependabot[bot]"
+      return "renovate" if login == "renovate[bot]"
+
+      actor = env["GITHUB_ACTOR"]
+      return "dependabot" if actor == "dependabot[bot]"
+      return "renovate" if actor == "renovate[bot]"
+
+      ref = env["GITHUB_HEAD_REF"] || current_branch
+      return "dependabot" if ref&.start_with?("dependabot/")
+      return "renovate" if ref&.start_with?("renovate/", "renovate-bot/")
+
+      return "dependabot" if head_subject&.match?(DEPENDABOT_SUBJECT)
+      return "renovate" if head_subject&.match?(RENOVATE_SUBJECT)
+
+      nil
+    end
+
+    # Reads pull_request.user.login from the GitHub Actions event payload
+    # (GITHUB_EVENT_PATH). Returns nil off Actions, on non-PR events, or if the
+    # file is missing/unreadable/malformed — all of which just fall through to
+    # the weaker signals. TypeError covers a payload that parses but has the
+    # wrong shape (e.g. a top-level array, or pull_request/user not a Hash);
+    # this method must never raise, since detect runs unguarded and a cosmetic
+    # narrative must not be able to abort the audit.
+    def pr_author_login(env)
+      path = env["GITHUB_EVENT_PATH"]
+      return if path.nil? || !File.file?(path)
+
+      JSON.parse(File.read(path)).dig("pull_request", "user", "login")
+    rescue JSON::ParserError, SystemCallError, TypeError
+      nil
+    end
+
+    def bumps_from(bot, subject)
+      return [] if subject.nil?
+
+      if bot == "dependabot" && (match = subject.match(DEPENDABOT_BUMP))
+        [{ gem: match[1], from: match[2], to: match[3] }]
+      elsif bot == "renovate" && (match = subject.match(RENOVATE_BUMP))
+        [{ gem: match[1], from: nil, to: match[2] }]
+      else
+        []
+      end
+    end
+
+    def single_bump_summary(label, bump)
+      arrow = bump[:from] ? "#{bump[:from]} → #{bump[:to]}" : "→ #{bump[:to]}"
+      verb = label == "Renovate" ? "update" : "bump"
+      "#{label} #{verb}: #{bump[:gem]} #{arrow}"
+    end
+
+    # SystemCallError (not just Errno::ENOENT) so a git that's missing *or*
+    # unlaunchable can't crash a run over a cosmetic narrative. git *logic*
+    # failures surface as a non-zero status, not an exception, and yield nil.
+    def current_branch
+      out, _, status = Open3.capture3("git", "rev-parse", "--abbrev-ref", "HEAD")
+      status.success? ? out.strip : nil
+    rescue SystemCallError
+      nil
+    end
+
+    def head_commit_subject
+      out, _, status = Open3.capture3("git", "log", "-1", "--pretty=%s")
+      status.success? ? out.strip : nil
+    rescue SystemCallError
+      nil
+    end
+  end
+end

data/lib/helpers/catalog_index.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "zlib"
+require "rubygems/package"
+require "yaml"
+require "json"
+require "open-uri"
+
+module StillActive
+  # Optional source of "alternative gem" leads: the rubytoolbox/catalog repo
+  # (MIT) mapped to gem -> co-category siblings. Fetched once and cached; every
+  # path is best-effort, returning nil/empty so a miss just means no leads.
+  module CatalogIndex
+    extend self
+
+    REPO = "rubytoolbox/catalog"
+    CACHE_TTL_SECONDS = 7 * 24 * 60 * 60
+    MAX_DOWNLOAD_BYTES = 25 * 1024 * 1024 # the catalog is ~50 KB; cap to avoid surprises
+
+    # Returns { gem => [siblings] } or nil. Never raises.
+    def load
+      cached = read_cache
+      return cached if cached
+
+      blob = download
+      index = build_index(blob)
+      write_cache(index)
+      index
+    rescue StandardError => e
+      warn("still_active: could not load Ruby Toolbox catalog for alternatives (#{e.class}); skipping leads")
+      nil
+    end
+
+    # Parse a gzipped catalog tarball into { gem_name => [sibling gem names] }.
+    def build_index(tar_gz_blob)
+      categories = []
+
+      reader = Gem::Package::TarReader.new(Zlib::GzipReader.new(StringIO.new(tar_gz_blob)))
+      reader.each do |entry|
+        next unless entry.file?
+        next unless entry.full_name.match?(%r{/catalog/.+\.ya?ml$})
+        next if File.basename(entry.full_name) == "_meta.yml"
+
+        data = YAML.safe_load(entry.read)
+        next unless data.is_a?(Hash) && data["projects"].is_a?(Array)
+
+        categories << data["projects"].map { |p| p.to_s.split("/").last }
+      end
+
+      build_siblings(categories)
+    end
+
+    private
+
+    def cache_path
+      base = ENV["XDG_CACHE_HOME"]
+      base = File.join(Dir.home, ".cache") if base.nil? || base.empty?
+      File.join(base, "still_active", "catalog-siblings.json")
+    end
+
+    def read_cache
+      path = cache_path
+      return unless File.exist?(path)
+      return if Time.now - File.mtime(path) > CACHE_TTL_SECONDS
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      nil
+    end
+
+    def write_cache(index)
+      path = cache_path
+      require "fileutils"
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.dump(index))
+    rescue SystemCallError
+      nil # an unwritable cache dir must not break the feature
+    end
+
+    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
+    end
+
+    def build_siblings(categories)
+      siblings = Hash.new { |h, k| h[k] = [] }
+
+      categories.each do |members|
+        members.each do |gem_name|
+          siblings[gem_name].concat(members - [gem_name])
+        end
+      end
+
+      siblings.transform_values(&:uniq)
+    end
+  end
+end