azeroth 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bb67d32bc51b4aa26e666ec6d4f942dba16b454d07cf65cb5ebff1f052766ae
-  data.tar.gz: b5d68c84445bde028dcc0038cfe075947de6d45ffb31afb5f7bec088de680a09
+  metadata.gz: 3abf116f0ed9063b02d06bba4bcedee4ec48036aaaf2a86238a5b4fcfe32b804
+  data.tar.gz: ba519353edc46b56834662db662a650b1bfddbbd3d10a3726b42aadb343fec73
 SHA512:
-  metadata.gz: c2604e2557de1bf029e1fbb0f32d16957e150a302c80b4db0c95e70dc2c7809f4883365b0e7f5756dfb8348aafd304f7262087ca80f95fa3f24e626a4dafe2b0
-  data.tar.gz: a54c254012d8de5f00c799a5cc9fa3e65467d8c624e3ad1d8eff8adf892f3bd7ec6b80134abd61766e0cadf37719a56d607b9d241af7c038fb56591b93255e94
+  metadata.gz: 181f6a5e4f0caf6a4d7e1e383956aad1b7cd34fccb3b30586e5d39e920de143ba5a1fd4dde681f3db368a39badbf9d3eb53ca3fc77e3e719927c8fd00c5043cf
+  data.tar.gz: 41baee7b1b1f00fe82a32da29ccd4c38470e504855a6036c56e28db51d04c3335a40a76c68b84cf2b266045d88c6d685f941fbd66370dd1763e8b671e51ed13d

data/.circleci/config.yml

@@ -18,18 +18,15 @@ workflows:
               only: /\d+\.\d+\.\d+/
             branches:
               only:
-                - master
+                - main
 jobs:
   test:
     docker:
-      - image: darthjee/circleci_rails_gems:2.0.0
+      - image: darthjee/circleci_rails_gems:2.1.1
         environment:
           PROJECT: azeroth
     steps:
       - checkout
-      - run:
-          name: Prepare Coverage Test Report
-          command: cc-test-reporter before-build
       - run:
           name: Bundle Install
           command: bundle install
@@ -37,11 +34,11 @@ jobs:
           name: RSpec
           command: bundle exec rspec
       - run:
-          name: Coverage Test Report
-          command: cc-test-reporter after-build --exit-code $?
+          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.0.0
+      - image: darthjee/circleci_rails_gems:2.1.1
         environment:
           PROJECT: azeroth
     steps:
@@ -66,7 +63,7 @@ jobs:
           command: check_specs
   build-and-release:
     docker:
-      - image: darthjee/circleci_rails_gems:2.0.0
+      - image: darthjee/circleci_rails_gems:2.1.1
         environment:
           PROJECT: azeroth
     steps:

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/azeroth-usage.md

