If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mislav/will_paginate shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 6mo ago
• 9 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 6mo ago
• ⚠ Single-maintainer risk — top contributor 83% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mislav/will_paginate repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mislav/will_paginate.

What it runs against: a local clone of mislav/will_paginate — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mislav/will_paginate | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 196 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mislav/will_paginate. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mislav/will_paginate.git
#   cd will_paginate
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mislav/will_paginate and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mislav/will_paginate(\\.git)?\\b" \\
  && ok "origin remote is mislav/will_paginate" \\
  || miss "origin remote is not mislav/will_paginate (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/will_paginate.rb" \\
  && ok "lib/will_paginate.rb" \\
  || miss "missing critical file: lib/will_paginate.rb"
test -f "lib/will_paginate/collection.rb" \\
  && ok "lib/will_paginate/collection.rb" \\
  || miss "missing critical file: lib/will_paginate/collection.rb"
test -f "lib/will_paginate/active_record.rb" \\
  && ok "lib/will_paginate/active_record.rb" \\
  || miss "missing critical file: lib/will_paginate/active_record.rb"
test -f "lib/will_paginate/view_helpers/link_renderer_base.rb" \\
  && ok "lib/will_paginate/view_helpers/link_renderer_base.rb" \\
  || miss "missing critical file: lib/will_paginate/view_helpers/link_renderer_base.rb"
test -f "lib/will_paginate/per_page.rb" \\
  && ok "lib/will_paginate/per_page.rb" \\
  || miss "missing critical file: lib/will_paginate/per_page.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 196 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~166d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mislav/will_paginate"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

will_paginate is a Ruby pagination library that adds .paginate() and .page() methods to Active Record queries, arrays, and other data sources to cleanly split large datasets into numbered pages. It handles the core problem of rendering paginated result sets with automatic link generation, working across Rails, Sinatra, Hanami, and Sequel ORM without boilerplate. Modular architecture: lib/will_paginate/core_ext.rb and lib/will_paginate/collection.rb provide the base pagination logic, lib/will_paginate/active_record.rb wraps Active Record, lib/will_paginate/sequel.rb and lib/will_paginate/mongoid.rb provide ORM adapters, and lib/will_paginate/view_helpers/ (with submodules for action_view.rb, sinatra.rb, hanami.rb) handle view rendering. Entry point is lib/will_paginate.rb.

Rails developers and other Ruby web developers who need to paginate database queries and collections in views without writing custom pagination logic or SQL LIMIT/OFFSET calculations. Also used by Sinatra and Hanami developers building data-heavy applications.

Production-ready and stable but in maintenance mode (no new features). The codebase is well-established with comprehensive test coverage across multiple Rails versions (5.0–7.0 in environments/), CI configured via GitHub Actions (.github/workflows/test.yml), and active dependency updates via Dependabot. However, it is not receiving active feature development.

Low risk for maintenance work but infrastructure risk: single primary maintainer (mislav), and the library is explicitly in maintenance mode with no new features planned. Dependency surface is minimal (pure Ruby with optional ORM integrations), but compatibility must be maintained across Rails 5.0–7.0 and Sequel/Mongoid. Breaking changes are unlikely given stability focus.

Repository is in steady maintenance: Dependabot is configured for automated dependency updates (.github/dependabot.yml), GitHub Actions test matrix runs across Rails versions (test.yml), and the focus is on compatibility and bug fixes rather than new features. No active development sprints visible; primarily accepting community contributions and compatibility patches.

git clone https://github.com/mislav/will_paginate.git
cd will_paginate
script/bootstrap  # installs dependencies (uses bundler from Gemfile)
bundle exec rspec spec/  # runs test suite

Daily commands: There is no 'dev server' — this is a library. Run the test suite:

bundle exec rspec spec/
# or for non-Rails adapters:
bundle exec rspec spec-non-rails/
# or the full CI matrix:
script/test_all

For Docker: docker-compose up (configuration in docker-compose.yml).

• lib/will_paginate.rb — Entry point that loads all core modules and initializes the pagination library.
• lib/will_paginate/collection.rb — Core abstraction for paginated collections; defines the WillPaginate::Collection class used by all adapters.
• lib/will_paginate/active_record.rb — Primary ORM integration that patches ActiveRecord with paginate() and page() methods.
• lib/will_paginate/view_helpers/link_renderer_base.rb — Base class for rendering pagination links; foundation for all view rendering logic.
• lib/will_paginate/per_page.rb — Manages per_page configuration across global and per-model scopes.
• lib/will_paginate/railtie.rb — Rails integration hook that initializes will_paginate within Rails environment.

