query_guard 0.4.2 → 0.5.1

data/lib/query_guard/analyzers/select_star_analyzer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Analyzers
+    # Detects SELECT * statements.
+    class SelectStarAnalyzer < Base
+      SELECT_STAR_PATTERN = /\bSELECT\s+\*/i.freeze
+
+      def initialize
+        super(:select_star)
+      end
+
+      def analyze(context, config)
+        findings = []
+
+        return findings unless config.block_select_star
+
+        context.queries.each do |query|
+          next unless matches_select_star?(query.sql)
+          next if exceeds_ignored_sql?(query.sql, config)
+
+          findings << Core::FindingBuilders.select_star(
+            query,
+            severity: config.select_star_severity || :warn
+          )
+        end
+
+        findings
+      end
+
+      private
+
+      def matches_select_star?(sql)
+        SELECT_STAR_PATTERN.match?(sql)
+      end
+
+      def exceeds_ignored_sql?(sql, config)
+        config.ignored_sql.any? { |pattern| pattern === sql }
+      end
+    end
+  end
+end

data/lib/query_guard/analyzers/slow_query_analyzer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Analyzers
+    # Detects slow queries based on duration threshold.
+    class SlowQueryAnalyzer < Base
+      def initialize
+        super(:slow_query)
+      end
+
+      def analyze(context, config)
+        findings = []
+        threshold = config.max_duration_ms_per_query
+
+        return findings if threshold.nil?
+
+        context.queries.each do |query|
+          next if exceeds_ignored_sql?(query.sql, config)
+          next unless query.duration_ms > threshold
+
+          findings << Core::FindingBuilders.slow_query(
+            query,
+            duration_ms: query.duration_ms,
+            threshold_ms: threshold,
+            severity: config.slow_query_severity || :warn
+          )
+        end
+
+        findings
+      end
+
+      private
+
+      def exceeds_ignored_sql?(sql, config)
+        config.ignored_sql.any? { |pattern| pattern === sql }
+      end
+    end
+  end
+end

