gemxray 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a6d939f389ed77e696ee646dbde1ab0bb7a8ceedc557f842d28c18c98db4ce5
-  data.tar.gz: 34b0b557679c2fa045833d3c2058e5b31277a01f06d60a0ebcc178a7b244b695
+  metadata.gz: 32f1f088a0926c5f77d7246c4312cf41d797e629a54e9962a01c182910bbd6fb
+  data.tar.gz: 34309d8c477b7044430f191cc8819f21325c014da311597a33f6a4220079b783
 SHA512:
-  metadata.gz: e1acb06ca5efd7b530d81293f4560c02948301073abb51611a2bd34d6fa473329436bf07e354e0d22923a53b19183738375a1a82c85effedf181d4f2f6ba2ffe
-  data.tar.gz: bb4421e1c58449dd6143afa8520a60bd38b4f5011aa5451b65f17737cffa8c7ecd8d10bc36be84cc12fb1993b489aea55a8600d4f045dd34d025acb972b0527e
+  metadata.gz: a15b1a9f0021545e3d03576c65be972a366214ae8bfe4b0bb55ea4de918dd4fabbbdfa73fc931a9c50e1e1bb143addfc6cb5c4156d5b914806610aeeeca4844f
+  data.tar.gz: b2375769bbd5abc10503d4f2619f0ca35022cd9b72339cf3a267881fabc077843e5ef47a120eb3ab651a79dd8aabc2407e49f71d54d8530134b12badb015664f

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.2.0 (2026-04-06)
+
+- Add `--fail-on` option and `ci_fail_on` config field to control the minimum severity that causes `scan --ci` to exit with status 1. Previously, any finding triggered a failure; now only findings at or above the specified level do. The default is `warning`.
+
 ## 0.1.0 (2026-03-27)
 
 - Initial release.

data/README.md

@@ -1,14 +1,36 @@
 # 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`.
