henitai 0.2.0 → 0.3.0

data/lib/henitai/checkpoint_reporter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Progress observer that flushes the canonical report to disk periodically
+  # during a run, so a crash on a long run keeps partial results and the report
+  # grows visibly mid-run instead of appearing only at the end (Gate 5).
+  #
+  # Each flush serialises only the mutants completed since the previous flush
+  # and folds them into the on-disk JSON report. When HTML reporting is active,
+  # the self-contained HTML report is regenerated from that merged JSON schema.
+  # Reuses {Result#to_stryker_schema} and {CanonicalReportWriter}.
+  #
+  # On a full (authoritative) run the first flush replaces the report — wiping
+  # entries left by earlier runs, including deleted files — and later flushes
+  # merge their batch in. On a scoped/partial run every flush merges, matching
+  # the end-of-run reporter's behaviour.
+  class CheckpointReporter
+    MONOTONIC = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
+    def initialize(config:, source_provider:, authoritative:, started_at: Time.now, clock: MONOTONIC)
+      @config = config
+      @source_provider = source_provider
+      @authoritative = authoritative
+      @started_at = started_at
+      @clock = clock
+      @batch = []
+      @last_flush_at = clock.call
+      @flushed = false
+    end
+
+    def progress(mutant, **)
+      @batch << mutant
+      flush! if due?
+    end
+
+    private
+
+    def due?
+      @batch.size >= @config.checkpoint_every ||
+        (@clock.call - @last_flush_at) >= @config.checkpoint_interval
+    end
+
+    def flush!
+      first_full_flush = @authoritative && !@flushed
+      merged_schema = CanonicalReportWriter.write(
+        build_schema(@batch),
+        path: canonical_path,
+        authoritative: first_full_flush
+      )
+      write_html(merged_schema) if html_reporter?
+      @flushed = true
+      @batch = []
+      @last_flush_at = @clock.call
+    end
+
+    def build_schema(mutants)
+      Result.new(
+        mutants: mutants,
+        started_at: @started_at,
+        finished_at: Time.now,
+        thresholds: @config.thresholds,
+        source_provider: @source_provider,
+        authoritative: @authoritative
+      ).to_stryker_schema
+    end
+
+    def canonical_path
+      File.join(@config.reports_dir, "mutation-report.json")
+    end
+
+    def html_reporter?
+      Array(@config.reporters).map(&:to_s).include?("html")
+    end
+
+    def write_html(schema)
+      Reporter::Html.new(config: @config).report_schema(schema)
+    end
+  end
+end

data/lib/henitai/cli/clean_command.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Henitai
+  class CLI
+    # Implements `henitai clean`: removes generated report artifacts listed in
+    # {CLI::REPORT_CLEANUP_PATHS} and prints a deletion summary. Mixed into
+    # {CLI}.
+    module CleanCommand
+      private
+
+      def clean_command
+        @command_halted = false
+        options = parse_clean_options
+        return if @command_halted
+
+        config = load_config(options)
+        removed_paths = ReportsDirectoryLock.new(reports_dir: config.reports_dir).synchronize do
+          cleanup_report_artifacts(config)
+        end
+        puts clean_summary(removed_paths)
+      rescue StandardError => e
+        handle_run_error(e)
+      end
+
+      def cleanup_report_artifacts(config)
+        removed_dirs = cleanup_dir_paths(config).select { |path| File.directory?(path) }
+        removed_dirs.each { |path| FileUtils.rm_rf(path) }
+        removed_files = cleanup_file_paths(config).select { |path| File.file?(path) }
+        removed_files.each { |path| FileUtils.rm_f(path) }
+        removed_dirs + removed_files
+      end
+
+      def cleanup_file_paths(config)
+        REPORT_CLEANUP_PATHS.map { |relative_path| File.join(config.reports_dir, *relative_path) }
+      end
+
+      def cleanup_dir_paths(config)
+        REPORT_CLEANUP_DIRS.map { |relative_path| File.join(config.reports_dir, *relative_path) }
+      end
+
+      def clean_summary(removed_paths)
+        return "No generated report artifacts to clean" if removed_paths.empty?
+
+        format(
+          "Removed %<count>s generated report artifact%<plural>s",
+          count: removed_paths.length,
+          plural: removed_paths.length == 1 ? "" : "s"
+        )
+      end
+    end
+  end
+end