@@ -0,0 +1,277 @@
+# Azeroth Gem Usage Instructions
+
+This file provides guidance for GitHub Copilot when working in projects that use the [Azeroth](https://github.com/darthjee/azeroth) gem.
+
+## About Azeroth
+
+Azeroth is a Ruby gem that simplifies the creation of Rails controller endpoints. Its main feature is the `resource_for` class method, which automatically generates controller action methods (`create`, `show`, `index`, `update`, `delete`, `edit`) and handles both HTML and JSON request formats transparently.
+
+- HTML requests render templates without performing database operations.
+- JSON requests perform database operations and return serialized JSON.
+
+## Installation
+
+Add Azeroth to your `Gemfile`:
+
+```ruby
+gem 'azeroth'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Basic Usage
+
+### Setting Up `resource_for`
+
+Include `Azeroth::Resourceable` in your controller and call `resource_for` with the resource name:
+
+```ruby
+class PublishersController < ApplicationController
+  include Azeroth::Resourceable
+  skip_before_action :verify_authenticity_token
+
+  resource_for :publisher, only: %i[create index]
+end
+```
+
+This generates the following behavior:
+- `GET /publishers` → calls `index`, returns all publishers
+- `POST /publishers` → calls `create`, creates a new publisher
+
+### Available Actions
+
+By default, `resource_for` builds all six standard actions: `create`, `show`, `index`, `update`, `delete`, and `edit`. Use `only:` or `except:` to restrict which actions are generated:
+
+```ruby
+# Only generate index and show
+resource_for :article, only: %i[index show]
+
+# Generate everything except delete
+resource_for :article, except: :delete
+```
+
+### Nested Resources
+
+Override the collection method to scope resources to a parent:
+
+```ruby
+class GamesController < ApplicationController
+  include Azeroth::Resourceable
+  skip_before_action :verify_authenticity_token
+
+  resource_for :game, except: :delete
+
+  private
+
+  def games
+    publisher.games
+  end
+
+  def publisher
+    @publisher ||= Publisher.find(publisher_id)
+  end
+
+  def publisher_id
+    params.require(:publisher_id)
+  end
+end
+```
+
+## `resource_for` Options
+
+| Option | Type | Description |
+|---|---|---|
+| `only` | Symbol / Array | List of actions to generate |
+| `except` | Symbol / Array | List of actions to skip |
+| `decorator` | Class / Boolean | Decorator class or flag to enable/disable decoration |
+| `before_save` | Symbol / Proc | Method or proc called before `create` or `update` saves |
+| `after_save` | Symbol / Proc | Method or proc called after `create` or `update` saves |
+| `build_with` | Symbol / Proc | Method or block used to build the resource on `create` |
+| `update_with` | Symbol / Proc | Method or block used to update the resource on `update` |
+| `paginated` | Boolean | Enable pagination on the `index` action |
+| `per_page` | Integer | Number of items per page when pagination is active (default: 20) |
+| `id_key` | Symbol | Parameter key used to look up a single resource (default: `:id`) |
+| `param_key` | Symbol | Parameter key used to find the model |
+
+### Callbacks: `before_save` and `after_save`
+
+```ruby
+class PokemonsController < ApplicationController
+  include Azeroth::Resourceable
+
+  resource_for :pokemon,
+               only: %i[create update],
+               before_save: :set_favorite
+
+  private
+
+  def set_favorite
+    pokemon.favorite = true
+  end
+end
+```
+
+### Pagination
+
+```ruby
+class DocumentsController < ApplicationController
+  include Azeroth::Resourceable
+
+  resource_for :document, only: :index, paginated: true, per_page: 10
+end
+```
+
+A paginated `index` request returns the items for the requested page and sets the following response headers:
+
+| Header | Description |
+|---|---|
+| `pages` | Total number of pages |
+| `per_page` | Number of items per page |
+| `page` | Current page number |
+
+```bash
+GET /documents.json        # page 1 – first 10 documents
+GET /documents.json?page=2 # page 2 – next 10 documents
+```
+
+## JSON Serialization with `Azeroth::Decorator`
+
+Decorators control which attributes are included in JSON responses.
+
+### Defining a Decorator
+
+Create a decorator class that inherits from `Azeroth::Decorator` and call `expose` for each attribute to include:
+
+```ruby
+# app/decorators/pokemon/decorator.rb
+class Pokemon::Decorator < Azeroth::Decorator
+  expose :name
+  expose :previous_form_name, as: :evolution_of, if: :evolution?
+
+  def evolution?
+    previous_form
+  end
+
+  def previous_form_name
+    previous_form.name
+  end
+end
+```
+
+### `expose` Options
+
+| Option | Type | Description |
+|---|---|---|
+| `as` | Symbol | Custom JSON key for the attribute |
+| `if` | Symbol / Proc | Method or block; attribute is only included when it returns truthy |
+| `decorator` | Class / Boolean | Nested decorator class or flag to enable/disable decoration |
+| `reader` | Boolean | Whether to create a reader method for the attribute |
+| `override` | Boolean | Whether to override an existing method with the same name |
+
+### Decorator Inheritance
+
+Extend decorators by subclassing them:
+
+```ruby
+# app/decorators/pokemon/favorite_decorator.rb
+class Pokemon::FavoriteDecorator < Pokemon::Decorator
+  expose :nickname
+end
+```
+
+### Using a Custom Decorator in a Controller
+
+Pass the decorator class to `resource_for`:
+
+```ruby
+class PokemonsController < ApplicationController
+  include Azeroth::Resourceable
+
+  resource_for :pokemon, decorator: Pokemon::FavoriteDecorator
+end
+```
+
+## `model_for`
+
+`model_for` adds singular and plural resource accessor methods to a controller (e.g., `document` and `documents`) **without** generating any HTTP route actions. This is useful when a controller needs to access a resource as context (for example a parent record) but should not expose CRUD endpoints for it.
+
+### Options
+
+| Option | Type | Description |
+|---|---|---|
+| `id_key` | Symbol | Parameter key used to find the record (default: `:id`) |
+| `param_key` | Symbol | Parameter key used to find the model |
+
+### Example
+
+```ruby
+class PostsController < ApplicationController
+  include Azeroth::Resourceable
+
+  # Generates full CRUD endpoints for Post,
+  # scoped to the author resolved by model_for below.
+  resource_for :post
+
+  # Only adds `author` and `authors` helper methods —
+  # no HTTP actions are created for Author.
+  model_for :author, id_key: :author_id
+
+  private
+
+  def posts
+    author.posts
+  end
+end
+```
+
+In this example:
+- `GET /authors/:author_id/posts.json` returns all posts belonging to the author.
+- `author` is resolved automatically via `Author.find(params[:author_id])`.
+- No `/authors` CRUD endpoints are generated.
+
+## Best Practices
+
+- **Use `only:` / `except:`** to expose only the actions your controller actually needs.
+- **Override collection methods** (e.g., `def games`) to scope resources to a parent instead of returning the full table.
+- **Use decorators** to keep serialization logic out of controllers and models.
+- **Use `before_save` / `after_save`** callbacks for business logic that must run around persistence, rather than overriding generated action methods.
+- **Prefer `resource_for`** over hand-written CRUD actions for standard resources to ensure consistent behavior across your application.
+
+## Testing Controllers That Use Azeroth
+
+Use standard Rails request specs or controller specs with RSpec. Since Azeroth generates conventional Rails actions, they can be exercised like any other controller action:
+
+```ruby
+RSpec.describe PokemonsController, type: :request do
+  let(:master) { create(:pokemon_master) }
+
+  describe 'POST /pokemons' do
+    it 'creates a pokemon' do
+      post "/pokemon_masters/#{master.id}/pokemons.json",
+           params: { pokemon: { name: 'Bulbasaur' } }
+
+      expect(response).to have_http_status(:created)
+      expect(response.parsed_body['name']).to eq('Bulbasaur')
+    end
+  end
+
+  describe 'GET /pokemons' do
+    it 'returns all pokemons' do
+      get "/pokemon_masters/#{master.id}/pokemons.json"
+
+      expect(response).to have_http_status(:ok)
+      expect(response.parsed_body).to be_an(Array)
+    end
+  end
+end
+```
+
+## Further Reading
+
+- [Azeroth on RubyGems](https://rubygems.org/gems/azeroth)
+- [YARD Documentation](https://www.rubydoc.info/gems/azeroth)
+- [GitHub Repository](https://github.com/darthjee/azeroth)

data/.github/copilot-instructions.md

@@ -0,0 +1,70 @@
+# GitHub Copilot Instructions for Azeroth
+
+## Project Overview
+
+Azeroth is a Ruby gem that simplifies the creation of Rails controller endpoints. The main feature is the `resource_for` method, which automatically generates controller action methods (`create`, `show`, `index`, `update`, `delete`, `edit`) and handles both HTML and JSON request formats transparently.
+
+## Language Requirements
+
+- All pull requests, comments, documentation, and code must be written in **English**.
+
+## Testing Requirements
+
+- **Tests are mandatory** for all code changes.
+- Every new class, module, or method must have corresponding specs under `spec/`.
+- Files without test coverage must be listed in `config/check_specs.yml` under the `ignore:` key.
+- Use RSpec for all tests, following the conventions already established in the `spec/` directory.
+- Ensure comprehensive test coverage for new features and changes, including edge cases.
+
+## Documentation Requirements
+
+- Use **YARD** format for all documentation.
+- Document all public methods, classes, and modules with:
+  - A summary line (single-line, ending with a period).
+  - `@param` tags for each parameter.
+  - `@return` tag describing the return value.
+  - `@example` tags showing representative usage where appropriate.
+  - `@api public` or `@api private` tags to mark visibility.
+- Documentation coverage is enforced via `config/yardstick.yml` (threshold: 96.5%).
+
+## Code Style and Design Principles
+
+- Follow the principles from **Sandi Metz's "99 Bottles of OOP"**:
+  - Prefer small, well-named methods with a single responsibility.
+  - Avoid large, complex methods—break them into smaller, well-defined ones.
+  - Aim for high cohesion and low coupling between classes.
+- Respect the **Law of Demeter**: avoid chaining method calls across object boundaries.
+- Keep classes focused; a class should do one thing and do it well.
+- Prefer composition over inheritance where possible.
+- Follow the **RuboCop** rules configured in `.rubocop.yml` (Ruby 3.3 target).
+
+## Project-Specific Guidelines
+
+- The gem is a **Rails** extension—follow Rails conventions and best practices.
+- The core abstraction is `Azeroth::Resourceable` (mixed into controllers via `include Azeroth::Resourceable`), which exposes the `resource_for` class method.
+- `Azeroth::Decorator` is used to control JSON serialization; use `expose` to declare which attributes are rendered.
+- **Maintain backward compatibility** when modifying existing public APIs.
+- Pagination is opt-in via `paginated: true` on `resource_for`; respect the `per_page` option and the pagination response headers (`pages`, `per_page`, `page`).
+- New options added to `resource_for` or `model_for` must be documented and covered by integration specs (see `spec/integration/`).
+
+## Using dependencies
+
+### Using Jace for Event-Driven Hooks
+
+Azeroth uses the [jace](https://github.com/darthjee/jace) gem to provide event-driven lifecycle hooks around controller actions. Refer to [`.github/jace-usage.md`](.github/jace-usage.md) for the full Jace API reference and usage patterns.
+
+Key points when working with Jace inside Azeroth:
+
+- Use `Jace::Registry` to register and trigger events.
+- Register handlers with `registry.register(event, instant = :after, &block)`, where `instant` is `:before` or `:after`.
+- Trigger events with `registry.trigger(event, context, &block)`; `:before` and `:after` handlers are `instance_eval`'d in `context`, while the main block is called in the surrounding scope.
+- Triggering an event with no registered handlers is safe—the main block still runs.
+
+
+### Using darthjee-core_ext for extending core classes
+
+Azeroth uses the [darthjee-core_ext](https://github.com/darthjee/core_ext) gem to extend core Ruby classes with additional methods. Refer to [`.github/core_ext-usage.md`](.github/core_ext-usage.md) for the full list of available extensions and usage examples.
+
+### Using darthjee-active_ext for extending active record and active support classes
+
+Azeroth uses the [darthjee-active_ext](https://github.com/darthjee/active_ext) gem to extend Active Record and Active Support classes with additional methods. Refer to [`.github/active_ext-usage.md`](.github/active_ext-usage.md) for the full list of available extensions and usage examples.