rails_vitals 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82d62304d92259c9c248b8033948784ba6bb5075d7f7af627c445624a042901a
-  data.tar.gz: 6285bf97528093389e861f96bb45259d434e336042c7d23e30fab02109e690ce
+  metadata.gz: c655986f52ddc0e0848b8e67c28d603ccea2a97dc6b85d9157a7a670fd298fc6
+  data.tar.gz: 49bbb1b8fc0041bd75edb7d3d990ed517dcd907f64b7f99af95eb2d33dbdee80
 SHA512:
-  metadata.gz: 0ae1ce76d1ac8c1bbf7559a119e1680f87b40faafe989f0e6c6afb9ec5f3cb8c374a1899a32ca28f04d39ee7ddb4e6f4b73251f16835c8a9587590ecc6ff6cc8
-  data.tar.gz: 48245cadf704dc9bced9103cad91485d0b9b1c1173b11b50fd79b8964259cb41eaba8af42ff86ca95c1d6ba16ddc52e1f88120159317065e36fb2a4c53d10792
+  metadata.gz: 7e905ff8aa217f398c7521b677c088f637b5483cd153af51db1453fbee560476d32b230a3a9d432d975910f60fd9992cd4368a79b6be07abb4a6f676cff5c866
+  data.tar.gz: fcd80c62bc58c1adfed045eb3764f29918705d6b9e0952af68f0f2601197f3af5079ca5abbe62aa6361c950b188711102f96ba3e36b28fa2766138b1fb69ce1d

data/app/controllers/rails_vitals/playgrounds_controller.rb

@@ -13,7 +13,7 @@ module RailsVitals
       access_associations = Array(params[:access_associations]).reject(&:blank?)
 
       result = Playground::Sandbox.run(
-        expression,
+        clean_expr,
         access_associations: access_associations
       )
 

data/app/helpers/rails_vitals/application_helper.rb

@@ -104,6 +104,16 @@ module RailsVitals
       }[risk.to_sym] || COLOR_NEUTRAL
     end
 
+    # Returns a hex color for EXPLAIN warning severity (:danger, :warning, :info)
+    def explain_severity_color(severity)
+      case severity&.to_sym
+      when :danger  then COLOR_LIGHT_RED
+      when :warning then COLOR_ORANGE
+      when :info    then "#90cdf4"
+      else               COLOR_ORANGE
+      end
+    end
+
     # Returns a readable hex text color for a numeric health score (0-100)
     def score_text_color(score)
       case score.to_i

data/app/views/rails_vitals/explains/show.html.erb

@@ -50,7 +50,7 @@
       </div>
 
       <% @result.warnings.each do |w| %>
-        <% severity_color = w[:severity] == :danger ? "#fc8181" : "#f6ad55" %>
+        <% severity_color = explain_severity_color(w[:severity]) %>
 
         <div
           style="background:#1a202c;border-left:3px solid <%= severity_color %>;
@@ -81,6 +81,13 @@
             <div class="text-muted">
               Nested Loop processed a large number of rows. Verify join columns are indexed.
             </div>
+          <% when :function_call %>
+            <div class="bold mb-4" style="color:<%= severity_color %>;">
+              Function Call Detected
+            </div>
+            <div class="text-muted">
+              <%= w[:message] %>
+            </div>
           <% end %>
         </div>
       <% end %>

data/lib/rails_vitals/analyzers/explain_analyzer.rb

@@ -10,7 +10,14 @@ module RailsVitals
       COLOR_NEUTRAL = "#a0aec0"
       COLOR_COOL = "#76e4f7"
 
-      # Node types and their risk/education metadata
+      # ─── Result / PlanNode structs ────────────────────────────────────────────────
+
+      Result = Struct.new(
+        :sql, :plan, :warnings, :suggestions,
+        :total_cost, :actual_time_ms, :rows_examined,
+        :interpretation, :error, :function_calls, :dry_run_result,
+        keyword_init: true
+      )
       NODE_METADATA = {
         "Seq Scan" => {
           risk: :danger,
@@ -114,12 +121,7 @@ module RailsVitals
         }
       }.freeze
 
