darthjee-active_ext 1.3.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: fb91b628ca83024e054c1739dea5c23e3086c99c
-  data.tar.gz: 7c95c17e1a61c92d9819bb9c4c206a4958d34d6b
+SHA256:
+  metadata.gz: b4c421c51d5123103187852e1275c366949004f25b24b39e01e18862d3a62bb8
+  data.tar.gz: 76350778a8a203605014368a71cd98577f0110e5b4a047d88afe4781837c159c
 SHA512:
-  metadata.gz: e7dad17a96b13c41e2d24185166006e1892c11ad2fb5a8bf9ccac364c8eb1f7a286a3cbbfd2adf147baaf3704d3c7fd1c574826158774b95743dcd13616e0b1f
-  data.tar.gz: 83ad3e5604468f5ab2128d572fc4f4ffc510ee503d284bf3ba8150c179711b252502b19e8df976bf6207d24e3c1eb1a70bbe3a0a6cbd66f75e3c1b8225f07f97
+  metadata.gz: 3e25a672c1677961f700d52c39dfabcbe7a8f19ac538a33003a1a6f610d50d8ade5e68e4c5ea1336499d7dd134b0a2a0a09355dd513b661abb228bc49462a2d5
+  data.tar.gz: c8988d38003fa18fc2e67460016dced99c86c24a112b574c7ba1f49a1b4386298facb2d36a325a611058c77f574ffe71a82a1348dc9031ef442b7004205b4f4c

data/.circleci/config.yml

@@ -1,13 +1,82 @@
 version: 2
+workflows:
+  version: 2
+  test-and-build:
+    jobs:
+      - test:
+          filters:
+            tags:
+              only: /.*/
+      - checks:
+          filters:
+            tags:
+              only: /.*/
+      - build-and-release:
+          requires: [test, checks]
+          filters:
+            tags:
+              only: /\d+\.\d+\.\d+/
+            branches:
+              only:
+                - main
 jobs:
-  build:
+  test:
     docker:
-      - image: circleci/ruby:2.4.1
+      - image: darthjee/circleci_rails_gems:2.1.1
+        environment:
+          PROJECT: active_ext
     steps:
       - checkout
