zen_apropos 0.2.0

data/lib/zen_apropos/engine.rb

@@ -0,0 +1,156 @@
+# Search engine that ties together parsing, indexing, searching, grouping, and formatting
+#
+# Usage:
+#   ZenApropos::Engine.new.search("employee")
+#   ZenApropos::Engine.new.search("team:finance safety:destructive")
+module ZenApropos
+  class Engine
+    attr_reader :index, :plain, :last_results
+
+    def initialize(root_path: Dir.pwd, plain: false, glob_patterns: nil)
+      source = Sources::RakeSource.new(
+        root_path: root_path,
+        glob_patterns: glob_patterns || Sources::RakeSource::DEFAULT_PATHS
+      )
+      @index = Index.new(source: source)
+      @plain = plain
+    end
+
+    def help
+      <<~HELP
+
+        🔍 ZenApropos - Rake Task Search
+
+        Usage:
+          CLI:     zen_apropos <query> [--plain]
+          Console: apropos "query"
+
+        Query Syntax:
+          Free text      Search task names, descriptions, annotations, and source
+          team:<name>    Filter by team annotation
+          safety:<level> Filter by safety level (safe, caution, destructive)
+          namespace:<ns> Filter by rake namespace
+          keyword:<word> Filter by declared keyword
+
+        Examples:
+          apropos "employee"
+          apropos "reindex"
+          apropos "namespace:indexer"
+          apropos "team:finance safety:destructive"
+          apropos "Employee.find_each"
+          apropos "reindex", plain: true
+
+      HELP
+    end
+
+    def search(raw_query)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      parsed  = QueryParser.parse(raw_query)
+      results = find_entries(parsed)
+      matches = build_match_context(results, parsed[:text])
+
+      grouper         = ResultGrouper.new(results, active_filters: parsed[:filters])
+      grouped         = grouper.group
+      group_dimension = results.length >= 5 ? grouper.best_dimension : nil
+
+      # Store results in display order so interactive viewer matches the numbered output
+      @last_results = grouped.values.flatten
+
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+      formatter = ResultFormatter.new(
+        results:         results,
+        grouped_results: grouped,
+        query:           raw_query,
+        group_dimension: group_dimension,
+        matches:         matches,
+        elapsed:         elapsed
+      )
+
+      plain ? formatter.format_plain : formatter.format_rich
+    end
+
+    # Returns raw filtered results (for interactive mode)
+    def search_entries(raw_query)
+      find_entries(QueryParser.parse(raw_query))
+    end
+
+    private
+
+    def find_entries(parsed)
+      results = filter(index.entries, parsed)
+      text_search(results, parsed[:text])
+    end
+
+    def filter(entries, parsed)
+      filters = parsed[:filters]
+      return entries if filters.empty?
+
+      entries.select do |entry|
+        filters.all? do |key, value|
+          case key
+          when :team      then entry.team&.downcase == value.downcase
+          when :safety    then entry.safety&.downcase == value.downcase
+          when :namespace then entry.namespace&.downcase == value.downcase
+          when :keyword   then entry.keywords.any? { |k| k.downcase == value.downcase }
+          else true
+          end
+        end
+      end
+    end
+
+    def text_search(entries, text)
+      return entries if text.nil? || text.empty?
+
+      query_lower = text.downcase
+
+      entries.select do |entry|
+        entry.name.downcase.include?(query_lower)        ||
+          entry.description.downcase.include?(query_lower) ||
+          entry.keywords.any? { |k| k.downcase.include?(query_lower) } ||
+          entry.source.downcase.include?(query_lower)
+      end
+    end
+
+    # Builds 3-line source context for entries that matched on source code
+    def build_match_context(entries, text)
+      return {} if text.nil? || text.empty?
+
+      context     = {}
+      query_lower = text.downcase
+
+      entries.each do |entry|
+        # Only show source context if the match was in source (not name/desc)
+        next if entry.name.downcase.include?(query_lower)
+        next if entry.description.downcase.include?(query_lower)
+
+        next unless entry.source.downcase.include?(query_lower)
+
+        source_lines = entry.source.lines
+        source_lines.each_with_index do |line, i|
+          next unless line.downcase.include?(query_lower)
+
+          actual_line = entry.line_number + i
+          context_lines = {}
+
+          # 1 line before
+          if i > 0
+            context_lines[actual_line - 1] = source_lines[i - 1]
+          end
+          # matched line
+          context_lines[actual_line] = line
+          # 1 line after
+          if i < source_lines.length - 1
+            context_lines[actual_line + 1] = source_lines[i + 1]
+          end
+
+          context[entry.name] = { source_lines: context_lines, matched_line: actual_line }
+          break # only show first match
+        end
+      end
+
+      context
+    end
+  end
+end