data/lib/henitai/cli/command_support.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Henitai
+  class CLI
+    # Shared helpers for CLI command handlers: configuration loading (applying
+    # CLI overrides on top of the config file) and uniform error handling.
+    module CommandSupport
+      private
+
+      def load_config(options)
+        Configuration.load(
+          path: options.fetch(:config, Configuration::CONFIG_FILE),
+          overrides: configuration_overrides(options)
+        )
+      end
+
+      def configuration_overrides(options)
+        deep_compact(
+          {
+            integration: options[:integration],
+            all_logs: options[:all_logs],
+            mutation: {
+              operators: options[:operators],
+              timeout: options[:timeout],
+              timeout_multiplier: options[:timeout_multiplier]
+            },
+            jobs: options[:jobs]
+          }
+        )
+      end
+
+      def deep_compact(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested_value), result|
+            compacted = deep_compact(nested_value)
+            result[key] = compacted unless compacted.nil?
+          end
+        when Array
+          value.map { |item| deep_compact(item) }.compact
+        else
+          value
+        end
+      end
+
+      def handle_run_error(error)
+        warn "#{error.class}: #{error.message}"
+        exit 2
+      end
+    end
+  end
+end

data/lib/henitai/cli/init_command.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Henitai
+  class CLI
+    # Implements `henitai init`: writes a starter `.henitai.yml`, optionally
+    # prompting for the default RSpec integration when stdin is a TTY. Mixed
+    # into {CLI}.
+    module InitCommand
+      INIT_TEMPLATE_LINES = [
+        "# yaml-language-server: $schema=./assets/schema/henitai.schema.json",
+        "includes:",
+        "  - lib",
+        "mutation:",
+        "  operators: light",
+        "  timeout: 10.0",
+        "  max_flaky_retries: 3",
+        "  sampling:",
+        "    ratio: 0.05",
+        "    strategy: stratified",
+        "reports_dir: reports",
+        "thresholds:",
+        "  high: 80",
+        "  low: 60"
+      ].freeze
+
+      private
+
+      def init_command
+        path = @argv.shift || Configuration::CONFIG_FILE
+        unexpected_arguments = @argv.dup
+        warn "Unexpected arguments: #{unexpected_arguments.join(' ')}" unless unexpected_arguments.empty?
+        exit 1 unless unexpected_arguments.empty?
+
+        File.write(path, init_template)
+        puts "Created #{path}"
+      end
+
+      def init_template
+        template = init_template_lines
+        template << integration_block if include_default_integration?
+        "#{template.join("\n")}\n"
+      end
+
+      def init_template_lines
+        INIT_TEMPLATE_LINES.dup
+      end
+
+      def include_default_integration?
+        return true unless $stdin.tty?
+
+        print "Use the default RSpec integration? [Y/n] "
+        response = $stdin.gets&.strip&.downcase
+        response.nil? || response.empty? || !%w[n no].include?(response)
+      end
+
+      def integration_block
+        <<~YAML.chomp
+          integration:
+            name: rspec
+        YAML
+      end
+    end
+  end
+end

