rails_preflight 0.1.0

data/lib/rails_preflight/gem_analyzer.rb

@@ -0,0 +1,178 @@
+module RailsPreflight
+  # Gems that stop working, or are on their way out, across the upgrade: Rails limits their locked versions
+  # declare in Gemfile.lock, plus the curated list in database/gems.yml for limits only a README states.
+  class GemAnalyzer
+    DATA_PATH = File.expand_path('../../database/gems.yml', __dir__)
+    RAILS_GEMS = %w[rails railties actioncable actionmailbox actionmailer actionpack actiontext actionview
+                    activejob activemodel activerecord activestorage activesupport].freeze
+
+    # specs: Gemfile.lock specs. hops: the Rails minors the upgrade passes through, after the current one, ending at the target.
+    # direct: gem names the Gemfile lists (Gemfile.lock DEPENDENCIES).
+    # last_releases: { gem name => latest release time (ISO 8601) } from rubygems.org; nil when not looked up (--offline).
+    # target_released: the target Rails release date (YYYY-MM-DD), nil when unknown.
+    def initialize(project_path, specs, hops:, direct: [], last_releases: {}, target_released: nil, database_path: DATA_PATH)
+      @project_path = project_path
+      @specs = specs
+      @hops = hops
+      @direct = direct
+      @last_releases = last_releases
+      @target_released = target_released
+      data = YAML.load_file(database_path)
+      @entries = data.fetch('gems', [])
+      @adapter_requirements = data.fetch('adapter_requirements', {})
+      @dropped_by_rails = data.fetch('dropped_by_rails', {})
+      @version_limits = data.fetch('version_limits', {})
+    end
+
+    def run
+      result = { title: "Gem Compatibility", status: :passed, checks: [], confidence: :medium }
+      return result if @hops.empty? # already on the target
+      result[:checks].concat(locked_limits, adapter_limits, version_limits, dropped_by_rails, curated)
+      result[:checks].concat(stale(result[:checks].filter_map { |check| check[:gem] }))
+
+      if result[:checks].empty?
+        result[:checks] << { message: "No locked gem limits Rails below #{@hops.last}, and none is on the list of retired gems.", status: :passed }
+      else
+        statuses = result[:checks].map { |c| c[:status] }
+        result[:status] = statuses.include?(:failed) ? :failed : :warning
+      end
+      result
+    end
+
+    private
+
+    # A gem whose locked version requires, say, railties < 6.1 blocks the 6.1 hop until it's upgraded or replaced.
+    def locked_limits
+      @specs.filter_map do |spec|
+        next if RAILS_GEMS.include?(spec.name)
+
+        limits = spec.dependencies.select { |dep| RAILS_GEMS.include?(dep.name) }
+        breaks_in = @hops.find { |hop| limits.any? { |dep| !allows?(dep.requirement, hop) } }
+        next unless breaks_in
+
+        requires = limits.map { |dep| "#{dep.name} #{dep.requirement}" }.join(", ")
+        { message: "#{spec.name} #{spec.version} requires #{requires}, so it doesn't install on Rails #{breaks_in}. Upgrade it to a release that allows #{breaks_in}, or replace it.",
+          status: :failed, removed_in: breaks_in, fix_effort: :medium, gem: spec.name, version: spec.version.to_s, requires: requires }
+      end
+    end
+
+    # sqlite3 1.3 still installs next to Rails 6.0, but Rails refuses to load it as the adapter.
+    def adapter_limits
+      @specs.filter_map do |spec|
+        breaks_in = @hops.find do |hop|
+          requirement = @adapter_requirements.dig(hop, spec.name)
+          requirement && !Gem::Requirement.new(*requirement).satisfied_by?(spec.version)
+        end
+        next unless breaks_in
+
+        requirement = @adapter_requirements[breaks_in][spec.name].join(", ")
+        adapter = spec.name == "pg" ? "postgresql" : spec.name
+        { message: "#{spec.name} #{spec.version} doesn't load on Rails #{breaks_in}, which requires #{spec.name} #{requirement}. Upgrade it in the same step.",
+          status: :failed, removed_in: breaks_in, fix_effort: :low, gem: spec.name, version: spec.version.to_s, requires: "#{spec.name} #{requirement}",
+          source: "https://github.com/rails/rails/blob/#{breaks_in.tr('.', '-')}-stable/activerecord/lib/active_record/connection_adapters/#{adapter}_adapter.rb" }
+      end
+    end
+
+    # listen 3.1 installs next to Rails 7.0, but the evented file watcher refuses to load it. Only checked when the app uses the feature.
+    def version_limits
+      locked = @specs.to_h { |spec| [spec.name, spec.version] }
+      @version_limits.filter_map do |name, entry|
+        version = locked[name]
+        breaks_in = version && @hops.find do |hop|
+          requirement = requirement_at(entry['from'], hop)
+          requirement && !Gem::Requirement.new(*requirement).satisfied_by?(version)
+        end
+        next unless breaks_in && used?(entry['used_if'])
+
+        requirement = "#{name} #{requirement_at(entry['from'], breaks_in).join(', ')}"
+        why = entry['raises'] ? ": #{entry['raises']}; Rails #{breaks_in} needs #{requirement}" : ", which requires #{requirement} for #{entry['for']}"
+        { message: "#{name} #{version} doesn't load on Rails #{breaks_in}#{why}. Upgrade it in the same step.",
+          status: :failed, removed_in: breaks_in, fix_effort: :low, gem: name, version: version.to_s, requires: requirement, source: entry['source'] }
+      end
+    end
+
+    # The requirement under the latest `from` key at or before the hop.
+    def requirement_at(from, hop)
+      from.select { |since, _| Gem::Version.new(since) <= Gem::Version.new(hop) }.max_by { |since, _| Gem::Version.new(since) }&.last
+    end
+
+    # A gem the app gets only through `rails` disappears on the hop where rails stops depending on it.
+    # Still pulled in by the Gemfile or another gem (sass-rails needs sprockets-rails), it stays; unused, it doesn't matter.
+    def dropped_by_rails
+      locked = @specs.map(&:name)
+      kept = @direct + @specs.reject { |spec| spec.name == "rails" }.flat_map { |spec| spec.dependencies.map(&:name) }
+      @hops.flat_map do |hop|
+        @dropped_by_rails.fetch(hop, {}).select { |name, used_if| locked.include?(name) && !kept.include?(name) && used?(used_if) }.keys.map do |name|
+          { message: "Rails #{hop} no longer depends on #{name}, and the Gemfile doesn't list it. Add gem \"#{name}\" to the Gemfile in the same step.",
+            status: :failed, removed_in: hop, fix_effort: :low, gem: name }
+        end
+      end
+    end
+
+    def used?(used_if)
+      return true if used_if.fetch('paths', []).any? { |path| File.exist?(File.join(@project_path, path)) }
+
+      pattern = used_if['pattern'] && Regexp.new(used_if['pattern'])
+      pattern && Dir.glob(File.join(@project_path, used_if.fetch('files', "config/**/*.rb"))).any? do |file|
+        File.foreach(file).any? { |line| !line.lstrip.start_with?("#") && line.match?(pattern) }
+      end
+    end
+
+    # Gems with no release since before the target Rails shipped: nothing says they break, but nobody may have tried.
+    # One grouped "couldn't check", oldest first. Gems already reported, or on the curated list, are left out.
+    def stale(reported)
+      if @last_releases.nil?
+        return [{ message: "Skipped the gem release-date check (--offline): gems not updated since before Rails #{@hops.last} aren't flagged.", status: :passed, kind: :tip }]
+      end
+      return [] unless @target_released
+
+      skip = reported + @entries.map { |entry| entry['name'] }
+      old = @last_releases.select { |name, at| at[0, 10] < @target_released && !skip.include?(name) }.sort_by { |_, at| at }
+      return [] if old.empty?
+
+      [{ message: "#{old.size} #{old.size == 1 ? 'gem' : 'gems'} that depend on Rails had no release since before Rails #{@hops.last} shipped (#{@target_released}). Check they work on #{@hops.last}, or find replacements.",
+         status: :warning, kind: :unknown, fix_effort: :unknown,
+         names: old.map { |name, at| "#{name} (last release #{at[0, 10]})" } }]
+    end
+
+    # Any patch release of the minor counts: `>= 7.0.1` allows 7.0.
+    def allows?(requirement, minor)
+      [minor, "#{minor}.99"].any? { |v| requirement.satisfied_by?(Gem::Version.new(v)) }
+    end
+
+    def curated
+      locked = @specs.to_h { |spec| [spec.name, spec.version] }
+      @entries.filter_map do |entry|
+        version = locked[entry['name']]
+        next unless version
+        next if entry['fixed_in'] && version >= Gem::Version.new(entry['fixed_in'])
+
+        files = usage(entry['pattern'])
+        next if entry['only_if_used'] && files.empty?
+
+        breaks_in = entry['breaks_in']
+        blocks = @hops.include?(breaks_in) # every hop is past the current Rails
+        message = "#{entry['name']} #{entry['fixed_in'] ? "#{version} " : ''}#{entry['message']}"
+        broken = breaks_in && !blocks && Gem::Version.new(breaks_in) <= Gem::Version.new(@hops.last)
+        if broken
+          message += " It doesn't work from Rails #{breaks_in}, which this app is already on."
+        elsif breaks_in && !blocks
+          message += " It doesn't work from Rails #{breaks_in}, so plan the move before then."
+        end
+        message += " Used in #{files.size} #{files.size == 1 ? 'file' : 'files'}." if files
+
+        { message: message, status: blocks || broken ? :failed : :warning, kind: (:broken if broken), removed_in: breaks_in,
+          gem: entry['name'], version: version.to_s, source: entry['source'], files: Array(files).map { |file| { file: file } },
+          fix_effort: entry['fix_effort']&.to_sym }
+      end
+    end
+
+    # Files matching the entry's pattern, nil when it has none.
+    def usage(pattern)
+      return unless pattern
+
+      rule = { 'pattern' => pattern, 'message' => pattern }
+      DeprecationAnalyzer.new(@project_path).scan_files([rule]).map { |hit| hit[:file] }.uniq.sort
+    end
+  end
+end

