benedictus 0.2.0

data/lib/benedictus/renderers/tree_renderer.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Renderers
+    class TreeRenderer
+      BRANCH_LAST    = "└─ "
+      BRANCH_MID     = "├─ "
+      CONTINUE_BAR   = "│  "
+      CONTINUE_GAP   = "   "
+      WARNING_GLYPH  = "⚠"
+      SEVERITY_ORDER = { critical: 0, warning: 1, info: 2, default: 3, good: 4 }.freeze
+
+      def initialize(tree, expression: nil, color: nil, sql: nil, footer: nil, output: $stdout)
+        @tree       = tree
+        @expression = expression
+        @sql        = sql
+        @footer     = footer
+        @output     = output
+        @pastel     = Benedictus::Color.new(enabled: color_enabled?(color))
+      end
+
+      def render
+        [
+          render_header,
+          render_sql,
+          render_tree,
+          render_footer
+        ].compact.reject(&:empty?).join("\n\n")
+      end
+
+      private
+
+      attr_reader :tree, :expression, :pastel
+
+      def color_enabled?(explicit)
+        return false if ENV["NO_COLOR"] && !ENV["NO_COLOR"].empty?
+        return explicit unless explicit.nil?
+
+        @output.respond_to?(:tty?) && @output.tty?
+      end
+
+      def render_header
+        lines = []
+        lines << "#{pastel.bold("Query:")} #{expression}" if expression
+        lines << header_summary_line
+        lines.join("\n")
+      end
+
+      def header_summary_line
+        parts = []
+        parts << "Total cost: #{format_cost(tree.total_cost)}"
+        parts << "Execution time: #{format_ms(tree.execution_time)}" if tree.execution_time
+        parts << "Planning: #{format_ms(tree.planning_time)}" if tree.planning_time
+        parts << "Rows: #{format_rows(tree.total_rows)}" if tree.total_rows
+        pastel.bold(parts.join("    "))
+      end
+
+      def render_sql
+        return nil unless @sql
+
+        [pastel.bold("SQL:").to_s, @sql].join("\n")
+      end
+
+      def render_footer
+        @footer
+      end
+
+      def render_tree
+        render_node(tree.root, "", true).join("\n")
+      end
+
+      def render_node(node, prefix, is_last)
+        lines = []
+        branch = is_last ? BRANCH_LAST : BRANCH_MID
+        child_prefix = prefix + (is_last ? CONTINUE_GAP : CONTINUE_BAR)
+
+        lines << "#{prefix}#{branch}#{node_label(node)}"
+        decoration_lines(node).each { |line| lines << "#{child_prefix}#{line}" }
+        warning_lines(node).each { |line| lines << "#{child_prefix}#{line}" }
+
+        last = node.children.length - 1
+        node.children.each_with_index do |child, i|
+          lines.concat(render_node(child, child_prefix, i == last))
+        end
+
+        lines
+      end
+
+      def node_label(node)
+        "#{paint_node_type(node)}#{relation_suffix(node)} #{paint_metrics(node)}".rstrip
+      end
+
+      def paint_node_type(node)
+        type = node.node_type.to_s
+        case severity_for(node)
+        when :critical then pastel.red.bold(type)
+        when :warning  then pastel.yellow.bold(type)
+        when :good     then pastel.green.bold(type)
+        else                pastel.bold(type)
+        end
+      end
+
+      def severity_for(node)
+        return node.warnings.map(&:severity).min_by { |s| SEVERITY_ORDER[s] } if node.warnings.any?
+        return :good if node.node_type =~ /\AIndex (Only )?Scan\z/
+
+        :default
+      end
+
+      def relation_suffix(node)
+        case node.node_type
+        when "Index Scan", "Index Only Scan", "Bitmap Index Scan"
+          parts = []
+          parts << "using #{node.index_name}" if node.index_name
+          parts << "on #{node.target}" if node.target
+          parts.empty? ? "" : " #{parts.join(" ")}"
+        when "Seq Scan", "Bitmap Heap Scan"
+          node.target ? " on #{node.target}" : ""
+        else
+          ""
+        end
+      end
+
+      def paint_metrics(node)
+        parts = []
+        parts << "cost=#{format_cost(node.startup_cost)}..#{format_cost(node.total_cost)}"
+        parts << "actual=#{format_ms(node.actual_total_time)}" if node.actual_total_time
+        parts << "rows=#{format_rows(node.actual_rows || node.plan_rows)}"
+        parts << "loops=#{format_rows(node.actual_loops)}" if node.actual_loops && node.actual_loops > 1
+        pastel.dim("(#{parts.join("  ")})")
+      end
+
+      def decoration_lines(node)
+        decorations = []
+        decorations << "Hash Cond: #{node.hash_cond}"     if node.hash_cond
+        decorations << "Index Cond: #{node.index_cond}"   if node.index_cond
+        decorations << "Recheck Cond: #{node.recheck_cond}" if node.recheck_cond
+        decorations << "Join Filter: #{node.join_filter}" if node.join_filter
+        decorations << "Filter: #{node.filter}"           if node.filter
+        decorations << "Sort Key: #{Array(node.sort_key).join(", ")}" if node.sort_key
+        decorations << "Sort Method: #{node.sort_method}#{sort_space(node)}" if node.sort_method
+        decorations.map { |d| pastel.dim(d) }
+      end
+
+      def sort_space(node)
+        return "" unless node.sort_space_used
+
+        " (#{node.sort_space_type}: #{node.sort_space_used} kB)"
+      end
+
+      def warning_lines(node)
+        node.warnings.flat_map { |warning| paint_warning(warning) }
+      end
+
+      def paint_warning(warning)
+        glyph = paint_glyph(warning.severity)
+        head  = "#{glyph}  #{warning.message}"
+        return [head] unless warning.suggestion
+
+        [head, "   #{pastel.italic(warning.suggestion)}"]
+      end
+
+      def paint_glyph(severity)
+        case severity
+        when :critical then pastel.red.bold(WARNING_GLYPH)
+        when :warning  then pastel.yellow(WARNING_GLYPH)
+        else                pastel.cyan(WARNING_GLYPH)
+        end
+      end
+
+      def format_cost(value)
+        return "?" if value.nil?
+
+        format("%.2f", value)
+      end
+
+      def format_ms(value)
+        return "?" if value.nil?
+
+        if value >= 100
+          format("%.1f ms", value)
+        else
+          format("%.2f ms", value)
+        end
+      end
+
+      def format_rows(value)
+        return "?" if value.nil?
+
+        n = value.to_i
+        digits = n.abs.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+        n.negative? ? "-#{digits}" : digits
+      end
+    end
+  end
+end

