woods 1.0.0

data/lib/tasks/woods_evaluation.rake

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# lib/tasks/woods_evaluation.rake
+#
+# Rake tasks for evaluating retrieval quality.
+#
+# Usage:
+#   bundle exec rake woods:evaluate                          # Run evaluation
+#   bundle exec rake woods:evaluate:baseline[grep]           # Run baseline comparison
+
+namespace :woods do
+  desc 'Run evaluation queries against the retrieval pipeline'
+  task evaluate: :environment do
+    require 'woods/retriever'
+    require 'woods/evaluation/query_set'
+    require 'woods/evaluation/evaluator'
+    require 'woods/evaluation/report_generator'
+
+    run_evaluation
+  end
+
+  namespace :evaluate do
+    desc 'Run baseline comparison'
+    task :baseline, [:strategy] => :environment do |_t, args|
+      require 'woods/evaluation/query_set'
+      require 'woods/evaluation/baseline_runner'
+      require 'woods/evaluation/metrics'
+
+      run_baseline(args)
+    end
+  end
+end
+
+def run_evaluation
+  query_set_path = ENV.fetch('EVAL_QUERY_SET', 'config/eval_queries.json')
+  output_path = ENV.fetch('EVAL_OUTPUT', 'tmp/eval_report.json')
+  budget = ENV.fetch('EVAL_BUDGET', '8000').to_i
+
+  puts "Loading query set from: #{query_set_path}"
+  query_set = Woods::Evaluation::QuerySet.load(query_set_path)
+  puts "Loaded #{query_set.size} queries — building retriever..."
+
+  evaluator = Woods::Evaluation::Evaluator.new(
+    retriever: build_eval_retriever, query_set: query_set, budget: budget
+  )
+  report = evaluator.evaluate
+
+  Woods::Evaluation::ReportGenerator.new
+                                    .save(report, output_path, metadata: { 'query_set' => query_set_path })
+
+  print_eval_report(report, output_path)
+end
+
+def run_baseline(args)
+  strategy = (args[:strategy] || ENV.fetch('EVAL_BASELINE_STRATEGY', 'grep')).to_sym
+  query_set_path = ENV.fetch('EVAL_QUERY_SET', 'config/eval_queries.json')
+  limit = ENV.fetch('EVAL_BASELINE_LIMIT', '10').to_i
+
+  puts "Loading query set from: #{query_set_path}"
+  query_set = Woods::Evaluation::QuerySet.load(query_set_path)
+  puts "Running #{strategy} baseline (limit: #{limit})..."
+
+  runner = Woods::Evaluation::BaselineRunner.new(
+    metadata_store: Woods.metadata_store
+  )
+
+  totals = compute_baseline_totals(query_set, runner, strategy, limit)
+  print_baseline_report(strategy, query_set.size, totals)
+end
+
+def compute_baseline_totals(query_set, runner, strategy, limit)
+  total_mrr = 0.0
+  total_recall = 0.0
+
+  query_set.queries.each do |query|
+    results = runner.run(query.query, strategy: strategy, limit: limit)
+    total_mrr += Woods::Evaluation::Metrics.mrr(results, query.expected_units)
+    total_recall += Woods::Evaluation::Metrics.recall(results, query.expected_units)
+  end
+
+  { mrr: total_mrr, recall: total_recall }
+end
+
+def print_eval_report(report, output_path)
+  puts
+  puts 'Evaluation complete!'
+  puts '=' * 50
+  report.aggregates.each do |key, value|
+    formatted = value.is_a?(Float) ? format('%.4f', value) : value.to_s
+    puts "  #{key.to_s.ljust(25)}: #{formatted}"
+  end
+  puts '=' * 50
+  puts "Report saved to: #{output_path}"
+end
+
+def print_baseline_report(strategy, count, totals)
+  puts
+  puts "Baseline: #{strategy}"
+  puts '=' * 50
+  puts "  Mean MRR:    #{format('%.4f', count.positive? ? totals[:mrr] / count : 0.0)}"
+  puts "  Mean Recall: #{format('%.4f', count.positive? ? totals[:recall] / count : 0.0)}"
+  puts '=' * 50
+end
+
+# Build a retriever for evaluation (requires Rails environment with stores configured).
+#
+# @return [Woods::Retriever]
+def build_eval_retriever
+  Woods::Retriever.new(
+    vector_store: Woods.vector_store,
+    metadata_store: Woods.metadata_store,
+    graph_store: Woods.graph_store,
+    embedding_provider: Woods.embedding_provider
+  )
+end