data/lib/rails_preflight/json_report.rb

@@ -0,0 +1,45 @@
+require 'json'
+
+module RailsPreflight
+  # The report as JSON, for CI and other tools. Findings are the analyzers' checks with their parts (see
+  # SummaryCalculator), plus :section and :kind. No timestamp: the same app gives the same output.
+  # Schema 1 may still change before 1.0; the number goes up when it does.
+  class JsonReport
+    SCHEMA = 1
+
+    def initialize(data)
+      @data = data
+      @summary = data[:summary] || {}
+    end
+
+    def generate
+      ruby, source = @data[:ruby]
+      report = {
+        schema: SCHEMA,
+        tool: { name: "rails-preflight", version: VERSION },
+        app: @data[:app],
+        current_rails: @data[:current_rails],
+        target_rails: @data[:target_rails],
+        ruby: ({ version: ruby, source: source } if ruby),
+        offline: @data[:offline],
+        verdict: @summary[:verdict],
+        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) })
+        end,
+        ahead: @summary.fetch(:ahead, {}).transform_values { |entries| entries.map { |entry| finding(entry) } },
+        cant_see: @summary.fetch(:cant_see, []).map { |entry| finding(entry) }
+      }
+      "#{JSON.pretty_generate(report)}\n"
+    end
+
+    private
+
+    # :status is how the analyzer saw it; :kind is what the report counts it as.
+    def finding(entry)
+      # Hash#except needs Ruby 3.0; the tool runs on 2.7.
+      entry.slice(:section, :kind).merge(entry.reject { |key, _| %i[status section kind].include?(key) }).compact
+    end
+  end
+end

