ace-search 0.24.0

data/handbook/workflow-instructions/search/run.wf.md

@@ -0,0 +1,289 @@
+---
+doc-type: workflow
+title: Search Workflow
+purpose: search workflow instruction
+ace-docs:
+  last-updated: 2026-03-06
+  last-checked: 2026-03-21
+---
+
+# Search Workflow
+
+## Purpose
+
+Intelligent code and file discovery using the **ace-search** gem - finding files by name, searching for code patterns, and exploring project structure.
+
+## Primary Tool: ace-search
+
+You use the **ace-search** command exclusively for all search operations. This unified tool combines file and content searching with intelligent DWIM (Do What I Mean) pattern analysis.
+
+## Search Modes
+
+### Auto Mode (Default - DWIM)
+Let ace-search intelligently detect search type:
+```bash
+# File glob patterns auto-detected
+ace-search "*.rb"
+ace-search "test_*.md"
+
+# Content searches auto-detected
+ace-search "class TaskManager"
+ace-search "def initialize"
+
+# Hybrid searches
+ace-search "bin/as-search"
+ace-search "TODO"
+```
+
+### Explicit Modes
+
+**File Search** - Find files by name/pattern:
+```bash
+ace-search "agent" --file
+ace-search "*.md" --file
+ace-search "*Manager*" --file
+```
+
+**Content Search** - Search within files:
+```bash
+ace-search "require 'ace/core'" --content
+ace-search "TODO|FIXME" --content
+ace-search "class.*Agent" --content
+```
+
+**Hybrid Mode** - Search both:
+```bash
+ace-search "TaskManager" --hybrid
+ace-search "config" --hybrid
+```
+
+## Scope Control
+
+### Search Scope
+Limit search to specific paths:
+```bash
+# Search specific directory (change directory first)
+cd lib/ && ace-search "pattern"
+cd ace-taskflow/ && ace-search "TODO"
+
+# Or use --include to filter paths
+ace-search "pattern" --include "lib/**/*"
+ace-search "TODO" --include "ace-taskflow/**/*"
+```
+
+### File Pattern Filtering (Glob)
+Filter by file patterns:
+```bash
+# Search only Ruby files
+ace-search "class" --content --glob "**/*.rb"
+
+# Search only markdown in specific paths
+ace-search "TODO" --content --glob "docs/**/*.md"
+
+# Multiple patterns
+ace-search "config" --glob "**/*.{yml,yaml,json}"
+```
+
+### Git Scope
+Limit to git-tracked files:
+```bash
+# Staged files only
+ace-search "console.log" --staged
+
+# Tracked files only
+ace-search "TODO" --tracked
+
+# Changed files only
+ace-search "FIXME" --changed
+```
+
+## Search Modifiers
+
+### Pattern Matching
+```bash
+# Case-insensitive
+ace-search "todo" --case-insensitive
+
+# Whole word matching
+ace-search "test" --whole-word
+
+# Multiline patterns
+ace-search "class.*end" --multiline
+```
+
+### Context Display
+Show surrounding lines:
+```bash
+# 3 lines before and after
+ace-search "error" --context 3
+
+# 2 lines after
+ace-search "warning" --after-context 2
+
+# 2 lines before
+ace-search "exception" --before-context 2
+```
+
+### Output Control
+```bash
+# Limit results
+ace-search "TODO" --max-results 20
+
+# Show only filenames
+ace-search "deprecated" --files-with-matches
+
+# Output formats
+ace-search "class" --format json
+ace-search "def" --format yaml
+```
+
+## Preset Support
+
+Use predefined search configurations:
+```bash
+# Use preset from .ace/search/presets/
+ace-search --preset ruby-classes
+
+# List available presets
+ace-search --list-presets
+```
+
+## Common Workflows
+
+### Finding Implementation
+```bash
+# 1. Broad discovery
+ace-search "TaskManager"
+
+# 2. Narrow by file type
+ace-search "TaskManager" --glob "**/*.rb"
+
+# 3. Find class definition
+ace-search "class TaskManager" --content --glob "**/*.rb"
+
+# 4. Find usage
+ace-search "TaskManager.new" --content
+```
+
+### Searching Configuration
+```bash
+# Find YAML config files
+ace-search "*.yml" --file --search-root .ace
+
+# Search within config
+ace-search "model: opus" --content --glob "**/*.yml"
+
+# Find environment variables
+ace-search "API_KEY" --content
+```
+
+### Exploring Code Structure
+```bash
+# Find all requires
+ace-search "require 'ace" --content --glob "**/*.rb"
+
+# Find class definitions
+ace-search "class.*< " --content --glob "**/*.rb"
+
+# Find method definitions (in lib/ directory)
+cd lib/ && ace-search "def " --content
+```
+
+### Debugging and Maintenance
+```bash
+# Find TODOs and FIXMEs
+ace-search "TODO|FIXME" --content
+
+# Find deprecated code
+ace-search "deprecated" --case-insensitive --content
+
+# Find error handling
+ace-search "rescue|raise" --content --glob "**/*.rb"
+```
+
+## Search Strategy
+
+### Progressive Refinement
+1. **Start broad**: Use auto mode to understand scope
+   ```bash
+   ace-search "notification"
+   ```
+
+2. **Identify patterns**: Look at results to understand structure
+   ```bash
+   ace-search "notification" --files-with-matches
+   ```
+
+3. **Narrow focus**: Add filters based on findings
+   ```bash
+   ace-search "class.*Notification" --content --glob "**/*.rb" --include "lib/**/*"
+   ```
+
+4. **Verify relevance**: Check sample results
+   ```bash
+   ace-search "Notification.new" --content --max-results 5
+   ```
+
+### Efficiency Tips
+- Use `--file` for filename-only searches (faster)
+- Change directories or use `--include` to limit scope
+- Use `--glob` to filter file types
+- Apply `--max-results` for initial exploration
+- Leverage auto mode for intelligent detection
+
+## Response Format
+
+### Success Response
+```markdown
+## Search Summary
+Found [N] matches for "[pattern]" across [M] files.
+
+## Key Results
+- path/to/file.rb:42: [relevant match with context]
+- another/file.md:15: [relevant match with context]
+
+## Patterns Observed
+- [Common themes or structures]
+- [Notable file/directory concentrations]
+
+## Suggestions
+- Refine with: ace-search "[pattern]" --glob "**/*.ext" --include "path/**/*"
+- Explore: [specific files or directories of interest]
+```
+
+### No Results Response
+```markdown
+## Search Summary
+No matches found for "[pattern]".
+
+## Suggestions
+- Try alternative terms or patterns
+- Broaden scope: --search-root .
+- Use case-insensitive: --case-insensitive
+- Check different file types: --glob "**/*.ext"
+```
+
+### Large Result Set Response
+```markdown
+## Search Summary
+Found [N] matches (showing first [M] due to limit).
+
+## Top Results
+[Most relevant matches]
+
+## Refinement Suggestions
+To narrow results, try:
+- ace-search "[pattern]" --glob "**/*.rb"
+- cd specific/path/ && ace-search "[pattern]"
+- ace-search "[pattern]" --whole-word
+- ace-search "[pattern]" --include "specific/path/**/*"
+```
+
+## Important Notes
+
+- **Discovery Only**: This workflow searches but does not modify files
+- **DWIM Mode**: Auto mode intelligently detects file vs content searches
+- **Git Integration**: Supports scoping to staged/tracked/changed files
+- **Preset Support**: Can use predefined search configurations
+- **Performance**: Use specific modes and filters for faster searches
+- **Results Limit**: Default max-results prevents overwhelming output

