anzen 0.1.0

data/lib/anzen/monitor.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Anzen
+  # Base interface/contract for all safety monitors
+  #
+  # All monitors (built-in and custom) must implement this interface.
+  # This module defines the required methods that every monitor must provide.
+  #
+  # @api public
+  # @example Implement a custom monitor
+  #   class MyMonitor
+  #     include Anzen::Monitor
+  #
+  #     def name
+  #       'my_monitor'
+  #     end
+  #
+  #     def check!
+  #       # Your monitoring logic here
+  #       raise Anzen::ViolationError.new("violation") if problem_detected?
+  #     end
+  #   end
+  module Monitor
+    # Unique identifier for this monitor
+    #
+    # @return [String] monitor name (format: [a-z0-9_]+)
+    def name
+      raise NotImplementedError, "#{self.class} must implement #name"
+    end
+
+    # Enable this monitor for checking
+    #
+    # @return [Boolean] true
+    def enable
+      raise NotImplementedError, "#{self.class} must implement #enable"
+    end
+
+    # Disable this monitor from checking
+    #
+    # @return [Boolean] false
+    def disable
+      raise NotImplementedError, "#{self.class} must implement #disable"
+    end
+
+    # Check if this monitor is currently enabled
+    #
+    # @return [Boolean] true if enabled, false if disabled
+    def enabled?
+      raise NotImplementedError, "#{self.class} must implement #enabled?"
+    end
+
+    # Execute this monitor's check
+    #
+    # Reads current state, compares to thresholds, and raises appropriate error if violation detected.
+    # Must raise a ViolationError subclass on violation, or CheckFailedError if check itself fails.
+    # Must not raise if check passes.
+    # Returns nil if check passes (monitor enabled or disabled).
+    #
+    # @return [nil] if check passes
+    # @raise [Anzen::ViolationError] subclass on detection
+    # @raise [Anzen::CheckFailedError] on infrastructure failure
+    def check!
+      raise NotImplementedError, "#{self.class} must implement #check!"
+    end
+
+    # Return current status of this monitor
+    #
+    # @return [Hash] status hash with keys: name, enabled, thresholds, last_check, violations
+    #   - name (String): monitor name
+    #   - enabled (Boolean): whether monitor is enabled
+    #   - thresholds (Hash): monitor-specific threshold values
+    #   - last_check (Time): timestamp of last check, or nil if never checked
+    #   - violations (Integer): count of violations detected
+    def status
+      raise NotImplementedError, "#{self.class} must implement #status"
+    end
+
+    # Return human-readable one-liner for CLI output
+    #
+    # @return [String] single line describing monitor status
+    def to_cli
+      raise NotImplementedError, "#{self.class} must implement #to_cli"
+    end
+  end
+end