data/lib/benedictus/runner.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Benedictus
+  class Runner
+    ANALYZE_FOOTER = "Executed inside rolled-back transaction. " \
+                     "Note: side effects of volatile Postgres functions " \
+                     "(setval, pg_advisory_lock, pg_notify, dblink, …) are NOT reverted by ROLLBACK."
+
+    def initialize(expression:, options: {}, output: $stdout, error: $stderr, skip_rails_load: false)
+      @expression      = expression
+      @options         = normalize_options(options)
+      @output          = output
+      @error           = error
+      @skip_rails_load = skip_rails_load
+    end
+
+    def call
+      warn_unused_buffers
+
+      Benedictus::RailsLoader.load! unless @skip_rails_load
+
+      value    = Benedictus::ExpressionEvaluator.call(@expression)
+      relation = Benedictus::RelationResolver.call(value)
+      sql      = relation.to_sql
+
+      output_string =
+        case @options[:format]
+        when "tree" then render_tree(relation, sql)
+        when "json" then render_json(relation)
+        when "raw"  then render_raw(relation)
+        else raise ArgumentError, "unknown format: #{@options[:format]}"
+        end
+
+      @output.puts(output_string)
+    end
+
+    HEURISTIC_OPTION_KEYS = %i[seq_scan_threshold drift_factor nested_loop_threshold per_row_cost_threshold].freeze
+
+    private
+
+    def normalize_options(options)
+      h = options.to_h.transform_keys { |k| k.to_s.tr("-", "_").to_sym }
+      {
+        analyze: h.fetch(:analyze,  false),
+        buffers: h.fetch(:buffers,  false),
+        verbose: h.fetch(:verbose,  false),
+        sql: h.fetch(:sql, false),
+        format: h.fetch(:format, "tree"),
+        no_color: h.fetch(:no_color, false)
+      }.merge(HEURISTIC_OPTION_KEYS.each_with_object({}) { |k, acc| acc[k] = h[k] if h.key?(k) })
+    end
+
+    def heuristics_config
+      HEURISTIC_OPTION_KEYS.each_with_object({}) do |key, acc|
+        acc[key] = @options[key] unless @options[key].nil?
+      end
+    end
+
+    def render_tree(relation, sql)
+      plan_data = run_plan(relation, format: "JSON")
+      tree = Benedictus::Plan::Parser.parse(plan_data)
+      Benedictus::Heuristics::Registry.annotate(tree, config: heuristics_config)
+
+      Benedictus::Renderers::TreeRenderer.new(
+        tree,
+        expression: @expression,
+        color: color_choice,
+        sql: sql_to_show(sql),
+        footer: footer,
+        output: @output
+      ).render
+    end
+
+    def render_json(relation)
+      plan_data = run_plan(relation, format: "JSON")
+      Benedictus::Renderers::JsonRenderer.new(plan_data).render
+    end
+
+    def render_raw(relation)
+      result = run_plan(relation, format: "TEXT")
+      Benedictus::Renderers::RawRenderer.new(result).render
+    end
+
+    def run_plan(relation, format:)
+      Benedictus::PlanRunner.call(
+        relation: relation,
+        analyze: @options[:analyze],
+        buffers: @options[:buffers],
+        verbose: @options[:verbose],
+        format: format
+      )
+    end
+
+    def color_choice
+      return false if @options[:no_color]
+
+      nil
+    end
+
+    def sql_to_show(sql)
+      return nil unless @options[:sql]
+
+      formatted_sql(sql)
+    end
+
+    def formatted_sql(sql)
+      Benedictus::SqlFormatter.format(sql)
+    end
+
+    def footer
+      return ANALYZE_FOOTER if @options[:analyze]
+
+      nil
+    end
+
+    def warn_unused_buffers
+      return unless @options[:buffers] && !@options[:analyze]
+
+      @error.puts("benedictus: --buffers is ignored without --analyze")
+    end
+  end
+end

