rails-ai-context 2.0.1 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 485ed8bdee695a10d5fd05b9a578bb3ff55f918d5ea9d3ddd3a18ba56f03c3f7
-  data.tar.gz: 010af0cd0f8958e09856f08e6be2c54d87f75ab6ea7a1e3c2993523a15d18992
+  metadata.gz: 28fe01be28232f19cf9fab8cb6b696630e21d663e47b426a206e771b0096bfcb
+  data.tar.gz: 488fdca01c018f6f9f468e7f03c78c2e6456e93dde0c7a89d17a5c554160b305
 SHA512:
-  metadata.gz: 66aced48319fe77c7d5301ca154150db872d5ee682be94c5ae81af229901fb3ac950e932ce984f0f5c13d4dbfceae5f89bcb2fbe479c04ab38ec1a6fb605d7a2
-  data.tar.gz: 81cbff9c0f81ef41d1c1db9b9b97a6af606da9915c59214097dfe8386d7437250f4e6c470b59ca3c1dd8721bf21a458bbe6cf351313ff7a47cfaaab90fabb221
+  metadata.gz: bd0017a556c8a728b58ac5b18dc52682a825602e295be6a54f8bde15baf552d62247d57441af936d8762d00763aec076e46dc52d745274bf74362df5105bb0ec
+  data.tar.gz: e16d3d1306ad9d4aa617a72e0311cbf1ffb8f2f5e80074913e3c1be62ceca2f8325642e3cf1515c6c14a930349b2f5a78a98f913d7c53f011bf3e1b6d7450eaa

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.2] - 2026-03-25
+
+### Added
+
+- **`match_type:"trace"` in search_code** — full method picture in one call: definition + source code + all callers grouped by type (Controller/Model/View/Job/Service/Test) + internal calls. The game changer for code navigation.
+- **`match_type:"call"`** — find call sites only, excluding definitions.
+- **Smart result limiting** — <10 shows all, 10-100 shows half, >100 caps at 100. Pagination via `offset:` param.
+- **`exclude_tests:true`** — skip test/spec/features directories in search results.
+- **`group_by_file:true`** — group search results by file with match counts.
+- **Inline cross-references** — schema shows model name + association count per table, routes show controller filters inline, views use pipe-separated metadata.
+- **Test template generation** — `get_test_info(detail:"standard")` includes a copy-paste test template matching the app's patterns (Minitest/RSpec, Devise sign_in, fixtures).
+- **Interactive AI tool selection** — install generator and `rails ai:context` prompt users to select which AI tools they use (Claude, Cursor, Copilot, Windsurf, OpenCode). Selection saved to `config.ai_tools`.
+- **Brakeman in validate** — `rails_validate(level:"rails")` now runs Brakeman security checks inline alongside syntax and semantic checks.
+
+### Fixed
+
+- **Documentation audit** — fixed max_tool_response_chars reference (120K→200K), added missing search_code params to GUIDE, added config.ai_tools to config reference.
+
 ## [2.0.1] - 2026-03-25
 
 ### Fixed

data/README.md

@@ -111,7 +111,7 @@ The gem exposes **25 read-only tools** via MCP that AI clients call on-demand:
 | `rails_get_test_info` | Test framework, factory attributes/traits, fixtures, CI config, coverage |
 | `rails_get_gems` | Notable gems categorized by function with config location hints |
 | `rails_get_conventions` | Architecture patterns, frontend stack, directory structure |
-| `rails_search_code` | Ripgrep search with 2-line context default, `match_type:"definition"` for method defs only |
+| `rails_search_code` | Ripgrep search with `match_type:"trace"` (definition + callers + internal calls in one shot), `"definition"`, `"call"`, `"class"` filters, smart result limiting, pagination |
 | `rails_get_view` | View templates, partials with render locals, Stimulus references |
 | `rails_get_stimulus` | Stimulus controllers — targets, values, actions, outlets, lifecycle methods |
 | `rails_get_edit_context` | Surgical edit helper — returns code with class/method context and line numbers |
@@ -146,7 +146,7 @@ rails_get_routes(controller: "users")         # → routes for one controller
 rails_get_model_details(model: "User")        # → associations, validations, scopes
 ```
 
-A safety net (`max_tool_response_chars`, default 120K) truncates oversized responses with hints to use filters.
+A safety net (`max_tool_response_chars`, default 200K) truncates oversized responses with hints to use filters.
 
 ---
 
@@ -351,6 +351,7 @@ end
 | **Extensibility** | | |
 | `custom_tools` | `[]` | Additional MCP tool classes to register alongside built-in tools |
 | `skip_tools` | `[]` | Built-in tool names to exclude (e.g. `%w[rails_security_scan]`) |
+| `ai_tools` | `nil` (all) | AI tools to generate context for: `%i[claude cursor copilot windsurf opencode]` |
 </details>
 
 ---

data/docs/GUIDE.md

@@ -561,31 +561,38 @@ Ripgrep-powered regex search across the codebase.
 
 | Param | Type | Description |
 |-------|------|-------------|
-| `pattern` | string | **Required.** Regex pattern to search for. |
+| `pattern` | string | **Required.** Regex pattern or method name to search for. |
 | `path` | string | Subdirectory to search in (e.g. `app/models`, `config`). Default: entire app. |
-| `file_type` | string | Filter by file type (e.g. `rb`, `erb`, `js`). Alphanumeric only. |
-| `match_type` | string | Filter matches: `any` (default), `definition` (only `def` lines), `class` (only `class`/`module` lines). |
+| `file_type` | string | Filter by file extension (e.g. `rb`, `erb`, `js`). Alphanumeric only. |
+| `match_type` | string | `any` (default), `definition` (def lines), `class` (class/module lines), `call` (call sites only), `trace` (**full picture** — definition + source + callers + internal calls). |
 | `exact_match` | boolean | Match whole words only (wraps pattern in `\b` boundaries). Default: false. |
-| `max_results` | integer | Max results to return. Default: 30, max: 100. |
+| `exclude_tests` | boolean | Exclude test/spec/features directories. Default: false. |
+| `group_by_file` | boolean | Group results by file with match counts. Default: false. |
+| `offset` | integer | Skip this many results for pagination. Default: 0. |
 | `context_lines` | integer | Lines of context before and after each match (like grep -C). Default: 2, max: 5. |
 
+Smart result limiting: <10 results shows all, 10-100 shows half, >100 caps at 100. Use `offset` for pagination.
+
 **Examples:**
 
 ```
