vote_fu 0.0.11 → 2.0.1

data/lib/generators/vote_fu/install/templates/migration.rb.erb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class CreateVoteFuVotes < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :vote_fu_votes do |t|
+      # Polymorphic voter (User, Admin, etc.)
+      t.references :voter, polymorphic: true, null: false
+
+      # Polymorphic voteable (Post, Comment, etc.)
+      t.references :voteable, polymorphic: true, null: false
+
+      # Integer value: 1 for up, -1 for down, 1-5 for stars, etc.
+      t.integer :value, null: false, default: 1
+
+      # Optional scope for multiple voting contexts on same voteable
+      # Example: "quality", "helpfulness", etc.
+      t.string :scope
+
+      t.timestamps
+    end
+
+    # Unique constraint: one vote per voter per voteable per scope
+    add_index :vote_fu_votes,
+              %i[voter_type voter_id voteable_type voteable_id scope],
+              unique: true,
+              name: "idx_vote_fu_unique_vote"
+
+    # Index for querying all votes on a voteable
+    add_index :vote_fu_votes,
+              %i[voteable_type voteable_id],
+              name: "idx_vote_fu_voteable"
+
+    # Index for querying a voter's history
+    add_index :vote_fu_votes,
+              %i[voter_type voter_id created_at],
+              name: "idx_vote_fu_voter_history"
+
+    # Index for recent votes queries
+    add_index :vote_fu_votes, :created_at
+  end
+end

data/lib/generators/vote_fu/migration/migration_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module VoteFu
+  module Generators
+    class MigrationGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the VoteFu votes table migration"
+
+      def create_migration_file
+        migration_template(
+          "create_vote_fu_votes.rb.erb",
+          "db/migrate/create_vote_fu_votes.rb"
+        )
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

data/lib/generators/vote_fu/migration/templates/create_vote_fu_votes.rb.erb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+class CreateVoteFuVotes < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :vote_fu_votes do |t|
+      # Polymorphic voter (User, Admin, etc.)
+      t.references :voter, polymorphic: true, null: false
+
+      # Polymorphic voteable (Post, Comment, etc.)
+      t.references :voteable, polymorphic: true, null: false
+
+      # Integer value: 1 for up, -1 for down, 1-5 for stars, etc.
+      t.integer :value, null: false, default: 1
+
+      # Optional scope for multiple voting contexts on same voteable
+      t.string :scope
+
+      t.timestamps
+    end
+
+    # Unique constraint: one vote per voter per voteable per scope
+    add_index :vote_fu_votes,
+              %i[voter_type voter_id voteable_type voteable_id scope],
+              unique: true,
+              name: "idx_vote_fu_unique_vote"
+
+    # Index for querying all votes on a voteable
+    add_index :vote_fu_votes,
+              %i[voteable_type voteable_id],
+              name: "idx_vote_fu_voteable"
+
+    # Index for querying a voter's history
+    add_index :vote_fu_votes,
+              %i[voter_type voter_id created_at],
+              name: "idx_vote_fu_voter_history"
+
+    # Index for recent votes
+    add_index :vote_fu_votes, :created_at
+  end
+end

data/lib/vote_fu/algorithms/hacker_news.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module VoteFu
+  module Algorithms
+    # Hacker News ranking algorithm
+    #
+    # This algorithm heavily penalizes older content. Items decay
+    # rapidly based on age, making it suitable for fast-moving
+    # content feeds where freshness is paramount.
+    #
+    # Formula: Score = (P - 1) / (T + 2)^G
+    # Where:
+    #   P = points (plusminus score)
+    #   T = age in hours
+    #   G = gravity (default 1.8)
+    #
+    # @see https://medium.com/hacking-and-gonzo/how-hacker-news-ranking-algorithm-works-1d9b0cf2c08d
+    #
+    # @example
+    #   Post.all.sort_by { |p| p.hacker_news_score }.reverse
+    #
+    class HackerNews
+      # Calculate the Hacker News score
+      #
+      # @param voteable [ActiveRecord::Base] The voteable object
+      # @param gravity [Float] Decay rate (higher = faster decay, default 1.8)
+      # @return [Float] The score (higher = better)
+      def self.call(voteable, gravity: 1.8)
+        new(voteable, gravity: gravity).calculate
+      end
+
+      def initialize(voteable, gravity:)
+        @voteable = voteable
+        @gravity = gravity
+      end
+
+      def calculate
+        points = [@voteable.plusminus - 1, 0].max
+        age_hours = hours_since_creation
+
+        return 0.0 if age_hours.negative?
+
+        points / ((age_hours + 2)**@gravity)
+      end
+
+      private
+
+      def hours_since_creation
+        created_at = @voteable.try(:created_at) || Time.current
+        (Time.current - created_at) / 1.hour
+      end
+    end
+  end
+end