data/lib/benedictus/safety_guard.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Benedictus
+  class SafetyGuard
+    DATA_MODIFYING_CTE = /\b(insert|update|delete|merge|truncate)\b/i
+
+    def self.assert_select!(sql)
+      normalized = normalize(sql)
+
+      reject_multi_statement!(normalized)
+
+      keyword = first_keyword(normalized)
+
+      return if keyword.casecmp("SELECT").zero?
+      return if keyword.casecmp("WITH").zero? && contains_no_data_modifying_cte?(normalized)
+
+      raise Benedictus::UnsafeQueryError,
+            "--analyze can only be used with SELECT queries (got: #{keyword.empty? ? "?" : keyword}...)"
+    end
+
+    def self.with_rollback(klass)
+      unless klass.respond_to?(:transaction) && active_record_class?(klass)
+        raise ArgumentError, "klass must be an ActiveRecord::Base subclass"
+      end
+
+      result = nil
+      klass.transaction(requires_new: true) do
+        result = yield
+        raise ActiveRecord::Rollback
+      end
+      result
+    end
+
+    def self.active_record_class?(klass)
+      return false unless defined?(ActiveRecord::Base)
+      return false unless klass.is_a?(Class)
+
+      klass <= ActiveRecord::Base
+    rescue TypeError, ArgumentError
+      false
+    end
+
+    # Replaces SQL string literals (single-quoted, dollar-quoted) and comments
+    # (line `--`, nested block `/* */`) with single spaces, preserving token
+    # boundaries. The result has identical keyword structure to the original
+    # but cannot bypass keyword scans by hiding payloads in comments or
+    # string literals.
+    def self.normalize(sql)
+      result = String.new
+      i = 0
+      n = sql.length
+
+      while i < n
+        c = sql[i]
+        nxt = sql[i + 1]
+
+        if c == "'"
+          i = skip_single_quoted(sql, i)
+          result << " "
+        elsif c == "$" && (tag = match_dollar_tag(sql, i))
+          i = skip_dollar_quoted(sql, i, tag)
+          result << " "
+        elsif c == "-" && nxt == "-"
+          i = sql.index("\n", i + 2) || n
+          result << " "
+        elsif c == "/" && nxt == "*"
+          i = skip_nested_block_comment(sql, i)
+          result << " "
+        else
+          result << c
+          i += 1
+        end
+      end
+
+      result
+    end
+
+    def self.first_keyword(normalized)
+      normalized.lstrip[/\A[A-Za-z_]+/].to_s
+    end
+
+    def self.reject_multi_statement!(normalized)
+      trimmed = normalized.rstrip
+      trimmed = trimmed.chomp(";").rstrip if trimmed.end_with?(";")
+
+      return unless trimmed.include?(";")
+
+      raise Benedictus::UnsafeQueryError,
+            "--analyze refuses multi-statement SQL (found ';' between statements)"
+    end
+
+    def self.contains_no_data_modifying_cte?(normalized)
+      !DATA_MODIFYING_CTE.match?(normalized)
+    end
+
+    def self.skip_single_quoted(sql, start)
+      i = start + 1
+      n = sql.length
+
+      while i < n
+        if sql[i] == "'" && sql[i + 1] == "'"
+          i += 2
+        elsif sql[i] == "'"
+          return i + 1
+        else
+          i += 1
+        end
+      end
+
+      n
+    end
+
+    def self.match_dollar_tag(sql, i)
+      m = sql[i..].match(/\A\$([A-Za-z_]\w*)?\$/)
+      m && m[0]
+    end
+
+    def self.skip_dollar_quoted(sql, start, tag)
+      i = start + tag.length
+      end_idx = sql.index(tag, i)
+      end_idx ? end_idx + tag.length : sql.length
+    end
+
+    def self.skip_nested_block_comment(sql, start)
+      i = start + 2
+      depth = 1
+      n = sql.length
+
+      while i < n && depth.positive?
+        if sql[i] == "/" && sql[i + 1] == "*"
+          depth += 1
+          i += 2
+        elsif sql[i] == "*" && sql[i + 1] == "/"
+          depth -= 1
+          i += 2
+        else
+          i += 1
+        end
+      end
+
+      i
+    end
+  end
+end

