covered 0.28.0 → 0.28.2

data/lib/covered/policy.rb

@@ -10,7 +10,9 @@ require_relative "persist"
 require_relative "forks"
 
 module Covered
+	# Configures coverage collection, filtering, persistence and reports.
 	class Policy < Wrapper
+		# Initialize a policy with an empty file collection.
 		def initialize
 			super(Files.new)
 			
@@ -18,8 +20,11 @@ module Covered
 			@capture = nil
 		end
 		
+		# @attribute [Covered::Base] The current output pipeline.
 		attr :output
 		
+		# Freeze the policy and eagerly build the capture pipeline.
+		# @returns [Covered::Policy] This frozen policy.
 		def freeze
 			return self if frozen?
 			
@@ -29,47 +34,67 @@ module Covered
 			super
 		end
 		
+		# Include files matching the given pattern in coverage results.
+		# Arguments are forwarded to {Covered::Include#initialize}.
 		def include(...)
 			@output = Include.new(@output, ...)
 		end
 		
+		# Exclude files matching the given pattern from coverage results.
+		# Arguments are forwarded to {Covered::Skip#initialize}.
 		def skip(...)
 			@output = Skip.new(@output, ...)
 		end
 		
+		# Restrict coverage results to files matching the given pattern.
+		# Arguments are forwarded to {Covered::Only#initialize}.
 		def only(...)
 			@output = Only.new(@output, ...)
 		end
 		
+		# Restrict coverage results to the given project root.
+		# Arguments are forwarded to {Covered::Root#initialize}.
 		def root(...)
 			@output = Root.new(@output, ...)
 		end
 		
+		# Persist coverage results to a database.
+		# Arguments are forwarded to {Covered::Persist#initialize}.
 		def persist!(...)
 			@output = Persist.new(@output, ...)
 		end
 		
+		# The runtime capture pipeline for this policy.
+		# @returns [Covered::Forks] The memoized capture pipeline.
 		def capture
 			@capture ||= Forks.new(
 				Capture.new(@output)
 			)
 		end
 		
+		# Start collecting coverage.
 		def start
 			capture.start
 		end
 		
+		# Finish collecting coverage.
 		def finish
 			capture.finish
 		end
 		
+		# @attribute [Array] The configured report objects or autoloaders.
 		attr :reports
 		
+		# Lazily loads a report class when it is first used.
 		class Autoload
+			# Initialize an autoloaded report with the given constant name.
+			# @parameter name [String] The report class name under {Covered}.
 			def initialize(name)
 				@name = name
 			end
 			
+			# Instantiate the report class.
+			# @returns [Object] A new report instance.
 			def new
 				begin
 					klass = Covered.const_get(@name)
@@ -82,10 +107,14 @@ module Covered
 				return klass.new
 			end
 			
+			# Instantiate the report and call it.
+			# Arguments are forwarded to the report.
 			def call(...)
 				self.new.call(...)
 			end
 			
+			# A human-readable representation of this autoloaded report.
+			# @returns [String] A debug representation of the autoloader.
 			def to_s
 				"\#<#{self.class} loading #{@name}>"
 			end
@@ -101,6 +130,8 @@ module Covered
 			end
 		end
 		
+		# Configure reports from names, booleans, arrays or report objects.
+		# @parameter reports [String | Boolean | Array | Object | Nil] The reports to configure.
 		def reports!(reports)
 			if reports.is_a?(String)
 				names = reports.split(",")
@@ -124,6 +155,8 @@ module Covered
 			end
 		end
 		
+		# Generate all configured reports.
+		# Arguments are forwarded to each report.
 		def call(...)
 			@reports.each do |report|
 				report.call(self, ...)

data/lib/covered/rspec.rb

@@ -9,18 +9,26 @@ require "rspec/core/formatters"
 $covered = Covered::Config.load
 
 module Covered
+	# Integrates coverage tracking with RSpec.
 	module RSpec
+		# Extends RSpec configuration with coverage tracking.
 		module Policy
+			# Start coverage before loading spec files.
+			# @returns [Object] The result of RSpec's original `load_spec_files` method.
 			def load_spec_files
 				$covered.start
 				
 				super
 			end
 			
+			# The active coverage configuration.
+			# @returns [Covered::Config] The active coverage configuration.
 			def covered
 				$covered
 			end
 			
+			# Assign the active coverage configuration.
+			# @parameter policy [Covered::Config] The replacement coverage configuration.
 			def covered= policy
 				$covered = policy
 			end

data/lib/covered/source.rb

@@ -4,7 +4,13 @@
 # Copyright, 2018-2023, by Samuel Williams.
 
 module Covered
