console 1.29.2 → 1.36.0

data/lib/console/format/safe.rb

@@ -1,29 +1,179 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 
 require "json"
 
 module Console
+	# @namespace
 	module Format
-		# This class is used to safely dump objects.
-		# It will attempt to dump the object using the given format, but if it fails, it will generate a safe version of the object.
+		# A safe format for converting objects to strings.
+		# 
+		# Handles issues like circular references, encoding errors, excessive nesting depth, and excessive output size.
 		class Safe
-			def initialize(format: ::JSON, limit: 8, encoding: ::Encoding::UTF_8)
+			# The JSON fragment used as the truncation marker when dropped fields cannot be named.
+			TRUNCATED = "\"truncated\":true"
+			
+			# Create a new safe format.
+			#
+			# @parameter format [JSON] The format to use for serialization.
+			# @parameter depth_limit [Integer] The maximum depth to recurse into objects (the JSON `max_nesting`).
+			# @parameter size_limit [Integer | Nil] The maximum byte size of the serialized output, or `nil` to disable size limiting. Limits below {TRUNCATED} (the minimal marker) cannot be honoured.
+			# @parameter encoding [Encoding] The encoding to use for strings.
+			# @parameter limit [Integer | Nil] Deprecated alias for `depth_limit`.
+			def initialize(format: ::JSON, depth_limit: 12, size_limit: 16 * 1024, encoding: ::Encoding::UTF_8, limit: nil)
+				if limit
+					warn "Console::Format::Safe `limit:` is deprecated, use `depth_limit:` instead.", uplevel: 1, category: :deprecated
+					depth_limit = limit
+				end
+				
 				@format = format
-				@limit = limit
+				@depth_limit = depth_limit
+				@size_limit = size_limit
 				@encoding = encoding
 			end
 			
+			# @attribute [Integer] The maximum depth to recurse into objects.
+			attr :depth_limit
+			
+			# @attribute [Integer | Nil] The maximum byte size of the serialized output.
+			attr :size_limit
+			
+			# Dump the given object to a string.
+			#
+			# The common case is a single fast serialization. If that fails (e.g. circular
+			# references, excessive nesting, or encoding errors) or its output exceeds
+			# {size_limit}, it falls back to {safe_dump}, which rebuilds the record
+			# field-by-field within the limit.
+			#
+			# @parameter object [Object] The object to dump.
+			# @returns [String] The dumped object.
 			def dump(object)
-				@format.dump(object, @limit)
-			rescue SystemStackError, StandardError => error
-				@format.dump(safe_dump(object, error))
+				buffer = @format.dump(object, @depth_limit)
+				
+				if @size_limit and buffer.bytesize > @size_limit
+					return safe_dump(object)
+				end
+				
+				return buffer
+			rescue SystemStackError, StandardError
+				return safe_dump(object)
 			end
 			
 			private
 			
