br-utils 0.1.0 → 0.2.0

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

@@ -0,0 +1,171 @@
+module BrazilianUtils
+  # Utilities for the matrícula of a certidão de registro civil (art. 473
+  # of the Código Nacional de Normas da Corregedoria Nacional de Justiça):
+  # a 32-digit number grouped as 6-2-2-4-1-5-3-7-2 (registry CNS, acervo,
+  # serviço, ano, tipo do livro, livro, folha, termo, 2 check digits).
+  module CertidaoUtils
+    # Maps the single-digit "tipo do livro" code to its name.
+    BOOK_TYPES = {
+      '1' => 'birth',
+      '2' => 'marriage',
+      '3' => 'religiousMarriage',
+      '4' => 'death',
+      '5' => 'stillbirth',
+      '6' => 'banns',
+      '7' => 'other',
+      '8' => 'emancipation',
+      '9' => 'interdiction'
+    }.freeze
+
+    FIELD_SIZES = [6, 2, 2, 4, 1, 5, 3, 7, 2].freeze
+    FIELD_KEYS = %i[registryCns acervo service year type book page term checkDigits].freeze
+
+    # @private
+    def self.apply_mask(digits, group_sizes, separators)
+      chunks = []
+      idx = 0
+      group_sizes.each do |size|
+        break if idx >= digits.length
+
+        chunks << digits[idx, size]
+        idx += size
+      end
+      chunks.each_with_index.map { |c, i| i.zero? ? c : "#{separators[i - 1]}#{c}" }.join
+    end
+
+    private_class_method :apply_mask
+
+    # Formats a matrícula into the printed groups (6-2-2-4-1-5-3-7-2),
+    # separated by spaces, applied as far as the digits go.
+    #
+    # @param value [String, Integer]
+    # @param options [Hash] `:pad` left-pads with zeros to 32 digits first.
+    # @return [String]
+    def self.format(value, options = {})
+      digits = value.to_s.gsub(/\D/, '')
+      digits = digits.rjust(32, '0') if options[:pad] || options['pad']
+      return '' if digits.empty?
+
+      apply_mask(digits, FIELD_SIZES, [' '] * 8)
+    end
+
+    # Removes the formatting of a certidão matrícula and keeps only
+    # digits, capped to 32 digits.
+    #
+    # @param value [String, Integer]
+    # @return [String]
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      value.to_s.gsub(/\D/, '')[0, 32]
+    end
+
+    # @private
+    #
+    # Computes a single modulus-11 check digit over `base`: the weight
+    # starts at 2 for the rightmost character and increases by 1 moving
+    # left (no cap, no wraparound).
+    def self.check_digit(base)
+      weights = (2...(2 + base.length)).to_a.reverse
+      sum = base.chars.each_with_index.sum { |d, i| d.to_i * weights[i] }
+      remainder = sum % 11
+      remainder < 2 ? 0 : 11 - remainder
+    end
+
+    private_class_method :check_digit
+
+    # @private
+    #
+    # Only digits and the separators {space, '.', '-', '/'} are accepted
+    # anywhere in the string; any other character makes the whole value
+    # invalid. Returns the digits-only string, or nil when the input isn't
+    # a String/Integer or contains a disallowed character.
+    def self.clean_for_validation(value)
+      return nil unless value.is_a?(String) || value.is_a?(Integer)
+
+      raw = value.to_s
+      return nil unless raw.match?(%r{\A[\d\s.\-/]*\z})
+
+      raw.gsub(%r{[\s.\-/]}, '')
+    end
+
+    private_class_method :clean_for_validation
+
+    # @private
+    def self.extract_fields(digits)
+      fields = {}
+      idx = 0
+      FIELD_KEYS.each_with_index do |key, i|
+        size = FIELD_SIZES[i]
+        fields[key] = digits[idx, size]
+        idx += size
+      end
+      fields
+    end
+
+    private_class_method :extract_fields
+
+    # Checks whether a certidão matrícula is structurally valid and its 2
+    # modulus-11 check digits match.
+    #
+    # @param value [String, Integer] The matrícula, bare or separated by
+    #   any mix of space, `.`, `-` or `/`. Any other character (a letter,
+    #   for instance) anywhere in the value makes it invalid.
+    # @param options [Hash] `:accept` an optional Array narrowing which
+    #   book-type codes (as the raw digit string, e.g. `"1"`) or names
+    #   (e.g. `"birth"`) are accepted; defaults to accepting all of 1-9.
+    # @return [Boolean]
+    def self.is_valid(value, options = {})
+      digits = clean_for_validation(value)
+      return false unless digits
+      return false unless digits.match?(/\A\d{32}\z/)
+
+      raw = extract_fields(digits)
+      return false unless raw[:service] == '55'
+      return false unless BOOK_TYPES.key?(raw[:type])
+
+      accept = options[:accept] || options['accept']
+      if accept
+        accepted = Array(accept).map(&:to_s)
+        return false unless accepted.include?(raw[:type]) || accepted.include?(BOOK_TYPES[raw[:type]])
+      end
+
+      base30 = digits[0, 30]
+      dv1 = check_digit(base30)
+      dv2 = check_digit(base30 + dv1.to_s)
+
+      raw[:checkDigits] == "#{dv1}#{dv2}"
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Parses a certidão matrícula into its fields.
+    #
+    # @param value [String, Integer] Same accepted forms as {is_valid}.
+    # @param options [Hash] Same as {is_valid}.
+    # @return [Hash, nil] `nil` whenever {is_valid} would return false;
+    #   otherwise a Hash with `:registryCns`, `:acervo`, `:service`,
+    #   `:year` (Integer), `:type` (the book-type name), `:book`, `:page`,
+    #   `:term` and `:checkDigits`.
+    def self.get_info(value, options = {})
+      return nil unless is_valid(value, options)
+
+      digits = clean_for_validation(value)
+      raw = extract_fields(digits)
+
+      {
+        registryCns: raw[:registryCns],
+        acervo: raw[:acervo],
+        service: raw[:service],
+        year: raw[:year].to_i,
+        type: BOOK_TYPES[raw[:type]],
+        book: raw[:book],
+        page: raw[:page],
+        term: raw[:term],
+        checkDigits: raw[:checkDigits]
+      }
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+require 'json'
+
+module BrazilianUtils
+  # Utilities for the CFOP (Código Fiscal de Operações e Prestações) table,
+  # the consolidated Anexo II of Convênio SINIEF s/nº 1970 in force. Only
+  # operable codes are included (group/subgroup headings are excluded).
+  module CFOPUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'cfop.json')
+
+    # @private
+    def self.load_data
+      @data ||= JSON.parse(File.read(DATA_FILE))
+    end
+
+    private_class_method :load_data
+
+    # Normalizes a CFOP value to its bare 4 digits, honoring the `N.NNN`
+    # single-separator mask; returns nil for anything else (nothing is
+    # padded, since no CFOP starts with a zero).
+    #
+    # @private
+    def self.normalize(value)
+      return nil if value.nil?
+      return nil unless value.is_a?(String) || value.is_a?(Integer)
+
+      raw = value.to_s.strip
+      return raw if raw.match?(/\A\d{4}\z/)
+
+      m = raw.match(%r{\A(\d)[ .\-/](\d{3})\z})
+      m && "#{m[1]}#{m[2]}"
+    end
+
+    private_class_method :normalize
+
+    # Checks whether a CFOP code exists in the official table (group and
+    # subgroup headings are not operable codes and are rejected).
+    #
+    # @param value [String, Integer]
+    # @return [Boolean]
+    def self.is_valid(value)
+      code = normalize(value)
+      return false unless code
+
+      load_data.key?(code)
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Looks a CFOP code up and returns its code and description.
+    #
+    # @param value [String, Integer]
+    # @return [Hash, nil]
+    def self.get(value)
+      code = normalize(value)
+      return nil unless code
+
+      description = load_data[code]
+      description && { code: code, description: description }
+    end
+
+    # Removes CFOP formatting and keeps only digits, capped to 4 digits
+    # (nothing is padded).
+    #
+    # @param value [String, Integer]
+    # @return [String]
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      value.to_s.gsub(/\D/, '')[0, 4]
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+require 'json'
+
+module BrazilianUtils
+  # Utilities for the CNAE-Subclasses 2.3 table (the current subclass
+  # revision of CNAE 2.0), sourced from the IBGE CONCLA API.
+  module CNAEUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'cnae.json')
+
+    # @private
+    def self.load_data
+      @data ||= JSON.parse(File.read(DATA_FILE))
+    end
+
+    private_class_method :load_data
+
+    # @private
+    def self.apply_mask(digits, group_sizes, separators)
+      chunks = []
+      idx = 0
+      group_sizes.each do |size|
+        break if idx >= digits.length
+
+        chunks << digits[idx, size]
+        idx += size
+      end
+      chunks.each_with_index.map { |c, i| i.zero? ? c : "#{separators[i - 1]}#{c}" }.join
+    end
+
+    private_class_method :apply_mask
+
+    # Normalizes a CNAE value to its bare 7 digits: bare digits (string or
+    # integer) are left-padded with zeros to 7; the `NNNN-N/NN` mask is
+    # read as written. Any other string is rejected.
+    #
+    # @private
+    def self.normalize(value)
+      return nil if value.nil?
+      return value.to_s.rjust(7, '0') if value.is_a?(Integer)
+      return nil unless value.is_a?(String)
+
+      raw = value.strip
+      return raw.rjust(7, '0') if raw.match?(/\A\d+\z/)
+
+      m = raw.match(%r{\A(\d{4})-(\d)/(\d{2})\z})
+      m && "#{m[1]}#{m[2]}#{m[3]}"
+    end
+
+    private_class_method :normalize
+
+    # Formats a CNAE subclass code with the mask `NNNN-N/NN`; the mask is
+    # applied as far as the digits go (only the structure changes — use
+    # {is_valid} to check the code).
+    #
+    # @param value [String, Integer]
+    # @param options [Hash] `:pad` left-pads with zeros to 7 digits first.
+    # @return [String] An empty string when there is no digit at all.
+    def self.format(value, options = {})
+      digits = value.to_s.gsub(/\D/, '')
+      digits = digits.rjust(7, '0') if options[:pad] || options['pad']
+      return '' if digits.empty?
+
+      apply_mask(digits, [4, 1, 2], ['-', '/'])
+    end
+
+    # Checks whether a CNAE subclass code exists in the table.
+    #
+    # @param value [String, Integer]
+    # @return [Boolean]
+    def self.is_valid(value)
+      code = normalize(value)
+      return false unless code
+
+      load_data.key?(code)
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Looks a CNAE subclass code up and returns its (bare, 7-digit) code
+    # and official description.
+    #
+    # @param value [String, Integer]
+    # @return [Hash, nil]
+    def self.get(value)
+      code = normalize(value)
+      return nil unless code
+
+      description = load_data[code]
+      description && { code: code, description: description }
+    end
+
+    # Removes CNAE formatting and keeps only digits, capped to 7 digits
+    # (nothing is left-padded).
+    #
+    # @param value [String, Integer]
+    # @return [String]
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      value.to_s.gsub(/\D/, '')[0, 7]
+    end
+  end
+end

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

