judges 0.56.0 → 0.57.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1bce8cfaa9c1567d94332da48e35b303ec5b963198d72a82bf69164cbd1928d
-  data.tar.gz: 467ab5d5bab974f97be24720c3e44f15d353c38f2ecf553648431facb603864f
+  metadata.gz: 99e0f160f5dfa27ca34a0e3869bbc26d7f7ee4c7bb25beca1197e4e2dd462e68
+  data.tar.gz: 923b096bf564c2c2e03ae4ad1697df5c8b7331f211246fef0f2b1fffb28b8333
 SHA512:
-  metadata.gz: dfd3eb005e029e442b5c924620a897df19c974599122e6ae20f0369718f02b8b6171b852e32d408c5a27c766dac92260ad59e4420e14c5d8ccdcc5c8b4ca38b5
-  data.tar.gz: 66fbdd630846645475cab1daa36b326d92e37eeb08cf41c176b1a710e93d25acc3565b8bd4c43f6905e0bdb2752ac03dc609d6d5152e93b08b993b34463be0b2
+  metadata.gz: 9bae673902b779709eb86dbc939fc234baabc546a08b953a2e5f9c7006467ad5279c0bc59268c7b240d60da93f6e5aca28adbe3774748a8b08eaa2d499b8c7e7
+  data.tar.gz: 38fbbd8411637b54b6515e96599e91924a82ea63599315a9d166a26d6aeff4aa65c0be86eb09fb39b8ce4de2494c6bf09d7af9baa6abd97f4ba32c7da452468f

data/bin/judges

@@ -27,6 +27,7 @@ class JudgesGLI extend GLI::App
       require_relative "../lib/judges/commands/#{ruby}"
       start = Time.now
       @@loog.debug("Running '#{ruby}' command...")
+      options = global.merge(options)
       begin
         Object.const_get("Judges::#{ruby.capitalize}").new(@@loog).run(options, args)
         @@loog.debug("Command '#{ruby}' completed in #{start.ago}")
@@ -135,6 +136,8 @@ class JudgesGLI extend GLI::App
     c.flag([:summary], must_match: %w[off add append], default_value: 'off')
     c.desc 'Use default logging facility'
     c.switch([:log], default_value: true)
+    c.desc 'Show execution statistics for each judge'
+    c.switch([:statistics], default_value: false)
     c.desc 'Expect at least one judge to be used (fail if none are used)'
     c.switch([:'expect-judges'], default_value: true)
     run_it(c, 'update')

data/features/print.feature

@@ -18,6 +18,14 @@ Feature: Print
     Then Stdout contains "printed"
     And Exit code is zero
 
+  Scenario: Simple print of a small factbase, to HTML, in offline mode
+    Given I make a temp directory
+    Then I run bin/judges with "--verbose eval simple.fb '$fb.insert.foo = 42'"
+    Then I run bin/judges with "--offline print --format=html simple.fb simple.html"
+    Then Stdout contains "printed"
+    Then simple.html contains "sha256-offline"
+    And Exit code is zero
+
   Scenario: Simple print of a small factbase, to JSON
     Given I make a temp directory
     Then I run bin/judges with "--verbose eval simple.fb '$fb.insert.foo = 42'"

data/features/step_definitions/steps.rb

@@ -56,6 +56,11 @@ When(/^I run bash with:$/) do |text|
   @exitstatus = $CHILD_STATUS.exitstatus
 end
 
+Then(/^([a-z].+) contains "([^"]*)"$/) do |file, txt|
+  data = File.read(file)
+  raise "The file #{file} doesn't contain '#{txt}':\n#{data}" unless data.include?(txt)
+end
+
 Then(/^Stdout contains "([^"]*)"$/) do |txt|
   raise "STDOUT doesn't contain '#{txt}':\n#{@stdout}" unless @stdout.include?(txt)
 end

data/features/update.feature

