query_guard 0.4.2 → 0.5.1

data/lib/query_guard/cli/formatter.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  class CLI
+    # Formats findings for terminal output or JSON
+    # Provides clean, developer-friendly output with:
+    # - Severity and type grouping
+    # - Clear recommendations and action items
+    # - Index suggestions and migration steps
+    # - Summary with detailed counts
+    class Formatter
+      def initialize(options = {})
+        @options = options
+        @json = options[:json] || options[:format] == 'json' || false
+        @verbose = options[:verbose] || false
+      end
+
+      def print_findings(findings, title = "Analysis Results", command = 'analyze', path = '.')
+        if @json
+          print_json(findings, command, path)
+        else
+          print_text(findings, title)
+        end
+      end
+
+      def print_text(findings, title)
+        puts "\n" + "=" * 60
+        puts title
+        puts "=" * 60
+
+        if findings.empty?
+          puts "\n✅ No issues found!\n"
+          return
+        end
+
+        # Group findings by severity, then by type
+        by_severity = findings.group_by { |f| f[:severity] }
+
+        # Print in order
+        severity_order = [:critical, :error, :warn, :info]
+        severity_order.each do |severity|
+          next unless by_severity[severity]
+
+          print_severity_section(severity, by_severity[severity])
+        end
+
+        print_summary(findings)
+      end
+
+      def print_severity_section(severity, findings)
+        icon = severity_icon(severity)
+        color = severity_color(severity)
+        label = severity.to_s.upcase
+
+        puts "\n#{icon}  #{color}#{label}#{reset_color} (#{findings.length})"
+        puts "-" * 60
+
+        # Group by type within severity
+        by_type = findings.group_by { |f| "#{f[:analyzer_name]}:#{f[:rule_name]}" }
+
+        by_type.each do |type_key, type_findings|
+          print_type_group(type_key, type_findings)
+        end
+      end
+
+      def print_type_group(type_key, findings)
+        # Print type header when multiple findings of same type
+        if findings.length == 1
+          print_finding(findings.first)
+        else
+          puts "\n  [#{type_key}] (#{findings.length} findings)"
+          findings.each do |finding|
+            print_finding(finding, indent: "    ")
+          end
+        end
+      end
+
+      def print_finding(finding, indent: "  ")
+        # Title and location
+        puts "\n#{indent}#{finding[:title]}"
+
+        # File and line info
+        if finding[:file_path]
+          location = "#{finding[:file_path]}"
+          location += ":#{finding[:line_number]}" if finding[:line_number]
+          puts "#{indent}  📄 #{location}"
+        end
+
+        # Description
+        if finding[:description]
+          puts "#{indent}  #{finding[:description]}"
+        end
+
+        # Metadata context (table, operation, escalation)
+        print_finding_context(finding, indent)
+
+        # Recommendations (primary)
+        print_recommendations(finding, indent)
+
+        # Special metadata sections: indexes, migration steps, strategies
+        print_index_suggestions(finding, indent)
+        print_migration_steps(finding, indent)
+
+        # Verbose debug metadata
+        if @verbose && finding[:metadata] && !finding[:metadata].empty?
+          puts "#{indent}  [Debug] #{finding[:metadata].inspect}"
+        end
+      end
+
+      def print_finding_context(finding, indent)
+        metadata = finding[:metadata] || {}
+
+        # Table context
+        if metadata[:table_name]
+          rows = metadata[:estimated_table_rows]
+          rows_str = rows ? " (#{format_row_count(rows)} rows)" : ""
+          puts "#{indent}  🗂️  Table: #{metadata[:table_name]}#{rows_str}"
+        end
+
+        # Operation context
+        if metadata[:operation]
+          puts "#{indent}  ⚙️  Operation: #{metadata[:operation]}"
+        end
+
+        # Escalation
+        if metadata[:severity_escalated]
+          original = metadata[:original_severity]
+          reason = metadata[:escalation_reason]
+          puts "#{indent}  ⬆️  Escalated from #{original}: #{reason}"
+        end
+
+        # Risk level
+        if metadata[:risk_level]
+          puts "#{indent}  Risk Level: #{metadata[:risk_level]}"
+        end
+      end
+
+      def print_recommendations(finding, indent)
+        # Show recommendations as action items
+        recommendations = Array(finding[:recommendation])
+
+        if recommendations.any?
+          puts "#{indent}  ✅ Recommended Actions:"
+          recommendations.each do |rec|
+            puts "#{indent}     - #{rec}"
+          end
+        end
+      end
+
+      def print_index_suggestions(finding, indent)
+        metadata = finding[:metadata] || {}
+
+        # Check for single index suggestion
+        if metadata[:index_sql]
+          puts "#{indent}  🔧 Suggested Index:"
+          puts "#{indent}     #{metadata[:index_sql]}"
+        elsif metadata[:suggested_indexes]
+          # Multiple index suggestions
+          puts "#{indent}  🔧 Suggested Indexes:"
+          Array(metadata[:suggested_indexes]).each do |idx_sql|
+            puts "#{indent}     #{idx_sql}"
+          end
+        end
+      end
+
+      def print_migration_steps(finding, indent)
+        metadata = finding[:metadata] || {}
+
+        # Migration step-by-step guidance
+        if metadata[:migration_steps]
+          puts "#{indent}  📋 Migration Steps:"
+          Array(metadata[:migration_steps]).each_with_index do |step, i|
+            puts "#{indent}     #{i + 1}. #{step}"
+          end
+        end
+
+        # Safe rollout strategy
+        if metadata[:safe_rollout_strategy]
+          puts "#{indent}  🛡️  Safe Rollout Strategy:"
+          puts "#{indent}     #{metadata[:safe_rollout_strategy]}"
+        end
+      end
+
+      def print_json(findings, command = 'analyze', path = '.')
+        reporter = JsonReporter.new(
+          findings: findings,
+          command: command,
+          path: path,
+          options: @options
+        )
+        puts reporter.generate
+      end
+
+      private
+
+      def print_summary(findings)
+        by_severity = findings.group_by { |f| f[:severity] }
+        severity_counts = by_severity.transform_values { |v| v.length }
+
+        # Count by type
+        by_type = findings.group_by { |f| "#{f[:analyzer_name]}:#{f[:rule_name]}" }
+        type_counts = by_type.transform_values { |v| v.length }
+
+        puts "\n" + "=" * 60
+        puts "SUMMARY"
+        puts "=" * 60
+
+        # Total
+        puts "\n  Total Findings: #{findings.length}"
+
+        # By Severity
+        puts "\n  By Severity:"
+        %i[critical error warn info].each do |severity|
+          count = severity_counts[severity] || 0
+          next if count.zero?
+
+          icon = severity_icon(severity)
+          puts "    #{icon} #{severity.to_s.upcase}: #{count}"
+        end
+
+        # By Type (if more than one)
+        if type_counts.length > 1
+          puts "\n  By Type:"
+          type_counts.sort_by { |_k, v| -v }.each do |type_key, count|
+            puts "    • #{type_key}: #{count}"
+          end
+        end
+
+        # Quick stats
+        puts "\n  Files Analyzed:"
+        files_with_findings = findings.group_by { |f| f[:file_path] }.keys.compact.length
+        puts "    • #{files_with_findings} file#{files_with_findings == 1 ? '' : 's'} with findings"
+
+        puts "\n" + "=" * 60 + "\n"
+      end
+
+      def severity_icon(severity)
+        case severity
+        when :critical then "🚨"
+        when :error then "❌"
+        when :warn then "⚠️ "
+        when :info then "ℹ️ "
+        else "•"
+        end
+      end
+
+      def severity_color(severity)
+        # ANSI color codes
+        case severity
+        when :critical then "\e[31m"     # Red
+        when :error then "\e[31m"        # Red
+        when :warn then "\e[33m"         # Yellow
+        when :info then "\e[34m"         # Blue
+        else ""
+        end
+      end
+
+      def reset_color
+        "\e[0m"
+      end
+
+      def format_row_count(count)
+        return "unknown" if count.nil?
+
+        case count
+        when 0..999
+          "#{count}"
+        when 1_000..999_999
+          "#{(count / 1_000.0).round(1)}K"
+        when 1_000_000..999_999_999
+          "#{(count / 1_000_000.0).round(1)}M"
+        else
+          "#{(count / 1_000_000_000.0).round(1)}B"
+        end
+      end
+    end
+  end
+end

