woods 1.6.1 → 2.0.0.beta2

data/lib/woods/ruby_analyzer/fqn_builder.rb

@@ -7,6 +7,8 @@ module Woods
       private
 
       def build_fqn(name, namespace_stack)
+        return name.delete_prefix('::') if name.start_with?('::')
+
         if namespace_stack.empty?
           name
         else

data/lib/woods/ruby_analyzer/mermaid_renderer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'set'
+require_relative '../dependency_graph'
 
 module Woods
   module RubyAnalyzer
@@ -89,16 +90,25 @@ module Woods
           lines << '  end'
         end
 
-        # Render edges
+        # Render edges. `to_h` has emitted `[{target:, via:}]` hashes since the
+        # via migration; iterating them as bare targets made `nodes.key?` false
+        # for every edge, so the map rendered nodes and nothing else (EXTB-6).
+        # Legacy bare-string edges still load — {DependencyGraph.normalize_edges}
+        # accepts both shapes.
         seen_edges = Set.new
         edges.each do |source, targets|
-          Array(targets).each do |target|
-            next unless nodes.key?(target)
+          Woods::DependencyGraph.normalize_edges(Array(targets)).each do |edge|
+            target = edge[:target]
+            next unless target && nodes.key?(target)
 
             edge_key = "#{sanitize_id(source)}->#{sanitize_id(target)}"
             next unless seen_edges.add?(edge_key)
 
-            lines << "  #{sanitize_id(source)} --> #{sanitize_id(target)}"
+            lines << if edge[:via]
+                       "  #{sanitize_id(source)} -->|#{edge[:via]}| #{sanitize_id(target)}"
+                     else
+                       "  #{sanitize_id(source)} --> #{sanitize_id(target)}"
+                     end
           end
         end
 

data/lib/woods/ruby_analyzer/method_analyzer.rb

@@ -63,7 +63,7 @@ module Woods
         body_children = (node.children || [])[body_offset..] || []
 
         visibility_tracker = VisibilityTracker.new
-        inner_ns = namespace_stack + [name]
+        inner_ns = fqn.split('::')
 
         body_children.each do |child|
           next unless child.is_a?(Ast::Node)

data/lib/woods/ruby_analyzer/trace_enricher.rb

@@ -21,7 +21,10 @@ module Woods
       #
       # @yield Block to trace
       # @return [Array<Hash>] Collected trace events
+      # @raise [ArgumentError] if no block is given
       def self.record(&block)
+        raise ArgumentError, 'block required' unless block
+
         traces = []
 
         trace = TracePoint.new(:call, :return) do |tp|

data/lib/woods/ruby_analyzer.rb

@@ -21,11 +21,14 @@ module Woods
     class << self
       # Analyze Ruby source files and produce ExtractedUnit objects.
       #
-      # @param paths [Array<String>] File paths or directories to analyze
+      # @param paths [Array<String>, nil] File paths or directories to analyze
+      # @param sources [Hash{String => String}, nil] Pre-read source keyed by
+      #   absolute file path. This lets callers analyze one consistent source
+      #   snapshot rather than re-reading files while they may be changing.
       # @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)
+      def analyze(paths: nil, sources: nil, trace_data: nil)
+        files = sources ? sources.keys.sort : discover_files(Array(paths))
         return [] if files.empty?
 
         parser = Ast::Parser.new
@@ -36,7 +39,7 @@ module Woods
         units = []
 
         files.each do |file_path|
-          source = read_file(file_path)
+          source = source_for(file_path, sources)
           next unless source
 
           units.concat(class_analyzer.analyze(source: source, file_path: file_path))
@@ -73,12 +76,25 @@ module Woods
         files.uniq
       end
 
+      def source_for(file_path, sources)
+        return sources.fetch(file_path) if sources
+
+        read_file(file_path)
+      end
+
       # Read a file safely, returning nil on failure.
       #
