simplecov 1.1.1 → 1.2.0

data/lib/simplecov/static_coverage_extractor/location_conventions.rb

@@ -4,198 +4,158 @@ require_relative "prism_compat"
 
 module SimpleCov
   module StaticCoverageExtractor
-    # The source ranges Ruby's Coverage assigns to branch conditions and
-    # arms, resolved from Prism nodes. Simulated entries only ever merge
-    # with real entries produced by the running Ruby, and CRuby 3.4
-    # changed several of these conventions, so every resolver here emits
-    # whichever shape this Ruby's Coverage uses. See issues #1226 / #1233.
+    # The source ranges Ruby's Coverage assigns to branch conditions and arms,
+    # resolved from Prism nodes. Simulated entries only ever merge with real
+    # entries produced by the running Ruby, and CRuby 3.4 changed several of
+    # these conventions, so every resolver here emits whichever shape this
+    # Ruby's Coverage uses (#1226, #1233). The "runtime tuple equivalence" spec
+    # exercises the module against real Coverage output on every CI Ruby, and
+    # is the authority on what each resolver should answer.
     #
-    # rubocop:disable Metrics/ModuleLength -- one cohesive home for the
-    # per-construct, per-Ruby-version Coverage location conventions;
-    # splitting it would scatter closely-related resolvers.
     module LocationConventions
       LEGACY_COVERAGE_LOCATIONS = Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.4")
 
       # A zero-width stand-in for Prism locations, for the arms Coverage
-      # anchors to a point rather than a range.
+      # anchors to a point rather than a range. Resolvers answer whichever of a
+      # node, one of its locations, or this is nearest to hand: all three
+      # answer the four position accessors the emitted tuples are built from.
       PointLocation = Data.define(:start_line, :start_column, :end_line, :end_column)
 
-    private
+      private
 
-      # simplecov:disable
-      # Which arm of each conditional below runs is fixed by the running
-      # Ruby's version, so no single process can cover both sides, and
-      # the legacy-only helpers are unreachable on modern Rubies (and
-      # vice versa). The "runtime tuple equivalence" spec exercises this
-      # module against real Coverage output on every CI Ruby.
+      # Which arm of each conditional below runs is fixed by the running Ruby's
+      # version, so no single process can cover both sides.
 
-      # The range Coverage assigns to an if-like node itself. Modern
-      # CRuby uses the node's full source range for every form; 3.2/3.3
-      # end an `elsif` clause's range at its last content instead of the
-      # shared `end` keyword the clause doesn't own.
+      # 3.2/3.3 end an `elsif` clause's range at its last content rather than
+      # at the shared `end` keyword the clause doesn't own.
       def if_like_location(node, type)
-        return node.location unless LEGACY_COVERAGE_LOCATIONS && type == :if && elsif_node?(node)
+        return node unless LEGACY_COVERAGE_LOCATIONS && type.equal?(:if) && elsif_node?(node)
 
-        span(node.location, legacy_content_end(node))
+        span(node, legacy_content_end(node))
       end
 
       def elsif_node?(node)
         keyword = node.if_keyword_loc
-        !keyword.nil? && keyword.slice == "elsif"
+        !keyword.nil? && keyword.slice.eql?("elsif")
       end
 
-      # Where an if/elsif chain's content ends, for the legacy range
-      # convention: the deepest trailing clause's statements, or that
-      # clause's predicate / `else` keyword when its body is empty.
+      # The deepest trailing clause's statements, or that clause's predicate /
+      # `else` keyword when its body is empty.
       def legacy_content_end(node)
         tail = node
-        while tail.is_a?(::Prism::IfNode)
+        while tail.instance_of?(Prism::IfNode)
           sub = PrismCompat.subsequent(tail)
           break unless sub
 
           tail = sub
         end
-        return (tail.statements || tail.predicate).location if tail.is_a?(::Prism::IfNode)
+        return tail.statements || tail.predicate if tail.instance_of?(Prism::IfNode)
 
-        tail.statements ? tail.statements.location : tail.else_keyword_loc
+        tail.statements || tail.else_keyword_loc
       end
 