data/lib/query_guard/cli/json_reporter.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module QueryGuard
+  class CLI
+    # Generates standardized JSON reports for QueryGuard analysis and check results.
+    #
+    # Provides a stable, versioned JSON schema suitable for:
+    # - SaaS platform ingestion
+    # - CI/CD integration
+    # - External tool consumption
+    # - Compliance and audit archival
+    #
+    # Schema version: 1.0 (documented in docs/JSON_REPORT_SCHEMA.md)
+    #
+    # Example:
+    #   reporter = QueryGuard::CLI::JsonReporter.new(
+    #     findings: findings,
+    #     command: 'analyze',
+    #     path: 'db/migrate',
+    #     options: { threshold: 'error' }
+    #   )
+    #   json_output = reporter.generate
+    class JsonReporter
+      SCHEMA_VERSION = '1.0'
+      TOOL_NAME = 'queryguard'
+
+      def initialize(findings:, command:, path: '.', options: {})
+        @findings = findings
+        @command = command # 'analyze' or 'check'
+        @path = path
+        @options = options
+        @started_at = Time.now
+
+        # Initialize tracing context (for distributed systems)
+        # Can be overridden via options: { request_id, trace_id, span_id, parent_span_id }
+        @request_id = options[:request_id] || generate_request_id
+        @trace_id = options[:trace_id] || generate_trace_id
+        @span_id = options[:span_id] || generate_span_id
+        @parent_span_id = options[:parent_span_id]
+
+        # Initialize source metadata collector
+        # Can be overridden via options: { source_metadata_collector }
+        @source_metadata_collector = options[:source_metadata_collector] || SourceMetadataCollector.new
+      end
+
+      # Generate the complete JSON report
+      # Returns: String (JSON)
+      def generate
+        JSON.pretty_generate(build_report)
+      end
+
+      # Generate report and return as parsed hash (useful for testing)
+      def build_report
+        {
+          report_version: SCHEMA_VERSION,
+          report_type: @command,
+          timestamp: Time.now.utc.iso8601.gsub('+00:00', 'Z'),
+          tool: build_tool,
+          source: build_source,
+          summary: build_summary,
+          findings: build_findings,
+          metadata: build_metadata,
+          tracing: build_tracing
+        }
+      end
+
+      private
+
+      # Tool information block
+      def build_tool
+        {
+          name: TOOL_NAME,
+          version: QueryGuard::VERSION || 'unknown'
+        }
+      end
+
+      # Source information (what was analyzed)
+      def build_source
+        source = {
+          path: File.expand_path(@path),
+          command: @command
+        }
+
+        # Include threshold for check command
+        source[:threshold] = @options[:threshold] if @command == 'check' && @options[:threshold]
+
+        # Include source metadata (git, CI provider information)
+        source_metadata = @source_metadata_collector.collect
+        if source_metadata
+          source[:metadata] = source_metadata
+        end
+
+        source
+      end
+
+      # Summary statistics
+      def build_summary
+        by_severity = @findings.group_by { |f| f[:severity] || :info }
+
+        {
+          total_findings: @findings.length,
+          by_severity: {
+            critical: (by_severity[:critical] || []).length,
+            error: (by_severity[:error] || []).length,
+            warn: (by_severity[:warn] || []).length,
+            info: (by_severity[:info] || []).length
+          },
+          files_analyzed: unique_files_count,
+          files_with_findings: unique_files_with_findings_count
+        }
+      end
+
+      # Array of finding objects
+      def build_findings
+        @findings.map do |finding|
+          {
+            id: finding[:id] || generate_finding_id(finding),
+            analyzer: finding[:analyzer_name] || finding[:analyzer] || 'unknown',
+            rule: finding[:rule_name] || finding[:rule] || 'unknown',
+            severity: (finding[:severity] || :info).to_s,
+            title: finding[:title] || finding[:message] || '(no title)',
+            description: finding[:description] || '',
+            file_path: finding[:file_path],
+            line_number: finding[:line_number],
+            recommendation: clean_recommendations(finding[:recommendation]),
+            metadata: clean_metadata(finding[:metadata])
+          }.compact # Remove nil values
+        end
+      end
+
+      # Additional metadata about the analysis
+      def build_metadata
+        {
+          total_files_checked: unique_files_count,
+          has_index_suggestions: findings_have_index_suggestions?,
+          has_migration_steps: findings_have_migration_steps?,
+          execution_time_ms: ((Time.now - @started_at) * 1000).round(2)
+        }
+      end
+
+      # Tracing context for distributed systems (OpenTelemetry compatible)
+      def build_tracing
+        tracing = {
+          request_id: @request_id,
+          trace_id: @trace_id,
+          span_id: @span_id
+        }
+
+        tracing[:parent_span_id] = @parent_span_id if @parent_span_id
+
+        tracing
+      end
+
+      # Helper: Count unique files analyzed
+      def unique_files_count
+        @findings.map { |f| f[:file_path] }.compact.uniq.length
+      end
+
+      # Helper: Count unique files that have findings
+      def unique_files_with_findings_count
+        @findings.map { |f| f[:file_path] }.compact.uniq.length
+      end
+
+      # Helper: Do any findings have index suggestions?
+      def findings_have_index_suggestions?
+        return false if @findings.empty?
+
+        @findings.any? do |f|
+          metadata = f[:metadata] || {}
+          metadata[:index_sql] || metadata[:suggested_indexes]
+        end
+      end
+
+      # Helper: Do any findings have migration steps?
+      def findings_have_migration_steps?
+        return false if @findings.empty?
+
+        @findings.any? do |f|
+          metadata = f[:metadata] || {}
+          metadata[:migration_steps]
+        end
+      end
+
+      # Helper: Ensure recommendations are an array of strings
+      def clean_recommendations(recommendations)
+        return nil if recommendations.nil? || recommendations.empty?
+
+        Array(recommendations).map(&:to_s)
+      end
+
+      # Helper: Clean metadata, ensure it doesn't leak internal objects
+      def clean_metadata(metadata)
+        return nil if metadata.nil? || metadata.empty?
+
+        # Convert metadata hash to a clean version
+        # Remove any Ruby objects that won't serialize to JSON
+        clean_hash(metadata)
+      end
+
+      # Helper: Recursively clean a hash for JSON serialization
+      def clean_hash(hash)
+        hash.transform_values do |value|
+          case value
+          when Hash
+            clean_hash(value)
+          when Array
+            value.map { |v| v.is_a?(Hash) ? clean_hash(v) : v.to_s }
+          when String, Numeric, TrueClass, FalseClass, NilClass
+            value
+          else
+            # Convert unknown objects to string representation
+            value.to_s
+          end
+        end
+      end
+
+      # Helper: Generate deterministic ID for a finding
+      def generate_finding_id(finding)
+        require 'digest'
+
+        content = "#{finding[:analyzer_name]}:#{finding[:rule_name]}:#{finding[:file_path]}:#{finding[:line_number]}"
+        Digest::SHA256.hexdigest(content)[0, 16]
+      end
+
+      # Helper: Generate a request ID (UUID-like format)
+      def generate_request_id
+        require 'securerandom'
+        SecureRandom.hex(8)
+      end
+
+      # Helper: Generate a trace ID for distributed tracing (16 hex chars, 64-bit)
+      def generate_trace_id
+        require 'securerandom'
+        SecureRandom.hex(8)
+      end
+
+      # Helper: Generate a span ID (8 hex chars, 32-bit)
+      def generate_span_id
+        require 'securerandom'
+        SecureRandom.hex(4)
+      end
+    end
+  end
+end

