gemxray 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a6d939f389ed77e696ee646dbde1ab0bb7a8ceedc557f842d28c18c98db4ce5
+  data.tar.gz: 34b0b557679c2fa045833d3c2058e5b31277a01f06d60a0ebcc178a7b244b695
+SHA512:
+  metadata.gz: e1acb06ca5efd7b530d81293f4560c02948301073abb51611a2bd34d6fa473329436bf07e354e0d22923a53b19183738375a1a82c85effedf181d4f2f6ba2ffe
+  data.tar.gz: bb4421e1c58449dd6143afa8520a60bd38b4f5011aa5451b65f17737cffa8c7ecd8d10bc36be84cc12fb1993b489aea55a8600d4f045dd34d025acb972b0527e

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 (2026-03-27)
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,151 @@
+# GemXray
+
+`gemxray` is a CLI that highlights gems you can likely remove from a Ruby project's `Gemfile`.
+
+It combines three analyzers:
+
+1. `unused`: no `require`, constant reference, gemspec dependency, or Rails autoload signal was found.
+2. `redundant`: another top-level gem already brings the gem in through `Gemfile.lock`.
+3. `version-redundant`: the gem is already covered by your Ruby or Rails version.
+
+If you run `gemxray` without a command, it defaults to `scan`.
+
+## Installation
+
+Add the gem to your toolchain:
+
+```bash
+bundle add gemxray --group development
+```
+
+Or install it directly:
+
+```bash
+gem install gemxray
+```
+
+If you install the gem globally, replace `bundle exec gemxray` with `gemxray` in the examples below.
+
+## Quick Start
+
+Generate a starter config:
+
+```bash
+bundle exec gemxray init
+```
+
+Scan the current project:
+
+```bash
+bundle exec gemxray scan
+```
+
+Use structured output for CI or scripts:
+
+```bash
+bundle exec gemxray scan --format json --ci
+bundle exec gemxray scan --only unused,version --severity warning
+```
+
+Preview or apply Gemfile cleanup:
+
+```bash
+bundle exec gemxray clean --dry-run
+bundle exec gemxray clean
+bundle exec gemxray clean --auto-fix
+```
+
+Create a cleanup branch and open a pull request:
+
+```bash
+bundle exec gemxray pr
+bundle exec gemxray pr --per-gem --no-bundle
+```
+
+Target a different project by passing a Gemfile path:
+
+```bash
+bundle exec gemxray scan --gemfile path/to/Gemfile
+```
+
+## Commands
+
+| Command | Purpose | Useful options |
+| --- | --- | --- |
+| `scan` | Analyze the Gemfile and print findings. | `--format`, `--only`, `--severity`, `--ci`, `--gemfile`, `--config` |
+| `clean` | Remove selected gems from `Gemfile`. | `--dry-run`, `--auto-fix`, `--comment`, `--[no-]bundle` |
+| `pr` | Create a branch, commit the cleanup, and open a GitHub PR. | `--per-gem`, `--[no-]bundle`, `--comment` |
+| `init` | Write a starter `.gemxray.yml`. | `--force` |
+| `version` | Print the installed gemxray version. | none |
+
+## Severity
+
+- `danger`: high-confidence removal candidate. `clean --auto-fix` only removes `danger` findings.
+- `warning`: likely removable, but worth a quick review.
+- `info`: informative hint, often tied to pinned versions or lower-confidence redundancy.
+
+## Configuration
+
+`gemxray` reads `.gemxray.yml` from the working directory unless you pass `--config PATH`.
+
+```yaml
+version: 1
+
+whitelist:
+  - bootsnap
+  - tzinfo-data
+
+scan_dirs:
+  - engines/billing/app
+  - engines/billing/lib
+
+redundant_depth: 2
+
+overrides:
+  puma:
+    severity: ignore
+
+github:
+  base_branch: main
+  labels:
+    - dependencies
+    - cleanup
+  reviewers: []
+  per_gem: false
+  bundle_install: true
+```
+
+Config fields:
+
+- `whitelist`: gems to skip entirely.
+- `scan_dirs`: extra directories to scan in addition to the defaults: `app`, `lib`, `config`, `db`, `script`, `bin`, `exe`, `spec`, `test`, and `tasks`.
+- `redundant_depth`: maximum dependency depth for redundant gem detection.
+- `overrides.<gem>.severity`: override a finding severity with `ignore`, `info`, `warning`, or `danger`.
+- `github.*`: defaults used by `pr`.
+
+## Notes
+
+- `clean` writes `Gemfile.bak` before editing the file.
+- `clean` removes the full source range for multiline gem declarations.
+- `clean --bundle` runs `bundle install` after editing.
+- `pr` runs `bundle install` before committing by default. Use `pr --no-bundle` to skip it.
+- `pr` requires a clean git worktree before it creates branches or commits.
+- `pr` switches to `github.base_branch` before creating the cleanup branch.
+- If `gh` is unavailable, `pr` falls back to the GitHub API when `GH_TOKEN` or `GITHUB_TOKEN` is set.
+- Ruby default and bundled gem checks use cached stdgems data when available and bundled offline data otherwise.
+- Rails version hints come from the bundled `data/rails_changes.yml` dataset.
+
+## Development
+
+Install dependencies and run the test suite:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+Run the executable locally:
+
+```bash
+ruby exe/gemxray scan --format terminal
+```

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/data/rails_changes.yml

