e11y 0.1.0 → 0.2.0

data/lib/e11y/adapters/audit_encrypted.rb

@@ -28,6 +28,8 @@ module E11y
     #
     # @see ADR-006 §4.0 Audit Trail Security
     # @see UC-012 Audit Trail
+    # rubocop:disable Metrics/ClassLength
+    # Audit adapter contains encryption/decryption logic as cohesive unit
     class AuditEncrypted < Base
       # AES-256-GCM cipher
       CIPHER = "aes-256-gcm"
@@ -125,6 +127,8 @@ module E11y
       #
       # @param encrypted [Hash] Encrypted data with nonce and tag
       # @return [Hash] Decrypted event data
+      # rubocop:disable Metrics/AbcSize
+      # Cryptographic operations require multiple steps for secure decryption
       def decrypt_event(encrypted)
         cipher = OpenSSL::Cipher.new(CIPHER)
         cipher.decrypt
@@ -137,6 +141,7 @@ module E11y
 
         JSON.parse(plaintext, symbolize_names: true)
       end
+      # rubocop:enable Metrics/AbcSize
 
       # Write encrypted data to storage
       #
@@ -185,7 +190,7 @@ module E11y
       #
       # @return [Boolean]
       def production?
-        defined?(Rails) && Rails.env.production?
+        defined?(::Rails) && ::Rails.env.production?
       end
 
       # Ensure storage directory exists
@@ -212,7 +217,7 @@ module E11y
       # @return [String] Encryption key
       def default_encryption_key
         key = ENV.fetch("E11Y_AUDIT_ENCRYPTION_KEY") do
-          if defined?(Rails) && Rails.env.production?
+          if defined?(::Rails) && ::Rails.env.production?
             raise E11y::Error, "E11Y_AUDIT_ENCRYPTION_KEY must be set in production"
           end
 
@@ -228,12 +233,13 @@ module E11y
       #
       # @return [String] Storage path
       def default_storage_path
-        if defined?(Rails)
-          Rails.root.join("log", "audit").to_s
+        if defined?(::Rails) && ::Rails.root
+          ::Rails.root.join("log", "audit").to_s
         else
           ::File.join(Dir.pwd, "log", "audit")
         end
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/e11y/adapters/base.rb

@@ -47,6 +47,8 @@ module E11y
     #   end
     #
     # @see ADR-004 Section 3.1 (Base Adapter Contract)
+    # rubocop:disable Metrics/ClassLength
+    # Base adapter is a foundational class with core adapter functionality
     class Base
       attr_reader :config
 
@@ -103,6 +105,8 @@ module E11y
       # @param event_data [Hash] Event payload
       # @return [Boolean] true on success
       # @raise [RetryExhaustedError, CircuitOpenError] if fail_on_error=true
+      # rubocop:disable Metrics/MethodLength
+      # Core reliability logic with retry and circuit breaker - should stay as cohesive unit
       def write_with_reliability(event_data)
         return write(event_data) unless @reliability_enabled
 
@@ -125,6 +129,7 @@ module E11y
           handle_reliability_error(event_data, e, :circuit_open)
         end
       end
+      # rubocop:enable Metrics/MethodLength
 
       # Write a batch of events (preferred for performance)
       #
@@ -301,6 +306,8 @@ module E11y
       #   def retriable_error?(error)
       #     super || error.is_a?(CustomTransientError)
       #   end
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # This method checks many different error types for retryability - splitting would reduce clarity
       def retriable_error?(error)
         # Network timeout errors
         return true if error.is_a?(Timeout::Error)
@@ -327,6 +334,7 @@ module E11y
 
         false
       end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
       # Calculate exponential backoff delay with jitter
       #
@@ -373,6 +381,8 @@ module E11y
       #   end
       #
       # @see ADR-004 Section 7.2 (Circuit Breaker)
