thumbsy 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98dd99f1f66f7fe37f9255fc170210cad077aea204dc5f5d664a43935c6194a1
+  data.tar.gz: d7c9d1404bf89c83a8d0589765dac86158a86670867ebcf162b823b47cc2b1b4
+SHA512:
+  metadata.gz: bc37f9a43af3fb528c384c9b734b135bdd84954a6e01916e3da44af9b9829e2d13314eb51dc39691234134d45ba2ddb99712d2761407d2bd06a682a36167f58d
+  data.tar.gz: 458119986851681bcd1d29718323fe0351f0ebad2c2a4917f443b5ae56631a6aa45ffd4cd03b571caa094dd17198db0338d1cbe2362909db78ecc7dbecb18a9e

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2024 Thumbsy
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,299 @@
+# Thumbsy - Rails Voting Gem
+
+[![CI](https://github.com/healthhive/thumbsy/workflows/CI/badge.svg)](https://github.com/healthhive/thumbsy/actions)
+
+A Rails gem for adding thumbs up/down voting functionality with comments and feedback_options.
+Includes optional JSON API endpoints.
+
+**Note**: This library was created with Claude Sonnet 4, based on the requirements specified in ORIGINAL_PROMPT.txt
+
+## Requirements
+
+- **Ruby**: 3.3.0 or newer
+- **Rails**: 7.1, 7.2, or 8.0+
+- **Database**: SQLite, PostgreSQL, or MySQL (any ActiveRecord-supported database)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'thumbsy'
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+Run the install generator:
+
+```sh
+# Uses default feedback_options (like, dislike, funny)
+rails generate thumbsy:install
+
+# Or specify custom feedback_options
+rails generate thumbsy:install --feedback=helpful,unhelpful,spam
+```
+
+**Note:**
+- The `--feedback` option is **optional**. If omitted, the default feedback_options are `like`, `dislike`, and `funny`.
+- If you pass `--feedback` but do not provide any values (e.g., `--feedback` or `--feedback ""`), the generator will fail with an error.
+
+## Basic Setup (ActiveRecord only)
+
+```bash
+# Generate migration and basic functionality
+rails generate thumbsy:install
+rails db:migrate
+```
+
+### ID Type Configuration
+
+Thumbsy supports different primary key types to match your application's needs:
+
+```bash
+# Default ID type is UUID (recommended for distributed systems)
+rails generate thumbsy:install
+
+# Use big integers (recommended for high-volume applications)
+rails generate thumbsy:install --id_type=bigint
+```
+
+The ID type affects:
+- Primary key of the `thumbsy_votes` table
+- Foreign key references to votable and voter models
+
+### Custom Feedback Options
+
+You can customize the feedback_options when generating the model:
+
+```bash
+# Use default feedback_options (like, dislike, funny)
+rails generate thumbsy:install
+
+# Use custom feedback_options
+rails generate thumbsy:install --feedback=helpful,unhelpful,spam
+```
+
+```ruby
+# Add to your models
+class Book < ApplicationRecord
+  votable  # Can receive votes
+end
+
+class User < ApplicationRecord
+  voter    # Can vote on other models
+end
+
+# Usage
+@book.vote_up(@user)
+@book.vote_down(@user, comment: 'Not helpful', feedback_options: ['unhelpful'])
+
+# Querying
+@book.votes_count           # Total votes
+@book.up_votes_count        # Up votes
+@book.voted_by?(@user)      # Check if user voted
+@book.voters                # All voters
+Book.with_votes             # Books with votes
+
+# Feedback options
+@book.vote_up(@user, feedback_options: ['helpful'])
+@book.vote_down(@user, feedback_options: ['spam'])
+```
+
+## Optional: JSON API Endpoints
+
+If you need API endpoints for mobile apps or SPAs:
+
+```bash
+# Generate API configuration
+rails generate thumbsy:api
+```
+
+This adds:
+
+- RESTful JSON endpoints
+- Authentication integration
+- Authorization support
+- Flexible routing
+
+### API Routes
+
+- `POST /:votable_type/:votable_id/vote_up` - Vote up
+- `POST /:votable_type/:votable_id/vote_down` - Vote down
+- `GET /:votable_type/:votable_id/vote` - Get current user's vote details
+- `DELETE /:votable_type/:votable_id/vote` - Remove vote
+
+### API Usage
+
+```bash
+# Vote up on a post
+curl -X POST /api/v1/books/1/vote_up \
+  -H "Authorization: Bearer TOKEN" \
+  -d '{"comment": "Great book!", "feedback_options": ["helpful"]}'
+
+# Get current user's vote details
+curl -X GET /api/v1/books/1/vote \
+  -H "Authorization: Bearer TOKEN"
+```
+
+### API Module Access
+
+The `Thumbsy::Api` module is automatically available when you require the gem:
+
+```ruby
+require 'thumbsy'
+
+# API module is immediately accessible
+Thumbsy::Api.configure do |config|
+  config.require_authentication = false
+end
+
+# Load full API functionality (controllers and routes)
+Thumbsy.load_api!  # Call this in config/application.rb or an initializer
+```
+
+### API Configuration
+
+```ruby
+# config/initializers/thumbsy_api.rb
+Thumbsy::Api.configure do |config|
+  # Works with any authentication system
+  config.authentication_method = proc do
+    authenticate_user! # Your auth method
+  end
+
+  config.current_voter_method = proc do
+    current_user # Your current user method
+  end
+end
+```
+
+## Core Features
+
+✅ **ActiveRecord Integration**: Simple `votable` and `voter` declarations
+
+✅ **Polymorphic Design**: Any model can vote on any other model
+
+✅ **Comment Support**: Optional comments on every vote
+
+✅ **Feedback Options**: Customizable feedback_options (like, dislike, funny, etc.)
+
+✅ **Rich Queries**: Comprehensive scopes and helper methods
+
+✅ **Performance Optimized**: Proper database indexes
+
+✅ **Optional API**: Add JSON endpoints only if needed
+
+✅ **Flexible Authentication**: Works with Devise, JWT, API keys, etc.
+
+✅ **Test Suite**: Complete RSpec tests included
+
+✅ **Gem-Provided Model**: Model is provided directly by the gem for consistency
+
+## Use Cases
+
+### ActiveRecord Only
+
+- Traditional Rails apps with server-rendered views
+- Internal voting systems
+- Simple like/dislike functionality
+- Content moderation with feedback_options
+
+### With API
+
+- Mobile applications
+- Single Page Applications (SPAs)
+- Microservices architecture
+- Third-party integrations
+
+## Documentation
+
+- **Basic Usage**: This README
+- **API Guide**: [docs/api-guide.md](docs/api-guide.md) - Complete API documentation and integration examples
+- **Architecture Guide**: [docs/architecture-guide.md](docs/architecture-guide.md) - Technical details and design decisions
+- **Release Guide**: [docs/release-guide.md](docs/release-guide.md) - How to release new versions to RubyGems
+
+## Releases
+
+Thumbsy uses automated releases with semantic versioning. To release a new version:
+
+### Quick Release
+
+```bash
+# Automatically determine version bump from commits
+ruby script/bump_version.rb
+
+# Or manually specify bump type
+ruby script/bump_version.rb minor
+```
+
+### Release Process
+
+1. **Version Bump**: The script automatically updates version files
+2. **Git Tag**: Creates a version tag (e.g., `v1.1.0`)
+3. **Push Tag**: `git push origin v1.1.0`
+4. **Automated Release**: CI/CD pipeline publishes to RubyGems and creates GitHub release
+
+### Version Bumping Rules
+
+- **Patch** (`1.0.0` → `1.0.1`): Bug fixes, docs, performance
+- **Minor** (`1.0.0` → `1.1.0`): New features (backward compatible)
+- **Major** (`1.0.0` → `2.0.0`): Breaking changes
+
+See [docs/release-guide.md](docs/release-guide.md) for complete release documentation.
+
+## Development & Testing
+
+### Running Tests Locally
+
+```bash
+# Run the full test suite
+bundle exec rspec
+
+# Run tests with coverage report
+COVERAGE=true bundle exec rspec
+
+# Run specific test files
+bundle exec rspec spec/thumbsy_spec.rb
+bundle exec rspec spec/api_integration_spec.rb
+```
+
+### Testing Across Rails Versions
+
+Thumbsy is tested against multiple Rails versions (7.1, 7.2, 8.0) and Ruby versions (3.3, 3.4):
+
+```bash
+
+RAILS_VERSION=8.0 bundle update rails
+RAILS_VERSION=8.0 bundle exec rspec
+
+# Use the automated test script
+ruby script/test_rails_versions.rb
+```
+
+### Continuous Integration
+
+Our CI pipeline automatically tests all supported combinations:
+
+- **Ruby versions**: 3.3, 3.4
+- **Rails versions**: 7.1, 7.2, 8.0
+- **Total combinations**: 9 test matrices
+- **Coverage requirement**: 78%+
+
+All tests must pass across all combinations before any changes are merged.
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for your changes
+4. Ensure all tests pass: `bundle exec rspec`
+5. Test across Rails versions: `ruby script/test_rails_versions.rb`
+6. Submit a pull request
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must gem install bundler and bundle install to run rake tasks"
+end
+
+require "rdoc/task"
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "Thumbsy"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/config/database.yml

@@ -0,0 +1,47 @@
+# Database configuration for Thumbsy gem testing
+default: &default
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  timeout: 5000
+
+development:
+  <<: *default
+  adapter: sqlite3
+  database: db/development.sqlite3
+
+test:
+  <<: *default
+  adapter: sqlite3
+  database: db/test.sqlite3
+
+# PostgreSQL configuration for CI testing
+test_postgresql:
+  <<: *default
+  adapter: postgresql
+  encoding: unicode
+  database: thumbsy_test
+  username: <%= ENV.fetch("POSTGRES_USER", "postgres") %>
+  password: <%= ENV.fetch("POSTGRES_PASSWORD", "postgres") %>
+  host: <%= ENV.fetch("POSTGRES_HOST", "localhost") %>
+  port: <%= ENV.fetch("POSTGRES_PORT", 5432) %>
+
+# MySQL configuration for CI testing
+test_mysql:
+  <<: *default
+  adapter: mysql2
+  encoding: utf8mb4
+  database: thumbsy_test
+  username: <%= ENV.fetch("MYSQL_USER", "root") %>
+  password: <%= ENV.fetch("MYSQL_PASSWORD", "root") %>
+  host: <%= ENV.fetch("MYSQL_HOST", "localhost") %>
+  port: <%= ENV.fetch("MYSQL_PORT", 3306) %>
+
+# SQLite configuration for CI testing
+test_sqlite:
+  <<: *default
+  adapter: sqlite3
+  database: db/test.sqlite3
+
+production:
+  <<: *default
+  adapter: sqlite3
+  database: db/production.sqlite3

data/lib/generators/thumbsy/api_generator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Thumbsy
+  module Generators
+    class ApiGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Generate Thumbsy API configuration and routes"
+
+      def create_api_initializer
+        initializer_path = "config/initializers/thumbsy.rb"
+        require_line = "require 'thumbsy/api'"
+        load_line = "Thumbsy::Api.load!"
+        insert_lines = "# Load Thumbsy API if you want to use the API endpoints\n#{require_line}\n#{load_line}\n\n"
+
+        if File.exist?(initializer_path)
+          content = File.read(initializer_path)
+          if content.include?(require_line) && content.include?(load_line)
+            say "API require and load lines already present in #{initializer_path}"
+          else
+            new_content = insert_lines + content
+            File.write(initializer_path, new_content)
+            say "Added API require and load lines to #{initializer_path}"
+          end
+        else
+          create_file initializer_path, insert_lines
+          say "Created #{initializer_path} with API require and load lines"
+        end
+      end
+
+      def add_api_require
+        inject_into_file "config/application.rb", after: "require \"rails/all\"\n" do
+          "require \"thumbsy/api\"\n"
+        end
+      end
+
+      def add_routes
+        route_content = <<~RUBY
+          # Thumbsy API routes
+          mount Thumbsy::Api::Engine => "/api/v1", as: :thumbsy_api
+        RUBY
+
+        inject_into_file "config/routes.rb", route_content, after: "Rails.application.routes.draw do\n"
+      end
+
+      def show_instructions
+        say "Thumbsy API has been configured!"
+        say ""
+        say "Next steps:"
+        say "1. Configure authentication in config/initializers/thumbsy_api.rb"
+        say "2. API routes are mounted at /api/v1"
+        say "3. Test with: curl -X POST /api/v1/posts/1/vote_up"
+        say ""
+        say "See API_DOCUMENTATION.md for complete usage examples."
+      end
+    end
+  end
+end

data/lib/generators/thumbsy/install_generator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module Thumbsy
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path("../../../lib/generators/thumbsy/templates", __dir__)
+      desc "Installs Thumbsy and sets up ThumbsyVote support."
+
+      class_option :feedback, type: :array, desc: "Feedback options for votes (e.g. --feedback like dislike funny)"
+
+      def self.next_migration_number(path)
+        next_migration_number = current_migration_number(path) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      class_option :id_type, type: :string, default: :uuid, desc: "ID type for primary keys (uuid, bigint, or integer)"
+
+      def create_migration_file
+        @id_type = options[:id_type].to_sym
+
+        if options.key?(:feedback) && (options[:feedback].nil? || options[:feedback].empty?)
+          say "\nERROR: --feedback option must have at least one value if provided (e.g. --feedback=like,dislike)", :red
+          exit(1)
+        end
+        @feedback_options = options[:feedback]
+        migration_template "create_thumbsy_votes.rb", "db/migrate/create_thumbsy_votes.rb"
+      end
+
+      def create_initializer_file
+        return unless options[:feedback].present?
+
+        feedback_options = if options[:feedback].is_a?(Array)
+                             options[:feedback]
+                           else
+                             options[:feedback].to_s.split(",")
+                           end
+        feedback_options.map!(&:strip)
+        template "thumbsy.rb", "config/initializers/thumbsy.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+        say ""
+        say "Optional: Generate API endpoints with:"
+        say "  rails generate thumbsy:api"
+      end
+    end
+  end
+end

data/lib/generators/thumbsy/templates/README

@@ -0,0 +1,56 @@
+===============================================================================
+
+Thumbsy has been installed!
+
+Next steps:
+
+1. Run the migration:
+   rails db:migrate
+
+2. Add thumbsy methods to your models:
+
+   # For models that can be voted on:
+   class Post < ApplicationRecord
+     votable
+   end
+
+   # For models that can vote:
+   class User < ApplicationRecord
+     voter
+   end
+
+3. Usage examples:
+
+   # Voting
+   @post.vote_up(@user)
+   @post.vote_down(@user, comment: "Not helpful")
+
+   # Or from voter perspective:
+   @user.vote_up_for(@post)
+   @user.vote_down_for(@post, comment: "Great post!")
+
+   # Checking votes
+   @post.voted_by?(@user)
+   @post.up_voted_by?(@user)
+   @post.votes_count
+   @post.up_votes_count
+   @post.votes_score
+
+   # Getting voters
+   @post.voters
+   @post.up_voters
+   @post.down_voters
+
+   # Scopes
+   Post.with_votes
+   Post.with_up_votes
+   Post.with_down_votes
+   Post.with_comments
+
+   # Comments on votes
+   @post.votes_with_comments
+   @post.up_votes_with_comments
+
+For more information, visit: https://github.com/healthhive/thumbsy
+
+===============================================================================

data/lib/generators/thumbsy/templates/create_thumbsy_votes.rb

@@ -0,0 +1,20 @@
+class CreateThumbsyVotes < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :thumbsy_votes, id: :<%= @id_type %> do |t|
+      t.references :votable, null: false, type: :<%= @id_type %>, polymorphic: true, index: false
+      t.references :voter, null: false, type: :<%= @id_type %>, polymorphic: true, index: false
+      t.boolean :vote, null: false, default: false
+      t.text :comment
+<% if defined?(@feedback_options) && @feedback_options.present? %>
+      t.text :feedback_options, default: <%= [].to_yaml.inspect %>
+<% end %>
+      t.timestamps null: false
+    end
+
+    add_index :thumbsy_votes, [:votable_type, :votable_id, :voter_type, :voter_id],
+      unique: true, name: "index_thumbsy_votes_on_voter_and_votable"
+
+    add_index :thumbsy_votes, [:votable_type, :votable_id, :vote]
+    add_index :thumbsy_votes, [:voter_type, :voter_id, :vote]
+  end
+end

data/lib/generators/thumbsy/templates/thumbsy.rb

@@ -0,0 +1,24 @@
+# Thumbsy Configuration
+# All Thumbsy and Thumbsy API settings are centralized here.
+
+Thumbsy.configure do |config|
+  config.feedback_options = %w[unclear confusing incorrect_info other]
+
+  config.api do |api_config|
+    # Uncomment and customize the following as needed:
+
+    # Authentication settings
+    # api_config.require_authentication = true
+
+    # Example for Devise:
+    # api_config.authentication_method = proc { authenticate_user! }
+    # api_config.current_voter_method = proc { current_user }
+
+    # Authorization (optional)
+    # api_config.require_authorization = true
+    # api_config.authorization_method = proc { |votable, voter| ... }
+
+    # Custom voter serialization for API responses
+    # api_config.voter_serializer = proc { |voter| { id: voter.id, ... } }
+  end
+end

data/lib/generators/thumbsy/templates/thumbsy_api.rb

@@ -0,0 +1,75 @@
+# Thumbsy API Configuration
+# Configure the voting API to work with your authentication system
+
+require 'thumbsy/api'
+require 'thumbsy/api/engine'
+
+# Load API components
+Thumbsy::Api.load!
+
+Thumbsy::Api.configure do |config|
+  # Authentication settings
+  config.require_authentication = true
+
+  # Define how to authenticate users
+  # Example for Devise:
+  config.authentication_method = proc do
+    authenticate_user! # Your authentication method
+  end
+
+  # Define how to get the current voter
+  # Example for Devise:
+  config.current_voter_method = proc do
+    current_user # Your current user method
+  end
+
+  # Authorization (optional)
+  # config.require_authorization = true
+  # config.authorization_method = proc do |votable, voter|
+  #   # Return true/false for permission to vote
+  #   case votable.class.name
+  #   when "Book"
+  #     votable.published? && !votable.archived?
+  #   when "Comment"
+  #     votable.@book.published? && voter.can_vote?
+  #   else
+  #     true
+  #   end
+  # end
+
+  # Custom voter serialization for API responses
+  # config.voter_serializer = proc do |voter|
+  #   {
+  #     id: voter.id,
+  #     name: voter.name,
+  #     avatar: voter.avatar.attached? ? rails_blob_url(voter.avatar) : nil
+  #   }
+  # end
+
+  # Vote model name (if you want to customize)
+  # config.vote_model_name = "CustomVote"
+end
+
+# Examples for different authentication systems:
+
+# JWT Authentication:
+# config.authentication_method = proc do
+#   token = request.headers["Authorization"]&.split(" ")&.last
+#   @decoded_token = JWT.decode(token, Rails.application.secret_key_base).first
+#   @current_user = User.find(@decoded_token["user_id"])
+# rescue JWT::DecodeError
+#   head :unauthorized
+# end
+
+# API Key Authentication:
+# config.authentication_method = proc do
+#   api_key = request.headers["X-API-Key"]
+#   @current_user = User.find_by(api_key: api_key)
+#   head :unauthorized unless @current_user
+# end
+
+# Session-based Authentication:
+# config.authentication_method = proc do
+#   @current_user = User.find(session[:user_id]) if session[:user_id]
+#   head :unauthorized unless @current_user
+# end