henitai 0.2.0 → 0.3.0

data/lib/henitai/mutant_identity.rb

@@ -10,10 +10,21 @@ module Henitai
   # session UUID or source coordinates, so it survives ordinary line shifts.
   module MutantIdentity
     def self.stable_id(mutant)
-      Digest::SHA256.hexdigest(identity_components(mutant).join("\0"))
+      digest(identity_components(mutant))
+    end
+
+    # Stable id formula used before site offsets were introduced. Emitted as a
+    # temporary report alias so scoped runs can replace pre-migration entries.
+    def self.legacy_stable_id(mutant)
+      digest(legacy_identity_components(mutant))
     end
 
     def self.identity_components(mutant)
+      legacy_identity_components(mutant) + [site_offset(mutant)]
+    end
+    private_class_method :identity_components
+
+    def self.legacy_identity_components(mutant)
       [
         mutant.subject.expression,
         mutant.operator,
@@ -22,7 +33,27 @@ module Henitai
         mutation_signature(mutant)
       ]
     end
-    private_class_method :identity_components
+    private_class_method :legacy_identity_components
+
+    def self.digest(components)
+      Digest::SHA256.hexdigest(components.join("\0"))
+    end
+    private_class_method :digest
+
+    # Position of the mutation site relative to its subject's own start,
+    # not the file's absolute line/column — this still disambiguates two
+    # call sites that produce the same operator/description/signature
+    # within one subject (e.g. two `MethodExpression — replaced with nil`
+    # mutants on different lines of a method), while surviving line drift
+    # elsewhere in the file, which would shift absolute coordinates but
+    # not this offset.
+    def self.site_offset(mutant)
+      subject_start = mutant.subject.source_range&.begin
+      return mutant.location[:start_col].to_s unless subject_start
+
+      "#{mutant.location[:start_line] - subject_start}:#{mutant.location[:start_col]}"
+    end
+    private_class_method :site_offset
 
     def self.mutation_signature(mutant)
       Unparser.unparse(mutant.mutated_node)