data/lib/zen_apropos/entry.rb

@@ -0,0 +1,38 @@
+# Represents a single searchable rake task entry
+module ZenApropos
+  Entry = Struct.new(
+    :name,        # full task name e.g. "indexer:employees"
+    :namespace,   # namespace portion e.g. "indexer"
+    :description, # the desc string
+    :file_path,   # absolute path to .rake file
+    :line_number, # line where task is defined
+    :source,      # full source of the task block
+    :annotations, # hash of @zen_desc metadata { team:, safety:, keywords: }
+    :args,        # array of argument names e.g. ["days_ago"]
+    keyword_init: true
+  ) do
+    def team
+      annotations[:team]
+    end
+
+    def safety
+      annotations[:safety]
+    end
+
+    def keywords
+      annotations[:keywords] || []
+    end
+
+    def relative_path
+      file_path.sub("#{Dir.pwd}/", '')
+    end
+
+    def usage
+      if args&.any?
+        "bundle exec rake #{name}[#{args.join(',')}]"
+      else
+        "bundle exec rake #{name}"
+      end
+    end
+  end
+end

data/lib/zen_apropos/index.rb

@@ -0,0 +1,56 @@
+require 'fileutils'
+
+# Builds and caches the search index with mtime-based invalidation
+#
+# Cache is stored in tmp/zen_apropos_index.cache
+# Rebuilds automatically when any .rake file is newer than the cache
+module ZenApropos
+  class Index
+    CACHE_PATH = 'tmp/zen_apropos_index.cache'.freeze
+
+    attr_reader :source
+
+    def initialize(source:)
+      @source = source
+    end
+
+    def entries
+      return @cached_entries if cache_fresh?
+
+      build_and_cache
+    end
+
+    private
+
+    def cache_fresh?
+      return false unless File.exist?(cache_path)
+
+      cached = Marshal.load(File.binread(cache_path))
+      return false unless cached.is_a?(Hash) && cached[:glob_patterns] == source.glob_patterns
+
+      cache_mtime     = File.mtime(cache_path)
+      fresh           = source.scan.none? { |file| File.mtime(file) > cache_mtime }
+      @cached_entries = cached[:entries] if fresh
+      fresh
+    rescue StandardError
+      false
+    end
+
+    def build_and_cache
+      all_entries = source.entries
+
+      begin
+        FileUtils.mkdir_p(File.dirname(cache_path))
+        File.binwrite(cache_path, Marshal.dump({ entries: all_entries, glob_patterns: source.glob_patterns }))
+      rescue SystemCallError
+        # Permission error or read-only filesystem — skip caching, return entries
+      end
+
+      all_entries
+    end
+
+    def cache_path
+      File.join(source.root_path, CACHE_PATH)
+    end
+  end
+end

data/lib/zen_apropos/linter.rb