+	# Source code metadata for a covered file or generated template.
 	class Source
+		# Build source metadata for the given path.
+		# Records the current file modification time when the path exists.
+		# @parameter path [String] The source path.
+		# @parameter options [Hash] Options forwarded to {initialize}.
+		# @returns [Covered::Source] The source metadata.
 		def self.for(path, **options)
 			if File.exist?(path)
 				# options[:code] ||= File.read(path)
@@ -14,6 +20,11 @@ module Covered
 			self.new(path, **options)
 		end
 		
+		# Initialize source metadata.
+		# @parameter path [String] The source path.
+		# @parameter code [String | Nil] Optional generated source code.
+		# @parameter line_offset [Integer] The starting line offset.
+		# @parameter modified_time [Time | Nil] The source modification time.
 		def initialize(path, code: nil, line_offset: 1, modified_time: nil)
 			@path = path
 			@code = code
@@ -21,15 +32,28 @@ module Covered
 			@modified_time = modified_time
 		end
 		
+		# @attribute [String] The source path.
 		attr_accessor :path
+		
+		# @attribute [String | Nil] Optional generated source code.
 		attr :code
+		
+		# @attribute [Integer] The starting line offset for generated source code.
 		attr :line_offset
+		
+		# @attribute [Time | Nil] The recorded source modification time.
 		attr :modified_time
 		
+		# A human-readable representation of this source.
+		# @returns [String] A summary containing the source path.
 		def to_s
 			"\#<#{self.class} path=#{path}>"
 		end
 		
+		# Read the source code from disk.
+		# @yields {|file| ...} If a block is given, yields an open source file.
+		# 	@parameter file [File] The open source file.
+		# @returns [String | Object] The source contents without a block, or the block result with a block.
 		def read(&block)
 			if block_given?
 				File.open(self.path, "r", &block)
@@ -39,14 +63,19 @@ module Covered
 		end
 		
 		# The actual code which is being covered. If a template generates the source, this is the generated code, while the path refers to the template itself.
+		# @returns [String] The generated code when present, otherwise the file contents.
 		def code!
 			self.code || self.read
 		end
 		
+		# Whether generated source code is present.
+		# @returns [Boolean] Whether this source has generated code.
 		def code?
 			!!self.code
 		end
 		
+		# Serialize this source with the given packer.
+		# @parameter packer [Object] The MessagePack-compatible packer.
 		def serialize(packer)
 			packer.write(self.path)
 			packer.write(self.code)
@@ -54,6 +83,9 @@ module Covered
 			packer.write(self.modified_time)
 		end
 		
+		# Deserialize a source from the given unpacker.
+		# @parameter unpacker [Object] The MessagePack-compatible unpacker.
+		# @returns [Covered::Source] The deserialized source metadata.
 		def self.deserialize(unpacker)
 			path = unpacker.read
 			code = unpacker.read

data/lib/covered/statistics.rb

@@ -7,21 +7,28 @@ require_relative "wrapper"
 require_relative "coverage"
 
 module Covered
+	# Raised when coverage does not meet the configured minimum.
 	class CoverageError < StandardError
 	end
 	
+	# Aggregates coverage statistics across files.
 	class Statistics
 		include Ratio
 		
+		# Build statistics for a single coverage object.
+		# @parameter coverage [Covered::Coverage] The coverage object to summarize.
+		# @returns [Covered::Statistics] Statistics containing the given coverage.
 		def self.for(coverage)
 			self.new.tap do |statistics|
 				statistics << coverage
 			end
 		end
 		
+		# Aggregate coverage totals.
 		class Aggregate
 			include Ratio
 			
+			# Initialize empty aggregate statistics.
 			def initialize
 				@count = 0
 				@executable_count = 0
@@ -29,14 +36,19 @@ module Covered
 			end
 			
 			# Total number of files added.
+			# @returns [Integer] The number of coverage objects added.
 			attr :count
 			
 			# The number of lines which could have been executed.
+			# @returns [Integer] The executable line count.
 			attr :executable_count
 			
 			# The number of lines that were executed.
+			# @returns [Integer] The executed line count.
 			attr :executed_count
 			
+			# A JSON-compatible representation of these aggregate statistics.
+			# @returns [Hash] The aggregate count, line counts and percentage.
 			def as_json
 				{
 					count: count,
@@ -46,10 +58,15 @@ module Covered
 				}
 			end
 			
+			# Convert these aggregate statistics to JSON.
+			# @parameter options [Hash] Options forwarded to `to_json`.
+			# @returns [String] The JSON representation.
 			def to_json(options)
 				as_json.to_json(options)
 			end
 			
