woods 1.0.0

data/lib/woods/session_tracer/session_flow_document.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Woods
+  module SessionTracer
+    # Value object representing an assembled session flow trace.
+    #
+    # Contains a two-level structure:
+    # - **Timeline** — ordered steps with unit_refs and side_effects (lightweight)
+    # - **Context pool** — deduplicated ExtractedUnit data (heavy, included once each)
+    #
+    # Follows the FlowDocument pattern for serialization and rendering.
+    #
+    # @example
+    #   doc = SessionFlowDocument.new(
+    #     session_id: "abc123",
+    #     steps: [...],
+    #     context_pool: { "OrdersController" => { ... } },
+    #     generated_at: Time.now.utc.iso8601
+    #   )
+    #   doc.to_h         # => JSON-serializable Hash
+    #   doc.to_markdown   # => human-readable document
+    #   doc.to_context    # => LLM XML format
+    #
+    # rubocop:disable Metrics/ClassLength
+    class SessionFlowDocument
+      attr_reader :session_id, :steps, :context_pool, :side_effects,
+                  :dependency_map, :token_count, :generated_at
+
+      # @param session_id [String] The session identifier
+      # @param steps [Array<Hash>] Ordered timeline steps
+      # @param context_pool [Hash<String, Hash>] Deduplicated unit data keyed by identifier
+      # @param side_effects [Array<Hash>] Async side effects (jobs, mailers)
+      # @param dependency_map [Hash<String, Array<String>>] Unit -> dependency identifiers
+      # @param token_count [Integer] Estimated total tokens
+      # @param generated_at [String, nil] ISO8601 timestamp (defaults to now)
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(session_id:, steps: [], context_pool: {}, side_effects: [],
+                     dependency_map: {}, token_count: 0, generated_at: nil)
+        @session_id = session_id
+        @steps = steps
+        @context_pool = context_pool
+        @side_effects = side_effects
+        @dependency_map = dependency_map
+        @token_count = token_count
+        @generated_at = generated_at || Time.now.utc.iso8601
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Serialize to a JSON-compatible Hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          session_id: @session_id,
+          generated_at: @generated_at,
+          token_count: @token_count,
+          steps: @steps,
+          context_pool: @context_pool,
+          side_effects: @side_effects,
+          dependency_map: @dependency_map
+        }
+      end
+
+      # Reconstruct from a serialized Hash.
+      #
+      # Handles both symbol and string keys for JSON round-trip compatibility.
+      #
+      # @param data [Hash] Previously serialized document data
+      # @return [SessionFlowDocument]
+      def self.from_h(data)
+        data = deep_symbolize_keys(data)
+
+        new(
+          session_id: data[:session_id],
+          steps: data[:steps] || [],
+          context_pool: data[:context_pool] || {},
+          side_effects: data[:side_effects] || [],
+          dependency_map: data[:dependency_map] || {},
+          token_count: data[:token_count] || 0,
+          generated_at: data[:generated_at]
+        )
+      end
+
+      # Render as human-readable Markdown.
+      #
+      # @return [String]
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def to_markdown
+        lines = []
+        lines << "## Session: #{@session_id}"
+        lines << "_Generated at #{@generated_at} | #{@steps.size} requests | ~#{@token_count} tokens_"
+        lines << ''
+
+        # Timeline
+        lines << '### Timeline'
+        lines << ''
+        @steps.each_with_index do |step, idx|
+          status = step[:status] || '?'
+          duration = step[:duration_ms] ? " (#{step[:duration_ms]}ms)" : ''
+          entry = "#{idx + 1}. #{step[:method]} #{step[:path]} → " \
+                  "#{step[:controller]}##{step[:action]} [#{status}]#{duration}"
+          lines << entry
+        end
+        lines << ''
+
+        # Side effects
+        if @side_effects.any?
+          lines << '### Side Effects'
+          lines << ''
+          @side_effects.each do |effect|
+            lines << "- #{effect[:type]}: #{effect[:identifier]} (triggered by #{effect[:trigger_step]})"
+          end
+          lines << ''
+        end
+
+        # Context pool
+        if @context_pool.any?
+          lines << '### Code Units'
+          lines << ''
+          @context_pool.each do |identifier, unit|
+            type = unit[:type] || 'unknown'
+            file_path = unit[:file_path]
+            lines << "#### #{identifier} (#{type})"
+            lines << "_#{file_path}_" if file_path
+            lines << ''
+            next unless unit[:source_code]
+
+            lines << '```ruby'
+            lines << unit[:source_code]
+            lines << '```'
+            lines << ''
+          end
+        end
+
+        # Dependencies
+        if @dependency_map.any?
+          lines << '### Dependencies'
+          lines << ''
+          @dependency_map.each do |unit_id, deps|
+            lines << "- #{unit_id} → #{deps.join(', ')}"
+          end
+          lines << ''
+        end
+
+        lines.join("\n")
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      # Render as LLM-consumable XML context.
+      #
+      # Follows the format from docs/CONTEXT_AND_CHUNKING.md.
+      #
+      # @return [String]
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def to_context
+        lines = []
+        header = "<session_context session_id=\"#{@session_id}\" requests=\"#{@steps.size}\" " \
+                 "tokens=\"#{@token_count}\" units=\"#{@context_pool.size}\">"
+        lines << header
+
+        # Timeline
+        lines << '<session_timeline>'
+        @steps.each_with_index do |step, idx|
+          status = step[:status] || '?'
+          duration = step[:duration_ms] ? ", #{step[:duration_ms]}ms" : ''
+          entry = "#{idx + 1}. #{step[:method]} #{step[:path]} → " \
+                  "#{step[:controller]}##{step[:action]} (#{status}#{duration})"
+          lines << entry
+        end
+        lines << '</session_timeline>'
+
+        # Units
+        @context_pool.each do |identifier, unit|
+          type = unit[:type] || 'unknown'
+          file_path = unit[:file_path] || 'unknown'
+          lines << %(<unit identifier="#{identifier}" type="#{type}" file="#{file_path}">)
+          lines << (unit[:source_code] || '# source not available')
+          lines << '</unit>'
+        end
+
+        # Side effects
+        if @side_effects.any?
+          lines << '<side_effects>'
+          @side_effects.each do |effect|
+            lines << "#{effect[:identifier]} (triggered by #{effect[:trigger_step]}, #{effect[:type]})"
+          end
+          lines << '</side_effects>'
+        end
+
+        # Dependencies
+        if @dependency_map.any?
+          lines << '<dependencies>'
+          @dependency_map.each do |unit_id, deps|
+            lines << "#{unit_id} → #{deps.join(', ')}"
+          end
+          lines << '</dependencies>'
+        end
+
+        lines << '</session_context>'
+        lines.join("\n")
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      # @api private
+      def self.deep_symbolize_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), result|
+            result[key.to_sym] = deep_symbolize_keys(value)
+          end
+        when Array
+          obj.map { |item| deep_symbolize_keys(item) }
+        else
+          obj
+        end
+      end
+      private_class_method :deep_symbolize_keys
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/woods/session_tracer/solid_cache_store.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'store'
+
+module Woods
+  module SessionTracer
+    # SolidCache-backed session store.
+    #
+    # Uses SolidCache key-value storage with `expires_in`. Single JSON blob
+    # per session (read-modify-write pattern). Requires the `solid_cache` gem.
+    #
+    # @example
+    #   store = SolidCacheStore.new(cache: SolidCache::Store.new, expires_in: 3600)
+    #   store.record("abc123", { controller: "OrdersController", action: "create" })
+    #
+    class SolidCacheStore < Store
+      KEY_PREFIX = 'woods:session:'
+      INDEX_KEY = 'woods:session_index'
+
+      # @param cache [ActiveSupport::Cache::Store] A SolidCache (or compatible) cache instance
+      # @param expires_in [Integer, nil] Expiry time in seconds (nil = no expiry)
+      def initialize(cache:, expires_in: nil)
+        super()
+        @cache = cache
+        @expires_in = expires_in
+      end
+
+      # Append a request record to a session (read-modify-write).
+      #
+      # NOTE: Not atomic — concurrent writes to the same session may lose data.
+      # Acceptable for development tracing. For high-concurrency tracing, use
+      # RedisStore (RPUSH is atomic) or FileStore (LOCK_EX).
+      #
+      # @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)
+        existing = @cache.read(key)
+        requests = existing ? JSON.parse(existing) : []
+        requests << request_data
+
+        write_opts = @expires_in ? { expires_in: @expires_in } : {}
+        @cache.write(key, JSON.generate(requests), **write_opts)
+
+        update_index(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)
+        raw = @cache.read(key)
+        return [] unless raw
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        []
+      end
+
+      # List recent session summaries.
+      #
+      # @param limit [Integer] Maximum number of sessions to return
+      # @return [Array<Hash>] Session summaries
+      def sessions(limit: 20)
+        index = read_index
+        active = index.select { |id| @cache.exist?(session_key(id)) }
+
+        # Clean up expired entries from the index
+        write_index(active) if active.size != index.size
+
+        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)
+        @cache.delete(session_key(session_id))
+        index = read_index
+        index.delete(session_id)
+        write_index(index)
+      end
+
+      # Remove all session data.
+      #
+      # @return [void]
+      def clear_all
+        index = read_index
+        index.each { |id| @cache.delete(session_key(id)) }
+        @cache.delete(INDEX_KEY)
+      end
+
+      private
+
+      # @param session_id [String]
+      # @return [String] Cache key for this session
+      def session_key(session_id)
+        "#{KEY_PREFIX}#{sanitize_session_id(session_id)}"
+      end
+
+      # Read the session index (list of known session IDs).
+      #
+      # @return [Array<String>]
+      def read_index
+        raw = @cache.read(INDEX_KEY)
+        return [] unless raw
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        []
+      end
+
+      # Write the session index.
+      #
+      # @param ids [Array<String>]
+      def write_index(ids)
+        @cache.write(INDEX_KEY, JSON.generate(ids))
+      end
+
+      # Add a session ID to the index if not already present.
+      #
+      # @param session_id [String]
+      def update_index(session_id)
+        index = read_index
+        return if index.include?(session_id)
+
+        index << session_id
+        write_index(index)
+      end
+    end
+  end
+end