data/lib/henitai/mutation_skip_directives.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Henitai
+  # Reads `# henitai:disable` magic comments from subject source files and
+  # decides whether a mutant is excluded from the run.
+  #
+  # Grammar (backward compatible — a bare directive means "all operators"):
+  #
+  #   # henitai:disable                          all operators, current scope
+  #   # henitai:disable -- prose                 same; `--` introduces prose
+  #   # henitai:disable OpA, OpB                 only the named operators
+  #   # henitai:disable OpA: reason              reason lands in the report
+  #   # henitai:disable: reason                  all operators, with reason
+  #   # henitai:disable-start [ops][: reason]    region begin
+  #   # henitai:disable-end                      region end
+  #
+  # Scopes: trailing comment (line), standalone comment directly above a
+  # `def` (method), and disable-start/disable-end pairs (region, no nesting).
+  # Operator names must exactly match the canonical registry names
+  # (`henitai operator list`); unknown names, unmatched or nested region
+  # directives raise Henitai::ConfigurationError with file:line.
+  #
+  # Matching mutants are reported as ignored by {StaticFilter}, not dropped.
+  class MutationSkipDirectives
+    DIRECTIVE = /\A#\s*henitai:disable(?<kind>-start|-end)?(?<rest>[:\s].*)?\z/
+    VALID_OPERATOR_NAMES = Operator::FULL_SET
+
+    # A parsed directive: +operators+ is nil (all) or a Set of canonical
+    # operator names; +reason+ is optional free text shown in reports.
+    Directive = Data.define(:operators, :reason) do
+      def match?(operator)
+        operators.nil? || operators.include?(operator.to_s)
+      end
+    end
+
+    # Per-file directives, classified by scope.
+    Index = Data.define(:trailing, :standalone, :regions, :standalone_comment_lines)
+    EMPTY_INDEX = Index.new(
+      trailing: {}.freeze,
+      standalone: {}.freeze,
+      regions: [].freeze,
+      standalone_comment_lines: Set.new.freeze
+    ).freeze
+
+    def initialize
+      @index_cache = {}
+    end
+
+    def skip?(mutant)
+      !directive_for(mutant).nil?
+    end
+
+    # @return [Directive, nil] the directive excluding this mutant, if any.
+    def directive_for(mutant)
+      line_directive_for(mutant) || region_directive_for(mutant) || method_directive_for(mutant)
+    end
+
+    private
+
+    def line_directive_for(mutant)
+      directive = index_for(mutant.location[:file]).trailing[mutant.location[:start_line]]
+      directive&.match?(mutant.operator) ? directive : nil
+    end
+
+    def region_directive_for(mutant)
+      index = index_for(mutant.location[:file])
+      line = mutant.location[:start_line]
+      _range, directive = index.regions.find do |range, region_directive|
+        range.cover?(line) && region_directive.match?(mutant.operator)
+      end
+      directive
+    end
+
+    def method_directive_for(mutant)
+      range = mutant.subject&.source_range
+      return nil unless range
+
+      index = index_for(mutant.subject.source_file)
+      line = range.begin - 1
+      while index.standalone_comment_lines.include?(line)
+        directive = index.standalone[line]
+        return directive if directive&.match?(mutant.operator)
+
+        line -= 1
+      end
+      nil
+    end
+
+    def index_for(path)
+      mtime = File.mtime(path)
+      cached_mtime, cached_index = @index_cache[path]
+      return cached_index if cached_mtime == mtime
+
+      index = build_index(path)
+      @index_cache[path] = [mtime, index]
+      index
+    rescue Errno::ENOENT, Errno::EACCES
+      EMPTY_INDEX
+    end
+
+    def build_index(path)
+      source = File.read(path)
+      lines = source.lines
+      builder = IndexBuilder.new(path)
+
+      Prism.parse(source).comments.sort_by { |comment| comment.location.start_line }.each do |comment|
+        builder.record(comment, standalone: standalone?(comment, lines))
+      end
+
+      builder.index
+    end
+
+    def standalone?(comment, lines)
+      prefix = lines[comment.location.start_line - 1].to_s[0...comment.location.start_column]
+      prefix.strip.empty?
+    end
+
+    # Accumulates classified directives for one file, tracking open
+    # disable-start regions and raising on malformed directive usage.
+    class IndexBuilder
+      def initialize(path)
+        @path = path
+        @trailing = {}
+        @standalone = {}
+        @regions = []
+        @standalone_comment_lines = Set.new
+        @open_region = nil
+      end
+
+      def record(comment, standalone:)
+        line = comment.location.start_line
+        @standalone_comment_lines << line if standalone
+        match = DIRECTIVE.match(comment.slice)
+        return unless match
+
+        dispatch(match, line, standalone)
+      end
+
+      def index
+        ensure_all_regions_closed!
+
+        Index.new(
+          trailing: @trailing.freeze,
+          standalone: @standalone.freeze,
+          regions: @regions.freeze,
+          standalone_comment_lines: @standalone_comment_lines.freeze
+        )
+      end
+
+      private
+
+      def ensure_all_regions_closed!
+        return unless @open_region
+
+        error("unclosed `henitai:disable-start` (opened at line #{@open_region.fetch(:line)})")
+      end
+
+      def dispatch(match, line, standalone)
+        case match[:kind]
+        when "-start" then open_region(parse_payload(match[:rest], line), line)
+        when "-end" then close_region(line)
+        else
+          bucket = standalone ? @standalone : @trailing
+          bucket[line] = parse_payload(match[:rest], line)
+        end
+      end
+
+      def open_region(directive, line)
+        error("nested `henitai:disable-start` at line #{line}") if @open_region
+
+        @open_region = { line:, directive: }
+      end
+
+      def close_region(line)
+        error("`henitai:disable-end` without a matching start at line #{line}") unless @open_region
+
+        @regions << [(@open_region.fetch(:line)..line), @open_region.fetch(:directive)]
+        @open_region = nil
+      end
+
+      def parse_payload(rest, line)
+        text = rest.to_s.strip
+        return Directive.new(operators: nil, reason: nil) if prose?(text)
+        return Directive.new(operators: nil, reason: presence(text[1..])) if text.start_with?(":")
+
+        operators_part, reason = text.split(":", 2)
+        Directive.new(
+          operators: parse_operator_names(operators_part, line),
+          reason: presence(reason)
+        )
+      end
+
+      # Free-form rationale after a bare directive stays valid (pre-grammar
+      # behavior): empty, `-- prose`, or anything whose first token cannot be
+      # an operator name (operators are CamelCase). Only CamelCase-looking
+      # tokens are validated against the registry and can raise.
+      def prose?(text)
+        text.empty? || text.start_with?("--") ||
+          (!text.start_with?(":") && !text.match?(/\A[A-Z]/))
+      end
+
+      def parse_operator_names(operators_part, line)
+        names = operators_part.split(",", -1).map(&:strip)
+        names.each do |name|
+          next if VALID_OPERATOR_NAMES.include?(name)
+
+          error(
+            "unknown operator #{name.inspect} in `henitai:disable` directive at line #{line} " \
+            "(valid names: `henitai operator list`)"
+          )
+        end
+        names.to_set
+      end
+
+      def presence(text)
+        stripped = text.to_s.strip
+        stripped.empty? ? nil : stripped
+      end
+
+      def error(message)
+        raise Henitai::ConfigurationError, "#{@path}: #{message}"
+      end
+    end
+  end
+end