• WillPaginate::Collection (Ruby core classes (Array, Enumerable)) — Universal wrapper for paginated data; holds results, total count, current page, and per_page settings.
  • Failure mode: If total_count or page metadata is incorrect, pagination links will be miscalculated.
• ORM Adapters (ActiveRecord, Mongoid, Sequel) — Translates generic paginate(page:, per_page:) calls into

Add Support for a New ORM

1. Create a new file in lib/will_paginate/ (e.g., lib/will_paginate/my_orm.rb) that extends the target ORM's query class. (lib/will_paginate/my_orm.rb)
2. Define a paginate() class method that accepts :page and :per_page options and returns a WillPaginate::Collection instance. (lib/will_paginate/my_orm.rb)
3. Load your adapter conditionally in lib/will_paginate.rb by checking if the ORM is available (e.g., require_if_exists). (lib/will_paginate.rb)
4. Add tests in spec-non-rails/ following the pattern of sequel_spec.rb or mongoid_spec.rb. (spec-non-rails/my_orm_spec.rb)

Add Support for a New View Framework

1. Create a new renderer class in lib/will_paginate/view_helpers/ (e.g., lib/will_paginate/view_helpers/my_framework.rb) that extends LinkRendererBase. (lib/will_paginate/view_helpers/my_framework.rb)
2. Override the render() method and html_container() method to generate framework-specific pagination HTML. (lib/will_paginate/view_helpers/my_framework.rb)
3. Register the new renderer in lib/will_paginate/view_helpers.rb by adding it to the framework detection logic. (lib/will_paginate/view_helpers.rb)
4. Add view helper tests in spec/view_helpers/ to verify pagination link rendering. (spec/view_helpers/my_framework_spec.rb)

Customize Pagination HTML Output

1. Subclass LinkRendererBase (or a framework-specific renderer) in your Rails initializer or app code. (lib/will_paginate/view_helpers/link_renderer_base.rb)
2. Override methods like html_container(), page_number(), previous_or_next_page(), or gap() to customize HTML structure. (lib/will_paginate/view_helpers/link_renderer_base.rb)
3. Pass your custom renderer class to will_paginate() view helper via the :renderer option. (lib/will_paginate/view_helpers/action_view.rb)

Add a New Locale for I18n

1. Create a new YAML file in lib/will_paginate/locale/ (e.g., lib/will_paginate/locale/es.yml) following the structure of en.yml. (lib/will_paginate/locale/es.yml)
2. Define translation keys for 'previous_label', 'next_label', and 'page_entries_info' in your language. (lib/will_paginate/locale/es.yml)
3. The I18n module in lib/will_paginate/i18n.rb will automatically load and merge your locale file. (lib/will_paginate/i18n.rb)

• Ruby module system & monkey-patching — Allows seamless integration into existing ORM and framework classes without requiring explicit inheritance.
• I18n for translations — Provides multi-language support for pagination labels (prev/next) without hardcoding strings.
• Railtie for Rails — Enables automatic loading and initialization within Rails without requiring manual configuration in initializers.
• Class-based renderers — Allows users to subclass and override rendering behavior for custom HTML generation while maintaining consistency across frameworks.

• Maintenance mode (no new features)

  • Why: Allows core maintainers to focus on stability and security rather than keeping pace with rapidly evolving ecosystem.
  • Consequence: Users seeking advanced features (Kaminari, Pagy) may need to migrate to alternative gems; contributions are lower priority.

• Multiple ORM adapters (ActiveRecord, Mongoid, Sequel) in single gem

  • Why: Provides unified pagination API across different data backends without users needing to swap gems.
  • Consequence: Increased maintenance burden and complexity; each adapter must be tested and kept in sync with ORM upgrades.

• View helpers for multiple frameworks (Rails, Sinatra, Hanami)

  • Why: Single pagination gem works across ecosystems, reducing ecosystem fragmentation.
  • Consequence: Tight coupling to multiple frameworks; changes in one framework may break compatibility elsewhere.

• SQL-based offset pagination (no cursor-based)

  • Why: Simpler API and familiar page number UI model that users understand.
  • Consequence: Poor performance on large offsets; not suitable for real-time or constantly-changing datasets.

• Real-time pagination updates or cursor-based pagination
• Handling of authentication or authorization logic
• Custom query optimization beyond basic LIMIT/OFFSET
• Support for non-SQL databases without explicit ORM adapter
• JSON API response generation (view-layer only)

