Implement package `br-utilities`

[juliolmuller]

Overview

Implement the br-utilities package as a class-based Ruby library to handle two key Brazilian taxpayer identification documents:

• CPF (Cadastro de Pessoas Físicas) — the individual taxpayer registry number issued by the Brazilian Federal Revenue Service (Receita Federal).
• CNPJ (Cadastro Nacional da Pessoa Jurídica) — the national registry number for legal entities, also managed by the Receita Federal.

---

Features

The package must provide the following capabilities for both CPF and CNPJ:

Feature	Description
Format	Apply the canonical mask to a raw number string (e.g., 12345678000195 → 12.345.678/0001-95).
Generate	Produce a random, valid CPF or CNPJ number (optionally formatted).
Validate	Check whether a given number is mathematically valid using the módulo 11 algorithm.

---

Document Specifications

CPF

• Length: 11 digits
• Formatted mask: xxx.xxx.xxx-xx (last 2 digits are check digits)
• Validation: Módulo 11 algorithm applied twice to compute the two check digits.

CNPJ

• Length: 14 characters
• Formatted mask (numeric): xx.xxx.xxx/xxxx-xx
• Formatted mask (alphanumeric): xx.XXX.xxx/XXXX-xx — e.g., 12.ABC.345/01DE-35
• Validation: Módulo 11 algorithm; for alphanumeric CNPJs, the numeric value of uppercase letters is derived from the ASCII table.

Alphanumeric CNPJ Support

Starting July 2026, Brazil's Receita Federal will begin issuing alphanumeric CNPJs under Normative Instruction RFB No. 2,229/2024 and Joint Technical Note No. 2025.001. The new format retains the 14-character length, with the first 12 positions being alphanumeric (letters A–Z and digits 0–9) and the last 2 remaining purely numeric check digits. Existing numeric CNPJs remain valid and both formats will coexist indefinitely.

This package must handle both numeric and alphanumeric CNPJ formats seamlessly.

---

Class-Based API Design

The library should expose dedicated classes (e.g., BrUtilities::CPF and BrUtilities::CNPJ) rather than plain modules or functions, providing an object-oriented interface. Example of expected usage:

cpf = BrUtilities::CPF.new('53282085796')
cpf.valid?     # => true
cpf.formatted  # => '532.820.857-96'
cpf.stripped   # => '53282085796'

BrUtilities::CPF.generate        # => random valid CPF (unformatted)
BrUtilities::CPF.generate(true)  # => random valid CPF (formatted)

cnpj = BrUtilities::CNPJ.new('12ABC34501DE35')
cnpj.valid?     # => true
cnpj.formatted  # => '12.ABC.345/01DE-35'
cnpj.stripped   # => '12ABC34501DE35'

BrUtilities::CNPJ.generate        # => random valid CNPJ (unformatted)
BrUtilities::CNPJ.generate(true)  # => random valid CNPJ (formatted)

---

Acceptance Criteria

• BrUtilities::CPF class with #valid?, #formatted, #stripped instance methods and .generate class method.
• BrUtilities::CNPJ class with #valid?, #formatted, #stripped instance methods and .generate class method.
• Validation correctly implements the módulo 11 algorithm for CPF.
• Validation correctly implements the módulo 11 algorithm for CNPJ, supporting both numeric and alphanumeric formats.
• Formatting applies the correct mask for numeric and alphanumeric CNPJs.
• Generator produces statistically random, mathematically valid numbers.
• Full unit test coverage for all public methods, including edge cases (all-same-digit inputs, invalid inputs, alphanumeric CNPJ).

[juliolmuller]

@coderabbitai, elaborate the description for this task.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
gh issue view 12 --repo LacusSolutions/br-utils-rb --json title,body,labels,assignees,comments

Length of output: 809

---

🏁 Script executed:

#!/bin/bash
# Get repo overview and existing structure
gh repo view LacusSolutions/br-utils-rb --json description,repositoryTopics
gh issue list --repo LacusSolutions/br-utils-rb --json number,title,labels,state
gh issue view 12 --repo LacusSolutions/br-utils-rb --json milestone
tree -L 3 2>/dev/null || find . -maxdepth 3 -not -path '*/.git/*' | sort

Length of output: 4395

---

🏁 Script executed:

#!/bin/bash
gh issue edit 12 --repo LacusSolutions/br-utils-rb --body "## Overview