-      # Location of the then arm. Coverage uses the body statements'
-      # range; with an empty then body the arm collapses to a zero-width
-      # point at the predicate's end — always on a modern `if`, and on
-      # legacy Rubies only when the construct is in void position (a
-      # trailing statement discards its value). In value (tail) position,
-      # legacy Rubies and `unless` fall back to the node's range.
       def if_like_then_location(node, type)
-        return node.statements.location if node.statements
-        return point_at_end(node.predicate.location) if empty_arm_collapses?(node, type)
+        return node.statements if node.statements
+        return point_at_end(node.predicate) if empty_arm_collapses?(node, type)
 
         if_like_location(node, type)
       end
 
-      # Resolve the source range Coverage attributes to a real-or-synthetic
-      # `:else` arm of an if-like construct (`PrismCompat` hides the
-      # per-Prism-version accessor split). When no else/elsif is present,
-      # the synthesized else inherits the condition's range (matches
-      # Coverage's convention).
+      # With no else/elsif present, the synthesized else inherits the
+      # condition's range.
       def if_like_else_location(node, type)
         sub = PrismCompat.subsequent(node)
         return if_like_location(node, type) unless sub
-        # An `elsif` arrives as a nested IfNode. Coverage attributes the
-        # outer else arm to the clause's own range, not its then body
-        # (which is what created phantom unmergeable arms).
-        return if_like_location(sub, :if) if sub.is_a?(::Prism::IfNode)
-        return sub.statements.location if sub.statements
+        # An `elsif` arrives as a nested IfNode, and Coverage attributes the
+        # outer else arm to the clause's own range, not its then body (which is
+        # what created phantom unmergeable arms).
+        return if_like_location(sub, :if) if sub.instance_of?(Prism::IfNode)
+        return sub.statements if sub.statements
 
         empty_else_location(node, sub, type)
       end
 
-      # Location of an empty explicit `else`: a modern `if` uses the
-      # else..end span; a legacy Ruby in void position collapses to a point
-      # at the `else` keyword's end; otherwise (legacy value position, or
-      # `unless`) it uses the condition's range.
       def empty_else_location(node, sub, type)
-        return sub.location if !LEGACY_COVERAGE_LOCATIONS && type == :if
-        return point_at_end(sub.else_keyword_loc) if LEGACY_COVERAGE_LOCATIONS && !value_position?(node)
+        return sub if !LEGACY_COVERAGE_LOCATIONS && type.equal?(:if)
+        # Void position is a legacy distinction: a Ruby that does not need the
+        # value-position pass answers every node as value.
+        return point_at_end(sub.else_keyword_loc) unless value_position?(node)
 
         if_like_location(node, type)
       end
 
-      # Arm location for a when/in clause: its body statements, or — when
-      # the body is empty — the clause's own range on modern Rubies, a
-      # point at the pattern's end for a legacy `in`, and for a legacy
-      # `when` a point at the clause's end in void position or the tail
-      # convention (keyword through the case's remaining content) in value.
       def case_arm_location(case_node, when_node, when_type)
-        return when_node.statements.location if when_node.statements
-        return when_node.location unless LEGACY_COVERAGE_LOCATIONS
-        return point_at_end(when_node.pattern.location) if when_type == :in
-        return point_at_end(when_node.location) unless value_position?(case_node)
+        return when_node.statements if when_node.statements
+        return when_node unless LEGACY_COVERAGE_LOCATIONS
+        return point_at_end(when_node.pattern) if when_type.equal?(:in)
+        return point_at_end(when_node) unless value_position?(case_node)
 
         legacy_when_value_location(case_node, when_node)
       end
 
       def legacy_when_value_location(case_node, when_node)
-        span(when_node.location, legacy_case_tail_end(case_node, when_node))
+        span(when_node, legacy_case_tail_end(case_node, when_node))
       end
 
-      # The last body content in the case after `when_node`, falling
-      # back to the clause's final condition value.
+      # Only a `when` reaches here, and a `when` always carries at least one
+      # condition, so the fallback is always available.
       def legacy_case_tail_end(case_node, when_node)
-        following_case_content(case_node, when_node).last ||
-          (when_node.conditions.last || when_node).location
+        following_case_content(case_node, when_node).last || when_node.conditions.last
       end
 
       def following_case_content(case_node, when_node)
         clauses = case_node.conditions
