judges 0.44.0 → 0.44.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc9d8bdc800247520e9f42a07f90143c7c3fcf505a4a993221d7aa8437b11611
-  data.tar.gz: 21d88232ebe5299cf672945ab83c702a3c942d984f233bd9f714fb2cdb846609
+  metadata.gz: 4791985ccc60d62edaf96e7fdf59912d4f5c53bfe21cfedd5d5554087c006324
+  data.tar.gz: e49a5acd43f2c9722e36233d7ed228f00dbbb63df3a7259c03e9b9f224e7b3c3
 SHA512:
-  metadata.gz: eb1ac7d1219d4f901c5856e8c2698c4e77eaf5a3b0f8f0658bc94e1304f5597b3cada4a9c1ba85660bbaebd81a2e03cea58a92b7ba8e1a2c820e3403ea269a60
-  data.tar.gz: a9937c3f3d031d3d2c6e1265d8ccc2bf0365ffcda171d539bdf03a22d68d6a3d887a6010beb876c17fd1f2a31cd38d06d0e7473861bc3e6cb2a21b62857041a3
+  metadata.gz: 3571c3740ed87fd99a5e56f482f297f1ecec20440c7a924122a1a0bd43d26aa5e492d986adf0de8bd65d2931d2a345af84afb469766ab2ce8a025e4c9014e424
+  data.tar.gz: 61e06fba2897f2fa04214372ee646029134cfd7f9877c2c92afdbe113d9665158da79b5c5257bf3a64dd880d276f26b81984c8b6b8240a166f81c16197f55b01

data/.github/workflows/copyrights.yml

@@ -16,4 +16,4 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
-      - uses: yegor256/copyrights-action@0.0.8
+      - uses: yegor256/copyrights-action@0.0.10

data/bin/judges

@@ -61,6 +61,13 @@ class JudgesGLI extend GLI::App
     true
   end
 
+  desc 'Print version of the tool'
+  command :version do |c|
+    c.action do
+      @@loog.info(Judges::VERSION)
+    end
+  end
+
   desc 'Update the factbase by executing all judges sequentially'
   command :update do |c|
     c.desc 'Options to pass to each judge'

data/features/version.feature

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+Feature: Version
+  I want to know the version of the gem
+
+  Scenario: Print the version
+    Given I make a temp directory
+    Then I run bin/judges with "version"
+    And Exit code is zero

data/judges.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
   s.required_ruby_version = '>=3.2'
   s.name = 'judges'
-  s.version = '0.44.0'
+  s.version = '0.44.1'
   s.license = 'MIT'
   s.summary = 'Command-Line Tool for a Factbase'
   s.description =

data/lib/judges/categories.rb

@@ -6,21 +6,51 @@
 require_relative '../judges'
 
 # Categories of tests.
+#
+# This class manages test categories, allowing you to enable or disable
+# specific categories of tests. It provides a mechanism to filter which
+# tests should be executed based on their associated categories.
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Judges::Categories
-  # Ctor.
+  # Initialize a new Categories instance.
+  #
+  # Creates a categories filter with lists of enabled and disabled categories.
+  # The filter logic works as follows:
+  # - If a category is in the disable list, the test is rejected
+  # - If a category is in the enable list, the test is accepted
+  # - If no categories are enabled (empty enable list), all tests are accepted
+  #   unless explicitly disabled
+  #
   # @param [Array<String>] enable List of categories to enable
-  # @param [Array<String>] disable List of categories to enable
+  # @param [Array<String>] disable List of categories to disable
   def initialize(enable, disable)
     @enable = enable.is_a?(Array) ? enable : []
     @disable = disable.is_a?(Array) ? disable : []
   end
 
-  # This test is good to go, with this list of categories?
-  # @param [Array<String>] cats List of them
-  # @return [Boolean] True if yes
+  # Check if a test with given categories should be executed.
+  #
+  # Determines whether a test associated with the provided categories
+  # should be executed based on the enable/disable lists configured
+  # during initialization.
+  #
+  # The evaluation logic:
+  # 1. If any category is in the disable list, returns false
+  # 2. If any category is in the enable list, returns true
+  # 3. If the enable list is empty, returns true (all tests allowed)
+  # 4. Otherwise, returns false
+  #
+  # @param [Array<String>, String, nil] cats List of categories associated with the test,
+  #   can be a single string or nil
+  # @return [Boolean] true if the test should be executed, false otherwise
+  # @example Check if a test with categories should run
+  #   categories = Judges::Categories.new(['important'], ['experimental'])
+  #   categories.ok?(['important', 'slow']) # => true
+  #   categories.ok?(['experimental']) # => false
+  #   categories.ok?(nil) # => true (if enable list is empty)
   def ok?(cats)
     cats = [] if cats.nil?
     cats = [cats] unless cats.is_a?(Array)

