judges 0.42.0 → 0.43.0

data/lib/judges/commands/push.rb

@@ -19,13 +19,16 @@ require_relative '../../judges/impex'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Judges::Push
+  # Initialize.
+  # @param [Loog] loog Logging facility
   def initialize(loog)
     @loog = loog
   end
 
-  # Run it (it is supposed to be called by the +bin/judges+ script.
+  # Run the push command (called by the +bin/judges+ script).
   # @param [Hash] opts Command line options (start with '--')
   # @param [Array] args List of command line arguments
+  # @raise [RuntimeError] If not exactly two arguments provided
   def run(opts, args)
     raise 'Exactly two arguments required' unless args.size == 2
     name = args[0]
@@ -42,7 +45,7 @@ class Judges::Push
       baza.lock(name, opts['owner'])
       begin
         id = baza.push(name, fb.export, opts['meta'] || [])
-        throw :"Pushed #{fb.size} facts, job ID is #{id}"
+        throw :"👍 Pushed #{fb.size} facts, job ID is #{id}"
       ensure
         baza.unlock(name, opts['owner'])
       end

data/lib/judges/commands/test.rb

@@ -23,13 +23,16 @@ require_relative '../../judges/categories'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Judges::Test
+  # Initialize.
+  # @param [Loog] loog Logging facility
   def initialize(loog)
     @loog = loog
   end
 
-  # Run it (it is supposed to be called by the +bin/judges+ script.
+  # Run the test command (called by the +bin/judges+ script).
   # @param [Hash] opts Command line options (start with '--')
   # @param [Array] args List of command line arguments
+  # @raise [RuntimeError] If not exactly one argument provided
   def run(opts, args)
     raise 'Exactly one argument required' unless args.size == 1
     dir = args[0]
@@ -51,11 +54,11 @@ class Judges::Test
           next unless include?(opts, judge.name, tname)
           yaml = YAML.load_file(f, permitted_classes: [Time])
           if yaml['skip']
-            @loog.info("Skippped #{f.to_rel}")
+            @loog.info("Skipped #{f.to_rel}")
             next
           end
           unless Judges::Categories.new(opts['enable'], opts['disable']).ok?(yaml['category'])
-            @loog.info("Skippped #{f.to_rel} because of its category")
+            @loog.info("Skipped #{f.to_rel} because of its category")
             next
           end
           @loog.info("🛠️ Testing #{f.to_rel}:")
@@ -122,8 +125,8 @@ class Judges::Test
   def include?(opts, name, tname = nil)
     judges = opts['judge'] || []
     return true if judges.empty?
