active_recall 2.0.2 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8709001a31591b453227c504d7f96684f924ac267d6c380ab8c5e6b86913b24c
-  data.tar.gz: 5efe33c2262b0b4549ff9f59c24ce504f65a798f5b2af1068bb10a419a7c182a
+  metadata.gz: b09e91a09c75f943e1bb2ced582d4520674053f5504f8e14fcfe370babbf4300
+  data.tar.gz: 9acaaad5775d5ff38694260e9d66983f97cd614ff5c52fde3bc67c7e13d14b01
 SHA512:
-  metadata.gz: f430431bf3ee4fd729c39a94915ad6b29750277631f5e85700684a464a71f633872033f69fcb763b01f3f2376afb0fbac7051b382ddc4843fe149502e2a9119a
-  data.tar.gz: '06837043f0e1290b99fea84f6ed317263f2155d10619e9ab08dac06bd6c9807703863848b1311216d08a23e3254176a03e76cc3c045fdd96f4e0de00db8d09bd'
+  metadata.gz: 6fffb380767376c2ad2b4bec163b508b2a32a03a33b05eebe755e80e6b0c825c1fd2a53133ae33e2582379e55329ef7a8b32dfbc3565a4fd4bca6ca2a93c994e
+  data.tar.gz: 982a9a742fb97e0cc9f0db89d6664f253c7f4534929b030d3ce78d9c3d164b08e2087cc31da79fbda4fb69b2e58e2bd05362a436d37743bebab574a1c529a78a

data/.github/workflows/tests.yml

@@ -19,10 +19,10 @@ jobs:
           - macos
           - ubuntu
         ruby:
-          - 3.0
-          - 3.1
           - 3.2
           - 3.3
+          - 3.4
+          - 4.0
         allow_failures:
           - false
     env:
@@ -37,14 +37,14 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
-          bundler-cache: true
+          bundler-cache: false
+      - name: Bundle Install
+        run: bundle install
       - name: Install Appraisal Dependencies
         run: bundle exec appraisal install
-      - name: Test with Rails 6.0
-        run: bundle exec appraisal rails-6-0 rake spec
-      - name: Test with Rails 6.1
-        run: bundle exec appraisal rails-6-1 rake spec
-      - name: Test with Rails 7.0
-        run: bundle exec appraisal rails-7-0 rake spec
       - name: Test with Rails 7.0
         run: bundle exec appraisal rails-7-0 rake spec
+      - name: Test with Rails 7.1
+        run: bundle exec appraisal rails-7-1 rake spec
+      - name: Test with Rails 8.0
+        run: bundle exec appraisal rails-8-0 rake spec

data/.gitignore

@@ -13,6 +13,6 @@ rdoc
 spec/reports
 test/tmp
 test/version_tmp
-tmp
 .idea/
 .DS_Store
+tmp

data/.tool-versions

@@ -1 +1 @@
-ruby 3.3.0
+ruby 3.4.8

data/Appraisals

@@ -1,15 +1,14 @@
-appraise "rails-6-0" do
-  gem "rails", "~> 6.0"
-end
-
-appraise "rails-6-1" do
-  gem "rails", "~> 6.1"
-end
-
 appraise "rails-7-0" do
   gem "rails", "~> 7.0"
+  gem "sqlite3", "~> 1.4"
 end
 
 appraise "rails-7-1" do
   gem "rails", "~> 7.1"
+  gem "sqlite3", "~> 1.4"
+end
+
+appraise "rails-8-0" do
+  gem "rails", "~> 8.0"
+  gem "sqlite3", ">= 2.1"
 end

data/CLAUDE.md