data/lib/woods/session_tracer/store.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Woods
+  module SessionTracer
+    # Abstract store interface for session trace data.
+    #
+    # Concrete implementations must define:
+    # - `record(session_id, request_data)` — append a request record
+    # - `read(session_id)` — return all requests for a session, ordered by timestamp
+    # - `sessions(limit:)` — return recent session summaries
+    # - `clear(session_id)` — remove a single session
+    # - `clear_all` — remove all sessions
+    #
+    # @abstract Subclass and implement the required methods.
+    class Store
+      # Append a request record to a session.
+      #
+      # @param session_id [String] The session identifier
+      # @param request_data [Hash] Request metadata to store
+      # @return [void]
+      def record(session_id, request_data)
+        raise NotImplementedError, "#{self.class}#record must be implemented"
+      end
+
+      # Read all request records for a session, ordered by timestamp.
+      #
+      # @param session_id [String] The session identifier
+      # @return [Array<Hash>] Request records, oldest first
+      def read(session_id)
+        raise NotImplementedError, "#{self.class}#read must be implemented"
+      end
+
+      # List recent session summaries.
+      #
+      # @param limit [Integer] Maximum number of sessions to return
+      # @return [Array<Hash>] Session summaries with :session_id, :request_count, :first_request, :last_request
+      def sessions(limit: 20)
+        raise NotImplementedError, "#{self.class}#sessions must be implemented"
+      end
+
+      # Remove all data for a single session.
+      #
+      # @param session_id [String] The session identifier
+      # @return [void]
+      def clear(session_id)
+        raise NotImplementedError, "#{self.class}#clear must be implemented"
+      end
+
+      # Remove all session data.
+      #
+      # @return [void]
+      def clear_all
+        raise NotImplementedError, "#{self.class}#clear_all must be implemented"
+      end
+
+      private
+
+      # Sanitize a session ID for use in keys/filenames.
+      #
+      # @param session_id [String] Raw session identifier
+      # @return [String] Sanitized identifier (alphanumeric, hyphens, underscores only)
+      def sanitize_session_id(session_id)
+        session_id.to_s.gsub(/[^a-zA-Z0-9_-]/, '_')
+      end
+
+      # Build a session summary hash from a session ID and its requests.
+      #
+      # @param session_id [String]
+      # @param requests [Array<Hash>]
+      # @return [Hash]
+      def session_summary(session_id, requests)
+        {
+          'session_id' => session_id,
+          'request_count' => requests.size,
+          'first_request' => requests.first&.fetch('timestamp', nil),
+          'last_request' => requests.last&.fetch('timestamp', nil)
+        }
+      end
+    end
+  end
+end

