[cnpj-utils] Create package to consolidate itilities for CNPJ

AGENTS.md

@@ -378,3 +378,31 @@ Before finishing any task that adds, changes, or documents errors:
 10. A summary table exists with the required columns and ordering, listing only defined failure modes.
 11. A rescue-granularity section exists with the four levels above, using real library classes.
 12. No docs mention `rescue Exception` or inheriting from `Exception` directly.
+
+---
+
+## Aggregator package re-exports
+
+Applies to aggregator gems such as `*-utilities` and `br-utilities` that load component packages and expose a unified façade.
+
+### Shape
+
+- One re-export file per component under `src/<agg-pkg>/<component_snake>.rb` (e.g. `src/cnpj-utilities/cnpj_fmt.rb`).
+- Nest the full sibling module on the façade: `<Utils>::CnpjFmt = ::CnpjFmt` (same-object assignment only — no wrappers).
+- Root shortcuts only for the three (or package-appropriate) **main classes** (e.g. `<Utils>::CnpjFormatter = CnpjFmt::CnpjFormatter`).
+- Options, helpers, errors, and types stay under the nested module — **not** aliased at the `<Utils>` root.
+- Root sibling modules (`CnpjFmt`, `CnpjGen`, `CnpjVal`, …) remain supported unchanged.
+- Require the re-export files from the aggregator entrypoint **after** class/module promotion and **after** the façade implementation file.
+
+### Default singleton + class helpers
+
+When the façade mirrors a JS default export / Python module-level singleton:
+
+- Expose a mutable constant `<Utils>::DEFAULT = new` (UPPERCASE names a constant binding, not an immutable value — do not freeze the instance).
+- Add class-method aliases for each façade operation that forward to `DEFAULT` (e.g. `CnpjUtils.format` / `.generate` / `.is_valid`). Prefer these in end-user docs as the quick path.
+- Mutating `DEFAULT` affects subsequent class-helper calls; `CnpjUtils.new` (custom) instances stay independent.
+- Specs: helper existence, parity with `DEFAULT`, mutability coupling with restore, custom-instance independence.
+
+### Reference
+
+Shipped reference: `ruby/packages/cnpj-utilities` (`CnpjUtils::CnpjFmt` nest + `CnpjUtils::CnpjFormatter` shortcut; `DEFAULT` + class helpers).

packages/br-utilities/br-utilities.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 3.1'
   spec.metadata['source_code_uri'] = spec.homepage
   spec.metadata['rubygems_mfa_required'] = 'true'
-  spec.files         = Dir['src/**/*'] + ['LICENSE', 'README.md'].select { |f| File.file?(f) }
+  spec.files         = Dir['src/**/*'] + ['LICENSE', 'README.md', 'README.pt.md', 'CHANGELOG.md']
   spec.require_paths = ['src']
   spec.add_dependency 'cnpj-utilities', '>= 0'
   spec.add_dependency 'cpf-utilities', '>= 0'

packages/cnpj-dv/README.md

@@ -68,10 +68,10 @@ require 'cnpj-dv'
 
 check_digits = CnpjDV::CnpjCheckDigits.new('914157320007')
 
-check_digits.first   # => '9'
-check_digits.second  # => '3'
-check_digits.both    # => '93'
-check_digits.cnpj    # => '91415732000793'
+check_digits.first    # => '9'
+check_digits.second   # => '3'
+check_digits.both     # => '93'
+check_digits.cnpj     # => '91415732000793'
 ```
 
 With alphanumeric CNPJ (new format):
@@ -81,10 +81,10 @@ require 'cnpj-dv'
 
 check_digits = CnpjDV::CnpjCheckDigits.new('MGKGMJ9X0001')
 
-check_digits.first   # => '6'
-check_digits.second  # => '8'
-check_digits.both    # => '68'
-check_digits.cnpj    # => 'MGKGMJ9X000168'
+check_digits.first    # => '6'
+check_digits.second   # => '8'
+check_digits.both     # => '68'
+check_digits.cnpj     # => 'MGKGMJ9X000168'
 ```
 
 