-      Result = Struct.new(
-        :sql, :plan, :warnings, :suggestions,
-        :total_cost, :actual_time_ms, :rows_examined,
-        :interpretation, :error,
-        keyword_init: true
-      )
+      # ─── Safe SQL analysis ───────────────────────────────────────────────────────
 
       PlanNode = Struct.new(
         :node_type, :relation, :alias_name,
@@ -132,15 +134,34 @@ module RailsVitals
         keyword_init: true
       )
 
+      ALLOWED_FUNCTIONS = %w[
+        COUNT SUM AVG MIN MAX
+        COALESCE NULLIF
+        NOW CURRENT_TIMESTAMP CURRENT_DATE CURRENT_TIME LOCALTIMESTAMP LOCALTIME
+        EXTRACT DATE_PART DATE_TRUNC AGE
+        UPPER LOWER TRIM LENGTH SUBSTRING CONCAT REPLACE POSITION REVERSE
+        ROUND FLOOR CEIL ABS MOD POWER SQRT
+        GREATEST LEAST CAST
+        ROW_NUMBER RANK DENSE_RANK LAG LEAD FIRST_VALUE LAST_VALUE NTILE
+        ARRAY_AGG STRING_AGG
+        JSON_EXTRACT_PATH_TEXT JSONB_EXTRACT_PATH
+      ].freeze
+
+      FUNCTION_CALL_PATTERN = /\b(?!#{ALLOWED_FUNCTIONS.join('|')}\b)[a-zA-Z_]\w*\s*\(/
+
       def self.analyze(sql, binds: [])
         return unsupported_env unless supported_environment?
         return unsupported_sql unless select_query?(sql)
 
         safe_sql = substitute_binds(sql, binds)
+        has_function_calls = contains_function_calls?(safe_sql)
 
-        raw = ActiveRecord::Base.connection.execute(
+        dry_run_result = dry_run(safe_sql)
+        return dry_run_result if dry_run_result.error
+
+        raw = exec_in_read_only_transaction(
           "EXPLAIN (FORMAT JSON, ANALYZE true, BUFFERS false) #{safe_sql}"
-        ).first["QUERY PLAN"]
+        )
 
         plan_json = JSON.parse(raw)
         root_plan = plan_json.first["Plan"]
@@ -150,6 +171,14 @@ module RailsVitals
         warnings = extract_warnings(root_node)
         suggestions = build_suggestions(warnings, root_node)
 
+        if has_function_calls
+          warnings << {
+            type: :function_call,
+            severity: :info,
+            message: "Query contains function calls — executed inside a read-only transaction that prevents writes"
+          }
+        end
+
         result = Result.new(
           sql: safe_sql,
           plan: root_node,
@@ -158,6 +187,8 @@ module RailsVitals
           total_cost: root_plan["Total Cost"]&.round(2),
           actual_time_ms: exec_time,
           rows_examined: count_rows_examined(root_plan),
+          function_calls: has_function_calls,
+          dry_run_result: dry_run_result,
           error: nil
         )
 
@@ -169,6 +200,28 @@ module RailsVitals
                    actual_time_ms: nil, rows_examined: nil)
       end
 
+      def self.dry_run(sql, binds: [])
+        safe_sql = substitute_binds(sql, binds)
+
+        raw = exec_in_read_only_transaction(
+          "EXPLAIN (FORMAT JSON, ANALYZE false, BUFFERS false) #{safe_sql}"
+        )
+
+        plan_json = JSON.parse(raw)
+        root_plan = plan_json.first["Plan"]
+
+        Result.new(
+          sql: safe_sql,
+          total_cost: root_plan["Total Cost"]&.round(2),
+          plan: build_node(root_plan),
+          error: nil
+        )
+      rescue => e
+        Result.new(error: e.message, sql: sql, plan: nil,
+                   warnings: [], suggestions: [], total_cost: nil,
+                   actual_time_ms: nil, rows_examined: nil)
+      end
+
       private
 
       def self.supported_environment?
@@ -179,6 +232,35 @@ module RailsVitals
         sql.strip.match?(/\ASELECT/i)
       end
 
