rails-ai-context 5.32.2 → 5.34.0

data/lib/rails_ai_context/tools/search_code.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require "set"
 
 module RailsAiContext
   module Tools
@@ -34,6 +35,9 @@ module RailsAiContext
       # one on a receiver (`def self.x`, `def Widget.x`) are definitions too.
       DEF_HEAD = "^\\s*(?:[a-z_]\\w*\\s+)*def\\s+(?:(?:self|[A-Z]\\w*(?:::[A-Z]\\w*)*)\\.)?"
       DEF_LINE = /\A\s*(?:[a-z_]\w*\s+)*def\s/
+      # A method or constant name, receiver or namespace and all, or one of
+      # Ruby's operator method names.
+      PLAIN_NAME = %r{\A(?:(?:self|[A-Z]\w*(?:::[A-Z]\w*)*)\.)?(?:(?:::)?[A-Za-z_]\w*(?:::[A-Za-z_]\w*)*[?!=]?|\[\]=?|[-+]@|\*\*|<=>|===?|[=!]~|!=|<<|>>|[<>]=|[-+*/%<>&|^~!`])\z}
       # Constant forms that define a class without the keyword.
       CLASS_BUILDERS = "(?:::)?(?:Data\\.define|Struct\\.new|Class\\.new|Module\\.new)\\b"
       NOT_A_CALL_LINE = {
@@ -58,7 +62,7 @@ module RailsAiContext
         properties: {
           pattern: {
             type: "string",
-            description: "Search pattern (regex supported)."
+            description: "Search pattern (regex supported). For definition and class, a plain method or constant name matches literally (`valid?`), anything else as a regex (`generate_.*`)."
           },
           path: {
             type: "string",
@@ -71,7 +75,7 @@ module RailsAiContext
           match_type: {
             type: "string",
             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."
+            description: "any: all matches (default). definition: `def` lines whose method name contains the pattern. class: `class/module` lines whose name contains it. call: call sites only (excludes definitions). trace: FULL PICTURE - shows definition + source code + all callers + what it calls internally."
           },
           exact_match: {
             type: "boolean",
@@ -121,25 +125,31 @@ module RailsAiContext
 
         # Trace mode: definition + source + callers + internal calls in one response
         if match_type == "trace"
-          return trace_method(pattern.strip, root, path, exclude_tests)
+          search_path, answer = resolve_search_path(path, root)
+          return answer || trace_method(pattern.strip, root, search_path, exclude_tests)
         end
 
         # Validate match_type
         valid_match_types = %w[any definition class call trace]
         unless valid_match_types.include?(match_type)
-          return text_response("Unknown match_type: '#{match_type}'. Valid values: #{valid_match_types.join(', ')}")
+          return text_response("Unknown match_type: '#{echo_input(match_type)}'. Valid values: #{valid_match_types.join(', ')}")
         end
 
         # Apply match_type filter to pattern (exact_match word boundaries applied per-type)
         search_pattern = case match_type
         when "definition"
           cleaned = pattern.sub(/\A\s*def\s+/, "")
-          escaped = literal(cleaned)
-          # `def\s+` already anchors the left edge, so only a trailing boundary.
-          exact_match ? "#{DEF_HEAD}#{escaped}#{RailsAiContext::MethodName.definition_end(cleaned)}" : "#{DEF_HEAD}#{escaped}"
+          if exact_match
+            # `def\s+` already anchors the left edge, so only a trailing boundary.
+            "#{DEF_HEAD}#{literal(cleaned)}#{RailsAiContext::MethodName.definition_end(cleaned)}"
+          else
+            # Anywhere in the name, as `class` takes a prefix: `slug` finds
+            # `def generate_slug` as well as `def slug_source`.
+            "#{DEF_HEAD}\\w*#{name_source(cleaned)}"
+          end
         when "class"
           cleaned = pattern.sub(/\A\s*(class|module)\s+/, "")
-          name = "(?:\\w+::)*\\w*#{literal(cleaned)}"
+          name = "(?:\\w+::)*\\w*#{exact_match ? literal(cleaned) : name_source(cleaned)}"
           # `\w*` stays unbounded so a CamelCase prefix still resolves.
           tail = exact_match ? trailing_boundary(cleaned) : "\\w*"
           "^\\s*(?:(?:class|module)\\s+(?:::)?#{name}#{exact_match ? tail : ""}|#{name}#{tail}\\s*=\\s*#{CLASS_BUILDERS})"
@@ -164,38 +174,21 @@ module RailsAiContext
         context_lines = [ [ context_lines.to_i, 0 ].max, 5 ].min
         offset = [ offset.to_i, 0 ].max
 
-        # Before the join, which would turn an absolute path into a subpath of
-        # the root and leave it looking merely absent.
-        return error_response("Path not allowed: #{path}") if path && RailsAiContext::SafePath.traversal?(path)
-
-        search_path = path ? File.join(root, path) : root
-        return error_response("Path not allowed: #{path}") if path && sensitive_file?(path)
-
-        # A symlink under the root can still resolve outside it; that check is
-        # on the realpath below.
-        unless File.exist?(search_path)
-          top_dirs = Dir.glob(File.join(root, "*")).select { |f| File.directory?(f) }.map { |f| File.basename(f) }.sort
-          return text_response("Path not found: #{path}. Top-level directories: #{top_dirs.first(15).join(', ')}")
-        end
-
-        begin
-          real_root = File.realpath(root)
-          real_search = File.realpath(search_path)
-        rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP, Errno::ENAMETOOLONG
-          return text_response("Path not found: #{path}")
-        end
-        return error_response("Path not allowed: #{path}") unless RailsAiContext::SafePath.contained?(real_search, real_root)
-        # A file named as the path is read whatever it is linked to.
-        return error_response("Path not allowed: #{path}") if File.file?(real_search) && sensitive_file?(real_search.delete_prefix("#{real_root}/"))
+        search_path, answer = resolve_search_path(path, root)
+        return answer if answer
 
+        # The cap counts context lines too, so one below the first match's
+        # leading context cut the match itself and the answer read "No results
+        # found". It always holds that much.
+        line_cap = [ max_results_cap, context_lines + 1 ].max
         # One row past the cap, so a cut list is knowable rather than silent.
-        fetch_limit = max_results_cap + 1
+        fetch_limit = line_cap + 1
         fetched, search_error = if ripgrep_available?
           search_with_ripgrep(search_pattern, search_path, file_type, fetch_limit, root, context_lines, exclude_tests: exclude_tests)
         else
           search_with_ruby(search_pattern, search_path, file_type, fetch_limit, root, context_lines, exclude_tests: exclude_tests)
         end
-        all_results, truncated = cap_results(fetched)
+        all_results, truncated = cap_results(fetched, line_cap)
 
         # A definition or comment line stays as context, never as a call site.
         if match_type == "call"
@@ -205,7 +198,9 @@ module RailsAiContext
         all_results = confirmed_rows(all_results, root, build_regexp(search_pattern, timeout: 1), context_lines)
 
         if all_results.empty?
-          return empty_response("No results found for '#{original_pattern}' in #{path || 'app'}.")
+          # The lines past a cut were never read, so they may still match.
+          unread = truncated ? " in the first #{count_phrase(line_cap, 'line')} scanned (max_search_results); more lines remain" : ""
+          return empty_response("No results found for '#{echo_input(original_pattern)}' in #{path ? echo_input(path) : 'app'}#{unread}.")
         end
 
         # A non-empty row list whose flags all went missing still found
@@ -253,7 +248,7 @@ module RailsAiContext
         mixed = paginated.any? { |r| !match_row?(r) }
         with_context = mixed ? " (#{count_phrase(paginated.size, 'line')} with context)" : ""
         header = "# Search: `#{original_pattern}`\n" \
-          "**#{capped_match_phrase(match_total, truncated)}#{scanned_note(truncated)}**#{" in #{path}" if path}, " \
+          "**#{capped_match_phrase(match_total, truncated)}#{scanned_note(truncated, line_cap)}**#{" in #{path}" if path}, " \
           "showing #{shown}#{with_context}\n"
         header += "`>` = match line\n" if mixed
         header += "_The limit held only context lines, so this page starts at the next match._\n" if moved_to_match
@@ -285,6 +280,13 @@ module RailsAiContext
         Regexp.escape(text).gsub("\\ ", " ")
       end
 
+      # A definition or class search reads a plain name literally, so `valid?`
+      # is not `vali` and an optional `d`, and any other pattern as the regex
+      # the schema promises: `\w+Job`, `generate_.*`.
+      private_class_method def self.name_source(text)
+        text.match?(PLAIN_NAME) ? literal(text) : "(?:#{text})"
+      end
+
       # "> " for match lines, "  " for context lines; empty when the result
       # set has no context lines to distinguish from.
       private_class_method def self.line_marker(result, mixed)
@@ -325,11 +327,16 @@ module RailsAiContext
 
       private_class_method def self.ripgrep_available?
         return @rg_available unless @rg_available.nil?
-        @rg_available = system("which rg > /dev/null 2>&1")
+        @rg_available = Executable.on_path?("rg")
       end
 
       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", "--with-filename", "--line-number", "--sort=path", "--max-count", max_results.to_s ]
+        # On Windows ripgrep joins the paths it finds with backslashes, which
+        # neither strip the root nor meet the sensitive patterns' slashes.
+        # --crlf ends a line before its CRLF, which is every line of a Windows
+        # checkout: without it `end$` matched none of them and `\s$` all.
+        cmd = [ "rg", "--no-heading", "--with-filename", "--line-number", "--sort=path", "--path-separator", "/",
+                "--crlf", "--max-count", max_results.to_s ]
         if ctx_lines > 0
           cmd.push("-C", ctx_lines.to_s)
           cmd.push("--field-context-separator", CONTEXT_FIELD_SEPARATOR)
@@ -360,8 +367,18 @@ module RailsAiContext
         cmd << "--" # Prevent pattern from being parsed as flags
         cmd << pattern
         cmd << search_path
-
-        output, err, status = Open3.capture3(*cmd)
+        # ripgrep enters no linked directory by itself but follows one it is handed.
+        trees = linked_trees(search_path, root, skip_rule(exclude_tests))
+        cmd.concat(trees.map(&:first).reject { |dir| dir == search_path })
+
+        output, err, status = begin
+          Open3.capture3(*cmd)
+        rescue SystemCallError
+          # Windows refuses a command line past 32K characters, and the error
+          # repeated the whole line, pattern and all. The Ruby search takes a
+          # pattern of any length.
+          return search_with_ruby(pattern, search_path, file_type, max_results, root, ctx_lines, exclude_tests: exclude_tests)
+        end
 
         # rg exits 1 for "no matches" and 2 for any error, including one it
         # recovered from - an unreadable file in the tree - and it still
@@ -375,7 +392,7 @@ module RailsAiContext
 
         # SafePath, not an rg glob, drops sensitive files: a glob cannot exempt a placeholder.
         rows = parse_rg_output(output, root)
-          .reject { |r| sensitive_file?(r[:file]) }
+          .reject { |r| sensitive_file?(r[:file]) || sensitive_in_tree?(r[:file], trees, root) }
           .first(max_results)
         [ rows, failed ]
       rescue => e
@@ -405,8 +422,7 @@ module RailsAiContext
         end
         # ripgrep searches a file it is named whatever its type or ignore files say.
         if File.file?(search_path)
-          relative = File.realpath(search_path).delete_prefix("#{File.realpath(root)}/")
-          scan_file(File.realpath(search_path), relative, regex, ctx_lines, max_results, results)
+          scan_file(File.realpath(search_path), spelled_relative(search_path, root), regex, ctx_lines, max_results, results)
           return [ results, search_error ]
         end
         return [ results, search_error ] unless File.directory?(search_path)
@@ -414,27 +430,148 @@ module RailsAiContext
         # Every file ripgrep searches, unless the app narrowed the fallback
         # with search_extensions.
         extensions = file_type ? [ file_type ] : RailsAiContext.configuration.search_extensions&.map(&:to_s)
-        # Read as ripgrep reads its `--glob=!` globs: `docs` at any depth, and
-        # `log` never reaching `logo/`.
-        skipped = RailsAiContext.configuration.excluded_paths + (exclude_tests ? TEST_DIRS : [])
-        skip_rules = RailsAiContext::GitIgnore.parse(skipped.join("\n"))
-        skip = ->(relative, dir) { RailsAiContext::GitIgnore.verdict(skip_rules, relative, dir: dir) == :ignore }
+        skip = skip_rule(exclude_tests)
         ai_context = ai_context_paths
 
         # ripgrep's walk and ignore files, so both backends search the same
-        # files, gitignored secrets excluded.
-        RailsAiContext::GitIgnore.for_tree(root).each_file(File.realpath(search_path), skip: skip) do |file, relative|
-          next if extensions && extensions.none? { |ext| file.end_with?(".#{ext}") }
-          next if sensitive_file?(relative) || ai_context_file?(ai_context, relative)
-          return [ results, search_error ] if scan_file(file, relative, regex, ctx_lines, max_results, results)
-        rescue => _e
-          search_error = true
-          next # Skip a file this process cannot read or scan
+        # files, gitignored secrets excluded: the tree under the root, then each
+        # directory linked in from the app's repository, under the name the app
+        # gives it and read against the ignore files where it lives.
+        linked = linked_trees(search_path, root, skip)
+        real_search = File.realpath(search_path)
+        own = RailsAiContext::SafePath.contained?(real_search, File.realpath(root)) ? [ [ nil, real_search, nil ] ] : []
+        (own + linked).each do |spelled, start, base|
+          prefix = spelled && spelled_relative(spelled, root)
+          in_tree = prefix ? ->(relative, dir) { skip.call("#{prefix}/#{relative}", dir) } : skip
+          RailsAiContext::GitIgnore.for_tree(prefix ? start : root).each_file(start, skip: in_tree) do |file, walked|
+            relative = prefix ? "#{prefix}/#{walked}" : walked
+            next if extensions && extensions.none? { |ext| file.end_with?(".#{ext}") }
+            next if sensitive_file?(relative) || ai_context_file?(ai_context, relative)
+            next if base && sensitive_file?(base.empty? ? walked : "#{base}/#{walked}")
+            return [ results, search_error ] if scan_file(file, relative, regex, ctx_lines, max_results, results)
+          rescue => _e
+            search_error = true
+            next # Skip a file this process cannot read or scan
+          end
         end
 
         [ results, search_error ]
       end
 
+      # Where a search runs: the root, or `path` under it when that resolves
+      # inside the root or through a directory linked in from the app's
+      # repository (SafePath.linked_in). [search_path, nil], or [nil, the
+      # answer that refuses the path or does not find it].
+      private_class_method def self.resolve_search_path(path, root)
+        return [ root, nil ] unless path
+
+        # Before the join, which would turn an absolute path into a subpath of
+        # the root and leave it looking merely absent.
+        return [ nil, error_response("Path not allowed: #{echo_input(path)}") ] if RailsAiContext::SafePath.traversal?(path)
+        return [ nil, error_response("Path not allowed: #{echo_input(path)} (sensitive file)") ] if sensitive_file?(path)
+
+        search_path = File.join(root, path)
+        # A symlink under the root can still resolve outside it; that check is
+        # on the realpath below.
+        unless File.exist?(search_path)
+          top_dirs = Dir.glob(File.join(root, "*")).select { |f| File.directory?(f) }.map { |f| File.basename(f) }.sort
+          return [ nil, text_response("Path not found: #{echo_input(path)}. Top-level directories: #{top_dirs.first(15).join(', ')}") ]
+        end
+
+        real_root = File.realpath(root)
+        real_search = File.realpath(search_path)
+        inside = RailsAiContext::SafePath.contained?(real_search, real_root)
+        linked = !inside && RailsAiContext::SafePath.linked_in(search_path, real_search, root, root)
+        return [ nil, error_response("Path not allowed: #{echo_input(path)}") ] unless inside || linked
+        # A file named as the path is read whatever it is linked to, so the
+        # name it has where it lives is asked too.
+        real_name = real_search.delete_prefix("#{linked || real_root}/")
+        return [ nil, error_response("Path not allowed: #{echo_input(path)} (sensitive file)") ] if File.file?(real_search) && sensitive_file?(real_name)
+
+        [ search_path, nil ]
+      rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP, Errno::ENAMETOOLONG
+        [ nil, text_response("Path not found: #{echo_input(path)}") ]
+      end
+
+      # Read as ripgrep reads its `--glob=!` globs: `docs` at any depth, and
+      # `log` never reaching `logo/`.
+      private_class_method def self.skip_rule(exclude_tests)
+        skipped = RailsAiContext.configuration.excluded_paths + (exclude_tests ? TEST_DIRS : [])
+        skip_rules = RailsAiContext::GitIgnore.parse(skipped.join("\n"))
+        ->(relative, dir) { RailsAiContext::GitIgnore.verdict(skip_rules, relative, dir: dir) == :ignore }
+      end
+
+      # The trees a search reads past the root's own, each as [path as spelled,
+      # real path, where that sits in its linked-in directory]: `search_path`
+      # when a directory linked in from the app's repository leads to it
+      # (SafePath.linked_in), then each such directory below it (linked_dirs).
+      private_class_method def self.linked_trees(search_path, root, skip)
+        real_search = File.realpath(search_path)
+        trees = []
+        unless RailsAiContext::SafePath.contained?(real_search, File.realpath(root))
+          linked = RailsAiContext::SafePath.linked_in(search_path, real_search, root, root)
+          trees << [ search_path, real_search, real_search == linked ? "" : real_search.delete_prefix("#{linked}/") ] if linked
+        end
+        trees + linked_dirs(search_path, root, skip).map { |name, target| [ name, target, "" ] }
+      rescue SystemCallError
+        []
+      end
+
+      # The directories linked in from the app's repository below `search_path`
+      # (SafePath.link_bound) that ripgrep's walk meets past the same ignore
+      # files and enters none of, a link inside one too, as [path as spelled,
+      # real path]. Each place is searched once: a link into the root or into
+      # another tree searched leads where the search goes already, and one up
+      # over the root or the search path would search them again.
+      private_class_method def self.linked_dirs(search_path, root, skip)
+        bound = RailsAiContext::SafePath.link_bound(root)
+        real_root = File.realpath(root)
+        # Outside a monorepo, nothing outside the root counts.
+        return [] if bound == real_root || !File.directory?(search_path)
+
+        real_search = File.realpath(search_path)
+        visited = Set.new([ real_root, real_search ])
+        pending = [ [ search_path, real_search ] ]
+        found = []
+        until pending.empty?
+          spelled, real = pending.shift
+          inside = RailsAiContext::SafePath.contained?(real, real_root)
+          prefix = spelled_relative(spelled, root)
+          rule = inside ? skip : ->(relative, dir) { skip.call("#{prefix}/#{relative}", dir) }
+          RailsAiContext::GitIgnore.for_tree(inside ? real_root : real).dir_links(real, skip: rule).each do |link|
+            target = RailsAiContext::SafePath.linked_dir(link, bound)
+            next unless target && visited.add?(target)
+            next if [ real_root, real_search ].any? { |dir| RailsAiContext::SafePath.contained?(target, dir) || RailsAiContext::SafePath.contained?(dir, target) }
+
+            name = File.join(spelled, link.delete_prefix("#{real}/"))
+            found << [ name, target ]
+            pending << [ name, target ]
+          end
+        end
+        targets = found.map(&:last)
+        found.reject { |_, target| targets.any? { |other| other != target && RailsAiContext::SafePath.contained?(target, other) } }
+      rescue SystemCallError
+        []
+      end
+
+      # A file in a linked-in tree is asked by the name it has there too, as
+      # SafePath.locate asks it: a pack's config/master.key is not the app's
+      # name for it, but it is the key.
+      private_class_method def self.sensitive_in_tree?(relative, trees, root)
+        trees.any? do |spelled, _real, base|
+          prefix = spelled_relative(spelled, root)
+          next false unless relative == prefix || relative.start_with?("#{prefix}/")
+
+          name = [ base, relative.delete_prefix(prefix).delete_prefix("/") ].reject(&:empty?).join("/")
+          sensitive_file?(name)
+        end
+      end
+
+      # A path under the root as the app spells it, whatever links lead there.
+      private_class_method def self.spelled_relative(path, root)
+        RailsAiContext::SafePath.spelled_relative(path, root)
+      end
+
       # One file's rows, as ripgrep's -C and --max-count give them: at most
       # max_results matches, each with its context, overlapping context once.
       # A binary file (ripgrep's test, on the first block) gives none. True
@@ -443,7 +580,8 @@ module RailsAiContext
         return false if File.open(file, "rb") { |io| io.read(BINARY_PROBE_BYTES) }.to_s.include?("\0")
 
         lines = (RailsAiContext::SafeFile.read(file) || "").lines
-        hits = lines.each_index.select { |i| lines[i].delete_suffix("\n").match?(regex) }.first(max_results)
+        # A line without its terminator, LF or CRLF, as ripgrep --crlf reads it.
+        hits = lines.each_index.select { |i| lines[i].delete_suffix("\n").delete_suffix("\r").match?(regex) }.first(max_results)
         hit = hits.to_h { |i| [ i, true ] }
         shown = hits.flat_map { |i| ([ i - ctx_lines, 0 ].max..[ i + ctx_lines, lines.size - 1 ].min).to_a }.uniq.sort
         shown.each do |i|
@@ -456,15 +594,15 @@ module RailsAiContext
 
       # Rows are matches plus context lines; only the flagged ones are matches.
       # Rows are fetched one past the cap so a cut list is knowable.
-      private_class_method def self.cap_results(rows)
-        truncated = rows.size > max_results_cap
-        [ truncated ? rows.first(max_results_cap) : rows, truncated ]
+      private_class_method def self.cap_results(rows, cap = max_results_cap)
+        truncated = rows.size > cap
+        [ truncated ? rows.first(cap) : rows, truncated ]
       end
 
       # The cap is on emitted lines, so a cut list means the count beside it
       # covers only the lines the search got to read.
-      private_class_method def self.scanned_note(truncated)
-        truncated ? " - first #{count_phrase(max_results_cap, 'line')} scanned" : ""
+      private_class_method def self.scanned_note(truncated, cap = max_results_cap)
+        truncated ? " - first #{count_phrase(cap, 'line')} scanned" : ""
       end
 
       private_class_method def self.capped_match_phrase(total, truncated)
@@ -586,17 +724,19 @@ module RailsAiContext
       # ── Trace Mode ─────────────────────────────────────────────────
       # Shows definition + source + callers + internal calls in one response
 
-      private_class_method def self.trace_method(method_name, root, path, exclude_tests)
+      private_class_method def self.trace_method(method_name, root, search_path, exclude_tests)
         # 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
+        # 1. Find the definition: a `def`, else the `scope :name` that
+        # defines the class method a model's scope is.
         def_pattern = "#{DEF_HEAD}#{literal(cleaned)}#{RailsAiContext::MethodName.definition_end(cleaned)}"
         def_results, = quick_search(def_pattern, search_path, root, 10, exclude_tests)
+        scope = def_results.empty?
+        def_results, = quick_search(scope_pattern(cleaned), search_path, root, 10, exclude_tests) if scope
 
         if def_results.any?
           lines << "## Definition"
@@ -605,8 +745,12 @@ module RailsAiContext
             class_context = extract_class_context(File.join(root, r[:file]), r[:line_number])
             lines << "**#{r[:file]}:#{r[:line_number]}**#{class_context ? " in `#{class_context}`" : ""}"
 
-            # Full method body
-            body = extract_method_body(File.join(root, r[:file]), r[:line_number])
+            # Full method body, or the whole scope declaration
+            body = if scope
+              extract_scope_source(File.join(root, r[:file]), r[:line_number], cleaned)
+            else
+              extract_method_body(File.join(root, r[:file]), r[:line_number])
+            end
             if body
               lines << "```ruby"
               lines << RailsAiContext::Redaction.redact_source_lines(body.lines.map(&:chomp), path: r[:file]).join("\n")
@@ -621,6 +765,8 @@ module RailsAiContext
               internal_calls += Introspectors::SourceCalls.calls(def_source)
               internal_calls.uniq!
               internal_calls.reject! { |c| c == cleaned }
+              # The scope macro and the lambda holding its body are no calls the scope makes.
+              internal_calls -= SCOPE_WRAPPERS if scope
 
               if internal_calls.any?
                 lines << "" << "## Calls internally"
@@ -638,7 +784,7 @@ module RailsAiContext
             lines << ""
           end
         else
-          lines << "_No definition found for `def #{cleaned}`_"
+          lines << "_No definition found for `def #{cleaned}` or `scope :#{cleaned}`_"
           lines << ""
         end
 
@@ -720,6 +866,36 @@ module RailsAiContext
         text_response("Trace error: #{e.message}")
       end
 
+      SCOPE_WRAPPERS = %w[scope lambda proc].freeze
+
+      # `scope :published, -> { ... }` or `scope("published", ...)`: the
+      # line that defines a model's scope method of that name.
+      private_class_method def self.scope_pattern(name)
+        "^\\s*scope\\s*\\(?\\s*(?::#{literal(name)}\\b|[\"']#{literal(name)}[\"'])"
+      end
+
+      # The whole `scope` call that starts on the line, however many lines
+      # its lambda runs to; the line alone when it cannot be parsed.
+      private_class_method def self.extract_scope_source(file_path, line, name)
+        source = RailsAiContext::SafeFile.read(file_path) || ""
+        found = nil
+        visit = lambda do |node|
+          return if found || !node.is_a?(Prism::Node)
+
+          first = node.arguments&.arguments&.first if node.is_a?(Prism::CallNode)
+          if node.is_a?(Prism::CallNode) && node.name == :scope && node.location.start_line == line &&
+             (first.is_a?(Prism::SymbolNode) || first.is_a?(Prism::StringNode)) && first.unescaped == name
+            found = node.slice
+          else
+            node.compact_child_nodes.each(&visit)
+          end
+        end
+        visit.call(RailsAiContext::AstCache.parse_string(source).value)
+        found || source.lines[line - 1]&.rstrip
+      rescue => e
+        RailsAiContext.debug_fail(e, nil, label: "extract_scope_source")
+      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?

data/lib/rails_ai_context/tools/search_docs.rb

@@ -58,7 +58,7 @@ module RailsAiContext
         # Validate source
         source = source.to_s.downcase
         unless VALID_SOURCES.include?(source)
-          return text_response("Invalid source: '#{source}'. Valid values: #{VALID_SOURCES.join(', ')}")
+          return text_response("Invalid source: '#{echo_input(source)}'. Valid values: #{VALID_SOURCES.join(', ')}")
         end
 
         # Normalize limit
@@ -94,11 +94,11 @@ module RailsAiContext
           { topic: topic, score: score }
         end
 
-        scored.sort_by! { |s| -s[:score] }
+        scored = scored.sort_by.with_index { |s, i| [ -s[:score], i ] }
         results = scored.first(limit)
 
         if results.empty?
-          return text_response("No documentation found for '#{query}'. Try broader terms like 'active record', 'routing', or 'testing'.")
+          return text_response("No documentation found for '#{echo_input(query)}'. Try broader terms like 'active record', 'routing', or 'testing'.")
         end
 
         format_results(results, query, source, branch, fetch: fetch)
@@ -178,7 +178,7 @@ module RailsAiContext
 
         def format_results(results, query, source, branch, fetch: false)
           lines = []
-          lines << "# Rails Documentation Search: \"#{query}\"#{" (fetched)" if fetch}"
+          lines << "# Rails Documentation Search: \"#{echo_input(query)}\"#{" (fetched)" if fetch}"
           lines << "Found #{count_phrase(results.size, "result")} (#{source})"
           lines << ""