+      # rubocop:disable Metrics/MethodLength
+      # Circuit breaker state machine logic should stay as cohesive unit
       def with_circuit_breaker(failure_threshold: 5, timeout: 60)
         init_circuit_breaker! unless @circuit_state
 
@@ -397,6 +407,7 @@ module E11y
           raise
         end
       end
+      # rubocop:enable Metrics/MethodLength
 
       # Initialize circuit breaker state
       #
@@ -487,6 +498,8 @@ module E11y
       # @raise [StandardError] Re-raises if fail_on_error=true
       #
       # @api private
+      # rubocop:disable Naming/PredicateMethod
+      # This is an action method (handle error), not a predicate (is error handled?)
       def handle_reliability_error(event_data, error, reason)
         # Save to DLQ if filter allows
         save_to_dlq_if_needed(event_data, error, reason)
@@ -503,6 +516,7 @@ module E11y
         # TODO: Track metric e11y.event.tracking_failed_silent
         false
       end
+      # rubocop:enable Naming/PredicateMethod
 
       # Save event to DLQ if filter allows.
       #
@@ -573,6 +587,7 @@ module E11y
         warn "[E11y] Self-monitoring error: #{e.message}"
       end
     end
+    # rubocop:enable Metrics/ClassLength
 
     # Circuit breaker open error
     class CircuitOpenError < Error; end

data/lib/e11y/adapters/file.rb

@@ -31,6 +31,8 @@ module E11y
     #     :file_logger,
     #     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
       # Default maximum file size before rotation (100MB)
       DEFAULT_MAX_SIZE = 100 * 1024 * 1024
@@ -191,7 +193,7 @@ module E11y
 
       # Perform actual file rotation
       def perform_rotation!
-        @file.close if @file
+        @file&.close
 
         timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
         rotated_path = "#{@path}.#{timestamp}"
@@ -220,5 +222,6 @@ module E11y
         warn "E11y File adapter compression error: #{e.message}"
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/e11y/adapters/in_memory.rb

@@ -80,6 +80,8 @@ module E11y
       #
       # @param event_data [Hash] Event payload
       # @return [Boolean] true on success
+      # rubocop:disable Naming/PredicateMethod
+      # This is an action method (write event), not a predicate (is written?)
       def write(event_data)
         @mutex.synchronize do
           @events << event_data
@@ -87,11 +89,14 @@ module E11y
         end
         true
       end
+      # rubocop:enable Naming/PredicateMethod
 
       # Write batch of events to memory
       #
       # @param events [Array<Hash>] Array of event payloads
       # @return [Boolean] true on success
+      # rubocop:disable Naming/PredicateMethod
+      # This is an action method (write batch), not a predicate (is written?)
       def write_batch(events)
         @mutex.synchronize do
           @events.concat(events)
@@ -100,6 +105,7 @@ module E11y
         end
         true
       end
+      # rubocop:enable Naming/PredicateMethod
 
       # Clear all stored events and batches
       #

data/lib/e11y/adapters/loki.rb

@@ -59,6 +59,8 @@ module E11y
     #
     # @see https://grafana.com/docs/loki/latest/api/#push-log-entries-to-loki
     # @see ADR-009 §8 (C04 Resolution - Universal Cardinality Protection)
+    # rubocop:disable Metrics/ClassLength
+    # Loki adapter contains HTTP client, batching, and Loki-specific formatting logic
     class Loki < Base
       # Default batch size (events)
       DEFAULT_BATCH_SIZE = 100
@@ -82,6 +84,8 @@ module E11y
       # @option config [String] :tenant_id (nil) Loki tenant ID (X-Scope-OrgID header)
       # @option config [Boolean] :enable_cardinality_protection (false) Enable cardinality protection for labels (C04)
       # @option config [Integer] :max_label_cardinality (100) Max unique values per label when protection enabled
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # Adapter initialization requires many instance variable assignments
       def initialize(config = {})
         @url = config[:url]
         @labels = config.fetch(:labels, {})
@@ -108,6 +112,7 @@ module E11y
 
         build_connection!
       end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       # Write a single event to buffer
       #