@@ -0,0 +1,6 @@
+versions:
+  "6.0":
+    removals:
+      - gem: zeitwerk
+        reason: "Rails 6 enables Zeitwerk mode by default, so an explicit gem entry is usually unnecessary"
+        source: "https://guides.rubyonrails.org/upgrading_ruby_on_rails.html"

data/exe/gemxray

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/gemxray"
+
+exit GemXray::CLI.start(ARGV)

data/lib/gemxray/analyzers/base.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module GemXray
+  module Analyzers
+    class Base
+      AUTOLOADED_GEMS = %w[
+        bootsnap devise sidekiq sidekiq-cron delayed_job_active_record good_job
+        letter_opener_web rack-mini-profiler spring sprockets-rails turbo-rails
+        stimulus-rails importmap-rails propshaft web-console solid_queue
+        solid_cache solid_cable
+      ].freeze
+
+      def initialize(config:, gemfile_parser:, code_snapshot: nil, dependency_resolver: nil, stdgems_client: nil,
+                     rails_knowledge: nil, gem_metadata_resolver: GemMetadataResolver.new)
+        @config = config
+        @gemfile_parser = gemfile_parser
+        @code_snapshot = code_snapshot
+        @dependency_resolver = dependency_resolver
+        @stdgems_client = stdgems_client
+        @rails_knowledge = rails_knowledge
+        @gem_metadata_resolver = gem_metadata_resolver
+      end
+
+      private
+
+      attr_reader :config, :gemfile_parser, :code_snapshot, :dependency_resolver, :stdgems_client, :rails_knowledge,
+                  :gem_metadata_resolver
+
+      def skipped?(gem_entry)
+        config.whitelisted?(gem_entry.name) || config.ignore_gem?(gem_entry.name)
+      end
+
+      def build_result(gem_entry:, type:, severity:, detail:)
+        Result.new(
+          gem_name: gem_entry.name,
+          gemfile_line: gem_entry.line_number,
+          gemfile_end_line: gem_entry.end_line,
+          gemfile_group: gem_entry.gemfile_group,
+          reasons: [Result::Reason.new(type: type, detail: detail, severity: severity)],
+          severity: severity
+        )
+      end
+
+      def require_candidates(gem_entry)
+        gem_entry.require_names.uniq
+      end
+
+      def constant_candidates(gem_entry)
+        gem_metadata_resolver.constant_candidates_for(gem_entry.name, version_requirement: gem_entry.version)
+      end
+
+      def autoloaded_gem?(gem_entry)
+        return true if AUTOLOADED_GEMS.include?(gem_entry.name)
+
+        gem_metadata_resolver.railtie?(gem_entry.name, version_requirement: gem_entry.version)
+      end
+    end
+  end
+end

