[cpf-utils] Create package to consolidate itilities for CPF

packages/br-utilities/Gemfile

@@ -5,10 +5,7 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'cnpj-utilities', path: '../cnpj-utilities'
-gem 'cpf-fmt', path: '../cpf-fmt'
-gem 'cpf-gen', path: '../cpf-gen'
 gem 'cpf-utilities', path: '../cpf-utilities'
-gem 'cpf-val', path: '../cpf-val'
 
 group :test do
   gem 'rake', '~> 13.2'

packages/cnpj-utilities/CHANGELOG.md

@@ -8,7 +8,7 @@ Unified toolkit to deal with CNPJ (Brazilian legal entity ID): formatting, gener
 
 - **Unified façade**: `CnpjUtils` delegates `#format`, `#generate`, and `#is_valid` to `cnpj-fmt`, `cnpj-gen`, and `cnpj-val`.
 - **Alphanumeric CNPJ**: full support for the [14-character alphanumeric CNPJ](https://www.gov.br/receitafederal/pt-br/assuntos/noticias/2023/julho/cnpj-alfa-numerico); generate with `type` `"numeric"`, `"alphabetic"`, or `"alphanumeric"`.
-- **Quick helpers**: `CnpjUtils.format` / `.generate` / `.is_valid` alias mutable `CnpjUtils::DEFAULT`.
+- **Quick helpers**: `CnpjUtils.format` / `.generate` / `.is_valid` alias mutable `CnpjUtils::DEFAULT` (process-wide; prefer `CnpjUtils.new` / per-call options under concurrency).
 - **Two-tier re-exports**: `CnpjUtils::CnpjFormatter` / `CnpjGenerator` / `CnpjValidator` at the façade root; full sibling surface under `CnpjUtils::CnpjFmt` / `CnpjGen` / `CnpjVal`.
 - **Configurable components**: constructor and setters accept component instances, `*Options`, `Hash`, or `nil`; accessors expose `formatter`, `generator`, and `validator`.
 - **Per-call overrides**: `#format`, `#generate`, and `#is_valid` accept an options `Hash`/instance or keyword overrides (not both).

packages/cnpj-utilities/README.md

@@ -87,7 +87,7 @@ CnpjUtils.is_valid('98765432000199')       # => false
 You can work in these equivalent ways:
 
 1. **`CnpjUtils.format` / `.generate` / `.is_valid`** — class helpers for quick one-off calls (forward to `DEFAULT`).
-2. **`CnpjUtils::DEFAULT`** — mutable shared singleton (same object the class helpers use).
+2. **`CnpjUtils::DEFAULT`** — mutable shared singleton (same object the class helpers use; process-wide / not thread-isolated).
 3. **`CnpjUtils.new`** — configurable instance with shared defaults across format, generate, and validate.
 4. **Main classes under `CnpjUtils`** — `CnpjUtils::CnpjFormatter`, `CnpjUtils::CnpjGenerator`, `CnpjUtils::CnpjValidator`.
 5. **Nested package modules** — Options, helpers, errors, and types via `CnpjUtils::CnpjFmt` / `CnpjGen` / `CnpjVal` (e.g. `CnpjUtils::CnpjFmt::CnpjFormatterOptions`, `CnpjUtils::CnpjFmt.cnpj_fmt`).
@@ -145,7 +145,7 @@ CnpjUtils.is_valid('98765432000198')
 
 ### `CnpjUtils::DEFAULT` (default instance)
 
-`CnpjUtils::DEFAULT` is the pre-built, **mutable** singleton behind the class helpers (parity with the JS default export / Python `cnpj_utils`). Mutating it affects subsequent `CnpjUtils.format` / `.generate` / `.is_valid` calls; custom `CnpjUtils.new` instances stay independent:
+`CnpjUtils::DEFAULT` is the pre-built, **mutable** singleton behind the class helpers (parity with the JS default export / Python `cnpj_utils`). Its configuration is **process-wide and shared across threads**: mutating it (e.g. `DEFAULT.formatter = …`) affects subsequent `CnpjUtils.format` / `.generate` / `.is_valid` calls for every caller in the process. Prefer `CnpjUtils.new` or per-call options for concurrent or isolated work; custom instances stay independent of `DEFAULT`:
 
 ```ruby
 CnpjUtils::DEFAULT.formatter = { slash_key: '|' }
@@ -265,7 +265,7 @@ After `require 'cnpj-utilities'`:
 
 - **`CnpjUtils`**: Façade class to create a utils instance with optional default formatter, generator, and validator settings.
 - **`CnpjUtils.format` / `.generate` / `.is_valid`**: Class helpers that forward to `CnpjUtils::DEFAULT`.
-- **`CnpjUtils::DEFAULT`**: Mutable pre-built `CnpjUtils` instance (same object the class helpers use).
+- **`CnpjUtils::DEFAULT`**: Mutable pre-built `CnpjUtils` instance (same object the class helpers use). Process-wide / shared across threads — prefer `CnpjUtils.new` or per-call options under concurrency.
 - **`CnpjUtils::VERSION`**: Gem version string.
 - **Main-class shortcuts**: `CnpjUtils::CnpjFormatter`, `CnpjUtils::CnpjGenerator`, `CnpjUtils::CnpjValidator` (same objects as the sibling classes).
 - **Nested package modules**: `CnpjUtils::CnpjFmt`, `CnpjUtils::CnpjGen`, `CnpjUtils::CnpjVal` — full sibling surface (Options, helpers, errors, types). Options/helpers/errors are **not** aliased at the `CnpjUtils` root.
@@ -285,8 +285,8 @@ Errors defined by this gem are **API misuse** only (wrong type or invalid argume
 
 | Class | Inherits from | Category | Trigger condition |
 |-------|---------------|----------|-------------------|
-| `CnpjUtils::TypeMismatchError` | `CnpjUtils::TypeMismatchError < TypeError < StandardError` (+ `include CnpjUtils::Error`) | API misuse | Non-`nil` `settings` argument to `CnpjUtils.new` is not a `Hash` |
 | `CnpjUtils::InvalidArgumentCombinationError` | `CnpjUtils::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CnpjUtils::Error`) | API misuse | Non-`nil` settings/options `Hash` (or options instance) passed together with any non-`nil` keyword argument |
+| `CnpjUtils::TypeMismatchError` | `CnpjUtils::TypeMismatchError < TypeError < StandardError` (+ `include CnpjUtils::Error`) | API misuse | Non-`nil` `settings` argument to `CnpjUtils.new` is not a `Hash` |
 
 ##### `CnpjUtils::Error` (marker module)
 

packages/cnpj-utilities/README.pt.md

@@ -72,7 +72,7 @@ CnpjUtils.is_valid('98765432000199')       # => false
 Você pode trabalhar destas formas equivalentes:
 
 1. **`CnpjUtils.format` / `.generate` / `.is_valid`** — helpers de classe para chamadas rápidas (encaminham para `DEFAULT`).
-2. **`CnpjUtils::DEFAULT`** — singleton compartilhado mutável (o mesmo objeto usado pelos helpers de classe).
+2. **`CnpjUtils::DEFAULT`** — singleton compartilhado mutável (o mesmo objeto usado pelos helpers de classe; em todo o processo / não isolado por thread).
 3. **`CnpjUtils.new`** — instância configurável com padrões compartilhados entre formatar, gerar e validar.
 4. **Classes principais sob `CnpjUtils`** — `CnpjUtils::CnpjFormatter`, `CnpjUtils::CnpjGenerator`, `CnpjUtils::CnpjValidator`.
 5. **Módulos aninhados do pacote** — Options, helpers, erros e tipos via `CnpjUtils::CnpjFmt` / `CnpjGen` / `CnpjVal` (ex.: `CnpjUtils::CnpjFmt::CnpjFormatterOptions`, `CnpjUtils::CnpjFmt.cnpj_fmt`).
@@ -130,7 +130,7 @@ CnpjUtils.is_valid('98765432000198')
 
 ### `CnpjUtils::DEFAULT` (instância padrão)
 
-`CnpjUtils::DEFAULT` é o singleton pré-construído e **mutável** por trás dos helpers de classe (paridade com o export padrão do JS / `cnpj_utils` do Python). Mutá-lo afeta chamadas seguintes a `CnpjUtils.format` / `.generate` / `.is_valid`; instâncias `CnpjUtils.new` personalizadas permanecem independentes:
+`CnpjUtils::DEFAULT` é o singleton pré-construído e **mutável** por trás dos helpers de classe (paridade com o export padrão do JS / `cnpj_utils` do Python). A configuração é **em todo o processo e compartilhada entre threads**: mutá-lo (ex.: `DEFAULT.formatter = …`) afeta chamadas seguintes a `CnpjUtils.format` / `.generate` / `.is_valid` para todos os chamadores no processo. Prefira `CnpjUtils.new` ou opções por chamada para trabalho concorrente ou isolado; instâncias personalizadas permanecem independentes de `DEFAULT`:
 
 ```ruby
 CnpjUtils::DEFAULT.formatter = { slash_key: '|' }
@@ -250,7 +250,7 @@ Após `require 'cnpj-utilities'`:
 
 - **`CnpjUtils`**: Classe fachada para criar uma instância com configurações padrão opcionais de formatador, gerador e validador.
 - **`CnpjUtils.format` / `.generate` / `.is_valid`**: Helpers de classe que encaminham para `CnpjUtils::DEFAULT`.
-- **`CnpjUtils::DEFAULT`**: Instância pré-construída mutável de `CnpjUtils` (o mesmo objeto usado pelos helpers de classe).
+- **`CnpjUtils::DEFAULT`**: Instância pré-construída mutável de `CnpjUtils` (o mesmo objeto usado pelos helpers de classe). Em todo o processo / compartilhada entre threads — prefira `CnpjUtils.new` ou opções por chamada sob concorrência.
 - **`CnpjUtils::VERSION`**: String da versão da gem.
 - **Atalhos das classes principais**: `CnpjUtils::CnpjFormatter`, `CnpjUtils::CnpjGenerator`, `CnpjUtils::CnpjValidator` (os mesmos objetos das classes irmãs).
 - **Módulos aninhados do pacote**: `CnpjUtils::CnpjFmt`, `CnpjUtils::CnpjGen`, `CnpjUtils::CnpjVal` — superfície completa do irmão (Options, helpers, erros, tipos). Options/helpers/erros **não** são aliasados na raiz de `CnpjUtils`.
@@ -270,8 +270,8 @@ Os erros definidos por esta gem são apenas de **uso indevido da API** (tipo inc
 
 | Classe | Herda de | Categoria | Condição de disparo |
 |--------|----------|-----------|---------------------|
-| `CnpjUtils::TypeMismatchError` | `CnpjUtils::TypeMismatchError < TypeError < StandardError` (+ `include CnpjUtils::Error`) | Uso indevido da API | Argumento `settings` não-`nil` de `CnpjUtils.new` não é um `Hash` |
 | `CnpjUtils::InvalidArgumentCombinationError` | `CnpjUtils::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CnpjUtils::Error`) | Uso indevido da API | `Hash`/instância de settings/options não-`nil` passado junto com qualquer argumento nomeado não-`nil` |
+| `CnpjUtils::TypeMismatchError` | `CnpjUtils::TypeMismatchError < TypeError < StandardError` (+ `include CnpjUtils::Error`) | Uso indevido da API | Argumento `settings` não-`nil` de `CnpjUtils.new` não é um `Hash` |
 
 ##### `CnpjUtils::Error` (módulo marcador)
 

packages/cnpj-utilities/src/cnpj-utilities/cnpj_utils.rb

@@ -15,7 +15,8 @@
 #
 # - {CnpjUtils.format}, {CnpjUtils.generate}, {CnpjUtils.is_valid} — class helpers
 #   that alias {CnpjUtils::DEFAULT} (preferred quick path)
-# - {CnpjUtils::DEFAULT} — mutable shared singleton (JS/Python parity)
+# - {CnpjUtils::DEFAULT} — mutable process-wide singleton (JS/Python parity; not
+#   thread-isolated — prefer {.new} / per-call options under concurrency)
 # - {CnpjUtils#format}, {CnpjUtils#generate}, {CnpjUtils#is_valid} — instance API
 # - {CnpjUtils::VERSION}
 # - {CnpjUtils::InvalidArgumentCombinationError} (API misuse)
@@ -25,7 +26,9 @@
 # {CnpjGen}, and {CnpjVal} remain loadable after +require 'cnpj-utilities'+.
 #
 # Mutating {CnpjUtils::DEFAULT} (e.g. via setters) affects subsequent class-helper
-# calls. Custom {CnpjUtils.new} instances are independent of +DEFAULT+.
+# calls process-wide (shared across threads). Prefer {CnpjUtils.new} or per-call
+# options for concurrent or isolated work. Custom instances are independent of
+# +DEFAULT+.
 #
 # @example
 #   require 'cnpj-utilities'
@@ -372,8 +375,11 @@ def is_valid(cnpj_input, options = nil, **keywords)
 
   # Default {CnpjUtils} instance with default formatter, generator, and
   # validator options (parity with the JS default export / Python +cnpj_utils+
-  # singleton). Mutating this instance (e.g. via setters) affects subsequent
-  # {CnpjUtils.format}, {CnpjUtils.generate}, and {CnpjUtils.is_valid} calls.
+  # singleton). Configuration is process-wide and shared across threads:
+  # mutating this instance (e.g. via setters) affects subsequent
+  # {CnpjUtils.format}, {CnpjUtils.generate}, and {CnpjUtils.is_valid} calls for
+  # every caller in the process. Prefer {CnpjUtils.new} or per-call options for
+  # threaded or isolated work.
   DEFAULT = new
 
   class << self

packages/cnpj-utilities/tests/cnpj_utils.spec.rb

@@ -1044,6 +1044,17 @@ def default_validator_options_snapshot
   end
 
   describe 'package smoke' do
+    it 'is an instantiable class' do
+      aggregate_failures do
+        expect(described_class).to be_a(Class)
+        expect(described_class.new).to be_a(described_class)
+      end
+    end
+
+    it 'exposes a VERSION string' do
+      expect(described_class::VERSION).to be_a(String).and match(/\A\d+\.\d+\.\d+\z/)
+    end
+
     it 'formats through DEFAULT with a custom slash_key' do
       result = described_class::DEFAULT.format('01ABC234000X56', slash_key: '|')
 

packages/cpf-utilities/CHANGELOG.md

@@ -1 +1,18 @@
 # cpf-utilities
+
+## 1.0.0
+
+### 🚀 Stable Version Released!
+
+Unified toolkit to deal with CPF (Brazilian personal tax ID): formatting, generation, and validation. Main features:
+
+- **Unified façade**: `CpfUtils` delegates `#format`, `#generate`, and `#is_valid` to `cpf-fmt`, `cpf-gen`, and `cpf-val`.
+- **Numeric CPF**: digits-only 11-character IDs formatted as `XXX.XXX.XXX-XX` (no alphanumeric / `slash_key` / `type` options).
+- **Quick helpers**: `CpfUtils.format` / `.generate` / `.is_valid` alias mutable `CpfUtils::DEFAULT` (process-wide; prefer `CpfUtils.new` / per-call options under concurrency).
+- **Two-tier re-exports**: `CpfUtils::CpfFormatter` / `CpfGenerator` / `CpfValidator` at the façade root; full sibling surface under `CpfUtils::CpfFmt` / `CpfGen` / `CpfVal`.
+- **Configurable components**: constructor and setters accept component instances, `*Options`/`Hash` (formatter/generator), or `nil`; validator is instance/`nil`/duck-type only (no `CpfValidatorOptions`).
+- **Per-call overrides**: `#format` and `#generate` accept an options `Hash`/instance or keyword overrides (not both); `#is_valid` takes input only.
+- **Root siblings**: after `require 'cpf-utilities'`, `CpfFmt`, `CpfGen`, and `CpfVal` remain loadable (same objects as the nests).
+- **Structured errors**: façade misuse leaves plus full propagated `CpfFmt` / `CpfGen` / `CpfVal` reference in the [README](./README.md) (complete `StandardError` chains; misuse-then-domain; `on_fail` / `false`).
+
+For detailed usage and API reference, see the [README](./README.md).

packages/cpf-utilities/Gemfile

@@ -4,10 +4,6 @@ source 'https://rubygems.org'
 
 gemspec
 
-gem 'cpf-fmt', path: '../cpf-fmt'
-gem 'cpf-gen', path: '../cpf-gen'
-gem 'cpf-val', path: '../cpf-val'
-
 group :test do
   gem 'rake', '~> 13.2'
   gem 'rspec', '~> 3.13'