Implement package `cnpj-gen`

[juliolmuller]

Overview

Implement the cnpj-gen package as a class-based utility to generate valid Brazilian CNPJ numbers (Cadastro Nacional da Pessoa Jurídica), the national registration number for legal entities in Brazil.

The implementation must be compatible with both the traditional numeric CNPJ and the new alphanumeric CNPJ format being gradually introduced from July 2026, as established by the Brazilian Federal Revenue Service (Receita Federal do Brasil — RFB) through Normative Instruction No. 2.229/2024.

---

Background

Current CNPJ Format

The CNPJ is a 14-character identifier structured as follows:

XX.XXX.XXX/XXXX-DV
└────────┘ └──┘ └┘
  Root(8)  Order Check
           (4)   Digits(2)

• Root (8 chars): Identifies the legal entity (company).
• Order (4 chars): Identifies each establishment (head office or branches).
• Check Digits (2 chars): Always numeric. Calculated via the Modulo 11 algorithm.

New Alphanumeric Format (from July 2026)

The first 12 positions (root + order) will accept any combination of uppercase letters (A–Z) and digits (0–9), while the last two positions (check digits) will remain numeric. Existing numeric CNPJs are not affected and remain valid alongside the new format.

---

Generation Algorithm

Generating a valid CNPJ consists of two steps:

1. Base Generation (12 characters)

Randomly produce the 12-character base (root + order):

• Numeric mode (traditional): Use only digits 0–9.
• Alphanumeric mode (new format): Use any combination of uppercase letters A–Z and digits 0–9, ensuring at least one letter is present to distinguish it from the traditional format.

⚠️ The all-zeros base (000000000000) must be rejected, as it produces an invalid CNPJ.

2. Check Digit Calculation (Modulo 11)

Compute the two check digits from the 12-character base using the same algorithm defined in the cnpj-dv package:

1. Character-to-value conversion: Each character is converted to a numeric value:
   • Digits (0–9): face value.
   • Letters (A–Z): ASCII value − 48 (e.g., A = 65 − 48 = 17, Z = 42).
2. First check digit: Apply Modulo 11 on the 12-character base using the standard CNPJ weights.
3. Second check digit: Append the first check digit, then apply Modulo 11 on the resulting 13-character sequence.

The final CNPJ is the concatenation of the 12-character base and the 2 numeric check digits.

---

Requirements

• Create the cnpj-gen package following the existing conventions of this library.
• Implement a class (e.g., CnpjGen) that exposes a method to generate a random, valid CNPJ.
• Support generating both numeric (traditional) and alphanumeric (new format) CNPJs, selectable via a parameter or overloaded method.
• Internally delegate check digit computation to the cnpj-dv package (CnpjDv) — do not duplicate the algorithm.
• Optionally return the result as a formatted string (XX.XXX.XXX/XXXX-DV) or as a raw unformatted string, selectable by the caller.
• Throw a meaningful exception/error if an invalid generation mode or option is provided.
• Cover the implementation with unit tests including:
  • Generated numeric CNPJs are structurally valid (correct length, all-digit base, numeric check digits).
  • Generated alphanumeric CNPJs are structurally valid (correct length, at least one letter in base, numeric check digits).
  • Check digits of generated CNPJs are verified using the cnpj-dv logic.
  • Formatted output matches the expected mask (XX.XXX.XXX/XXXX-DV).
  • Repeated calls produce different results (randomness smoke test).
• Add relevant documentation (Javadoc) to public classes and methods.

---

References