+      # Ruby source defaults to UTF-8, so the read is pinned to UTF-8
+      # rather than the process default external encoding. Under LANG=C
+      # (US-ASCII) a bare File.read tags multibyte source, such as an em
+      # dash in a comment, as invalid and JSON generation raises
+      # Encoding::InvalidByteSequenceError out of the analysis.
+      #
       # @param path [String] File path
       # @return [String, nil] File contents or nil
       def read_file(path)
-        File.read(path)
+        content = File.read(path, encoding: Encoding::UTF_8)
+        content.valid_encoding? ? content : content.scrub
       rescue StandardError
         nil
       end

data/lib/woods/session_tracer/file_store.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'fileutils'
+require 'tempfile'
 require_relative 'store'
 
 module Woods
@@ -11,22 +12,34 @@ module Woods
     # 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.
+    # Bounded JSONL history replaced atomically under a cross-process file lock.
+    # 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
+    class FileStore < Store # rubocop:disable Metrics/ClassLength
+      DEFAULT_MAX_SESSIONS = 1_000
+      DEFAULT_MAX_REQUESTS = 1_000
+
       # @param base_dir [String] Directory for session JSONL files
-      def initialize(base_dir:)
+      def initialize(base_dir:, ttl: nil, max_sessions: DEFAULT_MAX_SESSIONS,
+                     max_requests_per_session: DEFAULT_MAX_REQUESTS, clock: -> { Time.now })
         super()
+        validate_limit!(:max_sessions, max_sessions)
+        validate_limit!(:max_requests_per_session, max_requests_per_session)
         @base_dir = base_dir
+        @ttl = ttl
+        @max_sessions = max_sessions
+        @max_requests_per_session = max_requests_per_session
+        @clock = clock
+        @mutex = Mutex.new
         FileUtils.mkdir_p(@base_dir)
       end
 
-      # Append a request record to a session's JSONL file.
+      # Add a request record to a bounded session JSONL history.
       #
       # Uses file locking (LOCK_EX) for concurrency safety.
       #
@@ -34,12 +47,22 @@ module Woods
       # @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)
+        with_store_lock do
+          path = migrate_legacy_session!(session_id)
+          # Explicit UTF-8 on every read in this file: the JSONL is written as
+          # raw UTF-8 bytes, so a bare read tags the lines with the process
+          # default external encoding and one non-ASCII request path (a
+          # localized route) breaks `record`'s history join, `read`,
+          # `sessions`, and the `session_trace` MCP tool under LANG=C (R1-1).
+          lines = if File.exist?(path)
+                    File.readlines(path, encoding: Encoding::UTF_8).last(@max_requests_per_session - 1)
+                  else
+                    []
+                  end
+          atomic_replace(path, (lines << line).join)
+          prune_sessions!
         end
       end
 
@@ -48,10 +71,18 @@ module Woods
       # @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)
+        lines = with_store_lock do
+          path = migrate_legacy_session!(session_id)
+          return [] unless File.exist?(path)
+
+          if expired?(path)
+            FileUtils.rm_f(path)
+            return []
+          end
 
-        File.readlines(path).filter_map do |line|
+          File.readlines(path, encoding: Encoding::UTF_8)
+        end
+        lines.filter_map do |line|
           stripped = line.strip
           next if stripped.empty?
 
@@ -66,11 +97,14 @@ module Woods
       # @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 = with_store_lock do
+          migrate_legacy_sessions!
+          prune_expired!
+          session_files.sort_by { |file| -File.mtime(file).to_f }.first(limit)
+        end
 
-        files.first(limit).map do |file|
-          session_id = File.basename(file, '.jsonl')
+        files.map do |file|
+          session_id = restore_session_id(File.basename(file, '.jsonl'))
           session_summary(session_id, read(session_id))
         end
       end
@@ -80,16 +114,17 @@ module Woods
       # @param session_id [String] The session identifier
       # @return [void]
       def clear(session_id)
