fast_cov 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ce0e302b02e7989034b39bd84cc69e7563378edb3ec31d10491899a4da74bac
-  data.tar.gz: 7273c905846579200383b0409d91ae8ea8066102e1c91d50af5a4c601e03f06e
+  metadata.gz: c1319e05ab0d7a740626e94ed880dacb09b980dfc0ededc6b1c0259383fb0667
+  data.tar.gz: dd7af260d917264ab2f30affbc3dd2dfa44f5ddba03bc8d1f8dd222e29a9817e
 SHA512:
-  metadata.gz: 149d759f1b8005b69741319655c2366b8ff3f0422b8c978418942e50f67a0b81b6077e7810c0a70aad56bf80fe130f2fc7b4003f55dc28ac0780d3ce2b847dcb
-  data.tar.gz: 6b8a1e08762f8fdcc4d2488f9c49348c38f5701499fd96550fdb4362cf64089ca76e55ecbfb6d50523cb190e15ed588b4162e873b3419b238d3a1680a6f97016
+  metadata.gz: 6b594da4510ba6bb43767030b4d25e3f7787e22923b6e76b48616f2a085c030d22c1d870976570f7ac74fe921fe2c1eabbeeb16471ec8a533588f9d5b9974fef
+  data.tar.gz: 98f1b25e2565a56af55e472096a4c3159110b27117b99682cd031888083ec68d5aef8788aeff7a2538af9a5287f588653f8717ee30160e1126f127a0316191ea

data/README.md

@@ -1,6 +1,6 @@
 # FastCov
 
-A high-performance native C extension for tracking which Ruby source files are executed during test runs. Built for test impact analysis -- run only the tests affected by your code changes.
+A high-performance native C extension for tracking which Ruby source files are executed during test runs. Built for test impact analysis.
 
 FastCov hooks directly into the Ruby VM's event system, avoiding the overhead of Ruby's built-in `Coverage` module. The result is file-level coverage tracking with minimal performance impact.
 
@@ -23,229 +23,128 @@ Then:
 bundle install
 ```
 
-The C extension compiles automatically during gem installation.
-
 ## Quick start
 
 ```ruby
 require "fast_cov"
 
-FastCov.configure do |config|
-  config.root = File.expand_path("app")
-  config.use FastCov::CoverageTracker
-  config.use FastCov::FileTracker
-end
+coverage = FastCov::CoverageMap.new
+coverage.root = File.expand_path("app")
+coverage.use(FastCov::FileTracker)
 
-result = FastCov.start do
+result = coverage.start do
   # ... run a test ...
 end
 
-# => { "models/user.rb" => true, "config.yml" => true, ... }
+# => #<Set: {"models/user.rb", "config/settings.yml"}>
 ```
 
-`stop` returns a hash where each key is the path (relative to `root`) of a file that was touched during the coverage window.
+`CoverageMap#stop` returns a `Set` of paths relative to `root`.
 
-## Configuration
+## CoverageMap
 
-Call `FastCov.configure` before using `start`/`stop`. The block yields a `Configuration` object:
+`FastCov::CoverageMap` is the primary API.
 
 ```ruby
-FastCov.configure do |config|
-  config.root = Rails.root
-  config.ignored_path = Rails.root.join("vendor")
-  config.threads = true
+coverage = FastCov::CoverageMap.new
+coverage.root = Rails.root.to_s
+coverage.threads = true
+coverage.ignored_paths = Rails.root.join("vendor")
 
-  config.use FastCov::CoverageTracker
-  config.use FastCov::FileTracker
-end
+coverage.use(FastCov::FileTracker)
+coverage.use(FastCov::FactoryBotTracker)
 ```
 
-### Config options
+### Options
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `root` | String | `Dir.pwd` | Absolute path to the project root. Only files under this path are tracked. |
-| `ignored_path` | String | `nil` | Path prefix to exclude (e.g., vendor/bundle). |
+| `root` | String | `Dir.pwd` | Absolute project root. Returned paths are relativized to this root. |
 | `threads` | Boolean | `true` | `true` tracks all threads. `false` tracks only the thread that called `start`. |