data/lib/judges/commands/update.rb

@@ -159,7 +159,8 @@ class Judges::Update
           elapsed(@loog, level: Logger::INFO) do
             c = one_judge(opts, fb, judge, global, options, errors)
             churn += c
-            throw :"👍 The '#{judge.name}' judge #{c} out of #{fb.size}"
+            throw :"👍 The '#{judge.name}' judge made zero changes to #{fb.size} facts" if c.zero?
+            throw :"👍 The '#{judge.name}' judge #{c} out of #{fb.size} facts"
           end
         rescue StandardError, SyntaxError => e
           @loog.warn(Backtrace.new(e))
@@ -187,7 +188,7 @@ class Judges::Update
   # @param [Hash] global Global options
   # @param [Judges::Options] options The options
   # @param [Array<String>] errors List of errors
-  # @return [Churn] How many modifications have been made
+  # @return [Factbase::Churn] How many modifications have been made
   def one_judge(opts, fb, judge, global, options, errors)
     local = {}
     start = Time.now

data/lib/judges/impex.rb

@@ -10,21 +10,42 @@ require_relative '../judges'
 require_relative '../judges/to_rel'
 
 # Import/Export of factbases.
+#
+# This class provides functionality for importing and exporting Factbase
+# objects to and from binary files. It handles file I/O operations with
+# proper logging and error handling.
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Judges::Impex
-  # Initialize.
-  # @param [Loog] loog Logging facility
+  # Initialize a new Impex instance.
+  #
+  # @param [Loog] loog Logging facility for recording import/export operations
   # @param [String] file File path for import/export operations
+  # @example Create an Impex instance
+  #   impex = Judges::Impex.new(logger, '/path/to/factbase.fb')
   def initialize(loog, file)
     @loog = loog
     @file = file
   end
 
   # Import factbase from file.
-  # @param [Boolean] strict Whether to raise error if file doesn't exist
-  # @return [Factbase] The imported factbase
+  #
+  # Creates a new Factbase instance and imports data from the file specified
+  # during initialization. The operation is timed and logged. If the file
+  # doesn't exist, behavior depends on the strict parameter.
+  #
+  # @param [Boolean] strict Whether to raise error if file doesn't exist.
+  #   When true (default), raises an error if file is missing.
+  #   When false, logs a message and returns an empty factbase.
+  # @return [Factbase] The imported factbase, or empty factbase if file
+  #   doesn't exist and strict is false
+  # @raise [RuntimeError] If file doesn't exist and strict is true
+  # @example Import with strict mode (default)
+  #   fb = impex.import # Raises error if file missing
+  # @example Import with non-strict mode
+  #   fb = impex.import(strict: false) # Returns empty factbase if file missing
   def import(strict: true)
     fb = Factbase.new
     if File.exist?(@file)
@@ -40,8 +61,18 @@ class Judges::Impex
   end
 
   # Import factbase from file into existing factbase.
-  # @param [Factbase] fb The factbase to import into
+  #
+  # Imports data from the file into an existing Factbase instance rather
+  # than creating a new one. This is useful when you need to merge data
+  # into an already populated factbase. The operation is timed and logged.
+  #
+  # @param [Factbase] fb The factbase to import into. The imported data
+  #   will be added to this existing factbase.
   # @raise [RuntimeError] If file doesn't exist
+  # @example Import into existing factbase
+  #   fb = Factbase.new
+  #   # ... populate fb with some data ...
+  #   impex.import_to(fb) # Adds data from file to existing facts
   def import_to(fb)
     raise "The factbase is absent at #{@file.to_rel}" unless File.exist?(@file)
     elapsed(@loog, level: Logger::INFO) do
@@ -51,7 +82,17 @@ class Judges::Impex
   end
 
   # Export factbase to file.
