covered 0.28.1 → 0.28.2

data/lib/covered/files.rb

@@ -9,35 +9,57 @@ require_relative "wrapper"
 require "set"
 
 module Covered
+	# Collects coverage information keyed by source path.
 	class Files < Base
+		# Initialize an empty coverage collection.
 		def initialize(*)
 			super
 			
 			@paths = {}
 		end
 		
+		# @attribute [Hash(String, Covered::Coverage)] Coverage indexed by expanded source path.
 		attr_accessor :paths
 		
+		# Get or create coverage for the given path.
+		# @parameter path [String] The source path.
+		# @returns [Covered::Coverage] The coverage object for the path.
 		def [](path)
 			@paths[path] ||= Coverage.for(path)
 		end
 		
+		# Whether there are no tracked paths.
+		# @returns [Boolean] Whether no coverage paths are tracked.
 		def empty?
 			@paths.empty?
 		end
 		
+		# Mark a line in the given path as executed.
+		# @parameter path [String] The source path.
+		# @parameter line_number [Integer] The line number to mark.
+		# @parameter value [Integer | Array(Integer)] The execution count or counts to add.
 		def mark(path, line_number, value)
 			self[path].mark(line_number, value)
 		end
 		
+		# Add an annotation to a line in the given path.
+		# @parameter path [String] The source path.
+		# @parameter line_number [Integer] The line number to annotate.
+		# @parameter value [String] The annotation text.
 		def annotate(path, line_number, value)
 			self[path].annotate(line_number, value)
 		end
 		
+		# Merge coverage for the given path into this collection.
+		# @parameter coverage [Covered::Coverage] The coverage object to merge.
 		def add(coverage)
 			self[coverage.path].merge!(coverage)
 		end
 		
+		# Enumerate tracked coverage objects.
+		# @yields {|coverage| ...} Each tracked coverage object.
+		# 	@parameter coverage [Covered::Coverage] The current coverage object.
+		# @returns [Enumerator | Nil] An enumerator without a block.
 		def each
 			return to_enum unless block_given?
 			
@@ -46,12 +68,19 @@ module Covered
 			end
 		end
 		
+		# Remove all tracked coverage data.
+		# @returns [Hash] The cleared path map.
 		def clear
 			@paths.clear
 		end
 	end
 	
+	# Includes coverage for files matching a glob pattern.
 	class Include < Wrapper
+		# Initialize an include filter for the given glob pattern.
+		# @parameter output [Covered::Base] The output to wrap.
+		# @parameter pattern [String] The glob pattern to include.
+		# @parameter base [String] The base path used to expand the glob.
 		def initialize(output, pattern, base = "")
 			super(output)
 			
@@ -59,8 +88,11 @@ module Covered
 			@base = base
 		end
 		
+		# @attribute [String] The glob pattern to include.
 		attr :pattern
 		
+		# Resolve the include pattern to real file paths.
+		# @returns [Set(String)] The real paths matched by the include pattern.
 		def glob
 			paths = Set.new
 			root = self.expand_path(@base)
@@ -75,6 +107,9 @@ module Covered
 			return paths
 		end
 		
+		# Enumerate existing coverage and synthesize empty coverage for unmatched included files.
+		# @yields {|coverage| ...} Each existing or synthesized coverage object.
+		# 	@parameter coverage [Covered::Coverage] The current coverage object.
 		def each(&block)
 			paths = glob
 			
@@ -90,17 +125,22 @@ module Covered
 		end
 	end
 	
+	# Excludes coverage for paths matching a pattern.
 	class Skip < Filter
+		# Initialize a skip filter for the given pattern.
+		# @parameter output [Covered::Base] The output to wrap.
+		# @parameter pattern [Regexp] The pattern to exclude.
 		def initialize(output, pattern)
 			super(output)
 			
 			@pattern = pattern
 		end
 		
+		# @attribute [Regexp] The pattern to exclude.
 		attr :pattern
 		
 		if Regexp.instance_methods.include? :match?
-			# This is better as it doesn't allocate a MatchData instance which is essentially useless.
+			# This is better as it doesn't allocate a MatchData instance which is essentially useless:
 			def match? path
 				!@pattern.match?(path)
 			end
@@ -111,33 +151,52 @@ module Covered
 		end
 	end
 	
+	# Only includes coverage for paths matching a pattern.
 	class Only < Filter
+		# Initialize an only filter for the given pattern.
+		# @parameter output [Covered::Base] The output to wrap.
+		# @parameter pattern [Object] The pattern matched with `===`.
 		def initialize(output, pattern)
 			super(output)
 			
 			@pattern = pattern
 		end
 		
+		# @attribute [Object] The pattern matched with `===`.
 		attr :pattern
 		
