e11y 0.2.0 → 1.0.0

data/lib/e11y/adapters/dev_log/file_store.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "zlib"
+require "fileutils"
+
+module E11y
+  module Adapters
+    class DevLog
+      # Handles JSONL file I/O with thread-safe append and numbered gzip rotation.
+      #
+      # Current file is always plain text for fast appends.
+      # Rotated files are gzip-compressed to save disk space.
+      # Rotation is triggered synchronously on the write that crosses the threshold.
+      class FileStore
+        DEFAULT_MAX_SIZE = 50 * 1024 * 1024 # 50 MB
+        DEFAULT_MAX_LINES     = 10_000
+        DEFAULT_KEEP_ROTATED  = 5
+
+        attr_reader :path
+
+        def initialize(path:,
+                       max_size: DEFAULT_MAX_SIZE,
+                       max_lines: DEFAULT_MAX_LINES,
+                       keep_rotated: DEFAULT_KEEP_ROTATED)
+          @path         = path.to_s
+          @max_size     = max_size
+          @max_lines    = max_lines
+          @keep_rotated = keep_rotated
+          @mutex        = Mutex.new
+          @line_count   = nil
+          @dir_ensured  = false
+        end
+
+        # Append a JSON line to the log file. Thread-safe.
+        def append(json_line)
+          @mutex.synchronize do
+            ensure_dir!
+            # Warm the line count before writing so the post-write increment is accurate.
+            # If @line_count is nil (cold start or after clear!), scan the file now.
+            warm_count = @line_count || count_lines
+            ::File.open(@path, "a") do |f|
+              f.flock(::File::LOCK_EX)
+              begin
+                f.write("#{json_line}\n")
+              ensure
+                f.flock(::File::LOCK_UN)
+              end
+            end
+            @line_count = warm_count + 1
+            rotate_if_needed!
+          end
+        end
+
+        # Remove log file, rotated archives, and reset state.
+        def clear!
+          @mutex.synchronize do
+            ::FileUtils.rm_f(@path)
+            ::Dir.glob("#{@path}.*.gz").each { |f| ::FileUtils.rm_f(f) }
+            @line_count = nil
+            @dir_ensured = false
+          end
+        end
+
+        # Current file size in bytes (0 if file does not exist).
+        def file_size
+          ::File.size(@path)
+        rescue Errno::ENOENT
+          0
+        end
+
+        # Number of lines in current file.
+        def line_count
+          @mutex.synchronize { @line_count || count_lines }
+        end
+
+        private
+
+        def ensure_dir!
+          return if @dir_ensured
+
+          ::FileUtils.mkdir_p(::File.dirname(@path))
+          @dir_ensured = true
+        end
+
+        def rotate_if_needed!
+          return unless should_rotate?
+
+          rotate!
+          @line_count = nil
+        end
+
+        def should_rotate?
+          file_size > @max_size ||
+            (@line_count && @line_count > @max_lines)
+        end
+
+        def rotate!
+          shift_rotated_files!
+          compress_current_file!
+        end
+
+        def shift_rotated_files!
+          @keep_rotated.downto(1) do |n|
+            src = rotated_path(n)
+            next unless ::File.exist?(src)
+
+            if n + 1 > @keep_rotated
+              ::FileUtils.rm_f(src)
+            else
+              ::File.rename(src, rotated_path(n + 1))
+            end
+          end
+        end
+
+        def compress_current_file!
+          return unless ::File.exist?(@path)
+
+          tmp_path = "#{rotated_path(1)}.tmp"
+          begin
+            ::Zlib::GzipWriter.open(tmp_path) do |gz|
+              ::File.open(@path, "rb") { |f| ::IO.copy_stream(f, gz) }
+            end
+            ::File.rename(tmp_path, rotated_path(1))
+          ensure
+            ::FileUtils.rm_f(tmp_path)
+          end
+          # Truncate rather than delete so the file always exists after rotation
+          ::File.open(@path, "w") { |f| f.truncate(0) }
+        end
+
+        def rotated_path(num)
+          "#{@path}.#{num}.gz"
+        end
+
+        def count_lines
+          return 0 unless ::File.exist?(@path)
+
+          ::File.foreach(@path).count
+        end
+      end
+    end
+  end
+end

