woods 1.0.0

data/lib/woods/ruby_analyzer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative 'ast'
+require_relative 'extracted_unit'
+require_relative 'ruby_analyzer/class_analyzer'
+require_relative 'ruby_analyzer/method_analyzer'
+require_relative 'ruby_analyzer/dataflow_analyzer'
+require_relative 'ruby_analyzer/trace_enricher'
+
+module Woods
+  # Analyzes plain Ruby source code and produces ExtractedUnit objects.
+  #
+  # Orchestrates ClassAnalyzer, MethodAnalyzer, DataFlowAnalyzer, and
+  # optional TraceEnricher to extract structured data from Ruby files.
+  #
+  # @example Analyze gem source
+  #   units = Woods::RubyAnalyzer.analyze(paths: ["lib/"])
+  #   units.select { |u| u.type == :ruby_class }.map(&:identifier)
+  #
+  module RubyAnalyzer
+    class << self
+      # Analyze Ruby source files and produce ExtractedUnit objects.
+      #
+      # @param paths [Array<String>] File paths or directories to analyze
+      # @param trace_data [Array<Hash>, nil] Optional runtime trace data for enrichment
+      # @return [Array<ExtractedUnit>] All extracted units
+      def analyze(paths:, trace_data: nil)
+        files = discover_files(paths)
+        return [] if files.empty?
+
+        parser = Ast::Parser.new
+        class_analyzer = ClassAnalyzer.new(parser: parser)
+        method_analyzer = MethodAnalyzer.new(parser: parser)
+        dataflow_analyzer = DataFlowAnalyzer.new(parser: parser)
+
+        units = []
+
+        files.each do |file_path|
+          source = read_file(file_path)
+          next unless source
+
+          units.concat(class_analyzer.analyze(source: source, file_path: file_path))
+          units.concat(method_analyzer.analyze(source: source, file_path: file_path))
+        rescue Woods::ExtractionError
+          # Skip files that fail to parse
+          next
+        end
+
+        dataflow_analyzer.annotate(units)
+        TraceEnricher.merge(units: units, trace_data: trace_data) if trace_data
+
+        units
+      end
+
+      private
+
+      # Discover .rb files from a list of paths (files and/or directories).
+      #
+      # @param paths [Array<String>] File paths or directory paths
+      # @return [Array<String>] Absolute paths to .rb files
+      def discover_files(paths)
+        files = []
+        paths.each do |path|
+          expanded = File.expand_path(path)
+          if File.directory?(expanded)
+            Dir.glob(File.join(expanded, '**', '*.rb')).each do |f|
+              files << f
+            end
+          elsif File.file?(expanded) && expanded.end_with?('.rb')
+            files << expanded
+          end
+        end
+        files.uniq
+      end
+
+      # Read a file safely, returning nil on failure.
+      #
+      # @param path [String] File path
+      # @return [String, nil] File contents or nil
+      def read_file(path)
+        File.read(path)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/woods/session_tracer/file_store.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require_relative 'store'
+
+module Woods
+  module SessionTracer
+    # File-backed session store using JSONL (one JSON object per line).
+    #
+    # Sessions are stored as individual files in a configurable directory:
+    #   {base_dir}/{session_id}.jsonl
+    #
+    # Append-only with file locking for concurrency safety. Zero external dependencies.
+    #
+    # @example
+    #   store = FileStore.new(base_dir: "tmp/woods/sessions")
+    #   store.record("abc123", { controller: "PostsController", action: "create" })
+    #   store.read("abc123") # => [{ "controller" => "PostsController", ... }]
+    #
+    class FileStore < Store
+      # @param base_dir [String] Directory for session JSONL files
+      def initialize(base_dir:)
+        super()
+        @base_dir = base_dir
+        FileUtils.mkdir_p(@base_dir)
+      end
+
+      # Append a request record to a session's JSONL file.
+      #
+      # Uses file locking (LOCK_EX) for concurrency safety.
+      #
+      # @param session_id [String] The session identifier
+      # @param request_data [Hash] Request metadata to store
+      # @return [void]
+      def record(session_id, request_data)
+        path = session_path(session_id)
+        line = "#{JSON.generate(request_data)}\n"
+
+        File.open(path, 'a') do |f|
+          f.flock(File::LOCK_EX)
+          f.write(line)
+        end
+      end
+
+      # Read all request records for a session, ordered by file line order (timestamp).
+      #
+      # @param session_id [String] The session identifier
+      # @return [Array<Hash>] Request records, oldest first
+      def read(session_id)
+        path = session_path(session_id)
+        return [] unless File.exist?(path)
+
+        File.readlines(path).filter_map do |line|
+          stripped = line.strip
+          next if stripped.empty?
+
+          JSON.parse(stripped)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      # List recent session summaries, sorted by last modification time (newest first).
+      #
+      # @param limit [Integer] Maximum number of sessions to return
+      # @return [Array<Hash>] Session summaries
+      def sessions(limit: 20)
+        pattern = File.join(@base_dir, '*.jsonl')
+        files = Dir.glob(pattern).sort_by { |f| -File.mtime(f).to_f }
+
+        files.first(limit).map do |file|
+          session_id = File.basename(file, '.jsonl')
+          session_summary(session_id, read(session_id))
+        end
+      end
+
+      # Remove all data for a single session.
+      #
+      # @param session_id [String] The session identifier
+      # @return [void]
+      def clear(session_id)
+        path = session_path(session_id)
+        FileUtils.rm_f(path)
+      end
+
+      # Remove all session data.
+      #
+      # @return [void]
+      def clear_all
+        pattern = File.join(@base_dir, '*.jsonl')
+        Dir.glob(pattern).each { |f| File.delete(f) }
+      end
+
+      private
+
+      # @param session_id [String]
+      # @return [String] Full path to the session's JSONL file
+      def session_path(session_id)
+        File.join(@base_dir, "#{sanitize_session_id(session_id)}.jsonl")
+      end
+    end
+  end
+end

