kaisoku 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: edd8cb6fea57c23e069b7547ff435d61dad7b2e990fc6ab6993bd26b269d31c1
+  data.tar.gz: bd1b9a13f9e99b880bcf9637b9c158242d1d501ba137e0ab40da6a98ca9b2949
+SHA512:
+  metadata.gz: d498ab221286f31761d145022fea6b74be59c2ae594718ec369080715303d24c45ab0098c6c9e3655524802d133a18d4ba1ef400231f7d19b64a23492850fd68
+  data.tar.gz: a8499104174f91185d344f5c60ac0aaf7a6dc106125b29f3aeb0df54087dd457c386b3c2661b19822b0cd90a122abd40a78fc7241f079cc3118b21dc4c278eb6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+# Kaisoku
+
+Kaisoku is a research-backed Ruby test feedback engine for safe regression test
+selection. It records dynamic dependencies per test entity, selects the tests
+affected by a change, and falls back to a full run when it cannot preserve
+safety.
+
+## Installation
+
+Install the gem and add it to your application's Gemfile by executing:
+
+```bash
+bundle add kaisoku
+```
+
+If bundler is not being used to manage dependencies, install the gem by
+executing:
+
+```bash
+gem install kaisoku
+```
+
+## Usage
+
+Build the initial dependency map:
+
+```bash
+kaisoku map build
+```
+
+Run tests affected by changed files:
+
+```bash
+kaisoku run app/models/user.rb
+```
+
+Run all tests or previous failures:
+
+```bash
+kaisoku run --all
+kaisoku run --failed
+```
+
+Start watch mode:
+
+```bash
+kaisoku watch app lib spec
+```
+
+Inspect map health and preload state:
+
+```bash
+kaisoku doctor --preload
+```
+
+Export and import dependency maps for CI or cache reuse:
+
+```bash
+kaisoku map export > .kaisoku/map.json
+kaisoku map import .kaisoku/map.json
+```
+
+Evaluate selection quality:
+
+```bash
+kaisoku eval --total 100 --selected 12 --ci
+kaisoku eval --commits 20 --json-report .kaisoku/eval-report.json
+```
+
+Unsafe predictive mode is explicit:
+
+```bash
+kaisoku run --predictive
+```
+
+## Supported Frameworks
+
+- RSpec
+- minitest
+- test-unit
+- Cucumber
+
+Select an adapter with `--adapter`:
+
+```bash
+kaisoku run lib/user.rb --adapter minitest
+```
+
+## Features
+
+- Dynamic file-level dependency maps stored in SQLite
+- Smart Ruby checksums that ignore comments while preserving semantic magic comments
+- Safe fallback rules for unknown files, boot-impact files, Ruby/Gemfile changes, and stale maps
+- Fork-based parallel scheduling and failure-first prioritization
+- Watch mode, daemon RPC, console/TUI/JSON/JUnit reporters, and map export/import
+- Hot-file diagnostics and method-level HyRTS policy
+- Evaluation commands for selection metrics, JSON reports, CI history, commit replay, and mutation seeding
+- Preload integrity tracking, Rails-specific hooks, and inline snapshot matcher support
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rake
+```
+
+Run the executable from the checkout:
+
+```bash
+bundle exec ruby -Ilib exe/kaisoku --help
+```
+
+Build the gem locally:
+
+```bash
+gem build kaisoku.gemspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/ydah/kaisoku.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/kaisoku

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'kaisoku'
+
+exit Kaisoku::CLI.start(ARGV)