-        index = clauses.index { |clause| clause.equal?(when_node) } || 0
         # A when-clause's own location ends where its body ends (or at its
-        # condition when empty), so the whole clause extends the range
-        # through trailing EMPTY clauses that have no `statements`.
-        content = clauses.drop(index + 1).map(&:location)
+        # condition when empty), so the whole clause is what extends the range
+        # through trailing empty clauses that have no `statements`.
+        index = clauses.index { |clause| clause.equal?(when_node) }
+        content = clauses.drop(index + 1)
         else_statements = PrismCompat.else_clause(case_node)&.statements
-        content << else_statements.location if else_statements
+        content += [else_statements] if else_statements
         content
       end
 
-      # Resolve the source range Coverage attributes to a synthetic-or-real
-      # `:else` arm of a case construct: the body of an explicit else,
-      # the case's full range when no else is present, and — for an
-      # explicit else with an empty body — the else..end span on modern
-      # Rubies or the case's full range on legacy ones.
       def else_arm_location(node)
         else_clause = PrismCompat.else_clause(node)
-        return node.location unless else_clause
-        return else_clause.statements.location if else_clause.statements
-        return else_clause.location unless LEGACY_COVERAGE_LOCATIONS
-        # Empty explicit `else`: a point at the `else` keyword's end in void
-        # position, the whole case's range in value position.
+        return node unless else_clause
+        return else_clause.statements if else_clause.statements
+        return else_clause unless LEGACY_COVERAGE_LOCATIONS
         return point_at_end(else_clause.else_keyword_loc) unless value_position?(node)
 
-        node.location
+        node
       end
 
-      # An empty loop body falls back to the loop's range on modern
-      # Rubies and collapses to a point at the predicate's end on legacy
-      # ones.
       def loop_body_location(node)
         return legacy_do_while_body_location(node) if LEGACY_COVERAGE_LOCATIONS && begin_modifier_loop?(node)
-        return node.statements.location if node.statements
-        return point_at_end(node.predicate.location) if LEGACY_COVERAGE_LOCATIONS
+        return node.statements if node.statements
+        return point_at_end(node.predicate) if LEGACY_COVERAGE_LOCATIONS
 
-        node.location
+        node
       end
 
-      # `begin ... end while/until cond` (the do-while form) parses as a
-      # while/until whose sole statement is the BeginNode. Modern Coverage
-      # attributes the body to that whole `begin ... end` span (which the
-      # generic `node.statements.location` already yields), but 3.3 uses
-      # the begin's inner statements instead — or a point at the end of
-      # the `begin` keyword when the body is empty.
+      # The accessor arrived in Prism 0.25, and this gem supports older ones,
+      # where nothing answers the question.
       def begin_modifier_loop?(node)
         node.respond_to?(:begin_modifier?) && node.begin_modifier?
       end
 
+      # `begin ... end while cond` parses as a while whose sole statement is
+      # the BeginNode. Modern Coverage attributes the body to that whole
+      # `begin ... end` span, but 3.3 uses the begin's inner statements.
       def legacy_do_while_body_location(node)
-        begin_node = node.statements.body.first
+        begin_node, = node.statements.body
         inner = begin_node.statements
-        inner ? inner.location : point_at_end(begin_node.begin_keyword_loc)
-      end
-
-      # Coverage's safe-navigation branch spans the receiver through the
-      # end of the call's arguments (or just the message when there are
-      # none), but never includes a trailing block: `x&.foo { ... }` and
-      # `x&.foo(1) { ... }` both end exactly where `x&.foo` / `x&.foo(1)`
-      # would without the block. `node.location` includes an attached
-      # block, so build the end position from `closing_loc` (closing
-      # paren) / `arguments` (paren-less args) / `message_loc` instead.
-      # This convention is the same on legacy and modern Rubies. See
-      # issue #1233.
+        inner || point_at_end(begin_node.begin_keyword_loc)
+      end
+
+      # Coverage's safe-navigation branch spans the receiver through the end of
+      # the call's arguments (or just the message when there are none), but
+      # never includes a trailing block: `x&.foo { ... }` ends exactly where
+      # `x&.foo` would. `node.location` would include the block (#1233).
       def safe_navigation_location(node)
