fbe 0.14.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c645873d437ec40589dca8b3bd3789b3dd859d5c5b365e25dae38b82bd4d5feb
-  data.tar.gz: d586ef4096f29632302503f72f24f39511567760e179b0ca4373626b8541eb8e
+  metadata.gz: 1c418c6898cb137949a07664da066df3a81594a641f5a5bcc6b42713961e8f26
+  data.tar.gz: 89c4aae8d5858bf72360acee43f00e3cfa4d2943a91c8da1abf5161b572b6c77
 SHA512:
-  metadata.gz: a52fb8eaeab99279664d91e6b1bb50492f40f4c2583937c64e412822f84428863caaf6a33f330dc7706d1c0aad809761337b0a241163d4f914235b66c3fb59fc
-  data.tar.gz: 88d9ddc164b53f357515b223a69ac9622f1860258ff36fa94ce2ff6d7b3b6f996c81f495734c41f9a3fd5f5581bbf8085358a06c516f50b0466d7a2abe7eea7f
+  metadata.gz: bc6272d068c113efd0ee5c539c0a4130a4e087c449bdd7daa8aad565f8b51a857145aec11fbc023f1eb586ec7ac40afc2f793fc62698d221f3a31df88be8553d
+  data.tar.gz: 24b9c8cc24ba545b4a3b9e70806f7c1217a569fb81015c2cc602738b46a734fb6ca725d28c525284bb1c5c63a7bf6acbb3cf60d27cb1949d682dca674f00fa84

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/.github/workflows/typos.yml

@@ -16,6 +16,6 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
-      - uses: crate-ci/typos@v1.32.0
+      - uses: crate-ci/typos@v1.33.1
         with:
           config: .github/.typos.toml

data/Gemfile.lock

@@ -2,23 +2,23 @@ PATH
   remote: .
   specs:
     fbe (0.0.0)
-      backtrace (~> 0)
-      baza.rb (~> 0)
-      decoor (~> 0)
+      backtrace (> 0)
+      baza.rb (> 0)
+      decoor (> 0)
       factbase (>= 0.9.3)
-      faraday (~> 2)
-      faraday-http-cache (~> 2)
-      faraday-multipart (~> 1)
-      faraday-retry (~> 2)
-      graphql-client (~> 0)
-      judges (~> 0)
-      liquid (= 5.5.1)
-      loog (~> 0)
-      obk (~> 0)
-      octokit (~> 9)
-      others (~> 0)
-      tago (~> 0)
-      verbose (~> 0)
+      faraday (~> 2.0)
+      faraday-http-cache (~> 2.0)
+      faraday-multipart (~> 1.0)
+      faraday-retry (~> 2.0)
+      graphql-client (~> 0.0)
+      judges (> 0)
+      liquid (~> 5.5)
+      loog (> 0)
+      obk (> 0)
+      octokit (~> 10.0)
+      others (> 0)
+      tago (> 0)
+      verbose (> 0)
 
 GEM
   remote: https://rubygems.org/
@@ -41,8 +41,8 @@ GEM
     ansi (1.5.0)
     ast (2.4.3)
     backtrace (0.4.0)
-    base64 (0.2.0)
-    baza.rb (0.4.0)
+    base64 (0.3.0)
+    baza.rb (0.5.0)
       backtrace (> 0)
       elapsed (> 0)
       faraday (> 0)
@@ -54,8 +54,8 @@ GEM
       retries (~> 0)
       tago (~> 0)
       typhoeus (~> 1.3)
-    benchmark (0.4.0)
-    bigdecimal (3.1.9)
+    benchmark (0.4.1)
+    bigdecimal (3.2.1)
     builder (3.3.0)
     concurrent-ruby (1.3.5)
     connection_pool (2.5.3)
@@ -64,13 +64,13 @@ GEM
       rexml
     decoor (0.0.1)
     docile (1.4.1)
-    drb (2.2.1)
+    drb (2.2.3)
     elapsed (0.0.1)
       loog (> 0)
       tago (> 0)
     ethon (0.16.0)
       ffi (>= 1.15.0)
