rails_preflight 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e083ff064d2ee34d2b8862a68c3ea41ca63c1f39107237adec73647e8755b1ec
-  data.tar.gz: 770f2d5ac5a2b6b5a8bd491517c735be6c3874b45fdbafa7b25f5d1035af78ab
+  metadata.gz: 5116d66e0950679bf5a2c02c21220a866955d6e309c611899e23413572e3139c
+  data.tar.gz: 5c55311682aaff5b5865fb81d7e461cf7a42713c782a3f3165c406a4d5f692b2
 SHA512:
-  metadata.gz: 7c3486a813bd9c02965df146309c21966bc0c463905ea89c06760b74714b32e0ab5f75c2eabdaa20211e68c88f13aba0c03ddf368132d6a740ea772ccc34b9ce
-  data.tar.gz: 9d31b9cf5a20aedfbac6452d437760d0f509a169a44837ba9d651364b9d05516d770bac23a165b4f1b327d56be8400a414fc3107ec4f14c10f51e84724f52628
+  metadata.gz: ec6b19914d2de83e4fcb6b96689612ab6365302a4e58a44ad406ee958c6045b6f8a96eb1b42c07ff1395e70f431d17c03ce7489cbcafaaf0f926d1c86acdd987
+  data.tar.gz: f5bf7047615dc677b4a4a1d454d0450e9114797476bc04e098b186a428968e7a2efc47d9ba6b88cefb89b96eb5bdcdae6c0c597f8c11093cbf12f9f34885ee6e

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.0 (2026-10-30)
+
+- Each step links to its RailsDiff and reminds you to run `bin/rails app:update`; JSON steps carry the link as `railsdiff` (#29)
+- Dual boot: a tip to set it up when there's none, and a tip to add a CI job when CI doesn't run it (#30)
+- A warning when `.ruby-version`, the Dockerfile and CI config disagree on Ruby (#30)
+- Secrets committed in config YAML are flagged by file and key, never the value, outside the development and test sections (#31)
+- A production `secret_key_base` in `config/secrets.yml` is flagged, as a blocker when the target is Rails 7.2 or later, which stops reading that file; one read from `ENV["SECRET_KEY_BASE"]` isn't (#31)
+- The `STATS_DIRECTORIES` message shows its replacement as one code span (#33)
+
+## 0.1.2 (2026-10-13)
+
+- Code inside Packwerk packs (`packs/<name>/app`, `lib`, `spec`, ...) is scanned like the app root, and rules scoped to `app/helpers` or `spec` apply inside packs too (#22, thanks @JuanVqz)
+- `BUNDLE_GEMFILE=Gemfile.next rails-preflight` reads that Gemfile and its lockfile, so a dual-boot app can audit its next boot; one outside the app, as `bundle exec` sets it, is ignored (#23, #24, thanks @JuanVqz)
+- A compiled binary under `bin/` no longer aborts the run, and scanned files are read as UTF-8 whatever the locale, so a file with non-ASCII characters no longer crashes the scan under `LANG=C` (#21, thanks @JuanVqz)
+
 ## 0.1.1 (2026-10-09)
 
 - rubygems.org lookups also trust the certificates RubyGems ships for rubygems.org, so they work wherever `gem install` does, even when Ruby's OpenSSL can't find the system certificates

data/README.md

@@ -44,6 +44,8 @@ The audit analyzes your project for common Rails upgrade risk factors:
 - Docker runtime risks (EOL base image, locale, tzdata, OpenSSL mismatch)
 - Database schema risks (charset, integer IDs)
 - Missing or outdated `config.load_defaults`
+- Secrets committed in config YAML, by file and key, never the value; a production `secret_key_base` in `config/secrets.yml`, which Rails 7.2 stops reading
+- Dual boot (`Gemfile.next`, `next?` in the Gemfile, bootboot) and whether CI runs it, and a Ruby version that `.ruby-version`, the Dockerfile and CI config disagree on
 
 The output is a **single HTML report** designed to be:
 
@@ -97,13 +99,13 @@ It knows Rails 5.0 to 8.1 (`database/compatibility.yml`); the default target is
 
 The tool will analyze:
 
-- `Gemfile` and `Gemfile.lock`
+- `Gemfile` and `Gemfile.lock`, or the Gemfile `BUNDLE_GEMFILE` names and its lockfile (`BUNDLE_GEMFILE=Gemfile.next` for a dual-boot app)
 - `.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
+- `.rb`, `.erb`, `.haml`, `.slim` and `.rake` files under `app/`, `config/`, `db/`, `lib/`, `test/` and `spec/`, at the root and in each Packwerk pack (`packs/<name>/app/`, ...)
+- Scripts and CI config (`bin/`, `script/`, Procfiles, Makefiles, CI workflows) for removed rake tasks, and CI config for dual boot and its Ruby version
 
 And generate:
 
@@ -165,7 +167,7 @@ It's a checklist per step, with `file:line` and the matched line under each find
 ```markdown
 ## Step 3: 6.1 to 7.0
 
-Needs Ruby 2.7.0–3.2: 2.7.2 works.
+Needs Ruby 2.7.0–3.2: 2.7.2 works. Run `bin/rails app:update` and compare with [RailsDiff](https://railsdiff.org/6.1.0/7.0.0).
 
 - [ ] **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))
@@ -181,12 +183,13 @@ Needs Ruby 2.7.0–3.2: 2.7.2 works.
 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)):
+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, `railsdiff` 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",
+  "railsdiff": "https://railsdiff.org/6.1.0/7.0.0",
   "findings": [
     {
       "section": "Gem Compatibility",
@@ -227,7 +230,7 @@ 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).
+What's planned is in [ROADMAP.md](ROADMAP.md).
 
 ## Philosophy
 
@@ -248,6 +251,14 @@ bundle exec rake
 
 CI runs the suite on every Ruby from 2.7 to 4.0.
 
+## Support the project ❤️
+
+RailsPreFlight is independently developed and maintained. If it helps you assess an upgrade, identify risks, or save engineering time, consider [sponsoring its development](https://github.com/sponsors/aslam).
+
+Sponsorship helps support ongoing maintenance, compatibility updates, and improvements.
+
+Contributions, bug reports, and sharing the project are equally appreciated.
+
 ## License
 
 MIT

data/bin/rails-preflight

@@ -16,6 +16,7 @@ if %w[-h --help].include?(ARGV[0])
   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."
+  puts "BUNDLE_GEMFILE=Gemfile.next: read that Gemfile and its lockfile instead, for a dual-boot app. Ignored when it's outside APP_PATH."
   exit
 end
 
@@ -38,7 +39,8 @@ abort "Target must be a Rails version such as 7.2 (got #{target.inspect})." if t
 project_path = ARGV[0] || Dir.pwd
 
 begin
-  summary = RailsPreflight::UpgradeAnalyzer.new(target, project_path, offline: offline, format: format, stdout: stdout).run
+  summary = RailsPreflight::UpgradeAnalyzer.new(target, project_path, offline: offline, format: format, stdout: stdout,
+                                                gemfile: ENV["BUNDLE_GEMFILE"]).run
 rescue RailsPreflight::Error => e
   abort e.message
 end

data/database/deprecations.yml

@@ -103,7 +103,8 @@ deprecations:
     recategorization: "Rails 7.1 -> 7.2"
     fix_effort: low
   - id: fixture_path_assignment
-    pattern: "\\bfixture_path\\s*="
+    # Ruby reads a bare `fixture_path = x` as a local variable; the removed setter always has a receiver
+    pattern: "\\.fixture_path\\s*=(?!=)"
     message: "'fixture_path' was removed in Rails 7.2. Assign 'fixture_paths' instead, which takes an array."
     removed_in: "7.2"
     severity: error
@@ -228,7 +229,7 @@ deprecations:
     fix_effort: medium
   - id: stats_directories
     pattern: "\\bSTATS_DIRECTORIES\\b"
-    message: "'STATS_DIRECTORIES' was removed in Rails 8.1. Register extra directories with Rails::CodeStatistics.register_directory('Services', 'app/services')."
+    message: "'STATS_DIRECTORIES' was removed in Rails 8.1. Register extra directories with 'Rails::CodeStatistics.register_directory(\"Services\", \"app/services\")'."
     removed_in: "8.1"
     severity: error
     confidence: "High"

data/lib/rails_preflight/config_analyzer.rb

@@ -1,10 +1,21 @@
 # lib/rails_preflight/config_analyzer.rb
+require_relative 'deprecation_analyzer'
+
 module RailsPreflight
   class ConfigAnalyzer
-    def initialize(root_path = Dir.pwd, current_rails = nil)
+    # `key: value` in YAML, key quoted or not, with the value up to a trailing comment.
+    YAML_PAIR = /^\s*-?\s*["']?([\w-]+)["']?\s*:\s*(.*?)\s*(?:\s#.*)?$/
+    # Values, unquoted, that hold nothing secret: ERB, aliases, anchors, flow collections, booleans, null, numbers.
+    NOT_LITERAL = /\A(?:<%|[*&{\[]|(?:true|false|yes|no|null|~|-?\d+(?:\.\d+)?)\z)/i
+    # Top-level sections whose values never reach production.
+    LOCAL_ENVS = %w[development test].freeze
+    SECRETS_REMOVED = "https://guides.rubyonrails.org/7_2_release_notes.html#railties-removals"
+
+    def initialize(root_path = Dir.pwd, current_rails = nil, target_rails: nil)
       @root_path = root_path
       # load_defaults takes a minor version ("7.1"), so compare at that level
       @current_rails = Gem::Version.new(current_rails.to_s.split(".").first(2).join(".")) if current_rails
+      @target_rails = Gem::Version.new(target_rails) if target_rails && Gem::Version.correct?(target_rails)
     end
 
     def run
@@ -17,6 +28,9 @@ module RailsPreflight
         result[:checks] << { message: "config/application.rb not found.", status: :warning, kind: :unknown }
       end
 
+      check_committed_secrets(result[:checks])
+      check_secrets_secret_key_base(result[:checks])
+
       if result[:checks].any?
         result[:status] = :warning
       else
@@ -42,5 +56,48 @@ module RailsPreflight
         checks << { message: message, status: :warning, fix_effort: :medium }
       end
     end
+
+    # Secret-named keys with a literal value, outside the development and test sections. Shows the key, never the value.
+    def check_committed_secrets(checks)
+      hits = yaml_pairs(Dir.glob(File.join(@root_path, "config", "**", "*.{yml,yml.erb}")).reject { |file| file.include?("/locales/") })
+             .select { |_, _, section, key, value| key.match?(DeprecationAnalyzer::SECRET_NAME) && literal?(value) && !LOCAL_ENVS.include?(section) }
+      return if hits.empty?
+
+      them = hits.one? ? "it" : "them"
+      checks << { message: "#{hits.one? ? 'A secret is' : "#{hits.size} secrets are"} committed in config YAML, where anyone with the repository can read #{them}. Rotate #{them}, and read #{them} from credentials or ENV instead.",
+                  status: :warning, fix_effort: :medium, files: hits.map { |file, line, _, key| { file: file, line: line, snippet: "#{key}: [hidden]" } } }
+    end
+
+    # Rails 7.2 stops reading config/secrets.yml, so a production secret_key_base set there is lost; one read from
+    # ENV["SECRET_KEY_BASE"] still works, since 7.2 reads that variable itself.
+    def check_secrets_secret_key_base(checks)
+      return if @current_rails && @current_rails >= Gem::Version.new("7.2")
+
+      hit = yaml_pairs([File.join(@root_path, "config", "secrets.yml")]).find do |_, _, section, key, value|
+        %w[production shared].include?(section) && key == "secret_key_base" && !value.empty? && !value.match?(/ENV(?:\[|\.fetch\(\s*)["']SECRET_KEY_BASE["']/)
+      end
+      return unless hit
+
+      checks << { message: "'config/secrets.yml' sets 'secret_key_base' for production, and Rails 7.2 no longer reads 'config/secrets.yml'. Move the same value to credentials or 'SECRET_KEY_BASE' first: a new one invalidates sessions and signed cookies.",
+                  status: @target_rails && @target_rails >= Gem::Version.new("7.2") ? :failed : :warning, removed_in: "7.2", fix_effort: :medium,
+                  source: SECRETS_REMOVED, files: [{ file: hit[0], line: hit[1], snippet: "secret_key_base: [hidden]" }] }
+    end
+
+    def literal?(value)
+      value = value.sub(/\A(["'])(.*)\1\z/, '\2')
+      !value.empty? && !value.match?(NOT_LITERAL)
+    end
+
+    # [file, line, top-level section, key, value] for each `key: value` line in the files that exist.
+    def yaml_pairs(files)
+      files.select { |file| File.file?(file) }.sort.flat_map do |file|
+        section = nil
+        File.foreach(file, encoding: "UTF-8").with_index(1).filter_map do |line, number|
+          section = $1 if line =~ /^([\w-]+):/
+          next unless (pair = line.match(YAML_PAIR))
+          [file.delete_prefix(File.join(@root_path, "")), number, section, pair[1], pair[2]]
+        end
+      end
+    end
   end
 end

data/lib/rails_preflight/deprecation_analyzer.rb

@@ -4,6 +4,8 @@ module RailsPreflight
     DATA_PATH = File.expand_path('../../database/deprecations.yml', __dir__)
     SCAN_DIRS = %w[app config db lib test spec].freeze
     SCAN_EXTS = %w[.rb .erb .rake .haml .slim].freeze
+    # Packwerk packs (`packs/<name>/app`, `packs/<name>/spec`, ...) hold app code outside the root's SCAN_DIRS.
+    PACKS_DIR = 'packs'.freeze
     # Lines that never run, by file type: [line comment, silent comment]. A silent comment hides the lines indented
     # under it too (HAML `-#`, Slim `/`); an HTML comment (HAML `/`, Slim `/!` or `/[if IE]`) is text, but the lines
     # under it still render and run. In templates `#main` is an element id, not a comment.
@@ -22,8 +24,9 @@ module RailsPreflight
     # Snippets go into a report people print and share: on a line that names a secret, values are hidden.
     SECRET_NAME = /secret|token|passw(?:or)?d|api_?key|access_?key|private_?key|credential/i
 
-    def initialize(root_path = Dir.pwd, database_path = DATA_PATH, target_rails: nil, current_rails: nil)
+    def initialize(root_path = Dir.pwd, database_path = DATA_PATH, target_rails: nil, current_rails: nil, lockfile_path: nil)
       @root_path = root_path
+      @lockfile_path = lockfile_path || File.join(root_path, "Gemfile.lock")
       @rules = YAML.load_file(database_path)
       @target_rails = target_rails
       @current_rails = current_rails
@@ -68,7 +71,7 @@ module RailsPreflight
       # Rubocop Advisory Check
       if check_rubocop_rails
         result[:checks] << { 
-          message: "rubocop-rails is installed. Run `bundle exec rubocop -a` to auto-fix more deprecations.",
+          message: "rubocop-rails is installed. Run 'bundle exec rubocop -a' to auto-fix more deprecations.",
           status: :passed 
         }
       else
@@ -87,7 +90,8 @@ module RailsPreflight
       found = []
       compiled = rules.map { |rule| [Regexp.new(rule['pattern']), rule] }
 
-      files = Dir.glob(File.join(@root_path, "{#{SCAN_DIRS.join(',')}}/**/*")).select { |file| SCAN_EXTS.include?(File.extname(file)) }.to_h { |file| [file, 'code'] }
+      code_globs = ["", "#{PACKS_DIR}/*/"].map { |prefix| File.join(@root_path, "#{prefix}{#{SCAN_DIRS.join(',')}}/**/*") }
+      files = Dir.glob(code_globs).select { |file| SCAN_EXTS.include?(File.extname(file)) }.to_h { |file| [file, 'code'] }
       FILE_GLOBS.each do |kind, globs|
         Dir.glob(globs.map { |glob| File.join(@root_path, glob) }).each { |file| files[file] ||= kind }
       end
@@ -96,15 +100,19 @@ module RailsPreflight
         next if File.directory?(file)
 
         relative_path = Pathname.new(file).relative_path_from(Pathname.new(@root_path)).to_s
-        test = relative_path.start_with?('test/', 'spec/')
+        # A pack is laid out like the app root, so rules see `packs/billing/app/models/x.rb` as `app/models/x.rb`.
+        app_path = relative_path.sub(%r{\A#{PACKS_DIR}/[^/]+/}, '')
+        test = app_path.start_with?('test/', 'spec/')
 
-        under = ->(paths) { paths.any? { |path| relative_path == path || relative_path.start_with?("#{path}/") } }
+        under = ->(paths) { paths.any? { |path| app_path == path || app_path.start_with?("#{path}/") } }
         # A rule with `paths:` only applies under those directories or to those files.
         applicable = compiled.select do |_regex, rule|
           rule.fetch('files', ['code']).include?(kind) && (rule['paths'].nil? || under.(rule['paths']))
         end
         next if applicable.empty?
-        content = File.read(file)
+        # UTF-8 whatever the locale (LANG=C reads US-ASCII); a compiled binary under bin/ (e.g. a Rust CLI) isn't text to scan.
+        content = File.read(file, encoding: "UTF-8")
+        next unless content.valid_encoding?
         # Only `x.errors` counts under `needs_receiver_in:` (a bare `errors` in a helper or view is a local), and in a
         # file that assigns `errors` or takes it as a parameter (`skip_bare_if_local:`), where the bare name is that local.
         # ponytail: file-wide, so a model with an `errors` local in one method loses bare hits in the others.
@@ -207,7 +215,7 @@ module RailsPreflight
     end
 
     def lockfile
-      @lockfile ||= File.exist?(File.join(@root_path, "Gemfile.lock")) ? File.read(File.join(@root_path, "Gemfile.lock")) : ""
+      @lockfile ||= File.exist?(@lockfile_path) ? File.read(@lockfile_path) : ""
     end
 
   end

data/lib/rails_preflight/dual_boot_analyzer.rb

@@ -0,0 +1,79 @@
+# lib/rails_preflight/dual_boot_analyzer.rb
+require_relative 'docker_analyzer'
+
+module RailsPreflight
+  # Before the first step: can the app boot both Rails versions, does CI test both, and do the places
+  # that name a Ruby agree on it.
+  class DualBootAnalyzer
+    CI_GLOBS = %w[.github/workflows/*.{yml,yaml} .circleci/config.yml .gitlab-ci.yml .travis.yml].freeze
+    NEXT_RAILS = "https://github.com/fastruby/next_rails"
+    # next_rails runs the next boot with BUNDLE_GEMFILE=Gemfile.next; bootboot with DEPENDENCIES_NEXT=1.
+    CI_RUNS_NEXT = /Gemfile\.next|BUNDLE_GEMFILE|DEPENDENCIES_NEXT/
+    # setup-ruby's `ruby-version: 3.3`, and image tags such as `ruby:3.3` or `cimg/ruby:3.3.5`. A matrix
+    # (`ruby-version: ${{ matrix.ruby }}`) isn't resolved, so it's never compared.
+    CI_RUBY = /(?:ruby-version:\s*["']?|\bruby:)(\d+\.\d+(?:\.\d+)?)/
+
+    def initialize(root_path = Dir.pwd)
+      @root_path = root_path
+    end
+
+    def run
+      result = { title: "Dual Boot", status: :passed, checks: [], confidence: :medium }
+      ci = Dir.glob(CI_GLOBS.map { |glob| File.join(@root_path, glob) }).sort.to_h { |file| [relative(file), File.read(file, encoding: "UTF-8")] }
+
+      if (setup = dual_boot)
+        if ci.any? && ci.values.none? { |content| content.match?(CI_RUNS_NEXT) }
+          result[:checks] << { message: "Dual boot is set up (#{setup}), but CI only runs the current Gemfile. Add a CI job with 'BUNDLE_GEMFILE=Gemfile.next', so each step is tested on the next Rails before it ships.",
+                               status: :passed, kind: :tip, fix_effort: :low, source: NEXT_RAILS }
+        else
+          result[:checks] << { message: "Dual boot is set up (#{setup}).", status: :passed }
+        end
+      else
+        result[:checks] << { message: "No dual boot found (no 'Gemfile.next' or 'next?' in the Gemfile). Set it up first, e.g. with next_rails, so the app and its tests run on the current and the next Rails while each step is in progress.",
+                             status: :passed, kind: :tip, fix_effort: :low, source: NEXT_RAILS }
+      end
+
+      check_ruby_versions(ci, result)
+      result
+    end
+
+    private
+
+    def dual_boot
+      gemfile = File.join(@root_path, "Gemfile")
+      if File.exist?(File.join(@root_path, "Gemfile.next")) then "'Gemfile.next'"
+      elsif File.exist?(File.join(@root_path, "Gemfile_next.lock")) then "'Gemfile_next.lock'"
+      elsif File.exist?(gemfile) && File.read(gemfile, encoding: "UTF-8").match?(/^\s*def\s+next\?/) then "'next?' in the Gemfile"
+      end
+    end
+
+    # .ruby-version and the Dockerfile name the Ruby the app runs on, so they must agree. CI only has to test
+    # that Ruby somewhere: a matrix or a side workflow (docs, linting) on another Ruby is fine.
+    def check_ruby_versions(ci, result)
+      ruby_version_file = File.join(@root_path, ".ruby-version")
+      app = [[".ruby-version", File.exist?(ruby_version_file) && File.read(ruby_version_file)[/\d+\.\d+(?:\.\d+)?/]],
+             ["Dockerfile", DockerAnalyzer.new(@root_path).detect_ruby_version]].select(&:last)
+      return if app.empty?
+
+      ci_rubies = ci.flat_map { |file, content| content.scan(CI_RUBY).flatten.uniq.map { |version| [file, version] } }
+      app_ruby = app.first.last
+      differ = app.map(&:last).any? { |version| !same?(version, app_ruby) } ||
+               (ci_rubies.any? && ci_rubies.none? { |_, version| same?(version, app_ruby) })
+      return unless differ
+
+      result[:status] = :warning
+      result[:checks] << { message: "The Ruby version differs between files: #{(app + ci_rubies).map { |source, version| "#{source} #{version}" }.join(', ')}. Make them match, so CI tests the Ruby that runs in production.",
+                           status: :warning, fix_effort: :low }
+    end
+
+    # 3.3 and 3.3.5 agree; 3.3 and 3.4 don't.
+    def same?(a, b)
+      a, b = [a, b].map { |version| version.split(".") }
+      a.first(b.size) == b.first(a.size)
+    end
+
+    def relative(file)
+      file.delete_prefix(File.join(@root_path, ""))
+    end
+  end
+end

data/lib/rails_preflight/json_report.rb

@@ -26,7 +26,7 @@ module RailsPreflight
         counts: %i[broken blockers to_fix unknowns].to_h { |key| [key, @summary.fetch(key, []).size] },
         before: @summary.fetch(:before, []).map { |entry| finding(entry) },
         steps: @summary.fetch(:steps, []).map do |step|
-          step.slice(:from, :version, :ruby, :ruby_upgrade).merge(findings: step[:checks].map { |entry| finding(entry) })
+          step.slice(:from, :version, :ruby, :ruby_upgrade, :railsdiff).merge(findings: step[:checks].map { |entry| finding(entry) })
         end,
         ahead: @summary.fetch(:ahead, {}).transform_values { |entries| entries.map { |entry| finding(entry) } },
         cant_see: @summary.fetch(:cant_see, []).map { |entry| finding(entry) }

data/lib/rails_preflight/markdown_report.rb

@@ -22,7 +22,8 @@ module RailsPreflight
       out << section("Before you start#{" (on Rails #{@data[:current_rails]})" if @data[:current_rails]}", before) if before.any?
       @summary.fetch(:steps, []).each.with_index(1) do |step, i|
         title = "Step #{i}: #{step[:from] ? "#{step[:from]} to #{step[:version]}" : "Rails #{step[:version]}"}"
-        out << section(title, step[:checks], "#{step[:ruby]}.")
+        note = ["#{step[:ruby]}.", ("Run `bin/rails app:update` and compare with [RailsDiff](#{step[:railsdiff]})." if step[:railsdiff])]
+        out << section(title, step[:checks], note.compact.join(" "))
       end
       @summary.fetch(:ahead, {}).each do |version, entries|
         out << section("Ahead: removed in #{version}, not needed for #{@data[:target_rails]}", entries)

data/lib/rails_preflight/report_generator.rb

@@ -251,6 +251,7 @@ module RailsPreflight
               <article class="step" id="<%= step_id(step[:version]) %>">
                 <div class="step-head"><h3><%= h(step[:from] ? "#{step[:from]} → #{step[:version]}" : "Rails #{step[:version]}") %></h3><span class="tag"><%= h(blocker_tag(step[:checks])) %></span></div>
                 <div class="rubynote"><span class="k">Ruby</span><span><%= h(step[:ruby]) %></span></div>
+                <% if step[:railsdiff] %><div class="rubynote"><span class="k">Config</span><span>Run <code>bin/rails app:update</code> and compare with <a href="<%= h(step[:railsdiff]) %>">RailsDiff</a></span></div><% end %>
                 <% if step[:checks].any? %>
                   <ul class="rows"><% step[:checks].each do |entry| %><%= row_html(entry) %><% end %></ul>
                 <% end %>

data/lib/rails_preflight/summary_calculator.rb

@@ -97,7 +97,7 @@ module RailsPreflight
       max_now = @current_max_ruby
       @hops.map do |hop|
         note, upgraded = ruby_note(hop, ruby, max_now)
-        step = { version: hop[:version], from: from, ruby: note, ruby_upgrade: upgraded,
+        step = { version: hop[:version], from: from, ruby: note, ruby_upgrade: upgraded, railsdiff: railsdiff(from, hop[:version]),
                  checks: in_order(in_steps.select { |entry| step_for(entry) == hop[:version] }) }
         ruby = upgraded || ruby
         from = hop[:version]
@@ -106,6 +106,11 @@ module RailsPreflight
       end
     end
 
+    # The generated-app diff between the two minors, which is what `bin/rails app:update` brings in.
+    def railsdiff(from, to)
+      from && "https://railsdiff.org/#{from.split('.').first(2).join('.')}.0/#{to}.0"
+    end
+
     # An API removed in one of the step versions is fixed as part of that step. A Ruby too old or too new for
     # the target is checked against the target, so it sits in the last step, next to its Ruby note.
     def step_for(entry)

data/lib/rails_preflight/upgrade_analyzer.rb

@@ -16,14 +16,19 @@ module RailsPreflight
     # format: :html, :markdown or :json, written into the app as rails_preflight_report.<ext>.
     # stdout: print the report instead of writing it, with progress on stderr, for pipes and coding agents.
     # run returns the summary (nil when there's nothing to upgrade to), so the caller can set the exit code.
-    def initialize(target_rails = nil, project_path = Dir.pwd, offline: false, format: :html, stdout: false)
+    def initialize(target_rails = nil, project_path = Dir.pwd, offline: false, format: :html, stdout: false, gemfile: nil)
       @target_rails = target_rails
       @offline = offline
       @format = format
       @stdout = stdout
       @out = stdout ? $stderr : $stdout
       @project_path = project_path
-      @lockfile_path = File.join(project_path, "Gemfile.lock")
+      # gemfile: another Gemfile, as BUNDLE_GEMFILE names it (Gemfile.next for dual boot); its lockfile sits next to it.
+      # Only one inside the app counts: `bundle exec` sets BUNDLE_GEMFILE to the Gemfile of wherever it was run.
+      gemfile = File.expand_path(gemfile, project_path) if gemfile
+      inside = gemfile&.start_with?(File.join(File.expand_path(project_path), ""))
+      @gemfile_path = inside ? gemfile : File.expand_path("Gemfile", project_path)
+      @lockfile_path = "#{@gemfile_path}.lock"
       @rules = YAML.load_file(DATA_PATH)
     end
 
@@ -50,10 +55,12 @@ module RailsPreflight
       results << check_ruby_version
       results << scan_gems
       results << DockerAnalyzer.new(@project_path, checked_ruby: @eol_checked_ruby).run
+      results << DualBootAnalyzer.new(@project_path).run
       results << GemAnalyzer.new(@project_path, lockfile_specs, hops: upgrade_hops.map { |hop| hop[:version] }, direct: lockfile&.dependencies&.keys || [],
                                  last_releases: (@last_releases || {} unless @offline), target_released: target_rails_rules&.dig('released')).run
-      results << DeprecationAnalyzer.new(@project_path, target_rails: @target_rails, current_rails: current_rails&.to_s).run
-      results << ConfigAnalyzer.new(@project_path, current_rails).run
+      results << DeprecationAnalyzer.new(@project_path, target_rails: @target_rails, current_rails: current_rails&.to_s,
+                                         lockfile_path: @lockfile_path).run
+      results << ConfigAnalyzer.new(@project_path, current_rails, target_rails: @target_rails).run
       results << DatabaseAnalyzer.new(@project_path, database_rules).run
 
       report_data = {
@@ -100,12 +107,12 @@ module RailsPreflight
       if current_rails.nil?
         result[:status] = :warning
         result[:confidence] = :low
-        result[:checks] << { message: "Could not read current Rails version from Gemfile.lock.", status: :warning, kind: :unknown, fix_effort: :low }
+        result[:checks] << { message: "Could not read current Rails version from #{lockfile_name}.", status: :warning, kind: :unknown, fix_effort: :low }
       elsif Gem::Version.new(current_rails.segments.first(2).join(".")) >= Gem::Version.new(@target_rails)
         result[:status] = :warning
         result[:checks] << { message: "Already on Rails #{current_rails}: #{@target_rails} is not an upgrade.", status: :passed }
       else
-        result[:checks] << { message: "Rails #{current_rails} (Gemfile.lock) → #{@target_rails}", status: :passed, fix_effort: :low }
+        result[:checks] << { message: "Rails #{current_rails} (#{lockfile_name}) → #{@target_rails}", status: :passed, fix_effort: :low }
       end
 
       result
@@ -169,7 +176,7 @@ module RailsPreflight
       return [File.read(ruby_version_file), ".ruby-version"] if File.exist?(ruby_version_file)
 
       lock_ruby = File.exist?(@lockfile_path) && File.read(@lockfile_path)[/^RUBY VERSION\s+ruby (\S+)/, 1]
-      return [lock_ruby, "Gemfile.lock"] if lock_ruby
+      return [lock_ruby, lockfile_name] if lock_ruby
 
       docker_ruby = DockerAnalyzer.new(@project_path).detect_ruby_version
       [docker_ruby, "Dockerfile"] if docker_ruby
@@ -204,7 +211,7 @@ module RailsPreflight
         result[:status] = :warning
         result[:confidence] = :medium
         result[:checks] << {
-          message: "No Gemfile.lock found. Skipping gem compatibility checks.",
+          message: "No #{lockfile_name} found. Skipping gem compatibility checks.",
           status: :warning,
           kind: :unknown,
           fix_effort: :low
@@ -231,7 +238,7 @@ module RailsPreflight
       end
 
       if mixed_gems.any? && @offline
-        message = "#{mixed_gems.size} gems come from one Gemfile.lock section that lists rubygems.org and #{mixed_remotes.join(', ')}; can't tell which are private with --offline"
+        message = "#{mixed_gems.size} gems come from one #{lockfile_name} section that lists rubygems.org and #{mixed_remotes.join(', ')}; can't tell which are private with --offline"
         result[:checks] << { message: message, status: :warning, kind: :unknown, names: mixed_gems, fix_effort: :unknown }
         result[:status] = :warning
       end
@@ -244,7 +251,7 @@ module RailsPreflight
         private_gems.concat(mixed_gems.select { |name| found[name] == false })
         @last_releases = dated_gems.filter_map { |name| [name, found[name]['version_created_at']] if found[name].is_a?(Hash) && found[name]['version_created_at'] }.to_h
         if mixed_gems.any?
-          result[:checks] << { message: "Looked up #{mixed_gems.size} gems on rubygems.org, since Gemfile.lock lists them under both rubygems.org and #{mixed_remotes.join(', ')}. Pass --offline to skip.", status: :passed, fix_effort: :low }
+          result[:checks] << { message: "Looked up #{mixed_gems.size} gems on rubygems.org, since #{lockfile_name} lists them under both rubygems.org and #{mixed_remotes.join(', ')}. Pass --offline to skip.", status: :passed, fix_effort: :low }
         end
         # One entry per distinct error: a missing certificate fails every lookup the same way.
         inconclusive.group_by { |_, error| error }.each do |error, failed|
@@ -359,7 +366,7 @@ module RailsPreflight
         global = []
         scoped = {}
         blocks = [] # source for a `source … do` block, nil for any other block
-        gemfile_lines(File.join(@project_path, "Gemfile")).each do |line|
+        gemfile_lines(@gemfile_path).each do |line|
           source = line[/^\s*source\b\s*\(?\s*(.+?)\s*\)?\s*(?:do\b.*)?$/, 1]&.delete_prefix("\"")&.delete_suffix("\"")&.delete("'")
           name = line[/^\s*gem\s*\(?\s*["']([^"']+)["']/, 1]
           if name
@@ -406,6 +413,10 @@ module RailsPreflight
       @lockfile = File.exist?(@lockfile_path) ? Bundler::LockfileParser.new(File.read(@lockfile_path)) : nil
     end
 
+    def lockfile_name
+      File.basename(@lockfile_path)
+    end
+
     def known_rails_versions
       @rules.fetch('rails_versions', {}).keys.sort_by { |v| Gem::Version.new(v) }
     end
@@ -417,7 +428,7 @@ module RailsPreflight
     # Next known minor after the current Rails (7.1.3 → 7.2), or nil when already on the newest.
     def next_rails
       unless current_rails
-        reason = File.exist?(@lockfile_path) ? "No Rails in #{@lockfile_path}" : "No Gemfile.lock in #{@project_path}"
+        reason = File.exist?(@lockfile_path) ? "No Rails in #{@lockfile_path}" : "No #{lockfile_name} in #{@project_path}"
         raise Error, "#{reason}, so the current Rails version is unknown. Pass a target, e.g. `rails-preflight #{latest_known_rails}`."
       end
       current_minor = Gem::Version.new(current_rails.segments.first(2).join("."))

data/lib/rails_preflight/version.rb

@@ -1,3 +1,3 @@
 module RailsPreflight
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/rails_preflight.rb

@@ -1,6 +1,7 @@
 require "rails_preflight/version"
 require "rails_preflight/upgrade_analyzer"
 require "rails_preflight/docker_analyzer"
+require "rails_preflight/dual_boot_analyzer"
 require "rails_preflight/deprecation_analyzer"
 require "rails_preflight/gem_analyzer"
 require "rails_preflight/config_analyzer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_preflight
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Syed Aslam
@@ -35,6 +35,7 @@ files:
 - lib/rails_preflight/database_analyzer.rb
 - lib/rails_preflight/deprecation_analyzer.rb
 - lib/rails_preflight/docker_analyzer.rb
+- lib/rails_preflight/dual_boot_analyzer.rb
 - lib/rails_preflight/gem_analyzer.rb
 - lib/rails_preflight/json_report.rb
 - lib/rails_preflight/markdown_report.rb