br-utils 0.1.0 → 0.2.0

data/lib/brazilian-utils/vin-utils.rb

@@ -0,0 +1,46 @@
+module BrazilianUtils
+  # Utilities for validating a VIN (chassi) structurally: 17 characters,
+  # none of the excluded letters `I`, `O`, `Q`, and the check digit at
+  # position 9 (the North American / ISO 3779 rule).
+  #
+  # Brazilian rules do not mandate the check digit, so many Brazilian-built
+  # VINs fail it; this validates structure only, as the contract does.
+  module VINUtils
+    TRANSLITERATION = {
+      'A' => 1, 'B' => 2, 'C' => 3, 'D' => 4, 'E' => 5, 'F' => 6, 'G' => 7, 'H' => 8,
+      'J' => 1, 'K' => 2, 'L' => 3, 'M' => 4, 'N' => 5, 'P' => 7, 'R' => 9,
+      'S' => 2, 'T' => 3, 'U' => 4, 'V' => 5, 'W' => 6, 'X' => 7, 'Y' => 8, 'Z' => 9
+    }.freeze
+
+    WEIGHTS = [8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2].freeze
+
+    EXCLUDED_LETTERS = %w[I O Q].freeze
+
+    # Validates a VIN structurally.
+    #
+    # @param value [String] Case-insensitive.
+    # @return [Boolean]
+    def self.is_valid(value)
+      return false unless value.is_a?(String)
+
+      vin = value.strip.upcase
+      return false unless vin.length == 17
+      return false unless vin.match?(/\A[A-Z0-9]{17}\z/)
+      return false if EXCLUDED_LETTERS.any? { |l| vin.include?(l) }
+      return false if vin.chars.uniq.length == 1
+
+      values = vin.chars.map { |c| c.match?(/\d/) ? c.to_i : TRANSLITERATION[c] }
+      return false if values.include?(nil)
+
+      sum = values.each_with_index.sum { |v, i| v * WEIGHTS[i] }
+      remainder = sum % 11
+      check_char = remainder == 10 ? 'X' : remainder.to_s
+
+      vin[8] == check_char
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+  end
+end

data/lib/brazilian-utils/voter-id-utils.rb

@@ -13,13 +13,11 @@ module BrazilianUtils
       'AP' => '25', 'RR' => '26', 'TO' => '27', 'ZZ' => '28'
     }.freeze
 
-    module_function
-
     # Check if a Brazilian voter ID number is valid.
     #
     # @param voter_id [String] The voter ID to validate
     # @return [Boolean] true if valid, false otherwise
-    def is_valid_voter_id(voter_id)
+    def self.is_valid_voter_id(voter_id)
       # Ensure voter_id is a string with only digits and valid length
       return false unless voter_id.is_a?(String)
       return false unless voter_id.match?(/^\d+$/)
@@ -44,27 +42,37 @@ module BrazilianUtils
       true
     end
 
-    # Alias for is_valid_voter_id
-    alias valid_voter_id? is_valid_voter_id
+    class << self
+      # Alias for is_valid_voter_id
+      alias valid_voter_id? is_valid_voter_id
+    end
 
     # Format a voter ID for display with visual spaces.
     #
     # @param voter_id [String] The voter ID to format
     # @return [String, nil] Formatted voter ID or nil if invalid
-    def format_voter_id(voter_id)
+    def self.format_voter_id(voter_id)
       return nil unless is_valid_voter_id(voter_id)
 
-      "#{voter_id[0..3]} #{voter_id[4..7]} #{voter_id[8..9]} #{voter_id[10..11]}"
+      # The 13-digit SP/MG variant has an extra sequential digit; grouping it
+      # as 4+4+2+2 (like the 12-digit case) silently drops the last digit.
+      if voter_id.length == 13
+        "#{voter_id[0..3]} #{voter_id[4..7]} #{voter_id[8]} #{voter_id[9..10]} #{voter_id[11..12]}"
+      else
+        "#{voter_id[0..3]} #{voter_id[4..7]} #{voter_id[8..9]} #{voter_id[10..11]}"
+      end
     end
 