@@ -189,6 +194,8 @@ module E11y
       #
       # @see ADR-004 Section 7.1 (Retry Policy via gem-level middleware)
       # @see ADR-004 Section 6.1 (Connection pooling via HTTP client)
+      # rubocop:disable Metrics/MethodLength
+      # HTTP client configuration requires detailed retry and connection settings
       def build_connection!
         @connection = Faraday.new(url: @url) do |f|
           # Retry middleware (exponential backoff: 1s, 2s, 4s)
@@ -211,6 +218,7 @@ module E11y
           f.adapter Faraday.default_adapter
         end
       end
+      # rubocop:enable Metrics/MethodLength
 
       # Check if buffer should be flushed
       def flush_if_needed!
@@ -329,5 +337,6 @@ module E11y
         headers
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/e11y/adapters/otel_logs.rb

@@ -58,14 +58,16 @@ module E11y
     # @see ADR-007 for OpenTelemetry integration architecture
     # @see UC-008 for use cases
     class OTelLogs < Base
-      # E11y severity → OTel severity mapping
+      # E11y severity → OTel severity_number mapping
+      # See: https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber
+      # Severity numbers: TRACE=1, DEBUG=5, INFO=9, WARN=13, ERROR=17, FATAL=21
       SEVERITY_MAPPING = {
-        debug: OpenTelemetry::SDK::Logs::Severity::DEBUG,
-        info: OpenTelemetry::SDK::Logs::Severity::INFO,
-        success: OpenTelemetry::SDK::Logs::Severity::INFO, # OTel has no "success"
-        warn: OpenTelemetry::SDK::Logs::Severity::WARN,
-        error: OpenTelemetry::SDK::Logs::Severity::ERROR,
-        fatal: OpenTelemetry::SDK::Logs::Severity::FATAL
+        debug: 5,  # DEBUG
+        info: 9,   # INFO
+        success: 9, # INFO (OTel has no "success" level)
+        warn: 13,  # WARN
+        error: 17, # ERROR
+        fatal: 21  # FATAL
       }.freeze
 
       # Default baggage allowlist (safe keys that don't contain PII)
@@ -108,7 +110,7 @@ module E11y
       #
       # @return [Boolean] true if OTel SDK available and configured
       def healthy?
-        @logger_provider && @logger
+        !@logger_provider.nil? && !@logger.nil?
       end
 
       # Adapter capabilities
@@ -157,7 +159,7 @@ module E11y
       # @param severity [Symbol] E11y severity (:debug, :info, etc.)
       # @return [Integer] OTel severity number
       def map_severity(severity)
-        SEVERITY_MAPPING[severity] || OpenTelemetry::SDK::Logs::Severity::INFO
+        SEVERITY_MAPPING[severity] || 9 # Default to INFO
       end
 
       # Build OTel attributes from E11y payload

data/lib/e11y/adapters/sentry.rb

@@ -40,6 +40,8 @@ module E11y
     #   )
     #
     # @see https://docs.sentry.io/platforms/ruby/
+    # rubocop:disable Metrics/ClassLength
+    # Sentry adapter contains error transformation and context enrichment logic
     class Sentry < Base
       # Severity levels in order
       SEVERITY_LEVELS = %i[debug info success warn error fatal].freeze
@@ -153,6 +155,8 @@ module E11y
       # Send error to Sentry
       #
       # @param event_data [Hash] Event data
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # Sentry scope configuration requires multiple context enrichment steps
       def send_error_to_sentry(event_data)
         ::Sentry.with_scope do |scope|
           # Set tags
@@ -183,6 +187,7 @@ module E11y
           end
         end
       end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       # Send breadcrumb to Sentry
       #
@@ -215,6 +220,8 @@ module E11y
       #
       # @param severity [Symbol] E11y severity
       # @return [Symbol] Sentry level
