judges 0.56.0 → 0.57.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1bce8cfaa9c1567d94332da48e35b303ec5b963198d72a82bf69164cbd1928d
-  data.tar.gz: 467ab5d5bab974f97be24720c3e44f15d353c38f2ecf553648431facb603864f
+  metadata.gz: 25236f211b356d3dfe62fd6ba9eb7eb70a04e2de64d2581d682db989967cefa9
+  data.tar.gz: c804cf366c81db1834496d71852422dbb245edfc76f0a24511621a4aa7979ada
 SHA512:
-  metadata.gz: dfd3eb005e029e442b5c924620a897df19c974599122e6ae20f0369718f02b8b6171b852e32d408c5a27c766dac92260ad59e4420e14c5d8ccdcc5c8b4ca38b5
-  data.tar.gz: 66fbdd630846645475cab1daa36b326d92e37eeb08cf41c176b1a710e93d25acc3565b8bd4c43f6905e0bdb2752ac03dc609d6d5152e93b08b993b34463be0b2
+  metadata.gz: 1c33f8ae0312222d0ae2ec848d031648fc5f04cb2a64d49e63a26176157a2d9e82bb2fa1f8e010aa0fe8a482fe16690145bdca92f367f05afa851687a18f09af
+  data.tar.gz: 6bfafca7127eca496160d7b57325e92815ced1872da8f929380aa0fee185d5f3931cdf5eb753d39a3c68c9c19800a2cfa100b99da60288d9dbae33ccb9680309

data/bin/judges

@@ -135,6 +135,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/update.feature

@@ -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 . 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.0'
   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/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.0' 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.0
 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