brazil-validator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4a547d374960ed7a988ed11363ec67e020e70d7c3a09cbaeb605e9f142f0b645
+  data.tar.gz: c22a673bc326f22e1dc993309c4c7ee0edda786c2fcfed45d247f4d2119254b5
+SHA512:
+  metadata.gz: c435c11b391665702e5889563e434e7ab9f0bae4e65d2415a3427a0d399c3c015a421a30e5a52ef432a85d75b3f9d54b48e4fbcf1ad5b8daefbe9c93988557d8
+  data.tar.gz: 1a22275112825f05cde5fab1e155dd1e2ab4fa9f57d15a2091c5fa55610fb2c9dd246c2b7969ec273b1d657b616193503316fd387551d087ac2495ad31f80656

data/README.md

@@ -0,0 +1,77 @@
+# brazil-validator (Ruby)
+
+A validation, normalization, and formatting gem for Brazilian data: CPF, CNPJ, CEP, phone numbers, e-mail, PIX keys, and Inscrição Estadual.
+
+This is the Ruby port of the [TypeScript implementation](../README.md), replicating the same officially-verified rules. Every module follows the same conceptual API:
+
+```ruby
+Module.is_valid?(value) # -> true/false
+Module.normalize(value) # -> String
+Module.format(value)    # -> String
+```
+
+Two adaptations to Ruby convention: `is_valid?` carries the idiomatic `?` suffix for a predicate method (kept the `is_` prefix so the name still matches every other language's `isValid`/`is_valid`), and PIX's key-type lookup is named `key_type` (not `get_key_type`, per Ruby's convention of dropping `get_` on simple readers) and returns a symbol (`:cpf`, `:cnpj`, `:email`, `:phone`, `:evp`) or `nil` — not a string enum.
+
+`Ie` extends the pattern with a second `uf` argument (the check-digit algorithm is defined per state, not nationally).
+
+## Installation
+
+Not yet published to RubyGems. Add it straight from this repository to your `Gemfile`:
+
+```ruby
+gem "brazil-validator", git: "https://github.com/matheuslm7/brazil-validator.git", glob: "ruby/*.gemspec"
+```
+
+Or clone and build it locally:
+
+```bash
+git clone https://github.com/matheuslm7/brazil-validator.git
+cd brazil-validator/ruby
+gem build brazil-validator.gemspec
+gem install ./brazil-validator-0.1.0.gem
+```
+
+*(the gem is published as `brazil-validator`, but the require path keeps its original name: `require "br_validator"` — a gem's published name and its require path don't have to match, e.g. the `activesupport` gem is required as `active_support`)*
+
+## Usage
+
+```ruby
+require "br_validator"
+
+BrValidator::Cpf.is_valid?("529.982.247-25")       # true
+BrValidator::Cpf.format("52998224725")             # "529.982.247-25"
+
+BrValidator::Cnpj.is_valid?("11.222.333/0001-81")  # true
+
+BrValidator::Ie.is_valid?("110.042.490.114", "SP") # true
+
+BrValidator::Pix.key_type("+5511987654321")        # :phone
+```
+
+## Modules
+
+| Module | Notes |
+| --- | --- |
+| `Cpf` | |
+| `Cnpj` | Numeric and alphanumeric |
+| `Cep` | |
+| `Phone` | National numbers only, no `+55` |
+| `Email` | `format` returns the same value as `normalize` (no visual mask) |
+| `Pix` | `key_type` returns a symbol: `:cpf`, `:cnpj`, `:email`, `:phone`, `:evp`, or `nil` |
+| `Ie` | All 27 states/DF; `is_valid?`/`normalize`/`format` take `(value, uf)`. Each state is its own module under `BrValidator::Ie` — not part of the public API, only `BrValidator::Ie` itself is meant to be used directly |
+
+See the [main README](../README.md) for the full behavior reference (official sources, normalize/format rules per validator, known gaps) — it applies identically here.
+
+## Conformance
+
+`test/conformance_test.rb` checks this implementation against [`specification/`](../specification), the language-independent test vectors generated from the TypeScript implementation. If it passes, this port behaves identically to TypeScript (and to the [Go](../go), [Python](../python), [Java](../java), and [C#](../csharp) ports) for every vector on file.
+
+## Development
+
+Zero runtime dependencies. Tests use Minitest (bundled with Ruby) — `rake` and `minitest` are declared as development dependencies only.
+
+```bash
+cd ruby
+bundle install
+bundle exec rake test
+```

data/lib/br_validator/cep.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "shared"
+
+module BrValidator
+  # Validates, normalizes, and formats Brazilian CEP (postal) codes.
+  module Cep
+    module_function
+
+    ALLOWED_CHARS = /\A[\d-]+\z/.freeze
+    private_constant :ALLOWED_CHARS
+
+    # Strips formatting and returns the canonical (digits-only)
+    # representation of value.
+    def normalize(value)
+      Shared.remove_non_digits(value)
+    end
+
+    # Returns true if value is a structurally valid CEP.
+    #
+    # A CEP has no check digit -- it is an 8-digit postal routing code
+    # (region, sub-region, sector, subsector and distribution suffix)
+    # defined by Correios -- so validity here means structural correctness
+    # (8 digits), not whether the code exists in Correios' address
+    # database.
+    def is_valid?(value)
+      return false unless value.match?(ALLOWED_CHARS)
+
+      normalize(value).length == 8
+    end
+
+    # Returns value as XXXXX-XXX.
+    #
+    # If the normalized value has an invalid length, value is returned
+    # unchanged.
+    def format(value)
+      cep = normalize(value)
+
+      return value unless cep.length == 8
+
+      "#{cep[0...5]}-#{cep[5...8]}"
+    end
+  end
+end

data/lib/br_validator/cnpj.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module BrValidator
+  # Validates, normalizes, and formats Brazilian CNPJ numbers.
+  #
+  # Covers both the traditional numeric format and the alphanumeric format
+  # introduced by Receita Federal.
+  module Cnpj
+    module_function
+
+    ALLOWED_CHARS = %r{\A[A-Za-z0-9.\-/\s]+\z}.freeze
+    FORMATTING_CHARS = %r{[.\-/\s]}.freeze
+    NORMALIZED_SHAPE = /\A[A-Z0-9]{12}\d{2}\z/.freeze
+    private_constant :ALLOWED_CHARS, :FORMATTING_CHARS, :NORMALIZED_SHAPE
+
+    # Strips formatting and uppercases value.
+    #
+    # A digit-only strip would destroy alphanumeric CNPJ values, so only
+    # separator characters are removed.
+    def normalize(value)
+      value.gsub(FORMATTING_CHARS, "").upcase
+    end
+
+    def character_value(char)
+      char.ord - 48
+    end
+    private_class_method :character_value
+
+    def calculate_check_digit(value)
+      sum = 0
+      weight = value.length == 12 ? 5 : 6
+
+      value.each_char do |char|
+        sum += character_value(char) * weight
+        weight -= 1
+        weight = 9 if weight == 1
+      end
+
+      remainder = sum % 11
+
+      return 0 if [0, 1].include?(remainder)
+
+      11 - remainder
+    end
+    private_class_method :calculate_check_digit
+
+    # Returns true if value is a structurally and check-digit valid CNPJ,
+    # numeric or alphanumeric.
+    #
+    # Accepts raw or formatted input but rejects unexpected characters.
+    def is_valid?(value)
+      return false unless value.match?(ALLOWED_CHARS)
+
+      cnpj = normalize(value)
+
+      return false unless cnpj.match?(NORMALIZED_SHAPE)
+
+      first_digit = calculate_check_digit(cnpj[0...12])
+      return false unless first_digit == cnpj[12].to_i
+
+      second_digit = calculate_check_digit(cnpj[0...13])
+
+      second_digit == cnpj[13].to_i
+    end
+
+    # Returns value as XX.XXX.XXX/XXXX-XX.
+    #
+    # If the normalized value has an invalid length, value is returned
+    # unchanged.
+    def format(value)
+      cnpj = normalize(value)
+
+      return value unless cnpj.length == 14
+
+      "#{cnpj[0...2]}.#{cnpj[2...5]}.#{cnpj[5...8]}/#{cnpj[8...12]}-#{cnpj[12...14]}"
+    end
+  end
+end

data/lib/br_validator/cpf.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "shared"
+
+module BrValidator
+  # Validates, normalizes, and formats Brazilian CPF numbers.
+  module Cpf
+    module_function
+
+    ALLOWED_CHARS = /\A[\d.\-\s]+\z/.freeze
+    REPEATED_DIGITS = /\A(\d)\1{10}\z/.freeze
+    private_constant :ALLOWED_CHARS, :REPEATED_DIGITS
+
+    # Strips formatting and returns the canonical (digits-only)
+    # representation of value.
+    def normalize(value)
+      Shared.remove_non_digits(value)
+    end
+
+    def calculate_check_digit(cpf, weight)
+      sum = 0
+
+      cpf.each_char.with_index do |char, i|
+        sum += char.to_i * (weight - i)
+      end
+
+      remainder = (sum * 10) % 11
+      remainder == 10 ? 0 : remainder
+    end
+    private_class_method :calculate_check_digit
+
+    # Returns true if value is a structurally and check-digit valid CPF.
+    #
+    # Accepts raw or formatted input but rejects unexpected characters.
+    def is_valid?(value)
+      return false unless value.match?(ALLOWED_CHARS)
+
+      cpf = normalize(value)
+
+      return false unless cpf.length == 11
+      return false if cpf.match?(REPEATED_DIGITS)
+
+      first_digit = calculate_check_digit(cpf[0...9], 10)
+      return false unless first_digit == cpf[9].to_i
+
+      second_digit = calculate_check_digit(cpf[0...10], 11)
+
+      second_digit == cpf[10].to_i
+    end
+
+    # Returns value as XXX.XXX.XXX-XX.
+    #
+    # If the normalized value has an invalid length, value is returned
+    # unchanged.
+    def format(value)
+      cpf = normalize(value)
+
+      return value unless cpf.length == 11
+
+      "#{cpf[0...3]}.#{cpf[3...6]}.#{cpf[6...9]}-#{cpf[9...11]}"
+    end
+  end
+end

data/lib/br_validator/email.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module BrValidator
+  # Validates, normalizes, and formats e-mail addresses.
+  module Email
+    module_function
+
+    # Sourced from the WHATWG HTML Living Standard's email state regex
+    # (used by browsers to validate <input type="email">). All quantifiers
+    # are bounded, so it cannot suffer catastrophic backtracking.
+    EMAIL_REGEX = /
+      \A[a-zA-Z0-9.!\#$%&'*+\/=?^_`{|}~-]+
+      @[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?
+      (?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+\z
+    /x.freeze
+
+    MAX_EMAIL_LENGTH = 254
+    MAX_LOCAL_PART_LENGTH = 64
+    private_constant :EMAIL_REGEX, :MAX_EMAIL_LENGTH, :MAX_LOCAL_PART_LENGTH
+
+    # Trims whitespace and lowercases value.
+    def normalize(value)
+      value.strip.downcase
+    end
+
+    # Returns true if value is a structurally valid e-mail address, per the
+    # WHATWG regular expression plus RFC 5321 length limits.
+    def is_valid?(value)
+      email = normalize(value)
+
+      return false if email.empty? || email.length > MAX_EMAIL_LENGTH
+
+      local_part = email.split("@", 2).first
+
+      return false if local_part.nil? || local_part.empty? || local_part.length > MAX_LOCAL_PART_LENGTH
+
+      email.match?(EMAIL_REGEX)
+    end
+
+    # Returns the same canonical value as normalize.
+    #
+    # Unlike CPF/CNPJ/CEP/Phone, an e-mail address has no visual mask to
+    # apply.
+    def format(value)
+      normalize(value)
+    end
+  end
+end

data/lib/br_validator/ie/ac.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../shared"
+require_relative "mod11"
+
+module BrValidator
+  module Ie
+    # AC: verified against the official SEFAZ-AC "Roteiro de Crítica da
+    # Inscrição Estadual" (sintegra.gov.br/Cad_Estados/cad_AC.html),
+    # including its worked example (01.004.823/001-12). Format: 11 digits
+    # (always starting with "01") + 2 check digits.
+    module Ac
+      module_function
+
+      ALLOWED_CHARS = %r{\A[\d./\-\s]+\z}.freeze
+      FIRST_DIGIT_WEIGHTS = [4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2].freeze
+      SECOND_DIGIT_WEIGHTS = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2].freeze
+      private_constant :ALLOWED_CHARS, :FIRST_DIGIT_WEIGHTS, :SECOND_DIGIT_WEIGHTS
+
+      def normalize(value)
+        Shared.remove_non_digits(value)
+      end
+
+      def is_valid?(value)
+        return false unless value.match?(ALLOWED_CHARS)
+
+        v = normalize(value)
+
+        return false unless v.length == 13 && v.start_with?("01")
+
+        first_digit = Mod11.mod11_check_digit(Mod11.weighted_sum(v, FIRST_DIGIT_WEIGHTS))
+        return false unless first_digit == v[11].to_i
+
+        second_digit = Mod11.mod11_check_digit(Mod11.weighted_sum(v, SECOND_DIGIT_WEIGHTS))
+
+        second_digit == v[12].to_i
+      end
+
+      def format(value)
+        v = normalize(value)
+
+        return value unless v.length == 13
+
+        "#{v[0...2]}.#{v[2...5]}.#{v[5...8]}/#{v[8...11]}-#{v[11...13]}"
+      end
+    end
+  end
+end

data/lib/br_validator/ie/al.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../shared"
+require_relative "mod11"
+
+module BrValidator
+  module Ie
+    # AL: verified against the official SEFAZ-AL "Roteiro de Crítica da
+    # Inscrição Estadual" (sintegra.gov.br/Cad_Estados/cad_AL.html),
+    # including its worked example (24000004 -> check digit 8, i.e.
+    # 240000048).
+    #
+    # Format: "24" (fixed) + 1 "tipo de empresa" digit (0,3,5,7,8) + 5
+    # sequence digits + 1 check digit = 9 digits total. No official
+    # punctuation mask is published, so format returns the plain digits.
+    module Al
+      module_function
+
+      ALLOWED_CHARS = /\A[\d\s]+\z/.freeze
+      WEIGHTS = [9, 8, 7, 6, 5, 4, 3, 2].freeze
+      VALID_TYPE_DIGITS = %w[0 3 5 7 8].freeze
+      private_constant :ALLOWED_CHARS, :WEIGHTS, :VALID_TYPE_DIGITS
+
+      def normalize(value)
+        Shared.remove_non_digits(value)
+      end
+
+      def is_valid?(value)
+        return false unless value.match?(ALLOWED_CHARS)
+
+        v = normalize(value)
+
+        return false unless v.length == 9 && v.start_with?("24")
+        return false unless VALID_TYPE_DIGITS.include?(v[2])
+
+        check_digit = Mod11.mod11_times_ten_check_digit(Mod11.weighted_sum(v, WEIGHTS))
+
+        check_digit == v[8].to_i
+      end
+
+      def format(value)
+        normalize(value)
+      end
+    end
+  end
+end

data/lib/br_validator/ie/am.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../shared"
+require_relative "mod11"
+
+module BrValidator
+  module Ie
+    # AM: verified against the official SEFAZ-AM "Roteiro de Crítica da
+    # Inscrição Estadual" (sintegra.gov.br/Cad_Estados/cad_AM.html).
+    # Format: 99.999.999-9 (8 digits + 1 check digit). Unlike most other
+    # states, when the weighted sum itself is below 11 the digit is 11
+    # minus the sum directly (skipping the modulo step).
+    module Am
+      module_function
+
+      ALLOWED_CHARS = /\A[\d.\-\s]+\z/.freeze
+      WEIGHTS = [9, 8, 7, 6, 5, 4, 3, 2].freeze
+      private_constant :ALLOWED_CHARS, :WEIGHTS
+
+      def normalize(value)
+        Shared.remove_non_digits(value)
+      end
+
+      def calculate_check_digit(v)
+        sum = Mod11.weighted_sum(v, WEIGHTS)
+
+        return 11 - sum if sum < 11
+
+        Mod11.mod11_check_digit(sum)
+      end
+      private_class_method :calculate_check_digit
+
+      def is_valid?(value)
+        return false unless value.match?(ALLOWED_CHARS)
+
+        v = normalize(value)
+
+        return false unless v.length == 9
+
+        calculate_check_digit(v) == v[8].to_i
+      end
+
+      def format(value)
+        v = normalize(value)
+
+        return value unless v.length == 9
+
+        "#{v[0...2]}.#{v[2...5]}.#{v[5...8]}-#{v[8...9]}"
+      end
+    end
+  end
+end

data/lib/br_validator/ie/ap.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "../shared"
+require_relative "mod11"
+
+module BrValidator
+  module Ie
+    # AP: verified against the official SEFAZ-AP "Roteiro de Crítica da
+    # Inscrição Estadual" (sintegra.gov.br/Cad_Estados/cad_AP.html),
+    # including its worked example (030123459).
+    #
+    # Format: "03" (fixed) + 6 sequence digits + 1 check digit = 9 digits
+    # total. Unlike other states, the weighted sum starts from a constant
+    # "p" that depends on the numeric range of the registration, and a
+    # zero remainder maps to a range-dependent digit "d" instead of always
+    # 0.
+    module Ap
+      module_function
+
+      ALLOWED_CHARS = /\A[\d\s]+\z/.freeze
+      WEIGHTS = [9, 8, 7, 6, 5, 4, 3, 2].freeze
+      private_constant :ALLOWED_CHARS, :WEIGHTS
+
+      def normalize(value)
+        Shared.remove_non_digits(value)
+      end
+
+      def resolve_constants(base)
+        return [5, 0] if base <= 3_017_000
+        return [9, 1] if base <= 3_019_022
+
+        [0, 0]
+      end
+      private_class_method :resolve_constants
+
+      def calculate_check_digit(v)
+        base = v[0...8]
+        p, d = resolve_constants(base.to_i)
+        sum = p + Mod11.weighted_sum(base, WEIGHTS)
+        remainder = sum % 11
+
+        return 0 if remainder == 1
+        return d if remainder.zero?
+
+        11 - remainder
+      end
+      private_class_method :calculate_check_digit
+
+      def is_valid?(value)
+        return false unless value.match?(ALLOWED_CHARS)
+
+        v = normalize(value)
+
+        return false unless v.length == 9 && v.start_with?("03")
+
+        calculate_check_digit(v) == v[8].to_i
+      end
+
+      def format(value)
+        normalize(value)
+      end
+    end
+  end
+end

data/lib/br_validator/ie/ba.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "../shared"
+require_relative "mod11"
+
+module BrValidator
+  module Ie
+    # BA: verified against the official SEFAZ-BA "Roteiro de Crítica da
+    # Inscrição Estadual" (sintegra.gov.br/Cad_Estados/cad_BA.html),
+    # including its four worked examples (123456-63, 612345-57,
+    # 1000003-06 mod-10/mod-11 x 8/9-digit variants).
+    #
+    # Bahia has two lengths (8 or 9 digits) and, within each, two moduli:
+    # módulo 10 when the discriminating digit (the 1st digit for 8-digit
+    # IEs, the 2nd for 9-digit IEs) is one of 0,1,2,3,4,5,8, and módulo 11
+    # when it is 6, 7 or 9. The last check digit is calculated first (from
+    # the base digits alone), then the first check digit is calculated
+    # from the base plus that digit.
+    module Ba
+      module_function
+
+      ALLOWED_CHARS = /\A[\d\-\s]+\z/.freeze
+      MOD10_DIGITS = %w[0 1 2 3 4 5 8].freeze
+      MOD11_DIGITS = %w[6 7 9].freeze
+      private_constant :ALLOWED_CHARS, :MOD10_DIGITS, :MOD11_DIGITS
+
+      def normalize(value)
+        Shared.remove_non_digits(value)
+      end
+
+      def check_digit_for(sum, use_mod11)
+        use_mod11 ? Mod11.mod11_check_digit(sum) : Mod11.mod10_check_digit(sum)
+      end
+      private_class_method :check_digit_for
+
+      def descending_weights(length)
+        (0...length).map { |i| length + 1 - i }
+      end
+      private_class_method :descending_weights
+
+      def is_valid?(value)
+        return false unless value.match?(ALLOWED_CHARS)
+
+        v = normalize(value)
+
+        return false unless [8, 9].include?(v.length)
+
+        discriminant = v.length == 8 ? v[0] : v[1]
+        use_mod11 = MOD11_DIGITS.include?(discriminant)
+
+        return false if !use_mod11 && !MOD10_DIGITS.include?(discriminant)
+
+        base_length = v.length - 2
+        base = v[0...base_length]
+        last_digit = check_digit_for(Mod11.weighted_sum(base, descending_weights(base_length)), use_mod11)
+
+        return false unless last_digit == v[-1].to_i
+
+        base_with_last_digit = base + last_digit.to_s
+        first_digit = check_digit_for(
+          Mod11.weighted_sum(base_with_last_digit, descending_weights(base_length + 1)), use_mod11
+        )
+
+        first_digit == v[-2].to_i
+      end
+
+      def format(value)
+        v = normalize(value)
+
+        return value unless [8, 9].include?(v.length)
+
+        "#{v[0...-2]}-#{v[-2..]}"
+      end
+    end
+  end
+end

data/lib/br_validator/ie/ce.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../shared"
+require_relative "mod11"
+
+module BrValidator
+  module Ie
+    # CE: verified against the official SEFAZ-CE "Roteiro de Crítica da
+    # Inscrição Estadual" (sintegra.gov.br/Cad_Estados/cad_CE.html),
+    # including its worked example (06000001-5). Format: 8 digits + 1
+    # check digit.
+    module Ce
+      module_function
+
+      ALLOWED_CHARS = /\A[\d\-\s]+\z/.freeze
+      WEIGHTS = [9, 8, 7, 6, 5, 4, 3, 2].freeze
+      private_constant :ALLOWED_CHARS, :WEIGHTS
+
+      def normalize(value)
+        Shared.remove_non_digits(value)
+      end
+
+      def is_valid?(value)
+        return false unless value.match?(ALLOWED_CHARS)
+
+        v = normalize(value)
+
+        return false unless v.length == 9
+
+        Mod11.mod11_check_digit(Mod11.weighted_sum(v, WEIGHTS)) == v[8].to_i
+      end
+
+      def format(value)
+        v = normalize(value)
+
+        return value unless v.length == 9
+
+        "#{v[0...8]}-#{v[8...9]}"
+      end
+    end
+  end
+end