fix: Add class comments to fix issues

Author: danielaboost

Gemfile

@@ -13,3 +13,13 @@ group :development do
   gem 'rubocop-rake'
   gem 'rubocop-rspec'
 end
+
+group :development, :test do
+  gem 'combustion', '~> 1.3'
+  gem 'rspec', '~> 3.13'
+  gem 'rspec-rails', '~> 6.1'
+end
+
+group :test do
+  gem 'database_cleaner-mongoid', '~> 2.0'
+end

app/controllers/consyncful/webhook_controller.rb

@@ -1,6 +1,25 @@
 # frozen_string_literal: true
 
 module Consyncful
+  # The Consyncful::WebhookController is responsible for handling incoming
+  # webhook requests that can trigger synchronization jobs within Consyncful.
+  #
+  # Features:
+  # - Only responds to requests if `sync_mode` is configured as `:webhook`.
+  # - Optionally requires HTTP Basic authentication if
+  #   `webhook_authentication_required` is enabled in configuration.
+  # - Exposes a single endpoint (`trigger_sync`) that signals a sync process
+  #   through `Consyncful::Sync.signal_webhook!`.
+  #
+  # Security:
+  # - Uses `ActionController::HttpAuthentication::Basic` to enforce
+  #   authentication when enabled.
+  # - Compares provided credentials with configured values using
+  #   `ActiveSupport::SecurityUtils.secure_compare` to prevent timing attacks.
+  #
+  # Responses:
+  # - Returns `404 Not Found` if webhooks are not enabled.
+  # - Returns `202 Accepted` after signaling a sync.
   class WebhookController < ActionController::API
     include ActionController::HttpAuthentication::Basic::ControllerMethods
     before_action :authenticate, if: -> { Consyncful.configuration.webhook_authentication_required && use_webhooks? }

consyncful.gemspec

@@ -31,20 +31,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  #
-  # Runtime dependencies
-  #
   spec.add_dependency 'contentful', ['>=2.11.1', '<3.0.0']
   spec.add_dependency 'hooks', '>=0.4.1'
   spec.add_dependency 'mongoid', '>=7.0.2'
   spec.add_dependency 'rainbow'
   spec.metadata['rubygems_mfa_required'] = 'true'
-
-  #
-  # Development / test dependencies (installed in CI because Gemfile has `gemspec`)
-  #
-  spec.add_development_dependency "rspec", "~> 3.13"
-  spec.add_development_dependency "rspec-rails", "~> 6.1"
-  spec.add_development_dependency "combustion", "~> 1.3"
-  spec.add_development_dependency "database_cleaner-mongoid", "~> 2.0"
 end

lib/consyncful/configuration.rb

@@ -2,6 +2,18 @@
 
 # Handles Rails configurations for Consyncful
 module Consyncful
+  # Provides configuration options for Consyncful, including:
+  # - Contentful API client and sync options
+  # - MongoDB client and collection settings
+  # - Locale and content tag filtering
+  # - Sync mode (poll or webhook)
+  # - Webhook authentication credentials
+  #
+  # This class is typically accessed and customized via
+  #   Consyncful.configure do |config|
+  #     config.locale = 'en-NZ'
+  #     config.mongo_collection = 'my_models'
+  #   end
   class Configuration
     attr_accessor :contentful_client_options,
                   :contentful_sync_options,
@@ -16,6 +28,7 @@ class Configuration
                   :webhook_user,
                   :webhook_password
 
+    # rubocop:disable Metrics/MethodLength
     def initialize
       @sync_mode = :poll
       @contentful_client_options = {}
@@ -31,6 +44,7 @@ def initialize
       @webhook_user = nil
       @webhook_password = nil
     end
+    # rubocop:enable Metrics/MethodLength
 
     def initial_sync_options
       options = { initial: true }

lib/consyncful/engine.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 module Consyncful
+  # Rails engine for Consyncful.
+  #
+  # This isolates the Consyncful namespace and allows the gem
+  # to provide its own routes, controllers, and configuration
+  # within a Rails application without clashing with the host app.
   class Engine < ::Rails::Engine
     isolate_namespace Consyncful
   end

lib/consyncful/sync_runner.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
-# lib/consyncful/sync_runner.rb
 module Consyncful
+  # The SyncRunner is responsible for continuously executing Contentful sync
+  # jobs at a configurable interval or in response to webhook signals.
+  #
+  # Modes:
+  # - :poll    — runs the sync every N seconds (default 15)
+  # - :webhook — waits for webhook signals and triggers a sync when received
+  #
+  # Behavior:
+  # - Starts with an initial sync (`Consyncful::Sync.latest.run`).
+  # - In poll mode, sleeps for the configured interval and then re-runs sync.
+  # - In webhook mode, listens for webhook signals and runs sync immediately.
   class SyncRunner
     DEFAULT_INTERVAL = 15
     VALID_MODES = %i[poll webhook].freeze
