henitai 0.5.1 → 0.6.0

data/lib/henitai/source_parser.rb

@@ -12,10 +12,18 @@ module Henitai
   class SourceParser
     DEFAULT_PATH = "(string)"
 
+    # Emits the modern parser-gem AST format (procarg0, kwargs, index, lambda,
+    # forward_arg, ...). The legacy format cannot tell `|x|` from `|x,|` or
+    # keyword arguments from a braced hash, so re-rendering a mutated subtree
+    # through the unparser would silently change its meaning.
+    class Builder < Prism::Translation::Parser::Builder
+      modernize
+    end
+
     @cache = {}
 
-    def self.parse(source, path: DEFAULT_PATH)
-      new.parse(source, path:)
+    def self.parse(source, path: DEFAULT_PATH, line: 1)
+      new.parse(source, path:, line:)
     end
 
     # Returns the parsed AST for +path+, re-using a cached result when the
@@ -31,20 +39,32 @@ module Henitai
       @cache.clear
     end
 
-    def parse(source, path: DEFAULT_PATH)
-      Prism::Translation::ParserCurrent.new.parse(source_buffer(source, path))
+    # Reads +path+ as UTF-8 source, honouring a magic encoding comment the
+    # same way parsing does. Raises EncodingError when the bytes are invalid
+    # in the declared (or default UTF-8) encoding.
+    def self.read_file(path)
+      buffer = Parser::Source::Buffer.new(path)
+      buffer.source = File.read(path, encoding: Encoding::UTF_8)
+      buffer.source
+    end
+
+    # +line+ is the number of the source's first line, as for Kernel#eval.
+    def parse(source, path: DEFAULT_PATH, line: 1)
+      Prism::Translation::ParserCurrent.new(Builder.new).parse(source_buffer(source, path, line))
     end
 
+    # Read as UTF-8, Ruby's own default source encoding, not the process
+    # locale: with LANG=C the default external encoding is US-ASCII and every
+    # non-ASCII source file would fail to parse. A magic encoding comment is
+    # still honoured by the parser buffer, which re-encodes to UTF-8.
     def parse_file(path)
-      # Ruby's file encoding rules apply here. Projects that use explicit source
-      # encoding comments can be handled by a future encoding-aware option.
-      parse(File.read(path), path:)
+      parse(File.read(path, encoding: Encoding::UTF_8), path:)
     end
 
     private
 
-    def source_buffer(source, path)
-      Parser::Source::Buffer.new(path).tap do |buffer|
+    def source_buffer(source, path, line = 1)
+      Parser::Source::Buffer.new(path, line).tap do |buffer|
         buffer.source = source
       end
     end

data/lib/henitai/static_filter.rb

@@ -10,9 +10,11 @@ module Henitai
     DEFAULT_PER_TEST_COVERAGE_REPORT_PATH = CoverageReportReader::DEFAULT_PER_TEST_COVERAGE_REPORT_PATH
 
     def initialize(coverage_report_reader: CoverageReportReader.new,
-                   skip_directives: MutationSkipDirectives.new)
+                   skip_directives: MutationSkipDirectives.new,
+                   fidelity_check: FidelityCheck.new)
       @coverage_report_reader = coverage_report_reader
       @skip_directives = skip_directives
+      @fidelity_check = fidelity_check
     end
 
     # This method is the gate-level filter orchestrator.
@@ -22,6 +24,7 @@ module Henitai
 
       Array(mutants).each do |mutant|
         next if ignored_mutant?(mutant, config) || skip_directive_mutant?(mutant)