+      # rubocop:disable Lint/DuplicateBranch
+      # Multiple severity levels intentionally map to :info (info, success, unknown)
       def sentry_level(severity)
         case severity
         when :debug then :debug
@@ -225,6 +232,8 @@ module E11y
         else :info
         end
       end
+      # rubocop:enable Lint/DuplicateBranch
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/e11y/adapters/yabeda.rb

@@ -44,23 +44,33 @@ module E11y
     #
     # @see ADR-002 Metrics & Yabeda Integration
     # @see UC-003 Pattern-Based Metrics
+    # rubocop:disable Metrics/ClassLength
+    # Yabeda adapter contains metrics registration and update logic as cohesive unit
     class Yabeda < Base
       # Initialize Yabeda adapter
       #
       # @param config [Hash] Configuration options
       # @option config [Integer] :cardinality_limit (1000) Max unique values per label per metric
       # @option config [Array<Symbol>] :forbidden_labels ([]) Additional labels to denylist
+      # @option config [Symbol] :overflow_strategy (:drop) Strategy on overflow - :drop, :alert, or :relabel
       # @option config [Boolean] :auto_register (true) Automatically register metrics from Registry
       def initialize(config = {})
         super
 
         @cardinality_protection = E11y::Metrics::CardinalityProtection.new(
           cardinality_limit: config.fetch(:cardinality_limit, 1000),
-          forbidden_labels: config.fetch(:forbidden_labels, [])
+          additional_denylist: config.fetch(:forbidden_labels, []),
+          overflow_strategy: config.fetch(:overflow_strategy, :drop)
         )
 
         # Auto-register metrics from Registry
-        register_metrics_from_registry! if config.fetch(:auto_register, true)
+        return unless config.fetch(:auto_register, true)
+
+        register_metrics_from_registry!
+
+        # Apply configuration in non-Rails environments (Rails does this automatically)
+        # In tests, Yabeda.configure! should be called explicitly in before blocks
+        apply_yabeda_configuration!
       end
 
       # Write a single event to Yabeda
@@ -144,7 +154,7 @@ module E11y
         # Update Yabeda metric
         ::Yabeda.e11y.send(name).increment(safe_labels, by: value)
       rescue StandardError => e
-        E11y.logger.warn("Failed to increment Yabeda metric #{name}: #{e.message}", error: e.class.name)
+        E11y.logger.warn("Failed to increment Yabeda metric #{name}: #{e.message}")
       end
 
       # Track a histogram metric (for E11y::Metrics facade).
@@ -164,9 +174,9 @@ module E11y
         register_metric_if_needed(name, :histogram, safe_labels.keys, buckets: buckets)
 
         # Update Yabeda metric
-        ::Yabeda.e11y.send(name).observe(value, safe_labels)
+        ::Yabeda.e11y.send(name).measure(safe_labels, value)
       rescue StandardError => e
-        E11y.logger.warn("Failed to observe Yabeda histogram #{name}: #{e.message}", error: e.class.name)
+        E11y.logger.warn("Failed to observe Yabeda histogram #{name}: #{e.message}")
       end
 
       # Track a gauge metric (for E11y::Metrics facade).
@@ -185,9 +195,9 @@ module E11y
         register_metric_if_needed(name, :gauge, safe_labels.keys)
 
         # Update Yabeda metric
-        ::Yabeda.e11y.send(name).set(value, safe_labels)
+        ::Yabeda.e11y.send(name).set(safe_labels, value)
       rescue StandardError => e
-        E11y.logger.warn("Failed to set Yabeda gauge #{name}: #{e.message}", error: e.class.name)
+        E11y.logger.warn("Failed to set Yabeda gauge #{name}: #{e.message}")
       end
 
       # Validate configuration
@@ -232,6 +242,27 @@ module E11y
 
       private
 
