feat: add support for alphanumeric CNPJ

[edywladson]

🆕 Adiciona suporte ao CNPJ Alfanumérico

📋 Resumo

Implementa suporte ao novo formato de CNPJ alfanumérico conforme documentação oficial da Receita Federal, mantendo total retrocompatibilidade com o formato numérico atual.

🎯 Motivação

A Receita Federal anunciou a implementação do CNPJ alfanumérico a partir de julho de 2026, permitindo o uso de letras (A-Z) e números (0-9) nas 14 posições principais do CNPJ. Esta implementação prepara a biblioteca para suportar ambos os formatos.

✨ Principais Mudanças

🔧 Funcionalidades Implementadas

• Suporte a CNPJ Alfanumérico: Aceita letras (A-Z) e números (0-9)
• Detecção Automática de Formato: Identifica automaticamente se é numérico ou alfanumérico
• Validação Atualizada: Regex e algoritmos de validação para ambos os formatos
• Geração de CNPJs: Função específica para gerar CNPJs alfanuméricos válidos
• Retrocompatibilidade: Todas as funções existentes continuam funcionando

📦 Novas Funções

// Gera CNPJ alfanumérico válido
generateAlphanumeric(): string

// Verifica se contém letras (formato alfanumérico)
isAlphanumericCnpj(cnpj: string): boolean

// Verifica se contém apenas números (formato atual)
isNumericCnpj(cnpj: string): boolean

// Remove caracteres especiais e converte para maiúsculas
cleanCnpj(cnpj: string): string

// Converte caractere para valor numérico (ASCII - 48)
charToCnpjValue(char: string): number

// Valida formato alfanumérico
isValidFormat(cnpj: string): boolean

// Valida formato numérico
isValidNumericFormat(cnpj: string): boolean

// Valida checksum alfanumérico
isValidAlphanumericChecksum(cnpj: string): boolean

🔄 Funções Atualizadas

• isValid(): Agora suporta ambos os formatos automaticamente
• format(): Suporta formatação de CNPJs alfanuméricos
• isValidFormat(): Regex atualizado para aceitar letras e números

📊 Constantes Adicionadas

// Caracteres válidos para CNPJ alfanumérico
VALID_CNPJ_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'

// Regex para formato alfanumérico
CNPJ_FORMAT_REGEX = /^[0-9A-Z]{2}\.?[0-9A-Z]{3}\.?[0-9A-Z]{3}\/?[0-9A-Z]{4}-?[0-9]{2}$/

// Regex para formato numérico
NUMERIC_CNPJ_REGEX = /^\d{2}\.?\d{3}\.?\d{3}\/?\d{4}-?\d{2}$/

🧪 Testes

✅ Testes Implementados

• 41 novos testes para funcionalidades alfanuméricas
• Cobertura completa das novas funções
• Testes de validação para ambos os formatos
• Testes de geração de CNPJs alfanuméricos
• Testes de formatação com caracteres especiais
• Testes de conversão ASCII para valores numéricos

📈 Cobertura de Testes

Test Suites: 45 passed, 45 total
Tests:       312 passed, 312 total

🔍 Exemplo de Uso

import { 
  generate, 
  generateAlphanumeric, 
  isValid, 
  format,
  isAlphanumericCnpj,
  isNumericCnpj 
} from '@brazilian-utils/brazilian-utils';

// Gerar CNPJs
const numericCnpj = generate();           // "12345678000195"
const alphanumericCnpj = generateAlphanumeric(); // "AB1C2D3E4F5G6"

// Validar CNPJs
console.log(isValid(numericCnpj));        // true
console.log(isValid(alphanumericCnpj));   // true

// Verificar formato
console.log(isNumericCnpj(numericCnpj));        // true
console.log(isAlphanumericCnpj(alphanumericCnpj)); // true

// Formatar
console.log(format(numericCnpj));         // "12.345.678/0001-95"
console.log(format(alphanumericCnpj));    // "AB.1C2.D3E/4F5G-35"

🎯 Cálculo do Dígito Verificador

O cálculo do DV para CNPJs alfanuméricos segue o algoritmo módulo 11:

1. Cada caractere é convertido para seu valor ASCII
2. Subtrai-se 48 do valor ASCII
3. Multiplica-se pelo peso correspondente
4. Soma-se todos os valores
5. Aplica-se módulo 11
6. Calcula-se o DV: 11 - (módulo) (se < 2, DV = 0)

Exemplo de Cálculo

Para o CNPJ 12.ABC.345/01DE-35:

Caracteres: 1, 2, A, B, C, 3, 4, 5, 0, 1, D, E
Valores:    1, 2, 17, 18, 19, 3, 4, 5, 0, 1, 20, 21
Pesos:      5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2

🔒 Compatibilidade

✅ Retrocompatibilidade Total

• CNPJs numéricos existentes continuam válidos
• Todas as funções existentes funcionam sem mudanças
• Não há breaking changes

🔄 Coexistência de Formatos

• Ambos os formatos podem ser usados simultaneamente
• Detecção automática do formato
• Validação específica para cada tipo

📅 Cronograma de Implementação

• Julho/2026: Implementação oficial pela Receita Federal
• Atual: Biblioteca preparada para suportar ambos os formatos

📋 Checklist

• Implementação do CNPJ alfanumérico
• Detecção automática de formato
• Validação de formato alfanumérico
• Cálculo de DV usando valores ASCII
• Retrocompatibilidade com CNPJ numérico
• Limpeza e formatação de CNPJs
• Geração de CNPJs alfanuméricos
• Testes automatizados

🎉 Resultado

A biblioteca agora está preparada para suportar o novo formato de CNPJ alfanumérico da Receita Federal, mantendo total compatibilidade com o formato atual e oferecendo uma API intuitiva para trabalhar com ambos os formatos.

---

Referência: Documentação oficial da Receita Federal - CNPJ Alfanumérico

[hyanmandian]

Hey @edywladson agradeco imensamente a contribuicao! Poderia fazer um PR pra branch de refactor que estamos trabalhando, o nome eh v1-refactor?

Desculpa nao ter avisado ou pontuado algo antes, mas comecei a trabalhar num refactor da lib pensando em deixa-la mais facil de manter e mais convidativa a novos contribuidores