-rails_search_code(pattern: "has_secure_password")
-  → All files containing has_secure_password
+rails_search_code(pattern: "can_cook?", match_type: "trace")
+  → FULL PICTURE: definition + source code + all callers grouped by type + internal calls
+
+rails_search_code(pattern: "create", match_type: "definition")
+  → Only `def create` / `def self.create` lines
 
-rails_search_code(pattern: "class.*Controller", file_type: "rb")
-  → All Ruby files with controller class definitions
+rails_search_code(pattern: "can_cook", match_type: "call")
+  → Only call sites (excludes the definition)
 
-rails_search_code(pattern: "def create", file_type: "rb", max_results: 50)
-  → First 50 create methods across the codebase
+rails_search_code(pattern: "Controller", match_type: "class")
+  → All class/module definitions matching *Controller
 
-rails_search_code(pattern: "current_user", path: "app/controllers")
-  → Search only in app/controllers/
+rails_search_code(pattern: "has_many", group_by_file: true)
+  → Results grouped by file with match counts
 
-rails_search_code(pattern: "validates", context_lines: 3)
-  → Matches with 3 lines of context before and after (default is 2)
+rails_search_code(pattern: "cook", exclude_tests: true)
+  → Skip test/spec directories
 
 rails_search_code(pattern: "activate", match_type: "definition")
   → Only `def activate` / `def self.activate` lines (skips method calls)
@@ -1175,6 +1182,7 @@ end
 | `cache_ttl` | Integer | `60` | Cache TTL in seconds for introspection results |
 | `custom_tools` | Array | `[]` | Additional MCP tool classes to register alongside built-in tools |
 | `skip_tools` | Array | `[]` | Built-in tool names to exclude (e.g. `%w[rails_security_scan]`) |
+| `ai_tools` | Array | `nil` (all) | AI tools to generate context for: `%i[claude cursor copilot windsurf opencode]`. Selected during install. |
 | `excluded_models` | Array | internal Rails models | Models to skip |
 | `excluded_paths` | Array | `node_modules tmp log vendor .git` | Paths excluded from code search |
 | `sensitive_patterns` | Array | `.env`, `.key`, `.pem`, credentials | File patterns blocked from search and read tools |

data/lib/generators/rails_ai_context/install/install_generator.rb

@@ -9,6 +9,43 @@ module RailsAiContext
 
       desc "Install rails-ai-context: creates initializer, MCP config, and generates initial context files."
 