+      # Apply Yabeda configuration (smart detection of environment)
+      #
+      # In Rails environments, configuration is applied automatically via Railtie.
+      # In non-Rails environments (e.g., Sinatra, standalone Ruby), we apply it here.
+      # In test environments, configuration should be applied explicitly in test setup.
+      #
+      # @return [void]
+      # @api private
+      def apply_yabeda_configuration!
+        # Don't auto-apply in Rails - Rails will call configure! via Railtie
+        return if defined?(::Rails)
+
+        # Don't auto-apply if already configured
+        return if ::Yabeda.configured?
+
+        # Apply configuration (non-Rails environments only)
+        ::Yabeda.configure!
+      rescue StandardError => e
+        E11y.logger.debug("Could not apply Yabeda configuration: #{e.message}")
+      end
+
       # Register metrics from Registry into Yabeda
       #
       # This is called during initialization if auto_register is true.
@@ -251,6 +282,8 @@ module E11y
       #
       # @param metric_config [Hash] Metric configuration from Registry
       # @return [void]
+      # rubocop:disable Metrics/MethodLength
+      # Metric registration requires case/when for different metric types
       def register_yabeda_metric(metric_config)
         metric_name = metric_config[:name]
         metric_type = metric_config[:type]
@@ -276,6 +309,7 @@ module E11y
         # Metric might already be registered - that's OK
         warn "E11y Yabeda: Could not register metric #{metric_name}: #{e.message}"
       end
+      # rubocop:enable Metrics/MethodLength
 
       # Register a metric if it doesn't exist yet (for direct metric calls).
       #
@@ -285,6 +319,8 @@ module E11y
       # @param buckets [Array<Numeric>, nil] Optional histogram buckets
       # @return [void]
       # @api private
+      # rubocop:disable Metrics/MethodLength
+      # Metric registration requires case/when for different metric types
       def register_metric_if_needed(name, type, tags, buckets: nil)
         # Check if metric already exists
         return if ::Yabeda.metrics.key?(:"e11y_#{name}")
@@ -304,16 +340,22 @@ module E11y
             end
           end
         end
+
+        # Apply configuration for runtime-registered metrics (non-Rails environments)
+        apply_yabeda_configuration!
       rescue StandardError => e
         # Metric might already be registered - that's OK
-        E11y.logger.debug("Could not register Yabeda metric #{name}: #{e.message}")
+        E11y.logger.warn("Could not register Yabeda metric #{name}: #{e.message}")
       end
+      # rubocop:enable Metrics/MethodLength
 
       # Update a single metric based on event data
       #
       # @param metric_config [Hash] Metric configuration
       # @param event_data [Hash] Event data
       # @return [void]
+      # rubocop:disable Metrics/AbcSize
+      # Metric update requires multiple steps for label extraction and value handling
       def update_metric(metric_config, event_data)
         metric_name = metric_config[:name]
         labels = extract_labels(metric_config, event_data)
@@ -329,13 +371,14 @@ module E11y
         when :counter
           ::Yabeda.e11y.send(metric_name).increment(safe_labels)
         when :histogram
-          ::Yabeda.e11y.send(metric_name).observe(value, safe_labels)
+          ::Yabeda.e11y.send(metric_name).measure(safe_labels, value)
         when :gauge
-          ::Yabeda.e11y.send(metric_name).set(value, safe_labels)
+          ::Yabeda.e11y.send(metric_name).set(safe_labels, value)
         end
       rescue StandardError => e
         warn "E11y Yabeda: Error updating metric #{metric_name}: #{e.message}"
       end
+      # rubocop:enable Metrics/AbcSize
 
       # Extract labels from event data
       #
@@ -366,5 +409,6 @@ module E11y
         end
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/e11y/buffers.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
-# E11y::Buffers module - Event buffering implementations
-#
-# This module contains buffer implementations for high-throughput event storage:
-# - RingBuffer: Lock-free SPSC ring buffer (100K+ events/sec)
-# - AdaptiveBuffer: Memory-aware buffer with backpressure (Phase 1.2.2)
-#
-# @see E11y::Buffers::RingBuffer
-# @see ADR-001 §3.3 (Buffer Architecture)
 module E11y
