mysql_genius-core 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba1c5800131408bf90c87a052719196ebca6c84c9a9eae175e205a027d24e7a4
-  data.tar.gz: e5ae1079f22dea06691754b08b685550fb23b68c1b3dbec3f455ad9e38dc8436
+  metadata.gz: 197d8fdf10094c1acf1487e9cc958e8a948f2faf16d0fc06d89193c1ccbc69c7
+  data.tar.gz: b2503519e572e9520fcda9c2e0adfd166cb68623d3a4fa1115034ff2e51ead0b
 SHA512:
-  metadata.gz: 6142e5bd5cf98d4c1bda216240f48889e840af67d317fe9cb5b3c12afb48b252d37409fe652ada956c11867fe0d3ba98681ac41b1eda273be339f54c4b5404af
-  data.tar.gz: addd52a4e81dc87af3f5eec1f016208a1cd22b8a018fd471722d460af6d911a05241d771e2ec4d6765acde3cb52b47ad4b8f7346787231722377862d0a50c0e1
+  metadata.gz: 22a75ed744368906927aada6311e76b4b8f4a2ae8dd8d6acbc8b7ac0486d1f7634b82f6cc0a1ef10324fa6984d191142d5e295210f0641896d654882536f9218
+  data.tar.gz: f3bbd7408ed91148f288cd95130158e4400c5c6d31e1b14527bd90fde64d2e211e6ff6e25c170847982ed19e73b9d9470c0a04d182a051e403ef71bf3ae2d235

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.5.0
+
+### Added
+- `MysqlGenius::Core::Analysis::Columns` — service class for `GET /columns` logic with a tagged-result struct (`:ok`, `:blocked`, `:not_found`). Takes a `Core::Connection`, uses `Core::SqlValidator.masked_column?` for the masked-column rule.
+- `MysqlGenius::Core::Ai::{DescribeQuery, SchemaReview, RewriteQuery, IndexAdvisor, MigrationRisk}` — 5 AI prompt builder classes extracted from the `mysql_genius` Rails adapter's `AiFeatures` concern. Each takes `(client, config)` or `(client, config, connection)` and exposes a single `#call` method.
+- `MysqlGenius::Core::Ai::SchemaContextBuilder` — shared helper for building "Table: X (~N rows), Columns: …, Indexes: …" schema descriptions. Supports `detail: :basic` and `detail: :with_cardinality`.
+- `MysqlGenius::Core::Ai::Config#domain_context` — new optional keyword field (empty string default) interpolated into every extracted prompt builder's system prompt.
+- `MysqlGenius::Core.views_path` — public module method returning the absolute path to the shared ERB template directory. Adapters register this path with their own view loader.
+- **ERB templates extracted from the Rails adapter.** `MysqlGenius::Core.views_path` now points at `lib/mysql_genius/core/views/` which contains `mysql_genius/queries/dashboard.html.erb` and the 10 tab/partial files. Any adapter (Rails, Sinatra, or future desktop) can load these templates by registering this path with its own view loader. Templates depend on a minimal 2-method contract: `path_for(name)` and `render_partial(name)`.
+
 ## 0.4.1
 
 No functional changes in `mysql_genius-core`. Version bumped to maintain lockstep with `mysql_genius 0.4.1`, which hotfixes a regression in the Rails adapter's `GET /columns` endpoint. See the root `CHANGELOG.md` for details.

data/lib/mysql_genius/core/ai/config.rb

@@ -16,6 +16,8 @@ module MysqlGenius
       #   auth_style     - :bearer or :api_key
       #   system_context - optional domain context string that services
       #                    append to their system prompts
+      #   domain_context - optional host-app context string interpolated into
+      #                    AI system prompts (e.g. "Rails app, no FKs")
       Config = Struct.new(
         :client,
         :endpoint,
@@ -23,10 +25,11 @@ module MysqlGenius
         :model,
         :auth_style,
         :system_context,
+        :domain_context,
         keyword_init: true,
       ) do
