verdict_rules 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c6ebe08f124cc88d8cdcd68dcbf4335c6aae0c714d02dc03a2dd6610b2ba8eb0
+  data.tar.gz: 191c1ec6daf71053d0c24d212972d1bb1be45a7625e136f4f6fa2fe50b350597
+SHA512:
+  metadata.gz: 457d29778fd20e42da7fa74db1af6de5678250b031cf77b8fc00ae31e86c50fbf1df5faa0cdc424aa013931f8042e7f4a68e5d0597c0ee47b48e190cc63e8443
+  data.tar.gz: 4d15e8bc27ec6977fc8b75ed7c9bb9a328d9c5d502ccaf560500ddf85620691a87ff28d51dcc5c74c54283fcc128e55ce5c05766bd011fa605b49fcc4ca3a13e

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-23
+
+### Added
+- Initial release
+- Core rule engine with context management
+- Priority-based rule resolution
+- Explainable results with Result object
+- Expressive DSL for rule definition
+- Named rules for better debugging and logging
+- Immutable context for thread safety
+- 100% test coverage
+- Comprehensive examples
+- Full documentation in Portuguese
+
+### Features
+- `VerdictRules::Engine` - Main engine for rule evaluation
+- `VerdictRules::Rule` - Individual rule with condition, action, and priority
+- `VerdictRules::Result` - Rich result object explaining outcomes
+- `VerdictRules::RuleBuilder` - DSL builder for clean syntax
+- Support for complex nested contexts
+- Priority system with stable sort
+- Method chaining support
+
+[Unreleased]: https://github.com/tibas-ce/verdict_rules/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/tibas-ce/verdict_rules/releases/tag/v0.1.0

data/README.md