+| `ignored_paths` | String, Pathname, or Array | `[]` | Paths under `root` to exclude from tracking. Single values are wrapped into an array, and relative entries are resolved against `root` when coverage starts. |
 
-### Registering trackers
-
-Trackers are registered with `config.use`. Each tracker receives the config object and any options you pass:
-
-```ruby
-config.use FastCov::CoverageTracker
-config.use FastCov::CoverageTracker, constant_references: false
-config.use FastCov::FileTracker, ignored_path: "/custom/ignore"
-```
-
-## Singleton API
+### Lifecycle
 
 ```ruby
-FastCov.configure { |c| ... }  # Configure and install trackers
-FastCov.start                  # Start all trackers. Returns FastCov.
-FastCov.stop                   # Stop all trackers. Returns merged results hash.
-FastCov.start { ... }          # Block form: start, yield, stop. Returns results.
-FastCov.configured?            # true after configure, false after reset.
-FastCov.reset                  # Clear configuration and trackers.
+coverage.start        # starts tracking and returns the CoverageMap
+coverage.stop         # stops tracking and returns a Set
+coverage.start { ... } # block form: start, yield, stop
 ```
 
-### RSpec integration
-
-```ruby
-# spec/support/fast_cov.rb
-FastCov.configure do |config|
-  config.root = Rails.root
-  config.use FastCov::CoverageTracker
-  config.use FastCov::FileTracker
-end
-
-RSpec.configure do |config|
-  config.around(:each) do |example|
-    result = FastCov.start { example.run }
-    # result is a hash of impacted file paths
-  end
-end
-```
+Native line coverage is always enabled. Extra trackers registered with `use` are additive.
 
 ## Trackers
 
-### CoverageTracker
-
-Wraps the native C extension. Handles line event tracking, allocation tracing, and constant reference resolution.
-
-```ruby
-config.use FastCov::CoverageTracker
-```
-
-#### Options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `root` | String | `config.root` | Override the root path for this tracker. |
-| `ignored_path` | String | `config.ignored_path` | Override the ignored path for this tracker. |
-| `threads` | Boolean | `config.threads` | Override the threading mode for this tracker. |
-| `allocations` | Boolean | `true` | Track object allocations and resolve class hierarchies to source files. |
-| `constant_references` | Boolean | `true` | Parse source with Prism for constant references and resolve them to defining files. |
-
-#### What it tracks
-
-**Line events** -- hooks `RUBY_EVENT_LINE` to record which files execute. Uses pointer caching (`rb_sourcefile()` returns stable pointers) to skip redundant file checks with a single integer comparison.
-
-**Allocation tracing** (`allocations: true`) -- hooks `RUBY_INTERNAL_EVENT_NEWOBJ` to capture `T_OBJECT` and `T_STRUCT` allocations. At stop time, walks each instantiated class's ancestor chain and resolves every ancestor to its source file. This catches empty models, structs, and Data objects that line events alone would miss.
-
-**Constant reference resolution** (`constant_references: true`) -- at stop time, parses tracked files with Prism and walks the AST for `ConstantPathNode` and `ConstantReadNode` to extract constant references, then resolves each constant to its defining file via `Object.const_source_location`. Resolution is transitive (up to 10 rounds) and cached by filename for the lifetime of the process.
-
-#### Disabling expensive features
-
-For maximum speed when you only need line-level file tracking:
-
-```ruby
-config.use FastCov::CoverageTracker, allocations: false, constant_references: false
-```
-
-This disables the NEWOBJ hook (no per-allocation overhead) and skips AST parsing at stop time.
-
 ### FileTracker
 
-Tracks files read from disk during coverage -- JSON, YAML, ERB templates, or any file accessed via `File.read` or `File.open`.
+Tracks files read from disk during coverage, including JSON, YAML, ERB templates, and any file accessed via `File.read` or read-mode `File.open`.
 
 ```ruby
-config.use FastCov::FileTracker
+coverage.use(FastCov::FileTracker)
 ```
 