data/lib/query_guard/budget.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  # Budget system for enforcing query SLOs on controllers and jobs.
+  # Supports modes: :log (warn only), :notify (callback), :raise (exception).
+  class Budget
+    class Violation < StandardError; end
+
+    attr_reader :rules, :mode, :on_violation
+
+    def initialize
+      @rules = {}
+      @mode = :log
+      @on_violation = nil
+    end
+
+    # DSL: Define a budget for a specific controller action.
+    # Examples:
+    #   budget.for("users#index", count: 10, duration_ms: 500)
+    #   budget.for("posts#show", count: 5)
+    def for(key, **limits)
+      normalized = normalize_key(key)
+      @rules[normalized] ||= {}
+      @rules[normalized].merge!(limits)
+      self
+    end
+
+    # DSL: Define a budget for a background job.
+    # Examples:
+    #   budget.for_job("EmailJob", count: 50, duration_ms: 2000)
+    #   budget.for_job(EmailJob, count: 50)
+    def for_job(job_class_or_name, **limits)
+      key = job_class_or_name.is_a?(String) ? job_class_or_name : job_class_or_name.to_s
+      normalized = normalize_key("job:#{key}")
+      @rules[normalized] ||= {}
+      @rules[normalized].merge!(limits)
+      self
+    end
+
+    # Set the enforcement mode
+    # :log - Log warnings only (default)
+    # :notify - Call on_violation callback
+    # :raise - Raise Budget::Violation exception
+    def mode=(value)
+      unless [:log, :notify, :raise].include?(value)
+        raise ArgumentError, "Invalid mode: #{value}. Must be :log, :notify, or :raise"
+      end
+      @mode = value
+    end
+
+    # Set a callback for :notify mode
+    def on_violation=(callback)
+      unless callback.respond_to?(:call)
+        raise ArgumentError, "on_violation must be callable"
+      end
+      @on_violation = callback
+    end
+
+    # Check if a budget exists for the given key
+    def budget_for(key)
+      normalized = normalize_key(key)
+      @rules[normalized]
+    end
+
+    # Check stats against budget and return violations
+    def check(key, stats)
+      budget = budget_for(key)
+      return [] unless budget
+
+      violations = []
+
+      if budget[:count] && stats[:count] > budget[:count]
+        violations << {
+          type: :budget_exceeded_count,
+          key: key,
+          actual: stats[:count],
+          limit: budget[:count]
+        }
+      end
+
+      if budget[:duration_ms] && stats[:total_duration_ms] > budget[:duration_ms]
+        violations << {
+          type: :budget_exceeded_duration,
+          key: key,
+          actual: stats[:total_duration_ms],
+          limit: budget[:duration_ms]
+        }
+      end
+
+      violations
+    end
+
+    # Enforce budget violations according to current mode
+    def enforce!(key, violations)
+      return if violations.empty?
+
+      case @mode
+      when :log
+        log_violations(key, violations)
+      when :notify
+        notify_violations(key, violations)
+      when :raise
+        raise_violations(key, violations)
+      end
+    end
+
+    private
+
+    def normalize_key(key)
+      key.to_s.downcase.gsub(/\s+/, "")
+    end
+
+    def log_violations(key, violations)
+      violations.each do |v|
+        message = format_violation(key, v)
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.warn("[QueryGuard::Budget] #{message}")
+        else
+          warn("[QueryGuard::Budget] #{message}")
+        end
+      end
+    end
+
+    def notify_violations(key, violations)
+      return unless @on_violation
+
+      violations.each do |v|
+        @on_violation.call(key, v)
+      end
+    end
+
+    def raise_violations(key, violations)
+      messages = violations.map { |v| format_violation(key, v) }
+      raise Violation, messages.join("; ")
+    end
+
+    def format_violation(key, v)
+      case v[:type]
+      when :budget_exceeded_count
+        "#{key}: Query count exceeded (#{v[:actual]} > #{v[:limit]})"
+      when :budget_exceeded_duration
+        "#{key}: Total duration exceeded (#{v[:actual].round(2)}ms > #{v[:limit]}ms)"
+      else
+        "#{key}: #{v[:type]}"
+      end
+    end
+  end
+end

