ruby-coverage 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f625d52f5f7030429cd75eaa690bb45a62fa1e2a11b964e366d4ddb1c320009
+  data.tar.gz: ff482bc87fe61d48313e3e190333af9faabb272fb209edba68ab0ab4dd44bef0
+SHA512:
+  metadata.gz: 34f4e2fe8a19578a25a80c9db42ec761e154726ed55b590d7350b1b143cbe0643fcf5d28037cb75b212961b0474b2218e9893f1c8c59845e62190077042ebe19
+  data.tar.gz: b22011f57b243cd95166f2495963386a40517a8cea439f0f5ed9057f8e8342aa9030ad5f5417aac354720df85b6a5638d6c0f50b47d2a6d6322176b537ccb672

data/ext/extconf.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "mkmf"
+
+gem_name = File.basename(__dir__)
+extension_name = "Ruby_Coverage"
+
+append_cflags(["-Wall", "-Wno-unknown-pragmas", "-std=c99"])
+
+if ENV.key?("RUBY_DEBUG")
+	$stderr.puts "Enabling debug mode..."
+	
+	append_cflags(["-DRUBY_DEBUG", "-O0"])
+end
+
+$srcs = ["ruby/coverage/coverage.c", "ruby/coverage/tracer.c"]
+$VPATH << "$(srcdir)/ruby/coverage"
+
+if ENV.key?("RUBY_SANITIZE")
+	$stderr.puts "Enabling sanitizers..."
+	
+	append_cflags(["-fsanitize=address", "-fsanitize=undefined", "-fno-omit-frame-pointer"])
+	$LDFLAGS << " -fsanitize=address -fsanitize=undefined"
+end
+
+have_func("rb_tracearg_instruction_sequence", "ruby/debug.h")
+
+create_header
+
+# Generate the makefile to compile the native binary into `ext/`:
+create_makefile(extension_name)

data/ext/ruby/coverage/coverage.c

@@ -0,0 +1,13 @@
+// Released under the MIT License.
+// Copyright, 2025, by Samuel Williams.
+
+#include "coverage.h"
+#include "tracer.h"
+
+void Init_Ruby_Coverage(void)
+{
+	VALUE Ruby = rb_define_module("Ruby");
+	VALUE Ruby_Coverage = rb_define_module_under(Ruby, "Coverage");
+
+	Init_Ruby_Coverage_Tracer(Ruby_Coverage);
+}

data/ext/ruby/coverage/coverage.h

@@ -0,0 +1,8 @@
+// Released under the MIT License.
+// Copyright, 2025, by Samuel Williams.
+
+#pragma once
+
+#include <ruby.h>
+
+void Init_Ruby_Coverage(void);

data/ext/ruby/coverage/tracer.c