+      AI_TOOLS = {
+        "1" => { key: :claude,   name: "Claude Code",     files: "CLAUDE.md + .claude/rules/",                        format: :claude },
+        "2" => { key: :cursor,   name: "Cursor",          files: ".cursor/rules/",                                     format: :cursor },
+        "3" => { key: :copilot,  name: "GitHub Copilot",  files: ".github/copilot-instructions.md + .github/instructions/", format: :copilot },
+        "4" => { key: :windsurf, name: "Windsurf",        files: ".windsurfrules + .windsurf/rules/",                  format: :windsurf },
+        "5" => { key: :opencode, name: "OpenCode",        files: "AGENTS.md",                                          format: :opencode }
+      }.freeze
+
+      def select_ai_tools
+        say ""
+        say "Which AI tools do you use? (select all that apply)", :yellow
+        say ""
+        AI_TOOLS.each do |num, info|
+          say "  #{num}. #{info[:name].ljust(16)} → #{info[:files]}"
+        end
+        say "  a. All of the above"
+        say ""
+
+        input = ask("Enter numbers separated by commas (e.g. 1,2) or 'a' for all:").strip.downcase
+
+        @selected_formats = if input == "a" || input == "all"
+          AI_TOOLS.values.map { |t| t[:format] }
+        else
+          nums = input.split(/[\s,]+/)
+          nums.filter_map { |n| AI_TOOLS[n]&.dig(:format) }
+        end
+
+        if @selected_formats.empty?
+          say "No tools selected — defaulting to all.", :yellow
+          @selected_formats = AI_TOOLS.values.map { |t| t[:format] }
+        end
+
+        selected_names = AI_TOOLS.values.select { |t| @selected_formats.include?(t[:format]) }.map { |t| t[:name] }
+        say ""
+        say "Selected: #{selected_names.join(', ')}", :green
+      end
+
       def create_mcp_config
         mcp_path = Rails.root.join(".mcp.json")
         server_entry = {
@@ -36,46 +73,33 @@ module RailsAiContext
       end
 
       def create_initializer
+        tools_line = if @selected_formats.size == AI_TOOLS.size
+          "  # config.ai_tools = %i[claude cursor copilot windsurf opencode]  # default: all"
+        else
+          "  config.ai_tools = %i[#{@selected_formats.join(' ')}]"
+        end
+
         create_file "config/initializers/rails_ai_context.rb", <<~RUBY
           # frozen_string_literal: true
 
           RailsAiContext.configure do |config|
+            # AI tools to generate context files for (selected during install)
+            # Run `rails generate rails_ai_context:install` to change selection
+          #{tools_line}
+
             # Introspector preset:
-            #   :full     — all 28 introspectors (default — schema, models, routes, views, turbo, auth, API, assets, devops, etc.)
-            #   :standard — 13 core introspectors (schema, models, routes, jobs, gems, conventions, controllers, tests, migrations, stimulus, view_templates, design_tokens, config)
+            #   :full     — all 28 introspectors (default)
+            #   :standard — 13 core introspectors
             # config.preset = :full
 
-            # Or cherry-pick individual introspectors:
-            # config.introspectors += %i[views turbo auth api]
-
             # Models to exclude from introspection
             # config.excluded_models += %w[AdminUser InternalThing]
 
-            # Paths to exclude from code search
-            # config.excluded_paths += %w[vendor/bundle]
-
-            # Context mode for generated files (CLAUDE.md, .cursor/rules/, etc.)
-            # :compact — smart, ≤150 lines, references MCP tools for details (default)
-            # :full    — dumps everything into context files (good for small apps <30 models)
+            # Context mode: :compact (default, ≤150 lines) or :full (dumps everything)
             # config.context_mode = :compact
 
-            # Max lines for CLAUDE.md in compact mode
-            # config.claude_max_lines = 150
-
-            # Max response size for MCP tool results (chars). Safety net for large apps.
-            # config.max_tool_response_chars = 120_000
-
             # Live reload: auto-invalidate MCP tool caches on file changes
-            # :auto (default) — enable if `listen` gem is available
-            # true  — enable, raise if `listen` is missing
-            # false — disable entirely
             # config.live_reload = :auto
-            # config.live_reload_debounce = 1.5  # seconds
-
-            # Auto-mount HTTP MCP endpoint at /mcp
-            # config.auto_mount = false
-            # config.http_path  = "/mcp"
-            # config.http_port  = 6029
           end
         RUBY
 
@@ -104,13 +128,21 @@ module RailsAiContext
         say ""
         say "Generating AI context files...", :yellow
 
-        if Rails.application
-          require "rails_ai_context"
-          context = RailsAiContext.introspect
-          files = RailsAiContext.generate_context(format: :all)
-          files.each { |f| say "  Created #{f}", :green }
-        else
+        unless Rails.application
           say "  Skipped (Rails app not fully loaded). Run `rails ai:context` after install.", :yellow
+          return
+        end
+
+        require "rails_ai_context"
+
+        @selected_formats.each do |fmt|
+          begin
+            result = RailsAiContext.generate_context(format: fmt)
+            (result[:written] || []).each { |f| say "  ✅ #{f}", :green }
+            (result[:skipped] || []).each { |f| say "  ⏭️  #{f} (unchanged)", :yellow }
+          rescue => e
+            say "  ❌ #{fmt}: #{e.message}", :red
+          end
         end
       end
 
@@ -120,27 +152,26 @@ module RailsAiContext
         say " rails-ai-context installed!", :cyan
         say "=" * 50, :cyan
         say ""
-        say "Quick start:", :yellow
-        say "  rails ai:context         # Generate all context files"
-        say "  rails ai:context:claude   # Generate CLAUDE.md only"
-        say "  rails ai:context:cursor   # Generate .cursor/rules/ only"
-        say "  rails ai:serve           # Start MCP server (stdio)"
-        say "  rails ai:inspect         # Print introspection summary"
+        say "Your setup:", :yellow
+        AI_TOOLS.each_value do |info|
+          next unless @selected_formats.include?(info[:format])
+          say "  ✅ #{info[:name].ljust(16)} → #{info[:files]}"
+        end
         say ""
-        say "Generated files per AI tool:", :yellow
-        say "  Claude Code    → CLAUDE.md + .claude/rules/*.md"
-        say "  OpenCode       → AGENTS.md"
-        say "  Cursor         → .cursor/rules/*.mdc"
-        say "  Windsurf       → .windsurfrules + .windsurf/rules/*.md"
-        say "  GitHub Copilot → .github/copilot-instructions.md + .github/instructions/*.instructions.md"
+        say "Commands:", :yellow
+        say "  rails ai:context         # Regenerate context files"
+        say "  rails ai:serve           # Start MCP server (25 live tools)"
+        say "  rails ai:doctor          # Check AI readiness"
+        say "  rails ai:inspect         # Print introspection summary"
         say ""
         say "MCP auto-discovery:", :yellow
         say "  .mcp.json is auto-detected by Claude Code and Cursor."
-        say "  No manual MCP config needed — just open your project."
+        say "  No manual config needed — just open your project."
         say ""
-        say "Context modes:", :yellow
-        say "  rails ai:context         # compact mode (default, smart for any app size)"
-        say "  rails ai:context:full    # full dump (good for small apps)"
+        say "To add more AI tools later:", :yellow
+        say "  rails ai:context:cursor   # Generate for Cursor"
+        say "  rails ai:context:copilot  # Generate for Copilot"
+        say "  rails generate rails_ai_context:install  # Re-run to pick tools"
         say ""
         say "Commit context files and .mcp.json so your team benefits!", :green
       end

data/lib/rails_ai_context/configuration.rb

@@ -75,6 +75,10 @@ module RailsAiContext
     # Built-in tool names to skip (e.g. %w[rails_security_scan rails_get_design_system])
     attr_accessor :skip_tools
 
+    # Which AI tools to generate context for (selected during install)
+    # nil = all formats, or %i[claude cursor copilot windsurf opencode]
+    attr_accessor :ai_tools
+
     # Filtering — customize what's hidden from AI output
     attr_accessor :excluded_controllers   # Controller classes hidden from listings (e.g. DeviseController)
     attr_accessor :excluded_route_prefixes # Route controller prefixes hidden with app_only (e.g. action_mailbox/)
@@ -148,6 +152,7 @@ module RailsAiContext
       ]
       @custom_tools             = []
       @skip_tools               = []
+      @ai_tools                 = nil
       @search_extensions        = %w[rb js erb yml yaml json ts tsx vue svelte haml slim]
       @concern_paths            = %w[app/models/concerns app/controllers/concerns]
     end

data/lib/rails_ai_context/tasks/rails_ai_context.rake

@@ -24,24 +24,95 @@ def apply_context_mode_override
   end
 end unless defined?(apply_context_mode_override)
 