data/lib/e11y/adapters/dev_log/query.rb

@@ -0,0 +1,219 @@
+# lib/e11y/adapters/dev_log/query.rb
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "fileutils"
+
+module E11y
+  module Adapters
+    class DevLog
+      # Read-only query interface for the JSONL dev log.
+      #
+      # Used by TUI, Browser Overlay, and MCP Server.
+      #
+      # Performance strategy:
+      #   - In-memory cache invalidated by File.mtime
+      #   - JSON parser: oj if available, stdlib JSON as fallback
+      # rubocop:disable Metrics/ClassLength
+      class Query
+        # Value object returned by #interactions
+        Interaction = Struct.new(:started_at, :trace_ids, :has_error?, :source) do
+          def traces_count = trace_ids.size
+        end
+
+        ERROR_SEVERITIES = %w[error fatal].freeze
+
+        # Choose fastest available JSON parser
+        JSON_LOAD = if defined?(Oj)
+                      ->(str) { Oj.load(str) }
+                    else
+                      ->(str) { ::JSON.parse(str) }
+                    end
+
+        def initialize(path)
+          @path        = path.to_s
+          @cache       = nil
+          @cache_mtime = nil
+        end
+
+        # Return last +limit+ events, newest-first.
+        def stored_events(limit: 1000, severity: nil, source: nil)
+          events = all_events
+          events = events.select { |e| e["severity"] == severity } if severity
+          events = events.select { |e| e.dig("metadata", "source") == source } if source
+          events.last(limit).reverse
+        end
+
+        # Find event by id (returns nil if not found).
+        def find_event(id)
+          all_events.find { |e| e["id"] == id }
+        end
+
+        # Full-text search in event_name and payload JSON.
+        def search(query_str, limit: 500)
+          q = query_str.downcase
+          all_events.select do |e|
+            e["event_name"].to_s.downcase.include?(q) ||
+              ::JSON.generate(e["payload"] || {}).downcase.include?(q)
+          end.last(limit).reverse
+        end
+
+        # All events for a given trace_id in chronological order.
+        def events_by_trace(trace_id)
+          all_events.select { |e| e["trace_id"] == trace_id }
+        end
+
+        # Aggregate stats about the log.
+        def stats
+          events = all_events
+          {
+            total_events: events.size,
+            file_size: file_size,
+            by_severity: events.group_by { |e| e["severity"] }.transform_values(&:count),
+            by_event_name: events.group_by { |e| e["event_name"] }.transform_values(&:count),
+            oldest_event: events.first&.dig("timestamp"),
+            newest_event: events.last&.dig("timestamp")
+          }
+        end
+
+        # True if log file was modified after +timestamp+.
+        def updated_since?(timestamp)
+          return false unless ::File.exist?(@path)
+
+          ::File.mtime(@path) > timestamp
+        end
+
+        # Remove the log file and invalidate cache.
+        def clear!
+          ::FileUtils.rm_f(@path)
+          invalidate_cache!
+        end
+
+        # Group traces into time-window interaction bands.
+        # Returns Array<Interaction> sorted chronologically.
+        def interactions(window_ms: 500, limit: 50, source: nil)
+          events = all_events
+          events = events.select { |e| e.dig("metadata", "source") == source } if source
+
+          trace_map = build_trace_map(events)
+          return [] if trace_map.empty?
+
+          build_interaction_groups(trace_map, window_ms: window_ms, limit: limit)
+        end
+
+        private
+
+        # --- interactions helpers ---
+
+        def build_trace_map(events)
+          trace_map = {}
+          events.each { |e| merge_trace_entry(trace_map, e) }
+          trace_map
+        end
+
+        def merge_trace_entry(trace_map, event)
+          tid = event["trace_id"]
+          return unless tid
+
+          started = parse_started_at(event)
+          return unless started
+
+          entry = trace_map[tid] ||= { started_at: started, has_error: false,
+                                       source: event.dig("metadata", "source") }
+          entry[:has_error] = true if ERROR_SEVERITIES.include?(event["severity"])
+          entry[:started_at] = started if started < entry[:started_at]
+        end
+
+        def build_interaction_groups(trace_map, window_ms:, limit:)
+          sorted = trace_map.sort_by { |_, v| v[:started_at] }
+          groups = []
+          current = nil
+
+          sorted.each do |trace_id, meta|
+            current = append_to_groups(groups, current, trace_id, meta, window_ms)
+          end
+
+          groups.last(limit).map { |grp| interaction_struct(grp) }
+        end
+
+        def append_to_groups(groups, current, trace_id, meta, window_ms)
+          if current.nil? || new_window?(current, meta, window_ms)
+            current = { started_at: meta[:started_at], last_started_at: meta[:started_at],
+                        trace_ids: [], has_error: false, source: meta[:source] }
+            groups << current
+          end
+          current[:trace_ids] << trace_id
+          current[:has_error] ||= meta[:has_error]
+          current[:last_started_at] = meta[:started_at]
+          current
+        end
+
+        def new_window?(current, meta, window_ms)
+          (meta[:started_at] - current[:last_started_at]) * 1000 > window_ms
+        end
+
+        def interaction_struct(grp)
+          Interaction.new(grp[:started_at], grp[:trace_ids], grp[:has_error], grp[:source])
+        end
+
+        # --- cache helpers ---
+
+        def all_events
+          return @cache if cache_valid?
+
+          @cache       = load_events
+          @cache_mtime = current_mtime
+          @cache
+        end
+
+        def cache_valid?
+          return false unless @cache && @cache_mtime
+          return false unless ::File.exist?(@path)
+
+          current_mtime == @cache_mtime
+        end
+
+        def current_mtime
+          ::File.mtime(@path)
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def invalidate_cache!
+          @cache       = nil
+          @cache_mtime = nil
+        end
+
+        def load_events
+          return [] unless ::File.exist?(@path)
+
+          events = []
+          ::File.foreach(@path) do |line|
+            line = line.chomp
+            next if line.empty?
+
+            events << JSON_LOAD.call(line)
+          rescue ::JSON::ParserError
+            next
+          end
+          events
+        end
+
+        def file_size
+          ::File.size(@path)
+        rescue Errno::ENOENT
+          0
+        end
+
+        def parse_started_at(event)
+          ts = event.dig("metadata", "started_at") || event["timestamp"]
+          ::Time.parse(ts)
+        rescue ArgumentError, TypeError
+          nil
+        end
+      end
+      # rubocop:enable Metrics/ClassLength
+    end
+  end
+end