data/lib/woods/session_tracer/middleware.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Woods
+  module SessionTracer
+    # Rack middleware that captures request metadata for session tracing.
+    #
+    # Wraps `@app.call(env)`, records after response. Extracts controller/action
+    # from `env['action_dispatch.request.path_parameters']`. Session ID from
+    # `X-Trace-Session` header first, falls back to `request.session.id`.
+    #
+    # Fire-and-forget writes — `rescue StandardError` on recording, never breaks the request.
+    #
+    # @example Inserting into a Rails middleware stack
+    #   app.middleware.insert_after ActionDispatch::Session::CookieStore,
+    #                               Woods::SessionTracer::Middleware
+    #
+    class Middleware
+      # @param app [#call] The downstream Rack application
+      # @param store [Store] Session trace store backend
+      # @param session_id_proc [Proc, nil] Custom session ID extraction (receives env)
+      # @param exclude_paths [Array<String>] Path prefixes to skip
+      def initialize(app, store:, session_id_proc: nil, exclude_paths: [])
+        @app = app
+        @store = store
+        @session_id_proc = session_id_proc
+        @exclude_paths = exclude_paths
+      end
+
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response triple [status, headers, body]
+      def call(env)
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+        status, headers, body = @app.call(env)
+        duration_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - start_time
+
+        begin
+          record_request(env, status, duration_ms)
+        rescue StandardError
+          # Fire-and-forget — recording failures never break the request
+        end
+
+        [status, headers, body]
+      end
+
+      private
+
+      # Record the request metadata to the store.
+      #
+      # @param env [Hash] Rack environment
+      # @param status [Integer] HTTP response status
+      # @param duration_ms [Integer] Request duration in milliseconds
+      # rubocop:disable Metrics/MethodLength
+      def record_request(env, status, duration_ms)
+        path = env['PATH_INFO'] || ''
+        return if excluded?(path)
+
+        session_id = extract_session_id(env)
+        return unless session_id
+
+        path_params = env['action_dispatch.request.path_parameters'] || {}
+        controller = path_params[:controller]
+        action = path_params[:action]
+        return unless controller
+
+        # Classify controller name (e.g., "orders" -> "OrdersController")
+        controller_class = classify_controller(controller)
+
+        request_data = {
+          'session_id' => session_id,
+          'trace_tag' => env['HTTP_X_TRACE_SESSION'],
+          'timestamp' => Time.now.utc.iso8601,
+          'method' => env['REQUEST_METHOD'],
+          'path' => path,
+          'controller' => controller_class,
+          'action' => action.to_s,
+          'status' => status.to_i,
+          'duration_ms' => duration_ms.to_i,
+          'format' => extract_format(env)
+        }
+
+        @store.record(session_id, request_data)
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Extract session ID: X-Trace-Session header first, then session cookie, then fallback.
+      #
+      # @param env [Hash] Rack environment
+      # @return [String, nil] Session identifier
+      def extract_session_id(env)
+        return @session_id_proc.call(env) if @session_id_proc
+
+        # 1. X-Trace-Session header (explicit trace tag doubles as session ID)
+        trace_header = env['HTTP_X_TRACE_SESSION']
+        return trace_header if trace_header && !trace_header.empty?
+
+        # 2. Rack session ID
+        session = env['rack.session']
+        session_id = session&.id || session&.dig('session_id')
+        return session_id.to_s if session_id
+
+        nil
+      end
+
+      # Check if the path should be excluded from tracing.
+      #
+      # @param path [String] Request path
+      # @return [Boolean]
+      def excluded?(path)
+        @exclude_paths.any? { |prefix| path.start_with?(prefix) }
+      end
+
+      # Classify a Rails controller path segment into a controller class name.
+      #
+      # @param controller [String] e.g., "orders" or "admin/orders"
+      # @return [String] e.g., "OrdersController" or "Admin::OrdersController"
+      def classify_controller(controller)
+        parts = controller.to_s
+                          .split('/')
+                          .map { |segment| segment.split('_').map(&:capitalize).join }
+        "#{parts.join('::')}Controller"
+      end
+
+      # Extract response format from the Rack env.
+      #
+      # @param env [Hash] Rack environment
+      # @return [String] Format string (e.g., "html", "json")
+      def extract_format(env)
+        # Check action_dispatch format first
+        path_params = env['action_dispatch.request.path_parameters'] || {}
+        return path_params[:format].to_s if path_params[:format]
+
+        # Infer from content type or Accept header
+        accept = env['HTTP_ACCEPT'] || ''
+        return 'json' if accept.include?('application/json')
+        return 'html' if accept.include?('text/html')
+
+        'html'
+      end
+    end
+  end
+end