@@ -62,7 +62,7 @@ Feature: Update
       n = $fb.insert
       n.type = 'second'
     """
-    Then I run bin/judges with "--verbose update --quiet --lifetime 4 --timeout 3 --max-cycles 5 . simple.fb"
+    Then I run bin/judges with "--verbose update --quiet --lifetime 4 --timeout 3 --max-cycles 5 --shuffle 'first' . simple.fb"
     Then Stdout contains "Update completed in 2 cycle(s), did 3i/0d/3a"
     And Exit code is zero
 
@@ -214,3 +214,44 @@ Feature: Update
     Then Stdout contains "Running delayed"
     Then Stdout contains "3 judge(s) processed"
     And Exit code is zero
+
+  Scenario: Show statistics for judge execution
+    Given I make a temp directory
+    Then I have a "alpha/alpha.rb" file with content:
+    """
+      $fb.insert.name = 'alpha'
+    """
+    Then I have a "beta/beta.rb" file with content:
+    """
+      $fb.insert.name = 'beta'
+    """
+    Then I run bin/judges with "update --statistics --quiet --max-cycles 1 . stats.fb"
+    Then Stdout contains "Judge execution summary:"
+    Then Stdout contains "Judge"
+    Then Stdout contains "Seconds"
+    Then Stdout contains "Changes"
+    Then Stdout contains "Cycles"
+    Then Stdout contains "Result"
+    Then Stdout contains "alpha"
+    Then Stdout contains "beta"
+    Then Stdout contains "OK"
+    And Exit code is zero
+
+  Scenario: Summarize results in statistics
+    Given I make a temp directory
+    Then I have a "alpha/alpha.rb" file with content:
+    """
+      $fb.insert.name = 'alpha'
+      sleep 1.91
+    """
+    Then I have a "beta/beta.rb" file with content:
+    """
+      $fb.insert.name = 'beta'
+    """
+    Then I run bin/judges with "update --statistics --quiet --max-cycles 2 --lifetime 4 --timeout 3 --shuffle 'alpha' . stats.fb"
+    Then Stdout contains "Judge execution summary:"
+    Then Stdout contains "alpha"
+    Then Stdout contains "beta"
+    Then Stdout contains "1xOK"
+    Then Stdout contains "1xSKIPPED (timeout)"
+    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.56.0'
+  s.version = '0.57.1'
   s.license = 'MIT'
   s.summary = 'Command-Line Tool for a Factbase'
   s.description =

data/lib/judges/commands/update.rb

@@ -16,6 +16,7 @@ require_relative '../../judges'
 require_relative '../../judges/impex'
 require_relative '../../judges/judges'
 require_relative '../../judges/options'
+require_relative '../../judges/statistics'
 require_relative '../../judges/to_rel'
 
 # The +update+ command.
@@ -88,6 +89,7 @@ class Judges::Update
     c = 0
     churn = Factbase::Churn.new
     errors = []
+    statistics = opts['statistics'] ? Judges::Statistics.new : nil
     sum = fb.query('(eq what "judges-summary")').each.to_a
     if sum.empty?
       @loog.info('Summary fact not found') unless opts['summary'] == 'off'
@@ -108,7 +110,7 @@ class Judges::Update
           end
           @loog.info("\nStarting cycle ##{c}#{" (out of #{opts['max-cycles']})" if opts['max-cycles']}...")
         end
-        delta = cycle(opts, judges, fb, options, errors)
+        delta = cycle(opts, judges, fb, options, errors, statistics)
         churn += delta
         impex.export(fb)
         if delta.zero?
@@ -127,6 +129,7 @@ class Judges::Update
       end
       throw :"👍 Update completed in #{c} cycle(s), did #{churn}"
     end
+    statistics&.report(@loog)
     return unless %w[add append].include?(opts['summary'])
     summarize(fb, churn, errors, c)
     impex.export(fb)
@@ -172,9 +175,10 @@ class Judges::Update
   # @param [Factbase] fb The factbase
   # @param [Judges::Options] options The options
   # @param [Array<String>] errors List of errors
+  # @param [Judges::Statistics] statistics Statistics tracking object (optional)
   # @return [Factbase::Churn] How many modifications have been made
-  def cycle(opts, judges, fb, options, errors)
-    churn = Factbase::Churn.new
+  def cycle(opts, judges, fb, options, errors, statistics = nil)
+    delta = Factbase::Churn.new
     global = {}
     used = 0
     elapsed(@loog, level: Logger::INFO) do
@@ -182,27 +186,35 @@ class Judges::Update
         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")
+            statistics&.record(judge.name, 0, 'SKIPPED (fail-fast)') if include?(opts, judge.name)
             next
           end
           if opts['lifetime'] && opts['timeout']
             remained = @start + opts['lifetime'] - Time.now
             if remained < opts['timeout'].to_f / 16
               @loog.info("Not running #{judge.name.inspect}, not enough time left (just #{remained.seconds})")
+              statistics&.record(judge.name, 0, 'SKIPPED (timeout)') if include?(opts, judge.name)
               next
             end
           end
           next unless include?(opts, judge.name)
           @loog.info("\n👉 Running #{judge.name} (##{i}) at #{judge.dir.to_rel} (#{@start.ago} already)...")
           used += 1
+          start_time = Time.now
+          result = 'OK'
+          impact = nil
           elapsed(@loog, level: Logger::INFO) do
-            c = one_judge(opts, fb, judge, global, options, errors)
-            churn += c
-            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"
+            impact = one_judge(opts, fb, judge, global, options, errors)
+            delta += impact
+            throw :"👍 The '#{judge.name}' judge made zero changes to #{fb.size} facts" if impact.zero?
+            throw :"👍 The '#{judge.name}' judge #{impact} out of #{fb.size} facts"
           end
         rescue StandardError, SyntaxError => e
           @loog.warn(Backtrace.new(e))
           errors << e.message
+          result = 'ERROR'
+        ensure
+          statistics&.record(judge.name, Time.now - start_time, result, impact) if start_time
         end
       throw :"👍 #{done} judge(s) processed" if errors.empty?
       throw :"❌ #{done} judge(s) processed with #{errors.size} errors"
@@ -215,7 +227,7 @@ class Judges::Update
       raise "Failed to update correctly (#{errors.size} errors)" unless opts['quiet']
       @loog.info('Not failing because of the --quiet flag provided')
     end
-    churn
+    delta
   end
 
   # Run a single judge.

data/lib/judges/judges.rb

@@ -62,10 +62,10 @@ class Judges::Judges
   # 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
+  # 1. Randomly reorder judges (if shuffle prefix is empty, shuffle all judges;
+  #    if prefix is not empty, shuffle only those NOT starting with the prefix)
+  # 2. Judges whose names match the boost list are placed first
   # 3. Judges whose names match the demote list are placed last
-  # 4. 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
@@ -84,7 +84,7 @@ class Judges::Judges
     good = all.dup
     mapping = all
       .map { |a| [a[0].name, a[1], a[1]] }
-      .reject { |a| a[0].start_with?(@shuffle) }
+      .reject { |a| !@shuffle.empty? && a[0].start_with?(@shuffle) }
       .to_h { |a| [a[1], a[2]] }
     positions = mapping.values.shuffle
     mapping.keys.zip(positions).to_h.each do |before, after|

data/lib/judges/statistics.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../judges'
+
+# Statistics collector for judge executions.
+#
+# This class collects and aggregates statistics about judge executions
+# across multiple cycles, providing insights into performance and results.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class Judges::Statistics
+  # Initialize empty statistics.
+  def initialize
+    @data = {}
+  end
+
+  # Check if statistics are empty.
+  # @return [Boolean] True if no statistics have been collected
+  def empty?
+    @data.empty?
+  end
+
+  # Record statistics for a judge execution.
+  # @param [String] name The judge name
+  # @param [Float] time The execution time for this run
+  # @param [String] result The result for this run
+  # @param [Churn] churn The churn for this run (can be nil)
+  def record(name, time, result, churn = nil)
+    unless @data[name]
+      @data[name] = {
+        total_time: 0.0,
+        cycles: 0,
+        results: [],
+        total_churn: nil
+      }
+    end
+    stats = @data[name]
+    stats[:total_time] += time
+    stats[:cycles] += 1
+    stats[:results] << result
+    return unless churn
+    if stats[:total_churn]
+      stats[:total_churn] += churn
+    else
+      stats[:total_churn] = churn
+    end
+  end
+
+  # Generate a formatted statistics report.
+  # @param [Loog] loog Logging facility for output
+  def report(loog)
+    return if empty?
+    fmt = "%-30s\t%9s\t%7s\t%15s\t%-15s"
+    loog.info(
+      [
+        'Judge execution summary:',
+        format(fmt, 'Judge', 'Seconds', 'Cycles', 'Changes', 'Results'),
+        format(fmt, '---', '---', '---', '---', '---'),
+        @data.sort_by { |_, stats| stats[:total_time] }.reverse.map do |name, stats|
+          format(fmt, name, format('%.3f', stats[:total_time]), stats[:cycles],
+                 stats[:total_churn] ? stats[:total_churn].to_s : 'N/A', summarize(stats[:results]))
+        end.join("\n  ")
+      ].join("\n  ")
+    )
+  end
+
+  private
+
+  # Summarize results across multiple cycles into a compact string.
+  # @param [Array<String>] results Array of result strings from different cycles
+  # @return [String] Compact summary of results
+  def summarize(results)
+    return 'N/A' if results.empty?
+    counts = results.each_with_object(Hash.new(0)) { |result, hash| hash[result] += 1 }
+    return results.first if counts.size == 1
+    counts.sort_by { |_, count| -count }.map { |result, count| "#{count}x#{result}" }.join(', ')
+  end
+end

data/lib/judges.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: judges
 version: !ruby/object:Gem::Version
-  version: 0.56.0
+  version: 0.57.1
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -298,6 +298,7 @@ files:
 - lib/judges/judge.rb
 - lib/judges/judges.rb
 - lib/judges/options.rb
+- lib/judges/statistics.rb
 - lib/judges/to_rel.rb
 - package-lock.json
 - package.json