-        path = session_path(session_id)
-        FileUtils.rm_f(path)
+        with_store_lock do
+          FileUtils.rm_f(session_path(session_id))
+          FileUtils.rm_f(legacy_session_path(session_id))
+        end
       end
 
       # Remove all session data.
       #
       # @return [void]
       def clear_all
-        pattern = File.join(@base_dir, '*.jsonl')
-        Dir.glob(pattern).each { |f| File.delete(f) }
+        with_store_lock { session_files.each { |file| File.delete(file) } }
       end
 
       private
@@ -99,6 +134,90 @@ module Woods
       def session_path(session_id)
         File.join(@base_dir, "#{sanitize_session_id(session_id)}.jsonl")
       end
+
+      def session_files
+        Dir.glob(File.join(@base_dir, '*.jsonl'))
+      end
+
+      def with_store_lock
+        @mutex.synchronize do
+          File.open(File.join(@base_dir, '.woods-session-store.lock'), File::RDWR | File::CREAT, 0o600) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          end
+        end
+      end
+
+      def legacy_session_path(session_id)
+        raw = session_id.to_s
+        return unless raw.match?(/\A[a-zA-Z0-9_-]+\z/)
+
+        File.join(@base_dir, "#{raw}.jsonl")
+      end
+
+      def migrate_legacy_session!(session_id)
+        target = session_path(session_id)
+        legacy = legacy_session_path(session_id)
+        return target unless legacy && File.exist?(legacy)
+
+        if File.exist?(target)
+          atomic_replace(target,
+                         File.read(legacy, encoding: Encoding::UTF_8) +
+                         File.read(target, encoding: Encoding::UTF_8))
+          FileUtils.rm_f(legacy)
+        else
+          File.rename(legacy, target)
+          fsync_parent
+        end
+        target
+      end
+
+      def migrate_legacy_sessions!
+        session_files.each do |path|
+          basename = File.basename(path, '.jsonl')
+          migrate_legacy_session!(basename) unless basename.start_with?('b64.')
+        end
+      end
+
+      def atomic_replace(path, content)
+        temp = Tempfile.new([".#{File.basename(path)}-", '.tmp'], @base_dir)
+        temp.chmod(0o600)
+        temp.write(content)
+        temp.flush
+        temp.fsync
+        temp.close
+        File.rename(temp.path, path)
+        fsync_parent
+      ensure
+        temp&.close
+        temp&.unlink
+      end
+
+      def fsync_parent
+        File.open(@base_dir, File::RDONLY, &:fsync)
+      rescue Errno::EINVAL, Errno::ENOTSUP, Errno::EISDIR
+        nil
+      end
+
+      def expired?(path)
+        @ttl && @clock.call >= File.mtime(path) + @ttl
+      end
+
+      def prune_expired!
+        session_files.each { |file| FileUtils.rm_f(file) if expired?(file) }
+      end
+
+      def prune_sessions!
+        prune_expired!
+        stale = session_files.sort_by { |file| -File.mtime(file).to_f }.drop(@max_sessions)
+        stale.each { |file| FileUtils.rm_f(file) }
+      end
+
+      def validate_limit!(name, value)
+        return if value.is_a?(Integer) && value.positive?
+
+        raise ArgumentError, "#{name} must be a positive Integer"
+      end
     end
   end
 end

data/lib/woods/session_tracer/middleware.rb

@@ -85,7 +85,7 @@ module Woods
       # @param env [Hash] Rack environment
       # @param status [Integer] HTTP response status
       # @param duration_ms [Integer] Request duration in milliseconds
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def record_request(env, status, duration_ms)
         path = env['PATH_INFO'] || ''
         return if excluded?(path)
@@ -116,7 +116,6 @@ module Woods
 
         @store.record(session_id, request_data)
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Extract session ID: X-Trace-Session header first, then session cookie, then fallback.
       #

data/lib/woods/session_tracer/redis_store.rb

@@ -1,14 +1,25 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'time'
 require_relative 'store'
 