data/lib/henitai/cli/operator_command.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Henitai
+  class CLI
+    # Implements `henitai operator`: lists the built-in operators with their
+    # human-readable descriptions and examples. Mixed into {CLI}.
+    module OperatorCommand
+      OPERATOR_METADATA = {
+        "ArithmeticOperator" => ["Arithmetic operators", "a + b -> a - b"],
+        "EqualityOperator" => ["Comparison operators", "a == b -> a != b"],
+        "LogicalOperator" => ["Boolean operators", "a && b -> a || b"],
+        "BooleanLiteral" => ["Boolean literals", "true -> false"],
+        "ConditionalExpression" => ["Conditional branches", "if cond then ... end"],
+        "StringLiteral" => ["String literals", '"foo" -> ""'],
+        "ReturnValue" => ["Return expressions", "return x -> return nil"],
+        "ArrayDeclaration" => ["Array literals", "[1, 2] -> []"],
+        "HashLiteral" => ["Hash literals", "{ a: 1 } -> {}"],
+        "RangeLiteral" => ["Range literals", "1..5 -> 1...5"],
+        "SafeNavigation" => ["Safe navigation", "user&.name -> user.name"],
+        "PatternMatch" => ["Pattern matching", "in { x: Integer } -> in { x: String }"],
+        "BlockStatement" => ["Block statements", "{ do_work } -> {}"],
+        "MethodExpression" => ["Method calls", "call_service -> nil"],
+        "AssignmentExpression" => ["Assignment expressions", "x += 1 -> x -= 1"],
+        "MethodChainUnwrap" => ["Method chain unwrap", "a.b.c -> a.b"],
+        "RegexMutator" => ["Regex literals", "/foo+/ -> /foo*/"],
+        "UnaryOperator" => ["Unary operators", "-x -> x"],
+        "UpdateOperator" => ["Compound assignment", "x += 1 -> x -= 1"],
+        "EqualityIdentityOperator" => ["Identity-method comparisons", "a == b -> a.eql?(b)"]
+      }.freeze
+
+      private
+
+      def operator_command
+        subcommand = @argv.shift
+        case subcommand
+        when "list" then puts operator_list_text
+        when nil, "-h", "--help" then puts operator_help_text
+        else
+          warn "Unknown operator command: #{subcommand}"
+          warn operator_help_text
+          exit 1
+        end
+      rescue ArgumentError => e
+        warn e.message
+        exit 1
+      end
+
+      def operator_help_text
+        <<~HELP
+          Hen'i-tai operator commands
+
+          Usage:
+            henitai operator list
+
+          Run `henitai operator list` to see all built-in operators.
+        HELP
+      end
+
+      def operator_list_text
+        validate_operator_metadata!
+        sections = [
+          operator_list_section("Light set", Operator::LIGHT_SET),
+          operator_list_section("Full set", Operator::FULL_SET)
+        ]
+
+        ["Available operators", *sections].join("\n")
+      end
+
+      def operator_list_section(title, names)
+        rows = names.map { |name| operator_description_row(name) }
+        ([title] + rows).join("\n")
+      end
+
+      def operator_description_row(name)
+        description, example = operator_metadata[name] || fallback_operator_metadata
+
+        format("- %<name>s: %<description>s (%<example>s)", name:, description:, example:)
+      end
+
+      def operator_metadata
+        OPERATOR_METADATA
+      end
+
+      def fallback_operator_metadata
+        ["No metadata available", "n/a"]
+      end
+
+      def validate_operator_metadata!
+        missing = Operator::FULL_SET - operator_metadata.keys
+        return if missing.empty?
+
+        raise ArgumentError, "Missing operator metadata for: #{missing.join(', ')}"
+      end
+    end
+  end
+end

data/lib/henitai/cli/options.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "run_options"
+
+module Henitai
+  class CLI
+    # Builds the OptionParser instances for the `run` and `clean` commands and
+    # parses argv into an options Hash. Help/version options set
+    # +@command_halted+ so the caller can skip the rest of the command.
+    # Run-only option definitions live in {RunOptions}.
+    module Options
+      include RunOptions
+
+      private
+
+      def parse_run_options
+        options = {}
+        build_run_option_parser(options).parse!(@argv)
+        options
+      end
+
+      def parse_clean_options
+        options = {}
+        build_clean_option_parser(options).parse!(@argv)
+        options
+      end
+
+      def build_run_option_parser(options)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: henitai run [options] [SUBJECT_PATTERN...]"
+          add_run_flag_options(opts, options)
+          add_help_option(opts)
+          add_version_option(opts)
+        end
+      end
+
+      def add_run_flag_options(opts, options)
+        add_since_option(opts, options)
+        add_integration_option(opts, options)
+        add_config_option(opts, options)
+        add_operator_option(opts, options)
+        add_timeout_multiplier_option(opts, options)
+        add_jobs_option(opts, options)
+        add_output_option(opts, options)
+        add_survivors_from_option(opts, options)
+        add_incremental_option(opts, options)
+        add_force_option(opts, options)
+        add_dry_run_option(opts, options)
+        add_fail_on_survivors_option(opts, options)
+        add_strict_exit_codes_option(opts, options)
+      end
+
+      def build_clean_option_parser(options)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: henitai clean [options]"
+          add_config_option(opts, options)
+          add_help_option(opts)
+          add_version_option(opts)
+        end
+      end
+
+      def add_config_option(opts, options)
+        opts.on("--config PATH", "Path to .henitai.yml") do |path|
+          options[:config] = path
+        end
+      end
+
+      def add_help_option(opts)
+        opts.on("-h", "--help", "Show this help") do
+          puts opts
+          @command_halted = true
+        end
+      end
+
+      def add_version_option(opts)
+        opts.on("-v", "--version", "Show version") do
+          puts Henitai::VERSION
+          @command_halted = true
+        end
+      end
+    end
+  end
+end