+			# Add coverage to these aggregate statistics.
+			# @parameter coverage [Covered::Coverage] The coverage object to add.
 			def << coverage
 				@count += 1
 				
@@ -58,35 +75,52 @@ module Covered
 			end
 		end
 		
+		# Initialize empty coverage statistics.
 		def initialize
 			@total = Aggregate.new
 			@paths = Hash.new
 		end
 		
+		# @attribute [Covered::Statistics::Aggregate] The total aggregate statistics.
 		attr :total
+		
+		# @attribute [Hash(String, Covered::Coverage)] Coverage statistics indexed by path.
 		attr :paths
 		
+		# The number of unique paths with coverage data.
+		# @returns [Integer] The number of unique paths.
 		def count
 			@paths.size
 		end
 		
+		# The total number of executable lines.
+		# @returns [Integer] The total executable line count.
 		def executable_count
 			@total.executable_count
 		end
 		
+		# The total number of executed lines.
+		# @returns [Integer] The total executed line count.
 		def executed_count
 			@total.executed_count
 		end
 		
+		# Add coverage to these statistics.
+		# @parameter coverage [Covered::Coverage] The coverage object to add.
 		def << coverage
 			@total << coverage
 			(@paths[coverage.path] ||= coverage.empty).merge!(coverage)
 		end
 		
+		# Get coverage for the given path.
+		# @parameter path [String] The source path.
+		# @returns [Covered::Coverage | Nil] The merged coverage for the path.
 		def [](path)
 			@paths[path]
 		end
 		
+		# A JSON-compatible representation of these statistics.
+		# @returns [Hash] The total statistics and path statistics.
 		def as_json
 			{
 				total: total.as_json,
@@ -94,6 +128,9 @@ module Covered
 			}
 		end
 		
+		# Convert these statistics to JSON.
+		# @parameter options [Hash] Options forwarded to `to_json`.
+		# @returns [String] The JSON representation.
 		def to_json(options)
 			as_json.to_json(options)
 		end
@@ -111,6 +148,8 @@ module Covered
 			"100% code coverage: Zen achieved! Bugs in harmony, code at peace.",
 		]
 		
+		# Print a human-readable coverage summary.
+		# @parameter output [IO] The output stream.
 		def print(output)
 			output.puts "#{count} files checked; #{@total.executed_count}/#{@total.executable_count} lines executed; #{@total.percentage.to_f.round(2)}% covered."
 			
@@ -119,6 +158,9 @@ module Covered
 			end
 		end
 		
+		# Validate that coverage meets the given minimum ratio.
+		# @parameter minimum [Numeric] The minimum accepted coverage ratio.
+		# @raises [Covered::CoverageError] If coverage is below the minimum ratio.
 		def validate!(minimum = 1.0)
 			if total.ratio < minimum
 				raise CoverageError, "Coverage of #{self.percentage.to_f.round(2)}% is less than required minimum of #{(minimum * 100.0).round(2)}%!"

data/lib/covered/summary.rb

@@ -7,11 +7,17 @@ require_relative "statistics"
 require_relative "wrapper"
 
 module Covered
+	# Generates a detailed terminal coverage report.
 	class Summary
+		# Initialize the report with an optional coverage threshold.
+		# @parameter threshold [Numeric | Nil] The minimum ratio a file must meet to be omitted from the detailed output.
 		def initialize(threshold: 1.0)
 			@threshold = threshold
 		end
 		
+		# Build a styled terminal for the given output.
+		# @parameter output [IO] The output stream.
+		# @returns [Console::Terminal] The styled terminal wrapper.
 		def terminal(output)
 			require "console/terminal"
 			
@@ -33,6 +39,11 @@ module Covered
 			end
 		end
 		
+		# Enumerate coverage below the threshold and return aggregate statistics.
+		# @parameter wrapper [Covered::Base] The coverage wrapper to enumerate.
+		# @yields {|coverage| ...} Coverage whose ratio is below the configured threshold.
+		# 	@parameter coverage [Covered::Coverage] The coverage object below the threshold.
+		# @returns [Covered::Statistics] Statistics for all coverage objects, including omitted ones.
 		def each(wrapper)
 			statistics = Statistics.new
 			
@@ -47,6 +58,11 @@ module Covered
 			return statistics
 		end
 		