data/lib/woods/ast/call_site_extractor.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'set'
+require_relative 'node'
+
+module Woods
+  module Ast
+    # Method names that are too common to be useful in call graphs.
+    INSIGNIFICANT_METHODS = Set.new(%w[
+                                      to_s to_i to_f to_a to_h to_sym to_r to_c to_str to_proc
+                                      nil? present? blank? empty? any? none? frozen? is_a? kind_of?
+                                      respond_to? respond_to_missing? instance_of? equal?
+                                      == != eql? <=> === =~ !~ >= <= > <
+                                      ! & | ^ ~ + - * / % **
+                                      freeze dup clone inspect hash object_id class
+                                      send __send__ method tap then yield_self itself
+                                      new allocate
+                                      [] []=
+                                      length size count
+                                      first last
+                                      map each select reject flat_map collect detect find_index
+                                      merge merge! update
+                                      keys values
+                                      push pop shift unshift
+                                      strip chomp chop downcase upcase
+                                      puts print p pp warn raise fail
+                                      require require_relative load autoload
+                                      attr_reader attr_writer attr_accessor
+                                      private protected public
+                                      include extend prepend
+                                    ]).freeze
+
+    # Extracts call sites from an AST node tree.
+    #
+    # Returns method calls found in the tree, ordered by source line number.
+    # Used by both RubyAnalyzer (call graph building) and FlowAssembler
+    # (execution flow ordering).
+    #
+    # @example Extracting calls from a method body
+    #   parser = Ast::Parser.new
+    #   root = parser.parse(source)
+    #   calls = Ast::CallSiteExtractor.new.extract(root)
+    #   calls.first #=> { receiver: "User", method_name: "find", arguments: ["id"], line: 3, block: false }
+    #
+    class CallSiteExtractor
+      # Extract all call sites from an AST node, ordered by line number.
+      #
+      # @param node [Ast::Node] The AST node to search
+      # @return [Array<Hash>] Call site hashes ordered by line ascending
+      def extract(node)
+        calls = []
+        collect_calls(node, calls)
+        calls.sort_by { |c| c[:line] }
+      end
+
+      # Extract only significant call sites, filtering out noise.
+      #
+      # @param node [Ast::Node] The AST node to search
+      # @param known_units [Array<String>] Known unit identifiers for relevance filtering
+      # @return [Array<Hash>] Filtered call site hashes
+      def extract_significant(node, known_units: [])
+        calls = extract(node)
+        known_set = Set.new(known_units)
+
+        calls.reject do |call|
+          INSIGNIFICANT_METHODS.include?(call[:method_name]) &&
+            (known_units.empty? || !known_set.include?(call[:receiver]))
+        end
+      end
+
+      private
+
+      def collect_calls(node, calls)
+        return unless node.is_a?(Ast::Node)
+
+        case node.type
+        when :send
+          calls << {
+            receiver: node.receiver,
+            method_name: node.method_name,
+            arguments: node.arguments || [],
+            line: node.line,
+            block: false
+          }
+        when :block
+          # The send node in a block gets block: true
+          send_child = node.children&.first
+          if send_child.is_a?(Ast::Node) && send_child.type == :send
+            calls << {
+              receiver: send_child.receiver,
+              method_name: send_child.method_name,
+              arguments: send_child.arguments || [],
+              line: send_child.line,
+              block: true
+            }
+          end
+          # Also recurse into block body (children[1])
+          node.children&.drop(1)&.each { |child| collect_calls(child, calls) }
+          return # Don't double-recurse into children
+        end
+
+        (node.children || []).each { |child| collect_calls(child, calls) }
+      end
+    end
+  end
+end

