pg_canary 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5d97dd5cbefd1e0f736b3800993118237cb01c427e55d7c9dbc44a4296d63627
+  data.tar.gz: 1ebaec08d05be5f91fd6275b0236a4b5b6fbd53d826bfd319789cf8ee727f22d
+SHA512:
+  metadata.gz: 539edfe1fe783b0d4619d331e527447054ffd44affc964c514fb6d09005c2f8ffc8b48478816ad1ca088a8ef53b0827165b4895892d50d2222b7f207e46fe29e
+  data.tar.gz: 3bae6b432546feb624e0f898f4d8a23e1a3050a25f47e20bbfff89a81e34bd3c4b37acc65fbeb9574fa35e40fd48aab6f23f9d4fa7d99e9593079054149720e6

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.1.0] - 2026-07-14
+
+Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 kyuuri1791
+
+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,114 @@
+# pg_canary
+
+pg_canary watches the SQL your Rails app executes in development/test and warns about anti-patterns that can become slow queries in production: leading-wildcard `LIKE`s without a trigram index, function-wrapped columns in `WHERE`, `ORDER BY RANDOM()`, `NOT IN (SELECT ...)`, and more. PostgreSQL only.
+
+![pg_canary detecting a leading-wildcard LIKE query](demo.png)
+
+## Installation
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem "pg_canary"
+end
+```
+
+## Detection rules
+
+### Tier 1 — enabled by default (suspicious regardless of table size)
+
+| Rule | Detects | Rationale |
+|---|---|---|
+| `leading_wildcard_like` | `LIKE '%foo'` / `ILIKE '%foo%'` on a column without a pg_trgm GIN/GiST index | A leading wildcard can never use a btree index (having one doesn't help). pg_trgm is the only fix |
+| `deep_offset` | `OFFSET` beyond a threshold (default 1000) | Every skipped row is read and discarded; deep pages degrade linearly. Suggests keyset pagination |
+| `huge_in_list` | `IN (...)` / `= ANY(...)` with more values than a threshold (default 500) | Expensive to parse/plan, and usually a missing JOIN |
+| `correlated_subquery_in_select` | Scalar subquery in the SELECT list referencing the outer table | Executes once per returned row (an N+1 inside a single query). Suggests JOIN + GROUP BY |
+| `jsonb_search_without_gin` | jsonb search (`@>`, `?`, …) without a GIN index, or `->>` filtering without a matching expression index | No index can serve these predicates otherwise |
+| `array_search_without_gin` | Array search (`@>`, `&&`, `= ANY(column)`) without a GIN index | Same as above, for array columns |
+| `function_on_column` | The searched column wrapped in a function (`WHERE lower(email) = ?`) with no matching expression index | A function-wrapped column cannot be an index search key |
+| `not_in_subquery` | `NOT IN (SELECT ...)` | A single NULL from the subquery silently empties the result, and the planner optimizes it poorly compared to an anti-join. Suggests rewriting to `NOT EXISTS` |
+| `order_by_random` | `ORDER BY RANDOM()` | Reads and sorts every row; cost grows linearly with table size |
+| `regex_without_trgm` | `~` / `~*` / `SIMILAR TO` on a column without a trigram index | The regex variant of `leading_wildcard_like` |
+| `cartesian_join` | JOIN with no join condition — explicit `CROSS JOIN` between tables, or a comma join never connected in WHERE | The result grows with the product of both tables' row counts |
+| `implicit_cast` | Integer column compared with a numeric literal (`age = 1.5`) | The *column* gets implicitly cast to numeric, disabling its index. Restricted to cases provable from the AST alone |
+
+Notes:
+
+- `deep_offset` and `huge_in_list` read the **runtime bind values** (`OFFSET $1`, array binds) from the `sql.active_record` event — static SQL linters that only see query text cannot do this. `leading_wildcard_like` uses the same mechanism for `LIKE $1`.
+- `function_on_column` matches expression indexes by (function name, column name) — a deliberate approximation rather than full location-insensitive AST equality, which is sufficient in practice
+
+### Tier 2 — disabled by default (opt-in)
+
+| Rule | Detects |
+|---|---|
+| `unindexed_where` | Equality/range predicate columns in WHERE with no index led by any of them (leftmost-prefix matching on composite indexes is taken into account) |
+| `unindexed_order_by_with_limit` | `ORDER BY x LIMIT n` with no index led by x |
+| `unindexed_join` | Join-condition columns with no index. Looks at joins that actually ran, so raw-SQL joins are covered too |
+| `count_star_without_where` | `SELECT COUNT(*)` without WHERE — MVCC means a full scan. Suggests `reltuples` estimates or counter caches |
+| `distinct_with_join` | DISTINCT combined with JOIN, which often hides join fanout. Suggests `EXISTS`. Legitimate uses exist, hence opt-in |
+| `union_instead_of_union_all` | `UNION` without ALL — deduplication sorts the whole result. Whether duplicates matter is the author's call |
+| `or_across_columns` | OR spanning different columns, which often prevents a single index scan. PostgreSQL can sometimes BitmapOr, hence opt-in |
+| `select_star_with_heavy_columns` | `SELECT *` (ActiveRecord's default) on tables with heavy columns (bytea/text/jsonb, configurable) |
+| `query_complexity` | More than 8 joins or subquery nesting deeper than 4 (both configurable) — the "spaghetti query" guard |
+
+**Why disabled by default:** the first four depend on production table size — a missing index is not a problem in itself. Lookup tables like prefectures or plans hold a few dozen rows in production too, and a Seq Scan is the *correct* plan for them. The rest depend on the author's intent (deliberate DISTINCT, required deduplication, acceptable payloads). Nothing in the schema or the AST reveals either, so enabling these rules by default would drown you in false positives.
+
+Rule-specific thresholds are set through the same `config.rules` interface:
+
+```ruby
+config.rules.deep_offset.threshold = 2000
+config.rules.huge_in_list.threshold = 200
+config.rules.query_complexity.max_joins = 12
+config.rules.select_star_with_heavy_columns.heavy_types = %w[bytea jsonb]
+```
+
+Once opted in, you can keep false positives down two ways:
+
+1. List small tables in `config.ignore_tables`
+2. Provide approximate production row counts in `config.table_size_hints` — when hints are present, Tier 2 rules apply **only** to tables hinted at `size_rule_threshold` (default 10,000) or above. When hints are empty, Tier 2 rules apply to every table — which is precisely why they are off by default.
+
+## Configuration
+
+Everything works with the defaults; an initializer is only needed to change them — e.g. to enable Tier 2 rules:
+
+```ruby
+# config/initializers/pg_canary.rb
+PgCanary.configure do |config|
+  config.enabled = Rails.env.development?
+
+  # Per-rule settings
+  config.rules.unindexed_where.enabled = true
+  config.rules.leading_wildcard_like.severity = :error  # :error / :warning
+
+  # Excluding tables
+  config.ignore_tables = %w[prefectures plans schema_migrations ar_internal_metadata]
+
+  # For size-dependent (Tier 2) rules: approximate production row counts
+  config.table_size_hints = { "users" => 1_000_000, "orders" => 10_000_000 }
+  config.size_rule_threshold = 10_000  # apply Tier 2 rules only to tables hinted at or above this
+end
+```
+
+## Notifications
+
+Detections show up in a panel at the bottom of the page, each with: the rule name, the SQL, the table/columns involved, why it's a problem, the suggested fix, and the source location (file:line).
+
+## How it works
+
+pg_canary subscribes to ActiveRecord's `sql.active_record` notifications and analyzes each executed SELECT. Detection is based on the query's AST — parsed with [`pg_query`](https://github.com/pganalyze/pg_query), a binding to PostgreSQL's own parser — combined with schema metadata (index definitions, opclasses, expression indexes, column types) read through ActiveRecord's schema cache. Detections raised during a request are collected by a Rack middleware, which injects the panel into the HTML response.
+
+## Development
+
+The test suite runs integration tests against a local PostgreSQL (docker-compose included):
+
+```console
+$ docker compose up -d --wait
+$ bundle install
+$ bundle exec rake
+```
+
+To test against a different Rails version: `RAILS_VERSION=7.1 bundle install && bundle exec rspec`
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/pg_canary/configuration.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module PgCanary
+  # Global settings, exposed through PgCanary.configure.
+  class Configuration
+    # nil means "not explicitly configured" — the Railtie then enables
+    # pg_canary in development/test only.
+    attr_accessor :enabled
+
+    # False-positive controls
+    attr_accessor :ignore_tables, :table_size_hints, :size_rule_threshold
+
+    attr_accessor :logger, :app_root
+    attr_reader :rules
+
+    def initialize
+      @enabled = nil
+      @ignore_tables = %w[schema_migrations ar_internal_metadata]
+      @table_size_hints = {}
+      @size_rule_threshold = 10_000
+      @rules = RulesConfig.new
+      @logger = nil
+      @app_root = nil
+    end
+
+    def ignore_table?(table)
+      table && ignore_tables.map(&:to_s).include?(table.to_s)
+    end
+
+    # Whether a size-dependent (Tier 2) rule should look at this table.
+    # With no hints configured, every table qualifies (which is exactly why
+    # Tier 2 rules are opt-in).
+    def size_hint_allows?(table)
+      hints = table_size_hints || {}
+      return true if hints.empty?
+
+      hints[table.to_s].to_i >= size_rule_threshold
+    end
+  end
+
+  # Exposes one RuleConfig per built-in rule, both as methods and via [].
+  #
+  #   config.rules.unindexed_where.enabled = true
+  #   config.rules[:leading_wildcard_like].severity = :error
+  class RulesConfig
+    def initialize
+      @configs = {}
+      Rules::Base.all.each do |klass|
+        rule_config = RuleConfig.new(klass.options)
+        @configs[klass.rule_name] = rule_config
+        define_singleton_method(klass.rule_name) { rule_config }
+      end
+    end
+
+    def [](name)
+      @configs.fetch(name.to_sym)
+    end
+  end
+
+  # Per-rule settings. `enabled` / `severity` default to nil, meaning
+  # "use the rule class's default". Accessors for rule-specific options
+  # (e.g. config.rules.deep_offset.threshold = 2000) are generated from the
+  # rule class's declared options, so a typo raises NoMethodError instead of
+  # silently creating a setting nobody reads.
+  class RuleConfig
+    attr_accessor :enabled, :severity
+
+    def initialize(option_defaults = {})
+      @options = option_defaults.dup
+      @options.each_key do |name|
+        define_singleton_method(name) { @options[name] }
+        define_singleton_method(:"#{name}=") { |value| @options[name] = value }
+      end
+    end
+
+    def [](key)
+      @options.fetch(key.to_sym)
+    end
+  end
+end

data/lib/pg_canary/detector.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "active_support/backtrace_cleaner"
+
+module PgCanary
+  # Parses an event's SQL into a QueryContext, runs every enabled rule
+  # against it, and filters ignored tables. Each returned Detection carries
+  # the query's fingerprint, so a consumer that sees the same query and rule
+  # repeatedly (e.g. an N+1 loop within one request) can collapse them —
+  # see Middleware.
+  class Detector
+    include PgQuerySupport
+
+    # Swallows the configuration whole at construction: pg_canary treats it
+    # as fixed after boot (set in an initializer).
+    def initialize(config)
+      @config = config
+      @rules = Rules::Base.all.map(&:new).select { |rule| rule.enabled?(config) }
+      @backtrace_cleaner = build_backtrace_cleaner(config.app_root)
+    end
+
+    # => [Detection] the detections that should be notified.
+    def call(payload)
+      query = build_query(payload)
+      return [] unless query
+
+      location = nil
+      @rules.flat_map do |rule|
+        detections = check_rule(rule, query)
+        next [] if detections.empty?
+
+        location ||= source_location
+        detections.each do |d|
+          d.location = location
+          d.fingerprint = query.fingerprint
+        end
+      end
+    end
+
+    private
+
+    # nil for anything that is not a plain SELECT (or fails to parse).
+    def build_query(payload)
+      parse_result = PgQuery.parse(payload[:sql])
+      stmt = unwrap_node(parse_result.tree.stmts.first&.stmt)
+      return nil unless stmt.is_a?(PgQuery::SelectStmt)
+
+      Rules::QueryContext.new(
+        sql: payload[:sql],
+        connection: payload[:connection],
+        parse_result: parse_result,
+        config: @config,
+        binds: payload[:binds],
+        type_casted_binds: payload[:type_casted_binds]
+      )
+    rescue PgQuery::ParseError
+      nil
+    end
+
+    def check_rule(rule, query)
+      rule.check(query).reject { |d| ignored?(d, query) }
+    rescue StandardError => e
+      PgCanary.internal_error(e)
+      []
+    end
+
+    def ignored?(detection, query)
+      config = query.config
+      return true if config.ignore_table?(detection.table)
+
+      # Table-less detections (e.g. ORDER BY RANDOM() over a subquery) are
+      # dropped when every table in the query is ignored.
+      if detection.table.nil?
+        tables = query.tables
+        return tables.any? && tables.all? { |t| config.ignore_table?(t) }
+      end
+
+      false
+    end
+
+    def build_backtrace_cleaner(root)
+      ActiveSupport::BacktraceCleaner.new.tap do |cleaner|
+        cleaner.add_silencer { |line| line.include?("lib/pg_canary") }
+        cleaner.add_filter { |line| line.delete_prefix("#{root}/") } if root
+      end
+    end
+
+    # The application frame that triggered the query.
+    def source_location
+      line = @backtrace_cleaner.clean(caller).first
+      line && line[/\A.+?:\d+/]
+    end
+  end
+end

data/lib/pg_canary/middleware.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module PgCanary
+  # Rack middleware: collects the detections raised while the request runs
+  # (via the thread-local collector .collect appends to), collapses repeats
+  # of the same query within that request, and injects a footer panel into
+  # HTML responses.
+  class Middleware
+    COLLECTOR_KEY = :pg_canary_request_detections
+
+    def self.collect(detections)
+      Thread.current[COLLECTOR_KEY]&.concat(detections)
+    end
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      return @app.call(env) unless active?
+
+      detections = []
+      previous = Thread.current[COLLECTOR_KEY]
+      Thread.current[COLLECTOR_KEY] = detections
+      status, headers, body = @app.call(env)
+      detections = dedup(detections)
+      return [status, headers, body] if detections.empty?
+
+      inject(status, headers, body, detections)
+    ensure
+      Thread.current[COLLECTOR_KEY] = previous
+    end
+
+    private
+
+    def active?
+      PgCanary.config.enabled
+    end
+
+    # Collapses repeats of the same (query, rule) — e.g. an N+1 loop — into
+    # a single panel entry. Scoped to this one request: a fresh page load
+    # (or a reload of the same page) always shows detections again.
+    def dedup(detections)
+      detections.uniq { |d| [d.fingerprint, d.rule_name] }
+    end
+
+    def inject(status, headers, body, detections)
+      return [status, headers, body] unless html_response?(headers)
+
+      content = +""
+      body.each { |part| content << part }
+      body.close if body.respond_to?(:close)
+
+      snippet = footer_panel(detections)
+      if content.include?("</body>")
+        content = content.sub("</body>", "#{snippet}</body>")
+      else
+        content << snippet
+      end
+
+      headers = headers.merge("Content-Length" => content.bytesize.to_s) if content_length?(headers)
+      [status, headers, [content]]
+    end
+
+    def html_response?(headers)
+      headers.any? { |k, v| k.to_s.casecmp("content-type").zero? && v.to_s.include?("text/html") }
+    end
+
+    def content_length?(headers)
+      headers.any? { |k, _| k.to_s.casecmp("content-length").zero? }
+    end
+
+    def footer_panel(detections)
+      items = detections.map do |d|
+        <<~HTML
+          <div style="padding:8px 12px;border-top:1px solid #444;">
+            <div>
+              <strong style="color:#{d.severity == :error ? "#ff6b6b" : "#ffd93d"};">#{h(d.rule_name)}</strong>
+              <span style="opacity:.7;">(#{h(d.severity)})</span>
+              #{subject_span(d)}
+            </div>
+            <pre style="margin:4px 0;white-space:pre-wrap;color:#9ecbff;">#{h(d.truncated_sql)}</pre>
+            <div style="white-space:pre-wrap;">→ #{h(d.message)}</div>
+            #{%(<pre style="margin:4px 0;white-space:pre-wrap;color:#98c379;">#{h(d.suggestion)}</pre>) if d.suggestion}
+            #{%(<div style="opacity:.7;">at #{h(d.location)}</div>) if d.location}
+          </div>
+        HTML
+      end
+
+      <<~HTML
+        <div id="pg-canary-panel" style="position:fixed;left:0;right:0;bottom:0;max-height:45vh;overflow-y:auto;z-index:2147483647;background:#1e1e1e;color:#eee;font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;box-shadow:0 -2px 8px rgba(0,0,0,.4);">
+          <div style="display:flex;justify-content:space-between;align-items:center;padding:6px 12px;background:#2d2d2d;">
+            <strong>🐤 PgCanary — #{detections.size} anti-pattern#{"s" if detections.size > 1} detected</strong>
+            <button onclick="document.getElementById('pg-canary-panel').remove()" style="background:none;border:1px solid #666;color:#eee;cursor:pointer;padding:2px 8px;">×</button>
+          </div>
+          #{items.join}
+        </div>
+      HTML
+    end
+
+    def subject_span(detection)
+      return "" unless detection.table
+
+      subject = detection.table
+      subject += ".#{detection.columns.join(", ")}" if detection.columns.any?
+      %(<span style="opacity:.8;"> — #{h(subject)}</span>)
+    end
+
+    def h(value)
+      CGI.escapeHTML(value.to_s)
+    end
+  end
+end

data/lib/pg_canary/pg_query_support.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module PgCanary
+  # Helpers over the pg_query protobuf AST — the unwrapping, traversal and
+  # value extraction the pg_query gem does not provide itself. Mix into
+  # anything that inspects parsed queries (include for instance level,
+  # extend for class level).
+  module PgQuerySupport
+    COMPARISON_OPS = %w[= <> != < > <= >=].freeze
+
+    private
+
+    # --- unwrapping wrapper nodes -------------------------------------
+
+    # Unwraps a PgQuery::Node (oneof wrapper) into its inner message.
+    def unwrap_node(node)
+      return nil if node.nil?
+      return node unless node.is_a?(PgQuery::Node)
+
+      node.node ? node.inner : nil
+    end
+
+    # Strips TypeCast wrappers: `'foo'::text` → the A_Const for 'foo'.
+    def strip_type_casts(node)
+      node = unwrap_node(node)
+      node = unwrap_node(node.arg) while node.is_a?(PgQuery::TypeCast)
+      node
+    end
+
+    # --- traversal ----------------------------------------------------
+
+    # Depth-first walk over every protobuf message under +node+, yielding
+    # each unwrapped message. When +prune+ returns true for a message, it is
+    # yielded but its children are not visited.
+    def walk_ast(node, prune: nil, &block)
+      node = unwrap_node(node)
+      return if node.nil?
+      return unless node.is_a?(Google::Protobuf::MessageExts)
+
+      yield node
+      return if prune&.call(node)
+
+      each_ast_child(node) { |child| walk_ast(child, prune: prune, &block) }
+    end
+
+    # Yields every message-typed child of a protobuf message.
+    def each_ast_child(node, &block)
+      node.class.descriptor.each do |field|
+        next unless field.type == :message
+
+        value = node[field.name]
+        next if value.nil?
+
+        if value.is_a?(Google::Protobuf::RepeatedField)
+          value.each(&block)
+        else
+          yield value
+        end
+      end
+    end
+
+    # Walk that does not descend into nested sub-selects, so each scope is
+    # analyzed exactly once. Yielding starts at the given node's children,
+    # i.e. pass a where_clause / sort item, not a whole statement.
+    def walk_within_scope(node, &)
+      root_seen = false
+      walk_ast(node, prune: lambda { |msg|
+        if root_seen
+          msg.is_a?(PgQuery::SelectStmt)
+        else
+          root_seen = true # never prune the root itself
+          false
+        end
+      }, &)
+    end
+
+    # --- reading values out of nodes ----------------------------------
+
+    # ["users", "name"] for "users"."name"; nil when the ref contains A_Star.
+    def column_ref_fields(column_ref)
+      fields = column_ref.fields.map { |f| unwrap_node(f) }
+      return nil unless fields.all?(PgQuery::String)
+
+      fields.map(&:sval)
+    end
+
+    def string_values(nodes)
+      nodes.map { |n| unwrap_node(n) }.grep(PgQuery::String).map(&:sval)
+    end
+
+    # Operator name of an A_Expr, e.g. "=", "~~", "~~*".
+    def operator_name(a_expr)
+      string_values(a_expr.name).last
+    end
+
+    # Unqualified, downcased function name of a FuncCall.
+    def function_name(func_call)
+      string_values(func_call.funcname).last&.downcase
+    end
+
+    # Ruby value of an A_Const: Integer, Float, String, true/false or nil.
+    def constant_value(a_const)
+      case a_const.val
+      when :ival then a_const.ival.ival
+      when :fval then a_const.fval.fval.to_f
+      when :sval then a_const.sval.sval
+      when :boolval then a_const.boolval.boolval
+      end
+    end
+
+    def comparison_expr?(a_expr)
+      a_expr.kind == :AEXPR_OP && COMPARISON_OPS.include?(operator_name(a_expr))
+    end
+  end
+end

data/lib/pg_canary/rules/base.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Base class for detection rules.
+    #
+    # A rule implements #check(query) and returns an array of Detection.
+    # Configuration flows in explicitly through the QueryContext
+    # (query.config); rules never reach for global state themselves.
+    class Base
+      include PgQuerySupport
+
+      class << self
+        def all
+          subclasses.sort_by(&:name)
+        end
+
+        # :leading_wildcard_like for LeadingWildcardLike
+        def rule_name
+          @rule_name ||= name.split("::").last
+                             .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                             .downcase.to_sym
+        end
+
+        # Rule-specific options and their defaults, e.g. { threshold: 1000 }.
+        # Declared statically so RuleConfig can generate real accessors.
+        def options
+          {}
+        end
+      end
+
+      def check(_query)
+        raise NotImplementedError, "#{self.class} must implement #check"
+      end
+
+      def enabled?(config)
+        setting = config.rules[self.class.rule_name].enabled
+        setting.nil? ? default_enabled : setting
+      end
+
+      def default_enabled
+        raise NotImplementedError, "#{self.class} must declare #default_enabled (true for Tier 1, false for Tier 2)"
+      end
+
+      def size_dependent?
+        raise NotImplementedError, "#{self.class} must declare #size_dependent?"
+      end
+
+      private
+
+      def rule_config(query)
+        query.config.rules[self.class.rule_name]
+      end
+
+      # Tier 2 gate: with size hints configured, only tables hinted as large
+      # are checked.
+      def applicable_table?(query, table)
+        return false if query.config.ignore_table?(table)
+        return true unless size_dependent?
+
+        query.config.size_hint_allows?(table)
+      end
+
+      def detection(query, message:, suggestion: nil, table: nil, columns: nil)
+        Detection.new(
+          rule_name: self.class.rule_name,
+          severity: rule_config(query).severity || :warning,
+          sql: query.sql,
+          table: table,
+          columns: Array(columns),
+          message: message,
+          suggestion: suggestion
+        )
+      end
+    end
+  end
+end