data/lib/henitai/operator.rb

@@ -14,7 +14,8 @@ module Henitai
   # Additional operators (full set):
   #   ArrayDeclaration, HashLiteral, RangeLiteral, SafeNavigation,
   #   PatternMatch, BlockStatement, MethodExpression, AssignmentExpression,
-  #   UnaryOperator, UpdateOperator, RegexMutator, MethodChainUnwrap
+  #   UnaryOperator, UpdateOperator, RegexMutator, MethodChainUnwrap,
+  #   EqualityIdentityOperator
   #
   # Each operator subclass must implement:
   #   - .node_types  → Array<Symbol>  AST node types this operator handles
@@ -43,6 +44,7 @@ module Henitai
       AssignmentExpression
       UnaryOperator
       UpdateOperator
+      EqualityIdentityOperator
     ]).freeze
 
     # @param set [Symbol] :light or :full

data/lib/henitai/operators/equality_identity_operator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../parser_current"
+
+module Henitai
+  module Operators
+    # Replaces relational operators with identity methods (`eql?`, `equal?`)
+    # and vice versa.
+    #
+    # This is the noisy half of the equality/identity pairing split out of
+    # EqualityOperator: most Ruby objects don't observably distinguish `==`
+    # from `eql?`/`equal?`, so these mutations are frequently unkillable by
+    # ordinary tests. They stay available in the full operator set rather
+    # than the default light set.
+    class EqualityIdentityOperator < Henitai::Operator
+      NODE_TYPES = [:send].freeze
+      RELATIONAL = %i[== != < > <= >= <=>].freeze
+      IDENTITY = %i[eql? equal?].freeze
+      OPERATORS = (RELATIONAL + IDENTITY).freeze
+
+      def self.node_types
+        NODE_TYPES
+      end
+
+      def mutate(node, subject:)
+        method_name = node.children[1]
+        return [] unless OPERATORS.include?(method_name)
+
+        OPERATORS.each_with_object([]) do |replacement, mutants|
+          next if replacement == method_name
+          next if RELATIONAL.include?(method_name) && RELATIONAL.include?(replacement)
+
+          mutants << build_mutant(
+            subject:,
+            original_node: node,
+            mutated_node: mutated_node(node, replacement),
+            description: "replaced #{method_name} with #{replacement}"
+          )
+        end
+      end
+
+      private
+
+      def mutated_node(node, replacement)
+        receiver = node.children[0]
+        arguments = node.children[2..]
+        Parser::AST::Node.new(:send, [receiver, replacement, *arguments])
+      end
+    end
+  end
+end

data/lib/henitai/operators/equality_operator.rb

@@ -4,10 +4,15 @@ require_relative "../parser_current"
 
 module Henitai
   module Operators
-    # Replaces comparison operators with the other comparison operators.
+    # Replaces relational/equality operators with the other relational operators.
+    #
+    # Identity-method comparisons (`eql?`, `equal?`) are handled separately by
+    # EqualityIdentityOperator: that pairing is the hardest to kill in practice
+    # (most objects don't observably distinguish `==` from `eql?`/`equal?`), so
+    # it is kept out of the default light set.
     class EqualityOperator < Henitai::Operator
       NODE_TYPES = [:send].freeze
-      OPERATORS = %i[== != < > <= >= <=> eql? equal?].freeze
+      OPERATORS = %i[== != < > <= >= <=>].freeze
 
       def self.node_types
         NODE_TYPES