data/lib/woods/ast/method_extractor.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative 'parser'
+require_relative 'node'
+
+module Woods
+  module Ast
+    # Extracts method definitions and their source from Ruby source code.
+    #
+    # Replaces the fragile ~240 lines of `nesting_delta` / `neutralize_strings_and_comments`
+    # / `detect_heredoc_start` indentation heuristics in controller and mailer extractors.
+    #
+    # @example Extracting a method's source
+    #   extractor = Ast::MethodExtractor.new
+    #   source = extractor.extract_method_source(code, "create")
+    #   # => "def create\n  @user = User.find(params[:id])\nend\n"
+    #
+    class MethodExtractor
+      include SourceSpan
+
+      # @param parser [Ast::Parser, nil] Parser instance (creates default if nil)
+      def initialize(parser: nil)
+        @parser = parser || Parser.new
+      end
+
+      # Extract a method definition node by name.
+      #
+      # @param source [String] Ruby source code
+      # @param method_name [String] Method name to find
+      # @param class_method [Boolean] If true, look for `def self.method_name`
+      # @return [Ast::Node, nil] The :def or :defs node, or nil if not found
+      def extract_method(source, method_name, class_method: false)
+        root = @parser.parse(source)
+        target_type = class_method ? :defs : :def
+
+        root.find_all(target_type).find do |node|
+          node.method_name == method_name.to_s
+        end
+      end
+
+      # Extract all method definition nodes from source.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<Ast::Node>] All :def and :defs nodes
+      def extract_all_methods(source)
+        root = @parser.parse(source)
+        root.find_all(:def) + root.find_all(:defs)
+      end
+
+      # Extract the raw source text of a method, including def...end.
+      #
+      # This is the key replacement for `extract_action_source` in the controller
+      # and mailer extractors. Uses AST line tracking instead of indentation heuristics.
+      #
+      # @param source [String] Ruby source code
+      # @param method_name [String] Method name to find
+      # @param class_method [Boolean] If true, look for `def self.method_name`
+      # @return [String, nil] The method source text, or nil if not found
+      def extract_method_source(source, method_name, class_method: false)
+        node = extract_method(source, method_name, class_method: class_method)
+        return nil unless node
+
+        # If the node has a source field populated by the parser, use it
+        return node.source if node.source
+
+        # Fallback: extract by line range
+        extract_source_span(source, node.line, node.end_line)
+      end
+    end
+  end
+end

data/lib/woods/ast/node.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Woods
+  module Ast
+    # Normalized AST node struct used by all consumers.
+    #
+    # Provides a parser-independent representation of Ruby AST nodes.
+    # Both Prism and the parser gem are normalized to this common structure.
+    #
+    # @example Creating a send node
+    #   node = Ast::Node.new(
+    #     type: :send,
+    #     children: [],
+    #     line: 42,
+    #     receiver: "User",
+    #     method_name: "find",
+    #     arguments: ["id"]
+    #   )
+    #
+    Node = Struct.new(
+      :type,        # Symbol: :send, :block, :if, :def, :defs, :class, :module, :const, :begin, etc.
+      :children,    # Array<Ast::Node | String | Symbol | Integer | nil>
+      :line,        # Integer: 1-based source line number
+      :receiver,    # String | nil: method call receiver (for :send)
+      :method_name, # String | nil: method name (for :send, :def, :defs)
+      :arguments,   # Array<String>: argument representations (for :send)
+      :source,      # String | nil: raw source text of this node
+      :end_line,    # Integer | nil: 1-based end line number (when available)
+      keyword_init: true
+    ) do
+      # Find all descendant nodes matching a type.
+      #
+      # @param target_type [Symbol] The node type to search for
+      # @return [Array<Ast::Node>] All matching descendant nodes
+      def find_all(target_type)
+        results = []
+        queue = [self]
+        while (current = queue.shift)
+          results << current if current.type == target_type
+          (current.children || []).each do |child|
+            queue << child if child.is_a?(Ast::Node)
+          end
+        end
+        results
+      end
+
+      # Find the first descendant node matching a type (depth-first).
+      #
+      # @param target_type [Symbol] The node type to search for
+      # @return [Ast::Node, nil] The first matching node or nil
+      def find_first(target_type)
+        return self if type == target_type
+
+        (children || []).each do |child|
+          next unless child.is_a?(Ast::Node)
+
+          result = child.find_first(target_type)
+          return result if result
+        end
+        nil
+      end
+
+      # Return source text representation.
+      #
+      # @return [String] The source field if present, otherwise a reconstruction
+      def to_source
+        return source if source
+
+        case type
+        when :send
+          parts = []
+          parts << receiver if receiver
+          parts << method_name if method_name
+          parts.join('.')
+        when :const
+          parts = []
+          parts << receiver if receiver
+          parts << method_name if method_name
+          parts.join('::')
+        when :def, :defs
+          "def #{method_name}"
+        else
+          type.to_s
+        end
+      end
+    end
+
+    # Mixin for line-range source extraction, shared across Parser, MethodExtractor,
+    # and ClassAnalyzer.
+    #
+    # @example
+    #   include Ast::SourceSpan
+    #   extract_source_span(source, node.line, node.end_line)
+    #
+    module SourceSpan
+      private
+
+      # Extract source lines for a 1-based start/end line range.
+      #
+      # @param source [String] Full source text
+      # @param start_line [Integer, nil] 1-based start line
+      # @param end_line [Integer, nil] 1-based end line
+      # @return [String, nil] Extracted lines joined, or nil if out of range
+      def extract_source_span(source, start_line, end_line)
+        return nil unless start_line && end_line
+
+        lines = source.lines
+        start_idx = start_line - 1
+        end_idx = end_line - 1
+        return nil if start_idx.negative? || end_idx >= lines.length
+
+        lines[start_idx..end_idx].join
+      end
+    end
+  end
+end