covered 0.28.0 → 0.28.2

data/lib/covered/coverage.rb

@@ -6,53 +6,83 @@
 require_relative "source"
 
 module Covered
+	# Computes common coverage ratios from executed and executable line counts.
 	module Ratio
+		# The fraction of executable lines that were executed.
+		# @returns [Rational | Float] The executed-to-executable line ratio, or `1.0` when there are no executable lines.
 		def ratio
 			return 1.0 if executable_count.zero?
 			
 			Rational(executed_count, executable_count)
 		end
 		
+		# Whether all executable lines were executed.
+		# @returns [Boolean] Whether `executed_count` equals `executable_count`.
 		def complete?
 			executed_count == executable_count
 		end
 		
+		# The coverage ratio as a percentage.
+		# @returns [Numeric] The coverage ratio multiplied by `100`.
 		def percentage
 			ratio * 100
 		end
 	end
 	
+	# Stores line execution counts and source metadata for a single file.
 	class Coverage
 		include Ratio
 		
+		# Build coverage for the given source path.
+		# @parameter path [String] The source path.
+		# @parameter options [Hash] Options forwarded to {Covered::Source.for}.
+		# @returns [Covered::Coverage] The coverage object for the source path.
 		def self.for(path, **options)
 			self.new(Source.for(path, **options))
 		end
 		
+		# Initialize coverage with the given source, line counts and annotations.
+		# @parameter source [Covered::Source] The covered source metadata.
+		# @parameter counts [Array(Integer | Nil)] Line execution counts indexed by line number.
+		# @parameter annotations [Hash(Integer, Array(String))] Line annotations indexed by line number.
 		def initialize(source, counts = [], annotations = {})
 			@source = source
 			@counts = counts
 			@annotations = annotations
 		end
 		
+		# @attribute [Covered::Source] The covered source metadata.
 		attr_accessor :source
+		
+		# @attribute [Array(Integer | Nil)] Line execution counts indexed by line number.
 		attr :counts
+		
+		# @attribute [Hash(Integer, Array(String))] Line annotations indexed by line number.
 		attr :annotations
 		
+		# The total number of executions across all tracked lines.
+		# @returns [Integer] The sum of all non-`nil` execution counts.
 		def total
 			counts.sum{|count| count || 0}
 		end
 		
 		# Create an empty coverage with the same source.
+		# @returns [Covered::Coverage] Coverage with the same source and `nil` counts.
 		def empty
 			self.class.new(@source, [nil] * @counts.size)
 		end
 		
+		# Add an annotation to the given line number.
+		# @parameter line_number [Integer] The line number to annotate.
+		# @parameter annotation [String] The annotation text.
 		def annotate(line_number, annotation)
 			@annotations[line_number] ||= []
 			@annotations[line_number] << annotation
 		end
 		
+		# Add the given execution count to one or more line numbers.
+		# @parameter line_number [Integer] The first line number to mark.
+		# @parameter value [Integer | Array(Integer)] The execution count or counts to add.
 		def mark(line_number, value = 1)
 			# As currently implemented, @counts is base-zero rather than base-one.
 			# Line numbers generally start at line 1, so the first line, line 1, is at index 1. This means that index[0] is usually nil.
@@ -66,6 +96,8 @@ module Covered
 			end
 		end
 		
+		# Merge another coverage object into this coverage object.
+		# @parameter other [Covered::Coverage] The coverage object to merge.
 		def merge!(other)
 			# If the counts are non-zero and don't match, that can indicate a problem.
 			
@@ -83,6 +115,7 @@ module Covered
 		
 		# Construct a new coverage object for the given line numbers. Only the given line numbers will be considered for the purposes of computing coverage.
 		# @parameter line_numbers [Array(Integer)] The line numbers to include in the new coverage object.
+		# @returns [Covered::Coverage] A coverage object containing counts for the selected lines.
 		def for_lines(line_numbers)
 			counts = [nil] * @counts.size
 			line_numbers.each do |line_number|
@@ -92,14 +125,20 @@ module Covered
 			self.class.new(@source, counts, @annotations)
 		end
 		