• RFB Normative Instruction No. 2.229/2024
• Serpro reference implementations (Java, Python, TypeScript)
• New Brazilian CNPJ — Is Your Code Ready for the Change?
• Related: Implement package cnpj-dv (Implement package cnpj-dv #11)

[juliolmuller]

@coderabbitai, elaborate the description for this task.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

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

Length of output: 721

---

🏁 Script executed:

#!/bin/bash
# Get repo structure
tree -L 4 2>/dev/null || find . -maxdepth 4 -not -path '*/.git/*' | sort

echo "---"
# Look for existing README or docs
fd -e md -e txt -e adoc | head -20

echo "---"
# Look for existing packages/modules
fd -e java | head -40

echo "---"
# Look for existing issue `#1` or other issues for context
gh issue list --repo LacusSolutions/br-utils-java --json number,title,body --limit 10

Length of output: 4380

---

🏁 Script executed:

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

Implement the \`cnpj-gen\` package as a class-based utility to **generate valid Brazilian CNPJ numbers** (*Cadastro Nacional da Pessoa Jurídica*), the national registration number for legal entities in Brazil.

The implementation must be compatible with both the traditional **numeric CNPJ** and the new **alphanumeric CNPJ** format being gradually introduced from July 2026, as established by the Brazilian Federal Revenue Service (*Receita Federal do Brasil — RFB*) through Normative Instruction No. 2.229/2024.

---

## Background

### Current CNPJ Format
The CNPJ is a 14-character identifier structured as follows:

\`\`\`
XX.XXX.XXX/XXXX-DV
└────────┘ └──┘ └┘
  Root(8)  Order Check
           (4)   Digits(2)
\`\`\`

- **Root (8 chars):** Identifies the legal entity (company).
- **Order (4 chars):** Identifies each establishment (head office or branches).
- **Check Digits (2 chars):** Always numeric. Calculated via the **Modulo 11** algorithm.

### New Alphanumeric Format (from July 2026)
The first 12 positions (root + order) will accept any combination of uppercase letters (A–Z) and digits (0–9), while the last two positions (check digits) will **remain numeric**. Existing numeric CNPJs are not affected and remain valid alongside the new format.

---

## Generation Algorithm

Generating a valid CNPJ consists of two steps:

### 1. Base Generation (12 characters)
Randomly produce the 12-character base (root + order):
- **Numeric mode (traditional):** Use only digits \`0\`–\`9\`.
- **Alphanumeric mode (new format):** Use any combination of uppercase letters \`A\`–\`Z\` and digits \`0\`–\`9\`, ensuring at least one letter is present to distinguish it from the traditional format.

> ⚠️ The all-zeros base (\`000000000000\`) must be rejected, as it produces an invalid CNPJ.

### 2. Check Digit Calculation (Modulo 11)
Compute the two check digits from the 12-character base using the same algorithm defined in the [\`cnpj-dv\`](`#11`) package:

1. **Character-to-value conversion:** Each character is converted to a numeric value:
   - Digits (\`0\`–\`9\`): face value.
   - Letters (\`A\`–\`Z\`): \`ASCII value − 48\` (e.g., \`A\` = 65 − 48 = **17**, \`Z\` = **42**).
2. **First check digit:** Apply Modulo 11 on the 12-character base using the standard CNPJ weights.
3. **Second check digit:** Append the first check digit, then apply Modulo 11 on the resulting 13-character sequence.

The final CNPJ is the concatenation of the 12-character base and the 2 numeric check digits.

---

## Requirements

- [ ] Create the \`cnpj-gen\` package following the existing conventions of this library.
- [ ] Implement a class (e.g., \`CnpjGen\`) that exposes a method to generate a random, valid CNPJ.
- [ ] Support generating both **numeric** (traditional) and **alphanumeric** (new format) CNPJs, selectable via a parameter or overloaded method.
- [ ] Internally delegate check digit computation to the \`cnpj-dv\` package ([\`CnpjDv\`](`#11`)) — do not duplicate the algorithm.
- [ ] Optionally return the result as a **formatted string** (\`XX.XXX.XXX/XXXX-DV\`) or as a **raw unformatted string**, selectable by the caller.
- [ ] Throw a meaningful exception/error if an invalid generation mode or option is provided.
- [ ] Cover the implementation with **unit tests** including:
  - Generated numeric CNPJs are structurally valid (correct length, all-digit base, numeric check digits).
  - Generated alphanumeric CNPJs are structurally valid (correct length, at least one letter in base, numeric check digits).
  - Check digits of generated CNPJs are verified using the \`cnpj-dv\` logic.
  - Formatted output matches the expected mask (\`XX.XXX.XXX/XXXX-DV\`).
  - Repeated calls produce different results (randomness smoke test).
- [ ] Add relevant documentation (Javadoc) to public classes and methods.

---

## References

- [RFB Normative Instruction No. 2.229/2024](https://www.in.gov.br/web/dou/-/instrucao-normativa-rfb-n-2.229-de-15-de-outubro-de-2024)
- [Serpro reference implementations (Java, Python, TypeScript)](https://www.serpro.gov.br/)
- [New Brazilian CNPJ — Is Your Code Ready for the Change?](https://tiagoporto.com/en/blog/new-brazilian-cnpj-is-your-code-ready-for-the-change/)
- Related: Implement package \`cnpj-dv\` (`#11`)"

Length of output: 56

---

@juliolmuller, I've updated the description for issue #2 — Implement package cnpj-gen. Here's a summary of what was added, following the same structure as issue #11 (cnpj-dv):

• Overview — describes the goal: generating valid CNPJ numbers compatible with both the traditional numeric format and the new alphanumeric format (July 2026+).
• Background — explains the CNPJ structure (Root + Order + Check Digits) and the upcoming alphanumeric format from RFB Normative Instruction No. 2.229/2024.
• Generation Algorithm — details the two steps:
  1. Random base generation (12 chars) in either numeric or alphanumeric mode, with a guard against the all-zeros edge case.
  2. Check digit computation via Modulo 11 (delegated to cnpj-dv / #11 — no duplication).
• Requirements checklist — covers the class implementation (CnpjGen), mode selection (numeric vs. alphanumeric), optional formatted output (XX.XXX.XXX/XXXX-DV), unit tests, and Javadoc.
• References — links to the RFB normative instruction, Serpro, and the related cnpj-dv issue (#11).