br_validators 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ab3d772a8a5a9512686a875c429689adcb348af7eac07f7f795f2efa616d402
-  data.tar.gz: 5c222dfc1339f2c451501fd010767ce82b0111243e4768b0762a896b03b2a363
+  metadata.gz: 46a5c5d1d504c919923fbc23bb01ee2f4c82eeccbf752f8130740baa97ae35e6
+  data.tar.gz: 8d7dc883a24f170123e0df911397e4981af249941ae48d04d0476ff1d97029c0
 SHA512:
-  metadata.gz: a9663daabd0c2079d63aa4990c0e5454bb47024b7e7cf1545f2db7f0a76a3c69aaf5e3141d7a808b94457a79a65eef48a0ddf5a5e378b76ec0474beb2ea87bfd
-  data.tar.gz: bcc9e9bce3dda58ff44c9039fb7107cdc217a0dddd997d4d935995eb524a7a0e0ad23c910203bfe540d94990a1b4cbc56b9f9c4fb84e9ea22cd0c1d7b46e6a55
+  metadata.gz: 66f54a26023c513533a5f1928a7875232d645f44161b0d6457da9cff3579aa666444d5ff09cad07058144c4113f41d89e75c05543433cf62a811fe7f387a1ceb
+  data.tar.gz: '08a8f1547c74bf7062abb1a7dda42c69e55e7a9f6578f6473871d19155b36e463644a4d03458aed3b972c8fbce1d90b1da74151ec3fb539c0a7c3cc8ab294bc5'

data/CHANGELOG.md

