tarquinn 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b942f4c6eef09e4a94c12a33da00f6c878ebeb30d348dc06dad7aa2274d635b9
-  data.tar.gz: b80da172aef6a2067b97444c53842bed6215afbbba5d885793376f8f8ff8f6a6
+  metadata.gz: 472e75e26a2d619f0284c9eb797c5e47f717a9f9a6e52757fc1c5ad7272a174f
+  data.tar.gz: efb31ef0021491a3b99c48cb8c3a34026493a10500636449195c1070d281dc91
 SHA512:
-  metadata.gz: cbb0a21142829270e9ac2590ff071ed5dfada57c2bf6ba116543b9c8c735eb88f8170a6550b3badbc56506dbae2dfc109f76c88c7e40efaa90c94a3b3bb61629
-  data.tar.gz: 1b7fe947a50f0ee13e0ef2cdd1842b18f19af51c347d494442f34abf2eb4195f5335fcbdec8794933465652af544fa463b8d3846a49ff4c12835d17ace565d03
+  metadata.gz: 9391c038495ea739fee48b43a9c104bcb0dfb887aa87ecb75be3d1378ee2c11649cc68725fd8beea215036065b5deb1aeca08babea956d77b42628b887ead261
+  data.tar.gz: 59ccde1cade0e2b76b82f89073409cf9ced274d7346214ae08f2d4e6f06e11269feb9b768c219064bcec0e748205c1ce6a5eb45515e21dbe404a53459cb6643b

data/.circleci/config.yml

@@ -18,30 +18,24 @@ workflows:
               only: /\d+\.\d+\.\d+/
             branches:
               only:
-                - master
+                - main
 jobs:
   test:
     docker:
-      - image: darthjee/circleci_rails_gems:0.6.2
+      - image: darthjee/circleci_ruby_331:1.0.1
         environment:
           PROJECT: tarquinn
     steps:
       - checkout
-      - run:
-          name: Prepare Coverage Test Report
-          command: cc-test-reporter before-build
       - run:
           name: Bundle Install
           command: bundle install
       - run:
           name: RSpec
           command: bundle exec rspec
-      - run:
-          name: Coverage Test Report
-          command: cc-test-reporter after-build --exit-code $?
   checks:
     docker:
-      - image: darthjee/circleci_rails_gems:0.6.2
+      - image: darthjee/circleci_ruby_331:1.0.1
         environment:
           PROJECT: tarquinn
     steps:
@@ -49,12 +43,24 @@ jobs:
       - 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: 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:0.6.2
+      - image: darthjee/circleci_ruby_331:1.0.1
         environment:
           PROJECT: tarquinn
     steps:

data/.github/copilot-instructions.md

