still_active 1.6.0 → 3.0.0.rc1

data/lib/still_active/ecosystem_lens.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require_relative "deps_dev_client"
+require_relative "osv_client"
+require_relative "ecosystems_client"
+require_relative "github_client"
+require_relative "pypi_client"
+require "time"
+require_relative "../helpers/activity_helper"
+require_relative "../helpers/constraint_helper"
+require_relative "../helpers/libyear_helper"
+require_relative "../helpers/pep440_helper"
+require_relative "../helpers/runtime_ceiling_helper"
+require_relative "../helpers/vulnerability_helper"
+
+module StillActive
+  # The cross-ecosystem maintenance lens. Given one SBOM-derived dependency
+  # ({ecosystem, name, version}), it assembles the same maintenance signals the
+  # native Ruby path produces -- latest release date, archived, advisories,
+  # scorecard -- into a gem_data hash StatusHelper.gem_status can read directly.
+  # The breadth counterpart to the depth Bundler path gives Ruby.
+  #
+  # Security: the SBOM supplies only ecosystem/name/version. The repository is
+  # discovered from deps.dev (a public source still_active opts into), never from
+  # a lockfile-derived URL, so a hostile SBOM can't redirect a lookup. Anything
+  # unresolvable (a private package deps.dev doesn't index) degrades to nil
+  # signals -> :unknown, never a fabricated "ok".
+  module EcosystemLens
+    extend self
+
+    # still_active ecosystem symbol -> ecosyste.ms registry name for the declared
+    # dependency (poison-pill) lookup. Only the ecosystems where the ecosyste.ms
+    # registry name and the deps.dev package name align cleanly are wired; maven
+    # (group:artifact) and go (module paths) need name-format handling and are
+    # left out for now, so they simply carry no constraint signal rather than a
+    # wrong one.
+    ECOSYSTEM_REGISTRIES = {
+      rubygems: "rubygems.org",
+      npm: "npmjs.org",
+      pypi: "pypi.org",
+      cargo: "crates.io",
+    }.freeze
+
+    # A transitive cap only holds the WHOLE tree hostage where the ecosystem
+    # forces one version per package. Ruby/Bundler and pip do (flat resolution);
+    # npm nests multiple versions and cargo coexists majors, so a below-latest cap
+    # there pins a duplicate copy in one subtree -- not a tree-wide block. The one
+    # npm case that DOES block (peerDependencies / de-facto singletons) isn't
+    # visible in ecosyste.ms data (its parser drops peerDependencies), so emitting
+    # poison for npm/cargo would over-claim on the non-blocking cases and miss the
+    # blocking ones. Suppress it there until peer requirements are sourced from
+    # deps.dev; silence beats a false "holds your tree hostage".
+    FLAT_RESOLUTION_ECOSYSTEMS = [:rubygems, :pypi].freeze
+
+    def assess(ecosystem:, name:, version:, constraint_cache: {}, python_range: nil)
+      info = DepsDevClient.version_info(gem_name: name, version: version, system: ecosystem)
+      default = DepsDevClient.default_version_info(name: name, system: ecosystem)
+      # Retry the version lookup once when it came back empty but the package DID
+      # resolve: HttpHelper collapses a genuine 404 and a transient network blip to
+      # the same nil, and a healthy version must not be mis-flagged as unresolved
+      # (below) on a one-off miss. A real 404 stays nil; a blip recovers the data.
+      info ||= DepsDevClient.version_info(gem_name: name, version: version, system: ecosystem) if default
+      # Recover the repo from the default version when the exact locked version
+      # isn't indexed (yanked/normalization mismatch): otherwise its project link
+      # vanishes and a still-fresh package date would read a false :ok with
+      # archived/scorecard silently dropped. The native Bundler path resolves the
+      # repo independently of deps.dev's per-version record; this gives the lens
+      # the same resilience.
+      # The pinned version isn't indexed by deps.dev (info nil) while the package IS
+      # (default present, so the feed is up): the version is yanked/nonexistent, not a
+      # transient miss. Flag it so status reads :unknown rather than letting the still-
+      # fresh PACKAGE date report a nonexistent version as :ok.
+      version_unresolved = info.nil? && !default.nil?
+      project_id = info&.dig(:project_id) || project_id_from(name, ecosystem, default)
+      vulnerabilities = vulnerabilities_for(info)
+      # Enrich with OSV: a real GHSA severity label (deps.dev can't score a CVSS-4-only
+      # advisory) and the fixed-version ranges the "capped below the fix" signal needs.
+      OsvClient.enrich(vulnerabilities, ecosystem: ecosystem, name: name)
+      scorecard = DepsDevClient.project_scorecard(project_id: project_id)
+      repo = repo_signals(project_id)
+
+      used_release_date = info&.dig(:published_at)
+      latest_release_date = default&.dig(:published_at)
+      latest_version = default&.dig(:version)
+      gem_data = {
+        ecosystem: ecosystem,
+        name: name,
+        version_used: version,
+        version_used_release_date: used_release_date,
+        latest_version_release_date: latest_release_date,
+        # libyear parity with the native path: how far behind latest the locked
+        # version is, in release-years. Both dates come from deps.dev responses
+        # already fetched above (no extra call); nil when either date is missing.
+        libyear: LibyearHelper.gem_libyear(
+          version_used_release_date: parse_time(used_release_date),
+          latest_version_release_date: parse_time(latest_release_date),
+        ),
+        # Whether the pinned version is at or ahead of deps.dev's latest stable, so a
+        # prerelease or an ahead-of-stable pin reads current (true), not "behind" --
+        # parity with the native path's `>=` comparison. nil when latest is unknown.
+        up_to_date: version_current?(version, latest_version),
+        repository_url: project_id && "https://#{project_id}",
+        last_commit_date: repo[:last_commit_date],
+        archived: repo[:archived],
+        scorecard_score: scorecard&.dig(:score),
+        scorecard_maintained: scorecard&.dig(:maintained),
+        vulnerability_count: vulnerabilities.length,
+        vulnerabilities: vulnerabilities,
+      }
+      gem_data[:version_unresolved] = true if version_unresolved
+      attach_constraints(gem_data, ecosystem: ecosystem, name: name, version: version, cache: constraint_cache)
+      attach_language_ceiling(gem_data, ecosystem: ecosystem, name: name, version: version, latest_version: default&.dig(:version), python_range: python_range)
+      gem_data
+    end
+
+    private
+
+    # Language-runtime ceiling for the cross-ecosystem path, the sibling of the
+    # native Ruby ceiling in Workflow. Python declares its runtime constraint as a
+    # PEP 440 `requires_python`, an enforced pip install wall; translate it and run
+    # the same generic RuntimeCeilingHelper against Python's support window. Unlike
+    # poison this is NOT gated on dormancy (a cap is a fact of the resolved version
+    # whether or not the package is maintained), so it costs one PyPI read per
+    # pypi package; other ecosystems carry no ceiling here rather than a wrong one
+    # (cargo's rust_version is a soft MSRV hint, not an install wall). Best-effort:
+    # a nil range (endoflife feed down) or absent requires_python yields nothing.
+    def attach_language_ceiling(gem_data, ecosystem:, name:, version:, latest_version:, python_range:)
+      return if python_range.nil?
+      return unless ecosystem == :pypi
+
+      requirement = Pep440Helper.to_gem_requirement_string(PypiClient.requires_python(name: name, version: version))
+      finding = requirement && RuntimeCeilingHelper.analyze(requirement: requirement, support_window: python_range)
+      return if finding.nil?
+
+      finding[:runtime] = "Python"
+      finding[:fixed_by_upgrade] = python_ceiling_lifted_by_upgrade?(name: name, version: version, latest_version: latest_version, python_range: python_range)
+      gem_data[:language_ceiling] = finding
+    end
+
+    # Does upgrading the package to its latest release lift the cap? Requires
+    # POSITIVE confirmation, unlike the native ruby_ceiling_lifted_by_upgrade?
+    # whose latest requirement is read from data already in hand. Here the latest
+    # requires_python is a fresh PyPI read, and PypiClient returns nil for BOTH
+    # "declares no constraint" AND "the fetch failed" -- indistinguishable. Reading
+    # that nil as "no ceiling, safe to bump" would fabricate remediation on a
+    # transient PyPI error, the exact over-claim this tool must never make. So a
+    # nil specifier yields false (we don't advise an upgrade we couldn't verify);
+    # only a readable constraint that analyze confirms is non-capping lifts it.
+    def python_ceiling_lifted_by_upgrade?(name:, version:, latest_version:, python_range:)
+      return false if latest_version.nil? || latest_version == version
+
+      latest_specifier = PypiClient.requires_python(name: name, version: latest_version)
+      return false if latest_specifier.nil?
+
+      latest_requirement = Pep440Helper.to_gem_requirement_string(latest_specifier)
+      RuntimeCeilingHelper.analyze(requirement: latest_requirement, support_window: python_range).nil?
+    end
+
+    # Constraint enrichment for the cross-ecosystem path, gated on dormancy so a
+    # maintained package is never flagged. Two shapes by ecosystem:
+    #
+    # FLAT (rubygems/pypi): the poison-pill signal as-is -- a below-latest cap holds
+    # the whole tree hostage, so it renders directly (`constraints` + `poison`).
+    #
+    # NESTED (npm/cargo): the pure below-latest cap is subtree-local noise (nested
+    # copies, caret default), so no poison here. Instead keep every declared dep as a
+    # security CANDIDATE (`capped_deps`); the correlator, which alone sees the tree's
+    # resolved versions and advisories, promotes only the ones that pin a vulnerable
+    # copy below its fix. Candidates are NOT filtered to below-latest-major (npm/cargo
+    # fixes are mostly same-major patch bumps that filter would miss) and need no
+    # dep_latest fetch (the wall test is patch-precise on the requirement itself).
+    def attach_constraints(gem_data, ecosystem:, name:, version:, cache:)
+      registry = ECOSYSTEM_REGISTRIES[ecosystem]
+      return if registry.nil?
+      return unless [:critical, :archived].include?(ActivityHelper.activity_level(gem_data))
+
+      declared = EcosystemsClient.declared_dependencies(name: name, version: version, registry: registry)
+      if FLAT_RESOLUTION_ECOSYSTEMS.include?(ecosystem)
+        attach_flat_poison(gem_data, ecosystem, declared, cache)
+      else
+        attach_nested_candidates(gem_data, declared)
+      end
+    end
+
+    def attach_flat_poison(gem_data, ecosystem, declared, cache)
+      findings = ConstraintHelper.poison_findings(declared) do |dep_name|
+        latest_version_for(ecosystem, dep_name, cache)
+      end
+      return if findings.empty?
+
+      gem_data[:constraints] = findings
+      gem_data[:poison] = findings.any? { |finding| finding[:kind] == :ceiling }
+      gem_data[:poison_severity] = ConstraintHelper.worst_severity(findings) if gem_data[:poison]
+    end
+
+    def attach_nested_candidates(gem_data, declared)
+      candidates = declared.filter_map do |dep|
+        next if dep[:package_name].to_s.empty? || dep[:requirements].to_s.empty?
+
+        { dependency: dep[:package_name], requirement: dep[:requirements] }
+      end
+      gem_data[:capped_deps] = candidates unless candidates.empty?
+    end
+
+    # A capped dep's current latest version in `ecosystem`, via deps.dev's default
+    # (latest stable) version. Memoized per run, keyed by ecosystem+name so an npm
+    # `foo` and a pypi `foo` never collide. Only a RESOLVED version is cached: a
+    # nil can mean "genuinely unindexed" or "deps.dev was momentarily down / rate-
+    # limited" (both surface as nil here), and caching the transient case would
+    # suppress the pill for every later dormant package capping the same dep. So an
+    # unresolved dep is re-attempted rather than remembered as a permanent miss.
+    def latest_version_for(ecosystem, dep_name, cache)
+      key = "#{ecosystem}/#{dep_name}"
+      cache[key] ||= DepsDevClient.default_version_info(name: dep_name, system: ecosystem)&.dig(:version)
+    end
+
+    def vulnerabilities_for(info)
+      advisory_keys = info&.dig(:advisory_keys) || []
+      # The keys ARE the evidence the locked version is vulnerable; the detail
+      # fetch only enriches CVSS/title. A failed enrichment must not drop the
+      # count to zero and read a known-vulnerable dep as clean, so a key whose
+      # detail can't be loaded still contributes a minimal advisory.
+      deps_dev = advisory_keys.map { DepsDevClient.advisory_detail(advisory_id: _1) || { id: _1, source: "deps.dev" } }
+      # No ruby-advisory-db here: that database is Ruby-only and the native
+      # Bundler path already merges it. Cross-ecosystem advisories come from
+      # deps.dev/OSV, which covers every system the lens serves.
+      VulnerabilityHelper.merge_advisories(deps_dev: deps_dev, ruby_advisory_db: [])
+    end
+
+    # The repo project_id from the package's default version, used only when the
+    # locked version's deps.dev record is missing or carries no link.
+    def project_id_from(name, ecosystem, default)
+      version = default&.dig(:version)
+      return if version.nil?
+
+      DepsDevClient.version_info(gem_name: name, version: version, system: ecosystem)&.dig(:project_id)
+    end
+
+    # archived + last-commit for a flat github.com/owner/repo project, or {} for
+    # anything else. deps.dev indexes github.com and gitlab.com only, but gitlab
+    # subgroups nest arbitrarily and ecosyste.ms's repo crawler is GitHub-centric,
+    # so a gitlab (or nested, or unresolved) project keeps archived unknown rather
+    # than risk a bogus owner/name lookup.
+    def repo_signals(project_id)
+      host, owner, name, *rest = project_id.to_s.split("/")
+      return {} unless host == "github.com" && owner && name && rest.empty?
+
+      repo_provider.repo_signals(owner: owner, name: name) || {}
+    end
+
+    # Mirrors Workflow#provider_for(:github): the live GitHub API when a token is
+    # configured (freshest), else ecosyste.ms (5000 anonymous req/hr vs GitHub's
+    # 60), so an untokened cross-ecosystem run still resolves a large SBOM.
+    def repo_provider
+      StillActive.config.github_oauth_token ? GithubClient : EcosystemsClient
+    end
+
+    # Is the pinned version at or ahead of latest stable? nil when latest is unknown.
+    # Gem::Version handles semver prereleases (`16.3.0-canary.7` sorts as a prerelease
+    # of 16.3.0, so ahead of a 16.2.x stable -> current), so a beta/ahead pin reads
+    # true, not "behind". Versions Gem::Version can't parse (pypi epoch `1!2.3`, build
+    # metadata, a `v` prefix) fall back to exact match -- ahead reads false there, the
+    # safe direction, and libyear still carries the real magnitude.
+    def version_current?(version, latest)
+      return false if latest.nil?
+      return version == latest unless Gem::Version.correct?(version) && Gem::Version.correct?(latest)
+
+      Gem::Version.new(version) >= Gem::Version.new(latest)
+    end
+
+    # deps.dev renders dates as ISO8601 strings; libyear needs Time to subtract.
+    # nil-safe, and a malformed value degrades to nil rather than raising.
+    def parse_time(value)
+      # Guard the type, not just nil: a non-String publishedAt (schema drift) would
+      # make Time.parse raise TypeError (unrescued) and, since this enrichment runs
+      # in assess, demote an otherwise-healthy package. Best-effort must degrade.
+      return unless value.is_a?(String)
+
+      Time.parse(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/still_active/ecosystems_client.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../helpers/http_helper"
+require_relative "version"
+
+module StillActive
+  # Tokenless repo signals (archived?, last-commit date) for github.com-hosted
+  # gems, sourced from ecosyste.ms instead of the GitHub API. Used as the
+  # fallback when no GitHub token is configured, so an unauthenticated run isn't
+  # capped at GitHub's 60 req/hr (ecosyste.ms allows 5000 anonymous) -- the
+  # difference between "works on a large Gemfile" and "dies after a handful".
+  #
+  # GitHub-only by design: ecosyste.ms's repos service doesn't populate commit
+  # recency for GitLab/Codeberg (its repo crawler is GitHub-centric), so those
+  # hosts keep their own live clients.
+  #
+  # Data is CC-BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0/);
+  # still_active queries it live (no redistribution) and attributes ecosyste.ms
+  # in the README data sources.
+  module EcosystemsClient
+    extend self
+
+    BASE_URI = URI("https://repos.ecosyste.ms/")
+    # The packages service is a distinct host from the repos service above; it
+    # carries per-version declared dependency constraints (the poison-pill input).
+    PACKAGES_BASE_URI = URI("https://packages.ecosyste.ms/")
+    # ecosyste.ms asks consumers to identify themselves for its "polite pool".
+    USER_AGENT = "still_active/#{StillActive::VERSION} (+https://github.com/SeanLF/still_active)"
+
+    # archived + last-commit date from a single repository call. ecosyste.ms's
+    # pushed_at mirrors GitHub's, so this returns the same shape as GithubClient.
+    # Returns {} when the repo can't be read, so the caller leaves both blank.
+    def repo_signals(owner:, name:)
+      return {} if owner.nil? || name.nil?
+
+      path = "/api/v1/hosts/GitHub/repositories/#{encode_repo(owner, name)}"
+      body = HttpHelper.get_json(BASE_URI, path, headers: { "User-Agent" => USER_AGENT }, params: politeness_params)
+      # A non-Hash 200 body (error envelope rendered as an array, schema drift)
+      # would otherwise raise on indexing and vanish the gem from the audit via
+      # the workflow's rescue; degrade to "no signal" like any other read failure.
+      return {} unless body.is_a?(Hash)
+
+      signals = { last_commit_date: parse_time(body["pushed_at"], owner, name) }
+      # Only assert archived when the field is actually present. A missing field
+      # must read as unknown, not be invented as false -- otherwise a partial
+      # crawl could silently mask the most actionable verdict (gem is archived).
+      signals[:archived] = body["archived"] == true if body.key?("archived")
+      signals
+    end
+
+    # ecosyste.ms dependency-kind labels that ship at RUNTIME (so a cap on one
+    # holds the consumer's tree hostage). It is registry-specific vocabulary:
+    # rubygems/npm/pypi say "runtime", but cargo says "normal" (its "dev"/"build"
+    # kinds are excluded). An ALLOWLIST, not a denylist: an unrecognised kind is
+    # dropped rather than risk flagging a dev/build dep and breaking the FP
+    # discipline. Compared case-insensitively (rubygems's dev kind is
+    # "Development").
+    RUNTIME_KINDS = ["runtime", "normal"].freeze
+
+    # The runtime dependency constraints a package version declares: an array of
+    # { package_name:, requirements: } for runtime-shipped deps only (see
+    # RUNTIME_KINDS). Dev/build/test deps are dropped -- they don't cap the
+    # consumer's tree, so they can't be a poison-pill. `requirements` is the raw
+    # constraint string ("< 5.0, >= 4.0.1") ConstraintHelper reads. `registry` is
+    # the ecosyste.ms registry name (rubygems.org, pypi.org, npmjs.org,
+    # crates.io), defaulting to Ruby.
+    #
+    # Returns [] whenever the version can't be read (unindexed, 404, timeout,
+    # schema drift), so a caller degrades to "no constraints known" rather than
+    # crashing the per-gem audit.
+    def declared_dependencies(name:, version:, registry: "rubygems.org")
+      return [] if name.nil? || version.nil?
+
+      path = "/api/v1/registries/#{encode(registry)}/packages/#{encode(name)}/versions/#{encode(version)}"
+      body = HttpHelper.get_json(PACKAGES_BASE_URI, path, headers: { "User-Agent" => USER_AGENT }, params: politeness_params)
+      return [] unless body.is_a?(Hash)
+
+      dependencies = body["dependencies"]
+      return [] unless dependencies.is_a?(Array)
+
+      dependencies.filter_map do |dep|
+        next unless dep.is_a?(Hash) && RUNTIME_KINDS.include?(dep["kind"].to_s.downcase)
+
+        package_name = dep["package_name"]
+        requirements = dep["requirements"]
+        next if package_name.nil? || requirements.nil?
+
+        { package_name: package_name, requirements: requirements }
+      end
+    end
+
+    private
+
+    # ecosyste.ms raises the rate limit and prioritises requests that identify a
+    # contact via a mailto query param (its "polite pool"). Opt-in: empty unless
+    # the user configures an email, since anonymous already suffices for a typical
+    # lockfile and we don't attribute every user's traffic to one address.
+    def politeness_params
+      email = StillActive.config.ecosystems_email
+      email ? { mailto: email } : {}
+    end
+
+    # nil or a non-string (numeric/array from an off-spec payload) -> no date,
+    # never a crash; only an unparseable string is worth warning about.
+    def parse_time(value, owner, name)
+      return unless value.is_a?(String)
+
+      Time.parse(value)
+    rescue ArgumentError
+      $stderr.puts("warning: could not parse repo date for #{owner}/#{name}: #{value.inspect}")
+      nil
+    end
+
+    def encode_repo(owner, name)
+      URI.encode_www_form_component("#{owner}/#{name}")
+    end
+
+    def encode(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+  end
+end

data/lib/still_active/forgejo_client.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../helpers/http_helper"
+
+module StillActive
+  # Repo signals (archived?, last commit date) for Forgejo/Gitea-hosted gems.
+  # Codeberg.org is the only host wired into the workflow today, but every
+  # Forgejo/Gitea instance speaks the same `/api/v1` surface, so the host is a
+  # parameter for later self-hosted support. Mirrors GitlabClient: HttpHelper
+  # against a documented JSON API, anonymous by default with an optional token.
+  module ForgejoClient
+    extend self
+
+    DEFAULT_HOST = "codeberg.org"
+
+    # archived + last-activity date from a single repository call. The repo
+    # object's updated_at matches the latest commit date to the day in practice,
+    # so folding the two signals into one call halves the per-gem requests.
+    # Returns {} when the repo can't be read.
+    def repo_signals(owner:, name:, host: DEFAULT_HOST)
+      return {} if owner.nil? || name.nil?
+
+      body = HttpHelper.get_json(base_uri(host), "/api/v1/repos/#{owner}/#{name}", headers: auth_headers)
+      return {} if body.nil?
+
+      { archived: body["archived"] == true, last_commit_date: parse_time(body["updated_at"], owner, name) }
+    end
+
+    private
+
+    def parse_time(value, owner, name)
+      return if value.nil?
+
+      Time.parse(value)
+    rescue ArgumentError
+      $stderr.puts("warning: could not parse repo date for #{owner}/#{name}: #{value.inspect}")
+      nil
+    end
+
+    def base_uri(host)
+      URI("https://#{host}/")
+    end
+
+    def auth_headers
+      token = StillActive.config.forgejo_token
+      token ? { "Authorization" => "token #{token}" } : {}
+    end
+  end
+end

data/lib/still_active/github_client.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "time"
+require "octokit"
+
+module StillActive
+  # Repo signals (archived?, last commit date) for github.com-hosted gems.
+  # Wraps Octokit so the rest of the workflow dispatches to a provider with the
+  # same shape as GitlabClient, rather than reaching into Octokit inline. The
+  # Octokit dependency stays internal to this module.
+  module GithubClient
+    extend self
+
+    # A rate-limit response whose reset is at most this many seconds away is
+    # waited out and retried; a longer wait (hourly-limit exhaustion) is not
+    # auto-taken and falls through to the caller's rescue (warn + nil).
+    MAX_RATE_LIMIT_WAIT = 60
+
+    # archived + last-activity date from a single repository call. The repo
+    # object's pushed_at (last push) stands in for the last-commit date: it
+    # matches the default-branch commit date to the day in practice, and folding
+    # the two signals into one call halves the per-gem GitHub requests. Returns
+    # {} when the repo can't be read, so the caller leaves both signals blank.
+    def repo_signals(owner:, name:)
+      return {} if owner.nil? || name.nil?
+
+      repo = with_rate_limit_retry("repo #{owner}/#{name}") do
+        StillActive.config.github_client.repository("#{owner}/#{name}")
+      end
+      return {} unless repo
+
+      { archived: repo.archived, last_commit_date: as_time(repo.pushed_at, owner, name) }
+    rescue Octokit::Error, Faraday::Error => e
+      $stderr.puts("warning: repo signals failed for #{owner}/#{name}: #{e.class}")
+      {}
+    end
+
+    # Commits on the default branch since the latest release's tag: the
+    # "unreleased work" signal. GitHub's compare endpoint returns ahead_by as a
+    # single scalar, so this is one cheap call. The git tag name isn't carried
+    # by RubyGems, so resolve it from the version by trying the two ubiquitous
+    # forms (v7.0.1, 7.0.1) as the compare base; a wrong form 404s and we try
+    # the next. Returns nil when neither resolves (non-tagging repo, monorepo
+    # tag scheme we don't guess). Only GithubClient implements this; the
+    # workflow dispatches by respond_to?, so GitLab/Forgejo simply don't.
+    def commits_since_release(owner:, name:, version:)
+      return if owner.nil? || name.nil? || version.nil?
+
+      repo = "#{owner}/#{name}"
+      ["v#{version}", version.to_s].each do |tag|
+        return with_rate_limit_retry("unreleased-commits #{repo}") { StillActive.config.github_client.compare(repo, tag, "HEAD").ahead_by }
+      rescue Octokit::NotFound
+        # this tag form doesn't exist; fall through to try the next one
+      end
+      nil
+    rescue Octokit::Error, Faraday::Error => e
+      $stderr.puts("warning: unreleased-commits check failed for #{owner}/#{name}: #{e.class}")
+      nil
+    end
+
+    private
+
+    # Pause-and-retry on a rate-limit response when the reset is near, so a
+    # transient secondary/burst limit (which GitHub's concurrent fan-out can
+    # trip even with a token) self-heals instead of dropping the gem's signal.
+    # Retries at most once. Under the async reactor, sleep yields to other
+    # fibers rather than blocking the thread.
+    def with_rate_limit_retry(label)
+      retried = false
+      begin
+        yield
+      rescue Octokit::TooManyRequests => e
+        wait = rate_limit_wait(e)
+        if retried || wait.nil? || wait > MAX_RATE_LIMIT_WAIT
+          # Hourly-limit exhaustion (or a far reset): not worth auto-waiting.
+          # Surface the one actionable hint rather than a generic class name,
+          # then return nil so this signal is simply absent for the gem.
+          $stderr.puts("rate limited on #{label}; set GITHUB_TOKEN to raise your limit, or run less often")
+          return
+        end
+
+        retried = true
+        $stderr.puts("rate limited on #{label}; waiting #{wait}s for reset")
+        sleep(wait)
+        retry
+      end
+    end
+
+    # Seconds to wait before retrying, from the Retry-After header (secondary
+    # limits) or x-ratelimit-reset (primary), or nil when neither is present.
+    def rate_limit_wait(error)
+      # Octokit normalises response headers to lowercase (Faraday is
+      # case-insensitive), so a single lowercase lookup covers any casing.
+      headers = response_headers(error)
+      return if headers.nil? || headers.empty?
+
+      if (retry_after = headers["retry-after"])
+        return retry_after.to_i
+      end
+
+      reset = headers["x-ratelimit-reset"]
+      return if reset.nil?
+
+      [reset.to_i - Time.now.to_i, 0].max
+    end
+
+    # Octokit raises NoMethodError reading headers off an error with no response
+    # attached; treat only that as "can't tell" so the limiter degrades to no
+    # wait, while a real NoMethodError elsewhere still surfaces.
+    def response_headers(error)
+      error.response_headers
+    rescue NoMethodError
+      nil
+    end
+
+    def as_time(value, owner, name)
+      return value if value.is_a?(Time)
+      return if value.nil?
+
+      Time.parse(value)
+    rescue ArgumentError
+      $stderr.puts("warning: could not parse repo date for #{owner}/#{name}: #{value.inspect}")
+      nil
+    end
+  end
+end

data/lib/still_active/gitlab_client.rb

@@ -9,36 +9,31 @@ module StillActive
 
     BASE_URI = URI("https://gitlab.com/")
 
-    def archived(owner:, name:)
-      return if owner.nil? || name.nil?
+    # archived + last-activity date from a single project call. The project
+    # object's last_activity_at matches the latest commit date to the day in
+    # practice, so folding the two signals into one call halves the per-gem
+    # requests. Returns {} when the project can't be read.
+    def repo_signals(owner:, name:)
+      return {} if owner.nil? || name.nil?
 
       path = "/api/v4/projects/#{encode_project(owner, name)}"
       body = HttpHelper.get_json(BASE_URI, path, headers: auth_headers)
-      return if body.nil?
+      return {} if body.nil?
 
-      body["archived"] == true
+      { archived: body["archived"] == true, last_commit_date: parse_time(body["last_activity_at"], owner, name) }
     end
 
-    def last_commit_date(owner:, name:)
-      return if owner.nil? || name.nil?
-
-      path = "/api/v4/projects/#{encode_project(owner, name)}/repository/commits"
-      body = HttpHelper.get_json(BASE_URI, path, headers: auth_headers, params: { per_page: 1 })
-      return if body.nil? || body.empty?
+    private
 
-      date = body.first["committed_date"]
-      return unless date
+    def parse_time(value, owner, name)
+      return if value.nil?
 
-      begin
-        Time.parse(date)
-      rescue ArgumentError
-        $stderr.puts("warning: could not parse commit date for #{owner}/#{name}: #{date.inspect}")
-        nil
-      end
+      Time.parse(value)
+    rescue ArgumentError
+      $stderr.puts("warning: could not parse repo date for #{owner}/#{name}: #{value.inspect}")
+      nil
     end
 
-    private
-
     def auth_headers
       token = StillActive.config.gitlab_token
       token ? { "PRIVATE-TOKEN" => token } : {}