+[![Gem Version](https://badge.fury.io/rb/gemxray.svg)](https://badge.fury.io/rb/gemxray)
+[![CI](https://github.com/ydah/gemxray/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/gemxray/actions/workflows/main.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+A CLI that highlights gems you can likely remove from a Ruby project's `Gemfile`.
+
+GemXray combines three analyzers to find removal candidates:
+
+| Analyzer | What it detects |
+| --- | --- |
+| `unused` | No `require`, constant reference, gemspec dependency, or Rails autoload signal was found. |
+| `redundant` | Another top-level gem already brings the gem in through `Gemfile.lock`. |
+| `version` | The gem is already covered by your Ruby or Rails version (default/bundled gem). |
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+  - [Shared analysis options](#shared-analysis-options)
+  - [`scan`](#scan)
+  - [`clean`](#clean)
+  - [`pr`](#pr)
+  - [`init`](#init)
+  - [`version`](#version)
+  - [`help`](#help)
+- [Severity](#severity)
+- [Configuration](#configuration)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
@@ -43,7 +65,7 @@ bundle exec gemxray scan
 Use structured output for CI or scripts:
 
 ```bash
-bundle exec gemxray scan --format json --ci
+bundle exec gemxray scan --format json --ci --fail-on danger
 bundle exec gemxray scan --only unused,version --severity warning
 ```
 
@@ -70,27 +92,160 @@ bundle exec gemxray scan --gemfile path/to/Gemfile
 
 ## Commands
 
+If you run `gemxray` without a command, it behaves as `gemxray scan`.
+
 | Command | Purpose | Useful options |
 | --- | --- | --- |
-| `scan` | Analyze the Gemfile and print findings. | `--format`, `--only`, `--severity`, `--ci`, `--gemfile`, `--config` |
+| `scan` | Analyze the Gemfile and print findings. | `--format`, `--only`, `--severity`, `--ci`, `--fail-on`, `--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 |
+| `help` | Print top-level help. | none |
+
+### Shared analysis options
+
+`scan`, `clean`, and `pr` all build the same report first, so the options below change which findings are available to print, remove, or turn into pull requests.
+
+- `--gemfile PATH`
+  Selects the target Gemfile. This also changes the project root used for file edits, `bundle install`, and git operations, because the project root is derived from the Gemfile directory.
+- `--config PATH`
+  Loads a specific `.gemxray.yml` instead of the default file in the current working directory.
+- `--only unused,redundant,version`
+  Restricts analysis to the listed analyzers. This accepts a comma-separated list. For example, `--only unused` means `clean` and `pr` only act on unused-gem findings.
+- `--severity info|warning|danger`
+  Filters the report to findings at or above the selected severity. This happens before command-specific behavior, so hidden findings are also excluded from `clean`, `pr`, and `scan --ci`.
+- `--format terminal|json|yaml`
+  Controls output format for `scan`. `clean` and `pr` currently accept the option because they share the same parser, but they do not render the report, so `--format` has no visible effect on those commands today.
+- `--ci`
+  Only changes `scan`. When enabled, `scan` exits with status `1` if any reported finding matches `--fail-on` or `ci_fail_on` from config. `clean` and `pr` currently accept the flag but do not use it.
+- `--fail-on info|warning|danger`
+  Only changes `scan`, and only matters together with `--ci`. It sets the minimum reported severity that should return exit code `1`. `clean` and `pr` currently accept the flag but do not use it.
+- `-h`, `--help`
+  Prints help for the current command and exits with status `0`.
+
+### `scan`
+
+`scan` analyzes the target project, formats the resulting report, prints it to standard output, and exits without changing any files.
+
+Behavior:
+
+- It runs the selected analyzers, merges findings per gem, applies severity overrides, filters the report by `--severity`, and sorts results by severity and gem name.
+- With `--format terminal`, it prints a human-readable tree. With `json` or `yaml`, it prints machine-readable output including summary counts.
+- Without `--ci`, a successful scan exits with status `0` even if findings exist.
+- With `--ci`, the exit status becomes `1` when any reported finding reaches `--fail-on` or `ci_fail_on`.
+
+```bash
+bundle exec gemxray scan
+bundle exec gemxray scan --format json --ci --fail-on danger
+bundle exec gemxray scan --only unused --severity warning
+```
+
+### `clean`
+
+`clean` runs the same analysis pipeline as `scan`, then edits the Gemfile based on the reported results.
+
+Behavior:
+
+- Without `--auto-fix`, it prompts once per reported result: `Remove <gem> (<severity>)? [y/N]:`.
+- Only `y` and `yes` remove the gem. Any other answer skips it.
+- It edits the full detected source range, so multiline gem declarations are removed as a unit.
+- It writes a backup file at `Gemfile.bak` before saving changes.
+- If nothing is selected, it prints `No removable gems were selected.` and exits with status `0`.
+
+Command-specific options:
+
+- `--auto-fix` -- Skips prompts and removes every reported `danger` finding automatically. `warning` and `info` findings are never auto-removed.
+- `--dry-run` -- Does not write the Gemfile. Instead, it prints the selected candidates and a preview hunk showing the lines that would be removed or replaced.
+- `--comment` -- Replaces each removed gem entry with a comment such as `# Removed by gemxray: ...` instead of deleting the lines outright.
+- `--bundle`, `--no-bundle` -- After a real edit, `--bundle` runs `bundle install` in the target project. It is skipped automatically during `--dry-run` and when no gems were actually removed.
+
+```bash
+bundle exec gemxray clean
+bundle exec gemxray clean --auto-fix --severity danger
+bundle exec gemxray clean --dry-run --comment
+```
+
+### `pr`
+
+`pr` runs the same analysis pipeline as `scan`, edits the Gemfile, commits the changes on a new branch, pushes the branch, and opens a GitHub pull request.
+
+Behavior:
+
+- It fails if the report is empty after filters are applied.
+- It requires the target project to be inside a git repository with a clean worktree before it starts.
+- It switches to `github.base_branch`, creates a cleanup branch, edits the Gemfile, commits the change, optionally refreshes `Gemfile.lock`, pushes the branch, and opens a PR.
+- It tries `gh pr create` first. If `gh` is unavailable, it falls back to the GitHub API when `GH_TOKEN` or `GITHUB_TOKEN` is set.
+- The PR body includes removed gems, detection reasons, and a short checklist.
+
+Command-specific options:
+
+- `--per-gem` -- Creates one branch and one pull request per reported gem instead of grouping everything into a single cleanup PR.
+- `--comment` -- Leaves comments in the Gemfile instead of deleting lines, using the same replacement behavior as `clean --comment`.
+- `--bundle`, `--no-bundle` -- Controls whether `pr` runs `bundle install` before committing. The default is `--bundle` (from `github.bundle_install: true`).
+
+```bash
+bundle exec gemxray pr
+bundle exec gemxray pr --per-gem --no-bundle
+bundle exec gemxray pr --only unused --severity danger
+```
+
+### `init`
+
+`init` writes a starter `.gemxray.yml` into the current working directory.
+
+- It does not read `--config`; it always writes `.gemxray.yml` in the directory where you run the command.
+- If the file already exists, the command fails unless you pass `--force`.
+
+```bash
+bundle exec gemxray init
+bundle exec gemxray init --force
+```
+
+### `version`
+
+Prints the installed gemxray version and exits with status `0`.
+
+```bash
+bundle exec gemxray version
+```
+
+### `help`
+
+Prints the top-level command summary and exits with status `0`.
+
+```bash
+bundle exec gemxray help
+bundle exec gemxray --help
+bundle exec gemxray scan --help
+```
 
 ## 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.
+| Level | Meaning | Auto-fix target |
+| --- | --- | --- |
+| `danger` | High-confidence removal candidate. | Yes (`clean --auto-fix` removes these) |
+| `warning` | Likely removable, but worth a quick review. | No |
+| `info` | Informative hint (pinned versions, lower-confidence redundancy). | No |
 
 ## Configuration
 
 `gemxray` reads `.gemxray.yml` from the working directory unless you pass `--config PATH`.
 
+The effective config is built in this order:
+
+1. Built-in defaults
+2. `.gemxray.yml`
+3. CLI options for the current run
+
+Later scalar values override earlier ones. Array values (`scan_dirs`, `whitelist`, `github.labels`, `github.reviewers`) are merged and deduplicated.
+
 ```yaml
 version: 1
 
+ci: false
+ci_fail_on: warning
+
 whitelist:
   - bootsnap
   - tzinfo-data
@@ -115,30 +270,45 @@ github:
   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`.
+### Top-level fields
 
-## 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.
+| Field | Default | Description |
+| --- | --- | --- |
+| `version` | `1` | Schema marker for future compatibility. Currently accepted but does not change behavior. |
+| `gemfile_path` | `Gemfile` | Path to the target Gemfile. Expanded from the current working directory. |
+| `format` | `terminal` | Output format for `scan`. Accepted: `terminal`, `json`, `yaml`. |
+| `only` | all | Restricts analysis to listed analyzers: `unused`, `redundant`, `version`. |
+| `severity` | `info` | Minimum severity kept in the report. Also limits what `clean`, `pr`, and `scan --ci` can act on. |
+| `ci` | `false` | Enables CI-style exit codes for `scan`. |
+| `ci_fail_on` | `warning` | Minimum severity that makes `scan --ci` exit with status `1`. |
+| `auto_fix` | `false` | When `true`, `clean` removes `danger` findings without prompting. |
+| `dry_run` | `false` | When `true`, `clean` previews changes without writing the Gemfile. |
+| `comment` | `false` | When `true`, gem entries are replaced with comments instead of being deleted. |
+| `bundle_install` | `false` | When `true`, `clean` runs `bundle install` after editing. Does not affect `pr`. |
+| `whitelist` | `[]` | Gem names to skip completely. |
+| `scan_dirs` | `[]` | Extra directories added to the built-in scan roots (`app`, `lib`, `config`, `db`, `script`, `bin`, `exe`, `spec`, `test`, `tasks`). |
+| `redundant_depth` | `2` | Maximum dependency depth for the `redundant` analyzer in `Gemfile.lock`. |
+| `overrides` | `{}` | Per-gem overrides keyed by gem name. |
+
+### Override fields
+
+`overrides.<gem>.severity` accepts `ignore`, `info`, `warning`, or `danger`.
+
+- `ignore` skips the gem before analysis (no finding is produced).
+- `info`, `warning`, `danger` force the final reported severity after analyzers run.
+
+### GitHub fields
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `github.base_branch` | `main` | Base branch that `pr` checks out before creating the cleanup branch. |
+| `github.labels` | `["dependencies", "cleanup"]` | Labels applied to created PRs. Custom labels are added to defaults (arrays are merged). |
+| `github.reviewers` | `[]` | Reviewers requested on created PRs. |
+| `github.per_gem` | `false` | When `true`, `pr` creates one branch and one PR per gem. |
+| `github.bundle_install` | `true` | Controls whether `pr` runs `bundle install` before committing. |
 
 ## Development
 
-Install dependencies and run the test suite:
-
 ```bash
 bundle install
 bundle exec rspec
@@ -149,3 +319,11 @@ Run the executable locally:
 ```bash
 ruby exe/gemxray scan --format terminal
 ```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/ydah/gemxray).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/gemxray/cli.rb

@@ -62,7 +62,7 @@ module GemXray
       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
+      config.ci_failure?(report.results) ? 1 : 0
     end
 
     def run_clean(argv)
@@ -187,7 +187,10 @@ module GemXray
       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("--fail-on LEVEL", %w[info warning danger], "minimum reported severity that makes --ci exit 1") do |value|
+        options[:ci_fail_on] = value
+      end
+      parser.on("--ci", "exit with status 1 when findings at or above fail-on level 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)

data/lib/gemxray/config.rb

@@ -14,6 +14,7 @@ module GemXray
       auto_fix: false,
       dry_run: false,
       ci: false,
+      ci_fail_on: "warning",
       comment: false,
       bundle_install: false,
       whitelist: [],
@@ -32,6 +33,9 @@ module GemXray
     TEMPLATE = <<~YAML.freeze
       version: 1
 
+      ci: false
+      ci_fail_on: warning
+
       whitelist:
         - bootsnap
         - tzinfo-data
@@ -55,7 +59,7 @@ module GemXray
     YAML
 
     attr_reader :config_path, :gemfile_path, :format, :only, :severity_threshold, :whitelist,
-                :scan_dirs, :overrides, :redundant_depth, :github
+                :scan_dirs, :overrides, :redundant_depth, :github, :ci_fail_threshold
 
     def self.load(options = {})
       raw_options = symbolize_keys(options)
@@ -103,6 +107,7 @@ module GemXray
       @format = options.fetch(:format).to_s
       @only = normalize_only(options[:only])
       @severity_threshold = normalize_severity(options.fetch(:severity))
+      @ci_fail_threshold = normalize_severity(options.fetch(:ci_fail_on))
       @whitelist = Array(options[:whitelist]).map(&:to_s).uniq
       @scan_dirs = (DEFAULT_SCAN_DIRS + Array(options[:scan_dirs]).map(&:to_s)).uniq
       @overrides = options.fetch(:overrides, {})
@@ -135,6 +140,12 @@ module GemXray
       @ci
     end
 
+    def ci_failure?(results)
+      return false unless ci?
+
+      Array(results).any? { |result| severity_matches_threshold?(result.severity, ci_fail_threshold) }
+    end
+
     def comment?
       @comment
     end
@@ -165,7 +176,7 @@ module GemXray
     end
 
     def severity_in_scope?(severity)
-      SEVERITY_ORDER.fetch(severity) <= SEVERITY_ORDER.fetch(severity_threshold)
+      severity_matches_threshold?(severity, severity_threshold)
     end
 
     def github_base_branch
@@ -211,5 +222,9 @@ module GemXray
     def truthy?(value)
       value == true || value.to_s == "true"
     end
+
+    def severity_matches_threshold?(severity, threshold)
+      SEVERITY_ORDER.fetch(severity) <= SEVERITY_ORDER.fetch(threshold)
+    end
   end
 end

data/lib/gemxray/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GemXray
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemxray
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yudai Takada