fbe 0.14.1 → 0.16.0

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?