@@ -0,0 +1,345 @@
+// Released under the MIT License.
+// Copyright, 2025, by Samuel Williams.
+
+#include "tracer.h"
+
+#include <ruby.h>
+#include <ruby/debug.h>
+
+static const int DEBUG = 0;
+
+static ID id_call;
+static ID id_instruction_sequence;
+static ID id_path;
+
+struct Ruby_Coverage_Tracer {
+	// The Ruby callback: called with (path, iseq) the first time a new file is
+	// compiled. iseq is the RubyVM::InstructionSequence from the script_compiled
+	// event. Must return an Array to use as the line-count store, or nil to
+	// skip the file.
+	VALUE callback;
+
+	// Hash: { path String => counts Array }
+	VALUE counts;
+
+	// Cache of the most recently seen rb_sourcefile() pointer. Stable for the
+	// lifetime of the current ISeq, so pointer equality is an O(1) same-file
+	// check without a hash lookup on every line event.
+	uintptr_t last_path_pointer;
+
+	// The counts Array for the file identified by last_path_pointer.
+	VALUE last_counts;
+
+	// Re-entrancy guard. Set while the user callback is being invoked so that
+	// any RUBY_EVENT_LINE events fired by the callback itself are ignored.
+	int in_callback;
+
+	// Used on Rubies where rb_tracearg_instruction_sequence is not part of the
+	// public extension headers.
+	VALUE script_compiled_tracepoint;
+};
+
+static void Ruby_Coverage_Tracer_mark(void *pointer)
+{
+	struct Ruby_Coverage_Tracer *tracer = pointer;
+	rb_gc_mark_movable(tracer->callback);
+	rb_gc_mark_movable(tracer->counts);
+	rb_gc_mark_movable(tracer->last_counts);
+	rb_gc_mark_movable(tracer->script_compiled_tracepoint);
+}
+
+static void Ruby_Coverage_Tracer_free(void *pointer)
+{
+	xfree(pointer);
+}
+
+static void Ruby_Coverage_Tracer_compact(void *pointer)
+{
+	struct Ruby_Coverage_Tracer *tracer = pointer;
+	tracer->callback    = rb_gc_location(tracer->callback);
+	tracer->counts      = rb_gc_location(tracer->counts);
+	tracer->last_counts = rb_gc_location(tracer->last_counts);
+	tracer->script_compiled_tracepoint = rb_gc_location(tracer->script_compiled_tracepoint);
+}
+
+static const rb_data_type_t Ruby_Coverage_Tracer_type = {
+	.wrap_struct_name = "Ruby::Coverage::Tracer",
+	.function = {
+		.dmark    = Ruby_Coverage_Tracer_mark,
+		.dfree    = Ruby_Coverage_Tracer_free,
+		.dsize    = NULL,
+		.dcompact = Ruby_Coverage_Tracer_compact,
+	},
+	.flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+struct Ruby_Coverage_Tracer_CurrentISeq {
+	VALUE iseq;
+};
+
+struct Ruby_Coverage_Tracer_CallbackArguments {
+	struct Ruby_Coverage_Tracer *tracer;
+	VALUE path;
+	VALUE iseq;
+};
+
+static VALUE Ruby_Coverage_Tracer_current_iseq_callback(const rb_debug_inspector_t *debug_inspector, void *data)
+{
+	struct Ruby_Coverage_Tracer_CurrentISeq *current_iseq = data;
+	current_iseq->iseq = rb_debug_inspector_frame_iseq_get(debug_inspector, 0);
+
+	return Qnil;
+}
+
+static VALUE Ruby_Coverage_Tracer_current_iseq(void)
+{
+	struct Ruby_Coverage_Tracer_CurrentISeq current_iseq = {.iseq = Qnil};
+	rb_debug_inspector_open(Ruby_Coverage_Tracer_current_iseq_callback, &current_iseq);
+
+	return current_iseq.iseq;
+}
+
+static VALUE Ruby_Coverage_Tracer_call_callback(VALUE data)
+{
+	struct Ruby_Coverage_Tracer_CallbackArguments *arguments = (struct Ruby_Coverage_Tracer_CallbackArguments *)data;
+
+	return rb_funcall(arguments->tracer->callback, id_call, 2, arguments->path, arguments->iseq);
+}
+
+static VALUE Ruby_Coverage_Tracer_leave_callback(VALUE data)
+{
+	struct Ruby_Coverage_Tracer_CallbackArguments *arguments = (struct Ruby_Coverage_Tracer_CallbackArguments *)data;
+	arguments->tracer->in_callback -= 1;
+
+	return Qnil;
+}
+
+static VALUE Ruby_Coverage_Tracer_invoke_callback(struct Ruby_Coverage_Tracer *tracer, VALUE path, VALUE iseq)
+{
+	struct Ruby_Coverage_Tracer_CallbackArguments arguments = {
+		.tracer = tracer,
+		.path = path,
+		.iseq = iseq,
+	};
+
+	tracer->in_callback += 1;
+
+	return rb_ensure(
+		Ruby_Coverage_Tracer_call_callback,
+		(VALUE)&arguments,
+		Ruby_Coverage_Tracer_leave_callback,
+		(VALUE)&arguments
+	);
+}
+
+static VALUE Ruby_Coverage_Tracer_allocate(VALUE klass)
+{
+	struct Ruby_Coverage_Tracer *tracer;
+	VALUE self = TypedData_Make_Struct(klass, struct Ruby_Coverage_Tracer, &Ruby_Coverage_Tracer_type, tracer);
+
+	tracer->callback          = Qnil;
+	tracer->counts            = rb_hash_new();
+	tracer->last_path_pointer = 0;
+	tracer->last_counts       = Qnil;
+	tracer->in_callback       = 0;
+	tracer->script_compiled_tracepoint = Qnil;
+
+	return self;
+}
+
+static VALUE Ruby_Coverage_Tracer_initialize(VALUE self)
+{
+	struct Ruby_Coverage_Tracer *tracer;
+	TypedData_Get_Struct(self, struct Ruby_Coverage_Tracer,
+	                     &Ruby_Coverage_Tracer_type, tracer);
+
+	RB_OBJ_WRITE(self, &tracer->callback, rb_block_proc());
+
+	return self;
+}
+
+// Fires when any Ruby script is compiled and invokes the user callback
+// immediately so the counts array is registered before the first line event.
+//
+// Also invalidates the rb_sourcefile() pointer cache so the line hook
+// re-evaluates which counts array to use.
+#ifdef HAVE_RB_TRACEARG_INSTRUCTION_SEQUENCE
+// Installed via rb_add_event_hook2 with RUBY_EVENT_HOOK_FLAG_RAW_ARG.
+// Uses the direct C API to extract the compiled instruction sequence.
+static void Ruby_Coverage_Tracer_on_script_compiled(VALUE data, const rb_trace_arg_t *trace_arg)
+{
+	struct Ruby_Coverage_Tracer *tracer;
+	TypedData_Get_Struct(data, struct Ruby_Coverage_Tracer,
+	                     &Ruby_Coverage_Tracer_type, tracer);
+
+	tracer->last_path_pointer = 0;
+
+	// Guard the entire body: rb_funcall (for #path and the user callback) can
+	// fire RUBY_EVENT_LINE, and without the guard on_line would run and
+	// potentially invoke the user callback before we've finished here.
+	if (tracer->in_callback) return;
+
+	VALUE iseq = rb_tracearg_instruction_sequence((rb_trace_arg_t *)trace_arg);
+	if (NIL_P(iseq)) { return; }
+
+	VALUE path = rb_funcall(iseq, id_path, 0);
+	if (NIL_P(path)) { return; }
+
+	// Reuse existing counts for re-evals of the same path so hit counts
+	// accumulate rather than reset.
+	if (!NIL_P(rb_hash_lookup(tracer->counts, path))) { return; }
+
+	VALUE counts = Ruby_Coverage_Tracer_invoke_callback(tracer, path, iseq);
+
+	if (!NIL_P(counts)) {
+		rb_hash_aset(tracer->counts, path, counts);
+	}
+}
+#else
+// Installed via rb_tracepoint_new.
+// Uses the public TracePoint object API to extract the compiled instruction
+// sequence when the direct C helper is not declared in ruby/debug.h.
+static void Ruby_Coverage_Tracer_on_script_compiled(VALUE tpval, void *data)
+{
+	struct Ruby_Coverage_Tracer *tracer = data;
+
+	tracer->last_path_pointer = 0;
+
+	if (tracer->in_callback) return;
+
+	VALUE iseq = rb_funcall(tpval, id_instruction_sequence, 0);
+	if (NIL_P(iseq)) { return; }
+
+	VALUE path = rb_funcall(iseq, id_path, 0);
+	if (NIL_P(path)) { return; }
+
+	if (!NIL_P(rb_hash_lookup(tracer->counts, path))) { return; }
+
+	VALUE counts = Ruby_Coverage_Tracer_invoke_callback(tracer, path, iseq);
+
+	if (!NIL_P(counts)) {
+		rb_hash_aset(tracer->counts, path, counts);
+	}
+}
+#endif
+
+// Installed via rb_add_event_hook. Fires on every new source line.
+//
+// Uses rb_sourcefile() pointer comparison as an O(1) same-file sentinel.
+// On first entry to a new file, checks if the script_compiled hook already
+// registered a counts array. If not (file was compiled before the tracer
+// started), falls back to rb_profile_frames to get the iseq and invokes the
+// user callback, matching the behaviour of the script_compiled path.
+static void Ruby_Coverage_Tracer_on_line(rb_event_flag_t event, VALUE data, VALUE self, ID method_id, VALUE klass)
+{
+	struct Ruby_Coverage_Tracer *tracer;
+	TypedData_Get_Struct(data, struct Ruby_Coverage_Tracer, &Ruby_Coverage_Tracer_type, tracer);
+
+	if (tracer->in_callback) return;
+
+	uintptr_t current_path_pointer = (uintptr_t)rb_sourcefile();
+
+	if (tracer->last_path_pointer != current_path_pointer) {
+		tracer->last_path_pointer = current_path_pointer;
+
+		const char *path_cstr = rb_sourcefile();
+		VALUE counts = Qnil;
+
+		if (path_cstr) {
+			VALUE path = rb_str_new_cstr(path_cstr);
+			counts = rb_hash_lookup(tracer->counts, path);
+
+			if (NIL_P(counts)) {
+				// File was compiled before the tracer started; inspect the current
+				// frame to recover the active instruction sequence.
+				VALUE iseq = Ruby_Coverage_Tracer_current_iseq();
+
+				if (!NIL_P(iseq)) {
+					counts = Ruby_Coverage_Tracer_invoke_callback(tracer, path, iseq);
+
+					if (!NIL_P(counts)) {
+						rb_hash_aset(tracer->counts, path, counts);
+					}
+				}
+			}
+		}
+
+		RB_OBJ_WRITE(data, &tracer->last_counts, counts);
+	}
+
+	if (NIL_P(tracer->last_counts)) return;
+
+	int line = rb_sourceline();
+
+	// Counts are 1-indexed: index 0 is unused (nil), index N is the hit count
+	// for source line N. Grow the array if necessary.
+	while (RARRAY_LEN(tracer->last_counts) <= line) {
+		rb_ary_push(tracer->last_counts, Qnil);
+	}
+
+	VALUE current = rb_ary_entry(tracer->last_counts, line);
+	rb_ary_store(tracer->last_counts, line,
+	             NIL_P(current) ? INT2FIX(1) : INT2FIX(FIX2INT(current) + 1));
+}
+
+static VALUE Ruby_Coverage_Tracer_start(VALUE self)
+{
+	struct Ruby_Coverage_Tracer *tracer;
+	TypedData_Get_Struct(self, struct Ruby_Coverage_Tracer, &Ruby_Coverage_Tracer_type, tracer);
+
+	#ifdef HAVE_RB_TRACEARG_INSTRUCTION_SEQUENCE
+	rb_add_event_hook2(
+		(rb_event_hook_func_t)Ruby_Coverage_Tracer_on_script_compiled,
+		RUBY_EVENT_SCRIPT_COMPILED,
+		self,
+		RUBY_EVENT_HOOK_FLAG_SAFE | RUBY_EVENT_HOOK_FLAG_RAW_ARG
+	);
+	#else
+	if (NIL_P(tracer->script_compiled_tracepoint)) {
+		RB_OBJ_WRITE(self, &tracer->script_compiled_tracepoint,
+			rb_tracepoint_new(Qnil, RUBY_EVENT_SCRIPT_COMPILED,
+				Ruby_Coverage_Tracer_on_script_compiled, tracer));
+	}
+
+	rb_tracepoint_enable(tracer->script_compiled_tracepoint);
+	#endif
+
+	rb_add_event_hook(Ruby_Coverage_Tracer_on_line, RUBY_EVENT_LINE, self);
+
+	return self;
+}
+
+static VALUE Ruby_Coverage_Tracer_stop(VALUE self)
+{
+	struct Ruby_Coverage_Tracer *tracer;
+	TypedData_Get_Struct(self, struct Ruby_Coverage_Tracer, &Ruby_Coverage_Tracer_type, tracer);
+
+	#ifdef HAVE_RB_TRACEARG_INSTRUCTION_SEQUENCE
+	rb_remove_event_hook_with_data((rb_event_hook_func_t)Ruby_Coverage_Tracer_on_script_compiled, self);
+	#else
+	if (!NIL_P(tracer->script_compiled_tracepoint)) {
+		rb_tracepoint_disable(tracer->script_compiled_tracepoint);
+	}
+	#endif
+
+	rb_remove_event_hook_with_data(Ruby_Coverage_Tracer_on_line, self);
+
+	tracer->last_path_pointer = 0;
+	RB_OBJ_WRITE(self, &tracer->last_counts, Qnil);
+
+	return self;
+}
+
+void Init_Ruby_Coverage_Tracer(VALUE Ruby_Coverage)
+{
+	id_call = rb_intern("call");
+	id_instruction_sequence = rb_intern("instruction_sequence");
+	id_path = rb_intern("path");
+
+	VALUE Ruby_Coverage_Tracer = rb_define_class_under(Ruby_Coverage, "Tracer", rb_cObject);
+
+	rb_define_alloc_func(Ruby_Coverage_Tracer, Ruby_Coverage_Tracer_allocate);
+	rb_define_method(Ruby_Coverage_Tracer, "initialize", Ruby_Coverage_Tracer_initialize, 0);
+	rb_define_method(Ruby_Coverage_Tracer, "start",      Ruby_Coverage_Tracer_start,      0);
+	rb_define_method(Ruby_Coverage_Tracer, "stop",       Ruby_Coverage_Tracer_stop,       0);
+}

data/ext/ruby/coverage/tracer.h

@@ -0,0 +1,8 @@
+// Released under the MIT License.
+// Copyright, 2025, by Samuel Williams.
+
+#pragma once
+
+#include <ruby.h>
+
+void Init_Ruby_Coverage_Tracer(VALUE Ruby_Coverage);

data/lib/ruby/coverage/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+# @namespace
+module Ruby
+	# @namespace
+	module Coverage
+		VERSION = "0.0.1"
+	end
+end

data/lib/ruby/coverage.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "coverage/version"
+
+begin
+	require "Ruby_Coverage"
+rescue LoadError => error
+	warn "Could not load native coverage extension: #{error}"
+end
+
+module Ruby
+	# A reimplementation of Ruby's built-in `Coverage` module backed by
+	# `rb_add_event_hook(RUBY_EVENT_LINE)` rather than ISeq counters.
+	#
+	# The key behavioural difference: re-evaluating a file under the same path
+	# (e.g. via `module_eval`) accumulates hit counts rather than resetting
+	# them, because the counter store is owned here rather than inside the ISeq.
+	#
+	# The module-level API mirrors `::Coverage` closely enough that `covered`
+	# can multiplex between the two, preferring this implementation when
+	# available and falling back to `::Coverage` otherwise.
+	module Coverage
+		@tracer = nil
+		@files  = {}
+		
+		class << self
+			# Walk the instruction sequence to find which lines carry a
+			# RUBY_EVENT_LINE event — these are the executable lines.
+			#
+			# Lines without this event (comments, `else`, `end`, blank lines)
+			# remain nil in the counts array, matching the nil/0 distinction
+			# used by Ruby's built-in Coverage module.
+			#
+			# Recurses into child ISeqs (methods, blocks, lambdas) via
+			# `each_child` so that all executable lines across the entire
+			# compilation unit are collected.
+			#
+			# @parameter iseq [RubyVM::InstructionSequence]
+			# @returns [Array(Integer)] Sorted, deduplicated executable line numbers.
+			def executable_lines(iseq)
+				lines = []
+				current_line = nil
+				
+				iseq.to_a[13].each do |element|
+					case element
+					when Integer          then current_line = element
+					when :RUBY_EVENT_LINE then lines << current_line
+					end
+				end
+				
+				iseq.each_child{|child| lines.concat(executable_lines(child))}
+				
+				lines.sort!
+				lines.uniq!
+				lines
+			end
+			
+			# Start coverage tracking.
+			#
+			# The callback receives (path, iseq) for each newly compiled file and
+			# must return a Ruby Array to use as the line-count store for that
+			# file, or nil to skip it. Executable lines are pre-initialised to 0;
+			# non-executable lines remain nil.
+			#
+			# Safe to call multiple times; subsequent calls are no-ops.
+			# Returns self.
+			def start
+				return self if @tracer
+				
+				@files  = {}
+				@tracer = Tracer.new do |path, iseq|
+					@files[path] ||= begin
+						counts = []
+						executable_lines(iseq).each{|line| counts[line] = 0}
+						counts
+					end
+				end
+				@tracer.start
+				
+				self
+			end
+			
+			# Whether coverage is currently being tracked.
+			#
+			# @returns [Boolean]
+			def running?
+				!@tracer.nil?
+			end
+			
+			# Return the current line-count data without stopping the tracer.
+			#
+			# The returned hash has the same shape as `::Coverage.peek_result`:
+			#   { "/absolute/path.rb" => { lines: [nil, 0, 3, nil, ...] }, ... }
+			#
+			# @returns [Hash]
+			def peek_result
+				@files.transform_values{|counts| {lines: counts}}
+			end
+			
+			# Return coverage results, optionally stopping or clearing the tracer.
+			#
+			# @parameter stop [Boolean] Stop tracking after returning results
+			#   (default: true).
+			# @parameter clear [Boolean] Clear accumulated data and restart without
+			#   stopping (default: false).
+			# @returns [Hash] Same shape as {peek_result}.
+			def result(stop: true, clear: false)
+				result = peek_result
+				
+				if stop
+					@tracer&.stop
+					@tracer = nil
+					@files  = {}
+				elsif clear
+					@tracer&.stop
+					@files  = {}
+					@tracer = Tracer.new do |path, iseq|
+						@files[path] ||= begin
+							counts = []
+							executable_lines(iseq).each{|line| counts[line] = 0}
+							counts
+						end
+					end
+					@tracer.start
+				end
+				
+				result
+			end
+		end
+	end
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2026, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,71 @@
+# Ruby::Coverage
+
+A native reimplementation of Ruby's built-in `Coverage` module, backed by `rb_add_event_hook(RUBY_EVENT_LINE)` rather than ISeq counters.
+
+[![Development Status](https://github.com/socketry/ruby-coverage/workflows/Test/badge.svg)](https://github.com/socketry/ruby-coverage/actions?workflow=Test)
+
+## Motivation
+
+Ruby's built-in `Coverage` module ties its counter store to the ISeq. When a file is re-evaluated under the same path — for example when a test framework loads a file into a fresh anonymous module via `module_eval` — Ruby allocates a fresh counter array and discards the previous one. Any coverage accumulated before the re-eval is lost.
+
+`Ruby::Coverage` owns its own counter store. Re-evaluating a file under the same path simply continues incrementing the same counters. The `covered` gem can optionally use `Ruby::Coverage` in place of `::Coverage` to get correct results in test suites that load files multiple times.
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/ruby-coverage/) for more details.
+
+  - [Getting Started](https://socketry.github.io/ruby-coverage/guides/getting-started/index) - This guide explains how to use `ruby-coverage` to collect coverage for code that may be evaluated multiple times under the same path.
+
+### Drop-in module API
+
+``` ruby
+require "ruby/coverage"
+
+Ruby::Coverage.start
+
+# ... run code ...
+
+result = Ruby::Coverage.result
+# => { "/path/to/file.rb" => { lines: [nil, 3, 1, nil, 0, ...] }, ... }
+```
+
+### Low-level `Tracer`
+
+`Ruby::Coverage::Tracer` is the primitive that the module API is built on. It accepts a block that is called once each time execution enters a new file. The block receives the absolute path and must return a Ruby `Array` to use as the line-count store for that file, or `nil` to skip tracking it.
+
+The block controls the caching strategy: returning the same `Array` for the same path accumulates counts across re-evals; returning a fresh `Array` each time gives per-ISeq isolation.
+
+``` ruby
+files = {}
+
+tracer = Ruby::Coverage::Tracer.new do |path|
+	# Accumulate across re-evals of the same path:
+	files[path] ||= []
+end
+
+tracer.start
+# ... run tests ...
+tracer.stop
+
+# files is now populated with line-count arrays keyed by path.
+```
+
+## Integration with `covered`
+
+`covered` multiplexes between `Ruby::Coverage` and `::Coverage` internally. Add `ruby-coverage` to your `Gemfile` and `covered` will prefer it automatically.
+
+``` ruby
+# gems.rb / Gemfile
+gem "ruby-coverage"
+gem "covered"
+```
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/ruby-coverage/releases/index) for all releases.
+
+### v0.0.1
+
+## See Also
+
+  - [covered](https://github.com/socketry/covered) — the coverage reporting gem that uses this library.

data/releases.md

@@ -0,0 +1,3 @@
+# Releases
+
+## v0.0.1

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: ruby-coverage
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions:
+- ext/extconf.rb
+extra_rdoc_files: []
+files:
+- ext/extconf.rb
+- ext/ruby/coverage/coverage.c
+- ext/ruby/coverage/coverage.h
+- ext/ruby/coverage/tracer.c
+- ext/ruby/coverage/tracer.h
+- lib/ruby/coverage.rb
+- lib/ruby/coverage/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/ruby-coverage
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/ruby-coverage/
+  source_code_uri: https://github.com/socketry/ruby-coverage.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: A native reimplementation of Ruby's Coverage module with accumulating line
+  counts.
+test_files: []