pg_canary 0.2.0 → 0.3.0

data/lib/pg_canary/rules/definitions/not_in_subquery.rb

@@ -6,23 +6,23 @@ module PgCanary
     # NULL the whole predicate yields no rows, and the planner cannot use an
     # anti-join as effectively as with NOT EXISTS.
     class NotInSubquery < Base
-      def default_enabled
-        true
-      end
+      default_enabled true
+
+      using PgCanary::PgQueryRefinement
 
-      def check(query)
+      def check
         detections = []
-        query.each_scope do |scope|
+        each_scope do |scope|
           next unless scope.where_clause
 
-          walk_within_scope(scope.where_clause) do |node|
+          scope.where_clause.walk_scope do |node|
             next unless not_expr?(node)
 
             node.args.each do |arg|
-              sublink = unwrap_node(arg)
+              sublink = arg.unwrap
               next unless any_sublink?(sublink)
 
-              detections << build(query, scope, sublink)
+              detections << build(scope, sublink)
             end
           end
         end
@@ -31,35 +31,34 @@ module PgCanary
 
       private
 
-      def not_expr?(node)
-        node.is_a?(PgQuery::BoolExpr) && node.boolop == :NOT_EXPR
-      end
+        def not_expr?(node)
+          node.is_a?(PgQuery::BoolExpr) && node.boolop == :NOT_EXPR
+        end
 
-      # x NOT IN (SELECT ...) parses as NOT(SubLink ANY, "=" test).
-      def any_sublink?(node)
-        return false unless node.is_a?(PgQuery::SubLink)
-        return false unless node.sub_link_type == :ANY_SUBLINK
+        # x NOT IN (SELECT ...) parses as NOT(SubLink ANY, "=" test).
+        def any_sublink?(node)
+          return false unless node.is_a?(PgQuery::SubLink)
+          return false unless node.sub_link_type == :ANY_SUBLINK
 
-        operator = string_values(node.oper_name).last
-        operator.nil? || operator == "="
-      end
+          operator = node.oper_name.string_values.last
+          operator.nil? || operator == "="
+        end
 
-      def build(query, scope, sublink)
-        test = strip_type_casts(sublink.testexpr)
-        table, column = test.is_a?(PgQuery::ColumnRef) ? scope.resolve(test) : nil
+        def build(scope, sublink)
+          test = sublink.testexpr&.strip_casts
+          table, column = test.is_a?(PgQuery::ColumnRef) ? scope.resolve(test) : nil
 
-        detection(
-          query,
-          table: table,
-          columns: column,
-          message: "NOT IN (SELECT ...) returns zero rows if the subquery yields even one NULL, " \
-                   "and the planner optimizes it poorly compared to an anti-join — a classic slow query.",
-          suggestion: <<~SUGGESTION.chomp
-            Consider rewriting to NOT EXISTS:
-              SELECT ... FROM t WHERE NOT EXISTS (SELECT 1 FROM sub WHERE sub.ref_id = t.id)
-          SUGGESTION
-        )
-      end
+          detection(
+            table: table,
+            columns: column,
+            message: "NOT IN (SELECT ...) returns zero rows if the subquery yields even one NULL, " \
+                     "and the planner optimizes it poorly compared to an anti-join — a classic slow query.",
+            suggestion: <<~SUGGESTION.chomp
+              Consider rewriting to NOT EXISTS:
+                SELECT ... FROM t WHERE NOT EXISTS (SELECT 1 FROM sub WHERE sub.ref_id = t.id)
+            SUGGESTION
+          )
+        end
     end
   end
 end

data/lib/pg_canary/rules/definitions/or_across_columns.rb

@@ -2,29 +2,29 @@
 
 module PgCanary
   module Rules
-    # Tier 2 (opt-in): OR conditions spanning different columns. PostgreSQL
+    # OR conditions spanning different columns. PostgreSQL
     # can sometimes combine per-column indexes with a BitmapOr, so this is a
     # warning-level hint rather than a certainty.
     class OrAcrossColumns < Base
-      def default_enabled
-        false
-      end
+      default_enabled false
+
+      using PgCanary::PgQueryRefinement
 
-      def check(query)
+      def check
         detections = []
-        query.each_scope do |scope|
+        each_scope do |scope|
           next unless scope.where_clause
 
           seen = []
-          walk_within_scope(scope.where_clause) do |node|
+          scope.where_clause.walk_scope do |node|
             next unless node.is_a?(PgQuery::BoolExpr) && node.boolop == :OR_EXPR
 