+			# Produce a safe, size-limited serialization of the given object. This is the
+			# fallback path, used both when direct serialization fails (an exception) and
+			# when its output exceeds {size_limit}.
+			#
+			# Each top-level value is serialized independently and defensively, so a single
+			# un-serializable or oversized value cannot break or bloat the whole record.
+			# Whenever a field is degraded, the reason is recorded in a trailing `"truncated"`
+			# object that maps the field name to why it was truncated:
+			#
+			# - `"key": true` — the value was dropped because it did not fit the size limit.
+			# - `"key": {error}` — the value could not be serialized directly; a safe
+			#   representation was kept in its place and the triggering error is recorded.
+			#
+			# Fields are kept while they fit, always reserving room for at least a minimal
+			# `"truncated":true` marker. The detailed reason map is then emitted only if it
+			# fits in the remaining space; otherwise it degrades to `"truncated":true`. This
+			# is best-effort — in the worst case the per-field detail is lost — but it keeps
+			# the bookkeeping simple and the size guarantee hard.
+			#
+			# @parameter object [Object] The object to serialize.
+			# @returns [String] The safe, size-limited serialized record.
+			def safe_dump(object)
+				# Serialize hash-like objects field-by-field; anything else falls through to the
+				# error handler below, which emits a minimal truncated marker.
+				object = object.to_hash
+				
+				# Serialize each field once, capturing the error for any value that could not be
+				# serialized directly. Our own "truncated" key is skipped so it is never duplicated.
+				errors = {}
+				fragments = []
+				object.each do |key, value|
+					name = key.to_s
+					next if name == "truncated"
+					
+					fragment, error = dump_pair(key, value)
+					errors[name] = error_info(error) if error
+					fragments << [name, fragment]
+				end
+				
+				# Assemble the body, keeping each field while it fits — always reserving room for
+				# at least a minimal `"truncated":true` marker. Each truncated field's reason is
+				# collected: its error (value recovered) or `true` (dropped for size).
+				buffer = +"{"
+				first = true
+				reasons = {}
+				
+				fragments.each do |name, fragment|
+					if buffer.bytesize + (first ? 0 : 1) + fragment.bytesize + TRUNCATED.bytesize + 2 <= @size_limit
+						buffer << "," unless first
+						buffer << fragment
+						first = false
+						
+						# The value was kept; if it had to be recovered, note why.
+						reasons[name] = errors[name] if errors[name]
+					else
+						# The value did not fit and was dropped entirely.
+						reasons[name] = true
+					end
+				end
+				
+				unless reasons.empty?
+					# Include the detailed reasons if they fit, otherwise fall back to the minimal
+					# marker so the truncation is still signalled.
+					detailed = "\"truncated\":#{@format.dump(reasons)}"
+					fits = buffer.bytesize + (first ? 0 : 1) + detailed.bytesize + 1 <= @size_limit
+					
+					buffer << "," unless first
+					buffer << (fits ? detailed : TRUNCATED)
+				end
+				
+				buffer << "}"
+				
+				return buffer
+			rescue SystemStackError, StandardError
+				return "{#{TRUNCATED}}"
+			end
+			
+			# Serialize a single top-level `"key":value` pair, safely handling values that
+			# cannot be serialized directly.
+			#
+			# @parameter key [Object] The field key.
+			# @parameter value [Object] The field value.
+			# @returns [Array(String, Exception | Nil)] The `"key":value` fragment and the error, if recovery was needed.
+			def dump_pair(key, value)
+				value_json, error = dump_value(value)
+				
+				return ["#{dump_string(String(key))}:#{value_json}", error]
+			end
+			
+			# Serialize a single value, falling back to a safe representation on failure.
+			#
+			# @parameter value [Object] The value to serialize.
+			# @returns [Array(String, Exception | Nil)] The serialized value and the error, if recovery was needed.
+			def dump_value(value)
+				[@format.dump(value, @depth_limit), nil]
+			rescue SystemStackError, StandardError => error
+				[@format.dump(safe_dump_recurse(value)), error]
+			end
+			
+			# Serialize a string as a JSON string, encoding it safely first.
+			#
+			# @parameter value [String] The string to serialize.
+			# @returns [String] The serialized (quoted) string.
+			def dump_string(value)
+				@format.dump(value.encode(@encoding, invalid: :replace, undef: :replace))
+			end
+			
+			# Filter the backtrace to remove duplicate frames and reduce verbosity.
+			#
+			# @parameter error [Exception] The exception to filter.
+			# @returns [Array(String)] The filtered backtrace.
 			def filter_backtrace(error)
 				frames = error.backtrace
 				filtered = {}
@@ -61,74 +211,71 @@ module Console
 				return frames
 			end
 			
