henitai 0.1.0

data/lib/henitai/mutant_history_store.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require "date"
+require "digest"
+require "fileutils"
+require "json"
+require "sqlite3"
+require "time"
+require "unparser"
+
+module Henitai
+  # Persists mutant outcomes across runs in a lightweight SQLite database.
+  # rubocop:disable Metrics/ClassLength
+  class MutantHistoryStore
+    RUNS_TABLE_SQL = <<~SQL
+      CREATE TABLE IF NOT EXISTS runs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        version TEXT NOT NULL,
+        recorded_at TEXT NOT NULL,
+        mutation_score REAL,
+        mutation_score_indicator REAL,
+        equivalence_uncertainty TEXT,
+        total_mutants INTEGER NOT NULL,
+        killed_mutants INTEGER NOT NULL,
+        survived_mutants INTEGER NOT NULL,
+        timeout_mutants INTEGER NOT NULL,
+        equivalent_mutants INTEGER NOT NULL
+      );
+    SQL
+
+    MUTANTS_TABLE_SQL = <<~SQL
+      CREATE TABLE IF NOT EXISTS mutants (
+        mutant_id TEXT PRIMARY KEY,
+        first_seen_version TEXT NOT NULL,
+        first_seen_at TEXT NOT NULL,
+        last_seen_version TEXT NOT NULL,
+        last_seen_at TEXT NOT NULL,
+        current_status TEXT NOT NULL,
+        status_history TEXT NOT NULL,
+        days_alive INTEGER NOT NULL
+      );
+    SQL
+
+    INSERT_RUN_SQL = <<~SQL
+      INSERT INTO runs (
+        version,
+        recorded_at,
+        mutation_score,
+        mutation_score_indicator,
+        equivalence_uncertainty,
+        total_mutants,
+        killed_mutants,
+        survived_mutants,
+        timeout_mutants,
+        equivalent_mutants
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    SQL
+
+    UPSERT_MUTANT_SQL = <<~SQL
+      INSERT INTO mutants (
+        mutant_id,
+        first_seen_version,
+        first_seen_at,
+        last_seen_version,
+        last_seen_at,
+        current_status,
+        status_history,
+        days_alive
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(mutant_id) DO UPDATE SET
+        last_seen_version = excluded.last_seen_version,
+        last_seen_at = excluded.last_seen_at,
+        current_status = excluded.current_status,
+        status_history = excluded.status_history,
+        days_alive = excluded.days_alive
+    SQL
+
+    def initialize(path:)
+      @path = path
+    end
+
+    attr_reader :path
+
+    def record(result, version:, recorded_at: Time.now.utc)
+      FileUtils.mkdir_p(File.dirname(path))
+
+      with_database do |db|
+        ensure_schema(db)
+        db.transaction do
+          insert_run(db, result, version, recorded_at)
+          Array(result.mutants).each do |mutant|
+            upsert_mutant(db, mutant, version, recorded_at)
+          end
+        end
+      end
+    end
+
+    def trend_report
+      with_database do |db|
+        ensure_schema(db)
+        {
+          generatedAt: Time.now.utc.iso8601,
+          runs: load_runs(db),
+          mutants: load_mutants(db)
+        }
+      end
+    end
+
+    private
+
+    def with_database
+      db = SQLite3::Database.new(path)
+      db.results_as_hash = true
+      yield db
+    ensure
+      db&.close
+    end
+
+    def ensure_schema(db)
+      db.execute_batch(RUNS_TABLE_SQL)
+      db.execute_batch(MUTANTS_TABLE_SQL)
+    end
+
+    def insert_run(db, result, version, recorded_at)
+      db.execute(INSERT_RUN_SQL, insert_run_bindings(result, version, recorded_at))
+    end
+
+    def upsert_mutant(db, mutant, version, recorded_at)
+      db.execute(
+        UPSERT_MUTANT_SQL,
+        upsert_mutant_bindings(mutant_history_data(db, mutant, version, recorded_at))
+      )
+    end
+
+    def count_mutants(mutants)
+      mutants.each_with_object(Hash.new(0)) do |mutant, counts|
+        counts[:total] += 1
+        counts[mutant.status] += 1
+      end
+    end
+
+    def stable_mutant_id(mutant)
+      Digest::SHA256.hexdigest(
+        [
+          mutant.subject.expression,
+          mutant.operator,
+          mutant.description,
+          mutant.location[:file],
+          mutant.location[:start_line],
+          mutant.location[:end_line],
+          mutant.location[:start_col],
+          mutant.location[:end_col],
+          mutation_signature(mutant)
+        ].join("\0")
+      )
+    end
+
+    def mutation_signature(mutant)
+      Unparser.unparse(mutant.mutated_node)
+    rescue StandardError
+      mutant.mutated_node.class.name
+    end
+
+    def mutation_history_entry(mutant, version, recorded_at)
+      {
+        version: version,
+        status: mutant.status.to_s,
+        recordedAt: recorded_at.iso8601
+      }
+    end
+
+    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)
+      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,
+        days_alive: days_alive_since(first_seen[:at], recorded_at)
+      }
+    end
+
+    def existing_mutant_row(db, mutant_id)
+      db.get_first_row(
+        "SELECT * FROM mutants WHERE mutant_id = ?",
+        mutant_id
+      )
+    end
+
+    def existing_status_history(existing)
+      return [] unless existing
+
+      JSON.parse(existing["status_history"], symbolize_names: true)
+    end
+
+    def first_seen_metadata(existing, version, recorded_at)
+      {
+        version: existing ? existing["first_seen_version"] : version,
+        at: existing ? existing["first_seen_at"] : recorded_at.iso8601
+      }
+    end
+
+    def days_alive_since(first_seen_at, recorded_at)
+      first_seen = Time.iso8601(first_seen_at)
+      [(recorded_at.to_date - first_seen.to_date).to_i, 0].max
+    end
+
+    def load_runs(db)
+      db.execute("SELECT * FROM runs ORDER BY recorded_at").map do |row|
+        {
+          version: row["version"],
+          recordedAt: row["recorded_at"],
+          mutationScore: row["mutation_score"],
+          mutationScoreIndicator: row["mutation_score_indicator"],
+          equivalenceUncertainty: row["equivalence_uncertainty"],
+          totalMutants: row["total_mutants"],
+          killedMutants: row["killed_mutants"],
+          survivedMutants: row["survived_mutants"],
+          timeoutMutants: row["timeout_mutants"],
+          equivalentMutants: row["equivalent_mutants"]
+        }
+      end
+    end
+
+    def load_mutants(db)
+      db.execute("SELECT * FROM mutants ORDER BY first_seen_at, mutant_id").map do |row|
+        {
+          mutantId: row["mutant_id"],
+          firstSeenVersion: row["first_seen_version"],
+          firstSeenAt: row["first_seen_at"],
+          lastSeenVersion: row["last_seen_version"],
+          lastSeenAt: row["last_seen_at"],
+          currentStatus: row["current_status"],
+          daysAlive: row["days_alive"],
+          statusHistory: JSON.parse(row["status_history"], symbolize_names: true)
+        }
+      end
+    end
+
+    def insert_run_bindings(result, version, recorded_at)
+      summary = result.scoring_summary
+      counts = count_mutants(Array(result.mutants))
+      [
+        version,
+        recorded_at.iso8601,
+        summary[:mutation_score],
+        summary[:mutation_score_indicator],
+        summary[:equivalence_uncertainty],
+        counts[:total],
+        counts[:killed],
+        counts[:survived],
+        counts[:timeout],
+        counts[:equivalent]
+      ]
+    end
+
+    def upsert_mutant_bindings(data)
+      [
+        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,
+        JSON.generate(data.fetch(:history)),
+        data.fetch(:days_alive)
+      ]
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength

data/lib/henitai/operator.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Base class for all mutation operators.
+  #
+  # An Operator receives an AST node and produces zero or more Mutant objects.
+  # Operator names follow the Stryker-compatible naming convention so that the
+  # JSON report is compatible with stryker-dashboard filters and HTML reports.
+  #
+  # Built-in operators (light set):
+  #   ArithmeticOperator, EqualityOperator, LogicalOperator, BooleanLiteral,
+  #   ConditionalExpression, StringLiteral, ReturnValue
+  #
+  # Additional operators (full set):
+  #   ArrayDeclaration, HashLiteral, RangeLiteral, SafeNavigation,
+  #   PatternMatch, BlockStatement, MethodExpression, AssignmentExpression
+  #
+  # Each operator subclass must implement:
+  #   - .node_types  → Array<Symbol>  AST node types this operator handles
+  #   - #mutate(node, subject:) → Array<Mutant>
+  class Operator
+    LIGHT_SET = %w[
+      ArithmeticOperator
+      EqualityOperator
+      LogicalOperator
+      BooleanLiteral
+      ConditionalExpression
+      StringLiteral
+      ReturnValue
+    ].freeze
+
+    FULL_SET = (LIGHT_SET + %w[
+      ArrayDeclaration
+      HashLiteral
+      RangeLiteral
+      SafeNavigation
+      PatternMatch
+      BlockStatement
+      MethodExpression
+      AssignmentExpression
+    ]).freeze
+
+    # @param set [Symbol] :light or :full
+    # @return [Array<Operator>] operator instances for the given set
+    def self.for_set(set)
+      names = set.to_sym == :full ? FULL_SET : LIGHT_SET
+      names.map { |name| Henitai::Operators.const_get(name).new }
+    end
+
+    # Subclasses must declare which AST node types they handle.
+    def self.node_types
+      raise NotImplementedError, "#{name}.node_types must be defined"
+    end
+
+    # @param node    [Parser::AST::Node]
+    # @param subject [Subject]
+    # @return [Array<Mutant>]
+    def mutate(node, subject:)
+      raise NotImplementedError, "#{self.class}#mutate must be implemented"
+    end
+
+    # Operator name as used in the Stryker JSON schema.
+    def name
+      self.class.name.split("::").last
+    end
+
+    private
+
+    def build_mutant(subject:, original_node:, mutated_node:, description:)
+      loc = node_location(original_node)
+      Mutant.new(
+        subject:,
+        operator: name,
+        nodes: {
+          original: original_node,
+          mutated: mutated_node
+        },
+        description:,
+        location: loc
+      )
+    end
+
+    def node_location(node)
+      exp = node.location.expression
+      return {} unless exp
+
+      {
+        file: exp.source_buffer.name,
+        start_line: exp.line,
+        end_line: exp.last_line,
+        start_col: exp.column,
+        end_col: exp.last_column
+      }
+    end
+  end
+end

