still_active 1.6.0 → 3.0.0.rc1

data/lib/still_active/cli.rb

@@ -1,24 +1,55 @@
 # frozen_string_literal: true
 
 require_relative "options"
+require_relative "config_file"
 require_relative "diff"
 require_relative "../helpers/activity_helper"
 require_relative "../helpers/bot_context"
 require_relative "../helpers/bundler_helper"
+require_relative "../helpers/constraint_helper"
 require_relative "../helpers/cyclonedx_helper"
 require_relative "../helpers/diff_markdown_helper"
 require_relative "../helpers/emoji_helper"
 require_relative "../helpers/markdown_helper"
 require_relative "../helpers/sarif_helper"
+require_relative "../helpers/status_helper"
+require_relative "../helpers/summary_helper"
 require_relative "../helpers/terminal_helper"
 require_relative "../helpers/version_helper"
 require_relative "../helpers/vulnerability_helper"
+require_relative "sbom_reader"
+require_relative "sbom_workflow"
 require_relative "workflow"
 
 module StillActive
   class CLI
+    # The committed JSON Schema for the --json output. Emitted as `$schema` so
+    # the output is self-describing and a consumer can validate it.
+    SCHEMA_URL = "https://raw.githubusercontent.com/SeanLF/still_active/main/docs/still_active.schema.json"
+
     def run(args)
-      options = Options.new.parse!(args)
+      # Apply the committed .still_active.yml first so CLI flags (parsed next)
+      # win over it: CLI flag > env var > config file > default.
+      config_data = ConfigFile.load
+      ConfigFile.apply(StillActive.config, config_data).each { |warning| $stderr.puts("warning: #{warning}") }
+      options = begin
+        Options.new.parse!(args)
+      rescue ArgumentError, OptionParser::ParseError => e
+        # Bad CLI input (conflicting flags, a missing file, an unknown flag, a bad
+        # enum value) is a user error: print it and exit 2, matching the SBOM/baseline
+        # paths, rather than letting the raise bubble into a Ruby backtrace.
+        $stderr.puts("error: #{e.message}")
+        exit(2)
+      end
+      # After CLI flags resolve, nudge (don't auto-inherit) an un-imported
+      # bundler-audit ignore list when the vulnerability gate is on.
+      hint = ConfigFile.import_hint(config_data)
+      $stderr.puts("hint: #{hint}") if hint
+      # An SBOM audit is cross-ecosystem: it runs the deps.dev/ecosyste.ms lens
+      # over the SBOM's packages, not Bundler over a lockfile. Dispatch before the
+      # Bundler resolution below so a Gemfile is never required (or read).
+      return run_sbom if options[:provided_sbom]
+
       unless options[:provided_gems]
         begin
           StillActive.config.gems = BundlerHelper.gemfile_dependencies
@@ -29,6 +60,7 @@ module StillActive
       end
 
       warn_output_flag_conflicts(options)
+      warn_stale_suppressions
 
       result = if $stderr.tty?
         Workflow.call { |done, total| $stderr.print("\rChecking #{done}/#{total} gems...") }
@@ -50,14 +82,25 @@ module StillActive
         case resolve_format
         when :json
           output = {
+            "$schema": SCHEMA_URL,
             schema_version: 1,
             tool: { name: "still_active", version: StillActive::VERSION },
             generated_at: Time.now.utc.iso8601,
-            gems: result,
+            # A one-object digest of the audit's posture, so a machine/LLM
+            # consumer reads the headline counts without iterating every gem.
+            summary: SummaryHelper.summarize(result, ruby_info: ruby_info),
+            # Surface the derived verdict so a machine/LLM consumer reads it
+            # directly instead of re-deriving it from the raw dates.
+            gems: result.transform_values do |data|
+              data.merge(
+                activity_level: ActivityHelper.activity_level(data),
+                status: StatusHelper.gem_status(data),
+              )
+            end,
           }
           output[:ruby] = ruby_info if ruby_info
           output[:pr_context] = pr_context if pr_context