data/lib/kaisoku/adapter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Kaisoku
+  class Adapter
+    attr_reader :configuration
+
+    def initialize(configuration: Configuration.new)
+      @configuration = configuration
+    end
+
+    def discover(_paths = nil)
+      raise NotImplementedError
+    end
+
+    def run(_entities, reporter:, &_lifecycle)
+      raise NotImplementedError
+    end
+
+    def entity_granularity
+      :group
+    end
+
+    def before_fork(_context); end
+
+    def after_fork(_worker_index); end
+
+    def supports_dry_run?
+      false
+    end
+
+    private
+
+    def ruby_test_files(paths, default_dir:, suffix:)
+      targets = Array(paths).compact
+      targets = [default_dir] if targets.empty?
+
+      targets.flat_map do |path|
+        absolute = configuration.absolute_path(path)
+
+        if File.directory?(absolute)
+          Dir.glob(File.join(absolute, '**', "*#{suffix}")).select { |file| File.file?(file) }
+        elsif File.file?(absolute) && absolute.end_with?(suffix)
+          [absolute]
+        else
+          []
+        end
+      end.uniq.sort
+    end
+
+    def file_entity(file, adapter:)
+      relative = configuration.relative_path(file)
+      Entity.new(
+        adapter: adapter,
+        identifier: "#{relative}[file]",
+        file: relative,
+        line: 1
+      )
+    end
+  end
+
+  module Adapters
+    module Factory
+      module_function
+
+      def build(name, configuration:)
+        case name.to_s
+        when 'rspec'
+          RSpecAdapter.new(configuration: configuration)
+        when 'minitest'
+          MinitestAdapter.new(configuration: configuration)
+        when 'test-unit'
+          TestUnitAdapter.new(configuration: configuration)
+        when 'cucumber'
+          CucumberAdapter.new(configuration: configuration)
+        else
+          raise Error, "unknown adapter: #{name}"
+        end
+      end
+    end
+  end
+end

