makit 0.0.98 → 0.0.111

data/lib/makit/logging/configuration.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module Makit
+  module Logging
+    # Configuration management for unified logging
+    #
+    # Provides schema validation, default configurations, and helper methods
+    # for setting up the unified file sink with various output configurations.
+    #
+    # @example Basic configuration
+    #   config = Configuration.new(
+    #     configurations: [
+    #       { file: $stdout, format: :console },
+    #       { file: "logs/app.log", format: :json }
+    #     ]
+    #   )
+    #
+    # @example YAML configuration
+    #   config = Configuration.from_yaml("config/logging.yml")
+    #
+    # @example Environment-based configuration
+    #   config = Configuration.for_environment(:production)
+    class Configuration
+      # @return [Array<Hash>] list of output configurations
+      attr_reader :configurations
+
+      # Initialize configuration
+      #
+      # @param configurations [Array<Hash>] list of output configurations
+      def initialize(configurations: [])
+        @configurations = configurations
+      end
+
+      # Create configuration from YAML file
+      #
+      # @param yaml_file [String] path to YAML configuration file
+      # @return [Configuration] new configuration instance
+      def self.from_yaml(yaml_file)
+        require "yaml"
+        data = YAML.load_file(yaml_file)
+        configurations = data["logging"]["sinks"] || []
+
+        # Convert string keys to symbols
+        configurations = configurations.map do |config|
+          config.transform_keys(&:to_sym)
+        end
+
+        new(configurations: configurations)
+      end
+
+      # Create configuration from JSON file
+      #
+      # @param json_file [String] path to JSON configuration file
+      # @return [Configuration] new configuration instance
+      def self.from_json(json_file)
+        require "json"
+        data = JSON.parse(File.read(json_file))
+        configurations = data["logging"]["sinks"] || []
+
+        # Convert string keys to symbols
+        configurations = configurations.map do |config|
+          config.transform_keys(&:to_sym)
+        end
+
+        new(configurations: configurations)
+      end
+
+      # Create environment-specific configuration
+      #
+      # @param environment [Symbol] environment name (:development, :production, :test)
+      # @return [Configuration] new configuration instance
+      def self.for_environment(environment)
+        case environment
+        when :development
+          development_config
+        when :production
+          production_config
+        when :test
+          test_config
+        when :ci
+          ci_config
+        else
+          default_config
+        end
+      end
+
+      # Get default configuration
+      #
+      # @return [Configuration] default configuration
+      def self.default_config
+        new(
+          configurations: [
+            { file: $stdout, format: :console },
+            { file: "artifacts/makit.log", format: :json, append: true },
+          ],
+        )
+      end
+
+      # Get development configuration
+      #
+      # @return [Configuration] development configuration
+      def self.development_config
+        new(
+          configurations: [
+            {
+              file: $stdout,
+              format: :console,
+              show_timestamp: true,
+              show_level: true,
+            },
+            {
+              file: "logs/development.log",
+              format: :text,
+              append: true,
+              include_context: true,
+            },
+            {
+              file: "logs/debug.log",
+              format: :json,
+              append: true,
+              min_level: :debug,
+            },
+          ],
+        )
+      end
+
+      # Get production configuration
+      #
+      # @return [Configuration] production configuration
+      def self.production_config
+        new(
+          configurations: [
+            {
+              file: "logs/application.log",
+              format: :json,
+              append: true,
+              include_metadata: true,
+              rotation: { max_size: "100MB", max_files: 10 },
+            },
+            {
+              file: "logs/errors.log",
+              format: :json,
+              append: true,
+              min_level: :error,
+              include_metadata: true,
+            },
+          ],
+        )
+      end
+
+      # Get test configuration
+      #
+      # @return [Configuration] test configuration
+      def self.test_config
+        new(
+          configurations: [
+            {
+              file: "logs/test.log",
+              format: :text,
+              append: false,
+              include_context: true,
+            },
+          ],
+        )
+      end
+
+      # Get CI/CD configuration
+      #
+      # @return [Configuration] CI configuration
+      def self.ci_config
+        new(
+          configurations: [
+            {
+              file: $stdout,
+              format: :console,
+              show_level: true,
+            },
+            {
+              file: "artifacts/build.log",
+              format: :json,
+              append: true,
+              include_metadata: true,
+            },
+          ],
+        )
+      end
+
+      # Validate configuration
+      #
+      # @return [Boolean] true if valid
+      # @raise [ArgumentError] if configuration is invalid
+      def validate!
+        raise ArgumentError, "configurations must be an array" unless @configurations.is_a?(Array)
+        raise ArgumentError, "at least one configuration is required" if @configurations.empty?
+
+        @configurations.each_with_index do |config, index|
+          validate_single_configuration(config, index)
+        end
+
+        true
+      end
+
+      # Check if configuration is valid
+      #
+      # @return [Boolean] true if valid
+      def valid?
+        validate!
+        true
+      rescue ArgumentError
+        false
+      end
+
+      # Get configuration as hash
+      #
+      # @return [Hash] configuration as hash
+      def to_hash
+        {
+          logging: {
+            sinks: @configurations,
+          },
+        }
+      end
+
+      # Save configuration to YAML file
+      #
+      # @param yaml_file [String] path to YAML file
+      # @return [void]
+      def save_yaml(yaml_file)
+        require "yaml"
+        FileUtils.mkdir_p(File.dirname(yaml_file))
+        File.write(yaml_file, to_hash.to_yaml)
+      end
+
+      # Save configuration to JSON file
+      #
+      # @param json_file [String] path to JSON file
+      # @return [void]
+      def save_json(json_file)
+        require "json"
+        FileUtils.mkdir_p(File.dirname(json_file))
+        File.write(json_file, JSON.pretty_generate(to_hash))
+      end
+
+      private
+
+      # Validate a single configuration
+      #
+      # @param config [Hash] configuration to validate
+      # @param index [Integer] configuration index for error messages
+      # @raise [ArgumentError] if configuration is invalid
+      def validate_single_configuration(config, index)
+        raise ArgumentError, "configuration #{index} must be a hash" unless config.is_a?(Hash)
+
+        required_keys = [:file, :format]
+        missing_keys = required_keys - config.keys
+        raise ArgumentError, "configuration #{index} missing required keys: #{missing_keys.join(", ")}" unless missing_keys.empty?
+
+        # Validate file
+        file = config[:file]
+        unless file.is_a?(String) || file.is_a?(IO) || file.respond_to?(:write)
+          raise ArgumentError, "configuration #{index} file must be a String path, IO object, or writable object"
+        end
+
+        # Validate format
+        format = config[:format]
+        unless format.is_a?(Symbol) || format.is_a?(String)
+          raise ArgumentError, "configuration #{index} format must be a Symbol or String"
+        end
+
+        # Validate log levels if specified
+        if config[:min_level] && !valid_log_level?(config[:min_level])
+          raise ArgumentError, "configuration #{index} min_level must be a valid log level"
+        end
+
+        if config[:max_level] && !valid_log_level?(config[:max_level])
+          raise ArgumentError, "configuration #{index} max_level must be a valid log level"
+        end
+
+        # Validate rotation if specified
+        if config[:rotation] && !valid_rotation_config?(config[:rotation])
+          raise ArgumentError, "configuration #{index} rotation must be a valid rotation configuration"
+        end
+      end
+
+      # Check if log level is valid
+      #
+      # @param level [Symbol] log level to check
+      # @return [Boolean] true if valid
+      def valid_log_level?(level)
+        %i[debug info warn error fatal success].include?(level)
+      end
+
+      # Check if rotation configuration is valid
+      #
+      # @param rotation [Hash] rotation configuration
+      # @return [Boolean] true if valid
+      def valid_rotation_config?(rotation)
+        return false unless rotation.is_a?(Hash)
+
+        valid_keys = [:max_size, :max_files, :compress, :pattern]
+        rotation.keys.all? { |key| valid_keys.include?(key) }
+      end
+    end
+  end
+end