-        span(node.location, node.closing_loc || node.arguments&.location || node.message_loc)
+        span(node, node.closing_loc || node.arguments || node.message_loc)
       end
 
-      # The range from `from`'s start through `to`'s end.
       def span(from, to)
         PointLocation.new(
           start_line: from.start_line, start_column: from.start_column,
@@ -210,27 +170,22 @@ module SimpleCov
         )
       end
 
-      # Whether an empty then arm collapses to a point at the predicate's
-      # end. Modern Coverage does this for every `if` (but not `unless`);
-      # legacy Coverage does it only in void position, for both.
+      # Modern Coverage collapses an empty then arm for every `if` but not
+      # `unless`; legacy Coverage does it only in void position, for both.
       def empty_arm_collapses?(node, type)
-        return type == :if unless LEGACY_COVERAGE_LOCATIONS
+        return type.equal?(:if) unless LEGACY_COVERAGE_LOCATIONS
 
         !value_position?(node)
       end
 
-      # Whether `node` sits in value (method-return) position, which on
-      # legacy Rubies keeps an empty arm's range instead of collapsing it
-      # to a point. `@value_positions` is computed once per parse by
-      # ValuePositions (only on legacy; nil elsewhere, which reads as
-      # "value" — the safe, pre-audit default).
+      # `@value_positions` is computed once per parse by ValuePositions, and
+      # only on legacy Rubies. Nil elsewhere, which reads as "value": the safe,
+      # pre-audit default.
       def value_position?(node)
         return true if @value_positions.nil?
 
         @value_positions.key?(node)
       end
-      # simplecov:enable
     end
-    # rubocop:enable Metrics/ModuleLength
   end
 end

data/lib/simplecov/static_coverage_extractor/method_collector.rb

@@ -2,15 +2,11 @@
 
 module SimpleCov
   module StaticCoverageExtractor
-    # Visitor mixin that collects method tuples and tracks the lexical
-    # class / module nesting that names them, in the shape Ruby's
-    # `Coverage` reports methods. Mixed into `Visitor`, it shares that
-    # visitor's `@methods` / `@class_stack` state and keeps the
-    # method-collection concern separate from branch extraction.
+    # Visitor mixin that collects method tuples and tracks the lexical class /
+    # module nesting that names them, in the shape Ruby's `Coverage` reports
+    # methods. Module and Class are both namespaces here, since `Coverage` reports
+    # both as the constant.
     module MethodCollector
-      # Track class/module nesting so method tuples carry the lexical
-      # class name. Module + Class are both treated as namespaces here
-      # since `Coverage` reports both as the constant.
       def visit_class_node(node)
         with_class(constant_name(node.constant_path)) { super }
       end
@@ -19,37 +15,28 @@ module SimpleCov
         with_class(constant_name(node.constant_path)) { super }
       end
 
-      # `def name(...)` and `def self.name(...)` both produce DefNode.
-      # The class context is the surrounding lexical class/module (or
-      # `Object` at the top level, matching `Coverage`'s convention).
-      # Suppression covers 3.2's folded dead arms, where nested branches
-      # stay instrumented but a `def` never registers (see
-      # Visitor#visit_dead_arm).
+      # `def name(...)` and `def self.name(...)` both produce DefNode. The class
+      # context is the surrounding lexical class or module, or `Object` at the top
+      # level, matching `Coverage`'s convention. Suppression covers 3.2's folded
+      # dead arms, where nested branches stay instrumented but a `def` never
+      # registers.
       def visit_def_node(node)
-        # simplecov:disable branch — suppression is reachable on 3.2 only
         return super if @suppress_methods
 
-        # simplecov:enable branch
-        loc = node.location
         class_name = @class_stack.last || "Object"
-        key = [class_name, node.name, loc.start_line, loc.start_column, loc.end_line, loc.end_column]
+        key = [class_name, node.name, node.start_line, node.start_column, node.end_line, node.end_column]
         @methods[key] = 0
         super
       end
 
-    private
+      private
 
