bulletproof 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20e99f97d84e032e719fd33b16b11778667f2abf8d367f69a4201bdc221707ec
+  data.tar.gz: cfe6e4fabcbda428d45b3bbf88b403c67f7df6599704d3ac8bb4e45312f853cb
+SHA512:
+  metadata.gz: fe3727c8d74667fc57fd6930f65559ec0414965df3f87dc01c11d0e1d90c443d5b4dff692b9a50368f3e0b202cbee2733c632293477fd309f4499c7df2006e6e
+  data.tar.gz: d5a2a4d274e110e1ac0104390cfd6f6f3daf31ef97b1c3335829a214c959b5aa71f5df8bd7ce952d5027f001bd62746e9c8da10a9b3b5e8bcbb53ddfcc00a111

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,49 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Style/OneClassPerFile:
+  Exclude:
+    - "demo/**/*"
+    - "spec/**/*"
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "demo/**/*"
+
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - "lib/bulletproof/runtime/request_monitor.rb"
+
+Metrics/AbcSize:
+  Max: 40
+
+Metrics/CyclomaticComplexity:
+  Max: 12
+
+Metrics/PerceivedComplexity:
+  Max: 12
+
+Layout/LineLength:
+  Max: 160
+  Exclude:
+    - "spec/**/*"
+
+Lint/UnreachableLoop:
+  Exclude:
+    - "spec/**/*"

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-03-17
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 essei0-0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,201 @@
+# Bulletproof
+
+Bulletproof detects ActiveRecord memory problems caused by over-eager `includes`.
+
+- **Static analysis** — Scans Ruby source files and flags `includes` calls that load unbounded record sets
+- **Runtime monitoring** — Measures actual record counts and GC pressure per request, and warns when thresholds are exceeded
+
+## Installation
+
+```ruby
+# Gemfile
+gem "bulletproof", group: :development
+```
+
+```sh
+bundle install
+```
+
+---
+
+## Static Analysis
+
+### CLI
+
+```sh
+# Analyze a directory
+bundle exec bulletproof app/
+
+# Analyze a single file
+bundle exec bulletproof app/models/user.rb
+
+# Override thresholds
+bundle exec bulletproof app/ --max-includes-depth 3 --max-associations 5
+```
+
+**Output (violations found):**
+
+```
+[WARNING] app/models/post.rb:12 — nesting depth 3 (limit: 2), no record-limiting method (limit / find, etc.) in chain
+[WARNING] app/controllers/users_controller.rb:45 — 4 associations (limit: 3), no record-limiting method in chain
+
+2 violation(s) found.
+```
+
+**Output (clean):**
+
+```
+No violations found.
+```
+
+The exit code is `0` when clean and `1` when violations are found, making it easy to integrate into CI.
+
+### Programmatic usage
+
+```ruby
+report = Bulletproof.analyze("app/")
+
+if report.ok?
+  puts "No violations found."
+else
+  report.violations.each do |v|
+    puts "[#{v.severity.upcase}] #{v.file}:#{v.line} — #{v.message}"
+  end
+end
+```
+
+### How detection works
+
+A call to `includes` is only flagged when **both** conditions are true:
+
+1. The nesting depth or association count exceeds the configured threshold
+2. No record-limiting method (`limit`, `find`, `first`, `page`, etc.) appears anywhere in the method chain
+
+```ruby
+# Flagged — unbounded full-table load
+User.includes(posts: { comments: :author }).all
+Post.includes(:user, :comments, :tags, :likes)
+
+# Safe — record count is bounded
+User.includes(posts: { comments: :author }).limit(10)
+User.includes(posts: { comments: :author }).page(1).per(20)
+```
+
+---
+
+## Runtime Monitoring (Rails)
+
+### Setup
+
+```ruby
+# config/initializers/bulletproof.rb
+Bulletproof.configure do |c|
+  c.enabled = Rails.env.development?
+
+  # ---- Thresholds ----------------------------------------------------------
+
+  # Max records loaded at once per model (default: 1_000)
+  c.max_records_per_model = 1_000
+
+  # Max total records loaded across all models per request (default: 5_000)
+  # find_each / in_batches loads are excluded from this count
+  c.max_total_records = 5_000
+
+  # Max GC runs per request (default: nil = disabled)
+  # GC frequency varies widely between apps; set explicitly if needed
+  # c.max_gc_runs_per_request = 10
+
+  # ---- Notifiers -----------------------------------------------------------
+
+  # Log to Rails.logger.warn (default: true)
+  c.rails_logger = true
+
+  # Inject console.warn into HTML responses (default: true)
+  # Visible in the browser's Console tab (F12)
+  c.console = true
+
+  # Inject a floating overlay panel into HTML responses (default: false)
+  # Visible on the page without opening DevTools
+  c.alert = true
+
+  # Append warnings to a log file (default: nil = disabled)
+  # c.log_file = Rails.root.join("log/bulletproof.log").to_s
+
+  # Custom notifier callable — for Slack, etc. (default: nil = disabled)
+  # c.notifier = ->(w) { SlackNotifier.ping(w.message) }
+end
+```
+
+Setting `enabled = true` causes the Railtie to automatically insert the Rack middleware. You do not need to call `config.middleware.use` manually.
+
+### Notifiers
+
+| Key | Default | Description |
+|---|---|---|
+| `rails_logger` | `true` | Calls `Rails.logger.warn` for each warning |
+| `console` | `true` | Injects `console.warn` before `</body>`. Visible in the browser Console tab |
+| `alert` | `false` | Injects a floating overlay panel before `</body>`. Dismissible with ✕ |
+| `log_file` | `nil` (disabled) | Appends timestamped warnings to the specified file path |
+| `notifier` | `nil` (disabled) | Callable receiving a `RuntimeWarning`. Use for Slack, webhooks, etc. |
+
+### Warning output example
+
+```
+[Bulletproof] Post: loaded 5,200 records at once (limit: 1,000)
+  → app/controllers/posts_controller.rb:15:in 'index'
+
+[Bulletproof] Total records loaded in this request: 7,800 (limit: 5,000) [Post: 5,200, Comment: 2,600]
+```
+
+### Warning types
+
+| Type | Condition | Related config key |
+|---|---|---|
+| `:mass_instantiation` | A single model loaded more than `max_records_per_model` records in one batch | `max_records_per_model` |
+| `:high_total_records` | Total records across all models exceeded `max_total_records` (batch loads excluded) | `max_total_records` |
+| `:gc_pressure` | GC ran more than `max_gc_runs_per_request` times during the request | `max_gc_runs_per_request` |
+
+### `find_each` / `in_batches`
+
+Batch processing is intentional and memory-safe, so Bulletproof does not warn on it.
+
+```ruby
+# No warning — find_each loads records in bounded batches
+Post.find_each(batch_size: 500) { |post| process(post) }
+
+# Warning — all records loaded into memory at once
+Post.all.to_a
+```
+
+### How it works
+
+Bulletproof subscribes to the `instantiation.active_record` ActiveSupport notification for the duration of each request. It accumulates record counts per model and uses `caller_locations` to identify the application code line responsible for each load. Subscription is scoped to the current thread via `Thread.current`, so parallel requests in multi-threaded servers (e.g. Puma) do not interfere with each other.
+
+---
+
+## Configuration reference
+
+| Key | Default | Description |
+|---|---|---|
+| `enabled` | `false` | Enable runtime monitoring |
+| `max_includes_depth` | `2` | Static: max `includes` nesting depth |
+| `max_associations` | `3` | Static: max associations per `includes` call |
+| `max_records_per_model` | `1_000` | Runtime: max records loaded at once per model |
+| `max_total_records` | `5_000` | Runtime: max total records per request (batch loads excluded) |
+| `max_gc_runs_per_request` | `nil` (disabled) | Runtime: max GC runs per request |
+| `rails_logger` | `true` | Notifier: output to `Rails.logger.warn` |
+| `console` | `true` | Notifier: inject `console.warn` into HTML |
+| `alert` | `false` | Notifier: inject overlay panel into HTML |
+| `log_file` | `nil` (disabled) | Notifier: append to log file |
+| `notifier` | `nil` (disabled) | Notifier: custom callable receiving `RuntimeWarning` |
+
+---
+
+## Requirements
+
+- Ruby 3.0+
+- Rails 6.0+ (runtime monitoring only)
+
+## License
+
+[MIT License](LICENSE.txt)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/exe/bulletproof

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bulletproof"
+require "optparse"
+
+options = {}
+
+parser = OptionParser.new do |o|
+  o.banner = <<~BANNER
+    Usage: bulletproof [options] PATH
+
+    Static analysis for over-eager ActiveRecord includes.
+
+    Examples:
+      bulletproof app/
+      bulletproof app/models/user.rb
+      bulletproof app/ --max-includes-depth 3 --max-associations 5
+  BANNER
+
+  o.on("--max-includes-depth N", Integer, "Max nesting depth of includes (default: 2)") do |n|
+    options[:max_includes_depth] = n
+  end
+
+  o.on("--max-associations N", Integer, "Max number of associations in one includes (default: 3)") do |n|
+    options[:max_associations] = n
+  end
+
+  o.on("-v", "--version", "Print version") do
+    puts Bulletproof::VERSION
+    exit
+  end
+
+  o.on("-h", "--help", "Print this help") do
+    puts o
+    exit
+  end
+end
+
+parser.parse!
+
+path = ARGV.first
+
+if path.nil?
+  warn parser.banner
+  exit 1
+end
+
+unless File.exist?(path)
+  warn "bulletproof: #{path}: No such file or directory"
+  exit 1
+end
+
+Bulletproof.configure do |c|
+  c.max_includes_depth = options[:max_includes_depth] if options[:max_includes_depth]
+  c.max_associations   = options[:max_associations]   if options[:max_associations]
+end
+
+report = Bulletproof.analyze(path)
+
+if report.ok?
+  puts "No violations found."
+  exit 0
+else
+  puts report
+  puts
+  puts "#{report.violations.size} violation(s) found."
+  exit 1
+end

