pg_canary 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3117b64abbdaf73701f98780b6dd794822d6bf19919365e3a7c4ffffa62b69a5
-  data.tar.gz: c1c73a9c77af75bdcbc7bd3b3685654387728986a5d1d7a880c69c7263dc4ca6
+  metadata.gz: cb33135791d90607ecc14dc44818adc8a7173cb9ed4f5da995dbfeacc31de62e
+  data.tar.gz: a25ba3b887e3ec90961f63442b5a1721a60f41a8d11fe2902d3110cad904cf26
 SHA512:
-  metadata.gz: 17df21da5a3d3a6f221db4aa087d4627fac79de5e8a9d4c7cd96c77849df96a47a63ea4d681a9404bd0b52274cbf7424e926cb7a84769532b8e7b81dd0daa089
-  data.tar.gz: '08302281e57605688fd0eaded8f1a2d031ebae2b5e9499d67c564aecd81e420de5d8f015b495e3a5153297e0e3113366874fe13563c78eb403db7bd3a3eb40c5'
+  metadata.gz: d1116dfd6490e78a40f974d884d56e7ce095b39e5d61a1d6bb2e48de13e63ea2f3ad50f0b40168ccbbdb88269d1a5a72d5f0bad4319b23a06f3205cd22980ec9
+  data.tar.gz: dd130131ff6bcb1944cdc2173d99e3652c4a43572f89c3118d34634ff43ec4b4ec062a134f31237ac251d1d8ebc71088275dfeeb54e4579c8abb51e5738b0fc4

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.3.0] - 2026-07-20
+
+- Default `config.enabled` to development only (was development and test). The HTML panel is the only output, so running in test only added overhead and could alter response bodies under test.
+- Remove per-rule `severity` (`:error` / `:warning`). It only changed the panel's label color and implied consequences (failing tests) the gem doesn't have; detections are uniformly warnings now.
+- Remove `[]` access to rule settings (`config.rules[:deep_offset]`); use the method form (`config.rules.deep_offset`).
+
 ## [0.2.0] - 2026-07-18
 
 - Remove `config.table_size_hints` / `config.size_rule_threshold`. Tier 2 rules are already opt-in per rule; use `config.ignore_tables` to exclude small tables.

data/README.md

@@ -15,7 +15,7 @@ end
 
 ## Detection rules
 
-### Tier 1 — enabled by default (suspicious regardless of table size)
+### Enabled by default
 
 | Rule | Detects | Rationale |
 |---|---|---|
@@ -32,12 +32,7 @@ end
 | `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)
+### Disabled by default
 
 | Rule | Detects |
 |---|---|
@@ -51,44 +46,35 @@ Notes:
 | `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]
-```
+**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 right 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 these rules would produce many false positives if enabled by default. Enable the ones that fit your app individually (see [Configuration](#configuration)).
 
 Once opted in, keep false positives down by listing small tables in `config.ignore_tables`.
 
 ## Configuration
 
-Everything works with the defaults; an initializer is only needed to change them — e.g. to enable Tier 2 rules:
+Everything works with the defaults. To change them, create an initializer:
 
 ```ruby
 # config/initializers/pg_canary.rb
 PgCanary.configure do |config|
-  config.enabled = Rails.env.development?
+  # Where to run (defaults to development)
+  config.enabled = Rails.env.development? || Rails.env.test?
+
+  # Excluding tables
+  config.ignore_tables += %w[prefectures plans]
 
   # 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]
+  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]
 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.
+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. Because analysis happens at query execution time, runtime bind values are visible too — `OFFSET $1` with a bound value of 50000 is still caught, which linters that only see query text cannot do. Detections raised during a request are collected by a Rack middleware, which injects the panel into the HTML response.
 
 ## Development
 

data/lib/pg_canary/configuration.rb

@@ -2,14 +2,7 @@
 
 module PgCanary
   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
-
-    attr_accessor :logger, :app_root
+    attr_accessor :enabled, :ignore_tables, :logger, :app_root
     attr_reader :rules
 
     def initialize
@@ -25,32 +18,17 @@ module PgCanary
     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
+    attr_accessor :enabled
 
     def initialize(option_defaults = {})
       @options = option_defaults.dup
@@ -59,9 +37,5 @@ module PgCanary
         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

@@ -3,92 +3,100 @@
 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.
+  # Parses an event's SQL, 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
+    using PgCanary::PgQueryRefinement
 
     # 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)
+      @rule_classes = Rules::Base.all.select { |klass| klass.enabled?(config) }
+      @backtrace_cleaner = ActiveSupport::BacktraceCleaner.new.tap do |cleaner|
+        root = config.app_root
+        cleaner.add_silencer { |line| line.include?("lib/pg_canary") }
+        cleaner.add_filter { |line| line.delete_prefix("#{root}/") } if root
+      end
     end
 
     # => [Detection] the detections that should be notified.
     def call(payload)
-      query = build_query(payload)
-      return [] unless query
+      state = build_state(payload)
+      return [] unless state
 
       location = nil
-      @rules.flat_map do |rule|
-        detections = check_rule(rule, query)
+      fingerprint = nil
+      @rule_classes.flat_map do |klass|
+        detections = check_rule(klass, state)
         next [] if detections.empty?
 
         location ||= source_location
+        fingerprint ||= PgQuery.fingerprint(state[:sql])
         detections.each do |d|
           d.location = location
-          d.fingerprint = query.fingerprint
+          d.fingerprint = 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
+      # nil for anything that is not a plain SELECT (or fails to parse).
+      def build_state(payload)
+        parse_result = PgQuery.parse(payload[:sql])
+        stmt = parse_result.tree.stmts.first&.stmt&.unwrap
+        return nil unless stmt.is_a?(PgQuery::SelectStmt)
 
