query_guard 0.4.2 → 0.5.1

data/lib/query_guard/core/context.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Core
+    # Holds the state of a single request or analysis session.
+    # Replaces implicit Thread.current usage for better testability and clarity.
+    class Context
+      attr_reader :queries, :findings
+
+      def initialize
+        @queries = []
+        @findings = []
+      end
+
+      # Add a captured query to the context
+      def add_query(sql:, duration_ms:, name: nil, started_at: nil, finished_at: nil)
+        query = Query.new(
+          sql: sql,
+          duration_ms: duration_ms,
+          name: name,
+          started_at: started_at,
+          finished_at: finished_at
+        )
+        @queries << query
+        query
+      end
+
+      # Add a finding to the context
+      def add_finding(finding)
+        raise ArgumentError, "Must be a Finding" unless finding.is_a?(Finding)
+        @findings << finding
+      end
+
+      # Convenience: create and add a finding
+      def create_finding(analyzer_name:, rule_name:, severity: :warn, message:, metadata: {}, query: nil)
+        finding = Finding.new(
+          analyzer_name: analyzer_name,
+          rule_name: rule_name,
+          severity: severity,
+          message: message,
+          metadata: metadata,
+          query: query
+        )
+        add_finding(finding)
+        finding
+      end
+
+      # Query counts for easy checking
+      def query_count
+        @queries.length
+      end
+
+      def total_duration_ms
+        @queries.sum { |q| q.duration_ms }
+      end
+
+      # Finding counts
+      def finding_count
+        @findings.length
+      end
+
+      def findings_by_severity(severity)
+        @findings.select { |f| f.severity == severity.to_sym }
+      end
+
+      def clear
+        @queries.clear
+        @findings.clear
+      end
+
+      def to_h
+        {
+          query_count: query_count,
+          total_duration_ms: total_duration_ms,
+          findings: findings.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/lib/query_guard/core/finding.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Core
+    # Immutable result of a rule analysis.
+    # Represents a single violation or finding detected by an analyzer.
+    #
+    # A Finding encapsulates all information about a detected issue:
+    # - What rule triggered (analyzer_name, rule_name)
+    # - How severe it is (severity)
+    # - Where it occurred (file_path, line_number, sql)
+    # - Why it matters (title, description, recommendations)
+    # - Context data (metadata)
+    class Finding
+      SEVERITIES = %i[info warn error].freeze
+
+      # Core identification
+      attr_reader :analyzer_name, :rule_name, :severity
+
+      # Message and description (user-facing)
+      attr_reader :title, :description, :message, :recommendations
+
+      # Location information
+      attr_reader :file_path, :line_number, :sql
+
+      # Additional context
+      attr_reader :metadata, :query, :created_at
+
+      # Internal ID for tracking/deduplication
+      attr_reader :id
+
+      def initialize(
+        analyzer_name:,
+        rule_name:,
+        severity: :warn,
+        title: nil,
+        description: nil,
+        message: nil,
+        file_path: nil,
+        line_number: nil,
+        sql: nil,
+        metadata: {},
+        query: nil,
+        recommendations: []
+      )
+        @analyzer_name = analyzer_name.to_sym
+        @rule_name = rule_name.to_sym
+        @severity = validate_severity(severity)
+
+        # Message handling: use title/description or fall back to message
+        @title = title.to_s.freeze if title
+        @description = description.to_s.freeze if description
+        @message = (message || @title || "").to_s.freeze
+
+        # Location info
+        @file_path = file_path.to_s.freeze if file_path
+        @line_number = line_number.to_i if line_number
+        @sql = sql.to_s.freeze if sql
+
+        # Recommendations
+        @recommendations = Array(recommendations).map { |r| r.to_s.freeze }.freeze
+
+        # Metadata
+        @metadata = metadata.freeze
+        @query = query
+        @created_at = Time.now.freeze
+
+        # Generate deterministic ID based on analyzer, rule, and sql for deduplication
+        @id = generate_id
+      end
+
+      # Compare findings by key attributes
+      def ==(other)
+        other.is_a?(Finding) &&
+          analyzer_name == other.analyzer_name &&
+          rule_name == other.rule_name &&
+          severity == other.severity &&
+          message == other.message
+      end
+
+      # Hash based on ID for Set operations
+      def hash
+        id.hash
+      end
+
+      alias eql? ==
+
+      # Serialize to hash for reporting/API
+      # Useful for JSON output, CI integration, and telemetry
+      def to_h
+        {
+          id: id,
+          analyzer: analyzer_name,
+          rule: rule_name,
+          severity: severity,
+          title: title,
+          description: description,
+          message: message,
+          file_path: file_path,
+          line_number: line_number,
+          sql: sql,
+          metadata: metadata,
+          recommendations: recommendations,
+          created_at: created_at&.iso8601,
+          query: query&.to_h
+        }.compact
+      end
+
+      # Serialize to JSON-friendly hash (excludes large/binary data)
+      def to_json_h
+        h = to_h
+        # Optionally truncate SQL for JSON payloads
+        h[:sql] = truncate_sql(h[:sql], 500) if h[:sql]
+        h.except(:query) # Exclude full query object from JSON
+      end
+
+      # Human-readable string for logs
+      def to_s
+        "[#{severity.upcase}] #{analyzer_name}:#{rule_name} - #{message}"
+      end
+
+      # Detailed log format
+      def to_log_s
+        parts = [to_s]
+        parts << "File: #{file_path}:#{line_number}" if file_path
+        parts << "SQL: #{truncate_sql(sql, 100)}" if sql
+        parts.join(" | ")
+      end
+
+      # Inspection string
+      def inspect
+        "#<Finding id=#{id[0, 8]} #{analyzer_name}:#{rule_name} severity=#{severity}>"
+      end
+
+      # Check if finding has location information
+      def has_location?
+        !file_path.nil?
+      end
+
+      private
+
+      def generate_id
+        # Simple deterministic ID: hash of analyzer:rule:sql
+        content = "#{analyzer_name}:#{rule_name}:#{sql}:#{file_path}:#{line_number}"
+        Digest::SHA256.hexdigest(content)[0, 16]
+      end
+
+      def truncate_sql(sql_text, length = 100)
+        return sql_text if sql_text.nil? || sql_text.length <= length
+        "#{sql_text[0, length]}..."
+      end
+
+      def validate_severity(sev)
+        sym = sev.to_sym
+        raise ArgumentError, "Invalid severity: #{sev}. Must be one of #{SEVERITIES}" unless SEVERITIES.include?(sym)
+        sym
+      end
+    end
+  end
+end
+
+require "digest"

data/lib/query_guard/core/finding_builders.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Core
+    # Factory builders for common finding types.
+    # Provides convenient methods to create well-structured findings
+    # without manually specifying all parameters.
+    #
+    # Example:
+    #   finding = FindingBuilders.slow_query(
+    #     query,
+    #     duration_ms: 250.5,
+    #     threshold_ms: 100.0
+    #   )
+    module FindingBuilders
+      # Slow query finding
+      def self.slow_query(query, duration_ms:, threshold_ms:, **opts)
+        Finding.new(
+          analyzer_name: :slow_query,
+          rule_name: :duration_exceeded,
+          severity: opts[:severity] || :warn,
+          title: "Slow Query Detected",
+          description: "Query execution time exceeded the configured threshold.",
+          message: "Query took #{duration_ms.round(2)}ms (limit: #{threshold_ms}ms)",
+          sql: query&.sql,
+          metadata: {
+            duration_ms: duration_ms,
+            threshold_ms: threshold_ms
+          },
+          recommendations: [
+            "Add indexes on frequently queried columns",
+            "Review and optimize the query logic",
+            "Consider using pagination for large result sets",
+            "Check database statistics"
+          ],
+          query: query,
+          file_path: opts[:file_path],
+          line_number: opts[:line_number]
+        )
+      end
+
+      # Too many queries finding
+      def self.too_many_queries(count:, limit:, total_duration_ms:, **opts)
+        Finding.new(
+          analyzer_name: :query_count,
+          rule_name: :count_exceeded,
+          severity: opts[:severity] || :warn,
+          title: "Too Many Queries",
+          description: "Request executed more queries than the configured limit.",
+          message: "Executed #{count} queries (limit: #{limit})",
+          metadata: {
+            count: count,
+            limit: limit,
+            total_duration_ms: total_duration_ms
+          },
+          recommendations: [
+            "Use eager loading (N+1 query prevention)",
+            "Consolidate multiple queries into one",
+            "Use database-level aggregations where possible",
+            "Consider caching results"
+          ],
+          file_path: opts[:file_path],
+          line_number: opts[:line_number]
+        )
+      end
+
+      # SELECT * finding
+      def self.select_star(query, **opts)
+        Finding.new(
+          analyzer_name: :select_star,
+          rule_name: :select_star_detected,
+          severity: opts[:severity] || :warn,
+          title: "SELECT * Used",
+          description: "Query uses SELECT * instead of specifying columns.",
+          message: "SELECT * detected in query",
+          sql: query&.sql,
+          metadata: {
+            sql: query&.sql
+          },
+          recommendations: [
+            "Specify only required columns explicitly",
+            "Reduces bandwidth and improves query efficiency",
+            "Makes schema changes less error-prone",
+            "Enables better query optimization by the database"
+          ],
+          query: query,
+          file_path: opts[:file_path],
+          line_number: opts[:line_number]
+        )
+      end
+
+      # Generic builder for custom findings
+      def self.build(analyzer_name:, rule_name:, **opts)
+        Finding.new(
+          analyzer_name: analyzer_name,
+          rule_name: rule_name,
+          severity: opts[:severity] || :warn,
+          title: opts[:title],
+          description: opts[:description],
+          message: opts[:message],
+          sql: opts[:sql],
+          metadata: opts[:metadata] || {},
+          recommendations: opts[:recommendations] || [],
+          query: opts[:query],
+          file_path: opts[:file_path],
+          line_number: opts[:line_number]
+        )
+      end
+
+      # Migration-related finding (prepared for Phase 2)
+      def self.migration_risk(migration_file:, issue:, **opts)
+        Finding.new(
+          analyzer_name: :migration_safety,
+          rule_name: opts[:rule_name] || :unsafe_operation,
+          severity: opts[:severity] || :error,
+          title: opts[:title] || "Migration Risk Detected",
+          description: opts[:description] || "Migration may cause data loss or downtime.",
+          message: issue,
+          file_path: migration_file,
+          line_number: opts[:line_number],
+          metadata: opts[:metadata] || {},
+          recommendations: opts[:recommendations] || [
+            "Review migration carefully before deploying",
+            "Test on a staging environment",
+            "Consider phased rollout for large tables"
+          ]
+        )
+      end
+
+      # Pattern matching finding (prepared for future analyzers)
+      def self.pattern_detected(query, pattern_type:, **opts)
+        Finding.new(
+          analyzer_name: opts[:analyzer_name] || :pattern_detector,
+          rule_name: opts[:rule_name] || :pattern_detected,
+          severity: opts[:severity] || :info,
+          title: opts[:title] || "Pattern Detected",
+          description: opts[:description] || "A query pattern was detected.",
+          message: opts[:message] || "#{pattern_type} pattern detected",
+          sql: query&.sql,
+          metadata: {
+            pattern_type: pattern_type,
+            **(opts[:metadata] || {})
+          },
+          recommendations: opts[:recommendations] || [],
+          query: query,
+          file_path: opts[:file_path],
+          line_number: opts[:line_number]
+        )
+      end
+    end
+  end
+end

data/lib/query_guard/core/query.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Core
+    # Immutable representation of a single SQL query event.
+    # Captured from ActiveSupport::Notifications sql.active_record event.
+    class Query
+      attr_reader :sql, :duration_ms, :name, :started_at, :finished_at
+
+      def initialize(sql:, duration_ms:, name: nil, started_at: nil, finished_at: nil)
+        @sql = sql.freeze
+        @duration_ms = duration_ms
+        @name = name.to_s.freeze if name
+        @started_at = started_at
+        @finished_at = finished_at
+      end
+
+      # Serialize to hash for reporting
+      def to_h
+        {
+          sql: sql,
+          duration_ms: duration_ms,
+          name: name,
+          started_at: started_at&.iso8601,
+          finished_at: finished_at&.iso8601
+        }
+      end
+
+      def inspect
+        "#<Query duration_ms=#{duration_ms} sql='#{truncate_sql(sql, 50)}'>"
+      end
+
+      private
+
+      def truncate_sql(sql, length = 100)
+        sql.length > length ? "#{sql[0, length]}..." : sql
+      end
+    end
+  end
+end

data/lib/query_guard/explain/adapter_interface.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Explain
+    # Base interface for database-specific EXPLAIN plan adapters.
+    # Implementations should handle:
+    # - Safe query execution without side effects
+    # - Plan data extraction in JSON format
+    # - Graceful error handling
+    #
+    # Example:
+    #   adapter = PostgreSQLAdapter.new(connection)
+    #   plan = adapter.get_plan("SELECT * FROM users")
+    #   # => { "Plan" => { "Node Type" => "Seq Scan", ... }, ... }
+    class AdapterInterface
+      # Initialize adapter with database connection
+      #
+      # @param connection [Object] Database-specific connection object
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # Get EXPLAIN plan for a query (JSON format when possible)
+      #
+      # @param sql [String] SQL query to analyze
+      # @param options [Hash] Adapter-specific options
+      # @return [Hash] Parsed plan JSON or nil if unavailable
+      # @raise [QueryGuard::Explain::AdapterError] on execution failure
+      #
+      # Example return structure (PostgreSQL):
+      #   {
+      #     "Plan" => {
+      #       "Node Type" => "Seq Scan",
+      #       "Relation Name" => "users",
+      #       "Plans" => [...],
+      #       "Actual Rows" => 100,
+      #       "Actual Total Time" => 2.543
+      #     },
+      #     "Planning Time" => 0.234,
+      #     "Execution Time" => 2.543
+      #   }
+      def get_plan(sql, options = {})
+        raise NotImplementedError, "Subclasses must implement get_plan"
+      end
+
+      # Check if adapter can execute EXPLAIN for this query type
+      #
+      # @param sql [String] SQL query
+      # @return [Boolean] True if EXPLAIN is supported
+      def can_explain?(sql)
+        raise NotImplementedError, "Subclasses must implement can_explain?"
+      end
+
+      # Get engine name for this adapter
+      #
+      # @return [Symbol] Engine identifier (:postgresql, :mysql, etc.)
+      def engine_name
+        raise NotImplementedError, "Subclasses must implement engine_name"
+      end
+
+      protected
+
+      attr_reader :connection
+    end
+
+    # Custom error for EXPLAIN-related failures
+    class AdapterError < StandardError
+      attr_reader :query, :original_error
+
+      def initialize(message, query: nil, original_error: nil)
+        super(message)
+        @query = query
+        @original_error = original_error
+      end
+    end
+
+    # Raised when EXPLAIN execution is not supported for a query
+    class UnsupportedQueryError < AdapterError; end
+
+    # Raised when connection is unavailable
+    class ConnectionError < AdapterError; end
+
+    # Raised when query execution times out
+    class TimeoutError < AdapterError; end
+
+    # Raised when EXPLAIN plan parsing fails
+    class PlanParseError < AdapterError; end
+  end
+end