-  # @param [Factbase] fb The factbase to export
+  #
+  # Exports the given Factbase instance to the file specified during
+  # initialization. Creates any necessary parent directories automatically.
+  # The operation is timed and logged with file size and fact count information.
+  #
+  # @param [Factbase] fb The factbase to export. All facts in this factbase
+  #   will be serialized to the binary file format.
+  # @example Export a factbase
+  #   fb = Factbase.new
+  #   # ... add facts to fb ...
+  #   impex.export(fb) # Saves to file specified in constructor
   def export(fb)
     elapsed(@loog, level: Logger::INFO) do
       FileUtils.mkdir_p(File.dirname(@file))

data/lib/judges/judge.rb

@@ -28,25 +28,32 @@ class Judges::Judge
     @start = start
   end
 
-  # Print it as a string.
-  # @return [String] Name of it
+  # Returns the string representation of the judge.
+  #
+  # @return [String] The name of the judge (same as the directory name)
   def to_s
     name
   end
 
-  # Run it with the given Factbase and environment variables.
+  # Executes the judge script with the provided factbase and configuration.
+  #
+  # This method sets up the execution environment by creating global variables,
+  # loading library files, and running the judge script. It tracks execution time
+  # and captures any errors that occur during execution.
   #
-  # @param [Factbase] fb The factbase
-  # @param [Hash] global Global options
-  # @param [Hash] local Local options
-  # @param [Judges::Options] options The options from command line
-  # @return [Factbase::Churn] The changes just made
+  # @param [Factbase] fb The factbase instance to operate on
+  # @param [Hash] global Global configuration options shared across all judges
+  # @param [Hash] local Local configuration options specific to this judge
+  # @param [Judges::Options] options Command-line options object
+  # @return [Factbase::Churn] Object containing statistics about the changes made to the factbase
+  # @raise [RuntimeError] If the lib directory doesn't exist, the script can't be loaded, or execution fails
   def run(fb, global, local, options)
     $fb = Factbase::Tallied.new(fb)
     $judge = File.basename(@dir)
     $options = options
     $loog = @loog
     $global = global
+    $global.delete(:fb) # to make sure Tallied is always actual
     $local = local
     $start = @start
     options.to_h.each { |k, v| ENV.store(k.to_s, v.to_s) }
@@ -74,12 +81,22 @@ class Judges::Judge
     end
   end
 
-  # Get the name of the judge.
+  # Returns the name of the judge.
+  #
+  # The name is derived from the directory name containing the judge.
+  #
+  # @return [String] The base name of the judge directory
   def name
     File.basename(@dir)
   end
 
-  # Get the name of the .rb script in the judge.
+  # Returns the name of the main Ruby script file for this judge.
+  #
+  # The script file must have the same name as the judge directory with a .rb extension.
+  # For example, if the judge directory is "quality", the script must be "quality.rb".
+  #
+  # @return [String] The filename of the judge script (e.g., "judge_name.rb")
+  # @raise [RuntimeError] If the expected script file is not found in the judge directory
   def script
     b = "#{File.basename(@dir)}.rb"
     files = Dir.glob(File.join(@dir, '*.rb')).map { |f| File.basename(f) }
@@ -87,7 +104,12 @@ class Judges::Judge
     b
   end
 
-  # Return all .yml tests files.
+  # Returns all YAML test files in the judge directory.
+  #
+  # Test files are expected to have a .yml extension and contain test data
+  # used to validate the judge's behavior.
+  #
+  # @return [Array<String>] Array of absolute paths to all .yml files in the judge directory
   def tests
     Dir.glob(File.join(@dir, '*.yml'))
   end

data/lib/judges/judges.rb

@@ -42,19 +42,30 @@ class Judges::Judges
     @boost = boost
   end
 
-  # Get one judge by name.
-  # @param [String] name The name of the judge
-  # @return [Judge] The judge object
-  # @raise [RuntimeError] If judge doesn't exist
+  # Retrieves a specific judge by its name.
+  #
+  # The judge must exist as a directory within the judges directory with the given name.
+  #
+  # @param [String] name The name of the judge to retrieve (directory name)
+  # @return [Judges::Judge] The judge object initialized with the found directory
+  # @raise [RuntimeError] If no judge directory exists with the given name
   def get(name)
     d = File.absolute_path(File.join(@dir, name))
     raise "Judge #{name} doesn't exist in #{@dir}" unless File.exist?(d)
     Judges::Judge.new(d, @lib, @loog, start: @start)
   end
 