data/lib/woods/session_tracer/redis_store.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'store'
+
+module Woods
+  module SessionTracer
+    # Redis-backed session store using Lists.
+    #
+    # Each session is stored as a Redis List keyed `woods:session:{id}`.
+    # RPUSH per request for append-only ordering. Native TTL for automatic cleanup.
+    #
+    # Requires the `redis` gem at runtime.
+    #
+    # @example
+    #   store = RedisStore.new(redis: Redis.new, ttl: 3600)
+    #   store.record("abc123", { controller: "OrdersController", action: "create" })
+    #
+    class RedisStore < Store
+      KEY_PREFIX = 'woods:session:'
+      SESSIONS_KEY = 'woods:sessions'
+
+      # @param redis [Redis] A Redis client instance
+      # @param ttl [Integer, nil] Time-to-live in seconds for session keys (nil = no expiry)
+      def initialize(redis:, ttl: nil)
+        super()
+        unless defined?(::Redis)
+          raise SessionTracerError, 'The redis gem is required for RedisStore. Add `gem "redis"` to your Gemfile.'
+        end
+
+        @redis = redis
+        @ttl = ttl
+      end
+
+      # Append a request record to a session's Redis List.
+      #
+      # @param session_id [String] The session identifier
+      # @param request_data [Hash] Request metadata to store
+      # @return [void]
+      def record(session_id, request_data)
+        key = session_key(session_id)
+        @redis.rpush(key, JSON.generate(request_data))
+        @redis.expire(key, @ttl) if @ttl
+        @redis.sadd(SESSIONS_KEY, session_id)
+      end
+
+      # Read all request records for a session.
+      #
+      # @param session_id [String] The session identifier
+      # @return [Array<Hash>] Request records, oldest first
+      def read(session_id)
+        key = session_key(session_id)
+        @redis.lrange(key, 0, -1).filter_map do |json|
+          JSON.parse(json)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      # List recent session summaries.
+      #
+      # @param limit [Integer] Maximum number of sessions to return
+      # @return [Array<Hash>] Session summaries
+      def sessions(limit: 20)
+        all_ids = @redis.smembers(SESSIONS_KEY)
+
+        # Filter to sessions that still have data (TTL may have expired)
+        active = all_ids.select { |id| @redis.exists?(session_key(id)) }
+
+        # Remove expired session IDs from the set
+        expired = all_ids - active
+        expired.each { |id| @redis.srem(SESSIONS_KEY, id) } if expired.any?
+
+        active.first(limit).map do |session_id|
+          session_summary(session_id, read(session_id))
+        end
+      end
+
+      # Remove all data for a single session.
+      #
+      # @param session_id [String] The session identifier
+      # @return [void]
+      def clear(session_id)
+        @redis.del(session_key(session_id))
+        @redis.srem(SESSIONS_KEY, session_id)
+      end
+
+      # Remove all session data.
+      #
+      # @return [void]
+      def clear_all
+        all_ids = @redis.smembers(SESSIONS_KEY)
+        all_ids.each { |id| @redis.del(session_key(id)) }
+        @redis.del(SESSIONS_KEY)
+      end
+
+      private
+
+      # @param session_id [String]
+      # @return [String] Redis key for this session
+      def session_key(session_id)
+        "#{KEY_PREFIX}#{sanitize_session_id(session_id)}"
+      end
+    end
+  end
+end