data/lib/anzen/monitors/call_stack_depth.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Anzen
+  module Monitors
+    # Monitor that detects call stack depth exceeding configured threshold
+    #
+    # Tracks call stack depth and raises RecursionLimitExceeded when
+    # the depth exceeds the configured limit. Supports any recursion pattern
+    # (direct, indirect, n-way cycles).
+    #
+    # Use case: Hard limit on stack depth to prevent OOM/stack overflow
+    #
+    # @api public
+    # @example Basic usage
+    #   monitor = Anzen::Monitors::CallStackDepthMonitor.new(depth_limit: 1000)
+    #   monitor.enable
+    #   monitor.check!  # Raises RecursionLimitExceeded if depth > 1000
+    class CallStackDepthMonitor
+      include Anzen::Monitor
+
+      # @return [Integer] configured depth limit
+      attr_reader :depth_limit
+
+      # @return [Integer] count of violations detected
+      attr_reader :violation_count
+
+      # @return [Time, nil] timestamp of last check
+      attr_reader :last_check
+
+      # Initialize CallStackDepthMonitor
+      #
+      # @param depth_limit [Integer] maximum allowed call stack depth (must be positive)
+      # @raise [ConfigurationError] if depth_limit is not a positive integer
+      def initialize(depth_limit: 1000)
+        validate_depth_limit(depth_limit)
+        @depth_limit = depth_limit
+        @enabled = false
+        @violation_count = 0
+        @last_check = nil
+      end
+
+      # Monitor name
+      #
+      # @return [String] "call_stack_depth"
+      def name
+        'call_stack_depth'
+      end
+
+      # Enable this monitor
+      #
+      # @return [Boolean] true
+      def enable
+        @enabled = true
+      end
+
+      # Disable this monitor
+      #
+      # @return [Boolean] false
+      def disable
+        @enabled = false
+      end
+
+      # Check if monitor is enabled
+      #
+      # @return [Boolean]
+      def enabled?
+        @enabled
+      end
+
+      # Check current call stack depth
+      #
+      # Reads the call stack, counts method frames, and raises RecursionLimitExceeded
+      # if depth exceeds threshold. Blocks count as method frames.
+      # Does nothing if monitor is disabled.
+      #
+      # @return [nil]
+      # @raise [Anzen::RecursionLimitExceeded] if depth exceeds threshold
+      # @raise [Anzen::CheckFailedError] if check infrastructure fails
+      def check!
+        return nil unless @enabled
+
+        begin
+          current_depth = calculate_depth
+          @last_check = Time.now
+
+          if current_depth > @depth_limit
+            @violation_count += 1
+            raise Anzen::RecursionLimitExceeded.new(current_depth, @depth_limit)
+          end
+
+          nil
+        rescue Anzen::RecursionLimitExceeded
+          raise
+        rescue StandardError => e
+          raise Anzen::CheckFailedError.new(name, 'Failed to calculate call stack depth', e)
+        end
+      end
+
+      # Return current status
+      #
+      # @return [Hash] status hash with keys: name, enabled, thresholds, last_check, violations
+      def status
+        {
+          name: name,
+          enabled: @enabled,
+          thresholds: {
+            depth_limit: @depth_limit
+          },
+          last_check: @last_check,
+          violations: @violation_count
+        }
+      end
+
+      # Return human-readable one-liner for CLI
+      #
+      # @return [String]
+      def to_cli
+        status_text = @enabled ? 'enabled' : 'disabled'
+        "Call stack depth monitor (#{status_text}): limit=#{@depth_limit}, violations=#{@violation_count}"
+      end
+
+      private
+
+      # Calculate current call stack depth
+      #
+      # Counts method frames in the call stack.
+      # Uses Kernel.caller to get the call stack.
+      #
+      # @return [Integer] current depth
+      def calculate_depth
+        # Kernel.caller returns array of strings like "path/file.rb:123:in `method_name'"
+        # Each frame represents a method call (including blocks)
+        caller.length
+      end
+
+      # Validate depth_limit configuration
+      #
+      # @param depth_limit [Integer, Numeric]
+      # @raise [Anzen::ConfigurationError] if invalid
+      def validate_depth_limit(depth_limit)
+        return if depth_limit.is_a?(Numeric) && depth_limit > 0 && depth_limit == depth_limit.to_i
+
+        raise Anzen::ConfigurationError, "depth_limit must be a positive integer, got #{depth_limit.inspect}"
+      end
+    end
+  end
+end