data/lib/ace/search/atoms/debug_logger.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Ace
+  module Search
+    module Atoms
+      # Centralized debug logging for ace-search
+      #
+      # NOTE: This logger caches the ENV["DEBUG"] state on first use for performance
+      # and is intended for single-threaded, short-lived CLI processes.
+      #
+      # Usage:
+      #   DebugLogger.log("message")
+      #   DebugLogger.section("Title") do
+      #     DebugLogger.log("detail 1")
+      #     DebugLogger.log("detail 2")
+      #   end
+      module DebugLogger
+        # Check if debug logging is enabled via DEBUG environment variable
+        #
+        # @return [Boolean] true if DEBUG is set to "1" or "true"
+        def self.enabled?
+          @enabled ||= begin
+            debug_value = ENV["DEBUG"]
+            debug_value == "1" || debug_value == "true"
+          end
+        end
+
+        # Log a debug message to stderr if debugging is enabled
+        #
+        # @param message [String] Message to log
+        # @param prefix [String] Prefix for the message (default: "DEBUG")
+        # @return [void]
+        def self.log(message, prefix: "DEBUG")
+          return unless enabled?
+          warn "#{prefix}: #{message}"
+        end
+
+        # Log a section with title and optional block for grouped output
+        #
+        # @param title [String] Section title
+        # @yield Optional block to execute within the section
+        # @return [void]
+        def self.section(title)
+          return unless enabled?
+
+          warn "=" * 60
+          warn "DEBUG: #{title}"
+          yield if block_given?
+          warn "=" * 60
+        end
+
+        # Reset the enabled cache (useful for testing)
+        #
+        # @return [void]
+        def self.reset!
+          @enabled = nil
+        end
+      end
+    end
+  end
+end