-    # Alias for format_voter_id
-    alias format format_voter_id
+    class << self
+      # Alias for format_voter_id
+      alias format format_voter_id
+    end
 
     # Generate a random valid Brazilian voter ID.
     #
     # @param federative_union [String] The UF code (e.g., "SP", "MG", "ZZ")
     # @return [String, nil] A valid voter ID or nil if UF is invalid
-    def generate(federative_union = 'ZZ')
+    def self.generate(federative_union = 'ZZ')
       federative_union = federative_union.upcase
       return nil unless UF_CODES.key?(federative_union)
 
@@ -72,7 +80,9 @@ module BrazilianUtils
       return nil unless is_federative_union_valid?(uf_number)
 
       # Generate random 8-digit sequential number
-      sequential_number = format('%08d', rand(0..99_999_999))
+      # (uses rjust, not Kernel#format, since `format` is aliased to
+      # format_voter_id on this module's singleton class below)
+      sequential_number = rand(0..99_999_999).to_s.rjust(8, '0')
 
       # Calculate verification digits
       vd1 = calculate_vd1(sequential_number, uf_number)
@@ -81,11 +91,12 @@ module BrazilianUtils
       "#{sequential_number}#{uf_number}#{vd1}#{vd2}"
     end
 
-    private
+    # PRIVATE METHODS
+    #################
 
     # Check if the length of the voter ID is valid.
     # Typically 12 digits, but can be 13 for SP and MG (edge case).
-    def is_length_valid?(voter_id)
+    def self.is_length_valid?(voter_id)
       return true if voter_id.length == 12
 
       # Edge case: SP and MG can have 13 digits
@@ -94,22 +105,22 @@ module BrazilianUtils
     end
 
     # Extract the sequential number (first 8 digits).
-    def get_sequential_number(voter_id)
+    def self.get_sequential_number(voter_id)
       voter_id[0..7]
     end
 
     # Extract the federative union (2 digits before last 2 digits).
-    def get_federative_union(voter_id)
+    def self.get_federative_union(voter_id)
       voter_id[-4..-3]
     end
 
     # Extract the verifying digits (last 2 digits).
-    def get_verifying_digits(voter_id)
+    def self.get_verifying_digits(voter_id)
       voter_id[-2..-1]
     end
 
     # Check if the federative union is valid (between '01' and '28').
-    def is_federative_union_valid?(federative_union)
+    def self.is_federative_union_valid?(federative_union)
       num = federative_union.to_i
       num >= 1 && num <= 28
     end
@@ -119,7 +130,7 @@ module BrazilianUtils
     # @param sequential_number [String] First 8 digits
     # @param federative_union [String] 2-digit UF code
     # @return [Integer] The first verification digit
-    def calculate_vd1(sequential_number, federative_union)
+    def self.calculate_vd1(sequential_number, federative_union)
       # Weights: 2, 3, 4, 5, 6, 7, 8, 9
       weights = (2..9).to_a
 
@@ -144,7 +155,7 @@ module BrazilianUtils
     # @param federative_union [String] 2-digit UF code
     # @param vd1 [Integer] First verification digit
     # @return [Integer] The second verification digit
-    def calculate_vd2(federative_union, vd1)
+    def self.calculate_vd2(federative_union, vd1)
       # Weights: 7, 8, 9
       sum = (federative_union[0].to_i * 7) +
             (federative_union[1].to_i * 8) +
@@ -161,5 +172,45 @@ module BrazilianUtils
 
       vd2
     end