@@ -0,0 +1,249 @@
+<div align="center">
+
+# ⚖️ VerdictRules
+
+### Rule engine para Ruby com prioridades explícitas, resultados rastreáveis e DSL expressiva.
+
+Defina regras de negócio complexas de forma clara, debuggável e pronta para produção.
+
+[![CI](https://github.com/tibas-ce/verdict_rules/workflows/CI/badge.svg)](https://github.com/tibas-ce/verdict_rules/actions)
+[![Gem Version](https://img.shields.io/badge/status-not_published-lightgrey.svg)](https://rubygems.org/gems/verdict_rules)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[Recursos](#-recursos) •
+[Instalação](#-instalação) •
+[Início Rápido](#-início-rápido) •
+[API](#-api) •
+[Debugging e Observabilidade](#-debugging-e-observabilidade) •
+[Exemplos](#-exemplos)
+
+</div>
+
+---
+
+## 🎯 O que é VerdictRules?
+
+**VerdictRules** é uma gem Ruby leve e sem dependências que permite definir regras de negócio de forma declarativa com nome, prioridades explícitas e resultados explicáveis.
+
+Perfeita para:
+- 🏦 **Sistemas financeiros**: Aprovação de crédito, detecção de fraude
+- 🛒 **E-commerce**: Regras de preço, lógica de descontos
+- 🔐 **Autorização**: Controle de acesso, sistemas de permissão
+- ✅ **Validação**: Lógica condicional complexa
+- 🎮 **Lógica de jogos**: Sistemas de pontuação, conquistas
+
+---
+
+## ✨ Recursos
+
+| Recurso | Descrição |
+|---------|-----------|
+| 🎯 **Sistema de Prioridades** | Resolve conflitos quando múltiplas regras são verdadeiras |
+| 🏷️ **Regras Nomeadas** | Identifique exatamente qual regra foi aplicada |
+| 📊 **Resultados Explicáveis** | Saiba qual regra foi aplicada e por quê |
+| ✨ **DSL Expressiva** | Sintaxe limpa e legível |
+| 🔒 **Contexto Imutável** | Comportamento thread-safe e previsível |
+| 🧪 **100% de Cobertura** | Testado e confiável |
+| 📦 **Zero Dependências** | Leve e rápida |
+| 🚀 **Design pronto para produção** | Arquitetura preparada para uso real |
+
+---
+
+## 📦 Instalação
+
+Adicione esta linha ao Gemfile da sua aplicação:
+```ruby
+gem 'verdict_rules'
+```
+
+E então execute:
+```bash
+bundle install
+```
+
+Ou instale você mesmo:
+```bash
+gem install verdict_rules
+```
+
+---
+
+## 🚀 Início Rápido
+
+### Exemplo Básico
+```ruby
+require "verdict_rules"
+
+context = { age: 25, verified: true }
+
+engine = VerdictRules::Engine.new(context)
+
+engine.rules do
+  rule :verified_user, priority: 10 do
+    when_condition { |ctx| ctx[:verified] }
+    then_action :approve_verified
+  end
+
+  rule :adult_user, priority: 1 do
+    when_condition { |ctx| ctx[:age] >= 18 }
+    then_action :approve_adult
+  end
+end
+
+result = engine.evaluate
+
+result.value                    # => :approve_verified
+result.matched_rule.name       # => :verified_user
+```
+
+---
+
+### Problema que resolve
+
+Sem prioridades e rastreabilidade:
+
+- decisões imprevisíveis ❌
+- difícil entender por que algo foi aprovado/rejeitado ❌
+- debugging lento e custoso ❌
+
+Com VerdictRules:
+
+- decisão previsível ✅
+- regra identificável ✅
+- lógica centralizada ✅
+
+---
+### Exemplo Real: Produção
+```ruby
+engine.rules do
+  rule :vip_customer, priority: 100 do
+    when_condition { |ctx| ctx[:vip_customer] }
+    then_action({ status: :approved, limit: 50000 })
+  end
+
+  rule :income_not_verified, priority: 10 do
+    when_condition { |ctx| !ctx[:verified_income] }
+    then_action({ status: :manual_review })
+  end
+
+  rule :good_credit, priority: 1 do
+    when_condition { |ctx| ctx[:credit_score] >= 700 }
+    then_action({ status: :approved })
+  end
+end
+
+result = engine.evaluate
+
+result.to_h
+# => {
+#      value: { status: :manual_review },
+#      matched: true,
+#      matched_rule: { name: :income_not_verified, priority: 10, ... }
+#    }
+```
+
+---
+
+## 🔍 Debugging e Observabilidade
+Projetado para sistemas onde decisões precisam ser auditáveis e explicáveis.
+
+```ruby
+result = engine.evaluate
+
+result.matched_rule.name
+# => :income_not_verified
+
+result.matched_rule.priority
+# => 10
+```
+
+### 📊 Logging estruturado
+
+```ruby
+log = {
+  event: "rule_evaluation",
+  result: result.value,
+  matched: result.matched?,
+  rule: result.matched_rule&.to_h
+}
+
+puts JSON.pretty_generate(log)
+```
+
+### Ideal para cenários como:
+
+- auditoria
+- debugging em produção
+- sistemas financeiros / críticos
+
+---
+
+## 🔧 API
+
+```ruby
+engine.rule(:name, priority: 10) do
+  when_condition { |ctx| ... }
+  then_action :result
+end
+
+engine.rules do
+  rule(:a, priority: 10) { ... }
+  rule(:b, priority: 5)  { ... }
+end
+
+engine.evaluate
+```
+
+---
+
+## 💡 Exemplos
+
+Confira o diretório [`examples/`](examples/) para exemplos completos e funcionais:
+
+- **[Uso Básico](examples/basic_usage.rb)** - Regras simples sem DSL
+- **[Sistema de Prioridades](examples/priority_and_exceptions.rb)** - Aprovação de crédito com prioridades
+- **[DSL Básica](examples/dsl_basic.rb)** - DSL vs API tradicional
+- **[DSL no Mundo Real](examples/dsl_real_word.rb)** - Sistema de aprovação de compras
+- **[Debugging com regras nomeadas](examples/named_rules_debugging.rb)** - Investigando decisões e logs estruturados
+
+Execute-os:
+```bash
+ruby examples/basic_usage.rb
+```
+
+---
+
+## 📊 Princípios de Design
+
+VerdictRules segue estes princípios:
+
+- ✅ **Explícito sobre Implícito** - Sem mágica, comportamento claro
+- ✅ **Simples sobre Complexo** - Fácil de entender e debugar
+- ✅ **Testável** - Cada componente tem testes unitários
+- ✅ **Imutável** - Contexto não pode ser modificado
+- ✅ **Explicável** - Resultados dizem por que aconteceram
+- ✅ **Componível** - Misture DSL e API tradicional livremente
+
+---
+
+## 📄 Licença
+
+Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.
+
+---
+
+## 🙏 Construído usando
+
+- Ruby
+- RSpec
+- SimpleCov
+
+---
+
+<div align="center">
+
+**[⬆ voltar ao topo](#️-verdictrules)**
+
+Feito por [Tibério dos Santos Ferreira](https://github.com/tibas-ce)
+
+</div>

data/lib/verdict_rules/engine.rb

@@ -0,0 +1,111 @@
+# Engine é responsável por:
+# - armazenar o contexto de avaliação
+# - gerenciar a lista de regras
+# - avaliar as regras em ordem e retornar a primeira action válida
+# O contexto é fornecido na inicialização e pertence à Engine.
+
+module VerdictRules
+  class Engine
+    attr_reader :context, :rules
+
+    def initialize(context = {})
+      @context = deep_freeze(context.dup)
+      @rules = []
+    end
+
+    # Adiciona uma regra à engine
+    # Regras são automaticamente ordenadas por prioridade (maior primeiro)
+    # Em caso de empate, ordem de inserção é mantida (stable sort)
+    # Retorna self para permitir chaining
+    def add_rule(rule)
+      @rules << rule
+      sort_rules!
+      self
+    end
+
+    # DSL: Define uma única regra usando bloco
+    # Formas suportadas:
+    #   rule(priority: 10) { ... }
+    #   rule(:name, priority: 10) { ... }
+    #   rule(:name) { ... }
+    #
+    # Parâmetros:
+    # - name: identificador opcional da regra
+    # - priority: ordem de avaliação (maior primeiro)
+    #
+    # O bloco é executado no contexto de RuleBuilder, permitindo:
+    #   when_condition { |ctx| ... }
+    #   then_action :value
+    # Retorna self para permitir chaining
+    def rule(name = nil, priority: 0, &block)
+      raise ArgumentError, "block required" unless block_given?
+
+      builder = RuleBuilder.new(name: name, priority: priority)
+      builder.instance_eval(&block)
+      add_rule(builder.build)
+
+      self
+    end
+
+    # DSL: Define múltiplas regras em um bloco
+    # Executa o bloco no contexto da Engine, permitindo chamadas a `rule`
+    # Exemplo:
+    #   engine.rules do
+    #     rule(:check_age, priority: 10) { ... }
+    #     rule(:check_verified, priority: 5) { ... }
+    #   end
+    #
+    # Retorna self para permitir chaining
+    def rules(&block)
+      return @rules unless block_given?
+
+      instance_eval(&block)
+      self
+    end
+
+    # Avalia as regras utilizando o contexto interno da Engine.
+    # Regras são avaliadas em ordem de prioridade (maior primeiro)
+    # Decisão de design:
+    # - O contexto é definido na inicialização da Engine
+    # - O método `evaluate` não recebe argumentos
+    # - Cada regra recebe o contexto da Engine durante a avaliação
+    # Retorna um Result contendo:
+    # - value: a action da primeira regra que bater (ou nil)
+    # - matched_rule: a regra que bateu (ou nil)
+    # Isso mantém a API simples e evita múltiplas formas de fornecer contexto.
+    def evaluate
+      rules.each do |rule|
+        action = rule.evaluate(context)
+
+        unless action.nil?
+          return Result.new(value: action, matched_rule: rule)
+        end
+      end
+
+      # Nenhuma regra bateu
+      Result.new(value: nil, matched_rule: nil)
+    end
+
+    private
+
+    # Congela recursivamente hashes e arrays para garantir a imutabilidade do contexto após a inicialização
+    def deep_freeze(object)
+      case object
+      when Hash
+        object.each { |key, value| deep_freeze(value) }
+        object.freeze
+      when Array
+        object.each { |value| deep_freeze(value) }
+        object.freeze
+      else
+        object.freeze
+      end
+    end
+
+    # Ordena regras por prioridade (maior primeiro)
+    # Em caso de empate, preserva a ordem de inserção para garantir previsibilidade na avaliação.
+    def sort_rules!
+      @rules = @rules.sort_by.with_index { |rule, index| [-rule.priority, index] }
+    end
+  end
+end

data/lib/verdict_rules/result.rb

@@ -0,0 +1,43 @@
+module VerdictRules
+  # Representa o resultado da avaliação de uma Rule Engine. Encapsula o valor retornado e a regra que foi satisfeita (se houver)
+  class Result
+    attr_reader :value, :matched_rule
+    
+    def initialize(value:, matched_rule:)
+      @value = value
+      @matched_rule = matched_rule
+    end
+
+    # Indica se alguma regra foi satisfeita
+    def matched?
+      !matched_rule.nil?
+    end
+
+    # Retorna representação em hash do resultado da avaliação
+    def to_h
+      {
+        value: value,
+        matched: matched?,
+        matched_rule: matched_rule
+      }
+    end
+
+    # Representação legível para debugging
+    def inspect
+      if matched?
+        "#<VerdictRules::Result value=#{value.inspect} matched=true rule=#{matched_rule.object_id}>"
+      else
+        "#<VerdictRules::Result value=#{value.inspect} matched=false>"
+      end
+    end
+
+    # Define igualdade semâtica entre dois Results
+    def ==(other)
+      return false unless other.is_a?(Result)
+
+      value == other.value && matched_rule == other.matched_rule
+    end
+
+    alias eql? ==
+  end
+end

data/lib/verdict_rules/rule.rb

@@ -0,0 +1,80 @@
+module VerdictRules
+  # Representa uma regra simples composta por:
+  # - name: identificador opcional da regra (útil para debug e logging)
+  # - uma condition (Proc que recebe o contexto e retorna true/false)
+  # - uma action (valor retornado quando a condição é satisfeita)
+  # - priority: número usado para ordenar regras (quanto maior, maior prioridade)
+  class Rule
+    attr_reader :name, :condition, :action, :priority
+
+    def initialize(name: nil, condition:, action:, priority: 0)
+      validate_arguments!(name, condition, action, priority)
+      
+      @name = normalize_name(name)
+      @condition = condition
+      @action = action
+      @priority = priority
+    end
+
+    # Avalia a regra contra um contexto
+    # Retorna a action se a condition for true, nil caso contrário
+    def evaluate(context)
+      return action if matches?(context)
+      nil
+    end
+
+    # Verifica se a condição é satisfeita pelo contexto
+    def matches?(context)
+      condition.call(context)
+    end
+
+    # Representação em hash (útil para logging e serialização)
+    def to_h
+      {
+        name: name,
+        priority: priority,
+        action: action
+      }
+    end
+
+    # Representação legível para debugging
+    def inspect
+      if name
+        "#<VerdictRules::Rule name=#{name.inspect} priority=#{priority} action=#{action.inspect}>"
+      else
+        "#<VerdictRules::Rule priority=#{priority} action=#{action.inspect}>"
+      end
+    end
+
+    private
+
+    # Valida os argumentos da regra.
+    # Regras de design:
+    # - condition deve ser um Proc
+    # - action é obrigatória
+    # - priority deve ser numérica (pode ser negativa)
+    def validate_arguments!(name, condition, action, priority)
+      validate_name!(name) unless name.nil?
+      raise ArgumentError, "condition" if condition.nil?
+      raise ArgumentError, "action" if action.nil?
+      raise ArgumentError, "condition must be a Proc" unless condition.is_a?(Proc)
+      raise ArgumentError, "priority must be a number" unless priority.is_a?(Numeric)
+    end
+
+    def validate_name!(name)
+      unless name.is_a?(Symbol) || name.is_a?(String)
+        raise ArgumentError, "name must be a symbol or string"
+      end
+
+      if name.is_a?(String) && name.strip.empty?
+        raise ArgumentError, "name cannot be empty"
+      end
+    end
+
+    def normalize_name(name)
+      return nil if name.nil?
+      name = name.strip if name.is_a?(String)
+      name.to_sym
+    end
+  end
+end

data/lib/verdict_rules/rule_builder.rb

@@ -0,0 +1,51 @@
+module VerdictRules 
+  class RuleBuilder
+    # Builder responsável por construir instâncias de Rule a partir da DSL
+    # Encapsula validações e evita que a Engine lide com estado parcial
+    # Usado internamente pelo Engine#rule e Engine#rules
+    # name: identificador opcional da regra
+    # priority: define a ordem de avaliação (maior primeiro)
+    def initialize(name: nil, priority: 0)  
+      @name = name
+      @priority = priority
+      @condition = nil
+      @action = nil
+    end
+
+    # Define a condição da regra
+    # O bloco a ser chamado posteriormente com o contexto da Engine
+    # Exige bloco para garantir previsibilidade do DSL  
+    def when_condition(&block)
+      raise ArgumentError, "block required for when_condition" unless block_given?
+
+      @condition = block
+    end
+
+    # Define a ação executada quando a condição é satisfeita
+    # Aceita qualquer valor (symbol, string, hash, etc)
+    def then_action(value)
+      @action = value
+    end
+
+    # Constrói e retorna uma instância de Rule
+    # Garante que a DSL foi definida corretamente antes da criação
+    # Falha cedo caso condition ou action estejam ausentes
+    def build
+      validate! 
+
+      Rule.new(
+        name: @name,
+        condition: @condition,
+        action: @action,
+        priority: @priority
+      )
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "condition is required (use when_condition)" if @condition.nil?
+      raise ArgumentError, "action is required (use then_action)" if @action.nil?
+    end
+  end
+end

data/lib/verdict_rules/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module VerdictRules
+  VERSION = "0.1.0"
+end

data/lib/verdict_rules.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "verdict_rules/version"
+require_relative "verdict_rules/result"
+require_relative "verdict_rules/rule"
+require_relative "verdict_rules/rule_builder"
+require_relative "verdict_rules/engine"
+
+module VerdictRules
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: verdict_rules
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tibério dos Santos Ferreira
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: A gem to define and evaluate business rules with priorities and explainable
+  results.
+email:
+- tiberio.ferreiracs@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/verdict_rules.rb
+- lib/verdict_rules/engine.rb
+- lib/verdict_rules/result.rb
+- lib/verdict_rules/rule.rb
+- lib/verdict_rules/rule_builder.rb
+- lib/verdict_rules/version.rb
+homepage: https://github.com/tibas-ce/verdict_rules
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tibas-ce/verdict_rules
+  source_code_uri: https://github.com/tibas-ce/verdict_rules
+  changelog_uri: https://github.com/tibas-ce/verdict_rules/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/tibas-ce/verdict_rules/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A Ruby gem for defining and evaluating business rules with priorities.
+test_files: []