+      def self.contains_function_calls?(sql)
+        clean = sql.gsub(/'.*?(?:''|')/, "").gsub(/".*?"/, "")
+        clean.match?(FUNCTION_CALL_PATTERN)
+      end
+
+      def self.exec_in_read_only_transaction(sql)
+        if postgresql?
+          connection = ActiveRecord::Base.connection
+          connection.execute("BEGIN")
+          connection.execute("SET TRANSACTION READ ONLY")
+          begin
+            result = connection.execute(sql)
+            connection.execute("COMMIT")
+            result.first["QUERY PLAN"]
+          rescue => e
+            connection.execute("ROLLBACK") rescue nil
+            raise e
+          end
+        else
+          ActiveRecord::Base.connection.execute(sql).first["QUERY PLAN"]
+        end
+      end
+
+      def self.postgresql?
+        ActiveRecord::Base.connection.adapter_name.match?(/postgresql/i)
+      rescue
+        false
+      end
+
       def self.substitute_binds(sql, binds)
         # Replace $1, $2 placeholders with safe literal values
         result = sql.dup
@@ -334,6 +416,10 @@ module RailsVitals
           parts << "Sequential scan detected — missing index is causing full table reads"
         end
 
+        if result.function_calls
+          parts << "Query uses function calls — executed in a read-only transaction that prevents writes"
+        end
+
         if result.actual_time_ms.to_f > 100
           parts << "query took #{result.actual_time_ms}ms — above the 100ms warning threshold"
         end

data/lib/rails_vitals/mcp/tools/explain_query.rb

@@ -39,7 +39,14 @@ module RailsVitals
           return missing_sql_response if sql.nil? || sql.strip.empty?
           return rejected_sql_response(sql) if dml_present?(sql)
 
-          result = Analyzers::ExplainAnalyzer.analyze(sql.strip)
+          cleaned_sql = sql.strip
+
+          cost_estimate = Analyzers::ExplainAnalyzer.dry_run(cleaned_sql)
+          if cost_estimate.error
+            return error_response("Cost estimate failed: #{cost_estimate.error}")
+          end
+
+          result = Analyzers::ExplainAnalyzer.analyze(cleaned_sql)
 
           return error_response(result.error) if result.error
 
@@ -48,6 +55,11 @@ module RailsVitals
             total_cost: result.total_cost,
             actual_time_ms: result.actual_time_ms,
             rows_examined: result.rows_examined,
+            cost_estimate: {
+              total_cost: cost_estimate.total_cost,
+              note: "Cost estimate from dry-run EXPLAIN (ANALYZE was not executed for this estimate)"
+            },
+            function_calls: result.function_calls,
             warnings: serialize_warnings(result.warnings),
             suggestions: serialize_suggestions(result.suggestions),
             interpretation: result.interpretation

data/lib/rails_vitals/playground/safe_chain_builder.rb