@@ -0,0 +1,84 @@
+# Checks rake tasks for missing annotations
+#
+# Usage:
+#   ZenApropos::Linter.new.run                    # Check all rake files
+#   ZenApropos::Linter.new(changed_only: true).run # Check only changed files
+module ZenApropos
+  class Linter
+    attr_reader :warnings
+
+    def initialize(changed_only: false)
+      @changed_only = changed_only
+      @warnings     = []
+    end
+
+    def run
+      files = rake_files
+      files.each { |file| check_file(file) }
+      print_results
+      warnings.any? ? 1 : 0
+    end
+
+    private
+
+    def tag
+      ZenApropos.configuration.tag
+    end
+
+    def rake_files
+      if @changed_only
+        changed = `git diff --name-only --diff-filter=ACMR HEAD~1 2>/dev/null`.strip.split("\n")
+        changed.select { |f| f.end_with?('.rake') && File.exist?(f) }
+      else
+        patterns = ZenApropos.configuration.glob_patterns || Sources::RakeSource::DEFAULT_PATHS
+        patterns.flat_map { |p| Dir[p] }.sort
+      end
+    end
+
+    def check_file(file_path)
+      lines = File.readlines(file_path)
+
+      lines.each_with_index do |line, index|
+        next unless line =~ /^\s*desc\s+['"]/
+        next if preceding_has_tags?(lines, index)
+
+        task_name = extract_next_task_name(lines, index)
+        next unless task_name
+
+        warnings << { file: file_path, line: index + 1, task_name: task_name }
+      end
+    end
+
+    def preceding_has_tags?(lines, desc_index)
+      i = desc_index - 1
+      while i >= 0
+        line = lines[i]
+        return true if ZenApropos.configuration.tag_pattern.match?(line)
+        return true if line =~ /^\s*zen_desc\s+/
+        break unless line =~ /^\s*(#|$)/
+        i -= 1
+      end
+      false
+    end
+
+    def extract_next_task_name(lines, desc_index)
+      lines[desc_index + 1..desc_index + 3]&.each do |line|
+        return Regexp.last_match(1) if line =~ /^\s*task\s+[:'"]?(\w+)/
+      end
+      nil
+    end
+
+    def print_results
+      if warnings.empty?
+        puts "\n✅ All rake tasks have @#{tag} annotations.\n"
+        return
+      end
+
+      puts ''
+      warnings.each do |w|
+        puts "⚠ #{w[:file]}:#{w[:line]} — task \"#{w[:task_name]}\" has no @#{tag} annotations"
+      end
+      puts "\n#{warnings.length} task(s) missing annotations. Consider adding @#{tag} tags or using zen_desc.\n"
+    end
+  end
+end

data/lib/zen_apropos/query_parser.rb

@@ -0,0 +1,38 @@
+# Parses a search query into structured filters and free-text terms
+#
+# Examples:
+#   "employee"                        => { text: "employee", filters: {} }
+#   "team:finance safety:destructive" => { text: "", filters: { team: "finance", safety: "destructive" } }
+#   "employee team:search"            => { text: "employee", filters: { team: "search" } }
+module ZenApropos
+  class QueryParser
+    FILTER_KEYS = %w[team safety namespace keyword].freeze
+
+    def initialize(raw_query)
+      @raw_query = raw_query.to_s.strip
+    end
+
+    def parse
+      filters = {}
+      text_parts = []
+
+      @raw_query.split(/\s+/).each do |token|
+        key, value = token.split(':', 2)
+
+        if FILTER_KEYS.include?(key) && value && !value.empty?
+          filters[key.to_sym] = value
+        else
+          text_parts << token
+        end
+      end
+
+      { text: text_parts.join(' '), filters: filters }
+    end
+
+    class << self
+      def parse(raw_query)
+        new(raw_query).parse
+      end
+    end
+  end
+end

data/lib/zen_apropos/result_formatter.rb

@@ -0,0 +1,122 @@
+# Formats search results for terminal output
+#
+# Two modes:
+#   - Rich (default): colored boxes grouped by dimension
+#   - Plain (--plain): pipeable tab-separated output
+module ZenApropos
+  class ResultFormatter
+    SAFETY_BADGES = {
+      'safe'        => "\e[32m⚡ safe\e[0m",
+      'caution'     => "\e[33m⚠️  caution\e[0m",
+      'destructive' => "\e[31m🔴 destructive\e[0m"
+    }.freeze
+
+    RESET  = "\e[0m".freeze
+    CYAN   = "\e[36m".freeze
+    BOLD   = "\e[1m".freeze
+    DIM    = "\e[2m".freeze
+    YELLOW = "\e[33m".freeze
+
+    attr_reader :results, :grouped_results, :query, :group_dimension, :matches, :elapsed
+
+    def initialize(results:, grouped_results:, query:, group_dimension:, matches: {}, elapsed: 0)
+      @results         = results
+      @grouped_results = grouped_results
+      @query           = query
+      @group_dimension = group_dimension
+      @matches         = matches
+      @elapsed         = elapsed
+    end
+
+    def format_rich
+      output = []
+      output << header_box
+      output << ''
+
+      global_index = 0
+      grouped_results.each do |group_name, entries|
+        output << format_group(group_name, entries, start_index: global_index)
+        output << ''
+        global_index += entries.length
+      end
+
+      output << summary_line
+      output.join("\n")
+    end
+
+    def format_plain
+      results.map do |entry|
+        safety = entry.safety || '-'
+        team   = entry.team || '-'
+        [
+          entry.name.ljust(40),
+          (entry.description || '').ljust(50),
+          safety.ljust(12),
+          team
+        ].join(' | ')
+      end.join("\n")
+    end
+
+    private
+
+    def header_box
+      title = "ZenApropos — #{results.length} results for \"#{query}\""
+      group_label = group_dimension ? "Grouped by: #{group_dimension}" : nil
+
+      width = 60
+      lines = []
+      lines << "#{CYAN}╭#{'─' * width}╮#{RESET}"
+      lines << "#{CYAN}│#{RESET}  #{BOLD}#{title}#{RESET}#{' ' * [0, width - title.length - 2].max}#{CYAN}│#{RESET}"
+      if group_label
+        lines << "#{CYAN}│#{RESET}  #{DIM}#{group_label}#{RESET}#{' ' * [0, width - group_label.length - 2].max}#{CYAN}│#{RESET}"
+      end
+      lines << "#{CYAN}╰#{'─' * width}╯#{RESET}"
+      lines.join("\n")
+    end
+
+    def format_group(group_name, entries, start_index: 0)
+      lines = []
+      lines << "#{CYAN}┌ #{BOLD}#{group_name}#{RESET} #{'─' * [0, 55 - group_name.to_s.length].max}"
+
+      entries.each_with_index do |entry, i|
+        number = start_index + i + 1
+        lines << "#{CYAN}│#{RESET} #{DIM}[#{number}]#{RESET} #{BOLD}rake #{entry.name}#{RESET}"
+        lines << "#{CYAN}│#{RESET}   #{entry.description}" unless entry.description.empty?
+        lines << "#{CYAN}│#{RESET}   #{DIM}$ #{entry.usage}#{RESET}"
+        lines << "#{CYAN}│#{RESET}   #{format_badges(entry)}" if entry.safety || entry.team
+        lines << format_match_context(entry) if matches[entry.name]
+        lines << "#{CYAN}│#{RESET}" if i < entries.length - 1
+      end
+
+      lines << "#{CYAN}└#{'─' * 58}#{RESET}"
+      lines.join("\n")
+    end
+
+    def format_badges(entry)
+      parts = []
+      parts << SAFETY_BADGES[entry.safety] if entry.safety
+      parts << "#{DIM}team: #{entry.team}#{RESET}" if entry.team
+      parts.join("  ·  ")
+    end
+
+    def format_match_context(entry)
+      match_info = matches[entry.name]
+      return '' unless match_info && match_info[:source_lines]
+
+      lines = []
+      match_info[:source_lines].each do |line_num, content|
+        prefix = match_info[:matched_line] == line_num ? "#{YELLOW}>" : " "
+        lines << "#{CYAN}│#{RESET}   #{DIM}#{prefix} #{line_num}:#{RESET} #{content.rstrip}"
+      end
+      lines.join("\n")
+    end
+
+    def summary_line
+      group_count = grouped_results.keys.length
+      group_word  = group_dimension || 'groups'
+      elapsed_str = format('%.2fs', elapsed)
+
+      "#{results.length} results across #{group_count} #{group_word}#{group_count > 1 ? 's' : ''} (#{elapsed_str})"
+    end
+  end
+end

data/lib/zen_apropos/result_grouper.rb

@@ -0,0 +1,58 @@
+# Auto-groups search results by the most useful dimension
+#
+# Logic:
+#   - Skip any dimension used as a filter (it's constant across results)
+#   - Pick the dimension with the best cluster distribution
+#   - Fall back to namespace if all else is equal
+#   - No grouping for < 5 results
+module ZenApropos
+  class ResultGrouper
+    DIMENSIONS = %i[namespace team safety].freeze
+
+    attr_reader :entries, :active_filters
+
+    def initialize(entries, active_filters: {})
+      @entries        = entries
+      @active_filters = active_filters
+    end
+
+    def group
+      return { nil => entries } if entries.length < 5
+
+      dimension = best_dimension
+      grouped   = entries.group_by { |e| dimension_value(e, dimension) || '(none)' }
+
+      # Sort groups by size descending
+      grouped.sort_by { |_key, items| -items.length }.to_h
+    end
+
+    def best_dimension
+      candidates = DIMENSIONS.reject { |d| active_filters.key?(d) }
+      return :namespace if candidates.empty?
+
+      # Pick the dimension that creates the most balanced groups
+      # (not 1 giant group, not all singletons)
+      candidates.max_by { |d| grouping_score(d) } || :namespace
+    end
+
+    private
+
+    def grouping_score(dimension)
+      groups = entries.group_by { |e| dimension_value(e, dimension) }
+
+      return 0 if groups.length <= 1        # everything in one group = useless
+      return 0 if groups.length == entries.length # all singletons = useless
+
+      # Prefer more groups with reasonable sizes
+      groups.length.to_f / entries.length
+    end
+
+    def dimension_value(entry, dimension)
+      case dimension
+      when :namespace then entry.namespace.to_s.empty? ? nil : entry.namespace
+      when :team      then entry.team
+      when :safety    then entry.safety
+      end
+    end
+  end
+end

data/lib/zen_apropos/source.rb

@@ -0,0 +1,21 @@
+# Base class for source adapters
+#
+# Subclasses must implement:
+#   #entries  - returns Array of Entry objects
+#   #scan     - returns Array of file paths to process
+#   #parse    - returns Array of Entry objects for a single file
+module ZenApropos
+  class Source
+    def entries
+      raise NotImplementedError
+    end
+
+    def scan
+      raise NotImplementedError
+    end
+
+    def parse(_file_path)
+      raise NotImplementedError
+    end
+  end
+end