data/lib/kaisoku/adapters/cucumber.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Kaisoku
+  module Adapters
+    class CucumberAdapter < Adapter
+      ADAPTER_NAME = 'cucumber'
+
+      def discover(paths = nil)
+        feature_files(paths).flat_map { |file| scenarios_in(file) }
+      end
+
+      def run(entities, reporter:, &lifecycle)
+        lifecycle ||= proc {}
+
+        entities.each do |entity|
+          started_at = monotonic_milliseconds
+          lifecycle.call(:entity_started, entity, {})
+          ok = run_cucumber(execution_target(entity))
+          lifecycle.call(:entity_finished, entity, result_payload(ok, started_at))
+        end
+      end
+
+      def entity_granularity
+        :scenario
+      end
+
+      private
+
+      def feature_files(paths)
+        targets = Array(paths).compact
+        targets = ['features'] if targets.empty?
+        targets.flat_map { |path| feature_files_for(path) }.uniq.sort
+      end
+
+      def feature_files_for(path)
+        absolute = configuration.absolute_path(path)
+        return Dir.glob(File.join(absolute, '**', '*.feature')) if File.directory?(absolute)
+        return [absolute] if File.file?(absolute) && absolute.end_with?('.feature')
+
+        []
+      end
+
+      def scenarios_in(file)
+        relative = configuration.relative_path(file)
+        scenarios = File.readlines(file, chomp: true).filter_map.with_index(1) do |line, number|
+          scenario_entity(relative, line, number)
+        end
+        scenarios.empty? ? [file_entity(file, adapter: ADAPTER_NAME)] : scenarios
+      end
+
+      def scenario_entity(relative, line, number)
+        match = line.match(/^\s*Scenario(?: Outline)?:\s*(.+)$/)
+        return nil unless match
+
+        Entity.new(adapter: ADAPTER_NAME, identifier: "#{relative}[#{match[1]}]", file: relative, line: number)
+      end
+
+      def execution_target(entity)
+        "#{configuration.absolute_path(entity.file)}:#{entity.line || 1}"
+      end
+
+      def run_cucumber(target)
+        return system('cucumber', target) unless cucumber_cli_available?
+
+        output = StringIO.new
+        error = StringIO.new
+        status = ::Cucumber::Cli::Main.execute([target], output, error)
+        status.respond_to?(:zero?) ? status.zero? : status == true
+      end
+
+      def cucumber_cli_available?
+        return true if defined?(::Cucumber::Cli::Main)
+
+        require 'cucumber/cli/main'
+        true
+      rescue LoadError
+        false
+      end
+
+      def result_payload(ok, started_at)
+        { status: ok ? 'passed' : 'failed', exit_status: ok ? 0 : 1, duration_ms: monotonic_milliseconds - started_at }
+      end
+
+      def monotonic_milliseconds
+        (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+      end
+    end
+  end
+end

data/lib/kaisoku/adapters/minitest.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+require 'stringio'
+
+module Kaisoku
+  module Adapters
+    class MinitestAdapter < Adapter
+      ADAPTER_NAME = 'minitest'
+
+      def discover(paths = nil)
+        ruby_test_files(paths, default_dir: 'test', suffix: '_test.rb').flat_map { |file| classes_in(file) }
+      end
+
+      def run(entities, reporter:, &lifecycle)
+        lifecycle ||= proc {}
+
+        entities.each do |entity|
+          started_at = monotonic_milliseconds
+          lifecycle.call(:entity_started, entity, {})
+          result = run_entity(entity)
+          lifecycle.call(:entity_finished, entity, result_payload(result, started_at))
+        end
+      end
+
+      def entity_granularity
+        :class
+      end
+
+      def supports_dry_run?
+        true
+      end
+
+      private
+
+      def classes_in(file)
+        relative = configuration.relative_path(file)
+        classes = File.readlines(file, chomp: true).filter_map.with_index(1) do |line, number|
+          class_entity(relative, line, number)
+        end
+
+        classes.empty? ? [file_entity(file, adapter: ADAPTER_NAME)] : classes
+      end
+
+      def class_entity(relative, line, number)
+        match = line.match(/^\s*class\s+([A-Za-z_]\w*(?:::[A-Za-z_]\w*)*)\s*<\s*(?:Minitest::Test|ActiveSupport::TestCase)/)
+        return nil unless match
+
+        Entity.new(
+          adapter: ADAPTER_NAME,
+          identifier: "#{relative}[#{match[1]}]",
+          file: relative,
+          line: number
+        )
+      end
+
+      def run_entity(entity)
+        require 'minitest'
+        Minitest.seed ||= srand % 0xFFFF
+        before = Minitest::Runnable.runnables.dup
+        load configuration.absolute_path(entity.file)
+        classes = selected_classes(before, entity)
+        reporter = Minitest::CompositeReporter.new(Minitest::SummaryReporter.new(StringIO.new, {}))
+        reporter.start
+        classes.each do |klass|
+          klass.runnable_methods.each { |method_name| klass.run(klass, method_name, reporter) }
+        end
+        reporter.report
+        reporter.passed?
+      end
+
+      def class_name(entity)
+        entity.identifier[/\[(.+)\]\z/, 1]
+      end
+
+      def selected_classes(before, entity)
+        candidates = Minitest::Runnable.runnables - before
+        return candidates unless class_name(entity)
+
+        candidates.select { |klass| klass.name == class_name(entity) }
+      end
+
+      def result_payload(ok, started_at)
+        {
+          status: ok ? 'passed' : 'failed',
+          exit_status: ok ? 0 : 1,
+          duration_ms: monotonic_milliseconds - started_at
+        }
+      end
+
+      def monotonic_milliseconds
+        (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+      end
+    end
+  end
+end

data/lib/kaisoku/adapters/rspec.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'stringio'
+
+module Kaisoku
+  module Adapters
+    class RSpecAdapter < Adapter
+      ADAPTER_NAME = 'rspec'
+
+      def discover(paths = nil)
+        ruby_test_files(paths, default_dir: 'spec', suffix: '_spec.rb').flat_map { |file| groups_in(file) }
+      end
+
+      def run(entities, reporter:, &lifecycle)
+        require 'rspec/core'
+
+        lifecycle ||= proc {}
+
+        entities.each do |entity|
+          started_at = monotonic_milliseconds
+          lifecycle.call(:entity_started, entity, {})
+          status_code = ::RSpec::Core::Runner.run([execution_target(entity)], $stderr, $stdout)
+          lifecycle.call(:entity_finished, entity, result_payload(status_code, started_at))
+        end
+      end
+
+      def entity_granularity
+        :group
+      end
+
+      def supports_dry_run?
+        true
+      end
+
+      private
+
+      def groups_in(file)
+        dry_run = dry_run_examples_in(file)
+        return dry_run unless dry_run.empty?
+
+        relative = configuration.relative_path(file)
+        groups = File.readlines(file, chomp: true).filter_map.with_index(1) do |line, number|
+          group_entity(relative, line, number)
+        end
+
+        groups.empty? ? [file_entity(file, adapter: ADAPTER_NAME)] : groups
+      end
+
+      def group_entity(relative, line, number)
+        match = line.match(/^\s*(?:RSpec\.)?(describe|context)\s+(.+?)(?:\s+do|\s+\{|\z)/)
+        return nil unless match
+
+        name = match[2].gsub(/\s+/, ' ').strip
+        Entity.new(
+          adapter: ADAPTER_NAME,
+          identifier: "#{relative}[#{name}]",
+          file: relative,
+          line: number
+        )
+      end
+
+      def dry_run_examples_in(file)
+        return [] unless ENV['KAISOKU_RSPEC_DRY_RUN'] == '1'
+
+        require 'rspec/core'
+        output = StringIO.new
+        error = StringIO.new
+        status = ::RSpec::Core::Runner.run([configuration.absolute_path(file), '--dry-run', '--format', 'json'], error,
+                                           output)
+        return [] unless status.zero?
+
+        examples_from_json(file, output.string)
+      rescue StandardError
+        []
+      end
+
+      def examples_from_json(file, payload)
+        relative = configuration.relative_path(file)
+        ::JSON.parse(payload).fetch('examples', []).map do |example|
+          Entity.new(
+            adapter: ADAPTER_NAME,
+            identifier: "#{relative}[#{example.fetch('full_description', example['id'])}]",
+            file: relative,
+            line: example['line_number']
+          )
+        end
+      rescue ::JSON::ParserError
+        []
+      end
+
+      def execution_target(entity)
+        return configuration.absolute_path(entity.file) unless entity.line
+
+        "#{configuration.absolute_path(entity.file)}:#{entity.line}"
+      end
+
+      def result_payload(status_code, started_at)
+        {
+          status: status_code.zero? ? 'passed' : 'failed',
+          exit_status: status_code,
+          duration_ms: monotonic_milliseconds - started_at
+        }
+      end
+
+      def monotonic_milliseconds
+        (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+      end
+    end
+  end
+end

data/lib/kaisoku/adapters/test_unit.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Kaisoku
+  module Adapters
+    class TestUnitAdapter < MinitestAdapter
+      ADAPTER_NAME = 'test-unit'
+
+      def discover(paths = nil)
+        ruby_test_files(paths, default_dir: 'test', suffix: '_test.rb').flat_map { |file| classes_in(file) }
+      end
+
+      def entity_granularity
+        :class
+      end
+
+      private
+
+      def classes_in(file)
+        relative = configuration.relative_path(file)
+        classes = File.readlines(file, chomp: true).filter_map.with_index(1) do |line, number|
+          class_entity(relative, line, number)
+        end
+
+        classes.empty? ? [file_entity(file, adapter: ADAPTER_NAME)] : classes
+      end
+
+      def class_entity(relative, line, number)
+        match = line.match(/^\s*class\s+([A-Za-z_]\w*(?:::[A-Za-z_]\w*)*)\s*<\s*(?:Test::Unit::TestCase|Minitest::Test|ActiveSupport::TestCase)/)
+        return nil unless match
+
+        Entity.new(adapter: ADAPTER_NAME, identifier: "#{relative}[#{match[1]}]", file: relative, line: number)
+      end
+    end
+  end
+end

data/lib/kaisoku/checksum.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'prism'
+
+module Kaisoku
+  class Checksum
+    RUBY_EXTENSION = '.rb'
+    SKIPPED_RUBY_TOKENS = %i[COMMENT IGNORED_NEWLINE NEWLINE].freeze
+
+    def digest(path)
+      return nil unless File.file?(path)
+
+      if File.extname(path) == RUBY_EXTENSION
+        ruby_digest(path)
+      else
+        raw_digest(path)
+      end
+    rescue StandardError
+      raw_digest(path)
+    end
+
+    private
+
+    def ruby_digest(path)
+      result = Prism.lex_file(path)
+      raise Error, "Prism failed to lex #{path}" if result.failure?
+
+      normalized = result.value.filter_map do |token, _state|
+        normalize_token(token)
+      end
+
+      Digest::SHA256.hexdigest(normalized.join("\n"))
+    end
+
+    def normalize_token(token)
+      return normalize_magic_comment(token.value) if token.type == :COMMENT && magic_comment?(token.value)
+      return nil if SKIPPED_RUBY_TOKENS.include?(token.type)
+
+      "#{token.type}:#{token.value}"
+    end
+
+    def magic_comment?(value)
+      value.match?(/\A#.*\b(frozen_string_literal|encoding|coding):/i)
+    end
+
+    def normalize_magic_comment(value)
+      "COMMENT:#{value.strip}"
+    end
+
+    def raw_digest(path)
+      Digest::SHA256.file(path).hexdigest
+    end
+  end
+end