fbe 0.14.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c645873d437ec40589dca8b3bd3789b3dd859d5c5b365e25dae38b82bd4d5feb
-  data.tar.gz: d586ef4096f29632302503f72f24f39511567760e179b0ca4373626b8541eb8e
+  metadata.gz: db8d48febaa0fde74386158a1487da848c28058c4fadf85838b110105d70ada8
+  data.tar.gz: 46eec95f52085235848a464c2770887e5336f7b818644e61955fa3fbb026e84c
 SHA512:
-  metadata.gz: a52fb8eaeab99279664d91e6b1bb50492f40f4c2583937c64e412822f84428863caaf6a33f330dc7706d1c0aad809761337b0a241163d4f914235b66c3fb59fc
-  data.tar.gz: 88d9ddc164b53f357515b223a69ac9622f1860258ff36fa94ce2ff6d7b3b6f996c81f495734c41f9a3fd5f5581bbf8085358a06c516f50b0466d7a2abe7eea7f
+  metadata.gz: 90435fd9b0555636891b524d69835835096b69e3673ed21fe9a49ee2a5b8792040bbdad2fa303f05f7a86c0cc06e35c595b7968ce32e8a7c32e6a94d5f839c9e
+  data.tar.gz: ca87fd6888148a43e582ab14cc110189aa741bad4e57c44aca4755db004de9bbef539e3b245dfe7330461b74eb39545f005a632eb0c8ae5ed7801c84f9b2b980

data/.github/workflows/copyrights.yml

@@ -12,4 +12,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.12

data/Gemfile.lock

@@ -110,7 +110,7 @@ GEM
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     iri (0.10.0)
-    json (2.12.0)
+    json (2.12.2)
     judges (0.42.1)
       backtrace (~> 0)
       baza.rb (~> 0)