data/lib/gemxray/analyzers/redundant_analyzer.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module GemXray
+  module Analyzers
+    class RedundantAnalyzer < Base
+      def analyze(gems)
+        gem_names = gems.map(&:name)
+
+        gems.filter_map do |gem_entry|
+          next if skipped?(gem_entry)
+
+          path = dependency_resolver.find_parent(
+            target: gem_entry.name,
+            roots: gem_names - [gem_entry.name],
+            max_depth: config.redundant_depth
+          )
+          next unless path
+          next unless compatible_dependency?(gem_entry, path[:edges].last)
+
+          detail = "already installed as a dependency of #{path[:gems].first}"
+          detail = "#{detail} (#{path[:gems].join(' -> ')})" if path[:gems].length > 2
+
+          result = build_result(
+            gem_entry: gem_entry,
+            type: :redundant,
+            severity: gem_entry.pinned_version? ? :info : :warning,
+            detail: detail
+          )
+
+          if gem_entry.pinned_version?
+            result.add_reason(
+              type: :redundant,
+              severity: :info,
+              detail: "version is pinned in Gemfile (#{gem_entry.version}), so this may be intentional"
+            )
+          end
+
+          result
+        end
+      end
+
+      private
+
+      def compatible_dependency?(gem_entry, edge)
+        return true unless gem_entry.pinned_version?
+
+        requirement = edge.requirement
+        return true unless requirement
+
+        pinned_requirement = Gem::Requirement.new(gem_entry.version)
+        resolved_version = gemfile_parser.resolved_version(gem_entry.name)
+        if resolved_version
+          return pinned_requirement.satisfied_by?(resolved_version) && requirement.satisfied_by?(resolved_version)
+        end
+
+        allowed_versions = sample_versions_for(gem_entry.version)
+
+        allowed_versions.any? do |version|
+          pinned_requirement.satisfied_by?(version) && requirement.satisfied_by?(version)
+        end
+      rescue ArgumentError
+        false
+      end
+
+      def sample_versions_for(requirement_string)
+        versions = requirement_string.scan(/\d+(?:\.\d+)+/).map { |value| Gem::Version.new(value) }
+        versions << Gem::Version.new(requirement_string[/\d+(?:\.\d+)+/] || "0")
+        versions.uniq
+      end
+    end
+  end
+end

data/lib/gemxray/analyzers/unused_analyzer.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module GemXray
+  module Analyzers
+    class UnusedAnalyzer < Base
+      KNOWN_DEV_TOOLS = %w[
+        brakeman bundler-audit byebug capistrano capistrano-rails codecov
+        debug factory_bot factory_bot_rails faker overcommit pry pry-rails
+        rake rspec rspec-core rspec-rails rubocop rubocop-performance
+        rubocop-rails rubocop-rspec simplecov
+      ].freeze
+
+      def analyze(gems)
+        gems.filter_map do |gem_entry|
+          next if skipped?(gem_entry)
+          next if KNOWN_DEV_TOOLS.include?(gem_entry.name)
+          next if gem_used?(gem_entry)
+
+          detail =
+            if gem_entry.development_group?
+              "no usage found in code (group :development / :test)"
+            else
+              "no require or constant reference was found in the scanned code"
+            end
+
+          build_result(
+            gem_entry: gem_entry,
+            type: :unused,
+            severity: gem_entry.development_group? ? :warning : :danger,
+            detail: detail
+          )
+        end
+      end
+
+      private
+
+      def gem_used?(gem_entry)
+        code_snapshot.require_used?(require_candidates(gem_entry)) ||
+          code_snapshot.constant_used?(constant_candidates(gem_entry)) ||
+          code_snapshot.dependency_used?(gem_entry.name) ||
+          autoloaded_gem?(gem_entry)
+      end
+    end
+  end
+end