@@ -178,7 +178,7 @@ rescue CnpjDV::DomainError
 - **Example:**
 
 ```ruby
-CnpjDV::CnpjCheckDigits.new(12_345_678_000_100) # raises CnpjDV::TypeMismatchError
+CnpjDV::CnpjCheckDigits.new(12_345_678_000_100)   # raises CnpjDV::TypeMismatchError
 ```
 
 - **How to rescue it:**
@@ -199,7 +199,7 @@ rescue TypeError
 - **Example:**
 
 ```ruby
-CnpjDV::CnpjCheckDigits.new('12345678901') # raises CnpjDV::InvalidLengthError
+CnpjDV::CnpjCheckDigits.new('12345678901')   # raises CnpjDV::InvalidLengthError
 ```
 
 - **How to rescue it:**
@@ -220,7 +220,7 @@ rescue CnpjDV::DomainError
 - **Example:**
 
 ```ruby
-CnpjDV::CnpjCheckDigits.new('000000000001') # raises CnpjDV::ValidationError
+CnpjDV::CnpjCheckDigits.new('000000000001')   # raises CnpjDV::ValidationError
 ```
 
 - **How to rescue it:**

packages/cnpj-dv/README.pt.md

@@ -45,10 +45,10 @@ require 'cnpj-dv'
 
 check_digits = CnpjDV::CnpjCheckDigits.new('914157320007')
 
-check_digits.first   # => '9'
-check_digits.second  # => '3'
-check_digits.both    # => '93'
-check_digits.cnpj    # => '91415732000793'
+check_digits.first    # => '9'
+check_digits.second   # => '3'
+check_digits.both     # => '93'
+check_digits.cnpj     # => '91415732000793'
 ```
 
 Com CNPJ alfanumérico (novo formato):
@@ -58,10 +58,10 @@ require 'cnpj-dv'
 
 check_digits = CnpjDV::CnpjCheckDigits.new('MGKGMJ9X0001')
 
-check_digits.first   # => '6'
-check_digits.second  # => '8'
-check_digits.both    # => '68'
-check_digits.cnpj    # => 'MGKGMJ9X000168'
+check_digits.first    # => '6'
+check_digits.second   # => '8'
+check_digits.both     # => '68'
+check_digits.cnpj     # => 'MGKGMJ9X000168'
 ```
 
 ## Utilização
@@ -149,7 +149,7 @@ rescue CnpjDV::DomainError
 - **Exemplo:**
 
 ```ruby
-CnpjDV::CnpjCheckDigits.new(12_345_678_000_100) # levanta CnpjDV::TypeMismatchError
+CnpjDV::CnpjCheckDigits.new(12_345_678_000_100)   # levanta CnpjDV::TypeMismatchError
 ```
 
 - **Como resgatar:**
@@ -170,7 +170,7 @@ rescue TypeError
 - **Exemplo:**
 
 ```ruby
-CnpjDV::CnpjCheckDigits.new('12345678901') # levanta CnpjDV::InvalidLengthError
+CnpjDV::CnpjCheckDigits.new('12345678901')   # levanta CnpjDV::InvalidLengthError
 ```
 
 - **Como resgatar:**

packages/cnpj-fmt/README.md

@@ -70,9 +70,9 @@ require 'cnpj-fmt'
 
 cnpj = '03603568000195'
 
