saboteur 0.2.0

data/lib/saboteur/subject_finder.rb

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "subject"
+
+module Saboteur
+  # Finds `def` methods in a Ruby file with Prism.
+  #
+  # Included: instance methods and `def self.x` inside a class or module,
+  # defs inside `class << self`, and defs passed to a receiverless call such
+  # as `private def x`. Skipped: top-level defs, defs nested in defs, defs in
+  # blocks (`Class.new do`, `included do`), and `def obj.x` for obj != self.
+  class SubjectFinder
+    Parsed = Data.define(:subjects, :errors)
+
+    def call(file)
+      source = File.binread(file)
+      result = Prism.parse(source, filepath: file)
+      return Parsed.new(subjects: [], errors: result.errors.map(&:message)) if result.failure?
+
+      frozen = frozen_literals?(result)
+      subjects = []
+      walk(result.value, [], subjects, file: file, source: source, frozen: frozen)
+      mark_refinements(subjects, result.value)
+      Parsed.new(subjects: subjects, errors: [])
+    end
+
+    private
+
+    def frozen_literals?(result)
+      result.magic_comments.any? do |comment|
+        comment.key.tr("-", "_").casecmp?("frozen_string_literal") && comment.value.casecmp?("true")
+      end
+    end
+
+    def walk(node, nesting, out, **ctx)
+      case node
+      when nil, Prism::BlockNode, Prism::LambdaNode
+        nil
+      when Prism::ModuleNode
+        walk(node.body, nesting + [Scope.new(kind: :module, path: node.constant_path.slice)], out, **ctx)
+      when Prism::ClassNode
+        walk(node.body, nesting + [Scope.new(kind: :class, path: node.constant_path.slice)], out, **ctx)
+      when Prism::SingletonClassNode
+        walk_singleton_class(node, nesting, out, **ctx)
+      when Prism::DefNode
+        add_subject(node, nesting, out, **ctx)
+      else
+        node.compact_child_nodes.each { |child| walk(child, nesting, out, **ctx) }
+      end
+    end
+
+    def walk_singleton_class(node, nesting, out, **ctx)
+      return unless node.expression.is_a?(Prism::SelfNode)
+      return if nesting.empty? || nesting.last.sclass?
+
+      walk(node.body, nesting + [Scope.new(kind: :sclass, path: "self")], out, **ctx)
+    end
+
+    def add_subject(node, nesting, out, file:, source:, frozen:)
+      in_sclass = nesting.last&.sclass? || false
+      # `def self.x` inside `class << self`, and `def obj.x`, are not subjects.
+      return unless node.receiver.nil? || (node.receiver.is_a?(Prism::SelfNode) && !in_sclass)
+
+      singleton = in_sclass || !node.receiver.nil?
+      owner = owner_path(nesting)
+      return unless owner
+
+      out << Subject.new(name: node.name, owner: owner, singleton: singleton, sclass: in_sclass,
+                         file: file, node: node, file_source: source, nesting: nesting,
+                         frozen_literals: frozen)
+    end
+
+    # Lexical path of the enclosing class/module. `class ::Foo` restarts at the top.
+    def owner_path(nesting)
+      parts = nesting.reject(&:sclass?).map(&:path)
+      return nil if parts.empty?
+
+      parts.each_with_object([]) do |path, acc|
+        acc.clear if path.start_with?("::")
+        acc << path.delete_prefix("::")
+      end.join("::")
+    end
+
+    def mark_refinements(subjects, program)
+      return unless uses_refinements?(program)
+
+      subjects.each { |subject| subject.skip_reason = "refinements" }
+    end
+
+    def uses_refinements?(node)
+      return true if node.is_a?(Prism::CallNode) && node.name == :using && node.receiver.nil?
+
+      node.compact_child_nodes.any? { |child| uses_refinements?(child) }
+    end
+  end
+end

data/lib/saboteur/version.rb

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  VERSION = "0.2.0"
+end

