rails_preflight 0.1.0

data/database/gems.yml

@@ -0,0 +1,109 @@
+# Public gems whose gemspec doesn't state their Rails limit, so Bundler won't warn before the upgrade breaks.
+# Each entry cites where its limit comes from. Constraints a gemspec does declare are read from Gemfile.lock instead.
+#   breaks_in: first Rails minor the gem doesn't work on; a blocker on that hop. Omitted for gems that are
+#              retired or deprecated but still run: fix them when convenient.
+#   pattern:   optional; counts the files that use the gem, so the report shows how big the move is.
+#   fixed_in:  optional; only locked versions below it are affected.
+#   only_if_used: report only when the pattern matches, for gems that break in one use only.
+gems:
+  - name: protected_attributes_continued
+    breaks_in: "7.0"
+    message: "supports Rails 5.0 to 6.1 only and won't be updated for 7.0. Move to strong parameters."
+    source: "https://github.com/westonganger/protected_attributes_continued#readme"
+    pattern: "^\\s*attr_(?:accessible|protected)\\b"
+    fix_effort: high
+  - name: paperclip
+    message: "is deprecated and archived. Move to Active Storage, or to the maintained kt-paperclip fork."
+    source: "https://github.com/thoughtbot/paperclip#deprecated"
+    pattern: "^\\s*(?:has_attached_file|validates_attachment\\w*)\\b"
+    fix_effort: high
+  - name: webpacker
+    message: "was retired after Rails 7.0. Move to jsbundling-rails or import maps, or to shakapacker to keep webpack."
+    source: "https://github.com/rails/webpacker#readme"
+    pattern: "\\b(?:javascript|stylesheet)_pack_tag\\b"
+    fix_effort: medium
+  - name: therubyracer
+    message: "is unmaintained and stuck on V8 3.16. Move to mini_racer, or drop it if Node.js is available to ExecJS."
+    source: "https://github.com/rubyjs/therubyracer#readme"
+    fix_effort: low
+  - name: turbolinks
+    message: "is archived and superseded by Turbo (turbo-rails), the default since Rails 7.0."
+    source: "https://github.com/turbolinks/turbolinks#readme"
+    fix_effort: medium
+  - name: sass
+    message: "(Ruby Sass) is archived and gets no updates. Move to dartsass-rails (sassc, the replacement its README names, is archived too)."
+    source: "https://github.com/sass/ruby-sass#readme"
+    fix_effort: low
+  - name: sassc
+    message: "is archived and gets no updates. Move to dartsass-rails or dartsass-sprockets, or to sassc-embedded as a drop-in."
+    source: "https://github.com/sass/sassc-ruby#readme"
+    fix_effort: low
+  - name: que
+    breaks_in: "7.1"
+    fixed_in: "2.3.0"
+    only_if_used: true
+    message: "runs Active Job through Rails' Que adapter, which Rails 7.1 removed. Upgrade que to 2.3.0+, which ships its own."
+    source: "https://github.com/que-rb/que/blob/master/CHANGELOG.md#230-2023-10-16"
+    pattern: "\\bqueue_adapter\\s*=\\s*:que\\b"
+    fix_effort: low
+
+# Database adapter gems Rails checks itself when it loads the adapter (`gem "pg", "~> 1.1"`), so no gemspec
+# declares the limit. Read from activerecord/lib/active_record/connection_adapters/*_adapter.rb on each
+# X-Y-stable branch; a locked adapter outside the range blocks that hop.
+adapter_requirements:
+  "5.1": { sqlite3: ["~> 1.3", ">= 1.3.6"], mysql2: [">= 0.3.18", "< 0.6.0"], pg: [">= 0.18", "< 2.0"] }
+  "5.2": { sqlite3: ["~> 1.3", ">= 1.3.6"], mysql2: [">= 0.4.4", "< 0.6.0"], pg: [">= 0.18", "< 2.0"] }
+  "6.0": { sqlite3: ["~> 1.4"], mysql2: [">= 0.4.4"], pg: [">= 0.18", "< 2.0"] }
+  "6.1": { sqlite3: ["~> 1.4"], mysql2: ["~> 0.5"], pg: ["~> 1.1"] }
+  "7.0": { sqlite3: ["~> 1.4"], mysql2: ["~> 0.5"], pg: ["~> 1.1"] }
+  "7.1": { sqlite3: [">= 1.4"], mysql2: ["~> 0.5"], pg: ["~> 1.1"], trilogy: ["~> 2.4"] }
+  "7.2": { sqlite3: [">= 1.4"], mysql2: ["~> 0.5"], pg: ["~> 1.1"], trilogy: ["~> 2.7"] }
+  "8.0": { sqlite3: [">= 2.1"], mysql2: ["~> 0.5"], pg: ["~> 1.1"], trilogy: ["~> 2.7"] }
+  "8.1": { sqlite3: [">= 2.1"], mysql2: ["~> 0.5"], pg: ["~> 1.1"], trilogy: ["~> 2.7"] }
+
+# Gems the rails gem stopped depending on, from rails.gemspec on each X-Y-stable branch. An app that gets one
+# only through rails loses it on that hop, which matters only if the app uses it: `paths` any of which exists,
+# or `pattern` on an uncommented line in `files` (default config/**/*.rb). Without sprockets-rails, `config.assets`
+# raises on boot (7.0's rails/all no longer requires sprockets/railtie); an app with neither never loaded it.
+dropped_by_rails:
+  "7.0":
+    sprockets-rails:
+      paths: [app/assets]
+      pattern: "\\bconfig\\.assets\\b|require\\s*\\(?\\s*[\"']sprockets"
+
+# Version limits no gemspec declares. Mostly gems Rails loads itself for one feature, with a requirement of its own
+# (`gem "listen", "~> 3.5"`), read from each X-Y-stable branch; `raises` marks a gem that checks the Rails version
+# itself instead. `from` maps the first hop that requires a version to that requirement, which holds until a later
+# key. `used_if` works as in dropped_by_rails: an app that never uses the feature never loads the gem.
+version_limits:
+  listen:
+    from: { "7.0": ["~> 3.5"] }
+    for: "the evented file watcher in development"
+    used_if: { pattern: "\\bEventedFileUpdateChecker\\b" }
+    source: "https://github.com/rails/rails/blob/7-0-stable/activesupport/lib/active_support/evented_file_update_checker.rb#L3"
+  capybara:
+    from: { "5.1": [">= 2.15"], "6.1": [">= 3.26"] }
+    for: "system tests"
+    used_if: { files: "{test,spec}/**/*.rb", pattern: "\\bdriven_by\\b|\\bSystemTestCase\\b|type:\\s*:system\\b" }
+    source: "https://github.com/rails/rails/blob/6-1-stable/actionpack/lib/action_dispatch/system_test_case.rb#L3"
+  selenium-webdriver:
+    from: { "7.0": [">= 4.0.0"] }
+    for: "system tests driven by :selenium"
+    used_if: { files: "{test,spec}/**/*.rb", pattern: "\\bdriven_by\\s*\\(?\\s*:selenium\\b" }
+    source: "https://github.com/rails/rails/blob/7-0-stable/actionpack/lib/action_dispatch/system_testing/driver.rb#L24"
+  redis:
+    from: { "5.1": [">= 3", "< 5"], "7.0": [">= 3", "< 6"], "7.1": [">= 4", "< 6"], "8.0": [">= 4", "< 7"] }
+    for: "Action Cable's redis adapter"
+    used_if: { files: "config/cable.yml", pattern: "^\\s*adapter:\\s*[\"']?redis\\b" }
+    source: "https://github.com/rails/rails/blob/7-1-stable/actioncable/lib/action_cable/subscription_adapter/redis.rb#L3"
+  google-cloud-storage:
+    from: { "5.2": ["~> 1.8"], "6.0": ["~> 1.11"] }
+    for: "Active Storage's GCS service"
+    used_if: { files: "config/storage.yml", pattern: "^\\s*service:\\s*[\"']?GCS\\b" }
+    source: "https://github.com/rails/rails/blob/6-0-stable/activestorage/lib/active_storage/service/gcs_service.rb#L3"
+  bullet:
+    from: { "5.1": [">= 5.4.0"], "5.2": [">= 5.7.0"], "6.0": [">= 6.0.0"], "6.1": [">= 6.1.1"], "7.0": [">= 7.0.0"],
+            "7.1": [">= 7.1.0"], "7.2": [">= 7.2.0"], "8.0": [">= 8.0.0"], "8.1": [">= 8.1.0"] }
+    raises: "Bullet raises on an Active Record minor it doesn't know"
+    used_if: { pattern: "\\bBullet\\.enable\\s*=" }
+    source: "https://github.com/flyerhzm/bullet/blob/8.1.0/lib/bullet/dependency.rb"