@@ -32,41 +32,41 @@ module BrazilianUtils
       first_verificator = digits[9]
       second_verificator = digits[10]
 
-      # Check the 10th digit
-      return false unless check_first_verificator(digits, first_verificator)
+      # Check the 10th digit; keep the raw remainder (0-10), since the
+      # decrement applied to the 11th digit depends on whether the *pre-cap*
+      # remainder overflowed (>9), not on the printed digit (always 0-9).
+      first_rest = calculate_first_rest(digits)
+      expected_first = first_rest > 9 ? 0 : first_rest
+      return false unless expected_first == first_verificator
 
       # Check the 11th digit
-      check_second_verificator(digits, second_verificator, first_verificator)
+      check_second_verificator(digits, second_verificator, first_rest)
     end
 
-    # Generates the first verification digit and uses it to verify the 10th digit of the CNH
+    # Computes the raw remainder used to derive the CNH's first verification digit.
     #
     # @param digits [Array<Integer>] Array of CNH digits
-    # @param first_verificator [Integer] The first verification digit (10th digit)
-    # @return [Boolean] true if the first verificator is valid
+    # @return [Integer] The remainder (0-10) before capping to a single printable digit
     #
     # @private
-    def self.check_first_verificator(digits, first_verificator)
+    def self.calculate_first_rest(digits)
       sum = 0
       9.times do |i|
         sum += digits[i] * (9 - i)
       end
 