-			def safe_dump(object, error)
-				object = safe_dump_recurse(object)
-				
-				object[:truncated] = true
-				object[:error] = {
+			# Build a safe, primitive representation of an error for inclusion as an `"error"` field.
+			#
+			# @parameter error [Exception] The error that occurred while dumping the object.
+			# @returns [Hash] The error details (class, message, filtered backtrace).
+			def error_info(error)
+				{
 					class: safe_dump_recurse(error.class.name),
 					message: safe_dump_recurse(error.message),
 					backtrace: safe_dump_recurse(filter_backtrace(error)),
 				}
-				
-				return object
-			end
-			
-			def replacement_for(object)
-				case object
-				when Array
-					"[...]"
-				when Hash
-					"{...}"
-				else
-					"..."
-				end
 			end
 			
+			# Create a new hash with identity comparison.
 			def default_objects
 				Hash.new.compare_by_identity
 			end
 			
-			# This will recursively generate a safe version of the object.
-			# Nested hashes and arrays will be transformed recursively.
-			# Strings will be encoded with the given encoding.
-			# Primitive values will be returned as-is.
-			# Other values will be converted using `as_json` if available, otherwise `to_s`.
-			def safe_dump_recurse(object, limit = @limit, objects = default_objects)
-				if limit <= 0 || objects[object]
-					return replacement_for(object)
-				end
-				
+			# This will recursively generate a safe version of the object. Nested hashes and arrays will be transformed recursively. Strings will be encoded with the given encoding. Primitive values will be returned as-is. Other values will be converted using `as_json` if available, otherwise `to_s`.
+			#
+			# @parameter object [Object] The object to dump.
+			# @parameter limit [Integer] The maximum depth to recurse into objects.
+			# @parameter objects [Hash] The objects that have already been visited.
+			# @returns [Object] The dumped object as a primitive representation.
+			def safe_dump_recurse(object, limit = @depth_limit, objects = default_objects)
 				case object
 				when Hash
-					objects[object] = true
-					
-					object.to_h do |key, value|
-						[
-							String(key).encode(@encoding, invalid: :replace, undef: :replace),
-							safe_dump_recurse(value, limit - 1, objects)
-						]
+					if limit <= 0 || objects[object]
+						return "{...}"
+					else
+						objects[object] = true
+						
+						return object.to_h do |key, value|
+							[
+								String(key).encode(@encoding, invalid: :replace, undef: :replace),
+								safe_dump_recurse(value, limit - 1, objects)
+							]
+						end
 					end
 				when Array
-					objects[object] = true
-					
-					object.map do |value|
-						safe_dump_recurse(value, limit - 1, objects)
+					if limit <= 0 || objects[object]
+						return "[...]"
+					else
+						objects[object] = true
+						
+						return object.map do |value|
+							safe_dump_recurse(value, limit - 1, objects)
+						end
 					end
 				when String
-					object.encode(@encoding, invalid: :replace, undef: :replace)
+					return object.encode(@encoding, invalid: :replace, undef: :replace)
 				when Numeric, TrueClass, FalseClass, NilClass
-					object
+					return object
 				else
-					objects[object] = true
-					
-					# We could do something like this but the chance `as_json` will blow up.
-					# We'd need to be extremely careful about it.
-					# if object.respond_to?(:as_json)
-					# 	safe_dump_recurse(object.as_json, limit - 1, objects)
-					# else
-					
-					safe_dump_recurse(object.to_s, limit - 1, objects)
+					if limit <= 0 || objects[object]
+						return "..."
+					else
+						objects[object] = true
+						
+						# We could do something like this but the chance `as_json` will blow up.
+						# We'd need to be extremely careful about it.
+						# if object.respond_to?(:as_json)
+						# 	safe_dump_recurse(object.as_json, limit - 1, objects)
+						# else
+						return safe_dump_recurse(object.to_s, limit - 1, objects)
+					end
 				end
 			end
 		end

data/lib/console/format.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 
 require_relative "format/safe"
 
 module Console
+	# @namespace
 	module Format
+		# A safe format for converting objects to strings.
+		#
+		# @returns [Console::Format::Safe]
 		def self.default
 			Safe.new(format: ::JSON)
 		end

data/lib/console/interface.rb

@@ -1,53 +1,61 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
-require_relative "logger"
+require "fiber/local"
+require_relative "config"
 
 module Console
 	# The public logger interface.
 	module Interface
+		extend Fiber::Local
+		
+		# Create a new (thread local) logger instance.
+		def self.local
+			Config::DEFAULT.make_logger
+		end
+		
 		# Get the current logger instance.
 		def logger
-			Logger.instance
+			Interface.instance
 		end
 		
 		# Set the current logger instance.
 		#
 		# The current logger instance is assigned per-fiber.
 		def logger= instance
-			Logger.instance= instance
+			Interface.instance= instance
 		end
 		
 		# Emit a debug log message.
 		def debug(...)
-			Logger.instance.debug(...)
+			Interface.instance.debug(...)
 		end
 		
 		# Emit an informational log message.
 		def info(...)
-			Logger.instance.info(...)
+			Interface.instance.info(...)
 		end
 		
 		# Emit a warning log message.
 		def warn(...)
-			Logger.instance.warn(...)
+			Interface.instance.warn(...)
 		end
 		
 		# Emit an error log message.
 		def error(...)
-			Logger.instance.error(...)
+			Interface.instance.error(...)
 		end
 		
 		# Emit a fatal log message.
 		def fatal(...)
-			Logger.instance.fatal(...)
+			Interface.instance.fatal(...)
 		end
 		
 		# Emit a log message with arbitrary arguments and options.
 		def call(...)
-			Logger.instance.call(...)
+			Interface.instance.call(...)
 		end
 	end
 end

data/lib/console/logger.rb

@@ -1,68 +1,49 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2021, by Bryan Powell.
 # Copyright, 2021, by Robert Schulze.
+# Copyright, 2025, by Shigeru Nakajima.
+
+require_relative "filter"
 
 require_relative "output"
 require_relative "output/failure"
 
-require_relative "filter"
-require_relative "event"
-require_relative "resolver"
 require_relative "progress"
 
-require "fiber/local"
-
 module Console
+	# The standard logger interface with support for log levels and verbosity.
+	#
+	# The log levels are: `debug`, `info`, `warn`, `error`, and `fatal`.
 	class Logger < Filter[debug: 0, info: 1, warn: 2, error: 3, fatal: 4]
-		extend Fiber::Local
-		
 		# Set the default log level based on `$DEBUG` and `$VERBOSE`.
 		# You can also specify CONSOLE_LEVEL=debug or CONSOLE_LEVEL=info in environment.
 		# https://mislav.net/2011/06/ruby-verbose-mode/ has more details about how it all fits together.
-		def self.default_log_level(env = ENV)
+		#
+		# @parameter env [Hash] The environment to read the log level from.
+		# @parameter verbose [Boolean] The verbose flag.
+		# @parameter debug [Boolean] The debug flag.
+		# @returns [Integer] The default log level.
+		def self.default_log_level(env = ENV, verbose: $VERBOSE, debug: $DEBUG)
 			if level = env["CONSOLE_LEVEL"]
 				LEVELS[level.to_sym] || level.to_i
-			elsif $DEBUG
+			elsif debug
 				DEBUG
-			elsif $VERBOSE.nil?
+			elsif verbose.nil?
 				WARN
 			else
 				INFO
 			end
 		end
 		
-		# Controls verbose output using `$VERBOSE`.
-		def self.verbose?(env = ENV)
-			!$VERBOSE.nil? || env["CONSOLE_VERBOSE"]
-		end
-		
-		def self.default_logger(output = $stderr, env = ENV, **options)
-			if options[:verbose].nil?
-				options[:verbose] = self.verbose?(env)
-			end
-			
-			if options[:level].nil?
-				options[:level] = self.default_log_level(env)
-			end
-			
-			output = Output.new(output, env, **options)
-			
-			logger = self.new(output, **options)
-			
-			Resolver.default_resolver(logger)
-			
-			return logger
-		end
-		
-		def self.local
-			self.default_logger
-		end
-		
 		DEFAULT_LEVEL = 1
 		
+		# Create a new logger.
+		#
+		# @parameter output [Console::Output] The output destination.
+		# @parameter options [Hash] Additional options.
 		def initialize(output, **options)
 			# This is the expected default behaviour, but it may be nice to have a way to override it.
 			output = Output::Failure.new(output, **options)
@@ -70,6 +51,12 @@ module Console
 			super(output, **options)
 		end
 		
+		# Create a progress indicator for the given subject.
+		#
+		# @parameter subject [String] The subject of the progress indicator.
+		# @parameter total [Integer] The total number of items to process.
+		# @parameter options [Hash] Additional options passed to {Progress}.
+		# @returns [Progress] The progress indicator.
 		def progress(subject, total, **options)
 			options[:severity] ||= :info
 			

data/lib/console/output/default.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 require_relative "terminal"
 require_relative "serialized"
@@ -9,18 +9,43 @@ require_relative "failure"
 
 module Console
 	module Output
+		# Default output format selection.
 		module Default
-			def self.new(output, **options)
-				output ||= $stderr
+			# Create a new output format based on the given stream.
+			#
+			# @parameter io [IO] The output stream.
+			# @parameter env [Hash] Environment variables (defaults to ENV for testing).
+			# @parameter options [Hash] Additional options to customize the output.
+			# @returns [Console::Output::Terminal | Console::Output::Serialized] The output instance, depending on whether the `io` is a terminal or not.
+			def self.new(stream, env: ENV, **options)
+				stream ||= $stderr
 				
-				if output.tty?
-					output = Terminal.new(output, **options)
+				if stream.tty?
+					output = Terminal.new(stream, **options)
+				elsif self.mail?(env)
+					output = Text.new(stream, **options)
+				elsif self.github_actions?(env)
+					output = XTerm.new(stream, **options)
 				else
-					output = Serialized.new(output, **options)
+					output = Serialized.new(stream, **options)
 				end
 				
 				return output
 			end
+			
+			private
+			
+			# Detect if we're running in a cron job or mail context where human-readable output is preferred.
+			# Cron jobs often have MAILTO set and lack TERM, or have minimal TERM values.
+			def self.mail?(env = ENV)
+				env.key?("MAILTO") && !env["MAILTO"].empty?
+			end
+			
+			# Detect if we're running in GitHub Actions, where human-readable output is preferred.
+			# GitHub Actions sets the GITHUB_ACTIONS environment variable to "true".
+			def self.github_actions?(env = ENV)
+				env["GITHUB_ACTIONS"] == "true"
+			end
 		end
 	end
 end

data/lib/console/output/failure.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "wrapper"
 require_relative "../event/failure"
@@ -10,11 +10,18 @@ module Console
 	module Output
 		# A wrapper for outputting failure messages, which can include exceptions.
 		class Failure < Wrapper
+			# Create a new failure output wrapper.
 			def initialize(output, **options)
 				super(output, **options)
 			end
 			
 			# The exception must be either the last argument or passed as an option.
+			#
+			# @parameter subject [String] The subject of the message.
+			# @parameter arguments [Array] The arguments to output.
+			# @parameter exception [Exception] The exception to output.
+			# @parameter options [Hash] Additional options to pass to the output.
+			# @parameter block [Proc] An optional block to pass to the output.
 			def call(subject = nil, *arguments, exception: nil, **options, &block)
 				if exception.nil?
 					last = arguments.last
@@ -28,7 +35,7 @@ module Console
 					options[:exception] = exception
 				end
 				
-				super(subject, *arguments, **options)
+				super(subject, *arguments, **options, &block)
 			end
 		end
 	end

data/lib/console/output/null.rb

@@ -1,20 +1,23 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 
 module Console
 	module Output
+		# A null output that does nothing.
 		class Null
+			# Create a new null output.
 			def initialize(...)
 			end
 			
+			# The last output is always self.
 			def last_output
 				self
 			end
 			
+			# Do nothing.
 			def call(...)
-				# Do nothing.
 			end
 		end
 	end