gitlab-crystalball 0.7.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2edc0f271a5823ee73e40d74c51f6e357d578424aa059757b4ff6690316adc74
+  data.tar.gz: b9803cc94cd0d6b8437d317e7b47d25ebec6de6bf4b4a53735b9e12c97b6dd13
+SHA512:
+  metadata.gz: 24937f95403f4ba4637a9f7f5e3558b8a7f2fc4d7759577a237de8b849e0e6a20a4a87e764d0f73f58ac5b5cf18650f7a8ef15d94aaa479b726afe2ccf8fb599
+  data.tar.gz: 85ce3e28abde0853b087e685c7bc81dec2a0a11c136ff79b81dab558abbd55ce1c020d260d316c5c11ca865819a40f2483b33f65390a71f4ffe178e5cb931b4b

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2025 GitLab Inc
+
+MIT License
+
+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,56 @@
+# Crystalball
+
+![Build Status](https://gitlab.com/acunskis/crystalball/badges/main/pipeline.svg)
+![Test Coverage](https://gitlab.com/acunskis/crystalball/badges/main/coverage.svg?job=rspec)
+
+Crystalball is a Ruby library which implements [Regression Test Selection mechanism](https://tenderlovemaking.com/2015/02/13/predicting-test-failues.html) originally published by Aaron Patterson.
+Its main purpose is to select a minimal subset of your test suite which should be run to ensure your changes didn't break anything.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+group :test do
+  gem 'crystalball'
+end
+```
+
+And then execute:
+
+```console
+  bundle install
+```
+
+Or install it yourself as:
+
+```console
+  gem install crystalball
+```
+
+## Usage
+
+Please see our [official documentation](https://gitlab.com/acunskis/crystalball/-/blob/main/docs/index.md).
+
+### Versioning
+
+We use [semantic versioning](https://semver.org/) for our [releases](https://gitlab.com/acunskis/crystalball/-/releases).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Release
+
+In order to release new version, manual pipeline should be triggered via Gitlab UI and version component input should be set according to [semver versioning](#versioning) strategy. Pipeline will then automatically bump version, push updated files and release tag and build and push gem to <rubygems.org>.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/toptal/crystalball>.
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+Crystalball is released under the [MIT License](https://opensource.org/licenses/MIT).

data/bin/crystalball

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'crystalball'
+Crystalball::RSpec::Runner.invoke

data/lib/crystalball/active_record.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "crystalball/rails/tables_map_generator"
+require "crystalball/rails/predictor/modified_schema"

data/lib/crystalball/example_group_map.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Crystalball
+  # Data object to store execution map for specific example
+  class ExampleGroupMap
+    attr_reader :uid, :file_path, :used_files
+    extend Forwardable
+
+    delegate %i[push each] => :used_files
+
+    # @param [Example|ExampleGroup] example - RSpec example or example group
+    # @param [Array<String>] used_files - list of files affected by example
+    def initialize(example, used_files = [])
+      @uid = example.id
+      @file_path = example.file_path
+      @used_files = used_files
+    end
+  end
+end

data/lib/crystalball/execution_map.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Crystalball
+  # Storage for execution map
+  class ExecutionMap
+    extend Forwardable
+
+    # Simple data object for map metadata information
+    class Metadata
+      attr_reader :commit, :type, :version, :timestamp
+
+      # @param [String] commit - SHA of commit
+      # @param [String] type - type of execution map
+      # @param [Numeric] version - map generator version number
+      def initialize(commit: nil, type: nil, version: nil, timestamp: nil)
+        @commit = commit
+        @type = type
+        @timestamp = timestamp
+        @version = version
+      end
+
+      def to_h
+        {type: type, commit: commit, timestamp: timestamp, version: version}
+      end
+    end
+
+    attr_reader :example_groups, :metadata
+
+    delegate %i[commit version timestamp] => :metadata
+    delegate %i[size] => :example_groups
+
+    # @param [Hash] metadata - add or override metadata of execution map
+    # @param [Hash] example_groups - initial list of example groups data
+    def initialize(metadata: {}, example_groups: {})
+      @example_groups = example_groups
+
+      @metadata = Metadata.new(type: self.class.name, **metadata)
+    end
+
+    # Adds example group map to the list
+    #
+    # @param [Crystalball::ExampleGroupMap] example_group_map
+    def <<(example_group_map)
+      example_groups[example_group_map.uid] = example_group_map.used_files.uniq
+    end
+
+    # Remove all example_groups
+    def clear!
+      self.example_groups = {}
+    end
+
+    private
+
+    attr_writer :example_groups, :metadata
+  end
+end

data/lib/crystalball/extensions/git/base.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents git repo object itself.
+  class Base
+    # `git merge-base ...`. Returns common ancestor for all passed commits
+    #
+    # @param [Array<Object>] args - list of commits to process. Last argument can be options for merge-base command
+    # @return [Git::Object::Commit]
+    def merge_base(*args)
+      gcommit(lib.merge_base(*args))
+    end
+  end
+end

data/lib/crystalball/extensions/git/lib.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Git
+  # Class which holds whole collection of raw methods to work with git
+  class Lib
+    # `git merge-base ...`. Returns common ancestor for all passed commits
+    #
+    # @param [Array<Object>] args - list of commits to process. Last argument can be options for merge-base command
+    # @return [String]
+    def merge_base(*args)
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+      arg_opts = opts.filter_map { |k, v| "--#{k}" if v } + args
+
+      command("merge-base", *arg_opts.flatten)
+    end
+  end
+end

data/lib/crystalball/extensions/git.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "crystalball/extensions/git/base"
+require "crystalball/extensions/git/lib"

data/lib/crystalball/factory_bot.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "crystalball/map_generator/factory_bot_strategy"

data/lib/crystalball/git_repo.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "git"
+require "crystalball/source_diff"
+
+module Crystalball
+  # Wrapper class representing Git repository
+  class GitRepo
+    attr_reader :repo_path
+
+    class << self
+      # @return [Crystalball::GitRepo] instance for given path
+      def open(repo_path)
+        path = Pathname(repo_path)
+        new(path) if exists?(path)
+      end
+
+      # Check if given path is under git control (contains .git folder)
+      def exists?(path)
+        path.join(".git").directory?
+      end
+    end
+
+    # @param [Pathname] repo_path path to repository root folder
+    def initialize(repo_path)
+      @repo_path = repo_path
+    end
+
+    # Proxy all unknown calls to `Git` object
+    def method_missing(method, *args, &block)
+      repo.public_send(method, *args, &block)
+    end
+
+    def respond_to_missing?(method, *)
+      repo.respond_to?(method, false)
+    end
+
+    # Creates diff
+    #
+    # @param [String] from starting commit to build a diff. Default: HEAD
+    # @param [String] to ending commit to build a diff. Default: nil, will build diff of uncommitted changes
+    # @return [SourceDiff]
+    def diff(from = "HEAD", to = nil)
+      SourceDiff.new(repo.diff(from, to))
+    end
+
+    private
+
+    def repo
+      @repo ||= Git.open(repo_path)
+    end
+  end
+end

data/lib/crystalball/logging.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Crystalball
+  # This module logs information to the standard output based on the configured log level,
+  # and also logs unfiltered information to the configured log file.
+  module Logging
+    def log(severity_sym, *args, &block)
+      output_stream.log(severity(severity_sym), *args, &block)
+      log_file_output_stream.log(severity(severity_sym), *args, &block)
+    end
+
+    def self.extended(base)
+      base.private_class_method :severity, :output_stream, :log_file_output_stream, :configured_level, :config
+    end
+
+    # @api private
+    def reset_logger
+      @output_stream = nil
+      @log_file_output_stream = nil
+    end
+
+    def severity(severity_sym)
+      ::Logger.const_get(severity_sym.to_s.upcase)
+    end
+
+    def output_stream
+      @output_stream ||= ::Logger.new(STDOUT).tap do |logger|
+        logger.level = severity(configured_level)
+      end
+    end
+
+    def log_file_output_stream
+      @log_file_output_stream ||= begin
+        config["log_file"].dirname.mkpath
+        ::Logger.new(config["log_file"]).tap do |logger|
+          logger.level = ::Logger::DEBUG
+        end
+      end
+    end
+
+    def configured_level
+      config["log_level"].to_sym
+    end
+
+    def config
+      @config ||= Crystalball::RSpec::Runner.config
+    end
+  end
+end

data/lib/crystalball/map_compactor/example_context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Crystalball
+  module MapCompactor
+    # Class representing RSpec context data
+    class ExampleContext
+      attr_reader :address
+
+      def initialize(address)
+        @address = address
+      end
+
+      def parent
+        @parent ||= begin
+          parent_uid = address.split(":")[0..-2].join(":")
+          parent_uid.empty? ? nil : self.class.new(parent_uid)
+        end
+      end
+
+      def include?(example_id)
+        example_id =~ /\[#{address}[\:\]]/
+      end
+
+      def depth
+        @depth ||= address.split(":").size
+      end
+    end
+  end
+end

data/lib/crystalball/map_compactor/example_groups_data_compactor.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "crystalball/map_compactor/example_context"
+
+module Crystalball
+  module MapCompactor
+    # Class representing example groups data compacting logic for a single file
+    class ExampleGroupsDataCompactor
+      # @param [Hash] plain_data a hash of examples and used files
+      def self.compact!(plain_data)
+        new(plain_data).compact!
+      end
+
+      def compact!
+        contexts = extract_contexts(plain_data.keys).sort_by(&:depth)
+
+        contexts.each do |context|
+          compact_data[context.address] = compact_context!(context)
+        end
+        compact_data
+      end
+
+      private
+
+      attr_reader :compact_data, :plain_data
+
+      def initialize(plain_data)
+        @plain_data = plain_data
+        @compact_data = {}
+      end
+
+      def compact_context!(context) # rubocop:disable Metrics/MethodLength
+        result = nil
+        plain_data.each do |example_uid, used_files|
+          next unless context.include?(example_uid)
+
+          if result.nil?
+            result = used_files
+            result -= deep_used_files(context.parent) if context.parent
+          else
+            result &= used_files
+          end
+        end
+        result
+      end
+
+      def deep_used_files(context)
+        result = compact_data[context.address]
+        result += deep_used_files(context.parent) if context.parent
+        result
+      end
+
+      def extract_contexts(example_uids)
+        result = []
+        example_uids.each do |example_uid|
+          context_numbers = /\[(.*)\]/.match(example_uid)[1].split(":")
+          until context_numbers.empty?
+            result << ExampleContext.new(context_numbers.join(":"))
+            context_numbers.pop
+          end
+        end
+        result.compact.uniq(&:address)
+      end
+    end
+  end
+end

data/lib/crystalball/map_compactor.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+require "crystalball/example_group_map"
+require "crystalball/execution_map"
+require "crystalball/map_compactor/example_groups_data_compactor"
+
+module Crystalball
+  # a module for compacting execution map by moving out repeated used files to upper contexts records.
+  module MapCompactor
+    class << self
+      # @param [Crystalball::ExecutionMap] map execution map to be compacted
+      # @return [Crystalball::ExecutionMap] compact map
+      def compact_map!(map)
+        new_map = Crystalball::ExecutionMap.new(metadata: map.metadata.to_h)
+
+        compact_examples!(map.example_groups).each do |context, used_files|
+          new_map << ExampleGroupMap.new(OpenStruct.new(id: context, file_path: example_filename(context)), used_files)
+        end
+
+        new_map
+      end
+
+      def compact_examples!(example_groups)
+        result = {}
+        example_groups.group_by { |k, _v| example_filename(k) }.each do |filename, examples|
+          compact_data = ExampleGroupsDataCompactor.compact!(examples.to_h)
+
+          compact_data.each do |context_address, used_files|
+            result["#{filename}[#{context_address}]"] = used_files unless used_files.empty?
+          end
+        end
+        result
+      end
+
+      private
+
+      def example_filename(example_id)
+        example_id.split("[").first
+      end
+    end
+  end
+end

data/lib/crystalball/map_generator/allocated_objects_strategy/object_tracker.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Crystalball
+  class MapGenerator
+    class AllocatedObjectsStrategy
+      # Class to list object classes used during a block
+      class ObjectTracker
+        attr_reader :only_of
+
+        # @param [Array<Module>] only_of - classes or modules to watch on
+        def initialize(only_of: ["Object"])
+          @only_of = only_of
+          @created_object_classes = Set.new
+        end
+
+        # @yield a block to execute
+        # @return [Array<Object>] classes of objects allocated during the block execution
+        def used_classes_during(&block)
+          self.created_object_classes = Set.new
+          trace_point.enable(&block)
+          created_object_classes
+        end
+
+        private
+
+        attr_accessor :created_object_classes
+
+        def whitelisted_constants
+          @whitelisted_constants ||= only_of.map { |str| Object.const_get(str) }
+        end
+
+        def trace_point
+          @trace_point ||= TracePoint.new(:c_call) do |tp|
+            next unless tp.method_id == :new || tp.method_id == :allocate
+            next unless whitelisted_constants.any? { |c| tp.self <= c }
+
+            created_object_classes << tp.self
+          end
+        end
+      end
+    end
+  end
+end

data/lib/crystalball/map_generator/allocated_objects_strategy.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "crystalball/map_generator/base_strategy"
+require "crystalball/map_generator/object_sources_detector"
+require "crystalball/map_generator/allocated_objects_strategy/object_tracker"
+
+module Crystalball
+  class MapGenerator
+    # Map generator strategy to get paths to files contains definition for all objects and its
+    # ancestors allocated during test example.
+    class AllocatedObjectsStrategy
+      include BaseStrategy
+      extend Forwardable
+
+      attr_reader :execution_detector, :object_tracker
+
+      delegate %i[after_register before_finalize] => :execution_detector
+
+      def self.build(only: [], root: Dir.pwd)
+        hierarchy_fetcher = ObjectSourcesDetector::HierarchyFetcher.new(only)
+        execution_detector = ObjectSourcesDetector.new(root_path: root, hierarchy_fetcher: hierarchy_fetcher)
+
+        new(execution_detector: execution_detector, object_tracker: ObjectTracker.new(only_of: only))
+      end
+
+      # @param [#detect] execution_detector
+      # @param [#created_during] object_tracker
+      def initialize(execution_detector:, object_tracker:)
+        @object_tracker = object_tracker
+        @execution_detector = execution_detector
+      end
+
+      # Adds to the used files every file which contain the definition of the
+      # classes of the objects allocated during the spec execution.
+      # @param [Crystalball::ExampleGroupMap] example_map - object holding example metadata and used files
+      # @param [RSpec::Core::Example] example - a RSpec example
+      def call(example_map, example)
+        classes = object_tracker.used_classes_during do
+          yield example_map, example
+        end
+        example_map.push(*execution_detector.detect(classes))
+      end
+    end
+  end
+end

data/lib/crystalball/map_generator/base_strategy.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Crystalball
+  class MapGenerator
+    # Map generator strategy interface
+    module BaseStrategy
+      def after_register; end
+
+      def after_start; end
+
+      def before_finalize; end
+
+      # Each strategy must implement #call augmenting the used_files list and
+      # yielding back the ExampleGroupMap.
+      # @param [Crystalball::ExampleGroupMap] _example_map - object holding example metadata and used files
+      # @param [RSpec::Core::Example] _example - a RSpec example
+      def call(_example_map, _example)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/crystalball/map_generator/configuration.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "crystalball/map_generator/strategies_collection"
+
+module Crystalball
+  class MapGenerator
+    # Configuration of map generator. Is can be accessed as a first argument inside
+    # `Crystalball::MapGenerator.start! { |config| config } block.
+    class Configuration
+      attr_writer :map_storage
+      attr_writer :map_class
+      attr_accessor :commit, :version, :compact_map
+
+      attr_reader :strategies
+
+      def initialize
+        @strategies = StrategiesCollection.new
+        @compact_map = true
+      end
+
+      def compact_map?
+        !!@compact_map
+      end
+
+      def map_class
+        @map_class ||= ExecutionMap
+      end
+
+      def map_storage_path
+        @map_storage_path ||= Pathname("tmp/crystalball_data.yml")
+      end
+
+      def map_storage_path=(value)
+        @map_storage_path = Pathname(value)
+      end
+
+      def map_storage
+        @map_storage ||= MapStorage::YAMLStorage.new(map_storage_path)
+      end
+
+      def dump_threshold
+        @dump_threshold ||= 100
+      end
+
+      def dump_threshold=(value)
+        @dump_threshold = value.to_i
+      end
+
+      # Register new strategy for map generation
+      #
+      # @param [Crystalball::MapGenerator::BaseStrategy] strategy
+      def register(strategy)
+        @strategies.push strategy
+        strategy.after_register
+      end
+    end
+  end
+end

data/lib/crystalball/map_generator/coverage_strategy/execution_detector.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "../helpers/path_filter"
+
+module Crystalball
+  class MapGenerator
+    class CoverageStrategy
+      # Class for detecting code execution path based on coverage information diff
+      class ExecutionDetector
+        include ::Crystalball::MapGenerator::Helpers::PathFilter
+        # Detects files affected during example execution. Transforms absolute paths to relative.
+        # Exclude paths outside of repository
+        #
+        # @param[Array<String>] list of files affected before example execution
+        # @param[Array<String>] list of files affected after example execution
+        # @return [Array<String>]
+        def detect(before, after)
+          filter after.reject { |file_name, after_coverage| before[file_name] == after_coverage }.keys
+        end
+      end
+    end
+  end
+end