data/lib/benedictus/sql_formatter.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module SqlFormatter
+    INDENT = "  "
+
+    BLOCK_KEYWORDS = [
+      "WITH RECURSIVE", "WITH",
+      "SELECT DISTINCT", "SELECT",
+      "FROM",
+      "INNER JOIN",
+      "LEFT OUTER JOIN", "LEFT JOIN",
+      "RIGHT OUTER JOIN", "RIGHT JOIN",
+      "FULL OUTER JOIN", "FULL JOIN",
+      "CROSS JOIN", "JOIN",
+      "WHERE", "GROUP BY", "ORDER BY", "HAVING",
+      "LIMIT", "OFFSET",
+      "UNION ALL", "UNION", "INTERSECT", "EXCEPT",
+      "RETURNING"
+    ].freeze
+
+    INLINE_KEYWORDS = %w[
+      ON AS AND OR NOT IN IS LIKE ILIKE BETWEEN
+      NULL TRUE FALSE
+      ASC DESC NULLS FIRST LAST
+      USING CASE WHEN THEN ELSE END
+      DISTINCT ALL ANY EXISTS INTERVAL
+    ].freeze
+
+    # ASCII placeholder delimiters chosen so they cannot appear in
+    # well-formed SQL or in keyword names. Using printable ASCII keeps
+    # the file text-classifiable (no control bytes).
+    PLACEHOLDER_OPEN  = "[[!benedictus-mask:"
+    PLACEHOLDER_CLOSE = "!]]"
+    PLACEHOLDER_RE    = /\[\[!benedictus-mask:(\d+)!\]\]/
+
+    class << self
+      def format(sql)
+        return "" if sql.nil? || sql.empty?
+
+        masked, literals = mask_literals(sql.to_s)
+        upcased = uppercase_keywords(masked)
+        broken  = break_blocks(upcased)
+        restore(broken, literals).strip
+      rescue StandardError
+        sql.to_s
+      end
+
+      private
+
+      def mask_literals(sql)
+        literals = []
+        out = +""
+        i = 0
+        n = sql.length
+
+        while i < n
+          j = scan_protected_run(sql, i, n)
+
+          if j > i
+            literals << sql[i...j]
+            out << "#{PLACEHOLDER_OPEN}#{literals.length - 1}#{PLACEHOLDER_CLOSE}"
+            i = j
+          else
+            out << sql[i]
+            i += 1
+          end
+        end
+
+        [out, literals]
+      end
+
+      def scan_protected_run(sql, i, n)
+        case sql[i]
+        when "'" then scan_single_quoted(sql, i, n)
+        when '"' then scan_double_quoted(sql, i, n)
+        when "-" then sql[i + 1] == "-" ? (sql.index("\n", i) || n) : i
+        when "/" then sql[i + 1] == "*" ? scan_block_comment(sql, i, n) : i
+        when "$" then scan_dollar_quoted(sql, i, n)
+        else i
+        end
+      end
+
+      def scan_single_quoted(sql, i, n)
+        j = i + 1
+        while j < n
+          if sql[j] == "'" && sql[j + 1] == "'"
+            j += 2
+          elsif sql[j] == "'"
+            return j + 1
+          else
+            j += 1
+          end
+        end
+        n
+      end
+
+      def scan_double_quoted(sql, i, n)
+        j = i + 1
+        while j < n
+          if sql[j] == '"' && sql[j + 1] == '"'
+            j += 2
+          elsif sql[j] == '"'
+            return j + 1
+          else
+            j += 1
+          end
+        end
+        n
+      end
+
+      def scan_block_comment(sql, i, n)
+        depth = 1
+        j = i + 2
+        while j < n && depth.positive?
+          if sql[j] == "/" && sql[j + 1] == "*"
+            depth += 1
+            j += 2
+          elsif sql[j] == "*" && sql[j + 1] == "/"
+            depth -= 1
+            j += 2
+          else
+            j += 1
+          end
+        end
+        j
+      end
+
+      def scan_dollar_quoted(sql, i, _n)
+        m = sql[i..].match(/\A\$([A-Za-z0-9_]*)\$/)
+        return i unless m
+
+        close = "$#{m[1]}$"
+        j     = sql.index(close, i + m[0].length)
+        return i unless j
+
+        j + close.length
+      end
+
+      def uppercase_keywords(s)
+        (BLOCK_KEYWORDS + INLINE_KEYWORDS).each do |kw|
+          s = s.gsub(/\b#{Regexp.escape(kw)}\b/i, kw)
+        end
+        s
+      end
+
+      def break_blocks(s)
+        union = BLOCK_KEYWORDS
+                .sort_by { |k| -k.length }
+                .map { |k| "\\b#{Regexp.escape(k)}\\b" }
+                .join("|")
+        re = /\s*(#{union})\s*/
+        s.gsub(re) { "\n#{Regexp.last_match(1)}\n#{INDENT}" }
+      end
+
+      def restore(s, literals)
+        s.gsub(PLACEHOLDER_RE) { literals[Regexp.last_match(1).to_i] }
+      end
+    end
+  end
+end

data/lib/benedictus/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Benedictus
+  VERSION = "0.2.0"
+end

data/lib/benedictus.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "benedictus/version"
+require_relative "benedictus/errors"
+require_relative "benedictus/color"
+require_relative "benedictus/sql_formatter"
+require_relative "benedictus/plan/node"
+require_relative "benedictus/plan/tree"
+require_relative "benedictus/plan/parser"
+require_relative "benedictus/heuristics/warning"
+require_relative "benedictus/heuristics/base"
+require_relative "benedictus/heuristics/seq_scan_on_large_table"
+require_relative "benedictus/heuristics/row_estimate_drift"
+require_relative "benedictus/heuristics/external_sort"
+require_relative "benedictus/heuristics/nested_loop_blowup"
+require_relative "benedictus/heuristics/expensive_per_row_scan"
+require_relative "benedictus/heuristics/registry"
+require_relative "benedictus/renderers/tree_renderer"
+require_relative "benedictus/renderers/json_renderer"
+require_relative "benedictus/renderers/raw_renderer"
+require_relative "benedictus/safety_guard"
+require_relative "benedictus/plan_runner"
+require_relative "benedictus/expression_evaluator"
+require_relative "benedictus/relation_resolver"
+require_relative "benedictus/rails_loader"
+require_relative "benedictus/runner"
+require_relative "benedictus/cli"
+
+module Benedictus
+end