-      # Render a constant path (e.g., `Foo::Bar`) as its source-form
-      # string. Defensive nil / to_s fallbacks: ClassNode and ModuleNode
-      # always carry a constant_path in practice.
-      # simplecov:disable
       def constant_name(node)
         return "<anonymous>" if node.nil?
         return node.slice if node.respond_to?(:slice)
 
         node.to_s
       end
-      # simplecov:enable
 
       def with_class(name)
         @class_stack.push(name)

data/lib/simplecov/static_coverage_extractor/prism_compat.rb

@@ -2,51 +2,42 @@
 
 module SimpleCov
   module StaticCoverageExtractor
-    # The Prism 1.3 (Dec 2024) accessor renames for the trailing clause of
-    # conditional nodes, resolved ONCE at load so the per-node hot paths
-    # stay branch-free. Ruby 3.3's stdlib Prism (0.19) predates the
-    # renames; 3.4+ and any installed prism gem post-dates them. Reaching
-    # for the modern name on 0.19 raised NoMethodError inside the
-    # extractor — `call` swallowed it and the whole file silently fell
-    # back to no simulated data (see the 1.0.2 audit).
+    # The Prism 1.3 accessor renames for the trailing clause of conditional
+    # nodes, resolved once at load so the per-node hot paths stay branch-free.
+    # Ruby 3.3's stdlib Prism predates the renames; 3.4+ and any installed prism
+    # gem post-date them, and reaching for the modern name on the old one raised
+    # NoMethodError inside the extractor, which `call` swallowed, silently
+    # falling back to no simulated data.
     #
     # This lives in its own file, required by every consumer, because the
-    # constants are referenced from several extractor files and defining
-    # them after those files were loaded worked only while the references
-    # happened at call time — a load-order trap for the next editor.
+    # constants are referenced from several extractor files and defining them
+    # after those files were loaded worked only while the references happened at
+    # call time: a load-order trap for the next editor.
     module PrismCompat
-    module_function
+      extend self
 
-      # `Prism::IfNode#subsequent` was renamed from `consequent`. The
-      # not-taken arm on whichever Prism version we're on can't be
-      # exercised by our own dogfood (we only run on one Prism at a time).
       # simplecov:disable
       IF_NODE_SUBSEQUENT_METHOD =
-        if ::Prism::IfNode.method_defined?(:subsequent)
+        if Prism::IfNode.method_defined?(:subsequent)
           :subsequent
         else
           :consequent
         end
 
-      # The same rename hit the `else` accessor on `UnlessNode`,
-      # `CaseNode`, and `CaseMatchNode` (all three: `consequent` ->
-      # `else_clause`). All three renamed together, so one constant
-      # (probed off CaseNode) covers them.
       ELSE_CLAUSE_METHOD =
-        if ::Prism::CaseNode.method_defined?(:else_clause)
+        if Prism::CaseNode.method_defined?(:else_clause)
           :else_clause
         else
           :consequent
         end
       # simplecov:enable
 
-      # The `else`/`elsif` clause of an if-like node (an ElseNode, or a
-      # nested IfNode for `elsif`), or the `else` clause of anything else
-      # that has one, under whichever accessor this Prism exposes.
       def subsequent(node)
-        node.is_a?(::Prism::IfNode) ? node.public_send(IF_NODE_SUBSEQUENT_METHOD) : else_clause(node)
+        node.instance_of?(Prism::IfNode) ? node.public_send(IF_NODE_SUBSEQUENT_METHOD) : else_clause(node)
       end
 
+      # The rename hit `UnlessNode`, `CaseNode`, and `CaseMatchNode` together, so
+      # one constant probed off CaseNode covers all three.
       def else_clause(node)
         node.public_send(ELSE_CLAUSE_METHOD)
       end

data/lib/simplecov/static_coverage_extractor/value_position.rb

@@ -5,33 +5,24 @@ require_relative "prism_compat"
 module SimpleCov
   module StaticCoverageExtractor
     # Ruby 3.3 value-position analysis for the extractor's legacy branch
-    # conventions (see LocationConventions and the #1233 audit).
+    # conventions (#1233). On 3.3 the source range Coverage assigns to an empty
+    # branch arm depends on whether its construct is in value position, where its
+    # result is the method's return value, or void position, where the result is
+    # discarded. Value position keeps the whole-construct range; void collapses
+    # the arm to a point at its header's end. Ruby 3.4 dropped the distinction.
     #