data/lib/e11y/adapters/dev_log.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module E11y
+  module Adapters
+    # Development-only adapter that stores events in a local JSONL file
+    # and exposes a rich read API for TUI, Browser Overlay, and MCP Server.
+    #
+    # Auto-registered by Railtie in development/test environments.
+    # Do not use in production.
+    #
+    # @example Manual setup
+    #   adapter = E11y::Adapters::DevLog.new(
+    #     path: Rails.root.join("log", "e11y_dev.jsonl"),
+    #     max_size: 50.megabytes,
+    #     keep_rotated: 5
+    #   )
+    class DevLog < Base
+      # @param path           [String, Pathname]
+      # @param max_size       [Integer]  Rotation threshold in bytes (default 50 MB)
+      # @param max_lines      [Integer]  Rotation threshold in line count (default 10_000)
+      # @param keep_rotated   [Integer]  Number of .N.gz files to retain (default 5)
+      # @param enable_watcher [Boolean]  Reserved for future file-watcher integration
+      def initialize(path: "log/e11y_dev.jsonl",
+                     max_size: FileStore::DEFAULT_MAX_SIZE,
+                     max_lines: FileStore::DEFAULT_MAX_LINES,
+                     keep_rotated: FileStore::DEFAULT_KEEP_ROTATED,
+                     enable_watcher: false)
+        super({})
+        @store          = FileStore.new(path: path, max_size: max_size,
+                                        max_lines: max_lines, keep_rotated: keep_rotated)
+        @query          = Query.new(@store.path)
+        @enable_watcher = enable_watcher
+      end
+
+      # Write a single event to the JSONL file.
+      #
+      # @param event_data [Hash] Event from the E11y pipeline
+      # @return [Boolean] true on success, false on error
+      def write(event_data)
+        @store.append(serialize(event_data))
+        true
+      rescue StandardError => e
+        warn "[E11y::DevLog] write failed: #{e.message}"
+        false
+      end
+
+      # --- Read API (delegated to Query) ---
+
+      # @see Query#stored_events
+      def stored_events(limit: 1000, severity: nil, source: nil)
+        @query.stored_events(limit: limit, severity: severity, source: source)
+      end
+
+      # @see Query#find_event
+      def find_event(id) = @query.find_event(id)
+
+      # @see Query#search
+      def search(query_str, limit: 500) = @query.search(query_str, limit: limit)
+
+      # @see Query#events_by_name
+      def events_by_name(name, limit: 500)
+        @query.stored_events(limit: limit).select { |e| e["event_name"] == name }
+      end
+
+      # @see Query#events_by_severity
+      def events_by_severity(sev, limit: 500)
+        @query.stored_events(limit: limit, severity: sev)
+      end
+
+      # @see Query#events_by_trace
+      def events_by_trace(trace_id) = @query.events_by_trace(trace_id)
+
+      # @see Query#interactions
+      def interactions(window_ms: 500, limit: 50, source: nil)
+        @query.interactions(window_ms: window_ms, limit: limit, source: source)
+      end
+
+      # @see Query#stats
+      def stats = @query.stats
+
+      # @see Query#updated_since?
+      def updated_since?(timestamp) = @query.updated_since?(timestamp)
+
+      # @see Query#clear!
+      def clear! = @query.clear!
+
+      # Advertise dev_log and readable capabilities.
+      def capabilities
+        super.merge(dev_log: true, readable: true)
+      end
+
+      private
+
+      def serialize(event_data)
+        data = event_data.is_a?(::Hash) ? event_data.transform_keys(&:to_s) : {}
+        enrich_ids!(data)
+        enrich_metadata!(data)
+        ::JSON.generate(data)
+      end
+
+      def enrich_ids!(data)
+        data["id"]        ||= ::SecureRandom.uuid
+        data["timestamp"] ||= ::Time.now.utc.iso8601(3)
+      end
+
+      def enrich_metadata!(data)
+        source = ::Thread.current[:e11y_source] || "web"
+        meta   = (data["metadata"] || {}).dup
+        meta["source"]     ||= source
+        meta["started_at"] ||= data["timestamp"]
+        data["metadata"] = meta
+      end
+    end
+  end
+end