+
+    private_class_method :is_length_valid?, :get_sequential_number, :get_federative_union,
+                          :get_verifying_digits, :is_federative_union_valid?, :calculate_vd1,
+                          :calculate_vd2
+
+    # Removes the voter ID formatting symbols (spaces), keeping everything else.
+    #
+    # @param value [String] A voter ID, with or without spacing.
+    # @return [String] The value with spaces removed.
+    #
+    # @example
+    #   remove_symbols("1234 5678 01 24")  #=> "123456780124"
+    def self.remove_symbols(value)
+      return '' unless value.is_a?(String)
+
+      value.gsub(/\s/, '')
+    end
+
+    # Removes voter ID formatting and keeps only digits, capped to 12 digits
+    # (13 when the UF portion is SP or MG).
+    #
+    # @param value [String, Integer] A voter ID, with or without formatting.
+    # @return [String] The parsed digits.
+    #
+    # @example
+    #   parse("1234 5678 01 24")     #=> "123456780124"
+    #   parse("1234 5678 8 01 91")   #=> "1234567880191" (13-digit SP/MG form)
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      digits = value.to_s.gsub(/\D/, '')
+      return '' if digits.empty?
+
+      if digits.length > 12
+        candidate = digits[0, 13]
+        return candidate if candidate.length == 13 && %w[01 02].include?(candidate[-4..-3])
+      end
+
+      digits[0, 12]
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: br-utils
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Alex Rocha
@@ -10,6 +10,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -61,9 +75,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rspec"
-- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -83,21 +97,59 @@ files:
 - examples/pis_usage_example.rb
 - examples/renavam_usage_example.rb
 - examples/voter_id_usage_example.rb
+- lib/brazilian-utils/area-code-utils.rb
+- lib/brazilian-utils/bank-account-utils.rb
+- lib/brazilian-utils/bank-utils.rb
 - lib/brazilian-utils/boleto-utils.rb
+- lib/brazilian-utils/caepf-utils.rb
+- lib/brazilian-utils/cbo-utils.rb
+- lib/brazilian-utils/cei-utils.rb
 - lib/brazilian-utils/cep-utils.rb
+- lib/brazilian-utils/certidao-utils.rb
+- lib/brazilian-utils/cfop-utils.rb
+- lib/brazilian-utils/cnae-utils.rb
 - lib/brazilian-utils/cnh-utils.rb
+- lib/brazilian-utils/cno-utils.rb
 - lib/brazilian-utils/cnpj-utils.rb
+- lib/brazilian-utils/cns-utils.rb
 - lib/brazilian-utils/cpf-utils.rb
+- lib/brazilian-utils/credit-card-utils.rb
+- lib/brazilian-utils/csosn-utils.rb
+- lib/brazilian-utils/cst-utils.rb
 - lib/brazilian-utils/currency-utils.rb
+- lib/brazilian-utils/data/area_codes.json
+- lib/brazilian-utils/data/banks.json
+- lib/brazilian-utils/data/cbo.json
+- lib/brazilian-utils/data/cfop.json
+- lib/brazilian-utils/data/cnae.json
+- lib/brazilian-utils/data/csosn.json
+- lib/brazilian-utils/data/cst.json
+- lib/brazilian-utils/data/legal_nature.json
 - lib/brazilian-utils/data/legal_process_ids.json
+- lib/brazilian-utils/data/municipalities.json
+- lib/brazilian-utils/data/ncm.json
+- lib/brazilian-utils/data/states.json
 - lib/brazilian-utils/date-utils.rb
 - lib/brazilian-utils/email-utils.rb
+- lib/brazilian-utils/iban-utils.rb
+- lib/brazilian-utils/ie-utils.rb
 - lib/brazilian-utils/legal-nature-utils.rb
 - lib/brazilian-utils/legal-process-utils.rb
 - lib/brazilian-utils/license-plate-utils.rb
+- lib/brazilian-utils/municipality-utils.rb
+- lib/brazilian-utils/ncm-utils.rb
+- lib/brazilian-utils/nfe-key-utils.rb
+- lib/brazilian-utils/number-utils.rb
+- lib/brazilian-utils/passport-utils.rb
 - lib/brazilian-utils/phone-utils.rb
 - lib/brazilian-utils/pis-utils.rb
+- lib/brazilian-utils/pix-key-utils.rb
+- lib/brazilian-utils/pix-payload-utils.rb
+- lib/brazilian-utils/registro-profissional-utils.rb
 - lib/brazilian-utils/renavam-utils.rb
+- lib/brazilian-utils/state-utils.rb
+- lib/brazilian-utils/text-utils.rb
+- lib/brazilian-utils/vin-utils.rb
 - lib/brazilian-utils/voter-id-utils.rb
 homepage: https://github.com/brazilian-utils/ruby
 licenses:

data/.travis.yml

@@ -1,5 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.3.0
-before_install: gem install bundler -v 1.12.5