data/lib/henitai/operators/arithmetic_operator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../parser_current"
+
+module Henitai
+  module Operators
+    # Replaces arithmetic operators with their mutation counterparts.
+    class ArithmeticOperator < Henitai::Operator
+      NODE_TYPES = [:send].freeze
+      MUTATION_MATRIX = {
+        :+ => :-,
+        :- => :+,
+        :* => :/,
+        :/ => :*,
+        :** => :*,
+        :% => :*
+      }.freeze
+
+      def self.node_types
+        NODE_TYPES
+      end
+
+      def mutate(node, subject:)
+        replacement = MUTATION_MATRIX[node.children[1]]
+        return [] unless replacement
+
+        [
+          build_mutant(
+            subject:,
+            original_node: node,
+            mutated_node: mutated_node(node, replacement),
+            description: "replaced #{node.children[1]} with #{replacement}"
+          )
+        ]
+      end
+
+      private
+
+      def mutated_node(node, replacement)
+        receiver = node.children[0]
+        arguments = node.children[2..] || []
+        Parser::AST::Node.new(node.type, [receiver, replacement, *arguments])
+      end
+    end
+  end
+end

data/lib/henitai/operators/array_declaration.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../parser_current"
+
+module Henitai
+  module Operators
+    # Removes array elements or replaces empty arrays with a nil element.
+    class ArrayDeclaration < Henitai::Operator
+      NODE_TYPES = [:array].freeze
+
+      def self.node_types
+        NODE_TYPES
+      end
+
+      def mutate(node, subject:)
+        if node.children.empty?
+          [empty_array_mutant(subject:, node:)]
+        else
+          [empty_array_mutant(subject:, node:)] + remove_element_mutants(node, subject:)
+        end
+      end
+
+      private
+
+      def empty_array_mutant(subject:, node:)
+        replacement = node.children.empty? ? [Parser::AST::Node.new(:nil, [])] : []
+        description = node.children.empty? ? "replaced empty array with [nil]" : "replaced array with empty array"
+
+        build_mutant(
+          subject:,
+          original_node: node,
+          mutated_node: Parser::AST::Node.new(:array, replacement),
+          description:
+        )
+      end
+
+      def remove_element_mutants(node, subject:)
+        node.children.each_with_index.map do |_element, index|
+          children = node.children.dup
+          children.delete_at(index)
+
+          build_mutant(
+            subject:,
+            original_node: node,
+            mutated_node: Parser::AST::Node.new(:array, children),
+            description: "removed array element #{index + 1}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/henitai/operators/assignment_expression.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../parser_current"
+
+module Henitai
+  module Operators
+    # Mutates compound assignments and reduces ||= to a plain assignment.
+    class AssignmentExpression < Henitai::Operator
+      NODE_TYPES = %i[op_asgn or_asgn].freeze
+      OPERATOR_MAP = {
+        :+ => :-,
+        :- => :+
+      }.freeze
+
+      def self.node_types
+        NODE_TYPES
+      end
+
+      def mutate(node, subject:)
+        case node.type
+        when :op_asgn
+          mutate_compound_assignment(node, subject:)
+        when :or_asgn
+          # Memoization-style ||= is usually filtered earlier by AridNodeFilter.
+          mutate_coalesce_assignment(node, subject:)
+        else
+          []
+        end
+      end
+
+      private
+
+      def mutate_compound_assignment(node, subject:)
+        left, operator, right = node.children
+        replacement = OPERATOR_MAP[operator]
+        return [] unless replacement
+
+        [
+          build_mutant(
+            subject:,
+            original_node: node,
+            mutated_node: Parser::AST::Node.new(:op_asgn, [left, replacement, right]),
+            description: "replaced #{operator} with #{replacement}"
+          )
+        ]
+      end
+
+      def mutate_coalesce_assignment(node, subject:)
+        left, right = node.children
+        mutated_node = assignment_node(left, right)
+        return [] unless mutated_node
+
+        [
+          build_mutant(
+            subject:,
+            original_node: node,
+            mutated_node:,
+            description: "removed ||="
+          )
+        ]
+      end
+
+      def assignment_node(left, right)
+        case left.type
+        when :lvasgn, :ivasgn, :gvasgn, :cvasgn
+          Parser::AST::Node.new(left.type, [left.children.first, right])
+        when :casgn
+          namespace, name = left.children
+          Parser::AST::Node.new(:casgn, [namespace, name, right])
+        when :send
+          assignment_name = left.children[1] == :[] ? :[]= : :"#{left.children[1]}="
+          receiver, _method_name, *arguments = left.children
+          Parser::AST::Node.new(:send, [receiver, assignment_name, *arguments, right])
+        end
+      end
+    end
+  end
+end

data/lib/henitai/operators/block_statement.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../parser_current"
+
+module Henitai
+  module Operators
+    # Removes the body of normal block statements.
+    class BlockStatement < Henitai::Operator
+      NODE_TYPES = [:block].freeze
+
+      def self.node_types
+        NODE_TYPES
+      end
+
+      def mutate(node, subject:)
+        return [] if node.children.last.nil?
+
+        call, args, _body = node.children
+
+        [
+          build_mutant(
+            subject:,
+            original_node: node,
+            mutated_node: Parser::AST::Node.new(:block, [call, args, nil]),
+            description: "removed block content"
+          )
+        ]
+      end
+    end
+  end
+end

data/lib/henitai/operators/boolean_literal.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "../parser_current"
+
+module Henitai
+  module Operators
+    # Toggles boolean literals and removes unary negation.
+    class BooleanLiteral < Henitai::Operator
+      NODE_TYPES = %i[true false send].freeze
+
+      def self.node_types
+        NODE_TYPES
+      end
+
+      def mutate(node, subject:)
+        # Parser uses :true / :false node types, so the AST symbols are intentional.
+        # rubocop:disable Lint/BooleanSymbol
+        case node.type
+        when :true
+          [mutate_true_literal(node, subject:)]
+        when :false
+          [mutate_false_literal(node, subject:)]
+        when :send
+          mutate_negation(node, subject:)
+        else
+          []
+        end
+        # rubocop:enable Lint/BooleanSymbol
+      end
+
+      private
+
+      # Parser uses :true / :false node types, so the AST symbols are intentional.
+      # rubocop:disable Lint/BooleanSymbol
+      def mutate_true_literal(node, subject:)
+        build_mutant(
+          subject:,
+          original_node: node,
+          mutated_node: Parser::AST::Node.new(:false, []),
+          description: "replaced true with false"
+        )
+      end
+
+      def mutate_false_literal(node, subject:)
+        build_mutant(
+          subject:,
+          original_node: node,
+          mutated_node: Parser::AST::Node.new(:true, []),
+          description: "replaced false with true"
+        )
+      end
+      # rubocop:enable Lint/BooleanSymbol
+
+      def mutate_negation(node, subject:)
+        receiver, method_name, *arguments = node.children
+        return [] unless method_name == :! && arguments.empty?
+        return [] unless receiver
+
+        [
+          build_mutant(
+            subject:,
+            original_node: node,
+            mutated_node: receiver,
+            description: "removed negation"
+          )
+        ]
+      end
+    end
+  end
+end