@@ -0,0 +1,194 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ActiveRecall is a Ruby gem that implements a spaced-repetition system (SRS) for ActiveRecord models. It allows treating arbitrary ActiveRecord models as flashcards with configurable scheduling algorithms. The gem is backwards-compatible with the okubo gem and requires Rails 6+ and Ruby 3+.
+
+## Common Commands
+
+### Testing
+```bash
+# Run all tests (PREFERRED - handles appraisal automatically)
+bin/spec
+
+# Run tests against a specific Rails version
+bin/spec rails-7-0
+bin/spec rails-7-1
+bin/spec rails-8-0
+
+# Note: Direct bundle exec commands may encounter sqlite3 version conflicts
+# The bin/spec wrapper handles this by using the appropriate appraisal gemfiles
+```
+
+### Linting
+```bash
+# Run StandardRB linter
+bin/lint
+# or
+bundle exec standardrb
+
+# Auto-fix issues
+bundle exec standardrb --fix
+```
+
+### Development Setup
+```bash
+# Install dependencies and set up database
+bin/setup
+
+# Launch interactive console
+bin/console
+```
+
+### Testing Against Multiple Rails Versions
+```bash
+# Generate gemfiles for different Rails versions (run after Gemfile changes)
+bundle exec appraisal install
+
+# Run tests against specific Rails version manually
+bundle exec appraisal rails-7-0 rake spec
+bundle exec appraisal rails-7-1 rake spec
+bundle exec appraisal rails-8-0 rake spec
+
+# Note: bin/spec runs tests against all Rails versions automatically
+# This is defined in the Appraisals file and creates separate gemfiles in gemfiles/
+```
+
+### Gem Management
+```bash
+# Build the gem
+bundle exec rake build
+
+# Install gem locally
+bundle exec rake install
+
+# Release new version (requires updating lib/active_recall/version.rb first)
+bundle exec rake release
+```
+
+## Architecture
+
+### Core Components
+
+1. **ActiveRecall::Base** (lib/active_recall/base.rb)
+   - Provides `has_deck` class method that makes any ActiveRecord model a deck owner
+   - Mixes in DeckMethods and ItemMethods when invoked
+   - Sets up polymorphic relationship between users and their decks
+
+2. **ActiveRecall::Deck** (lib/active_recall/models/deck.rb)
+   - Polymorphic model representing a collection of items to review
+   - Belongs to a user (polymorphic), has many items
+   - Key methods: `review`, `next`, `untested`, `failed`, `known`, `expired`, `box(n)`
+   - Handles database adapter differences (MySQL vs others) for random ordering
+
+3. **ActiveRecall::Item** (lib/active_recall/models/item.rb)
+   - Represents individual flashcard items in a deck
+   - Polymorphic association to source objects (the actual flashcard content)
+   - Methods: `score!(grade)`, `right!`, `wrong!`
+   - Delegates to configured algorithm for calculating next review dates
+
+4. **Algorithms** (lib/active_recall/algorithms/)
+   - Each algorithm class implements: `type`, `required_attributes`, `right`, `wrong`, and optionally `score`
+   - Algorithm types: `:binary` (right/wrong only) or `:gradable` (accepts scores)
+   - Binary algorithms: LeitnerSystem (default), SoftLeitnerSystem, FibonacciSequence
+   - Gradable algorithm: SM2
+   - All algorithms are stateless; they accept current state and return new state as a hash
+
+5. **Configuration** (lib/active_recall/configuration.rb)
+   - Global configuration via `ActiveRecall.configure`
+   - Primary setting: `algorithm_class` (defaults to LeitnerSystem)
+   - Configuration should be set in Rails initializers
+
+### Data Flow
+
+1. A model calls `has_deck :items_name` to enable SRS functionality
+2. This creates a Deck record (polymorphic, user_id/user_type)
+3. Items are added to deck with `<<` operator, creating Item records
+4. Item records store: box number, review dates, times_right/times_wrong, easiness_factor (for SM2)
+5. User calls `right_answer_for!(item)` or `wrong_answer_for!(item)` (or `score!(grade, item)` for gradable algorithms)
+6. This delegates to Item's `right!`/`wrong!`/`score!` which calls the configured algorithm
+7. Algorithm returns hash of updated attributes (box, next_review, etc.)
+8. Deck provides query methods that filter items by state and return source objects
+
+### Key Design Patterns
+
+- **Polymorphic associations**: Decks belong to any "user" model, Items reference any "source" model
+- **Strategy pattern**: Algorithms are swappable via configuration
+- **Delegation**: Deck methods delegate to Item scopes, which use the configured algorithm
+- **Stateless algorithms**: All algorithm classes are stateless with class methods only (except FibonacciSequence which caches Fibonacci numbers in instances)
+
+## Database Schema
+
+The gem creates two tables via generators:
+- `active_recall_decks`: id, user_id (polymorphic), user_type, created_at, updated_at
+- `active_recall_items`: id, deck_id, source_id (polymorphic), source_type, box, times_right, times_wrong, last_reviewed, next_review, easiness_factor, created_at, updated_at
+
+## Migration from Okubo
+
+The gem includes a migration template (`migrate_okubo_to_active_recall.rb`) that renames tables from okubo_* to active_recall_*. Use `rails generate active_recall --migrate_data true` to generate this migration.
+
+## Code Style
+
+- Uses StandardRB for linting (config in standard.yml)
+- All files have `# frozen_string_literal: true` pragma
+- Ruby 3.2+ syntax required
+
+## Testing Conventions
+
+### Test File Structure
+- Spec files mirror lib/ directory structure (e.g., `lib/active_recall/foo.rb` → `spec/active_recall/foo_spec.rb`)
+- All spec files start with `# frozen_string_literal: true` and `require "spec_helper"`
+- Use `describe ClassName` for top-level blocks
+- Use `context` blocks to organize different scenarios
+- Use `subject { described_class.new }` for the class under test
+
+### Common Patterns
+```ruby
+# Basic structure
+describe ActiveRecall::SomeClass do
+  subject { described_class.new }
+
+  describe "#method_name" do
+    it "describes expected behavior" do
+      expect(subject.method_name).to eq(expected_value)
+    end
+  end
+
+  context "when specific condition" do
+    it "behaves differently" do
+      # test implementation
+    end
+  end
+end
+```
+
+### Shared Examples
+- Algorithm specs use shared examples for common behavior (see spec/active_recall/algorithms/algorithm_spec.rb)
+- Binary algorithms share: `it_behaves_like "binary spaced repetition algorithms"`
+- This ensures consistent testing across algorithm implementations
+
+### Test Data Setup
+- Use `let` blocks for test data that needs to be created
+- Use `before` blocks for setup that must run before each test
+- The spec_helper.rb defines Word and User models for testing deck functionality
+
+### Running Specific Tests
+While `bin/spec` is preferred for full test runs, you can run individual specs during development:
+```bash
+# During active development, you may need to specify the appraisal
+bundle exec appraisal rails-8-0 rspec spec/active_recall/configuration_spec.rb
+
+# Or run all specs via bin/spec which handles all Rails versions
+bin/spec
+```
+
+### Test Infrastructure Notes
+- Tests use an in-memory SQLite database (`:memory:`) configured in spec/spec_helper.rb
+- Different Rails versions require different sqlite3 gem versions:
+  - Rails 7.0/7.1 use sqlite3 ~> 1.4
+  - Rails 8.0 uses sqlite3 >= 2.1
+- The appraisal system manages these version conflicts via separate gemfiles
+- Always use `bin/spec` to avoid sqlite3 version conflict errors
+- Direct `bundle exec rspec` commands will fail with "can't activate sqlite3" errors