+		# Print any annotations for the given line.
+		# @parameter terminal [Console::Terminal] The terminal to write to.
+		# @parameter coverage [Covered::Coverage] The coverage being rendered.
+		# @parameter line [String] The source line.
+		# @parameter line_offset [Integer] The current line number.
 		def print_annotations(terminal, coverage, line, line_offset)
 			if annotations = coverage.annotations[line_offset]
 				prefix = "#{line_offset}|".rjust(8) + "*|".rjust(8)
@@ -57,12 +73,19 @@ module Covered
 			end
 		end
 		
+		# Print the line and hit-count header.
+		# @parameter terminal [Console::Terminal] The terminal to write to.
 		def print_line_header(terminal)
 			prefix = "Line|".rjust(8) + "Hits|".rjust(8)
 			
 			terminal.puts prefix, style: :header_prefix
 		end
 		
+		# Print a single source line with coverage styling.
+		# @parameter terminal [Console::Terminal] The terminal to write to.
+		# @parameter line [String] The source line.
+		# @parameter line_offset [Integer] The current line number.
+		# @parameter count [Integer | Nil] The execution count for the line.
 		def print_line(terminal, line, line_offset, count)
 			prefix = "#{line_offset}|".rjust(8) + "#{count}|".rjust(8)
 			
@@ -83,6 +106,9 @@ module Covered
 			end
 		end
 		
+		# Print line-by-line coverage for one source file.
+		# @parameter terminal [Console::Terminal] The terminal to write to.
+		# @parameter coverage [Covered::Coverage] The coverage to render.
 		def print_coverage(terminal, coverage)
 			line_offset = 1
 			counts = coverage.counts
@@ -102,12 +128,19 @@ module Covered
 			end
 		end
 		
+		# Print an error raised while rendering coverage.
+		# @parameter terminal [Console::Terminal] The terminal to write to.
+		# @parameter error [Exception] The rendering error.
 		def print_error(terminal, error)
 			terminal.puts "Error: #{error.message}", style: :error
 			terminal.puts error.backtrace
 		end
 		
-		# A coverage array gives, for each line, the number of line execution by the interpreter. A nil value means coverage is finishd for this line (lines like else and end).
+		# Print the detailed coverage report.
+		# A coverage array gives, for each line, the number of line executions by the interpreter. A `nil` value means coverage is finished for this line (lines like `else` and `end`).
+		# @parameter wrapper [Covered::Base] The coverage wrapper to report.
+		# @parameter output [IO] The output stream.
+		# @parameter options [Hash] Options forwarded to {print_coverage}.
 		def call(wrapper, output = $stdout, **options)
 			terminal = self.terminal(output)
 			
@@ -130,13 +163,19 @@ module Covered
 		end
 	end
 	
+	# Generates a detailed report without applying a coverage threshold.
 	class FullSummary < Summary
+		# Initialize a full summary report.
 		def initialize
 			super(threshold: nil)
 		end
 	end
 	
+	# Suppresses coverage report output.
 	class Quiet
+		# Generate no output.
+		# @parameter wrapper [Covered::Base] The coverage wrapper to ignore.
+		# @parameter output [IO] The output stream to ignore.
 		def call(wrapper, output = $stdout)
 			# Silent.
 		end

data/lib/covered/sus.rb

@@ -4,11 +4,14 @@
 # Copyright, 2019-2025, by Samuel Williams.
 
 module Covered
+	# Integrates coverage tracking with Sus.
 	module Sus
+		# Initialize Sus with optional coverage tracking.
+		# Loads and starts coverage only when the `COVERAGE` environment variable is set.
 		def initialize(...)
 			super
 			
-			# Defer loading the coverage configuration unless we are actually running with coverage startd to avoid performance cost/overhead.
+			# Defer loading the coverage configuration unless we are actually running with coverage started to avoid performance cost/overhead:
 			if ENV["COVERAGE"]
 				require_relative "config"
 				
@@ -21,6 +24,8 @@ module Covered
 			end
 		end
 		
+		# Finish coverage tracking after tests complete.
+		# @parameter assertions [Object] The assertions object passed through to Sus.
 		def after_tests(assertions)
 			super(assertions)
 			
@@ -30,6 +35,8 @@ module Covered
 			end
 		end
 		
+		# The active coverage configuration.
+		# @returns [Covered::Config | Nil] The active coverage configuration when coverage is enabled.
 		def covered
 			@covered
 		end

data/lib/covered/version.rb

@@ -3,6 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2018-2025, by Samuel Williams.
 
+# @namespace
 module Covered
-	VERSION = "0.28.0"
+	VERSION = "0.28.2"
 end

data/lib/covered/wrapper.rb

@@ -4,6 +4,7 @@
 # Copyright, 2018-2023, by Samuel Williams.
 
 module Covered