+		# The covered source path.
+		# @returns [String] The covered source path.
 		def path
 			@source.path
 		end
 		
+		# Assign the covered source path.
+		# @parameter value [String] The new covered source path.
 		def path= value
 			@source.path = value
 		end
 		
+		# Whether the source file has not changed since this coverage was recorded.
+		# @returns [Boolean] Whether the source exists and its modification time is not newer than the recorded time.
 		def fresh?
 			if @source.modified_time.nil?
 				# We don't know when the file was last modified, so we assume it is stale:
@@ -119,10 +158,16 @@ module Covered
 			return false
 		end
 		
+		# Read the covered source.
+		# @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)
 			@source.read(&block)
 		end
 		
+		# Freeze this coverage and its mutable collections.
+		# @returns [Covered::Coverage] This frozen coverage object.
 		def freeze
 			return self if frozen?
 			
@@ -132,46 +177,69 @@ module Covered
 			super
 		end
 		
+		# The raw coverage counts array.
+		# @returns [Array(Integer | Nil)] The raw coverage counts.
 		def to_a
 			@counts
 		end
 		
+		# Whether this coverage has no executions.
+		# @returns [Boolean] Whether the total execution count is zero.
 		def zero?
 			total.zero?
 		end
 		
+		# The raw coverage count for the given line number.
+		# @parameter line_number [Integer] The line number to query.
+		# @returns [Integer | Nil] The execution count for the line.
 		def [] line_number
 			@counts[line_number]
 		end
 		
+		# Counts for lines that are executable.
+		# @returns [Array(Integer)] Execution counts for executable lines.
 		def executable_lines
 			@counts.compact
 		end
 		
+		# The number of executable lines.
+		# @returns [Integer] The number of executable lines.
 		def executable_count
 			executable_lines.count
 		end
 		
+		# Counts for executable lines that were executed.
+		# @returns [Array(Integer)] Non-zero execution counts for executable lines.
 		def executed_lines
 			executable_lines.reject(&:zero?)
 		end
 		
+		# The number of executable lines that were executed.
+		# @returns [Integer] The number of executed lines.
 		def executed_count
 			executed_lines.count
 		end
 		
+		# The number of executable lines that were not executed.
+		# @returns [Integer] The number of missing executable lines.
 		def missing_count
 			executable_count - executed_count
 		end
 		
+		# Print a human-readable coverage summary.
+		# @parameter output [IO] The output stream.
 		def print(output)
 			output.puts "** #{executed_count}/#{executable_count} lines executed; #{percentage.to_f.round(2)}% covered."
 		end
 		
+		# A human-readable representation of this coverage object.
+		# @returns [String] A summary including the source path and percentage.
 		def to_s
 			"\#<#{self.class} path=#{self.path} #{self.percentage.to_f.round(2)}% covered>"
 		end
 		
+		# A JSON-compatible representation of this coverage object.
+		# @returns [Hash] The coverage counts and summary statistics.
 		def as_json
 			{
 				counts: counts,
@@ -181,12 +249,17 @@ module Covered
 			}
 		end
 		
+		# Serialize this coverage object with the given packer.
+		# @parameter packer [Object] The MessagePack-compatible packer.
 		def serialize(packer)
 			packer.write(@source)
 			packer.write(@counts)
 			packer.write(@annotations)
 		end
 		
+		# Deserialize a coverage object from the given unpacker.
+		# @parameter unpacker [Object] The MessagePack-compatible unpacker.
+		# @returns [Covered::Coverage] The deserialized coverage object.
 		def self.deserialize(unpacker)
 			source = unpacker.read
 			counts = unpacker.read

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,11 +44,18 @@ 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 = []
+			partial_files_count = 0
 			
 			statistics = self.each(wrapper) do |coverage|
+				partial_files_count += 1
+				
 				path = wrapper.relative_path(coverage.path)
 				terminal.puts ""
 				terminal.puts path, style: :path
@@ -56,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)
@@ -66,8 +79,8 @@ module Covered
 			terminal.puts
 			statistics.print(output)
 			
-			# Show information about files with 100% coverage
-			if complete_files.any?
+			# 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
 					terminal.puts "1 file has 100% coverage and is not shown above:"

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