+AI_TOOL_OPTIONS = {
+  "1" => { key: :claude,   name: "Claude Code" },
+  "2" => { key: :cursor,   name: "Cursor" },
+  "3" => { key: :copilot,  name: "GitHub Copilot" },
+  "4" => { key: :windsurf, name: "Windsurf" },
+  "5" => { key: :opencode, name: "OpenCode" }
+}.freeze unless defined?(AI_TOOL_OPTIONS)
+
+def prompt_ai_tools
+  puts ""
+  puts "Which AI tools do you use? (select all that apply)"
+  puts ""
+  AI_TOOL_OPTIONS.each { |num, info| puts "  #{num}. #{info[:name]}" }
+  puts "  a. All of the above"
+  puts ""
+  print "Enter numbers separated by commas (e.g. 1,2) or 'a' for all: "
+  input = $stdin.gets&.strip&.downcase || "a"
+
+  selected = if input == "a" || input == "all" || input.empty?
+    AI_TOOL_OPTIONS.values.map { |t| t[:key] }
+  else
+    input.split(/[\s,]+/).filter_map { |n| AI_TOOL_OPTIONS[n]&.dig(:key) }
+  end
+
+  if selected.empty?
+    puts "No tools selected — using all."
+    selected = AI_TOOL_OPTIONS.values.map { |t| t[:key] }
+  end
+
+  names = AI_TOOL_OPTIONS.values.select { |t| selected.include?(t[:key]) }.map { |t| t[:name] }
+  puts "Selected: #{names.join(', ')}"
+  selected
+end unless defined?(prompt_ai_tools)
+
+def save_ai_tools_to_initializer(tools)
+  init_path = Rails.root.join("config/initializers/rails_ai_context.rb")
+  return unless File.exist?(init_path)
+
+  content = File.read(init_path)
+  tools_line = "  config.ai_tools = %i[#{tools.join(' ')}]"
+
+  if content.include?("config.ai_tools")
+    # Replace existing ai_tools line
+    content.sub!(/^.*config\.ai_tools.*$/, tools_line)
+  elsif content.include?("RailsAiContext.configure")
+    # Insert after configure block opening
+    content.sub!(/RailsAiContext\.configure do \|config\|\n/, "RailsAiContext.configure do |config|\n#{tools_line}\n")
+  else
+    return
+  end
+
+  File.write(init_path, content)
+  puts "💾 Saved to config/initializers/rails_ai_context.rb"
+rescue
+  nil
+end unless defined?(save_ai_tools_to_initializer)
+
 namespace :ai do
-  desc "Generate AI context files (CLAUDE.md, .cursor/rules/, .windsurfrules, .github/copilot-instructions.md)"
+  desc "Generate AI context files for configured AI tools (prompts on first run)"
   task context: :environment do
     require "rails_ai_context"
 
     apply_context_mode_override
 
+    ai_tools = RailsAiContext.configuration.ai_tools
+
+    # First time — no tools configured, ask the user
+    if ai_tools.nil?
+      ai_tools = prompt_ai_tools
+      save_ai_tools_to_initializer(ai_tools) if ai_tools
+    end
+
     puts "🔍 Introspecting #{Rails.application.class.module_parent_name}..."
 
-    puts "📝 Writing context files..."
-    result = RailsAiContext.generate_context(format: :all)
+    if ai_tools.nil? || ai_tools.empty?
+      puts "📝 Writing context files for all AI tools..."
+      result = RailsAiContext.generate_context(format: :all)
+      print_result(result)
+    else
+      puts "📝 Writing context files for: #{ai_tools.map(&:to_s).join(', ')}..."
+      ai_tools.each do |fmt|
+        result = RailsAiContext.generate_context(format: fmt)
+        print_result(result)
+      end
+    end
 
-    print_result(result)
     puts ""
-    puts "Done! Your AI assistants now understand your Rails app."
-    puts "Commit these files so your whole team benefits."
-    puts ""
-    puts ASSISTANT_TABLE
+    puts "Done! Commit these files so your team benefits."
+    puts "Change AI tools: config/initializers/rails_ai_context.rb (config.ai_tools)"
   end
 
   desc "Generate AI context in a specific format (claude, cursor, windsurf, copilot, json)"

data/lib/rails_ai_context/tools/get_routes.rb

@@ -168,7 +168,19 @@ module RailsAiContext
                   ctrl_lines << "- `#{r[:verb]}` `#{r[:path]}` → #{r[:action]}#{helper_part}#{params_part}"
                 end
                 if ctrl_lines.any?
-                  lines << "## #{ctrl}"
+                  # Inline controller summary so AI doesn't need a separate get_controllers call
+                  ctrl_class = "#{ctrl.camelize}Controller"
+                  ctrl_data = cached_context.dig(:controllers, :controllers, ctrl_class)
+                  ctrl_summary = ""
+                  if ctrl_data
+                    filters = (ctrl_data[:filters] || []).map { |f| f[:name] }.first(3)
+                    formats = ctrl_data[:respond_to_formats]
+                    parts = []
+                    parts << "filters: #{filters.join(', ')}" if filters.any?
+                    parts << "formats: #{formats.join(', ')}" if formats&.any?
+                    ctrl_summary = " (#{parts.join(' | ')})" if parts.any?
+                  end
+                  lines << "## #{ctrl}#{ctrl_summary}"
                   lines.concat(ctrl_lines)
                   lines << ""
                 end

data/lib/rails_ai_context/tools/get_schema.rb

@@ -144,7 +144,19 @@ module RailsAiContext
                 hint_str = hints.any? ? " [#{hints.join(', ')}]" : ""
                 "#{c[:name]}:#{c[:type]}#{hint_str}"
               end.join(", ")
-            lines << "### #{name}"
+            # Inline model info so AI doesn't need a separate get_model_details call
+            model_info = ""
+            if model_refs.any?
+              model_refs.each do |mname|
+                md = models_data[mname]
+                next unless md.is_a?(Hash) && !md[:error]
+                assoc_count = md[:associations]&.size || 0
+                val_count = md[:validations]&.size || 0
+                model_info = " → **#{mname}** (#{assoc_count} assoc, #{val_count} val)"
+                break
+              end
+            end
+            lines << "### #{name}#{model_info}"
             lines << cols
             lines << ""
           end

data/lib/rails_ai_context/tools/get_test_info.rb

@@ -76,6 +76,11 @@ module RailsAiContext
             lines << "" << "## Test Helpers"
             data[:test_helpers].each { |h| lines << "- `#{h}`" }
           end