data/lib/bulletproof/analyzer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Bulletproof
+  class Analyzer
+    def initialize(config = Bulletproof.config)
+      @config = config
+      @detectors = [
+        Detectors::ExcessiveIncludesDetector.new(config)
+      ]
+    end
+
+    # @param path [String] ファイルまたはディレクトリのパス
+    # @return [Report]
+    def call(path)
+      report = Report.new
+      ruby_files(path).each do |file|
+        source = File.read(file)
+        @detectors.each do |detector|
+          detector.call(source, file: file).each { |v| report.add_violation(v) }
+        end
+      end
+      report
+    end
+
+    private
+
+    def ruby_files(path)
+      if File.directory?(path)
+        Dir.glob(File.join(path, "**", "*.rb"))
+      else
+        [path]
+      end
+    end
+  end
+end

data/lib/bulletproof/configuration.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Bulletproof
+  class Configuration
+    # ---- 静的解析 -----------------------------------------------------------
+
+    # includes のネスト深さの上限（例: posts: { comments: :author } は深さ2）
+    attr_accessor :max_includes_depth
+
+    # 1つの includes で許容するアソシエーション数の上限
+    attr_accessor :max_associations
+
+    # ---- ランタイム監視 -----------------------------------------------------
+
+    # ランタイム監視を有効にするか（デフォルト: false）
+    # Rails では config/initializers/bulletproof.rb で true に設定して使う
+    attr_accessor :enabled
+
+    # 1モデルあたりのロード件数の上限
+    # 超えると :mass_instantiation 警告を出す
+    attr_accessor :max_records_per_model
+
+    # リクエスト全体（全モデル合算）のロード件数の上限
+    # 超えると :high_total_records 警告を出す
+    attr_accessor :max_total_records
+
+    # リクエスト中に許容する GC 実行回数の上限
+    # 超えると :gc_pressure 警告を出す
+    # nil（デフォルト）のとき無効。GC 頻度はアプリや Ruby 設定に依存するため
+    # 必要な場合にのみ明示的に設定する（例: 10）
+    attr_accessor :max_gc_runs_per_request
+
+    # Rails.logger.warn に出力するか（デフォルト: true）
+    attr_accessor :rails_logger
+
+    # HTML レスポンスの </body> 直前に console.warn を注入するか（デフォルト: true）
+    # ブラウザの開発者ツールの Console タブで確認できる
+    attr_accessor :console
+
+    # HTML レスポンスにオーバーレイパネルを注入するか（デフォルト: false）
+    # 開発者ツールを開かなくても画面上で警告を確認できる
+    attr_accessor :alert
+
+    # 警告をファイルに追記するか（デフォルト: nil = 無効）
+    # ファイルパスを文字列で指定する
+    #   c.log_file = Rails.root.join("log/bulletproof.log").to_s
+    attr_accessor :log_file
+
+    # カスタム通知先。Slack 等に飛ばしたいときに設定する（デフォルト: nil = 無効）
+    # callable で RuntimeWarning を引数に取る
+    #   c.notifier = ->(w) { SlackNotifier.ping(w.message) }
+    attr_accessor :notifier
+
+    def initialize
+      @enabled                  = false
+      @max_includes_depth       = 2
+      @max_associations         = 3
+      @max_records_per_model    = 1_000
+      @max_total_records        = 5_000
+      @max_gc_runs_per_request  = nil
+      @rails_logger             = true
+      @console                  = true
+      @alert                    = false
+      @log_file                 = nil
+      @notifier                 = nil
+    end
+  end
+end