data/lib/e11y/adapters/file.rb

@@ -26,11 +26,8 @@ module E11y
     #
     #   adapter.write(event_name: "user.login", severity: :info)
     #
-    # @example With Registry
-    #   E11y::Adapters::Registry.register(
-    #     :file_logger,
-    #     E11y::Adapters::File.new(path: "log/events.log")
-    #   )
+    # @example Configuration
+    #   config.adapters[:file] = E11y::Adapters::File.new(path: "log/events.log")
     # rubocop:disable Metrics/ClassLength
     # File adapter contains file rotation and buffering logic as cohesive unit
     class File < Base
@@ -152,7 +149,7 @@ module E11y
 
       # Open file for writing
       def open_file!
-        @file = ::File.open(@path, "a")
+        @file = ::File.open(@path, "a") # rubocop:disable Style/FileOpen -- intentional: adapter keeps file handle open for lifecycle of adapter
         @file.sync = true
         @current_date = Date.today if @rotation == :daily
       end

data/lib/e11y/adapters/in_memory.rb

@@ -39,6 +39,7 @@ module E11y
     #   test_adapter = E11y::Adapters::InMemory.new(max_events: nil)
     #
     # @see ADR-004 §9.1 (In-Memory Test Adapter)
+    # rubocop:disable Metrics/ClassLength
     class InMemory < Base
       # Default maximum number of events to store
       DEFAULT_MAX_EVENTS = 1000
@@ -118,17 +119,28 @@ module E11y
         end
       end
 
