simplecov-ai 0.10.6 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb0ee3780e192789926c8cf8b891596209c8304525436d11091f34ab4d7f86c6
-  data.tar.gz: e32fbea00cde5bad4d546942f69461f646aa0dbf687731401d3c9a249d692015
+  metadata.gz: c74a6bfde86ee9beeaf6a02adb04c043878e1c2d7c6e4fc173a00a9d479998de
+  data.tar.gz: 98dc5d09ad61af95a6ffd131ee5b96a07fbda217000bb1e4af032d8024ba2fd8
 SHA512:
-  metadata.gz: 37a92b9aad862aa0952f7ab712182b35e55d04ce4982656f8de5bc4ead4a00827bd92fa74e272978af69d84f9a79268e98fc20c25e50afce02d0cb73c7b83013
-  data.tar.gz: e0eef35acaab28b50c50a9d0d5fbcf5166b66fa67dbc83382b95a9bb29e889625c3be4b33d0d2bcaf3316c386e2f4d38facbf85135e097f028f02d0e38676b51
+  metadata.gz: 6e19f160818648eafc77ce7865d47df9e439a7de3004de11b483d3eefd2e458c025fa94ee0ad8615e062c7898012e1e66072510506a15a128164c1a6fa172db2
+  data.tar.gz: 0e0ec8706c0a2545047ed541a783566cc802a32776f84eb45ad5a80afa65fac7508d9007224ada990f536ce4bce05d008ce9e667c048fdd8b42a370278d7dd0f

data/README.md

@@ -1,19 +1,45 @@
 # simplecov-ai
 
-A custom `SimpleCov::Formatter` designed explicitly for consumption by Large Language Models (LLMs) and autonomous engineering agents. 
+A `SimpleCov::Formatter` that writes a compact Markdown digest of missing coverage for Large
+Language Models (LLMs) and autonomous engineering agents.
 
-Standard coverage reporters generate massive HTML files or exhaustive JSON/console outputs detailing every line number. This overwhelms strict LLM token constraints and relies on highly volatile line numbers. `simplecov-ai` solves this by generating a concise, structurally optimized **Markdown document** containing only the exact missing semantic coverage blocks.
+Standard coverage reporters produce large HTML files or exhaustive JSON/console output keyed by
+line numbers, which fills an LLM's context window with coordinates that shift on every edit.
+`simplecov-ai` resolves each missed line and branch to its enclosing module, class or method
+through the Ruby AST and emits only those semantic groups, each with the exact unexecuted
+expression.
 
-## Why use simplecov-ai?
+## What the digest contains
 