data/lib/vote_fu/algorithms/reddit_hot.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module VoteFu
+  module Algorithms
+    # Reddit's "Hot" ranking algorithm
+    #
+    # This algorithm balances popularity (vote score) with recency.
+    # Items with high scores rise quickly, but decay over time,
+    # allowing fresh content to surface.
+    #
+    # The formula uses logarithmic scaling for votes, so the first
+    # 10 votes have the same impact as the next 100, then 1000, etc.
+    # This prevents runaway popular items from dominating forever.
+    #
+    # @see https://medium.com/hacking-and-gonzo/how-reddit-ranking-algorithms-work-ef111e33d0d9
+    #
+    # @example
+    #   Post.all.sort_by(&:hot_score).reverse
+    #
+    class RedditHot
+      # Reddit's epoch (December 8, 2005)
+      EPOCH = Time.utc(2005, 12, 8, 7, 46, 43).to_i
+
+      # Calculate the hot score
+      #
+      # @param voteable [ActiveRecord::Base] The voteable object
+      # @param gravity [Float] Not used in Reddit's algorithm but kept for API consistency
+      # @return [Float] The hot score (higher = hotter)
+      def self.call(voteable, gravity: 1.8)
+        new(voteable).calculate
+      end
+
+      def initialize(voteable)
+        @voteable = voteable
+      end
+
+      def calculate
+        score = @voteable.plusminus
+        order = Math.log10([score.abs, 1].max)
+        sign = score <=> 0
+        seconds = epoch_seconds
+
+        # The score decays over time (45000 seconds ≈ 12.5 hours)
+        (sign * order + seconds / 45_000.0).round(7)
+      end
+
+      private
+
+      def epoch_seconds
+        created_at = @voteable.try(:created_at) || Time.current
+        created_at.to_i - EPOCH
+      end
+    end
+  end
+end

data/lib/vote_fu/algorithms/wilson_score.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module VoteFu
+  module Algorithms
+    # Wilson Score Confidence Interval for Bernoulli Parameter
+    #
+    # This algorithm provides the lower bound of a Wilson score confidence interval.
+    # It's excellent for ranking items by quality when you have binary ratings
+    # (up/down votes). Unlike simple averages, it accounts for statistical uncertainty
+    # when there are few votes.
+    #
+    # @see https://www.evanmiller.org/how-not-to-sort-by-average-rating.html
+    #
+    # @example
+    #   post.wilson_score # => 0.85 (high confidence it's good)
+    #
+    class WilsonScore
+      # Z-scores for common confidence levels
+      Z_SCORES = {
+        0.80 => 1.28,
+        0.85 => 1.44,
+        0.90 => 1.64,
+        0.95 => 1.96,
+        0.99 => 2.58
+      }.freeze
+
+      # Calculate the Wilson Score Lower Bound
+      #
+      # @param voteable [ActiveRecord::Base] The voteable object
+      # @param confidence [Float] Confidence level (0.80 to 0.99)
+      # @param scope [Symbol, nil] Optional voting scope
+      # @return [Float] Score from 0.0 to 1.0
+      def self.call(voteable, confidence: 0.95, scope: nil)
+        new(voteable, confidence: confidence, scope: scope).calculate
+      end
+
+      def initialize(voteable, confidence:, scope:)
+        @voteable = voteable
+        @z = Z_SCORES.fetch(confidence) { Z_SCORES[0.95] }
+        @scope = scope
+      end
+
+      def calculate
+        n = total_votes
+        return 0.0 if n.zero?
+
+        pos = positive_votes
+        phat = pos / n
+
+        # Wilson Score Interval lower bound formula
+        numerator = phat + (@z**2 / (2 * n)) -
+                    @z * Math.sqrt((phat * (1 - phat) + @z**2 / (4 * n)) / n)
+        denominator = 1 + @z**2 / n
+
+        (numerator / denominator).clamp(0.0, 1.0).round(6)
+      end
+
+      private
+
+      def total_votes
+        @voteable.votes_count(scope: @scope).to_f
+      end
+
+      def positive_votes
+        @voteable.votes_for(scope: @scope).to_f
+      end
+    end
+  end
+end