data/Gemfile

@@ -4,5 +4,18 @@ source "https://rubygems.org"
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-# Specify your gem's dependencies in active_recall.gemspec
 gemspec
+
+# TODO: Remove conditional dependency after dropping support for Ruby 3.2
+begin
+  ruby_version = Gem::Version.new(RUBY_VERSION)
+  if ruby_version >= Gem::Version.new("3.4.0")
+    gem "nokogiri", ">= 1.16.2"
+  end
+  if ruby_version >= Gem::Version.new("4.0.0")
+    gem "benchmark"
+    gem "ostruct"
+    gem "logger"
+  end
+rescue
+end

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    active_recall (2.0.2)
-      activerecord (>= 6.0, <= 7.2)
-      activesupport (>= 6.0, <= 7.2)
+    active_recall (2.2.0)
+      activerecord (>= 7.0, < 9.0)
+      activesupport (>= 7.0, < 9.0)
 
 GEM
   remote: https://rubygems.org/
@@ -132,10 +132,10 @@ GEM
     net-smtp (0.4.0.1)
       net-protocol
     nio4r (2.7.0)
-    nokogiri (1.16.0)
+    nokogiri (1.18.7)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    nokogiri (1.16.0-x86_64-linux)
+    nokogiri (1.18.7-x86_64-linux-gnu)
       racc (~> 1.4)
     parallel (1.24.0)
     parser (3.3.1.0)