data/lib/anzen/monitors/memory.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module Anzen
+  module Monitors
+    # Monitor that detects memory consumption exceeding configurable threshold
+    #
+    # Monitors process RSS (Resident Set Size) memory usage with configurable sampling
+    # to minimize overhead. Supports absolute MB limits or percentage of available memory.
+    # Raises MemoryLimitExceeded immediately when threshold is exceeded.
+    #
+    # Use case: Prevent memory leaks and runaway memory consumption in long-running processes
+    #
+    # @api public
+    # @example Basic usage
+    #   monitor = Anzen::Monitors::MemoryMonitor.new(limit_mb: 512)
+    #   monitor.enable
+    #   monitor.check!  # Raises MemoryLimitExceeded if > 512MB used
+    class MemoryMonitor
+      include Anzen::Monitor
+
+      # Default sampling interval in milliseconds
+      DEFAULT_SAMPLING_INTERVAL_MS = 100
+
+      # Default memory limit in MB
+      DEFAULT_LIMIT_MB = 512
+
+      # @return [String] monitor name
+      attr_reader :name
+
+      # @return [Integer] memory limit in MB
+      attr_reader :limit_mb
+
+      # @return [Integer] sampling interval in milliseconds
+      attr_reader :sampling_interval_ms
+
+      # @return [Time, nil] timestamp of last check
+      attr_reader :last_check_time
+
+      # @return [Float] current RSS memory in MB at last check
+      attr_reader :current_rss_mb
+
+      # @return [Integer] count of violations detected
+      attr_reader :violation_count
+
+      # Initialize MemoryMonitor
+      #
+      # @param limit_mb [Integer] memory limit in MB (default: 512)
+      # @param sampling_interval_ms [Integer] milliseconds between checks (default: 100)
+      def initialize(limit_mb: DEFAULT_LIMIT_MB, sampling_interval_ms: DEFAULT_SAMPLING_INTERVAL_MS)
+        @name = 'memory'
+        @enabled = false
+        @limit_mb = limit_mb
+        @sampling_interval_ms = sampling_interval_ms
+        @last_check_time = nil
+        @current_rss_mb = 0.0
+        @violation_count = 0
+
+        validate_configuration!
+      end
+
+      # Enable this monitor
+      #
+      # @return [Boolean] true
+      def enable
+        @enabled = true
+      end
+
+      # Disable this monitor
+      #
+      # @return [Boolean] false
+      def disable
+        @enabled = false
+      end
+
+      # Check if monitor is enabled
+      #
+      # @return [Boolean]
+      def enabled?
+        @enabled
+      end
+
+      # Check for memory limit violation
+      #
+      # Reads current process RSS memory and compares to configured limit.
+      # Only performs check if sampling interval has elapsed since last check.
+      # Raises MemoryLimitExceeded if memory usage exceeds threshold.
+      # Does nothing if monitor is disabled.
+      #
+      # @return [nil]
+      # @raise [Anzen::MemoryLimitExceeded] if memory usage exceeds threshold
+      # @raise [Anzen::CheckFailedError] if memory reading fails
+      def check!
+        return nil unless @enabled
+
+        begin
+          if should_check?
+            @current_rss_mb = read_process_memory_mb
+            @last_check_time = Time.now
+
+            if @current_rss_mb > @limit_mb
+              @violation_count += 1
+              raise Anzen::MemoryLimitExceeded.new(@current_rss_mb, @limit_mb)
+            end
+          end
+
+          nil
+        rescue Anzen::MemoryLimitExceeded
+          raise
+        rescue StandardError => e
+          raise Anzen::CheckFailedError.new(name, 'Failed to read process memory', e)
+        end
+      end
+
+      # Return current status
+      #
+      # @return [Hash] status hash with keys: name, enabled, thresholds, last_check, violations
+      def status
+        {
+          name: name,
+          enabled: @enabled,
+          thresholds: {
+            limit_mb: @limit_mb,
+            sampling_interval_ms: @sampling_interval_ms
+          },
+          last_check: @last_check_time,
+          violations: @violation_count
+        }
+      end
+
+      # Return human-readable one-liner for CLI
+      #
+      # @return [String]
+      def to_cli
+        status_text = @enabled ? 'enabled' : 'disabled'
+        "Memory monitor (#{status_text}): limit=#{@limit_mb}MB, current=#{@current_rss_mb.round(1)}MB, violations=#{@violation_count}"
+      end
+
+      private
+
+      # Validate configuration parameters
+      #
+      # @raise [Anzen::ConfigurationError] if configuration is invalid
+      def validate_configuration!
+        unless @limit_mb.is_a?(Integer) && @limit_mb > 0
+          raise Anzen::ConfigurationError, "limit_mb must be a positive integer, got: #{@limit_mb.inspect}"
+        end
+
+        return if @sampling_interval_ms.is_a?(Integer) && @sampling_interval_ms >= 0
+
+        raise Anzen::ConfigurationError,
+              "sampling_interval_ms must be a non-negative integer, got: #{@sampling_interval_ms.inspect}"
+      end
+
+      # Check if enough time has elapsed since last check
+      #
+      # @return [Boolean] true if should perform check
+      def should_check?
+        return true if @last_check_time.nil?
+
+        elapsed_ms = (Time.now - @last_check_time) * 1000
+        elapsed_ms >= @sampling_interval_ms
+      end
+
+      # Read current process memory usage in MB
+      #
+      # Attempts to read RSS from /proc/[pid]/status (Linux) or falls back to
+      # parsing `ps` command output for cross-platform compatibility.
+      #
+      # @return [Float] memory usage in MB
+      # @raise [StandardError] if memory reading fails
+      def read_process_memory_mb
+        pid = Process.pid
+
+        # Try Linux /proc filesystem first (most efficient)
+        return read_memory_from_proc(pid) if File.exist?("/proc/#{pid}/status")
+
+        # Fallback to ps command (cross-platform)
+        read_memory_from_ps(pid)
+      end
+
+      # Read memory from Linux /proc/[pid]/status
+      #
+      # @param pid [Integer] process ID
+      # @return [Float] memory in MB
+      def read_memory_from_proc(pid)
+        status_file = "/proc/#{pid}/status"
+        content = File.read(status_file)
+
+        # Find VmRSS line: "VmRSS:    12345 kB"
+        vmrss_match = content.match(/^VmRSS:\s+(\d+)\s+kB/)
+        raise "Could not find VmRSS in #{status_file}" unless vmrss_match
+
+        kb = vmrss_match[1].to_i
+        kb / 1024.0 # Convert to MB
+      end
+
+      # Read memory using ps command (fallback for non-Linux systems)
+      #
+      # @param pid [Integer] process ID
+      # @return [Float] memory in MB
+      def read_memory_from_ps(pid)
+        # Use ps to get RSS in KB, then convert to MB
+        # Format: "PID RSS" where RSS is in KB
+        output, status = run_ps_command(pid)
+        raise "ps command failed: #{status.exitstatus}" unless status.success?
+
+        lines = output.strip.split("\n")
+        raise "ps output incomplete for PID #{pid}" if lines.length < 2
+
+        # Second line contains the data
+        fields = lines[1].strip.split
+        raise "ps output format unexpected: #{lines[1]}" if fields.length < 2
+
+        rss_kb = fields[1].to_i
+        rss_kb / 1024.0 # Convert to MB
+      end
+
+      # Execute ps command (extracted for testability)
+      #
+      # @param pid [Integer] process ID
+      # @return [Array<String, Process::Status>] output and status
+      def run_ps_command(pid)
+        output = `ps -o pid,rss -p #{pid} 2>/dev/null`
+        [output, $?]
+      end
+    end
+  end
+end

