Implement package `cnpj-fmt`

[juliolmuller]

Overview

Implement the cnpj-fmt Ruby gem — a class-based utility for formatting and parsing CNPJ strings, fully compatible with both the traditional numeric and the upcoming alphanumeric CNPJ formats.

Background

The current CNPJ structure is purely numerical, following the format 99.999.999/9999-99 with check digits for validation. Brazil's Tax Reform introduces an alphanumeric CNPJ format, replacing the purely numeric model while keeping the same 14-character length. Under the new format, the first 12 characters of the CNPJ include letters and numbers; the last two characters remain numeric check digits. This update is effective from July 2026, and existing CNPJs containing numeric characters only will continue to be valid and recognized.

Goals

• Implement a class-based interface within the CnpjFmt module that exposes methods to format and parse CNPJ strings.
• Apply the standard CNPJ mask: XX.XXX.XXX/XXXX-XX.
• Strip the mask from a formatted CNPJ, returning only the raw alphanumeric characters.
• Accept both numeric-only (legacy) and alphanumeric (new format) CNPJs as valid inputs.
• Follow the same conventions already adopted by sibling packages in this monorepo (e.g. cpf-fmt).

Expected API (tentative)

# Apply mask
CnpjFmt.format('11222333000181')   # => '11.222.333/0001-81'
CnpjFmt.format('11ABC3330001DE')   # => '11.ABC.333/0001-DE'

# Strip mask
CnpjFmt.unformat('11.222.333/0001-81')  # => '11222333000181'
CnpjFmt.unformat('11.ABC.333/0001-DE')  # => '11ABC3330001DE'

Acceptance Criteria

• CnpjFmt.format(cnpj) returns the CNPJ string with the XX.XXX.XXX/XXXX-XX mask applied.
• CnpjFmt.unformat(cnpj) returns the raw CNPJ string with all punctuation removed.
• Both methods handle numeric-only and alphanumeric CNPJs (uppercase letters A–Z).
• Unit tests cover formatting and unformatting for both CNPJ variants (numeric and alphanumeric).
• The gem version is set to 0.1.0 upon first functional release.
• The gemspec summary and description are updated to reflect the actual functionality.

References

• Receita Federal – Technical Note COCAD/SUARA/RFB nº 49/2024
• Instrução Normativa RFB nº 2.229/2024
• Sibling package: packages/cpf-fmt

[juliolmuller]

@coderabbitai, elaborate the description for this task.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

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

Length of output: 776

---

🏁 Script executed:

#!/bin/bash
# Explore the repository structure
tree -L 3

Length of output: 1563

---

🏁 Script executed:

#!/bin/bash
echo "=== cpf-fmt gemspec ==="
cat packages/cpf-fmt/cpf-fmt.gemspec

echo ""
echo "=== cpf-fmt src ==="
find packages/cpf-fmt/src -type f | sort | xargs -I{} sh -c 'echo "--- {} ---"; cat "{}"'

echo ""
echo "=== cpf-fmt test ==="
find packages/cpf-fmt/test -type f | sort | xargs -I{} sh -c 'echo "--- {} ---"; cat "{}"'

echo ""
echo "=== cnpj-fmt gemspec ==="
cat packages/cnpj-fmt/cnpj-fmt.gemspec

echo ""
echo "=== cnpj-fmt src ==="
find packages/cnpj-fmt/src -type f | sort | xargs -I{} sh -c 'echo "--- {} ---"; cat "{}"'

echo ""
echo "=== cnpj-fmt test ==="
find packages/cnpj-fmt/test -type f | sort | xargs -I{} sh -c 'echo "--- {} ---"; cat "{}"'

echo ""
echo "=== cnpj-dv src ==="
find packages/cnpj-dv/src -type f | sort | xargs -I{} sh -c 'echo "--- {} ---"; cat "{}"'

echo ""
echo "=== cnpj-val src ==="
find packages/cnpj-val/src -type f | sort | xargs -I{} sh -c 'echo "--- {} ---"; cat "{}"'

Length of output: 3194

---

🏁 Script executed:

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

Implement the \`cnpj-fmt\` Ruby gem — a class-based utility for **formatting and parsing CNPJ strings**, fully compatible with both the traditional numeric and the upcoming alphanumeric CNPJ formats.

## Background

The current CNPJ structure is purely numerical, following the format \`99.999.999/9999-99\` with check digits for validation. Brazil's Tax Reform introduces an alphanumeric CNPJ format, replacing the purely numeric model while keeping the same 14-character length. Under the new format, the first 12 characters of the CNPJ include letters and numbers; the last two characters remain numeric check digits. This update is effective from July 2026, and existing CNPJs containing numeric characters only will continue to be valid and recognized.

## Goals

- Implement a **class-based interface** within the \`CnpjFmt\` module that exposes methods to format and parse CNPJ strings.
- Apply the standard CNPJ mask: \`XX.XXX.XXX/XXXX-XX\`.
- Strip the mask from a formatted CNPJ, returning only the raw alphanumeric characters.
- Accept both numeric-only (legacy) and alphanumeric (new format) CNPJs as valid inputs.
- Follow the same conventions already adopted by sibling packages in this monorepo (e.g. \`cpf-fmt\`).

## Expected API (tentative)

\`\`\`ruby
# Apply mask
CnpjFmt.format('11222333000181')   # => '11.222.333/0001-81'
CnpjFmt.format('11ABC3330001DE')   # => '11.ABC.333/0001-DE'

# Strip mask
CnpjFmt.unformat('11.222.333/0001-81')  # => '11222333000181'
CnpjFmt.unformat('11.ABC.333/0001-DE')  # => '11ABC3330001DE'
\`\`\`

## Acceptance Criteria

- [ ] \`CnpjFmt.format(cnpj)\` returns the CNPJ string with the \`XX.XXX.XXX/XXXX-XX\` mask applied.
- [ ] \`CnpjFmt.unformat(cnpj)\` returns the raw CNPJ string with all punctuation removed.
- [ ] Both methods handle numeric-only and alphanumeric CNPJs (uppercase letters A–Z).
- [ ] Unit tests cover formatting and unformatting for both CNPJ variants (numeric and alphanumeric).
- [ ] The gem version is set to \`0.1.0\` upon first functional release.
- [ ] The \`gemspec\` summary and description are updated to reflect the actual functionality.

## References

- [Receita Federal – Technical Note COCAD/SUARA/RFB nº 49/2024](https://www.gov.br/receitafederal/)
- [Instrução Normativa RFB nº 2.229/2024](https://www.in.gov.br/)
- Sibling package: \`packages/cpf-fmt\`"

Length of output: 54

---

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

• Overview — clarifies the gem's purpose as a class-based formatter/parser for CNPJ strings.
• Background — explains the traditional numeric CNPJ format (99.999.999/9999-99) and the upcoming alphanumeric CNPJ format (effective July 2026), noting that the first 12 characters may include letters while the last 2 check digits remain numeric.
• Goals — outlines the expected responsibilities: applying/stripping the XX.XXX.XXX/XXXX-XX mask, handling both numeric-only and alphanumeric CNPJs, and following the same conventions used by sibling packages like cpf-fmt.
• Expected API — provides a tentative Ruby interface with CnpjFmt.format and CnpjFmt.unformat examples for both CNPJ variants.
• Acceptance Criteria — a checklist covering both methods, alphanumeric support, unit tests, versioning (0.1.0), and gemspec update.
• References — links to Receita Federal's normative instructions and the sibling packages/cpf-fmt package.

You can view the updated issue at: #3