@@ -0,0 +1,292 @@
+require "strscan"
+
+module RailsVitals
+  module Playground
+    class SafeChainBuilder
+      ALLOWED_METHODS = %w[
+        all where select limit offset order group
+        includes preload eager_load joins left_joins
+        find find_by first last count sum average
+        pluck distinct having references unscoped not
+      ].freeze
+
+      DISALLOWED_CLASS_METHODS = %w[
+        connection execute exec system eval send public_send __send__
+        instance_eval class_eval module_eval define_method method_missing
+        delete destroy delete_all destroy_all update_all
+      ].freeze
+
+      ParseError = Class.new(StandardError)
+
+      def self.build(chain_str, model)
+        relation = model.all
+        parse_chain(chain_str).each do |method_name, args|
+          if DISALLOWED_CLASS_METHODS.include?(method_name)
+            raise ParseError, "Method '#{method_name}' is not allowed for security reasons"
+          end
+          unless ALLOWED_METHODS.include?(method_name)
+            raise ParseError, "Method '#{method_name}' is not allowed. Allowed: #{ALLOWED_METHODS.join(', ')}"
+          end
+          relation = relation.public_send(method_name, *args)
+        end
+
+        raise ParseError, "Expression must return an ActiveRecord::Relation" unless relation.is_a?(ActiveRecord::Relation)
+        relation
+      end
+
+      private
+
+      def self.parse_chain(str)
+        scanner = StringScanner.new(str)
+        calls = []
+        scanner.skip(/\s+/)
+
+        until scanner.eos?
+          scanner.skip(/\.\s*/)
+
+          name = scanner.scan(/[a-z_][a-zA-Z0-9_!?]*/)
+          raise ParseError, "Expected method name at position #{scanner.pos}" unless name
+
+          scanner.skip(/\s+/)
+          if scanner.scan(/\(/)
+            args = parse_args(scanner)
+            scanner.skip(/\s*\)/)
+            calls << [ name, args ]
+          else
+            calls << [ name, [] ]
+          end
+          scanner.skip(/\s+/)
+        end
+
+        calls
+      end
+
+      def self.parse_args(scanner)
+        args = []
+        scanner.skip(/\s+/)
+        return args if scanner.eos? || scanner.peek(1) == ")"
+
+        loop do
+          scanner.skip(/\s+/)
+          break if scanner.eos? || scanner.peek(1) == ")"
+
+          if keyword_hash_start?(scanner)
+            args << scan_keyword_hash(scanner)
+          else
+            args << scan_value(scanner)
+          end
+
+          scanner.skip(/\s+/)
+          break unless scanner.scan(/,/)
+        end
+
+        args
+      end
+
+      def self.keyword_hash_start?(scanner)
+        pos = scanner.pos
+        ident = scanner.scan(/[a-zA-Z_][a-zA-Z0-9_]*/)
+        return false unless ident
+
+        scanner.skip(/\s*/)
+
+        if scanner.scan(/:/) && !scanner.scan(/:/)
+          scanner.pos = pos
+          return true
+        end
+
+        scanner.pos = pos
+        false
+      end
+
+      def self.scan_keyword_hash(scanner)
+        hash = {}
+        loop do
+          scanner.skip(/\s+/)
+          break if scanner.eos? || scanner.peek(1) == ")" || scanner.peek(1) == "}"
+
+          key = scanner.scan(/[a-zA-Z_][a-zA-Z0-9_]*/)
+          raise ParseError, "Expected hash key" unless key
+          scanner.skip(/\s*:\s*/)
+          value = scan_value(scanner)
+          hash[key.to_sym] = value
+          scanner.skip(/\s+/)
+          break unless scanner.scan(/,/)
+        end
+        hash
+      end
+
+      def self.scan_value(scanner)
+        scanner.skip(/\s+/)
+        ch = scanner.peek(1)
+        raise ParseError, "Unexpected end of expression" unless ch
+
+        case ch
+        when "'" then scan_single_quoted_string(scanner)
+        when '"' then scan_double_quoted_string(scanner)
+        when ":" then scan_symbol(scanner)
+        when "t"
+          if scanner.scan(/true\b/)
+            true
+          else
+            raise ParseError, "Unexpected token at position #{scanner.pos}"
+          end
+        when "f"
+          if scanner.scan(/false\b/)
+            false
+          else
+            raise ParseError, "Unexpected token at position #{scanner.pos}"
+          end
+        when "n"
+          if scanner.scan(/nil\b/)
+            nil
+          else
+            raise ParseError, "Unexpected token at position #{scanner.pos}"
+          end
+        when "[" then scan_array(scanner)
+        when "{" then scan_hash_literal(scanner)
+        when "-", "+", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9" then scan_number(scanner)
+        else
+          raise ParseError, "Unexpected token '#{ch}' at position #{scanner.pos}"
+        end
+      end
+
+      def self.scan_single_quoted_string(scanner)
+        scanner.pos += 1
+        result = +""
+        until scanner.eos?
+          case scanner.peek(1)
+          when "'"
+            scanner.pos += 1
+            return result
+          when "\\"
+            scanner.pos += 1
+            escaped = scanner.getch
+            case escaped
+            when "'" then result << "'"
+            when "\\" then result << "\\"
+            else result << "\\#{escaped}"
+            end
+          else
+            result << scanner.getch
+          end
+        end
+        raise ParseError, "Unterminated single-quoted string"
+      end
+
+      def self.scan_double_quoted_string(scanner)
+        scanner.pos += 1
+        result = +""
+        until scanner.eos?
+          case scanner.peek(1)
+          when '"'
+            scanner.pos += 1
+            return result
+          when "\\"
+            scanner.pos += 1
+            escaped = scanner.getch
+            case escaped
+            when '"' then result << '"'
+            when "\\" then result << "\\"
+            when "n" then result << "\n"
+            when "t" then result << "\t"
+            when "r" then result << "\r"
+            when "#" then result << "#"
+            else result << "\\#{escaped}"
+            end
+          else
+            result << scanner.getch
+          end
+        end
+        raise ParseError, "Unterminated double-quoted string"
+      end
+
+      def self.scan_symbol(scanner)
+        scanner.pos += 1
+        if scanner.scan(/[a-zA-Z_][a-zA-Z0-9_]*/)
+          scanner.matched.to_sym
+        elsif (str = scanner.scan(/"[^"]*"/) || scanner.scan(/'[^']*'/))
+          str[1..-2].to_sym
+        else
+          raise ParseError, "Invalid symbol at position #{scanner.pos}"
+        end
+      end
+
+      def self.scan_number(scanner)
+        num_str = scanner.scan(/-?[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?/)
+        raise ParseError, "Invalid number at position #{scanner.pos}" unless num_str
+        if num_str.include?(".") || num_str.match?(/[eE]/)
+          num_str.to_f
+        else
+          num_str.to_i
+        end
+      end
+
+      def self.scan_array(scanner)
+        scanner.pos += 1
+        arr = []
+        scanner.skip(/\s+/)
+        unless scanner.peek(1) == "]"
+          loop do
+            arr << scan_value(scanner)
+            scanner.skip(/\s+/)
+            break unless scanner.scan(/,/)
+            scanner.skip(/\s+/)
+          end
+        end
+        scanner.skip(/\s*\]/)
+        raise ParseError, "Unterminated array" unless scanner.matched
+        arr
+      end
+
+      def self.scan_hash_literal(scanner)
+        scanner.pos += 1
+        hash = {}
+        scanner.skip(/\s+/)
+        unless scanner.eos? || scanner.peek(1) == "}"
+          loop do
+            scanner.skip(/\s+/)
+            break if scanner.eos? || scanner.peek(1) == "}"
+
+            key = parse_hash_key(scanner)
+            scanner.skip(/\s+/)
+
+            if scanner.scan(/=>/)
+              scanner.skip(/\s+/)
+              hash[key] = scan_value(scanner)
+            elsif scanner.scan(/:\s*/)
+              hash[key.to_sym] = scan_value(scanner)
+            else
+              raise ParseError, "Expected '=>' or ':' after hash key"
+            end
+
+            scanner.skip(/\s+/)
+            break unless scanner.scan(/,/)
+          end
+        end
+        scanner.skip(/\s*}/)
+        raise ParseError, "Unterminated hash" unless scanner.matched
+        hash
+      end
+
+      def self.parse_hash_key(scanner)
+        case scanner.peek(1)
+        when '"', "'" then scan_string(scanner)
+        when ":" then scan_symbol(scanner)
+        else
+          ident = scanner.scan(/[a-zA-Z_][a-zA-Z0-9_]*/)
+          raise ParseError, "Expected hash key" unless ident
+          ident
+        end
+      end
+
+      def self.scan_string(scanner)
+        case scanner.peek(1)
+        when "'" then scan_single_quoted_string(scanner)
+        when '"' then scan_double_quoted_string(scanner)
+        else raise ParseError, "Expected string"
+        end
+      end
+    end
+  end
+end