@@ -217,7 +217,9 @@ GEM
       rubocop-ast (>= 1.30.0, < 2.0)
     ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
-    sqlite3 (1.4.2)
+    sqlite3 (2.5.0)
+      mini_portile2 (~> 2.8.0)
+    sqlite3 (2.5.0-x86_64-linux-gnu)
     standard (1.35.1)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
@@ -248,11 +250,12 @@ PLATFORMS
 DEPENDENCIES
   active_recall!
   appraisal
-  rails (>= 6.0, <= 7.2)
+  nokogiri (>= 1.16.2)
+  rails (>= 7.0, < 9.0)
   rake (>= 12.0)
   rdoc
   rspec (>= 3.0)
-  sqlite3
+  sqlite3 (~> 2.1)
   standard
 
 BUNDLED WITH

data/active_recall.gemspec

@@ -33,13 +33,13 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "appraisal"
-  spec.add_development_dependency "rails", ">= 6.0", "<= 7.2"
+  spec.add_development_dependency "rails", ">= 7.0", "< 9.0"
   spec.add_development_dependency "rake", ">= 12.0"
   spec.add_development_dependency "rdoc"
   spec.add_development_dependency "rspec", ">= 3.0"
-  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "sqlite3", "~> 2.1"
   spec.add_development_dependency "standard"
-  spec.add_runtime_dependency "activerecord", ">= 6.0", "<= 7.2"
-  spec.add_runtime_dependency "activesupport", ">= 6.0", "<= 7.2"
-  spec.required_ruby_version = ">= 3.0"
+  spec.add_runtime_dependency "activerecord", ">= 7.0", "< 9.0"
+  spec.add_runtime_dependency "activesupport", ">= 7.0", "< 9.0"
+  spec.required_ruby_version = ">= 3.2"
 end

data/bin/flatten

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+
+require 'fileutils'
+
+app_root = Dir.pwd
+app_name = File.basename(app_root)
+
+# Create tmp directory
+tmp_dir = File.join(app_root, 'tmp')
+FileUtils.mkdir_p(tmp_dir)
+
+# Define directories and file patterns to include in the search, excluding specific files and directories
+include_patterns = [
+  File.join(app_root, 'bin', '**', '*'),
+  File.join(app_root, 'lib', '**', '*'),
+  File.join(app_root, 'spec', '**', '*'),
+  File.join(app_root, '.github', '**', '*'),
+  File.join(app_root, '*.{md,rss,json,rb,gemspec,lock,yml,gitignore,rspec,tool-versions,Appraisals,Rakefile}')
+]
+
+# Find all matching files
+files = include_patterns.flat_map { |pattern| Dir.glob(pattern, File::FNM_DOTMATCH) }
+files.select! { |f| File.file?(f) }
+
+# Exclude the gemfiles directory and the top-level Gemfile.lock
+files.reject! do |file|
+  file.start_with?(File.join(app_root, 'gemfiles')) || file == File.join(app_root, 'Gemfile.lock')
+end
+
+# Output file
+output_file = File.join(tmp_dir, "#{app_name}_flat_file.txt")
+
+File.open(output_file, 'w') do |file|
+  files.each do |file_path|
+    relative_path = file_path.sub("#{app_root}/", '')
+    extension = File.extname(file_path).delete_prefix('.')
+
+    file.puts "#{relative_path}:"
+
+    content = File.read(file_path)
+    if extension == 'md'
+      file.puts content
+    else
+      file.puts "```#{extension}"
+      file.puts content
+      file.puts "```"
+    end
+
+    file.puts ""
+  end
+end
+
+# Print the path to the generated flat file
+puts "Flat file created at: #{output_file}"

data/gemfiles/rails_7_0.gemfile

@@ -2,6 +2,8 @@
 
 source "https://rubygems.org"
 
+gem "nokogiri", ">= 1.16.2"
 gem "rails", "~> 7.0"
+gem "sqlite3", "~> 1.4"
 
 gemspec path: "../"

data/gemfiles/rails_7_0.gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: ..
   specs:
-    active_recall (2.0.2)
-      activerecord (>= 6.0, <= 7.2)
-      activesupport (>= 6.0, <= 7.2)
+    active_recall (2.2.0)
+      activerecord (>= 7.0, < 9.0)
+      activesupport (>= 7.0, < 9.0)
 
 GEM
   remote: https://rubygems.org/
@@ -119,6 +119,7 @@ GEM
       net-smtp
     marcel (1.0.2)
     mini_mime (1.1.5)
+    mini_portile2 (2.8.8)
     minitest (5.21.2)
     mutex_m (0.2.0)
     net-imap (0.4.9.1)
@@ -131,7 +132,7 @@ GEM
     net-smtp (0.4.0.1)
       net-protocol
     nio4r (2.7.0)
-    nokogiri (1.16.0-arm64-darwin)
+    nokogiri (1.18.7-arm64-darwin)
       racc (~> 1.4)
     parallel (1.24.0)
     parser (3.3.1.0)
@@ -216,7 +217,8 @@ GEM
       rubocop-ast (>= 1.30.0, < 2.0)
     ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
-    sqlite3 (1.7.1-arm64-darwin)
+    sqlite3 (1.7.3)
+      mini_portile2 (~> 2.8.0)
     standard (1.35.1)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
@@ -243,15 +245,18 @@ GEM
 
 PLATFORMS
   arm64-darwin-23
+  arm64-darwin-24
+  arm64-darwin-25
 
 DEPENDENCIES
   active_recall!
   appraisal
+  nokogiri (>= 1.16.2)
   rails (~> 7.0)
   rake (>= 12.0)
   rdoc
   rspec (>= 3.0)
-  sqlite3
+  sqlite3 (~> 1.4)
   standard
 
 BUNDLED WITH

data/gemfiles/rails_7_1.gemfile

@@ -2,6 +2,8 @@
 
 source "https://rubygems.org"
 
+gem "nokogiri", ">= 1.16.2"
 gem "rails", "~> 7.1"
+gem "sqlite3", "~> 1.4"
 
 gemspec path: "../"

data/gemfiles/rails_7_1.gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: ..
   specs:
-    active_recall (2.0.2)
-      activerecord (>= 6.0, <= 7.2)
-      activesupport (>= 6.0, <= 7.2)
+    active_recall (2.2.0)
+      activerecord (>= 7.0, < 9.0)
+      activesupport (>= 7.0, < 9.0)
 
 GEM
   remote: https://rubygems.org/
@@ -119,6 +119,7 @@ GEM
       net-smtp
     marcel (1.0.2)
     mini_mime (1.1.5)
+    mini_portile2 (2.8.8)
     minitest (5.21.2)
     mutex_m (0.2.0)
     net-imap (0.4.9.1)
@@ -131,7 +132,7 @@ GEM
     net-smtp (0.4.0.1)
       net-protocol
     nio4r (2.7.0)
-    nokogiri (1.16.0-arm64-darwin)
+    nokogiri (1.18.7-arm64-darwin)
       racc (~> 1.4)
     parallel (1.24.0)
     parser (3.3.1.0)
@@ -216,7 +217,8 @@ GEM
       rubocop-ast (>= 1.30.0, < 2.0)
     ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
-    sqlite3 (1.7.1-arm64-darwin)
+    sqlite3 (1.7.3)
+      mini_portile2 (~> 2.8.0)
     standard (1.35.1)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
@@ -243,15 +245,18 @@ GEM
 
 PLATFORMS
   arm64-darwin-23
+  arm64-darwin-24
+  arm64-darwin-25
 
 DEPENDENCIES
   active_recall!
   appraisal
+  nokogiri (>= 1.16.2)
   rails (~> 7.1)
   rake (>= 12.0)
   rdoc
   rspec (>= 3.0)
-  sqlite3
+  sqlite3 (~> 1.4)
   standard
 
 BUNDLED WITH

data/gemfiles/{rails_6_0.gemfile → rails_8_0.gemfile}

@@ -2,6 +2,8 @@
 
 source "https://rubygems.org"
 
-gem "rails", "~> 6.0"
+gem "nokogiri", ">= 1.16.2"
+gem "rails", "~> 8.0"
+gem "sqlite3", ">= 2.1"
 
 gemspec path: "../"