-          puts output.to_json
+          puts iso8601_times(output).to_json
         when :terminal
           puts BotContext.summary(pr_context) if pr_context
           puts TerminalHelper.render(result, ruby_info: ruby_info)
@@ -71,6 +114,126 @@ module StillActive
 
     private
 
+    # The --sbom path: assess a CycloneDX SBOM's packages cross-ecosystem via
+    # EcosystemLens, then emit a JSON report shaped like the native audit's but
+    # keyed "ecosystem/name@version" and carrying an `unassessable` list of every
+    # dep we couldn't assess (reader-level: unsupported ecosystem, no version/PURL;
+    # or assessment-level: the lens call raised) rather than silently dropping it.
+    def run_sbom
+      path = StillActive.config.sbom_path
+      require_parseable_sbom(path)
+      # deps.dev is the SBOM path's sole vulnerability source and an alpha API; a
+      # field rename would silently zero every vuln count. Canary the schema once
+      # and warn loudly so a degraded run never reads as an authoritative all-clear.
+      unless DepsDevClient.advisory_schema_ok?
+        $stderr.puts("warning: deps.dev vulnerability schema check failed (its `advisoryKeys` field may have changed, or the API is unreachable); vulnerability counts may be understated -- a clean result is NOT authoritative")
+      end
+      sbom = SbomReader.parse(path)
+      outcome = if $stderr.tty?
+        SbomWorkflow.call(sbom) { |done, total| $stderr.print("\rAssessing #{done}/#{total} dependencies...") }
+      else
+        SbomWorkflow.call(sbom)
+      end
+      $stderr.print("\r\e[K") if $stderr.tty?
+
+      # A reader-level gap (unsupported ecosystem, no version/PURL) and an
+      # assessment-time failure (a raised lens call) both mean "not assessed":
+      # surface them together so neither is a silent hole in the reported coverage.
+      unassessable = sbom.unassessable + outcome.failures
+      emit_sbom_json(outcome.assessed, unassessable)
+      warn_unassessable(unassessable)
+      check_exit_status(outcome.assessed)
+    end
+
+    # SbomReader never raises (a malformed file degrades to an empty result), which
+    # is right for the library entrypoint but wrong for the explicit --sbom flag:
+    # the user pointed at a file to audit, so a truncated/wrong-format one must
+    # error, not flow through to an empty "all clear" report with exit 0.
+    def require_parseable_sbom(path)
+      doc = JSON.parse(File.read(path))
+      return if doc.is_a?(Hash) && doc["components"].is_a?(Array)
+
+      # Matches SbomReader's own parse contract (a `components` array is what it
+      # reads). A metadata-only CycloneDX has nothing to audit, so the message
+      # names the missing array rather than over-claiming "not CycloneDX".
+      $stderr.puts("error: #{path} has no CycloneDX `components` array to audit")
+      exit(2)
+    rescue JSON::ParserError
+      $stderr.puts("error: #{path} is not valid JSON")
+      exit(2)
+    rescue SystemCallError => e
+      # Options checked the path exists, not that it's readable (a permission
+      # denial, or a directory). Exit cleanly instead of crashing with a trace.
+      $stderr.puts("error: cannot read SBOM file #{path}: #{e.message}")
+      exit(2)
+    end
+
+    # SBOM output deliberately omits the Ruby audit's `$schema`: the shape differs
+    # (composite keys, an unassessable list, no Ruby/PR-context blocks), so it
+    # would be a false claim to point at that contract. schema_version stays 1.
+    def emit_sbom_json(result, unassessable)
+      output = {
+        schema_version: 1,
+        tool: { name: "still_active", version: StillActive::VERSION },
+        generated_at: Time.now.utc.iso8601,
+        summary: sbom_summary(result, unassessable),
+        dependencies: result.transform_values do |data|
+          data.merge(
+            activity_level: ActivityHelper.activity_level(data),
+            status: StatusHelper.gem_status(data),
+          )
+        end,
+        unassessable:,
+      }
+      puts iso8601_times(output).to_json
+    end
+
+    def sbom_summary(result, unassessable)
+      statuses = result.each_value.map { |data| StatusHelper.gem_status(data) }
+      {
+        total_assessed: result.size,
+        unassessable_count: unassessable.size,
+        # The single worst per-dependency verdict, so a consumer reads one
+        # project-level posture without scanning every dependency.
+        status: StatusHelper.project_status(result),
+        status_counts: statuses.tally,
+      }
+    end
+
+    # Unassessable deps are already in the JSON; echo a one-line count to stderr so
+    # a human running interactively sees the coverage gap without parsing stdout.
+    def warn_unassessable(unassessable)
+      return if unassessable.empty?
+
+      noun = unassessable.size == 1 ? "dependency" : "dependencies"
+      $stderr.puts("warning: #{unassessable.size} #{noun} could not be assessed " \
+        "(a private/alternative registry, unsupported ecosystem, missing version, no package URL, or a lookup failure); " \
+        "see \"unassessable\" in the JSON output")
+    end
+
+    # Dates live in the result as real Time objects (the activity/libyear math
+    # needs them), but the JSON contract is ISO8601 UTC strings, matching
+    # generated_at. Normalize at the serialization boundary only, so the
+    # terminal/markdown/SARIF paths keep their Time objects untouched.
+    def iso8601_times(value)
+      case value
+      when Time then value.utc.iso8601
+      when Hash then value.transform_values { |v| iso8601_times(v) }
+      when Array then value.map { |v| iso8601_times(v) }
+      else value
+      end
+    end
+
+    # A suppression naming a gem that isn't in the resolved dependency set can
+    # never fire, so it's dead config worth surfacing (the presence half of
+    # suppression rot, alongside the expiry half the entries handle themselves).
+    def warn_stale_suppressions
+      present = StillActive.config.gems.map { |gem| gem[:name] }
+      StillActive.config.suppressions.stale_gem_warnings(present).each do |warning|
+        $stderr.puts("warning: #{warning}")
+      end
+    end
+
     # The output destinations are mutually exclusive and resolved by precedence
     # (baseline > sarif > cyclonedx > terminal/markdown/json). Warn rather than
     # silently dropping the loser when more than one is set.