-- **Semantic Resolution:** Instead of volatile line numbers, missing coverage is resolved via Abstract Syntax Tree (AST) mapping into immutable semantic groupings (e.g., Class, Module, Instance Method).
-- **Maximum Token Conservation:** Fully covered files are completely omitted. If the report exceeds size limits, it safely truncates the output prioritizing the lowest-coverage files.
-- **Actionable Delta Directives:** Missing branches and lines are mapped directly to method names, letting the AI instantly search the code and write targeted specs.
-- **Directive Auditing:** Explicitly reports `:nocov:` bypasses, ensuring artificial metric inflation is completely transparent to the reviewing AI.
+- **Semantic resolution.** Deficits are grouped under the innermost enclosing node:
+  `Module::Class#method` for instance methods, `Module::Class.method` for singleton methods
+  (`def self.x`, `class << self`), constants bound to `Struct.new`, `Class.new`, `Module.new` or
+  `Data.define` blocks (`Point#distance`), `define_method` / `define_singleton_method` blocks with
+  a literal name, and `class << obj` singleton classes opened on a variable or constant
+  (`obj.name`, `@ivar.name`, `Foo::Bar.name`). A method defined at the top level is `Object#name`
+  (Ruby adds it to `Object`, which is how SimpleCov's method coverage names it too) and a top-level
+  `def self.x` is `main.x`; any other code outside a class or method belongs to `main`, the root
+  scope of the file.
+- **Exact snippets.** Each deficit carries its line(s) as `[L<n>]` or `[L<n>-<m>]` and the exact
+  source text: a missed branch quotes only its own arm (the `:neg` of `x.positive? ? :pos : :neg`),
+  the `else` arm that spans an `elsif` chain is cut to its first line plus `...`, and identical
+  lines within one node are told apart with `(Occurrence N of M)`.
+- **Token conservation.** Fully covered files are omitted, the `## Coverage Deficits` section
+  disappears on a perfect run, and `max_file_size_kb` is a hard ceiling on the written file.
+- **Bypass audit.** Every region SimpleCov skipped (`# :nocov:`, `# simplecov:disable`) is listed
+  with the directive that caused it, so artificially inflated metrics stay visible to the reader.
+- **Method coverage.** With SimpleCov >= 1.0 and `enable_coverage :method`, never-invoked methods
+  are reported too.
 
-## Installation
+## Requirements
+
+- **Ruby** 2.7 through 4.0 (MRI). JRuby and TruffleRuby run the formatter but implement no branch
+  coverage, so only line deficits are reported there and the header shows `N/A` for branches.
+- **SimpleCov** `>= 0.18, < 2.0`. Branch coverage needs `enable_coverage :branch`. Method
+  coverage and `# simplecov:disable` directives are SimpleCov 1.x features; on older releases they
+  are neither measured nor reported.
 
-Add this line to your application's `Gemfile` strictly in the `test` group:
+## Installation
 
 ```ruby
 group :test do
@@ -22,67 +48,212 @@ group :test do
 end
 ```
 
-## Usage & Configuration
+## Usage
 
-Require and configure the formatter in your test helper (`spec_helper.rb` or `test_helper.rb`) after requiring `simplecov`:
+Require the formatter after `simplecov` in your test helper and register it with SimpleCov:
 
 ```ruby
 require 'simplecov'
 require 'simplecov-ai'
 
-# Optional Configuration (defaults shown below):
-SimpleCov::Formatter::AIFormatter.configure do |config|
-  config.report_path = 'coverage/ai_report.md'      # Output location
-  config.max_file_size_kb = 50                      # Maximum size (Token Ceiling)
-  config.max_snippet_lines = 5                      # AST context truncation limit
-  config.output_to_console = false                  # Echo digest to STDOUT
-  config.granularity = :fine                        # :fine (statements) or :coarse (methods)
-  config.include_bypasses = true                    # Audit `:nocov:` ignores
+SimpleCov.start do
+  enable_coverage :branch
+  skip '/spec/'         # SimpleCov >= 1.0; use `add_filter '/spec/'` on 0.x (1.x deprecates it)
 end
 
-SimpleCov.start do
-  # Combine with your existing formatters
-  SimpleCov.formatters = SimpleCov::Formatter::MultiFormatter.new([
-    SimpleCov::Formatter::HTMLFormatter,
-    SimpleCov::Formatter::AIFormatter
-  ])
+SimpleCov.formatter = SimpleCov::Formatter::AIFormatter
+# Alongside other formatters:
+# SimpleCov.formatters = [SimpleCov::Formatter::HTMLFormatter, SimpleCov::Formatter::AIFormatter]
+```
+
+When the suite exits, the formatter writes the report and announces it on STDOUT:
+
+```text
+AI coverage digest written to /path/to/project/coverage/ai_report.md
+```
+
+### Configuration
+
+All settings are optional; the defaults are shown:
+
+```ruby
+SimpleCov::Formatter::AIFormatter.configure do |config|
+  config.report_path = 'coverage/ai_report.md' # default: ai_report.md inside SimpleCov's coverage_dir
+  config.max_file_size_kb = 50                 # hard ceiling on the written file (metric kB)
+  config.max_snippet_lines = 5                 # snippets longer than 5 x 80 characters end in `...`
+  config.output_to_console = false             # true: print the digest to STDOUT instead of the notice
+  config.granularity = :fine                   # :fine (every line/branch) or :coarse (one line per node)
+  config.include_bypasses = true               # false: omit the "Ignored Coverage Bypasses" section
 end
 ```
 
-## Example Output
+- `report_path` — unset, the digest goes to `ai_report.md` inside `SimpleCov.coverage_path`, so
+  a custom `coverage_dir` is honoured (the reader reports this default as
+  `coverage/ai_report.md`). An explicit absolute path is used as-is; an explicit relative path is
+  resolved against `SimpleCov.root`, independent of the working directory at exit. Blank values
+  and values containing a NUL byte are rejected.
+- `max_file_size_kb`, `max_snippet_lines` — positive Integers.
+- `granularity` — `:fine` or `:coarse`.
+- `output_to_console`, `include_bypasses` — `true` or `false`.
+
+Every setting is validated when it is assigned: a value of the wrong type raises `TypeError`
+(the writers are typed with sorbet-runtime) and an out-of-range value raises `ArgumentError`
+naming the setting, for example `granularity must be one of [:fine, :coarse], got :medium`.
+`SimpleCov::Formatter::AIFormatter.reset_configuration!` discards the configuration so the next
+access starts from the defaults (useful in test suites).
+
+## Example output
 
-The output is written to `coverage/ai_report.md` (or your configured path), perfect for providing directly as context to an LLM:
+Generated from a small sample project on Ruby 4.0 and SimpleCov 1.1.1, trimmed by one file and
+one node that quotes a 300-character line:
 
 ```md
 # AI Coverage Digest
 **Status:** FAILED
-**Global Line Coverage:** 92.5%
-**Global Branch Coverage:** 88.0%
-**Generated At:** 2026-04-21T23:40:44+09:00 (Local Timezone)
-**Report File Size:** 1.2 kB
-
+**Global Line Coverage:** 69.3%
+**Global Branch Coverage:** 38.4%
+**Generated At:** 2026-08-28T06:05:29+00:00 (Local Timezone)
 ## Coverage Deficits
 
-### `lib/my_gem/client.rb`
-- `MyGem::Client#authenticate!`
-  - **Branch Deficit:** Missing coverage for conditional evaluation handling `ExpiredTokenError`.
-- `MyGem::Client#initialize`
-  - **Line Deficit:** Variable initialization state uncovered.
+### `lib/sample/weird.rb`
+- `Sample::Weird#dupes`
+  - **Line Deficit:** [L11] `a += 1` (Occurrence 1 of 3).
+  - **Line Deficit:** [L12] `a += 1` (Occurrence 2 of 3).
+  - **Line Deficit:** [L13] `a += 1` (Occurrence 3 of 3).
+  - **Line Deficit:** [L14] `a`
+
+### `lib/sample/calc.rb`
+- `Sample::Calc#sign`
+  - **Branch Deficit:** [L7] Missing coverage for `else` branch: `:neg`
+- `Sample::Calc#classify`
+  - **Line Deficit:** [L13] `elsif n.odd?`
+  - **Line Deficit:** [L14] `:odd`
+  - **Line Deficit:** [L16] `:even`
+  - **Branch Deficit:** [L13-17] Missing coverage for `else` branch: `elsif n.odd?...`
+  - **Branch Deficit:** [L14] Missing coverage for `then` branch: `:odd`
+  - **Branch Deficit:** [L16] Missing coverage for `else` branch: `:even`
+- `Sample::Calc#bucket`
+  - **Line Deficit:** [L23] `when 2 then :two`
+  - **Line Deficit:** [L24] `else :many`
+  - **Branch Deficit:** [L23] Missing coverage for `when` branch: `:two`
+  - **Branch Deficit:** [L24] Missing coverage for `else` branch: `:many`
+- `Sample::Calc#never_called`
+  - **Line Deficit:** [L29] `@never = 1`
+  - **Line Deficit:** [L30] `@never += 1`
+- `Sample::Calc.unused_factory`
+  - **Line Deficit:** [L55] `new.tap { |c| c.sign(1) }`
+- `Sample::Point#origin?`
+  - **Line Deficit:** [L66] `x.zero? && y.zero?`
 
-### `lib/my_gem/parser/processor.rb`
-- `MyGem::Parser::Processor.parse_stream`
-  - **Branch Deficit:** Missing coverage for early-exit condition `break if stream.closed?` (Occurrence 1 of 2).
+### `lib/sample/boot.rb`
+- `main`
+  - **Branch Deficit:** [L9] Missing coverage for `then` branch: `true`
 
 ## Ignored Coverage Bypasses
 
-### `lib/my_gem/legacy_handler.rb`
-- `MyGem::LegacyHandler#obsolete_action`
-  - **Bypass Present:** Contains `:nocov:` directive artificially ignoring coverage (Occurrence 1 of 1).
+### `lib/sample/boot.rb`
+- `main`
+  - **Bypass Present:** Coverage explicitly ignored via `# :nocov:`.
+
+### `lib/sample/calc.rb`
+- `Sample::Calc#legacy_skipped`
+  - **Bypass Present:** Coverage explicitly ignored via `# :nocov:`.
+- `Sample::Calc#inline_disabled`
+  - **Bypass Present:** Coverage explicitly ignored via `# simplecov:disable`.
+- `Sample::Calc#branch_scoped`
+  - **Bypass Present:** Coverage explicitly ignored via `# simplecov:disable branch`.
 ```
 
-## Error Handling
+Things to notice:
+
+- Files are ordered by coverage, lowest first (path as the tie-break); nodes appear in source
+  order.
+- `main` is the root scope of `lib/sample/boot.rb`: the missed `then` arm belongs to a top-level
+  statement (`SAMPLE_DEBUG = ENV['SAMPLE_DEBUG'] ? true : false`), and the `# :nocov:` region
+  wraps only top-level code.
+- `[L13-17] … elsif n.odd?...` is the `else` arm of the outer `if` in `classify`; it spans the
+  whole `elsif` chain, so it is cut to its first line instead of repeating the inner arms.
+- The `Status` is `PASSED` only when every measured criterion is at 100%, and percentages are
+  floored to one decimal, so a run at 99.96% reads `99.9%`.
+
+### Method coverage (SimpleCov >= 1.0)
+
+With `enable_coverage :method` the header gains a method line, the status accounts for it, and
+each never-invoked method is listed under its node before its line and branch deficits. From the
+same sample:
+
+```md
+**Global Method Coverage:** 53.3%
+```
+
+```md
+- `Sample::Calc#never_called`
+  - **Method Deficit:** [L28-31] `Sample::Calc#never_called` never invoked
+  - **Line Deficit:** [L29] `@never = 1`
+  - **Line Deficit:** [L30] `@never += 1`
+```
+
+### Bypass audit
+
+The `## Ignored Coverage Bypasses` section lists what SimpleCov actually skipped, attributed to
+the outermost nodes a skipped region contains (or to the node enclosing it, `main` at worst), with
+the directive comment quoted verbatim as the reason. Because it is derived from SimpleCov's own
+skip verdicts rather than from a second scan of the comments:
+
+- `# :nocov:` pairs (including a custom `nocov_token`), inline `# simplecov:disable` comments and
+  `# simplecov:disable line` / `# simplecov:disable branch` regions are all reported;
+- a directive inside a heredoc, which SimpleCov ignores, is not reported;
+- a skipped region made only of comments and blank lines is not reported either, since it excludes
+  nothing from any figure — SimpleCov 1.x honours a directive wherever it appears in a comment, so
+  a comment that merely quotes `# simplecov:disable` skips its own line;
+- on SimpleCov < 1.0, which does not implement `# simplecov:disable`, those lines stay ordinary
+  deficits and only `# :nocov:` regions appear. The same sample on SimpleCov 0.22.0 lists
+  `raise 'unreachable' # simplecov:disable` as a line deficit and a single bypass.
+
+SimpleCov 1.x itself deprecates `# :nocov:` in favour of `# simplecov:disable` /
+`# simplecov:enable`; both are audited.
+
+### Size ceiling
+
+`max_file_size_kb` bounds the written file. Both sections are filled lowest-coverage file first,
+one semantic node at a time, until the next node would no longer fit; a single notice then closes
+the report. With a 1 kB limit the sample above ends in:
+
+```md
+> **[WARNING] TRUNCATION NOTIFICATION:**
+> The report reached the maximum token constraint (1 kB) and was truncated: 3 deficit file(s) and 2 bypass file(s) omitted or cut short. Lowest-coverage files are listed first; resolve the deficits above to reveal the remaining ones in subsequent test runs.
+```
+
+A file whose block was cut short counts towards those numbers. No notice is printed when
+everything fits.
+
+## Parser backend
+
+Sources are parsed with Prism's `parser`-compatible translation on Ruby >= 3.3 when Prism >= 1.2
+and `parser` >= 3.3.7.2 are installed (the exact grammar of the running Ruby, about twice as fast
+as the `parser` gem); otherwise the `parser` gem's grammar for the running Ruby is used, with
+`parser/current` as a muted last resort. Ruby 2.7 to 3.2 always use the `parser` gem. The
+selection happens once at load time, and no parser diagnostic — including the
+`parser/current is loading …` version warning — is ever written to STDERR.
+
+## Error handling
+
+Reporting is best-effort and never aborts a passing test run. A file the parser cannot process is
+listed with its raw line numbers under an `AST Parsing Failed` notice while the other files are
+resolved normally. Sources are read as bytes and decoded per their `# encoding:` magic comment or
+byte-order mark, string literals whose escapes are invalid in UTF-8 (`"\xf0-\xff"`) are accepted
+as MRI accepts them, and a file that cannot be read at all is reported without snippets (each
+shown as a code span holding one space). Branch column data that a SimpleCov version does not
+provide degrades to full-line snippets. Snippets, names, paths and directive comments are rendered
+as code spans that stay intact whatever characters they contain (see `SECURITY.md`). If the
+report itself cannot be written — a `report_path` whose parent is a regular file, a read-only or
+full disk — the formatter prints `AI coverage digest could not be written to <path> (<error>)` on
+STDERR, still echoes the digest when `output_to_console` is set, and does not raise from
+SimpleCov's `at_exit` hook.
 
-Adhering to fail-fast principles, if the AST parser encounters structurally unparseable Ruby code or corrupt telemetry, it will gracefully degrade or explicitly fail. It will not silently ignore failures or emit corrupted artifacts.
+One limitation: nodes are resolved by line, so two definitions on one line
+(`def a; 1; end; def b; 2; end`) both resolve to the line's last node; a method deficit keeps the
+name SimpleCov derived unless that node carries the method's own name.
 
 ## License
 

data/lib/simplecov-ai/ast_resolver/bypass_scanner.rb

@@ -0,0 +1,69 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class ASTResolver
+        # Attributes coverage-skip regions (line ranges SimpleCov excluded from its metrics,
+        # each paired with the directive text that caused the exclusion) to the semantic nodes
+        # they cover. A region is attributed to the outermost semantic nodes it fully contains,
+        # or — when it sits inside a single node — to that innermost enclosing node; a region
+        # wrapping only top-level code therefore lands on the root scope.
+        module BypassScanner
+          extend T::Sig
+
+          # A skipped line range together with the reason SimpleCov skipped it.
+          Region = T.type_alias { [T::Range[Integer], String] }
+          # Reasons keyed by the node they apply to.
+          ReasonsByNode = T.type_alias { T::Hash[SemanticNode, T::Array[String]] }
+
+          # Attributes every region to the matching semantic nodes. The result is a pure
+          # function of its inputs: nodes are never mutated, and a reason is listed once per
+          # node even when several regions inside that node carry the same directive text.
+          #
+          # @param nodes [Array<SemanticNode>] The resolved structural entities in pre-order.
+          # @param regions [Array<Array(Range<Integer>, String)>] Skipped ranges with reasons.
+          # @return [Hash{SemanticNode => Array<String>}] The reasons attributed to each node,
+          #   keyed by node identity; nodes without a bypass are absent.
+          sig { params(nodes: T::Array[SemanticNode], regions: T::Array[Region]).returns(ReasonsByNode) }
+          def self.attribute(nodes, regions)
+            reasons_by_node = T.let({}.compare_by_identity, ReasonsByNode)
+            regions.each do |range, reason|
+              targets_of(nodes, range).each do |node|
+                node_reasons = (reasons_by_node[node] ||= [])
+                node_reasons << reason unless node_reasons.include?(reason)
+              end
+            end
+            reasons_by_node
+          end
+
+          sig { params(nodes: T::Array[SemanticNode], range: T::Range[Integer]).returns(T::Array[SemanticNode]) }
+          def self.targets_of(nodes, range)
+            contained = nodes.select { |node| LineSpan.encloses?(range, node.line_range) }
+            return outermost(contained) if contained.any?
+
+            [innermost_enclosing(nodes, range)].compact
+          end
+
+          sig { params(contained: T::Array[SemanticNode]).returns(T::Array[SemanticNode]) }
+          def self.outermost(contained)
+            contained.reject do |node|
+              contained.any? { |other| LineSpan.strictly_encloses?(other.line_range, node.line_range) }
+            end
+          end
+
+          # Nodes are in pre-order, so among the (nested) nodes enclosing a region the last one
+          # is the innermost — including when an inner node spans exactly the same lines as its
+          # parent (a method filling its class, or a class filling the root scope).
+          sig { params(nodes: T::Array[SemanticNode], range: T::Range[Integer]).returns(T.nilable(SemanticNode)) }
+          def self.innermost_enclosing(nodes, range)
+            nodes.reverse.find { |node| LineSpan.encloses?(node.line_range, range) }
+          end
+
+          private_class_method :targets_of, :outermost, :innermost_enclosing
+        end
+      end
+    end
+  end
+end

data/lib/simplecov-ai/ast_resolver/dynamic_method_resolver.rb

@@ -0,0 +1,61 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class ASTResolver
+        # Recognizes `define_method(:name) do … end` and `define_singleton_method(:name) { … }`
+        # blocks whose method name is a literal symbol or string. Such a block is the body of the
+        # method it defines, so deficits inside it belong to that method rather than to the whole
+        # enclosing class. Dynamic names (`define_method(name)`), explicit foreign receivers
+        # (`klass.define_method`) and block-less forms (`define_method(:a, method(:b))`) are not
+        # recognized and stay transparent.
+        module DynamicMethodResolver
+          extend T::Sig
+
+          # Method-defining calls mapped to whether they define a singleton method.
+          DEFINERS = T.let({ define_method: false, define_singleton_method: true }.freeze,
+                           T::Hash[Symbol, T::Boolean])
+          # Node types accepted as a literal method name.
+          LITERAL_NAME_TYPES = T.let(%i[sym str].freeze, T::Array[Symbol])
+
+          # @param node [Parser::AST::Node] A node whose type is one of
+          #   {MetaclassResolver::BLOCK_TYPES}.
+          # @return [[String, Boolean], nil] The literal method name and whether the call
+          #   defines a singleton method, or nil when the block is not a recognized definition.
+          sig { params(node: Parser::AST::Node).returns(T.nilable([String, T::Boolean])) }
+          def self.definition(node)
+            call = MetaclassResolver.block_call(node)
+            return nil unless call && implicit_receiver?(call)
+
+            singleton_definer = DEFINERS[NodeChildren.symbol_at(call, 1)]
+            name = literal_name(call)
+            return nil if singleton_definer.nil? || name.nil?
+
+            [name, singleton_definer]
+          end
+
+          # True when the call has no receiver or `self` as its receiver, i.e. it defines the
+          # method on the lexical class being resolved.
+          sig { params(call: Parser::AST::Node).returns(T::Boolean) }
+          def self.implicit_receiver?(call)
+            receiver = NodeChildren.node_at(call, 0)
+            receiver.nil? || receiver.type == :self
+          end
+
+          # The first argument of the call as a method name, when it is a symbol or string literal.
+          sig { params(call: Parser::AST::Node).returns(T.nilable(String)) }
+          def self.literal_name(call)
+            argument = NodeChildren.node_at(call, 2)
+            return nil unless argument && LITERAL_NAME_TYPES.include?(argument.type)
+
+            NodeChildren.literal_value(argument)
+          end
+
+          private_class_method :implicit_receiver?, :literal_name
+        end
+      end
+    end
+  end
+end

data/lib/simplecov-ai/ast_resolver/lenient_literals.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class ASTResolver
+        # Extended onto a `parser` builder so it accepts string literals whose escape sequences
+        # produce bytes that are invalid in the source encoding (e.g. `"\xf0-\xff"`). MRI and
+        # Prism accept such literals, but the `parser` builder rejects them with "literal
+        # contains escape sequences incompatible with UTF-8", which would discard the structure
+        # of an otherwise valid file.
+        module LenientLiterals
+          extend T::Sig
+
+          # @param token [Array] The `[value, location]` pair the lexer emits for a literal.
+          # @return [String] The literal value, skipping the encoding validity check.
+          sig { params(token: T::Array[BasicObject]).returns(BasicObject) }
+          def string_value(token)
+            token.fetch(0)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov-ai/ast_resolver/metaclass_resolver.rb

@@ -0,0 +1,71 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class ASTResolver
+        # Recognizes constant assignments whose value is a `Struct.new` / `Class.new` /
+        # `Module.new` / `Data.define` block. These bind an anonymous class or module to the
+        # constant, so methods defined inside the block belong to that constant rather than to
+        # the enclosing lexical scope.
+        module MetaclassResolver
+          extend T::Sig
+
+          # Recognized builders mapped to the constructor method that signals the pattern.
+          BUILDERS = T.let({ 'Struct' => :new, 'Class' => :new, 'Module' => :new, 'Data' => :define }.freeze,
+                           T::Hash[String, Symbol])
+          # Every AST node type that attaches a block to a call: `do … end` / `{ … }` blocks,
+          # numbered-parameter blocks (`{ _1 }`) and Ruby 3.4 `it` blocks.
+          BLOCK_TYPES = T.let(%i[block numblock itblock].freeze, T::Array[Symbol])
+
+          # @param node [Parser::AST::Node] A `:casgn` constant-assignment node.
+          # @return [String, nil] The builder label ("Struct"/"Class"/"Module"/"Data"), or nil
+          #   if the assignment is not a recognized metaprogramming class definition.
+          sig { params(node: Parser::AST::Node).returns(T.nilable(String)) }
+          def self.builder_kind(node)
+            send_node = builder_send(node)
+            return nil unless send_node
+
+            receiver = NodeChildren.node_at(send_node, 0)
+            return nil unless receiver && receiver.type == :const
+
+            kind = NodeChildren.symbol_at(receiver, 1).to_s
+            kind if BUILDERS[kind] == NodeChildren.symbol_at(send_node, 1)
+          end
+
+          # @param node [Parser::AST::Node] Any AST node.
+          # @return [Boolean] Whether the node attaches a block to a call (see {BLOCK_TYPES}).
+          sig { params(node: Parser::AST::Node).returns(T::Boolean) }
+          def self.block?(node)
+            BLOCK_TYPES.include?(node.type)
+          end
+
+          # The method call a block node is attached to.
+          #
+          # @param node [Parser::AST::Node] A node whose type is one of {BLOCK_TYPES}.
+          # @return [Parser::AST::Node, nil] The `:send` node the block decorates, or nil when
+          #   the block belongs to something else (`super do … end`, `yield { … }`).
+          sig { params(node: Parser::AST::Node).returns(T.nilable(Parser::AST::Node)) }
+          def self.block_call(node)
+            call = NodeChildren.required_node_at(node, 0)
+            call if call.type == :send
+          end
+
+          # The call a block-valued constant assignment wraps, or nil when the assignment has no
+          # block value: a plain value, or the value-less `:casgn` targets that sit inside a
+          # multiple assignment (`MAJOR, MINOR = …`) or an or-assignment (`FOO ||= …`).
+          sig { params(node: Parser::AST::Node).returns(T.nilable(Parser::AST::Node)) }
+          def self.builder_send(node)
+            value = NodeChildren.node_at(node, 2)
+            return nil unless value && block?(value)
+
+            block_call(value)
+          end
+
+          private_class_method :builder_send
+        end
+      end
+    end
+  end
+end

data/lib/simplecov-ai/ast_resolver/node_children.rb

@@ -0,0 +1,56 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class ASTResolver
+        # Typed access to the children of Parser AST nodes. Parser types every child as untyped
+        # while each node type the resolver reads has one known shape (`:def` holds its name
+        # Symbol first, `:casgn` its scope node, name Symbol and value node), so the casts live
+        # here and every call site names the child it reads and nothing else.
+        module NodeChildren
+          extend T::Sig
+
+          # @param node [Parser::AST::Node] The parent node.
+          # @param index [Integer] The position of the child.
+          # @return [Parser::AST::Node, nil] The child node, or nil when the child is absent.
+          sig { params(node: Parser::AST::Node, index: Integer).returns(T.nilable(Parser::AST::Node)) }
+          def self.node_at(node, index)
+            T.cast(node.children[index], T.nilable(Parser::AST::Node))
+          end
+
+          # @param node [Parser::AST::Node] The parent node.
+          # @param index [Integer] The position of a child the grammar guarantees to be present.
+          # @return [Parser::AST::Node] The child node.
+          sig { params(node: Parser::AST::Node, index: Integer).returns(Parser::AST::Node) }
+          def self.required_node_at(node, index)
+            T.cast(node.children[index], Parser::AST::Node)
+          end
+
+          # @param node [Parser::AST::Node] The parent node.
+          # @param index [Integer] The position of a child the grammar guarantees to be a Symbol.
+          # @return [Symbol] The child.
+          sig { params(node: Parser::AST::Node, index: Integer).returns(Symbol) }
+          def self.symbol_at(node, index)
+            T.cast(node.children[index], Symbol)
+          end
+
+          # @param node [Parser::AST::Node] A `:lvar` or `:ivar` node, whose only child is its name.
+          # @return [Symbol] The variable's name.
+          sig { params(node: Parser::AST::Node).returns(Symbol) }
+          def self.variable_name(node)
+            T.cast(node.children[0], Symbol)
+          end
+
+          # @param node [Parser::AST::Node] A `:sym` or `:str` literal node.
+          # @return [String] The literal's value as a String.
+          sig { params(node: Parser::AST::Node).returns(String) }
+          def self.literal_value(node)
+            T.cast(node.children[0], T.any(Symbol, String)).to_s
+          end
+        end
+      end
+    end
+  end
+end