@@ -33,7 +38,7 @@ module Henitai
 
       def mutated_node(node, replacement)
         receiver = node.children[0]
-        arguments = node.children[2..] || []
+        arguments = node.children[2..]
         Parser::AST::Node.new(:send, [receiver, replacement, *arguments])
       end
     end

data/lib/henitai/operators.rb

@@ -8,6 +8,7 @@ module Henitai
   module Operators
     autoload :ArithmeticOperator, "henitai/operators/arithmetic_operator"
     autoload :EqualityOperator, "henitai/operators/equality_operator"
+    autoload :EqualityIdentityOperator, "henitai/operators/equality_identity_operator"
     autoload :LogicalOperator, "henitai/operators/logical_operator"
     autoload :BooleanLiteral, "henitai/operators/boolean_literal"
     autoload :ConditionalExpression, "henitai/operators/conditional_expression"

data/lib/henitai/per_test_coverage.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Read-side view of the per-test coverage map (henitai_per_test.json):
+  # which test files reach which source lines. The single implementation of
+  # the line-intersection check, shared by test selection
+  # (PerTestCoverageSelector) and survivor verdict reuse (IncrementalFilter),
+  # so both callers always agree on what "covers" means.
+  class PerTestCoverage
+    def initialize(reports_dir:, coverage_report_reader: CoverageReportReader.new)
+      @reports_dir = reports_dir
+      @coverage_report_reader = coverage_report_reader
+    end
+
+    def available?
+      !map.empty?
+    end
+
+    # The full-map intersection set: every test file whose covered lines
+    # intersect the mutant's current line range.
+    #
+    # @return [Array<String>] sorted test file paths; empty when the map or
+    #   the mutant's location is unavailable — callers must treat that as
+    #   "unknown", never as "not covered".
+    def tests_covering(mutant)
+      return [] unless location_available?(mutant)
+
+      map.keys.select { |test| covers?(test, mutant) }.sort
+    end
+
+    # True when the given test file's recorded coverage intersects the
+    # mutant's current line range.
+    def covers?(test, mutant)
+      return false unless location_available?(mutant)
+
+      coverage_lines_for(test, mutant).intersect?(mutant_lines(mutant))
+    end
+
+    private
+
+    attr_reader :reports_dir, :coverage_report_reader
+
+    def location_available?(mutant)
+      mutant.respond_to?(:location) &&
+        mutant.location.is_a?(Hash) &&
+        mutant.location[:file] &&
+        mutant.location[:start_line] &&
+        mutant.location[:end_line]
+    end
+
+    def coverage_lines_for(test, mutant)
+      source_map = map[test.to_s] || {}
+      Array(source_map[File.expand_path(mutant.location[:file])]).uniq
+    end
+
+    def mutant_lines(mutant)
+      (mutant.location[:start_line]..mutant.location[:end_line]).to_a
+    end
+
+    def map
+      @map ||= coverage_report_reader.test_lines_by_file(
+        File.join(reports_dir, PerTestCoverageCollector::REPORT_FILE_NAME)
+      )
+    end
+  end
+end

data/lib/henitai/per_test_coverage_collector.rb

@@ -18,11 +18,12 @@ module Henitai
       @coverage_by_test = Hash.new do |hash, test_file|
         hash[test_file] = Hash.new { |nested, source_file| nested[source_file] = [] }
       end
+      @duration_by_test = Hash.new(0.0)
       @previous_snapshot = {}
       @warned_missing_coverage = false
     end
 
-    def record_test(test_file)
+    def record_test(test_file, duration: nil)
       snapshot = current_snapshot
       return warn_missing_coverage unless snapshot
 
@@ -31,6 +32,7 @@ module Henitai
         @coverage_by_test[test_file][source_file].uniq!
         @coverage_by_test[test_file][source_file].sort!
       end
+      @duration_by_test[test_file] += duration.to_f
       @previous_snapshot = snapshot
     end
 
@@ -53,17 +55,28 @@ module Henitai
 
     def current_snapshot
       Coverage.peek_result
-    rescue StandardError
+    rescue RuntimeError
+      # Raised when coverage measurement is not running; caller warns and skips.
+      # Other errors are genuine bugs and must surface.
       nil
     end
 
     def warn_missing_coverage
       return if @warned_missing_coverage
+      return if coverage_suppressed?
 
       warn "Per-test coverage unavailable; skipping coverage formatter output"
       @warned_missing_coverage = true
     end
 