data/lib/gemxray/analyzers/version_analyzer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module GemXray
+  module Analyzers
+    class VersionAnalyzer < Base
+      def analyze(gems)
+        ruby_version = gemfile_parser.ruby_version
+        rails_version = gemfile_parser.rails_version(gems)
+        default_gems = stdgems_client.default_gems_for(ruby_version)
+        bundled_gems = stdgems_client.bundled_gems_for(ruby_version)
+
+        gems.each_with_object([]) do |gem_entry, results|
+          next if skipped?(gem_entry)
+
+          if default_gems.include?(gem_entry.name) && !gem_entry.pinned_version?
+            results << build_result(
+              gem_entry: gem_entry,
+              type: :version_redundant,
+              severity: :warning,
+              detail: "Ruby #{ruby_version} already ships this as a default gem"
+            )
+          elsif bundled_gems.include?(gem_entry.name) && !gem_entry.pinned_version?
+            results << build_result(
+              gem_entry: gem_entry,
+              type: :version_redundant,
+              severity: :warning,
+              detail: "Ruby #{ruby_version} already ships this as a bundled gem"
+            )
+          end
+
+          change = rails_knowledge.find_removal(gem_entry.name, rails_version)
+          next unless change
+
+          results << build_result(
+            gem_entry: gem_entry,
+            type: :version_redundant,
+            severity: :warning,
+            detail: "since Rails #{change.since}, #{change.reason}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/gemxray/cli.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module GemXray
+  class CLI
+    HelpRequested = Class.new(StandardError)
+    COMMANDS = %w[scan clean pr init version help].freeze
+
+    def self.start(argv = ARGV, out: $stdout, err: $stderr, stdin: $stdin)
+      new(argv, out: out, err: err, stdin: stdin).run
+    end
+
+    def initialize(argv, out:, err:, stdin:)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @stdin = stdin
+    end
+
+    def run
+      command = extract_command
+
+      case command
+      when "scan" then run_scan(@argv)
+      when "clean" then run_clean(@argv)
+      when "pr" then run_pr(@argv)
+      when "init" then run_init(@argv)
+      when "version"
+        out.puts(GemXray::VERSION)
+        0
+      else
+        out.puts(help_text)
+        0
+      end
+    rescue HelpRequested
+      0
+    rescue OptionParser::ParseError => e
+      err.puts(e.message)
+      err.puts(help_text)
+      1
+    rescue Error => e
+      err.puts("Error: #{e.message}")
+      1
+    end
+
+    private
+
+    attr_reader :out, :err, :stdin
+
+    def extract_command
+      return "scan" if @argv.empty?
+      return "help" if %w[-h --help].include?(@argv.first)
+      return "scan" if @argv.first.start_with?("-")
+
+      return @argv.shift if COMMANDS.include?(@argv.first)
+
+      "scan"
+    end
+
+    def run_scan(argv)
+      config = Config.load(parse_scan_options(argv))
+      report = Scanner.new(config).run
+      out.puts(formatter_for(config.format).render(report))
+      config.ci? && report.results.any? ? 1 : 0
+    end
+
+    def run_clean(argv)
+      options = parse_clean_options(argv)
+      config = Config.load(options)
+      report = Scanner.new(config).run
+      candidates = config.auto_fix? ? report.results.select(&:danger?) : interactive_selection(report.results)
+
+      if candidates.empty?
+        out.puts("No removable gems were selected.")
+        return 0
+      end
+
+      editor = Editors::GemfileEditor.new(config.gemfile_path)
+      outcome = editor.apply(candidates, dry_run: config.dry_run?, comment: config.comment?, backup: true)
+      out.puts("Candidates: #{candidates.map(&:gem_name).join(', ')}")
+      out.puts(outcome.preview) if config.dry_run? && !outcome.preview.to_s.empty?
+      out.puts("Removed: #{outcome.removed.join(', ')}") unless outcome.removed.empty?
+      out.puts("Skipped: #{outcome.skipped.join(', ')}") unless outcome.skipped.empty?
+      if config.bundle_install? && !config.dry_run? && outcome.removed.any?
+        out.puts(editor.bundle_install!)
+      end
+      0
+    end
+
+    def run_pr(argv)
+      options = parse_pr_options(argv)
+      config = Config.load(options)
+      report = Scanner.new(config).run
+      raise Error, "no PR candidates were found" if report.results.empty?
+
+      result = Editors::GithubPr.new(config).create(
+        report.results,
+        per_gem: options.fetch(:per_gem, config.github_per_gem?),
+        bundle_install: options.fetch(:bundle_install, config.github_bundle_install?),
+        comment: config.comment?
+      )
+
+      pull_requests = Array(result[:pull_requests])
+      if pull_requests.length <= 1
+        out.puts("Branch: #{result[:branch]}")
+        out.puts("PR: #{result[:pr_url]}")
+      else
+        out.puts("Created #{pull_requests.length} PRs:")
+        pull_requests.each do |pull_request|
+          label = pull_request[:gem_name] || Array(pull_request[:gem_names]).join(", ")
+          out.puts("#{label}: #{pull_request[:pr_url]} (#{pull_request[:branch]})")
+        end
+      end
+      0
+    end
+
+    def run_init(argv)
+      options = { force: false }
+      OptionParser.new do |parser|
+        parser.banner = "Usage: gemxray init [--force]"
+        parser.on("--force", "overwrite an existing config file") { options[:force] = true }
+        parser.on("-h", "--help", "show help") do
+          out.puts(parser)
+          raise HelpRequested
+        end
+      end.parse!(argv)
+
+      path = File.expand_path(Config::DEFAULT_CONFIG_PATH)
+      if File.exist?(path) && !options[:force]
+        raise Error, "#{Config::DEFAULT_CONFIG_PATH} already exists"
+      end
+
+      File.write(path, Config::TEMPLATE)
+      out.puts("created #{Config::DEFAULT_CONFIG_PATH}")
+      0
+    end
+
+    def parse_scan_options(argv)
+      options = {}
+
+      OptionParser.new do |parser|
+        parser.banner = "Usage: gemxray scan [options]"
+        common_options(parser, options)
+      end.parse!(argv)
+
+      options
+    end
+
+    def parse_clean_options(argv)
+      options = {}
+
+      OptionParser.new do |parser|
+        parser.banner = "Usage: gemxray clean [options]"
+        common_options(parser, options)
+        parser.on("--auto-fix", "remove only danger level gems without prompting") { options[:auto_fix] = true }
+        parser.on("--dry-run", "show targets without writing Gemfile") { options[:dry_run] = true }
+        parser.on("--comment", "leave a comment in place of the removed gem line") { options[:comment] = true }
+        parser.on("--[no-]bundle", "run bundle install after editing") { |value| options[:bundle_install] = value }
+      end.parse!(argv)
+
+      options
+    end
+
+    def parse_pr_options(argv)
+      options = {}
+
+      OptionParser.new do |parser|
+        parser.banner = "Usage: gemxray pr [options]"
+        common_options(parser, options)
+        parser.on("--[no-]bundle", "run bundle install before committing (default: yes)") do |value|
+          options[:bundle_install] = value
+        end
+        parser.on("--comment", "leave comments in Gemfile instead of deleting lines") { options[:comment] = true }
+        parser.on("--per-gem", "create one PR per gem") { options[:per_gem] = true }
+      end.parse!(argv)
+
+      options
+    end
+
+    def common_options(parser, options)
+      parser.on("-f", "--format FORMAT", %w[terminal json yaml], "output format") { |value| options[:format] = value }
+      parser.on("-g", "--gemfile PATH", "path to Gemfile") { |value| options[:gemfile_path] = value }
+      parser.on("--only LIST", "comma separated analyzers (unused,redundant,version)") do |value|
+        options[:only] = value.split(",")
+      end
+      parser.on("--severity LEVEL", %w[info warning danger], "minimum severity to report") do |value|
+        options[:severity] = value
+      end
+      parser.on("--ci", "exit with status 1 when issues are found") { options[:ci] = true }
+      parser.on("--config PATH", "path to .gemxray.yml") { |value| options[:config_path] = value }
+      parser.on("-h", "--help", "show help") do
+        out.puts(parser)
+        raise HelpRequested
+      end
+    end
+
+    def formatter_for(format)
+      case format
+      when "terminal" then Formatters::Terminal.new
+      when "json" then Formatters::Json.new
+      when "yaml" then Formatters::Yaml.new
+      else
+        raise Error, "unknown format: #{format}"
+      end
+    end
+
+    def interactive_selection(results)
+      results.filter_map do |result|
+        out.print("Remove #{result.gem_name} (#{result.severity})? [y/N]: ")
+        answer = stdin.gets.to_s.strip.downcase
+        result if answer == "y" || answer == "yes"
+      end
+    end
+
+    def help_text
+      <<~TEXT
+        gemxray [COMMAND] [OPTIONS]
+
+        Commands:
+          scan     Analyze Gemfile and report removable gems
+          clean    Interactively remove reported gems from Gemfile
+          pr       Create a cleanup branch, commit, and open a GitHub PR
+          init     Generate .gemxray.yml
+          version  Print gemxray version
+      TEXT
+    end
+  end
+end