Know your Ruby/Rails upgrade cost before you start.
Upgrade Radar is a static analysis gem that scans your codebase for deprecations and breaking changes between Ruby/Rails versions. Run one command and get a full report — what will break, where, why, and how long it will take to fix — before you touch the version number.
$ upgrade_radar scan --from rails-7.2 --to rails-8.0
Upgrade Radar v0.1.0
Scanning for: rails-7.2 → rails-8.0
Files scanned: 247
app/models/lead.rb
[BREAKS] Line 4: Positional hash argument to `enum` is deprecated in Rails 7.2 and removed in 8.0.
Source: enum status: { draft: 0, published: 1, archived: 2 }
Fix: enum :status, { active: 0, inactive: 1 }
Docs: https://guides.rubyonrails.org/upgrading_ruby_on_rails.html#enumerations
app/models/profile.rb
[BREAKS] Line 5: `serialize` requires an explicit `coder:` keyword argument in Rails 7.1+.
Source: serialize :tags, Array
Fix: serialize :attr, coder: JSON
app/controllers/api_controller.rb
[BREAKS] Line 17: `params.require(:x).permit(...)` is deprecated in Rails 8.0.
Source: params.require(:user).permit(:name, :email)
Fix: params.expect(user: [:name, :email])
============================================================
UPGRADE SUMMARY
============================================================
Total findings: 14
Breaking: 11
Warnings: 3
Files affected: 8
Estimated effort: ~2.5 hours (small)
Scan completed in 0.03s
- The Problem
- Installation
- Quick Start
- Commands
- Output Formats
- Configuration
- Runtime Mode
- Built-in Rules
- Custom Rules
- Architecture
- Comparison with Existing Tools
- Development
- License
Upgrading Ruby (say 3.3 → 3.4) or Rails (7.2 → 8.0) usually goes like this:
- Bump the version
- Run tests
- Watch things break
- Dig through changelogs to figure out why
- Repeat for weeks
For a big app, you can't easily estimate the effort beforehand. You don't know if it's a 2-hour job or a 2-week project until you're in the middle of it.
Upgrade Radar solves this. Before upgrading, you run one command and get a complete report — every breaking change and deprecation in your codebase, with the exact file, line, fix, and documentation link. You know the cost before you start.
# Gemfile
gem "upgrade_radar", group: :developmentThen run:
bundle installgem install upgrade_radar- Ruby >= 3.2.0 (uses the Prism parser, Ruby's official AST parser since 3.3)
- No Rails dependency for static analysis — works on any Ruby project
upgrade_radar scan --from rails-7.2 --to rails-8.0upgrade_radar scan --from ruby-3.3 --to ruby-3.4upgrade_radar scan --from rails-7.2 --to rails-8.0 --format json --output report.jsonThe exit code is 1 when breaking changes are found, 0 otherwise — so you can gate CI on it.
The main command. Scans your codebase and reports findings.
Usage:
upgrade_radar scan --from FROM --to TO
Options:
--from Source version (e.g., rails-7.2, ruby-3.3) [required]
--to Target version (e.g., rails-8.0, ruby-3.4) [required]
--path Path to scan (default: current directory)
--format Output format: text, json, html (default: text)
--output Write report to file instead of stdout
--exclude Glob patterns to exclude (e.g., vendor/** tmp/**)
--config Path to config file
Examples:
# Scan only the app directory
upgrade_radar scan --from rails-7.2 --to rails-8.0 --path app/
# Exclude vendor and generated files
upgrade_radar scan --from rails-7.2 --to rails-8.0 --exclude vendor/** db/schema.rb
# Generate an HTML report
upgrade_radar scan --from rails-7.2 --to rails-8.0 --format html --output upgrade_report.htmlList all rules that apply for a version range, without scanning any files.
upgrade_radar rules --from rails-7.2 --to rails-8.0
upgrade_radar rules --from ruby-3.2 --to ruby-3.4 --format jsonupgrade_radar version
# upgrade_radar 0.1.0Colorized terminal output with [BREAKS] and [WARN] badges, grouped by file. Includes an effort summary at the bottom.
Structured output for CI pipelines and tooling:
{
"metadata": {
"upgrade_radar_version": "0.1.0",
"from": "rails-7.2",
"to": "rails-8.0",
"scanned_at": "2026-10-27T15:45:28+0530",
"scan_duration_seconds": 0.012,
"files_scanned": 247
},
"summary": {
"total_findings": 14,
"breaking": 11,
"warnings": 3,
"files_affected": 8,
"total_effort_minutes": 150,
"total_effort_human": "~2.5 hours",
"effort_level": "small"
},
"findings": [
{
"id": "rails-7.2-enum-keyword-args",
"severity": "breaking",
"file": "app/models/lead.rb",
"line": 4,
"message": "Positional hash argument to `enum` is deprecated...",
"replacement": "enum :status, { active: 0, inactive: 1 }",
"docs": "https://guides.rubyonrails.org/...",
"effort_minutes": 5
}
]
}A standalone, self-contained HTML report with dark mode support, severity badges, and effort summary cards. Suitable for sharing with the team.
upgrade_radar scan --from rails-7.2 --to rails-8.0 --format html --output report.htmlCreate .upgrade_radar.yml in your project root to set defaults:
# .upgrade_radar.yml
exclude:
- vendor/**
- tmp/**
- log/**
- db/schema.rb
- node_modules/**
custom_rules_path: ./my_rules/The following paths are excluded by default: vendor/**, node_modules/**, tmp/**, log/**.
Some deprecations only surface at runtime — for example, Rails deprecation warnings emitted during test execution. Upgrade Radar provides optional hooks to capture these.
# spec/spec_helper.rb
require "upgrade_radar/runtime/middleware"
UpgradeRadar::Runtime::Middleware.setup_for_rspec# test/test_helper.rb
require "upgrade_radar/runtime/middleware"
collector = UpgradeRadar::Runtime::Middleware.setup_for_minitest- Rails deprecations via
ActiveSupport::Deprecation(Rails 7.1+ deprecators API and legacy API) - Ruby deprecations via
Warning[:deprecated](Ruby 3.0+)
Captured warnings are printed after the test suite with file/line information.
Upgrade Radar ships with 19 rules covering the most impactful breaking changes in recent Rails and Ruby versions.
| Rule ID | What It Detects | Introduced | Breaks |
|---|---|---|---|
rails-7.1-serialize-coder |
serialize without explicit coder: keyword |
7.1 | 8.0 |
rails-7.2-enum-keyword-args |
Old-style enum status: {} hash syntax |
7.2 | 8.0 |
rails-7.2-secrets-removed |
Rails.application.secrets usage |
7.2 | 7.2 |
rails-7.2-alias-attribute |
alias_attribute bypassing custom accessors |
7.2 | 7.2 |
rails-8.0-connection-pool |
connection_pool.connection (removed) |
8.0 | 8.0 |
rails-8.0-params-expect |
params.require(:x).permit(...) chain |
8.0 | 8.0 |
rails-8.0-proxy-object |
ActiveSupport::ProxyObject (removed) |
8.0 | 8.0 |
rails-8.0-form-with-nil |
form_with model: nil (invalid) |
8.0 | 8.0 |
rails-8.0-read-encrypted-secrets |
config.read_encrypted_secrets (removed) |
8.0 | 8.0 |
| Rule ID | What It Detects | Introduced | Breaks |
|---|---|---|---|
ruby-3.3-it-block-param |
Bare it in parameterless blocks |
3.3 | 3.4 |
ruby-3.3-default-gems-bundled |
require 'csv' etc. without Gemfile entry |
3.3 | 3.4 |
ruby-3.3-lambda-proc |
lambda(&non_lambda_proc) |
3.3 | 3.3 |
ruby-3.3-time-new-string |
Time.new("2024-01-15") partial strings |
3.3 | 3.3 |
ruby-3.3-io-pipe |
IO.read("| cmd") pipe prefix |
3.3 | 3.3 |
ruby-3.4-kwargs-index |
obj[1, key: val] kwargs in [] |
3.4 | 3.4 |
ruby-3.4-range-size |
Range#size on non-iterable ranges (low confidence) |
3.4 | 3.4 |
ruby-3.4-socket-resolution-error |
rescue SocketError missing new subclass |
3.4 | 3.4 |
ruby-3.4-chilled-string |
"literal".gsub! string mutation |
3.4 | 3.4 |
ruby-3.4-hash-inspect |
Hash#inspect format change (low confidence) |
3.4 | 3.4 |
- BREAKING — Code will fail (raise an error, change behavior silently, or be removed) in the target version
- WARNING — Code is deprecated and emits warnings; will break in a future version
Severity is computed dynamically based on the --to version. A rule that is a warning in 7.2 becomes breaking in 8.0.
Rules marked confidence: low (ruby-3.4-range-size, ruby-3.4-hash-inspect) can't determine the receiver type statically, so they are always reported as WARNING and never cause a non-zero exit code on their own.
You can author your own rules as YAML files. Point Upgrade Radar to them via config:
# .upgrade_radar.yml
custom_rules_path: ./my_rules/# my_rules/custom.yml
- id: my-app-deprecated-helper # Unique rule identifier
framework: rails # "rails" or "ruby"
introduced_in: "8.0" # Version where this was deprecated/changed
breaking_in: "8.0" # Version where this breaks
pattern:
type: method_call # Pattern type (see below)
name: legacy_helper # Method name to match
receiver: null # null = implicit self
conditions: [] # Additional conditions
message: > # What to tell the developer
`legacy_helper` is removed. Use `modern_helper` instead.
replacement: "modern_helper" # Suggested fix
docs: "https://wiki.example.com/upgrade"
effort_minutes: 5 # Estimated fix time per occurrence
confidence: high # Optional; "low" = always reported as a warning| Type | Matches | Use For |
|---|---|---|
method_call |
Prism::CallNode |
Method invocations, chained calls |
constant_reference |
Prism::ConstantPathNode |
Class/module references |
block_parameter |
ItLocalVariableReadNode |
Bare it in blocks |
gemfile_dependency |
Gemfile analysis | Missing gem declarations |
string_mutation |
Literal string mutations | "str".gsub! patterns |
| Condition | Example | Description |
|---|---|---|
no_keyword |
{no_keyword: coder} |
Keyword arg must NOT be present |
has_block_pass |
{has_block_pass: true} |
Has &block argument |
first_arg_type |
{first_arg_type: hash} |
First arg is hash/string/symbol/constant |
first_arg_starts_with |
{first_arg_starts_with: "|"} |
First string arg starts with prefix |
keyword_value |
{keyword_value: {key: model, value: nil}} |
Keyword has specific value |
has_keywords |
{has_keywords: true} |
Has any keyword arguments |
min_positional_args |
{min_positional_args: 1} |
Minimum positional arg count |
┌──────────────┐ ┌───────────────┐ ┌───────────────┐
│ YAML Rules │────▶│ Rule Registry │────▶│ Active Rules │
│ (19 rules) │ │ (load+filter) │ │ (for version) │
└──────────────┘ └───────────────┘ └───────┬───────┘
│
┌──────────────┐ ┌───────────────┐ ┌───────▼───────┐
│ Ruby Files │────▶│ Prism Parser │────▶│ AuditVisitor │
│ (FileFinder)│ │ (AST per file)│ │ (1 walk/file) │
└──────────────┘ └───────────────┘ └───────┬───────┘
│
┌───────▼───────┐
│ Matchers │
│ (5 types) │
└───────┬───────┘
│
┌───────────────┐ ┌───────▼───────┐
│ Formatters │◀────│ Findings │
│ (text/json/ │ │ + Result │
│ html) │ └───────────────┘
└───────────────┘
-
Single AuditVisitor (Commissioner pattern) — One
Prism::Visitorsubclass walks each file's AST once and dispatches to all relevant matchers. Same pattern RuboCop uses. This is O(nodes x relevant_rules), not O(nodes x all_rules). -
YAML rules with typed matchers — Rules are defined in accessible YAML. Each
pattern.typemaps to a Ruby matcher class. You don't need Ruby knowledge to author a rule. -
Dynamic severity — A rule's severity depends on the target version.
serializewithoutcoder:is a warning in Rails 7.2 but breaking in 8.0. -
Version resolution via
Gem::Version— Built into Ruby, handles comparison correctly, no external dependency.
UpgradeRadar
├── CLI # Thor CLI (scan, rules, version)
├── Scanner # Orchestrator
├── FileFinder # File discovery with excludes
├── Rule / RuleRegistry # YAML rule loading + version filtering
├── VersionRange # "rails-7.2" parsing
├── AuditVisitor # Prism::Visitor subclass
├── Matchers/
│ ├── MethodCallMatcher # 14 of 19 rules
│ ├── ConstantReferenceMatcher
│ ├── BlockParameterMatcher
│ ├── GemfileMatcher
│ └── StringMutationMatcher
├── Finding / Result # Data model
├── EffortEstimator # Time estimation
├── Formatters/
│ ├── TextFormatter # Colorized CLI
│ ├── JsonFormatter # CI-friendly
│ └── HtmlFormatter # Shareable report
└── Runtime/
├── Collector # Deduplicating warning collector
├── RailsHook # ActiveSupport::Deprecation hook
├── RubyWarningHook # Warning[:deprecated] hook
└── Middleware # RSpec/Minitest integration
| Tool | Static Analysis | Runtime Capture | Version-to-Version Report | Effort Estimate |
|---|---|---|---|---|
| Upgrade Radar | Yes | Yes | Yes | Yes |
| RuboCop + rubocop-rails | Partial (scattered cops) | No | No | No |
| next_rails (FastRuby.io) | No | Yes | No | No |
rails app:update |
No (config files only) | No | No | No |
| Deprecation Toolkit (Shopify) | No | Yes | No | No |
The gap Upgrade Radar fills: a single version-to-version report that combines static and runtime findings, tells you what will break before you upgrade, and estimates the effort so you can plan.
name: Upgrade Readiness Check
on:
schedule:
- cron: '0 9 * * 1' # Weekly on Monday
workflow_dispatch:
jobs:
upgrade-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ruby/setup-ruby@v1
with:
ruby-version: '3.3'
- run: gem install upgrade_radar
- name: Check Rails upgrade readiness
run: |
upgrade_radar scan \
--from rails-7.2 --to rails-8.0 \
--format json --output upgrade-report.json
- uses: actions/upload-artifact@v4
if: always()
with:
name: upgrade-report
path: upgrade-report.json| Code | Meaning |
|---|---|
0 |
No breaking changes found (warnings only, or clean) |
1 |
Breaking changes found |
2 |
Invalid arguments or configuration error |
git clone https://github.com/samrocks03/upgrade_radar.git
cd upgrade_radar
bundle install
bundle exec rspec # Run tests (78 specs)
bundle exec rake # Run tests (default task)cd /path/to/your/rails/app
upgrade_radar scan --from rails-7.2 --to rails-8.0- Create or edit a YAML file in
rules/rails/orrules/ruby/ - Follow the schema documented in Custom Rules
- Add a fixture file in
spec/fixtures/with the pattern - Add a test in
spec/audit_visitor_spec.rb - Run
bundle exec rspec
MIT License. See LICENSE.txt.