+# Woods::SessionTracerError is defined in the entry point; required here so
+# this file can be loaded directly. Without it a narrow entry point (a custom
+# boot, a script) turned the documented "add `gem \"redis\"`" error into a
+# NameError naming a missing constant (INF-8).
+require 'woods'
+
 module Woods
   module SessionTracer
-    # Redis-backed session store using Lists.
+    # Redis-backed session store using Lists plus a recency ZSET.
     #
     # Each session is stored as a Redis List keyed `woods:session:{id}`.
-    # RPUSH per request for append-only ordering. Native TTL for automatic cleanup.
+    # RPUSH per request for append-only ordering. Native TTL for automatic
+    # cleanup. The `woods:sessions` index is a ZSET scored by each session's
+    # last request timestamp, so eviction touches O(log n) members instead
+    # of re-reading every session's history (audit P4). A legacy SET left by
+    # an earlier version is migrated on the first record.
     #
     # Requires the `redis` gem at runtime.
     #
@@ -18,11 +29,37 @@ module Woods
     #
     class RedisStore < Store
       KEY_PREFIX = 'woods:session:'
+      # Recency index: ZSET of session_id => last-request epoch. Was a SET
+      # before the zset migration; legacy deployments migrate through the
+      # atomic script below.
       SESSIONS_KEY = 'woods:sessions'
+      DEFAULT_MAX_SESSIONS = 1_000
+      DEFAULT_MAX_REQUESTS = 1_000
+
+      # Recency-index update for one record, executed server-side as one
+      # atomic step: type check, legacy SET transfer, insertion of the
+      # current member. Redis runs a script without interleaving, so two
+      # writers racing a legacy index can neither observe the SET with one
+      # writer and erase the other's members, nor fail with WRONGTYPE after
+      # the other converted; a writer arriving on an already-converted (or
+      # fresh) key takes the plain ZADD path of the same script.
+      INDEX_UPDATE_SCRIPT = <<~LUA
+        local kind = redis.call('TYPE', KEYS[1]).ok
+        if kind == 'set' then
+          local legacy = redis.call('SMEMBERS', KEYS[1])
+          redis.call('DEL', KEYS[1])
+          for _, member in ipairs(legacy) do
+            redis.call('ZADD', KEYS[1], 0, member)
+          end
+        end
+        redis.call('ZADD', KEYS[1], tonumber(ARGV[1]), ARGV[2])
+        return 1
+      LUA
 
       # @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)
+      def initialize(redis:, ttl: nil, max_sessions: DEFAULT_MAX_SESSIONS,
+                     max_requests_per_session: DEFAULT_MAX_REQUESTS)
         super()
         unless defined?(::Redis)
           raise SessionTracerError, 'The redis gem is required for RedisStore. Add `gem "redis"` to your Gemfile.'
@@ -30,6 +67,8 @@ module Woods
 
         @redis = redis
         @ttl = ttl
+        @max_sessions = max_sessions
+        @max_requests_per_session = max_requests_per_session
       end
 
       # Append a request record to a session's Redis List.
@@ -40,8 +79,10 @@ module Woods
       def record(session_id, request_data)
         key = session_key(session_id)
         @redis.rpush(key, JSON.generate(request_data))
+        @redis.ltrim(key, -@max_requests_per_session, -1)
         @redis.expire(key, @ttl) if @ttl
-        @redis.sadd(SESSIONS_KEY, session_id)
+        index_session(session_id, request_data)
+        prune_sessions(session_id)
       end
 
       # Read all request records for a session.
@@ -62,18 +103,28 @@ module Woods
       # @param limit [Integer] Maximum number of sessions to return
       # @return [Array<Hash>] Session summaries
       def sessions(limit: 20)
-        all_ids = @redis.smembers(SESSIONS_KEY)
+        all_ids = @redis.zrange(SESSIONS_KEY, 0, -1)
 
         # 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
+        # Remove expired session IDs from the index
         expired = all_ids - active
-        expired.each { |id| @redis.srem(SESSIONS_KEY, id) } if expired.any?
+        expired.each { |id| @redis.zrem(SESSIONS_KEY, id) } if expired.any?
 