-    factbase (0.10.2)
+    factbase (0.11.0)
       backtrace (~> 0.4)
       decoor (~> 0.0)
       json (~> 2.7)
@@ -99,19 +99,19 @@ GEM
     fiber-storage (1.0.1)
     gli (2.22.2)
       ostruct
-    graphql (2.5.7)
+    graphql (2.5.8)
       base64
       fiber-storage
       logger
-    graphql-client (0.25.0)
+    graphql-client (0.26.0)
       activesupport (>= 3.0)
       graphql (>= 1.13.0)
-    hashdiff (1.1.2)
+    hashdiff (1.2.0)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
-    iri (0.10.0)
-    json (2.12.0)
-    judges (0.42.1)
+    iri (0.11.2)
+    json (2.12.2)
+    judges (0.45.0)
       backtrace (~> 0)
       baza.rb (~> 0)
       concurrent-ruby (~> 1.2)
@@ -130,7 +130,9 @@ GEM
       typhoeus (~> 1.3)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    liquid (5.5.1)
+    liquid (5.8.6)
+      bigdecimal
+      strscan (>= 3.1.1)
     logger (1.7.0)
     loog (0.6.1)
       logger (~> 1.0)
@@ -153,7 +155,7 @@ GEM
     nokogiri (1.18.8-x86_64-linux-gnu)
       racc (~> 1.4)
     obk (0.3.2)
-    octokit (9.2.0)
+    octokit (10.0.0)
       faraday (>= 1, < 3)
       sawyer (~> 0.9)
     os (1.1.4)
@@ -172,11 +174,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 +192,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)
@@ -215,6 +217,7 @@ GEM
       simplecov (~> 0.19)
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
+    strscan (3.1.5)
     tago (0.1.0)
     timeout (0.4.3)
     total (0.4.1)

data/fbe.gemspec

@@ -22,22 +22,22 @@ Gem::Specification.new do |s|
   s.files = `git ls-files`.split($RS)
   s.rdoc_options = ['--charset=UTF-8']
   s.extra_rdoc_files = ['README.md', 'LICENSE.txt']
-  s.add_dependency 'backtrace', '~>0'
-  s.add_dependency 'baza.rb', '~>0'
-  s.add_dependency 'decoor', '~>0'
+  s.add_dependency 'backtrace', '>0'
+  s.add_dependency 'baza.rb', '>0'
+  s.add_dependency 'decoor', '>0'
   s.add_dependency 'factbase', '>=0.9.3'
-  s.add_dependency 'faraday', '~>2'
-  s.add_dependency 'faraday-http-cache', '~>2'
-  s.add_dependency 'faraday-multipart', '~>1'
-  s.add_dependency 'faraday-retry', '~>2'
-  s.add_dependency 'graphql-client', '~>0'
-  s.add_dependency 'judges', '~>0'
-  s.add_dependency 'liquid', '5.5.1'
-  s.add_dependency 'loog', '~>0'
-  s.add_dependency 'obk', '~>0'
-  s.add_dependency 'octokit', '~>9'
-  s.add_dependency 'others', '~>0'
-  s.add_dependency 'tago', '~>0'
-  s.add_dependency 'verbose', '~>0'
+  s.add_dependency 'faraday', '~>2.0'
+  s.add_dependency 'faraday-http-cache', '~>2.0'
+  s.add_dependency 'faraday-multipart', '~>1.0'
+  s.add_dependency 'faraday-retry', '~>2.0'
+  s.add_dependency 'graphql-client', '~>0.0'
+  s.add_dependency 'judges', '>0'
+  s.add_dependency 'liquid', '~>5.5'
+  s.add_dependency 'loog', '>0'
+  s.add_dependency 'obk', '>0'
+  s.add_dependency 'octokit', '~>10.0'
+  s.add_dependency 'others', '>0'
+  s.add_dependency 'tago', '>0'
+  s.add_dependency 'verbose', '>0'
   s.metadata['rubygems_mfa_required'] = 'true'
 end

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?