data/lib/query_guard/cli/batch_report_formatter.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module QueryGuard
+  class CLI
+    # Formats multiple QueryGuard reports into a single batch request.
+    #
+    # Used for bulk ingestion into SaaS platforms. Supports:
+    # - Multiple reports in a single API request
+    # - Batch correlation IDs for tracking across the entire batch
+    # - Per-report tracing for individual finding tracking
+    # - Pagination metadata for large batches
+    #
+    # Example:
+    #   reports = [
+    #     { report_version: '1.0', findings: [...], ... },
+    #     { report_version: '1.0', findings: [...], ... }
+    #   ]
+    #
+    #   batch = BatchReportFormatter.new(
+    #     reports: reports,
+    #     batch_id: 'batch-123',
+    #     correlation_id: 'api-request-456'
+    #   )
+    #
+    #   json_output = batch.generate
+    class BatchReportFormatter
+      BATCH_SCHEMA_VERSION = '1.0'
+      BATCH_TYPE = 'batch'
+
+      def initialize(reports:, batch_id: nil, correlation_id: nil, options: {})
+        @reports = Array(reports)
+        @batch_id = batch_id || generate_batch_id
+        @correlation_id = correlation_id || generate_correlation_id
+        @options = options
+        @created_at = Time.now
+      end
+
+      # Generate the complete batch JSON
+      # Returns: String (JSON)
+      def generate
+        JSON.pretty_generate(build_batch)
+      end
+
+      # Build batch structure and return as hash
+      def build_batch
+        {
+          batch_version: BATCH_SCHEMA_VERSION,
+          batch_type: BATCH_TYPE,
+          batch_id: @batch_id,
+          correlation_id: @correlation_id,
+          created_at: @created_at.utc.iso8601.gsub('+00:00', 'Z'),
+          report_count: @reports.length,
+          reports: @reports,
+          pagination: build_pagination,
+          stats: build_batch_stats
+        }
+      end
+
+      private
+
+      # Pagination metadata for large batches
+      # Useful when records exceed size limits (e.g., >10MB)
+      def build_pagination
+        pagination = {
+          total_reports: @reports.length,
+          page: @options[:page] || 1,
+          page_size: @options[:page_size] || @reports.length,
+          has_more: @options[:has_more] || false
+        }
+
+        # Include continuation token if provided (for cursor-based pagination)
+        pagination[:continuation_token] = @options[:continuation_token] if @options[:continuation_token]
+        pagination[:next_page_token] = @options[:next_page_token] if @options[:next_page_token]
+
+        pagination
+      end
+
+      # Aggregate statistics across all reports in the batch
+      def build_batch_stats
+        total_findings = 0
+        total_critical = 0
+        total_error = 0
+        total_warn = 0
+        total_info = 0
+        by_report_type = { 'analyze' => 0, 'check' => 0 }
+
+        @reports.each do |report|
+          summary = report[:summary] || {}
+          total_findings += summary[:total_findings] || 0
+          total_critical += summary[:by_severity]&.dig(:critical) || 0
+          total_error += summary[:by_severity]&.dig(:error) || 0
+          total_warn += summary[:by_severity]&.dig(:warn) || 0
+          total_info += summary[:by_severity]&.dig(:info) || 0
+
+          report_type = report[:report_type] || 'unknown'
+          by_report_type[report_type] ||= 0
+          by_report_type[report_type] += 1
+        end
+
+        {
+          total_findings: total_findings,
+          findings_by_severity: {
+            critical: total_critical,
+            error: total_error,
+            warn: total_warn,
+            info: total_info
+          },
+          reports_by_type: by_report_type,
+          processing_time_ms: ((@created_at - @created_at) * 1000).round(2)
+        }
+      end
+
+      # Helper: Generate a unique batch ID
+      def generate_batch_id
+        require 'securerandom'
+        "batch-#{SecureRandom.hex(8)}"
+      end
+
+      # Helper: Generate a correlation ID for the entire batch
+      def generate_correlation_id
+        require 'securerandom'
+        "corr-#{SecureRandom.hex(8)}"
+      end
+    end
+  end
+end

data/lib/query_guard/cli/command.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  class CLI
+    # Base class for CLI commands
+    class Command
+      def initialize(path, options = {})
+        @path = path
+        @options = options
+        @formatter = Formatter.new(options)
+      end
+
+      protected
+
+      def find_migration_files(path)
+        pattern = File.join(path, '**', '*_*.rb')
+        Dir.glob(pattern)
+      end
+
+      def find_ruby_files(path)
+        pattern = File.join(path, '**', '*.rb')
+        Dir.glob(pattern)
+      end
+
+      def analyze_migrations(files)
+        analyzer = QueryGuard::Migrations::MigrationAnalyzer.new(
+          database_adapter: get_database_adapter
+        )
+
+        findings = []
+        files.each do |file|
+          begin
+            file_findings = analyzer.analyze_migration(file)
+            file_findings.each do |finding|
+              finding[:file] = file
+              findings << finding
+            end
+          rescue => e
+            puts "Warning: Failed to analyze #{file}: #{e.message}" if @options[:verbose]
+          end
+        end
+
+        findings
+      end
+
+      def get_database_adapter
+        # Try to get a live database adapter if available
+        return nil unless defined?(ActiveRecord) && ActiveRecord::Base.connected?
+
+        begin
+          QueryGuard::Migrations::PostgreSQLAdapter.new(
+            connection: ActiveRecord::Base.connection
+          )
+        rescue StandardError
+          nil  # Fall back to NullDatabaseAdapter
+        end
+      end
+
+      def severity_to_number(severity)
+        case severity
+        when :critical then 4
+        when :error then 3
+        when :warn then 2
+        when :info then 1
+        else 0
+        end
+      end
+
+      def threshold_to_number(threshold)
+        case threshold&.to_s&.downcase
+        when 'critical' then 4
+        when 'error' then 3
+        when 'warn' then 2
+        when 'info' then 1
+        else 2  # Default to warn
+        end
+      end
+
+      def findings_exceed_threshold?(findings, threshold)
+        threshold_num = threshold_to_number(threshold)
+        findings.any? { |f| severity_to_number(f[:severity]) >= threshold_num }
+      end
+
+      def path_exists?
+        File.exist?(@path)
+      end
+
+      def path_absolute
+        File.expand_path(@path)
+      end
+    end
+  end
+end