+        next if unfaithful_mutant?(mutant)
 
         mark_equivalent_mutant(mutant)
         mark_no_coverage_mutant(
@@ -64,21 +67,22 @@ module Henitai
 
     private
 
-    attr_reader :coverage_report_reader, :skip_directives
+    attr_reader :coverage_report_reader, :skip_directives, :fidelity_check
 
-    def ignored?(mutant, config)
-      source = source_for(mutant)
-      return false unless source
+    def ignore_pattern_for(mutant, config)
+      patterns = compiled_ignore_patterns(config)
+      return if patterns.empty?
 
-      compiled_ignore_patterns(config).any? do |pattern|
-        pattern.match?(source)
-      end
+      line = source_line_for(mutant)
+      patterns.find { |pattern| pattern.match?(line) }
     end
 
     def ignored_mutant?(mutant, config)
-      return false unless ignored?(mutant, config)
+      pattern = ignore_pattern_for(mutant, config)
+      return false unless pattern
 
       mutant.status = :ignored
+      mutant.ignore_reason = "ignore_patterns: #{pattern.source}" if mutant.respond_to?(:ignore_reason=)
       true
     end
 
@@ -91,6 +95,17 @@ module Henitai
       true
     end
 
+    # A mutant whose activated code is not the reported mutation must not
+    # run: any test failure would be credited to a change it never made.
+    def unfaithful_mutant?(mutant)
+      reason = fidelity_check.violation(mutant)
+      return false unless reason
+
+      mutant.status = :compile_error
+      mutant.status_reason = reason
+      true
+    end
+
     def mark_equivalent_mutant(mutant)
       return unless mutant.pending?
 
@@ -111,11 +126,27 @@ module Henitai
       covered.any? { |line| (mutant.location[:start_line]..mutant.location[:end_line]).cover?(line) }
     end
 
-    def source_for(mutant)
-      original_node = mutant.original_node
-      location = original_node&.location
-      expression = location&.expression
-      expression&.source
+    # Ignore patterns are line-scoped: they match the source line on which the
+    # mutant's original node starts, like a trailing `# henitai:disable`.
+    def source_line_for(mutant)
+      line_number = mutant.location[:start_line]
+      return unless line_number.is_a?(Integer) && line_number.positive?
+
+      lines = source_lines_for(mutant.location[:file])
+      lines&.fetch(line_number - 1, nil)
+    end
+
+    def source_lines_for(path)
+      @source_lines ||= {}
+      return @source_lines[path] if @source_lines.key?(path)
+
+      @source_lines[path] = read_source_lines(path)
+    end
+
+    def read_source_lines(path)
+      SourceParser.read_file(path).lines
+    rescue SystemCallError, IOError, EncodingError
+      nil
     end
 
     def compiled_ignore_patterns(config)

data/lib/henitai/stillborn_filter.rb

@@ -1,11 +1,81 @@
 # frozen_string_literal: true
 
+require "prism"
 require "unparser"
 
 module Henitai
   # Suppresses mutants that do not produce syntactically valid Ruby.
+  #
+  # A mutant of a resolved method is checked in context: its activation
+  # source -- the whole method with the mutation spliced in -- must parse. A
+  # fragment such as `size: 2` (one keyword argument left) or a `next` guard
+  # is only valid inside its call or block, so checking it on its own would
+  # drop valid mutants. Without a method to splice into, the rendered
+  # fragment is compiled inside a bare method instead.
+  #
+  # A mutant that removes the only assignment of a local which is read later
+  # is suppressed as well (ACT-10): Ruby then parses the later read as a
+  # method call, so the mutant would fail with a NameError wherever it runs
+  # -- a trivial kill of a program other than the reported one.
   class StillbornFilter
+    # Collects the names of identifiers Ruby parses as method calls.
+    class VariableCalls < Prism::Visitor
+      def self.tally(node)
+        new.tap { |visitor| node.accept(visitor) }.names.tally
+      end
+
+      attr_reader :names
+
+      def initialize
+        super
+        @names = []
+      end
+
+      def visit_call_node(node)
+        @names << node.name if node.variable_call?
+        super
+      end
+    end
+
+    def initialize
+      @original_calls = {}.compare_by_identity
+    end
+
     def suppressed?(mutant)
+      activation = in_context_activation(mutant)
+      return fragment_invalid?(mutant) unless activation
+
+      result = Prism.parse(activation.source)
+      result.errors.any? || drops_local?(mutant.subject.ast_node, result.value)
+    end
+
+    private
+
+    def drops_local?(method_node, activated)
+      original = @original_calls[method_node] ||= original_calls(method_node)
+      VariableCalls.tally(activated).any? do |name, count|
+        count > original.fetch(name, 0) && local_read?(method_node, name)
+      end
+    end
+
+    def original_calls(method_node)
+      VariableCalls.tally(Prism.parse(method_node.location.expression.source).value)
+    end
+
+    def local_read?(node, name)
+      return false unless node.is_a?(Parser::AST::Node)
+      return true if node.type == :lvar && node.children.first == name
+
+      node.children.any? { |child| local_read?(child, name) }
+    end
+
+    def in_context_activation(mutant)
+      return unless mutant.subject.respond_to?(:ast_node) && mutant.subject.ast_node
+
+      Mutant::Activator.activation_for(mutant)
+    end
+
+    def fragment_invalid?(mutant)
       source = render(mutant)
       return true unless source
 
@@ -15,8 +85,6 @@ module Henitai
       true
     end
 
-    private
-
     def render(mutant)
       Unparser.unparse(mutant.mutated_node)
     rescue StandardError

data/lib/henitai/subject.rb

@@ -14,7 +14,7 @@ module Henitai
   # descriptions in the test suite.
   class Subject
     attr_reader :namespace, :method_name, :method_type, :source_file,
-                :source_range, :ast_node
+                :source_range, :ast_node, :lexical_scope
 
     # @param expression [String] subject expression, e.g. "Foo::Bar#method"
     def self.parse(expression)
@@ -25,11 +25,15 @@ module Henitai
     # @param method_name [String]  method name (nil for wildcard subjects)
     # @param method_type [Symbol]  :instance or :class
     # @param source_location [Hash] file/range metadata for the subject source
+    # @param lexical_scope [Array<String>, nil] the openers of the modules and
+    #   classes around the method as written ("module Outer", "class Inner",
+    #   "class << self", "Point.class_eval do"); nil when a scope cannot be
+    #   reopened by name
     # The explicit keyword API matches the public call sites and keeps the
     # metadata fields discoverable without a single options hash.
     # rubocop:disable Metrics/ParameterLists
     def initialize(expression: nil, namespace: nil, method_name: nil,
-                   method_type: :instance, source_location: nil, ast_node: nil)
+                   method_type: :instance, source_location: nil, ast_node: nil, lexical_scope: nil)
       if expression
         parse_expression(expression)
       else