data/lib/makit/logging/format_registry.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Makit
+  module Logging
+    # Registry for managing available log formatters
+    #
+    # Provides a centralized way to register, retrieve, and manage formatters
+    # by name. This allows for easy extension and configuration of formatters.
+    #
+    # @example Registering a custom formatter
+    #   FormatRegistry.register(:audit, AuditFormatter)
+    #   formatter = FormatRegistry.get(:audit).new
+    #
+    # @example Using built-in formatters
+    #   formatter = FormatRegistry.get(:json).new
+    #   formatter = FormatRegistry.get(:text).new(timestamp_format: "%H:%M:%S")
+    class FormatRegistry
+      @formatters = {}
+
+      class << self
+        # @return [Hash] registered formatters
+        attr_reader :formatters
+
+        # Register a formatter class with a name
+        #
+        # @param name [Symbol, String] the name to register the formatter under
+        # @param formatter_class [Class] the formatter class to register
+        # @return [void]
+        def register(name, formatter_class)
+          @formatters[name.to_sym] = formatter_class
+        end
+
+        # Get a formatter class by name
+        #
+        # @param name [Symbol, String] the name of the formatter
+        # @return [Class] the formatter class
+        # @raise [ArgumentError] if formatter is not found
+        def get(name)
+          @formatters[name.to_sym] || raise(ArgumentError, "Unknown formatter: #{name}")
+        end
+
+        # Get all available formatter names
+        #
+        # @return [Array<Symbol>] list of registered formatter names
+        def available_formats
+          @formatters.keys
+        end
+
+        # Check if a formatter is registered
+        #
+        # @param name [Symbol, String] the name to check
+        # @return [Boolean] true if formatter is registered
+        def registered?(name)
+          @formatters.key?(name.to_sym)
+        end
+
+        # Clear all registered formatters
+        #
+        # @return [void]
+        def clear
+          @formatters.clear
+        end
+
+        # Register built-in formatters
+        #
+        # @return [void]
+        def register_built_ins
+          require_relative "formatters/json_formatter"
+          require_relative "formatters/text_formatter"
+          require_relative "formatters/plain_text_formatter"
+          require_relative "formatters/console_formatter"
+
+          register(:json, Formatters::JsonFormatter)
+          register(:text, Formatters::TextFormatter)
+          register(:plain, Formatters::PlainTextFormatter)
+          register(:console, Formatters::ConsoleFormatter)
+        end
+      end
+
+      # Initialize registry with built-in formatters
+      register_built_ins
+    end
+  end
+end

