makit 0.0.140 → 0.0.142

data/lib/makit/logging.rb

@@ -1,565 +1,565 @@
-# frozen_string_literal: true
-
-require "logger"
-begin
-  require "colorize"
-rescue LoadError
-  # colorize gem not available, define a no-op colorize method
-  class String
-    def colorize(*_args)
-      self
-    end
-  end
-end
-require_relative "symbols"
-require_relative "logging/logger"
-require_relative "logging/log_request"
-require_relative "logging/sinks/base"
-require_relative "logging/sinks/console"
-require_relative "logging/sinks/file_sink"
-require_relative "logging/sinks/structured"
-require_relative "logging/sinks/unified_file_sink"
-require_relative "logging/configuration"
-
-# This module provides classes for the Makit gem.
-module Makit
-  # Logging infrastructure for the Makit gem
-  #
-  # This module provides a comprehensive logging system with multiple formatters,
-  # multi-target output capabilities, and configurable log levels. It supports:
-  #
-  # - Plain text logging (suitable for files)
-  # - Colored console output (improved terminal readability)
-  # - Structured JSON logging (machine-parsable format)
-  # - Multi-target logging (write to multiple destinations simultaneously)
-  # - Sink-based output processing (similar to Commands::Runner)
-  #
-  # @deprecated The legacy MultiLogger, Formatter classes, and create_logger method
-  #   are deprecated and will be removed in version 0.2.0. Use the new Logger class
-  #   with sinks instead.
-  #
-  # @example Basic usage with new architecture (recommended)
-  #   Makit::Logging.info("Application started")
-  #   Makit::Logging.success("Build completed")
-  #   Makit::Logging.error("Something went wrong")
-  #
-  # @example Custom logger configuration
-  #   logger = Makit::Logging::Logger.new(
-  #     sinks: [
-  #       Makit::Logging::Sinks::Console.new,
-  #       Makit::Logging::Sinks::FileSink.new(log_file: "custom.log")
-  #     ]
-  #   )
-  #   logger.info("Custom message")
-  #
-  # @example Legacy usage (deprecated - will be removed in v0.2.0)
-  #   logger = Makit::Logging::MultiLogger.create_logger
-  #   logger.info("Application started")
-  #   logger.error("Something went wrong")
-  module Logging
-    ANSI_COLOR_REGEX = /\e\[[0-9;]*m/
-
-    # Log levels that can be configured
-    LOG_LEVELS = {
-      debug: ::Logger::DEBUG,
-      info: ::Logger::INFO,
-      warn: ::Logger::WARN,
-      error: ::Logger::ERROR,
-      fatal: ::Logger::FATAL,
-    }.freeze
-
-    # Default log level
-    DEFAULT_LOG_LEVEL = :info
-
-    # Get the current log level from environment or use default
-    def self.current_log_level
-      env_level = ENV["LOG_LEVEL"]&.downcase&.to_sym
-      return env_level if env_level && LOG_LEVELS.key?(env_level)
-
-      DEFAULT_LOG_LEVEL
-    end
-
-    # Get the current verbosity level from environment or use default
-    def self.current_verbosity
-      env_verbosity = ENV["VERBOSITY"]&.downcase&.to_sym
-      return env_verbosity if env_verbosity && %i[quiet normal verbose debug].include?(env_verbosity)
-
-      :normal
-    end
-
-    # Get the current verbosity level from the default logger
-    #
-    # @return [Symbol] current verbosity level (:quiet, :normal, :verbose, :debug)
-    def self.verbosity
-      DEFAULT_LOGGER.verbosity
-    end
-
-    # Logs the duration of a rake task to a file
-    #
-    # This method calculates the elapsed time since the STARTTIME constant was set
-    # and appends this information to a log file. Used to track performance of rake tasks.
-    #
-    # @return [nil]
-    def self.log_rake_duration
-      # use the STARTTIME constant to log the duration of the rake task
-      # to the log/rake.duration.txt file
-      duration = Time.now - STARTTIME
-      FileUtils.mkdir_p("log")
-      File.open("log/rake.duration.txt", "a") do |file|
-        file.puts "Rake task duration: #{duration} seconds"
-      end
-    end
-
-    # Plain text log formatter that strips ANSI color codes
-    #
-    # This formatter removes color codes from log messages and provides
-    # clean, plain text output suitable for file logging or systems
-    # that don't support color output.
-    #
-    # @deprecated This class is deprecated and will be removed in version 0.2.0.
-    #   Use Makit::Logging::Logger with Makit::Logging::Sinks::FileSink instead.
-    class PlainFormatter < ::Logger::Formatter
-      # Format a log message as plain text
-      #
-      # @param severity [String] log level (DEBUG, INFO, WARN, ERROR, FATAL)
-      # @param time [Time] timestamp of the log message
-      # @param _progname [String] program name (unused)
-      # @param msg [String] the log message content
-      # @return [String] formatted plain text log entry
-      def call(severity, time, _progname, msg)
-        warn "Makit::Logging::PlainFormatter is deprecated and will be removed in version 0.2.0. Use Makit::Logging::Logger with Makit::Logging::Sinks::FileSink instead."
-        stripped_msg = msg.gsub(ANSI_COLOR_REGEX, "") # Remove ANSI color codes
-        timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
-        "[#{timestamp}] #{severity}: #{stripped_msg}\n"
-      end
-    end
-
-    # Colored log formatter for terminal output
-    #
-    # This formatter adds appropriate colors to different log levels
-    # to improve readability in terminal environments. Colors are:
-    # DEBUG (light blue), INFO (green), WARN (yellow), ERROR (red), FATAL (bold red)
-    #
-    # @deprecated This class is deprecated and will be removed in version 0.2.0.
-    #   Use Makit::Logging::Logger with Makit::Logging::Sinks::Console instead.
-    class ColorFormatter < ::Logger::Formatter
-      # Format a log message with colors
-      #
-      # @param severity [String] log level (DEBUG, INFO, WARN, ERROR, FATAL)
-      # @param time [Time] timestamp of the log message
-      # @param _progname [String] program name (unused)
-      # @param msg [String] the log message content
-      # @return [String] formatted colored log entry
-      def call(severity, time, _progname, msg)
-        warn "Makit::Logging::ColorFormatter is deprecated and will be removed in version 0.2.0. Use Makit::Logging::Logger with Makit::Logging::Sinks::Console instead."
-        timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
-        colored_severity = colorize_severity(severity)
-        "[#{timestamp}] #{colored_severity}: #{msg}\n"
-      end
-
-      private
-
-      def colorize_severity(severity)
-        case severity
-        when "DEBUG"
-          severity.light_blue
-        when "INFO"
-          severity.green
-        when "WARN"
-          severity.yellow
-        when "ERROR"
-          severity.red
-        when "FATAL"
-          severity.red.bold
-        else
-          severity
-        end
-      end
-    end
-
-    # Structured JSON log formatter
-    #
-    # This formatter outputs log messages as JSON objects with structured
-    # fields including timestamp, level, message, and program name.
-    # Useful for log aggregation systems and machine parsing.
-    #
-    # @deprecated This class is deprecated and will be removed in version 0.2.0.
-    #   Use Makit::Logging::Logger with Makit::Logging::Sinks::FileSink (formatter: :json) instead.
-    class StructuredFormatter < ::Logger::Formatter
-      # Format a log message as JSON
-      #
-      # @param severity [String] log level (DEBUG, INFO, WARN, ERROR, FATAL)
-      # @param time [Time] timestamp of the log message
-      # @param progname [String] program name
-      # @param msg [String] the log message content
-      # @return [String] JSON formatted log entry with newline
-      def call(severity, time, progname, msg)
-        warn "Makit::Logging::StructuredFormatter is deprecated and will be removed in version 0.2.0. Use Makit::Logging::Logger with Makit::Logging::Sinks::FileSink (formatter: :json) instead."
-        timestamp = time.strftime("%Y-%m-%d %H:%M:%S.%L")
-        {
-          timestamp: timestamp,
-          level: severity,
-          message: msg,
-          progname: progname,
-        }.to_json + "\n"
-      end
-    end
-
-    # Multi-target logger that writes to multiple destinations
-    #
-    # This logger allows writing log messages to multiple targets simultaneously,
-    # such as both stdout and a file, or multiple files with different formats.
-    #
-    # @deprecated This class is deprecated and will be removed in version 0.2.0.
-    #   Use Makit::Logging::Logger with multiple middleware instead.
-    #
-    # @example Create a logger that writes to both console and file
-    #   stdout_logger = Logger.new($stdout)
-    #   file_logger = Logger.new("app.log")
-    #   multi_logger = MultiLogger.new(stdout_logger, file_logger)
-    #   multi_logger.info("This goes to both destinations")
-    class MultiLogger
-      # Initialize a new MultiLogger with multiple logging targets
-      #
-      # @param targets [Array<Logger>] One or more logger instances to write to
-      def initialize(*targets)
-        warn "Makit::Logging::MultiLogger is deprecated and will be removed in version 0.2.0. Use Makit::Logging::Logger with middleware instead."
-        @targets = targets
-      end
-
-      # Add a message to all logger targets
-      #
-      # @param severity [Integer] The severity level (::Logger::DEBUG, ::Logger::INFO, etc.)
-      # @param message [String, nil] The message to log (or nil if using block)
-      # @param progname [String, nil] The program name to include in the log
-      # @param block [Proc, nil] Optional block that returns the message to log
-      # @return [nil]
-      def add(severity, message = nil, progname = nil, &block)
-        @targets.each do |logger|
-          logger.add(severity, message, progname, &block)
-          logger.flush if logger.respond_to?(:flush)
-        end
-      end
-
-      # Append a message directly to all logger targets
-      #
-      # @param message [String] The message to append to all loggers
-      # @return [nil]
-      def <<(message)
-        @targets.each do |logger|
-          logger << message
-          logger.flush if logger.respond_to?(:flush)
-        end
-      end
-
-      # Close all logger targets
-      #
-      # @return [nil]
-      def close
-        @targets.each(&:close)
-      end
-
-      # Forward any unknown methods to all logger targets
-      #
-      # This allows calling standard Logger methods like info, debug, error, etc.
-      # directly on the MultiLogger instance.
-      #
-      # @param method [Symbol] The method name to forward
-      # @param args [Array] Arguments to pass to the method
-      # @return [nil]
-      def method_missing(method, ...)
-        @targets.each { |logger| logger.send(method, ...) }
-      end
-
-      # Check if all logger targets respond to a given method
-      #
-      # @param method [Symbol] The method name to check
-      # @param include_private [Boolean] Whether to include private methods
-      # @return [Boolean] True if all logger targets respond to the method
-      def respond_to_missing?(method, include_private = false)
-        @targets.all? { |logger| logger.respond_to?(method, include_private) }
-      end
-
-      # Create a configured logger based on options
-      #
-      # This factory method creates a logger configured with appropriate formatters
-      # and targets based on the provided options. By default, it creates a logger
-      # that writes to both stdout (with colors) and a log file (plain text).
-      #
-      # @deprecated This method is deprecated and will be removed in version 0.2.0.
-      #   Use Makit::Logging::Logger.new with middleware instead.
-      #
-      # @param options [Hash] Logger configuration options
-      # @option options [Symbol] :level (:info) The log level (:debug, :info, :warn, :error, :fatal)
-      # @option options [Boolean] :file_logging (true) Whether to log to a file
-      # @option options [String] :log_file (nil) Custom log file path, defaults to rake task-based path
-      # @option options [Boolean] :structured_logging (false) Whether to use JSON structured logging for file output
-      # @return [Logger, MultiLogger] A configured logger instance
-      def self.create_logger(options = {})
-        warn "Makit::Logging::MultiLogger.create_logger is deprecated and will be removed in version 0.2.0. Use Makit::Logging::Logger.new with middleware instead."
-        log_level = options[:level] || DEFAULT_LOG_LEVEL
-        log_level = LOG_LEVELS[log_level] || LOG_LEVELS[DEFAULT_LOG_LEVEL]
-
-        stdout_logger = ::Logger.new($stdout)
-        stdout_logger.level = log_level
-        stdout_logger.formatter = ColorFormatter.new
-
-        # if clean or clobber commands are used, then log ONLY to stdout
-        return stdout_logger if ARGV.include?("clean") || ARGV.include?("clobber")
-
-        return stdout_logger if Makit::Environment.project_root_directory.nil?
-
-        # Create file logger if logging to file is enabled
-        if options[:file_logging] != false
-          log_filename = create_log_filename(options)
-          file_logger = create_file_logger(log_filename, log_level, options)
-          return MultiLogger.new(file_logger, stdout_logger)
-        end
-
-        stdout_logger
-      end
-
-      # Create a file logger with appropriate formatter
-      #
-      # Creates a logger that writes to a file with the specified formatter
-      # and log level. Ensures the directory for the log file exists.
-      #
-      # @param log_filename [String] Path where log file should be created
-      # @param log_level [Integer] Log level to set (from Logger constants)
-      # @param options [Hash] Configuration options
-      # @option options [Boolean] :structured_logging (false) Whether to use JSON formatted logs
-      # @return [Logger] Configured file logger
-      def self.create_file_logger(log_filename, log_level, options)
-        FileUtils.mkdir_p(File.dirname(log_filename))
-
-        file_logger = ::Logger.new(log_filename)
-        file_logger.level = log_level
-
-        # Use structured logging for file output if requested
-        file_logger.formatter = if options[:structured_logging]
-            StructuredFormatter.new
-          else
-            PlainFormatter.new
-          end
-
-        file_logger
-      end
-
-      # Determine the appropriate log filename
-      #
-      # Generates a log filename based on options and the current rake task.
-      # If a custom log file is specified in options, that is used. Otherwise,
-      # a log file is created in the artifacts directory with a name based on
-      # the current rake task.
-      #
-      # @param options [Hash] Configuration options
-      # @option options [String] :log_file (nil) Custom log file path
-      # @return [String] The path to use for the log file
-      def self.create_log_filename(options)
-        if options[:log_file]
-          options[:log_file]
-        elsif ARGV.empty?
-          "#{Makit::Environment.project_root_directory}/artifacts/rake.log"
-        else
-          task_name = ARGV.join("_").gsub(":", "_")
-          "#{Makit::Environment.project_root_directory}/artifacts/rake_#{task_name}.log"
-        end
-      end
-    end
-
-    # ===== DEPRECATED LEGACY LOGGING =====
-    #
-    # The following classes and methods are deprecated and will be removed in version 0.2.0:
-    # - PlainFormatter
-    # - ColorFormatter
-    # - StructuredFormatter
-    # - MultiLogger
-    # - MultiLogger.create_logger
-    #
-    # MIGRATION GUIDE:
-    #
-    # OLD (deprecated):
-    #   logger = Makit::Logging::MultiLogger.create_logger
-    #   logger.info("message")
-    #
-    # NEW (recommended):
-    #   Makit::Logging.info("message")  # Uses default logger
-    #   # OR
-    #   logger = Makit::Logging::Logger.new(sinks: [...])
-    #   logger.info("message")
-    #
-    # For custom formatting, use sinks:
-    #   logger = Makit::Logging::Logger.new(
-    #     sinks: [
-    #       Makit::Logging::Sinks::Console.new,
-    #       Makit::Logging::Sinks::FileSink.new(log_file: "app.log")
-    #     ]
-    #   )
-
-    # ===== NEW LOGGING ARCHITECTURE =====
-
-    # Default logger with unified file sink
-    # This replaces the previous multi-sink approach with a single, configurable sink
-    DEFAULT_LOGGER = Logger.new(
-      level: current_log_level,
-      verbosity: current_verbosity,
-      sinks: [
-        Sinks::UnifiedFileSink.new(
-          configurations: [
-            # Console output with colors and symbols
-            {
-              file: $stdout,
-              format: :console,
-              show_timestamp: false,
-              show_level: false,
-            },
-            # Main log file in JSON format
-            {
-              file: "artifacts/makit.log",
-              format: :json,
-              append: true,
-              include_metadata: true,
-            },
-            # Debug log file in text format
-            {
-              file: "artifacts/debug.log",
-              format: :text,
-              append: true,
-              min_level: :debug,
-              include_context: true,
-            },
-          ],
-        ),
-      ],
-    )
-
-    # Convenience methods that delegate to the default logger
-    # These provide a simple API for common logging operations
-
-    # Log an info message
-    #
-    # @param message [String] the log message
-    # @param context [Hash] additional context information
-    # @return [void]
-    def self.info(message, context = {})
-      DEFAULT_LOGGER.info(message, context)
-    end
-
-    # Log a success message
-    #
-    # @param message [String] the log message
-    # @param context [Hash] additional context information
-    # @return [void]
-    def self.success(message, context = {})
-      DEFAULT_LOGGER.success(message, context)
-    end
-
-    # Log an error message
-    #
-    # @param message [String] the log message
-    # @param context [Hash] additional context information
-    # @return [void]
-    def self.error(message, context = {})
-      DEFAULT_LOGGER.error(message, context)
-    end
-
-    # Log a warning message
-    #
-    # @param message [String] the log message
-    # @param context [Hash] additional context information
-    # @return [void]
-    def self.warn(message, context = {})
-      DEFAULT_LOGGER.warn(message, context)
-    end
-
-    # Log a debug message
-    #
-    # @param message [String] the log message
-    # @param context [Hash] additional context information
-    # @return [void]
-    def self.debug(message, context = {})
-      DEFAULT_LOGGER.debug(message, context)
-    end
-
-    # Log a fatal message
-    #
-    # @param message [String] the log message
-    # @param context [Hash] additional context information
-    # @return [void]
-    def self.fatal(message, context = {})
-      DEFAULT_LOGGER.fatal(message, context)
-    end
-
-    # Log a verbose message (only shown in verbose or debug mode)
-    #
-    # @param message [String] the log message
-    # @param context [Hash] additional context information
-    # @return [void]
-    def self.verbose(message, context = {})
-      DEFAULT_LOGGER.verbose(message, context)
-    end
-
-    # Log a quiet message (shown even in quiet mode)
-    #
-    # @param message [String] the log message
-    # @param context [Hash] additional context information
-    # @return [void]
-    def self.quiet(message, context = {})
-      DEFAULT_LOGGER.quiet(message, context)
-    end
-
-    # Create a logger with environment-specific configuration
-    #
-    # @param environment [Symbol] environment name (:development, :production, :test, :ci)
-    # @return [Logger] configured logger instance
-    def self.create_logger(environment: :default)
-      config = case environment
-        when :development
-          Configuration.development_config
-        when :production
-          Configuration.production_config
-        when :test
-          Configuration.test_config
-        when :ci
-          Configuration.ci_config
-        else
-          Configuration.default_config
-        end
-
-      Logger.new(
-        sinks: [
-          Sinks::UnifiedFileSink.new(configurations: config.configurations),
-        ],
-      )
-    end
-
-    # Create a logger from configuration file
-    #
-    # @param config_file [String] path to configuration file (YAML or JSON)
-    # @return [Logger] configured logger instance
-    def self.create_logger_from_file(config_file)
-      config = if config_file.end_with?(".yaml") || config_file.end_with?(".yml")
-          Configuration.from_yaml(config_file)
-        elsif config_file.end_with?(".json")
-          Configuration.from_json(config_file)
-        else
-          raise ArgumentError, "Configuration file must be YAML (.yaml/.yml) or JSON (.json)"
-        end
-
-      config.validate!
-
-      Logger.new(
-        sinks: [
-          Sinks::UnifiedFileSink.new(configurations: config.configurations),
-        ],
-      )
-    end
-
-    # Get the default logger instance
-    #
-    # @return [Logger] the default logger
-    def self.default_logger
-      DEFAULT_LOGGER
-    end
-  end
-end
+# frozen_string_literal: true
+
+require "logger"
+begin
+  require "colorize"
+rescue LoadError
+  # colorize gem not available, define a no-op colorize method
+  class String
+    def colorize(*_args)
+      self
+    end
+  end
+end
+require_relative "symbols"
+require_relative "logging/logger"
+require_relative "logging/log_request"
+require_relative "logging/sinks/base"
+require_relative "logging/sinks/console"
+require_relative "logging/sinks/file_sink"
+require_relative "logging/sinks/structured"
+require_relative "logging/sinks/unified_file_sink"
+require_relative "logging/configuration"
+
+# This module provides classes for the Makit gem.
+module Makit
+  # Logging infrastructure for the Makit gem
+  #
+  # This module provides a comprehensive logging system with multiple formatters,
+  # multi-target output capabilities, and configurable log levels. It supports:
+  #
+  # - Plain text logging (suitable for files)
+  # - Colored console output (improved terminal readability)
+  # - Structured JSON logging (machine-parsable format)
+  # - Multi-target logging (write to multiple destinations simultaneously)
+  # - Sink-based output processing (similar to Commands::Runner)
+  #
+  # @deprecated The legacy MultiLogger, Formatter classes, and create_logger method
+  #   are deprecated and will be removed in version 0.2.0. Use the new Logger class
+  #   with sinks instead.
+  #
+  # @example Basic usage with new architecture (recommended)
+  #   Makit::Logging.info("Application started")
+  #   Makit::Logging.success("Build completed")
+  #   Makit::Logging.error("Something went wrong")
+  #
+  # @example Custom logger configuration
+  #   logger = Makit::Logging::Logger.new(
+  #     sinks: [
+  #       Makit::Logging::Sinks::Console.new,
+  #       Makit::Logging::Sinks::FileSink.new(log_file: "custom.log")
+  #     ]
+  #   )
+  #   logger.info("Custom message")
+  #
+  # @example Legacy usage (deprecated - will be removed in v0.2.0)
+  #   logger = Makit::Logging::MultiLogger.create_logger
+  #   logger.info("Application started")
+  #   logger.error("Something went wrong")
+  module Logging
+    ANSI_COLOR_REGEX = /\e\[[0-9;]*m/
+
+    # Log levels that can be configured
+    LOG_LEVELS = {
+      debug: ::Logger::DEBUG,
+      info: ::Logger::INFO,
+      warn: ::Logger::WARN,
+      error: ::Logger::ERROR,
+      fatal: ::Logger::FATAL,
+    }.freeze
+
+    # Default log level
+    DEFAULT_LOG_LEVEL = :info
+
+    # Get the current log level from environment or use default
+    def self.current_log_level
+      env_level = ENV["LOG_LEVEL"]&.downcase&.to_sym
+      return env_level if env_level && LOG_LEVELS.key?(env_level)
+
+      DEFAULT_LOG_LEVEL
+    end
+
+    # Get the current verbosity level from environment or use default
+    def self.current_verbosity
+      env_verbosity = ENV["VERBOSITY"]&.downcase&.to_sym
+      return env_verbosity if env_verbosity && %i[quiet normal verbose debug].include?(env_verbosity)
+
+      :normal
+    end
+
+    # Get the current verbosity level from the default logger
+    #
+    # @return [Symbol] current verbosity level (:quiet, :normal, :verbose, :debug)
+    def self.verbosity
+      DEFAULT_LOGGER.verbosity
+    end
+
+    # Logs the duration of a rake task to a file
+    #
+    # This method calculates the elapsed time since the STARTTIME constant was set
+    # and appends this information to a log file. Used to track performance of rake tasks.
+    #
+    # @return [nil]
+    def self.log_rake_duration
+      # use the STARTTIME constant to log the duration of the rake task
+      # to the log/rake.duration.txt file
+      duration = Time.now - STARTTIME
+      FileUtils.mkdir_p("log")
+      File.open("log/rake.duration.txt", "a") do |file|
+        file.puts "Rake task duration: #{duration} seconds"
+      end
+    end
+
+    # Plain text log formatter that strips ANSI color codes
+    #
+    # This formatter removes color codes from log messages and provides
+    # clean, plain text output suitable for file logging or systems
+    # that don't support color output.
+    #
+    # @deprecated This class is deprecated and will be removed in version 0.2.0.
+    #   Use Makit::Logging::Logger with Makit::Logging::Sinks::FileSink instead.
+    class PlainFormatter < ::Logger::Formatter
+      # Format a log message as plain text
+      #
+      # @param severity [String] log level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param time [Time] timestamp of the log message
+      # @param _progname [String] program name (unused)
+      # @param msg [String] the log message content
+      # @return [String] formatted plain text log entry
+      def call(severity, time, _progname, msg)
+        warn "Makit::Logging::PlainFormatter is deprecated and will be removed in version 0.2.0. Use Makit::Logging::Logger with Makit::Logging::Sinks::FileSink instead."
+        stripped_msg = msg.gsub(ANSI_COLOR_REGEX, "") # Remove ANSI color codes
+        timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
+        "[#{timestamp}] #{severity}: #{stripped_msg}\n"
+      end
+    end
+
+    # Colored log formatter for terminal output
+    #
+    # This formatter adds appropriate colors to different log levels
+    # to improve readability in terminal environments. Colors are:
+    # DEBUG (light blue), INFO (green), WARN (yellow), ERROR (red), FATAL (bold red)
+    #
+    # @deprecated This class is deprecated and will be removed in version 0.2.0.
+    #   Use Makit::Logging::Logger with Makit::Logging::Sinks::Console instead.
+    class ColorFormatter < ::Logger::Formatter
+      # Format a log message with colors
+      #
+      # @param severity [String] log level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param time [Time] timestamp of the log message
+      # @param _progname [String] program name (unused)
+      # @param msg [String] the log message content
+      # @return [String] formatted colored log entry
+      def call(severity, time, _progname, msg)
+        warn "Makit::Logging::ColorFormatter is deprecated and will be removed in version 0.2.0. Use Makit::Logging::Logger with Makit::Logging::Sinks::Console instead."
+        timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
+        colored_severity = colorize_severity(severity)
+        "[#{timestamp}] #{colored_severity}: #{msg}\n"
+      end
+
+      private
+
+      def colorize_severity(severity)
+        case severity
+        when "DEBUG"
+          severity.light_blue
+        when "INFO"
+          severity.green
+        when "WARN"
+          severity.yellow
+        when "ERROR"
+          severity.red
+        when "FATAL"
+          severity.red.bold
+        else
+          severity
+        end
+      end
+    end
+
+    # Structured JSON log formatter
+    #
+    # This formatter outputs log messages as JSON objects with structured
+    # fields including timestamp, level, message, and program name.
+    # Useful for log aggregation systems and machine parsing.
+    #
+    # @deprecated This class is deprecated and will be removed in version 0.2.0.
+    #   Use Makit::Logging::Logger with Makit::Logging::Sinks::FileSink (formatter: :json) instead.
+    class StructuredFormatter < ::Logger::Formatter
+      # Format a log message as JSON
+      #
+      # @param severity [String] log level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param time [Time] timestamp of the log message
+      # @param progname [String] program name
+      # @param msg [String] the log message content
+      # @return [String] JSON formatted log entry with newline
+      def call(severity, time, progname, msg)
+        warn "Makit::Logging::StructuredFormatter is deprecated and will be removed in version 0.2.0. Use Makit::Logging::Logger with Makit::Logging::Sinks::FileSink (formatter: :json) instead."
+        timestamp = time.strftime("%Y-%m-%d %H:%M:%S.%L")
+        {
+          timestamp: timestamp,
+          level: severity,
+          message: msg,
+          progname: progname,
+        }.to_json + "\n"
+      end
+    end
+
+    # Multi-target logger that writes to multiple destinations
+    #
+    # This logger allows writing log messages to multiple targets simultaneously,
+    # such as both stdout and a file, or multiple files with different formats.
+    #
+    # @deprecated This class is deprecated and will be removed in version 0.2.0.
+    #   Use Makit::Logging::Logger with multiple middleware instead.
+    #
+    # @example Create a logger that writes to both console and file
+    #   stdout_logger = Logger.new($stdout)
+    #   file_logger = Logger.new("app.log")
+    #   multi_logger = MultiLogger.new(stdout_logger, file_logger)
+    #   multi_logger.info("This goes to both destinations")
+    class MultiLogger
+      # Initialize a new MultiLogger with multiple logging targets
+      #
+      # @param targets [Array<Logger>] One or more logger instances to write to
+      def initialize(*targets)
+        warn "Makit::Logging::MultiLogger is deprecated and will be removed in version 0.2.0. Use Makit::Logging::Logger with middleware instead."
+        @targets = targets
+      end
+
+      # Add a message to all logger targets
+      #
+      # @param severity [Integer] The severity level (::Logger::DEBUG, ::Logger::INFO, etc.)
+      # @param message [String, nil] The message to log (or nil if using block)
+      # @param progname [String, nil] The program name to include in the log
+      # @param block [Proc, nil] Optional block that returns the message to log
+      # @return [nil]
+      def add(severity, message = nil, progname = nil, &block)
+        @targets.each do |logger|
+          logger.add(severity, message, progname, &block)
+          logger.flush if logger.respond_to?(:flush)
+        end
+      end
+
+      # Append a message directly to all logger targets
+      #
+      # @param message [String] The message to append to all loggers
+      # @return [nil]
+      def <<(message)
+        @targets.each do |logger|
+          logger << message
+          logger.flush if logger.respond_to?(:flush)
+        end
+      end
+
+      # Close all logger targets
+      #
+      # @return [nil]
+      def close
+        @targets.each(&:close)
+      end
+
+      # Forward any unknown methods to all logger targets
+      #
+      # This allows calling standard Logger methods like info, debug, error, etc.
+      # directly on the MultiLogger instance.
+      #
+      # @param method [Symbol] The method name to forward
+      # @param args [Array] Arguments to pass to the method
+      # @return [nil]
+      def method_missing(method, ...)
+        @targets.each { |logger| logger.send(method, ...) }
+      end
+
+      # Check if all logger targets respond to a given method
+      #
+      # @param method [Symbol] The method name to check
+      # @param include_private [Boolean] Whether to include private methods
+      # @return [Boolean] True if all logger targets respond to the method
+      def respond_to_missing?(method, include_private = false)
+        @targets.all? { |logger| logger.respond_to?(method, include_private) }
+      end
+
+      # Create a configured logger based on options
+      #
+      # This factory method creates a logger configured with appropriate formatters
+      # and targets based on the provided options. By default, it creates a logger
+      # that writes to both stdout (with colors) and a log file (plain text).
+      #
+      # @deprecated This method is deprecated and will be removed in version 0.2.0.
+      #   Use Makit::Logging::Logger.new with middleware instead.
+      #
+      # @param options [Hash] Logger configuration options
+      # @option options [Symbol] :level (:info) The log level (:debug, :info, :warn, :error, :fatal)
+      # @option options [Boolean] :file_logging (true) Whether to log to a file
+      # @option options [String] :log_file (nil) Custom log file path, defaults to rake task-based path
+      # @option options [Boolean] :structured_logging (false) Whether to use JSON structured logging for file output
+      # @return [Logger, MultiLogger] A configured logger instance
+      def self.create_logger(options = {})
+        warn "Makit::Logging::MultiLogger.create_logger is deprecated and will be removed in version 0.2.0. Use Makit::Logging::Logger.new with middleware instead."
+        log_level = options[:level] || DEFAULT_LOG_LEVEL
+        log_level = LOG_LEVELS[log_level] || LOG_LEVELS[DEFAULT_LOG_LEVEL]
+
+        stdout_logger = ::Logger.new($stdout)
+        stdout_logger.level = log_level
+        stdout_logger.formatter = ColorFormatter.new
+
+        # if clean or clobber commands are used, then log ONLY to stdout
+        return stdout_logger if ARGV.include?("clean") || ARGV.include?("clobber")
+
+        return stdout_logger if Makit::Environment.project_root_directory.nil?
+
+        # Create file logger if logging to file is enabled
+        if options[:file_logging] != false
+          log_filename = create_log_filename(options)
+          file_logger = create_file_logger(log_filename, log_level, options)
+          return MultiLogger.new(file_logger, stdout_logger)
+        end
+
+        stdout_logger
+      end
+
+      # Create a file logger with appropriate formatter
+      #
+      # Creates a logger that writes to a file with the specified formatter
+      # and log level. Ensures the directory for the log file exists.
+      #
+      # @param log_filename [String] Path where log file should be created
+      # @param log_level [Integer] Log level to set (from Logger constants)
+      # @param options [Hash] Configuration options
+      # @option options [Boolean] :structured_logging (false) Whether to use JSON formatted logs
+      # @return [Logger] Configured file logger
+      def self.create_file_logger(log_filename, log_level, options)
+        FileUtils.mkdir_p(File.dirname(log_filename))
+
+        file_logger = ::Logger.new(log_filename)
+        file_logger.level = log_level
+
+        # Use structured logging for file output if requested
+        file_logger.formatter = if options[:structured_logging]
+            StructuredFormatter.new
+          else
+            PlainFormatter.new
+          end
+
+        file_logger
+      end
+
+      # Determine the appropriate log filename
+      #
+      # Generates a log filename based on options and the current rake task.
+      # If a custom log file is specified in options, that is used. Otherwise,
+      # a log file is created in the artifacts directory with a name based on
+      # the current rake task.
+      #
+      # @param options [Hash] Configuration options
+      # @option options [String] :log_file (nil) Custom log file path
+      # @return [String] The path to use for the log file
+      def self.create_log_filename(options)
+        if options[:log_file]
+          options[:log_file]
+        elsif ARGV.empty?
+          "#{Makit::Environment.project_root_directory}/artifacts/rake.log"
+        else
+          task_name = ARGV.join("_").gsub(":", "_")
+          "#{Makit::Environment.project_root_directory}/artifacts/rake_#{task_name}.log"
+        end
+      end
+    end
+
+    # ===== DEPRECATED LEGACY LOGGING =====
+    #
+    # The following classes and methods are deprecated and will be removed in version 0.2.0:
+    # - PlainFormatter
+    # - ColorFormatter
+    # - StructuredFormatter
+    # - MultiLogger
+    # - MultiLogger.create_logger
+    #
+    # MIGRATION GUIDE:
+    #
+    # OLD (deprecated):
+    #   logger = Makit::Logging::MultiLogger.create_logger
+    #   logger.info("message")
+    #
+    # NEW (recommended):
+    #   Makit::Logging.info("message")  # Uses default logger
+    #   # OR
+    #   logger = Makit::Logging::Logger.new(sinks: [...])
+    #   logger.info("message")
+    #
+    # For custom formatting, use sinks:
+    #   logger = Makit::Logging::Logger.new(
+    #     sinks: [
+    #       Makit::Logging::Sinks::Console.new,
+    #       Makit::Logging::Sinks::FileSink.new(log_file: "app.log")
+    #     ]
+    #   )
+
+    # ===== NEW LOGGING ARCHITECTURE =====
+
+    # Default logger with unified file sink
+    # This replaces the previous multi-sink approach with a single, configurable sink
+    DEFAULT_LOGGER = Logger.new(
+      level: current_log_level,
+      verbosity: current_verbosity,
+      sinks: [
+        Sinks::UnifiedFileSink.new(
+          configurations: [
+            # Console output with colors and symbols
+            {
+              file: $stdout,
+              format: :console,
+              show_timestamp: false,
+              show_level: false,
+            },
+            # Main log file in JSON format
+            {
+              file: "artifacts/makit.log",
+              format: :json,
+              append: true,
+              include_metadata: true,
+            },
+            # Debug log file in text format
+            {
+              file: "artifacts/debug.log",
+              format: :text,
+              append: true,
+              min_level: :debug,
+              include_context: true,
+            },
+          ],
+        ),
+      ],
+    )
+
+    # Convenience methods that delegate to the default logger
+    # These provide a simple API for common logging operations
+
+    # Log an info message
+    #
+    # @param message [String] the log message
+    # @param context [Hash] additional context information
+    # @return [void]
+    def self.info(message, context = {})
+      DEFAULT_LOGGER.info(message, context)
+    end
+
+    # Log a success message
+    #
+    # @param message [String] the log message
+    # @param context [Hash] additional context information
+    # @return [void]
+    def self.success(message, context = {})
+      DEFAULT_LOGGER.success(message, context)
+    end
+
+    # Log an error message
+    #
+    # @param message [String] the log message
+    # @param context [Hash] additional context information
+    # @return [void]
+    def self.error(message, context = {})
+      DEFAULT_LOGGER.error(message, context)
+    end
+
+    # Log a warning message
+    #
+    # @param message [String] the log message
+    # @param context [Hash] additional context information
+    # @return [void]
+    def self.warn(message, context = {})
+      DEFAULT_LOGGER.warn(message, context)
+    end
+
+    # Log a debug message
+    #
+    # @param message [String] the log message
+    # @param context [Hash] additional context information
+    # @return [void]
+    def self.debug(message, context = {})
+      DEFAULT_LOGGER.debug(message, context)
+    end
+
+    # Log a fatal message
+    #
+    # @param message [String] the log message
+    # @param context [Hash] additional context information
+    # @return [void]
+    def self.fatal(message, context = {})
+      DEFAULT_LOGGER.fatal(message, context)
+    end
+
+    # Log a verbose message (only shown in verbose or debug mode)
+    #
+    # @param message [String] the log message
+    # @param context [Hash] additional context information
+    # @return [void]
+    def self.verbose(message, context = {})
+      DEFAULT_LOGGER.verbose(message, context)
+    end
+
+    # Log a quiet message (shown even in quiet mode)
+    #
+    # @param message [String] the log message
+    # @param context [Hash] additional context information
+    # @return [void]
+    def self.quiet(message, context = {})
+      DEFAULT_LOGGER.quiet(message, context)
+    end
+
+    # Create a logger with environment-specific configuration
+    #
+    # @param environment [Symbol] environment name (:development, :production, :test, :ci)
+    # @return [Logger] configured logger instance
+    def self.create_logger(environment: :default)
+      config = case environment
+        when :development
+          Configuration.development_config
+        when :production
+          Configuration.production_config
+        when :test
+          Configuration.test_config
+        when :ci
+          Configuration.ci_config
+        else
+          Configuration.default_config
+        end
+
+      Logger.new(
+        sinks: [
+          Sinks::UnifiedFileSink.new(configurations: config.configurations),
+        ],
+      )
+    end
+
+    # Create a logger from configuration file
+    #
+    # @param config_file [String] path to configuration file (YAML or JSON)
+    # @return [Logger] configured logger instance
+    def self.create_logger_from_file(config_file)
+      config = if config_file.end_with?(".yaml") || config_file.end_with?(".yml")
+          Configuration.from_yaml(config_file)
+        elsif config_file.end_with?(".json")
+          Configuration.from_json(config_file)
+        else
+          raise ArgumentError, "Configuration file must be YAML (.yaml/.yml) or JSON (.json)"
+        end
+
+      config.validate!
+
+      Logger.new(
+        sinks: [
+          Sinks::UnifiedFileSink.new(configurations: config.configurations),
+        ],
+      )
+    end
+
+    # Get the default logger instance
+    #
+    # @return [Logger] the default logger
+    def self.default_logger
+      DEFAULT_LOGGER
+    end
+  end
+end