data/lib/query_guard/cli/commands/analyze.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  class CLI
+    module Commands
+      # Analyzes queries and migrations, printing detailed results
+      class Analyze < Command
+        def execute
+          unless path_exists?
+            puts "Error: Path does not exist: #{path_absolute}"
+            exit 1
+          end
+
+          # Skip progress output if JSON format is being used
+          unless @options[:json] || @options[:format] == 'json'
+            puts "Analyzing: #{path_absolute}"
+            
+            # Show database context
+            adapter = get_database_adapter
+            if adapter
+              puts "Database context: Connected (accurate severity)\n"
+            else
+              puts "Database context: Not available (conservative estimates)"
+              puts "  For more accurate results, run: DATABASE_URL=... queryguard analyze\n"
+            end
+            
+            puts "(This may take a moment...)\n"
+          end
+
+          # Find and analyze migration files
+          migration_files = find_migration_files(@path)
+          if migration_files.any?
+            puts "  Found #{migration_files.length} migration files" unless @options[:json] || @options[:format] == 'json'
+            findings = analyze_migrations(migration_files)
+          else
+            findings = []
+          end
+
+          # Format and print results
+          if findings.any?
+            @formatter.print_findings(findings, "Migration Risk Analysis Results", 'analyze', @path)
+          else
+            puts "\n✅ No issues found in migrations!\n" unless @options[:json] || @options[:format] == 'json'
+          end
+
+          # Exit with success (analyze doesn't fail on findings)
+          0
+        end
+      end
+    end
+  end
+end

data/lib/query_guard/cli/commands/check.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  class CLI
+    module Commands
+      # Checks if findings exceed severity threshold for CI/CD
+      class Check < Command
+        def execute
+          unless path_exists?
+            puts "Error: Path does not exist: #{path_absolute}"
+            return 2  # Failed to check
+          end
+
+          threshold = @options[:threshold] || 'error'
+
+          # Skip progress output if JSON format is being used
+          unless @options[:json] || @options[:format] == 'json'
+            puts "Checking migrations: #{path_absolute}"
+            puts "Threshold: #{threshold.upcase}\n"
+            puts "(This may take a moment...)\n"
+          end
+
+          # Find and analyze migration files
+          migration_files = find_migration_files(@path)
+          if migration_files.empty?
+            puts "✅ No migrations found - clear to deploy!\n" unless @options[:json] || @options[:format] == 'json'
+            return 0
+          end
+
+          puts "  Found #{migration_files.length} migration files" unless @options[:json] || @options[:format] == 'json'
+          findings = analyze_migrations(migration_files)
+
+          if findings.empty?
+            puts "\n✅ No issues found - clear to deploy!\n" unless @options[:json] || @options[:format] == 'json'
+            return 0
+          end
+
+          # Check if findings exceed threshold
+          if findings_exceed_threshold?(findings, threshold)
+            @formatter.print_findings(findings, "Migration Risk Check - FAILED ❌", 'check', @path)
+            unless @options[:json] || @options[:format] == 'json'
+              puts "\n🚫 Risk threshold exceeded! Deployment blocked.\n"
+              puts "To proceed, either:"
+              puts "  1. Fix the identified risks above"
+              puts "  2. Increase the threshold (e.g., --threshold error)"
+              puts "  3. Review with your DBA\n"
+            end
+            return 1  # Check failed
+          else
+            @formatter.print_findings(findings, "Migration Risk Check - PASSED ✅", 'check', @path)
+            puts "\n✅ All risks below threshold - clear to deploy!\n" unless @options[:json] || @options[:format] == 'json'
+            return 0
+          end
+        end
+      end
+    end
+  end
+end