recheck 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d3abb8f0a8b65c31746964627a98cd5e713f77370797153268465e16a515646
-  data.tar.gz: 767cc703b8a396e486f2350d9f67e39c7d6b572b749dba5e1a9ef48e6394da7c
+  metadata.gz: 229b7b48547c7da457bff99e2d10cef1d46a915ad4f3699dd0ae3ad29b7075af
+  data.tar.gz: 55d665725da5fe601a0c86ba9c4f62943702b56c7ae239aa3c8c1fe31e01b94c
 SHA512:
-  metadata.gz: 7509ef3cc281c76f022fd1c2599242a4cc5b758f8feb2975de6d70b8fa9756419d45d23740e16487b44b8088506ae8f5a11fc62bf25d77ec38255553d8d044f3
-  data.tar.gz: ec42bd74543f4ea2a8d884528005d3da2a2f302e1a987f16e15631f324d901f5e817da143151116a836a59b0e3c98aa81f438ccf0c67f29038411559a01737cf
+  metadata.gz: b2b403ea3658c20f66b825f1198c3c6ea341161b84face61a83529c284135f230b069bd4db13f2550dde0e7965944ac36d3de56b3ec0cb4b579a99796e16dc5a
+  data.tar.gz: 1dbfd3a4dd3252b9e8603a9b9bbb28fb35255acdb4d068dfe74d55fde7e0683b53ff66b59c89eae29848070193a0ea48c8da51a78195e88ede9e3f8c35b6039a

data/lib/recheck/commands.rb

@@ -136,7 +136,7 @@ module Recheck
 
       def run
         create_helper
-        create_reporter_dir
+        create_samples
         create_site_checks
         setup_model_checks
         run_linter
@@ -168,8 +168,9 @@ module Recheck
         copy_template("#{template_dir}/recheck_helper.rb", "recheck/recheck_helper.rb")
       end
 
-      def create_reporter_dir
-        FileUtils.mkdir_p("recheck/reporter")
+      def create_samples
+        copy_template("#{template_dir}/reporter_sample.rb", "recheck/reporter/reporter.rb.sample")
+        copy_template("#{template_dir}/regression_checker_sample.rb", "recheck/regression/regression_checker.rb.sample")
       end
 
       def create_site_checks

data/lib/recheck/reporters.rb

@@ -35,10 +35,12 @@ module Recheck
       #
       # around_run -> for each Checker class:
       #   around_checker ->
-      #     run each query() method
-      #     for each 'check_' method on the checker:
-      #       for each record queried:
-      #         around_check -> check(record)
+      #     around_query ->
+      #       run each query() method
+      #       for each 'check_' method on the checker:
+      #         for each record queried:
+      #           around_check ->
+      #             check(record)
 
       def around_run(checkers: [])
         total_count = yield
@@ -48,6 +50,10 @@ module Recheck
         counts = yield
       end
 
+      def around_query(checker:, query:, checks: [])
+        yield
+      end
+
       def around_check(checker:, query:, check:, record:)
         result = yield
       end
@@ -97,20 +103,20 @@ module Recheck
 
       def print_errors
         failure_details = []
-        grouped_errors = @errors.group_by { |e| [e.checker_class, e.query, e.check, e.type] }
+        grouped_errors = @errors.group_by { |e| [e.checker, e.query, e.check, e.type] }
 
-        grouped_errors.each do |(checker_class, query, check), group_errors|
+        grouped_errors.each do |(checker, query, check), group_errors|
           case group_errors.first.type
           when :fail
             ids = group_errors.map { |e| fetch_record_id(e.record) }.join(", ")
-            failure_details << "  #{checker_class}##{query} -> #{check} failed for records: #{ids}"
+            failure_details << "  #{checker}##{query} -> #{check} failed for records: #{ids}"
           when :exception
             error = group_errors.first
-            error_message = "  #{checker_class}##{query} -> #{check} exception #{error.exception.message} for #{group_errors.size} records"
+            error_message = "  #{checker}##{query} -> #{check} exception #{error.exception.message} for #{group_errors.size} records"
             failure_details << error_message
             failure_details << error.record.full_message(highlight: false, order: :top) if error.record.respond_to?(:full_message)
           when :blanket