-        def initialize(*)
-          super
+        def initialize(**kwargs)
+          super(domain_context: "", **kwargs)
           freeze
         end
 

data/lib/mysql_genius/core/ai/describe_query.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Ai
+      # Builds and sends a "describe this query" prompt to Core::Ai::Client.
+      # Pure function of SQL + config.domain_context — no connection lookup.
+      #
+      # Extracted from app/controllers/concerns/mysql_genius/ai_features.rb
+      # in Phase 2a.
+      class DescribeQuery
+        def initialize(client, config)
+          @client = client
+          @config = config
+        end
+
+        def call(sql)
+          messages = [
+            { role: "system", content: system_prompt },
+            { role: "user",   content: sql },
+          ]
+          @client.chat(messages: messages)
+        end
+
+        private
+
+        def system_prompt
+          <<~PROMPT
+            You are a MySQL query explainer. Given a SQL query, explain in plain English:
+            1. What the query does (tables involved, joins, filters, aggregations)
+            2. How data flows through the query
+            3. Any subtle behaviors (implicit type casts, NULL handling in NOT IN, DISTINCT effects, etc.)
+            4. Potential performance concerns visible from the SQL structure alone
+            #{@config.domain_context}
+            Respond with JSON: {"explanation": "your plain-English explanation using markdown formatting"}
+          PROMPT
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/ai/index_advisor.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Ai
+      class IndexAdvisor
+        def initialize(client, config, connection)
+          @client = client
+          @config = config
+          @connection = connection
+        end
+
+        def call(sql, explain_rows)
+          tables = SqlValidator.extract_table_references(sql, @connection)
+          schema = SchemaContextBuilder.new(@connection).call(tables, detail: :with_cardinality)
+          explain_text = explain_rows.map { |row| row.join(" | ") }.join("\n")
+
+          messages = [
+            { role: "system", content: system_prompt },
+            { role: "user",   content: "Query:\n#{sql}\n\nEXPLAIN:\n#{explain_text}\n\nSchema:\n#{schema}" },
+          ]
+          @client.chat(messages: messages)
+        end
+
+        private
+
+        def system_prompt
+          <<~PROMPT
+            You are a MySQL index advisor. Given a query, its EXPLAIN output, and current index/cardinality information, suggest optimal indexes. Consider:
+            - Composite index column ordering (most selective first, or matching query order)
+            - Covering indexes to avoid table lookups
+            - Partial indexes for long string columns
+            - Write-side costs (if this is a high-write table, note the INSERT/UPDATE overhead)
+            - Whether existing indexes could be extended rather than creating new ones
+            #{@config.domain_context}
+
+            Respond with JSON: {"indexes": "markdown-formatted recommendations with exact CREATE INDEX statements, rationale for column ordering, and estimated impact. Include any indexes that should be DROPPED as part of the change."}
+          PROMPT
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/ai/migration_risk.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Ai
+      class MigrationRisk
+        def initialize(client, config, connection)
+          @client = client
+          @config = config
+          @connection = connection
+        end
+
+        def call(migration_sql)
+          tables = extract_table_names(migration_sql)
+          schema = SchemaContextBuilder.new(@connection).call(tables, detail: :basic)
+          schema_text = schema.to_s.empty? ? "Could not determine" : schema
+
+          messages = [
+            { role: "system", content: system_prompt },
+            { role: "user",   content: "Migration:\n#{migration_sql}\n\nAffected Tables:\n#{schema_text}" },
+          ]
+          @client.chat(messages: messages)
+        end
+
+        private
+
+        def extract_table_names(migration_sql)
+          # Match Rails migration helpers and raw SQL ALTER TABLE statements.
+          rails_matches = migration_sql.scan(/(?:create_table|add_column|remove_column|add_index|remove_index|rename_column|change_column|alter\s+table)\s+[:"]?(\w+)/i).flatten
+          sql_matches   = migration_sql.scan(/ALTER\s+TABLE\s+`?(\w+)`?/i).flatten
+          (rails_matches + sql_matches).uniq
+        end
+
+        def system_prompt
+          <<~PROMPT
+            You are a MySQL migration risk assessor. Given a Rails migration or DDL, evaluate:
+            1. Will this lock the table? For how long given the row count?
+            2. Is this safe to run during traffic, or does it need a maintenance window?
+            3. Should pt-online-schema-change or gh-ost be used instead?
+            4. Will it break or degrade any of the active queries against this table?
+            5. Are there any data loss risks?
+            6. What is the recommended deployment strategy?
+            #{@config.domain_context}
+
+            Respond with JSON: {"risk_level": "low|medium|high|critical", "assessment": "markdown-formatted risk assessment with specific recommendations and estimated lock duration"}
+          PROMPT
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/ai/rewrite_query.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Ai
+      # Suggests a rewritten version of a SQL query based on the schema
+      # context of the tables it references.
+      class RewriteQuery
+        def initialize(client, config, connection)
+          @client = client
+          @config = config
+          @connection = connection
+        end
+
+        def call(sql)
+          tables = SqlValidator.extract_table_references(sql, @connection)
+          schema = SchemaContextBuilder.new(@connection).call(tables, detail: :basic)
+
+          messages = [
+            { role: "system", content: system_prompt(schema) },
+            { role: "user",   content: sql },
+          ]
+          @client.chat(messages: messages)
+        end
+
+        private
+
+        def system_prompt(schema)
+          <<~PROMPT
+            You are a MySQL query rewrite expert. Analyze the SQL for anti-patterns and suggest a rewritten version. Look for:
+            - SELECT * when specific columns would suffice
+            - Correlated subqueries that could be JOINs
+            - OR conditions preventing index use (suggest UNION ALL)
+            - LIKE '%prefix' patterns (leading wildcard)
+            - Implicit type conversions in WHERE clauses
+            - NOT IN with NULLable columns (suggest NOT EXISTS)
+            - ORDER BY on non-indexed columns with LIMIT
+            - Unnecessary DISTINCT
+            - Functions on indexed columns in WHERE (e.g., DATE(created_at) instead of range)
+
+            Available schema:
+            #{schema}
+            #{@config.domain_context}
+
+            Respond with JSON: {"original": "the original SQL", "rewritten": "the improved SQL", "changes": "markdown list of each change and why it helps"}
+          PROMPT
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/ai/schema_context_builder.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Ai
+      # Builds formatted schema-description strings for AI prompt context.
+      # Used by SchemaReview, RewriteQuery, IndexAdvisor, and MigrationRisk.
+      #
+      # Consolidates the ~10 lines of schema description logic that were
+      # duplicated across 4 AI features in the Rails adapter's
+      # app/controllers/concerns/mysql_genius/ai_features.rb.
+      class SchemaContextBuilder
+        def initialize(connection)
+          @connection = connection
+        end
+
+        # Returns a formatted multi-line string describing the given tables.
+        #
+        # detail:
+        #   :basic             — name, row count, primary key, columns, indexes
+        #   :with_cardinality  — adds information_schema.STATISTICS cardinality per index
+        def call(tables, detail: :basic)
+          Array(tables).filter_map { |t| describe_table(t, detail: detail) }.join("\n\n")
+        end
+
+        private
+
+        def describe_table(table, detail:)
+          return unless @connection.tables.include?(table)
+
+          cols = @connection.columns_for(table).map do |c|
+            parts = ["#{c.name} #{c.sql_type}"]
+            parts << "NOT NULL" unless c.null
+            parts << "DEFAULT #{c.default}" if c.default
+            parts.join(" ")
+          end
+
+          pk = @connection.primary_key(table)
+          indexes = @connection.indexes_for(table).map do |idx|
+            "#{"UNIQUE " if idx.unique}INDEX #{idx.name} (#{idx.columns.join(", ")})"
+          end
+
+          row_count = fetch_row_count(table)
+
+          parts = [
+            "Table: #{table} (~#{row_count || "unknown"} rows)",
+            "Primary Key: #{pk || "NONE"}",
+            "Columns: #{cols.join(", ")}",
+            "Indexes: #{indexes.any? ? indexes.join(", ") : "NONE"}",
+          ]
+
+          parts << index_cardinality(table) if detail == :with_cardinality
+
+          parts.join("\n")
+        end
+
+        def fetch_row_count(table)
+          sql = "SELECT TABLE_ROWS FROM information_schema.tables " \
+            "WHERE table_schema = #{@connection.quote(@connection.current_database)} " \
+            "AND table_name = #{@connection.quote(table)}"
+          result = @connection.exec_query(sql)
+          result.rows.first&.first
+        rescue StandardError
+          nil
+        end
+
+        def index_cardinality(table)
+          sql = "SELECT INDEX_NAME, COLUMN_NAME, CARDINALITY, SEQ_IN_INDEX " \
+            "FROM information_schema.STATISTICS " \
+            "WHERE TABLE_SCHEMA = #{@connection.quote(@connection.current_database)} " \
+            "AND TABLE_NAME = #{@connection.quote(table)} " \
+            "ORDER BY INDEX_NAME, SEQ_IN_INDEX"
+          result = @connection.exec_query(sql)
+          stats = result.rows.map { |r| "#{r[0]}.#{r[1]}: cardinality=#{r[2]}" }
+          "Cardinality: #{stats.join(", ")}"
+        rescue StandardError
+          "Cardinality: (unavailable)"
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/ai/schema_review.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Ai
+      # Reviews a schema for anti-patterns. Takes a specific table name
+      # (or nil to review the top 20 queryable tables).
+      class SchemaReview
+        def initialize(client, config, connection)
+          @client = client
+          @config = config
+          @connection = connection
+        end
+
+        def call(table)
+          tables_to_review = table.nil? || table.to_s.empty? ? @connection.tables.first(20) : [table]
+          schema_desc = SchemaContextBuilder.new(@connection).call(tables_to_review, detail: :basic)
+
+          messages = [
+            { role: "system", content: system_prompt },
+            { role: "user",   content: schema_desc },
+          ]
+          @client.chat(messages: messages)
+        end
+
+        private
+
+        def system_prompt
+          <<~PROMPT
+            You are a MySQL schema reviewer. Analyze the following schema and identify anti-patterns and improvement opportunities. Look for:
+            - Inappropriate column types (VARCHAR(255) for short values, TEXT where VARCHAR suffices, INT for booleans)
+            - Missing indexes on foreign key columns or frequently filtered columns
+            - Missing NOT NULL constraints where NULLs are unlikely
+            - ENUM columns that should be lookup tables
+            - Missing created_at/updated_at timestamps
+            - Tables without a PRIMARY KEY
+            - Overly wide indexes or redundant indexes
+            - Column naming inconsistencies
+            #{@config.domain_context}
+            Respond with JSON: {"findings": "markdown-formatted findings organized by severity (Critical, Warning, Suggestion). Include specific ALTER TABLE statements where applicable."}
+          PROMPT
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/analysis/columns.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Analysis
+      # Service class for the Rails engine's GET /columns action and its
+      # Phase 2b sidecar equivalent. Takes a Core::Connection and the
+      # relevant configuration; returns a tagged Result struct that
+      # adapters map to HTTP responses.
+      #
+      # Each status maps 1:1 to an HTTP status code:
+      #   :ok        → 200 with columns: array
+      #   :blocked   → 403 with error_message:
+      #   :not_found → 404 with error_message:
+      #
+      # The adapter reads result.status and dispatches accordingly.
+      class Columns
+        Result = Struct.new(:status, :columns, :error_message, keyword_init: true)
+
+        def initialize(connection, blocked_tables:, masked_column_patterns:, default_columns:)
+          @connection = connection
+          @blocked_tables = blocked_tables
+          @masked_column_patterns = masked_column_patterns
+          @default_columns = default_columns
+        end
+
+        def call(table:)
+          return blocked_result(table)   if @blocked_tables.include?(table)
+          return not_found_result(table) unless @connection.tables.include?(table)
+
+          defaults = @default_columns[table] || []
+          visible = @connection.columns_for(table).reject do |col|
+            SqlValidator.masked_column?(col.name, @masked_column_patterns)
+          end
+          formatted = visible.map do |col|
+            {
+              name: col.name,
+              type: col.type.to_s,
+              default: defaults.empty? || defaults.include?(col.name),
+            }
+          end
+
+          Result.new(status: :ok, columns: formatted)
+        end
+
+        private
+
+        def blocked_result(table)
+          Result.new(
+            status: :blocked,
+            error_message: "Table '#{table}' is not available for querying.",
+          )
+        end
+
+        def not_found_result(table)
+          Result.new(
+            status: :not_found,
+            error_message: "Table '#{table}' does not exist.",
+          )
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/version.rb

@@ -2,6 +2,6 @@
 
 module MysqlGenius
   module Core
-    VERSION = "0.4.1"
+    VERSION = "0.5.0"
   end
 end

data/lib/mysql_genius/core.rb

@@ -10,6 +10,17 @@ module MysqlGenius
   # overall design.
   module Core
     class Error < StandardError; end
+
+    class << self
+      # Absolute path to the shared ERB template directory. Adapters
+      # register this path with their view loader:
+      #
+      #   Rails:   engine.config.paths["app/views"] << MysqlGenius::Core.views_path
+      #   Sinatra: set :views, MysqlGenius::Core.views_path
+      def views_path
+        File.expand_path("core/views", __dir__)
+      end
+    end
   end
 end
 
@@ -24,11 +35,18 @@ require "mysql_genius/core/ai/config"
 require "mysql_genius/core/ai/client"
 require "mysql_genius/core/ai/suggestion"
 require "mysql_genius/core/ai/optimization"
+require "mysql_genius/core/ai/schema_context_builder"
+require "mysql_genius/core/ai/describe_query"
+require "mysql_genius/core/ai/schema_review"
+require "mysql_genius/core/ai/rewrite_query"
+require "mysql_genius/core/ai/index_advisor"
+require "mysql_genius/core/ai/migration_risk"
 require "mysql_genius/core/analysis/table_sizes"
 require "mysql_genius/core/analysis/duplicate_indexes"
 require "mysql_genius/core/analysis/query_stats"
 require "mysql_genius/core/analysis/unused_indexes"
 require "mysql_genius/core/analysis/server_overview"
+require "mysql_genius/core/analysis/columns"
 require "mysql_genius/core/execution_result"
 require "mysql_genius/core/query_runner/config"
 require "mysql_genius/core/query_runner"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mysql_genius-core
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Antarr Byrd
@@ -24,8 +24,15 @@ files:
 - lib/mysql_genius/core.rb
 - lib/mysql_genius/core/ai/client.rb
 - lib/mysql_genius/core/ai/config.rb
+- lib/mysql_genius/core/ai/describe_query.rb
+- lib/mysql_genius/core/ai/index_advisor.rb
+- lib/mysql_genius/core/ai/migration_risk.rb
 - lib/mysql_genius/core/ai/optimization.rb
+- lib/mysql_genius/core/ai/rewrite_query.rb
+- lib/mysql_genius/core/ai/schema_context_builder.rb
+- lib/mysql_genius/core/ai/schema_review.rb
 - lib/mysql_genius/core/ai/suggestion.rb
+- lib/mysql_genius/core/analysis/columns.rb
 - lib/mysql_genius/core/analysis/duplicate_indexes.rb
 - lib/mysql_genius/core/analysis/query_stats.rb
 - lib/mysql_genius/core/analysis/server_overview.rb