azeroth 2.1.1 → 2.2.0

data/.github/core_ext-usage.md

@@ -0,0 +1,324 @@
+# Using `darthjee-core_ext` in Your Project
+
+This file is intended to be copied into the `.github/` folder of other projects.
+It provides GitHub Copilot (and developers) with a clear, actionable guide on how
+to use the [`darthjee-core_ext`](https://github.com/darthjee/core_ext) Ruby gem.
+
+---
+
+## What Is `core_ext`?
+
+`darthjee-core_ext` is a Ruby gem that extends Ruby's built-in (core) classes with
+additional utility methods. It follows the convention of "core extensions" — monkey-patching
+standard objects such as `Array`, `Hash`, `Symbol`, `Enumerable`, `Date`, `Object`,
+`Numeric`, and `Math` with useful helpers, while maintaining predictable behavior.
+
+- **Gem name**: `darthjee-core_ext`
+- **Source**: <https://github.com/darthjee/core_ext>
+- **YARD docs**: <https://www.rubydoc.info/gems/darthjee-core_ext>
+- **Current stable release**: 3.0.0
+
+---
+
+## Adding the Gem to Your Project
+
+### Via RubyGems (recommended)
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'darthjee-core_ext'
+```
+
+Or pin a specific version for reproducible builds:
+
+```ruby
+gem 'darthjee-core_ext', '~> 3.0'
+```
+
+### Via GitHub (source)
+
+```ruby
+gem 'darthjee-core_ext',
+    github: 'darthjee/core_ext',
+    branch: 'main'
+```
+
+---
+
+## Installing
+
+After adding the gem to your `Gemfile`, run:
+
+```shell
+bundle install
+```
+
+Or install it system-wide:
+
+```shell
+gem install darthjee-core_ext
+```
+
+---
+
+## Loading the Gem
+
+When using Bundler (Rails, typical Ruby apps), the gem is loaded automatically via
+`Bundler.require`. No explicit `require` is needed.
+
+In plain Ruby scripts or when Bundler auto-require is disabled, add:
+
+```ruby
+require 'darthjee/core_ext'
+```
+
+---
+
+## Extensions Provided
+
+### `Hash`
+
+| Method | Description |
+|---|---|
+| `#append_to_keys` | Appends a string to every key |
+| `#prepend_to_keys` | Prepends a string to every key |
+| `#camelize_keys` / `#camelize_keys!` | Converts keys to CamelCase |
+| `#lower_camelize_keys` / `#lower_camelize_keys!` | Converts keys to lowerCamelCase |
+| `#underscore_keys` / `#underscore_keys!` | Converts keys to snake_case |
+| `#change_keys` / `#change_keys!` | Transforms keys with a block |
+| `#chain_change_keys` / `#chain_change_keys!` | Transforms keys by chaining method calls |
+| `#change_values` / `#change_values!` | Transforms values with a block (optionally recursive) |
+| `#chain_fetch` | Fetches nested keys in a chain |
+| `#exclusive_merge` / `#exclusive_merge!` | Merges only existing keys |
+| `#remap_keys` / `#remap_keys!` | Renames keys based on a mapping hash |
+| `#sort_keys` / `#sort_keys!` | Sorts the hash by its keys |
+| `#squash` / `#squash!` | Flattens a deep hash into a single-level hash |
+| `#to_deep_hash` / `#to_deep_hash!` | Expands a squashed hash back into a deep hash |
+| `#map_to_hash` | Maps values keeping original keys |
+| `#transpose` / `#transpose!` | Swaps keys with values |
+
+### `Array`
+
+| Method | Description |
+|---|---|
+| `#as_hash` | Zips the array with a keys array into a Hash |
+| `#average` | Returns the arithmetic average of the elements |
+| `#chain_map` | Applies `.map` in a chain of method calls |
+| `#mapk` | Maps by fetching nested keys from hashes inside the array |
+| `#procedural_join` | Joins elements with a dynamically computed separator |
+| `#random` | Returns a random element |
+| `#random!` | Removes and returns a random element |
+
+### `Symbol`
+
+| Method | Description |
+|---|---|
+| `#camelize` | Camelizes the symbol (`:my_sym` → `:MySym`) |
+| `#underscore` | Underscores a camelized symbol (`:MySym` → `:my_sym`) |
+
+### `Enumerable` (available on `Array`, `Hash`, and any `Enumerable`)
+
+| Method | Description |
+|---|---|
+| `#clean` | Returns a copy with empty values removed |
+| `#clean!` | Removes empty values in place (recursive) |
+| `#map_and_find` | Maps and stops at the first truthy result |
+| `#map_and_select` | Maps and returns only truthy results |
+| `#map_to_hash` | Maps values, using original elements as keys |
+
+### `Object` (available on every Ruby object)
+
+| Method | Description |
+|---|---|
+| `#is_any?` | Returns `true` if the object is an instance of any of the given classes |
+| `#trueful?` | Returns `true` only when the object is not `nil` (unlike `#present?`, `[]` and `{}` are trueful) |
+
+### `Date`
+
+| Method | Description |
+|---|---|
+| `#days_between` | Returns the absolute number of days between two dates |
+
+### `Math`
+
+| Method | Description |
+|---|---|
+| `.average` | Calculates the (optionally weighted) average of values |
+
+### `Class`
+
+| Method | Description |
+|---|---|
+| `.default_value` | Adds a reader that returns the same default instance every time |
+| `.default_values` | Adds multiple readers sharing the same default instance |
+| `.default_reader` | Adds a reader that returns a default value only when the instance variable was never set |
+| `.default_readers` | Adds multiple default readers sharing the same default value |
+
+---
+
+## Code Examples
+
+### Hash key transformations
+
+```ruby
+# Converting API responses from camelCase to snake_case
+response = { 'userId' => 1, 'firstName' => 'Alice' }
+response.underscore_keys  # => { 'user_id' => 1, 'first_name' => 'Alice' }
+
+# Preparing a payload for a camelCase API
+params = { user_id: 1, first_name: 'Alice' }
+params.lower_camelize_keys
+# => { userId: 1, firstName: 'Alice' }
+
+# Equivalent long form with explicit option
+params.camelize_keys(uppercase_first_letter: false)
+# => { userId: 1, firstName: 'Alice' }
+```
+
+### Fetching nested values safely
+
+```ruby
+config = { database: { primary: { host: 'localhost' } } }
+
+config.chain_fetch(:database, :primary, :host)  # => 'localhost'
+config.chain_fetch(:database, :replica, :host) { |key, _rest| "default-#{key}" }
+# => 'default-replica'
+```
+
+### Flattening and restoring deep hashes
+
+```ruby
+deep = { a: { b: [1, 2] } }
+flat = deep.squash   # => { 'a.b[0]' => 1, 'a.b[1]' => 2 }
+flat.to_deep_hash    # => { 'a' => { 'b' => [1, 2] } }
+```
+
+### Exclusive merge (update only existing keys)
+
+```ruby
+defaults = { timeout: 30, retries: 3 }
+overrides = { retries: 5, unknown_key: 'ignored' }
+
+defaults.exclusive_merge(overrides)  # => { timeout: 30, retries: 5 }
+```
+
+### Array utilities
+
+```ruby
+# Zip an array with keys into a Hash
+values = [10, 20, 30]
+values.as_hash(%i[x y z])  # => { x: 10, y: 20, z: 30 }
+
+# Chain map calls
+[:hello, :world].chain_map(:to_s, :upcase)  # => ['HELLO', 'WORLD']
+
+# Fetch nested keys from an array of hashes
+records = [{ user: { id: 1 } }, { user: { id: 2 } }]
+records.mapk(:user, :id)  # => [1, 2]
+```
+
+### Symbol utilities
+
+```ruby
+:my_method_name.camelize         # => :MyMethodName
+:my_method_name.camelize(:lower) # => :myMethodName
+:MyMethodName.underscore         # => :my_method_name
+```
+
+### Enumerable cleaning
+
+```ruby
+data = { name: 'Alice', nickname: nil, tags: [], meta: {} }
+data.clean   # => { name: 'Alice' }
+
+mixed = [1, nil, '', [], {}, 'hello']
+mixed.clean  # => [1, 'hello']
+```
+
+### Object helpers
+
+```ruby
+value = 42
+value.is_any?(String, Symbol)         # => false
+value.is_any?(String, Symbol, Integer)  # => true
+
+nil.trueful?          # => false
+[].trueful?           # => true   (unlike blank?/present?)
+''.trueful?           # => true
+```
+
+### Class default readers
+
+```ruby
+class Report
+  attr_writer :title
+  default_reader :title, 'Untitled Report'
+end
+
+r = Report.new
+r.title         # => 'Untitled Report'
+r.title = 'Q1'
+r.title         # => 'Q1'
+r.title = nil
+r.title         # => nil  (nil is respected; differs from default_value)
+```
+
+### Math weighted average
+
+```ruby
+# Simple average
+Math.average([10, 20, 30])  # => 20.0
+
+# Weighted average (value => weight)
+Math.average(10 => 1, 20 => 2, 30 => 1)  # => 20.0
+```
+
+---
+
+## Best Practices and Caveats
+
+### Monkey-patching awareness
+
+`core_ext` extends Ruby's built-in classes globally. This means:
+
+- All objects of the extended classes gain the new methods **throughout your entire application**, including third-party gems.
+- **Name collision risk**: if another gem or your application already defines a method with the same name on the same class, the last `require`/`load` wins. Review the method list above before adoption and check for conflicts.
+- In libraries (gems) intended for wide reuse, prefer not requiring `core_ext` at the top level unless you own all consumers.
+
+### Recursive options
+
+Several `Hash` methods (`change_keys`, `camelize_keys`, `underscore_keys`, `change_values`, `clean!`) operate recursively by default, descending into nested arrays and hashes. Pass `recursive: false` when you only need shallow transformation to avoid unintended side-effects on nested structures.
+
+### Bang (`!`) methods vs. non-bang methods
+
+Methods ending with `!` mutate the receiver **in place**. Use them when you are sure you do not need the original structure. Use the non-bang variants to return a transformed copy.
+
+### Versioning
+
+Pin to a minor version to avoid unexpected breaking changes:
+
+```ruby
+gem 'darthjee-core_ext', '~> 3.0'
+```
+
+Check the [CHANGELOG / releases page](https://github.com/darthjee/core_ext/releases) before upgrading.
+
+---
+
+## Running the Test Suite / Contributing
+
+If you are contributing to `core_ext` itself or want to verify its behavior locally:
+
+```shell
+# Install dependencies
+bundle install
+
+# Run the full test suite
+bundle exec rspec
+
+# Run a single spec file
+bundle exec rspec spec/lib/darthjee/core_ext/hash_spec.rb
+```
+
+Tests live under `spec/` and mirror the structure of `lib/`. Every public method must have a corresponding spec. See the [README](https://github.com/darthjee/core_ext/blob/main/README.md) and the repository's Copilot instructions (`.github/copilot-instructions.md`) for more details.

data/.github/jace-usage.md

@@ -0,0 +1,241 @@
+# Using the Jace Gem
+
+## What is Jace?
+
+**Jace** is a Ruby gem for event-driven development **within a single application**.
+It is not about distributed architecture or message queues — it is about building
+internal event-oriented logic inside a Ruby gem or application.
+
+With Jace, you register handlers for named events and trigger those events from
+anywhere in your codebase. When an event is triggered, Jace executes the registered
+`before` handlers (inside the context via `instance_eval`), then the main block,
+then the `after` handlers (also inside the context via `instance_eval`).
+
+---
+
+## Installation
+
+Add `jace` to your `Gemfile`:
+
+```ruby
+gem 'jace'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install jace
+```
+
+---
+
+## Core Concepts
+
+### `Jace::Registry`
+
+The central object. It stores event-to-handler mappings and exposes two public
+methods: `register` and `trigger`.
+
+```ruby
+registry = Jace::Registry.new
+```
+
+### `register(event, instant = :after, &block)`
+
+Adds a handler block for a named event. The `instant` parameter controls whether
+the block runs before or after the main event block.
+
+| `instant` | When the handler runs |
+|-----------|----------------------|
+| `:after` (default) | After the main block |
+| `:before` | Before the main block |
+
+```ruby
+registry.register(:payment_processed)          { send_receipt }
+registry.register(:payment_processed, :before) { validate_payment }
+```
+
+### `trigger(event, context, &block)`
+
+Fires the named event. Jace runs the `before` handlers, then the given block,
+then the `after` handlers. The `before` and `after` handlers are `instance_eval`'d
+inside `context`, so bare method calls in handlers resolve against the context.
+The main block is called normally (not `instance_eval`'d), so it uses the
+surrounding scope's receiver.
+
+```ruby
+registry.trigger(:payment_processed, payment_object) do
+  charge_credit_card
+end
+```
+
+---
+
+## Basic Usage
+
+```ruby
+class Order
+  attr_reader :log
+
+  def initialize
+    @log = []
+  end
+
+  def validate
+    log << 'validated'
+  end
+
+  def persist
+    log << 'persisted'
+  end
+
+  def notify
+    log << 'notified'
+  end
+end
+
+registry = Jace::Registry.new
+order    = Order.new
+
+registry.register(:save, :before) { validate }
+registry.register(:save)          { notify }
+
+registry.trigger(:save, order) do
+  order.persist   # main block uses the surrounding scope, so explicit receiver is needed
+end
+
+order.log
+# => ['validated', 'persisted', 'notified']
+```
+
+---
+
+## Handler Types
+
+Handlers are registered as **blocks** (procs) and are `instance_eval`'d inside
+the context object when the event fires, so bare method calls resolve against
+the context.
+
+```ruby
+registry.register(:shipment_sent)          { send_confirmation_email }
+registry.register(:shipment_sent, :before) { freeze_order }
+```
+
+---
+
+## Multiple Handlers per Event
+
+You can register as many `before` and `after` handlers as you like for the same
+event. They execute in registration order.
+
+```ruby
+registry.register(:user_created, :before) { sanitize_input }
+registry.register(:user_created, :before) { check_duplicates }
+registry.register(:user_created)          { send_welcome_email }
+registry.register(:user_created)          { notify_admin }
+
+registry.trigger(:user_created, user_context) do
+  persist_user
+end
+# Order: sanitize_input → check_duplicates → persist_user
+#        → send_welcome_email → notify_admin
+```
+
+---
+
+## Triggering Events Without a Main Block
+
+The main block is optional. If omitted, only the registered handlers run:
+
+```ruby
+registry.trigger(:cache_invalidated, cache_context)
+# Runs all :before handlers, then all :after handlers; no main block
+```
+
+---
+
+## Triggering an Unregistered Event
+
+Triggering an event that has no registered handlers is safe. The main block is
+still executed, and no error is raised:
+
+```ruby
+registry.trigger(:unknown_event, some_context) do
+  do_work
+end
+# do_work runs normally; no handlers fire
+```
+
+---
+
+## Typical Integration Pattern
+
+The most common pattern is to hold a `Jace::Registry` instance inside a service
+or module and expose `register` to callers so they can hook into lifecycle events:
+
+```ruby
+module PaymentService
+  REGISTRY = Jace::Registry.new
+
+  def self.on(event, instant = :after, &block)
+    REGISTRY.register(event, instant, &block)
+  end
+
+  def self.process(payment)
+    REGISTRY.trigger(:payment_processed, payment) do
+      payment.charge!
+    end
+  end
+end
+
+# In an initializer or plugin:
+PaymentService.on(:payment_processed)          { send_receipt }
+PaymentService.on(:payment_processed, :before) { log_attempt }
+
+# Elsewhere in the application:
+PaymentService.process(payment)
+# Runs: log_attempt → payment.charge! → send_receipt
+```
+
+---
+
+## Execution Model (summary)
+
+```
+registry.trigger(:event, context) { main_block }
+
+Execution order:
+  1. All :before handlers  (in registration order, instance_eval'd in context)
+  2. main_block            (called as-is, context is NOT the receiver)
+  3. All :after  handlers  (in registration order, instance_eval'd in context)
+```
+
+> **Note:** The `before` and `after` handlers are `instance_eval`'d inside the
+> context object, so bare method calls inside them (`send_receipt`, `validate`,
+> etc.) resolve against the context. The main block, however, is a regular
+> `call` (not `instance_eval`), so its receiver is the surrounding scope.
+
+---
+
+## API Reference
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `Registry#register` | `(event, instant = :after, &block)` | Adds a handler to the named event |
+| `Registry#trigger` | `(event, context, &block)` | Fires the event, running handlers around the block |
+| `Registry#events` | `()` | Returns all registered event names as `Array<Symbol>` |
+| `Registry#registry` | `()` | Returns the raw `Hash` of event → `Dispatcher` mappings |
+
+---
+
+## YARD Documentation
+
+Full API docs: [https://www.rubydoc.info/gems/jace](https://www.rubydoc.info/gems/jace)
+
+Source: [https://github.com/darthjee/jace](https://github.com/darthjee/jace)

data/.rubocop.yml

@@ -1,4 +1,9 @@
-require: rubocop-rspec
+plugins:
+  - rubocop-rspec
+  - rubocop-rake
+  - rubocop-factory_bot
+  - rubocop-rails
+  - rubocop-rspec_rails
 inherit_from: .rubocop_todo.yml
 
 AllCops:
@@ -49,3 +54,11 @@ Lint/EmptyBlock:
 
 Lint/EmptyClass:
   Enabled: false
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/support/matchers/add_method.rb'
+
+FactoryBot/ExcessiveCreateList:
+  Exclude:
+    - 'spec/integration/yard/controllers/paginated_documents_controller_spec.rb'

data/.rubocop_todo.yml

@@ -1,21 +1,7 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2019-03-26 17:30:42 +0000 using RuboCop version 0.58.1.
+# on 2026-03-12 10:44:24 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.
-
-# Offense count: 8
-Style/Documentation:
-  Exclude:
-    - 'spec/**/*'
-    - 'test/**/*'
-    - 'lib/azeroth.rb'
-    - 'lib/azeroth/model.rb'
-    - 'lib/azeroth/options.rb'
-    - 'lib/azeroth/resource_builder.rb'
-    - 'lib/azeroth/resource_route_builder.rb'
-    - 'lib/azeroth/resourceable.rb'
-    - 'lib/azeroth/resourceable/builder.rb'
-    - 'lib/azeroth/routes_builder.rb'

data/Dockerfile

@@ -1,6 +1,6 @@
-FROM darthjee/scripts:0.4.3 as scripts
+FROM darthjee/scripts:0.7.0 as scripts
 
-FROM darthjee/rails_gems:2.0.0 as base
+FROM darthjee/rails_gems:2.1.1 as base
 
 COPY --chown=app:app ./ /home/app/app/
 

data/Gemfile

@@ -6,30 +6,34 @@ gemspec
 
 gem 'actionpack',                '7.2.2.1'
 gem 'activerecord',              '7.2.2.1'
-gem 'bundler',                   '~> 2.6.8'
-gem 'factory_bot',               '6.2.1'
-gem 'minitest',                  '5.25.4'
-gem 'nokogiri',                  '1.18.8'
+gem 'bundler',                   '>= 2.5.13'
+gem 'factory_bot',               '6.5.6'
+gem 'nokogiri',                  '1.19.1'
 gem 'pry',                       '0.14.2'
 gem 'pry-nav',                   '1.0.0'
 gem 'rails',                     '7.2.2.1'
 gem 'rails-controller-testing',  '1.0.5'
 gem 'rake',                      '13.2.1'
-gem 'reek',                      '6.4.0'
-gem 'rspec',                     '3.13.0'
+gem 'reek',                      '6.5.0'
+gem 'rspec',                     '3.13.2'
 gem 'rspec-collection_matchers', '1.2.1'
-gem 'rspec-core',                '3.13.3'
-gem 'rspec-expectations',        '3.13.3'
-gem 'rspec-mocks',               '3.13.2'
-gem 'rspec-rails',               '8.0.0'
-gem 'rspec-support',             '3.13.2'
-gem 'rubocop',                   '1.75.5'
-gem 'rubocop-rspec',             '3.6.0'
-gem 'rubycritic',                '4.9.2'
-gem 'shoulda-matchers',          '6.5.0'
+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-factory_bot',       '2.28.0'
+gem 'rubocop-rails',             '2.34.3'
+gem 'rubocop-rake',              '0.7.1'
+gem 'rubocop-rspec',             '3.9.0'
+gem 'rubocop-rspec_rails',       '2.32.0'
+gem 'rubycritic',                '5.0.0'
+gem 'shoulda-matchers',          '7.0.1'
 gem 'simplecov',                 '0.22.0'
+gem 'simplecov-html',            '0.13.2'
+gem 'simplecov-lcov',            '0.9.0'
 gem 'sprockets-rails',           '3.5.2'
 gem 'sqlite3',                   '1.4.2'
 gem 'tzinfo-data',               '~> 1.2025.2'
-gem 'yard',                      '0.9.37'
+gem 'yard',                      '0.9.38'
 gem 'yardstick',                 '0.9.9'