chronos-ruby 0.9.0.pre.4 → 1.1.0

data/lib/chronos/core/sql_query_analyzer.rb

@@ -0,0 +1,309 @@
+module Chronos
+  module Core
+    # Derives bounded query-shape evidence and index recommendations from normalized SQL.
+    #
+    # @responsibility Extract tables and access columns, compare index metadata, and emit diagnostics.
+    # @motivation Give the Chronos consumer actionable SQL evidence without collecting binds or raw SQL.
+    # @limits It is a defensive heuristic for SELECT statements, not a dialect-complete parser or optimizer.
+    # @collaborators SqlNormalizer and an optional query-inspection adapter.
+    # @thread_safety Instances are stateless and safe to share.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails and database drivers.
+    # @example
+    #   SqlQueryAnalyzer.new.call("normalized_query" => "SELECT * FROM users WHERE email = ?")
+    # @errors Malformed input returns an empty bounded analysis and never escapes.
+    # @performance Input, tables, columns, candidates, diagnostics, and inspection evidence are capped.
+    class SqlQueryAnalyzer # rubocop:disable Metrics/ClassLength
+      MAX_TABLES = 8
+      MAX_COLUMNS = 12
+      MAX_INDEXES = 20
+      MAX_DIAGNOSTICS = 20
+      IDENTIFIER = "[A-Za-z_][A-Za-z0-9_$]*".freeze
+      TABLE_PATTERN = /\b(?:FROM|JOIN)\s+["`\[]?(#{IDENTIFIER}(?:\.#{IDENTIFIER})?)["`\]]?
+                       (?:\s+(?:AS\s+)?(#{IDENTIFIER}))?/ix
+      CLAUSE_END = /\b(?:GROUP\s+BY|ORDER\s+BY|HAVING|LIMIT|OFFSET|UNION|RETURNING)\b/i
+      RESERVED = %w(WHERE JOIN LEFT RIGHT INNER OUTER FULL CROSS ON GROUP ORDER HAVING LIMIT OFFSET).freeze
+
+      def call(query, inspection = {})
+        data = hash(query)
+        normalized = bounded(data["normalized_query"] || data[:normalized_query], 512)
+        operation = (data["operation"] || data[:operation]).to_s.upcase
+        return empty_analysis(operation) unless operation == "SELECT" && !normalized.empty?
+
+        aliases = table_aliases(normalized, data["table"] || data[:table])
+        access = access_columns(normalized, aliases)
+        candidates = index_candidates(access, hash(inspection))
+        evidence = inspection_evidence(inspection)
+        {
+          "operation" => operation,
+          "tables" => aliases.values.uniq.first(MAX_TABLES),
+          "access_columns" => access,
+          "index_candidates" => candidates,
+          "inspection" => evidence,
+          "diagnostics" => diagnostics(candidates, evidence)
+        }
+      rescue StandardError
+        empty_analysis("UNKNOWN")
+      end
+
+      private
+
+      def empty_analysis(operation)
+        {
+          "operation" => operation.to_s.empty? ? "UNKNOWN" : operation.to_s,
+          "tables" => [], "access_columns" => {}, "index_candidates" => [],
+          "inspection" => {}, "diagnostics" => []
+        }
+      end
+
+      def table_aliases(sql, fallback)
+        result = {}
+        sql.scan(TABLE_PATTERN) do |table, name|
+          alias_name = name.to_s
+          alias_name = table.to_s.split(".").last if alias_name.empty? || RESERVED.include?(alias_name.upcase)
+          result[alias_name] = bounded_identifier(table)
+          break if result.length >= MAX_TABLES
+        end
+        if result.empty? && !fallback.to_s.empty?
+          table = bounded_identifier(fallback)
+          result[table.split(".").last] = table unless table.empty?
+        end
+        result
+      end
+
+      def access_columns(sql, aliases)
+        result = {}
+        aliases.values.uniq.each do |table|
+          result[table] = {"equality" => [], "range" => [], "join" => [], "order" => []}
+        end
+        base_table = aliases.values.first
+        where = clause(sql, /\bWHERE\b/i, CLAUSE_END)
+        collect_predicates(where, aliases, base_table, result)
+        collect_join_predicates(sql, aliases, result)
+        collect_order_columns(clause(sql, /\bORDER\s+BY\b/i, /\b(?:LIMIT|OFFSET|UNION|RETURNING)\b/i), aliases,
+                              base_table, result)
+        result.delete_if { |_table, groups| groups.values.all?(&:empty?) }
+      end
+
+      def collect_predicates(section, aliases, base_table, result)
+        return if section.empty?
+
+        pattern = /(?:(#{IDENTIFIER})\.)?(#{IDENTIFIER})\s*(=|<>|!=|<=|>=|<|>|\bIN\b|\bIS\b|\bLIKE\b)/i
+        section.scan(pattern).each do |alias_name, column, operator|
+          table = alias_name.to_s.empty? ? base_table : aliases[alias_name]
+          next unless table && result[table]
+
+          group = ["=", "IN", "IS"].include?(operator.to_s.upcase) ? "equality" : "range"
+          append_column(result[table][group], column)
+        end
+      end
+
+      def collect_join_predicates(sql, aliases, result)
+        sql.scan(/\bON\b(.*?)(?=\b(?:JOIN|WHERE|GROUP\s+BY|ORDER\s+BY|HAVING|LIMIT|OFFSET)\b|\z)/im) do |match|
+          match.first.to_s.scan(/(#{IDENTIFIER})\.(#{IDENTIFIER})/i).each do |alias_name, column|
+            table = aliases[alias_name]
+            append_column(result[table]["join"], column) if table && result[table]
+          end
+        end
+      end
+
+      def collect_order_columns(section, aliases, base_table, result)
+        section.split(",").first(MAX_COLUMNS).each do |item|
+          match = item.match(/(?:(#{IDENTIFIER})\.)?(#{IDENTIFIER})(?:\s+(?:ASC|DESC))?/i)
+          next unless match
+
+          table = match[1].to_s.empty? ? base_table : aliases[match[1]]
+          append_column(result[table]["order"], match[2]) if table && result[table]
+        end
+      end
+
+      def index_candidates(access, inspection)
+        indexes = Array(inspection["indexes"] || inspection[:indexes]).first(MAX_INDEXES)
+        access.map do |table, groups|
+          columns = (groups["equality"] + groups["join"] + groups["range"] + groups["order"]).uniq.first(MAX_COLUMNS)
+          next if columns.empty?
+
+          covering = indexes.find { |index| index_covers?(index, table, columns) }
+          {
+            "table" => table, "columns" => columns,
+            "status" => candidate_status(indexes, covering),
+            "covered_by" => covering ? bounded(hash(covering)["name"] || hash(covering)[:name], 128) : nil,
+            "confidence" => candidate_confidence(inspection, covering)
+          }.delete_if { |_key, value| value.nil? || value == "" }
+        end.compact.first(MAX_TABLES)
+      end
+
+      def candidate_status(indexes, covering)
+        return "unverified" if indexes.empty?
+
+        covering ? "covered" : "missing"
+      end
+
+      def index_covers?(index, table, columns)
+        data = hash(index)
+        return false unless (data["table"] || data[:table]).to_s == table.to_s
+
+        existing = Array(data["columns"] || data[:columns]).map(&:to_s)
+        existing.first(columns.length) == columns
+      end
+
+      def candidate_confidence(inspection, covering)
+        return "high" if covering
+
+        plan = hash(hash(inspection)["plan"] || hash(inspection)[:plan])
+        return "high" if plan["sequential_scan"] == true || plan[:sequential_scan] == true
+        return "medium" unless Array(hash(inspection)["indexes"] || hash(inspection)[:indexes]).empty?
+
+        "low"
+      end
+
+      def inspection_evidence(value)
+        data = hash(value)
+        result = {"indexes" => bounded_indexes(data["indexes"] || data[:indexes])}
+        statistics = hash(data["statistics"] || data[:statistics])
+        result["statistics"] = bounded_statistics(statistics) unless statistics.empty?
+        plan = hash(data["plan"] || data[:plan])
+        result["plan"] = bounded_plan(plan) unless plan.empty?
+        errors = bounded_errors(data["errors"] || data[:errors])
+        result["errors"] = errors unless errors.empty?
+        result
+      end
+
+      def bounded_indexes(values)
+        Array(values).first(MAX_INDEXES).map do |index|
+          item = hash(index)
+          columns = Array(item["columns"] || item[:columns]).first(MAX_COLUMNS)
+          {
+            "table" => bounded_identifier(item["table"] || item[:table]),
+            "name" => bounded(item["name"] || item[:name], 128),
+            "columns" => columns.map { |column| bounded_identifier(column) },
+            "unique" => item["unique"] == true || item[:unique] == true
+          }
+        end
+      end
+
+      def bounded_errors(values)
+        Array(values).first(5).map { |error| bounded(error, 128) }
+      end
+
+      def bounded_statistics(statistics)
+        {
+          "estimated_rows" => non_negative_integer(statistics["estimated_rows"] || statistics[:estimated_rows]),
+          "source" => bounded(statistics["source"] || statistics[:source], 64)
+        }.delete_if { |_key, value| value.nil? || value == "" }
+      end
+
+      def bounded_plan(plan)
+        {
+          "nodes" => Array(plan["nodes"] || plan[:nodes]).first(20).map do |node|
+            bounded_plan_node(node)
+          end,
+          "uses_index" => plan["uses_index"] == true || plan[:uses_index] == true,
+          "sequential_scan" => plan["sequential_scan"] == true || plan[:sequential_scan] == true
+        }
+      end
+
+      def bounded_plan_node(node)
+        data = hash(node)
+        {
+          "type" => bounded(data["type"] || data[:type], 64),
+          "table" => bounded_identifier(data["table"] || data[:table]),
+          "index" => bounded(data["index"] || data[:index], 128),
+          "estimated_rows" => non_negative_integer(data["estimated_rows"] || data[:estimated_rows]),
+          "total_cost" => non_negative_number(data["total_cost"] || data[:total_cost])
+        }.delete_if { |_key, child| child.nil? || child == "" }
+      end
+
+      def diagnostics(candidates, inspection)
+        result = [diagnostic("query_pattern_analyzed", "info", "query_pattern", {},
+                             "Normalized SELECT access pattern was analyzed")]
+        candidates.each do |candidate|
+          status = candidate["status"]
+          code = index_diagnostic_code(status)
+          severity = status == "covered" ? "info" : "suggestion"
+          result << diagnostic(code, severity, "index", candidate, index_diagnostic_message(status))
+        end
+        plan = hash(inspection["plan"])
+        if plan["sequential_scan"] == true
+          result << diagnostic("sequential_scan", "warning", "plan", {},
+                               "The bounded query plan contains a sequential scan")
+        end
+        Array(inspection["errors"]).each do |error|
+          result << diagnostic("query_inspection_failed", "error", "inspection", {"error_class" => error},
+                               "Read-only query inspection failed")
+        end
+        result.first(MAX_DIAGNOSTICS)
+      end
+
+      def index_diagnostic_code(status)
+        return "missing_index_candidate" if status == "missing"
+        return "index_covered" if status == "covered"
+
+        "index_candidate"
+      end
+
+      def index_diagnostic_message(status)
+        return "Existing index covers the observed access pattern" if status == "covered"
+
+        "Review a candidate index for the observed access pattern"
+      end
+
+      def diagnostic(code, severity, category, evidence, message)
+        result = {
+          "code" => code, "severity" => severity, "category" => category,
+          "message" => message, "evidence" => evidence
+        }
+        if severity == "suggestion"
+          result["recommendation"] = "Validate selectivity and write cost before creating the candidate index"
+        end
+        result
+      end
+
+      def clause(sql, start_pattern, finish_pattern)
+        start = sql.index(start_pattern)
+        return "" unless start
+
+        tail = sql[start..-1].to_s.sub(start_pattern, "")
+        finish = tail.index(finish_pattern)
+        finish ? tail[0...finish] : tail
+      end
+
+      def append_column(collection, value)
+        column = bounded_identifier(value)
+        collection << column if !column.empty? && !collection.include?(column) && collection.length < MAX_COLUMNS
+      end
+
+      def bounded_identifier(value)
+        bounded(value, 128).gsub(/[^A-Za-z0-9_.$-]/, "")
+      end
+
+      def bounded(value, limit)
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text.bytesize > limit ? text.byteslice(0, limit).to_s : text
+      rescue StandardError
+        ""
+      end
+
+      def non_negative_integer(value)
+        return nil if value.nil?
+
+        [value.to_i, 0].max
+      rescue StandardError
+        nil
+      end
+
+      def non_negative_number(value)
+        return nil if value.nil?
+
+        number = value.to_f
+        number < 0.0 ? 0.0 : number
+      rescue StandardError
+        nil
+      end
+
+      def hash(value)
+        value.is_a?(Hash) ? value : {}
+      end
+    end
+  end
+end

data/lib/chronos/ports/query_inspector.rb

@@ -0,0 +1,23 @@
+module Chronos
+  module Ports
+    # Documents the optional read-only database-inspection boundary used by SQL monitoring.
+    #
+    # @responsibility Define compatibility for index, statistics, and plan inspection adapters.
+    # @motivation Keep database and ActiveRecord behavior outside the framework-independent core.
+    # @limits It does not require inspection, execute DDL, or prescribe a database driver.
+    # @thread_safety Implementations define their own connection and concurrency guarantees.
+    # @compatibility The compatibility check uses APIs available in Ruby 2.2.10.
+    # @example
+    #   QueryInspector.compatible?(adapter) #=> true
+    # @errors Compatibility checks contain objects with failing reflection methods.
+    module QueryInspector
+      REQUIRED_METHODS = [:call].freeze
+
+      def self.compatible?(object)
+        REQUIRED_METHODS.all? { |method_name| object.respond_to?(method_name) }
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/chronos/rails/active_record_query_inspector.rb

@@ -0,0 +1,235 @@
+require "json"
+
+module Chronos
+  module Rails
+    # Performs bounded, read-only ActiveRecord index, statistics, and query-plan inspection.
+    #
+    # @responsibility Read public schema metadata and optional non-executing SELECT plans.
+    # @motivation Add database evidence to query diagnostics without exposing raw SQL or bind values.
+    # @limits It never runs EXPLAIN ANALYZE or DDL; support is best-effort and explicitly opt-in.
+    # @collaborators An ActiveRecord connection supplied by sql.active_record notifications.
+    # @thread_safety Calls use the notification connection and a thread-local recursion guard.
+    # @compatibility Feature-detected Rails 4.2/5.2 connections for PostgreSQL and MySQL-family adapters.
+    # @example
+    #   inspector.call(sql, query_metadata, :plan => false)
+    # @errors Adapter failures become bounded error-class evidence and never escape.
+    # @performance Each uncached inspection adds schema/statistics queries and optionally EXPLAIN.
+    class ActiveRecordQueryInspector
+      GUARD_KEY = :__chronos_query_inspection
+      MAX_PLAN_NODES = 20
+
+      def self.suppressed?
+        Thread.current[GUARD_KEY] == true
+      rescue StandardError
+        false
+      end
+
+      def call(raw_sql, query, options = {})
+        connection = options[:connection]
+        return {} unless eligible?(raw_sql, query, connection)
+
+        previous = Thread.current[GUARD_KEY]
+        Thread.current[GUARD_KEY] = true
+        guarded = true
+        result = {"errors" => []}
+        capture(result) { result["indexes"] = indexes(connection, table(query)) }
+        if options[:statistics] == true
+          capture(result) { result["statistics"] = statistics(connection, table(query)) }
+        end
+        if options[:plan] == true
+          capture(result) do
+            plan_result = plan(connection, raw_sql, adapter_name(connection))
+            result["errors"].concat(Array(plan_result.delete("errors")))
+            result["plan"] = plan_result
+          end
+        end
+        result.delete("errors") if result["errors"].empty?
+        result
+      rescue StandardError => error
+        {"errors" => [safe_error_class(error)]}
+      ensure
+        Thread.current[GUARD_KEY] = previous if guarded
+      end
+
+      private
+
+      def capture(result)
+        yield
+      rescue StandardError => error
+        result["errors"] << safe_error_class(error) if result["errors"].length < 5
+      end
+
+      def eligible?(raw_sql, query, connection)
+        return false unless connection
+        return false unless (query["operation"] || query[:operation]).to_s == "SELECT"
+        return false if table(query).empty?
+        return false unless raw_sql.to_s.lstrip =~ /\ASELECT\b/i
+
+        normalized = (query["normalized_query"] || query[:normalized_query]).to_s
+        normalized.sub(/;\s*\z/, "") !~ /;/
+      end
+
+      def indexes(connection, table_name)
+        return [] unless connection.respond_to?(:indexes)
+
+        Array(connection.indexes(table_name)).first(20).map do |index|
+          {
+            "table" => bounded_identifier(table_name), "name" => bounded(value(index, :name), 128),
+            "columns" => Array(value(index, :columns)).first(12).map { |column| bounded_identifier(column) },
+            "unique" => value(index, :unique) == true
+          }
+        end
+      end
+
+      def statistics(connection, table_name)
+        adapter = adapter_name(connection)
+        if adapter =~ /postgres/i
+          row = first_row(connection, "SELECT reltuples AS estimated_rows FROM pg_class WHERE oid = " \
+                                      "#{quote(connection, table_name)}::regclass")
+          return {"estimated_rows" => numeric(row, "estimated_rows"), "source" => "pg_class"}
+        end
+        if adapter =~ /mysql|trilogy/i
+          sql = "SELECT table_rows AS estimated_rows FROM information_schema.tables " \
+                "WHERE table_schema = DATABASE() AND table_name = #{quote(connection, table_name)}"
+          row = first_row(connection, sql)
+          return {"estimated_rows" => numeric(row, "estimated_rows"), "source" => "information_schema"}
+        end
+
+        {}
+      end
+
+      def plan(connection, raw_sql, adapter)
+        return {} unless connection.respond_to?(:select_all)
+
+        if adapter =~ /postgres/i
+          rows = rows(connection.select_all("EXPLAIN (FORMAT JSON) #{raw_sql}"))
+          return postgres_plan(rows)
+        end
+        if adapter =~ /mysql|trilogy/i
+          return mysql_plan(rows(connection.select_all("EXPLAIN #{raw_sql}")))
+        end
+
+        {}
+      end
+
+      def postgres_plan(rows_value)
+        raw = rows_value.first || {}
+        document = raw["QUERY PLAN"] || raw["query_plan"] || raw.values.first
+        parsed = document.is_a?(String) ? JSON.parse(document) : document
+        root = Array(parsed).first
+        root = root["Plan"] if root.is_a?(Hash) && root["Plan"]
+        nodes = []
+        collect_postgres_nodes(root, nodes)
+        summarize_plan(nodes)
+      rescue StandardError => error
+        {"nodes" => [], "uses_index" => false, "sequential_scan" => false,
+         "errors" => [safe_error_class(error)]}
+      end
+
+      def collect_postgres_nodes(node, result)
+        return unless node.is_a?(Hash) && result.length < MAX_PLAN_NODES
+
+        result << {
+          "type" => bounded(node["Node Type"], 64),
+          "table" => bounded_identifier(node["Relation Name"]),
+          "index" => bounded(node["Index Name"], 128),
+          "estimated_rows" => integer(node["Plan Rows"]),
+          "total_cost" => number(node["Total Cost"])
+        }.delete_if { |_key, child| child.nil? || child == "" }
+        Array(node["Plans"]).each { |child| collect_postgres_nodes(child, result) }
+      end
+
+      def mysql_plan(rows_value)
+        nodes = rows_value.first(MAX_PLAN_NODES).map do |row|
+          {
+            "type" => bounded(row["type"] || row[:type] || row["select_type"], 64),
+            "table" => bounded_identifier(row["table"] || row[:table]),
+            "index" => bounded(row["key"] || row[:key], 128),
+            "estimated_rows" => integer(row["rows"] || row[:rows])
+          }.delete_if { |_key, child| child.nil? || child == "" }
+        end
+        summarize_plan(nodes)
+      end
+
+      def summarize_plan(nodes)
+        types = nodes.map { |node| node["type"].to_s }
+        {
+          "nodes" => nodes,
+          "uses_index" => nodes.any? { |node| !node["index"].to_s.empty? || node["type"].to_s =~ /Index/i },
+          "sequential_scan" => types.any? { |type| type =~ /Seq Scan|ALL/i }
+        }
+      end
+
+      def first_row(connection, sql)
+        return {} unless connection.respond_to?(:select_all)
+
+        rows(connection.select_all(sql)).first || {}
+      end
+
+      def rows(value)
+        return value.to_a if value.respond_to?(:to_a)
+
+        Array(value)
+      rescue StandardError
+        []
+      end
+
+      def quote(connection, value)
+        return connection.quote(value.to_s) if connection.respond_to?(:quote)
+
+        "'#{value.to_s.gsub("'", "''")}'"
+      end
+
+      def adapter_name(connection)
+        connection.respond_to?(:adapter_name) ? connection.adapter_name.to_s : ""
+      rescue StandardError
+        ""
+      end
+
+      def table(query)
+        bounded_identifier(query["table"] || query[:table])
+      end
+
+      def value(object, method_name)
+        object.respond_to?(method_name) ? object.public_send(method_name) : nil
+      rescue StandardError
+        nil
+      end
+
+      def numeric(row, key)
+        value = row[key] || row[key.to_sym]
+        integer(value)
+      end
+
+      def integer(value)
+        value.nil? ? nil : [value.to_i, 0].max
+      rescue StandardError
+        nil
+      end
+
+      def number(value)
+        value.nil? ? nil : [value.to_f, 0.0].max
+      rescue StandardError
+        nil
+      end
+
+      def safe_error_class(error)
+        bounded(error.class.name.to_s, 128)
+      rescue StandardError
+        "StandardError"
+      end
+
+      def bounded_identifier(value)
+        bounded(value, 128).gsub(/[^A-Za-z0-9_.$-]/, "")
+      end
+
+      def bounded(value, limit)
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text.bytesize > limit ? text.byteslice(0, limit).to_s : text
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end