@@ -17,9 +27,7 @@ def run
 
       loop do
         sleep(@interval)
-        if @mode == :poll || Consyncful::Sync.consume_webhook_signal!
-          current_sync.run
-        end
+        current_sync.run if @mode == :poll || Consyncful::Sync.consume_webhook_signal!
       end
     end
 

spec/controllers/consyncful/webhook_controller_spec.rb

@@ -1,83 +1,84 @@
 # frozen_string_literal: true
-require "rails_helper"
 
-RSpec.describe "Consyncful::WebhookController", type: :request do
+require 'rails_helper'
+
+RSpec.describe 'Consyncful::WebhookController', type: :request do
   let(:config) do
     # Provide a simple configuration double with the fields used by the controller
     instance_double(
-      "Consyncful::Configuration",
+      'Consyncful::Configuration',
       sync_mode: sync_mode,
       webhook_authentication_required: auth_required,
-      webhook_user: "user1",
-      webhook_password: "secret"
+      webhook_user: 'user1',
+      webhook_password: 'secret'
     )
   end
 
   before do
     allow(Consyncful).to receive(:configuration).and_return(config)
   end
 
-  describe "POST /consyncful/webhook" do
-    subject(:perform) { post "/consyncful/webhook", headers: headers }
+  describe 'POST /consyncful/webhook' do
+    subject(:perform) { post '/consyncful/webhook', headers: headers }
 
     let(:headers) { {} }
 
-    context "when sync mode is not :webhook" do
+    context 'when sync mode is not :webhook' do
       let(:sync_mode) { :poll }
       let(:auth_required) { false }
 
-      it "returns 404 Not Found" do
+      it 'returns 404 Not Found' do
         perform
         expect(response).to have_http_status(:not_found)
       end
     end
 
-    context "when sync mode is :webhook" do
+    context 'when sync mode is :webhook' do
       let(:sync_mode) { :webhook }
 
-      context "and authentication is not required" do
+      context 'and authentication is not required' do
         let(:auth_required) { false }
 
-        it "signals the sync and returns 202 Accepted" do
+        it 'signals the sync and returns 202 Accepted' do
           expect(Consyncful::Sync).to receive(:signal_webhook!)
           perform
           expect(response).to have_http_status(:accepted)
         end
       end
 
-      context "and authentication is required" do
+      context 'and authentication is required' do
         let(:auth_required) { true }
 
-        context "with no credentials" do
-          it "returns 401 Unauthorized" do
+        context 'with no credentials' do
+          it 'returns 401 Unauthorized' do
             perform
             expect(response).to have_http_status(:unauthorized)
           end
         end
 
-        context "with wrong credentials" do
+        context 'with wrong credentials' do
           let(:headers) do
             {
-              "HTTP_AUTHORIZATION" =>
-                ActionController::HttpAuthentication::Basic.encode_credentials("user1", "wrong")
+              'HTTP_AUTHORIZATION' =>
+                ActionController::HttpAuthentication::Basic.encode_credentials('user1', 'wrong')
             }
           end
 
-          it "returns 401 Unauthorized" do
+          it 'returns 401 Unauthorized' do
             perform
             expect(response).to have_http_status(:unauthorized)
           end
         end
 
-        context "with correct credentials" do
+        context 'with correct credentials' do
           let(:headers) do
             {
-              "HTTP_AUTHORIZATION" =>
-                ActionController::HttpAuthentication::Basic.encode_credentials("user1", "secret")
+              'HTTP_AUTHORIZATION' =>
+                ActionController::HttpAuthentication::Basic.encode_credentials('user1', 'secret')
             }
           end
 
-          it "signals the sync and returns 202 Accepted" do
+          it 'signals the sync and returns 202 Accepted' do
             expect(Consyncful::Sync).to receive(:signal_webhook!)
             perform
             expect(response).to have_http_status(:accepted)

spec/internal/config/routes.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 Rails.application.routes.draw do
-  mount Consyncful::Engine => "/consyncful"
-end
+  mount Consyncful::Engine => '/consyncful'
+end

spec/rails_helper.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
-ENV["RAILS_ENV"] ||= "test"
 
-require "bundler/setup"
-require "combustion"
-require "consyncful"
-require "consyncful/engine"
+ENV['RAILS_ENV'] ||= 'test'
+
+require 'bundler/setup'
+require 'combustion'
+require 'consyncful'
+require 'consyncful/engine'
 
 Combustion.initialize! :action_controller, :active_support
 
-require "rspec/rails"
+require 'rspec/rails'
 
 RSpec.configure do |config|
   config.use_active_record = false