-            failure_details << "  #{checker_class}: Skipping because the first 20 checks all failed. Either there's a lot of bad data or there's something wrong with the checks."
+            failure_details << "  #{checker}: Skipping because the first 20 checks all failed. Either there's a lot of bad data or there's something wrong with the checks."
           end
         end
         puts failure_details

data/lib/recheck/results.rb

@@ -12,7 +12,7 @@ module Recheck
     end
   end
 
-  Error = Data.define(:checker, :query, :check, :record, :type, :exception) do
+  Error = Data.define(:type, :checker, :query, :check, :record, :exception) do
     def initialize(*args)
       super
       raise ArgumentError unless ERROR_TYPES.include? type

data/lib/recheck/runner.rb

@@ -110,39 +110,43 @@ module Recheck
           reduce(reporters: @reporters, hook: :around_checker, kwargs: {checker:, queries:, checks:}) do
             # for each query_...
             queries.each do |query|
-              checker_counts.increment :queries
-              # for each record...
-              # TODO: must handle if the query method yields (find_each) OR returns (current)
-              (checker.public_send(query) || []).each do |record|
-                # for each check_method...
-                checks.each do |check|
-                  raw_result = nil
-                  reduce(reporters: @reporters, hook: :around_check, kwargs: {checker:, query:, check:, record:}) do
-                    raw_result = checker.public_send(check, record)
-                    result = raw_result ? pass : Error.new(checker:, query:, check:, record:, type: :fail, exception: nil)
-
-                    checker_counts.increment(result.type)
-                    break if checker_counts.reached_blanket_failure?
-
-                    result
-                  rescue *PASSTHROUGH_EXCEPTIONS
-                    raise
-                  rescue => e
-                    Error.new(checker:, query:, check:, record:, type: :exception, exception: e)
+              reduce(reporters: @reporters, hook: :around_query, kwargs: {checker:, query:, checks:}) do
+                checker_counts.increment :queries
+                # for each record...
+                # TODO: must handle if the query method yields (find_each) OR returns (current)
+                (checker.public_send(query) || []).each do |record|
+                  # for each check_method...
+                  checks.each do |check|
+                    raw_result = nil
+                    reduce(reporters: @reporters, hook: :around_check, kwargs: {checker:, query:, check:, record:}) do
+                      raw_result = checker.public_send(check, record)
+                      result = raw_result ? pass : Error.new(checker:, query:, check:, record:, type: :fail, exception: nil)
+
+                      checker_counts.increment(result.type)
+                      break if checker_counts.reached_blanket_failure?
+
+                      result
+                    rescue *PASSTHROUGH_EXCEPTIONS
+                      raise
+                    rescue => e
+                      Error.new(checker:, query:, check:, record:, type: :exception, exception: e)
+                    end
                   end
-                end
-                @yields.raise_unless_all_reporters_yielded(hook: :around_check)
+                  @yields.raise_unless_all_reporters_yielded(hook: :around_check)
 
-                # if the first 20 error out, halt the check method, it's probably buggy
-                if checker_counts.reached_blanket_failure?
-                  checker_counts.increment :blanket
+                  # if the first 20 error out, halt the check method, it's probably buggy
+                  if checker_counts.reached_blanket_failure?
+                    checker_counts.increment :blanket
 
-                  error = Error.new(checker:, query:, check: nil, record: nil, type: :blanket, exception: nil)
-                  @reporters.each { it.halt(checker:, query:, check: nil, error:) }
+                    error = Error.new(checker:, query:, check: nil, record: nil, type: :blanket, exception: nil)
+                    @reporters.each { it.halt(checker:, query:, check: nil, error:) }
 
-                  break
+                    break
+                  end
                 end
+                nil # yield nothing around_query
               end
+              @yields.raise_unless_all_reporters_yielded(hook: :around_query)
             rescue *PASSTHROUGH_EXCEPTIONS
               raise
             rescue => e
@@ -160,6 +164,7 @@ module Recheck
         @total_counts
       end
       @yields.raise_unless_all_reporters_yielded(hook: :around_run)