+		# Whether the given path matches the only pattern.
+		# @parameter path [String] The source path.
+		# @returns [Boolean] Whether the path matches the pattern.
 		def match?(path)
 			@pattern === path
 		end
 	end
 	
+	# Restricts coverage to a project root and converts paths relative to it.
 	class Root < Filter
+		# Initialize a root filter for the given path.
+		# @parameter output [Covered::Base] The output to wrap.
+		# @parameter path [String] The root path.
 		def initialize(output, path)
 			super(output)
 			
 			@path = path
 		end
 		
+		# @attribute [String] The root path.
 		attr :path
 		
+		# Expand a path relative to this root.
+		# @parameter path [String] The path to expand.
+		# @returns [String] The expanded path.
 		def expand_path(path)
 			File.expand_path(super, @path)
 		end
 		
+		# Convert a path under this root to a relative path.
+		# @parameter path [String] The path to relativize.
+		# @returns [String] The relative path when under this root, otherwise the wrapped output result.
 		def relative_path(path)
 			if path.start_with?(@path)
 				path.slice(@path.size+1, path.size)
@@ -146,6 +205,9 @@ module Covered
 			end
 		end
 		
+		# Whether the given path is under this root.
+		# @parameter path [String] The source path.
+		# @returns [Boolean] Whether the path starts with this root.
 		def match?(path)
 			path.start_with?(@path)
 		end

data/lib/covered/forks.rb

@@ -6,25 +6,33 @@
 require_relative "wrapper"
 
 module Covered
+	# Tracks coverage across forked child processes.
 	class Forks < Wrapper
+		# Start tracking coverage and install the fork handler.
 		def start
 			super
 			
 			Handler.start(self)
 		end
 		
+		# Stop tracking coverage and remove the fork handler state.
 		def finish
 			Handler.finish
 			
 			super
 		end
 		
+		# Handles `Process.fork` so child processes record coverage independently.
 		module Handler
 			LOCK = Mutex.new
 			
 			class << self
+				# @attribute [Covered::Forks | Nil] The currently registered coverage wrapper.
 				attr :coverage
 				
+				# Register coverage for fork handling.
+				# @parameter coverage [Covered::Forks] The coverage wrapper to use in forked children.
+				# @raises [ArgumentError] If coverage is already registered.
 				def start(coverage)
 					LOCK.synchronize do
 						if @coverage
@@ -35,12 +43,14 @@ module Covered
 					end
 				end
 				
+				# Clear the registered coverage.
 				def finish
 					LOCK.synchronize do
 						@coverage = nil
 					end
 				end
 				
+				# Reset coverage in a forked child and save it at exit.
 				def after_fork
 					return unless coverage = Handler.coverage
 					pid = Process.pid
@@ -57,6 +67,8 @@ module Covered
 				end
 			end
 			
+			# Intercept `Process.fork` and initialize coverage in the child.
+			# @returns [Integer | Nil] The process ID in the parent, and `0` or `nil` in the child depending on Ruby's fork semantics.
 			def _fork
 				pid = super
 				

data/lib/covered/markdown_summary.rb

@@ -9,11 +9,19 @@ require_relative "wrapper"
 require "console/output"
 
 module Covered
+	# Generates a Markdown coverage summary.
 	class MarkdownSummary
+		# 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
 		
+		# 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
 			
@@ -28,6 +36,11 @@ module Covered
 			return statistics
 		end
 		
+		# Print any annotations for the given line.
+		# @parameter output [IO] The output stream.
+		# @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(output, coverage, line, line_offset)
 			if annotations = coverage.annotations[line_offset]
 				prefix = "#{line_offset}|".rjust(8) + "*|".rjust(8)
@@ -38,10 +51,17 @@ module Covered
 			end
 		end
 		
+		# Print the line and hit-count header.
+		# @parameter output [IO] The output stream.
 		def print_line_header(output)
 			output.puts "Line|".rjust(8) + "Hits|".rjust(8)
 		end
 		
+		# Print a single source line.
+		# @parameter output [IO] The output stream.
+		# @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(output, line, line_offset, count)
 			prefix = "#{line_offset}|".rjust(8) + "#{count}|".rjust(8)
 			
@@ -54,7 +74,9 @@ module Covered
 			end
 		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).
+		# 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.
 		def call(wrapper, output = $stdout)
 			output.puts "# Coverage Report"
 			output.puts

data/lib/covered/minitest.rb

@@ -11,7 +11,10 @@ require "minitest"
 $covered = Covered::Config.load
 
 module Covered
+	# Integrates coverage tracking with Minitest.
 	module Minitest
+		# Start coverage before running the Minitest suite.
+		# @returns [Object] The result of Minitest's original `run` method.
 		def run(*)
 			$covered.start
 			

data/lib/covered/partial_summary.rb

@@ -6,7 +6,13 @@
 require_relative "summary"
 
 module Covered