@@ -141,8 +304,9 @@ module StillActive
       current = current_snapshot(result, ruby_info)
       baseline = JSON.parse(File.read(baseline_path))
       diff = Diff.call(baseline: baseline, current: current)
+      accepted = partition_accepted_regressions!(diff)
       puts "> **#{BotContext.summary(pr_context)}**\n\n" if pr_context
-      puts DiffMarkdownHelper.render(diff)
+      puts DiffMarkdownHelper.render(diff, accepted: accepted)
       exit(1) if diff.regressions.any?
     rescue JSON::ParserError => e
       $stderr.puts("error: --baseline file is not valid JSON: #{e.message}")
@@ -155,6 +319,27 @@ module StillActive
       exit(2)
     end
 
+    # Drops regressions a committed .still_active.yml accepts from the CI-failable
+    # set (mutating diff.regressions in place) and returns them as accepted
+    # entries so the render can show them as knowingly-suppressed rather than
+    # silently vanishing. Mirrors the audit/SARIF gates, which already honour the
+    # same suppression list; the diff was the only gate that ignored it.
+    def partition_accepted_regressions!(diff)
+      suppressions = StillActive.config.suppressions
+      accepted = []
+      diff.regressions = diff.regressions.reject do |reg|
+        signal = Diff.suppressible_signal(reg.kind)
+        next false unless signal
+
+        entry = suppressions.match(gem: reg.gem, signal: signal)
+        next false unless entry
+
+        accepted << Diff::Accepted.new(regression: reg, reason: entry.reason)
+        true
+      end
+      accepted
+    end
+
     def current_snapshot(result, ruby_info)
       snapshot = {
         "schema_version" => 1,
@@ -190,8 +375,14 @@ module StillActive
 
         puts MarkdownHelper.markdown_table_body_line(gem_name: name, data: gem_data)
       end
+      poison = MarkdownHelper.poison_section(result)
+      puts poison unless poison.empty?
+      language_ceiling = MarkdownHelper.language_ceiling_section(result)
+      puts language_ceiling unless language_ceiling.empty?
       alternatives = MarkdownHelper.alternatives_section(result)
       puts alternatives unless alternatives.empty?
+      transitive = MarkdownHelper.transitive_section(result)
+      puts transitive unless transitive.empty?
       if ruby_info
         puts ""
         puts MarkdownHelper.ruby_line(ruby_info)
@@ -200,29 +391,110 @@ module StillActive
 
     def check_exit_status(result)
       config = StillActive.config
-      return unless config.fail_if_critical || config.fail_if_warning || config.fail_if_vulnerable || config.fail_if_outdated
+      return unless config.fail_if_critical || config.fail_if_warning || config.fail_if_vulnerable || config.fail_if_outdated || config.fail_if_poison || config.fail_if_language_ceiling
 
-      ignored = config.ignored_gems
-      checked = result.reject { |name, _| ignored.include?(name) }
+      warn_unknown_severity_gate(result, config)
+      exit(1) if result.any? { |name, data| gate_failed?(name, data, config) }
+    end
 
-      if config.fail_if_critical || config.fail_if_warning
-        levels = checked.each_value.map { |gem_data| ActivityHelper.activity_level(gem_data) }
-        exit(1) if config.fail_if_warning && levels.intersect?([:stale, :critical, :archived])
-        exit(1) if config.fail_if_critical && levels.intersect?([:critical, :archived])
-      end
+    # --fail-if-vulnerable=<threshold> fails closed on an advisory with no CVSS
+    # score (it could exceed the threshold; fresh CVEs often lack a score). Say so
+    # per gem, so failing a =high gate on an "unknown" severity reads as a
+    # deliberate conservative call the user can review and fix or suppress, not a
+    # mystery. Only for the thresholded form; bare --fail-if-vulnerable fails on
+    # every advisory regardless of severity, so there's nothing to explain.
+    def warn_unknown_severity_gate(result, config)
+      threshold = config.fail_if_vulnerable
+      return unless threshold.is_a?(String)
 
-      if (vuln_setting = config.fail_if_vulnerable)
-        checked.each_value do |d|
-          next unless d[:vulnerability_count]&.positive?
+      suppressions = config.suppressions
+      result.each do |name, data|
+        next if config.ignored_gems.include?(name)
 
-          exit(1) if vuln_setting == true
-          exit(1) if VulnerabilityHelper.severity_at_or_above?(d[:vulnerabilities], vuln_setting)
-        end
+        unknown = live_advisories(name, data, suppressions).select { |vuln| VulnerabilityHelper.unknown_severity?(vuln) }
+        next if unknown.empty?
+
+        ids = unknown.filter_map { |vuln| vuln[:id] }.join(", ")
+        labelled = ids.empty? ? "" : " (#{ids})"
+        $stderr.puts("warning: #{name} has an advisory of unknown severity#{labelled}; failing --fail-if-vulnerable=#{threshold} because it can't be ruled out below the threshold (review, then fix or suppress it in .still_active.yml)")
       end
+    end
+
+    # A gem fails the run when it trips an enabled gate that is neither
+    # whole-gem --ignore'd nor covered by a granular .still_active.yml
+    # suppression. Each signal is checked independently so accepting one finding
+    # (e.g. a single advisory) never blinds the others.
+    def gate_failed?(name, data, config)
+      return false if config.ignored_gems.include?(name)
+
+      suppressions = config.suppressions
+      failed_activity?(name, data, config, suppressions) ||
+        failed_vulnerability?(name, data, config, suppressions) ||
+        failed_outdated?(name, data, config, suppressions) ||
+        failed_poison?(name, data, config, suppressions) ||
+        failed_language_ceiling?(name, data, config, suppressions)
+    end
+
+    def failed_poison?(name, data, config, suppressions)
+      return false unless config.fail_if_poison
+      return false if suppressions.suppressed?(gem: name, signal: :poison)
 
-      if (threshold = config.fail_if_outdated)
-        exit(1) if checked.each_value.any? { |d| d[:libyear] && d[:libyear] > threshold }
+      # Bare --fail-if-poison fails at :warning and above (a 1-behind :note is FYI,
+      # not a build breaker); --fail-if-poison=TIER sets an explicit threshold.
+      threshold = config.fail_if_poison == true ? :warning : config.fail_if_poison
+      ConstraintHelper.severity_at_or_above?(data[:poison_severity], threshold)
+    end
+
+    def failed_language_ceiling?(name, data, config, suppressions)
+      return false unless config.fail_if_language_ceiling
+      return false if suppressions.suppressed?(gem: name, signal: :language_ceiling)
+
+      # Ceiling findings are only ever :critical (EOL-forced) or :note
+      # (latest-not-yet) -- there is no :warning tier for this signal -- so the
+      # bare flag defaults to :critical (the genuine blocker: no supported runtime
+      # is reachable). A latest-not-yet :note is an FYI/contribution lead that gates
+      # only when the user explicitly opts in with =note.
+      threshold = config.fail_if_language_ceiling == true ? :critical : config.fail_if_language_ceiling
+      ConstraintHelper.severity_at_or_above?(data.dig(:language_ceiling, :severity), threshold)
+    end
+
+    def failed_activity?(name, data, config, suppressions)
+      return false unless config.fail_if_warning || config.fail_if_critical
+      return false if suppressions.suppressed?(gem: name, signal: :activity)
+
+      level = ActivityHelper.activity_level(data)
+      (config.fail_if_warning && [:stale, :critical, :archived].include?(level)) ||
+        (config.fail_if_critical && [:critical, :archived].include?(level))
+    end
+
+    def failed_vulnerability?(name, data, config, suppressions)
+      setting = config.fail_if_vulnerable
+      return false unless setting
+
+      # Reason over the live advisory array (not vulnerability_count) so the gate
+      # and warn_unknown_severity_gate share one source of truth: a warning that
+      # says "failing" can never disagree with whether exit(1) actually fires.
+      live = live_advisories(name, data, suppressions)
+      return false if live.empty?
+
+      setting == true || VulnerabilityHelper.severity_at_or_above?(live, setting)
+    end
+
+    # The gem's advisories minus those an explicit .still_active.yml suppression
+    # accepts (by advisory id or alias). Shared by the vulnerability gate and the
+    # unknown-severity warning so both reason over the same live set.
+    def live_advisories(name, data, suppressions)
+      Array(data[:vulnerabilities]).reject do |vuln|
+        suppressions.suppressed?(gem: name, signal: :vulnerability, advisory: vuln[:id], aliases: Array(vuln[:aliases]))
       end
     end
+
+    def failed_outdated?(name, data, config, suppressions)
+      threshold = config.fail_if_outdated
+      return false unless threshold
+      return false if suppressions.suppressed?(gem: name, signal: :libyear)
+
+      data[:libyear] && data[:libyear] > threshold
+    end
   end
 end

data/lib/still_active/config.rb

@@ -3,16 +3,22 @@
 require "bundler"
 require "octokit"
 require "open3"
+require_relative "suppressions"
 
 module StillActive
   class Config
-    attr_writer :github_oauth_token, :gitlab_token, :gemfile_path
+    attr_writer :github_oauth_token, :gitlab_token, :forgejo_token, :artifactory_token, :artifactory_host, :gemfile_path, :ecosystems_email
+    attr_accessor :sbom_path
     attr_accessor :alternatives,
+      :unreleased_commits,
+      :direct_only,
       :baseline_path,
       :critical_warning_emoji,
       :cyclonedx_path,
       :cyclonedx_version,
       :fail_if_critical,
+      :fail_if_poison,
+      :fail_if_language_ceiling,
       :fail_if_warning,
       :futurist_emoji,
       :gems,
@@ -24,21 +30,31 @@ module StillActive
       :no_warning_range_end,
       :sarif_path,
       :success_emoji,
+      :suppressions,
       :unsure_emoji,
       :warning_emoji,
       :warning_range_end
 
     def initialize
       @alternatives = false
+      @unreleased_commits = false
+      @direct_only = false
       @fail_if_critical = false
+      @fail_if_poison = false
+      @fail_if_language_ceiling = false
       @fail_if_outdated = nil
       @fail_if_vulnerable = nil
       @fail_if_warning = false
       @gemfile_path = nil
       @gems = []
       @ignored_gems = []
+      @suppressions = Suppressions.from(nil)
       @github_oauth_token = nil
       @gitlab_token = nil
+      @forgejo_token = nil
+      @artifactory_token = nil
+      @artifactory_host = nil
+      @ecosystems_email = nil
 
       @parallelism = 10
 
@@ -54,7 +70,11 @@ module StillActive
       @unsure_emoji = "❓"
       @warning_emoji = "⚠️"
 
-      @no_warning_range_end = 1
+      # Release-age thresholds (years) calibrated against real RubyGems cadence,
+      # not the npm-derived 12-month convention: healthy mature gems routinely go
+      # 12-18 months between releases, so the ok ceiling is 18 months. > 3 years
+      # is critical. See #32.
+      @no_warning_range_end = 1.5
       @warning_range_end = 3
     end
 
@@ -64,13 +84,50 @@ module StillActive
     end
 
     def github_oauth_token
+      # Cache the resolution including a nil result: the token can't change
+      # mid-run, and provider selection now reads this per gem, so a plain ||=
+      # (which doesn't memoize nil) would re-shell `gh auth token` for every gem
+      # in a no-token run.
+      return @github_oauth_token if @github_oauth_token_resolved
+
+      # Assign before flipping the flag: gh_cli_token shells out and yields the
+      # async reactor, so a concurrent fiber must never see resolved=true while
+      # the value is still nil (it would wrongly route a tokened gem to the
+      # ecosyste.ms fallback). Worst case under contention is a few extra `gh`
+      # calls, never a premature nil; Workflow.call also resolves this once before
+      # the fan-out so the contended path isn't normally hit.
       @github_oauth_token ||= presence(ENV["GITHUB_TOKEN"]) || presence(ENV["GH_TOKEN"]) || gh_cli_token
+      @github_oauth_token_resolved = true
+      @github_oauth_token
     end
 
     def gitlab_token
       @gitlab_token ||= presence(ENV["GITLAB_TOKEN"]) || glab_cli_token
     end
 
+    # Codeberg/Forgejo has no ubiquitous CLI to borrow a token from (unlike
+    # gh/glab), so it's env-var only. Anonymous works for public repos; a token
+    # only raises the rate limit. CODEBERG_TOKEN is accepted as a convenience
+    # alias for the codeberg.org default host.
+    # Optional contact email for ecosyste.ms's "polite pool" (sent as a mailto
+    # query param), which raises the anonymous rate limit and lets them reach
+    # out. Nil by default -- anonymous is plenty for a typical lockfile.
+    def ecosystems_email
+      @ecosystems_email ||= presence(ENV["STILL_ACTIVE_ECOSYSTEMS_EMAIL"]&.strip)
+    end
+
+    def forgejo_token
+      @forgejo_token ||= presence(ENV["STILL_ACTIVE_FORGEJO_TOKEN"]) || presence(ENV["CODEBERG_TOKEN"])
+    end
+
+    def artifactory_token
+      @artifactory_token ||= presence(ENV["STILL_ACTIVE_ARTIFACTORY_TOKEN"])
+    end
+
+    def artifactory_host
+      @artifactory_host ||= presence(ENV["STILL_ACTIVE_ARTIFACTORY_HOST"])
+    end
+
     # Lazy so that running with --gems=... (no Gemfile needed) doesn't crash
     # when invoked from a directory without a Gemfile in the tree.
     def gemfile_path