covered 0.28.1 → 0.28.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '050825f1f7f7966b0592e4fa5864ccd53dfbb0027795e422e47deb32d7300be5'
-  data.tar.gz: 27984bc6a74fb8cd375e2277ea59592a544f6d3617034cc0626dee085fec4ac0
+  metadata.gz: '009f56de49059187634630092d8e8256fc32e59a309c155d46676f3a87002581'
+  data.tar.gz: 3f91b876b34f65800ab6b92a6a991eba898131dee199d476c2f82620a864d3d1
 SHA512:
-  metadata.gz: 12300d334169f20ed66a8f6429e6294b7fcd75306fc4c589b3ebf71c2fed2a6feb29a41f502729a15a77bceefc3213ba9c65033d4cd14a7859b49318e58aaeb7
-  data.tar.gz: e822368a201045b58b653a87d37951a8e2ca773da45f16537fea1fbafe70a968047acf28d4b369111a68384afda93514c796648173ada8c61053fb65b4f6bc84
+  metadata.gz: d11ce0723dc200027f6a319972baab7492599d40fc383cc2c1deba7ef88c9e600231809ce6e4de701a11fec78c0b5de4ac136c82110b503ebf5f59a9c6d7591e
+  data.tar.gz: f848f0fde6e08847fa8194c8dc6854ecc80053279ea1f97cd99028840f9892f102964a52d901a63ffd9393e00bc917ecbfefb247db94ab0c65b59272e1a63188

data/bake/covered/policy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 # Copyright, 2023, by Michael Adams.
 
 def initialize(context)
@@ -14,27 +14,7 @@ end
 # Defaults to the default coverage path if no paths are specified.
 # @parameter paths [Array(String)] The coverage database paths.
 def current(paths: nil, reports: Covered::Config.reports)
-	policy = Covered::Policy.new
-	
-	# Load the default path if no paths are specified:
-	paths ||= Dir.glob(Covered::Persist::DEFAULT_PATH, base: context.root)
-	
-	# If no paths are specified, raise an error:
-	if paths.empty?
-		raise ArgumentError, "No coverage paths specified!"
-	end
-	
-	# Load all coverage information:
-	paths.each do |path|
-		# It would be nice to have a better algorithm here than just ignoring mtime - perhaps using checksums?
-		Covered::Persist.new(policy.output, path).load!(ignore_mtime: true)
-	end
-	
-	if reports
-		policy.reports!(reports)
-	end
-	
-	return policy
+	return Covered::Config.load(root: context.root, reports: reports).policy_for(paths)
 end
 
 # Validate the coverage of multiple test runs.

data/bake/covered/validate.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2025, by Samuel Williams.
+# Copyright, 2022-2026, by Samuel Williams.
 
 def initialize(context)
 	super
@@ -14,19 +14,19 @@ end
 # @parameter minimum [Float] The minimum required coverage in order to pass.
 # @parameter input [Covered::Policy] The input policy to validate.
 def validate(paths: nil, minimum: 1.0, input:)
-	policy ||= context.lookup("covered:policy:current").call(paths: paths)
+	input ||= context.lookup("covered:policy:current").call(paths: paths)
 	
 	# Calculate statistics:
 	statistics = Covered::Statistics.new
 	
-	policy.each do |coverage|
+	input.each do |coverage|
 		statistics << coverage
 	end
 	
 	# Print statistics:
 	statistics.print($stderr)
 	
-	policy.call(STDOUT)
+	input.call(STDOUT)
 	
 	# Validate statistics and raise an error if they are not met:
 	statistics.validate!(minimum)

data/context/configuration.md