-CnpjFmt.cnpj_fmt(cnpj)                    # => "03.603.568/0001-95"
-CnpjFmt.cnpj_fmt(cnpj, hidden: true)      # => "03.603.***/****-**"
-CnpjFmt.cnpj_fmt(                         # => "03603568|0001_95"
+CnpjFmt.cnpj_fmt(cnpj)                 # => "03.603.568/0001-95"
+CnpjFmt.cnpj_fmt(cnpj, hidden: true)   # => "03.603.***/****-**"
+CnpjFmt.cnpj_fmt(                      # => "03603568|0001_95"
   cnpj,
   dot_key: '',
   slash_key: '|',
@@ -119,15 +119,15 @@ require 'cnpj-fmt'
 
 cnpj = '03603568000195'
 
-CnpjFmt.cnpj_fmt(cnpj)                # => "03.603.568/0001-95"
-CnpjFmt.cnpj_fmt(cnpj, hidden: true)  # masked with defaults
-CnpjFmt.cnpj_fmt(                     # => "03603568|0001_95"
+CnpjFmt.cnpj_fmt(cnpj)                 # => "03.603.568/0001-95"
+CnpjFmt.cnpj_fmt(cnpj, hidden: true)   # masked with defaults
+CnpjFmt.cnpj_fmt(                      # => "03603568|0001_95"
   cnpj,
   dot_key: '',
   slash_key: '|',
   dash_key: '_'
 )
-CnpjFmt.cnpj_fmt(cnpj, {              # Hash form
+CnpjFmt.cnpj_fmt(cnpj, {               # Hash form
   hidden: true,
   hidden_key: '#'
 })
@@ -159,9 +159,9 @@ require 'cnpj-fmt'
 formatter = CnpjFmt::CnpjFormatter.new(hidden: true)
 cnpj = '03603568000195'
 
-formatter.format(cnpj)                 # uses instance masking
-formatter.format(cnpj, hidden: false)  # this call only: unmasked
-formatter.format(cnpj)                 # back to instance defaults
+formatter.format(cnpj)                  # uses instance masking
+formatter.format(cnpj, hidden: false)   # this call only: unmasked
+formatter.format(cnpj)                  # back to instance defaults
 ```
 
 Alphanumeric input and array input:
@@ -283,7 +283,7 @@ rescue CnpjFmt::DomainError
 - **Example:**
 
 ```ruby
-CnpjFmt::CnpjFormatter.new.format(12_345) # raises CnpjFmt::TypeMismatchError
+CnpjFmt::CnpjFormatter.new.format(12_345)   # raises CnpjFmt::TypeMismatchError
 ```
 
 - **How to rescue it:**
@@ -307,10 +307,10 @@ rescue TypeError
 CnpjFmt::CnpjFormatter.new.format(
   'short',
   on_fail: ->(_value, error) {
-    error # => #<CnpjFmt::InvalidLengthError ...> (a DomainError)
+    error   # => #<CnpjFmt::InvalidLengthError ...> (a DomainError)
     'invalid'
   }
-) # => "invalid"
+)   # => "invalid"
 
 ```
 
@@ -358,7 +358,7 @@ rescue ArgumentError
 - **Example:**
 
 ```ruby
-CnpjFmt::CnpjFormatterOptions.new(hidden_start: 14) # raises CnpjFmt::OutOfRangeError
+CnpjFmt::CnpjFormatterOptions.new(hidden_start: 14)   # raises CnpjFmt::OutOfRangeError
 ```
 
 - **How to rescue it:**
@@ -379,7 +379,7 @@ rescue CnpjFmt::DomainError
 - **Example:**
 
 ```ruby
-CnpjFmt::CnpjFormatterOptions.new(dot_key: 'å') # raises CnpjFmt::ValidationError
+CnpjFmt::CnpjFormatterOptions.new(dot_key: 'å')   # raises CnpjFmt::ValidationError
 ```
 
 - **How to rescue it:**

packages/cnpj-fmt/README.pt.md

@@ -57,9 +57,9 @@ require 'cnpj-fmt'
 
 cnpj = '03603568000195'
 
-CnpjFmt.cnpj_fmt(cnpj)                    # => "03.603.568/0001-95"
-CnpjFmt.cnpj_fmt(cnpj, hidden: true)      # => "03.603.***/****-**"
-CnpjFmt.cnpj_fmt(                         # => "03603568|0001_95"
+CnpjFmt.cnpj_fmt(cnpj)                 # => "03.603.568/0001-95"
+CnpjFmt.cnpj_fmt(cnpj, hidden: true)   # => "03.603.***/****-**"
+CnpjFmt.cnpj_fmt(                      # => "03603568|0001_95"
   cnpj,
   dot_key: '',
   slash_key: '|',
@@ -106,15 +106,15 @@ require 'cnpj-fmt'
 
 cnpj = '03603568000195'
 
-CnpjFmt.cnpj_fmt(cnpj)                # => "03.603.568/0001-95"
+CnpjFmt.cnpj_fmt(cnpj)                 # => "03.603.568/0001-95"
 CnpjFmt.cnpj_fmt(cnpj, hidden: true)   # mascarado com padrões
-CnpjFmt.cnpj_fmt(                     # => "03603568|0001_95"
+CnpjFmt.cnpj_fmt(                      # => "03603568|0001_95"
   cnpj,
   dot_key: '',
   slash_key: '|',
   dash_key: '_'
 )
-CnpjFmt.cnpj_fmt(cnpj, {              # forma com Hash
+CnpjFmt.cnpj_fmt(cnpj, {               # forma com Hash
   hidden: true,
   hidden_key: '#'
 })
@@ -146,9 +146,9 @@ require 'cnpj-fmt'
 formatter = CnpjFmt::CnpjFormatter.new(hidden: true)
 cnpj = '03603568000195'
 
-formatter.format(cnpj)                 # usa mascaramento da instância
-formatter.format(cnpj, hidden: false)  # só nesta chamada: sem máscara
-formatter.format(cnpj)                 # volta aos padrões da instância
+formatter.format(cnpj)                  # usa mascaramento da instância
+formatter.format(cnpj, hidden: false)   # só nesta chamada: sem máscara
+formatter.format(cnpj)                  # volta aos padrões da instância
 ```
 
 Entrada alfanumérica e array:
@@ -159,7 +159,7 @@ require 'cnpj-fmt'
 formatter = CnpjFmt::CnpjFormatter.new
 
 formatter.format('RK0CMT3W000100')   # => "RK.0CM.T3W/0001-00"
-formatter.format([                     # => "RK.0CM.T3W/0001-00"
+formatter.format([                   # => "RK.0CM.T3W/0001-00"
   'RK',
   '0CM',
   'T3W',
@@ -270,7 +270,7 @@ rescue CnpjFmt::DomainError
 - **Exemplo:**
 
 ```ruby
-CnpjFmt::CnpjFormatter.new.format(12_345) # levanta CnpjFmt::TypeMismatchError
+CnpjFmt::CnpjFormatter.new.format(12_345)   # levanta CnpjFmt::TypeMismatchError
 ```
 
 - **Como resgatar:**
@@ -294,10 +294,10 @@ rescue TypeError
 CnpjFmt::CnpjFormatter.new.format(
   'short',
   on_fail: ->(_value, error) {
-    error # => #<CnpjFmt::InvalidLengthError ...> (um DomainError)
+    error   # => #<CnpjFmt::InvalidLengthError ...> (um DomainError)
     'invalid'
   }
-) # => "invalid"
+)   # => "invalid"
 ```
 
 - **Como resgatar:** Trate dentro do `on_fail` (caso típico), ou resgate se você o reerguer:
@@ -344,7 +344,7 @@ rescue ArgumentError
 - **Exemplo:**
 
 ```ruby
-CnpjFmt::CnpjFormatterOptions.new(hidden_start: 14) # levanta CnpjFmt::OutOfRangeError
+CnpjFmt::CnpjFormatterOptions.new(hidden_start: 14)   # levanta CnpjFmt::OutOfRangeError
 ```
 
 - **Como resgatar:**
@@ -365,7 +365,7 @@ rescue CnpjFmt::DomainError
 - **Exemplo:**
 
 ```ruby
-CnpjFmt::CnpjFormatterOptions.new(dot_key: 'å') # levanta CnpjFmt::ValidationError
+CnpjFmt::CnpjFormatterOptions.new(dot_key: 'å')   # levanta CnpjFmt::ValidationError
 ```
 
 - **Como resgatar:**