data/lib/anzen/monitors/recursion.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Anzen
+  module Monitors
+    # Monitor that detects any recursive method calls (pattern-based)
+    #
+    # Detects direct recursion (same method repeating) and indirect recursion
+    # (method chains forming cycles). Raises RecursionLimitExceeded immediately
+    # on first recursion detection, with no depth threshold.
+    #
+    # Use case: Strict no-recursion enforcement (e.g., signal handlers, async contexts)
+    #
+    # @api public
+    # @example Basic usage
+    #   monitor = Anzen::Monitors::RecursionMonitor.new
+    #   monitor.enable
+    #   monitor.check!  # Raises RecursionLimitExceeded if any recursion detected
+    class RecursionMonitor
+      include Anzen::Monitor
+
+      # Thread-local key for storing call frame tracking
+      FRAME_KEY = :anzen_recursion_frames
+
+      # @return [Integer] count of violations detected
+      attr_reader :violation_count
+
+      # Initialize RecursionMonitor
+      #
+      # @param depth_limit [Integer] maximum allowed recursion depth (default: 1000)
+      def initialize(depth_limit: 1000)
+        @enabled = false
+        @violation_count = 0
+        @depth_limit = depth_limit
+        @last_check = nil
+      end
+
+      # Monitor name
+      #
+      # @return [String] "recursion"
+      def name
+        'recursion'
+      end
+
+      # Enable this monitor
+      #
+      # @return [Boolean] true
+      def enable
+        @enabled = true
+      end
+
+      # Disable this monitor
+      #
+      # @return [Boolean] false
+      def disable
+        @enabled = false
+      end
+
+      # Check if monitor is enabled
+      #
+      # @return [Boolean]
+      def enabled?
+        @enabled
+      end
+
+      # Check for recursion pattern
+      #
+      # Analyzes the current call stack to detect if any method appears
+      # multiple times (direct recursion) or if there's a cycle in the call chain
+      # (indirect recursion). Raises RecursionLimitExceeded if recursion is
+      # detected and the call stack depth exceeds the configured limit.
+      #
+      # @return [nil]
+      # @raise [Anzen::RecursionLimitExceeded] if recursion detected and depth exceeds limit
+      # @raise [Anzen::CheckFailedError] if check infrastructure fails
+      def check!
+        return nil unless @enabled
+
+        begin
+          current_depth = caller.length
+          @last_check = Time.now
+
+          if recursion_detected? && current_depth > @depth_limit
+            @violation_count += 1
+            raise Anzen::RecursionLimitExceeded.new(current_depth, @depth_limit)
+          end
+
+          nil
+        rescue Anzen::RecursionLimitExceeded
+          raise
+        rescue StandardError => e
+          raise Anzen::CheckFailedError.new(name, 'Failed to detect recursion pattern', e)
+        end
+      end
+
+      # Return current status
+      #
+      # @return [Hash] status hash with keys: name, enabled, thresholds, last_check, violations
+      def status
+        {
+          name: name,
+          enabled: @enabled,
+          thresholds: {
+            depth_limit: @depth_limit
+          },
+          last_check: @last_check,
+          violations: @violation_count
+        }
+      end
+
+      # Return human-readable one-liner for CLI
+      #
+      # @return [String]
+      def to_cli
+        status_text = @enabled ? 'enabled' : 'disabled'
+        "Recursion monitor (#{status_text}): violations=#{@violation_count}"
+      end
+
+      private
+
+      # Detect if current call stack has recursion pattern
+      #
+      # Uses call context (file:line:method) for application frames to avoid
+      # false positives from framework internals while still detecting cycles.
+      #
+      # @return [Boolean] true if recursion detected
+      def recursion_detected?
+        contexts = extract_call_contexts
+        seen = Set.new
+        contexts.each do |ctx|
+          return true if seen.include?(ctx)
+
+          seen.add(ctx)
+        end
+        false
+      end
+
+      # Extract call contexts (file:line:method) from the filtered call stack
+      #
+      # Example: "path/file.rb:123:in `method'" => "path/file.rb:123:method"
+      #
+      # @return [Array<String>]
+      def extract_call_contexts
+        caller
+          .reject { |frame| should_skip_frame?(frame) }
+          .map { |frame| extract_call_context(frame) }
+          .compact
+      end
+
+      # Determine if a caller frame should be skipped
+      #
+      # Skips frames from:
+      # - Standard library (stdlib paths)
+      # - RSpec and testing framework core
+      # - Ruby's internal code
+      # - Gems/vendor directories (except application code)
+      #
+      # Does NOT skip application code in spec/test/integration directories.
+      #
+      # @param frame [String] caller frame string
+      # @return [Boolean] true if frame should be skipped
+      def should_skip_frame?(frame)
+        # Skip only specific framework/library patterns, not application test code
+        skip_patterns = [
+          %r{/gems/.*\.rb:}, # Bundler gems
+          %r{\.bundle/}, # Bundler paths
+          %r{/lib/ruby/\d+\.\d+}, # Standard library
+          %r{rspec.*gem.*/lib/},       # RSpec gem code (not test files)
+          /<internal:/,                # Ruby internals
+          /method_missing/ # Dynamic method dispatch
+        ]
+
+        skip_patterns.any? { |pattern| frame.match?(pattern) }
+      end
+
+      # Extract file:line:method context from a caller frame
+      def extract_call_context(frame)
+        match = frame.match(/^([^:]+:\d+):in `([^']+)'/)
+        return nil unless match
+
+        file_line = match[1]
+        method = match[2]
+        "#{file_line}:#{method}"
+      end
+
+      # Get current call stack depth for error reporting
+      #
+      # @return [Integer]
+      def current_depth
+        caller.length
+      end
+    end
+  end
+end