@@ -0,0 +1,188 @@
+# GitHub Copilot Instructions for Tarquinn
+
+## Project Overview
+
+Tarquinn is a Ruby gem that provides generic redirection control for Rails controllers.
+It is implemented as an `ActiveSupport::Concern` that adds `before_action` hooks and
+class-level DSL methods (`redirection_rule`, `skip_redirection`, `skip_redirection_rule`)
+to any Rails controller.
+
+Key components:
+
+- **`Tarquinn`** – The main concern included in controllers; sets up `before_action :perform_redirection`.
+- **`Tarquinn::ClassMethods`** – DSL methods added to controller classes.
+- **`Tarquinn::RequestHandlerBuilder`** – Accumulates redirection configurations for a controller class.
+- **`Tarquinn::RequestHandler`** – Processes a single request, iterating over configs to find the first matching redirect.
+- **`Tarquinn::RedirectionHandler`** – Evaluates one redirection config (conditions + skip rules) for a request.
+- **`Tarquinn::RedirectionConfig`** – Holds the data for a single redirection rule (blocks, skip blocks, redirect target).
+- **`Tarquinn::Condition`** – Wraps a single condition (method name or block) used in redirection/skip evaluation.
+- **`Tarquinn::Controller`** – Thin wrapper around the Rails controller instance, used by handlers.
+
+## Redirection Rules Data Flow
+
+### How It Works
+
+1. A controller includes `Tarquinn` (an `ActiveSupport::Concern`), which:
+   - Extends the controller with `Tarquinn::ClassMethods`, making the DSL methods available.
+   - Registers a `before_action :perform_redirection` that runs on every request.
+
+2. During a request, `perform_redirection` delegates to `Tarquinn::RequestHandler`, which
+   iterates over all registered `Tarquinn::RedirectionConfig` objects (in definition order)
+   and applies the **first** rule whose conditions are satisfied.
+
+3. Each rule is evaluated by `Tarquinn::RedirectionHandler`:
+   - All condition methods and/or the optional block are evaluated against the current
+     controller instance.
+   - If **any** condition returns a truthy value the rule fires and the controller redirects
+     to the path returned by the rule's target method.
+   - Skip conditions (registered via `skip_redirection` or `skip_redirection_rule`) are
+     checked first; if any skip condition is truthy the rule is bypassed entirely.
+
+### Defining a Redirection Rule — `redirection_rule`
+
+```ruby
+redirection_rule <rule_name>, *<condition_methods>, &<block>
+```
+
+| Argument            | Description                                                                                  |
+|---------------------|----------------------------------------------------------------------------------------------|
+| `rule_name`         | Symbol. Also the name of the controller method that returns the redirect path.               |
+| `condition_methods` | Zero or more symbol method names. Each is called on the controller; truthy → rule fires.     |
+| `block`             | Optional. Evaluated in the context of the controller; truthy → rule fires.                   |
+
+**Evaluation**: the rule fires when **any** condition method **or** the block returns truthy.
+
+#### Example 1 — block-based rule
+
+```ruby
+redirection_rule :redirect_home { params[:secret_key] != '12345' }
+
+def redirect_home
+  home_path
+end
+```
+
+Redirects to `home_path` if `secret_key` is absent or different from `'12345'`.
+
+#### Example 2 — method-based rule
+
+```ruby
+redirection_rule :redirect_home, :misses_secret_key
+
+def redirect_home
+  home_path
+end
+
+def misses_secret_key
+  params[:secret_key] != '12345'
+end
+```
+
+Same behaviour as Example 1, but the condition is extracted into a dedicated method.
+
+### Skipping a Rule for Specific Actions — `skip_redirection`
+
+```ruby
+skip_redirection <rule_name>, *<actions>
+```
+
+Prevents the named rule from running for the listed controller actions.
+
+```ruby
+skip_redirection :redirect_home, :index
+```
+
+The `index` action is not affected by the `redirect_home` rule; all other actions still are.
+
+### Skipping a Rule Under a Condition — `skip_redirection_rule`
+
+```ruby
+skip_redirection_rule <rule_name>, *<condition_methods>, &<block>
+```
+
+Registers a skip condition for a rule. When the condition is truthy the rule is bypassed,
+regardless of the action.
+
+```ruby
+skip_redirection_rule :redirect_home { params[:admin_key] == '9999' }
+```
+
+The `redirect_home` rule does not fire when the correct admin key is provided.
+
+### Passing Options to Redirection Rules
+
+You can pass options to `redirection_rule` to control advanced behavior. Currently, the main supported option is `domain`, which enables cross-domain redirection.
+
+| Option   | Description                                                                                 |
+|----------|---------------------------------------------------------------------------------------------|
+| `domain` | String. If set, allows redirection to the specified domain (cross-domain). If not set, only same-host redirection is allowed. |
+
+#### Example — domain-based rule
+
+```ruby
+redirection_rule :redirect_external, domain: 'example.com' do
+  params[:should_redirect]
+end
+
+def redirect_external
+  '/external_path'
+end
+```
+
+This will only allow redirection to `https://example.com/external_path` because the domain option is set to `'example.com'`.
+
+## Language
+
+All code, comments, documentation, commit messages, and PR descriptions must be written in **English**.
+
+## Coding Standards
+
+### General Style
+
+- Follow the existing RuboCop configuration (`.rubocop.yml` / `.rubocop_todo.yml`).
+- Use `# frozen_string_literal: true` at the top of every Ruby file.
+- Keep methods small and focused (Sandi Metz style): aim for methods under 5 lines.
+- Keep classes small with clear, single responsibilities and explicit object boundaries.
+- Avoid deeply nested conditionals; extract guard clauses or helper methods.
+- Use `private` / `attr_reader` to hide implementation details.
+- Use `delegate` (ActiveSupport) instead of manual forwarding where it improves readability.
+
+### Documentation
+
+- Add **YARD** documentation to all public classes, modules, and methods.
+- Non-obvious private methods should also have short YARD comments.
+- Always include `@param`, `@return`, and `@api public` / `@api private` tags where applicable.
+- Ensure documentation coverage stays at or above the threshold in `config/yardstick.yml`.
+
+### Tests
+
+- Write **RSpec** tests using the patterns established in `spec/`.
+- Keep tests small and focused — one behaviour per example.
+- Use `let` definitions that are **reusable** and **avoid duplication** across contexts.
+- Prefer `context` blocks to describe different input/state scenarios.
+- Avoid `before` blocks that do more than one thing; split them if needed.
+- Use `shared_examples` or `shared_context` when the same setup appears in multiple groups.
+
+## CI Checks
+
+The CI pipeline (`.circleci/config.yml`) runs the following checks on every push.
+Reproduce them locally before opening a PR:
+
+| CI Step                        | Local Command                                    |
+|-------------------------------|--------------------------------------------------|
+| Run tests                     | `bundle exec rspec`                              |
+| RuboCop lint                  | `bundle exec rubocop`                            |
+| YARD documentation coverage   | `bundle exec rake verify_measurements`           |
+| RubyCritic quality check      | `rubycritic.sh` (or `bundle exec rubycritic`)    |
+
+All checks must pass before a PR can be merged.
+
+## Docker / Local Development
+
+To run the project locally, use the Makefile targets:
+
+- Build Docker image:  `make build`
+- Start development environment:  `make dev`
+- Run tests:  `make tests`
+
+See the [Developer Guide](../README.md#developer-guide) in the README for further instructions.

data/.gitignore

@@ -1,3 +1,12 @@
 /coverage
 /pkg
 Gemfile.lock
+**/*.swp
+**/*.swo
+spec/dummy/log/*
+spec/dummy/tmp/*
+**/*.sqlite3
+doc
+.yardoc
+measurement
+rubycritic

data/.rubocop.yml

@@ -0,0 +1,29 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 3.3
+  NewCops: enable
+
+Lint/BooleanSymbol:
+  Enabled: false
+
+Lint/EmptyBlock:
+  Exclude:
+    - spec/dummy/db/schema.rb
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*_spec.rb
+
+Lint/MissingSuper:
+  Enabled: false
+
+Lint/ScriptPermission:
+  Exclude:
+    - spec/dummy/bin/*
+
+Naming/BlockForwarding:
+  Enabled: false
+
+Style/ArgumentsForwarding:
+  Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,13 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2024-07-10 16:10:57 UTC using RuboCop version 1.59.0.
+# 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: 9
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 87

data/Dockerfile

@@ -1,6 +1,6 @@
-FROM darthjee/scripts:0.1.8 as scripts
+FROM darthjee/scripts:0.6.0 as scripts
 
-FROM darthjee/rails_gems:0.6.2 as base
+FROM darthjee/ruby_331:1.0.1 as base
 
 COPY --chown=app:app ./ /home/app/app/
 

data/Gemfile

@@ -1,3 +1,18 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
+gem 'bundler',     '~> 2.5.13'
+gem 'pry',         '~> 0.14.2'
+gem 'pry-nav',     '~> 1.0.0'
+gem 'rails',       '7.2.3'
+gem 'rake',        '~> 13.1.0'
+gem 'rspec',       '~> 3.12.0'
+gem 'rspec-rails', '6.1.1'
+gem 'rubycritic',  '4.9.1'
+gem 'simplecov',   '~> 0.22.0'
+gem 'sqlite3',     '1.4.2'
+gem 'yard',        '0.9.38'
+gem 'yardstick',   '0.9.9'
+
 gemspec

data/Makefile

@@ -0,0 +1,21 @@
+.PHONY: build dev tests
+
+PROJECT?=tarquinn
+IMAGE?=$(PROJECT)
+BASE_IMAGE?=$(DOCKER_ID_USER)/$(PROJECT)-base
+DOCKER_FILE_BASE=Dockerfile.$(PROJECT)-base
+
+all:
+	@echo "Usage:"
+	@echo "  make build\n    Build docker image for $(PROJECT)"
+	@echo "  make dev\n    Run development environment for $(PROJECT)"
+	@echo "  make tests\n    Run tests for $(PROJECT)"
+
+build:
+	docker build -f Dockerfile.$(PROJECT) . -t $(IMAGE) -t $(PUSH_IMAGE):latest
+
+tests:
+	docker-compose run $(PROJECT)_tests /bin/bash
+
+dev:
+	docker-compose run $(PROJECT) /bin/bash

data/README.md

@@ -2,8 +2,6 @@ Tarquinn
 ========
 [![Build Status](https://circleci.com/gh/darthjee/tarquinn.svg?style=shield)](https://circleci.com/gh/darthjee/tarquinn)
 [![Code Climate](https://codeclimate.com/github/darthjee/tarquinn/badges/gpa.svg)](https://codeclimate.com/github/darthjee/tarquinn)
-[![Test Coverage](https://codeclimate.com/github/darthjee/tarquinn/badges/coverage.svg)](https://codeclimate.com/github/darthjee/tarquinn/coverage)
-[![Issue Count](https://codeclimate.com/github/darthjee/tarquinn/badges/issue_count.svg)](https://codeclimate.com/github/darthjee/tarquinn)
 [![Gem Version](https://badge.fury.io/rb/tarquinn.svg)](https://badge.fury.io/rb/tarquinn)
 [![Inline docs](http://inch-ci.org/github/darthjee/tarquinn.svg)](http://inch-ci.org/github/darthjee/tarquinn)
 
@@ -11,10 +9,14 @@ Tarquinn
 
 Yard Documentation
 -------------------
-[https://www.rubydoc.info/gems/tarquinn/0.2.0](https://www.rubydoc.info/gems/tarquinn/0.2.0)
+[https://www.rubydoc.info/gems/tarquinn/0.4.0](https://www.rubydoc.info/gems/tarquinn/0.4.0)
 
 This gem makes easier to controll generic redirection
 
+Current Release: [0.4.0](https://github.com/darthjee/tarquinn/tree/0.4.0)
+
+Next Version [0.4.1](https://github.com/darthjee/tarquinn/compare/0.4.0...main)
+
 Getting started
 ---------------
 1. Add Tarquinn to your `Gemfile` and `bundle install`:
@@ -56,3 +58,108 @@ Getting started
       end
     end
   ```
+
+---
+
+## Developer Guide
+
+### How It Works
+
+Tarquinn is a Rails concern that adds a `before_action` to any controller it is included in.
+On each request the action chain works as follows:
+
+1. `before_action :perform_redirection` is triggered automatically.
+2. A `RequestHandlerBuilder` (stored per controller class) holds all registered redirection
+   configs (`redirection_rule` / `skip_redirection` / `skip_redirection_rule` calls).
+3. At request time, `RequestHandlerBuilder` creates a `RequestHandler` for the current request.
+4. `RequestHandler` iterates over every `RedirectionConfig` and checks whether a redirect
+   should fire via `RedirectionHandler`.
+5. `RedirectionHandler` evaluates skip conditions first; if none match, it evaluates redirect
+   conditions. The first config that requires a redirect triggers `redirect_to`.
+
+### Running Locally with Docker Compose
+
+> Prerequisites: Docker and Docker Compose installed.
+
+**Build the image**
+
+```bash
+docker compose build base_build
+# or
+### Running Locally with Docker Compose and Makefile
+
+| `make build`    | Build the Docker image                               |
+
+| `make dev`      | Open an interactive bash shell inside the container  |
+
+| `make test`     | Run RSpec tests inside the container                 |
+make build
+```
+
+**Run the test suite**
+
+```bash
+make tests
+```
+
+**Open an interactive shell inside the container**
+
+```bash
+make dev
+```
+
+### Makefile Targets
+
+| Target        | Description                                 |
+|--------------|---------------------------------------------|
+| `make build` | Build Docker image for the project          |
+| `make dev`   | Run development environment (bash shell)    |
+| `make tests` | Run tests (RSpec) in the container          |
+
+### CI Checks
+
+The CircleCI pipeline (`.circleci/config.yml`) runs three jobs:
+
+| Job                   | What it does                                                                             |
+|-----------------------|------------------------------------------------------------------------------------------|
+| `test`                | `bundle exec rspec` + uploads coverage report                                            |
+| `checks`              | RuboCop, Yardstick coverage, README version check, RubyCritic, unit-test structure check |
+| `build-and-release`   | Builds and pushes the gem (tags only, on `master`)                                       |
+
+Run the same checks locally before opening a PR:
+
+```bash
+# Tests
+bundle exec rspec
+
+# RuboCop
+bundle exec rubocop
+
+# YARD documentation coverage
+bundle exec rake verify_measurements
+```
+
+### Domain Option for Cross-Domain Redirection
+
+You can specify a `domain` option in your `redirection_rule` to allow cross-domain redirection. When set, the redirection will be allowed to external hosts and the specified domain will be used for validation.
+
+**Example:**
+
+```ruby
+class ExternalRedirectController < ApplicationController
+  include Tarquinn
+
+  redirection_rule :redirect_external, domain: 'example.com' do
+    params[:should_redirect]
+  end
+
+  private
+
+  def redirect_external
+    '/external_path'
+  end
+end
+```
+
+- If `domain` is not set, redirection is only allowed for the same host.
+- If `domain` is set, redirection to the specified domain is allowed.

data/Rakefile

@@ -1,5 +1,10 @@
+# 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
 

data/config/check_specs.yml

@@ -0,0 +1,4 @@
+ignore:
+  - lib/tarquinn/class_methods.rb
+  - lib/tarquinn/version.rb
+  - lib/tarquinn/exception.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,55 @@
+threshold: 100.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:
+      - Tarquinn.redirection_rule
+      - Tarquinn.skip_redirection
+      - Tarquinn.skip_redirection_rule
+  ReturnTag:
+    enabled: true
+    exclude:
+      - Tarquinn.redirection_rule
+      - Tarquinn.skip_redirection
+      - Tarquinn.skip_redirection_rule
+      - Tarquinn.redirector_builder
+      - Tarquinn#perform_redirection
+      - Tarquinn::RedirectionHandler#initialize
+      - Tarquinn::RequestHandler#initialize
+      - Tarquinn::RedirectionConfigBuilder#initialize
+      - Tarquinn::Condition::ProcRunner#initialize
+      - Tarquinn::Condition::MethodCaller#initialize
+      - Tarquinn::Condition::ActionChecker#initialize
+      - Tarquinn::Exception::RedirectionAlreadyDefined#initialize
+  Summary::Presence:
+    enabled: true
+    exclude:
+      - Tarquinn::RedirectionHandler#initialize
+      - Tarquinn::RequestHandler#initialize
+      - Tarquinn::RedirectionConfigBuilder#initialize
+      - Tarquinn::Condition::ProcRunner#initialize
+      - Tarquinn::Condition::MethodCaller#initialize
+      - Tarquinn::Condition::ActionChecker#initialize
+      - Tarquinn::Exception::RedirectionAlreadyDefined#initialize
+  Summary::Length:
+    enabled: true
+    exclude: []
+  Summary::Delimiter:
+    enabled: true
+    exclude: []
+  Summary::SingleLine:
+    enabled: true
+    exclude: []

data/docker-compose.yml

@@ -17,7 +17,7 @@ services:
     depends_on: [base_build]
     command: /bin/bash -c 'rspec'
 
-  test_all:
+  tarquinn_tests:
     <<: *base
     depends_on: [base_build]
     command: /bin/bash -c 'rspec && yard && rake yardstick_measure && rake verify_measurements'