-        active.first(limit).map do |session_id|
-          session_summary(session_id, read(session_id))
-        end
+        # Redis sorted sets order by score, but a summary's last_request is
+        # the payload timestamp of the session's last record — the same
+        # source the score is derived from. Ordering the built summaries by
+        # that field keeps the exact ordering contract (#218 / B-105) even
+        # where a clock crept between score and payload.
+        #
+        # This still reads every active session rather than `limit` of them,
+        # as before; the zset made *eviction* the O(log n) path.
+        active
+          .map { |session_id| session_summary(session_id, read(session_id)) }
+          .sort_by { |summary| recency_key(summary) }
+          .reverse
+          .first(limit)
       end
 
       # Remove all data for a single session.
@@ -82,14 +133,14 @@ module Woods
       # @return [void]
       def clear(session_id)
         @redis.del(session_key(session_id))
-        @redis.srem(SESSIONS_KEY, session_id)
+        @redis.zrem(SESSIONS_KEY, session_id)
       end
 
       # Remove all session data.
       #
       # @return [void]
       def clear_all
-        all_ids = @redis.smembers(SESSIONS_KEY)
+        all_ids = @redis.zrange(SESSIONS_KEY, 0, -1)
         all_ids.each { |id| @redis.del(session_key(id)) }
         @redis.del(SESSIONS_KEY)
       end
@@ -101,6 +152,65 @@ module Woods
       def session_key(session_id)
         "#{KEY_PREFIX}#{sanitize_session_id(session_id)}"
       end
+
+      # Record the session in the recency index, scored by the request's own
+      # timestamp so eviction order matches the last-request ordering
+      # {#sessions} reports. The whole update — a legacy SET migration
+      # included — runs as one atomic script (see {INDEX_UPDATE_SCRIPT}).
+      #
+      # @param session_id [String]
+      # @param request_data [Hash]
+      # @return [void]
+      def index_session(session_id, request_data)
+        @redis.eval(INDEX_UPDATE_SCRIPT, keys: [SESSIONS_KEY], argv: [recency_score(request_data), session_id])
+      end
+
+      # @param request_data [Hash]
+      # @return [Float] Request timestamp as an epoch, or write time
+      def recency_score(request_data)
+        timestamp = request_data['timestamp'] if request_data.is_a?(Hash)
+        timestamp.is_a?(String) ? Time.iso8601(timestamp).to_f : Time.now.to_f
+      rescue ArgumentError
+        Time.now.to_f
+      end
+
+      # Evict the oldest sessions once the recency index overflows
+      # `@max_sessions`.
+      #
+      # The ZSET is scored by last request timestamp (see {#index_session}),
+      # so the `overflow + 1` lowest-scoring members contain the oldest
+      # `overflow` sessions other than the one just recorded. That matches
+      # the FileStore twin's oldest-by-mtime eviction without reading any
+      # session's history — the pre-zset implementation re-read every
+      # candidate on every record once the cap was reached (audit P4).
+      #
+      # @param current_session_id [String] never evicted, even if oldest
+      # @return [void]
+      def prune_sessions(current_session_id)
+        overflow = @redis.zcard(SESSIONS_KEY) - @max_sessions
+        return unless overflow.positive?
+
+        victims = @redis.zrange(SESSIONS_KEY, 0, overflow)
+                        .reject { |id| id == current_session_id }
+                        .first(overflow)
+
+        victims.each do |id|
+          @redis.del(session_key(id))
+          @redis.zrem(SESSIONS_KEY, id)
+        end
+      end
+
+      # Sort key for {#sessions}: most recent request first.
+      #
+      # Timestamps are ISO-8601 strings, which sort correctly as strings. A
+      # session with no requests (all entries expired mid-read) sorts last
+      # rather than raising on a nil comparison.
+      #
+      # @param summary [Hash]
+      # @return [String]
+      def recency_key(summary)
+        summary['last_request'].to_s
+      end
     end
   end
 end