@@ -146,13 +146,13 @@ def make_policy(policy)
 	policy.only(/^app\//)
 	
 	# Set custom root
-	policy.root(File.expand_path('..', __dir__))
+	policy.root(File.expand_path("..", __dir__))
 	
 	# Enable persistent coverage across runs
 	policy.persist!
 	
 	# Configure reports programmatically
-	if ENV['CI']
+	if ENV["CI"]
 		policy.reports << Covered::MarkdownSummary.new
 	else
 		policy.reports << Covered::PartialSummary.new
@@ -245,7 +245,7 @@ def make_policy(policy)
 	super
 	
 	# Ensure template coverage is enabled
-	require 'covered/erb' if defined?(ERB)
+	require "covered/erb" if defined?(ERB)
 end
 ```
 
@@ -257,14 +257,14 @@ end
 def make_policy(policy)
 	super
 	
-	if ENV['GITHUB_ACTIONS']
+	if ENV["GITHUB_ACTIONS"]
 		# Use markdown format for GitHub
 		policy.reports << Covered::MarkdownSummary.new
 		
 		# Fail build on low coverage
 		policy.reports << Class.new do
 			def call(wrapper, output = $stdout)
-				statistics = wrapper.each.inject(Statistics.new) { |s, c| s << c }
+				statistics = wrapper.each.inject(Statistics.new){|s, c| s << c}
 				if statistics.ratio < 0.90
 					exit 1
 				end
@@ -281,9 +281,9 @@ def make_policy(policy)
 	super
 	
 	# Different thresholds for different environments
-	threshold = case ENV['RAILS_ENV']
-	when 'production' then 0.95
-	when 'staging' then 0.90
+	threshold = case ENV["RAILS_ENV"]
+	when "production" then 0.95
+	when "staging" then 0.90
 	else 0.80
 	end
 	
@@ -305,7 +305,7 @@ def make_policy(policy)
 	policy.skip(/\/coverage\//)
 	
 	# Use more efficient reports for large projects
-	if Dir['**/*.rb'].length > 1000
+	if Dir["**/*.rb"].length > 1000
 		policy.reports << Covered::BriefSummary.new
 	else
 		policy.reports << Covered::PartialSummary.new
@@ -344,7 +344,7 @@ def make_policy(policy)
 	super
 	
 	# Debug: print current configuration
-	if ENV['DEBUG_COVERAGE']
+	if ENV["DEBUG_COVERAGE"]
 		puts "Ignore paths: #{ignore_paths}"
 		puts "Include patterns: #{include_patterns}"
 		puts "Root: #{@root}"

data/context/getting-started.md

@@ -7,7 +7,7 @@ This guide explains how to get started with `covered` and integrate it with your
 Add this line to your application's `Gemfile`:
 
 ``` ruby
-gem 'covered'
+gem "covered"
 ```
 
 ### Sus Integration
@@ -15,7 +15,7 @@ gem 'covered'
 In your `config/sus.rb` add the following:
 
 ``` ruby
-require 'covered/sus'
+require "covered/sus"
 include Covered::Sus
 ```
 
@@ -24,7 +24,7 @@ include Covered::Sus
 In your `spec/spec_helper.rb` add the following before loading any other code:
 
 ``` ruby
-require 'covered/rspec'
+require "covered/rspec"
 ```
 
 Ensure that you have a `.rspec` file with `--require spec_helper`:
@@ -38,14 +38,14 @@ Ensure that you have a `.rspec` file with `--require spec_helper`:
 In your `test/test_helper.rb` add the following before loading any other code:
 
 ``` ruby
-require 'covered/minitest'
-require 'minitest/autorun'
+require "covered/minitest"
+require "minitest/autorun"
 ```
 
 In your test files, e.g. `test/dummy_test.rb` add the following at the top:
 
 ``` ruby
-require_relative 'test_helper'
+require_relative "test_helper"
 ```
 
 ### Template Coverage

data/context/usage.md

@@ -13,7 +13,7 @@ more accurate than classic line-count tools like SimpleCov.
 Add this line to your application's `Gemfile`:
 
 ```ruby
-gem 'covered'
+gem "covered"
 ```
 
 ## Configuration
@@ -65,7 +65,7 @@ One possibly helpful functionality to take note of is that you can override the
 In your `config/sus.rb` add the following:
 
 ```ruby
-require 'covered/sus'
+require "covered/sus"
 include Covered::Sus
 ```
 ### RSpec Integration
@@ -73,7 +73,7 @@ include Covered::Sus
 In your `spec/spec_helper.rb` add the following before loading any other code:
 
 ```ruby
-require 'covered/rspec'
+require "covered/rspec"
 ```
 
 Ensure that you have a `.rspec` file with `--require spec_helper`:
@@ -89,14 +89,14 @@ Ensure that you have a `.rspec` file with `--require spec_helper`:
 In your `test/test_helper.rb` add the following before loading any other code:
 
 ```ruby
-require 'covered/minitest'
-require 'minitest/autorun'
+require "covered/minitest"
+require "minitest/autorun"
 ```
 
 In your test files, e.g. `test/dummy_test.rb` add the following at the top:
 
 ```ruby
-require_relative 'test_helper'
+require_relative "test_helper"
 ```
 
 

data/lib/covered/autostart.rb

@@ -5,10 +5,13 @@
 
 require_relative "config"
 
+# @namespace
 module Coverage
+	# Integrates `covered` with Ruby's `Coverage.autostart!` hook.
 	module Autostart
 		# Start recording coverage information.
 		# Usage: RUBYOPT=-rcovered/autostart ruby my_script.rb
+		# Registers an `at_exit` hook which finishes coverage and writes reports for the original process.
 		def self.autostart!
 			config = Covered::Config.load
 			config.start

data/lib/covered/brief_summary.rb

@@ -6,7 +6,13 @@
 require_relative "summary"
 
 module Covered
+	# Generates a short coverage report with the least-covered files.
 	class BriefSummary < Summary
+		# Print aggregate statistics and the files with the most missing lines.
+		# @parameter wrapper [Covered::Base] The coverage wrapper to report.
+		# @parameter output [IO] The output stream.
+		# @parameter before [Integer] Reserved for compatibility with other summaries.
+		# @parameter after [Integer] Reserved for compatibility with other summaries.
 		def call(wrapper, output = $stdout, before: 4, after: 4)
 			terminal = self.terminal(output)
 			

data/lib/covered/capture.rb

@@ -8,13 +8,16 @@ require_relative "wrapper"
 require "coverage"
 
 module Covered
+	# Captures Ruby coverage data and forwards it to another coverage output.
 	class Capture < Wrapper
+		# Start Ruby coverage collection.
 		def start
 			super
 			
 			::Coverage.start(lines: true, eval: true)
 		end
 		
+		# Clear any collected coverage data without stopping coverage.
 		def clear
 			super
 			
@@ -27,6 +30,8 @@ module Covered
 			"eval" => true
 		}
 		
+		# Stop coverage collection and add the collected results to the output.
+		# Ignores Ruby's anonymous eval paths and files that no longer exist.
 		def finish
 			results = ::Coverage.result
 			
@@ -35,7 +40,7 @@ module Covered
 				
 				path = self.expand_path(path)
 				
-				# Skip files which don't exist. This can happen if `eval` is used with an invalid/incorrect path.
+				# Skip files which don't exist. This can happen if `eval` is used with an invalid/incorrect path:
 				if File.exist?(path)
 					@output.mark(path, 1, result[:lines])
 				else
@@ -47,6 +52,10 @@ module Covered
 			super
 		end
 		
+		# Execute the given source while capturing coverage for it.
+		# @parameter source [Covered::Source] The source to execute.
+		# @parameter binding [Binding] The binding used to evaluate the source.
+		# @returns [Object] The result of evaluating the source.
 		def execute(source, binding: TOPLEVEL_BINDING)
 			start
 			

data/lib/covered/config.rb

@@ -1,18 +1,24 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require_relative "policy"
 
 module Covered
+	# Loads project coverage configuration and controls a configured policy.
 	class Config
 		PATH = "config/covered.rb"
 		
+		# The root directory used for coverage configuration.
+		# @returns [String] The value of `COVERED_ROOT`, or the current working directory.
 		def self.root
 			ENV["COVERED_ROOT"] || Dir.pwd
 		end
 		
+		# The coverage configuration path under the given root.
+		# @parameter root [String] The project root.
+		# @returns [String | Nil] The expanded configuration path if it exists.
 		def self.path(root)
 			path = ::File.expand_path(PATH, root)
 			
@@ -21,10 +27,16 @@ module Covered
 			end
 		end
 		
+		# The report names requested by the environment.
+		# @returns [String | Nil] The `COVERAGE` environment value.
 		def self.reports
 			ENV["COVERAGE"]
 		end
 		
+		# Load the project coverage configuration for the given root.
+		# @parameter root [String] The project root.
+		# @parameter reports [String | Boolean | Array | Object | Nil] The report configuration.
+		# @returns [Covered::Config] The loaded configuration instance.
 		def self.load(root: self.root, reports: self.reports)
 			derived = Class.new(self)
 			
@@ -37,6 +49,9 @@ module Covered
 			return derived.new(root, reports)
 		end
 		
+		# Initialize the configuration for a project root and reports.
+		# @parameter root [String] The project root.
+		# @parameter reports [String | Boolean | Array | Object | Nil] The report configuration.
 		def initialize(root, reports)
 			@root = root
 			@reports = reports
@@ -45,23 +60,31 @@ module Covered
 			@environment = nil
 		end
 		
+		# Whether reports should be generated.
+		# @returns [Boolean] Whether reporting is enabled.
 		def report?
 			!!@reports
 		end
 		
 		alias :record? :report?
 		
+		# @attribute [Covered::Policy | Nil] The active coverage policy, if assigned by an integration.
 		attr :coverage
 		
+		# The configured coverage policy.
+		# @returns [Covered::Policy] The memoized, frozen policy.
 		def policy
 			@policy ||= Policy.new.tap{|policy| make_policy(policy)}.freeze
 		end
 		
+		# The configured policy output wrapper.
+		# @returns [Covered::Base] The output wrapper at the end of the policy pipeline.
 		def output
 			policy.output
 		end
 		
 		# Start coverage tracking.
+		# Stores the current environment, configures child process autostart, and starts the policy capture pipeline.
 		def start
 			# Save and setup the environment:
 			@environment = ENV.to_h
@@ -72,6 +95,7 @@ module Covered
 		end
 		
 		# Finish coverage tracking.
+		# Stops the policy capture pipeline and restores the environment saved by {start}.
 		def finish
 			# Finish coverage tracking:
 			policy.finish
@@ -82,15 +106,39 @@ module Covered
 		end
 		
 		# Generate coverage reports to the given output.
-		# @param output [IO] The output stream to write the coverage report to.
+		# @parameter output [IO] The output stream to write the coverage report to.
 		def call(output)
 			policy.call(output)
 		end
 		
+		# Enumerate the coverage data from the configured policy.
+		# @yields {|coverage| ...} Each coverage object from the policy.
+		# 	@parameter coverage [Covered::Coverage] The current coverage object.
 		def each(&block)
 			policy.each(&block)
 		end
 		
+		# Build a configured policy using coverage data from persistent storage.
+		#
+		# @parameter paths [Array(String)] The coverage database paths.
+		# @parameter ignore_mtime [Boolean] Whether to ignore source file modification times.
+		# @returns [Covered::Policy] The configured policy with loaded coverage data.
+		def policy_for(paths = nil, ignore_mtime: true)
+			paths ||= Dir.glob(Persist::DEFAULT_PATH, base: @root)
+			paths = Array(paths)
+			
+			if paths.empty?
+				raise ArgumentError, "No coverage paths specified!"
+			end
+			
+			paths.each do |path|
+				# It would be nice to have a better algorithm here than just ignoring mtime - perhaps using checksums:
+				Persist.new(policy.output, path).load!(ignore_mtime: ignore_mtime)
+			end
+			
+			return policy
+		end
+		
 		# Which paths to ignore when computing coverage for a given project.
 		# @returns [Array(String)] An array of relative paths to ignore.
 		def ignore_paths
@@ -104,6 +152,7 @@ module Covered
 		end
 		
 		# Override this method to implement your own policy.
+		# @parameter policy [Covered::Policy] The policy to configure.
 		def make_policy(policy)
 			# Only files in the root would be tracked:
 			policy.root(@root)

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