rails_vitals 0.6.1 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce21f0b9edbbef2e18452c51755bf980c067c92afb651a86ee99b78aac0cbe6d
-  data.tar.gz: 0ee7cddd129757762d01cdce2f049622bb6f449e44de05ff5d592bfd4933136d
+  metadata.gz: a4479577c80975bad32203d017cff00cf4070589c6059424b393796bb5f4b7a2
+  data.tar.gz: e96412a5354e3e79ae97e4957a8e4c96372ffabb705fb8cb52251bb9348a4d9d
 SHA512:
-  metadata.gz: 201b26e862cafbde3dfe07f1011ceb3d8241f362ff5386cbae8edbe5e0a250aa99ac800fd4c3d57d9984beec6f54348c78bd7a13f5265cae6a390d137494348e
-  data.tar.gz: de6f0ff8c15da14e155850368884cd14830dce374505ad098f8c3a902865d16ad7d42bd17a38ba51561b3e2fb829e73b03abf2530f16873f6249b1782da4ccc5
+  metadata.gz: 9d7f670412fc9caaf74d8310161f246eb5d7f2d20a433a9eae01fa10350602afcfabbddb89048920b54a136001d0aaee0338c642ca6826dff3a8a99f133ee175
+  data.tar.gz: b46385277f03c958362eff854389098c921f6b7bdaf490ddbb41212c255a14c60c3c48c45c7a10fd290361dbd58d9a8619865c154b2a020b7daeb6bc342e9b66

data/app/controllers/rails_vitals/mcp_controller.rb

@@ -13,11 +13,12 @@ module RailsVitals
     private
 
     def verify_environment
-      if Rails.env.production?
+      unless RailsVitals.config.permitted_environment?
         render json: ResponseBuilder.error(
           nil,
           ResponseBuilder::AUTH_ERROR,
-          "RailsVitals MCP is not available in production"
+          "RailsVitals MCP is not available in this environment. " \
+          "Permitted: #{RailsVitals::Configuration::PERMITTED_ENVIRONMENTS.join(', ')}"
         ), status: :forbidden
       end
     end

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

@@ -1,8 +1,6 @@
 module RailsVitals
   module Analyzers
     class ExplainAnalyzer
-      SUPPORTED_ENVIRONMENTS = %w[development test].freeze
-
       COLOR_DANGER = "#fc8181"
       COLOR_HEALTHY = "#68d391"
       COLOR_WARNING = "#f6ad55"
@@ -10,7 +8,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 +119,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 +132,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)
+
+        dry_run_result = dry_run(safe_sql)
+        return dry_run_result if dry_run_result.error
 
-        raw = ActiveRecord::Base.connection.execute(
+        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 +169,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 +185,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,16 +198,67 @@ 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?
-        SUPPORTED_ENVIRONMENTS.include?(Rails.env.to_s)
+        RailsVitals.config&.permitted_environment? || false
       end
 
       def self.select_query?(sql)
         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
@@ -311,7 +391,8 @@ module RailsVitals
 
       def self.unsupported_env
         Result.new(
-          error: "EXPLAIN is only available in development and test environments.",
+          error: "EXPLAIN is only available in permitted environments: " \
+                 "#{RailsVitals::Configuration::PERMITTED_ENVIRONMENTS.join(', ')}.",
           sql: nil, plan: nil, warnings: [], suggestions: [],
           total_cost: nil, actual_time_ms: nil, rows_examined: nil
         )
@@ -334,6 +415,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/configuration.rb

@@ -15,8 +15,10 @@ module RailsVitals
                   :mcp_max_log_size,
                   :mcp_slow_query_threshold_ms
 
+    PERMITTED_ENVIRONMENTS = %w[development test].freeze
+
     def initialize
-      @enabled                  = defined?(Rails) && !Rails.env.production?
+      @enabled                  = defined?(Rails) && permitted_environment?
       @store_size               = 200
       @store_enabled            = true
       @auth                     = :none
@@ -33,5 +35,9 @@ module RailsVitals
       @mcp_max_log_size            = 100
       @mcp_slow_query_threshold_ms = 100
     end
+
+    def permitted_environment?
+      PERMITTED_ENVIRONMENTS.include?(Rails.env.to_s)
+    end
   end
 end

data/lib/rails_vitals/engine.rb

@@ -16,7 +16,10 @@ module RailsVitals
 
     initializer "rails_vitals.mcp" do
       if RailsVitals.config.mcp_enabled
-        raise "RailsVitals MCP cannot run in production" if Rails.env.production?
+        unless RailsVitals.config.permitted_environment?
+          raise "RailsVitals MCP cannot run in #{Rails.env} environment. " \
+                "Permitted: #{RailsVitals::Configuration::PERMITTED_ENVIRONMENTS.join(', ')}"
+        end
 
         require "rails_vitals/mcp/auth"
         require "rails_vitals/mcp/response_builder"

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/sandbox.rb

@@ -4,7 +4,14 @@ module RailsVitals
       BLOCKED_PATTERNS = [
         /\b(insert|update|delete|destroy|drop|truncate|create|alter)\b/i,
         /\.save/i, /\.save!/i, /\.update/i, /\.delete/i,
-        /\.destroy/i, /`/
+        /\.destroy/i, /`/,
+        /\.connection\b/i, /\.execute\b/i, /\.exec\b/i,
+        /\.send\b/i, /\.public_send\b/i, /\.__send__\b/i,
+        /\.send_data\b/i, /\.open\b/i,
+        /\.instance_eval\b/i, /\.class_eval\b/i, /\.module_eval\b/i,
+        /\.define_method\b/i, /\.method_missing\b/i,
+        /\bsystem\b/i, /\beval\b/i, /\bfork\b/i, /\bspawn\b/i,
+        /\bIO\b/i, /\bFile\b/i, /\bThread\b/i, /\bProcess\b/i
       ].freeze
 
       SAFE_EXPRESSION_PATTERN = /\A[a-zA-Z0-9_\.\s\(\),:\[\]{}'"!?=<>|&*+\-\/\\%]+\z/

data/lib/rails_vitals/version.rb

@@ -1,3 +1,3 @@
 module RailsVitals
-  VERSION = "0.6.1"
+  VERSION = "0.6.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_vitals
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.3
 platform: ruby
 authors:
 - David Sanchez