data/lib/makit/logging/formatters/base.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Makit
+  module Logging
+    module Formatters
+      # Base class for all logging formatters
+      #
+      # Formatters handle the conversion of log requests into formatted strings
+      # that can be written to various outputs (console, files, etc.).
+      # This separates formatting concerns from output routing concerns.
+      #
+      # @example Creating a custom formatter
+      #   class CustomFormatter < Base
+      #     def format(log_request)
+      #       "#{log_request.level.upcase}: #{log_request.message}"
+      #     end
+      #   end
+      class Base
+        # Format a log request into a string
+        #
+        # @param log_request [LogRequest] the log request to format
+        # @return [String] the formatted log entry
+        def format(log_request)
+          raise NotImplementedError, "Subclasses must implement #format"
+        end
+
+        # Get formatter configuration
+        #
+        # @return [Hash] formatter configuration
+        def config
+          {
+            name: self.class.name.split("::").last,
+            type: self.class.name,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/makit/logging/formatters/console_formatter.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "colorize"
+require_relative "base"
+
+module Makit
+  module Logging
+    module Formatters
+      # Console formatter for colored log output
+      #
+      # Formats log requests for console display with colors, symbols, and optional
+      # timestamps/levels. This is specifically designed for human-readable console output.
+      #
+      # @example
+      #   formatter = ConsoleFormatter.new
+      #   formatted = formatter.format(log_request)
+      #   # => "→ Processing started" (with appropriate color)
+      class ConsoleFormatter < Base
+        # @return [Boolean] whether to show timestamps
+        attr_reader :show_timestamp
+        # @return [Boolean] whether to show log levels
+        attr_reader :show_level
+
+        # Initialize console formatter
+        #
+        # @param show_timestamp [Boolean] whether to show timestamps (default: false)
+        # @param show_level [Boolean] whether to show log levels (default: false)
+        def initialize(show_timestamp: false, show_level: false)
+          @show_timestamp = show_timestamp
+          @show_level = show_level
+        end
+
+        # Format log request for console display
+        #
+        # @param log_request [LogRequest] the log request to format
+        # @return [String] console formatted log entry with colors
+        def format(log_request)
+          parts = []
+
+          # Add timestamp if enabled
+          if @show_timestamp
+            timestamp = log_request.timestamp.strftime("%H:%M:%S")
+            parts << "[#{timestamp}]".colorize(:light_black)
+          end
+
+          # Add log level if enabled
+          if @show_level
+            level_str = log_request.level.to_s.upcase
+            level_color = get_level_color(log_request.level)
+            parts << level_str.colorize(level_color)
+          end
+
+          # Add symbol and message
+          symbol = get_level_symbol(log_request.level)
+          symbol_color = get_level_color(log_request.level)
+          message = log_request.message
+
+          # Add context if present
+          if !log_request.context.empty?
+            context_str = log_request.context.map { |k, v| "#{k}=#{v}" }.join(" ")
+            message += " #{context_str}".colorize(:light_black)
+          end
+
+          parts << "#{symbol} #{message}".colorize(symbol_color)
+
+          parts.join(" ")
+        end
+
+        # Get formatter configuration
+        #
+        # @return [Hash] formatter configuration
+        def config
+          super.merge(
+            show_timestamp: @show_timestamp,
+            show_level: @show_level,
+          )
+        end
+
+        private
+
+        # Get the color for a log level
+        #
+        # @param level [Symbol] the log level
+        # @return [Symbol] the color for the level
+        def get_level_color(level)
+          case level
+          when :debug
+            :grey
+          when :info
+            :grey
+          when :warn
+            :light_yellow
+          when :error, :fatal
+            :light_red
+          when :success
+            :green
+          else
+            :white
+          end
+        end
+
+        # Get the symbol for a log level
+        #
+        # @param level [Symbol] the log level
+        # @return [String] the symbol for the level
+        def get_level_symbol(level)
+          case level
+          when :debug
+            "•"
+          when :info
+            " " #"→"
+          when :warn
+            "!" #"⚠"
+          when :error
+            "✗"
+          when :fatal
+            "💀"
+          when :success
+            "✓"
+          else
+            "•"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/makit/logging/formatters/json_formatter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+
+module Makit
+  module Logging
+    module Formatters
+      # JSON formatter for structured logging
+      #
+      # Formats log requests as JSON objects with timestamp, level, message, and context.
+      # This is ideal for log aggregation systems and structured data analysis.
+      #
+      # @example
+      #   formatter = JsonFormatter.new
+      #   formatted = formatter.format(log_request)
+      #   # => '{"timestamp":"2024-01-15T10:30:45Z","level":"INFO","message":"User logged in","context":{"user_id":123}}'
+      class JsonFormatter < Base
+        # @return [Hash] additional options for JSON formatting
+        attr_reader :options
+
+        # Initialize JSON formatter
+        #
+        # @param options [Hash] JSON generation options
+        def initialize(options: {})
+          @options = {
+            indent: nil,
+            space: nil,
+            space_before: nil,
+            object_nl: nil,
+            array_nl: nil,
+            allow_nan: false,
+            max_nesting: 100,
+          }.merge(options)
+        end
+
+        # Format log request as JSON
+        #
+        # @param log_request [LogRequest] the log request to format
+        # @return [String] JSON formatted log entry
+        def format(log_request)
+          log_data = {
+            timestamp: log_request.timestamp.iso8601,
+            level: log_request.level.to_s.upcase,
+            message: log_request.message,
+          }
+
+          # Add context if present
+          log_data[:context] = log_request.context unless log_request.context.empty?
+
+          JSON.generate(log_data, @options)
+        end
+
+        # Get formatter configuration
+        #
+        # @return [Hash] formatter configuration including JSON options
+        def config
+          super.merge(
+            json_options: @options,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/makit/logging/formatters/plain_text_formatter.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Makit
+  module Logging
+    module Formatters
+      # Plain text formatter with just the message
+      #
+      # Formats log requests as plain text containing only the message content.
+      # This is useful for simple log files where only the message matters.
+      #
+      # @example
+      #   formatter = PlainTextFormatter.new
+      #   formatted = formatter.format(log_request)
+      #   # => 'User logged in'
+      class PlainTextFormatter < Base
+        # @return [Boolean] whether to include context in output
+        attr_reader :include_context
+
+        # Initialize plain text formatter
+        #
+        # @param include_context [Boolean] whether to include context in output
+        def initialize(include_context: false)
+          @include_context = include_context
+        end
+
+        # Format log request as plain text
+        #
+        # @param log_request [LogRequest] the log request to format
+        # @return [String] plain text formatted log entry
+        def format(log_request)
+          message = log_request.message
+
+          # Add context if enabled and present
+          if @include_context && !log_request.context.empty?
+            # Create a more readable context representation
+            context_parts = log_request.context.map do |k, v|
+              # Format values nicely based on their type
+              formatted_value = case v
+                when String
+                  v.include?(" ") ? "\"#{v}\"" : v
+                when Hash, Array
+                  v.inspect
+                when Time
+                  v.strftime("%Y-%m-%d %H:%M:%S")
+                else
+                  v.to_s
+                end
+              "#{k}: #{formatted_value}"
+            end
+
+            context_str = context_parts.join(", ")
+            message += " (#{context_str})"
+          end
+
+          message
+        end
+
+        # Get formatter configuration
+        #
+        # @return [Hash] formatter configuration
+        def config
+          super.merge(
+            include_context: @include_context,
+          )
+        end
+      end
+    end
+  end
+end