-#### Options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `root` | String | `config.root` | Override the root path for this tracker. |
-| `ignored_path` | String | `config.ignored_path` | Override the ignored path for this tracker. |
-| `threads` | Boolean | `config.threads` | Override the threading mode for this tracker. |
-
-#### How it works
-
-Prepends a module on `File.singleton_class` to intercept `File.read` and `File.open` (read-mode only). When a file within the root is read during coverage, its path is recorded. Write operations (`"w"`, `"a"`, etc.) are ignored.
-
-This catches `YAML.load_file`, `JSON.parse(File.read(...))`, `CSV.read`, ERB template loading, and any other pattern that goes through `File.read` or `File.open`.
-
 ### FactoryBotTracker
 
-Tracks FactoryBot factory definition files when factories are used during tests. Factory files are typically loaded at boot time before coverage starts, so this tracker intercepts `FactoryBot.factories.find` to record the source file where each factory was defined.
+Tracks FactoryBot factory definition files when factories are used. This is useful because factory files are often loaded before coverage starts.
 
 ```ruby
-config.use FastCov::FactoryBotTracker
+coverage.use(FastCov::FactoryBotTracker)
 ```
 
-**Requires:** The `factory_bot` gem must be installed. Raises `LoadError` if FactoryBot is not defined.
-
-#### Options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `root` | String | `config.root` | Override the root path for this tracker. |
-| `ignored_path` | String | `config.ignored_path` | Override the ignored path for this tracker. |
-| `threads` | Boolean | `config.threads` | Override the threading mode for this tracker. |
-
-#### How it works
-
-Prepends a module on `FactoryBot.factories.singleton_class` to intercept the `find` method (called by `create`, `build`, etc.). When a factory is used, the tracker walks its declaration blocks and extracts `source_location` from each proc to find the factory definition file.
-
 ### ConstGetTracker
 
-Tracks constants looked up dynamically via `Module#const_get`. This catches dynamic constant lookups that static analysis (Prism) would miss.
+Tracks constants looked up dynamically via `Module#const_get`.
 
 ```ruby
-config.use FastCov::ConstGetTracker
+coverage.use(FastCov::ConstGetTracker)
 ```
 
-#### What it catches
+This catches patterns such as:
 
 - `Object.const_get("Foo::Bar")`
-- Rails' `"UserMailer".constantize` (uses `const_get` under the hood)
-- Any metaprogramming that looks up constants by string name
+- Rails `"UserMailer".constantize`
+- metaprogramming that resolves constants from strings
 
-**Note:** This does NOT catch direct constant references like `Foo::Bar` in source code -- those compile to `opt_getconstant_path` bytecode and bypass `const_get`. Use `CoverageTracker` with `constant_references: true` for static analysis of literal constant references.
+It does not catch direct constant references such as `Foo::Bar` in source code.
 
-#### Options
+## Low-level native coverage
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `root` | String | `config.root` | Override the root path for this tracker. |
-| `ignored_path` | String | `config.ignored_path` | Override the ignored path for this tracker. |
-| `threads` | Boolean | `config.threads` | Override the threading mode for this tracker. |
+`FastCov::Coverage` is still available as a low-level primitive:
 
-#### How it works
+```ruby
+cov = FastCov::Coverage.new(
+  root: "/repo/app",
+  ignored_paths: ["/repo/app/vendor"],
+  threads: true
+)
+```
 
-Prepends a module on `Module` to intercept `const_get` calls. When a constant is looked up, the tracker calls `const_source_location` to find where the constant was defined and records that file.
+This API is mainly useful for internal use and low-level tests. `CoverageMap` is the intended public orchestration API.
 
 ## Writing custom trackers
 
-There are two approaches to writing custom trackers: from scratch (minimal interface) or inheriting from `AbstractTracker` (batteries included).
+There are two approaches: a minimal custom tracker, or inheriting from `AbstractTracker`.
 
 ### Option 1: From scratch
 