data/lib/rails_vitals/playground/sandbox.rb

@@ -1,19 +1,16 @@
 module RailsVitals
   module Playground
     class Sandbox
-      ALLOWED_METHODS = %w[
-        all where select limit offset order group
-        includes preload eager_load joins left_joins
-        find find_by first last count sum average
-        pluck distinct having references unscoped
-      ].freeze
-
       BLOCKED_PATTERNS = [
         /\b(insert|update|delete|destroy|drop|truncate|create|alter)\b/i,
         /\.save/i, /\.save!/i, /\.update/i, /\.delete/i,
         /\.destroy/i, /`/
       ].freeze
 
+      SAFE_EXPRESSION_PATTERN = /\A[a-zA-Z0-9_\.\s\(\),:\[\]{}'"!?=<>|&*+\-\/\\%]+\z/
+
+      ASSOCIATION_NAME_PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
       DEFAULT_LIMIT = 100
 
       Result = Struct.new(
@@ -26,6 +23,13 @@ module RailsVitals
       def self.run(expression, access_associations: [])
         return blocked_result("No expression provided") if expression.blank?
 
+        expression = expression.gsub(/#[^\n]*/, "").strip
+        return blocked_result("No expression provided") if expression.blank?
+
+        return blocked_result(
+          "Expression contains invalid characters."
+        ) unless expression.match?(SAFE_EXPRESSION_PATTERN)
+
         BLOCKED_PATTERNS.each do |pattern|
           return blocked_result(
             "Expression contains blocked operation. " \
@@ -33,6 +37,10 @@ module RailsVitals
           ) if expression.match?(pattern)
         end
 
+        access_associations = access_associations.select do |name|
+          name.to_s.match?(ASSOCIATION_NAME_PATTERN)
+        end
+
         model_name = extract_model_name(expression)
         return blocked_result(
           "Could not detect model from expression. " \
@@ -111,10 +119,7 @@ module RailsVitals
       end
 
       def self.extract_model_name(expression)
-        # Strip comments first
-        clean = expression.gsub(/#[^\n]*/, "").strip
-        # First word before a dot or whitespace — must look like a constant (CamelCase)
-        match = clean.match(/\A([A-Z][A-Za-z0-9]*)/)
+        match = expression.match(/\A([A-Z][A-Za-z0-9]*)/)
         match ? match[1] : nil
       end
 
@@ -132,31 +137,15 @@ module RailsVitals
       end
 
       def self.build_relation(expression, model)
-        # Parse "Post.includes(:likes).where(published: true).limit(10)"
-        # Strip the model name prefix if present
         chain_str = expression
           .sub(/\A#{Regexp.escape(model.name)}\s*\.?\s*/, "")
           .strip
 
         return model.all if chain_str.blank?
 
-        # Build the chain by safe eval within a controlled binding
-        # Only the model constant is exposed, no access to app globals
-        sandbox_binding = build_binding(model)
-        relation = eval(chain_str, sandbox_binding) # rubocop:disable Security/Eval
-
-        unless relation.is_a?(ActiveRecord::Relation)
-          raise "Expression must return an ActiveRecord::Relation"
-        end
-
-        relation
-      end
-
-      def self.build_binding(model)
-        # Create a minimal binding with only the model exposed
-        ctx = Object.new
-        ctx.define_singleton_method(:relation) { model.all }
-        ctx.instance_eval { binding }
+        SafeChainBuilder.build(chain_str, model)
+      rescue SafeChainBuilder::ParseError => e
+        raise "Expression error: #{e.message}"
       end
 
       def self.apply_limit(relation)

data/lib/rails_vitals/version.rb

@@ -1,3 +1,3 @@
 module RailsVitals
-  VERSION = "0.6.0"
+  VERSION = "0.6.2"
 end

data/lib/rails_vitals.rb

@@ -14,6 +14,7 @@ require "rails_vitals/scorers/base_scorer"
 require "rails_vitals/scorers/query_scorer"
 require "rails_vitals/scorers/n_plus_one_scorer"
 require "rails_vitals/scorers/composite_scorer"
+require "rails_vitals/playground/safe_chain_builder"
 require "rails_vitals/playground/sandbox"
 require "rails_vitals/panel_renderer"
 require "rails_vitals/middleware/panel_injector"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_vitals
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.2
 platform: ruby
 authors:
 - David Sanchez
@@ -95,6 +95,7 @@ files:
 - lib/rails_vitals/middleware/panel_injector.rb
 - lib/rails_vitals/notifications/subscriber.rb
 - lib/rails_vitals/panel_renderer.rb
+- lib/rails_vitals/playground/safe_chain_builder.rb
 - lib/rails_vitals/playground/sandbox.rb
 - lib/rails_vitals/request_record.rb
 - lib/rails_vitals/scorers/base_scorer.rb