Implement the \`br-utilities\` package as a **class-based Ruby library** to handle two key Brazilian taxpayer identification documents:

- **CPF** (*Cadastro de Pessoas Físicas*) — the individual taxpayer registry number issued by the Brazilian Federal Revenue Service (Receita Federal).
- **CNPJ** (*Cadastro Nacional da Pessoa Jurídica*) — the national registry number for legal entities, also managed by the Receita Federal.

---

## Features

The package must provide the following capabilities for both **CPF** and **CNPJ**:

| Feature      | Description                                                                 |
|--------------|-----------------------------------------------------------------------------|
| **Format**   | Apply the canonical mask to a raw number string (e.g., \`12345678000195\` → \`12.345.678/0001-95\`). |
| **Generate** | Produce a random, valid CPF or CNPJ number (optionally formatted).         |
| **Validate** | Check whether a given number is mathematically valid using the *módulo 11* algorithm. |

---

## Document Specifications

### CPF
- **Length:** 11 digits
- **Formatted mask:** \`xxx.xxx.xxx-xx\` (last 2 digits are check digits)
- **Validation:** *Módulo 11* algorithm applied twice to compute the two check digits.

### CNPJ
- **Length:** 14 characters
- **Formatted mask (numeric):** \`xx.xxx.xxx/xxxx-xx\`
- **Formatted mask (alphanumeric):** \`xx.XXX.xxx/XXXX-xx\` — e.g., \`12.ABC.345/01DE-35\`
- **Validation:** *Módulo 11* algorithm; for alphanumeric CNPJs, the numeric value of uppercase letters is derived from the ASCII table.

#### Alphanumeric CNPJ Support
Starting **July 2026**, Brazil's Receita Federal will begin issuing alphanumeric CNPJs under *Normative Instruction RFB No. 2,229/2024* and *Joint Technical Note No. 2025.001*. The new format retains the 14-character length, with the first 12 positions being alphanumeric (letters A–Z and digits 0–9) and the last 2 remaining purely numeric check digits. Existing numeric CNPJs remain valid and both formats will coexist indefinitely.

This package must handle **both** numeric and alphanumeric CNPJ formats seamlessly.

---

## Class-Based API Design

The library should expose dedicated classes (e.g., \`BrUtilities::CPF\` and \`BrUtilities::CNPJ\`) rather than plain modules or functions, providing an object-oriented interface. Example of expected usage:

\`\`\`ruby
cpf = BrUtilities::CPF.new('53282085796')
cpf.valid?     # => true
cpf.formatted  # => '532.820.857-96'
cpf.stripped   # => '53282085796'

BrUtilities::CPF.generate        # => random valid CPF (unformatted)
BrUtilities::CPF.generate(true)  # => random valid CPF (formatted)

cnpj = BrUtilities::CNPJ.new('12ABC34501DE35')
cnpj.valid?     # => true
cnpj.formatted  # => '12.ABC.345/01DE-35'
cnpj.stripped   # => '12ABC34501DE35'

BrUtilities::CNPJ.generate        # => random valid CNPJ (unformatted)
BrUtilities::CNPJ.generate(true)  # => random valid CNPJ (formatted)
\`\`\`

---

## Acceptance Criteria

- [ ] \`BrUtilities::CPF\` class with \`#valid?\`, \`#formatted\`, \`#stripped\` instance methods and \`.generate\` class method.
- [ ] \`BrUtilities::CNPJ\` class with \`#valid?\`, \`#formatted\`, \`#stripped\` instance methods and \`.generate\` class method.
- [ ] Validation correctly implements the *módulo 11* algorithm for CPF.
- [ ] Validation correctly implements the *módulo 11* algorithm for CNPJ, supporting **both** numeric and alphanumeric formats.
- [ ] Formatting applies the correct mask for numeric and alphanumeric CNPJs.
- [ ] Generator produces statistically random, mathematically valid numbers.
- [ ] Full unit test coverage for all public methods, including edge cases (all-same-digit inputs, invalid inputs, alphanumeric CNPJ).
"

Length of output: 55

---

@juliolmuller, I've updated the description for issue #12. Here's a summary of what was added:

• Overview — explains the purpose of the br-utilities gem and the two documents it covers (CPF and CNPJ).
• Features table — describes the three capabilities: format, generate, and validate.
• Document specifications — details the format masks, lengths, and validation algorithm (módulo 11) for both CPF and CNPJ, including a dedicated section on alphanumeric CNPJ support (the new format being rolled out by Receita Federal starting July 2026).
• Class-based API design — illustrates the expected OOP interface using BrUtilities::CPF and BrUtilities::CNPJ with sample Ruby code.
• Acceptance criteria — a checklist covering both classes, validation algorithms, formatting masks, the generator, and unit test coverage (including edge cases like all-same-digit inputs and alphanumeric CNPJ).

You can view the updated issue at #12.