-Any object that responds to `start` and `stop` can be a tracker. This is the minimal interface:
+Any object that responds to `start` and `stop` can be used.
 
 ```ruby
 class MyTracker
-  def initialize(config, **options)
-    @config = config
+  def initialize(coverage_map, **options)
+    @coverage_map = coverage_map
     @options = options
-    @files = {}
+    @files = Set.new
   end
 
   def install
-    # Optional: one-time setup (called during configure)
-    # Good place to patch classes, set up hooks, etc.
   end
 
   def start
-    @files = {}
-    # Begin tracking
+    @files = Set.new
   end
 
   def stop
-    # Stop tracking and return results
-    # Paths should be absolute; FastCov will relativize them to config.root
     @files
   end
 end
@@ -253,23 +152,21 @@ end
 
 ### Option 2: Inherit from AbstractTracker
 
-`AbstractTracker` provides common functionality out of the box:
+`AbstractTracker` provides:
 
-- **Path filtering** — Only records files within `root`, excludes `ignored_path`
-- **Thread-aware recording** — Respects the `threads` option
-- **Lifecycle management** — Handles `@files` hash and `active` class attribute
+- path filtering through the owning `CoverageMap`
+- thread-aware recording
+- lifecycle management
+- class-level `record` dispatch for patched hooks
 
 ```ruby
 class MyTracker < FastCov::AbstractTracker
   def install
-    # Patch the class/module you want to track
     SomeClass.singleton_class.prepend(MyPatch)
   end
 
   module MyPatch
     def some_method(...)
-      # Record the file when this method is called
-      # Uses inherited class method - no need to check .active
       MyTracker.record(some_file_path)
       super
     end
@@ -277,91 +174,29 @@ class MyTracker < FastCov::AbstractTracker
 end
 ```
 
-#### AbstractTracker hooks
-
-Override these methods as needed:
-
-| Method | When called | Purpose |
-|---|---|---|
-| `install` | Once during `configure` | Set up patches, hooks, instrumentation |
-| `on_start` | At the beginning of `start` | Initialize tracker-specific state |
-| `on_stop` | At the beginning of `stop` | Clean up tracker-specific state |
-| `on_record(path)` | When `record(path)` is called | Return `true` to record, `false` to skip |
+#### Hooks
 
-The base `record(path)` method handles path filtering and thread checks before calling `on_record`.
-
-#### Full example: tracking ActiveRecord queries
-
-```ruby
-class QueryTracker < FastCov::AbstractTracker
-  def install
-    return unless defined?(ActiveSupport::Notifications)
-
-    ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
-      # Extract the caller location from the backtrace
-      caller_locations(1, 20).each do |loc|
-        path = loc.absolute_path
-        next unless path
-
-        # Uses inherited class method - safely no-ops if tracker isn't active
-        QueryTracker.record(path)
-        break
-      end
-    end
-  end
-end
-```
-
-### Tracker lifecycle
-
-1. `initialize(config, **options)` — Called when registered via `config.use`
-2. `install` — Called once after all trackers are registered
-3. `start` — Called on `FastCov.start` (in registration order)
-4. `stop` — Called on `FastCov.stop` (in reverse order), must return `{ path => true }`
-
-Results from all trackers are merged, with later trackers overwriting earlier ones for duplicate keys.
-
-## Cache
-
-FastCov caches constant reference resolution results in memory so files only need parsing once per process. The cache is process-level, keyed by filename, and populated automatically during `stop`.
-
-```ruby
-FastCov::Cache.data      # the raw cache hash
-FastCov::Cache.clear     # empty the cache
-FastCov::Cache.data = {} # replace cache contents
-```
+| Method | When called |
+|---|---|
+| `install` | Once when the tracker is registered with `CoverageMap#use` |
+| `on_start` | At the beginning of `start` |
+| `on_stop` | At the beginning of `stop` |
+| `on_record(path)` | Before a path is added to the result set |
 
 ## Local development with path: gems
 
 When developing FastCov alongside a consuming project, use the compile entrypoint to auto-compile the C extension:
 
 ```ruby
-# Gemfile
 gem "fast_cov", path: "../fast_cov", require: "fast_cov/dev"
 ```
 
-This compiles on first use and detects source changes for recompilation.
-
 ## Development
 
 ```sh
 git clone <repo>
 cd fast_cov
 bundle install
-bundle exec rake compile  # compile the C extension
-bundle exec rake spec     # run tests (compiles first)
+bundle exec rake compile
+bundle exec rspec --fail-fast
 ```
-
-### Benchmarking
-
-```sh
-bin/benchmark --baseline   # save current performance as baseline
-# ... make changes ...
-bin/benchmark              # compare against baseline
-```
-
-Override iteration count: `ITERATIONS=5000 bin/benchmark`
-
-## License
-
-MIT