hayaoki 0.1.0

data/lib/hayaoki/boot_report/rules/base.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "../gemfile"
+
+module Hayaoki
+  module BootReport
+    # Report / RunResult は Hash のキーが String でも Symbol でも動くように、値の取り出しはこの補助を通す。
+    module Access
+      module_function
+
+      # obj が Hash なら String / Symbol 両方のキーを試す。それ以外は同名のメソッドを呼ぶ。
+      def get(obj, *keys)
+        keys.reduce(obj) do |cur, key|
+          return nil if cur.nil?
+          if cur.is_a?(Hash)
+            if cur.key?(key.to_s) then cur[key.to_s]
+            elsif cur.key?(key.to_sym) then cur[key.to_sym]
+            end
+          elsif cur.respond_to?(key)
+            cur.public_send(key)
+          end
+        end
+      end
+
+      # { "median" => x, ... } でも数値でもよい。
+      def med(stat)
+        v = stat.is_a?(Hash) ? get(stat, :median) : stat
+        v.is_a?(Numeric) ? v.to_f : nil
+      end
+
+      def round(x) = x.nil? ? nil : x.round(1)
+    end
+
+    # ルールが受け取る入力一式。
+    Context = Struct.new(:report, :app_dir, :result, :initializer_threshold_ms, :gem_threshold_ms, keyword_init: true) do
+      def gems = Array(Access.get(report, :gems))
+      def meta = Access.get(report, :meta) || {}
+      def env = (Access.get(meta, :env) || Access.get(result, :meta, :env)).to_s
+
+      def warnings
+        (Array(Access.get(report, :warnings)) + Array(Access.get(result, :meta, :warnings))).map(&:to_s)
+      end
+
+      def phase_ms(name) = Access.med(Access.get(report, :phases, name))
+    end
+
+    module Rules
+      # 各ルールの基底。call は Suggestion の配列を返す。
+      class Base
+        include Hayaoki::BootReport::Access
+
+        def self.rule_id = name.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+
+        def initialize(ctx)
+          @ctx = ctx
+        end
+
+        def call = raise(NotImplementedError)
+
+        private
+
+        attr_reader :ctx
+
+        def suggestion(confidence, title:, evidence:, action:, savings: nil)
+          Suggestion.new(rule: self.class.rule_id, confidence: confidence, title: title, evidence: evidence,
+                         estimated_savings_ms: savings && savings.round(1), action: action)
+        end
+
+        # Gemfile のパス。BUNDLE_GEMFILE (絶対 / app からの相対) > <app>/Gemfile > <app>/gems.rb。無ければ nil
+        def gemfile_path
+          return @gemfile_path if defined?(@gemfile_path)
+          app = ctx.app_dir.to_s
+          env = ENV["BUNDLE_GEMFILE"].to_s
+          candidates = []
+          candidates << File.expand_path(env, app) unless env.empty?
+          candidates << File.join(app, "Gemfile") << File.join(app, "gems.rb")
+          @gemfile_path = candidates.find { File.file?(_1) }
+        end
+
+        # Gemfile の中身 (無ければ nil)
+        def gemfile
+          path = gemfile_path
+          path && File.read(path)
+        rescue SystemCallError
+          nil
+        end
+
+        # Gemfile を解析した { gem 名 => Gemfile::Entry } (eval_gemfile 先を含む)。Gemfile が無ければ nil。
+        def gemfile_entries
+          return @gemfile_entries if defined?(@gemfile_entries)
+          src = gemfile
+          @gemfile_entries = src && Hayaoki::BootReport::Gemfile.parse(src, dir: File.dirname(gemfile_path))
+        end
+
+        # 子プロセスの payload が記録した gem の full_gem_path ({ name => path })。計測対象 app の bundle を指す。
+        def gem_paths = @gem_paths ||= spec_field(1)
+
+        # 子プロセスが記録した gem のバージョン (アプリの bundle のもの)
+        def gem_versions = @gem_versions ||= spec_field(0)
+
+        def spec_field(i)
+          pl = get(ctx.result, :payloads)
+          lists = pl.is_a?(Hash) ? pl.values : []
+          lists.flatten.each_with_object({}) do |p, h|
+            specs = get(p, :specs)
+            next unless specs.is_a?(Hash)
+            specs.each { |name, info| h[name.to_s] ||= info[i] if info.is_a?(Array) && info[i] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hayaoki/boot_report/rules/bootsnap_ineffective.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Hayaoki
+  module BootReport
+    module Rules
+      # bootsnap が無い / 有効になっていない可能性。
+      class BootsnapIneffective < Base
+        MIN_DIFF_RATIO = 0.05 # cold と warm の差がこれ未満なら有効になっていないとみなす
+        CACHE_WARNING = /BOOTSNAP_CACHE_DIR was not used/
+
+        def call
+          loaded = ctx.gems.any? { |g| get(g, :name).to_s == "bootsnap" }
+          return [missing(loaded_in_gemfile?)] unless loaded
+          out = []
+          out << small_diff
+          out << cache_unused
+          out.compact
+        end
+
+        private
+
+        def loaded_in_gemfile? = !!(gemfile.to_s =~ /^\s*gem\s+["']bootsnap["']/)
+
+        def missing(in_gemfile)
+          if in_gemfile
+            suggestion(:high,
+                       title: "bootsnap is in the Gemfile but does not seem to be loaded at boot",
+                       evidence: [{ "bootsnap_in_gemfile" => true, "loaded_at_boot" => false }],
+                       action: "Check that config/boot.rb contains `require \"bootsnap/setup\"` (after bundler/setup), " \
+                               "or remove `require: false` handling that skips it.")
+          else
+            suggestion(:high,
+                       title: "bootsnap was not loaded; adding it can speed up boot",
+                       evidence: [{ "bootsnap_loaded" => false }],
+                       action: "Add to the Gemfile: gem \"bootsnap\", require: false\n" \
+                               "and to config/boot.rb (after `require \"bundler/setup\"`): require \"bootsnap/setup\"")
+          end
+        end
+
+        def small_diff
+          warm = boot_ms(:warm)
+          cold = boot_ms(:cold)
+          return nil unless warm && cold && cold.positive?
+          diff = cold - warm
+          return nil unless diff / cold < MIN_DIFF_RATIO
+          suggestion(:high,
+                     title: "bootsnap's warm cache shows little benefit over a cold cache (#{(diff / cold * 100).round(1)}%)",
+                     evidence: [{ "cold_ms" => round(cold), "warm_ms" => round(warm), "diff_ms" => round(diff),
+                                  "threshold_pct" => MIN_DIFF_RATIO * 100 }],
+                     action: "Bootsnap may not be configured as expected. Check that Bootsnap.setup (or bootsnap/setup) " \
+                             "runs before the app loads, that cache_dir is writable and persisted between boots, " \
+                             "and that load_path_cache / compile_cache are enabled.")
+        end
+
+        def cache_unused
+          hit = ctx.warnings.grep(CACHE_WARNING)
+          return nil if hit.empty?
+          suggestion(:high,
+                     title: "bootsnap's cache directory stayed empty during measurement",
+                     evidence: hit.map { |w| { "warning" => w } },
+                     action: "The app may call Bootsnap.setup with its own cache_dir, or bootsnap is not active. " \
+                             "Make sure the cache is actually written (default tmp/cache/bootsnap) and kept between deploys/boots.")
+        end
+
+        # 条件ごとの boot 時間 (ms, 中央値)。payload の boot_end_us / exit_us から求める。
+        def boot_ms(cond)
+          list = payloads(cond)
+          vals = list.filter_map do |p|
+            us = get(p, :boot_end_us) || get(p, :exit_us)
+            us && us / 1000.0
+          end
+          return nil if vals.empty?
+          s = vals.sort
+          n = s.size
+          n.odd? ? s[n / 2] : (s[n / 2 - 1] + s[n / 2]) / 2.0
+        end
+
+        def payloads(cond)
+          pl = get(ctx.result, :payloads)
+          return [] unless pl.is_a?(Hash)
+          Array(pl[cond] || pl[cond.to_s]).select { |p| get(p, :status).to_s == "ok" }
+        end
+      end
+    end
+  end
+end

data/lib/hayaoki/boot_report/rules/controller_action_methods.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Hayaoki
+  module BootReport
+    module Rules
+      # AbstractController.eager_load! は全コントローラの action_methods を起動時に計算する。
+      # 遅延にすると、各コントローラの最初のリクエストで自分の分だけ計算する
+      # (Mastodon: 起動 -201ms、336 コントローラ合計 217ms = 1 個あたり約 0.65ms)。
+      class ControllerActionMethods < Base
+        NAME = "AbstractController.eager_load!"
+        MIN_MS = 100.0
+
+        def call
+          e = Array(get(ctx.report, :eager_namespaces)).find { |x| get(x, :name) == NAME } or return []
+          ms = med(get(e, :inclusive_ms))
+          return [] unless ms && ms >= MIN_MS
+          [suggestion(:low,
+                      title: "#{NAME} computes action_methods for every controller at boot (#{round(ms)} ms)",
+                      evidence: [{ "namespace" => NAME, "inclusive_ms" => round(ms), "threshold_ms" => MIN_MS }],
+                      savings: ms,
+                      action: "To compute each controller's action_methods on its first request instead, add\n" \
+                              "  # config/initializers/lazy_action_methods.rb\n" \
+                              "  Rails.application.config.eager_load_namespaces.delete(AbstractController)\n" \
+                              "The work moves to requests, but each request pays only for its own controller " \
+                              "(the total divided by the number of controllers). Useful for serverless and short-lived " \
+                              "processes; for long-running servers, keeping it is usually better.")]
+        end
+      end
+    end
+  end
+end

data/lib/hayaoki/boot_report/rules/dev_gems_in_production.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Hayaoki
+  module BootReport
+    module Rules
+      # 開発・テスト用の既知の gem が、計測した環境 (既定は production) で読み込まれている。
+      class DevGemsInProduction < Base
+        # 完全一致
+        DEV_GEMS = %w[
+          pry byebug debug rubocop web-console listen spring rspec factory_bot factory_bot_rails faker
+          better_errors binding_of_caller bullet annotate annotate_models brakeman guard minitest-reporters
+          capybara selenium-webdriver webdrivers rails-controller-testing shoulda-matchers simplecov
+          database_cleaner database_cleaner-active_record rack-mini-profiler letter_opener derailed_benchmarks
+          rubocop-ast
+        ].freeze
+        # 前方一致 (pry-rails, rubocop-rails, rspec-core, spring-watcher-listen ...)
+        DEV_GEM_PREFIXES = %w[pry- rubocop- rspec- spring- factory_bot_ capybara- guard- web-console- debug_].freeze
+        # 開発・テスト以外の環境ではこの rule は対象外
+        NON_PRODUCTION_ENVS = %w[development test].freeze
+
+        def self.dev_gem?(name)
+          DEV_GEMS.include?(name) || DEV_GEM_PREFIXES.any? { |p| name.start_with?(p) }
+        end
+
+        # テスト用データ生成系は本番で読み込まれると実害 (メモリ・起動時間) が大きいので medium に引き上げる
+        MEDIUM_GEMS = %w[faker factory_bot factory_bot_rails].freeze
+        DEV_GROUPS = %w[development test].freeze
+
+        def call
+          return [] if NON_PRODUCTION_ENVS.include?(ctx.env)
+          entries = gemfile_entries
+          tiers = Hash.new { |h, k| h[k] = [] }
+          ctx.gems.each do |g|
+            name = get(g, :name).to_s
+            next unless get(g, :category).to_s == "gem" && self.class.dev_gem?(name)
+            entry = entries && entries[name]
+            # development/test の group だけに属する gem は本番では読み込まれない
+            next if entry && !entry.groups.empty? && entry.groups.all? { DEV_GROUPS.include?(_1) }
+            ms = med(get(g, :self_ms))
+            row = { "name" => name, "self_ms" => round(ms || 0.0),
+                    "gemfile" => entry ? (entry.groups.empty? ? "direct, no group" : "direct, groups: #{entry.groups.join(",")}") : (entries ? "transitive" : "unknown (no Gemfile)") }
+            tiers[tier(name, entry)] << row
+          end
+          %i[high medium low].filter_map { |t| tiers.key?(t) && build(t, tiers[t]) }
+        end
+
+        private
+
+        # Gemfile に直接書かれ group 無し (= production で読み込まれる) なら high、
+        # 間接依存や Gemfile 不明は確認できないので low。
+        def tier(name, entry)
+          return :low unless entry
+          MEDIUM_GEMS.include?(name) ? :medium : :high
+        end
+
+        def build(tier, found)
+          total = found.sum { |f| f["self_ms"] }
+          names = found.map { |f| f["name"] }
+          env = ctx.env.empty? ? "the measured environment" : ctx.env
+          title = if tier == :low
+            "Development/test gems may be loaded in #{env} via other dependencies (#{names.first(3).join(", ")}#{names.size > 3 ? ", ..." : ""})"
+          else
+            "Development/test gems are loaded in #{env} (#{names.first(3).join(", ")}#{names.size > 3 ? ", ..." : ""})"
+          end
+          action = if tier == :low
+            "These were not found as direct Gemfile entries (transitive dependency or Gemfile not found). " \
+            "Check which gem depends on them (`bundle viz` / `bundle why`) before acting."
+          else
+            "Move them to the development/test groups in the Gemfile, e.g.:\n" \
+            "  group :development, :test do\n    #{names.first(3).map { |n| %(gem "#{n}") }.join("\n    ")}\n  end\n" \
+            "Check first that nothing in production code depends on them."
+          end
+          suggestion(tier, title: title, evidence: found.sort_by { |f| -f["self_ms"] }, savings: total, action: action)
+        end
+      end
+    end
+  end
+end

data/lib/hayaoki/boot_report/rules/devise_reload_routes.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Hayaoki
+  module BootReport
+    module Rules
+      # Devise は before_eager_load で app.reload_routes! を呼ぶ (Devise.reload_routes = true が初期値)。
+      # production では set_routes_reloader_hook でもルーティングを読むので、起動中に 2 回読むことになる。
+      # Mastodon で 194ms 短くなった (bench/boot_variants.rb)。Devise 5.0 からは Devise.mappings を参照したときに
+      # 必要ならルーティングを読むので、false にしても mappings は使える。4.x にはこの処理が無い。
+      class DeviseReloadRoutes < Base
+        SOURCE = "/lib/devise/rails.rb"
+        MIN_MS = 50.0
+
+        def call
+          hook = Array(get(ctx.report, :on_loads)).find do |h|
+            get(h, :name).to_s == "before_eager_load" && get(h, :source).to_s.include?(SOURCE)
+          end or return []
+          ms = med(get(hook, :inclusive_ms))
+          return [] unless ms && ms >= MIN_MS
+          version = gem_versions["devise"]
+          modern = version && Gem::Version.new(version) >= Gem::Version.new("5.0.0.rc")
+          caveat = if modern
+                     "Devise #{version} loads the routes on demand when Devise.mappings is first used, so this is safe " \
+                       "unless your own code reads Devise.mappings during eager loading."
+                   else
+                     "Devise #{version || "(version unknown)"} builds Devise.mappings only when the routes are loaded. " \
+                       "Routes are still loaded later in boot (set_routes_reloader_hook), but code that reads " \
+                       "Devise.mappings during eager loading would see none. Devise 5.0+ removes this risk."
+                   end
+          [suggestion(modern ? :medium : :low,
+                      title: "Devise reloads the routes before eager loading (#{round(ms)} ms); they are loaded again later in boot",
+                      evidence: [{ "hook" => "before_eager_load", "source" => "devise/rails.rb", "inclusive_ms" => round(ms),
+                                   "devise" => version, "threshold_ms" => MIN_MS }],
+                      savings: ms,
+                      action: "In config/initializers/devise.rb:\n" \
+                              "  config.reload_routes = false\n" + caveat)]
+        end
+      end
+    end
+  end
+end

data/lib/hayaoki/boot_report/rules/eager_load_tradeoff.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Hayaoki
+  module BootReport
+    module Rules
+      # eager_load の割合が大きいときの判断材料 (情報のみ)。
+      class EagerLoadTradeoff < Base
+        MIN_RATIO = 0.15
+
+        def call
+          eager = ctx.phase_ms("eager_load")
+          total = ctx.phase_ms("boot") || ctx.phase_ms("total")
+          return [] unless eager && total && total.positive?
+          ratio = eager / total
+          return [] if ratio < MIN_RATIO
+          [suggestion(:info,
+                      title: "eager_load accounts for #{(ratio * 100).round(1)}% of boot time",
+                      evidence: [{ "eager_load_ms" => round(eager), "boot_ms" => round(total), "ratio" => ratio.round(3),
+                                   "threshold" => MIN_RATIO }],
+                      savings: eager,
+                      action: "For serverless or short-lived processes where boot latency matters, you could consider " \
+                              "config.eager_load = false: boot gets faster, but classes are then loaded on first use, " \
+                              "so the first requests may be slower and thread-safety/CoW benefits of eager loading are lost. " \
+                              "For long-running servers, keeping eager_load enabled is usually preferable. " \
+                              "The estimated saving moves work to the first request; it is not a net saving.")]
+        end
+      end
+    end
+  end
+end

data/lib/hayaoki/boot_report/rules/heavy_app_initializer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Hayaoki
+  module BootReport
+    module Rules
+      # アプリ自身の initializer (config/initializers 配下など) が重い。
+      class HeavyAppInitializer < Base
+        def call
+          items = candidates.select { |i| i["inclusive_ms"] > ctx.initializer_threshold_ms }
+          return [] if items.empty?
+          items.sort_by! { |i| -i["inclusive_ms"] }
+          [suggestion(:medium,
+                      title: "#{items.size} app initializer(s) take more than #{fmt(ctx.initializer_threshold_ms)} ms; " \
+                             "they may be deferrable (slowest: #{items.first["name"]})",
+                      evidence: items,
+                      savings: items.sum { |i| i["inclusive_ms"] },
+                      action: "Consider (the time may include gem requires counted elsewhere):\n" \
+                              "  - run it later: Rails.application.config.after_initialize { ... }\n" \
+                              "  - require heavy libraries lazily, inside the code that uses them\n" \
+                              "  - register it with ActiveSupport.on_load(:active_record) { ... } so it runs only when needed\n" \
+                              "Savings are an upper bound: deferred work still runs, just later.")]
+        end
+
+        private
+
+        def candidates
+          by_name = {}
+          # 切り詰め前の app_initializer_times があればそれを使う (無ければ表示用の上位 N 件)
+          full = get(ctx.report, :app_initializer_times)
+          inits = full ? get(full, :initializers) : get(ctx.report, :initializers)
+          files = full ? get(full, :files) : get(ctx.report, :files)
+          Array(inits).each do |i|
+            next unless get(i, :category).to_s == "app"
+            ms = med(get(i, :inclusive_ms)) or next
+            name = [get(i, :name), get(i, :context)].compact.join(" ")
+            add(by_name, name, ms, "initializer")
+          end
+          Array(files).each do |f|
+            path = get(f, :path).to_s
+            next unless get(f, :category).to_s == "app" && path.include?("/config/initializers/")
+            ms = med(get(f, :inclusive_ms)) or next
+            add(by_name, path.sub(%r{\A.*?/(config/initializers/)}, '\1'), ms, "file")
+          end
+          by_name.values
+        end
+
+        def add(h, name, ms, kind)
+          cur = h[name]
+          return if cur && cur["inclusive_ms"] >= ms
+          h[name] = { "name" => name, "kind" => kind, "inclusive_ms" => round(ms) }
+        end
+
+        def fmt(x) = x == x.to_i ? x.to_i.to_s : x.to_s
+      end
+    end
+  end
+end

data/lib/hayaoki/boot_report/rules/tzinfo_eager_load.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Hayaoki
+  module BootReport
+    module Rules
+      # Rails は active_support.initialize_time_zone で TZInfo を eager_load_namespaces に加え、
+      # production の eager_load! で全タイムゾーン (約 600) を読み込む。Linux のコンテナでは 200〜330ms かかる
+      # (bench/tzinfo_eager_load.rb)。遅延にすると、使うゾーンだけを初回に読む (1 ゾーン 0.3ms 未満)。
+      class TzinfoEagerLoad < Base
+        NAME = "TZInfo.eager_load!"
+        MIN_MS = 20.0
+
+        def call
+          e = Array(get(ctx.report, :eager_namespaces)).find { |x| get(x, :name) == NAME } or return []
+          ms = med(get(e, :inclusive_ms))
+          return [] unless ms && ms >= MIN_MS
+          [suggestion(:medium,
+                      title: "#{NAME} loads every time zone at boot (#{round(ms)} ms)",
+                      evidence: [{ "namespace" => NAME, "inclusive_ms" => round(ms), "threshold_ms" => MIN_MS }],
+                      savings: ms,
+                      action: "Rails eager loads all ~600 TZInfo zones in production. To load zones on first use instead, add\n" \
+                              "  # config/initializers/tzinfo_lazy.rb\n" \
+                              "  Rails.application.config.eager_load_namespaces.delete(TZInfo)\n" \
+                              "Each zone is then read when first used (typically well under 1 ms). TZInfo's lazy loading is thread-safe.\n" \
+                              "Trade-off: with a forking server (Puma workers + preload_app!), zones are no longer loaded before fork, " \
+                              "so they are not shared copy-on-write. Most useful for serverless and short-lived processes.")]
+        end
+      end
+    end
+  end
+end

data/lib/hayaoki/boot_report/rules/unused_heavy_gem.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+require "set"
+
+require_relative "base"
+require_relative "dev_gems_in_production"
+
+module Hayaoki
+  module BootReport
+    module Rules
+      # 重い gem の定数が app/ config/ lib/ から参照されていない (require: false の候補)。
+      class UnusedHeavyGem < Base
+        SEARCH_DIRS = %w[app config lib].freeze
+        SEARCH_EXTS = %w[.rb .erb .rake .haml .slim .jbuilder .ru].freeze
+        SEARCH_ROOT_FILES = %w[config.ru Rakefile].freeze
+        MAX_FILE_BYTES = 2_000_000
+
+        EXCLUDED = (%w[
+          rails railties activesupport activerecord activemodel actionpack actionview actionmailer actioncable
+          activejob activestorage actiontext actionmailbox bootsnap zeitwerk bundler rubygems rack i18n
+          concurrent-ruby tzinfo mutex_m bigdecimal drb base64 logger
+        ]).freeze
+        # Railtie やアダプタ経由で使われ、定数を直接書かないことが多い gem (誤検出を避けるため対象外)
+        IMPLICIT_USE = %w[
+          puma pg mysql2 sqlite3 sprockets sprockets-rails sass-rails sassc sassc-rails propshaft importmap-rails
+          turbo-rails stimulus-rails jbuilder tailwindcss-rails jsbundling-rails cssbundling-rails
+          solid_cache solid_queue solid_cable tzinfo-data kamal thruster net-imap net-smtp net-pop
+        ].freeze
+        # APM / 監視系: Railtie や Rack middleware 経由で動くため定数参照が無くても使われている
+        APM_GEMS = %w[newrelic_rpm ddtrace datadog scout_apm skylight honeybadger bugsnag rollbar appsignal].freeze
+        APM_PREFIXES = %w[sentry- opentelemetry-].freeze
+        # gem が提供する DSL 名 (定数でなくクラス本体のマクロとして使われるもの)。小さく明示的に保つ
+        DSL_NAMES = {
+          "paper_trail" => %w[has_paper_trail], "carrierwave" => %w[mount_uploader mount_uploaders],
+          "friendly_id" => %w[friendly_id], "acts-as-taggable-on" => %w[acts_as_taggable_on acts_as_taggable],
+          "acts_as_list" => %w[acts_as_list], "ancestry" => %w[has_ancestry], "rolify" => %w[rolify],
+          "searchkick" => %w[searchkick], "counter_culture" => %w[counter_culture],
+          "devise" => %w[devise_for devise], "audited" => %w[audited], "aasm" => %w[aasm],
+          "enumerize" => %w[enumerize],
+        }.freeze
+        # 既知の定数名 (gem 名から機械的に導けないもの)
+        KNOWN_CONSTANTS = {
+          "httparty" => %w[HTTParty], "aws-sdk-s3" => %w[Aws::S3 Aws], "aws-sdk" => %w[Aws],
+          "nokogiri" => %w[Nokogiri], "rest-client" => %w[RestClient], "activeadmin" => %w[ActiveAdmin],
+          "google-cloud-storage" => %w[Google::Cloud::Storage], "mini_magick" => %w[MiniMagick],
+          "ruby-vips" => %w[Vips], "image_processing" => %w[ImageProcessing], "rqrcode" => %w[RQRCode],
+          "redcarpet" => %w[Redcarpet], "kaminari" => %w[Kaminari], "elasticsearch" => %w[Elasticsearch],
+          "stripe" => %w[Stripe], "sentry-ruby" => %w[Sentry], "sentry-rails" => %w[Sentry],
+        }.freeze
+
+        def call
+          return [] unless gemfile_entries # Gemfile が無ければ直接依存か判定できないので提案しない
+          cands = candidates
+          return [] if cands.empty?
+          used = referenced(cands)
+          cands.reject { |c| used.include?(c[:name]) }.sort_by { |c| -c[:ms] }.map do |c|
+            suggestion(:low,
+                       title: "No references found to #{c[:name]} in app code (#{round(c[:ms])} ms at boot)",
+                       evidence: [{ "gem" => c[:name], "self_ms" => round(c[:ms]), "searched_tokens" => c[:tokens] }],
+                       savings: c[:ms],
+                       action: "If it is not needed at boot, consider loading it lazily in the Gemfile:\n" \
+                               "  gem \"#{c[:name]}\", require: false\n" \
+                               "and `require \"#{c[:name]}\"` where it is first needed. This is a static text search: " \
+                               "it can miss use via metaprogramming, other gems, rake tasks outside the searched " \
+                               "directories, or Railtie hooks, so please verify before changing.")
+          end
+        end
+
+        private
+
+        def candidates
+          entries = gemfile_entries
+          ctx.gems.filter_map do |g|
+            name = get(g, :name).to_s
+            ms = med(get(g, :self_ms))
+            next unless get(g, :category).to_s == "gem" && ms && ms > ctx.gem_threshold_ms
+            next if EXCLUDED.include?(name) || IMPLICIT_USE.include?(name) || DevGemsInProduction.dev_gem?(name)
+            next if apm?(name) || railtie?(g, name)
+            if entries
+              entry = entries[name]
+              next unless entry # 間接依存は Gemfile で require: false にできない
+              next if entry.require == false # 既に lazy
+              next if entry.require.is_a?(Array) && !entry.require.empty? # 別名で require されている
+            end
+            given = Array(get(g, :constants)).map(&:to_s).reject(&:empty?)
+            tokens = (given.empty? ? guess_constants(name) : given) + DSL_NAMES.fetch(name, [])
+            { name: name, ms: ms, tokens: tokens.uniq }
+          end
+        end
+
+        def apm?(name) = APM_GEMS.include?(name) || APM_PREFIXES.any? { name.start_with?(_1) }
+
+        # Railtie / Engine を持つ gem は初期化時に自動で組み込まれるので、定数参照が無くても使われている。
+        # 計測結果 (gem が initializer を定義している / on_load の時間が gem に計上されている) か、gem 内の railtie.rb / engine.rb で判定する。
+        def railtie?(g, name)
+          return true if (med(get(g, :initializer_count)) || 0) > 0 || (med(get(g, :on_load_ms)) || 0) > 0
+          railtie_files?(name)
+        end
+
+        def railtie_files?(name)
+          path = gem_paths[name] || Gem.loaded_specs[name]&.full_gem_path or return false # 子プロセスの記録を優先
+          Dir.glob(File.join(path, "lib", "**", "{railtie,engine}.rb")).any?
+        rescue StandardError
+          false
+        end
+
+        # gem 名 → 定数名の候補 (ゆるい方に倒す: 一つでも見つかれば「使われている」とみなす)
+        def guess_constants(name)
+          return KNOWN_CONSTANTS[name] if KNOWN_CONSTANTS.key?(name)
+          parts = name.split(/[-]/)
+          camel = ->(s) { s.split("_").map { |w| w[0].to_s.upcase + w[1..].to_s }.join }
+          toks = [parts.map(&camel).join("::"), parts.map(&camel).join]
+          # rack-attack → Rack のように先頭だけでは広すぎるので、単一セグメントの gem 名だけ
+          toks << camel.call(parts.first) if parts.size == 1
+          toks << name # require "foo-bar" の文字列
+          toks.uniq
+        end
+
+        # 各ファイルを 1 回だけ読み、全トークンをまとめた正規表現で比べる。使われていた gem 名の Set を返す。
+        def referenced(cands)
+          owner = Hash.new { |h, k| h[k] = [] }
+          cands.each { |c| c[:tokens].each { |t| owner[t.downcase] << c[:name] } }
+          re = Regexp.new("(?<![A-Za-z0-9_])(#{owner.keys.sort_by { |k| -k.size }.map { |k| Regexp.escape(k) }.join("|")})(?![A-Za-z0-9_])", Regexp::IGNORECASE)
+          used = Set.new
+          each_source_file do |path|
+            text = File.binread(path).force_encoding(Encoding::UTF_8).scrub
+            text.scan(re) { |(tok)| owner[tok.downcase].each { |n| used << n } }
+            return used if used.size >= cands.size
+          end
+          used
+        end
+
+        def each_source_file
+          root = ctx.app_dir.to_s
+          files = SEARCH_DIRS.flat_map do |d|
+            Dir.glob(File.join(root, d, "**", "*{#{SEARCH_EXTS.join(",")}}"), File::FNM_DOTMATCH)
+          end
+          files += SEARCH_ROOT_FILES.map { |f| File.join(root, f) }
+          files.uniq.each do |path|
+            next unless File.file?(path)
+            next if File.size(path) > MAX_FILE_BYTES
+            yield path
+          rescue SystemCallError
+            next
+          end
+        end
+      end
+    end
+  end
+end