henitai 0.2.1 → 0.3.0

data/lib/henitai/mutant_history_store.rb

@@ -7,12 +7,19 @@ require "sqlite3"
 require "time"
 require_relative "mutant_identity"
 require_relative "mutant_history_store/sql"
+require_relative "mutant_history_store/verdict_cache"
 
 module Henitai
   # Persists mutant outcomes across runs in a lightweight SQLite database.
   class MutantHistoryStore
-    def initialize(path:)
+    include VerdictCache
+
+    # @param per_test_coverage [PerTestCoverage, nil] live per-test coverage
+    #   view used to record the full-map intersection set for survived
+    #   verdicts; without it survived rows stay NULL (never reusable).
+    def initialize(path:, per_test_coverage: nil)
       @path = path
+      @per_test_coverage = per_test_coverage
     end
 
     attr_reader :path
@@ -31,6 +38,27 @@ module Henitai
       end
     end
 
+    # Verdict-cache lookup for `--incremental`: returns the stored hashes for
+    # the mutant's LATEST verdict when it is Killed or Survived — the upsert
+    # keeps exactly one row per stable id, so current_status is always the
+    # most recent outcome. nil for every other status, unknown ids and legacy
+    # rows without hashes (recorded before the cache columns existed).
+    def verdict_for(stable_id)
+      return nil unless File.exist?(path)
+
+      with_database do |db|
+        ensure_schema(db)
+        verdict_from_row(db.get_first_row(Sql::VERDICT_LOOKUP, stable_id))
+      end
+    end
+
+    # Killed-only view of {#verdict_for}, kept for the original killed reuse
+    # path.
+    def killed_verdict_for(stable_id)
+      verdict = verdict_for(stable_id)
+      verdict if verdict && verdict[:status] == :killed
+    end
+
     def trend_report
       with_database do |db|
         ensure_schema(db)
@@ -44,6 +72,19 @@ module Henitai
 
     private
 
+    attr_reader :per_test_coverage
+
+    def verdict_from_row(row)
+      return nil unless row && VerdictCache::CACHEABLE_STATUSES.include?(row["current_status"])
+      return nil if row["subject_source_hash"].nil? || row["covered_tests_fingerprint"].nil?
+
+      {
+        status: row["current_status"].to_sym,
+        subject_source_hash: row["subject_source_hash"],
+        covered_tests_fingerprint: row["covered_tests_fingerprint"]
+      }
+    end
+
     def partial_rerun?(result)
       result.respond_to?(:partial_rerun?) && result.partial_rerun?
     end
@@ -59,6 +100,19 @@ module Henitai
     def ensure_schema(db)
       db.execute_batch(Sql::RUNS_TABLE)
       db.execute_batch(Sql::MUTANTS_TABLE)
+      migrate_mutants_table(db)
+    end
+
+    # Additive, idempotent in-place migration: databases created before the
+    # verdict-cache columns existed gain them on first contact, with existing
+    # rows left intact (NULL hashes — valid but never reusable).
+    def migrate_mutants_table(db)
+      existing = db.execute("PRAGMA table_info(mutants)").map { |row| row["name"] }
+      Sql::MIGRATION_COLUMNS.each do |column, type|
+        next if existing.include?(column)
+
+        db.execute("ALTER TABLE mutants ADD COLUMN #{column} #{type}")
+      end
     end
 
     def insert_run(db, result, version, recorded_at)
@@ -94,18 +148,12 @@ module Henitai
     def mutant_history_data(db, mutant, version, recorded_at)
       mutant_id = stable_mutant_id(mutant)
       existing = existing_mutant_row(db, mutant_id)
-      history = existing_status_history(existing)
-      history << mutation_history_entry(mutant, version, recorded_at)
+      history = existing_status_history(existing) << mutation_history_entry(mutant, version, recorded_at)
       first_seen = first_seen_metadata(existing, version, recorded_at)
 
       {
-        mutant_id: mutant_id,
-        first_seen_version: first_seen[:version],
-        first_seen_at: first_seen[:at],
-        version: version,
-        recorded_at: recorded_at,
-        mutant: mutant,
-        history: history,
+        mutant_id:, version:, recorded_at:, mutant:, history:, existing_row: existing,
+        first_seen_version: first_seen[:version], first_seen_at: first_seen[:at],
         days_alive: days_alive_since(first_seen[:at], recorded_at)
       }
     end
@@ -185,15 +233,17 @@ module Henitai
     end
 
     def upsert_mutant_bindings(data)
+      mutant = data.fetch(:mutant)
       [
         data.fetch(:mutant_id),
         data.fetch(:first_seen_version),
         data.fetch(:first_seen_at),
         data.fetch(:version),
         data.fetch(:recorded_at).iso8601,
-        data.fetch(:mutant).status.to_s,
+        mutant.status.to_s,
         JSON.generate(data.fetch(:history)),
-        data.fetch(:days_alive)
+        data.fetch(:days_alive),
+        *verdict_cache_bindings(mutant, data[:existing_row])
       ]
     end
   end

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
 
@@ -61,11 +63,20 @@ module Henitai
 
     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)
@@ -78,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
@@ -111,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