+    # Mutant children deliberately suppress coverage startup
+    # (CoverageRuntimeSuppressors), so missing coverage is expected there and
+    # warning on every child run is pure noise.
+    def coverage_suppressed?
+      defined?(Henitai::Integration::CoverageRuntimeSuppressors) &&
+        Henitai::Integration::CoverageRuntimeSuppressors.active?
+    end
+
     def new_lines(snapshot)
       snapshot.each_with_object({}) do |(source_file, file_coverage), result|
         next unless source_file?(source_file)
@@ -76,10 +89,13 @@ module Henitai
       end
     end
 
+    # Count-delta attribution: a line belongs to every test whose run
+    # incremented its cumulative count, not just the first toucher. This keeps
+    # the per-test map a complete over-approximation of reachability — the
+    # soundness precondition for survivor verdict reuse (ADR-11).
     def new_line_numbers(file_coverage, previous_counts)
       line_counts_for(file_coverage).each_with_index.filter_map do |count, index|
-        next unless count.to_i.positive?
-        next if previous_counts.fetch(index, 0).to_i.positive?
+        next unless count.to_i > previous_counts.fetch(index, 0).to_i
 
         index + 1
       end
@@ -109,10 +125,11 @@ module Henitai
     end
 
     def serializable_report
-      @coverage_by_test.transform_values do |source_map|
-        source_map.to_h do |source_file, lines|
+      @coverage_by_test.to_h do |test_file, source_map|
+        coverage = source_map.to_h do |source_file, lines|
           [File.expand_path(source_file), lines.uniq.sort]
         end
+        [test_file, { "coverage" => coverage, "duration" => @duration_by_test[test_file] }]
       end
     end
   end

data/lib/henitai/per_test_coverage_selector.rb

@@ -2,6 +2,11 @@
 
 module Henitai
   # Narrows candidate test files using the per-test coverage report.
+  #
+  # The intersection check itself lives in {PerTestCoverage}; this class only
+  # adds the selection policy: when no candidate provably covers the mutant
+  # (or the map / location is unavailable), it falls back to all candidates —
+  # over-selection costs time, never correctness.
   class PerTestCoverageSelector
     def initialize(coverage_report_reader: CoverageReportReader.new)
       @coverage_report_reader = coverage_report_reader
@@ -10,49 +15,22 @@ module Henitai
     def filter(tests, mutant, reports_dir:)
       candidates = Array(tests)
       return candidates if candidates.empty?
-      return candidates unless location_available?(mutant)
-      return candidates unless per_test_coverage_available?(reports_dir)
 
+      coverage = per_test_coverage(reports_dir)
       covered_tests = candidates.select do |test|
-        covers_mutant?(test, mutant, reports_dir)
+        coverage.covers?(test, mutant)
       end
       covered_tests.empty? ? candidates : covered_tests
     end
 
     private
 
-    def location_available?(mutant)
-      mutant.respond_to?(:location) &&
-        mutant.location.is_a?(Hash) &&
-        mutant.location[:file] &&
-        mutant.location[:start_line] &&
-        mutant.location[:end_line]
-    end
-
-    def covers_mutant?(test, mutant, reports_dir)
-      covered_lines = coverage_lines_for(test, mutant, reports_dir)
-      mutant_lines(mutant).any? { |line| covered_lines.include?(line) }
-    end
-
-    def coverage_lines_for(test, mutant, reports_dir)
-      source_map = per_test_coverage(reports_dir)[test.to_s] || {}
-      Array(source_map[File.expand_path(mutant.location[:file])]).uniq
-    end
-
-    def mutant_lines(mutant)
-      (mutant.location[:start_line]..mutant.location[:end_line]).to_a
-    end
-
     def per_test_coverage(reports_dir)
       @per_test_coverage ||= {}
-      @per_test_coverage[reports_dir] ||= begin
-        path = File.join(reports_dir, "henitai_per_test.json")
-        coverage_report_reader.test_lines_by_file(path)
-      end
-    end
-
-    def per_test_coverage_available?(reports_dir)
-      !per_test_coverage(reports_dir).empty?
+      @per_test_coverage[reports_dir] ||= PerTestCoverage.new(
+        reports_dir:,
+        coverage_report_reader:
+      )
     end
 
     attr_reader :coverage_report_reader