data/lib/rails_preflight/markdown_report.rb

@@ -0,0 +1,72 @@
+module RailsPreflight
+  # The report as Markdown: for issues, PRs and coding agents. Takes the same data as ReportGenerator
+  # and renders only the findings' parts, never the HTML.
+  class MarkdownReport
+    LABELS = { broken: "Broken", blocker: "Blocker", to_fix: "To fix", tip: "Tip" }.freeze
+
+    def initialize(data)
+      @data = data
+      @summary = data[:summary] || {}
+    end
+
+    def generate
+      out = []
+      out << "# #{@data[:app]}: Rails #{@data[:current_rails] || 'unknown'} to #{@data[:target_rails]}"
+      out << @summary[:verdict]
+      counts = { "Already broken" => :broken, "Blockers" => :blockers, "To fix" => :to_fix, "Couldn't check" => :unknowns }
+      out << counts.map { |label, key| "#{label}: #{@summary.fetch(key, []).size}" }.join(" · ")
+      out << "> For a coding agent: take one step at a time, in order. After each step, run the test suite and fix what fails " \
+             "before starting the next. Leave \"Ahead\" and \"Couldn't check\" alone unless asked."
+
+      before = @summary.fetch(:before, [])
+      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]}.")
+      end
+      @summary.fetch(:ahead, {}).each do |version, entries|
+        out << section("Ahead: removed in #{version}, not needed for #{@data[:target_rails]}", entries)
+      end
+      cant_see = @summary.fetch(:cant_see, [])
+      if cant_see.any?
+        out << "## Couldn't check\n\n" + cant_see.map { |entry| "- #{text(entry[:message])}#{": #{entry[:names].join(', ')}" if entry[:names]&.any?}" }.join("\n")
+      end
+      out << "Made with [rails-preflight](#{ReportGenerator::REPO_URL}) #{VERSION}. Run it again after each step."
+      "#{out.join("\n\n")}\n"
+    end
+
+    private
+
+    def section(title, entries, note = nil)
+      lines = entries.map { |entry| finding(entry) }
+      lines = ["Nothing found."] if lines.empty?
+      ["## #{title}", note, lines.join("\n")].compact.join("\n\n")
+    end
+
+    # A checkbox per finding to fix, then where it is: file:line with the matched line, or the files that use a gem.
+    def finding(entry)
+      label = LABELS.fetch(entry[:kind], entry[:kind].to_s)
+      box = entry[:kind] == :tip ? "-" : "- [ ]"
+      cite = " ([source](#{entry[:source]}))" if entry[:source].to_s.start_with?("https://")
+      lines = ["#{box} **#{label}:** #{text(entry[:message])}#{cite}"]
+      Array(entry[:files]).each do |hit|
+        place = hit[:line] ? "#{hit[:file]}:#{hit[:line]}" : hit[:file]
+        lines << "  - #{code(place)}#{" #{code(hit[:snippet])}" if hit[:snippet]}"
+      end
+      lines.join("\n")
+    end
+
+    # 'quoted' names become code, as in the HTML; an apostrophe inside a word (doesn't) stays.
+    def text(message)
+      message.to_s.gsub(/(?<!\w)'(.+?)'(?!\w)/) { code($1) }
+    end
+
+    # A code span that survives backticks in the snippet.
+    def code(value)
+      value = value.to_s
+      fence = "`" * ((value.scan(/`+/).map(&:size).max || 0) + 1)
+      pad = value.start_with?("`") || value.end_with?("`") ? " " : ""
+      "#{fence}#{pad}#{value}#{pad}#{fence}"
+    end
+  end
+end