data/lib/rails_preflight/config_analyzer.rb

@@ -0,0 +1,46 @@
+# lib/rails_preflight/config_analyzer.rb
+module RailsPreflight
+  class ConfigAnalyzer
+    def initialize(root_path = Dir.pwd, current_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
+    end
+
+    def run
+      result = { title: "Configuration", status: :passed, checks: [], confidence: :high }
+
+      app_config = File.join(@root_path, 'config', 'application.rb')
+      if File.exist?(app_config)
+        check_load_defaults(File.read(app_config), result[:checks])
+      else
+        result[:checks] << { message: "config/application.rb not found.", status: :warning, kind: :unknown }
+      end
+
+      if result[:checks].any?
+        result[:status] = :warning
+      else
+        result[:checks] << { message: "No configuration issues found.", status: :passed }
+      end
+
+      result
+    end
+
+    private
+
+    def check_load_defaults(content, checks)
+      match = content.match(/^\s*config\.load_defaults\b\s*\(?\s*["']?(\d+\.\d+)?/)
+
+      if match.nil?
+        # load_defaults arrived in Rails 5.1
+        return if @current_rails && @current_rails < Gem::Version.new("5.1")
+        checks << { message: "config.load_defaults missing in application.rb. Without it, the app keeps legacy framework defaults unless each is set by hand.", status: :warning, fix_effort: :medium }
+      elsif match[1] && @current_rails && Gem::Version.new(match[1]) < @current_rails
+        message = "load_defaults #{match[1]} is behind Rails #{@current_rails}: framework defaults added after #{match[1]} are not enabled."
+        pending = Dir.glob(File.join(@root_path, 'config', 'initializers', 'new_framework_defaults*.rb')).map { |f| File.basename(f) }
+        message += " Found #{pending.join(', ')}, so enabling them looks in progress." if pending.any?
+        checks << { message: message, status: :warning, fix_effort: :medium }
+      end
+    end
+  end
+end

data/lib/rails_preflight/database_analyzer.rb

@@ -0,0 +1,64 @@
+# lib/rails_preflight/database_analyzer.rb
+
+module RailsPreflight
+  class DatabaseAnalyzer
+    def initialize(project_path, rules = [])
+      @schema_path = File.join(project_path, "db/schema.rb")
+      @structure_path = File.join(project_path, "db/structure.sql")
+      @rules = rules || []
+      @warnings = []
+    end
+
+    def run
+      # Pattern-based, so medium confidence
+      result = { title: "Database Schema", status: :passed, checks: [], confidence: :medium }
+
+      unless File.exist?(@schema_path)
+        result[:status] = :warning
+        # ponytail: structure.sql is only noted; reading its CREATE TABLEs is on the roadmap.
+        message = if File.exist?(@structure_path)
+                    "The schema is in db/structure.sql, which isn't read yet, so the schema checks (table charset, integer primary keys) were skipped. Check those in the SQL by hand."
+                  else
+                    "No db/schema.rb found. Skipping database checks."
+                  end
+        result[:checks] << { message: message, status: :warning, kind: :unknown }
+        return result
+      end
+
+      if @rules.empty?
+        result[:checks] << { message: "No database checks apply to this target Rails version.", status: :passed }
+        return result
+      end
+
+      content = File.read(@schema_path)
+      scan_schema(content)
+
+      if @warnings.any?
+        result[:status] = @warnings.any? { |w| w[:severity] == 'critical' } ? :failed : :warning
+        @warnings.each do |w|
+           result[:checks] << {
+             message: w[:message],
+             status: w[:severity] == 'critical' ? :failed : :warning
+           }
+        end
+      end
+
+      result
+    end
+
+    private
+
+    def scan_schema(content)
+      @rules.each do |rule|
+        pattern = Regexp.new(rule['pattern'])
+        if content.match?(pattern)
+          @warnings << {
+            type: rule['name'],
+            message: rule['message'],
+            severity: rule['type']
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rails_preflight/deprecation_analyzer.rb

@@ -0,0 +1,214 @@
+module RailsPreflight
+  require 'pathname'
+  class DeprecationAnalyzer
+    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
+    # 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.
+    COMMENTS = {
+      '.haml' => [%r{\A/}, /\A-#/],
+      '.slim' => [%r{\A/[!\[]}, %r{\A/(?![!\[])}]
+    }.freeze
+    RUBY_COMMENT = [/\A(?:#|<%#)/, nil].freeze
+    # A rule runs on the kinds of files its `files:` lists, code by default.
+    # scripts: where rake tasks get called from outside Ruby code. yaml: the app's own config files.
+    FILE_GLOBS = {
+      'scripts' => %w[bin/* script/**/* Procfile* Makefile Dockerfile* *.sh .github/workflows/*.{yml,yaml}
+                      .circleci/config.yml .gitlab-ci.yml .travis.yml],
+      'yaml' => %w[config/**/*.yml config/**/*.yml.erb]
+    }.freeze
+    # 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)
+      @root_path = root_path
+      @rules = YAML.load_file(database_path)
+      @target_rails = target_rails
+      @current_rails = current_rails
+    end
+
+    def run
+      result = { title: "Deprecation Warnings", status: :passed, checks: [], confidence: :medium }
+
+      warnings = scan_files(@rules['deprecations'].reject { |rule| rule['unless_gem'] && kept_by_gem?(rule['unless_gem']) })
+
+      if warnings.any?
+        # Group warnings by message
+        grouped_warnings = warnings.group_by { |w| w[:message] }
+        
+        grouped_warnings.each do |message, occurrences|
+          rule = occurrences.first
+          info = rule[:severity].to_s.downcase == "info"
+          # An API this upgrade removes blocks it; one removed before the current Rails is already broken
+          # (or dead code); otherwise it's a warning to fix.
+          removed_in = rule[:removed_in]
+          status = info ? :passed : (removed_by_target?(removed_in) || already_removed?(removed_in) ? :failed : :warning)
+
+          result[:checks] << {
+            message: message,
+            status: status,
+            kind: (:tip if info) || (:broken if already_removed?(removed_in)),
+            rule: rule[:rule],
+            removed_in: removed_in,
+            fix_effort: (rule[:fix_effort] || "low").to_sym,
+            confidence: rule[:confidence]&.downcase&.to_sym,
+            source: rule[:guide_link],
+            files: occurrences.map { |hit| hit.slice(:file, :line, :snippet, :test) }
+          }
+        end
+
+        statuses = result[:checks].map { |c| c[:status] }
+        result[:status] = statuses.include?(:failed) ? :failed : (statuses.include?(:warning) ? :warning : :passed)
+      else
+        result[:checks] << { message: "No obvious deprecated patterns found (this scan is static; check your deprecation logs too).", status: :passed }
+      end
+      
+      # Rubocop Advisory Check
+      if check_rubocop_rails
+        result[:checks] << { 
+          message: "rubocop-rails is installed. Run `bundle exec rubocop -a` to auto-fix more deprecations.",
+          status: :passed 
+        }
+      else
+        result[:checks] << { 
+          message: "Install rubocop-rails. It can auto-fix many deprecations this tool only detects.",
+          status: :passed,
+          kind: :tip
+        }
+      end
+
+      result
+    end
+
+    # One pass over the files, every rule tested per line: a rule costs a regex, not a re-read.
+    def scan_files(rules)
+      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'] }
+      FILE_GLOBS.each do |kind, globs|
+        Dir.glob(globs.map { |glob| File.join(@root_path, glob) }).each { |file| files[file] ||= kind }
+      end
+
+      files.each do |file, kind|
+        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/')
+
+        under = ->(paths) { paths.any? { |path| relative_path == path || relative_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)
+        # 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.
+        needs_receiver = applicable.select do |_regex, rule|
+          (rule['needs_receiver_in'] && under.(rule['needs_receiver_in'])) ||
+            (rule['skip_bare_if_local'] && local?(content, rule['skip_bare_if_local']))
+        end.map(&:last)
+
+        line_comment, silent_comment = COMMENTS.fetch(File.extname(file), RUBY_COMMENT)
+        silenced = nil # indent of the silent comment the current lines sit under
+        content.each_line.with_index(1) do |line, line_num|
+          indent = line[/\A[ \t]*/].size
+          next if silenced && (line.strip.empty? || indent > silenced)
+
+          silenced = nil
+          code = line.lstrip
+          if silent_comment&.match?(code)
+            silenced = indent
+            next
+          end
+          # Skip comments and method definitions (e.g. "def update_attributes") to avoid false positives
+          next if line_comment.match?(code) || code.start_with?("def ")
+
+          applicable.each do |regex, rule|
+            next unless (match = regex.match(line))
+            next if needs_receiver.include?(rule) && !match.pre_match.end_with?(".")
+            # `respond_to?(:x)` or `try(:x)` checks for the API, it doesn't use it; the line still counts if it uses it too.
+            next if match.pre_match.match?(/(?:respond_to\?|try)\(\s*:\z/) && line.scan(regex).size == 1
+
+            found << {
+              message: rule['message'],
+              rule: rule['id'],
+              file: relative_path,
+              line: line_num,
+              test: test,
+              snippet: redact(line.strip),
+              confidence: rule['confidence'],
+              guide_link: rule['guide_link'],
+              removed_in: rule['removed_in'],
+              severity: rule['severity'],
+              fix_effort: rule['fix_effort']
+            }
+          end
+        end
+      end
+      found
+    end
+
+    private
+
+    # Quoted strings, and plain `name: value` / `NAME=value` values (YAML, shell, CI config), become [hidden].
+    # ponytail: over-hides (ENV["SECRET_TOKEN"] loses its name too); the file and line still point to it.
+    def redact(line)
+      return line unless line.match?(SECRET_NAME)
+
+      line.gsub(/(["'])(?:\\.|(?!\1).)*\1/) { "#{$1}[hidden]#{$1}" }
+          .gsub(/((?:#{SECRET_NAME.source})\w*\s*(?:=>|[:=])\s*)[^"'\s#,][^#,]*?(?=\s*(?:#|,|$))/i) { "#{$1}[hidden]" }
+    end
+
+    # `name = ...`, `name ||= ...`, a block parameter (`do |x, name|`) or a method parameter.
+    def local?(content, name)
+      # [ \t], not \s: each part stays on one line (`def valid?` then `errors` on the next isn't a parameter).
+      content.match?(/(?<![.@\w])#{name}[ \t]*(?:\|\|)?=(?![=~>])|(?:\bdo|\{)[ \t]*\|[\w \t,*&]*\b#{name}\b[\w \t,*&]*\||
+                      ^[ \t]*def[ \t]+(?:self\.)?\w+[!?]?(?:[ \t]*\([^)\n]*\b#{name}\b|[ \t]+[^(=;\n]*\b#{name}\b)/x)
+    end
+
+    # Removed at or before the current version: the app already runs without it.
+    def already_removed?(removed_in)
+      removed_in && @current_rails && Gem::Version.new(removed_in.to_s) <= Gem::Version.new(@current_rails)
+    end
+
+    # Removed after the current version and by the target: this upgrade breaks it.
+    def removed_by_target?(removed_in)
+      return false unless removed_in && @target_rails
+      removed = Gem::Version.new(removed_in.to_s)
+      removed <= Gem::Version.new(@target_rails) && (@current_rails.nil? || removed > Gem::Version.new(@current_rails))
+    end
+
+    def check_rubocop_rails
+      locked?("rubocop-rails")
+    end
+
+    # `unless_gem:` names a gem, optionally with a version ("benchmark >= 0.5.0"), that keeps the API working when the
+    # Gemfile lists it: record_tag_helper keeps div_for, benchmark 0.5+ keeps Benchmark.ms. Only a gem the Gemfile lists
+    # counts; one another gem pulls in can disappear on the upgrade (Active Support 8.1 drops benchmark).
+    def kept_by_gem?(spec)
+      name, requirement = spec.split(" ", 2)
+      version = locked_version(name)
+      direct = lockfile[/^DEPENDENCIES\n((?: {2}.*\n?)*)/, 1].to_s.lines.any? { |line| line.strip[/\A[^\s!]+/] == name }
+      direct && version && Gem::Requirement.new(requirement || ">= 0").satisfied_by?(version)
+    end
+
+    def locked?(gem)
+      !locked_version(gem).nil?
+    end
+
+    def locked_version(gem)
+      version = lockfile[/^ {4}#{Regexp.escape(gem)} \(([^)\s-]+)/, 1]
+      version && Gem::Version.new(version)
+    end
+
+    def lockfile
+      @lockfile ||= File.exist?(File.join(@root_path, "Gemfile.lock")) ? File.read(File.join(@root_path, "Gemfile.lock")) : ""
+    end
+
+  end
+end

data/lib/rails_preflight/docker_analyzer.rb

@@ -0,0 +1,124 @@
+# lib/rails_preflight/docker_analyzer.rb
+module RailsPreflight
+  class DockerAnalyzer
+    # Update when a release goes EOL: Ruby 3.2 (2026-03-31), Node 20 (2026-04-30).
+    RUBY_EOL_BELOW = "3.3"
+    NODE_EOL_BELOW = 22
+
+    # Official image, with or without registry prefix: `ruby:3.3`, `docker.io/library/ruby:$RUBY_VERSION-slim`.
+    RUBY_IMAGE = %r{^\s*FROM\s+(?:--platform=\S+\s+)?(?:\S+/)?ruby:(\S+)}i
+
+    # checked_ruby: app Ruby the Ruby Version section already checked for EOL
+    def initialize(root_path = Dir.pwd, checked_ruby: nil)
+      @dockerfile_path = File.join(root_path, "Dockerfile")
+      @checked_ruby = checked_ruby
+    end
+
+    # Version from the ruby image tag, resolving ARG defaults as in Rails' generated Dockerfile.
+    def detect_ruby_version
+      return nil unless File.exist?(@dockerfile_path)
+      content = File.read(@dockerfile_path)
+      match = content.match(RUBY_IMAGE)
+      return nil unless match
+
+      args = content.scan(/^\s*ARG\s+(\w+)=["']?([^\s"']+)/).to_h
+      match[1].gsub(/\$\{?(\w+)\}?/) { args[$1].to_s }[/\A\d+\.\d+(?:\.\d+)?/]
+    end
+
+    def run
+      result = { title: "Docker Configuration", status: :passed, checks: [], confidence: :medium }
+
+      unless File.exist?(@dockerfile_path)
+        result[:checks] << { message: "No Dockerfile found. Docker checks skipped.", status: :passed }
+        return result
+      end
+
+      content = File.read(@dockerfile_path)
+      ruby_version = detect_ruby_version
+      # Official ruby images set LANG=C.UTF-8, and their Debian variants ship tzdata.
+      official_ruby = content.match?(RUBY_IMAGE)
+      alpine = content.match?(/alpine/)
+
+      check_ruby_version(ruby_version, result)
+      check_package_manager_pitfalls(content, result)
+      check_alpine_pitfalls(content, result) if alpine
+      check_node_version(content, result)
+      check_eol_base_image(ruby_version, result)
+      check_locale(content, result) unless official_ruby
+      check_tzdata(content, result) if alpine || !official_ruby
+      check_openssl_mismatch(content, ruby_version, result)
+
+      update_overall_status(result)
+      result
+    end
+
+    private
+
+    def check_ruby_version(ruby_version, result)
+      if ruby_version
+        result[:checks] << { message: "Dockerfile uses Ruby #{ruby_version} base image", status: :passed, fix_effort: :low }
+      else
+        result[:checks] << { message: "Could not detect a versioned ruby base image in Dockerfile.", status: :warning, kind: :unknown, fix_effort: :medium }
+      end
+    end
+
+    def check_package_manager_pitfalls(content, result)
+      if content.include?("bundle install") && !content.match?(/without/i)
+        result[:checks] << { message: "'bundle install' also installs development and test gems. Set BUNDLE_WITHOUT=\"development:test\".", status: :passed, kind: :tip, fix_effort: :low }
+      end
+    end
+
+    def check_alpine_pitfalls(content, result)
+      unless content.match?(/build-base|libxml2-dev|postgresql-dev/)
+        result[:checks] << { message: "Alpine image without build-base: gems with native extensions may fail to install. Add 'apk add build-base'.", status: :warning, fix_effort: :medium }
+      end
+    end
+
+    def check_node_version(content, result)
+      # Support ENV NODE_VERSION 12.0.0 (space) and ENV NODE_VERSION=12.0.0 (equals)
+      if match = content.match(/NODE_VERSION\s*[:=\s]\s*['"]?(\d+)/)
+        major_version = match[1].to_i
+        if major_version < NODE_EOL_BELOW
+          result[:checks] << { message: "Node #{major_version} is end-of-life. Upgrade to Node #{NODE_EOL_BELOW}+.", status: :warning, fix_effort: :medium }
+        end
+      end
+    end
+
+    def check_eol_base_image(ruby_version, result)
+      # EOL is per minor version; same minor as the checked app Ruby was already reported
+      return if ruby_version && @checked_ruby && ruby_version.split(".").first(2) == @checked_ruby.split(".").first(2)
+
+      if ruby_version && Gem::Version.new(ruby_version) < Gem::Version.new(RUBY_EOL_BELOW)
+        result[:checks] << { message: "Dockerfile Ruby #{ruby_version} is end-of-life. Upgrade to Ruby #{RUBY_EOL_BELOW}+.", status: :warning, fix_effort: :high }
+      end
+    end
+
+    def check_locale(content, result)
+      unless content.match?(/^\s*ENV\s+(LANG|LC_ALL)/)
+        result[:checks] << { message: "No ENV LANG or LC_ALL set, which can cause encoding errors.", status: :warning, fix_effort: :low }
+      end
+    end
+
+    def check_tzdata(content, result)
+      unless content.match?(/tzdata/)
+        result[:checks] << { message: "tzdata isn't installed. Time zone lookups need it, or the tzinfo-data gem.", status: :warning, fix_effort: :low }
+      end
+    end
+
+    def check_openssl_mismatch(content, ruby_version, result)
+      # Alpine >= 3.17 ships OpenSSL 3, which Ruby < 3.1's openssl gem doesn't support.
+      alpine_version = content[/alpine(\d+\.\d+)/, 1]
+      return unless ruby_version && alpine_version
+
+      if Gem::Version.new(alpine_version) >= Gem::Version.new("3.17") && Gem::Version.new(ruby_version) < Gem::Version.new("3.1")
+        result[:checks] << { message: "Alpine #{alpine_version} ships OpenSSL 3, which Ruby #{ruby_version} (< 3.1) does not support.", status: :warning, fix_effort: :high }
+      end
+    end
+
+    def update_overall_status(result)
+      if result[:checks].any? { |c| c[:status] != :passed }
+        result[:status] = :warning
+      end
+    end
+  end
+end