+      alias clear clear!
+
       # Find events matching pattern
       #
-      # @param pattern [String, Regexp] Pattern to match against event_name
+      # @param pattern [String, Regexp, Class] Event name pattern or event class
       # @return [Array<Hash>] Matching events
       #
       # @example
       #   adapter.find_events(/order/)  # All order.* events
       #   adapter.find_events("order.paid")  # Exact match
+      #   adapter.find_events(Events::OrderPaid)  # By event class
       def find_events(pattern)
-        pattern = Regexp.new(Regexp.escape(pattern)) if pattern.is_a?(String)
-        @events.select { |event| event[:event_name].to_s.match?(pattern) }
+        pattern = event_pattern_for(pattern)
+        @events.select { |event| event_matches?(event, pattern) }
+      end
+
+      # Find first event matching pattern
+      #
+      # @param pattern [String, Regexp, Class] Event name pattern or event class
+      # @return [Hash, nil] First matching event or nil
+      def find_event(pattern)
+        find_events(pattern).first
       end
 
       # Count events by name
@@ -138,8 +150,10 @@ module E11y
       #
       # @example
       #   adapter.event_count  # Total events
-      #   adapter.event_count("order.paid")  # Specific event count
-      def event_count(event_name: nil)
+      #   adapter.event_count("order.paid")  # Specific event count (positional)
+      #   adapter.event_count(event_name: "order.paid")  # Specific event count (keyword)
+      def event_count(event_name = nil, **kwargs)
+        event_name ||= kwargs[:event_name]
         if event_name
           @events.count { |event| event[:event_name] == event_name }
         else
@@ -147,6 +161,16 @@ module E11y
         end
       end
 
+      # Get the most recently written event.
+      #
+      # @return [Hash, nil] The last event, or nil if none
+      #
+      # @example
+      #   adapter.last_event  # Most recently written event
+      def last_event
+        events.last
+      end
+
       # Get last N events
       #
       # @param count [Integer] Number of events to return
@@ -205,6 +229,28 @@ module E11y
 
       private
 
+      def event_pattern_for(pattern)
+        case pattern
+        when Class then pattern
+        when String, Regexp then pattern.is_a?(String) ? Regexp.new(Regexp.escape(pattern)) : pattern
+        else raise ArgumentError, "Pattern must be Class, String, or Regexp, got #{pattern.class}"
+        end
+      end
+
+      def event_matches?(event, pattern)
+        return event[:event_name].to_s.match?(pattern) if pattern.is_a?(Regexp)
+        return event_matches_class?(event, pattern) if pattern.is_a?(Class)
+
+        false
+      end
+
+      def event_matches_class?(event, klass)
+        event[:event_class] == klass ||
+          event[:event_class]&.name == klass.name ||
+          event[:event_name].to_s == (klass.respond_to?(:event_name) ? klass.event_name : klass.name) ||
+          event[:event_name].to_s.include?(klass.name)
+      end
+
       # Enforce max_events limit by dropping oldest events (FIFO)
       #
       # @return [void]
@@ -218,5 +264,6 @@ module E11y
         @dropped_count += excess
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/e11y/adapters/in_memory_test.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "in_memory"
+
+module E11y
+  module Adapters
+    # InMemoryTest Adapter — extends InMemory with test-specific helpers.
+    #
+    # Overrides `last_event` to skip Rails auto-instrumentation events
+    # (E11y::Events::Rails::*) that fire after each HTTP request and
+    # would otherwise obscure the event your test just tracked.
+    #
+    # Use this adapter in test suites; use `InMemory` in production configs.
+    #
+    # @example
+    #   let(:adapter) { E11y::Adapters::InMemoryTest.new }
+    #   before { E11y.register_adapter :memory, adapter }
+    class InMemoryTest < InMemory
+      # Return the last event that was NOT fired by Rails auto-instrumentation.
+      #
+      # @return [Hash, nil]
+      def last_event
+        events.reverse_each.find do |e|
+          !e[:event_name].to_s.start_with?("E11y::Events::Rails::")
+        end
+      end
+    end
+  end
+end