-    tre = tname.nil? ? '.+' : tname
-    judges.any? { |n| n.match?(%r{^#{name}(/#{tre})?$}) }
+    re = tname.nil? ? '.+' : tname
+    judges.any? { |n| n.match?(%r{^#{name}(/#{re})?$}) }
   end
 
   def prepare(fb, yaml)

data/lib/judges/commands/trim.rb

@@ -17,22 +17,25 @@ require_relative '../../judges/impex'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Judges::Trim
+  # Initialize.
+  # @param [Loog] loog Logging facility
   def initialize(loog)
     @loog = loog
   end
 
-  # Run it (it is supposed to be called by the +bin/judges+ script.
+  # Run the trim command (called by the +bin/judges+ script).
   # @param [Hash] opts Command line options (start with '--')
   # @param [Array] args List of command line arguments
+  # @raise [RuntimeError] If not exactly one argument provided
   def run(opts, args)
     raise 'Exactly one argument required' unless args.size == 1
     impex = Judges::Impex.new(@loog, args[0])
     fb = impex.import
     elapsed(@loog, level: Logger::INFO) do
       deleted = fb.query(opts['query']).delete!
-      throw :'No facts deleted' if deleted.zero?
+      throw :'⚠️ No facts deleted' if deleted.zero?
       impex.export(fb)
-      throw :"🗑 #{deleted} fact(s) deleted"
+      throw :"👍 #{deleted} fact(s) deleted"
     end
   end
 end

data/lib/judges/commands/update.rb

@@ -26,15 +26,17 @@ require_relative '../../judges/to_rel'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Judges::Update
+  # Initialize.
+  # @param [Loog] loog Logging facility
   def initialize(loog)
     @loog = loog
     @start = Time.now
   end
 
-  # Run it (it is supposed to be called by the +bin/judges+ script.
-  #
+  # Run the update command (called by the +bin/judges+ script).
   # @param [Hash] opts Command line options (start with '--')
   # @param [Array] args List of command line arguments
+  # @raise [RuntimeError] If not exactly two arguments provided or directory is missing
   def run(opts, args)
     raise 'Exactly two arguments required' unless args.size == 2
     dir = args[0]
@@ -79,9 +81,13 @@ class Judges::Update
           @loog.info("Too many cycles already, as set by --max-cycles=#{opts['max-cycles']}, breaking")
           break
         end
+        if opts['fail-fast'] && !errors.empty?
+          @loog.info("Due to #{errors.count} errors we must stop at the update cycle ##{c}")
+          break
+        end
         @loog.info("The cycle #{c} did #{delta}")
       end
-      throw :"Update finished in #{c} cycle(s), did #{churn}"
+      throw :"👍 Update completed in #{c} cycle(s), did #{churn}"
     end
     return unless opts['summary']
     summarize(fb, churn, errors, start, c)
@@ -94,7 +100,7 @@ class Judges::Update
   # @param [Factbase] fb The factbase
   # @param [Churn] churn The churn
   # @param [Array<String>] errors List of errors
-  # @param [Time] start Whe we started
+  # @param [Time] start When we started
   # @param [Integer] cycles How many cycles
   def summarize(fb, churn, errors, start, cycles)
     before = fb.query('(eq what "judges-summary")').each.to_a
@@ -142,6 +148,10 @@ class Judges::Update
     elapsed(@loog, level: Logger::INFO) do
       done =
         judges.each_with_index do |judge, i|
+          if opts['fail-fast'] && !errors.empty?
+            @loog.info("Not running #{judge.name.inspect} due to #{errors.count} errors above, in --fail-fast mode")
+            next
+          end
           next unless include?(opts, judge.name)
           @loog.info("\n👉 Running #{judge.name} (##{i}) at #{judge.dir.to_rel} (#{start.ago} already)...")
           elapsed(@loog, level: Logger::INFO) do

data/lib/judges/impex.rb

@@ -14,11 +14,17 @@ require_relative '../judges/to_rel'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Judges::Impex
+  # Initialize.
+  # @param [Loog] loog Logging facility
+  # @param [String] file File path for import/export operations
   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
   def import(strict: true)
     fb = Factbase.new
     if File.exist?(@file)
@@ -33,6 +39,9 @@ class Judges::Impex
     fb
   end
 
+  # Import factbase from file into existing factbase.
+  # @param [Factbase] fb The factbase to import into
+  # @raise [RuntimeError] If file doesn't exist
   def import_to(fb)
     raise "The factbase is absent at #{@file.to_rel}" unless File.exist?(@file)
     elapsed(@loog, level: Logger::INFO) do
@@ -41,6 +50,8 @@ class Judges::Impex
     end
   end
 
+  # Export factbase to file.
+  # @param [Factbase] fb The factbase to export
   def export(fb)
     elapsed(@loog, level: Logger::INFO) do
       FileUtils.mkdir_p(File.dirname(@file))

data/lib/judges/judge.rb

@@ -59,7 +59,7 @@ class Judges::Judge
     end
     s = File.join(@dir, script)
     raise "Can't load '#{s}'" unless File.exist?(s)
-    elapsed(@loog, intro: "#{$judge} finished", level: Logger::INFO) do
+    elapsed(@loog, intro: "#{$judge} completed", level: Logger::INFO) do
       load(s, true)
       $fb.churn
       # rubocop:disable Lint/RescueException

data/lib/judges/judges.rb

@@ -26,6 +26,13 @@ require_relative 'judge'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Judges::Judges
+  # Initialize.
+  # @param [String] dir Directory containing judges
+  # @param [String] lib Library directory
+  # @param [Loog] loog Logging facility
+  # @param [Time] start Start time
+  # @param [String] shuffle Prefix for names of judges to shuffle
+  # @param [Array<String>] boost Names of judges to boost in priority
   def initialize(dir, lib, loog, start: Time.now, shuffle: '', boost: [])
     @dir = dir
     @lib = lib
@@ -36,15 +43,18 @@ class Judges::Judges
   end
 
   # Get one judge by name.
-  # @return [Judge]
+  # @param [String] name The name of the judge
+  # @return [Judge] The judge object
+  # @raise [RuntimeError] If judge doesn't exist
   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 them all.
-  # @yield [Judge]
+  # Iterate over all judges.
+  # @yield [Judge] Yields each judge
+  # @return [Enumerator] If no block given
   def each(&)
     return to_enum(__method__) unless block_given?
     list =
@@ -77,8 +87,9 @@ class Judges::Judges
     ret.each(&)
   end
 
-  # Iterate over them all, with an index.
-  # @yield [(Judge, Integer)]
+  # Iterate over all judges with index.
+  # @yield [Judge, Integer] Yields each judge with its index
+  # @return [Integer] The total count of judges
   def each_with_index
     idx = 0
     each do |p|

data/lib/judges/options.rb

@@ -17,10 +17,15 @@ class Judges::Options
     @pairs = pairs
   end
 
+  # Check if options are empty.
+  # @return [Boolean] true if no options are set
   def empty?
     to_h.empty?
   end
 
+  # Merge with another Options object.
+  # @param [Judges::Options] other The other options to merge
+  # @return [Judges::Options] A new Options object with merged values
   def +(other)
     h = to_h
     other.to_h.each do |k, v|
@@ -38,6 +43,8 @@ class Judges::Options
     end.sort.join("\n")
   end
 
+  # Convert options to hash.
+  # @return [Hash] The options as a hash with symbol keys
   def to_h
     @to_h ||=
       begin

data/lib/judges/to_rel.rb

@@ -11,6 +11,7 @@ require 'pathname'
 # License:: MIT
 class Object
   # Generates a relative name of a file (to the current dir).
+  # @return [String] Relative path to the file with optional quotes if it contains spaces
   def to_rel
     s = File.absolute_path(to_s)
     p = Pathname.new(s).relative_path_from(Dir.getwd)

data/lib/judges.rb

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