+
+          # Generate a test template based on app patterns
+          template = generate_test_template(data)
+          lines.concat(template) if template.any?
+
           text_response(lines.join("\n"))
 
         when "full"
@@ -210,6 +215,89 @@ module RailsAiContext
         "No test file found for #{name}. Searched: #{candidates.join(', ')}#{hint}"
       end
 
+      # Generate a test template based on the app's actual test patterns
+      private_class_method def self.generate_test_template(data)
+        lines = []
+        framework = data[:framework]
+
+        if framework&.include?("RSpec") || framework&.include?("rspec")
+          lines << "" << "## Test Template (follow this pattern for new tests)"
+          lines << "```ruby"
+          lines << "require \"rails_helper\""
+          lines << ""
+          lines << "RSpec.describe ModelName, type: :model do"
+          lines << "  describe \"validations\" do"
+          lines << "    it { is_expected.to validate_presence_of(:field) }"
+          lines << "  end"
+          lines << ""
+          lines << "  describe \"#method_name\" do"
+          lines << "    it \"does something\" do"
+          lines << "      record = create(:model_name)"
+          lines << "      expect(record.method_name).to eq(expected)"
+          lines << "    end"
+          lines << "  end"
+          lines << "end"
+          lines << "```"
+        else
+          # Detect Devise + sign_in pattern from existing tests
+          has_devise = false
+          has_sign_in = false
+          test_dir = Rails.root.join("test")
+          if Dir.exist?(test_dir)
+            Dir.glob(File.join(test_dir, "**/*_test.rb")).first(5).each do |path|
+              content = File.read(path, encoding: "UTF-8") rescue next
+              has_devise = true if content.include?("Devise::Test")
+              has_sign_in = true if content.include?("sign_in")
+            end
+          end
+
+          lines << "" << "## Test Template (follow this pattern for new tests)"
+          lines << "```ruby"
+          lines << "require \"test_helper\""
+          lines << ""
+          lines << "class ModelNameTest < ActiveSupport::TestCase"
+          lines << "  test \"should be valid with required attributes\" do"
+          lines << "    record = model_names(:fixture_name)"
+          lines << "    assert record.valid?"
+          lines << "  end"
+          lines << ""
+          lines << "  test \"should require field\" do"
+          lines << "    record = ModelName.new"
+          lines << "    assert_not record.valid?"
+          lines << "    assert_includes record.errors[:field], \"can't be blank\""
+          lines << "  end"
+          lines << "end"
+          lines << "```"
+
+          if has_devise
+            lines << ""
+            lines << "```ruby"
+            lines << "# Controller test pattern"
+            lines << "require \"test_helper\""
+            lines << ""
+            lines << "class FeatureControllerTest < ActionDispatch::IntegrationTest"
+            lines << "  include Devise::Test::IntegrationHelpers" if has_devise
+            lines << ""
+            lines << "  test \"requires authentication\" do"
+            lines << "    get feature_path"
+            lines << "    assert_response :redirect"
+            lines << "  end"
+            lines << ""
+            lines << "  test \"shows page for signed in user\" do"
+            lines << "    sign_in users(:chef_one)" if has_sign_in
+            lines << "    get feature_path"
+            lines << "    assert_response :success"
+            lines << "  end"
+            lines << "end"
+            lines << "```"
+          end
+        end
+
+        lines
+      rescue
+        []
+      end
+
       # Parse factory file to extract attributes and traits
       private_class_method def self.parse_factory_details(relative_path)
         # Try common factory locations

data/lib/rails_ai_context/tools/get_view.rb

@@ -96,12 +96,14 @@ module RailsAiContext
 
             lines << "## #{ctrl}/" unless controller && all_dirs.size == 1
             ctrl_templates.sort.each do |name, meta|
-              parts = meta[:partials]&.any? ? " renders: #{meta[:partials].join(', ')}" : ""
-              stim = meta[:stimulus]&.any? ? " stimulus: #{meta[:stimulus].join(', ')}" : ""
+              detail_parts = []
+              detail_parts << "renders: #{meta[:partials].join(', ')}" if meta[:partials]&.any?
+              detail_parts << "stimulus: #{meta[:stimulus].join(', ')}" if meta[:stimulus]&.any?
               extra = extract_view_metadata(name)
-              ivars = extra[:ivars]&.any? ? " ivars: #{extra[:ivars].join(', ')}" : ""
-              turbo = extra[:turbo]&.any? ? " turbo: #{extra[:turbo].join(', ')}" : ""
-              lines << "- #{name} (#{meta[:lines]} lines)#{parts}#{stim}#{ivars}#{turbo}"
+              detail_parts << "ivars: #{extra[:ivars].join(', ')}" if extra[:ivars]&.any?
+              detail_parts << "turbo: #{extra[:turbo].join(', ')}" if extra[:turbo]&.any?
+              details = detail_parts.any? ? " — #{detail_parts.join(' | ')}" : ""
+              lines << "- **#{name}** (#{meta[:lines]} lines)#{details}"
             end
             ctrl_partials.sort.each do |name, meta|
               fields = meta[:fields]&.any? ? " fields: #{meta[:fields].join(', ')}" : ""

data/lib/rails_ai_context/tools/search_code.rb

@@ -6,24 +6,15 @@ module RailsAiContext
   module Tools
     class SearchCode < BaseTool
       tool_name "rails_search_code"
-      description "Search the Rails codebase by regex pattern, returning matching lines with file paths and line numbers. " \
-        "Use when: finding where a method is called, locating class definitions, or tracing how a feature is implemented. " \
-        "Requires pattern:\"def activate\". Narrow with path:\"app/models\" and file_type:\"rb\"."
+      description "Search the Rails codebase with smart modes. " \
+        "Use match_type:\"trace\" to see where a method is defined, who calls it, and what it calls — in one call. " \
+        "Use match_type:\"definition\" for definitions only, \"call\" for call sites only, \"class\" for class/module definitions. " \
+        "Requires pattern:\"method_name\". Narrow with path:\"app/models\" and file_type:\"rb\"."
 
       def self.max_results_cap
         RailsAiContext.configuration.max_search_results
       end
 
