rails_preflight 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 02fcbcfa3f7d98bbc550334fcf9bd65919fbb2eb5266088823b87c0fd7465ae3
+  data.tar.gz: 42c66fa2d33b67e47fed5a36a7127eba476c34b57705d0f3c2591dea9fa1f5eb
+SHA512:
+  metadata.gz: ab95dfb109b6fee6cd50d1014792f85d4e941ba7871734766b834844bea2a2bfb15e526e426f7a19a97be7abd58339141bfea037365d9e0b34a3e6f5063b8226
+  data.tar.gz: 1606dfaa001672ed19d45469592f212979228c2efb6500b9e7f8b8017d9977817e1814b25045f79b3ada23a9d3d9fe32b09fbe71e74c3b606e5e69e761ea7731

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-10-09)
+
+First release. Point it at a Rails 5.0 – 8.1 app and a target version: it writes a report into the app as HTML, Markdown or JSON, plus a short terminal summary. Read-only and static.
+
+- Upgrade path with one step per Rails minor, the Ruby each step needs, and which step to upgrade Ruby on
+- 118 deprecation rules from the release notes, 5.0 to 8.1, each cited, scanning `.rb`, `.erb`, `.haml`, `.slim` and `.rake` files, config YAML, and rake tasks in scripts and CI; APIs already removed from the current Rails are listed first as already broken
+- Gem checks: private gems from `Gemfile.lock` and the Gemfile's sources; locked gems whose declared Rails requirement caps the upgrade; limits no gemspec declares, which Rails or the gem checks when it loads (database adapters, listen, capybara, selenium-webdriver, redis, google-cloud-storage, bullet); gems the rails gem stops pulling in; a curated list of retired gems; and, online, gems with no release since the target Rails shipped
+- Ruby and Node end-of-life, Docker runtime risks, `config.load_defaults`, and schema charset and integer IDs from `db/schema.rb` (an app on `db/structure.sql` gets a note that these were skipped)
+- HTML report: verdict, counts, route, plan table, one card per step with files and lines, and what the report can't see; dark mode, print styles, no network requests
+- `--format markdown`: a checklist per step for issues, PRs and coding agents
+- `--format json`: every finding with its parts (`"schema": 1`, may change before 1.0)
+- `--stdout` prints the report instead of writing it, for pipes and coding agents
+- `--fail-on blockers|broken` sets the exit code, so CI can gate on it
+- `--offline` for a fully static run; private gem names are never sent
+- Report snippets hide quoted values on lines that name a secret, token or password
+- Checked against real Rails upgrades in Mastodon, Discourse, Forem, Redmine, Coursemology and Fat Free CRM

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Syed Aslam
+
+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,253 @@
+# RailsPreFlight 🛡️
+
+**Assess Rails upgrade risk before you touch a single line of code.**
+
+`rails-preflight` is a static analysis tool that scans legacy Rails applications and produces a **human-readable upgrade risk report**.
+
+It helps teams understand:
+
+- what will block a Rails upgrade
+- what is easy vs painful to fix
+- where hidden dependency and infrastructure risks exist
+
+This tool is designed for **planning and scoping**, not automated migration.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/report-overview-dark.png">
+  <img alt="The report for Mastodon v3.3.0, Rails 5.2.4.4 to 7.0: verdict, counts, the route through 6.0, 6.1 and 7.0 with blockers at each, and the plan table" src="docs/images/report-overview-light.png">
+</picture>
+
+<sub>Mastodon v3.3.0, an open-source app, checked for Rails 7.0. <a href="https://aslam.github.io/rails-preflight/sample-report.html">See the full report</a>.</sub>
+
+## Why this exists
+
+Rails upgrades fail not because teams can’t write code, but because they underestimate risk:
+
+- private gems with unknown compatibility
+- subtle framework deprecations
+- Ruby and OS lifecycle mismatches
+- Docker runtime issues that surface late
+
+`rails-preflight` makes these risks visible before you start upgrading.
+
+Think of it as **upgrade reconnaissance**, not a fixer. Run it before the upgrade starts, whoever does it: your team, a consultant or a coding agent.
+
+## What this tool does
+
+The audit analyzes your project for common Rails upgrade risk factors:
+
+- Ruby & Rails compatibility, and which upgrade step to move Ruby on
+- End-of-life Ruby and Node versions
+- Private / internal gem dependencies
+- Locked gems whose declared Rails requirement caps the upgrade, plus a curated list of gems with known limits
+- Removed and deprecated Rails APIs in code, config YAML, rake tasks in scripts and CI, including ones already removed from your current Rails
+- Docker runtime risks (EOL base image, locale, tzdata, OpenSSL mismatch)
+- Database schema risks (charset, integer IDs)
+- Missing or outdated `config.load_defaults`
+
+The output is a **single HTML report** designed to be:
+
+- readable by engineers
+- understandable by EMs and tech leads
+- usable in upgrade planning discussions
+
+The same findings also come as **Markdown**, a checklist for issues, PRs and coding agents, and as **JSON** for CI and other tools. See [Output formats](#output-formats).
+
+## What this tool intentionally does NOT do
+
+- ❌ It does not modify your code
+- ❌ It does not auto-fix deprecations
+- ❌ It does not guarantee upgrade success
+- ❌ It is not a replacement for running tests or CI
+
+If you’re looking for a “one-click upgrade,” this is not that tool.
+
+## Related tools
+
+These cover what `rails-preflight` leaves out, and pair well with it:
+
+- [next_rails](https://github.com/fastruby/next_rails) or [RailsBump](https://railsbump.org): which gem versions work with your target Rails
+- [Brakeman](https://brakemanscanner.org): security issues
+- [rubocop-rails](https://github.com/rubocop/rubocop-rails): autofixes for many deprecations
+
+## Who this is for
+
+This tool is especially useful if you are:
+
+- Upgrading a Rails 5.0 or newer application (Rails 3 and 4 aren't covered)
+- Planning a security-driven upgrade
+- Scoping an upgrade before committing resources
+- Auditing multiple legacy Rails apps
+- A consultant or staff engineer responsible for upgrade strategy
+
+## Installation
+
+Install it globally and point it at your app. It only reads files, so the app can be on any Ruby version, including the old one your servers run. The machine running it needs Ruby 2.7 or newer.
+
+```bash
+gem install rails_preflight
+rails-preflight /path/to/your/app
+```
+
+With no target, it reports on the next Rails minor after the app's (5.2 → 6.0, 7.1 → 7.2), the step Rails recommends taking next. Pass a target to plan a bigger jump: `rails-preflight 8.1 /path/to/your/app`. Leave out the path to audit the current directory.
+
+Private gems come from `Gemfile.lock` and the Gemfile's `source` blocks, which are read, never run. Only when neither says where a gem comes from does the tool ask rubygems.org. It also asks rubygems.org when each public gem that depends on Rails last had a release, and lists the ones with nothing newer than the target Rails: nothing says they break, but nobody may have tried. Private gem names are never sent. Pass `--offline` for a fully static run; unplaced gems are then reported as unchecked, and release dates are skipped.
+
+It knows Rails 5.0 to 8.1 (`database/compatibility.yml`); the default target is only as current as that list.
+
+The tool will analyze:
+
+- `Gemfile` and `Gemfile.lock`
+- `.ruby-version`
+- `Dockerfile` (if present)
+- `db/schema.rb` (if present; an app on `db/structure.sql` gets a note that the schema checks were skipped)
+- `config/application.rb` and `config/**/*.yml`
+- `.rb`, `.erb`, `.haml`, `.slim` and `.rake` files under `app/`, `config/`, `db/`, `lib/`, `test/` and `spec/`
+- Scripts and CI config (`bin/`, `script/`, Procfiles, Makefiles, CI workflows) for removed rake tasks
+
+And generate:
+
+```
+rails_preflight_report.html
+```
+
+Or `rails_preflight_report.md` or `.json` with `--format markdown` or `--format json`: see [Output formats](#output-formats).
+
+## Output formats
+
+Every format renders the same findings. Each finding carries its parts, not only a sentence: the gem, its locked version and the requirement it fails, or the rule with every file, line and matched line, plus the release notes, README or Rails source it rests on.
+
+| Format | Flag | Written to, in the app | For |
+|---|---|---|---|
+| HTML | (default) | `rails_preflight_report.html` | reading, planning, sharing |
+| Markdown | `--format markdown` | `rails_preflight_report.md` | issues, PRs, coding agents |
+| JSON | `--format json` | `rails_preflight_report.json` | CI and other tools |
+
+The report is the only file the tool writes. Add `--stdout` to print it instead, for pipes and coding agents: no file is written, and progress goes to stderr so stdout holds only the report. Every run also prints a short summary (counts, then each blocker) for SSH sessions and CI logs.
+
+### HTML
+
+One self-contained file. It makes no network requests when opened, follows the OS dark mode, and prints on A4. [Sample: Mastodon v3.3.0 to Rails 7.0](https://aslam.github.io/rails-preflight/sample-report.html).
+
+1.  **Title and verdict**: `app: Rails current to target`, then one sentence: how many steps, when to upgrade Ruby, how many blockers.
+
+2.  **Counts**, each linked to where the findings are:
+    *   **Already broken**: APIs removed before your current Rails, or gems past their last supported Rails. That code fails when it runs, or never runs.
+    *   **Blockers**: must be fixed before the upgrade can work (e.g. Ruby too old, removed APIs still in use).
+    *   **To fix**: will warn or break along the way (deprecations, lagging config), split into now and later versions.
+    *   **Couldn't check**: what the tool could not verify (private gems, missing files), to review by hand.
+
+3.  **Route and plan**: one stop per Rails minor, since Rails recommends upgrading one at a time, with the blockers at each. Later versions past the target are faded and count the code they remove, found in the same scan. A table gives each step's work, the Ruby it needs and a relative effort: the hardest single fix in it (low, medium or high, set per check), not the amount of work. The occurrence counts on each finding show that.
+
+4.  **Steps**: "Before you start" for findings that don't belong to a step, then one card per step with its Ruby range and the removed APIs and gems to fix for it. Each finding links to the Rails release notes or the gem's source; its occurrence line expands to file, line and snippet, with app and test occurrences counted apart.
+
+5.  **Ahead of the target**: code that later Rails versions remove, by version. Not needed now.
+
+6.  **What this report can't see**: private gems and quiet gems by name, behavior changes, multi-line code and test coverage, with what to do instead.
+
+7.  **Footer**: the confidence of each section (read from project files, pattern matches, or a key input missing) and where the findings come from.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/report-step-dark.png">
+  <img alt="The 6.1 to 7.0 step card: four gem blockers, then removed APIs with their files, line numbers and matched lines expanded" src="docs/images/report-step-light.png">
+</picture>
+
+### Markdown
+
+`--format markdown` writes `rails_preflight_report.md` into the app. A coding agent can read it from stdout instead:
+
+```bash
+rails-preflight --format markdown --stdout 7.2 /path/to/your/app
+```
+
+It's a checklist per step, with `file:line` and the matched line under each finding. It pastes into an issue or PR as is, and opens with a note telling a coding agent to take one step at a time, run the tests after each, and leave "Ahead" and "Couldn't check" alone. From the same Mastodon run ([full sample](docs/sample-report.md)):
+
+```markdown
+## Step 3: 6.1 to 7.0
+
+Needs Ruby 2.7.0–3.2: 2.7.2 works.
+
+- [ ] **Blocker:** annotate 3.1.1 requires activerecord >= 3.2, < 7.0, so it doesn't install on Rails 7.0. Upgrade it to a release that allows 7.0, or replace it.
+- [ ] **Blocker:** `ActionMailer::DeliveryJob` and `ActionMailer::Parameterized::DeliveryJob` were removed in Rails 7.0. Mail is delivered by `ActionMailer::MailDeliveryJob`. ([source](https://guides.rubyonrails.org/7_0_release_notes.html#action-mailer-removals))
+  - `config/initializers/delivery_job.rb:1` `ActionMailer::DeliveryJob.class_eval do`
+  - `spec/models/user_spec.rb:178` `expect { user.send_confirmation_instructions }.to have_enqueued_job(ActionMailer::DeliveryJob)`
+```
+
+### JSON
+
+`--format json` writes `rails_preflight_report.json` into the app, for CI and other tools. With `--stdout` it can be piped:
+
+```bash
+rails-preflight --format json --stdout 7.2 /path/to/your/app | jq '.counts'
+```
+
+The top level holds `schema`, `tool`, `app`, `current_rails`, `target_rails`, `ruby`, `offline`, `verdict` and `counts`, then the findings in `before` (before the first step), `steps` (each with `from`, `version`, its Ruby note and `findings`), `ahead` (keyed by the Rails version that removes them) and `cant_see`. There's no timestamp, so the same app gives the same output. Schema 1 may still change before 1.0; the number goes up when it does. A step from the same run, shortened ([full sample](docs/sample-report.json)):
+
+```json
+{
+  "from": "6.1",
+  "version": "7.0",
+  "findings": [
+    {
+      "section": "Gem Compatibility",
+      "kind": "blocker",
+      "message": "annotate 3.1.1 requires activerecord >= 3.2, < 7.0, so it doesn't install on Rails 7.0. ...",
+      "removed_in": "7.0",
+      "fix_effort": "medium",
+      "gem": "annotate",
+      "version": "3.1.1",
+      "requires": "activerecord >= 3.2, < 7.0"
+    },
+    {
+      "section": "Deprecation Warnings",
+      "kind": "blocker",
+      "message": "'ActiveModel::Errors#keys', '#values', '#to_h', '#slice!' and '#to_xml' were removed in Rails 7.0. ...",
+      "rule": "errors_hash_methods",
+      "removed_in": "7.0",
+      "fix_effort": "low",
+      "confidence": "medium",
+      "source": "https://guides.rubyonrails.org/7_0_release_notes.html#active-model-removals",
+      "files": [
+        { "file": "lib/mastodon/accounts_cli.rb", "line": 106, "snippet": "user.errors.to_h.each do |key, error|", "test": false }
+      ]
+    }
+  ]
+}
+```
+
+`kind` is `broken`, `blocker`, `to_fix`, `tip` or `unknown`. A finding has only the parts that apply to it: gem findings have `gem`, `version` and `requires`; code findings have `rule`, `confidence` and `files`; what the report couldn't check has `names`.
+
+### Gating CI
+
+`--fail-on blockers` exits 1 when anything blocks the upgrade or is already broken; `--fail-on broken` only when something is already broken. It works with any format. In CI, `--offline` keeps the run fully static:
+
+```bash
+rails-preflight --offline --format json --fail-on blockers 7.2
+```
+
+## Roadmap
+
+For a detailed list of current features and future plans, please see [ROADMAP.md](ROADMAP.md).
+
+## Philosophy
+
+This tool favors:
+
+- clarity over completeness
+- honesty over false confidence
+- planning support over automation
+
+If it helps you avoid one failed upgrade attempt, it has done its job.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake
+```
+
+CI runs the suite on every Ruby from 2.7 to 4.0.
+
+## License
+
+MIT

data/bin/rails-preflight

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# No bundler/setup on purpose: it would load the Gemfile in the current directory,
+# which is usually the app being audited, often pinned to an old Ruby.
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'rails_preflight'
+
+if %w[-h --help].include?(ARGV[0])
+  puts "Usage: rails-preflight [--offline] [--format html|markdown|json] [--stdout] [--fail-on blockers|broken] [TARGET_RAILS_VERSION] [APP_PATH]"
+  puts "Example: rails-preflight 7.2 ~/code/my_app"
+  puts "TARGET defaults to the next Rails minor after the app's; APP_PATH to the current directory."
+  puts "--offline: don't call rubygems.org; gems the lockfile can't place are reported as unchecked, and gem release dates are skipped."
+  puts "--format markdown|json: write rails_preflight_report.md or .json into the app instead of the HTML report."
+  puts "--stdout: print the report instead of writing it (progress goes to stderr), for pipes and coding agents."
+  puts "--fail-on blockers: exit 1 when anything blocks the upgrade or is already broken. --fail-on broken: only when something is already broken."
+  exit
+end
+
+offline = !ARGV.delete("--offline").nil?
+stdout = !ARGV.delete("--stdout").nil?
+format = :html
+if (i = ARGV.index("--format"))
+  format = ARGV.slice!(i, 2)[1].to_s.to_sym
+  abort "--format must be html, markdown or json (got #{format})." unless %i[html markdown json].include?(format)
+end
+fail_on = nil
+if (i = ARGV.index("--fail-on"))
+  fail_on = ARGV.slice!(i, 2)[1].to_s.to_sym
+  abort "--fail-on must be blockers or broken (got #{fail_on})." unless %i[blockers broken].include?(fail_on)
+end
+
+# The target is optional, so a lone argument that isn't a version is the app path.
+target = ARGV.shift if ARGV[0] && (Gem::Version.correct?(ARGV[0]) || !File.directory?(ARGV[0]))
+abort "Target must be a Rails version such as 7.2 (got #{target.inspect})." if target && !Gem::Version.correct?(target)
+project_path = ARGV[0] || Dir.pwd
+
+begin
+  summary = RailsPreflight::UpgradeAnalyzer.new(target, project_path, offline: offline, format: format, stdout: stdout).run
+rescue RailsPreflight::Error => e
+  abort e.message
+end
+
+# Already broken is worse than blocked, so --fail-on blockers counts it too.
+failing = { blockers: %i[broken blockers], broken: %i[broken] }.fetch(fail_on, []).sum { |key| summary&.fetch(key)&.size.to_i }
+exit 1 if failing.positive?

data/database/compatibility.yml

@@ -0,0 +1,59 @@
+# database/compatibility.yml
+# released: the X.Y.0 release date on rubygems.org.
+rails_versions:
+  "5.0":
+    released: "2016-06-30"
+    required_ruby: ">= 2.2.2"
+    max_ruby: "2.4.99"
+  "5.1":
+    released: "2017-04-27"
+    required_ruby: ">= 2.2.2"
+    max_ruby: "2.5.99"
+  "5.2":
+    released: "2018-04-09"
+    required_ruby: ">= 2.2.2"
+    max_ruby: "2.6.99"
+    # Note: Rails 5.2.8.1 supports up to 2.7, but 3.0 is a hard break.
+  "6.0":
+    released: "2019-08-16"
+    required_ruby: ">= 2.5.0"
+    max_ruby: "2.7.99"
+  "6.1":
+    released: "2020-12-09"
+    required_ruby: ">= 2.5.0"
+    max_ruby: "3.0.99"
+  "7.0":
+    released: "2021-12-15"
+    required_ruby: ">= 2.7.0"
+    max_ruby: "3.2.99"
+  "7.1":
+    released: "2023-10-05"
+    required_ruby: ">= 2.7.0"
+    max_ruby: "3.4.99"
+  "7.2":
+    released: "2024-08-09"
+    required_ruby: ">= 3.1.0"
+    max_ruby: "3.4.99"
+    # Rails CI treats Ruby 3.4+ as allowed-to-fail on 7.x; 3.4 per FastRuby's compatibility table.
+  "8.0":
+    released: "2024-11-07"
+    required_ruby: ">= 3.2.0"
+    max_ruby: "4.0.99"
+  "8.1":
+    released: "2025-10-22"
+    required_ruby: ">= 3.2.0"
+    max_ruby: "4.0.99"
+    # Rails CI gates 8.x on Ruby 4.0 (rails/buildkite-config).
+
+# Schema checks, applied when the target Rails is at or past `since`.
+database_rules:
+  - name: "utf8_charset"
+    message: "Legacy utf8mb3 charset detected. Upgrade to utf8mb4 for Rails 6+."
+    pattern: "utf8mb3"
+    type: "warning"
+    since: "6.0"
+  - name: "integer_ids"
+    message: "Integer IDs detected. Rails 5.1+ defaults to bigint."
+    pattern: "id: :integer"
+    type: "warning"
+    since: "5.1"