+	# The base coverage output interface.
 	class Base
 		# Start tracking coverage.
 		def start
@@ -17,13 +18,22 @@ module Covered
 		def finish
 		end
 		
+		# Whether the given path should be accepted.
+		# @parameter path [String] The source path.
+		# @returns [Boolean] Whether the path should be included.
 		def accept?(path)
 			true
 		end
 		
+		# Mark coverage for the given path and line number.
+		# @parameter path [String] The source path.
+		# @parameter lineno [Integer] The starting line number.
+		# @parameter value [Integer | Array(Integer)] The execution count or counts to add.
 		def mark(path, lineno, value)
 		end
 		
+		# Add a coverage object.
+		# @parameter coverage [Covered::Coverage] The coverage object to add.
 		def add(coverage)
 		end
 		
@@ -33,42 +43,64 @@ module Covered
 		def each
 		end
 		
+		# Convert a path to a relative path.
+		# @parameter path [String] The source path.
+		# @returns [String] The relative path.
 		def relative_path(path)
 			path
 		end
 		
+		# Expand a path relative to this output.
+		# @parameter path [String] The path to expand.
+		# @returns [String] The expanded path.
 		def expand_path(path)
 			path
 		end
 	end
 	
+	# Wraps another coverage output.
 	class Wrapper < Base
+		# Initialize the wrapper with the given output.
+		# @parameter output [Covered::Base] The output to wrap.
 		def initialize(output = Base.new)
 			@output = output
 		end
 		
+		# @attribute [Covered::Base] The wrapped output.
 		attr :output
 		
+		# Start tracking coverage on the wrapped output.
 		def start
 			@output.start
 		end
 		
+		# Clear coverage on the wrapped output.
 		def clear
 			@output.clear
 		end
 		
+		# Finish tracking coverage on the wrapped output.
 		def finish
 			@output.finish
 		end
 		
+		# Whether the wrapped output accepts the given path.
+		# @parameter path [String] The source path.
+		# @returns [Boolean] Whether the wrapped output accepts the path.
 		def accept?(path)
 			@output.accept?(path)
 		end
 		
+		# Mark coverage on the wrapped output.
+		# @parameter path [String] The source path.
+		# @parameter lineno [Integer] The starting line number.
+		# @parameter value [Integer | Array(Integer)] The execution count or counts to add.
 		def mark(path, lineno, value)
 			@output.mark(path, lineno, value)
 		end
 		
+		# Add coverage to the wrapped output.
+		# @parameter coverage [Covered::Coverage] The coverage object to add.
 		def add(coverage)
 			@output.add(coverage)
 		end
@@ -78,20 +110,33 @@ module Covered
 			@output.each(&block)
 		end
 		
+		# Convert a path using the wrapped output.
+		# @parameter path [String] The source path.
+		# @returns [String] The converted path.
 		def relative_path(path)
 			@output.relative_path(path)
 		end
 		
+		# Expand a path using the wrapped output.
+		# @parameter path [String] The path to expand.
+		# @returns [String] The expanded path.
 		def expand_path(path)
 			@output.expand_path(path)
 		end
 		
+		# Convert all coverage data to a hash keyed by path.
+		# @returns [Hash(String, Covered::Coverage)] Coverage keyed by path.
 		def to_h
 			to_enum(:each).collect{|coverage| [coverage.path, coverage]}.to_h
 		end
 	end
 	
+	# Filters coverage before forwarding it to another output.
 	class Filter < Wrapper
+		# Mark coverage if the path is accepted by this filter.
+		# @parameter path [String] The source path.
+		# @parameter lineno [Integer] The starting line number.
+		# @parameter value [Integer | Array(Integer)] The execution count or counts to add.
 		def mark(path, lineno, value)
 			@output.mark(path, lineno, value) if accept?(path)
 		end
@@ -103,10 +148,16 @@ module Covered
 			end
 		end
 		
+		# Whether the given path is accepted by this filter and its output.
+		# @parameter path [String] The source path.
+		# @returns [Boolean] Whether this filter and the wrapped output accept the path.
 		def accept?(path)
 			match?(path) and super
 		end
 		
+		# Whether the given path matches this filter.
+		# @parameter path [String] The source path.
+		# @returns [Boolean] Whether this filter matches the path.
 		def match?(path)
 			true
 		end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2018-2025, by Samuel Williams.  
+Copyright, 2018-2026, by Samuel Williams.  
 Copyright, 2018, by Shannon Skipper.  
 Copyright, 2019, by Cyril Roelandt.  
 Copyright, 2022, by Adam Daniels.