+      @total_counts
     end
   end
 end

data/lib/recheck/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Recheck
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/template/regression_checker_sample.rb

@@ -0,0 +1,206 @@
+# Recheck Checker API Documentation
+#
+# This file documents the complete Checker API for Recheck.
+# Use this as a reference when creating your own checkers.
+
+# All checkers must inherit from Recheck::Checker::Base to be registered
+class SampleChecker < Recheck::Checker::Base
+  #
+  # CHECKER LIFECYCLE AND HOOKS
+  # ==========================
+  #
+  # Checkers have a simple lifecycle with four hooks:
+  #
+  # 1. initialize - Optional setup
+  # 2. query_* methods - Required to fetch records to check
+  # 3. check_* methods - Required to validate each record
+  # 4. Metadata methods - Optional for routing and prioritization
+  #
+
+  # Hook 1: initialize (optional)
+  # ----------------------------
+  # Use initialize to set up any resources needed by your checks.
+  # This runs once when the checker is instantiated.
+  def initialize
+    # You can:
+    # - Connect to external services
+    # - Load reference data
+    # - Set up caches or other shared resources
+    # - Configure the checker based on environment
+
+    @external_service = ExternalService.new(api_key: ENV["API_KEY"])
+    @reference_data = load_reference_data
+    @cache = {}
+  end
+
+  # You can use helper methods to organize your code
+  def load_reference_data
+    # Load data from a file, database, or API
+    # This is just a helper method, not part of the Checker API
+    {}
+  end
+
+  # Hook 2: query_* methods (one required)
+  # ---------------------------------
+  # At least one query method is required. Query methods must:
+  # - Start with "query" (or they won't be detected)
+  # - Return an Enumerable of records to check
+  # - Be efficient (they often run against production databases)
+
+  # Basic query method - returns all records of a type
+  def query
+    # The simplest query just returns all records
+    # Use find_each with ActiveRecord for batching
+    Model.find_each
+  end
+
+  # You can have multiple query methods to:
+  # - Check different record types
+  # - Optimize performance with targeted queries
+  # - Focus on specific subsets of data
+  def query_recent
+    # Focus on recently created/updated records
+    Model.where("updated_at > ?", 1.day.ago).find_each
+  end
+
+  def query_problematic
+    # Target records that might have issues
+    Model.where(status: "error")
+      .or(Model.where(processed_at: nil))
+      .includes(:related_records) # Eager load associations
+      .find_each
+  end
+
+  # Query methods can return any Enumerable, not just ActiveRecord
+  def query_external_data
+    # You can check data from external sources
+    @external_service.fetch_records.map do |record|
+      # Transform external data if needed
+      {id: record["id"], data: record["payload"]}
+    end
+  end
+
+  # Query methods can return arrays, hashes, or custom objects
+  def query_composite
+    # You can join data from multiple sources
+    [
+      {type: "config", value: AppConfig.settings},
+      {type: "status", value: SystemStatus.current}
+    ]
+  end
+
+  # Hook 3: check_* methods (one required)
+  # ---------------------------------
+  # Check methods must:
+  # - Start with "check_" (or they won't be detected)
+  # - Take a single record parameter
+  # - Return false/nil for failing records, anything else for passing
+
+  # Basic check - validates a single aspect of a record
+  def check_record_is_valid(record)
+    # The simplest check just calls ActiveRecord validations
+    # Returns false if invalid, true if valid
+    record.valid?
+  end
+
+  # Checks can implement complex business rules
+  def check_business_rule(record)
+    # Implement any business logic
+    # Return false/nil for failing records
+    if record.status == "completed" && record.completed_at.nil?
+      # This is a failing condition
+      return false
+    end
+
+    # Any non-false/nil return is considered passing
+    true
+  end
+
+  # Checks can integrate with external systems
+  def check_external_consistency(record)
+    # Check that record matches external system
+    external_data = @external_service.find(record.external_id)
+
+    # Return false if inconsistent
+    return false if external_data.nil?
+    return false if external_data["status"] != record.status
+
+    # Return true if consistent
+    true
+  end
+
+  # Checks can automatically fix issues (use carefully!)
+  def check_and_fix(record)
+    # Check if there's an issue
+    if record.calculated_total != record.stored_total
+      # Fix the issue
+      record.stored_total = record.calculated_total
+      record.save!
+
+      # Log the fix
+      LoggingService.info("Fixed total for record #{record.id}")
+    end
+
+    # Return true since we've fixed the issue
+    true
+  end
+
+  # Checks can handle different record types from different queries
+  def check_config_is_valid(record)
+    # Handle records from query_composite
+    if record[:type] == "config"
+      # Check config settings
+      return record[:value].valid?
+    elsif record[:type] == "status"
+      # Check system status
+      return record[:value].ok?
+    end
+
+    # Skip records this check doesn't understand
+    true
+  end
+
+  #
+  # METADATA METHODS
+  # ===============
+  #
+  # These optional methods provide metadata about your checker
+  # for use by reporters and the Recheck runner.
+  #
+
+  # Team responsible for this checker
+  # Used by reporters to route notifications
+  def team
+    :data_integrity
+  end
+
+  # Priority of this checker
+  # Used by reporters to prioritize notifications
+  def priority
+    :high # :high, :medium, :low
+  end
+
+  # Tags for this checker
+  # Used for filtering and categorization
+  def tags
+    [:critical, :customer_facing]
+  end
+
+  # Documentation URL
+  # Link to runbook or documentation
+  def documentation_url
+    "https://internal-docs.example.com/data-integrity/sample-checker"
+  end
+
+  # Slack channel for notifications
+  # Used by SlackReporter
+  def slack_channel
+    "#data-alerts"
+  end
+
+  # Email recipients for notifications
+  # Perhaps used by EmailReporter
+  def email_recipients
+    ["data-team@example.com", "oncall@example.com"]
+  end
+end