data/lib/query_guard/cli/paged_report_formatter.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module QueryGuard
+  class CLI
+    # Formats QueryGuard reports with pagination support for large finding sets.
+    #
+    # When a report has many findings (e.g., thousands), pagination allows:
+    # - Chunking findings into pages for API transmission
+    # - Cursor-based pagination for large datasets
+    # - Memory-efficient processing on receiving end
+    #
+    # Example:
+    #   # Paginate findings into pages of 100 each
+    #   paged = PagedReportFormatter.new(
+    #     report: full_report,
+    #     page_size: 100,
+    #     page: 1
+    #   )
+    #
+    #   json = paged.generate  # Returns report with findings[0..99]
+    #
+    # Example with cursor:
+    #   paged = PagedReportFormatter.new(
+    #     report: full_report,
+    #     page_size: 100,
+    #     continuation_token: 'abc123...'
+    #   )
+    #
+    #   json = paged.generate  # Returns next batch of 100 findings
+    class PagedReportFormatter
+      DEFAULT_PAGE_SIZE = 100
+      MAX_PAGE_SIZE = 1000
+
+      def initialize(report:, page_size: DEFAULT_PAGE_SIZE, page: 1, continuation_token: nil)
+        @report = report.dup  # Don't mutate original
+        @page_size = [page_size.to_i, MAX_PAGE_SIZE].min
+        @page = [page.to_i, 1].max
+        @continuation_token = continuation_token
+        @all_findings = @report.delete(:findings) || []
+      end
+
+      # Generate paginated report
+      # Returns: String (JSON)
+      def generate
+        JSON.pretty_generate(build_paged_report)
+      end
+
+      # Build the paginated report
+      def build_paged_report
+        start_index = (@page - 1) * @page_size
+        end_index = start_index + @page_size
+
+        paginated_findings = @all_findings[start_index...end_index]
+        has_more = end_index < @all_findings.length
+
+        # Build the report with paginated findings
+        report = @report.dup
+        report[:findings] = paginated_findings
+
+        # Add pagination metadata
+        report[:pagination] = build_pagination(has_more)
+
+        # Update summary to match paginated findings only
+        report[:summary] = update_summary(paginated_findings) if report[:summary]
+
+        report
+      end
+
+      private
+
+      # Build pagination metadata
+      def build_pagination(has_more)
+        pagination = {
+          page: @page,
+          page_size: @page_size,
+          total_findings: @all_findings.length,
+          has_more: has_more,
+          findings_on_page: [@all_findings.length - ((@page - 1) * @page_size), @page_size].min
+        }
+
+        # Add next/previous page tokens for cursor-based pagination
+        if has_more
+          pagination[:next_page_token] = generate_page_token(@page + 1)
+        end
+
+        if @page > 1
+          pagination[:prev_page_token] = generate_page_token(@page - 1)
+        end
+
+        pagination
+      end
+
+      # Update summary to reflect current page counts
+      def update_summary(paginated_findings)
+        summary = @report[:summary].dup
+        by_severity = paginated_findings.group_by { |f| f[:severity] || :info }
+
+        summary[:total_findings] = paginated_findings.length
+        summary[:by_severity] = {
+          critical: (by_severity[:critical] || []).length,
+          error: (by_severity[:error] || []).length,
+          warn: (by_severity[:warn] || []).length,
+          info: (by_severity[:info] || []).length
+        }
+
+        # Keep original file counts from full analysis
+        summary
+      end
+
+      # Generate a pagination token (opaque, base64-encoded)
+      def generate_page_token(page_number)
+        require 'base64'
+        data = {
+          page: page_number,
+          page_size: @page_size,
+          generated_at: Time.now.to_i
+        }
+        Base64.strict_encode64(JSON.dump(data))
+      end
+
+      # Decode a pagination token (for cursor continuations)
+      def decode_page_token(token)
+        require 'base64'
+        data = JSON.parse(Base64.strict_decode64(token))
+        {
+          page: data['page'],
+          page_size: data['page_size']
+        }
+      rescue StandardError
+        { page: 1, page_size: @page_size }
+      end
+    end
+  end
+end