+	# Generates a report containing only lines near missing coverage.
 	class PartialSummary < Summary
+		# Print coverage snippets around uncovered lines.
+		# @parameter terminal [Console::Terminal] The terminal to write to.
+		# @parameter coverage [Covered::Coverage] The coverage to render.
+		# @parameter before [Integer] The number of lines before an uncovered line to show.
+		# @parameter after [Integer] The number of lines after an uncovered line to show.
 		def print_coverage(terminal, coverage, before: 4, after: 4)
 			return if coverage.zero?
 			
@@ -38,6 +44,10 @@ module Covered
 			end
 		end
 		
+		# Print the partial coverage report.
+		# @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)
 			complete_files = []
@@ -59,7 +69,7 @@ module Covered
 				coverage.print(output)
 			end
 			
-			# Collect files with 100% coverage that were not shown
+			# Collect files with 100% coverage that were not shown:
 			wrapper.each do |coverage|
 				if coverage.ratio >= 1.0
 					complete_files << wrapper.relative_path(coverage.path)
@@ -69,7 +79,7 @@ module Covered
 			terminal.puts
 			statistics.print(output)
 			
-			# Only show information about files with 100% coverage if there were files with partial coverage shown above
+			# Only show information about files with 100% coverage if there were files with partial coverage shown above:
 			if complete_files.any? && partial_files_count > 0
 				terminal.puts ""
 				if complete_files.size == 1

data/lib/covered/persist.rb

@@ -10,15 +10,24 @@ require "msgpack"
 require "time"
 
 module Covered
+	# Persists coverage records to a MessagePack database.
 	class Persist < Wrapper
 		DEFAULT_PATH = ".covered.db"
 		
+		# Initialize persistence for the given output and database path.
+		# @parameter output [Covered::Base] The output to wrap.
+		# @parameter path [String] The coverage database path.
 		def initialize(output, path = DEFAULT_PATH)
 			super(output)
 			
 			@path = self.expand_path(path)
 		end
 		
+		# Apply a persisted record to the output.
+		# Records with stale source modification times are ignored unless `ignore_mtime` is true.
+		# @parameter record [Hash] The persisted coverage record.
+		# @parameter ignore_mtime [Boolean] Whether to apply records even if their source appears stale.
+		# @returns [Boolean] Whether the record was applied.
 		def apply(record, ignore_mtime: false)
 			if coverage = record[:coverage]
 				if path = record[:path]
@@ -35,6 +44,9 @@ module Covered
 			return false
 		end
 		
+		# Convert coverage into a database record.
+		# @parameter coverage [Covered::Coverage] The coverage object to serialize.
+		# @returns [Hash] A MessagePack-compatible record.
 		def serialize(coverage)
 			{
 				# We want to use relative paths so that moving the repo won't break everything:
@@ -45,6 +57,9 @@ module Covered
 			}
 		end
 		
+		# Load persisted coverage records into the output.
+		# @parameter options [Hash] Options forwarded to {apply}.
+		# @raises [LoadError] If the database exists but cannot be decoded.
 		def load!(**options)
 			return unless File.exist?(@path)
 			
@@ -61,6 +76,7 @@ module Covered
 			raise LoadError, "Failed to load coverage from #{@path}, maybe old format or corrupt!"
 		end
 		
+		# Save all output coverage records to the database.
 		def save!
 			# Dump all coverage:
 			File.open(@path, "ab") do |file|
@@ -77,12 +93,17 @@ module Covered
 			end
 		end
 		
+		# Finish the wrapped output and save the coverage database.
 		def finish
 			super
 			
 			self.save!
 		end
 		
+		# Reload persisted coverage and enumerate the wrapped output.
+		# @yields {|coverage| ...} Each coverage object from the reloaded output.
+		# 	@parameter coverage [Covered::Coverage] The current coverage object.
+		# @returns [Enumerator | Nil] An enumerator without a block.
 		def each(&block)
 			return to_enum unless block_given?
 			
@@ -92,6 +113,8 @@ module Covered
 			super
 		end
 		
+		# Build the MessagePack factory used for coverage records.
+		# @returns [MessagePack::Factory] The configured MessagePack factory.
 		def make_factory
 			factory = MessagePack::Factory.new
 			
@@ -117,10 +140,16 @@ module Covered
 			return factory
 		end
 		
+		# Build a MessagePack packer for the given IO.
+		# @parameter io [IO] The IO to write packed records to.
+		# @returns [MessagePack::Packer] A packer configured for coverage records.
 		def make_packer(io)
 			return make_factory.packer(io)
 		end
 		
+		# Build a MessagePack unpacker for the given IO.
+		# @parameter io [IO] The IO to read packed records from.
+		# @returns [MessagePack::Unpacker] An unpacker configured for coverage records.
 		def make_unpacker(io)
 			return make_factory.unpacker(io)
 		end

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