data/lib/vote_fu/concerns/karmatic.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module VoteFu
+  module Concerns
+    module Karmatic
+      extend ActiveSupport::Concern
+
+      # Default karma level thresholds
+      DEFAULT_LEVELS = {
+        0 => "Newcomer",
+        10 => "Contributor",
+        50 => "Active",
+        100 => "Trusted",
+        250 => "Veteran",
+        500 => "Expert",
+        1000 => "Legend"
+      }.freeze
+
+      class_methods do
+        # Configure karma calculation based on votes on owned content
+        #
+        # @example Simple karma from posts
+        #   class User < ApplicationRecord
+        #     has_many :posts
+        #     has_karma :posts
+        #   end
+        #
+        # @example With custom foreign key
+        #   class User < ApplicationRecord
+        #     has_many :articles, foreign_key: :author_id
+        #     has_karma :articles, as: :author
+        #   end
+        #
+        # @example With weighted karma (upvotes worth 1, downvotes worth -0.5)
+        #   class User < ApplicationRecord
+        #     has_karma :posts, weight: [1.0, 0.5]
+        #   end
+        #
+        # @example With time decay (votes older than 90 days worth less)
+        #   class User < ApplicationRecord
+        #     has_karma :posts, decay: { half_life: 90.days }
+        #   end
+        #
+        # @example With scoped karma
+        #   class User < ApplicationRecord
+        #     has_karma :posts, scope: :quality
+        #   end
+        #
+        # @param association [Symbol] The association name
+        # @param as [Symbol, nil] Custom foreign key name (without _id)
+        # @param weight [Float, Array<Float>] Weight(s) for karma calculation
+        # @param decay [Hash, nil] Time decay options (:half_life, :floor)
+        # @param scope [Symbol, nil] Only count votes with this scope
+        def has_karma(association, as: nil, weight: 1.0, decay: nil, scope: nil)
+          class_attribute :karma_sources, default: [] unless respond_to?(:karma_sources)
+          class_attribute :karma_levels, default: DEFAULT_LEVELS.dup unless respond_to?(:karma_levels)
+
+          foreign_key = as ? "#{as}_id" : "#{name.underscore}_id"
+          weights = Array(weight)
+
+          self.karma_sources = karma_sources + [{
+            association: association,
+            foreign_key: foreign_key,
+            positive_weight: weights[0].to_f,
+            negative_weight: weights[1]&.to_f || weights[0].to_f,
+            decay: decay,
+            scope: scope
+          }]
+
+          include VoteFu::Concerns::Karmatic::InstanceMethods
+          extend VoteFu::Concerns::Karmatic::KarmaClassMethods
+        end
+
+        # Configure karma levels with custom thresholds
+        #
+        # @example Custom levels
+        #   class User < ApplicationRecord
+        #     set_karma_levels 0 => "Noob", 100 => "Pro", 1000 => "Elite"
+        #   end
+        def set_karma_levels(levels)
+          self.karma_levels = levels
+        end
+      end
+
+      module KarmaClassMethods
+        # Order users by karma (requires subquery, can be slow)
+        # For performance, consider adding a karma_cache column
+        def by_karma(direction = :desc)
+          if column_names.include?("karma_cache")
+            order(karma_cache: direction)
+          else
+            all.sort_by(&:karma).tap { |r| r.reverse! if direction == :desc }
+          end
+        end
+
+        # Users above a karma threshold
+        def with_karma_above(threshold)
+          if column_names.include?("karma_cache")
+            where("karma_cache > ?", threshold)
+          else
+            select { |u| u.karma > threshold }
+          end
+        end
+
+        # Users at or above a certain level
+        def with_karma_level(level_name)
+          threshold = karma_levels.key(level_name) || 0
+          with_karma_above(threshold - 1)
+        end
+      end
+
+      module InstanceMethods
+        # Calculate total karma from all sources
+        #
+        # @param force [Boolean] Bypass cache
+        # @return [Integer] Total karma points
+        def karma(force: false)
+          return 0 unless self.class.respond_to?(:karma_sources)
+
+          # Use cached value if available and not forcing recalculation
+          if !force && has_attribute?(:karma_cache) && karma_cache.present?
+            return karma_cache
+          end
+
+          calculated = self.class.karma_sources.sum do |source|
+            calculate_karma_for(source)
+          end.round
+
+          # Update cache if column exists
+          update_karma_cache(calculated) if has_attribute?(:karma_cache) && force
+
+          calculated
+        end
+
+        # Get karma for last N days only
+        #
+        # @param days [Integer] Number of days to look back
+        # @return [Integer]
+        def recent_karma(days: 30)
+          return 0 unless self.class.respond_to?(:karma_sources)
+
+          self.class.karma_sources.sum do |source|
+            calculate_karma_for(source, since: days.days.ago)
+          end.round
+        end
+
+        # Get karma breakdown by source
+        #
+        # @return [Array<Hash>] Array of {source:, value:, recent:} hashes
+        def karma_breakdown
+          return [] unless self.class.respond_to?(:karma_sources)
+
+          self.class.karma_sources.map do |source|
+            {
+              source: source[:association],
+              value: calculate_karma_for(source).round,
+              recent: calculate_karma_for(source, since: 30.days.ago).round
+            }
+          end
+        end
+
+        # Get karma for a specific source
+        #
+        # @param association [Symbol] The association name
+        # @return [Integer]
+        def karma_for(association)
+          source = self.class.karma_sources.find { |s| s[:association] == association }
+          return 0 unless source
+
+          calculate_karma_for(source).round
+        end
+
+        # Get the user's karma level
+        #
+        # @return [String] Level name
+        def karma_level
+          return "Unknown" unless self.class.respond_to?(:karma_levels)
+
+          current_karma = karma
+          level = "Unknown"
+
+          self.class.karma_levels.sort_by { |k, _| k }.each do |threshold, name|
+            level = name if current_karma >= threshold
+          end
+
+          level
+        end
+
+        # Get progress to next karma level
+        #
+        # @return [Hash] { current_level:, next_level:, progress:, karma_needed: }
+        def karma_progress
+          return nil unless self.class.respond_to?(:karma_levels)
+
+          current_karma = karma
+          sorted_levels = self.class.karma_levels.sort_by { |k, _| k }
+
+          current_threshold = 0
+          current_level = sorted_levels.first&.last || "Unknown"
+          next_threshold = nil
+          next_level = nil
+
+          sorted_levels.each_with_index do |(threshold, name), i|
+            if current_karma >= threshold
+              current_threshold = threshold
+              current_level = name
+              # Only set next level if there IS a next level
+              if i < sorted_levels.length - 1
+                next_data = sorted_levels[i + 1]
+                next_threshold = next_data[0]
+                next_level = next_data[1]
+              else
+                next_threshold = nil
+                next_level = nil
+              end
+            end
+          end
+
+          if next_threshold.nil?
+            # Already at max level
+            {
+              current_level: current_level,
+              next_level: nil,
+              progress: 100.0,
+              karma_needed: 0
+            }
+          else
+            range = next_threshold - current_threshold
+            progress_in_range = current_karma - current_threshold
+            {
+              current_level: current_level,
+              next_level: next_level,
+              progress: ((progress_in_range.to_f / range) * 100).round(1),
+              karma_needed: next_threshold - current_karma
+            }
+          end
+        end
+
+        # Check if user has at least a certain karma level
+        #
+        # @param level_name [String] The level name to check
+        # @return [Boolean]
+        def karma_level?(level_name)
+          return false unless self.class.respond_to?(:karma_levels)
+
+          threshold = self.class.karma_levels.key(level_name)
+          return false unless threshold
+
+          karma >= threshold
+        end
+
+        # Update the karma cache (call periodically or after votes)
+        def update_karma_cache(value = nil)
+          return unless has_attribute?(:karma_cache)
+
+          value ||= self.class.karma_sources.sum { |s| calculate_karma_for(s) }.round
+          update_column(:karma_cache, value)
+        end
+
+        # Alias for update_karma_cache
+        def recalculate_karma!
+          update_karma_cache
+          karma(force: true)
+        end
+
+        private
+
+        def calculate_karma_for(source, since: nil)
+          klass = source[:association].to_s.classify.constantize
+
+          # Get all voteables owned by this user
+          voteable_ids = klass.where(source[:foreign_key] => id).pluck(:id)
+          return 0.0 if voteable_ids.empty?
+
+          # Build votes query
+          votes = VoteFu::Vote.where(
+            voteable_type: klass.name,
+            voteable_id: voteable_ids
+          )
+
+          # Apply scope filter if specified
+          votes = votes.with_scope(source[:scope]) if source[:scope]
+
+          # Apply time filter if specified
+          votes = votes.where(created_at: since..) if since
+
+          # If decay is enabled, calculate weighted sum
+          if source[:decay]
+            calculate_decayed_karma(votes, source)
+          else
+            upvotes = votes.up.count
+            downvotes = votes.down.count
+            (upvotes * source[:positive_weight]) - (downvotes * source[:negative_weight])
+          end
+        end
+
+        def calculate_decayed_karma(votes, source)
+          half_life = source[:decay][:half_life] || 90.days
+          floor = source[:decay][:floor] || 0.1
+
+          now = Time.current
+          total = 0.0
+
+          # This is slow for many votes - consider caching
+          votes.find_each do |vote|
+            age = now - vote.created_at
+            decay_factor = [2**(-age / half_life), floor].max
+
+            weight = vote.up? ? source[:positive_weight] : -source[:negative_weight]
+            total += weight * decay_factor
+          end
+
+          total
+        end
+      end
+    end
+  end
+end