data/lib/bulletproof/detectors/excessive_includes_detector.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "rubocop-ast"
+
+module Bulletproof
+  module Detectors
+    # Rubyソースを静的解析し、メモリ過剰消費につながるincludes呼び出しを検出する
+    #
+    # 検出の前提:
+    #   includesのネスト深さ・アソシエーション数が大きくても、
+    #   件数を絞るメソッドがチェーンにあれば安全とみなす。
+    #
+    # 危険パターン（フラグを立てる）:
+    #   User.includes(posts: { comments: :author }).all          # 全件 + 深いネスト
+    #   User.includes(:a, :b, :c, :d)                           # 全件 + 多アソシエーション
+    #
+    # 安全パターン（フラグを立てない）:
+    #   User.includes(posts: { comments: :author }).limit(10)    # 件数制限あり
+    #   User.includes(posts: { comments: :author }).find(1)      # 単件取得
+    #   User.includes(posts: { comments: :author }).first        # 単件取得
+    #   User.includes(:a, :b, :c, :d).page(1).per(20)           # ページネーションあり
+    LIMITING_METHODS = %i[
+      limit find find_by find_by!
+      first first! last last! take take!
+      page paginate per per_page
+    ].freeze
+
+    class ExcessiveIncludesDetector
+      def initialize(config)
+        @config = config
+      end
+
+      # @param source [String] Rubyソースコード
+      # @param file [String] ファイルパス（表示用）
+      # @return [Array<Violation>]
+      def call(source, file: "(string)")
+        processed = RuboCop::AST::ProcessedSource.new(source, RUBY_VERSION.to_f, file)
+        return [] unless processed.valid_syntax?
+
+        parent_map = build_parent_map(processed.ast)
+        violations = []
+        collect_includes_nodes(processed.ast).each do |node|
+          check(node, violations, file, parent_map)
+        end
+        violations
+      end
+
+      private
+
+      # ---- AST 走査 --------------------------------------------------------
+
+      def collect_includes_nodes(node, result = [])
+        return result unless node.is_a?(RuboCop::AST::Node)
+
+        result << node if includes_call?(node)
+        node.each_child_node { |child| collect_includes_nodes(child, result) }
+        result
+      end
+
+      # 各ノードの親を記録するマップを構築する
+      def build_parent_map(node, parent = nil, map = {}.compare_by_identity)
+        return map unless node.is_a?(RuboCop::AST::Node)
+
+        map[node] = parent
+        node.each_child_node { |child| build_parent_map(child, node, map) }
+        map
+      end
+
+      # ---- チェーン解析 ----------------------------------------------------
+
+      # includes ノードから連続する send チェーンの根（最外ノード）を返す
+      def chain_root(node, parent_map)
+        current = node
+        loop do
+          parent = parent_map[current]
+          break unless parent&.send_type? && parent.receiver.equal?(current)
+
+          current = parent
+        end
+        current
+      end
+
+      # send チェーンに含まれる全メソッド名を収集する（チェーン根から下向き）
+      def collect_chain_methods(node, methods = [])
+        return methods unless node.is_a?(RuboCop::AST::Node) && node.send_type?
+
+        methods << node.method_name
+        collect_chain_methods(node.receiver, methods)
+        methods
+      end
+
+      # ---- 検出ロジック ----------------------------------------------------
+
+      def includes_call?(node)
+        node.send_type? && node.method_name == :includes
+      end
+
+      def check(node, violations, file, parent_map)
+        depth = max_includes_depth(node)
+        count = count_top_level_associations(node.arguments)
+
+        deep  = depth >= @config.max_includes_depth
+        wide  = count > @config.max_associations
+
+        return unless deep || wide
+
+        root    = chain_root(node, parent_map)
+        methods = collect_chain_methods(root)
+
+        return if (methods & LIMITING_METHODS).any?
+
+        issues = []
+        issues << "ネスト深さ #{depth}（上限: #{@config.max_includes_depth}）" if deep
+        issues << "アソシエーション数 #{count}（上限: #{@config.max_associations}）" if wide
+
+        violations << Violation.new(
+          file: file,
+          line: node.loc.line,
+          message: "#{issues.join("、")} かつ件数を絞るメソッド（limit / find 等）がチェーンにありません",
+          severity: :warning
+        )
+      end
+
+      # ---- 深さ・幅の計算 -------------------------------------------------
+
+      # includes 引数のネスト深さを計算する
+      #   :posts                                 → 0
+      #   { posts: :comments }                   → 1
+      #   { posts: { comments: :author } }       → 2
+      #   { posts: [:comments, :likes] }         → 1
+      def node_depth(node)
+        case node.type
+        when :hash  then 1 + (node.each_pair.map { |pair| node_depth(pair.value) }.max || 0)
+        when :array then node.children.map { |child| node_depth(child) }.max || 0
+        else             0
+        end
+      end
+
+      def max_includes_depth(node)
+        node.arguments.map { |arg| node_depth(arg) }.max || 0
+      end
+
+      # トップレベルのアソシエーション数を数える
+      #   includes(:a, :b)         → 2
+      #   includes(a: :b, c: :d)   → 2（ハッシュのキー数）
+      #   includes(:a, b: :c)      → 2（sym + ハッシュキー）
+      def count_top_level_associations(args)
+        args.sum do |arg|
+          case arg.type
+          when :sym, :str then 1
+          when :hash      then arg.keys.size
+          else                 0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bulletproof/middleware.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Bulletproof
+  # Rack ミドルウェア。リクエストごとに AR ロード件数・GC 負荷を計測し、
+  # 閾値を超えた場合は設定済みの通知先へ RuntimeWarning を送る。
+  #
+  # 通知先:
+  #   rails_logger: true     → Rails.logger.warn に出力
+  #   console:      true     → HTML に console.warn を注入（開発者ツール Console タブ）
+  #   alert:        true     → HTML にオーバーレイパネルを注入（画面上で確認）
+  #   log_file:     "path"   → ファイルに追記
+  #   notifier:     callable → Slack 等カスタム通知先
+  class Middleware
+    def initialize(app, config = Bulletproof.config)
+      @app     = app
+      @config  = config
+      @monitor = Runtime::RequestMonitor.new(config)
+    end
+
+    def call(env)
+      response, warnings = @monitor.monitor { @app.call(env) }
+      return response if warnings.empty?
+
+      notify_logger(warnings)
+      notify_log_file(warnings)
+      notify_custom(warnings)
+      inject_html(response, warnings)
+    end
+
+    private
+
+    # ---- ログ通知 ------------------------------------------------------------
+
+    def notify_logger(warnings)
+      return unless @config.rails_logger
+      return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      warnings.each { |w| Rails.logger.warn("[Bulletproof] #{w.message}") }
+    end
+
+    def notify_log_file(warnings)
+      return unless @config.log_file
+
+      File.open(@config.log_file, "a") do |f|
+        warnings.each do |w|
+          f.puts "[#{Time.now.strftime("%Y-%m-%d %H:%M:%S")}] [#{w.severity.upcase}] [#{w.type}] #{w.message}"
+        end
+      end
+    end
+
+    def notify_custom(warnings)
+      return unless @config.notifier
+
+      warnings.each { |w| @config.notifier.call(w) }
+    end
+
+    # ---- HTML 注入 -----------------------------------------------------------
+
+    def inject_html(response, warnings)
+      return response unless @config.console || @config.alert
+
+      status, headers, body = response
+      return response unless html?(headers)
+
+      content  = ""
+      content += build_console_script(warnings) if @config.console
+      content += build_alert_overlay(warnings)  if @config.alert
+
+      new_body = inject_into_body(body, content)
+      [status, update_content_length(headers, new_body), new_body]
+    end
+
+    def html?(headers)
+      (headers["content-type"] || "").include?("text/html")
+    end
+
+    # console.warn を発火する <script> タグ
+    def build_console_script(warnings)
+      lines = warnings.map do |w|
+        "  console.warn('[Bulletproof] ' + #{JSON.generate(w.message)});"
+      end.join("\n")
+      "\n<script>\n#{lines}\n</script>"
+    end
+
+    # 画面右下に浮かぶオーバーレイパネル
+    def build_alert_overlay(warnings)
+      items = warnings.map do |w|
+        msg = w.message
+               .gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+               .gsub("\n", "<br>&nbsp;&nbsp;")
+        "<li style='margin-bottom:6px;'>#{msg}</li>"
+      end.join
+
+      <<~HTML
+        <div id="__bp_overlay__" style="position:fixed;bottom:16px;right:16px;max-width:500px;background:#fff3cd;border:2px solid #ffc107;border-radius:8px;padding:12px 16px;font-family:monospace;font-size:12px;line-height:1.5;z-index:999999;box-shadow:0 4px 16px rgba(0,0,0,0.2);">
+          <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:8px;">
+            <strong style="color:#856404;font-size:13px;">⚠ Bulletproof (#{warnings.size}件の警告)</strong>
+            <button onclick="document.getElementById('__bp_overlay__').remove()" style="background:none;border:none;cursor:pointer;font-size:20px;line-height:1;color:#856404;padding:0 0 0 12px;">✕</button>
+          </div>
+          <ul style="margin:0;padding:0 0 0 16px;">#{items}</ul>
+        </div>
+      HTML
+    end
+
+    def inject_into_body(body, content)
+      chunks = []
+      body.each { |chunk| chunks << chunk } # rubocop:disable Style/MapIntoArray
+      injected = false
+      chunks.map do |chunk|
+        if !injected && chunk.include?("</body>")
+          injected = true
+          chunk.sub("</body>", "#{content}\n</body>")
+        else
+          chunk
+        end
+      end
+    end
+
+    def update_content_length(headers, body)
+      return headers unless headers["content-length"]
+
+      headers.merge("content-length" => body.sum(&:bytesize).to_s)
+    end
+  end
+end

data/lib/bulletproof/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Bulletproof
+  class Railtie < Rails::Railtie
+    # config/initializers が読まれた後にミドルウェアを挿入する。
+    # これにより、ユーザーが initializer 内で設定した値が反映される。
+    initializer "bulletproof.insert_middleware", after: :load_config_initializers do |app|
+      app.middleware.use Bulletproof::Middleware if Bulletproof.config.enabled
+    end
+  end
+end

data/lib/bulletproof/report.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Bulletproof
+  Violation = Data.define(:file, :line, :message, :severity)
+
+  class Report
+    attr_reader :violations
+
+    def initialize
+      @violations = []
+    end
+
+    def add_violation(violation)
+      @violations << violation
+      self
+    end
+
+    def ok?
+      @violations.empty?
+    end
+
+    def to_s
+      return "No violations found." if ok?
+
+      @violations.map do |v|
+        "[#{v.severity.upcase}] #{v.file}:#{v.line} — #{v.message}"
+      end.join("\n")
+    end
+  end
+end

data/lib/bulletproof/runtime/callstack_filter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Bulletproof
+  module Runtime
+    # コールスタックからアプリケーションコードのフレームを探すユーティリティ
+    #
+    # gem 内部・bulletproof 自身のフレームを除外し、
+    # 最初にヒットしたアプリケーションコードの位置を返す。
+    module CallstackFilter
+      # 除外するパスのパターン（gem・bulletproof 自身・eval を対象外にする）
+      EXCLUDE_PATTERNS = [
+        %r{/gems/}, # bundler でインストールされた gem
+        %r{lib/bulletproof}, # bulletproof 自身
+        /\A\(eval\)/ # eval されたコード
+      ].freeze
+
+      # @param locations [Array<Thread::Backtrace::Location>]
+      # @return [String, nil]  "path/to/file.rb:42:in 'method_name'" 形式、見つからなければ nil
+      def self.app_location(locations)
+        frame = locations.find do |loc|
+          path = loc.absolute_path || loc.path || ""
+          EXCLUDE_PATTERNS.none? { |pattern| path.match?(pattern) }
+        end
+        frame&.to_s
+      end
+    end
+  end
+end

data/lib/bulletproof/runtime/memory_sampler.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Bulletproof
+  module Runtime
+    # GC 統計を計測するユーティリティ
+    # RSS 計測はオーバーヘッドと精度の問題があるため採用しない
+    module MemorySampler
+      # GC 統計のスナップショットを返す（低オーバーヘッド）
+      def self.gc_snapshot
+        GC.stat.slice(:count, :total_allocated_objects, :heap_allocated_pages)
+      end
+    end
+  end
+end

data/lib/bulletproof/runtime/model_load_collector.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Bulletproof
+  module Runtime
+    # リクエスト中に ActiveRecord の instantiation.active_record イベントを購読し、
+    # モデルごとのロード件数とロード発生箇所を集計する。
+    #
+    # スレッドローカル変数を使うため、Puma 等のマルチスレッドサーバーでも
+    # 並列リクエスト間で集計が混線しない。
+    #
+    # 同一モデルが複数回ロードされた場合は件数を合算し、ロード箇所は初回を記録する。
+    module ModelLoadCollector
+      THREAD_KEY = :__bulletproof_ar_loads__
+      private_constant :THREAD_KEY
+
+      # ブロック実行中のイベントを収集し、ModelLoadEvent の配列を返す（件数降順）
+      def self.collect(&block)
+        Thread.current[THREAD_KEY] = {}
+
+        ActiveSupport::Notifications.subscribed(
+          method(:handle_event),
+          "instantiation.active_record", &block
+        )
+
+        build_events(Thread.current[THREAD_KEY])
+      ensure
+        Thread.current[THREAD_KEY] = nil
+      end
+
+      # ActiveSupport::Notifications のコールバック形式 (name, start, finish, id, payload)
+      # ActiveRecord の find_each / in_batches 経由かどうかを判定するパス
+      BATCH_PATH_PATTERN = %r{activerecord.*/relation/batches}
+
+      def self.handle_event(_name, _start, _finish, _id, payload)
+        loads = Thread.current[THREAD_KEY]
+        return unless loads
+
+        model_name   = payload[:class_name]
+        record_count = payload[:record_count].to_i
+        locs         = caller_locations(1)
+        batched      = locs.any? { |l| (l.absolute_path || l.path || "").match?(BATCH_PATH_PATTERN) }
+
+        if loads.key?(model_name)
+          # 2回目以降: 件数を累計、1回の最大値を更新（ロード箇所・batched フラグは初回を保持）
+          loads[model_name][:count]           += record_count
+          loads[model_name][:max_single_load]  = [loads[model_name][:max_single_load], record_count].max
+        else
+          # 初回: アプリコードのフレームをキャプチャ
+          location = CallstackFilter.app_location(locs)
+          loads[model_name] =
+            { count: record_count, max_single_load: record_count, batched: batched, location: location }
+        end
+      end
+      private_class_method :handle_event
+
+      def self.build_events(loads)
+        loads
+          .map do |model_name, data|
+            ModelLoadEvent.new(
+              model_name: model_name,
+              record_count: data[:count],
+              max_single_load: data[:max_single_load],
+              batched: data[:batched],
+              caller_location: data[:location]
+            )
+          end
+          .sort_by { |e| -e.record_count }
+      end
+      private_class_method :build_events
+    end
+  end
+end

data/lib/bulletproof/runtime/model_load_event.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Bulletproof
+  module Runtime
+    # 1モデルのロード集計結果
+    # record_count:     リクエスト全体の累計ロード件数（find_each の複数バッチも合算）
+    # max_single_load:  1回のイベントで最大何件ロードされたか（find_each のバッチ上限に相当）
+    # batched:          find_each / in_batches 経由のロードかどうか
+    # caller_location:  アプリコードで最初にロードが発生した箇所（"path:line:in 'method'" 形式）
+    ModelLoadEvent = Data.define(:model_name, :record_count, :max_single_load, :batched, :caller_location)
+  end
+end

data/lib/bulletproof/runtime/request_monitor.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Bulletproof
+  module Runtime
+    # リクエスト中の AR ロード件数・GC 統計を計測し、閾値超過時に RuntimeWarning を生成する
+    class RequestMonitor
+      Snapshot = Data.define(
+        :ar_loads,               # Array<ModelLoadEvent>  モデルごとのロード件数
+        :total_records,          # Integer                リクエスト全体の合計レコード数
+        :gc_count_delta,         # Integer                GC 実行回数の増分
+        :allocated_objects_delta # Integer                生成オブジェクト数の増分
+      )
+
+      def initialize(config)
+        @config = config
+      end
+
+      # ブロックを実行し、[戻り値, Array<RuntimeWarning>] を返す
+      def monitor
+        gc_before = MemorySampler.gc_snapshot
+        result    = nil
+        ar_loads  = ModelLoadCollector.collect { result = yield }
+        gc_after  = MemorySampler.gc_snapshot
+
+        snapshot = Snapshot.new(
+          ar_loads: ar_loads,
+          total_records: ar_loads.sum(&:record_count),
+          gc_count_delta: gc_after[:count] - gc_before[:count],
+          allocated_objects_delta: gc_after[:total_allocated_objects] - gc_before[:total_allocated_objects]
+        )
+
+        [result, build_warnings(snapshot)]
+      end
+
+      private
+
+      def build_warnings(snapshot)
+        warnings = []
+
+        snapshot.ar_loads.each do |event|
+          # max_single_load で判定することで find_each のバッチ処理を誤検知しない
+          # find_each(batch_size: 100) → max_single_load: 100 → 閾値以下なら警告しない
+          # Post.all.to_a (500件)      → max_single_load: 500 → 閾値超えで警告
+          next unless event.max_single_load > @config.max_records_per_model
+
+          location_hint = event.caller_location ? "\n  → #{event.caller_location}" : ""
+          warnings << RuntimeWarning.new(
+            type: :mass_instantiation,
+            message: "#{event.model_name} を一度に #{format_count(event.max_single_load)} 件ロードしました" \
+                     "（上限: #{format_count(@config.max_records_per_model)} 件）#{location_hint}",
+            severity: :warning,
+            detail: snapshot
+          )
+        end
+
+        # find_each / in_batches のバッチ処理は意図的な大量処理なので合計から除外する
+        non_batched_loads   = snapshot.ar_loads.reject(&:batched)
+        non_batched_total   = non_batched_loads.sum(&:record_count)
+
+        if non_batched_total > @config.max_total_records
+          summary = non_batched_loads
+                    .map { |e| "#{e.model_name}: #{format_count(e.record_count)}" }
+                    .join(", ")
+          warnings << RuntimeWarning.new(
+            type: :high_total_records,
+            message: "リクエスト全体で #{format_count(non_batched_total)} 件のレコードをロードしました" \
+                     "（上限: #{format_count(@config.max_total_records)} 件）[#{summary}]",
+            severity: :warning,
+            detail: snapshot
+          )
+        end
+
+        if @config.max_gc_runs_per_request && snapshot.gc_count_delta > @config.max_gc_runs_per_request
+          warnings << RuntimeWarning.new(
+            type: :gc_pressure,
+            message: "リクエスト中に GC が #{snapshot.gc_count_delta} 回実行されました" \
+                     "（上限: #{@config.max_gc_runs_per_request} 回）",
+            severity: :warning,
+            detail: snapshot
+          )
+        end
+
+        warnings
+      end
+
+      def format_count(num)
+        num.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      end
+    end
+  end
+end

data/lib/bulletproof/runtime_warning.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Bulletproof
+  RuntimeWarning = Data.define(:type, :message, :severity, :detail)
+end

data/lib/bulletproof/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Bulletproof
+  VERSION = "0.1.3"
+end

data/lib/bulletproof.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "bulletproof/version"
+require_relative "bulletproof/configuration"
+require_relative "bulletproof/report"
+require_relative "bulletproof/runtime_warning"
+require_relative "bulletproof/detectors/excessive_includes_detector"
+require_relative "bulletproof/analyzer"
+require_relative "bulletproof/railtie" if defined?(Rails::Railtie)
+require_relative "bulletproof/runtime/memory_sampler"
+require_relative "bulletproof/runtime/callstack_filter"
+require_relative "bulletproof/runtime/model_load_event"
+require_relative "bulletproof/runtime/model_load_collector"
+require_relative "bulletproof/runtime/request_monitor"
+require_relative "bulletproof/middleware"
+
+module Bulletproof
+  class Error < StandardError; end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # @param path [String] 解析対象のファイルまたはディレクトリ
+    # @return [Report]
+    def analyze(path)
+      Analyzer.new(config).call(path)
+    end
+  end
+end

data/sig/bulletproof.rbs

@@ -0,0 +1,4 @@
+module Bulletproof
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: bulletproof
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- essei0-0
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-ast
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Bulletproof detects ActiveRecord includes that load too many records,
+  both statically via source analysis and at runtime via ActiveSupport::Notifications.
+email:
+- hello.essei@gmail.com
+executables:
+- bulletproof
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/bulletproof
+- lib/bulletproof.rb
+- lib/bulletproof/analyzer.rb
+- lib/bulletproof/configuration.rb
+- lib/bulletproof/detectors/excessive_includes_detector.rb
+- lib/bulletproof/middleware.rb
+- lib/bulletproof/railtie.rb
+- lib/bulletproof/report.rb
+- lib/bulletproof/runtime/callstack_filter.rb
+- lib/bulletproof/runtime/memory_sampler.rb
+- lib/bulletproof/runtime/model_load_collector.rb
+- lib/bulletproof/runtime/model_load_event.rb
+- lib/bulletproof/runtime/request_monitor.rb
+- lib/bulletproof/runtime_warning.rb
+- lib/bulletproof/version.rb
+- sig/bulletproof.rbs
+homepage: https://github.com/essei0-0/bulletproof
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/essei0-0/bulletproof
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Linter and runtime monitor for expensive ActiveRecord includes
+test_files: []