-    def check_rule(rule, query)
-      rule.check(query).reject { |d| ignored?(d, query) }
-    rescue StandardError => e
-      PgCanary.internal_error(e)
-      []
-    end
+        {
+          sql: payload[:sql],
+          config: @config,
+          connection: payload[:connection],
+          parse_result: parse_result,
+          scopes: build_scopes(parse_result),
+          binds: payload[:binds],
+          type_casted_binds: payload[:type_casted_binds]
+        }
+      rescue PgQuery::ParseError
+        nil
+      end
 
-    def ignored?(detection, query)
-      config = query.config
-      return true if config.ignore_table?(detection.table)
+      # All SELECT scopes in the statement, including CTEs, subqueries in
+      # FROM/WHERE and UNION branches.
+      def build_scopes(parse_result)
+        stmts = []
+        parse_result.tree.stmts.each do |raw|
+          raw.stmt.walk { |msg| stmts << msg if msg.is_a?(PgQuery::SelectStmt) }
+        end
+        stmts.map { |s| Rules::Scope.new(s) }
+      end
 
-      # 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) }
+      def check_rule(klass, state)
+        klass.check(**state).reject { |d| ignored?(d, state[:scopes]) }
+      rescue StandardError => e
+        PgCanary.internal_error(e)
+        []
       end
 
-      false
-    end
+      def ignored?(detection, scopes)
+        return true if @config.ignore_table?(detection.table)
 
-    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
+        # 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 = scopes.flat_map(&:tables).uniq
+          return tables.any? && tables.all? { |t| @config.ignore_table?(t) }
+        end
+
+        false
       end
-    end
 
-    # The application frame that triggered the query.
-    def source_location
-      line = @backtrace_cleaner.clean(caller).first
-      line && line[/\A.+?:\d+/]
-    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

@@ -35,81 +35,80 @@ module PgCanary
 
     private
 
-    def active?
-      PgCanary.config.enabled
-    end
+      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
+      # 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)
 
-    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)
 
-      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
 
-      snippet = footer_panel(detections)
-      if content.include?("</body>")
-        content = content.sub("</body>", "#{snippet}</body>")
-      else
-        content << snippet
+        headers = headers.merge("Content-Length" => content.bytesize.to_s) if content_length?(headers)
+        [status, headers, [content]]
       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 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 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:#ffd93d;">#{h(d.rule_name)}</strong>
+                #{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
 
-    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 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>
-            <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}
+            #{items.join}
           </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
+      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
+        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
+      def h(value)
+        CGI.escapeHTML(value.to_s)
+      end
   end
 end

data/lib/pg_canary/pg_query_refinement.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module PgQueryRefinement
+    COMPARISON_OPS = %w[= <> != < > <= >=].freeze
+
+    module Impl
+      module_function
+
+      def unwrap(node)
+        return nil if node.nil?
+        return node unless node.is_a?(PgQuery::Node)
+
+        node.node ? node.inner : nil
+      end
+
+      def strip_casts(node)
+        node = unwrap(node)
+        node = unwrap(node.arg) while node.is_a?(PgQuery::TypeCast)
+        node
+      end
+
+      def walk(node, prune: nil, &block)
+        node = unwrap(node)
+        return if node.nil?
+        return unless node.is_a?(Google::Protobuf::MessageExts)
+
+        yield node
+        return if prune&.call(node)
+
+        each_child(node) { |child| walk(child, prune: prune, &block) }
+      end
+
+      def each_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
+
+      def walk_scope(node, &)
+        root_seen = false
+        walk(node, prune: lambda { |msg|
+          if root_seen
+            msg.is_a?(PgQuery::SelectStmt)
+          else
+            root_seen = true
+            false
+          end
+        }, &)
+      end
+
+      def string_values(nodes)
+        nodes.map { |n| unwrap(n) }.grep(PgQuery::String).map(&:sval)
+      end
+    end
+
+    module MessageMethods
+      def unwrap = self
+
+      def walk(prune: nil, &) = Impl.walk(self, prune: prune, &)
+
+      def walk_scope(&) = Impl.walk_scope(self, &)
+
+      def each_child(&) = Impl.each_child(self, &)
+
+      def strip_casts = Impl.strip_casts(self)
+    end
+
+    message_classes = PgQuery.constants
+                             .map { |name| PgQuery.const_get(name) }
+                             .grep(Class)
+                             .select { |klass| klass < Google::Protobuf::MessageExts }
+
+    message_classes.each do |klass|
+      refine klass do
+        import_methods MessageMethods
+      end
+    end
+
+    refine PgQuery::Node do
+      def unwrap = Impl.unwrap(self)
+    end
+
+    refine PgQuery::ColumnRef do
+      def field_names
+        unwrapped = fields.map { |f| Impl.unwrap(f) }
+        return nil unless unwrapped.all?(PgQuery::String)
+
+        unwrapped.map(&:sval)
+      end
+    end
+
+    refine PgQuery::A_Expr do
+      def operator = Impl.string_values(name).last
+
+      def comparison? = kind == :AEXPR_OP && COMPARISON_OPS.include?(operator)
+    end
+
+    refine PgQuery::FuncCall do
+      def function_name = Impl.string_values(funcname).last&.downcase
+    end
+
+    refine PgQuery::A_Const do
+      def value
+        case val
+        when :ival then ival.ival
+        when :fval then fval.fval.to_f
+        when :sval then sval.sval
+        when :boolval then boolval.boolval
+        end
+      end
+    end
+
+    refine Google::Protobuf::RepeatedField do
+      def string_values = Impl.string_values(self)
+    end
+  end
+end