data/lib/woods/session_tracer/session_flow_assembler.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'set'
+require_relative '../token_utils'
+require_relative 'session_flow_document'
+
+module Woods
+  module SessionTracer
+    # Assembles a context tree from captured session requests against the extracted index.
+    #
+    # Does NOT require Rails — reads from a store + on-disk extracted index.
+    #
+    # Algorithm:
+    # 1. Load requests from store for session_id
+    # 2. For each request, resolve "Controller#action" via IndexReader
+    # 3. Expand dependencies via DependencyGraph — filter :job/:mailer as async side effects
+    # 4. Deduplicate units across steps (include source once, reference by identifier)
+    # 5. Token budget allocation with priority-based truncation
+    # 6. Build SessionFlowDocument
+    #
+    # @example
+    #   assembler = SessionFlowAssembler.new(store: store, reader: reader)
+    #   doc = assembler.assemble("abc123", budget: 8000, depth: 1)
+    #   puts doc.to_context
+    #
+    # rubocop:disable Metrics/ClassLength
+    class SessionFlowAssembler
+      ASYNC_TYPES = %w[job mailer].to_set.freeze
+
+      # @param store [Store] Session trace store
+      # @param reader [MCP::IndexReader] Index reader for unit lookups
+      def initialize(store:, reader:)
+        @store = store
+        @reader = reader
+      end
+
+      # Assemble a context tree for a session.
+      #
+      # @param session_id [String] The session to assemble
+      # @param budget [Integer] Maximum token budget (default: 8000)
+      # @param depth [Integer] Expansion depth (0=metadata only, 1=direct deps, 2+=full flow)
+      # @return [SessionFlowDocument] The assembled document
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      def assemble(session_id, budget: 8000, depth: 1)
+        requests = @store.read(session_id)
+        return empty_document(session_id) if requests.empty?
+
+        steps = []
+        context_pool = {}
+        side_effects = []
+        dependency_map = {}
+        seen_units = Set.new
+
+        requests.each_with_index do |req, idx|
+          step = build_step(req, idx)
+          steps << step
+
+          next if depth.zero?
+
+          controller_id = req['controller']
+          next unless controller_id
+
+          # Resolve controller unit
+          unit = @reader.find_unit(controller_id)
+          if unit && !seen_units.include?(controller_id)
+            seen_units.add(controller_id)
+            context_pool[controller_id] = unit_summary(unit)
+          end
+          step[:unit_refs] = [controller_id].compact
+
+          # Expand dependencies
+          next unless unit
+
+          deps = resolve_dependencies(controller_id, seen_units, context_pool,
+                                      side_effects, step, dependency_map, depth)
+          step[:unit_refs].concat(deps)
+        end
+
+        # Apply token budget
+        token_count = apply_budget(context_pool, budget)
+
+        SessionFlowDocument.new(
+          session_id: session_id,
+          steps: steps,
+          context_pool: context_pool,
+          side_effects: side_effects,
+          dependency_map: dependency_map,
+          token_count: token_count
+        )
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+      private
+
+      # Build a timeline step from a request record.
+      #
+      # @param req [Hash] Request data from store
+      # @param index [Integer] Step index
+      # @return [Hash] Step hash
+      def build_step(req, index)
+        {
+          index: index,
+          method: req['method'],
+          path: req['path'],
+          controller: req['controller'],
+          action: req['action'],
+          status: req['status'],
+          duration_ms: req['duration_ms'],
+          unit_refs: [],
+          side_effects: []
+        }
+      end
+
+      # Resolve dependencies for a unit, separating sync deps from async side effects.
+      #
+      # @return [Array<String>] Non-async dependency identifiers added
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
+      def resolve_dependencies(unit_id, seen_units, context_pool,
+                               side_effects, step, dependency_map, depth)
+        graph = @reader.dependency_graph
+        dep_ids = graph.dependencies_of(unit_id)
+        added = []
+
+        dep_ids.each do |dep_id|
+          dep_unit = @reader.find_unit(dep_id)
+          next unless dep_unit
+
+          dep_type = dep_unit['type']&.to_s
+
+          if ASYNC_TYPES.include?(dep_type)
+            effect = {
+              type: dep_type.to_sym,
+              identifier: dep_id,
+              trigger_step: "#{step[:controller]}##{step[:action]}"
+            }
+            side_effects << effect
+            step[:side_effects] << effect
+          else
+            unless seen_units.include?(dep_id)
+              seen_units.add(dep_id)
+              context_pool[dep_id] = unit_summary(dep_unit)
+              added << dep_id
+
+              # Depth 2+: expand transitive dependencies
+              expand_transitive(dep_id, seen_units, context_pool, dependency_map, depth - 1) if depth >= 2
+            end
+          end
+        end
+
+        # Record dependency map for this unit
+        all_deps = dep_ids.select { |id| @reader.find_unit(id) }
+        dependency_map[unit_id] = all_deps if all_deps.any?
+
+        added
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
+
+      # Expand transitive dependencies (depth 2+).
+      #
+      # @param unit_id [String] Unit to expand from
+      # @param seen_units [Set<String>] Already-seen unit identifiers
+      # @param context_pool [Hash] Accumulator for unit data
+      # @param dependency_map [Hash] Accumulator for dependency edges
+      # @param remaining_depth [Integer] Remaining expansion depth
+      def expand_transitive(unit_id, seen_units, context_pool, dependency_map, remaining_depth)
+        return if remaining_depth <= 0
+
+        graph = @reader.dependency_graph
+        dep_ids = graph.dependencies_of(unit_id)
+        resolved_deps = []
+
+        dep_ids.each do |dep_id|
+          dep_unit = @reader.find_unit(dep_id)
+          next unless dep_unit
+
+          resolved_deps << dep_id
+          next if seen_units.include?(dep_id)
+
+          seen_units.add(dep_id)
+          context_pool[dep_id] = unit_summary(dep_unit)
+
+          expand_transitive(dep_id, seen_units, context_pool, dependency_map, remaining_depth - 1)
+        end
+
+        dependency_map[unit_id] = resolved_deps if resolved_deps.any?
+      end
+
+      # Extract a summary hash from a full unit data hash.
+      #
+      # @param unit [Hash] Full unit data from IndexReader
+      # @return [Hash] Summary with :type, :file_path, :source_code
+      def unit_summary(unit)
+        {
+          type: unit['type'],
+          file_path: unit['file_path'],
+          source_code: unit['source_code']
+        }
+      end
+
+      # Apply token budget by truncating source code from lowest-priority units.
+      #
+      # Priority order (highest first):
+      # 1. Controller action chunks (directly hit by requests)
+      # 2. Direct dependencies (models, services)
+      # 3. Transitive dependencies
+      #
+      # @param context_pool [Hash] Unit data to budget
+      # @param budget [Integer] Maximum tokens
+      # @return [Integer] Actual token count
+      def apply_budget(context_pool, budget)
+        total = estimate_tokens(context_pool)
+        return total if total <= budget
+
+        # Truncate from the end (lowest priority = last added)
+        identifiers = context_pool.keys.reverse
+        identifiers.each do |id|
+          break if total <= budget
+
+          unit = context_pool[id]
+          source = unit[:source_code]
+          next unless source
+
+          source_tokens = TokenUtils.estimate_tokens(source)
+          unit[:source_code] = "# source truncated (#{source_tokens} tokens)"
+          total -= source_tokens
+          total += TokenUtils.estimate_tokens(unit[:source_code])
+        end
+
+        [total, 0].max
+      end
+
+      # Estimate total tokens for the context pool.
+      #
+      # @param context_pool [Hash] Unit data
+      # @return [Integer] Estimated token count
+      def estimate_tokens(context_pool)
+        context_pool.values.sum do |unit|
+          source = unit[:source_code] || ''
+          TokenUtils.estimate_tokens(source) + 20 # overhead for tags/metadata
+        end
+      end
+
+      # Build an empty document for sessions with no requests.
+      #
+      # @param session_id [String]
+      # @return [SessionFlowDocument]
+      def empty_document(session_id)
+        SessionFlowDocument.new(session_id: session_id)
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end