@@ -40,6 +44,7 @@ module Henitai
       @source_file  = source_location&.fetch(:file, nil)
       @source_range = source_location&.fetch(:range, nil)
       @ast_node = ast_node
+      @lexical_scope = lexical_scope
     end
     # rubocop:enable Metrics/ParameterLists
 
@@ -56,7 +61,7 @@ module Henitai
     private
 
     def parse_expression(expr)
-      if (m = expr.match(/\A(.+?)([#.])(\w+)\z/))
+      if (m = expr.match(/\A([\w:]+)([#.])([^#.\s]+)\z/))
         @namespace   = m[1]
         @method_type = m[2] == "." ? :class : :instance
         @method_name = m[3]

data/lib/henitai/subject_resolver.rb

@@ -2,6 +2,7 @@
 
 require_relative "source_parser"
 require_relative "subject"
+require_relative "constant_path"
 
 module Henitai
   # Resolves AST subjects from Ruby source files.
@@ -26,6 +27,7 @@ module Henitai
     private
 
     def resolve_from_file(path)
+      @scope = []
       subjects = []
       walk(
         SourceParser.parse_file(path),
@@ -38,6 +40,7 @@ module Henitai
 
     def walk(node, namespace:, singleton_context:, subjects:)
       return unless node.respond_to?(:type)
+      return walk_constructor_body(node, namespace, subjects) if constructor_assignment?(node)
       return if anonymous_class_block?(node)
 
       namespace, singleton_context = update_context(
@@ -46,8 +49,60 @@ module Henitai
         singleton_context
       )
 
-      collect_subject(node, namespace, singleton_context, subjects)
-      traverse_children(node, namespace, singleton_context, subjects)
+      within_scope(node) do
+        collect_subject(node, namespace, singleton_context, subjects)
+        traverse_children(node, namespace, singleton_context, subjects)
+      end
+    end
+
+    # +Point = Struct.new(:x) do ... end+: the block is evaluated with
+    # class_eval on the new class, so its methods belong to +Point+ while
+    # constant lookup stays in the enclosing scope. +Point.class_eval do+
+    # reproduces exactly that when the method is re-evaluated.
+    def walk_constructor_body(node, namespace, subjects)
+      @scope.push("#{assigned_constant_source(node)}.class_eval do")
+      walk(node.children[2].children[2], namespace: ConstantPath.qualify(namespace, ConstantPath.of(node)),
+                                         singleton_context: false, subjects:)
+    ensure
+      @scope.pop
+    end
+
+    def constructor_assignment?(node)
+      node.type == :casgn && anonymous_class_block?(node.children[2])
+    end
+
+    def assigned_constant_source(node)
+      node.location.expression.begin.join(node.location.name).source
+    end
+
+    # Tracks the openers of the modules and classes around the walk position,
+    # so a method can later be re-evaluated in its original lexical scope.
+    def within_scope(node)
+      opener = scope_opener(node)
+      @scope.push(opener) unless opener == :none
+      yield
+    ensure
+      @scope.pop unless opener == :none
+    end
+
+    def scope_opener(node)
+      case node.type
+      when :class, :module then "#{node.type} #{node.children.first.location.expression.source}"
+      when :sclass then singleton_opener(node.children.first)
+      else :none
+      end
+    end
+
+    def singleton_opener(receiver)
+      case receiver.type
+      when :self then "class << self"
+      when :const then "class << #{receiver.location.expression.source}"
+      end
+    end
+
+    # nil when some enclosing scope cannot be reopened by name (class << obj).
+    def lexical_scope
+      @scope.include?(nil) ? nil : @scope.dup
     end
 
     def collect_subject(node, namespace, singleton_context, subjects)
@@ -70,7 +125,7 @@ module Henitai
 
       receiver = call_node.children.first
       method_name = call_node.children[1]
-      receiver_name = constant_name(receiver)
+      receiver_name = ConstantPath.of(receiver)&.delete_prefix("::")
 
       anonymous_constructor_call?(receiver_name, method_name)
     end
@@ -86,10 +141,10 @@ module Henitai
     def update_context(node, namespace, singleton_context)
       case node.type
       when :class, :module
-        [qualify_namespace(namespace, constant_name(node.children.first)),
+        [ConstantPath.qualify(namespace, ConstantPath.of(node.children.first)),
          singleton_context]
       when :sclass
-        [namespace, true]
+        [ConstantPath.owner(node.children.first, namespace), true]
       else
         [namespace, singleton_context]
       end
@@ -102,7 +157,7 @@ module Henitai
       when :def
         instance_subject(node, namespace, singleton_context)
       when :defs
-        class_subject(node, namespace)
+        class_subject(node, ConstantPath.owner(node.children.first, namespace))
       end
     end
 
@@ -114,7 +169,8 @@ module Henitai
         method_name: method_name(node.children.first),
         method_type: singleton_context ? :class : :instance,
         source_location: source_location_for(node),
-        ast_node: node
+        ast_node: node,
+        lexical_scope:
       )
     end
 
@@ -126,7 +182,8 @@ module Henitai
         method_name: method_name(node.children[1]),
         method_type: :class,
         source_location: source_location_for(node),
-        ast_node: node
+        ast_node: node,
+        lexical_scope:
       )
     end
 
@@ -147,29 +204,6 @@ module Henitai
       )
     end
 
-    def qualify_namespace(namespace, name)
-      return name if namespace.nil? || namespace.empty?
-      return namespace if name.nil? || name.empty?
-
-      "#{namespace}::#{name}"
-    end
-
-    def constant_name(node)
-      return unless node.respond_to?(:type)
-
-      case node.type
-      when :const
-        parent_name = constant_name(node.children.first)
-        current_name = symbol_name(node.children.last)
-
-        return current_name if parent_name.nil? || parent_name.empty?
-
-        "#{parent_name}::#{current_name}"
-      when :cbase
-        ""
-      end
-    end
-
     def method_name(value)
       symbol_name(value)
     end

data/lib/henitai/suite_boot_clock.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Measures how long a baseline suite process spent before its first test
+  # started. The parent passes its spawn wall-clock time through
+  # STARTED_AT_ENV; the boot time covers loading helpers and spec files and
+  # running before(:suite).
+  class SuiteBootClock
+    STARTED_AT_ENV = "HENITAI_SUITE_STARTED_AT"
+
+    # @param started_at [Float, nil] epoch seconds of the suite spawn
+    # @param clock [#call] returns the current epoch seconds
+    def initialize(started_at:, clock: -> { Time.now.to_f })
+      @started_at = started_at
+      @clock = clock
+      @boot_seconds = nil
+    end
+
+    # @param env [Hash] environment of the suite process
+    # @return [SuiteBootClock]
+    def self.from_env(env, clock: -> { Time.now.to_f })
+      new(started_at: parse_timestamp(env[STARTED_AT_ENV]), clock:)
+    end
+
+    def self.parse_timestamp(value)
+      Float(value)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    # Records boot time at the first test start only; later calls are ignored.
+    def mark_first_test_started
+      return if @boot_seconds || @started_at.nil?
+
+      @boot_seconds = [@clock.call - @started_at, 0.0].max
+    end
+
+    # @return [Float] boot seconds, 0.0 when unknown
+    def boot_seconds
+      @boot_seconds || 0.0
+    end
+
+    # @return [Boolean] true once a boot time has been recorded
+    def measured?
+      !@boot_seconds.nil?
+    end
+  end
+end

data/lib/henitai/survivor_activation_cache.rb

@@ -4,7 +4,7 @@ require "json"
 require "fileutils"
 
 module Henitai
-  # Stores and retrieves pre-computed +define_method+ activation sources for
+  # Stores and retrieves pre-computed activations (see Mutant::Activation) for
   # survived mutants, enabling survivor reruns to skip the full mutant-generation
   # pipeline.
   #
@@ -14,7 +14,7 @@ module Henitai
   # objects directly and execute them without re-parsing source files.
   #
   # A recipe entry encodes everything needed to activate and re-report a mutant:
-  # the +define_method+ source, subject coordinates, operator, description,
+  # the activation (source, mode, file, line), subject coordinates, operator, description,
   # location, and the coveredBy test list.
   class SurvivorActivationCache
     FILENAME = "activation-recipes.json"
@@ -26,10 +26,10 @@ module Henitai
     # @return [Hash<String, Hash>] stableId → recipe
     def self.compute(survived_mutants)
       survived_mutants.each_with_object({}) do |mutant, cache|
-        source = Mutant::Activator.activation_source_for(mutant)
-        next unless source
+        activation = Mutant::Activator.activation_for(mutant)
+        next unless activation
 
-        cache[mutant.stable_id] = build_recipe(mutant, source)
+        cache[mutant.stable_id] = build_recipe(mutant, activation)
       end
     end
 
@@ -53,13 +53,11 @@ module Henitai
     class << self
       private
 
-      def build_recipe(mutant, activation_source)
+      def build_recipe(mutant, activation)
         {
-          "activationSource" => activation_source,
-          "namespace" => mutant.subject.namespace,
-          "methodName" => mutant.subject.method_name,
-          "methodType" => mutant.subject.method_type.to_s,
-          "sourceFile" => mutant.subject.source_file,
+          "activation" => activation.to_h,
+          "replacement" => mutant.mutated_source,
+          **subject_fields(mutant.subject),
           "operator" => mutant.operator,
           "description" => mutant.description,
           "location" => serialize_location(mutant.location),
@@ -67,6 +65,15 @@ module Henitai
         }
       end
 
+      def subject_fields(subject)
+        {
+          "namespace" => subject.namespace,
+          "methodName" => subject.method_name,
+          "methodType" => subject.method_type.to_s,
+          "sourceFile" => subject.source_file
+        }
+      end
+
       def serialize_location(location)
         {
           "file" => location[:file],