data/lib/henitai/cli/run_command.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Henitai
+  class CLI
+    # Implements `henitai run`: option parsing, pipeline execution, survivors
+    # resolution, and exit-status derivation. Mixed into {CLI} so it shares the
+    # instance (and observable +exit+/+warn+ calls).
+    module RunCommand
+      private
+
+      def run_command
+        @command_halted = false
+        options = parse_run_options
+        return if @command_halted
+
+        config = load_config(options)
+        result = run_pipeline(options, config)
+        exit(run_exit_status(result, config, options))
+      rescue StandardError => e
+        handle_run_error(e)
+      end
+
+      def run_exit_status(result, config, options)
+        # A dry run tests nothing, so there is no score to gate on.
+        return 0 if options[:dry_run]
+
+        exit_status_for(
+          result,
+          config,
+          fail_on_survivors: options[:fail_on_survivors],
+          strict_exit_codes: options[:strict_exit_codes]
+        )
+      end
+
+      def run_pipeline(options, config)
+        resolved_survivors_from = resolve_survivors_from(options[:survivors_from])
+        runner = Runner.new(
+          config:,
+          subjects: subjects_from_argv,
+          since: options[:since],
+          survivors_from: resolved_survivors_from,
+          mode: {
+            dry_run: options.fetch(:dry_run, false),
+            incremental: options.fetch(:incremental, false) && !options.fetch(:force, false)
+          }
+        )
+        runner.run
+      end
+
+      def subjects_from_argv
+        @argv.empty? ? nil : @argv.map { |expr| Subject.parse(expr) }
+      end
+
+      def resolve_survivors_from(survivors_from)
+        return nil if survivors_from.nil?
+
+        # Fast path: if the path already points into reports/sessions/<session_id>/,
+        # keep it as-is so activation-recipes.json can be found by the runner.
+        report_dir = File.dirname(survivors_from)
+        parent_dir = File.dirname(report_dir)
+        # Heuristic: treat any path under a directory named "sessions" as already
+        # being a snapshot path; this keeps activation-recipes lookup correct.
+        return survivors_from if File.basename(parent_dir) == "sessions"
+
+        session_id = session_id_from_report(survivors_from)
+        return survivors_from if session_id.nil?
+
+        snapshot_path = survivors_snapshot_path(report_dir, session_id)
+        recipe_path = File.join(report_dir, "sessions", session_id, "activation-recipes.json")
+        return snapshot_path if File.exist?(recipe_path) && File.exist?(snapshot_path)
+
+        # If the recipes exist but the snapshot doesn't (e.g. partial cleanup),
+        # fall back to the path the user provided so the error message points
+        # at what they actually passed.
+
+        survivors_from
+      rescue StandardError => e
+        warn_survivors_from_resolution_error(survivors_from, e)
+        survivors_from
+      end
+
+      def survivors_snapshot_path(report_dir, session_id)
+        File.join(report_dir, "sessions", session_id, "mutation-report.json")
+      end
+
+      def session_id_from_report(path)
+        parsed = JSON.parse(File.read(path))
+        parsed["sessionId"]
+      rescue JSON::ParserError, Errno::ENOENT
+        nil
+      end
+
+      def exit_status_for(result, config, fail_on_survivors: false, strict_exit_codes: false)
+        if result.respond_to?(:partial_rerun?) && result.partial_rerun?
+          warn "henitai: partial rerun - mutation score threshold not evaluated"
+          return result.survived.positive? ? 1 : 0 if fail_on_survivors
+
+          return 0
+        end
+
+        strict_status = strict_exit_codes ? strict_status_for(result) : nil
+        strict_status || threshold_status_for(result, config)
+      end
+
+      # Expanded, opt-in exit codes (precedence: timeout > runtime/compile
+      # error > threshold miss). The timeout code is informational and
+      # independent of coverage_criteria.timeout: a run can pass its threshold
+      # and still exit 3.
+      def strict_status_for(result)
+        statuses = result.mutants.map(&:status)
+        return 3 if statuses.include?(:timeout)
+        return 4 if statuses.include?(:runtime_error) || statuses.include?(:compile_error)
+
+        nil
+      end
+
+      def threshold_status_for(result, config)
+        score = result.mutation_score
+        # No valid mutants to evaluate (e.g. an incremental run with no changed
+        # code) cannot fail a threshold — treat it as success.
+        return 0 if score.nil?
+
+        score.to_i >= config.thresholds.fetch(:low, 60) ? 0 : 1
+      end
+
+      def warn_survivors_from_resolution_error(survivors_from, error)
+        warn(
+          "henitai: warning: could not resolve survivors-from " \
+          "#{survivors_from}: #{error.class}: #{error.message}"
+        )
+      end
+    end
+  end
+end