-      - run: curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
-      - run: chmod +x ./cc-test-reporter
-      - run: ./cc-test-reporter before-build
-      - run: bundle install
-      - run: bundle exec rspec
-      - run: ./cc-test-reporter after-build --exit-code $?
+      - run:
+          name: Bundle Install
+          command: bundle install
+      - run:
+          name: RSpec
+          command: bundle exec rspec
+      - run:
+          name: Upload coverage to Codacy
+          command: bash <(curl -Ls https://coverage.codacy.com/get.sh) report -r coverage/lcov/project.lcov
+  checks:
+    docker:
+      - image: darthjee/circleci_rails_gems:2.1.1
+        environment:
+          PROJECT: active_ext
+    steps:
+      - checkout
+      - run:
+          name: Bundle Install
+          command: bundle install
+      - run:
+          name: Rubocop
+          command: rubocop
+      - run:
+          name: Yardstick coverage check
+          command: bundle exec rake verify_measurements
+      - run:
+          name: Check version documentation
+          command: VERSION_PATH=lib/darthjee/active_ext/version.rb GEM_NAME=darthjee-active_ext check_readme.sh
+      - run:
+          name: Rubycritcs check
+          command: rubycritic.sh
+      - run:
+          name: Check unit tests
+          command: check_specs
+  build-and-release:
+    docker:
+      - image: darthjee/circleci_rails_gems:2.1.1
+        environment:
+          PROJECT: active_ext
+    steps:
+      - checkout
+      - run:
+          name: Bundle Install
+          command: bundle install
+      - run:
+          name: Signin
+          command: build_gem.sh signin
+      - run:
+          name: Build Gem
+          command: PROJECT=darthjee-active_ext build_gem.sh build
+      - run:
+          name: Push Gem
+          command: PROJECT=darthjee-active_ext build_gem.sh push

data/.github/active_ext-usage.md

@@ -0,0 +1,137 @@
+# Using `darthjee-active_ext` in This Project
+
+This project uses the [`darthjee-active_ext`](https://github.com/darthjee/active_ext) gem,
+which adds utility methods to `ActiveRecord::Relation` and `ActiveRecord::Base`.
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'darthjee-active_ext'
+```
+
+Then run:
+
+```console
+bundle install
+```
+
+---
+
+## Methods Added
+
+The gem adds the following methods to **`ActiveRecord::Relation`** and, by delegation,
+to every **`ActiveRecord::Base`** subclass (i.e., every model):
+
+| Method | Returns | Purpose |
+|---|---|---|
+| `#percentage(*filters)` | `Float` (0.0 – 1.0) | Fraction of records matching a condition within the current scope |
+| `#pluck_as_json(*keys)` | `Array<Hash>` | Like `pluck`, but returns an array of hashes instead of an array of arrays |
+
+---
+
+## `#percentage`
+
+Returns the fraction of records within the current relation that match the
+given condition.  The result is a `Float` between `0.0` and `1.0`.
+Returns `0` (integer) when the relation is empty, to avoid division by zero.
+
+### Accepted filter forms
+
+| Form | Example argument |
+|---|---|
+| Named scope (Symbol) | `:with_error` |
+| Multiple chained scopes (Symbols) | `:active, :with_error` |
+| Hash condition | `status: :error` |
+| Raw SQL string | `"status = 'error'"` |
+
+### Examples
+
+```ruby
+# Given a model and some data:
+class Document < ActiveRecord::Base
+  scope :with_error,   -> { where(status: :error) }
+  scope :with_success, -> { where(status: :success) }
+  scope :active,       -> { where(active: true) }
+end
+
+# 3 error documents, 1 success document (4 total)
+Document.percentage(:with_error)          #=> 0.75
+Document.percentage(status: :error)       #=> 0.75
+Document.percentage("status = 'error'")   #=> 0.75
+
+# Nested scope: among active documents only
+Document.active.percentage(:with_error)   #=> 0.5
+
+# Multiple scope filters chained together
+Document.percentage(:active, :with_error) #=> 0.25
+
+# Empty relation → returns 0, not a float, to avoid division by zero
+Document.where(id: nil).percentage(:with_error) #=> 0
+```
+
+### When to use `percentage`
+
+- Displaying statistics or progress indicators (e.g., "75% of tasks completed").
+- Feature-flag rollout checks across a filtered user base.
+- Any situation where you need a ratio of one subset to its parent scope.
+
+---
+
+## `#pluck_as_json`
+
+Works like `ActiveRecord`'s built-in `pluck`, but returns an **array of hashes**
+instead of an array of arrays.  Each hash maps column name (as a Symbol) to its
+value.
+
+When called **with no arguments**, it returns the full `as_json` representation
+of every record in the relation (equivalent to `map(&:as_json)`).
+
+### Examples
+
+```ruby
+# Standard pluck returns nested arrays — column order matters
+Document.pluck(:id, :status)
+#=> [[1, "error"], [2, "success"], [3, "success"]]
+
+# pluck_as_json returns hashes — keys make meaning explicit
+Document.pluck_as_json(:id, :status)
+#=> [
+#     { id: 1, status: "error"   },
+#     { id: 2, status: "success" },
+#     { id: 3, status: "success" }
+#   ]
+
+# Works with any ActiveRecord scope chain
+Document.active.pluck_as_json(:id, :status)
+#=> [{ id: 3, status: "success" }]
+
+# No arguments — returns all columns for every record as JSON hashes
+Document.pluck_as_json
+#=> [
+#     { id: 1, status: "error",   active: false, created_at: ..., updated_at: ... },
+#     { id: 2, status: "success", active: false, created_at: ..., updated_at: ... },
+#     { id: 3, status: "success", active: true,  created_at: ..., updated_at: ... }
+#   ]
+```
+
+### When to use `pluck_as_json`
+
+- Building JSON API responses without loading full ActiveRecord objects.
+- Feeding data into serializers or view helpers that expect hashes.
+- Any scenario where column position in a plain array would be fragile or unclear.
+
+---
+
+## Notes
+
+- Both methods are available directly on model classes (`Document.percentage(...)`)
+  **and** on any `ActiveRecord::Relation` (`Document.active.percentage(...)`),
+  because the class-level methods are delegated to `Model.all`.
+- `percentage` with Symbol arguments chains named scopes; with a Hash or String it
+  uses `where`.  Do **not** mix Symbols with Hashes/Strings in a single call.
+- The gem requires `darthjee-core_ext` (pulled in automatically as a dependency),
+  which provides the `Array#as_hash` helper used internally by `pluck_as_json`.

data/.github/copilot-instructions.md

@@ -0,0 +1,102 @@
+# GitHub Copilot Instructions for `darthjee/active_ext`
+
+## Project Overview
+
+`active_ext` is a Ruby gem that provides extension methods to be used with
+**ActiveRecord** and **ActiveSupport** (Ruby on Rails components). It enriches
+`ActiveRecord::Relation` and related classes with additional query helpers and
+utilities, keeping the extensions idiomatic, lightweight, and Rails-friendly.
+
+---
+
+## Language
+
+All contributions must be in **English**:
+
+- Pull request titles and descriptions
+- Code comments and inline documentation
+- YARD docstrings and examples
+- Commit messages
+- Identifiers (class names, method names, variable names, etc.)
+
+---
+
+## Testing
+
+- **Always add tests** for every change, bug fix, or new feature.
+- Tests live under `spec/` and use **RSpec**.
+- Follow the existing spec structure: place specs next to the corresponding
+  `lib/` file (e.g., `lib/active_record/my_extension.rb` →
+  `spec/lib/active_record/my_extension_spec.rb`).
+- If a source file genuinely cannot have a spec (e.g., it only re-exports
+  constants or requires other files), list it in **`check_specs.yml`** so it
+  is explicitly acknowledged as exempt from the coverage requirement.
+
+---
+
+## Documentation
+
+- Provide documentation compatible with **YARD**.
+- Every **public** class, module, and method must include a YARD docstring.
+- Include `@param`, `@return`, and `@example` tags where appropriate.
+- Example:
+
+```ruby
+# Returns the percentage of records matching +scope+ within the current
+# relation.
+#
+# @param scope [Symbol, Hash, String] the scope or condition to evaluate
+# @return [Float] percentage as a decimal between 0.0 and 1.0
+#
+# @example Using a named scope
+#   Document.percentage(:with_error) #=> 0.75
+#
+# @example Using a hash condition
+#   Document.percentage(status: :error) #=> 0.75
+#
+# @example Within a nested scope
+#   Document.active.percentage(:with_error) #=> 0.5
+def percentage(scope)
+  # ...
+end
+```
+
+---
+
+## Design & Quality
+
+Follow the principles championed by **Sandi Metz** (as described in
+*99 Bottles of OOP* and *Practical Object-Oriented Design*):
+
+- **Small classes and methods** — each should have a single, well-defined
+  responsibility.
+- **Limit method length** — prefer short, readable methods over long ones.
+- **Prefer composition over inheritance** when extending behavior.
+- **Avoid Law of Demeter violations** — an object should only talk to its
+  immediate collaborators; avoid long method-chain calls like
+  `a.b.c.do_something`.
+- **Favor clear, explicit boundaries** — modules and classes should expose
+  minimal public APIs and hide implementation details.
+
+---
+
+## Rails & ActiveRecord Compatibility
+
+- Extensions must remain **Rails-friendly**: follow Rails conventions and
+  naming patterns.
+- New methods added to `ActiveRecord::Relation` or `ActiveSupport` classes
+  should integrate naturally with existing Rails query interfaces (scopes,
+  chainability, etc.).
+- Avoid monkey-patching core Ruby classes unless absolutely necessary; prefer
+  extending the appropriate Rails base classes or using `ActiveSupport::Concern`.
+- Ensure compatibility with the Ruby and Rails versions declared in
+  `active_ext.gemspec` and `Gemfile`.
+
+---
+
+## Pull Request Guidelines
+
+- Keep PRs focused and small — one logical change per PR.
+- Include a clear description of *what* changed and *why*.
+- Reference any related issues.
+- Ensure all existing and new specs pass before requesting review.

data/.gitignore

@@ -1,3 +1,8 @@
 coverage
 Gemfile.lock
 pkg
+
+.yardoc/
+doc/
+rubycritic/
+measurement

data/.rubocop.yml

@@ -0,0 +1,12 @@
+plugins:
+  - rubocop-rspec
+  - rubocop-rake
+
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 3.3
+  NewCops: enable
+
+Gemspec/RequireMFA:
+  Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,8 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2026-03-10 23:25:07 UTC using RuboCop version 1.85.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+

data/Dockerfile

@@ -0,0 +1,21 @@
+FROM darthjee/scripts:0.7.0 as scripts
+
+FROM darthjee/rails_gems:2.1.1 as base
+
+COPY --chown=app:app ./ /home/app/app/
+
+######################################
+
+FROM base as builder
+
+COPY --chown=app:app --from=scripts /home/scripts/builder/bundle_builder.sh /usr/local/sbin/bundle_builder.sh
+
+ENV HOME_DIR /home/app
+RUN bundle_builder.sh
+
+#######################
+#FINAL IMAGE
+FROM base
+
+COPY --chown=app:app --from=builder /home/app/bundle/ /usr/local/bundle/
+RUN bundle install

data/Gemfile

@@ -1,5 +1,30 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in credential_builder.gemspec
 gemspec
 
+gem 'activerecord', '7.2.2.1'
+gem 'bundler',                  '>= 2.5.13'
+gem 'pry',                      '0.14.2'
+gem 'pry-nav',                  '1.0.0'
+gem 'rake', '13.2.1'
+gem 'reek',                     '6.5.0'
+gem 'rspec',                    '3.13.2'
+gem 'rspec-collection_matchers'
+gem 'rspec-core',               '3.13.6'
+gem 'rspec-expectations',       '3.13.5'
+gem 'rspec-mocks',              '3.13.8'
+gem 'rspec-rails',              '8.0.3'
+gem 'rspec-support',            '3.13.7'
+gem 'rubocop',                  '1.85.1'
+gem 'rubocop-rake',             '0.7.1'
+gem 'rubocop-rspec',            '3.9.0'
+gem 'rubycritic',               '5.0.0'
+gem 'simplecov',                '0.22.0'
+gem 'simplecov-html',           '0.13.2'
+gem 'simplecov-lcov',           '0.9.0'
+gem 'sqlite3', '1.4.2'
+gem 'yard',                     '0.9.38'
+gem 'yardstick',                '0.9.9'

data/Makefile

@@ -0,0 +1,6 @@
+.PHONY: dev
+
+PROJECT?=active_ext
+
+dev:
+	docker-compose run $(PROJECT) /bin/bash

data/README.md

@@ -1,9 +1,19 @@
 ActiveExt
 ==========
 
-[![Code Climate](https://codeclimate.com/github/darthjee/active_ext/badges/gpa.svg)](https://codeclimate.com/github/darthjee/active_ext)
-[![Test Coverage](https://codeclimate.com/github/darthjee/active_ext/badges/coverage.svg)](https://codeclimate.com/github/darthjee/active_ext/coverage)
-[![Issue Count](https://codeclimate.com/github/darthjee/active_ext/badges/issue_count.svg)](https://codeclimate.com/github/darthjee/active_ext)
+[![CircleCI](https://dl.circleci.com/status-badge/img/gh/darthjee/active_ext/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/darthjee/active_ext/tree/main)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/ba204b06239b4e1483fe1ce2fb4aced2)](https://app.codacy.com/gh/darthjee/active_ext/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/ba204b06239b4e1483fe1ce2fb4aced2)](https://app.codacy.com/gh/darthjee/active_ext/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
+[![Gem Version](https://badge.fury.io/rb/darthjee-active_ext.svg)](https://badge.fury.io/rb/darthjee-active_ext)
+
+**Current Release**: [1.4.0](https://github.com/darthjee/active_ext/tree/1.4.0)
+
+**Next release**: [1.5.0](https://github.com/darthjee/active_ext/compare/1.4.0...main)
+
+Yard Documentation
+-------------------
+[https://www.rubydoc.info/gems/darthjee-active_ext/1.4.0](https://www.rubydoc.info/gems/darthjee-active_ext/1.4.0)
+
 
 # Usage
 This project adds some new methods to the core active_record classes

data/Rakefile

@@ -1,7 +1,15 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'yardstick/rake/measurement'
+require './config/yardstick'
+require './config/rubycritc'
 
 RSpec::Core::RakeTask.new
 
+desc 'run rspec'
 task default: :spec
+
+desc 'run rspec'
 task test: :spec

data/active_ext.gemspec

@@ -1,5 +1,6 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'darthjee/active_ext/version'
 
@@ -11,21 +12,13 @@ Gem::Specification.new do |gem|
   gem.summary       = 'Active Extensions'
   gem.homepage      = 'https://github.com/darthjee/active_ext'
   gem.description   = 'Extension of active support classes with usefull methods'
+  gem.required_ruby_version = '>= 3.3.1'
 
   gem.files         = `git ls-files -z`.split("\x0")
   gem.executables   = gem.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ['lib']
 
-  gem.add_runtime_dependency 'activesupport',     '>= 5.x'
-  gem.add_runtime_dependency 'darthjee-core_ext', '>= 1.5.6'
-
-  gem.add_development_dependency 'activerecord', '~> 5.x'
-  gem.add_development_dependency 'sqlite3'
-
-  gem.add_development_dependency 'bundler',     '>= 1.6'
-  gem.add_development_dependency 'rake',        '>= 11.3.0'
-  gem.add_development_dependency 'rspec',       '>= 2.14'
-  gem.add_development_dependency 'rspec-mocks', '>= 2.99.4'
-  gem.add_development_dependency 'simplecov',   '>= 0.14.1'
+  gem.add_dependency 'activesupport',     '~> 7.2.x'
+  gem.add_dependency 'darthjee-core_ext', '>= 3.1.0'
+  gem.metadata['rubygems_mfa_required'] = 'false'
 end

data/config/check_specs.yml

@@ -0,0 +1,6 @@
+ignore:
+  - lib/darthjee/active_ext/version.rb
+  - lib/active_record/base_ext.rb
+  - lib/active_record/relation_ext.rb
+  - lib/darthjee/active_ext.rb
+  - lib/darthjee.rb

data/config/rubycritc.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'rubycritic/rake_task'
+
+RubyCritic::RakeTask.new do |task|
+  options = %w[
+    --path rubycritic/
+    --no-browser
+  ]
+  task.options = options.join(' ')
+  task.paths   = %w[lib]
+end

data/config/yardstick.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'yardstick/rake/measurement'
+require 'yardstick/rake/verify'
+require 'yaml'
+
+options = YAML.load_file('config/yardstick.yml')
+
+Yardstick::Rake::Measurement.new(:yardstick_measure, options) do |measurement|
+  measurement.output = 'measurement/report.txt'
+end
+
+Yardstick::Rake::Verify.new(:verify_measurements, options)

data/config/yardstick.yml

@@ -0,0 +1,39 @@
+threshold: 10.0
+require_exact_threshold: false
+rules:
+  ApiTag::Presence:
+    enabled: true
+    exclude: []
+  ApiTag::Inclusion:
+    enabled: true
+    exclude: []
+  ApiTag::ProtectedMethod:
+    enabled: true
+    exclude: []
+  ApiTag::PrivateMethod:
+    enabled: true
+    exclude: []
+  ExampleTag:
+    enabled: true
+    exclude:
+      - ActiveRecord::Base.percentage
+      - ActiveRecord::Base.pluck_as_json
+      - ActiveRecord::Base.scopped
+  ReturnTag:
+    enabled: true
+    exclude:
+      - ActiveRecord::Base.percentage
+      - ActiveRecord::Base.pluck_as_json
+      - ActiveRecord::Base.scopped
+  Summary::Presence:
+    enabled: true
+    exclude: []
+  Summary::Length:
+    enabled: true
+    exclude: []
+  Summary::Delimiter:
+    enabled: true
+    exclude: []
+  Summary::SingleLine:
+    enabled: true
+    exclude: []

data/docker-compose.yml

@@ -1,18 +1,23 @@
-version: '2'
+version: '3'
 services:
   base: &base
-    image: ruby:2.4.0
-    working_dir: /home/app/active_ext
+    image: active_ext
+    working_dir: /home/app/app
     volumes:
-      - .:/home/app/active_ext
-      - active_ext_gems_2_4_0:/usr/local/bundle
+      - .:/home/app/app
 
-  #################### CONTAINERS ####################
+  base_build:
+    <<: *base
+    build: .
+    command: echo done
 
   active_ext:
     <<: *base
     container_name: active_ext
-    command: /bin/bash -c 'bundle install && bundle exec rspec'
+    depends_on: [base_build]
+    command: /bin/bash -c 'rspec'
 
-volumes:
-  active_ext_gems_2_4_0:
+  test_all:
+    <<: *base
+    depends_on: [base_build]
+    command: /bin/bash -c 'rspec && yard && rake yardstick_measure && rake verify_measurements'

data/lib/active_record/base_ext.rb

@@ -1,10 +1,47 @@
+# frozen_string_literal: true
+
 require 'active_record'
 
 module ActiveRecord
+  # Extends +ActiveRecord::Base+ with additional class methods.
+
+  # These methods are delegated to the `all` scope of the model,
+  # allowing you to call them directly on the model class.
   class Base
     class << self
-      delegate :percentage, :pluck_as_json, to: :all
+      delegate :percentage, :pluck_as_json, :scopped, to: :all
+
+      # @method percentage
+      # @api public
+      #
+      # Calculates the percentage of records that match a given condition
+      # @overload (see ActiveRecord::Relation#percentage)
+      #
+      # @see ActiveRecord::Relation#percentage
+      # @param (see ActiveRecord::Relation#percentage)
+      # @return (see ActiveRecord::Relation#percentage)
+      # @example (see ActiveRecord::Relation#percentage)
+
+      # @method scopped
+      # @api public
+      #
+      # Applies the given filters to the relation, returning a new relation
+      # @overload (see ActiveRecord::Relation#scopped)
+      # @see ActiveRecord::Relation#scopped
+      # @param (see ActiveRecord::Relation#scopped)
+      # @return (see ActiveRecord::Relation#scopped)
+      # @example (see ActiveRecord::Relation#scopped)
+
+      # @method pluck_as_json
+      # @api public
+      #
+      # Plucks specified columns and returns an array of hashes
+      #
+      # @overload (see ActiveRecord::Relation#pluck_as_json)
+      # @see ActiveRecord::Relation#pluck_as_json
+      # @param (see ActiveRecord::Relation#pluck_as_json)
+      # @return (see ActiveRecord::Relation#pluck_as_json)
+      # @example (see ActiveRecord::Relation#pluck_as_json)
     end
   end
 end
-

data/lib/active_record/relation_ext.rb

@@ -1,23 +1,121 @@
+# frozen_string_literal: true
+
 require 'active_record'
 
 module ActiveRecord
+  # Extends +ActiveRecord::Relation+ with additional instance methods.
+  #
+  # These methods are available on all ActiveRecord relations.
   class Relation
+    # @api public
+    #
+    # Returns the percentage of records that match the given filter
+    #
+    # @overload percentage(**conditions)
+    #   @param conditions [Hash] a hash of column names and values to match.
+    # @overload percentage(sql_condition)
+    #   @param sql_condition [String] a raw SQL condition to evaluate.
+    # @overload percentage(*scopes)
+    #   @param scopes [Array<Symbol>] one or more named scopes to chain.
+    #
+    # @return [Float] fraction of matching records (0.0–1.0), or +0.0+
+    #   when the relation is empty (to avoid division by zero).
+    #
+    # @note Do *not* mix Symbol scope names with Hash or String conditions in a
+    #   single call.  Use Symbols together, or a single Hash/String — never both
+    #   forms at once.
+    #
+    # @example Using a named scope
+    #   Document.percentage(:with_error) #=> 0.75
+    #
+    # @example Using a hash condition
+    #   Document.percentage(status: :error) #=> 0.75
+    #
+    # @example Using a raw SQL string
+    #   Document.percentage("status = 'error'") #=> 0.75
+    #
+    # @example Chaining multiple named scopes
+    #   Document.percentage(:active, :with_error) #=> 0.25
+    #
+    # @example Within a nested scope
+    #   Document.active.percentage(:with_error) #=> 0.5
+    #
+    # @example Empty relation returns 0.0, not a Float
+    #   Document.where(id: nil).percentage(:with_error) #=> 0.0
+    #
+    # @see #scopped for the underlying implementation of filter application.
     def percentage(*filters)
-      return 0 if count == 0
+      return 0.0 if count.zero?
 
-      if filters.first.is_a?(Symbol)
-        filtered = filters.inject(self) do |relation, scope|
-          relation.public_send(scope)
-        end
-      else
-        filtered = where(*filters)
-      end
+      scopped(*filters).count / count.to_f
+    end
 
-      filtered.count * 1.0 / count
+    # @api private
+    #
+    # Applies the given filters to the relation, returning a new relation
+    #
+    # This is a helper method for +percentage+ to handle both named scopes and
+    # arbitrary conditions.
+    #
+    # @overload scopped(**conditions)
+    #   @param conditions [Hash] a hash of column names and values to match.
+    # @overload scopped(sql_condition)
+    #   @param sql_condition [String] a raw SQL condition to evaluate.
+    # @overload scopped(*scopes)
+    #   @param scopes [Array<Symbol>] one or more named scopes to chain.
+    #
+    # @return [ActiveRecord::Relation] a new relation with the filters applied.
+    #
+    # @example Using a named scope
+    #   Document.scopped(:with_error) #=> returns relation with :with_error scope applied
+    #
+    # @example Using a hash condition
+    #   Document.scopped(status: :error) #=> returns relation where status is error
+    #
+    # @example Using a raw SQL string
+    #   Document.scopped("status = 'error'") #=> returns relation where status is error
+    #
+    # @example Chaining multiple named scopes
+    #   Document.scopped(:active, :with_error) #=> returns relation with both scopes applied
+    def scopped(*filters)
+      return where(*filters) unless filters.first.is_a?(Symbol)
+
+      filters.inject(self) do |relation, scope|
+        relation.public_send(scope)
+      end
     end
 
+    # @api public
+    #
+    # Returns an array of hashes for the selected columns, one hash per record
+    #
+    # This is similar to +pluck+, but each row is represented as a Hash keyed
+    # by column name (as a Symbol) rather than a plain Array.
+    #
+    # When called with no arguments, returns the full +as_json+ representation
+    # of every record in the relation.
+    #
+    # @overload pluck_as_json(*keys)
+    #  @param keys [Array<Symbol>] column names to include in each hash.
+    # @overload pluck_as_json()
+    #
+    # @return [Array<Hash>] array of hashes mapping column name to value.
+    #
+    # @example Selecting specific columns
+    #   Document.pluck_as_json(:id, :status)
+    #   #=> [{ id: 1, status: "error" }, { id: 2, status: "success" }]
+    #
+    # @example No arguments returns all columns
+    #   Document.pluck_as_json
+    #   #=> [{ id: 1, status: "error", active: false, ... }, ...]
+    #
+    # @example Works with scope chains
+    #   Document.active.pluck_as_json(:id, :status)
+    #   #=> [{ id: 2, status: "success" }]
     def pluck_as_json(*keys)
-      keys.empty? ? map(&:as_json) : pluck(*keys).map { |i| i.as_hash(keys) }
+      return map(&:as_json) if keys.empty?
+
+      pluck(*keys).map { |entry| entry.as_hash(keys) }
     end
   end
 end

data/lib/darthjee/active_ext/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Darthjee
   module ActiveExt
-    VERSION = '1.3.2'
+    VERSION = '1.4.0'
   end
 end

data/lib/darthjee/active_ext.rb

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
+
 require 'darthjee/core_ext'
 require 'active_record/relation_ext'
 require 'active_record/base_ext'
 
 module Darthjee
+  # Namespace for the gem.
   module ActiveExt
     require 'darthjee/active_ext/version'
   end

data/lib/darthjee.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
+
+# Namespace for the gem.
 module Darthjee
   require 'darthjee/active_ext'
 end
-

data/spec/lib/active_record/relation_spec.rb

@@ -1,13 +1,15 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ActiveRecord::Relation do
-  let(:subject) { Document.all }
+  subject { Document }
 
-  describe '#percentage' do
+  describe '.percentage' do
     it_behaves_like 'a method that returns the percentage of objects found'
   end
 
-  describe '#pluck_as_json' do
+  describe '.pluck_as_json' do
     it_behaves_like 'a method that works as pluck but returning the keys'
   end
 end

data/spec/spec_helper.rb

@@ -1,12 +1,19 @@
+# frozen_string_literal: true
+
 require 'simplecov'
 
-SimpleCov.profiles.define 'gem' do
+if ENV['CI']
+  require 'simplecov-lcov'
+  SimpleCov::Formatter::LcovFormatter.config.report_with_single_file = true
+  SimpleCov.formatter = SimpleCov::Formatter::LcovFormatter
+end
+
+SimpleCov.start do
   add_filter '/spec/'
 end
 
-SimpleCov.start 'gem'
 require 'darthjee/active_ext'
-ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
 
 # This file was generated by the `rspec --init` command. Conventionally, all
 # specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
@@ -17,8 +24,8 @@ ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:"
 
 # Requires supporting ruby files with custom matchers and macros, etc,
 # in spec/support/ and its subdirectories.
-support_files = File.expand_path("spec/support/**/*.rb")
-Dir[support_files].each { |file| require file  }
+support_files = File.expand_path('spec/support/**/*.rb')
+Dir[support_files].each { |file| require file }
 
 RSpec.configure do |config|
   config.treat_symbols_as_metadata_keys_with_true_values = true
@@ -30,7 +37,4 @@ RSpec.configure do |config|
   # the seed, which is printed after each run.
   # --seed 1234
   config.order = 'random'
-
-  config.before do
-  end
 end

data/spec/support/models/document.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Document < ActiveRecord::Base
   scope :with_error, -> { where(status: :error) }
   scope :with_success, -> { where(status: :success) }

data/spec/support/schema.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 ActiveRecord::Schema.define do
   self.verbose = false
 
-  create_table :documents, :force => true do |t|
+  create_table :documents, force: true do |t|
     t.string :status
     t.boolean :active, default: false
     t.timestamps null: true

data/spec/support/shared_examples/active_relation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 shared_examples 'a method that returns the percentage of objects found' do
@@ -53,7 +55,7 @@ end
 shared_examples 'a method that works as pluck but returning the keys' do
   let(:json) { subject.pluck_as_json(:id, :status) }
   let(:expected) do
-    [ { id: 1, status: 'error' }, { id: 2, status: 'success' } ]
+    [{ id: 1, status: 'error' }, { id: 2, status: 'success' }]
   end
 
   before do
@@ -70,7 +72,7 @@ shared_examples 'a method that works as pluck but returning the keys' do
     let(:keys) do
       subject.pluck_as_json.first.keys
     end
-    let(:expected) {%w(id status updated_at created_at active)}
+    let(:expected) { %w[id status updated_at created_at active] }
 
     it 'returns all keys' do
       expect(keys).to match_array(expected)

metadata

@@ -1,141 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: darthjee-active_ext
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.4.0
 platform: ruby
 authors:
 - Darthjee
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-19 00:00:00.000000000 Z
+date: 2026-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.x
+        version: 7.2.x
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.x
+        version: 7.2.x
 - !ruby/object:Gem::Dependency
   name: darthjee-core_ext
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.5.6
+        version: 3.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.5.6
-- !ruby/object:Gem::Dependency
-  name: activerecord
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 5.x
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 5.x
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.6'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.6'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 11.3.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 11.3.0
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.14'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.14'
-- !ruby/object:Gem::Dependency
-  name: rspec-mocks
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.99.4
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.99.4
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.14.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.14.1
+        version: 3.1.0
 description: Extension of active support classes with usefull methods
 email:
 - darthjee@gmail.com
@@ -144,20 +46,29 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".circleci/config.yml"
+- ".github/active_ext-usage.md"
+- ".github/copilot-instructions.md"
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
+- Dockerfile
 - Gemfile
 - LICENSE
+- Makefile
 - README.md
 - Rakefile
 - active_ext.gemspec
+- config/check_specs.yml
+- config/rubycritc.rb
+- config/yardstick.rb
+- config/yardstick.yml
 - docker-compose.yml
 - lib/active_record/base_ext.rb
 - lib/active_record/relation_ext.rb
 - lib/darthjee.rb
 - lib/darthjee/active_ext.rb
 - lib/darthjee/active_ext/version.rb
-- spec/lib/active_record/base_spec.rb
 - spec/lib/active_record/relation_spec.rb
 - spec/spec_helper.rb
 - spec/support/models/document.rb
@@ -165,7 +76,8 @@ files:
 - spec/support/shared_examples/active_relation.rb
 homepage: https://github.com/darthjee/active_ext
 licenses: []
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'false'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -174,22 +86,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.3.1
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 3.5.9
 signing_key: 
 specification_version: 4
 summary: Active Extensions
-test_files:
-- spec/lib/active_record/base_spec.rb
-- spec/lib/active_record/relation_spec.rb
-- spec/spec_helper.rb
-- spec/support/models/document.rb
-- spec/support/schema.rb
-- spec/support/shared_examples/active_relation.rb
+test_files: []

data/spec/lib/active_record/base_spec.rb

@@ -1,13 +0,0 @@
-require 'spec_helper'
-
-describe ActiveRecord::Relation do
-  let(:subject) { Document }
-
-  describe '.percentage' do
-    it_behaves_like 'a method that returns the percentage of objects found'
-  end
-
-  describe '.pluck_as_json' do
-    it_behaves_like 'a method that works as pluck but returning the keys'
-  end
-end