data/lib/woods/storage/graph_store.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative '../dependency_graph'
+
+module Woods
+  module Storage
+    # GraphStore provides an interface for querying code unit relationships.
+    #
+    # All graph store adapters must include the {Interface} module and implement
+    # its methods. The {Memory} adapter wraps the existing {DependencyGraph}.
+    #
+    # @example Using the memory adapter
+    #   store = Woods::Storage::GraphStore::Memory.new
+    #   store.register(unit)
+    #   store.dependencies_of("User")
+    #
+    module GraphStore
+      # Interface that all graph store adapters must implement.
+      module Interface
+        # Get direct dependencies of a unit.
+        #
+        # @param identifier [String] Unit identifier
+        # @return [Array<String>] List of dependency identifiers
+        # @raise [NotImplementedError] if not implemented by adapter
+        def dependencies_of(identifier)
+          raise NotImplementedError
+        end
+
+        # Get direct dependents of a unit (reverse dependencies).
+        #
+        # @param identifier [String] Unit identifier
+        # @return [Array<String>] List of dependent identifiers
+        # @raise [NotImplementedError] if not implemented by adapter
+        def dependents_of(identifier)
+          raise NotImplementedError
+        end
+
+        # Find all units transitively affected by changes to the given files.
+        #
+        # @param changed_files [Array<String>] List of changed file paths
+        # @param max_depth [Integer, nil] Maximum traversal depth (nil for unlimited)
+        # @return [Array<String>] List of affected unit identifiers
+        # @raise [NotImplementedError] if not implemented by adapter
+        def affected_by(changed_files, max_depth: nil)
+          raise NotImplementedError
+        end
+
+        # Get all units of a specific type.
+        #
+        # @param type [Symbol] Unit type (:model, :controller, etc.)
+        # @return [Array<String>] List of unit identifiers
+        # @raise [NotImplementedError] if not implemented by adapter
+        def by_type(type)
+          raise NotImplementedError
+        end
+
+        # Compute PageRank importance scores for all units.
+        #
+        # @param damping [Float] Damping factor (default: 0.85)
+        # @param iterations [Integer] Number of iterations (default: 20)
+        # @return [Hash<String, Float>] Identifier => PageRank score
+        # @raise [NotImplementedError] if not implemented by adapter
+        def pagerank(damping: 0.85, iterations: 20)
+          raise NotImplementedError
+        end
+      end
+
+      # In-memory graph store wrapping the existing DependencyGraph.
+      #
+      # Delegates all operations to {Woods::DependencyGraph}, providing
+      # a consistent storage interface.
+      #
+      # @example
+      #   store = Memory.new
+      #   store.register(user_unit)
+      #   store.dependencies_of("User")  # => ["Organization"]
+      #
+      class Memory
+        include Interface
+
+        # @param graph [DependencyGraph, nil] Existing graph to wrap, or nil to create a new one
+        def initialize(graph = nil)
+          @graph = graph || DependencyGraph.new
+        end
+
+        # Register a unit in the graph.
+        #
+        # @param unit [ExtractedUnit] The unit to register
+        def register(unit)
+          @graph.register(unit)
+        end
+
+        # @see Interface#dependencies_of
+        def dependencies_of(identifier)
+          @graph.dependencies_of(identifier)
+        end
+
+        # @see Interface#dependents_of
+        def dependents_of(identifier)
+          @graph.dependents_of(identifier)
+        end
+
+        # @see Interface#affected_by
+        def affected_by(changed_files, max_depth: nil)
+          @graph.affected_by(changed_files, max_depth: max_depth)
+        end
+
+        # @see Interface#by_type
+        def by_type(type)
+          @graph.units_of_type(type)
+        end
+
+        # @see Interface#pagerank
+        def pagerank(damping: 0.85, iterations: 20)
+          @graph.pagerank(damping: damping, iterations: iterations)
+        end
+      end
+    end
+  end
+end