@@ -3,6 +3,28 @@
 As mudanças de cada versão ficam aqui. O projeto segue o
 [versionamento semântico](https://semver.org/lang/pt-BR/).
 
+## [0.3.0] - 2026-10-31
+
+### Novo
+
+- `require "br_validators/documentos"` carrega só os documentos, sem os validadores do
+  Rails. Serve para o app que já tem um `CpfValidator` (ou outro com o mesmo nome): o da
+  gem, no nível de cima, fazia o Rails ignorar o arquivo do app sem avisar. No Gemfile:
+  `gem "br_validators", require: "br_validators/documentos"`.
+- Assinaturas de tipo (RBS) em `sig/`, incluídas no pacote.
+- Link da documentação (rubydoc.info) nos dados da gem no RubyGems.
+
+### Mudado
+
+- `require "br_validators/consulta"` carrega só os documentos de que precisa, sem os
+  validadores do Rails.
+
+### Outros
+
+- Página de teste com visual novo: botões para escolher o documento, motivo quando o
+  número é inválido (tamanho ou regra) e o trecho de código Ruby equivalente. A API
+  devolve `caracteres`, o tamanho sem a máscara.
+
 ## [0.2.1] - 2026-10-26
 
 ### Corrigido

data/README.md

@@ -1,6 +1,18 @@
 # br_validators
 
-Gem Ruby para validar e formatar documentos brasileiros, sem dependências.
+[![Gem](https://img.shields.io/gem/v/br_validators)](https://rubygems.org/gems/br_validators)
+[![CI](https://github.com/PedroPedrassolli/br_validators/actions/workflows/ci.yml/badge.svg)](https://github.com/PedroPedrassolli/br_validators/actions/workflows/ci.yml)
+
+Gem Ruby para validar e formatar documentos brasileiros, sem dependências. Dá para
+testar cada documento no navegador em https://br-validators.vercel.app.
+
+```ruby
+require "br_validators"
+
+BrValidators::CPF.valid?("123.456.789-09")     # => true
+BrValidators::CNPJ.format("12abc34501de35")     # => "12.ABC.345/01DE-35"
+BrValidators::Telefone.type("(11) 98765-4321")  # => :celular
+```
 
 ## Instalação
 
@@ -148,24 +160,48 @@ sobrescreva as chaves `errors.messages.<documento>_invalid` (`cpf_invalid`, `cep
 Os validadores ficam no nível de cima (`CpfValidator`, `TelefoneValidator`,
 `TituloEleitorValidator`...), porque é assim que o Rails encontra `cpf: true`.
 
+Se o seu app já tem um validador com o mesmo nome (um `app/validators/cpf_validator.rb`,
+por exemplo), o Rails passa a ignorar o arquivo do app sem avisar, porque a classe já
+existe. Para ficar com o seu, carregue só os documentos:
+
+```ruby
+# Gemfile
+gem "br_validators", require: "br_validators/documentos"
+```
+
+Os módulos (`BrValidators::CPF`...) continuam disponíveis; só os validadores do Rails
+ficam de fora.
+
 Já existem boas gems para CPF e CNPJ. A ideia aqui é juntar num lugar só os documentos
 que costumam aparecer em sistemas brasileiros (inclusive CNS, Pix, boleto, placa, NF-e e
 processo judicial), com mensagens de erro em português e inglês.
 
+## Tipos (RBS)
+
+A gem vem com assinaturas de tipo em `sig/`, para quem usa Steep, o Ruby LSP ou outra
+ferramenta que lê RBS. A documentação de cada módulo fica em
+[rubydoc.info](https://rubydoc.info/gems/br_validators).
+
 ## Página de teste
 
-Dá para testar cada validador no navegador em https://br-validators.vercel.app. A página
-(`public/`) é HTML e JavaScript puro e chama uma função Ruby da Vercel
+Dá para testar cada validador no navegador em https://br-validators.vercel.app. O link
+pode abrir direto num documento: `?documento=placa`, `?documento=boleto`... A página
+mostra o resultado, explica por que um número é inválido e monta o trecho de código
+Ruby que faz o mesmo.
+
+A página (`public/`) é HTML e JavaScript puro e chama uma função Ruby da Vercel
 (`api/validar.rb`) que usa a própria gem, então as regras ficam num lugar só:
 
 ```
 GET /api/validar?documento=cnpj&valor=12.ABC.345/01DE-35
-{"documento":"cnpj","valido":true,"formatado":"12.ABC.345/01DE-35","tipo":null,"detalhe":null}
+{"documento":"cnpj","valido":true,"formatado":"12.ABC.345/01DE-35","tipo":null,"detalhe":null,"caracteres":14}
 
 GET /api/validar?documento=titulo_eleitor&valor=1023%208501%200671
-{"documento":"titulo_eleitor","valido":true,"formatado":"1023 8501 0671","tipo":null,"detalhe":"PR"}
+{"documento":"titulo_eleitor","valido":true,"formatado":"1023 8501 0671","tipo":null,"detalhe":"PR","caracteres":12}
 ```
 
+`caracteres` é o tamanho sem pontos, traços e espaços (para a chave Pix, `null`).
+
 ## Desenvolvimento
 
 Precisa de Ruby 3.3 ou mais novo.
@@ -174,6 +210,7 @@ Precisa de Ruby 3.3 ou mais novo.
 bundle install
 bundle exec rake test   # testes (a cobertura mínima é 100% das linhas)
 bundle exec rubocop     # estilo
+bundle exec rbs -r uri -I sig validate   # assinaturas de tipo
 node --test "test/js/*.test.mjs"   # testes da página de teste
 ```
 

data/lib/br_validators/active_model.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_model"
+require_relative "documentos"
 
 # Validação nos models do Rails (ou de qualquer classe com ActiveModel):
 #
@@ -10,6 +11,10 @@ require "active_model"
 #
 # O Rails procura a classe pelo nome da opção ("cpf: true" vira CpfValidator),
 # por isso os validadores ficam no nível de cima, fora do módulo BrValidators.
+# Efeito colateral: se o app já tem um validador com o mesmo nome (por exemplo,
+# app/validators/cpf_validator.rb), o Rails ignora o arquivo do app sem avisar,
+# porque a classe já existe. Para ficar com o do app, o Gemfile carrega só os
+# documentos: gem "br_validators", require: "br_validators/documentos".
 # As mensagens de erro estão em lib/br_validators/locale (pt-BR e en).
 I18n.load_path += Dir[File.expand_path("locale/*.yml", __dir__)]
 

data/lib/br_validators/consulta.rb

@@ -3,7 +3,8 @@
 require "json"
 require "net/http"
 require "openssl"
-require_relative "../br_validators"
+# Só os documentos (para validar antes de consultar), sem os validadores do Rails.
+require_relative "documentos"
 
 module BrValidators
   # Consultas online pela BrasilAPI (https://brasilapi.com.br), um serviço gratuito,

data/lib/br_validators/documentos.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "version"
+require_relative "texto"
+require_relative "cpf"
+require_relative "cnpj"
+require_relative "cns"
+require_relative "pix"
+require_relative "boleto"
+require_relative "cep"
+require_relative "telefone"
+require_relative "placa"
+require_relative "renavam"
+require_relative "titulo_eleitor"
+require_relative "processo_cnj"
+require_relative "chave_acesso"
+
+# Validação e formatação de documentos brasileiros.
+#
+# Cada documento tem um módulo próprio (BrValidators::CPF, BrValidators::CNPJ...)
+# com os mesmos três métodos:
+#   valid?(valor)  -> true ou false
+#   format(valor)  -> o documento com a máscara, ou nil se for inválido
+#   strip(valor)   -> o documento sem a máscara
+# A chave Pix é a exceção: tem valid? e type, mas não format nem strip, porque
+# precisa estar exatamente como o Banco Central guarda.
+# Alguns têm métodos a mais: type (Pix, Boleto, Telefone, Placa), uf (TituloEleitor),
+# segmento (ProcessoCNJ), modelo (ChaveAcesso), ddd (Telefone), mercosul e antiga (Placa).
+#
+# Este arquivo carrega só os documentos, sem os validadores do Rails. Serve para o
+# app que já tem um CpfValidator (ou outro com o mesmo nome) e quer continuar com o
+# dele: no Gemfile, gem "br_validators", require: "br_validators/documentos".
+module BrValidators
+end

data/lib/br_validators/version.rb

@@ -2,5 +2,5 @@
 
 # Versão da gem, lida também pelo gemspec.
 module BrValidators
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/br_validators.rb

@@ -1,33 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "br_validators/version"
-require_relative "br_validators/texto"
-require_relative "br_validators/cpf"
-require_relative "br_validators/cnpj"
-require_relative "br_validators/cns"
-require_relative "br_validators/pix"
-require_relative "br_validators/boleto"
-require_relative "br_validators/cep"
-require_relative "br_validators/telefone"
-require_relative "br_validators/placa"
-require_relative "br_validators/renavam"
-require_relative "br_validators/titulo_eleitor"
-require_relative "br_validators/processo_cnj"
-require_relative "br_validators/chave_acesso"
-
-# Validação e formatação de documentos brasileiros.
-#
-# Cada documento tem um módulo próprio (BrValidators::CPF, BrValidators::CNPJ...)
-# com os mesmos três métodos:
-#   valid?(valor)  -> true ou false
-#   format(valor)  -> o documento com a máscara, ou nil se for inválido
-#   strip(valor)   -> o documento sem a máscara
-# A chave Pix é a exceção: tem valid? e type, mas não format nem strip, porque
-# precisa estar exatamente como o Banco Central guarda.
-# Alguns têm métodos a mais: type (Pix, Boleto, Telefone, Placa), uf (TituloEleitor),
-# segmento (ProcessoCNJ), modelo (ChaveAcesso), ddd (Telefone), mercosul e antiga (Placa).
-module BrValidators
-end
+# Os documentos (BrValidators::CPF, BrValidators::CNPJ...). A explicação de cada
+# método está em br_validators/documentos.rb.
+require_relative "br_validators/documentos"
 
 # Validação nos models (validates :cpf, cpf: true): só entra quando o projeto tem
 # o ActiveModel (todo app Rails tem), para a gem continuar sem dependências.

data/sig/br_validators.rbs

@@ -0,0 +1,130 @@
+# Assinaturas de tipo (RBS) da parte pública da gem, para quem usa Steep, o
+# Ruby LSP ou outra ferramenta que lê tipos. Os validadores do ActiveModel
+# (CpfValidator...) ficam de fora: quem chama é o Rails, não o seu código.
+#
+# Confira com: bundle exec rbs -r uri -I sig validate
+module BrValidators
+  VERSION: String
+
+  # Converte qualquer valor em texto UTF-8 (uso interno dos módulos).
+  def self.texto: (untyped valor) -> String
+
+  module CPF
+    def self.valid?: (untyped value) -> bool
+    def self.format: (untyped value) -> String?
+    def self.strip: (untyped value) -> String
+  end
+
+  module CNPJ
+    def self.valid?: (untyped value) -> bool
+    def self.format: (untyped value) -> String?
+    def self.strip: (untyped value) -> String
+  end
+
+  module CNS
+    def self.valid?: (untyped value) -> bool
+    def self.format: (untyped value) -> String?
+    def self.strip: (untyped value) -> String
+  end
+
+  module TituloEleitor
+    def self.valid?: (untyped value) -> bool
+    def self.format: (untyped value) -> String?
+    def self.strip: (untyped value) -> String
+    def self.uf: (untyped value) -> String?
+  end
+
+  module Pix
+    type tipo = :cpf | :cnpj | :phone | :email | :evp
+
+    def self.valid?: (untyped value) -> bool
+    def self.type: (untyped value) -> tipo?
+  end
+
+  module Boleto
+    type tipo = :cobranca | :arrecadacao
+
+    def self.valid?: (untyped value) -> bool
+    def self.format: (untyped value) -> String?
+    def self.strip: (untyped value) -> String
+    def self.type: (untyped value) -> tipo?
+  end
+
+  module CEP
+    def self.valid?: (untyped value) -> bool
+    def self.format: (untyped value) -> String?
+    def self.strip: (untyped value) -> String
+  end
+
+  module Telefone
+    type tipo = :celular | :fixo
+
+    DDDS: Array[String]
+
+    def self.valid?: (untyped value) -> bool
+    def self.format: (untyped value) -> String?
+    def self.strip: (untyped value) -> String
+    def self.type: (untyped value) -> tipo?
+    def self.ddd: (untyped value) -> String?
+  end
+
+  module Placa
+    type tipo = :antiga | :mercosul
+
+    def self.valid?: (untyped value) -> bool
+    def self.format: (untyped value) -> String?
+    def self.strip: (untyped value) -> String
+    def self.type: (untyped value) -> tipo?
+    def self.mercosul: (untyped value) -> String?
+    def self.antiga: (untyped value) -> String?
+  end
+
+  module RENAVAM
+    def self.valid?: (untyped value) -> bool
+    def self.format: (untyped value) -> String?
+    def self.strip: (untyped value) -> String
+  end
+
+  module ChaveAcesso
+    def self.valid?: (untyped value) -> bool
+    def self.format: (untyped value) -> String?
+    def self.strip: (untyped value) -> String
+    def self.modelo: (untyped value) -> String?
+  end
+
+  module ProcessoCNJ
+    SEGMENTOS: Hash[String, String]
+
+    def self.valid?: (untyped value) -> bool
+    def self.format: (untyped value) -> String?
+    def self.strip: (untyped value) -> String
+    def self.segmento: (untyped value) -> String?
+  end
+
+  # Opcional: require "br_validators/consulta".
+  module Consulta
+    # Qualquer objeto com get(uri) que devolva [status, corpo] serve de cliente.
+    interface _Cliente
+      def get: (URI::Generic uri) -> [Integer, String]
+    end
+
+    BASE: String
+    TIMEOUT: Integer
+
+    class Erro < StandardError
+    end
+
+    attr_writer self.cliente: _Cliente
+    def self.cliente: () -> _Cliente
+
+    # O JSON da BrasilAPI como Hash, ou nil quando o dado é inválido ou não existe.
+    def self.cep: (untyped valor) -> Hash[String, untyped]?
+    def self.cnpj: (untyped valor) -> Hash[String, untyped]?
+    def self.banco: (untyped codigo) -> Hash[String, untyped]?
+    def self.ddd: (untyped valor) -> Hash[String, untyped]?
+
+    module HTTP
+      def self.get: (URI::Generic uri) -> [Integer, String]
+    end
+  end
+end

data/sig/manifest.yaml

@@ -0,0 +1,3 @@
+# Bibliotecas padrão do Ruby que as assinaturas usam (o rbs collection lê daqui).
+dependencies:
+  - name: uri

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: br_validators
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Pedro Pedrassolli
@@ -31,6 +31,7 @@ files:
 - lib/br_validators/cns.rb
 - lib/br_validators/consulta.rb
 - lib/br_validators/cpf.rb
+- lib/br_validators/documentos.rb
 - lib/br_validators/locale/en.yml
 - lib/br_validators/locale/pt-BR.yml
 - lib/br_validators/pix.rb
@@ -53,6 +54,8 @@ files:
 - lib/br_validators/validators/telefone_validator.rb
 - lib/br_validators/validators/titulo_eleitor_validator.rb
 - lib/br_validators/version.rb
+- sig/br_validators.rbs
+- sig/manifest.yaml
 homepage: https://github.com/PedroPedrassolli/br_validators
 licenses:
 - MIT
@@ -60,6 +63,7 @@ metadata:
   source_code_uri: https://github.com/PedroPedrassolli/br_validators
   changelog_uri: https://github.com/PedroPedrassolli/br_validators/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/PedroPedrassolli/br_validators/issues
+  documentation_uri: https://rubydoc.info/gems/br_validators
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: