anzen 0.1.0

data/lib/anzen/registry.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Anzen
+  # Registry for managing safety monitors
+  #
+  # Handles registration, lifecycle management, and coordination of monitors.
+  # Thread-safe for monitor state queries.
+  #
+  # @api public
+  class Registry
+    # Initialize Registry
+    def initialize
+      @monitors = {}
+      @enabled_monitors = Set.new
+      @violations_count = {}
+      @mutex = Mutex.new
+    end
+
+    # Register a monitor
+    #
+    # @param monitor [Anzen::Monitor] monitor instance implementing Monitor interface
+    # @raise [InvalidMonitorError] if monitor doesn't implement required interface
+    # @raise [MonitorNameConflictError] if monitor name already registered
+    def register(monitor)
+      validate_monitor_interface(monitor)
+
+      @mutex.synchronize do
+        raise Anzen::MonitorNameConflictError.new(monitor.name) if @monitors.key?(monitor.name)
+
+        @monitors[monitor.name] = monitor
+        @violations_count[monitor.name] = 0
+      end
+    end
+
+    # Unregister a monitor
+    #
+    # @param name [String] monitor name
+    # @raise [MonitorNotFoundError] if monitor not found
+    # @raise [InvalidMonitorError] if monitor is currently enabled
+    def unregister(name)
+      @mutex.synchronize do
+        raise Anzen::MonitorNotFoundError.new(name) unless @monitors.key?(name)
+
+        if @enabled_monitors.include?(name)
+          raise Anzen::InvalidMonitorError.new("Cannot unregister enabled monitor '#{name}'")
+        end
+
+        @monitors.delete(name)
+        @violations_count.delete(name)
+      end
+    end
+
+    # Get monitor by name
+    #
+    # @param name [String] monitor name
+    # @return [Anzen::Monitor] monitor instance
+    # @raise [MonitorNotFoundError] if monitor not found
+    def get(name)
+      @mutex.synchronize do
+        raise Anzen::MonitorNotFoundError.new(name) unless @monitors.key?(name)
+
+        @monitors[name]
+      end
+    end
+
+    # List all registered monitors
+    #
+    # @return [Array<Anzen::Monitor>] all monitors
+    def list
+      @mutex.synchronize do
+        @monitors.values.dup
+      end
+    end
+
+    # List enabled monitors
+    #
+    # @return [Array<Anzen::Monitor>] enabled monitors
+    def list_enabled
+      @mutex.synchronize do
+        @enabled_monitors.map { |name| @monitors[name] }.dup
+      end
+    end
+
+    # Enable a monitor by name
+    #
+    # @param name [String] monitor name
+    # @raise [MonitorNotFoundError] if monitor not found
+    def enable(name)
+      @mutex.synchronize do
+        raise Anzen::MonitorNotFoundError.new(name) unless @monitors.key?(name)
+
+        monitor = @monitors[name]
+        monitor.enable
+        @enabled_monitors.add(name)
+      end
+    end
+
+    # Disable a monitor by name
+    #
+    # @param name [String] monitor name
+    # @raise [MonitorNotFoundError] if monitor not found
+    def disable(name)
+      @mutex.synchronize do
+        raise Anzen::MonitorNotFoundError.new(name) unless @monitors.key?(name)
+
+        monitor = @monitors[name]
+        monitor.disable
+        @enabled_monitors.delete(name)
+      end
+    end
+
+    # Run all enabled monitors' checks
+    #
+    # Calls check! on each enabled monitor in order.
+    # Raises first violation immediately (fail-fast).
+    #
+    # @return [nil]
+    # @raise [ViolationError] subclass on first violation detected
+    # @raise [CheckFailedError] on infrastructure failure
+    def check_all!
+      enabled = @mutex.synchronize { @enabled_monitors.dup }
+
+      enabled.each do |name|
+        monitor = @mutex.synchronize { @monitors[name] }
+        monitor.check!
+      end
+
+      nil
+    end
+
+    # Return status of all monitors
+    #
+    # @return [Hash] aggregated status with keys:
+    #   - monitors (Array): status of each monitor
+    #   - enabled_count (Integer): number of enabled monitors
+    #   - violations_total (Integer): total violations across all monitors
+    def status
+      @mutex.synchronize do
+        monitor_statuses = @monitors.values.map(&:status)
+        enabled_count = @enabled_monitors.size
+        violations_total = @monitors.values.sum { |m| m.status[:violations] }
+
+        {
+          monitors: monitor_statuses,
+          enabled_count: enabled_count,
+          violations_total: violations_total
+        }
+      end
+    end
+
+    private
+
+    # Validate monitor implements required interface
+    #
+    # @param monitor [Object] monitor to validate
+    # @raise [InvalidMonitorError] if monitor doesn't implement interface
+    def validate_monitor_interface(monitor)
+      required_methods = %i[name enable disable enabled? check! status to_cli]
+
+      required_methods.each do |method|
+        next if monitor.respond_to?(method)
+
+        raise Anzen::InvalidMonitorError.new(
+          "Monitor must implement ##{method} method"
+        )
+      end
+    end
+  end
+end

data/lib/anzen/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Anzen
+  VERSION = '0.1.0'
+end

data/lib/anzen.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require_relative 'anzen/version'
+require_relative 'anzen/exceptions'
+require_relative 'anzen/monitor'
+require_relative 'anzen/monitors/call_stack_depth'
+require_relative 'anzen/monitors/recursion'
+require_relative 'anzen/monitors/memory'
+require_relative 'anzen/registry'
+require_relative 'anzen/configuration'
+
+# Anzen - Runtime safety protection gem
+#
+# Provides safety monitoring for recursion, memory, and other runtime concerns.
+# Use Anzen.setup to initialize with monitors and configuration.
+#
+# @example Basic usage
+#   Anzen.setup(config: { enabled_monitors: ['recursion'], monitors: { recursion: { depth_limit: 1000 } } })
+#   # ... your code ...
+#   Anzen.check!  # Raises if any monitor detects violation
+#
+# @api public
+module Anzen
+  # @!visibility private
+  @@registry = nil
+
+  # @!visibility private
+  @@initialized = false
+
+  # @!visibility private
+  @@setup_at = nil
+
+  # Reset Anzen state (for testing only)
+  #
+  # @private
+  # @api private
+  def self._reset_for_testing
+    @@registry = nil
+    @@initialized = false
+    @@setup_at = nil
+  end
+
+  # Setup Anzen with configuration and monitors
+  #
+  # Initializes the registry, creates and registers default monitors (call_stack_depth, recursion, memory),
+  # and enables specified ones based on configuration sources (programmatic, env var, or file).
+  # Can only be called once per process.
+  #
+  # @param config [Hash] configuration hash with keys:
+  #   - config_file (String): path to YAML/JSON config file (optional)
+  #   - enabled_monitors (Array): list of monitor names to enable
+  #   - monitors (Hash): per-monitor configurations
+  # @raise [InitializationError] if Anzen is already initialized
+  # @raise [ConfigurationError] if configuration is invalid
+  # @return [void]
+  #
+  # @example Programmatic setup
+  #   Anzen.setup(config: {
+  #     enabled_monitors: ['recursion'],
+  #     monitors: { recursion: { depth_limit: 500 } }
+  #   })
+  #
+  # @example Environment variable setup
+  #   ENV['ANZEN_CONFIG'] = '{"enabled_monitors": ["memory"], "monitors": {"memory": {"limit_mb": 1024}}}'
+  #   Anzen.setup  # Uses env var config
+  #
+  # @example File-based setup
+  #   Anzen.setup(config: { config_file: 'config/anzen.yml' })
+  def self.setup(config: {})
+    raise Anzen::InitializationError if @@initialized
+
+    @@registry = Registry.new
+
+    # Determine configuration source
+    configuration = if config.key?(:config_file)
+                      Configuration.from_file(config[:config_file])
+                    elsif ENV['ANZEN_CONFIG']
+                      Configuration.from_env
+                    else
+                      Configuration.programmatic(config)
+                    end
+
+    # Register CallStackDepthMonitor
+    depth_limit = 1000
+    begin
+      depth_limit = configuration.monitor_config('call_stack_depth')['depth_limit']
+    rescue Anzen::ConfigurationError
+      # Use default if not configured
+    end
+
+    call_stack_depth_monitor = Monitors::CallStackDepthMonitor.new(depth_limit: depth_limit)
+    @@registry.register(call_stack_depth_monitor)
+
+    # Register RecursionMonitor
+    recursion_config = {}
+    begin
+      recursion_config = configuration.monitor_config('recursion')
+    rescue Anzen::ConfigurationError
+      # Use defaults if not configured
+    end
+    depth_limit = recursion_config['depth_limit'] || 1000
+
+    recursion_monitor = Monitors::RecursionMonitor.new(depth_limit: depth_limit)
+    @@registry.register(recursion_monitor)
+
+    # Register MemoryMonitor
+    memory_config = {}
+    begin
+      memory_config = configuration.monitor_config('memory')
+    rescue Anzen::ConfigurationError
+      # Use defaults if not configured
+    end
+    limit_mb = memory_config['limit_mb'] || 512
+    sampling_interval_ms = memory_config['sampling_interval_ms'] || 100
+
+    memory_monitor = Monitors::MemoryMonitor.new(
+      limit_mb: limit_mb,
+      sampling_interval_ms: sampling_interval_ms
+    )
+    @@registry.register(memory_monitor)
+
+    # Enable specified monitors
+    @@registry.enable('call_stack_depth') if configuration.monitor_enabled?('call_stack_depth')
+    @@registry.enable('recursion') if configuration.monitor_enabled?('recursion')
+    @@registry.enable('memory') if configuration.monitor_enabled?('memory')
+
+    @@setup_at = Time.now
+    @@initialized = true
+  end
+
+  # Enable a monitor by name
+  #
+  # @param name [String] monitor name
+  # @raise [MonitorNotFoundError] if monitor not found
+  # @return [void]
+  def self.enable(name)
+    ensure_initialized
+    @@registry.enable(name)
+  end
+
+  # Disable a monitor by name
+  #
+  # @param name [String] monitor name
+  # @raise [MonitorNotFoundError] if monitor not found
+  # @return [void]
+  def self.disable(name)
+    ensure_initialized
+    @@registry.disable(name)
+  end
+
+  # Execute all enabled monitors' checks
+  #
+  # Runs check! on each enabled monitor. Raises immediately if any violation detected.
+  #
+  # @raise [ViolationError] subclass on first violation detected
+  # @raise [CheckFailedError] on infrastructure failure
+  # @return [nil]
+  def self.check!
+    ensure_initialized
+    @@registry.check_all!
+  end
+
+  # Return status of all monitors
+  #
+  # @return [Hash] status hash with keys:
+  #   - enabled (Array): array of enabled monitor names
+  #   - enabled_count (Integer): number of enabled monitors
+  #   - setup_at (Time): when Anzen was initialized
+  #   - monitors (Array): array of monitor status hashes with keys: name, enabled, thresholds, last_check, violations
+  #   - violations_total (Integer): total violations across all monitors
+  def self.status
+    ensure_initialized
+    registry_status = @@registry.status
+
+    # Transform registry status to API contract format
+    enabled_monitor_names = @@registry.instance_variable_get(:@enabled_monitors).to_a
+
+    {
+      monitors: registry_status[:monitors],
+      enabled: enabled_monitor_names,
+      enabled_count: registry_status[:enabled_count],
+      violations_total: registry_status[:violations_total],
+      setup_at: @@setup_at
+    }
+  end
+
+  # Register a custom monitor
+  #
+  # Monitor must implement the Monitor interface.
+  #
+  # @param monitor [Anzen::Monitor] monitor instance
+  # @raise [InvalidMonitorError] if monitor doesn't implement required interface
+  # @raise [MonitorNameConflictError] if monitor name already registered
+  # @return [void]
+  def self.register_monitor(monitor)
+    ensure_initialized
+    @@registry.register(monitor)
+  end
+
+  class << self
+    private
+
+    # Ensure Anzen is initialized
+    #
+    # @raise [InitializationError] if not initialized
+    def ensure_initialized
+      raise Anzen::InitializationError, 'Anzen not initialized. Call Anzen.setup first.' unless @@initialized
+    end
+  end
+end

data/sig/anzen.rbs

@@ -0,0 +1,4 @@
+module Anzen
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: anzen
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Korakot Leemakdej
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-17 00:00:00.000000000 Z
+dependencies: []
+description: Anzen detects and prevents bad code patterns (recursive call stacks,
+  memory overflow) before they crash your production system. Provides pluggable monitors
+  for safety protection via Ruby API and CLI interface.
+email:
+- kleemakdej@gmail.com
+executables:
+- anzen
+- console
+- setup
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- README.md
+- Rakefile
+- bin/anzen
+- bin/console
+- bin/setup
+- lib/anzen.rb
+- lib/anzen/README_API.md
+- lib/anzen/cli.rb
+- lib/anzen/configuration.rb
+- lib/anzen/exceptions.rb
+- lib/anzen/monitor.rb
+- lib/anzen/monitors/call_stack_depth.rb
+- lib/anzen/monitors/memory.rb
+- lib/anzen/monitors/recursion.rb
+- lib/anzen/registry.rb
+- lib/anzen/version.rb
+- sig/anzen.rbs
+homepage: https://github.com/korakot-leemakdej/anzen
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/korakot-leemakdej/anzen
+  source_code_uri: https://github.com/korakotlee/anzen
+  changelog_uri: https://github.com/korakotlee/anzen/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Runtime safety protection gem for Ruby applications
+test_files: []