@@ -172,11 +172,11 @@ GEM
       tago (> 0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
+    rake (13.3.0)
     regexp_parser (2.10.0)
     retries (0.0.5)
     rexml (3.4.1)
-    rubocop (1.75.6)
+    rubocop (1.75.8)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -190,7 +190,7 @@ GEM
     rubocop-ast (1.44.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
-    rubocop-minitest (0.38.0)
+    rubocop-minitest (0.38.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)

data/lib/fbe/bylaws.rb

@@ -6,15 +6,35 @@
 require 'liquid'
 require_relative '../fbe'
 
-# Generates policies/bylaws.
+# Generates policies/bylaws from Liquid templates.
 #
 # Using the templates stored in the +assets/bylaws+ directory, this function
-# creates a hash, where keys are names and values are formulas of bylaws.
+# creates a hash where keys are bylaw names (derived from filenames) and values
+# are the rendered formulas. Templates can use three parameters to control
+# the strictness and generosity of the bylaws.
 #
-# @param [Integer] anger How strict must be the bylaws, giving punishments
-# @param [Integer] love How big should be the volume of rewards
-# @param [Integer] paranoia How much should be required to reward love
-# @return [Hash<String, String>] Names of bylaws and their formulas
+# @param [Integer] anger Strictness level for punishments (0-4, default: 2)
+#   - 0: Very lenient, minimal punishments
+#   - 2: Balanced approach (default)
+#   - 4: Very strict, maximum punishments
+# @param [Integer] love Generosity level for rewards (0-4, default: 2)
+#   - 0: Minimal rewards
+#   - 2: Balanced rewards (default)
+#   - 4: Maximum rewards
+# @param [Integer] paranoia Requirements threshold for rewards (1-4, default: 2)
+#   - 1: Easy to earn rewards
+#   - 2: Balanced requirements (default)
+#   - 4: Very difficult to earn rewards
+# @return [Hash<String, String>] Hash mapping bylaw names to their formulas
+# @raise [RuntimeError] If parameters are out of valid ranges
+# @example Generate balanced bylaws
+#   bylaws = Fbe.bylaws(anger: 2, love: 2, paranoia: 2)
+#   bylaws['bug-report-was-rewarded']
+#   # => "award { 2 * love * paranoia }"
+# @example Generate strict bylaws with minimal rewards
+#   bylaws = Fbe.bylaws(anger: 4, love: 1, paranoia: 3)
+#   bylaws['dud-was-punished']
+#   # => "award { -16 * anger }"
 def Fbe.bylaws(anger: 2, love: 2, paranoia: 2)
   raise "The 'anger' must be in the [0..4] interval: #{anger.inspect}" unless !anger.negative? && anger < 5
   raise "The 'love' must be in the [0..4] interval: #{love.inspect}" unless !love.negative? && love < 5

data/lib/fbe/copy.rb

@@ -9,12 +9,20 @@ require_relative 'fb'
 # Makes a copy of a fact, moving all properties to a new fact.
 #
 # All properties from the +source+ will be copied to the +target+, except those
-# listed in the +except+.
+# listed in the +except+ array. Only copies properties that don't already exist
+# in the target. Multi-valued properties are copied with all their values.
 #
-# @param [Factbase::Fact] source The source
-# @param [Factbase::Fact] target The target
-# @param [Array<String>] except List of properties to NOT copy
-# @return [Integer] How many properties were copied
+# @param [Factbase::Fact] source The source fact to copy from
+# @param [Factbase::Fact] target The target fact to copy to
+# @param [Array<String>] except List of property names to NOT copy (defaults to empty)
+# @return [Integer] The number of property values that were copied
+# @raise [RuntimeError] If source, target, or except is nil
+# @note Existing properties in target are preserved (not overwritten)
+# @example Copy all properties except timestamps
+#   source = fb.query('(eq type "user")').first
+#   target = fb.insert
+#   count = Fbe.copy(source, target, except: ['_time', '_id'])
+#   puts "Copied #{count} property values"
 def Fbe.copy(source, target, except: [])
   raise 'The source is nil' if source.nil?
   raise 'The target is nil' if target.nil?

data/lib/fbe/delete.rb

@@ -6,13 +6,22 @@
 require_relative '../fbe'
 require_relative 'fb'
 
-# Delete a few properties from the fact.
+# Delete properties from a fact by creating a new fact without them.
 #
-# @param [Factbase::Fact] source The source
-# @param [Array<String>] props List of properties to delete
-# @param [Factbase] fb The factbase
-# @param [String] id The unique ID of the fact
-# @return [Factbase::Fact] New fact
+# This method doesn't modify the original fact. Instead, it deletes the existing
+# fact from the factbase and creates a new one with all properties except those
+# specified for deletion.
+#
+# @param [Factbase::Fact] fact The fact to delete properties from (must have an ID)
+# @param [Array<String>] props List of property names to delete
+# @param [Factbase] fb The factbase to use (defaults to Fbe.fb)
+# @param [String] id The property name used as unique identifier (defaults to '_id')
+# @return [Factbase::Fact] New fact without the deleted properties
+# @raise [RuntimeError] If fact is nil, has no ID, or ID property doesn't exist
+# @example Delete multiple properties from a fact
+#   fact = fb.query('(eq type "user")').first
+#   new_fact = Fbe.delete(fact, 'age', 'city')
+#   # new_fact will have all properties except 'age' and 'city'
 def Fbe.delete(fact, *props, fb: Fbe.fb, id: '_id')
   raise 'The fact is nil' if fact.nil?
   i = fact[id]

data/lib/fbe/enter.rb

@@ -6,13 +6,25 @@
 require 'baza-rb'
 require_relative '../fbe'
 
-# Enter a new valve.
+# Enter a new valve in the Zerocracy system.
 #
-# @param [String] badge Unique badge of the valve
-# @param [String] why The reason
-# @param [Judges::Options] options The options coming from the +judges+ tool
-# @param [Loog] loog The logging facility
-# @return [String] Full name of the user
+# A valve is a checkpoint or gate in the processing pipeline. This method
+# records the entry into a valve with a reason, unless in testing mode.
+#
+# @param [String] badge Unique badge identifier for the valve
+# @param [String] why The reason for entering this valve
+# @param [Judges::Options] options The options from judges tool (uses $options if not provided)
+# @param [Loog] loog The logging facility (uses $loog if not provided)
+# @yield Block to execute within the valve context
+# @return [Object] The result of the yielded block
+# @raise [RuntimeError] If badge, why, or required globals are nil
+# @note Requires $options and $loog global variables to be set
+# @note In testing mode (options.testing != nil), bypasses valve recording
+# @example Enter a valve for processing
+#   Fbe.enter('payment-check', 'Validating payment data') do
+#     # Process payment validation
+#     validate_payment(data)
+#   end
 def Fbe.enter(badge, why, options: $options, loog: $loog, &)
   raise 'The badge is nil' if badge.nil?
   raise 'The why is nil' if why.nil?

data/lib/fbe/github_graph.rb

@@ -271,12 +271,34 @@ class Fbe::Graph
     end
   end
 
-  # Fake GitHub GraphQL client, for tests.
+  # Fake GitHub GraphQL client for testing.
+  #
+  # This class mocks the GraphQL client interface and returns predictable
+  # test data without making actual API calls. It's used when the application
+  # is in testing mode.
+  #
+  # @example Using the fake client in tests
+  #   fake = Fbe::Graph::Fake.new
+  #   result = fake.total_commits('owner', 'repo', 'main')
+  #   # => 1484 (always returns the same value)
   class Fake
+    # Executes a GraphQL query (mock implementation).
+    #
+    # @param [String] _query The GraphQL query (ignored)
+    # @return [Hash] Empty hash
     def query(_query)
       {}
     end
 
+    # Returns mock resolved conversation threads.
+    #
+    # @param [String] owner Repository owner
+    # @param [String] name Repository name
+    # @param [Integer] _number Pull request number (ignored)
+    # @return [Array<Hash>] Array of conversation threads
+    # @example
+    #   fake.resolved_conversations('zerocracy', 'baza', 42)
+    #   # => [conversation data for zerocracy_baza]
     def resolved_conversations(owner, name, _number)
       data = {
         zerocracy_baza: [
@@ -286,6 +308,14 @@ class Fbe::Graph
       data[:"#{owner}_#{name}"] || []
     end
 
+    # Returns mock issue and pull request counts.
+    #
+    # @param [String] _owner Repository owner (ignored)
+    # @param [String] _name Repository name (ignored)
+    # @return [Hash] Hash with 'issues' and 'pulls' counts
+    # @example
+    #   fake.total_issues_and_pulls('owner', 'repo')
+    #   # => {"issues"=>23, "pulls"=>19}
     def total_issues_and_pulls(_owner, _name)
       {
         'issues' => 23,
@@ -293,10 +323,23 @@ class Fbe::Graph
       }
     end
 
+    # Returns mock total commit count.
+    #
+    # @param [String] _owner Repository owner (ignored)
+    # @param [String] _name Repository name (ignored)
+    # @param [String] _branch Branch name (ignored)
+    # @return [Integer] Always returns 1484
     def total_commits(_owner, _name, _branch)
       1484
     end
 
+    # Returns mock issue type event data.
+    #
+    # @param [String] node_id The event node ID
+    # @return [Hash, nil] Event data for known IDs, nil otherwise
+    # @example
+    #   fake.issue_type_event('ITAE_examplevq862Ga8lzwAAAAQZanzv')
+    #   # => {'type'=>'IssueTypeAddedEvent', ...}
     def issue_type_event(node_id)
       case node_id
       when 'ITAE_examplevq862Ga8lzwAAAAQZanzv'
@@ -362,6 +405,10 @@ class Fbe::Graph
 
     private
 
+    # Generates mock conversation thread data.
+    #
+    # @param [String] id The conversation thread ID
+    # @return [Hash] Mock conversation data with comments
     def conversation(id)
       {
         'id' => id,

data/lib/fbe/if_absent.rb

@@ -8,28 +8,43 @@ require 'time'
 require_relative '../fbe'
 require_relative 'fb'
 
-# Injects a fact if it's absent in the factbase, otherwise (if it is already
-# there) returns NIL.
+# Injects a fact if it's absent in the factbase, otherwise returns nil.
+#
+# Checks if a fact with the same property values already exists. If not,
+# creates a new fact. System properties (_id, _time, _version) are excluded
+# from the uniqueness check.
 #
 # Here is what you do when you want to add a fact to the factbase, but
 # don't want to make a duplicate of an existing one:
 #
 #  require 'fbe/if_absent'
-#  n =
-#   Fbe.if_absent do |f|
-#     f.what = 'something'
-#     f.details = 'important'
-#   end
-#  return if n.nil?
-#  n.when = Time.now
+#  n = Fbe.if_absent do |f|
+#    f.what = 'something'
+#    f.details = 'important'
+#  end
+#  return if n.nil?  # Fact already existed
+#  n.when = Time.now # Add additional properties to the new fact
 #
 # This code will definitely create one fact with +what+ equals to +something+
 # and +details+ equals to +important+, while the +when+ will be equal to the
 # time of its first creation.
 #
-# @param [Factbase] fb The global factbase
-# @yield [Factbase::Fact] The fact just created
-# @return [nil|Factbase::Fact] Either +nil+ if it's already there or a new fact
+# @param [Factbase] fb The factbase to check and insert into (defaults to Fbe.fb)
+# @yield [Factbase::Fact] A proxy fact object to set properties on
+# @return [nil, Factbase::Fact] nil if fact exists, otherwise the newly created fact
+# @note String values are properly escaped in queries
+# @note Time values are converted to UTC ISO8601 format for comparison
+# @example Ensure unique user registration
+#   user = Fbe.if_absent do |f|
+#     f.type = 'user'
+#     f.email = 'john@example.com'
+#   end
+#   if user
+#     user.registered_at = Time.now
+#     puts "New user created"
+#   else
+#     puts "User already exists"
+#   end
 def Fbe.if_absent(fb: Fbe.fb)
   attrs = {}
   f =

data/lib/fbe/issue.rb

@@ -6,18 +6,27 @@
 require_relative '../fbe'
 require_relative 'octo'
 
-# Converts an ID of GitHub issue into a nicely formatted string.
+# Converts GitHub repository and issue IDs into a formatted issue reference.
 #
-# The function takes the +repository+ property of the provided +fact+,
-# goes to the GitHub API in order to find the full name of the repository,
-# and then creates a string with the full name of repository + issue, for
-# example +"zerocracy/fbe#42"+.
+# Takes the +repository+ and +issue+ properties from the provided +fact+,
+# queries the GitHub API to get the repository's full name, and formats it
+# as a standard GitHub issue reference (e.g., "zerocracy/fbe#42").
+# Results are cached globally to minimize API calls.
 #
-# @param [Factbase::Fact] fact The fact, where to get the ID of GitHub issue
-# @param [Judges::Options] options The options coming from the +judges+ tool
-# @param [Hash] global The hash for global caching
-# @param [Loog] loog The logging facility
-# @return [String] Textual representation of GitHub issue number
+# @param [Factbase::Fact] fact The fact containing repository and issue properties
+# @param [Judges::Options] options The options from judges tool (uses $options global)
+# @param [Hash] global The hash for global caching (uses $global)
+# @param [Loog] loog The logging facility (uses $loog global)
+# @return [String] Formatted issue reference (e.g., "owner/repo#123")
+# @raise [RuntimeError] If fact is nil or required properties are missing
+# @raise [RuntimeError] If required global variables are not set
+# @note Requires 'repository' and 'issue' properties in the fact
+# @note Repository names are cached to reduce GitHub API calls
+# @example Format an issue reference
+#   issue_fact = fb.query('(eq type "issue")').first
+#   issue_fact.repository = 549866411  # Repository ID
+#   issue_fact.issue = 42               # Issue number
+#   puts Fbe.issue(issue_fact)  # => "zerocracy/fbe#42"
 def Fbe.issue(fact, options: $options, global: $global, loog: $loog)
   raise 'The fact is nil' if fact.nil?
   raise 'The $global is not set' if global.nil?

data/lib/fbe/iterate.rb

@@ -10,13 +10,30 @@ require_relative 'fb'
 require_relative 'octo'
 require_relative 'unmask_repos'
 
-# Creates an instance of {Fbe::Iterate} and evals it with the block provided.
+# Creates an instance of {Fbe::Iterate} and evaluates it with the provided block.
 #
-# @param [Factbase] fb The global factbase provided by the +judges+ tool
-# @param [Judges::Options] options The options coming from the +judges+ tool
-# @param [Hash] global The hash for global caching
-# @param [Loog] loog The logging facility
-# @yield [Factbase::Fact] The fact
+# This is a convenience method that creates an iterator instance and evaluates
+# the DSL block within its context. The iterator processes repositories defined
+# in options.repositories, executing queries and managing state for each.
+#
+# @param [Factbase] fb The global factbase provided by the +judges+ tool (defaults to Fbe.fb)
+# @param [Judges::Options] options The options from judges tool (uses $options global)
+# @param [Hash] global The hash for global caching (uses $global)
+# @param [Loog] loog The logging facility (uses $loog global)
+# @yield Block containing DSL methods (as, by, over, etc.) to configure iteration
+# @return [Object] Result of the block evaluation
+# @raise [RuntimeError] If required globals are not set
+# @example Iterate through repositories processing issues
+#   Fbe.iterate do
+#     as 'issues-iterator'
+#     by '(and (eq what "issue") (gt created_at $before))'
+#     repeats 5
+#     quota_aware
+#     over(timeout: 300) do |repository_id, issue_id|
+#       process_issue(repository_id, issue_id)
+#       issue_id + 1
+#     end
+#   end
 def Fbe.iterate(fb: Fbe.fb, loog: $loog, options: $options, global: $global, &)
   raise 'The fb is nil' if fb.nil?
   raise 'The $global is not set' if global.nil?
@@ -26,24 +43,44 @@ def Fbe.iterate(fb: Fbe.fb, loog: $loog, options: $options, global: $global, &)
   c.instance_eval(&)
 end
 
-# An iterator.
+# Repository iterator with stateful query execution.
+#
+# This class provides a DSL for iterating through repositories and executing
+# queries while maintaining state between iterations. It tracks progress using
+# "marker" facts in the factbase and supports features like:
+#
+# - Stateful iteration with automatic restart capability
+# - GitHub API quota awareness to prevent rate limit issues
+# - Configurable repeat counts per repository
+# - Timeout controls for long-running operations
 #
-# Here, you go through all repositories defined by the +repositories+ option
-# in the +$options+, trying to run the provided query for each of them. If the
-# query returns an integer that is different from the previously seen, the
-# function keeps repeating the cycle. Otherwise, it will restart from the
-# beginning.
+# The iterator executes a query for each repository, passing the previous
+# result as context. If the query returns nil, it restarts from the beginning
+# for that repository. Progress is persisted in the factbase to support
+# resuming after interruptions.
+#
+# @example Processing pull requests with state management
+#   iterator = Fbe::Iterate.new(fb: fb, loog: loog, options: options, global: global)
+#   iterator.as('pull-requests')
+#   iterator.by('(and (eq what "pull_request") (gt number $before))')
+#   iterator.repeats(10)
+#   iterator.quota_aware
+#   iterator.over(timeout: 600) do |repo_id, pr_number|
+#     # Process pull request
+#     fetch_and_store_pr(repo_id, pr_number)
+#     pr_number  # Return next PR number to process
+#   end
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Zerocracy
 # License:: MIT
 class Fbe::Iterate
-  # Ctor.
+  # Creates a new iterator instance.
   #
-  # @param [Factbase] fb The factbase
-  # @param [Loog] loog The logging facility
-  # @param [Judges::Options] options The options coming from the +judges+ tool
-  # @param [Hash] global The hash for global caching
+  # @param [Factbase] fb The factbase for storing iteration state
+  # @param [Loog] loog The logging facility for debug output
+  # @param [Judges::Options] options The options containing repository configuration
+  # @param [Hash] global The hash for global caching of API responses
   def initialize(fb:, loog:, options:, global:)
     @fb = fb
     @loog = loog
@@ -56,56 +93,107 @@ class Fbe::Iterate
     @quota_aware = false
   end
 
-  # Make this block aware of GitHub API quota.
+  # Makes the iterator aware of GitHub API quota limits.
   #
-  # When the quota is reached, the loop will gracefully stop to avoid
-  # hitting GitHub API rate limits. This helps prevent interruptions
-  # in long-running operations.
+  # When enabled, the iterator will check quota status before processing
+  # each repository and gracefully stop when the quota is exhausted.
+  # This prevents API errors and allows for resuming later.
   #
   # @return [nil] Nothing is returned
+  # @example Enable quota awareness
+  #   iterator.quota_aware
+  #   iterator.over { |repo, item| ... }  # Will stop if quota exhausted
   def quota_aware
     @quota_aware = true
   end
 
-  # Sets the total counter of repeats to make.
+  # Sets the maximum number of iterations per repository.
+  #
+  # Controls how many times the query will be executed for each repository
+  # before moving to the next one. Useful for limiting processing scope.
   #
-  # @param [Integer] repeats The total count of repeats to execute
+  # @param [Integer] repeats The maximum iterations per repository
   # @return [nil] Nothing is returned
+  # @raise [RuntimeError] If repeats is nil or not positive
+  # @example Process up to 100 items per repository
+  #   iterator.repeats(100)
   def repeats(repeats)
     raise 'Cannot set "repeats" to nil' if repeats.nil?
     raise 'The "repeats" must be a positive integer' unless repeats.positive?
     @repeats = repeats
   end
 
-  # Sets the query to run.
+  # Sets the query to execute for each iteration.
+  #
+  # The query can use two special variables:
+  # - $before: The value from the previous iteration (or initial value)
+  # - $repository: The current repository ID
   #
-  # @param [String] query The query to execute
+  # @param [String] query The Factbase query to execute
   # @return [nil] Nothing is returned
+  # @raise [RuntimeError] If query is already set or nil
+  # @example Query for issues after a certain ID
+  #   iterator.by('(and (eq what "issue") (gt id $before) (eq repo $repository))')
   def by(query)
     raise 'Query is already set' unless @query.nil?
     raise 'Cannot set query to nil' if query.nil?
     @query = query
   end
 
-  # Sets the label to use in the "marker" fact.
+  # Sets the label for tracking iteration state.
   #
-  # @param [String] label The label identifier
+  # The label is used to create marker facts in the factbase that track
+  # the last processed item for each repository. This enables resuming
+  # iteration after interruptions.
+  #
+  # @param [String] label Unique identifier for this iteration type
   # @return [nil] Nothing is returned
+  # @raise [RuntimeError] If label is already set or nil
+  # @example Set label for issue processing
+  #   iterator.as('issue-processor')
   def as(label)
     raise 'Label is already set' unless @label.nil?
     raise 'Cannot set "label" to nil' if label.nil?
     @label = label
   end
 
-  # It makes a number of repeats of going through all repositories
-  # provided by the +repositories+ configuration option. In each "repeat"
-  # it yields the repository ID and a number that is retrieved by the
-  # +query+. The query is supplied with two parameters:
-  # +$before+ (the value from the previous repeat) and +$repository+ (GitHub repo ID).
+  # Executes the iteration over all configured repositories.
+  #
+  # For each repository, retrieves the last processed value (or uses the initial
+  # value from +since+) and executes the configured query with it. The query
+  # receives two parameters: $before (the last processed value) and $repository
+  # (GitHub repository ID).
+  #
+  # When the query returns a non-nil result, the block is called with the
+  # repository ID and query result. The block must return an Integer that will
+  # be stored as the new "latest" value for the next iteration.
+  #
+  # When the query returns nil, the iteration for that repository restarts
+  # from the initial value (set by +since+), and the block is NOT called.
+  #
+  # The method tracks progress using marker facts and supports:
+  # - Automatic restart when query returns nil
+  # - Timeout to prevent infinite loops
+  # - GitHub API quota checking (if enabled)
+  # - State persistence for resuming after interruptions
+  #
+  # Processing flow for each repository:
+  # 1. Read the "latest" value from factbase (or use +since+ if not found)
+  # 2. Execute the query with $before=latest and $repository=repo_id
+  # 3. If query returns nil: restart from +since+ value, skip to next repo
+  # 4. If query returns a value: call the block with (repo_id, query_result)
+  # 5. Store the block's return value as the new "latest" for next iteration
   #
-  # @param [Float] timeout How many seconds to spend as a maximum
-  # @yield [Integer, Integer] Repository ID and the next number to be considered
+  # @param [Float] timeout Maximum seconds to run (default: 120)
+  # @yield [Integer, Object] Repository ID and the result from query execution
+  # @yieldreturn [Integer] The value to store as "latest" for next iteration
   # @return [nil] Nothing is returned
+  # @raise [RuntimeError] If block doesn't return an Integer
+  # @example Process issues incrementally
+  #   iterator.over(timeout: 300) do |repo_id, issue_number|
+  #     fetch_and_process_issue(repo_id, issue_number)
+  #     issue_number + 1  # Return next issue number to process
+  #   end
   def over(timeout: 2 * 60, &)
     raise 'Use "as" first' if @label.nil?
     raise 'Use "by" first' if @query.nil?
@@ -129,7 +217,7 @@ class Fbe::Iterate
           break
         end
         if Time.now - start > timeout
-          $loog.info("We are doing this for #{start.ago} already, won't check #{repo}")
+          @loog.info("We are doing this for #{start.ago} already, won't check #{repo}")
           next
         end
         next if restarted.include?(repo)
@@ -178,7 +266,7 @@ class Fbe::Iterate
         break
       end
       if Time.now - start > timeout
-        $loog.info("We are iterating for #{start.ago} already, time to give up")
+        @loog.info("We are iterating for #{start.ago} already, time to give up")
         break
       end
     end

data/lib/fbe/just_one.rb

@@ -8,22 +8,30 @@ require 'others'
 require_relative '../fbe'
 require_relative 'fb'
 
-# Injects a fact if it's absent in the factbase, otherwise (it is already
-# there) returns the existing one.
+# Ensures exactly one fact exists with the specified attributes in the factbase.
 #
-#  require 'fbe/just_one'
-#  n =
-#   Fbe.just_one do |f|
-#     f.what = 'something'
-#     f.details = 'important'
+# This method creates a new fact if none exists with the given attributes,
+# or returns an existing fact if one already matches. Useful for preventing
+# duplicate facts while ensuring required facts exist.
+#
+# @example Creating or finding a unique fact
+#   require 'fbe/just_one'
+#   fact = Fbe.just_one do |f|
+#     f.what = 'github_issue'
+#     f.issue_id = 123
+#     f.repository = 'zerocracy/fbe'
 #   end
+#   # Returns existing fact if one exists with these exact attributes,
+#   # otherwise creates and returns a new fact
 #
-# This code will guarantee that only one fact with +what+ equals to +something+
-# and +details+ equals to +important+ may exist.
+# @example Attributes are matched exactly (case-sensitive)
+#   Fbe.just_one { |f| f.name = 'Test' }  # Creates fact with name='Test'
+#   Fbe.just_one { |f| f.name = 'test' }  # Creates another fact (different case)
 #
-# @param [Factbase] fb The global factbase
-# @yield [Factbase::Fact] The fact that was either created or found
-# @return [Factbase::Fact] The fact found
+# @param [Factbase] fb The factbase to search/insert into (defaults to Fbe.fb)
+# @yield [Factbase::Fact] Block to set attributes on the fact
+# @return [Factbase::Fact] The existing or newly created fact
+# @note System attributes (_id, _time, _version) are ignored when matching
 def Fbe.just_one(fb: Fbe.fb)
   attrs = {}
   f =

data/lib/fbe/middleware/formatter.rb

@@ -8,22 +8,50 @@ require 'faraday/logging/formatter'
 require_relative '../../fbe'
 require_relative '../../fbe/middleware'
 
-# Faraday logging formatter shows verbose logs for error responses only
+# Custom Faraday formatter that logs only error responses (4xx/5xx).
+#
+# This formatter reduces log noise by only outputting details when HTTP
+# requests fail. For 403 errors with JSON responses, it shows a compact
+# warning with the error message. For other errors, it logs the full
+# request/response details including headers and bodies.
+#
+# @example Usage in Faraday middleware
+#   connection = Faraday.new do |f|
+#     f.response :logger, nil, formatter: Fbe::Middleware::Formatter
+#   end
+#
+# @example Log output for 403 error
+#   # GET https://api.github.com/repos/private/repo -> 403 / Repository access denied
+#
+# @example Log output for other errors (500, 404, etc)
+#   # GET https://api.example.com/endpoint HTTP/1.1
+#   #   Content-Type: "application/json"
+#   #   Authorization: "Bearer [FILTERED]"
+#   #
+#   #   {"query": "data"}
+#   # HTTP/1.1 500
+#   #   Content-Type: "text/html"
+#   #
+#   #   Internal Server Error
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Zerocracy
 # License:: MIT
 class Fbe::Middleware::Formatter < Faraday::Logging::Formatter
-  # Log HTTP request.
+  # Captures HTTP request details for later use in error logging.
   #
-  # @param [Hash] http The hash with data about HTTP request
+  # @param [Hash] http Request data including method, url, headers, and body
+  # @return [void]
   def request(http)
     @req = http
   end
 
-  # Log HTTP response.
+  # Logs HTTP response details only for error responses (4xx/5xx).
   #
-  # @param [Hash] http The hash with data about HTTP response
+  # @param [Hash] http Response data including status, headers, and body
+  # @return [void]
+  # @note Only logs when status >= 400
+  # @note Special handling for 403 JSON responses to show compact error message
   def response(http)
     return if http.status < 400
     if http.status == 403 && http.response_headers['content-type'].start_with?('application/json')

data/lib/fbe/middleware.rb

@@ -5,11 +5,24 @@
 
 require_relative '../fbe'
 
-# The module.
+# Middleware components for Faraday HTTP client configuration.
+#
+# This module serves as a namespace for various middleware components
+# that enhance Faraday HTTP client functionality with custom behaviors
+# such as request/response formatting, logging, and error handling.
+#
+# The middleware components in this module are designed to work with
+# the Faraday HTTP client library and can be plugged into the Faraday
+# middleware stack to provide additional functionality.
+#
+# @example Using middleware in Faraday client
+#   Faraday.new do |conn|
+#     conn.use Fbe::Middleware::Formatter
+#     conn.adapter Faraday.default_adapter
+#   end
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Zerocracy
 # License:: MIT
 module Fbe::Middleware
-  # empty
 end

data/lib/fbe/octo.rb

@@ -128,7 +128,21 @@ end
 # Fake GitHub client for testing purposes.
 #
 # This class provides mock implementations of Octokit methods for testing.
-# It returns predictable data structures that mimic GitHub API responses.
+# It returns predictable, deterministic data structures that mimic GitHub API
+# responses without making actual API calls. The mock data uses consistent
+# patterns:
+# - IDs are generated from string names using character code sums
+# - Timestamps are random but within recent past
+# - Repository and user data follows GitHub's JSON structure
+#
+# @example Using FakeOctokit in tests
+#   client = Fbe::FakeOctokit.new
+#   repo = client.repository('octocat/hello-world')
+#   puts repo[:full_name]  # => "octocat/hello-world"
+#   puts repo[:id]         # => 1224 (deterministic from name)
+#
+# @note All methods return static or pseudo-random data
+# @note No actual API calls are made
 class Fbe::FakeOctokit
   # Generates a random time in the past.
   #
@@ -167,6 +181,13 @@ class Fbe::FakeOctokit
     o
   end
 
+  # Lists repositories for a user or organization.
+  #
+  # @param [String] _user The user/org name (ignored in mock)
+  # @return [Array<Hash>] Array of repository hashes
+  # @example
+  #   client.repositories('octocat')
+  #   # => [{:id=>123, :full_name=>"yegor256/judges", ...}, ...]
   def repositories(_user = nil)
     [
       repository('yegor256/judges'),
@@ -428,6 +449,14 @@ class Fbe::FakeOctokit
     }
   end
 
+  # Lists releases for a repository.
+  #
+  # @param [String] _repo Repository name (ignored in mock)
+  # @param [Hash] _opts Options hash (ignored in mock)
+  # @return [Array<Hash>] Array of release hashes
+  # @example
+  #   client.releases('octocat/Hello-World')
+  #   # => [{:tag_name=>"0.19.0", :name=>"just a fake name", ...}, ...]
   def releases(_repo, _opts = {})
     [
       release('https://github...'),
@@ -435,6 +464,13 @@ class Fbe::FakeOctokit
     ]
   end
 
+  # Gets a single release.
+  #
+  # @param [String] _url Release URL (ignored in mock)
+  # @return [Hash] Release information
+  # @example
+  #   client.release('https://api.github.com/repos/octocat/Hello-World/releases/1')
+  #   # => {:tag_name=>"0.19.0", :name=>"just a fake name", ...}
   def release(_url)
     {
       node_id: 'RE_kwDOL6GCO84J7Cen',
@@ -449,6 +485,14 @@ class Fbe::FakeOctokit
     }
   end
 
+  # Gets repository information.
+  #
+  # @param [String, Integer] name Repository name ('owner/repo') or ID
+  # @return [Hash] Repository information
+  # @raise [Octokit::NotFound] If name is 404123 or 404124 (for testing)
+  # @example
+  #   client.repository('octocat/Hello-World')
+  #   # => {:id=>1296269, :full_name=>"octocat/Hello-World", ...}
   def repository(name)
     raise Octokit::NotFound if [404_123, 404_124].include?(name)
     {
@@ -488,12 +532,28 @@ class Fbe::FakeOctokit
     }
   end
 
+  # Lists pull requests associated with a commit.
+  #
+  # @param [String] repo Repository name ('owner/repo')
+  # @param [String] _sha Commit SHA (ignored in mock)
+  # @return [Array<Hash>] Array of pull request hashes
+  # @example
+  #   client.commit_pulls('octocat/Hello-World', 'abc123')
+  #   # => [{:number=>42, :state=>"open", ...}]
   def commit_pulls(repo, _sha)
     [
       pull_request(repo, 42)
     ]
   end
 
+  # Lists issues for a repository.
+  #
+  # @param [String] repo Repository name ('owner/repo')
+  # @param [Hash] _options Query options (ignored in mock)
+  # @return [Array<Hash>] Array of issue hashes
+  # @example
+  #   client.list_issues('octocat/Hello-World', state: 'open')
+  #   # => [{:number=>42, :title=>"Found a bug", ...}, ...]
   def list_issues(repo, _options = {})
     [
       issue(repo, 42),
@@ -501,6 +561,14 @@ class Fbe::FakeOctokit
     ]
   end
 
+  # Gets a single issue.
+  #
+  # @param [String] repo Repository name ('owner/repo')
+  # @param [Integer] number Issue number
+  # @return [Hash] Issue information
+  # @example
+  #   client.issue('octocat/Hello-World', 42)
+  #   # => {:id=>42, :number=>42, :created_at=>...}
   def issue(repo, number)
     {
       id: 42,
@@ -515,6 +583,14 @@ class Fbe::FakeOctokit
     }
   end
 
+  # Gets a single pull request.
+  #
+  # @param [String] repo Repository name ('owner/repo')
+  # @param [Integer] number Pull request number
+  # @return [Hash] Pull request information
+  # @example
+  #   client.pull_request('octocat/Hello-World', 1)
+  #   # => {:id=>42, :number=>1, :additions=>12, ...}
   def pull_request(repo, number)
     {
       id: 42,
@@ -529,6 +605,14 @@ class Fbe::FakeOctokit
     }
   end
 
+  # Lists pull requests for a repository.
+  #
+  # @param [String] _repo Repository name (ignored in mock)
+  # @param [Hash] _options Query options (ignored in mock)
+  # @return [Array<Hash>] Array of pull request hashes
+  # @example
+  #   client.pull_requests('octocat/Hello-World', state: 'open')
+  #   # => [{:number=>100, :state=>"closed", :title=>"#90: some title", ...}]
   def pull_requests(_repo, _options = {})
     [
       {
@@ -1045,6 +1129,45 @@ class Fbe::FakeOctokit
     ]
   end
 
+  def issue_events(_repo, _number)
+    [
+      {
+        id: 126, actor: { login: 'user', id: 411, type: 'User' },
+        event: 'labeled', created_at: Time.parse('2025-05-30 14:41:00 UTC'),
+        label: { name: 'bug', color: 'd73a4a' }
+      },
+      {
+        id: 206, actor: { login: 'user', id: 411, type: 'User' },
+        event: 'mentioned', created_at: Time.parse('2025-05-30 14:41:10 UTC')
+      },
+      {
+        id: 339, actor: { login: 'user2', id: 422, type: 'User' },
+        event: 'subscribed', created_at: Time.parse('2025-05-30 14:41:10 UTC')
+      },
+      {
+        id: 490, actor: { login: 'github-actions[bot]', id: 41_898_282, type: 'Bot' },
+        event: 'renamed', created_at: Time.parse('2025-05-30 14:41:30 UTC'),
+        rename: { from: 'some title', to: 'some title 2' }
+      },
+      {
+        id: 505, actor: { login: 'user', id: 411, type: 'User' },
+        event: 'subscribed', created_at: Time.parse('2025-05-30 16:18:24 UTC')
+      },
+      {
+        id: 608, actor: { login: 'user2', id: 422, type: 'User', test: 123 },
+        event: 'assigned', created_at: Time.parse('2025-05-30 17:59:08 UTC'),
+        assignee: { login: 'user2', id: 422, type: 'User' },
+        assigner: { login: 'user', id: 411, type: 'User' }
+      },
+      {
+        id: 776, actor: { login: 'user2', id: 422, type: 'User' },
+        event: 'referenced', commit_id: '4621af032170f43d',
+        commit_url: 'https://api.github.com/repos/foo/foo/commits/4621af032170f43d',
+        created_at: Time.parse('2025-05-30 19:57:50 UTC')
+      }
+    ]
+  end
+
   def pull_request_comments(_name, _number)
     [
       {

data/lib/fbe/overwrite.rb

@@ -6,19 +6,27 @@
 require_relative '../fbe'
 require_relative 'fb'
 
-# Overwrites a property in the fact.
+# Overwrites a property in the fact by recreating the entire fact.
 #
 # If the property doesn't exist in the fact, it will be added. If it does
-# exist, it will be re-set (the entire fact will be destroyed, a new fact
-# created, and the property set with the new value).
+# exist, the entire fact will be destroyed, a new fact created with all
+# existing properties, and the specified property set with the new value.
 #
 # It is important that the fact has the +_id+ property. If it doesn't,
 # an exception will be raised.
 #
-# @param [Factbase::Fact] fact The fact to modify
+# @param [Factbase::Fact] fact The fact to modify (must have _id property)
 # @param [String] property The name of the property to set
-# @param [Any] value The value to set
-# @return [Factbase::Fact] Returns new fact or previous one
+# @param [Any] value The value to set (can be any type)
+# @param [Factbase] fb The factbase to use (defaults to Fbe.fb)
+# @return [Factbase::Fact] Returns new fact if recreated, or original if unchanged
+# @raise [RuntimeError] If fact is nil, has no _id, or property is not a String
+# @note This operation preserves all other properties during recreation
+# @note If property already has the same single value, no changes are made
+# @example Update a user's status
+#   user = fb.query('(eq login "john")').first
+#   updated_user = Fbe.overwrite(user, 'status', 'active')
+#   # All properties preserved, only 'status' is set to 'active'
 def Fbe.overwrite(fact, property, value, fb: Fbe.fb)
   raise 'The fact is nil' if fact.nil?
   raise 'The fb is nil' if fb.nil?

data/lib/fbe/regularly.rb

@@ -6,15 +6,28 @@
 require_relative '../fbe'
 require_relative 'fb'
 
-# Run the block provided every X days.
+# Run the block provided every X days based on PMP configuration.
+#
+# Executes a block periodically based on PMP (Project Management Plan) settings.
+# The block will only run if it hasn't been executed within the specified interval.
+# Creates a fact recording when the judge was last run.
 #
 # @param [String] area The name of the PMP area
-# @param [Integer] p_every_days How frequently to run, every X days
-# @param [Integer] p_since_days Since when to collect stats, X days
-# @param [Factbase] fb The factbase
-# @param [String] judge The name of the judge, from the +judges+ tool
-# @param [Loog] loog The logging facility
+# @param [String] p_every_days PMP property name for interval (defaults to 7 days if not in PMP)
+# @param [String] p_since_days PMP property name for since period (defaults to 28 days if not in PMP)
+# @param [Factbase] fb The factbase (defaults to Fbe.fb)
+# @param [String] judge The name of the judge (uses $judge global)
+# @param [Loog] loog The logging facility (uses $loog global)
+# @yield [Factbase::Fact] Fact to populate with judge execution details
 # @return [nil] Nothing
+# @raise [RuntimeError] If required parameters or globals are nil
+# @note Skips execution if judge was run within the interval period
+# @note The 'since' property is added to the fact when p_since_days is provided
+# @example Run a cleanup task every 3 days
+#   Fbe.regularly('cleanup', 'days_between_cleanups', 'cleanup_history_days') do |f|
+#     f.total_cleaned = cleanup_old_records
+#     # PMP might have: days_between_cleanups=3, cleanup_history_days=30
+#   end
 def Fbe.regularly(area, p_every_days, p_since_days = nil, fb: Fbe.fb, judge: $judge, loog: $loog, &)
   raise 'The area is nil' if area.nil?
   raise 'The p_every_days is nil' if p_every_days.nil?

data/lib/fbe/repeatedly.rb

@@ -7,14 +7,29 @@ require_relative '../fbe'
 require_relative 'fb'
 require_relative 'overwrite'
 
-# Run the block provided every X hours.
+# Run the block provided every X hours based on PMP configuration.
+#
+# Similar to Fbe.regularly but works with hour intervals instead of days.
+# Executes a block periodically, maintaining a single fact that tracks the
+# last execution time. The fact is overwritten on each run rather than
+# creating new facts.
 #
 # @param [String] area The name of the PMP area
-# @param [Integer] p_every_hours How frequently to run, every X hours
-# @param [Factbase] fb The factbase
-# @param [String] judge The name of the judge, from the +judges+ tool
-# @param [Loog] loog The logging facility
+# @param [String] p_every_hours PMP property name for interval (defaults to 24 hours if not in PMP)
+# @param [Factbase] fb The factbase (defaults to Fbe.fb)
+# @param [String] judge The name of the judge (uses $judge global)
+# @param [Loog] loog The logging facility (uses $loog global)
+# @yield [Factbase::Fact] The judge fact to populate with execution details
 # @return [nil] Nothing
+# @raise [RuntimeError] If required parameters or globals are nil
+# @note Skips execution if judge was run within the interval period
+# @note Overwrites the 'when' property of existing judge fact
+# @example Run a monitoring task every 6 hours
+#   Fbe.repeatedly('monitoring', 'hours_between_checks') do |f|
+#     f.servers_checked = check_all_servers
+#     f.issues_found = count_issues
+#     # PMP might have: hours_between_checks=6
+#   end
 def Fbe.repeatedly(area, p_every_hours, fb: Fbe.fb, judge: $judge, loog: $loog, &)
   raise 'The area is nil' if area.nil?
   raise 'The p_every_hours is nil' if p_every_hours.nil?

data/lib/fbe/sec.rb

@@ -6,15 +6,22 @@
 require 'tago'
 require_relative '../fbe'
 
-# Converts number of seconds into text.
+# Converts number of seconds into human-readable time format.
 #
 # The number of seconds is taken from the +fact+ provided, usually stored
-# there in the +seconds+ property. The seconds are formatted to hours,
-# days, or weeks.
+# there in the +seconds+ property. The seconds are formatted into a
+# human-readable string like "3 days ago" or "5 hours ago" using the
+# tago gem.
 #
-# @param [Factbase::Fact] fact The fact, where to get the number of seconds
-# @param [String] prop The property in the fact, with the seconds
-# @return [String] Time interval as a text
+# @param [Factbase::Fact] fact The fact containing the seconds property
+# @param [String, Symbol] prop The property name with seconds (defaults to :seconds)
+# @return [String] Human-readable time interval (e.g., "2 weeks ago", "3 hours ago")
+# @raise [RuntimeError] If the specified property doesn't exist in the fact
+# @note Uses the tago gem's ago method for formatting
+# @example Format elapsed time from a fact
+#   build_fact = fb.query('(eq type "build")').first
+#   build_fact.duration = 7200  # 2 hours in seconds
+#   puts Fbe.sec(build_fact, :duration)  # => "2 hours ago"
 def Fbe.sec(fact, prop = :seconds)
   s = fact[prop.to_s]
   raise "There is no #{prop.inspect} property" if s.nil?

data/lib/fbe/unmask_repos.rb

@@ -6,31 +6,52 @@
 require_relative '../fbe'
 require_relative 'octo'
 
-# Converts mask to repository name.
+# Converts a repository mask pattern to a regular expression.
 #
-# This function takes something like +"zerocracy/*"+ as an input and returns
-# a regular expression that may match repositories defined by this mask, which
-# is +/zerocracy\/.*+ in this particular case.
+# @example Basic wildcard matching
+#   Fbe.mask_to_regex('zerocracy/*')
+#   # => /zerocracy\/.*/i
 #
-# @param [String] mask The mask
-# @return [Regex] Regular expression
+# @example Specific repository (no wildcard)
+#   Fbe.mask_to_regex('zerocracy/fbe')
+#   # => /zerocracy\/fbe/i
+#
+# @param [String] mask Repository mask in format 'org/repo' where repo can contain '*'
+# @return [Regexp] Case-insensitive regular expression for matching repositories
+# @raise [RuntimeError] If organization part contains asterisk
 def Fbe.mask_to_regex(mask)
   org, repo = mask.split('/')
   raise "Org '#{org}' can't have an asterisk" if org.include?('*')
   Regexp.compile("#{org}/#{repo.gsub('*', '.*')}", Regexp::IGNORECASE)
 end
 
-# Builds a list of repositories required by the +repositories+ option.
+# Resolves repository masks to actual GitHub repository names.
+#
+# Takes a comma-separated list of repository masks from options and expands
+# wildcards by querying GitHub API. Supports inclusion and exclusion patterns.
+# Archived repositories are automatically filtered out.
+#
+# @example Basic usage with wildcards
+#   # options.repositories = "zerocracy/fbe,zerocracy/ab*"
+#   repos = Fbe.unmask_repos
+#   # => ["zerocracy/fbe", "zerocracy/abc", "zerocracy/abcd"]
+#
+# @example Using exclusion patterns
+#   # options.repositories = "zerocracy/*,-zerocracy/private*"
+#   repos = Fbe.unmask_repos
+#   # Returns all zerocracy repos except those starting with 'private'
 #
-# The +repositories+ option defined in the +$options+ must contain something
-# like "zerocracy/fbe,zerocracy/ab*" (a comma-separated list of masks). This
-# function will go to the GitHub API and fetch all available repositories
-# matching these masks.
+# @example Empty result handling
+#   # options.repositories = "nonexistent/*"
+#   Fbe.unmask_repos  # Raises error: "No repos found matching: nonexistent/*"
 #
-# @param [Judges::Options] options The options coming from the +judges+ tool
-# @param [Hash] global The hash for global caching
-# @param [Loog] loog The logging facility
-# @return [Array<String>] List of repository full names
+# @param [Judges::Options] options Options containing 'repositories' field with masks
+# @param [Hash] global Global cache for storing API responses
+# @param [Loog] loog Logger for debug output
+# @return [Array<String>] Shuffled list of repository full names (e.g., 'org/repo')
+# @raise [RuntimeError] If no repositories match the provided masks
+# @note Exclusion patterns must start with '-' (e.g., '-org/pattern*')
+# @note Results are shuffled to distribute load when processing
 def Fbe.unmask_repos(options: $options, global: $global, loog: $loog)
   repos = []
   octo = Fbe.octo(loog:, global:, options:)

data/lib/fbe/who.rb

@@ -6,19 +6,26 @@
 require_relative '../fbe'
 require_relative 'octo'
 
-# Converts an ID of GitHub user into a nicely formatted string with their name.
+# Converts a GitHub user ID into a formatted username string.
 #
 # The ID of the user (integer) is expected to be stored in the +who+ property of the
-# provided +fact+. This function makes a live request to GitHub API in order
-# to find out what is the name of the user. For example, the ID +526301+
-# will be converted to the +"@yegor256"+ string.
+# provided +fact+. This function makes a live request to GitHub API to
+# retrieve the username. The result is cached globally to minimize API calls.
+# For example, the ID +526301+ will be converted to +"@yegor256"+.
 #
-# @param [Factbase::Fact] fact The fact, where to get the ID of GitHub user
-# @param [String] prop The property in the fact, with the ID
-# @param [Judges::Options] options The options coming from the +judges+ tool
-# @param [Hash] global The hash for global caching
-# @param [Loog] loog The logging facility
-# @return [String] Full name of the user
+# @param [Factbase::Fact] fact The fact containing the GitHub user ID
+# @param [String, Symbol] prop The property name with the ID (defaults to :who)
+# @param [Judges::Options] options The options from judges tool (uses $options global)
+# @param [Hash] global The hash for global caching (uses $global)
+# @param [Loog] loog The logging facility (uses $loog global)
+# @return [String] Formatted username with @ prefix (e.g., "@yegor256")
+# @raise [RuntimeError] If the specified property doesn't exist in the fact
+# @note Results are cached to reduce GitHub API calls
+# @note Subject to GitHub API rate limits
+# @example Convert user ID to username
+#   contributor = fb.query('(eq type "contributor")').first
+#   contributor.author_id = 526301
+#   puts Fbe.who(contributor, :author_id)  # => "@yegor256"
 def Fbe.who(fact, prop = :who, options: $options, global: $global, loog: $loog)
   id = fact[prop.to_s]
   raise "There is no #{prop.inspect} property" if id.nil?

data/lib/fbe.rb

@@ -10,5 +10,5 @@
 # License:: MIT
 module Fbe
   # Current version of the gem (changed by +.rultor.yml+ on every release)
-  VERSION = '0.14.1' unless const_defined?(:VERSION)
+  VERSION = '0.15.0' unless const_defined?(:VERSION)
 end

data/test/fbe/test_octo.rb

@@ -274,4 +274,23 @@ class TestOcto < Fbe::Test
     assert_raises(Octokit::NotFound) { o.repository(404_123) }
     assert_raises(Octokit::NotFound) { o.repository(404_124) }
   end
+
+  def test_fetches_fake_issue_events_has_assigned_event
+    o = Fbe.octo(loog: Loog::NULL, global: {}, options: Judges::Options.new({ 'testing' => true }))
+    result = o.issue_events('foo/foo', 123)
+    assert_instance_of(Array, result)
+    assert_equal(7, result.size)
+    event = result.find { _1[:event] == 'assigned' }
+    assert_equal(608, event[:id])
+    assert_pattern do
+      event => {
+        id: Integer,
+        actor: { login: 'user2', id: 422, type: 'User' },
+        event: 'assigned',
+        created_at: Time,
+        assignee: { login: 'user2', id: 422, type: 'User' },
+        assigner: { login: 'user', id: 411, type: 'User' }
+      }
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fbe
 version: !ruby/object:Gem::Version
-  version: 0.14.1
+  version: 0.15.0
 platform: ruby
 authors:
 - Yegor Bugayenko