tasker-engine 1.0.0

data/lib/tasker/registry/statistics_collector.rb

@@ -0,0 +1,381 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative '../concerns/structured_logging'
+
+module Tasker
+  module Registry
+    # Comprehensive statistics collection for all registry systems
+    #
+    # Provides unified observability, performance monitoring, and
+    # health checking across all registry components.
+    class StatisticsCollector
+      include Tasker::Concerns::StructuredLogging
+
+      class << self
+        # Collect comprehensive statistics from all registries
+        #
+        # @return [Hash] Complete statistics for all registries
+        def collect_all_registry_stats
+          registries = discover_all_registries
+
+          stats = {
+            collection_timestamp: Time.current,
+            total_registries: registries.size,
+            registries: {}
+          }
+
+          registries.each do |registry|
+            registry_stats = collect_registry_stats(registry)
+            stats[:registries][registry_stats[:registry_name]] = registry_stats
+          end
+
+          # Calculate aggregated metrics
+          stats[:aggregated] = calculate_aggregated_metrics(stats[:registries])
+
+          stats
+        end
+
+        # Collect statistics from a specific registry
+        #
+        # @param registry [BaseRegistry] Registry to collect stats from
+        # @return [Hash] Registry statistics with performance metrics
+        def collect_registry_stats(registry)
+          base_stats = registry.stats
+          health_check = registry.health_check
+
+          {
+            **base_stats,
+            health: health_check,
+            performance: measure_registry_performance(registry),
+            usage_patterns: analyze_usage_patterns(registry),
+            recommendations: generate_recommendations(registry)
+          }
+        end
+
+        # Get health status for all registries
+        #
+        # @return [Hash] Health status summary
+        def health_summary
+          registries = discover_all_registries
+
+          health_results = registries.map do |registry|
+            {
+              registry_name: registry.class.name.demodulize.underscore,
+              healthy: registry.healthy?,
+              health_details: registry.health_check
+            }
+          end
+
+          {
+            overall_healthy: health_results.all? { |result| result[:healthy] },
+            registry_count: registries.size,
+            healthy_registries: health_results.count { |result| result[:healthy] },
+            unhealthy_registries: health_results.reject { |result| result[:healthy] },
+            registries: health_results,
+            checked_at: Time.current
+          }
+        end
+
+        # Find registries matching criteria
+        #
+        # @param criteria [Hash] Search criteria
+        # @option criteria [String] :name_pattern Registry name pattern
+        # @option criteria [Symbol] :health_status Health status filter (:healthy, :unhealthy)
+        # @option criteria [Integer] :min_items Minimum item count
+        # @return [Array<BaseRegistry>] Matching registries
+        def find_registries(criteria = {})
+          registries = discover_all_registries
+
+          if criteria[:name_pattern]
+            pattern = Regexp.new(criteria[:name_pattern], Regexp::IGNORECASE)
+            registries = registries.select { |registry| registry.class.name.match?(pattern) }
+          end
+
+          if criteria[:health_status]
+            case criteria[:health_status]
+            when :healthy
+              registries = registries.select(&:healthy?)
+            when :unhealthy
+              registries = registries.reject(&:healthy?)
+            end
+          end
+
+          if criteria[:min_items]
+            registries = registries.select do |registry|
+              registry.stats[:total_handlers] ||
+                registry.stats[:total_plugins] ||
+                registry.stats[:total_subscribers] || criteria[:min_items] <= 0
+            end
+          end
+
+          registries
+        end
+
+        # Generate performance report
+        #
+        # @return [Hash] Performance analysis across all registries
+        def performance_report
+          registries = discover_all_registries
+
+          performance_data = registries.map do |registry|
+            {
+              registry_name: registry.class.name.demodulize.underscore,
+              performance: measure_registry_performance(registry),
+              item_count: calculate_registry_item_count(registry)
+            }
+          end
+
+          {
+            report_timestamp: Time.current,
+            total_registries: registries.size,
+            performance_data: performance_data,
+            performance_summary: calculate_performance_summary(performance_data)
+          }
+        end
+
+        private
+
+        # Discover all available registries
+        #
+        # @return [Array<BaseRegistry>] All registry instances
+        def discover_all_registries
+          registries = []
+
+          # Core registries
+          registries << Tasker::HandlerFactory.instance if defined?(Tasker::HandlerFactory)
+          registries << Tasker::Registry::SubscriberRegistry.instance if defined?(Tasker::Registry::SubscriberRegistry)
+
+          # Telemetry registries
+          if defined?(Tasker::Telemetry)
+            registries << Tasker::Telemetry::PluginRegistry.instance if defined?(Tasker::Telemetry::PluginRegistry)
+            if defined?(Tasker::Telemetry::ExportCoordinator)
+              registries << Tasker::Telemetry::ExportCoordinator.instance
+            end
+          end
+
+          registries.compact
+        end
+
+        # Measure performance metrics for a registry
+        #
+        # @param registry [BaseRegistry] Registry to measure
+        # @return [Hash] Performance metrics
+        def measure_registry_performance(registry)
+          # Measure stats collection time
+          stats_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          registry.stats
+          stats_duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - stats_start
+
+          # Measure health check time
+          health_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          registry.health_check
+          health_duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - health_start
+
+          {
+            stats_response_time_ms: (stats_duration * 1000).round(2),
+            health_check_time_ms: (health_duration * 1000).round(2),
+            thread_safe: true,
+            last_measured: Time.current
+          }
+        end
+
+        # Analyze usage patterns for a registry
+        #
+        # @param registry [BaseRegistry] Registry to analyze
+        # @return [Hash] Usage pattern analysis
+        def analyze_usage_patterns(registry)
+          stats = registry.stats
+
+          {
+            utilization: calculate_utilization(stats),
+            distribution: calculate_distribution(stats),
+            growth_trend: 'stable', # Would track over time in production
+            efficiency_score: calculate_efficiency_score(stats)
+          }
+        end
+
+        # Calculate utilization level
+        #
+        # @param stats [Hash] Registry statistics
+        # @return [String] Utilization level
+        def calculate_utilization(stats)
+          total_items = stats[:total_handlers] || stats[:total_plugins] || stats[:total_subscribers] || 0
+
+          case total_items
+          when 0 then 'empty'
+          when 1..5 then 'low'
+          when 6..20 then 'medium'
+          when 21..50 then 'high'
+          else 'very_high'
+          end
+        end
+
+        # Calculate distribution pattern
+        #
+        # @param stats [Hash] Registry statistics
+        # @return [String] Distribution pattern
+        def calculate_distribution(stats)
+          if stats[:handlers_by_namespace]
+            analyze_namespace_distribution(stats[:handlers_by_namespace])
+          elsif stats[:plugins_by_format]
+            analyze_format_distribution(stats[:plugins_by_format])
+          elsif stats[:subscribers_by_event]
+            analyze_event_distribution(stats[:subscribers_by_event])
+          else
+            'unknown'
+          end
+        end
+
+        # Analyze namespace distribution for handlers
+        #
+        # @param handlers_by_namespace [Hash] Handler distribution data
+        # @return [String] Distribution pattern
+        def analyze_namespace_distribution(handlers_by_namespace)
+          return 'empty' if handlers_by_namespace.empty?
+
+          values = handlers_by_namespace.values
+          return 'single' if values.size == 1
+
+          avg = values.sum.to_f / values.size
+          variance = values.sum { |v| (v - avg)**2 } / values.size
+
+          variance < 2 ? 'even' : 'skewed'
+        end
+
+        # Analyze format distribution for plugins
+        #
+        # @param plugins_by_format [Hash] Plugin distribution data
+        # @return [String] Distribution pattern
+        def analyze_format_distribution(plugins_by_format)
+          return 'empty' if plugins_by_format.empty?
+
+          values = plugins_by_format.values
+          values.uniq.size == 1 ? 'uniform' : 'varied'
+        end
+
+        # Analyze event distribution for subscribers
+        #
+        # @param subscribers_by_event [Hash] Subscriber distribution data
+        # @return [String] Distribution pattern
+        def analyze_event_distribution(subscribers_by_event)
+          return 'empty' if subscribers_by_event.empty?
+
+          values = subscribers_by_event.values
+          avg = values.sum.to_f / values.size
+          variance = values.sum { |v| (v - avg)**2 } / values.size
+
+          variance < 1 ? 'balanced' : 'unbalanced'
+        end
+
+        # Calculate efficiency score
+        #
+        # @param stats [Hash] Registry statistics
+        # @return [Float] Efficiency score (0.0 - 1.0)
+        def calculate_efficiency_score(stats)
+          # Simple efficiency calculation based on utilization and distribution
+          base_score = 0.5
+
+          # Adjust for utilization
+          utilization = calculate_utilization(stats)
+          utilization_bonus = case utilization
+                              when 'empty' then -0.3
+                              when 'low' then 0.0
+                              when 'medium' then 0.2
+                              when 'high' then 0.3
+                              when 'very_high' then 0.1
+                              end
+
+          # Adjust for distribution
+          distribution = calculate_distribution(stats)
+          distribution_bonus = case distribution
+                               when 'even', 'balanced', 'uniform' then 0.2
+                               when 'skewed', 'unbalanced', 'varied' then -0.1
+                               else 0.0
+                               end
+
+          [0.0, [1.0, base_score + utilization_bonus + distribution_bonus].min].max
+        end
+
+        # Generate recommendations for a registry
+        #
+        # @param registry [BaseRegistry] Registry to analyze
+        # @return [Array<String>] Recommendations
+        def generate_recommendations(registry)
+          recommendations = []
+          stats = registry.stats
+
+          # Health recommendations
+          recommendations << 'Registry health check failed - investigate immediately' unless registry.healthy?
+
+          # Utilization recommendations
+          utilization = calculate_utilization(stats)
+          case utilization
+          when 'empty'
+            recommendations << "Registry is empty - consider if it's needed"
+          when 'very_high'
+            recommendations << 'High utilization - monitor performance and consider optimization'
+          end
+
+          # Distribution recommendations
+          distribution = calculate_distribution(stats)
+          case distribution
+          when 'skewed', 'unbalanced'
+            recommendations << 'Uneven distribution detected - consider rebalancing'
+          end
+
+          recommendations.empty? ? ['Registry is operating optimally'] : recommendations
+        end
+
+        # Calculate aggregated metrics across all registries
+        #
+        # @param registries_stats [Hash] Statistics for all registries
+        # @return [Hash] Aggregated metrics
+        def calculate_aggregated_metrics(registries_stats)
+          total_items = 0
+          healthy_count = 0
+          efficiency_scores = []
+
+          registries_stats.each_value do |stats|
+            total_items += stats[:total_handlers] || stats[:total_plugins] || stats[:total_subscribers] || 0
+            healthy_count += 1 if stats[:health][:healthy]
+            efficiency_scores << stats[:usage_patterns][:efficiency_score]
+          end
+
+          {
+            total_registered_items: total_items,
+            overall_health_percentage: registries_stats.empty? ? 0 : (healthy_count.to_f / registries_stats.size * 100).round(1),
+            average_efficiency_score: efficiency_scores.empty? ? 0 : (efficiency_scores.sum / efficiency_scores.size).round(3),
+            registry_count: registries_stats.size
+          }
+        end
+
+        # Calculate item count for a registry
+        #
+        # @param registry [BaseRegistry] Registry to count items for
+        # @return [Integer] Total item count
+        def calculate_registry_item_count(registry)
+          stats = registry.stats
+          stats[:total_handlers] || stats[:total_plugins] || stats[:total_subscribers] || 0
+        end
+
+        # Calculate performance summary
+        #
+        # @param performance_data [Array<Hash>] Performance data for all registries
+        # @return [Hash] Performance summary
+        def calculate_performance_summary(performance_data)
+          response_times = performance_data.map { |data| data[:performance][:stats_response_time_ms] }
+
+          return { summary: 'no_data' } if response_times.empty?
+
+          {
+            average_response_time_ms: (response_times.sum / response_times.size).round(2),
+            max_response_time_ms: response_times.max,
+            min_response_time_ms: response_times.min,
+            total_items_managed: performance_data.sum { |data| data[:item_count] }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/tasker/registry/subscriber_registry.rb

@@ -0,0 +1,285 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative 'base_registry'
+require_relative 'interface_validator'
+require 'concurrent-ruby'
+
+module Tasker
+  module Registry
+    # Registry for managing event subscribers
+    #
+    # Provides centralized management of event subscribers with discovery,
+    # registration, and event-based lookup capabilities. Integrates with
+    # the existing event system to provide comprehensive subscriber coordination.
+    #
+    # @example Register a subscriber
+    #   registry = Tasker::Registry::SubscriberRegistry.instance
+    #   registry.register(MySubscriber, events: ['task.created', 'task.completed'])
+    #
+    # @example Find subscribers for an event
+    #   subscribers = registry.subscribers_for_event('task.created')
+    #
+    # @example Auto-discover subscribers
+    #   registry.auto_discover_subscribers
+    class SubscriberRegistry < BaseRegistry
+      include Singleton
+
+      def initialize
+        super
+        @subscribers = Concurrent::Hash.new
+        @event_mappings = Concurrent::Hash.new
+        log_registry_operation('initialized', total_subscribers: 0, total_events: 0)
+      end
+
+      # Register an event subscriber
+      #
+      # @param subscriber_class [Class] The subscriber class to register
+      # @param events [Array<String>] Events this subscriber handles
+      # @param replace [Boolean] Whether to replace existing subscriber
+      # @param options [Hash] Additional registration options
+      # @return [Boolean] True if registration successful
+      # @raise [ArgumentError] If subscriber already exists and replace is false
+      def register(subscriber_class, events: [], replace: false, **options)
+        subscriber_name = subscriber_class.name.demodulize.underscore
+
+        thread_safe_operation do
+          # Validate subscriber interface
+          begin
+            Registry::InterfaceValidator.validate_subscriber!(subscriber_class)
+          rescue ArgumentError => e
+            log_validation_failure('event_subscriber', subscriber_name, e.message)
+            raise
+          end
+
+          # Check for existing subscriber
+          if @subscribers.key?(subscriber_name) && !replace
+            raise ArgumentError, "Subscriber '#{subscriber_name}' already registered. Use replace: true to override."
+          end
+
+          # Remove existing subscriber if replacing
+          if @subscribers.key?(subscriber_name)
+            existing_config = @subscribers[subscriber_name]
+            unregister_event_mappings(subscriber_name, existing_config[:events])
+            log_unregistration('event_subscriber', subscriber_name, existing_config[:subscriber_class])
+          end
+
+          # Register subscriber
+          subscriber_config = {
+            subscriber_class: subscriber_class,
+            events: events,
+            registered_at: Time.current,
+            options: options.merge(replace: replace)
+          }
+
+          @subscribers[subscriber_name] = subscriber_config
+
+          # Index by events
+          register_event_mappings(subscriber_name, events)
+
+          log_registration('event_subscriber', subscriber_name, subscriber_class,
+                           { events: events, event_count: events.size, **options })
+
+          true
+        end
+      end
+
+      # Unregister an event subscriber
+      #
+      # @param subscriber_class [Class, String] The subscriber class or name to unregister
+      # @return [Boolean] True if unregistered successfully
+      def unregister(subscriber_class)
+        subscriber_name = if subscriber_class.is_a?(Class)
+                            subscriber_class.name.demodulize.underscore
+                          else
+                            subscriber_class.to_s
+                          end
+
+        thread_safe_operation do
+          subscriber_config = @subscribers.delete(subscriber_name)
+
+          if subscriber_config
+            # Remove from event mappings
+            unregister_event_mappings(subscriber_name, subscriber_config[:events])
+
+            log_unregistration('event_subscriber', subscriber_name, subscriber_config[:subscriber_class])
+            true
+          else
+            false
+          end
+        end
+      end
+
+      # Get subscribers for a specific event
+      #
+      # @param event_name [String] The event name to find subscribers for
+      # @return [Array<Hash>] Array of subscriber configurations
+      def subscribers_for_event(event_name)
+        subscriber_names = @event_mappings[event_name.to_s] || []
+        subscriber_names.filter_map { |name| @subscribers[name] }
+      end
+
+      # Get all registered subscribers
+      #
+      # @return [Hash] All registered subscribers
+      def all_subscribers
+        @subscribers.dup
+      end
+
+      # Get all registered subscribers (required by BaseRegistry)
+      #
+      # @return [Hash] All registered subscribers
+      def all_items
+        all_subscribers
+      end
+
+      # Get supported events across all subscribers
+      #
+      # @return [Array<String>] Array of supported event names
+      def supported_events
+        @event_mappings.keys.sort
+      end
+
+      # Check if an event has any subscribers
+      #
+      # @param event_name [String] Event name to check
+      # @return [Boolean] True if event has subscribers
+      def has_subscribers?(event_name)
+        @event_mappings.key?(event_name.to_s) && !@event_mappings[event_name.to_s].empty?
+      end
+
+      # Auto-discover subscribers in the subscribers directory
+      #
+      # @param directory [String] Directory to search for subscribers
+      # @return [Integer] Number of subscribers discovered
+      def auto_discover_subscribers(directory = nil)
+        directory ||= File.join(File.dirname(__FILE__), '..', 'events', 'subscribers')
+
+        return 0 unless Dir.exist?(directory)
+
+        discovered_count = 0
+
+        Dir.glob(File.join(directory, '*_subscriber.rb')).each do |file|
+          require file
+
+          # Extract class name from filename
+          class_name = File.basename(file, '.rb').camelize
+          full_class_name = "Tasker::Events::Subscribers::#{class_name}"
+
+          begin
+            # Try to instantiate the subscriber
+            subscriber_class = full_class_name.constantize
+
+            # Auto-discover events from class methods or constants
+            events = discover_subscriber_events(subscriber_class)
+
+            register(subscriber_class, events: events, auto_discovered: true)
+            discovered_count += 1
+
+            log_registry_operation('auto_discovered_subscriber',
+                                   subscriber_name: subscriber_class.name,
+                                   events: events,
+                                   file_path: file)
+          rescue StandardError => e
+            log_registry_error('auto_discovery_failed', e,
+                               file_path: file,
+                               class_name: full_class_name)
+          end
+        end
+
+        discovered_count
+      end
+
+      # Get comprehensive registry statistics
+      #
+      # @return [Hash] Detailed statistics about the registry
+      def stats
+        base_stats.merge(
+          total_subscribers: @subscribers.size,
+          total_events: @event_mappings.size,
+          events_covered: @event_mappings.keys.sort,
+          subscribers_by_event: @event_mappings.transform_values(&:size),
+          average_events_per_subscriber: calculate_average_events_per_subscriber,
+          most_popular_events: find_most_popular_events
+        )
+      end
+
+      # Clear all registered subscribers (required by BaseRegistry)
+      #
+      # @return [Boolean] True if cleared successfully
+      def clear!
+        thread_safe_operation do
+          @subscribers.clear
+          @event_mappings.clear
+          log_registry_operation('cleared_all')
+          true
+        end
+      end
+
+      private
+
+      # Register event mappings for a subscriber
+      #
+      # @param subscriber_name [String] Name of the subscriber
+      # @param events [Array<String>] Events to map
+      def register_event_mappings(subscriber_name, events)
+        events.each do |event|
+          event_key = event.to_s
+          @event_mappings[event_key] ||= []
+          @event_mappings[event_key] << subscriber_name unless @event_mappings[event_key].include?(subscriber_name)
+        end
+      end
+
+      # Unregister event mappings for a subscriber
+      #
+      # @param subscriber_name [String] Name of the subscriber
+      # @param events [Array<String>] Events to unmap
+      def unregister_event_mappings(subscriber_name, events)
+        events.each do |event|
+          event_key = event.to_s
+          @event_mappings[event_key]&.delete(subscriber_name)
+          @event_mappings.delete(event_key) if @event_mappings[event_key] && @event_mappings[event_key].empty?
+        end
+      end
+
+      # Discover events that a subscriber handles
+      #
+      # @param subscriber_class [Class] The subscriber class to analyze
+      # @return [Array<String>] Array of event names
+      def discover_subscriber_events(subscriber_class)
+        events = []
+
+        # Check for EVENTS constant
+        events.concat(Array(subscriber_class::EVENTS)) if subscriber_class.const_defined?(:EVENTS)
+
+        # Check for events class method
+        events.concat(Array(subscriber_class.events)) if subscriber_class.respond_to?(:events)
+
+        # Check for event_patterns class method
+        events.concat(Array(subscriber_class.event_patterns)) if subscriber_class.respond_to?(:event_patterns)
+
+        events.map(&:to_s).uniq
+      end
+
+      # Calculate average events per subscriber
+      #
+      # @return [Float] Average number of events per subscriber
+      def calculate_average_events_per_subscriber
+        return 0.0 if @subscribers.empty?
+
+        total_events = @subscribers.values.sum { |config| config[:events].size }
+        (total_events.to_f / @subscribers.size).round(2)
+      end
+
+      # Find the most popular events (top 5)
+      #
+      # @return [Array<Hash>] Array of event popularity data
+      def find_most_popular_events
+        @event_mappings
+          .map { |event, subscribers| { event: event, subscriber_count: subscribers.size } }
+          .sort_by { |data| -data[:subscriber_count] }
+          .first(5)
+      end
+    end
+  end
+end

data/lib/tasker/registry.rb

@@ -0,0 +1,22 @@
+# typed: false
+# frozen_string_literal: true
+
+# Registry module for Tasker
+#
+# Provides unified registry management with thread-safe operations,
+# validation, observability, and coordination capabilities.
+module Tasker
+  module Registry
+    # Registry-related errors
+    class RegistryError < StandardError; end
+    class ValidationError < RegistryError; end
+    class RegistrationError < RegistryError; end
+  end
+end
+
+# Require all registry components
+require_relative 'registry/base_registry'
+require_relative 'registry/interface_validator'
+require_relative 'registry/event_publisher'
+require_relative 'registry/subscriber_registry'
+require_relative 'registry/statistics_collector'