-  # Iterate over all judges.
-  # @yield [Judge] Yields each judge
-  # @return [Enumerator] If no block given
+  # Iterates over all valid judges in the directory.
+  #
+  # This method discovers all judge directories, validates them (ensuring they contain
+  # a corresponding .rb file), and yields them in a specific order. The order is
+  # determined by:
+  # 1. Judges whose names match the boost list are placed first
+  # 2. Judges whose names start with the shuffle prefix are randomly reordered
+  # 3. All other judges maintain their alphabetical order
+  #
+  # @yield [Judges::Judge] Yields each valid judge object
+  # @return [Enumerator] Returns an enumerator if no block is given
   def each(&)
     return to_enum(__method__) unless block_given?
     list =
@@ -87,9 +98,14 @@ class Judges::Judges
     ret.each(&)
   end
 
-  # Iterate over all judges with index.
-  # @yield [Judge, Integer] Yields each judge with its index
-  # @return [Integer] The total count of judges
+  # Iterates over all judges while tracking their index position.
+  #
+  # This method calls the #each method and additionally provides a zero-based
+  # index for each judge yielded. The judges are processed in the same order
+  # as determined by the #each method (with boost and shuffle rules applied).
+  #
+  # @yield [Judges::Judge, Integer] Yields each judge object along with its index (starting from 0)
+  # @return [Integer] The total count of judges processed
   def each_with_index
     idx = 0
     each do |p|

data/lib/judges/options.rb

@@ -7,25 +7,62 @@ require 'others'
 require_relative '../judges'
 
 # Options for Ruby scripts in the judges.
+#
+# This class manages configuration options that can be passed to judge scripts.
+# Options are key-value pairs that can be provided in various formats and are
+# normalized into a hash with symbol keys. Values are automatically converted
+# to appropriate types (integers for numeric strings, etc.).
+#
+# The class also provides dynamic method access to options using the 'others' gem,
+# allowing options to be accessed as method calls.
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Judges::Options
-  # Ctor.
-  # @param [Array<String>] pairs List of pairs, like ["token=af73cd3", "max_speed=1"]
+  # Initialize a new Options instance.
+  #
+  # @param [Array<String>, String, Hash, nil] pairs List of key-value pairs.
+  #   Can be provided as:
+  #   - Array of strings: ["token=af73cd3", "max_speed=1"]
+  #   - Comma-separated string: "token=af73cd3,max_speed=1"
+  #   - Hash: { token: "af73cd3", max_speed: 1 }
+  #   - nil: Creates empty options
+  # @example Initialize with array
+  #   options = Judges::Options.new(["token=abc123", "debug=true"])
+  # @example Initialize with string
+  #   options = Judges::Options.new("token=abc123,debug")
+  # @example Initialize with hash
+  #   options = Judges::Options.new({ token: "abc123", debug: true })
   def initialize(pairs = nil)
     @pairs = pairs
   end
 
   # Check if options are empty.
-  # @return [Boolean] true if no options are set
+  #
+  # @return [Boolean] true if no options are set, false otherwise
+  # @example Check if options are empty
+  #   options = Judges::Options.new
+  #   options.empty? # => true
+  #   options = Judges::Options.new(["key=value"])
+  #   options.empty? # => false
   def empty?
     to_h.empty?
   end
 
   # Merge with another Options object.
+  #
+  # Creates a new Options instance containing values from both this instance
+  # and the other. Values from the other Options object override values
+  # with the same key in this instance.
+  #
   # @param [Judges::Options] other The other options to merge
   # @return [Judges::Options] A new Options object with merged values
+  # @example Merge two Options objects
+  #   opts1 = Judges::Options.new(["token=abc", "debug=true"])
+  #   opts2 = Judges::Options.new(["token=xyz", "verbose=true"])
+  #   merged = opts1 + opts2
+  #   # merged now has token=xyz, debug=true, verbose=true
   def +(other)
     h = to_h
     other.to_h.each do |k, v|
@@ -34,7 +71,19 @@ class Judges::Options
     Judges::Options.new(h)
   end
 
-  # Convert them all to a string (printable in a log).
+  # Convert options to a string representation.
+  #
+  # Creates a human-readable string representation of all options,
+  # suitable for logging. Sensitive values (longer than 8 characters)
+  # are partially masked with asterisks for security.
+  #
+  # @return [String] Formatted string with each option on a new line
+  # @example Convert to string
+  #   options = Judges::Options.new(["token=supersecrettoken", "debug=true"])
+  #   puts options.to_s
+  #   # Output:
+  #   # debug → "true"
+  #   # token → "supe****oken"
   def to_s
     to_h.map do |k, v|
       v = v.to_s
