benedictus 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 596fa217f7075749c18b7f4310037667fbbb066be7354d587aa93386712c95f5
+  data.tar.gz: 82faf203b522663f984ec867b6060aaa47798897e90cd40641bc67d3326e9fc4
+SHA512:
+  metadata.gz: eb0cb3195f56ee8038049d383c58d70c6d7128d49a35c070d13b87603de8a832c62df658ba68b1e5512be0f201adceedd30ac833e0f28b74854c0f37cd058486
+  data.tar.gz: abd0a1ae4f084ccfdec16105b780d59f802cb7f4972df7422f47b00bfb18a2424471e473d7175411a3a8411f78a8c5ffdb8052798659a8bde337723fdb62a89f

data/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-05-11
+
+### Changed
+
+- **Dropped `pastel` and `anbt-sql-formatter` runtime dependencies.**
+  Both gems are effectively unmaintained. Their roles are now filled by
+  small internal modules:
+  - `Benedictus::Color` — ~50-line ANSI wrapper with the same API
+    surface we used (`red`/`yellow`/`green`/`cyan`/`bold`/`dim`/`italic`
+    plus chained calls like `color.red.bold(text)`) and the same
+    `enabled:` toggle.
+  - `Benedictus::SqlFormatter` — tokenizer-light SQL pretty-printer for
+    `--sql`. Strips string literals, dollar-quoted strings, line
+    comments, and nested block comments before doing any keyword work,
+    so embedded text like `WHERE bio = 'I will DELETE you'` is never
+    mistaken for a clause.
+
+  The only remaining runtime dependency is `thor`. No public CLI flags
+  or output formats changed.
+
+### Added
+
+- **Fifth heuristic: `ExpensivePerRowScan`** — flags scan nodes whose
+  per-row cost (`(total_cost − startup_cost) / plan_rows`) exceeds
+  `1.0`, the most common indicator that correlated subplans (or
+  expensive filter functions) are multiplying the work the scan does
+  for every outer row. Severity is `:critical` (red) when the scan has
+  subplan children, `:warning` (yellow) otherwise. Catches the
+  "small Seq Scan with huge total cost" pattern that the row-count
+  heuristic alone can't see.
+- **Configurable heuristic thresholds via CLI flags**:
+  - `--seq-scan-threshold ROWS` (default `10_000`)
+  - `--drift-factor X` (default `10`)
+  - `--nested-loop-threshold LOOPS` (default `10_000`)
+  - `--per-row-cost-threshold COST` (default `1.0`)
+
+  Heuristic constructors now accept a `threshold:` kwarg, and
+  `Heuristics::Registry.new(config:)` routes named thresholds to the
+  matching heuristic via each class's `.config_key`. Existing defaults
+  unchanged.
+
+## [0.1.0] - 2026-05-08
+
+### Added — initial release
+
+- **CLI** — `benedictus`, `bnd`, `bemdito` executables (Thor-backed).
+  Positional Ruby expression dispatched to the `explain` task by
+  default; `--version`/`-v` and `help` work without booting Rails.
+- **Rails integration** — locates and loads the host application's
+  `config/environment.rb`, evaluates the expression in `TOPLEVEL_BINDING`,
+  resolves to an `ActiveRecord::Relation` (with `.call` / `.to_relation`
+  / `.to_sql` fallbacks).
+- **Plan parser** — typed in-memory tree of `Plan::Node`s built from
+  Postgres' `EXPLAIN (FORMAT JSON)` envelope. Defensive against unknown
+  or non-array `Plans` keys (preserved under `attrs`); empty-array
+  envelopes raise a clear `DatabaseError`.
+- **Tree renderer** — colored, indented box-drawing output with
+  inline warnings, severity-aware coloring (critical red, warning
+  yellow, info cyan, Index Scan / Index Only Scan green), Pastel
+  with NO_COLOR/TTY honoring. `format_rows` preserves negative signs
+  and truncates floats.
+- **JSON renderer** — pretty-printed Postgres plan, paste-ready for
+  explain.dalibo.com.
+- **Raw renderer** — verbatim text-format EXPLAIN.
+- **Heuristics** — four annotations: Seq Scan on large tables, row
+  estimate drift (suggests `ANALYZE`), external sort, Nested Loop
+  blowup. `Heuristics::Base#apply` raises `NotImplementedError` if a
+  subclass forgets to override.
+- **Safety (`--analyze` only)**:
+  - SELECT-only static check that **first normalizes** the SQL —
+    strips single-quoted *and* dollar-quoted strings, line comments,
+    and *nested* block comments — before scanning the first keyword
+    or detecting data-modifying CTEs. Eliminates false positives like
+    `WHERE bio = 'I will DELETE you'` and false negatives that hide
+    DML behind comments.
+  - **Multi-statement rejection**: SQL containing `;` outside string
+    literals is refused. `"SELECT 1; DELETE FROM users"` no longer
+    passes through to the adapter.
+  - **`RawSqlAdapter` rejection under `--analyze`**: only actual
+    `ActiveRecord::Relation` instances are accepted; arbitrary objects
+    responding to `.to_sql` are refused with a clear error.
+  - **Stricter rollback wrapper**: `klass <= ActiveRecord::Base` is
+    enforced. A duck-typed `.transaction` that doesn't actually open a
+    DB transaction can no longer silently disable the rollback.
+  - Footer wording calls out that volatile-function side effects
+    (`setval`, `pg_advisory_lock`, `pg_notify`, `dblink`, …) are NOT
+    reverted by ROLLBACK. README documents the full list.
+- **Error→exit-code mapping** — RailsNotFound (2), Evaluation /
+  Unresolvable (3), UnsafeQuery (4), Database (5).
+- **CLI dispatch hardening**: `--analyze` and other Thor flags route
+  to the right command; expressions starting with `-` (e.g.
+  `-1.times`, `-User.count`) are correctly treated as expressions
+  rather than flags.
+- **`--buffers` without `--analyze`**: emits a stderr warning per
+  ERD §5.5 instead of being silently dropped.
+
+### Configuration
+
+- `BENEDICTUS_RAILS_ENV` overrides `RAILS_ENV` for the CLI invocation.
+- `NO_COLOR` and `--no-color` both disable color.
+
+### Known limitations (deferred)
+
+- Terminal-width-aware truncation for very wide rows (PRD §11 Q3) is
+  not implemented; deep/wide trees may wrap awkwardly on narrow
+  terminals.
+- The four heuristics are the v1 set; more (N+1 detection, index
+  suggestions backed by schema introspection, plan diffing) are
+  marked post-v1 in PRD §9.
+- Only Rails 8.x is exercised by CI; 6.1 / 7.x compatibility is
+  asserted by API surface but not by automated tests.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Paulino
+
+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,221 @@
+# Benedictus
+
+> A query bem-dita.
+
+A Ruby gem that turns the obscure PostgreSQL `EXPLAIN` output into a
+clear, colored, human-readable tree — for any ActiveRecord scope, query
+object, or expression that resolves to an `ActiveRecord::Relation`.
+
+```sh
+bundle exec benedictus "User.active.with_recent_orders" --analyze
+```
+
+```
+Query: User.active.with_recent_orders
+Total cost: 1834.21    Execution time: 412.9 ms    Planning: 1.30 ms    Rows: 1,204
+
+└─ Hash Join (cost=234.10..1834.21  actual=412.3 ms  rows=1,204)
+   Hash Cond: (orders.user_id = users.id)
+   ├─ Seq Scan on orders (cost=0.00..1500.00  actual=389.2 ms  rows=120,000)
+   │  ⚠  Seq Scan on a table with ~12000 estimated rows
+   │     Consider adding an index that matches the filter on `orders`.
+   │  ⚠  Plan estimated 12000 rows, actual was 120000 (10.0x drift).
+   │     Run `ANALYZE orders` to refresh planner statistics.
+   └─ Hash (cost=234.10..234.10  actual=18.70 ms  rows=1,500)
+      └─ Index Scan using index_users_on_active on users (cost=0.42..234.10  actual=18.50 ms  rows=1,500)
+         Index Cond: (active = true)
+
+Executed inside rolled-back transaction. Note: side effects of volatile
+Postgres functions (setval, pg_advisory_lock, pg_notify, dblink, …) are
+NOT reverted by ROLLBACK.
+```
+
+## Why?
+
+PostgreSQL `EXPLAIN` is powerful but hard to read at a glance:
+
+- The indentation-based tree is fragile and unfamiliar.
+- Costs and times are interleaved with rows in a wall of text.
+- Critical issues — sequential scans on large tables, bad row
+  estimates, sorts spilling to disk — aren't visually highlighted.
+- You have to mentally translate a Ruby scope chain back to SQL
+  before the plan even starts to make sense.
+
+Benedictus reads the plan, applies a small set of heuristics, and
+renders it the way you'd actually want to read it.
+
+## Installation
+
+In your application's Gemfile, in the `:development` group:
+
+```ruby
+group :development do
+  gem "benedictus"
+end
+```
+
+Then:
+
+```sh
+bundle install
+```
+
+Three executables are installed: `benedictus`, `bnd`, `bemdito`.
+They are interchangeable.
+
+### Requirements
+
+- Ruby >= 3.1
+- ActiveRecord >= 6.1 (verified against Rails 8.x; 6.1 / 7.x should
+  work but aren't covered by CI yet)
+- PostgreSQL (any version supported by your Rails app)
+
+## Usage
+
+The first positional argument is a Ruby expression that resolves to an
+`ActiveRecord::Relation` — or a query object responding to `.call`, or
+anything responding to `.to_sql`.
+
+```sh
+bundle exec benedictus "User.active.recent"
+bundle exec benedictus "User.where(active: true).order(:created_at)"
+bundle exec benedictus "OrdersQuery.new(user_id: 123).call"
+bundle exec bnd        "User.active" --analyze --sql
+```
+
+### Options
+
+| Flag                  | Description                                         | Default     |
+|-----------------------|-----------------------------------------------------|-------------|
+| `--analyze` / `--analyse` | Run `EXPLAIN ANALYZE` inside a rolled-back transaction | `false` |
+| `--format FORMAT`     | Output format: `tree`, `json`, or `raw`             | `tree`      |
+| `--sql`               | Print the SQL being analyzed (formatted)            | `false`     |
+| `--buffers`           | Include buffer usage info (requires `--analyze`)    | `false`     |
+| `--verbose`           | Verbose plan output                                 | `false`     |
+| `--no-color`          | Disable colored output                              | TTY-aware   |
+| `--seq-scan-threshold ROWS` | Min `plan_rows` to flag a Seq Scan            | `10_000`    |
+| `--drift-factor X`    | Min actual/plan ratio to flag row-estimate drift    | `10`        |
+| `--nested-loop-threshold LOOPS` | Min inner loops to flag Nested Loop blowup | `10_000`   |
+| `--per-row-cost-threshold COST` | Min `(total − startup) / rows` to flag a scan | `1.0`     |
+| `--version` / `-v`    | Print version                                       | —           |
+| `--help` / `-h`       | Show help                                           | —           |
+
+The `NO_COLOR` environment variable also disables color, per
+[no-color.org](https://no-color.org). `--buffers` without `--analyze`
+emits a stderr warning and is otherwise ignored.
+
+### Output formats
+
+- `tree` (default) — the colored, annotated tree shown above.
+- `json` — pretty-printed Postgres JSON plan; paste into
+  [explain.dalibo.com](https://explain.dalibo.com) for a deeper look.
+- `raw` — the text-format `EXPLAIN` exactly as Postgres returns it.
+
+## Heuristics (v1)
+
+Inline warnings flag the most common issues. Every threshold is
+overridable via a CLI flag — see *Tuning thresholds* below.
+
+| Heuristic | Default trigger | Severity | Override flag |
+|---|---|---|---|
+| Seq Scan on a large table | `plan_rows > 10_000` | Critical (red) | `--seq-scan-threshold` |
+| Row estimate drift | `actual / plan > 10x` (under `--analyze`) | Warning (yellow) | `--drift-factor` |
+| External sort | `Sort Method` includes `"external"` | Critical (red) | — |
+| Nested Loop blowup | inner-side `actual_loops > 10_000` (under `--analyze`) | Warning (yellow) | `--nested-loop-threshold` |
+| Expensive per-row scan | `(total_cost − startup_cost) / plan_rows > 1.0` | Critical when correlated subplans drive it; Warning otherwise | `--per-row-cost-threshold` |
+
+The "expensive per-row scan" heuristic catches the *most common
+hidden-cost pattern*: a small Seq Scan that looks fine on row counts
+but whose total cost is multiplied by correlated subplans running once
+per outer row, like:
+
+```
+└─ Seq Scan on stars (cost=0.00..49318.79  rows=519)
+   ⚠  Seq Scan on stars costs 95.03 per row over 519 rows (total 49318.79). Driven by SubPlan 1, SubPlan 2.
+      Correlated subplans run once per outer row. Consider rewriting as a JOIN, LATERAL, or window function.
+```
+
+### Tuning thresholds
+
+```sh
+# Lower the Seq Scan trigger for a small dev database
+bundle exec benedictus "User.active" --seq-scan-threshold=500
+
+# Be more aggressive about flagging row-estimate drift
+bundle exec benedictus "User.active" --analyze --drift-factor=3
+
+# Catch even mildly expensive per-row work
+bundle exec benedictus "User.active" --per-row-cost-threshold=0.5
+```
+
+Each flag accepts a number; the units match the trigger column above.
+
+## Safety
+
+When `--analyze` is set, Benedictus applies three layers of defense:
+
+1. **Tokenizing static check.** The SQL is normalized — string
+   literals (single-quoted *and* dollar-quoted), line comments, and
+   nested block comments are stripped before any keyword scan. The
+   first remaining keyword must be `SELECT` (or `WITH` with no
+   data-modifying CTE).
+2. **Multi-statement rejection.** SQL containing `;` outside string
+   literals is rejected, so a `RawSqlAdapter` returning
+   `"SELECT 1; DELETE FROM users"` is refused.
+3. **AR-class rollback.** The EXPLAIN ANALYZE runs inside
+   `relation.klass.transaction(requires_new: true) { …; raise
+   ActiveRecord::Rollback }`. The class is verified to be
+   `<= ActiveRecord::Base`, so an arbitrary duck-typed
+   `transaction(...)` cannot silently disable the rollback.
+
+`RawSqlAdapter` (the fallback wrapper for any object that just
+responds to `.to_sql`) is **rejected outright under `--analyze`** —
+pass an actual `ActiveRecord::Relation` if you want to analyze.
+
+### Caveats
+
+`EXPLAIN ANALYZE` *physically executes the query plan* in order to
+measure runtime. The transaction wrapping reverts row-level changes,
+but the following kinds of side effects **escape ROLLBACK** and will
+persist:
+
+- Sequence advancement: `setval(...)`, `nextval(...)`
+- Advisory locks: `pg_advisory_lock(...)`, including session-level locks
+- Notifications: `pg_notify(...)`, `LISTEN`/`NOTIFY`
+- Cross-database writes via `dblink(...)`, `postgres_fdw`, foreign data wrappers
+- Large-object operations: `lo_create`, `lo_unlink`, `lo_put`
+- `COPY ... TO PROGRAM` (executes shell commands on the server)
+- `SECURITY DEFINER` UDFs whose body performs the above
+
+If your scope or query object passes a value through one of these
+functions, `--analyze` will run it for real and there is no rolling it
+back. **Use `--analyze` only on read-only queries** that don't call
+volatile functions.
+
+## Security note
+
+Benedictus uses `eval` to evaluate the expression you pass in.
+**The expression is your own Ruby code, executed in your own
+development environment.** Do not pass untrusted input.
+
+## Development
+
+```sh
+git clone https://github.com/tonyaraujop/benedictus
+cd benedictus
+bundle install
+bundle exec rspec spec/benedictus              # unit tests, no DB required
+bundle exec rspec spec/integration              # full integration, needs PG
+```
+
+Integration tests need a reachable PostgreSQL — see
+[`spec/support/dummy_app/README.md`](spec/support/dummy_app/README.md).
+A one-line `docker run` is documented there.
+
+## Etymology
+
+Latin *benedictus* = *bene* (well) + *dictus* (said) = "well-said".
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

data/exe/bemdito

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "benedictus"
+
+Benedictus::CLI.start(ARGV)

data/exe/benedictus

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "benedictus"
+
+Benedictus::CLI.start(ARGV)

data/exe/bnd

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "benedictus"
+
+Benedictus::CLI.start(ARGV)

data/lib/benedictus/cli.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Benedictus
+  class CLI < Thor
+    default_task :explain
+    map %w[--version -v] => :version
+
+    class << self
+      def exit_on_failure?
+        true
+      end
+
+      def start(given_args = ARGV, config = {})
+        args = Array(given_args)
+        return super if args.empty?
+        return super if dispatchable_directly?(args.first)
+
+        super(["explain", *args], config)
+      end
+
+      def dispatchable_directly?(arg)
+        return true if all_tasks.key?(arg.to_s)
+        return true if arg == "help"
+
+        # Match Thor-style flags: -x, --foo, --foo-bar.
+        # Does NOT match expressions starting with `-`, e.g. `-1.times`, `-User.count`.
+        arg.match?(/\A--?[a-zA-Z][\w-]*\z/)
+      end
+    end
+
+    desc "explain EXPRESSION", "Render an EXPLAIN tree for a Ruby/Rails expression"
+    long_desc <<~DESC
+      Evaluates EXPRESSION inside the host Rails app and renders the
+      EXPLAIN plan of the resolved ActiveRecord::Relation as a colored,
+      annotated tree. Pass --analyze to run EXPLAIN ANALYZE inside a
+      rolled-back transaction (SELECT-only).
+    DESC
+    option :analyze,    type: :boolean, default: false, aliases: ["--analyse"],
+                        desc: "Run EXPLAIN ANALYZE inside a rolled-back transaction"
+    option :format,     type: :string,  default: "tree", enum: %w[tree json raw],
+                        desc: "Output format"
+    option :sql,        type: :boolean, default: false,
+                        desc: "Print the SQL being analyzed"
+    option :buffers,    type: :boolean, default: false,
+                        desc: "Include buffer usage info (requires --analyze)"
+    option :verbose,    type: :boolean, default: false,
+                        desc: "Enable verbose plan output"
+    option :"no-color", type: :boolean, default: false,
+                        desc: "Disable colored output"
+    option :"seq-scan-threshold",     type: :numeric, banner: "ROWS",
+                                      desc: "Min plan_rows for a Seq Scan to be flagged (default: 10000)"
+    option :"drift-factor",           type: :numeric, banner: "X",
+                                      desc: "Min actual/plan ratio to flag row-estimate drift (default: 10)"
+    option :"nested-loop-threshold",  type: :numeric, banner: "LOOPS",
+                                      desc: "Min inner loops to flag a Nested Loop blowup (default: 10000)"
+    option :"per-row-cost-threshold", type: :numeric, banner: "COST",
+                                      desc: "Min per-row cost to flag an expensive scan (default: 1.0)"
+    def explain(expression)
+      Benedictus::Runner.new(expression: expression, options: options).call
+    rescue Benedictus::Error => e
+      handle_error(e)
+    end
+
+    desc "version", "Print the Benedictus version"
+    def version
+      puts Benedictus::VERSION
+    end
+
+    private
+
+    def handle_error(error)
+      color = Benedictus::Color.new(enabled: $stderr.tty? && !ENV["NO_COLOR"])
+      warn(color.red("benedictus: #{error.message}"))
+      exit error.exit_code
+    end
+  end
+end

data/lib/benedictus/color.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Benedictus
+  class Color
+    CODES = {
+      bold: 1,
+      dim: 2,
+      italic: 3,
+      red: 31,
+      green: 32,
+      yellow: 33,
+      blue: 34,
+      cyan: 36
+    }.freeze
+
+    def initialize(enabled: true)
+      @enabled = enabled
+    end
+
+    CODES.each_key do |style|
+      define_method(style) do |text = nil|
+        styled(text, [style])
+      end
+    end
+
+    private
+
+    def styled(text, styles)
+      return Decorator.new(@enabled, styles) if text.nil?
+      return text unless @enabled
+
+      "\e[#{styles.map { |s| CODES.fetch(s) }.join(";")}m#{text}\e[0m"
+    end
+
+    class Decorator
+      def initialize(enabled, styles)
+        @enabled = enabled
+        @styles  = styles
+      end
+
+      CODES.each_key do |style|
+        define_method(style) do |text = nil|
+          next self.class.new(@enabled, @styles + [style]) if text.nil?
+          next text unless @enabled
+
+          codes = (@styles + [style]).map { |s| CODES.fetch(s) }.join(";")
+          "\e[#{codes}m#{text}\e[0m"
+        end
+      end
+    end
+  end
+end

data/lib/benedictus/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Benedictus
+  class Error < StandardError
+    EXIT_CODE = 1
+
+    def exit_code
+      self.class::EXIT_CODE
+    end
+  end
+
+  class RailsNotFoundError < Error
+    EXIT_CODE = 2
+  end
+
+  class EvaluationError < Error
+    EXIT_CODE = 3
+  end
+
+  class UnresolvableExpression < Error
+    EXIT_CODE = 3
+  end
+
+  class UnsafeQueryError < Error
+    EXIT_CODE = 4
+  end
+
+  class DatabaseError < Error
+    EXIT_CODE = 5
+  end
+end

data/lib/benedictus/expression_evaluator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Benedictus
+  class ExpressionEvaluator
+    EVAL_ERRORS = [NameError, NoMethodError, SyntaxError, LoadError].freeze
+
+    def self.call(expression)
+      new(expression).call
+    end
+
+    def initialize(expression)
+      @expression = expression
+    end
+
+    def call
+      raise Benedictus::EvaluationError, "Expression is empty" if @expression.to_s.strip.empty?
+
+      eval(@expression, TOPLEVEL_BINDING, "(benedictus)")
+    rescue *EVAL_ERRORS => e
+      raise Benedictus::EvaluationError,
+            "Failed to evaluate expression `#{@expression}`: #{e.class}: #{e.message}"
+    end
+  end
+end

data/lib/benedictus/heuristics/base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Heuristics
+    class Base
+      def self.apply(node)
+        new.apply(node)
+      end
+
+      def apply(_node)
+        raise NotImplementedError, "#{self.class}#apply must return an Array<Warning>"
+      end
+
+      protected
+
+      def warning(severity:, code:, message:, suggestion: nil)
+        Warning.new(severity: severity, code: code, message: message, suggestion: suggestion)
+      end
+    end
+  end
+end

data/lib/benedictus/heuristics/expensive_per_row_scan.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Heuristics
+    # Flags scan nodes whose per-row cost is anomalously high — usually
+    # a sign that correlated subplans (or expensive filter functions) are
+    # multiplying the work the scan does for every outer row.
+    #
+    # A normal Seq Scan tends to cost ~0.05 per row; anything above ~1.0 is
+    # almost always doing something extra (a SubPlan running per row, a
+    # SECURITY DEFINER UDF in a filter, etc.).
+    class ExpensivePerRowScan < Base
+      DEFAULT_THRESHOLD = 1.0
+      SCAN_TYPES = ["Seq Scan", "Index Scan", "Index Only Scan", "Bitmap Heap Scan"].freeze
+
+      def self.config_key
+        :per_row_cost_threshold
+      end
+
+      def initialize(threshold: DEFAULT_THRESHOLD)
+        super()
+        @threshold = threshold
+      end
+
+      def apply(node)
+        return [] unless SCAN_TYPES.include?(node.node_type)
+        return [] unless node.plan_rows&.positive?
+        return [] unless node.total_cost && node.startup_cost
+
+        per_row = (node.total_cost - node.startup_cost) / node.plan_rows.to_f
+        return [] if per_row < @threshold
+
+        subplans = subplan_children(node)
+
+        [
+          warning(
+            severity: subplans.any? ? :critical : :warning,
+            code: :expensive_per_row_scan,
+            message: build_message(node, per_row, subplans),
+            suggestion: build_suggestion(subplans)
+          )
+        ]
+      end
+
+      private
+
+      def subplan_children(node)
+        node.children.select { |c| %w[SubPlan InitPlan].include?(c.parent_relationship) }
+      end
+
+      def build_message(node, per_row, subplans)
+        target = node.relation_name || "unknown"
+        base = "#{node.node_type} on #{target} costs #{format("%.2f", per_row)} per row over #{node.plan_rows} rows " \
+               "(total #{format("%.2f", node.total_cost - node.startup_cost)})."
+        return base if subplans.empty?
+
+        names = subplans.filter_map(&:subplan_name).uniq
+        suffix = names.empty? ? "#{subplans.size} correlated subplan(s)" : names.join(", ")
+        "#{base} Driven by #{suffix}."
+      end
+
+      def build_suggestion(subplans)
+        if subplans.any?
+          "Correlated subplans run once per outer row. Consider rewriting as a JOIN, LATERAL, or window function."
+        else
+          "Heavy per-row processing — check the filter for expensive function calls."
+        end
+      end
+    end
+  end
+end