data/lib/ace/search/atoms/fd_executor.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+require "timeout"
+require_relative "debug_logger"
+
+module Ace
+  module Search
+    module Atoms
+      # FdExecutor provides a safe wrapper around fd command
+      # This is an atom - pure function for executing fd commands
+      module FdExecutor
+        module_function
+
+        # Execute fd with given pattern and options
+        # @param pattern [String] Search pattern (can be glob or regex)
+        # @param options [Hash] Search options
+        # @return [Hash] Command result with success status and output
+        def execute(pattern = nil, options = {})
+          command = build_command(pattern, options)
+          # Read timeout from options (runtime override), then config, then fallback to 120 seconds
+          default_timeout = Ace::Search.config["timeout"] || 120
+          timeout_seconds = options.fetch(:timeout, default_timeout)
+
+          # Debug output
+          DebugLogger.section("FdExecutor") do
+            DebugLogger.log("Command: #{command}")
+            DebugLogger.log("Will chdir to: #{options[:search_path] || "(current directory)"}")
+          end
+
+          begin
+            # Change to search directory if specified, otherwise use current dir
+            # This ensures .gitignore, excludes, and includes are processed correctly
+            search_dir = options[:search_path] || "."
+
+            stdout, stderr, status = Timeout.timeout(timeout_seconds) do
+              Open3.capture3(command, chdir: search_dir)
+            end
+
+            {
+              success: status.success?,
+              stdout: stdout,
+              stderr: stderr,
+              exit_code: status.exitstatus,
+              command: command
+            }
+          rescue Timeout::Error
+            {
+              success: false,
+              error: "Command timed out after #{timeout_seconds} seconds",
+              exit_code: -1
+            }
+          rescue => e
+            {
+              success: false,
+              error: e.message,
+              exit_code: -1
+            }
+          end
+        end
+
+        # Check if fd is available
+        # @return [Boolean] True if fd is installed
+        def available?
+          stdout, _stderr, status = Open3.capture3("which fd")
+          status.success? && !stdout.strip.empty?
+        rescue
+          false
+        end
+
+        # Build fd command with proper escaping
+        # @param pattern [String, nil] Search pattern (nil for all files)
+        # @param options [Hash] Search options
+        # @return [String] Complete fd command
+        def build_command(pattern = nil, options = {})
+          args = ["fd"]
+
+          # Basic options
+          args << "--color=never" unless options[:color]
+          args << "--absolute-path" if options[:absolute_path]
+          args << "--follow" if options[:follow_symlinks]
+          args << "--hidden" if options[:include_hidden] || options[:hidden]
+          args << "--no-ignore" if options[:no_ignore]
+          args << "--no-ignore-vcs" if options[:no_ignore_vcs]
+
+          # Type filtering
+          case options[:fd_type]
+          when "f", "file"
+            args << "--type=file"
+          when "d", "directory"
+            args << "--type=directory"
+          when "l", "symlink"
+            args << "--type=symlink"
+          when "s", "socket"
+            args << "--type=socket"
+          when "p", "pipe"
+            args << "--type=pipe"
+          end
+
+          # Extension filtering
+          if options[:extension]
+            Array(options[:extension]).each { |ext| args << "--extension=#{ext}" }
+          end
+
+          # Size filtering
+          args << "--size=#{options[:size]}" if options[:size]
+
+          # Depth limiting
+          args << "--max-depth=#{options[:max_depth]}" if options[:max_depth]
+          args << "--min-depth=#{options[:min_depth]}" if options[:min_depth]
+
+          # Case sensitivity
+          args << "--ignore-case" if options[:ignore_case]
+          args << "--case-sensitive" if options[:case_sensitive]
+
+          # Max results
+          args << "--max-results=#{options[:max_results]}" if options[:max_results]
+
+          # Exclude patterns
+          if options[:exclude]
+            Array(options[:exclude]).each { |pattern| args << "--exclude=#{pattern}" }
+          end
+
+          # Search paths
+          # When search_path is set, we use chdir in execute(), so search current dir
+          paths = if options[:search_path]
+            ["."]  # Will chdir to search_path, then search current dir
+          elsif options[:paths]
+            options[:paths]
+          else
+            ["."]
+          end
+
+          # Build the complete command
+          command_parts = args
+
+          # Add pattern with appropriate flag
+          if pattern
+            # Check if pattern looks like a glob
+            if pattern.include?("*") || pattern.include?("?") || pattern.include?("[")
+              command_parts << "--glob"
+            end
+            command_parts << Shellwords.escape(pattern)
+          end
+
+          command_parts.concat(paths.map { |p| Shellwords.escape(p) })
+
+          command_parts.join(" ")
+        end
+
+        # Get fd version
+        # @return [String, nil] Version string or nil if not available
+        def version
+          return nil unless available?
+
+          stdout, _stderr, status = Open3.capture3("fd --version")
+          if status.success?
+            version_match = stdout.match(/fd ([\d.]+)/)
+            version_match ? version_match[1] : nil
+          end
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ace/search/atoms/pattern_analyzer.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Ace
+  module Search
+    module Atoms
+      # PatternAnalyzer provides intelligent analysis of search patterns for DWIM mode selection
+      # This is an atom - pure function for pattern analysis
+      module PatternAnalyzer
+        # File glob indicators
+        FILE_GLOB_PATTERNS = [
+          /^\*+\./,                    # *.extension
+          /\*\*\/\*/,                  # **/* recursive patterns
+          /^\w+\/\*+/,                 # dir/* patterns
+          /\.\w+$/,                    # .extension endings
+          /\/\*+$/,                    # ending with /*
+          /^\w+\*+\w*$/                # word* or *word patterns for filenames
+        ].freeze
+
+        # Content regex indicators
+        CONTENT_REGEX_PATTERNS = [
+          /[|+?{}()\[\]\\]/,           # Regex metacharacters (removed * from here)
+          /def\s+\w+/,                 # Method definitions
+          /class\s+\w+/,               # Class definitions
+          /function\s+\w+/,            # Function definitions
+          /import\s+/,                 # Import statements
+          /require\s+/,                # Require statements
+          /\b(TODO|FIXME|BUG|HACK)\b/, # Code annotations
+          /^\^/,                       # Line start anchor
+          /\$$/,                       # Line end anchor
+          /\\[bBdDsSwW]/               # Character class escapes
+        ].freeze
+
+        # Literal text indicators
+        LITERAL_INDICATORS = [
+          /^\w+$/,                     # Single word
+          /^[\w\s]+$/,                 # Words with spaces
+          /^"[^"]*"$/,                 # Quoted strings
+          /^'[^']*'$/                  # Single quoted strings
+        ].freeze
+
+        module_function
+
+        # Analyze a pattern and determine its most likely type
+        # @param pattern [String] Pattern to analyze
+        # @return [Hash] Analysis result with type and confidence
+        def analyze_pattern(pattern)
+          return {type: :invalid, confidence: 0.0, reason: "Pattern is nil"} if pattern.nil?
+          return {type: :invalid, confidence: 0.0, reason: "Pattern is empty"} if pattern.empty?
+
+          clean_pattern = pattern.strip
+
+          # Check for file glob patterns
+          if file_glob_pattern?(clean_pattern)
+            return {
+              type: :file_glob,
+              confidence: calculate_file_glob_confidence(clean_pattern),
+              reason: "Contains file glob patterns",
+              suggested_tool: "fd"
+            }
+          end
+
+          # Check for content regex patterns
+          if content_regex_pattern?(clean_pattern)
+            return {
+              type: :content_regex,
+              confidence: calculate_content_regex_confidence(clean_pattern),
+              reason: "Contains regex metacharacters or code patterns",
+              suggested_tool: "rg"
+            }
+          end
+
+          # Check for literal patterns
+          if literal_pattern?(clean_pattern)
+            return {
+              type: :literal,
+              confidence: calculate_literal_confidence(clean_pattern),
+              reason: "Simple literal text pattern",
+              suggested_tool: "rg"
+            }
+          end
+
+          # Default to hybrid if unclear
+          {
+            type: :hybrid,
+            confidence: 0.5,
+            reason: "Pattern could match files or content",
+            suggested_tool: "both"
+          }
+        end
+
+        # Check if pattern looks like a file glob
+        def file_glob_pattern?(pattern)
+          FILE_GLOB_PATTERNS.any? { |regex| pattern.match?(regex) }
+        end
+
+        # Check if pattern looks like content regex
+        def content_regex_pattern?(pattern)
+          CONTENT_REGEX_PATTERNS.any? { |regex| pattern.match?(regex) }
+        end
+
+        # Check if pattern looks like literal text
+        def literal_pattern?(pattern)
+          LITERAL_INDICATORS.any? { |regex| pattern.match?(regex) }
+        end
+
+        # Suggest search mode based on pattern analysis
+        def suggest_search_mode(pattern, flags = {})
+          return :files if flags[:files_only] || flags[:name_only]
+          return :content if flags[:content_only]
+
+          analysis = analyze_pattern(pattern)
+
+          case analysis[:type]
+          when :file_glob
+            :files
+          when :content_regex, :literal
+            :content
+          when :hybrid
+            :both
+          else
+            :content
+          end
+        end
+
+        # Extract file extensions from a pattern if present
+        def extract_extensions(pattern)
+          extensions = []
+
+          # Match patterns like *.rb, **/*.js, etc.
+          extension_matches = pattern.scan(/\*+\.(\w+)/)
+          extensions.concat(extension_matches.flatten)
+
+          # Match explicit .ext at the end
+          if pattern.match?(/\.(\w+)$/)
+            extension_match = pattern.match(/\.(\w+)$/)
+            extensions << extension_match[1]
+          end
+
+          extensions.uniq
+        end
+
+        def calculate_file_glob_confidence(pattern)
+          confidence = 0.5
+
+          confidence += 0.3 if pattern.include?("*")
+          confidence += 0.2 if pattern.match?(/\.\w+$/)
+          confidence += 0.1 if pattern.include?("/")
+
+          [confidence, 1.0].min
+        end
+
+        def calculate_content_regex_confidence(pattern)
+          confidence = 0.5
+
+          metachar_count = pattern.scan(/[|+?{}()\[\]\\]/).length
+          confidence += metachar_count * 0.1
+
+          confidence += 0.2 if pattern.match?(/\b(def|class|function|import|require)\s+/)
+          confidence += 0.1 if pattern.match?(/^\^|\$$/)
+
+          [confidence, 1.0].min
+        end
+
+        def calculate_literal_confidence(pattern)
+          confidence = 0.6
+
+          confidence += 0.2 if pattern.match?(/^\w+$/)
+          confidence += 0.1 if pattern.length < 20
+          confidence += 0.3 if pattern.match?(/^["'][^"']*["']$/)
+
+          [confidence, 1.0].min
+        end
+      end
+    end
+  end
+end