@@ -44,7 +93,18 @@ class Judges::Options
   end
 
   # Convert options to hash.
+  #
+  # Converts the raw pairs into a normalized hash with the following transformations:
+  # - Keys are converted to uppercase symbols
+  # - Values without equals sign get 'true' as value
+  # - Numeric strings are converted to integers
+  # - Leading/trailing whitespace is stripped
+  # - Empty or nil keys are rejected
+  #
   # @return [Hash] The options as a hash with symbol keys
+  # @example Convert to hash
+  #   options = Judges::Options.new("token=abc123,max_speed=100,debug")
+  #   options.to_h # => { TOKEN: "abc123", MAX_SPEED: 100, DEBUG: "true" }
   def to_h
     @to_h ||=
       begin
@@ -72,6 +132,19 @@ class Judges::Options
   end
 
   # Get option by name.
+  #
+  # This method is implemented using the 'others' gem, which provides
+  # dynamic method handling. It allows accessing options as method calls.
+  # Method names are automatically converted to uppercase symbols to match
+  # the keys in the options hash.
+  #
+  # @param [Symbol, String] method_name The option name to retrieve
+  # @return [Object, nil] The value of the option, or nil if not found
+  # @example Access options as methods
+  #   options = Judges::Options.new(["token=abc123", "max_speed=100"])
+  #   options.token # => "abc123"
+  #   options.max_speed # => 100
+  #   options.missing_option # => nil
   others do |*args|
     to_h[args[0].upcase.to_sym]
   end

data/lib/judges.rb

@@ -8,5 +8,5 @@
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Judges
-  VERSION = '0.44.0' unless const_defined?(:VERSION)
+  VERSION = '0.44.1' unless const_defined?(:VERSION)
 end

data/test/commands/test_update.rb

@@ -157,6 +157,21 @@ class TestUpdate < Minitest::Test
     end
   end
 
+  def test_isolates_churns
+    Dir.mktmpdir do |d|
+      save_it(File.join(d, 'first/first.rb'), '$global[:fb] ||= $fb; 2 + 2')
+      save_it(File.join(d, 'second/second.rb'), '$global[:fb] ||= $fb; $global[:fb].insert')
+      file = File.join(d, 'base.fb')
+      Judges::Update.new(Loog::VERBOSE).run(
+        { 'max-cycles' => 3, 'boost' => 'first' },
+        [d, file]
+      )
+      fb = Factbase.new
+      fb.import(File.binread(file))
+      assert_equal(3, fb.size)
+    end
+  end
+
   def test_fails_when_no_judges_used
     assert_raises(StandardError) do
       Dir.mktmpdir do |d|

data/test/test_judge.rb

@@ -25,6 +25,30 @@ class TestJudge < Minitest::Test
     end
   end
 
+  def test_counts_churn
+    Dir.mktmpdir do |d|
+      save_it(File.join(d, "#{File.basename(d)}.rb"), '$fb.insert.foo = 42')
+      judge = Judges::Judge.new(d, nil, Loog::NULL)
+      fb = Factbase.new
+      c = judge.run(fb, {}, {}, {})
+      assert_equal(1, c.inserted)
+      assert_equal(0, c.deleted)
+      assert_equal(1, c.added)
+    end
+  end
+
+  def test_counts_churn_after_txn
+    Dir.mktmpdir do |d|
+      save_it(File.join(d, "#{File.basename(d)}.rb"), '$fb.txn { |fbt| fbt.insert.foo = 42 }')
+      judge = Judges::Judge.new(d, nil, Loog::NULL)
+      fb = Factbase.new
+      c = judge.run(fb, {}, {}, {})
+      assert_equal(1, c.inserted)
+      assert_equal(0, c.deleted)
+      assert_equal(1, c.added)
+    end
+  end
+
   def test_run_isolated
     Dir.mktmpdir do |d|
       save_it(File.join(d, "#{File.basename(d)}.rb"), '$fb.insert')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: judges
 version: !ruby/object:Gem::Version
-  version: 0.44.0
+  version: 0.44.1
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -286,6 +286,7 @@ files:
 - features/test.feature
 - features/trim.feature
 - features/update.feature
+- features/version.feature
 - fixtures/guess/guess.rb
 - fixtures/guess/guess_made.yml
 - fixtures/guess/skipped.yml