-      # Non-code files excluded from all searches — lock files, docs, generated context, config meta
-      NON_CODE_GLOBS = %w[
-        *.lock package-lock.json yarn.lock pnpm-lock.yaml bun.lockb
-        *.md LICENSE* CHANGELOG* CONTRIBUTING*
-        CLAUDE.md AGENTS.md .cursorrules .cursor/ .claude/
-        Dockerfile* docker-compose*
-        .rubocop.yml .ruby-version .node-version .tool-versions
-        .github/ .circleci/ .gitlab-ci.yml
-      ].freeze
-
       input_schema(
         properties: {
           pattern: {
@@ -40,16 +31,24 @@ module RailsAiContext
           },
           match_type: {
             type: "string",
-            enum: %w[any definition class],
-            description: "Filter match type. any: all matches (default). definition: only `def method_name` lines. class: only `class/module Name` lines."
+            enum: %w[any definition class call trace],
+            description: "any: all matches (default). definition: `def` lines only. class: `class/module` lines. call: call sites only (excludes definitions). trace: FULL PICTURE — shows definition + source code + all callers + what it calls internally."
           },
           exact_match: {
             type: "boolean",
             description: "Match whole words only (wraps pattern in \\b word boundaries). Default: false."
           },
-          max_results: {
+          exclude_tests: {
+            type: "boolean",
+            description: "Exclude test/spec files from results. Default: false."
+          },
+          group_by_file: {
+            type: "boolean",
+            description: "Group results by file with match counts. Default: false."
+          },
+          offset: {
             type: "integer",
-            description: "Maximum number of results. Default: 30, max: 200."
+            description: "Skip this many results for pagination. Default: 0."
           },
           context_lines: {
             type: "integer",
@@ -61,31 +60,40 @@ module RailsAiContext
 
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
 
-      def self.call(pattern:, path: nil, file_type: nil, match_type: "any", exact_match: false, max_results: 30, context_lines: 2, server_context: nil)
+      def self.call(pattern:, path: nil, file_type: nil, match_type: "any", exact_match: false, exclude_tests: false, group_by_file: false, offset: 0, context_lines: 2, server_context: nil) # rubocop:disable Metrics
         root = Rails.root.to_s
+        original_pattern = pattern
 
         # Reject empty or whitespace-only patterns
         if pattern.nil? || pattern.strip.empty?
           return text_response("Pattern is required. Provide a search term or regex.")
         end
 
+        # Trace mode — the game changer: full method picture in one call
+        if match_type == "trace"
+          return trace_method(pattern.strip, root, path, exclude_tests)
+        end
+
         # Apply exact_match word boundaries
         pattern = "\\b#{pattern}\\b" if exact_match
 
-        # Apply match_type filter to pattern (strip keyword if user already included it)
-        pattern = case match_type
+        # Apply match_type filter to pattern
+        search_pattern = case match_type
         when "definition"
           cleaned = pattern.sub(/\A\s*def\s+/, "")
           "^\\s*def\\s+(self\\.)?#{cleaned}"
         when "class"
           cleaned = pattern.sub(/\A\s*(class|module)\s+/, "")
-          "^\\s*(class|module)\\s+#{cleaned}"
-        else pattern
+          "^\\s*(class|module)\\s+\\w*#{cleaned}"
+        when "call"
+          pattern
+        else
+          pattern
         end
 
         # Validate regex syntax early
         begin
-          Regexp.new(pattern, timeout: 1)
+          Regexp.new(search_pattern, timeout: 1)
         rescue RegexpError => e
           return text_response("Invalid regex pattern: #{e.message}")
         end
@@ -95,10 +103,8 @@ module RailsAiContext
           return text_response("Invalid file_type: must contain only alphanumeric characters.")
         end
 
-        # Cap max_results and context_lines
-        max_results = [ max_results.to_i, max_results_cap ].min
-        max_results = 30 if max_results < 1
         context_lines = [ [ context_lines.to_i, 0 ].max, 5 ].min
+        offset = [ offset.to_i, 0 ].max
 
         search_path = path ? File.join(root, path) : root
 
@@ -118,28 +124,60 @@ module RailsAiContext
           return text_response("Path not found: #{path}")
         end
 
-        results = if ripgrep_available?
-                    search_with_ripgrep(pattern, search_path, file_type, max_results, root, context_lines)
+        # Fetch all results (capped at 200 for safety)
+        all_results = if ripgrep_available?
+          search_with_ripgrep(search_pattern, search_path, file_type, max_results_cap, root, context_lines, exclude_tests: exclude_tests)
         else
-                    search_with_ruby(pattern, search_path, file_type, max_results, root)
+          search_with_ruby(search_pattern, search_path, file_type, max_results_cap, root, exclude_tests: exclude_tests)
+        end
+
+        # Filter out definitions for match_type:"call"
+        all_results.reject! { |r| r[:content].match?(/\A\s*def\s/) } if match_type == "call"
+
+        if all_results.empty?
+          return text_response("No results found for '#{original_pattern}' in #{path || 'app'}.")
         end
 
-        if results.empty?
-          return text_response("No results found for '#{pattern}' in #{path || 'app'}.")
+        # Smart result limiting:
+        # <10 total → show all, 10-100 → show half, >100 → cap at 100
+        total = all_results.size
+        show_count = if total <= 10 then total
+        elsif total <= 100 then (total / 2.0).ceil
+        else 100
         end
 
-        output = results.map { |r| "#{r[:file]}:#{r[:line_number]}: #{r[:content].strip}" }.join("\n")
-        header = "# Search: `#{pattern}`\n**#{results.size} results**#{" in #{path}" if path}\n\n```\n"
-        footer = "\n```"
+        # Apply pagination
+        paginated = all_results.drop(offset).first(show_count)
 
-        text_response("#{header}#{output}#{footer}")
+        if paginated.empty? && total > 0
+          return text_response("No results at offset #{offset}. Total: #{total}. Use `offset:0`.")
+        end
+
+        # Build header with total count and pagination info
+        showing = offset > 0 ? "#{offset + 1}-#{offset + paginated.size}" : "#{paginated.size}"
+        pagination = if offset + paginated.size < total
+          "\n_Showing #{showing} of #{total}. Use `offset:#{offset + paginated.size}` for more._"
+        elsif total > paginated.size
+          "\n_Showing #{showing} of #{total}._"
+        else
+          ""
+        end
+
+        header = "# Search: `#{original_pattern}`\n**#{total} total results**#{" in #{path}" if path}, showing #{showing}\n"
+
+        if group_by_file
+          text_response(header + "\n" + format_grouped(paginated) + pagination)
+        else
+          output = paginated.map { |r| "#{r[:file]}:#{r[:line_number]}: #{r[:content].strip}" }.join("\n")
+          text_response("#{header}\n```\n#{output}\n```#{pagination}")
+        end
       end
 
       private_class_method def self.ripgrep_available?
         @rg_available ||= system("which rg > /dev/null 2>&1")
       end
 
-      private_class_method def self.search_with_ripgrep(pattern, search_path, file_type, max_results, root, ctx_lines = 0)
+      private_class_method def self.search_with_ripgrep(pattern, search_path, file_type, max_results, root, ctx_lines = 0, exclude_tests: false)
         cmd = [ "rg", "--no-heading", "--line-number", "--sort=path", "--max-count", max_results.to_s ]
         if ctx_lines > 0
           cmd.push("-C", ctx_lines.to_s)
@@ -157,9 +195,12 @@ module RailsAiContext
           cmd << "--glob=!#{p}"
         end
 
-        # Exclude non-code files that generate noise in search results
-        # (excluded_paths already handles node_modules, tmp, log, vendor, .git)
-        NON_CODE_GLOBS.each { |glob| cmd << "--glob=!#{glob}" }
+        # Exclude test/spec directories if requested
+        if exclude_tests
+          cmd << "--glob=!test/"
+          cmd << "--glob=!spec/"
+          cmd << "--glob=!features/"
+        end
 
         if file_type
           cmd.push("--type-add", "custom:*.#{file_type}", "--type", "custom")
@@ -178,7 +219,7 @@ module RailsAiContext
         [ { file: "error", line_number: 0, content: e.message } ]
       end
 
-      private_class_method def self.search_with_ruby(pattern, search_path, file_type, max_results, root)
+      private_class_method def self.search_with_ruby(pattern, search_path, file_type, max_results, root, exclude_tests: false)
         results = []
         begin
           regex = Regexp.new(pattern, Regexp::IGNORECASE, timeout: 2)
@@ -189,11 +230,13 @@ module RailsAiContext
         glob = file_type ? "**/*.#{file_type}" : "**/*.{#{extensions}}"
         excluded = RailsAiContext.configuration.excluded_paths
         sensitive = RailsAiContext.configuration.sensitive_patterns
+        test_dirs = %w[test/ spec/ features/]
 
         Dir.glob(File.join(search_path, glob)).each do |file|
           relative = file.sub("#{root}/", "")
           next if excluded.any? { |ex| relative.start_with?(ex) }
           next if sensitive_file?(relative, sensitive)
+          next if exclude_tests && test_dirs.any? { |td| relative.start_with?(td) }
 
           File.readlines(file).each_with_index do |line, idx|
             if line.match?(regex)
@@ -216,6 +259,20 @@ module RailsAiContext
         end
       end
 
+      # Group results by file for cleaner output
+      private_class_method def self.format_grouped(results)
+        grouped = results.group_by { |r| r[:file] }
+        lines = []
+        grouped.each do |file, matches|
+          lines << "## #{file} (#{matches.size} matches)"
+          lines << "```"
+          matches.each { |r| lines << "#{r[:line_number]}: #{r[:content].strip}" }
+          lines << "```"
+          lines << ""
+        end
+        lines.join("\n")
+      end
+
       private_class_method def self.parse_rg_output(output, root)
         output.lines.filter_map do |line|
           next if line.strip == "--" # Skip group separators from -C context output
@@ -229,6 +286,129 @@ module RailsAiContext
           }
         end
       end
+
+      # ── Trace Mode — the game changer ──────────────────────────────
+      # Shows definition + source + callers + internal calls in one response
+
+      private_class_method def self.trace_method(method_name, root, path, exclude_tests) # rubocop:disable Metrics
+        # Clean input: strip "def ", "self.", parens
+        cleaned = method_name.sub(/\A\s*def\s+/, "").sub(/\Aself\./, "").sub(/\(.*/, "").strip
+        return text_response("Provide a method name to trace.") if cleaned.empty?
+
+        search_path = path ? File.join(root, path) : root
+        lines = [ "# Trace: `#{cleaned}`", "" ]
+
+        # 1. Find the definition (no \b after ? or ! since they ARE word boundaries)
+        def_pattern = "^\\s*def\\s+(self\\.)?#{Regexp.escape(cleaned)}"
+        def_pattern += "\\b" unless cleaned.end_with?("?") || cleaned.end_with?("!")
+        def_results = quick_search(def_pattern, search_path, root, 10, exclude_tests)
+
+        if def_results.any?
+          lines << "## Definition"
+          def_results.each do |r|
+            lines << "**#{r[:file]}:#{r[:line_number]}**"
+            # Extract the full method body
+            body = extract_method_body(File.join(root, r[:file]), r[:line_number])
+            if body
+              lines << "```ruby"
+              lines << body
+              lines << "```"
+
+              # 3. What does this method call? (extract method-like calls from body)
+              internal_calls = body.scan(/\b([a-z_]\w*[!?]?)(?:\s*[\(])/).flatten.uniq
+              internal_calls += body.scan(/\b([A-Z]\w+(?:::\w+)*)\.(new|call|perform_later|perform_async|find|where|create)/).map { |c| "#{c[0]}.#{c[1]}" }
+              internal_calls.reject! { |c| %w[if else elsif unless return end def class module do begin rescue ensure raise puts print].include?(c) }
+              internal_calls.reject! { |c| c == cleaned }
+
+              if internal_calls.any?
+                lines << "" << "## Calls internally"
+                internal_calls.first(15).each { |c| lines << "- `#{c}`" }
+              end
+            end
+            lines << ""
+          end
+        else
+          lines << "_No definition found for `def #{cleaned}`_"
+          lines << ""
+        end
+
+        # 2. Find all callers (everywhere the method is referenced, excluding the def line)
+        call_pattern = if cleaned.end_with?("?") || cleaned.end_with?("!")
+          "#{Regexp.escape(cleaned)}"
+        else
+          "\\b#{Regexp.escape(cleaned)}\\b"
+        end
+        call_results = quick_search(call_pattern, search_path, root, max_results_cap, exclude_tests)
+        callers = call_results.reject { |r| r[:content].match?(/\A\s*def\s/) }
+
+        # Exclude the definition file+line to avoid self-reference
+        def_locations = def_results.map { |r| "#{r[:file]}:#{r[:line_number]}" }.to_set
+        callers.reject! { |r| def_locations.include?("#{r[:file]}:#{r[:line_number]}") }
+
+        if callers.any?
+          lines << "## Called from (#{callers.size} sites)"
+
+          # Group by file for readability
+          grouped = callers.group_by { |r| r[:file] }
+          grouped.each do |file, matches|
+            # Categorize the file
+            category = case file
+            when /controller/i then "Controller"
+            when /model/i then "Model"
+            when /view|\.erb/i then "View"
+            when /job/i then "Job"
+            when /service/i then "Service"
+            when /test|spec/i then "Test"
+            when /\.js$|\.ts$/i then "JavaScript"
+            else "Other"
+            end
+
+            lines << "### #{file} (#{category})"
+            matches.first(5).each do |r|
+              lines << "  #{r[:line_number]}: #{r[:content].strip}"
+            end
+            lines << "  _(#{matches.size - 5} more)_" if matches.size > 5
+          end
+        else
+          lines << "## Called from"
+          lines << "_No call sites found (method may be unused or called dynamically)_"
+        end
+
+        text_response(lines.join("\n"))
+      rescue => e
+        text_response("Trace error: #{e.message}")
+      end
+
+      # Fast ripgrep search for trace mode (no formatting, just results)
+      private_class_method def self.quick_search(pattern, search_path, root, limit, exclude_tests)
+        if ripgrep_available?
+          search_with_ripgrep(pattern, search_path, nil, limit, root, 0, exclude_tests: exclude_tests)
+        else
+          search_with_ruby(pattern, search_path, nil, limit, root, exclude_tests: exclude_tests)
+        end
+      end
+
+      # Extract a method body from a file given the def line number
+      private_class_method def self.extract_method_body(file_path, def_line)
+        return nil unless File.exist?(file_path)
+        return nil if File.size(file_path) > RailsAiContext.configuration.max_file_size
+
+        source_lines = File.readlines(file_path)
+        start_idx = def_line - 1
+        return nil if start_idx >= source_lines.size
+
+        def_indent = source_lines[start_idx][/\A\s*/].length
+        result = [ source_lines[start_idx].rstrip ]
+
+        source_lines[(start_idx + 1)..].each do |line|
+          result << line.rstrip
+          break if line.match?(/\A\s{#{def_indent}}end\b/)
+        end
+
+        result.join("\n")
+      rescue
+        nil
+      end
     end
   end
 end

data/lib/rails_ai_context/tools/validate.rb

@@ -95,6 +95,12 @@ module RailsAiContext
           end
         end
 
+        # Run Brakeman security scan on validated files (if installed and level:"rails")
+        if level == "rails"
+          brakeman_warnings = check_brakeman_security(files)
+          brakeman_warnings.each { |w| results << "  \u26A0 #{w}" }
+        end
+
         output = results.join("\n")
         output += "\n\n#{passed}/#{total} files passed"
         output += " _(Prism unavailable — using fallback parser, some semantic checks skipped)_" unless prism_available?
@@ -950,6 +956,48 @@ module RailsAiContext
       rescue
         []
       end
+
+      # ── Brakeman security scan (runs once for all files) ───────────
+
+      private_class_method def self.check_brakeman_security(files)
+        return [] unless brakeman_available?
+
+        tracker = Brakeman.run(
+          app_path: Rails.root.to_s,
+          quiet: true,
+          report_progress: false,
+          print_report: false
+        )
+
+        warnings = tracker.filtered_warnings
+        return [] if warnings.empty?
+
+        # Filter to only warnings in the validated files
+        normalized = files.map { |f| f.delete_prefix("/") }
+        relevant = warnings.select do |w|
+          path = w.file.relative
+          normalized.any? { |f| path == f || path.start_with?(f) }
+        end
+        return [] if relevant.empty?
+
+        relevant.sort_by(&:confidence).first(5).map do |w|
+          loc = w.line ? "#{w.file.relative}:#{w.line}" : w.file.relative
+          "[#{w.confidence_name}] #{w.warning_type} — #{loc}: #{w.message}"
+        end
+      rescue
+        []
+      end
+
+      private_class_method def self.brakeman_available?
+        return @brakeman_available unless @brakeman_available.nil?
+
+        @brakeman_available = begin
+          require "brakeman"
+          true
+        rescue LoadError
+          false
+        end
+      end
     end
   end
 end

data/lib/rails_ai_context/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAiContext
-  VERSION = "2.0.1"
+  VERSION = "2.0.2"
 end

data/server.json

@@ -7,11 +7,11 @@
     "url": "https://github.com/crisnahine/rails-ai-context",
     "source": "github"
   },
-  "version": "2.0.1",
+  "version": "2.0.2",
   "packages": [
     {
       "registryType": "mcpb",
-      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v2.0.1/rails-ai-context-mcp.mcpb",
+      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v2.0.2/rails-ai-context-mcp.mcpb",
       "fileSha256": "dd711a0ad6c4de943ae4da94eaf59a6dc9494b9d57f726e24649ed4e2f156990",
       "transport": {
         "type": "stdio"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-ai-context
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.0.2
 platform: ruby
 authors:
 - crisnahine