-      sum = sum % 11
-      result = sum > 9 ? 0 : sum
-
-      result == first_verificator
+      sum % 11
     end
 
     # Generates the second verification digit and uses it to verify the 11th digit of the CNH
     #
     # @param digits [Array<Integer>] Array of CNH digits
     # @param second_verificator [Integer] The second verification digit (11th digit)
-    # @param first_verificator [Integer] The first verification digit (10th digit)
+    # @param first_rest [Integer] The raw remainder (0-10) used to compute the 10th digit
     # @return [Boolean] true if the second verificator is valid
     #
     # @private
-    def self.check_second_verificator(digits, second_verificator, first_verificator)
+    def self.check_second_verificator(digits, second_verificator, first_rest)
       sum = 0
       9.times do |i|
         sum += digits[i] * (i + 1)
@@ -74,7 +74,7 @@ module BrazilianUtils
 
       result = sum % 11
 
-      if first_verificator > 9
+      if first_rest > 9
         result = (result - 2).negative? ? result + 9 : result - 2
       end
 
@@ -83,6 +83,59 @@ module BrazilianUtils
       result == second_verificator
     end
 
-    private_class_method :check_first_verificator, :check_second_verificator
+    private_class_method :calculate_first_rest, :check_second_verificator
+
+    # Formats a CNH number as `000000000-00` (9 digits, hyphen, 2 check
+    # digits). The mask is applied as far as the digits go.
+    #
+    # @param value [String, Integer] The value to format.
+    # @param options [Hash] `:pad` left-pads the value with zeros to 11
+    #   digits first.
+    # @return [String]
+    #
+    # @example
+    #   format("00000000119")  #=> "000000001-19"
+    def self.format(value, options = {})
+      digits = value.to_s.gsub(/\D/, '')
+      digits = digits.rjust(11, '0') if options[:pad] || options['pad']
+      return digits if digits.length <= 9
+
+      "#{digits[0, 9]}-#{digits[9..-1]}"
+    end
+
+    # Removes CNH formatting and keeps only digits, capped to 11 digits.
+    #
+    # @param value [String, Integer]
+    # @return [String]
+    #
+    # @example
+    #   parse("000000001-19")  #=> "00000000119"
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      value.to_s.gsub(/\D/, '')[0, 11]
+    end
+
+    # Generates a valid random CNH number (11 digits, unformatted).
+    #
+    # @return [String]
+    def self.generate
+      loop do
+        base9 = 9.times.map { rand(0..9) }
+        next if base9.uniq.length == 1
+
+        first_rest = calculate_first_rest(base9)
+        first_verificator = first_rest > 9 ? 0 : first_rest
+
+        sum2 = 0
+        9.times { |i| sum2 += base9[i] * (i + 1) }
+        result = sum2 % 11
+        result = (result - 2).negative? ? result + 9 : result - 2 if first_rest > 9
+        second_verificator = result > 9 ? 0 : result
+
+        cnh = "#{base9.join}#{first_verificator}#{second_verificator}"
+        return cnh if valid?(cnh)
+      end
+    end
   end
 end

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