data/template/reporter_sample.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+# Reporters are how you turn failing checks into emails, bug tracker tickets,
+# or any other useful notification or report. You can notify different teams
+# however they most "enjoy" hearing about bad data.
+
+class SampleReporter < Recheck::Reporter::Base
+  # Optional but strongly recommended: Provide help text that appears when running `recheck
+  # reporters`. This should briefly explain what your reporter does and any argument it takes.
+  def self.help
+    "A template reporter showing how to implement your own custom reporter. Takes an optional argument."
+  end
+
+  # Optional: Initialize with the argument string from the command line.
+  # The arg is passed as a single string, or nil if no arg is provided
+  # Arguments:
+  # * arg: The string argument passed after the colon in the reporter specification
+  #   For example: `--reporter SampleReporter:api_key_123` -> `api_key_123`
+  def initialize(arg:)
+    # Process your argument here if needed
+    @config = arg || "default_config"
+  end
+
+  # Important: If you define an around_ hook, it must 'yield' to run the next step.
+  # A hook method's return value is not used.
+
+  # around_run: Fires around the entire run.
+  # This is a good place to set up resources, send summary emails, etc.
+  # Arguments:
+  # * checkers: Array of checker instances that will be run
+  def around_run(checkers: [])
+    # Setup before the run
+    start_time = Time.now
+
+    # yield returns: a CountStats about the entire run
+    # CountStats tracks counts of passes, failures, and other result types
+    # It provides methods like #all_pass?, #any_errors?, #summary, etc.
+    total_counts = yield
+
+    # Teardown/reporting after the run
+    duration = Time.now - start_time
+
+    # Example of how you might report results
+    if total_counts.any_errors?
+      puts "SampleReporter: Found errors in #{duration.round(2)}s: #{total_counts.summary}"
+      # In a real reporter, you might:
+      # - Send an email
+      # - Post to Slack
+      # - Create a ticket in your issue tracker
+      # - Log to a monitoring service
+    end
+
+    # Return the counts (optional)
+    total_counts
+  end
+
+  # around_checker: Fires around each checker.
+  # Arguments:
+  # * checker: The checker instance being run
+  # * queries: Array of query method names defined on the checker
+  # * checks: Array of check method names defined on the checker
+  def around_checker(checker:, queries: [], checks: [])
+    # Before running this checker
+    checker_name = checker.class.name
+
+    # yields returns a CountStats for the checker
+    counts = yield
+
+    # After running this checker
+    if counts.any_errors?
+      puts "SampleReporter: Checker #{checker_name} had issues: #{counts.summary}"
+      # In a real reporter, you might group errors by checker
+    end
+  end
+
+  # around_query: Fires around each query
+  # This is useful for tracking which queries are slow or problematic
+  # Arguments:
+  # * checker: The checker instance being run
+  # * query: The name of the query method being executed
+  # * checks: Array of check method names that will be run against query results
+  def around_query(checker:, query:, checks: [])
+    # Before running this query
+    query_start = Time.now
+
+    # yield does not return anything for this hook
+    yield
+
+    # After running this query
+    query_duration = Time.now - query_start
+    if query_duration > 5 # seconds
+      puts "SampleReporter: Slow query #{checker.class.name}##{query} took #{query_duration.round(2)}s"
+    end
+  end
+
+  # The around_check and halt hooks both receive one of two result objects.
+  #
+  # Recheck::Pass: A successful check.
+  # Attributes:
+  #   #type: always :pass
+  #
+  # Recheck::Error: A failed check.
+  # Attributes:
+  #   #type: One of the following symbols
+  #     fail: The check returned a falsey value
+  #     exception: The check raised an exception
+  #     blanket: The first 20 checks all failed or raised; the runner skips
+  #     no_query_methods: The checker does not define a query_methods
+  #     no_queries: The checker defines query_methods, but did not return any
+  #     no_check_methods: The checker does not define a check_methods
+  #     no_checks: The checker defines check_methods, but did not return any
+  #   #checker: Checker instance
+  #   #query: Query method name
+  #   #check: Check method name
+  #   #record: The record being checked
+  #   #exception: rescued Exception
+  #
+
+  # around_check: Fires for each call to a check_ method on each record
+  # This is where you can collect detailed information about failures.
+  # Arguments:
+  # * checker: The checker instance being run
+  # * query: The name of the query method that produced this record
+  # * check: The name of the check method being executed
+  # * record: The individual record being checked
+  def around_check(checker:, query:, check:, record:)
+    # Returns a result object, see comment above
+    result = yield
+
+    # Process the result
+    if result.is_a?(Recheck::Error)
+      case result.type
+      when :fail
+        record_id = fetch_record_id(result.record)
+        puts "SampleReporter: #{checker.class.name}##{check} failed for record: #{record_id}"
+      when :exception
+        puts "SampleReporter: #{checker.class.name}##{check} raised exception: #{result.exception.message}"
+      end
+
+      # In a real reporter, you might:
+      # - Collect failures to report in a batch
+      # - Send immediate alerts for critical failures
+      # - Log to a monitoring system
+    end
+  end
+
+  # halt: Called when a checker is halted due to an error.
+  # This is useful for reporting fatal errors that prevent checks from running
+  # Arguments:
+  # * checker: The checker instance that was halted
+  # * query: The name of the query method that was running (if any)
+  # * check: The name of the check method that was running (if any)
+  # * error: The error result, see comment above around_check
+  def halt(checker:, query:, error:, check: nil)
+    puts "SampleReporter: Halted #{checker.class.name}##{query} due to #{error.type}"
+
+    # In a real reporter, you might:
+    # - Send an urgent alert
+    # - Create a high-priority ticket
+    # - Log a critical error
+  end
+
+  # You can add any helper methods, include modules, etc.
+
+  # Example of a helper method to format data for reporting
+  def format_error_message(error)
+    case error.type
+    when :fail
+      "Record is invalid"
+    when :exception
+      "Exception occurred: #{error.exception.message}"
+    when :blanket
+      "Blanket failure - first 20 checks all failed"
+    else
+      "Other error: #{error.type}"
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: recheck
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Peter Bhat Harkins
@@ -71,6 +71,8 @@ files:
 - lib/recheck/runner.rb
 - lib/recheck/version.rb
 - template/recheck_helper.rb
+- template/regression_checker_sample.rb
+- template/reporter_sample.rb
 - template/site/dns_checker.rb
 - template/site/tls_checker.rb
 - template/site/whois_checker.rb