data/lib/saboteur.rb

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "saboteur/version"
+
+module Saboteur
+  class Error < StandardError; end
+
+  # Invalid configuration or input files (exit code 2).
+  class ConfigError < Error; end
+
+  class << self
+    # Set while hook files from config load, so they can call Saboteur.hook.
+    attr_accessor :current_hooks
+
+    # Registers a lifecycle hook from a hooks file:
+    #
+    #   Saboteur.hook(:after_fork) { Redis.current.disconnect! }
+    #   Saboteur.hook(:around_mutant) { |mutation, run| Timecop.freeze { run.call } }
+    def hook(name, callable = nil, &)
+      raise Error, "Saboteur.hook is only available while hook files load" unless current_hooks
+
+      current_hooks.register(name, callable, &)
+    end
+  end
+end
+
+require_relative "saboteur/hooks"
+require_relative "saboteur/mutation_source/base"
+require_relative "saboteur/mutation_source/builtin"
+require_relative "saboteur/integration/base"
+require_relative "saboteur/subject"
+require_relative "saboteur/subject_finder"
+require_relative "saboteur/execution/protocol"
+require_relative "saboteur/execution/process_table"
+require_relative "saboteur/execution/process_tree"
+require_relative "saboteur/execution/supervisor"
+require_relative "saboteur/execution/reevaluator"
+require_relative "saboteur/execution/runner"
+require_relative "saboteur/execution/worker_pool"
+require_relative "saboteur/selection/coverage_map"
+require_relative "saboteur/selection/recorder"
+require_relative "saboteur/selection/git_diff"
+require_relative "saboteur/result"
+require_relative "saboteur/config"
+require_relative "saboteur/ignore_list"
+require_relative "saboteur/frameworks/rails"
+require_relative "saboteur/reporter/diff"
+require_relative "saboteur/reporter/terminal"
+require_relative "saboteur/reporter/stryker"
+require_relative "saboteur/engine"

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: saboteur
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Vamsi Pavan Mahesh Gunturu
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: |
+  saboteur makes small deliberate changes to your methods, runs only the tests
+  that cover each change, and reports the changes no test notices.
+email:
+- gvpmahesh@gmail.com
+executables:
+- saboteur
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/saboteur
+- lib/saboteur.rb
+- lib/saboteur/cli.rb
+- lib/saboteur/config.rb
+- lib/saboteur/engine.rb
+- lib/saboteur/engine/boot.rb
+- lib/saboteur/engine/candidates.rb
+- lib/saboteur/engine/coverage_store.rb
+- lib/saboteur/engine/diagnostics.rb
+- lib/saboteur/engine/diff_scope.rb
+- lib/saboteur/engine/distribution.rb
+- lib/saboteur/engine/result_cache.rb
+- lib/saboteur/engine/scheduler.rb
+- lib/saboteur/engine/subject_selection.rb
+- lib/saboteur/engine/suite_files.rb
+- lib/saboteur/engine/verdict_check.rb
+- lib/saboteur/execution/process_table.rb
+- lib/saboteur/execution/process_tree.rb
+- lib/saboteur/execution/protocol.rb
+- lib/saboteur/execution/reevaluator.rb
+- lib/saboteur/execution/runner.rb
+- lib/saboteur/execution/supervisor.rb
+- lib/saboteur/execution/worker_pool.rb
+- lib/saboteur/frameworks/rails.rb
+- lib/saboteur/hooks.rb
+- lib/saboteur/ignore_list.rb
+- lib/saboteur/integration/base.rb
+- lib/saboteur/integration/rspec.rb
+- lib/saboteur/mutation_source/base.rb
+- lib/saboteur/mutation_source/builtin.rb
+- lib/saboteur/mutation_source/edit.rb
+- lib/saboteur/mutation_source/mutation.rb
+- lib/saboteur/reporter/diff.rb
+- lib/saboteur/reporter/stryker.rb
+- lib/saboteur/reporter/terminal.rb
+- lib/saboteur/result.rb
+- lib/saboteur/selection/coverage_map.rb
+- lib/saboteur/selection/git_diff.rb
+- lib/saboteur/selection/recorder.rb
+- lib/saboteur/subject.rb
+- lib/saboteur/subject_finder.rb
+- lib/saboteur/version.rb
+homepage: https://github.com/vamsipavanmahesh/saboteur
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/vamsipavanmahesh/saboteur
+  source_code_uri: https://github.com/vamsipavanmahesh/saboteur
+  changelog_uri: https://github.com/vamsipavanmahesh/saboteur/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/vamsipavanmahesh/saboteur/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Mutation testing for Ruby, driven by per-test coverage.
+test_files: []