still_active 1.6.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e5e5e599cdd630ec6e916800c4abd7df4a3c9d37e24122e80d8859accb1c4e3
-  data.tar.gz: 0cb0dfd2c761612f665a9d2f4e0ba20f47bf8b082c42281af09b8429335aa2a9
+  metadata.gz: 1db517014109d081c46e71d63cf61d4446d60f7c7205793c520293f6cc03e329
+  data.tar.gz: 5239b26426cb8a8359c3efbafb1aaf3480150bf6a190a0912cc1f78d4ca0e226
 SHA512:
-  metadata.gz: 571797c9863bf6597e7c9474e8cf718019925d37d163002e9d594b137458ca0a6be155dfb7a5069777afe83963fb4dc595026a69c8237ce1aa7d024eb254be99
-  data.tar.gz: 4e7ba6a7777973b6fe7f1fa54fc1fad00a06639da18944f0bc89befd6a3e794b1d55eeaca62f33b193bebb54cdb2d6d85c63ae48a73adc722e58a3f194c0aeae
+  metadata.gz: 49f561e7ea5a5e0de227e5c861cd4b1ef2bcca57ad967712e5411fd25ea00cea49ee07801f3b4b6be7dc205259c8f2e3c36481ec5148fa52849a8246070beb62
+  data.tar.gz: 5552c0f3c9ba60c3e9046372923f4fa3aee2b2152e5eea6765f99f0c14fdf7785798df477605e04c11a7ac5f6bb2fec06dbc1f0ece3e46b1ee91aaa341cc2ae7

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [Unreleased]
+
+### Upgrading to 2.0
+
+2.0 is a major bump because two changes can alter `--fail-if-*` outcomes on upgrade (the CLI flags and JSON `schema_version` are otherwise backward-compatible):
+
+- **Transitive by default.** Maintenance signals now cover the full resolved lockfile, so a CI gate can newly fail on a transitive critical/vulnerable/outdated gem. Add `--direct-only` to restore the pre-2.0 declared-deps scope.
+- **Activity recalibration.** The "ok" ceiling moved 12 → 18 months and the level is release-driven, so some gems are reclassified. Tune with `--safe-range-end` / `--warning-range-end`.
+- **Baselines:** re-capture your `--baseline` JSON after upgrading. The transitive expansion shows the new gems as additions (and any unhealthy transitive deps as regressions) on the first run.
+
+### Added
+
+- The `--json` output is now a **versioned, contract-tested machine schema** ([`docs/still_active.schema.json`](docs/still_active.schema.json), JSON Schema 2020-12), carried as a `$schema` URL so the output is self-describing, and it gains a `summary{}` digest, the audit's headline posture (total / direct / transitive, the activity-level breakdown, archived / up-to-date / outdated counts, and vulnerability totals) in one object so a machine or LLM consumer reads it without iterating every gem. The terminal summary line now derives from the same digest, so the human and machine summaries can't drift. Unlike SARIF (findings-only) and CycloneDX (SBOM-only), this is the complete correlation-layer view. (#33)
+- Maintenance signals (stale releases, archived repos, last-commit age, advisories, libyear) now cover the **full transitive lockfile graph** by default, not just declared dependencies, matching libyear-bundler and the CVE scanners still_active composes with. Each gem carries `direct: true|false`, and a flagged transitive gem carries a `dependency_path` back to the direct dependency that pulls it in (e.g. `["rails", "actionpack", "rack"]`), turning an un-actionable transitive finding into an actionable "replace your direct gem" in terminal, markdown, JSON, and SARIF output. `--alternatives` stays **direct-only** by design (you can't swap a gem you didn't choose). `--direct-only` opts back to the previous declared-deps-only scope. Because this multiplies the number of repo/version lookups, prefer running on a schedule rather than per-commit (see the README). (#60)
+- A committed `.still_active.yml` config file, with granular finding-level suppression replacing the all-or-nothing `--ignore`. `--ignore=GEM` drops a gem from every gate at once, so accepting one unfixable advisory also hid that gem going archived or getting a *new* CVE. The file's `ignore:` block keys suppressions by advisory id and/or signal (`activity` / `vulnerability` / `libyear`), each with an optional `reason` and `expires` date. A vulnerability suppression must name an explicit advisory id, so a newly disclosed CVE on the same gem still fails; a lapsed `expires:` makes the finding re-surface as a normal failure (Trivy-style) rather than rotting silently, and a suppression that names a gem not in your dependency graph (a typo, or a gem you've since removed) is reported as a warning, so dead entries surface instead of lingering. The file also mirrors the policy flags (gates, thresholds, `output`, `alternatives`, `unreleased_commits`, `direct_only`) with precedence CLI flag > env var > config file > default, and an `import: [.bundler-audit.yml]` opt-in folds bundler-audit's accepted-advisory list in so teams keep one ignore list. Secrets (tokens) and invocation-specific paths are deliberately not read from the file, so a committed config never carries a credential. Suppressed findings still appear in JSON/terminal/markdown output and are marked in SARIF as native `suppressions[]` entries (with the reason as justification), so GitHub Code Scanning renders them dismissed rather than open. (#46)
+- `--unreleased-commits` adds an `unreleased_commits` count per gem: commits on the default branch since the latest release's tag, the "unreleased work" signal no Ruby tool surfaces today (only GitHub's UI shows it). It distinguishes a gem that looks stale but is genuinely done (no unreleased work) from one with a recent release but a pile of merged-but-unreleased fixes. Opt-in and GitHub-only: it adds one API call per GitHub-hosted gem (the tag is resolved from the RubyGems version, trying `v1.2.3` then `1.2.3`), non-GitHub sources report `null` (the signal is duck-typed via `respond_to?`, no base-class interface), and it is purely informational, never gating a run. Inflated for monorepos and release-branch projects, so it is documented as a lead, not a verdict. (#32)
+- Forgejo/Codeberg repos are now a recognised source for the archived and last-commit signals, alongside GitHub and GitLab. A gem whose canonical `source_code_uri` points at `codeberg.org` previously fell through to no repo signals at all; it now resolves through a new `ForgejoClient` (the Gitea `/api/v1` surface every Forgejo/Gitea instance shares), so the host is a parameter for later self-hosted support. Reads are anonymous by default; `STILL_ACTIVE_FORGEJO_TOKEN`/`CODEBERG_TOKEN` only raise the rate limit or reach private repos. Codeberg-hosted repos are correctly left out of deps.dev OpenSSF Scorecard lookups (deps.dev indexes only github.com/gitlab.com) rather than minting a bogus `github.com/owner/name` project id. (#31)
+- JSON output now includes a derived `activity_level` per gem (`"ok"`, `"stale"`, `"critical"`, `"archived"`, or `"unknown"`), so a machine or LLM consumer reads still_active's maintenance verdict directly instead of re-deriving it from the raw dates. Documented in `docs/schema.md`. (#33)
+- JFrog Artifactory gem registry support: fetches versions from `.jfrog.io` RubyGems-compatible registries via the versions API with an AQL search fallback. Auth reuses Bundler's per-source credentials when present, otherwise a global token via `--artifactory-token` or `STILL_ACTIVE_ARTIFACTORY_TOKEN` (requires a matching `--artifactory-host` / `STILL_ACTIVE_ARTIFACTORY_HOST`).
+
+### Changed
+
+- Per-gem date fields in `--json` (`last_commit_date` and the `*_release_date` fields) are now ISO8601 UTC (e.g. `2026-01-02T01:04:05Z`), matching `generated_at`, and the published schema marks them `date-time`. They were previously serialized in Ruby's default `Time` format in the machine's local timezone (`2026-01-02 03:04:05 +0200`), so a consumer parsing them got an inconsistent, machine-dependent value. Consumers that parsed those fields should re-check their date handling.
+- A gem's `archived` flag and last-activity date now come from a **single repository call per gem instead of two**, halving the repo-signal API requests (and easing the rate limit on the full-transitive audits of #60). The repo object already carries both the archived flag and a last-activity timestamp (GitHub `pushed_at`, GitLab `last_activity_at`, Forgejo `updated_at`), so the separate "latest commit" call was redundant: across 11 GitHub repos plus GitLab and Forgejo checks, that timestamp matched the default-branch commit date **to the day**. `last_commit_date` is now that repo last-activity timestamp; it tracks the last commit in practice and, since the activity verdict is release-driven (#32), this doesn't change classifications. (#35)
+- A GitHub rate-limit response is now waited out and retried once when its reset is near (at most 60 seconds away), instead of silently dropping that gem's repo signals. GitHub's concurrent fan-out can trip the secondary/burst limit even with a token, especially now that the full transitive graph is audited (#60); honouring the `Retry-After` / `x-ratelimit-reset` header lets the run self-heal rather than return blanks. Under the async reactor the wait yields to other fibers rather than blocking. A far-away reset (hourly-limit exhaustion) is not auto-waited; it still warns and moves on (set a token, or run less often). (#35)
+- A gem's activity level is now driven by release recency rather than the most recent of release-or-commit. A single trivial commit (a rubocop autofix, a README tweak) on a gem whose last real release was years ago previously masked the release drought and read as healthy; the commit date is now context only, and stands in for the level solely when a gem has no releases at all (e.g. a git-sourced gem). The "ok" ceiling also moves from 12 to 18 months, calibrated against real RubyGems release cadence rather than the npm-derived annual convention, since healthy mature gems (mime-types, bcrypt, mail) routinely go a year or more between releases. (#32)
+
+### Fixed
+
+- `--baseline` no longer crashes when pointed at a JSON file that isn't a still_active snapshot (a top-level array, a non-object `gems` section, or a gem/`ruby`/field of the wrong type); it exits 2 with a message naming the problem, honouring the exit-code contract documented since 1.4.0.
+- SARIF `SA002` (AbandonedGem) now uses the same release-driven activity level as the rest of the tool, instead of its own separate commit-date threshold. A gem with recent commits but a years-old release was silently missed by the SARIF/code-scanning output (the inverse of the terminal fix), and the message reported commit age ("no commits in 2.0 years") rather than the release gap that actually triggered the finding ("no release in 4.4 years"). SA002 now fires on the `:critical` tier (no release in over 3 years; the last commit date is used only for gems with no releases, e.g. git-sourced), and the message names the real signal. (#32)
+- CycloneDX SBOM: every versioned component now carries a purl. git/path gems were previously emitted as versioned `type:library` components with no purl, which made Datadog SCA and strict CycloneDX consumers reject the document. The Ruby runtime component also gains a `pkg:generic/ruby` purl and a `ruby-lang:ruby` CPE so interpreter CVEs can match. (#45)
+- deps.dev OpenSSF Scorecard lookups now keep the full GitLab subgroup path. `extract_project_id` truncated `gitlab.com/group/subgroup/project` to `gitlab.com/group/subgroup`, so the score was fetched for the wrong project on any nested GitLab namespace. (#44)
+- GitHub Packages version lookups now URL-escape the (lockfile-derived) gem name, matching the Artifactory path. A name with URL-unsafe characters previously raised `URI::InvalidComponentError`, which was swallowed and silently dropped that gem from the audit. Defensive hardening for the untrusted-lockfile stance; the GitHub token is never sent off the fixed `rubygems.pkg.github.com` host. (#50)
+- `--gemfile` is now honoured under `bundle exec`. Dependency loading and the Ruby-version lookup derived their target from a memoized `Bundler.definition` / the ambient `BUNDLE_GEMFILE`, so an explicit `--gemfile` was ignored; both now read the given path directly. (#42)
+- `HttpHelper` no longer crashes on a 3xx response with a missing or malformed `Location` header. `uri + nil` raised `ArgumentError` and a malformed value raised `URI::InvalidURIError`, neither rescued, so the gem was silently dropped; both now return nil with a warning. (#39)
+- Gems from an unqueryable private source (Gemfury, Gemstash, geminabox, a private mirror) are no longer silently looked up on public rubygems.org. A private name with no public match reported blank data, and one that collided with a public gem reported the *public* gem's versions/dates/libyear/repository as if they were the private gem's. still_active now detects a non-rubygems.org rubygems source, warns, and skips both the public version lookup and the public repository-metadata fallback rather than substituting public data. (#43)
+- A gemspec project's (or local Rails engine's) runtime dependencies are now audited. The `gemspec` / `gem path:` directive surfaces the local gem's *development* deps in the lockfile's DEPENDENCIES, but its *runtime* deps appear only as that gem's nested lockfile deps, so a maintainer auditing their own repo never saw the deps they ship. still_active now expands local path-sourced gems' runtime deps (transitively through nested engines) into the audited set, still parsing the lockfile only and never the gemspec. (#41)
+
+### Security
+
+- Credentials are no longer retained on a redirect that changes the port or downgrades the scheme. The redirect follower previously dropped auth headers only when the host changed, so a same-host redirect to a different port (a different service) kept the token; it now requires a full-origin match (scheme, host, and port) and refuses a non-https redirect.
+- still_active no longer evaluates the audited project's Gemfile. `gemfile_dependencies` loaded it via `Bundler.definition`, executing arbitrary Ruby straight from the Gemfile, an unauthenticated RCE when run on an untrusted repository (e.g. CI on a pull request). It now parses `Gemfile.lock` directly with a side-effect-free parser, which also neutralizes `Bundler::LockfileParser`'s own `PLUGIN SOURCE` registry resolution. (#37)
+- `HttpHelper` now caps a response body at 16 MiB, streaming the read rather than buffering the whole body. A source URL is lockfile-derived and a `*.jfrog.io` host is attacker-registerable, so an unbounded body was an unauthenticated OOM triggerable by lockfile content alone. (#40)
+- Markdown output now escapes untrusted metadata. Gem names, licences, versions, repository URLs, and advisory ids drawn from registry/repo metadata, the Gemfile/lockfile, `--baseline`, or `--gems` could otherwise forge table columns or links, break a code span, or inject a list item/heading into a PR comment. GFM escaping is centralised in `StillActive::MarkdownEscape` and applied to both the audit table and the PR diff. (#38)
+- The Ruby Toolbox catalog (used by `--alternatives`) is now fetched via `URI.parse(url).open` instead of `URI.open`, resolving a CodeQL `rb/non-constant-kernel-open` finding. The URL is a constant repo-archive link with no injection path, so this is hardening rather than a fix for a reachable issue.
+
 ## [1.6.0] - 2026-06-08
 
 ### Added

data/README.md

@@ -2,7 +2,7 @@
 
 **How do you know if your Ruby dependencies are still maintained?**
 
-`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.
+`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 dependency graph — direct and transitive by default (`--direct-only` to narrow), with granular, committed suppression via `.still_active.yml`.
 
 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.
 
@@ -85,10 +85,16 @@ still_active --markdown
 3. `GH_TOKEN` environment variable (`gh` CLI convention)
 4. `gh auth token` (if `gh` is installed and authenticated)
 
-Without a token, GitHub API calls are unauthenticated and rate-limited to 60 requests/hour — you will hit the limit on anything beyond a handful of gems. With a token the limit is 5000 requests/hour.
+Without a token, GitHub API calls are unauthenticated and rate-limited to 60 requests/hour — you will hit the limit on anything beyond a handful of gems. With a token the limit is 5000 requests/hour. When a rate-limit response comes back with a reset that's near (within 60 seconds, typically a secondary/burst limit that the concurrent fan-out can trip even with a token), still_active waits it out and retries rather than dropping that gem's signals; a far-off reset (you've exhausted the hourly limit) isn't waited out, so add a token or run less often.
 
 GitLab cascade mirrors GitHub: `--gitlab-token` → `GITLAB_TOKEN` → `glab auth status --show-token`. Optional for public repos, required for private ones.
 
+Forgejo/Codeberg (the rare gem whose canonical `source_code_uri` is `codeberg.org`) is read anonymously by default; set `STILL_ACTIVE_FORGEJO_TOKEN` (or `CODEBERG_TOKEN`) only to raise the rate limit or reach a private repo. There is no CLI flag, since Codeberg has no ubiquitous CLI to borrow a token from the way `gh`/`glab` do.
+
+Artifactory auth looks for Bundler configuration's credentials first so that private registries work without extra configuration if they are already configured in Bundler. To set those credentials in Bundler, run `bundle config set credentials.my-org.jfrog.io user:pass`. If no credentials are set there, still_active falls back using a token provided via `--artifactory-token` or `STILL_ACTIVE_ARTIFACTORY_TOKEN`. Authentication expects a `user:password` format for Basic auth, otherwise it will be treated as a bare token for Bearer auth. Valid authentication is required for private JFrog gem registries (`*.jfrog.io`).
+
+When providing the artifactory token via flag or env, you must also set `--artifactory-host` or `STILL_ACTIVE_ARTIFACTORY_HOST` to the expected registry hostname (e.g. `my-org.jfrog.io`). still_active only sends the credentials to that host, ensuring that a lockfile containing other Artifactory hosts will not leak the token (a security risk). Providing a token/host in this manner will work only for a single host. To support multiple Artifactory hosts, use Bundler's configuration for per-host credentials.
+
 ### CLI options
 
 ```text
@@ -102,15 +108,19 @@ Usage: still_active [options]
         --markdown                   Markdown table output
         --json                       JSON output (default when piped)
         --alternatives               Suggest maintained alternatives (Ruby Toolbox leads) for archived/critical gems
+        --unreleased-commits         Count commits on the default branch since the latest release (GitHub only; opt-in)
+        --direct-only                Audit only direct (declared) deps, not the full transitive graph
         --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
+        --artifactory-token=TOKEN    Artifactory token for private gem registry API calls
+        --artifactory-host=HOST      Artifactory host allowed to receive the global token (e.g. my-org.jfrog.io)
         --simultaneous-requests=QTY  Number of simultaneous requests made
-        --safe-range-end=YEARS       maximum years since last activity considered safe (no warning)
-        --warning-range-end=YEARS    maximum years since last activity that triggers a warning (beyond this is critical)
+        --safe-range-end=YEARS       maximum years since last release considered safe, no warning (default 1.5)
+        --warning-range-end=YEARS    maximum years since last release that triggers a warning, beyond this is critical (default 3)
         --fail-if-critical           Exit 1 if any gem has critical activity warning
         --fail-if-warning            Exit 1 if any gem has warning or critical activity warning
         --fail-if-vulnerable[=SEVERITY]
@@ -334,13 +344,54 @@ still_active --fail-if-outdated=3 --json
 still_active --fail-if-warning --fail-if-vulnerable --ignore=legacy_gem --json
 ```
 
+### Configuration file (`.still_active.yml`)
+
+`--ignore=GEM` is blunt: it drops a gem from **every** gate at once, so accepting one unfixable advisory also blinds you to that gem going archived or to a *new* CVE. A committed `.still_active.yml` in the project root replaces that with granular, auditable suppression, and lets you keep your policy flags in version control instead of threading them through every invocation.
+
+```yaml
+# .still_active.yml -- policy defaults plus granular suppression
+fail_if_critical: true
+fail_if_vulnerable: high       # true, or a minimum severity: low|medium|high|critical
+fail_if_outdated: 3            # libyears
+unreleased_commits: true
+output: json                   # terminal | markdown | json
+direct_only: true              # audit only declared deps, not the full transitive graph (--direct-only)
+
+# Pull bundler-audit's accepted-advisory list instead of maintaining two files
+import:
+  - .bundler-audit.yml
+
+ignore:
+  # Accept ONE advisory, by id -- a different/new CVE on nokogiri still fails
+  - advisory: CVE-2024-1234
+    gem: nokogiri
+    reason: "no fix released; not reachable from our code path"
+    expires: 2026-09-01        # re-surfaces as a normal failure after this date
+
+  # Accept staleness on a vendored gem, but still fail if it gets a CVE
+  - gem: legacy_thing
+    signal: activity            # activity | vulnerability | libyear
+    reason: "vendored, intentionally frozen"
+
+  # A bare gem name keeps the old whole-gem behaviour (mutes every signal)
+  - some_internal_gem
+```
+
+Design:
+
+- **Granularity.** Key by `advisory:` (one CVE) and/or `signal:` (`activity` / `vulnerability` / `libyear`), not the whole gem. A vulnerability suppression **must** name an advisory id, so a newly disclosed CVE on the same gem is never pre-silenced. `--ignore=GEM` (and a bare gem-name entry) still mute everything, by design.
+- **Precedence.** CLI flag > env var > config file > default. A CLI flag always wins; `--ignore` unions with the file's suppressions rather than replacing them. Secrets (tokens) and invocation-specific paths (`--gemfile`, `--gems`, `--baseline`, output paths) are intentionally **not** read from the file, so a committed config never carries a credential.
+- **Expiry.** An `expires:` date makes accepted risk visible: once it passes, the entry stops applying and the finding fails the gate again (Trivy-style), so a suppression can't rot silently. `reason:` is optional but recommended. A suppression naming a gem that isn't in your dependency graph (a typo, or a gem you've since removed) is also surfaced as a warning, so dead entries don't accumulate.
+- **bundler-audit, suggested not absorbed.** still_active never silently inherits another tool's ignore list: auto-importing `.bundler-audit.yml` would suppress vulnerabilities you only accepted in bundler-audit's context, with no reason or expiry here. Instead, when `--fail-if-vulnerable` is on and an un-imported `.bundler-audit.yml` is present, it prints a one-line hint suggesting the `import:` line, leaving the opt-in to you.
+- **Output.** Suppression changes the **exit code** and marks the finding in **SARIF** as a native `suppressions[]` entry (with your `reason` as the justification, so GitHub Code Scanning renders it dismissed rather than open). The finding still appears in JSON/terminal/markdown output; suppression accepts a risk, it doesn't hide that the risk exists.
+
 ### Activity thresholds
 
-Activity is determined by the most recent signal across last commit date, latest release date, and latest pre-release date:
+Activity is driven by release recency (the latest stable or pre-release date), since a release is what you can actually `bundle update` to. A recent commit does not offset a stale release: the last commit date is shown as context and only stands in when a gem has no releases at all (e.g. git-sourced). Thresholds are calibrated against real RubyGems cadence, where healthy mature gems often go a year or more between releases:
 
-- **ok**: last activity within 1 year (configurable with `--safe-range-end`)
-- **stale**: last activity between 1 and 3 years ago (configurable with `--warning-range-end`)
-- **critical**: last activity over 3 years ago
+- **ok**: last release within 18 months (configurable with `--safe-range-end`)
+- **stale**: last release between 18 months and 3 years ago
+- **critical**: last release over 3 years ago (configurable with `--warning-range-end`)
 
 ### Alternative gem leads (opt-in)
 
@@ -356,10 +407,26 @@ still_active --gems=paperclip --alternatives
 
 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).
 
+### Transitive dependencies
+
+Maintenance signals (stale releases, archived repos, last-commit age, advisories, libyear) cover the **full transitive lockfile graph by default** — an unmaintained gem you ship transitively is real risk even though you never named it, and the CVE tools still_active composes with already enumerate the whole resolved graph. This matches libyear-bundler (transitive by default, `--only-explicit` opts out) and every CVE scanner (bundler-audit, npm/cargo/pip-audit are all full-tree).
+
+When a transitive gem trips a signal, the output names the **direct dependency that pulls it in**: `dependency_path` in JSON, a dimmed `↳ transitive, pulled in by X` line in the terminal, a `(transitive, pulled in by X)` suffix in SARIF messages, and a **Transitive findings** list in markdown. That turns an un-actionable transitive finding into an actionable one: you can't bump a gem you didn't choose, but you can replace or pressure the direct gem that drags it in.
+
+`--alternatives` stays **direct-only** by design — "replace gem X with Y" is incoherent for a gem you never selected. Pass `--direct-only` to audit just your declared dependencies (the pre-1.7 behaviour), which is also much cheaper in API calls.
+
+> **Run on a schedule, not on every commit.** Auditing the full graph means a repo/release/advisory lookup for *every* resolved gem (hundreds, for a real app), and the GitHub signals are rate-limited (60 req/hour unauthenticated, 5000 with a token). Maintenance status changes over days and weeks, not per-commit, so a nightly or weekly job (or `--direct-only` in PR gates) gets you the signal without burning your API budget for nothing. This is why advisory tools like Brakeman ship their check database; still_active's signals are inherently live (a release date or an archived flag can't be vendored), so the answer is cadence, not bundling.
+
+### Unreleased commits (opt-in)
+
+`--unreleased-commits` adds an `unreleased_commits` count to the JSON output: commits on the default branch since the latest release's tag. It catches the case the release-recency signal can't, a gem with a *recent* release but a pile of merged-but-unreleased fixes sitting on top, or conversely one that looks stale but is genuinely *done* (no unreleased work). It is the one maintenance signal no Ruby tool surfaces today; only GitHub's own UI shows it.
+
+It is **opt-in and GitHub-only**: enabling it adds one extra API call per GitHub-hosted gem (the git tag is resolved from the RubyGems version by trying `v1.2.3` then `1.2.3` as the compare base), so mind your rate limit on a large lockfile. Non-GitHub sources report `null` (GitLab has no equivalent scalar; the signal is duck-typed, so a provider either implements it or doesn't). The count is **informational and never gates a run**. Read it as a lead, not a verdict: it is inflated for monorepos (the count spans the whole repository, e.g. `bundler` living in `rubygems/rubygems`) and for release-branch projects (the default branch is the next-version trunk, so `rails` reads ~2000 commits ahead of its latest stable tag).
+
 ### Data sources
 
-- **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
+- **Versions, release dates, and licenses** from [RubyGems.org](https://rubygems.org), [GitHub Packages](https://docs.github.com/en/packages), or [JFrog Artifactory](https://jfrog.com/artifactory/) gem registries
+- **Last commit date and archived status** from the [GitHub](https://docs.github.com/en/rest), [GitLab](https://docs.gitlab.com/ee/api/), or [Forgejo/Gitea](https://forgejo.org/docs/latest/user/api-usage/) (Codeberg) 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)
@@ -370,8 +437,8 @@ These are **leads, not recommendations**: same-category does not mean drop-in re
 | Option                  | Default     | Description                                                      |
 | ----------------------- | ----------- | ---------------------------------------------------------------- |
 | `output_format`         | auto-detect | Coloured terminal on TTY, JSON when piped                        |
-| `safe_range_end`        | 1 year      | Last activity within this range is "ok"                          |
-| `warning_range_end`     | 3 years     | Last activity within this range is "stale"; beyond is "critical" |
+| `safe_range_end`        | 1.5 years   | Last release within this range is "ok"                           |
+| `warning_range_end`     | 3 years     | Last release within this range is "stale"; beyond is "critical"  |
 | `simultaneous_requests` | 10          | Concurrent API requests                                          |
 
 ## Development

data/lib/helpers/activity_helper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "time"
 require_relative "../still_active/core_ext"
 
 module StillActive
@@ -8,22 +9,46 @@ module StillActive
 
     using StillActive::CoreExt
 
+    # The most recent activity signal that drives the level, or nil if none:
+    # { date:, kind: } where kind is :release (preferred) or :commit. Release
+    # recency drives the level because a release is what a consumer can actually
+    # consume (you can't `bundle update` to unreleased commits), so a lone
+    # rubocop/README commit can't mask a multi-year release drought. The commit
+    # date stands in only when a gem has no releases at all (e.g. a git-sourced
+    # gem), where it is the only signal available.
+    def last_activity(gem_data)
+      release = [
+        gem_data[:latest_version_release_date],
+        gem_data[:latest_pre_release_version_release_date],
+      ].filter_map { parse_time(_1) }.max
+      return { date: release, kind: :release } if release
+
+      commit = parse_time(gem_data[:last_commit_date])
+      commit ? { date: commit, kind: :commit } : nil
+    end
+
+    # Coerce a Time or an iso8601-ish string (the SARIF path may supply either)
+    # to a Time, or nil if absent/unparseable.
+    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
+
     # Returns :archived, :ok, :stale, :critical, or :unknown
     def activity_level(gem_data)
       return :archived if gem_data[:archived]
 
-      most_recent = [
-        gem_data[:last_commit_date],
-        gem_data[:latest_version_release_date],
-        gem_data[:latest_pre_release_version_release_date],
-      ].compact.max
-
-      return :unknown if most_recent.nil?
+      activity = last_activity(gem_data)
+      return :unknown if activity.nil?
 
       config = StillActive.config
-      if most_recent >= config.no_warning_range_end.years.ago
+      if activity[:date] >= config.no_warning_range_end.years.ago
         :ok
-      elsif most_recent >= config.warning_range_end.years.ago
+      elsif activity[:date] >= config.warning_range_end.years.ago
         :stale
       else
         :critical

data/lib/helpers/bundler_helper.rb

@@ -1,52 +1,113 @@
 # frozen_string_literal: true
 
+require "set"
+require_relative "lockfile_dependency_parser"
+
 module StillActive
   module BundlerHelper
     extend self
 
     def gemfile_dependencies(gemfile_path: StillActive.config.gemfile_path)
       absolute_gemfile = File.expand_path(gemfile_path)
-      ::Bundler::SharedHelpers.set_env("BUNDLE_GEMFILE", absolute_gemfile)
-      gemfile_gems = ::Bundler.definition.dependencies.map(&:name)
-      locked_gems = ::Bundler.definition.locked_gems
-      if locked_gems.nil?
+      lockfile = lockfile_path_for(absolute_gemfile)
+      unless File.file?(lockfile)
         raise MissingLockfileError,
-          "no lockfile next to #{absolute_gemfile} — run `bundle lock` (or `bundle install`) first"
+          "no lockfile next to #{absolute_gemfile}; run `bundle lock` (or `bundle install`) first"
+      end
+
+      parsed = LockfileDependencyParser.parse(File.read(lockfile))
+      if parsed[:plugin_source?]
+        warn("warning: lockfile contains a PLUGIN SOURCE block; still_active does not audit Bundler plugins, skipping it")
       end
 
-      locked_gems
-        .specs
-        .select { |spec| gemfile_gems.include?(spec.name) }
+      direct = audited_names(parsed)
+      # Maintenance signals cover the full resolved graph by default (matching
+      # libyear-bundler and the CVE scanners we compose with); --direct-only
+      # opts back to just the declared/shipped set. Transitive gems carry the
+      # path back to the direct dep that pulls them in, so an un-actionable
+      # transitive flag becomes an actionable "replace your direct gem A". #60.
+      audited = StillActive.config.direct_only ? direct : parsed[:specs].map(&:name)
+      direct_set = direct.to_set
+      paths = StillActive.config.direct_only ? {} : dependency_paths(parsed[:specs], direct)
+
+      parsed[:specs]
+        .select { |spec| audited.include?(spec.name) }
         .uniq(&:name)
         .map do |spec|
+          is_direct = direct_set.include?(spec.name)
           {
             name: spec.name,
-            version: spec.version.version,
-            source_type: detect_source_type(spec),
-            source_uri: detect_source_uri(spec),
+            version: spec.version,
+            source_type: spec.source_type || :unknown,
+            source_uri: spec.source_uri,
+            direct: is_direct,
+            dependency_path: is_direct ? nil : paths[spec.name],
           }
         end
     end
 
-    private
+    # Shortest path from a direct dependency to each reachable gem, by BFS over
+    # the lockfile's resolved dependency edges. A direct root maps to [name];
+    # a transitive gem maps to [direct_root, ..., name], whose head names the
+    # direct dependency a maintainer can actually act on. An unreachable spec
+    # (no declared ancestor) gets no path.
+    def dependency_paths(specs, roots)
+      specs_by_name = specs.to_h { |spec| [spec.name, spec] }
+      paths = {}
+      queue = []
+      roots.each do |name|
+        paths[name] = [name]
+        queue << name
+      end
+
+      until queue.empty?
+        name = queue.shift
+        specs_by_name[name]&.dependencies&.each do |dep|
+          next if paths.key?(dep)
+
+          paths[dep] = paths[name] + [dep]
+          queue << dep
+        end
+      end
+
+      paths
+    end
+
+    # The DEPENDENCIES names, plus the runtime deps of any local path-sourced gem
+    # reachable from them (a gemspec project's own gem, or a local Rails engine).
+    # A `gemspec` / `gem path:` directive surfaces the local gem's *development*
+    # deps in DEPENDENCIES but its *runtime* deps arrive only as that gem's
+    # nested lockfile deps, so without this a gem maintainer auditing their own
+    # repo would never see the deps they ship. We follow path gems transitively
+    # (nested engines) but never expand a regular gem's transitive graph, keeping
+    # parity with the "audit what you declare" scope for normal projects. Refs #41.
+    def audited_names(parsed)
+      specs_by_name = parsed[:specs].to_h { |spec| [spec.name, spec] }
+      names = []
+      queue = parsed[:direct].dup
+
+      until queue.empty?
+        name = queue.shift
+        next if names.include?(name)
 
-    def detect_source_type(spec)
-      case spec.source
-      when ::Bundler::Source::Rubygems then :rubygems
-      when ::Bundler::Source::Git then :git
-      when ::Bundler::Source::Path then :path
-      else :unknown
+        names << name
+        spec = specs_by_name[name]
+        queue.concat(spec.dependencies) if spec&.source_type == :path
       end
+
+      names
     end
 
-    def detect_source_uri(spec)
-      case spec.source
-      when ::Bundler::Source::Rubygems
-        spec.source.remotes&.first&.to_s
-      when ::Bundler::Source::Git
-        spec.source.uri
-      when ::Bundler::Source::Path
-        spec.source.path&.to_s
+    # Bundler's lockfile naming: `gems.rb` pairs with `gems.locked`, every other
+    # Gemfile with `<gemfile>.lock`. Derived from the explicit path rather than
+    # global Bundler state so `--gemfile` is honoured even under `bundle exec`
+    # (where a memoized Bundler.definition / ambient BUNDLE_GEMFILE would
+    # otherwise win). Refs #42.
+    def lockfile_path_for(gemfile)
+      if File.basename(gemfile) == "gems.rb"
+        File.join(File.dirname(gemfile), "gems.locked")
+      else
+        "#{gemfile}.lock"
       end
     end
   end

data/lib/helpers/catalog_index.rb

@@ -80,7 +80,10 @@ module StillActive
 
     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
+      # URI(url).open (not URI.open/Kernel#open) so a "|cmd" string can never be
+      # treated as a shell command — the URL is a constant-repo archive link, but
+      # this keeps the open path injection-proof regardless.
+      URI.parse(url).open { |io| io.read(MAX_DOWNLOAD_BYTES) }
     end
 
     def build_siblings(categories)

data/lib/helpers/cyclonedx_helper.rb

@@ -55,7 +55,7 @@ module StillActive
       component = { "type" => "library", "name" => name }
       component["version"] = version if version
       component["bom-ref"] = bom_ref(name, data)
-      component["purl"] = purl(name, version) if data[:source_type] == :rubygems && version
+      component["purl"] = purl(name, version, data[:source_type]) if version
       component["licenses"] = licenses(data[:license]) if data[:license]
       if data[:repository_url]
         component["externalReferences"] = [{ "type" => "vcs", "url" => data[:repository_url] }]
@@ -67,13 +67,19 @@ module StillActive
 
     def bom_ref(name, data)
       version = data[:version_used]
-      return purl(name, version) if data[:source_type] == :rubygems && version
+      return purl(name, version, data[:source_type]) if version
 
-      "#{data[:source_type]}-source:#{name}@#{version || "unknown"}"
+      "#{data[:source_type]}-source:#{name}@unknown"
     end
 
-    def purl(name, version)
-      "pkg:gem/#{name}@#{version}"
+    # Datadog SCA (and strict CycloneDX consumers) hard-reject a versioned
+    # library component with no purl, so every gem with a version needs one.
+    # A path gem is local and not on rubygems, so it gets pkg:generic to avoid
+    # false-matching a public gem of the same name; git/rubygems-sourced gems
+    # get pkg:gem so a fork still matches the upstream gem's advisories.
+    def purl(name, version, source_type)
+      type = source_type == :path ? "generic" : "gem"
+      "pkg:#{type}/#{name}@#{version}"
     end
 
     # VersionHelper joins multiple SPDX ids with ", " for terminal/markdown
@@ -93,12 +99,22 @@ module StillActive
       }.filter_map { |name, value| { "name" => name, "value" => value } unless value.nil? }
     end
 
+    # The Ruby interpreter. CycloneDX's "platform" type fits semantically, but
+    # nothing consumes it and strict SCA validators (Datadog) only accept
+    # "library" + a purl. We follow Syft's convention for an unmanaged runtime:
+    # type "library", purl pkg:generic/ruby@<ver>, plus a CPE — the CPE is what
+    # actually lets a matcher (NVD/Grype) hit interpreter CVEs, since no purl
+    # type maps the Ruby runtime in OSV. The EOL/libyear signals stay as
+    # still_active properties.
     def ruby_component(ruby_info)
+      version = ruby_info[:version]
       {
-        "type" => "platform",
+        "type" => "library",
         "name" => "ruby",
-        "version" => ruby_info[:version],
-        "bom-ref" => "platform:ruby@#{ruby_info[:version]}",
+        "version" => version,
+        "bom-ref" => "pkg:generic/ruby@#{version}",
+        "purl" => "pkg:generic/ruby@#{version}",
+        "cpe" => "cpe:2.3:a:ruby-lang:ruby:#{version}:*:*:*:*:*:*:*",
         "properties" => [
           { "name" => "still_active:eol", "value" => boolean_property(ruby_info[:eol]) },
           { "name" => "still_active:libyear", "value" => ruby_info[:libyear]&.to_s },

data/lib/helpers/diff_markdown_helper.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "markdown_escape"
+
 module StillActive
   # Renders a StillActive::Diff::Result as PR-comment-friendly markdown.
   # Section taxonomy mirrors GitHub's dependency-review-action so reviewers
@@ -49,7 +51,7 @@ module StillActive
     def regressions_section(regressions)
       return "" if regressions.empty?
 
-      lines = regressions.map { |r| "- **#{r.kind}** `#{r.gem}` — #{r.detail}" }
+      lines = regressions.map { |r| "- **#{r.kind}** #{MarkdownEscape.code_span(r.gem)} — #{MarkdownEscape.inline(r.detail)}" }
       section("Regressions (CI-failable)", lines)
     end
 
@@ -63,7 +65,7 @@ module StillActive
     def removed_section(removed)
       return "" if removed.empty?
 
-      lines = removed.map { |r| "- `#{r.name}` (was #{(r.data || {})["version_used"] || "?"})" }
+      lines = removed.map { |r| "- #{MarkdownEscape.code_span(r.name)} (was #{MarkdownEscape.inline((r.data || {})["version_used"] || "?")})" }
       section("Removed", lines)
     end
 
@@ -88,9 +90,9 @@ module StillActive
       lines = []
       if ruby[:version_changed]
         eol_suffix = ruby[:newly_eol] ? " (now EOL)" : ""
-        lines << "- Ruby `#{ruby[:from]}` → `#{ruby[:to]}`#{eol_suffix}"
+        lines << "- Ruby #{MarkdownEscape.code_span(ruby[:from])} → #{MarkdownEscape.code_span(ruby[:to])}#{eol_suffix}"
       elsif ruby[:newly_eol]
-        lines << "- Ruby `#{ruby[:to]}` is now EOL"
+        lines << "- Ruby #{MarkdownEscape.code_span(ruby[:to])} is now EOL"
       end
       section("Ruby", lines)
     end
@@ -108,30 +110,31 @@ module StillActive
         (data["archived"] ? "archived" : nil),
         data["libyear"] && "#{data["libyear"]}y behind",
       ].compact
-      "`#{added.name}` (#{bits.join(", ")})"
+      "#{MarkdownEscape.code_span(added.name)} (#{MarkdownEscape.inline(bits.join(", "))})"
     end
 
     def format_bump(bump)
       label = BUMP_KIND_LABELS[bump.kind]
       suffix = label ? " (#{label})" : ""
-      "- `#{bump.name}` #{bump.before_version} → #{bump.after_version}#{suffix}"
+      "- #{MarkdownEscape.code_span(bump.name)} #{MarkdownEscape.inline(bump.before_version)} → #{MarkdownEscape.inline(bump.after_version)}#{suffix}"
     end
 
     def format_signal_change_lines(sc)
+      name = MarkdownEscape.code_span(sc.name)
       sc.changes.filter_map do |ch|
         case ch[:kind]
         when :archived
-          "- `#{sc.name}` — archived (false → true)"
+          "- #{name} — archived (false → true)"
         when :new_vulnerability
-          ids = Array(ch[:ids]).join(", ")
-          "- `#{sc.name}` — new vulnerability (#{ch[:from]} → #{ch[:to]}#{" — #{ids}" unless ids.empty?})"
+          ids = MarkdownEscape.inline(Array(ch[:ids]).join(", "))
+          "- #{name} — new vulnerability (#{MarkdownEscape.inline(ch[:from])} → #{MarkdownEscape.inline(ch[:to])}#{" — #{ids}" unless ids.empty?})"
         when :scorecard_dropped
           note = ch[:crossed_good] ? " (crossed 7.0)" : ""
-          "- `#{sc.name}` — scorecard #{ch[:from]} → #{ch[:to]}#{note}"
+          "- #{name} — scorecard #{MarkdownEscape.inline(ch[:from])} → #{MarkdownEscape.inline(ch[:to])}#{note}"
         when :version_yanked
-          "- `#{sc.name}` — version yanked from rubygems"
+          "- #{name} — version yanked from rubygems"
         when :libyear_worsened
-          "- `#{sc.name}` — libyear #{ch[:from]} → #{ch[:to]} (+#{ch[:delta]}y; same pinned version)"
+          "- #{name} — libyear #{MarkdownEscape.inline(ch[:from])} → #{MarkdownEscape.inline(ch[:to])} (+#{ch[:delta]}y; same pinned version)"
         end
       end
     end