rails preflight — Gauge Rails upgrade risk before you…

Pitch

Description

Comments

About this project

rails-preflight scans a Rails app and reports what will block its upgrade, step by step: gems capped below the target Rails, removed and deprecated APIs, EOL Ruby and Node, Docker and database schema risks. It reads files and never runs them, and it lists what it couldn't check, so teams can plan and scope the upgrade before they touch a line of code.

rails-preflight is a static tool that scans legacy Rails applications and produces a human-readable upgrade risk report, so teams can plan and scope a Rails upgrade before they touch a line of code.

Key Features:

Upgrade Risk: Shows what will block a Rails upgrade, what is easy vs painful to fix, and where hidden dependency and infrastructure risks are.
Upgrade Route: Lays out the route step by step (for example 5.2 → 6.0 → 6.1 → 7.0), with the blockers at each step and which step to move Ruby on.
Human-Readable Reports: A single HTML report that engineers can read, EMs and tech leads can follow, and teams can use in upgrade planning.
Audit Scope:
- Ruby and Rails compatibility, and which upgrade step to move Ruby on.
- End-of-life Ruby and Node versions.
- Private and 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, and 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 (character set, integer IDs).
- Missing or outdated config.load_defaults.
Private by Default: Gemfiles are read, never run, and private gem names are never sent anywhere. --offline gives a fully static run.

Intended Use:

This is upgrade reconnaissance, not a fixer. It doesn't modify your code, auto-fix deprecations, or replace your tests and CI. Run it before the upgrade starts, no matter who does it: your team, a consultant or a coding agent.

Output Formats:

HTML: The full report, for reading, sharing and planning.
Markdown: A checklist per upgrade step with file:line for each finding, for issues, PRs and coding agents.
JSON: Structured output for CI and other tools, with --fail-on blockers to gate a build.

Who It's For:

Teams upgrading a Rails 5.0 or newer application (Rails 3 and 4 aren't covered).
Teams planning a security-driven upgrade.
Teams scoping an upgrade before committing resources.
Anyone auditing multiple legacy Rails apps.

Limits:

It doesn't guarantee upgrade success. Each report says what it couldn't check (private gems, behavior changes, test coverage) and what to do instead, so nothing is reported as safe just because it went unchecked.