Monkey-patching: will_paginate extends Array, Relation, and Hash at load time via core_ext.rb; conflicts possible with other gems using similar extensions. Per-page scoping: WillPaginate.per_page is global; model-level per_page (e.g., Post.per_page = 10) overrides it but must be set before paginate() is called. Rails version matrix: lib/will_paginate/railtie.rb requires Rails; non-Rails usage (Sinatra, Hanami, Sequel alone) must manually require lib/will_paginate and specific adapter. Page parameter casting: lib/will_paginate/page_number.rb coerces params[:page] to Integer; nil/invalid values default to 1. I18n locale path: I18n must be configured to include lib/will_paginate/locale/ for translation keys (done automatically in Railtie for Rails).

• Offset-based pagination — will_paginate uses SQL OFFSET and LIMIT (via Active Record's offset() and limit()) to fetch page N; understanding how offset = (page - 1) * per_page works is critical to debugging page boundary issues.
• Monkey-patching / metaprogramming (Ruby open classes) — will_paginate extends Array, Hash, and Active Record::Relation by reopening their classes and adding methods like paginate() and page(); understanding Module.include and method_missing is essential to reading lib/will_paginate/core_ext.rb.
• ActiveRecord::Relation scoping and lazy evaluation — will_paginate's Active Record adapter chains paginate() into a Relation; knowing when SQL is executed (lazy vs. eager) prevents N+1 queries and subtle bugs in lib/will_paginate/active_record.rb.
• Rails Railtie initialization hooks — lib/will_paginate/railtie.rb uses Rails.application.config.after_initialize to inject the library into Rails; understanding Railtie lifecycle is needed to debug Rails integration issues.
• I18n (Internationalization) in Ruby on Rails — will_paginate uses Rails I18n to translate pagination UI labels ('previous', 'next', etc.) via lib/will_paginate/i18n.rb and lib/will_paginate/locale/; understanding YAML locale files and I18n.t() is needed to add languages.
• Adapter pattern (ORM abstraction) — will_paginate implements separate adapters for Active Record, Sequel, Mongoid, and Hanami; understanding how each adapter defines paginate() differently allows extending the library to new ORMs.
• Total count strategies (COUNT queries optimization) — Collection#total_entries triggers a COUNT(*) query; understanding when count is cached vs. recomputed (lib/will_paginate/collection.rb) is critical to avoiding performance regressions in pagination views.

• ddnexus/pagy — Modern alternative to will_paginate; lighter, faster, with more customization options; the most recommended successor in the Ruby ecosystem.
• kaminari/kaminari — Competing pagination library with built-in view customization via generators and better Rails 5+ integration; more actively developed than will_paginate.
• rails/rails — will_paginate is a Rails extension library; understanding ActiveRecord::Relation and Railties (lib/will_paginate/railtie.rb) requires Rails internals knowledge.
• sinatra/sinatra — will_paginate provides a Sinatra adapter (lib/will_paginate/view_helpers/sinatra.rb) for use in Sinatra applications.
• hanami/hanami — will_paginate provides a Hanami::View adapter (lib/will_paginate/view_helpers/hanami.rb) for Hanami web framework applications.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for view_helpers/hanami.rb integration

The Hanami view helper integration (lib/will_paginate/view_helpers/hanami.rb) exists but there are no corresponding spec files in spec/ directory like there are for active_record_spec.rb. Given that will_paginate supports multiple frameworks (Rails, Sinatra, Hanami, Sequel), the Hanami integration deserves parity in test coverage to ensure pagination rendering works correctly with Hanami::View.

• [ ] Create spec/finders/hanami_spec.rb following the pattern of spec/finders/active_record_spec.rb
• [ ] Add Hanami test fixtures similar to spec/fixtures/ for testing model integration
• [ ] Test the link_renderer output for Hanami views with various pagination scenarios
• [ ] Add Hanami to the CI matrix in script/ci-matrix if not already present

Add integration tests for Sequel pagination with the test suite

While spec-non-rails/sequel_spec.rb exists, the test file appears minimal and Sequel is listed as a supported framework. The repo has comprehensive Rails/ActiveRecord tests but Sequel deserves equivalent coverage given it's explicitly supported via lib/will_paginate/sequel.rb. This would ensure pagination correctness across different ORMs.

• [ ] Expand spec-non-rails/sequel_spec.rb with comprehensive pagination scenarios (page limits, per_page, edge cases)
• [ ] Add Sequel fixtures and schema setup in spec-non-rails/ following the pattern from spec/fixtures/
• [ ] Test Collection behavior with Sequel's Dataset objects
• [ ] Add Sequel to automated CI testing in .github/workflows/test.yml with a dedicated test matrix entry

Add missing documentation for i18n locale customization in README.md

The repo has i18n support (lib/will_paginate/i18n.rb and lib/will_paginate/locale/en.yml exist) but the README.md snippet provided doesn't mention i18n configuration at all. Contributors and users need guidance on how to add custom locales or override default locale strings, especially given the maintenance mode status where external contribution is important.

• [ ] Document i18n usage in README.md with examples of adding custom locales
• [ ] Add a section explaining the structure of locale files (reference lib/will_paginate/locale/en.yml)
• [ ] Include example of how to override pagination labels (Previous, Next, Page X of Y, etc.)
• [ ] Link to CONTRIBUTING.md from the i18n documentation section for locale contribution guidelines

• Add test coverage for lib/will_paginate/hanami.rb integration with realistic Hanami::View examples; currently no spec files exist for Hanami adapter.: spec/hanami_spec.rb (new file)
• Document the PerPage class API and model-level configuration in a wiki page; currently unclear how per_page inheritance works across models.: README.md or wiki (external)
• Add deprecation warnings in lib/will_paginate/deprecation.rb for the old hash-style params (e.g., :page => params[:page]); currently no guidance for Rails 6+ keyword argument migration.: lib/will_paginate/deprecation.rb and spec/deprecation_spec.rb (new)
• Expand lib/will_paginate/locale/en.yml with examples for RTL languages and add test coverage in lib/will_paginate/i18n.rb for locale fallback behavior.: lib/will_paginate/locale/ and lib/will_paginate/i18n.rb
• Add examples for Sequel and Mongoid pagination to README.md (currently only Active Record and array examples); create spec-non-rails/integration_examples.rb.: README.md and spec-non-rails/

The will_paginate library has a reasonable security posture as a maintenance-mode pagination library. Primary concerns are: (1) Docker Compose misconfiguration with exposed ports and empty MySQL password suitable only for development, (2) Reliance on proper parameter validation by consuming applications, and (3) Need for explicit XSS prevention in view helper output. The codebase shows no obvious hardcoded secrets, direct SQL injection risks, or dangerous patterns. Security depends largely on proper usage by developers and securing the deployment environment. Recommend updating Docker Compose for secure defaults and adding explicit security testing.

• Medium · Exposed Database Ports in Docker Compose — docker-compose.yml. The docker-compose.yml file exposes database service ports (3307 for MySQL, 5433 for PostgreSQL, 27018 for MongoDB) to the host machine. This is a development convenience but could expose databases if the compose file is used in production or if the host is accessible on a network. Fix: Remove port mappings for production deployments. Use named volumes and internal networking instead. Document that docker-compose is for development only and create separate secure deployment configurations.
• Medium · Empty MySQL Password in Docker Compose — docker-compose.yml (MySQL service). The MySQL service is configured with MYSQL_ALLOW_EMPTY_PASSWORD=true, which allows connections without authentication. This is insecure even for development environments and could lead to accidental security oversights. Fix: Set a secure password for MySQL: MYSQL_ROOT_PASSWORD=<strong_password>. Update database.yml accordingly. Document secure credentials in development setup instructions.
• Low · Potential SQL Injection in Active Record Integration — lib/will_paginate/active_record.rb, lib/will_paginate/page_number.rb. The library integrates with Active Record for pagination. While the pagination gem itself appears to handle parameters safely, the usage pattern shown in README (Post.paginate(page: params[:page])) relies on proper parameter validation. If params[:page] is not properly validated, it could lead to SQL injection. Fix: Ensure PageNumber class properly validates and sanitizes the page parameter. Add input validation tests. Document proper usage patterns for developers.
• Low · Missing HTTPS/Security Headers in View Helpers — lib/will_paginate/view_helpers/link_renderer.rb, lib/will_paginate/view_helpers/link_renderer_base.rb. The view helper files (lib/will_paginate/view_helpers/) generate pagination links. Without proper output encoding, there could be XSS risks if pagination parameters are reflected in URLs without escaping. Fix: Ensure all URL parameters are properly HTML-escaped. Use Rails' link_to helper which auto-escapes by default. Add Content Security Policy headers in applications using this gem.
• Low · Insufficient Test Coverage for Security — spec/ directory. While the test structure is comprehensive, there are no explicitly visible security-focused tests for injection attacks, parameter tampering, or XSS in the spec files. Fix: Add security-focused test cases for: malicious page parameters, XSS attempts in URLs, SQL injection attempts, and boundary value testing for page numbers.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.