-            columns = predicate_columns(query, scope, node)
+            columns = predicate_columns(scope, node)
             next if columns.length < 2
             next if seen.include?(columns)
 
             seen << columns
-            detections << build(query, columns)
+            detections << build(columns)
           end
         end
         detections
@@ -32,34 +32,33 @@ module PgCanary
 
       private
 
-      # Distinct (table, column) pairs among the OR branches' simple
-      # column-vs-constant predicates.
-      def predicate_columns(query, scope, bool_expr)
-        columns = bool_expr.args.filter_map do |arg|
-          expr = unwrap_node(arg)
-          next nil unless expr.is_a?(PgQuery::A_Expr)
-          next nil unless comparison_expr?(expr) || %i[AEXPR_IN AEXPR_LIKE AEXPR_ILIKE].include?(expr.kind)
+        # Distinct (table, column) pairs among the OR branches' simple
+        # column-vs-constant predicates.
+        def predicate_columns(scope, bool_expr)
+          columns = bool_expr.args.filter_map do |arg|
+            expr = arg.unwrap
+            next nil unless expr.is_a?(PgQuery::A_Expr)
+            next nil unless expr.comparison? || %i[AEXPR_IN AEXPR_LIKE AEXPR_ILIKE].include?(expr.kind)
 
-          column_ref = strip_type_casts(expr.lexpr)
-          next nil unless column_ref.is_a?(PgQuery::ColumnRef)
+            column_ref = expr.lexpr&.strip_casts
+            next nil unless column_ref.is_a?(PgQuery::ColumnRef)
 
-          resolved = scope.resolve(column_ref)
-          resolved if resolved && applicable_table?(query, resolved.first)
+            resolved = scope.resolve(column_ref)
+            resolved if resolved && applicable_table?(resolved.first)
+          end
+          columns.uniq.sort
         end
-        columns.uniq.sort
-      end
 
-      def build(query, columns)
-        column_list = columns.map { |table, column| "#{table}.#{column}" }.join(", ")
-        detection(
-          query,
-          table: columns.first.first,
-          columns: columns.map(&:last),
-          message: "OR across different columns (#{column_list}) often prevents a single index scan.",
-          suggestion: "Ensure each column has its own index (PostgreSQL can then BitmapOr them), " \
-                      "or split the query into a UNION of two indexed queries."
-        )
-      end
+        def build(columns)
+          column_list = columns.map { |table, column| "#{table}.#{column}" }.join(", ")
+          detection(
+            table: columns.first.first,
+            columns: columns.map(&:last),
+            message: "OR across different columns (#{column_list}) often prevents a single index scan.",
+            suggestion: "Ensure each column has its own index (PostgreSQL can then BitmapOr them), " \
+                        "or split the query into a UNION of two indexed queries."
+          )
+        end
     end
   end
 end

data/lib/pg_canary/rules/definitions/order_by_random.rb

@@ -5,20 +5,19 @@ module PgCanary
     # ORDER BY RANDOM() sorts the entire result set just to pick rows —
     # always suspicious regardless of table size.
     class OrderByRandom < Base
-      def default_enabled
-        true
-      end
+      default_enabled true
+
+      using PgCanary::PgQueryRefinement
 
-      def check(query)
+      def check
         detections = []
-        query.each_scope do |scope|
+        each_scope do |scope|
           scope.sort_items.each do |sort_by|
-            func = unwrap_node(sort_by.node)
+            func = sort_by.node&.unwrap
             next unless func.is_a?(PgQuery::FuncCall)