+  # Event buffering implementations
+  #
+  # This module contains buffer implementations for high-throughput event storage:
+  # - RingBuffer: Lock-free SPSC ring buffer (100K+ events/sec)
+  # - AdaptiveBuffer: Memory-aware buffer with backpressure (Phase 1.2.2)
+  #
+  # @see E11y::Buffers::RingBuffer
+  # @see ADR-001 §3.3 (Buffer Architecture)
   module Buffers
   end
 end

data/lib/e11y/console.rb

@@ -27,75 +27,67 @@ module E11y
     # Define helper methods on E11y module
     # @return [void]
     def self.define_helper_methods
-      E11y.singleton_class.class_eval do
-        # Show E11y statistics
-        # @return [Hash] Statistics hash
-        def stats
+      E11y.extend(ConsoleHelpers)
+    end
+
+    # Console helper methods module
+    module ConsoleHelpers
+      # Show E11y statistics
+      def stats
+        {
+          enabled: config.enabled,
+          environment: config.environment,
+          service_name: config.service_name,
+          adapters: adapters_info,
+          buffer: buffer_info
+        }
+      end
+
+      # Track a test event
+      def test_event
+        puts "✅ E11y test event would be tracked here"
+        puts "   (Waiting for Events::Console::Test implementation)"
+      end
+
+      # List all registered event classes
+      def events
+        puts "📋 E11y events list"
+        puts "   (Waiting for Event registry implementation)"
+        []
+      end
+
+      # List all registered adapters
+      def adapters
+        Adapters::Registry.all.map do |adapter|
           {
-            enabled: E11y.config.enabled,
-            environment: E11y.config.environment,
-            service_name: E11y.config.service_name,
-            adapters: E11y::Adapters::Registry.all.map do |a|
-              {
-                name: a.name,
-                class: a.class.name,
-                healthy: a.healthy?
-              }
-            end,
-            buffer: {
-              size: buffer_size,
-              max_size: E11y.config.buffer&.max_size
-            }
+            name: adapter.name,
+            class: adapter.class.name,
+            healthy: adapter.healthy?,
+            capabilities: adapter.capabilities
           }
         end
+      end
 
-        # Track a test event
-        # @return [void]
-        def test_event
-          # TODO: Implement test event tracking
-          # For now, just print a message
-          puts "✅ E11y test event would be tracked here"
-          puts "   (Waiting for Events::Console::Test implementation)"
-        end
-
-        # List all registered event classes
-        # @return [Array<String>] Event class names
-        def events
-          # TODO: Implement event registry
-          puts "📋 E11y events list"
-          puts "   (Waiting for Event registry implementation)"
-          []
-        end
+      # Reset buffers
+      def reset!
+        puts "✅ E11y buffers would be cleared here"
+        puts "   (Waiting for Buffer#clear! implementation)"
+      end
 
-        # List all registered adapters
-        # @return [Array<Hash>] Adapter details
-        def adapters
-          E11y::Adapters::Registry.all.map do |adapter|
-            {
-              name: adapter.name,
-              class: adapter.class.name,
-              healthy: adapter.healthy?,
-              capabilities: adapter.capabilities
-            }
-          end
-        end
+      private
 
-        # Reset buffers (clear all buffered events)
-        # @return [void]
-        def reset!
-          # TODO: Implement buffer clearing
-          puts "✅ E11y buffers would be cleared here"
-          puts "   (Waiting for Buffer#clear! implementation)"
+      def adapters_info
+        Adapters::Registry.all.map do |a|
+          { name: a.name, class: a.class.name, healthy: a.healthy? }
         end
+      end
 
-        private
+      def buffer_info
+        { size: buffer_size }
+      end
 
-        # Get current buffer size
-        # @return [Integer] Number of buffered events
-        def buffer_size
-          # TODO: Implement buffer size tracking
-          0
-        end
+      def buffer_size
+        0 # TODO: Implement buffer size tracking
       end
     end