makit 0.0.98 → 0.0.111

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Makit
+  module Logging
+    module Formatters
+      # Text formatter with timestamp and log level
+      #
+      # Formats log requests as human-readable text with timestamp, log level,
+      # and message. This is the most common format for traditional log files.
+      #
+      # @example
+      #   formatter = TextFormatter.new
+      #   formatted = formatter.format(log_request)
+      #   # => '[2024-01-15 10:30:45] INFO User logged in'
+      class TextFormatter < Base
+        # @return [String] timestamp format string
+        attr_reader :timestamp_format
+        # @return [Boolean] whether to include context in output
+        attr_reader :include_context
+
+        # Initialize text formatter
+        #
+        # @param timestamp_format [String] strftime format for timestamps
+        # @param include_context [Boolean] whether to include context in output
+        def initialize(timestamp_format: "%Y-%m-%d %H:%M:%S", include_context: false)
+          @timestamp_format = timestamp_format
+          @include_context = include_context
+        end
+
+        # Format log request as text
+        #
+        # @param log_request [LogRequest] the log request to format
+        # @return [String] text formatted log entry
+        def format(log_request)
+          timestamp = log_request.timestamp.strftime(@timestamp_format)
+          level = log_request.level.to_s.upcase
+          message = log_request.message
+
+          formatted = "[#{timestamp}] #{level} #{message}"
+
+          # Add context if enabled and present
+          if @include_context && !log_request.context.empty?
+            context_str = log_request.context.map { |k, v| "#{k}=#{v}" }.join(" ")
+            formatted += " #{context_str}"
+          end
+
+          formatted
+        end
+
+        # Get formatter configuration
+        #
+        # @return [Hash] formatter configuration
+        def config
+          super.merge(
+            timestamp_format: @timestamp_format,
+            include_context: @include_context,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/makit/logging/log_request.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Makit
+  module Logging
+    # Represents a log request that flows through the logging middleware chain
+    #
+    # This class encapsulates all the information needed for a log entry,
+    # including the log level, message, context, and metadata. It provides
+    # a clean interface for middleware to process and modify log information.
+    #
+    # @example Basic usage
+    #   request = LogRequest.new(:info, "Processing started")
+    #   request.add_metadata(process_id: 12345)
+    #   puts request.to_h
+    #
+    # @example With context
+    #   request = LogRequest.new(:error, "Build failed", {
+    #     repository: "user/repo",
+    #     commit: "abc123"
+    #   })
+    class LogRequest
+      # @return [Symbol] the log level (:debug, :info, :warn, :error, :fatal, :success)
+      attr_reader :level
+
+      # @return [String] the log message
+      attr_reader :message
+
+      # @return [Hash] additional context information
+      attr_reader :context
+
+      # @return [Hash] metadata about the log entry
+      attr_reader :metadata
+
+      # @return [Time] when the log request was created
+      attr_reader :timestamp
+
+      # Initialize a new log request
+      #
+      # @param level [Symbol] the log level
+      # @param message [String] the log message
+      # @param context [Hash] additional context information
+      def initialize(level, message, context = {})
+        @level = level
+        @message = message
+        @context = context.dup
+        @metadata = {}
+        @timestamp = Time.now
+      end
+
+      # Add metadata to the log request
+      #
+      # @param data [Hash] metadata to add
+      # @return [void]
+      def add_metadata(data)
+        @metadata.merge!(data)
+      end
+
+      # Convert the log request to a hash representation
+      #
+      # @return [Hash] hash representation of the log request
+      def to_h
+        {
+          level: @level,
+          message: @message,
+          context: @context,
+          metadata: @metadata,
+          timestamp: @timestamp.iso8601,
+        }
+      end
+
+      # Convert the log request to a JSON string
+      #
+      # @return [String] JSON representation of the log request
+      def to_json
+        require "json"
+        JSON.generate(to_h)
+      end
+
+      # Get a formatted string representation
+      #
+      # @return [String] formatted string representation
+      def to_s
+        "[#{@timestamp.strftime("%Y-%m-%d %H:%M:%S")}] #{@level.to_s.upcase}: #{@message}"
+      end
+
+      # Check if this is an error level log
+      #
+      # @return [Boolean] true if error level
+      def error?
+        @level == :error || @level == :fatal
+      end
+
+      # Check if this is a success level log
+      #
+      # @return [Boolean] true if success level
+      def success?
+        @level == :success
+      end
+
+      # Check if this is an info level log
+      #
+      # @return [Boolean] true if info level
+      def info?
+        @level == :info
+      end
+
+      # Check if this is a warning level log
+      #
+      # @return [Boolean] true if warn level
+      def warn?
+        @level == :warn
+      end
+    end
+  end
+end

data/lib/makit/logging/logger.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "log_request"
+require_relative "sinks/base"
+require_relative "sinks/console"
+require_relative "sinks/file_sink"
+require_relative "sinks/structured"
+
+module Makit
+  module Logging
+    # Main logger class that orchestrates logging through sinks
+    #
+    # This class provides a clean interface for logging with support for
+    # sink-based output processing. It follows the same pattern as the
+    # Commands::Runner but for logging operations.
+    #
+    # @example Basic usage
+    #   logger = Logger.new
+    #   logger.info("Processing started")
+    #
+    # @example With custom sinks
+    #   logger = Logger.new(
+    #     sinks: [
+    #       Sinks::Console.new,
+    #       Sinks::File.new(log_file: "custom.log")
+    #     ]
+    #   )
+    #
+    # @example Using convenience methods
+    #   logger.success("Build completed")
+    #   logger.error("Build failed", { repository: "user/repo" })
+    class Logger
+      # @return [Array<Sinks::Base>] list of sinks to process log requests
+      attr_reader :sinks
+      # @return [Symbol] minimum log level for filtering
+      attr_reader :level
+
+      # Initialize the logger with sinks and log level
+      #
+      # @param sinks [Array<Sinks::Base>] list of sinks to use
+      # @param level [Symbol] minimum log level (:debug, :info, :warn, :error, :fatal, :success)
+      def initialize(sinks: [], level: :info)
+        @sinks = sinks
+        @level = level
+        @logged_tasks = Set.new
+      end
+
+      # Log a message with the specified level
+      #
+      # @param level [Symbol] the log level (:debug, :info, :warn, :error, :fatal, :success)
+      # @param message [String] the log message
+      # @param context [Hash] additional context information
+      # @return [void]
+      def log(level, message, context = {})
+        return unless should_log?(level)
+
+        log_request = LogRequest.new(level, message, context)
+        execute_sinks(log_request)
+      end
+
+      # Log an info message
+      #
+      # @param message [String] the log message
+      # @param context [Hash] additional context information
+      # @return [void]
+      def info(message, context = {})
+        log(:info, message, context)
+      end
+
+      # Log a success message
+      #
+      # @param message [String] the log message
+      # @param context [Hash] additional context information
+      # @return [void]
+      def success(message, context = {})
+        log(:success, message, context)
+      end
+
+      # Log an error message
+      #
+      # @param message [String] the log message
+      # @param context [Hash] additional context information
+      # @return [void]
+      def error(message, context = {})
+        log(:error, message, context)
+      end
+
+      # Log a warning message
+      #
+      # @param message [String] the log message
+      # @param context [Hash] additional context information
+      # @return [void]
+      def warn(message, context = {})
+        log(:warn, message, context)
+      end
+
+      # Log a debug message
+      #
+      # @param message [String] the log message
+      # @param context [Hash] additional context information
+      # @return [void]
+      def debug(message, context = {})
+        log(:debug, message, context)
+      end
+
+      # Log a fatal message
+      #
+      # @param message [String] the log message
+      # @param context [Hash] additional context information
+      # @return [void]
+      def fatal(message, context = {})
+        log(:fatal, message, context)
+      end
+
+      def task_start(message, context = {})
+        return if @logged_tasks.include?(message)
+        @logged_tasks.add(message)
+        log(:info, message, context)
+      end
+
+      # Get logger configuration
+      #
+      # @return [Hash] logger configuration
+      def config
+        {
+          level: @level,
+          sinks_count: @sinks.length,
+          sinks: @sinks.map(&:config),
+        }
+      end
+
+      private
+
+      # Check if a log level should be processed
+      #
+      # @param level [Symbol] the log level to check
+      # @return [Boolean] true if the level should be logged
+      def should_log?(level)
+        levels = [:debug, :info, :warn, :error, :fatal, :success]
+        levels.index(level) >= levels.index(@level)
+      end
+
+      # Execute the sink chain for a log request
+      #
+      # @param log_request [LogRequest] the log request to process
+      # @return [void]
+      def execute_sinks(log_request)
+        # Filter applicable sinks
+        applicable_sinks = @sinks.select { |s| s.applicable?(log_request) }
+
+        # Execute sink chain
+        applicable_sinks.reduce(log_request) do |request, sink|
+          sink.call(request)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Makit
+  module Logging
+    module Sinks
+      # Base class for all logging sinks
+      #
+      # Sinks provide a way to output log requests to various destinations like
+      # console, files, or external services. This follows the same pattern as
+      # the commands middleware but focuses on output rather than transformation.
+      #
+      # @example Creating a custom logging sink
+      #   class CustomSink < Base
+      #     def call(log_request, &block)
+      #       # Output the log request
+      #       output_log(log_request)
+      #
+      #       # Continue to next sink
+      #       block.call(log_request) if block_given?
+      #     end
+      #   end
+      class Base
+        # Execute sink logic
+        #
+        # This method must be implemented by subclasses to provide the actual
+        # sink functionality. The pattern is to output the log request to the
+        # destination, then call the block to continue the sink chain.
+        #
+        # @param log_request [LogRequest] the log request to process
+        # @yield [LogRequest] yields the processed log request to the next sink
+        # @yieldreturn [LogRequest] the processed log request
+        # @return [LogRequest] the final processed log request
+        # @raise [NotImplementedError] if not overridden by subclass
+        def call(log_request, &block)
+          raise NotImplementedError, "#{self.class.name} must implement #call"
+        end
+
+        # Check if this sink should be applied to the given log request
+        #
+        # Override this method to provide conditional sink application
+        # based on log request properties like level, message, or context.
+        #
+        # @param log_request [LogRequest] the log request
+        # @return [Boolean] true if sink should be applied
+        def applicable?(log_request)
+          true
+        end
+
+        # Get sink name for logging and debugging
+        #
+        # @return [String] sink name
+        def name
+          self.class.name.split("::").last
+        end
+
+        # Get sink configuration
+        #
+        # Override this method to provide sink-specific configuration.
+        #
+        # @return [Hash] sink configuration
+        def config
+          {}
+        end
+
+        private
+
+        # Pre-process the log request before outputting
+        #
+        # Override this method to modify the log request before it is output
+        # to the destination.
+        #
+        # @param log_request [LogRequest] the log request
+        # @return [LogRequest] the modified log request
+        def pre_process(log_request)
+          log_request
+        end
+
+        # Post-process the log request after outputting
+        #
+        # Override this method to perform any final processing after the
+        # log request has been output to the destination.
+        #
+        # @param log_request [LogRequest] the log request
+        # @return [LogRequest] the final log request
+        def post_process(log_request)
+          log_request
+        end
+      end
+    end
+  end
+end

data/lib/makit/logging/sinks/console.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "unified_file_sink"
+
+module Makit
+  module Logging
+    module Sinks
+      # Console sink for clean, colored log output
+      #
+      # This is a thin wrapper around UnifiedFileSink that provides a simple
+      # API for console output. It maintains backward compatibility while
+      # leveraging the unified logging architecture.
+      #
+      # @example Basic usage
+      #   console = Console.new
+      #   logger = Logger.new(sinks: [console])
+      #   logger.info("Processing started")
+      #   # Shows: → Processing started
+      #
+      # @example With custom formatter options
+      #   console = Console.new(show_timestamp: true, show_level: true)
+      #
+      # @example With custom formatter
+      #   console = Console.new(formatter: :text)
+      class Console < UnifiedFileSink
+        # @return [Symbol] the format being used
+        attr_reader :format
+
+        # Initialize console sink
+        #
+        # @param formatter [Symbol, String] formatter name (default: :console)
+        # @param show_timestamp [Boolean] whether to show timestamps (default: false)
+        # @param show_level [Boolean] whether to show log levels (default: false)
+        # @param formatter_options [Hash] additional formatter options
+        def initialize(formatter: :console, show_timestamp: false, show_level: false, **formatter_options)
+          @format = formatter.to_sym
+
+          # Build configuration for UnifiedFileSink
+          configuration = {
+            file: $stdout,
+            format: @format,
+            formatter_options: {
+              show_timestamp: show_timestamp,
+              show_level: show_level,
+            }.merge(formatter_options),
+          }
+
+          super(configurations: [configuration])
+        end
+
+        # Get sink configuration
+        #
+        # @return [Hash] sink configuration
+        def config
+          {
+            name: self.class.name.split("::").last,
+            format: @format,
+            colors_enabled: true,
+            unified_sink: true,
+          }
+        end
+
+        # Check if this is a console sink (for compatibility)
+        #
+        # @return [Boolean] always true for Console sink
+        def console?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/makit/logging/sinks/file_sink.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "unified_file_sink"
+
+module Makit
+  module Logging
+    module Sinks
+      # File sink for writing log entries to files
+      #
+      # This sink is a thin wrapper around UnifiedFileSink that provides
+      # a simpler API for single-file logging. It maintains backward compatibility
+      # with the original FileSink interface while leveraging the more robust
+      # UnifiedFileSink implementation.
+      #
+      # @example Basic usage with default JSON formatter
+      #   file_sink = FileSink.new(log_file: "makit.log")
+      #   logger = Logger.new(sinks: [file_sink])
+      #   logger.info("Processing started")
+      #
+      # @example Using built-in formatters
+      #   file_sink = FileSink.new(
+      #     log_file: "makit.log",
+      #     formatter: :text
+      #   )
+      #
+      # @example Using custom formatter options
+      #   file_sink = FileSink.new(
+      #     log_file: "makit.log",
+      #     formatter: :json,
+      #     include_context: true,
+      #     include_metadata: true
+      #   )
+      class FileSink < Base
+        # @return [String] path to the log file
+        attr_reader :log_file
+        # @return [Symbol] the formatter format name
+        attr_reader :formatter
+        # @return [Boolean] whether to append to existing file (true) or overwrite (false)
+        attr_reader :append
+        # @return [UnifiedFileSink] the underlying unified sink
+        attr_reader :unified_sink
+
+        # Initialize file sink
+        #
+        # @param log_file [String] path to the log file
+        # @param formatter [Symbol, String] formatter format name
+        # @param append [Boolean] whether to append to existing file (true) or overwrite (false)
+        # @param include_context [Boolean] whether to include context in formatted output
+        # @param include_metadata [Boolean] whether to include metadata in formatted output
+        # @param show_timestamp [Boolean] whether to show timestamp in formatted output
+        # @param show_level [Boolean] whether to show log level in formatted output
+        def initialize(log_file: "makit.log", formatter: :json, append: true, **formatter_options)
+          @log_file = log_file
+          @formatter = formatter.to_sym
+          @append = append
+
+          # Create unified sink configuration
+          config = {
+            file: @log_file,
+            format: @formatter,
+            append: @append,
+          }.merge(formatter_options)
+
+          @unified_sink = UnifiedFileSink.new(configurations: [config])
+        end
+
+        # Execute sink logic to write log entry to file
+        #
+        # @param log_request [LogRequest] the log request to process
+        # @yield [LogRequest] yields the processed log request to the next sink
+        # @yieldreturn [LogRequest] the processed log request
+        # @return [LogRequest] the final processed log request
+        def call(log_request, &block)
+          @unified_sink.call(log_request, &block)
+        end
+
+        # Get sink configuration
+        #
+        # @return [Hash] sink configuration
+        def config
+          {
+            name: self.class.name.split("::").last,
+            log_file: @log_file,
+            formatter: @formatter,
+            append: @append,
+            unified_config: @unified_sink.config,
+          }
+        end
+      end
+    end
+  end
+end