Adapt CNPJ generation and validation to alphanumeric format

[potatowski]

Description

Brazil’s Federal Revenue Service (Receita Federal) announced that, starting July 2026, the CNPJ (business ID) will support letters as well as numbers (alphanumeric format).
Official references:

• Official statement - gov.br news

Our brazilcode package currently generates and validates only numeric CNPJs (14 digits). We must evolve the API well before the deadline to ensure forward compatibility and offer a smooth migration path for library consumers.

Goals

1. Define canonical format

   • Align with the official spec (total length, reserved positions, checksum rules).
   • Document clear valid & invalid examples.

2. Update generation function

   • Allow optional alphanumeric output via a flag (e.g., WithAlphanum: true).
   • Keep purely numeric generation as the default until 2026‑07‑01 for backward compatibility.

3. Update validation function

   • Accept alphanumeric sequences per the new rules.
   • Return granular errors: ErrInvalidChar, ErrChecksumMismatch, etc.

4. Add detection helper

   • Provide IsAlphanumericCNPJ(s string) bool to help consumer code branch during migration.

5. Testing coverage

   • Success & failure cases for numeric, alphanumeric, and malformed inputs.
   • Benchmarks comparing old vs. new performance.

6. Docs & README

   • Refresh GoDoc comments and README examples to showcase the new format.
   • Include a timeline note: “Alphanumeric format becomes official on 1 July 2026”.

7. CI / Linters

   • Extend the pipeline to run tests for alphanumeric CNPJs.
   • Ensure 100 % coverage on critical validation paths.

Acceptance Criteria

• Generation and validation fully support both numeric and alphanumeric rules.
• Test suite covers ≥ 95 % of newly added lines.
• Changelog and migration guide are published.

Expected Impact

Proactively supporting the upcoming alphanumeric CNPJ format ensures applications relying on brazilcode remain functional when the legal change goes live, avoiding last‑minute disruptions and rework.