covered 0.28.0 → 0.28.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 289a32298170797803df03aec0f13ab6452bcc2787d38e85860ead1bca0b17b0
-  data.tar.gz: 6f682d81566f970a93a4aed6b00e1db77603fcf2a982245e75c60e7c30f15652
+  metadata.gz: '009f56de49059187634630092d8e8256fc32e59a309c155d46676f3a87002581'
+  data.tar.gz: 3f91b876b34f65800ab6b92a6a991eba898131dee199d476c2f82620a864d3d1
 SHA512:
-  metadata.gz: 4495fe21349a2cd25fbfc81e7de1b0d2c00465635f543b991cb8f740e8dad98653dd7a59552e065fb51a5224e39ce12601199ca912fde16033eb43b109f1197d
-  data.tar.gz: e43586380b8587f803c1175f3a919eafd55a860dd61092057ecbf729cce902671e7046fe81fb0baacbd699f4968bdb571b3fe8a10017f80b6341365291584003
+  metadata.gz: d11ce0723dc200027f6a319972baab7492599d40fc383cc2c1deba7ef88c9e600231809ce6e4de701a11fec78c0b5de4ac136c82110b503ebf5f59a9c6d7591e
+  data.tar.gz: f848f0fde6e08847fa8194c8dc6854ecc80053279ea1f97cd99028840f9892f102964a52d901a63ffd9393e00bc917ecbfefb247db94ab0c65b59272e1a63188

checksums.yaml.gz.sig

@@ -1,3 +1,4 @@
-`�#dpJ`6��ˑ��
-�#Ed�ӲO���1J#9T:� ������PK��5�׬�u�}f�?�P}�X+V2A
-i����b�8�3���)y��1�q��=���ɚ
������z{۶~7CG�/�@�%��&�Ul�%�v����-H�_�e��>�|�Q�jȋ�Wx��윁Ɉ�
+a��0����(M\$�*�~s��B�Xa'�BD����[��[1���z
+%�9+����nk�x��ˢ*f{�{���x��q%�W������B[f3�H�}Ȑ��6��]h<�"Е�d�`!w���<��	T����G�T.q��!�f�c�qz����7����
+B@k!��,��aX� <^���{Ѳ
+���1K�gK9"�TY.��pb|�2Jn�y��b�i���{����@���gd���y�)!н��̞!�#Bͫ�,���-�R�+En���vZ�/�o��Yosc�NMSX�'�$l�P�d����Uwm��ht����.4����^+'@y�^[֩�l�"�'Yt�G
a�=�Зɏ�����ԙM���/C��e�

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)