-    # On Ruby 3.3, the source range Coverage assigns to an EMPTY branch arm
-    # depends on whether its construct is in value position — its result is
-    # the method's return value — or void position, where the result is
-    # discarded. Value position keeps the whole-construct range; void
-    # collapses the arm to a point at its header's end. Ruby 3.4 dropped the
-    # distinction, so this pass only runs on legacy Rubies.
-    #
-    # "Value position" here is narrower than general value-use: it is
-    # strictly method-return (tail) position. It reaches a node only through
-    # statement tails and `if`/`unless`/`when` arms. Assignments, blocks,
-    # lambdas, method arguments, `case/in` arms, and loop bodies all discard
-    # it (Coverage treats their empty arms as void). So `tail_children`
-    # names the constructs that forward tail position and everything else
-    # falls through to the void default.
+    # "Value position" here is strictly method-return (tail) position. It reaches
+    # a node only through statement tails and `if`/`unless`/`when` arms.
+    # Assignments, blocks, lambdas, method arguments, `case/in` arms, and loop
+    # bodies all discard it, so `tail_children` names the constructs that forward
+    # tail position and everything else falls through to the void default.
     module ValuePositions
-    module_function
-
-      # simplecov:disable
-      # This whole pass runs only on legacy Rubies (the modern dogfood
-      # never calls it), so its lines can't be covered on the CI Ruby that
-      # enforces 100%. Behavior is pinned instead by the differential
-      # tuple-equivalence spec, which runs against real Coverage on 3.3.
+      extend self
 
-      # An identity set (a `compare_by_identity` Hash used as a set) of the
-      # Prism nodes Coverage treats as being in value position.
+      # An identity set of the Prism nodes Coverage treats as being in value
+      # position. This pass runs natively only on legacy Rubies; elsewhere the
+      # specs drive it directly, pinned by the differential tuple-equivalence spec
+      # against real Coverage on 3.3.
       def call(root)
         positions = {} #: Hash[untyped, bool]
         positions.compare_by_identity
@@ -40,7 +31,7 @@ module SimpleCov
       end
 
       def mark(node, in_value, positions)
-        return unless node.is_a?(::Prism::Node)
+        return unless node.is_a?(Prism::Node)
 
         positions[node] = true if in_value
         children = tail_children(node, in_value)
@@ -49,26 +40,22 @@ module SimpleCov
         end
       end
 
-      # The children of `node` that inherit its tail position; empty for the
-      # void default. A method body is a tail context even when the `def`
-      # itself is not (the method still returns its last expression), so it
-      # is included regardless of `in_value`.
+      # A method body is a tail context even when the `def` itself is not, since
+      # the method still returns its last expression, so it is included regardless
+      # of `in_value`. `case/in` is intentionally absent: its `in` arms and `else`
+      # both discard tail position.
       def tail_children(node, in_value)
-        # A method body is a tail context even when the `def` is not.
-        return [node.body] if node.is_a?(::Prism::DefNode)
+        return [node.body] if node.instance_of?(Prism::DefNode)
         return [] unless in_value
 
-        # `case/in` (CaseMatchNode) is intentionally not a tail construct:
-        # its `in` arms and `else` both discard tail position.
         case node
-        when ::Prism::StatementsNode then [node.body.last]
-        when ::Prism::IfNode, ::Prism::UnlessNode then [node.statements, PrismCompat.subsequent(node)]
-        when ::Prism::CaseNode then [*node.conditions, PrismCompat.else_clause(node)]
-        when ::Prism::ElseNode, ::Prism::WhenNode, ::Prism::BeginNode, ::Prism::ProgramNode then [node.statements]
+        when Prism::StatementsNode then [node.body.last]
+        when Prism::IfNode, Prism::UnlessNode then [node.statements, PrismCompat.subsequent(node)]
+        when Prism::CaseNode then [*node.conditions, PrismCompat.else_clause(node)]
+        when Prism::ElseNode, Prism::WhenNode, Prism::BeginNode, Prism::ProgramNode then [node.statements]
         else []
         end
       end
-      # simplecov:enable
     end
   end
 end