query_guard 0.4.2 → 0.5.1

data/lib/query_guard/analysis/query_risk_classifier.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Analysis
+    # Query risk classifier and aggregator.
+    # Orchestrates all risk detectors and produces findings.
+    class QueryRiskClassifier
+      def initialize(config)
+        @config = config
+        @detectors = [
+          SelectStarRiskDetector.new,
+          MissingIndexRiskDetector.new,
+          ComplexJoinRiskDetector.new,
+          SubqueryRiskDetector.new,
+          UnionRiskDetector.new,
+          AggregationRiskDetector.new
+        ]
+      end
+
+      # Analyze a single query for risks
+      # @param query [Core::Query]
+      # @return [Array<Hash>] Detected risks
+      def analyze_query(query)
+        risks = []
+        @detectors.each do |detector|
+          risks.concat(detector.detect(query, @config))
+        end
+        risks
+      end
+
+      # Analyze all queries in context for request-level risks (N+1, repeated queries)
+      # @param context [Core::Context]
+      # @return [Array<Hash>] Request-level risks
+      def analyze_context_risks(context)
+        risks = []
+
+        # Detect potentially repeated queries (same SQL pattern)
+        risks.concat(detect_repeated_queries(context))
+
+        # Detect potential N+1 pattern: many queries in sequence
+        risks.concat(detect_n_plus_one_pattern(context))
+
+        risks
+      end
+
+      private
+
+      def detect_repeated_queries(context)
+        risks = []
+        return risks if context.queries.length < 2
+
+        # Group queries by normalized SQL
+        query_groups = context.queries.group_by { |q| normalize_sql(q.sql) }
+
+        # Find SQL patterns executed multiple times
+        query_groups.each do |_normalized_sql, queries|
+          next if queries.length < 3
+
+          risks << {
+            pattern: :repeated_query,
+            risk_level: :medium,
+            message: "Query executed #{queries.length} times in single request; possible N+1 or missing eager load",
+            metadata: {
+              count: queries.length,
+              duration_total_ms: queries.sum(&:duration_ms),
+              recommendation: "Use eager loading (e.g., .includes) or batch queries",
+              impact: "Unnecessary query overhead"
+            }
+          }
+        end
+
+        risks
+      end
+
+      def detect_n_plus_one_pattern(context)
+        risks = []
+        return risks if context.queries.length < 5
+
+        # Simple heuristic: many SELECT FROM single table queries in sequence
+        select_queries = context.queries.select { |q| q.sql.match?(/^SELECT\b/i) }
+        return risks if select_queries.length < 5
+
+        # Heuristic: similar query patterns (likely same table)
+        patterns = select_queries.map { |q| extract_table_name(q.sql) }.compact.uniq
+        return risks if patterns.length < 2
+
+        # If we have many queries (5+) hitting few tables, likely N+1
+        select_count = select_queries.length
+        if select_count >= 5
+          avg_duration = context.total_duration_ms / context.queries.length
+          risks << {
+            pattern: :potential_n_plus_one,
+            risk_level: :high,
+            message: "Detected #{select_count} SELECT queries hitting ~#{patterns.length} table(s); likely N+1 query problem",
+            metadata: {
+              select_count: select_count,
+              table_count: patterns.length,
+              avg_query_ms: avg_duration.round(2),
+              recommendation: "Use eager loading (.includes, .joins) or batch queries",
+              impact: "Performance degradation with data scale"
+            }
+          }
+        end
+
+        risks
+      end
+
+      def normalize_sql(sql)
+        sql.upcase.gsub(/\d+/, "?").gsub(/\s+/, " ").strip
+      end
+
+      def extract_table_name(sql)
+        # Simple heuristic: first table after FROM
+        if sql.match?(/\bFROM\s+(\w+)/i)
+          sql.match(/\bFROM\s+(\w+)/i)[1].downcase
+        elsif sql.match?(/\bINTO\s+(\w+)/i)
+          sql.match(/\bINTO\s+(\w+)/i)[1].downcase
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/query_guard/analysis/risk_detectors.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Analysis
+    # Base class for query risk detectors.
+    # Detectors analyze specific SQL patterns and return risks.
+    class RiskDetector
+      attr_reader :name
+
+      def initialize(name)
+        @name = name.to_sym
+      end
+
+      # Analyze a query and return risks
+      # @param query [Core::Query] The query to analyze
+      # @param config [Config] Configuration with thresholds
+      # @return [Array<Hash>] List of detected risks with :pattern, :risk_level, :message, :metadata
+      def detect(query, config)
+        raise NotImplementedError, "#{self.class} must implement #detect"
+      end
+
+      protected
+
+      # Extract SQL normalized (uppercase, whitespace normalized)
+      def normalize_sql(sql)
+        sql.upcase.gsub(/\s+/, " ").strip
+      end
+
+      # Check if pattern matches (case-insensitive regex)
+      def matches_pattern?(sql, pattern)
+        pattern.match?(sql)
+      end
+    end
+
+    # Detects SELECT * usage patterns
+    class SelectStarRiskDetector < RiskDetector
+      SELECT_STAR_PATTERN = /\bSELECT\s+\*/i.freeze
+
+      def initialize
+        super(:select_star_risk)
+      end
+
+      def detect(query, config)
+        risks = []
+        return risks unless matches_pattern?(query.sql, SELECT_STAR_PATTERN)
+
+        risks << {
+          pattern: :select_star,
+          risk_level: :medium,
+          message: "SELECT * can fetch unnecessary columns, increasing bandwidth and reducing query efficiency",
+          metadata: {
+            recommendation: "Specify only required columns explicitly",
+            impact: "Unnecessary data transfer; harder schema evolution"
+          }
+        }
+
+        risks
+      end
+    end
+
+    # Detects missing table alias patterns (likely missing indexes)
+    class MissingIndexRiskDetector < RiskDetector
+      # Patterns that often indicate missing indexes
+      FULL_TABLE_SCAN_INDICATORS = [
+        /\bWHERE\b.*\b(?:LIKE|ILIKE|REGEXP)\b/i,  # LIKE on non-indexed column
+        /\bON\b.*\b(?:FUNCTION|CAST|COALESCE)\b/i  # Function in JOIN condition
+      ].freeze
+
+      def initialize
+        super(:missing_index_risk)
+      end
+
+      def detect(query, config)
+        risks = []
+        sql = query.sql
+
+        # Simple heuristic: LIKE without index hint
+        if matches_pattern?(sql, FULL_TABLE_SCAN_INDICATORS[0])
+          risks << {
+            pattern: :like_without_index,
+            risk_level: :high,
+            message: "LIKE pattern matching often requires full table scan; consider full-text search or indexed prefix matching",
+            metadata: {
+              recommendation: "Index column(s) or use full-text search",
+              impact: "Sequential scan on large tables"
+            }
+          }
+        end
+
+        # Function in JOIN condition
+        if matches_pattern?(sql, FULL_TABLE_SCAN_INDICATORS[1])
+          risks << {
+            pattern: :function_in_join,
+            risk_level: :high,
+            message: "Functions in JOIN conditions prevent index usage, causing sequential scans",
+            metadata: {
+              recommendation: "Move function outside JOIN condition",
+              impact: "Index cannot be used"
+            }
+          }
+        end
+
+        risks
+      end
+    end
+
+    # Detects patterns indicative of N+1 or repeated queries
+    class RepeatedQueryRiskDetector < RiskDetector
+      def initialize
+        super(:repeated_query_risk)
+      end
+
+      # Note: Can only detect within current request context
+      def detect(query, config)
+        risks = []
+        # Detected at request level by QueryRiskAnalyzer
+        # Return empty for now; actual detection happens in orchestrator
+        risks
+      end
+    end
+
+    # Detects complex join patterns
+    class ComplexJoinRiskDetector < RiskDetector
+      # 5+ tables is generally considered complex
+      COMPLEX_JOIN_TABLE_COUNT = 5
+
+      def initialize
+        super(:complex_join_risk)
+      end
+
+      def detect(query, config)
+        risks = []
+        sql = query.sql
+
+        # Count JOIN keywords (crude heuristic)
+        join_count = sql.scan(/\bJOIN\b/i).length
+        return risks if join_count < COMPLEX_JOIN_TABLE_COUNT
+
+        risks << {
+          pattern: :many_joins,
+          risk_level: :medium,
+          message: "Query with #{join_count + 1} tables; complex joins can be slow and hard to optimize",
+          metadata: {
+            table_count: join_count + 1,
+            recommendation: "Consider breaking into multiple queries or database view",
+            impact: "Performance degradation with scale"
+          }
+        }
+
+        risks
+      end
+    end
+
+    # Detects subquery patterns
+    class SubqueryRiskDetector < RiskDetector
+      SUBQUERY_PATTERN = /\(SELECT\b/i.freeze
+
+      def initialize
+        super(:subquery_risk)
+      end
+
+      def detect(query, config)
+        risks = []
+        return risks unless matches_pattern?(query.sql, SUBQUERY_PATTERN)
+
+        # Count subqueries
+        subquery_count = query.sql.scan(/\(SELECT\b/i).length
+        return risks if subquery_count.zero?
+
+        # Nested subqueries are more risky
+        risk_level = subquery_count > 2 ? :high : :medium
+
+        risks << {
+          pattern: :nested_subqueries,
+          risk_level: risk_level,
+          message: "Query contains #{subquery_count} subquery(ies); consider using JOINs or CTE for better performance",
+          metadata: {
+            subquery_count: subquery_count,
+            recommendation: "Replace with JOIN or WITH clause",
+            impact: "Multiple table scans"
+          }
+        }
+
+        risks
+      end
+    end
+
+    # Detects UNION queries (can be slower than OR)
+    class UnionRiskDetector < RiskDetector
+      UNION_PATTERN = /\bUNION\b/i.freeze
+
+      def initialize
+        super(:union_risk)
+      end
+
+      def detect(query, config)
+        risks = []
+        return risks unless matches_pattern?(query.sql, UNION_PATTERN)
+
+        # UNION ALL is better than UNION (no sorting)
+        has_union_all = query.sql.match?(/\bUNION\s+ALL\b/i)
+
+        risks << {
+          pattern: :union_query,
+          risk_level: has_union_all ? :low : :medium,
+          message: "UNION #{'ALL' if has_union_all} query; consider OR clause or application-level merging",
+          metadata: {
+            has_union_all: has_union_all,
+            recommendation: has_union_all ? "Consider OR instead" : "Use UNION ALL instead of UNION",
+            impact: "Sorting overhead if UNION (not ALL)"
+          }
+        }
+
+        risks
+      end
+    end
+
+    # Detects GROUP BY / DISTINCT patterns
+    class AggregationRiskDetector < RiskDetector
+      def initialize
+        super(:aggregation_risk)
+      end
+
+      def detect(query, config)
+        risks = []
+        sql = query.sql
+
+        # DISTINCT on large columns
+        if query.sql.match?(/\bSELECT\s+DISTINCT\b/i)
+          risks << {
+            pattern: :distinct_usage,
+            risk_level: :low,
+            message: "DISTINCT forces sorting; ensure needed and indexed properly",
+            metadata: {
+              recommendation: "Verify uniqueness constraint or consider GROUP BY",
+              impact: "Sorting overhead"
+            }
+          }
+        end
+
+        # GROUP BY without ORDER BY (random order)
+        if sql.match?(/\bGROUP\s+BY\b/i) && !sql.match?(/\bORDER\s+BY\b/i)
+          risks << {
+            pattern: :group_by_unordered,
+            risk_level: :low,
+            message: "GROUP BY without ORDER BY returns results in random order; add ORDER BY if order matters",
+            metadata: {
+              recommendation: "Add ORDER BY if result order is important",
+              impact: "Unpredictable result ordering"
+            }
+          }
+        end
+
+        risks
+      end
+    end
+  end
+end

data/lib/query_guard/analysis/risk_level.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Analysis
+    # Risk severity levels for query analysis
+    # Used to classify and report on query risks
+    class RiskLevel
+      LEVELS = {
+        low: 1,
+        medium: 2,
+        high: 3,
+        critical: 4
+      }.freeze
+
+      SEVERITY_MAP = {
+        low: :info,
+        medium: :warn,
+        high: :error,
+        critical: :error
+      }.freeze
+
+      def self.valid?(level)
+        LEVELS.key?(level.to_sym)
+      end
+
+      def self.to_severity(level)
+        SEVERITY_MAP[level.to_sym] || :warn
+      end
+
+      def self.compare(level1, level2)
+        LEVELS[level1.to_sym] <=> LEVELS[level2.to_sym]
+      end
+    end
+  end
+end

data/lib/query_guard/analyzers/base.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Analyzers
+    # Base class for all rule-based analyzers.
+    # Subclasses implement `analyze(context, config)` to produce findings.
+    class Base
+      attr_reader :name
+
+      def initialize(name)
+        @name = name.to_sym
+      end
+
+      # Analyze the context and produce findings.
+      # Must return an array of Finding objects.
+      #
+      # @param context [Core::Context] Contains queries and metadata
+      # @param config [Config] Configuration object
+      # @return [Array<Core::Finding>] List of findings
+      def analyze(context, config)
+        raise NotImplementedError, "#{self.class} must implement #analyze"
+      end
+
+      # Enabled check - allows per-analyzer enable/disable
+      def enabled?(config)
+        !config.disabled_analyzers&.include?(name)
+      end
+    end
+  end
+end

data/lib/query_guard/analyzers/query_count_analyzer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Analyzers
+    # Detects when query count per request exceeds threshold.
+    class QueryCountAnalyzer < Base
+      def initialize
+        super(:query_count)
+      end
+
+      def analyze(context, config)
+        findings = []
+        limit = config.max_queries_per_request
+
+        return findings if limit.nil?
+
+        count = context.queries.length
+        return findings unless count > limit
+
+        findings << Core::FindingBuilders.too_many_queries(
+          count: count,
+          limit: limit,
+          total_duration_ms: context.total_duration_ms,
+          severity: config.query_count_severity || :warn
+        )
+
+        findings
+      end
+    end
+  end
+end

data/lib/query_guard/analyzers/query_risk_analyzer.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Analyzers
+    # Analyzes queries for performance and safety risks.
+    # Evaluates SQL patterns, missing indexes, N+1 patterns, and other risks.
+    # Optionally enriches findings with EXPLAIN plan analysis (PostgreSQL).
+    class QueryRiskAnalyzer < Base
+      def initialize
+        super(:query_risk)
+      end
+
+      def analyze(context, config)
+        findings = []
+        # Only analyze if enabled
+        return findings unless config.analyze_query_risks
+
+        classifier = Analysis::QueryRiskClassifier.new(config)
+
+        # Analyze each query individually
+        context.queries.each do |query|
+          risks = classifier.analyze_query(query)
+          query_findings = risks_to_findings(risks, query, config)
+
+          # Enrich with EXPLAIN analysis if enabled
+          if config.use_explain_plans && config.explain_enricher
+            query_findings = config.explain_enricher.enrich(query_findings, query, context)
+          end
+
+          findings.concat(query_findings)
+        end
+
+        # Analyze request-level patterns (N+1, repeated queries)
+        context_risks = classifier.analyze_context_risks(context)
+        findings.concat(context_risks_to_findings(context_risks, config))
+
+        findings
+      end
+
+      private
+
+      def risks_to_findings(risks, query, config)
+        findings = []
+
+        risks.each do |risk|
+          severity = Analysis::RiskLevel.to_severity(risk[:risk_level])
+
+          finding = Core::FindingBuilders.build(
+            analyzer_name: name,
+            rule_name: risk[:pattern],
+            severity: severity,
+            title: risk_title(risk[:pattern]),
+            description: risk_description(risk[:pattern]),
+            message: risk[:message],
+            sql: query.sql,
+            metadata: risk[:metadata],
+            recommendations: [risk[:metadata][:recommendation]],
+            query: query
+          )
+
+          findings << finding
+        end
+
+        findings
+      end
+
+      def context_risks_to_findings(risks, config)
+        findings = []
+
+        risks.each do |risk|
+          severity = Analysis::RiskLevel.to_severity(risk[:risk_level])
+
+          finding = Core::FindingBuilders.build(
+            analyzer_name: name,
+            rule_name: risk[:pattern],
+            severity: severity,
+            title: risk_title(risk[:pattern]),
+            description: risk_description(risk[:pattern]),
+            message: risk[:message],
+            metadata: risk[:metadata],
+            recommendations: [risk[:metadata][:recommendation]]
+          )
+
+          findings << finding
+        end
+
+        findings
+      end
+
+      def risk_title(pattern)
+        case pattern
+        when :select_star
+          "SELECT * Usage"
+        when :like_without_index
+          "LIKE Without Index"
+        when :function_in_join
+          "Function in JOIN Condition"
+        when :many_joins
+          "Complex Multi-Table Join"
+        when :nested_subqueries
+          "Nested Subqueries"
+        when :union_query
+          "UNION Query"
+        when :distinct_usage
+          "DISTINCT Clause"
+        when :group_by_unordered
+          "GROUP BY Without ORDER BY"
+        when :repeated_query
+          "Repeated Query in Request"
+        when :potential_n_plus_one
+          "Potential N+1 Query Problem"
+        else
+          pattern.to_s.titleize
+        end
+      end
+
+      def risk_description(pattern)
+        case pattern
+        when :select_star
+          "Selecting all columns can fetch unnecessary data and reduce efficiency."
+        when :like_without_index
+          "LIKE pattern matching typically requires full table scans."
+        when :function_in_join
+          "Functions in JOIN conditions prevent index usage."
+        when :many_joins
+          "Queries joining many tables are complex and difficult to optimize."
+        when :nested_subqueries
+          "Nested subqueries can cause multiple table scans."
+        when :union_query
+          "UNION requires sorting; UNION ALL is often faster."
+        when :distinct_usage
+          "DISTINCT forces sorting and can be expensive."
+        when :group_by_unordered
+          "GROUP BY without ORDER BY returns results in unpredictable order."
+        when :repeated_query
+          "Same query executed multiple times suggests missing eager loading."
+        when :potential_n_plus_one
+          "Many sequential queries in a single request indicates an N+1 problem."
+        else
+          pattern.to_s.titleize
+        end
+      end
+    end
+  end
+end
+

data/lib/query_guard/analyzers/registry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Analyzers
+    # Registry for managing analyzer instances.
+    # Provides global registration and per-request analysis coordination.
+    class Registry
+      def initialize
+        @analyzers = {}
+      end
+
+      # Register an analyzer instance
+      # @param name [Symbol] Unique identifier for the analyzer
+      # @param analyzer [Base] Analyzer instance
+      def register(name, analyzer)
+        raise ArgumentError, "Analyzer must inherit from Base" unless analyzer.is_a?(Base)
+        @analyzers[name.to_sym] = analyzer
+      end
+
+      # Retrieve analyzer by name
+      # @param name [Symbol] Analyzer name
+      # @return [Base, nil] Analyzer instance or nil if not found
+      def get(name)
+        @analyzers[name.to_sym]
+      end
+
+      # Check if analyzer is registered
+      def registered?(name)
+        @analyzers.key?(name.to_sym)
+      end
+
+      # Get all registered analyzers
+      # @return [Hash{Symbol => Base}]
+      def all
+        @analyzers.dup
+      end
+
+      # Run all enabled analyzers against the context
+      # @param context [Core::Context] Request context
+      # @param config [Config] Configuration
+      # @return [Array<Core::Finding>] Combined findings from all analyzers
+      def analyze(context, config)
+        findings = []
+        @analyzers.each do |name, analyzer|
+          next unless analyzer.enabled?(config)
+          findings.concat(analyzer.analyze(context, config))
+        end
+        findings
+      end
+
+      # Clear all registered analyzers
+      def clear
+        @analyzers.clear
+      end
+    end
+  end
+end