@@ -0,0 +1,76 @@
+module BrazilianUtils
+  # Utilities for the CNO (Cadastro Nacional de Obras), which replaced the
+  # CEI for construction works and kept its numbering/check-digit rule.
+  module CNOUtils
+    WEIGHTS = [7, 4, 1, 8, 5, 2, 1, 6, 3, 7, 4].freeze
+
+    # @private
+    def self.apply_mask(digits, group_sizes, separators)
+      chunks = []
+      idx = 0
+      group_sizes.each do |size|
+        break if idx >= digits.length
+
+        chunks << digits[idx, size]
+        idx += size
+      end
+      chunks.each_with_index.map { |c, i| i.zero? ? c : "#{separators[i - 1]}#{c}" }.join
+    end
+
+    private_class_method :apply_mask
+
+    # @private
+    def self.check_digit(base)
+      sum = base.chars.each_with_index.sum { |d, i| d.to_i * WEIGHTS[i] }
+      last_two = sum % 100
+      combined = (last_two / 10) + (last_two % 10)
+      (10 - (combined % 10)) % 10
+    end
+
+    private_class_method :check_digit
+
+    # Validates a CNO: same rules as CEIUtils#is_valid.
+    #
+    # @param value [String, Integer]
+    # @return [Boolean]
+    def self.is_valid(value)
+      return false unless value.is_a?(String) || value.is_a?(Integer)
+
+      raw = value.to_s.strip
+      return false unless raw.match?(%r{\A[\d\s.\-/]+\z})
+
+      digits = raw.gsub(%r{[\s.\-/]}, '')
+      return false unless digits.match?(/\A\d{12}\z/)
+      return false if digits.chars.uniq.length == 1
+
+      digits[11].to_i == check_digit(digits[0, 11])
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Formats a CNO with the mask `00.000.00000/00` (the CEI numbering).
+    #
+    # @param value [String, Integer]
+    # @param options [Hash] `:pad` left-pads with zeros to 12 digits first.
+    # @return [String]
+    def self.format(value, options = {})
+      digits = value.to_s.gsub(/\D/, '')
+      digits = digits.rjust(12, '0') if options[:pad] || options['pad']
+      return '' if digits.empty?
+
+      apply_mask(digits, [2, 3, 5, 2], ['.', '.', '/'])
+    end
+
+    # Removes CNO formatting and keeps only digits, capped to 12 digits.
+    #
+    # @param value [String, Integer]
+    # @return [String]
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      value.to_s.gsub(/\D/, '')[0, 12]
+    end
+  end
+end