-            next unless function_name(func) == "random"
+            next unless func.function_name == "random"
 
             detections << detection(
-              query,
               table: scope.tables.length == 1 ? scope.tables.first : nil,
               message: "ORDER BY RANDOM() reads and sorts every row, so it gets slower " \
                        "in proportion to table size.",

data/lib/pg_canary/rules/definitions/query_complexity.rb

@@ -2,23 +2,21 @@
 
 module PgCanary
   module Rules
-    # Tier 2 (opt-in): "spaghetti query" guard — too many joins or too much
+    # "spaghetti query" guard — too many joins or too much
     # subquery nesting. Thresholds:
     #   config.rules.query_complexity.max_joins (default 8)
     #   config.rules.query_complexity.max_depth (default 4)
     class QueryComplexity < Base
-      def default_enabled
-        false
-      end
+      default_enabled false
+      option :max_joins, default: 8
+      option :max_depth, default: 4
 
-      def self.options
-        { max_joins: 8, max_depth: 4 }
-      end
+      using PgCanary::PgQueryRefinement
 
-      def check(query)
-        max_joins = rule_config(query).max_joins
-        max_depth = rule_config(query).max_depth
-        stmt = query.parse_result.tree.stmts.first&.stmt
+      def check
+        max_joins = rule_config.max_joins
+        max_depth = rule_config.max_depth
+        stmt = parse_result.tree.stmts.first&.stmt
         return [] unless stmt
 
         problems = []
@@ -29,7 +27,6 @@ module PgCanary
         return [] if problems.empty?
 
         [detection(
-          query,
           message: "Query complexity exceeds thresholds: #{problems.join(", ")}.",
           suggestion: "Consider splitting the query, precomputing intermediate results, " \
                       "or reviewing whether every join/subquery is necessary."
@@ -38,24 +35,24 @@ module PgCanary
 
       private
 
-      def count_joins(stmt)
-        joins = 0
-        walk_ast(stmt) { |node| joins += 1 if node.is_a?(PgQuery::JoinExpr) }
-        joins
-      end
-
-      # Maximum nesting depth of SELECT statements (a flat query is 1).
-      def max_select_depth(node)
-        node = unwrap_node(node)
-        return 0 unless node.is_a?(Google::Protobuf::MessageExts)
+        def count_joins(stmt)
+          joins = 0
+          stmt.walk { |node| joins += 1 if node.is_a?(PgQuery::JoinExpr) }
+          joins
+        end
 
-        deepest_child = 0
-        each_ast_child(node) do |child|
-          depth = max_select_depth(child)
-          deepest_child = depth if depth > deepest_child
+        # Maximum nesting depth of SELECT statements (a flat query is 1).
+        def max_select_depth(node)
+          node = node.unwrap
+          return 0 unless node.is_a?(Google::Protobuf::MessageExts)
+
+          deepest_child = 0
+          node.each_child do |child|
+            depth = max_select_depth(child)
+            deepest_child = depth if depth > deepest_child
+          end
+          (node.is_a?(PgQuery::SelectStmt) ? 1 : 0) + deepest_child
         end
-        (node.is_a?(PgQuery::SelectStmt) ? 1 : 0) + deepest_child
-      end
     end
   end
 end

data/lib/pg_canary/rules/definitions/regex_without_trgm.rb

@@ -6,35 +6,34 @@ module PgCanary
     # index; only a pg_trgm GIN/GiST index can serve it. The regex variant of
     # leading_wildcard_like.
     class RegexWithoutTrgm < Base
+      default_enabled true
+
       include IndexPredicates
 
-      def default_enabled
-        true
-      end
+      using PgCanary::PgQueryRefinement
 
       REGEX_OPS = %w[~ ~* !~ !~*].freeze
 
-      def check(query)
+      def check
         detections = []
-        query.each_scope do |scope|
+        each_scope do |scope|
           next unless scope.where_clause
 
-          walk_within_scope(scope.where_clause) do |node|
+          scope.where_clause.walk_scope do |node|
             next unless node.is_a?(PgQuery::A_Expr)
 
             operator = display_operator(node)
             next unless operator
 
-            column_ref = strip_type_casts(node.lexpr)
+            column_ref = node.lexpr&.strip_casts
             next unless column_ref.is_a?(PgQuery::ColumnRef)
 
             table, column = scope.resolve(column_ref)
             next unless table && column
-            next unless applicable_table?(query, table)
-            next if trgm_index?(query, table, column)
+            next unless applicable_table?(table)
+            next if trgm_index?(table, column)
 
             detections << detection(
-              query,
               table: table,
               columns: column,
               message: "Regular-expression search (#{operator}) on #{table}.#{column} cannot use " \
@@ -52,15 +51,15 @@ module PgCanary
 
       private
 
-      def display_operator(a_expr)
-        case a_expr.kind
-        when :AEXPR_OP
-          operator = operator_name(a_expr)
-          REGEX_OPS.include?(operator) ? operator : nil
-        when :AEXPR_SIMILAR
-          "SIMILAR TO"
+        def display_operator(a_expr)
+          case a_expr.kind
+          when :AEXPR_OP
+            operator = a_expr.operator
+            REGEX_OPS.include?(operator) ? operator : nil
+          when :AEXPR_SIMILAR
+            "SIMILAR TO"
+          end
         end
-      end
     end
   end
 end

data/lib/pg_canary/rules/definitions/select_star_with_heavy_columns.rb

@@ -2,31 +2,27 @@
 
 module PgCanary
   module Rules
-    # Tier 2 (opt-in): SELECT * (ActiveRecord's default) on a table that has
+    # SELECT * (ActiveRecord's default) on a table that has
     # heavy columns (bytea / text / jsonb) transfers those payloads on every
     # query. Whether that matters depends on the data, hence opt-in.
     # Heavy types: config.rules.select_star_with_heavy_columns.heavy_types.
     class SelectStarWithHeavyColumns < Base
-      def default_enabled
-        false
-      end
+      default_enabled false
+      option :heavy_types, default: %w[bytea jsonb text].freeze
 
-      def self.options
-        { heavy_types: %w[bytea jsonb text].freeze }
-      end
+      using PgCanary::PgQueryRefinement
 
-      def check(query)
-        heavy_types = rule_config(query).heavy_types
+      def check
+        heavy_types = rule_config.heavy_types
         detections = []
-        query.each_scope do |scope|
+        each_scope do |scope|
           star_tables(scope).each do |table|
-            next unless applicable_table?(query, table)
+            next unless applicable_table?(table)
 
-            heavy = query.column_types(table).select { |_, type| heavy_types.include?(type) }.keys
+            heavy = column_types(table).select { |_, type| heavy_types.include?(type) }.keys
             next if heavy.empty?
 
             detections << detection(
-              query,
               table: table,
               columns: heavy,
               message: "SELECT * on #{table} transfers its heavy columns (#{heavy.join(", ")}) " \
@@ -41,29 +37,29 @@ module PgCanary
 
       private
 
-      # Tables whose rows are fetched with a star target (t.* or bare *).
-      def star_tables(scope)
-        tables = []
-        scope.stmt.target_list.each do |target|
-          res_target = unwrap_node(target)
-          next unless res_target.is_a?(PgQuery::ResTarget)
+        # Tables whose rows are fetched with a star target (t.* or bare *).
+        def star_tables(scope)
+          tables = []
+          scope.stmt.target_list.each do |target|
+            res_target = target.unwrap
+            next unless res_target.is_a?(PgQuery::ResTarget)
 
-          column_ref = unwrap_node(res_target.val)
-          next unless column_ref.is_a?(PgQuery::ColumnRef)
+            column_ref = res_target.val&.unwrap
+            next unless column_ref.is_a?(PgQuery::ColumnRef)
 
-          fields = column_ref.fields.map { |f| unwrap_node(f) }
-          next unless fields.last.is_a?(PgQuery::A_Star)
+            fields = column_ref.fields.map(&:unwrap)
+            next unless fields.last.is_a?(PgQuery::A_Star)
 
-          qualifier = fields[-2]
-          if qualifier.is_a?(PgQuery::String)
-            table = scope.aliases[qualifier.sval]
-            tables << table if table
-          else
-            tables.concat(scope.tables)
+            qualifier = fields[-2]
+            if qualifier.is_a?(PgQuery::String)
+              table = scope.aliases[qualifier.sval]
+              tables << table if table
+            else
+              tables.concat(scope.tables)
+            end
           end
+          tables.uniq
         end
-        tables.uniq
-      end
     end
   end
 end

data/lib/pg_canary/rules/definitions/unindexed_join.rb

@@ -2,25 +2,24 @@
 
 module PgCanary
   module Rules
-    # Tier 2 (opt-in): join-condition columns with no index leading with
+    # join-condition columns with no index leading with
     # them. Unlike active_record_doctor's static association check, this
     # looks at joins that actually ran, so raw-SQL joins are covered too.
     class UnindexedJoin < Base
+      default_enabled false
+
       include IndexPredicates
 
-      def default_enabled
-        false
-      end
+      using PgCanary::PgQueryRefinement
 
-      def check(query)
+      def check
         detections = []
-        query.each_scope do |scope|
+        each_scope do |scope|
           join_columns(scope).each do |table, column|
-            next unless applicable_table?(query, table)
-            next if index_leading_with?(query, table, column)
+            next unless applicable_table?(table)
+            next if index_leading_with?(table, column)
 
             detections << detection(
-              query,
               table: table,
               columns: column,
               message: "Join condition on #{table}.#{column} has no index leading with it — " \
@@ -37,45 +36,45 @@ module PgCanary
 
       private
 
-      # Unique [table, column] pairs appearing in cross-table equality
-      # conditions (JOIN ... ON and comma joins connected in WHERE).
-      def join_columns(scope)
-        columns = []
-        scope.stmt.from_clause.each do |item|
-          collect_join_quals(unwrap_node(item)) do |quals|
-            columns.concat(equality_columns(scope, quals))
+        # Unique [table, column] pairs appearing in cross-table equality
+        # conditions (JOIN ... ON and comma joins connected in WHERE).
+        def join_columns(scope)
+          columns = []
+          scope.stmt.from_clause.each do |item|
+            collect_join_quals(item.unwrap) do |quals|
+              columns.concat(equality_columns(scope, quals))
+            end
           end
+          columns.concat(equality_columns(scope, scope.where_clause)) if scope.where_clause
+          columns.uniq
         end
-        columns.concat(equality_columns(scope, scope.where_clause)) if scope.where_clause
-        columns.uniq
-      end
 
-      def collect_join_quals(node, &)
-        return unless node.is_a?(PgQuery::JoinExpr)
+        def collect_join_quals(node, &)
+          return unless node.is_a?(PgQuery::JoinExpr)
 
-        yield node.quals if node.quals
-        collect_join_quals(unwrap_node(node.larg), &)
-        collect_join_quals(unwrap_node(node.rarg), &)
-      end
+          yield node.quals if node.quals
+          collect_join_quals(node.larg&.unwrap, &)
+          collect_join_quals(node.rarg&.unwrap, &)
+        end
 
-      def equality_columns(scope, clause)
-        columns = []
-        walk_within_scope(clause) do |node|
-          next unless node.is_a?(PgQuery::A_Expr) && node.kind == :AEXPR_OP && operator_name(node) == "="
+        def equality_columns(scope, clause)
+          columns = []
+          clause.walk_scope do |node|
+            next unless node.is_a?(PgQuery::A_Expr) && node.kind == :AEXPR_OP && node.operator == "="
 
-          left = unwrap_node(node.lexpr)
-          right = unwrap_node(node.rexpr)
-          next unless left.is_a?(PgQuery::ColumnRef) && right.is_a?(PgQuery::ColumnRef)
+            left = node.lexpr&.unwrap
+            right = node.rexpr&.unwrap
+            next unless left.is_a?(PgQuery::ColumnRef) && right.is_a?(PgQuery::ColumnRef)
 
-          left_resolved = scope.resolve(left)
-          right_resolved = scope.resolve(right)
-          next unless left_resolved && right_resolved
-          next if left_resolved.first == right_resolved.first # same table: not a join condition
+            left_resolved = scope.resolve(left)
+            right_resolved = scope.resolve(right)
+            next unless left_resolved && right_resolved
+            next if left_resolved.first == right_resolved.first # same table: not a join condition
 
-          columns << left_resolved << right_resolved
+            columns << left_resolved << right_resolved
+          end
+          columns
         end
-        columns
-      end
     end
   end
 end

data/lib/pg_canary/rules/definitions/unindexed_order_by_with_limit.rb

@@ -2,34 +2,33 @@
 
 module PgCanary
   module Rules
-    # Tier 2 (opt-in): ORDER BY x LIMIT n without an index led by x forces a
+    # ORDER BY x LIMIT n without an index led by x forces a
     # full sort before the limit can apply. Size-dependent, so disabled by
     # default.
     class UnindexedOrderByWithLimit < Base
+      default_enabled false
+
       include IndexPredicates
 
-      def default_enabled
-        false
-      end
+      using PgCanary::PgQueryRefinement
 
-      def check(query)
+      def check
         detections = []
-        query.each_scope do |scope|
+        each_scope do |scope|
           next unless scope.limited?
 
           sort_by = scope.sort_items.first
           next unless sort_by
 
-          column_ref = unwrap_node(sort_by.node)
+          column_ref = sort_by.node&.unwrap
           next unless column_ref.is_a?(PgQuery::ColumnRef)
 
           table, column = scope.resolve(column_ref)
           next unless table && column
-          next unless applicable_table?(query, table)
-          next if index_leading_with?(query, table, column)
+          next unless applicable_table?(table)
+          next if index_leading_with?(table, column)
 
           detections << detection(
-            query,
             table: table,
             columns: column,
             message: "ORDER BY #{column} LIMIT sorts every row before the limit can apply " \