data/lib/henitai/cli/run_options.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Henitai
+  class CLI
+    # Option definitions specific to `henitai run`, mixed into {Options} to
+    # keep each module focused: {Options} owns parser construction and the
+    # shared options, this module owns the run-only flags.
+    module RunOptions
+      private
+
+      def add_since_option(opts, options)
+        opts.on("--since GIT_REF", "Only mutate subjects changed since GIT_REF") do |ref|
+          options[:since] = ref
+        end
+      end
+
+      def add_integration_option(opts, options)
+        opts.on("--use INTEGRATION", "Test framework integration (rspec)") do |name|
+          options[:integration] = name
+        end
+      end
+
+      def add_operator_option(opts, options)
+        opts.on("--operators SET", "Operator set: light | full") do |set|
+          options[:operators] = set
+        end
+      end
+
+      def add_timeout_multiplier_option(opts, options)
+        opts.on(
+          "--timeout-multiplier N", Float,
+          "Multiplier applied to the measured per-mutant test baseline " \
+          "when mutation.timeout is unset (default: 3.0)"
+        ) do |n|
+          options[:timeout_multiplier] = n
+        end
+      end
+
+      def add_jobs_option(opts, options)
+        opts.on("--jobs N", Integer, "Number of parallel workers (default: 1)") do |n|
+          options[:jobs] = n
+        end
+      end
+
+      def add_output_option(opts, options)
+        opts.on("--all-logs", "--verbose", "Print all captured child logs") do
+          options[:all_logs] = true
+        end
+      end
+
+      def add_survivors_from_option(opts, options)
+        opts.on(
+          "--survivors-from PATH",
+          "Re-run only survivors from a prior report " \
+          "(partial rerun; threshold checks are skipped; dirty worktrees are included)"
+        ) do |path|
+          options[:survivors_from] = path
+        end
+      end
+
+      def add_dry_run_option(opts, options)
+        opts.on(
+          "--dry-run",
+          "List the post-filter mutant set without executing mutants (always exits 0)"
+        ) do
+          options[:dry_run] = true
+        end
+      end
+
+      def add_incremental_option(opts, options)
+        opts.on(
+          "--incremental",
+          "Reuse still-valid Killed verdicts from the history store instead of re-executing them"
+        ) do
+          options[:incremental] = true
+        end
+      end
+
+      def add_force_option(opts, options)
+        opts.on(
+          "--force",
+          "Bypass verdict reuse and execute every mutant (only meaningful with --incremental)"
+        ) do
+          options[:force] = true
+        end
+      end
+
+      def add_fail_on_survivors_option(opts, options)
+        opts.on(
+          "--fail-on-survivors",
+          "Exit 1 for partial reruns when any survivors remain (otherwise exits 0)"
+        ) do
+          options[:fail_on_survivors] = true
+        end
+      end
+
+      def add_strict_exit_codes_option(opts, options)
+        opts.on(
+          "--strict-exit-codes",
+          "Expanded exit codes: 0 threshold met, 1 threshold miss, " \
+          "2 framework error, 3 timeouts present, 4 runtime/compile errors present"
+        ) do
+          options[:strict_exit_codes] = true
+        end
+      end
+    end
+  end
+end