covered 0.28.1 → 0.28.2

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.1"
+	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.  

data/readme.md

@@ -34,6 +34,10 @@ Please see the [project documentation](https://socketry.github.io/covered/) for
 
 Please see the [project releases](https://socketry.github.io/covered/releases/index) for all releases.
 
+### v0.28.2
+
+  - Ensure bake coverage validation loads persisted coverage using project configuration.
+
 ### v0.28.0
 
   - List files that have 100% coverage in `PartialSummary` output.
@@ -58,6 +62,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.28.2
+
+  - Ensure bake coverage validation loads persisted coverage using project configuration.
+
 ## v0.28.0
 
   - List files that have 100% coverage in `PartialSummary` output.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: covered
 version: !ruby/object:Gem::Version
-  version: 0.28.1
+  version: 0.28.2
 platform: ruby
 authors:
 - Samuel Williams
@@ -121,14 +121,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A modern approach to code coverage.
 test_files: []