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

[juliolmuller]

Resolves #11

Summary by CodeRabbit

• New Features
  • Introduced a unified CPF utility (CpfUtils) to format, generate, and validate CPFs via a shared default instance.
  • Added facade shortcuts/aliases for formatter, generator, and validator, plus clearer API-misuse errors.
• Documentation
  • Added comprehensive English and Portuguese README for CpfUtils, including usage and error handling; added a 1.0.0 “stable release” changelog entry.
  • Clarified CnpjUtils::DEFAULT as a mutable, process-wide singleton and updated related documentation wording.
• Tests
  • Added an extensive RSpec suite for CpfUtils and removed the old placeholder coverage.
• Chores
  • Updated gem/dependency declarations and simplified Gemfile usage.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

The PR replaces the placeholder CpfUtils module with a class-based facade for CPF formatting, generation, and validation. It adds component re-exports, configurable instances, default helpers, structured errors, dependency cleanup, extensive RSpec coverage, and English/Portuguese documentation. It also clarifies CnpjUtils::DEFAULT singleton behavior.

CPF utilities facade

Layer / File(s)	Summary
Facade contracts and component exports packages/cpf-utilities/src/cpf-utilities*, packages/cpf-utilities/Gemfile, packages/br-utilities/Gemfile	CpfUtils becomes a class, defines facade-specific errors, loads component packages, and re-exports their public constants.
Configuration and unified operations packages/cpf-utilities/src/cpf-utilities/cpf_utils.rb	Component settings support instances, option objects, hashes, or defaults; facade methods delegate formatting, generation, and validation through configured components and DEFAULT.
Facade behavior verification packages/cpf-utilities/tests/cpf_utils.spec.rb	RSpec coverage validates initialization, setters, delegation, option handling, aliases, errors, CPF fixtures, and package smoke behavior.
Public API documentation and release notes packages/cpf-utilities/README*, packages/cpf-utilities/CHANGELOG.md, packages/cpf-utilities/cpf-utilities.gemspec	Documentation and metadata describe the facade API, exports, options, errors, dependencies, and 1.0.0 release.
CNPJ default singleton documentation packages/cnpj-utilities/README*, packages/cnpj-utilities/src/cnpj-utilities/cnpj_utils.rb, packages/cnpj-utilities/CHANGELOG.md, packages/cnpj-utilities/tests/cnpj_utils.spec.rb	CNPJ documentation and smoke tests clarify mutable, process-wide DEFAULT behavior and class-helper sharing.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related issues

• LacusSolutions/br-utils-py#40 — Describes the corresponding CpfUtils facade, re-exports, default instance, tests, and documentation.
• LacusSolutions/br-utils-java#8 — Covers a related CPF utility package providing formatting, generation, and validation.

Possibly related PRs

• LacusSolutions/br-utils-ruby#22 — Provides the formatter API that this facade loads and re-exports.
• LacusSolutions/br-utils-ruby#24 — Provides the validator API integrated by this facade.

Poem

A rabbit hops through CPF lines,
Formatting digits into signs.
It generates, checks, and knows,
With aliases neatly tucked in rows.
“One facade!” the bunny cheers—
Docs and tests now bloom like ears.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR also changes cnpj-utilities docs/tests, which are unrelated to the cpf-utilities package requested in #11.	Remove the cnpj-utilities changes or split them into a separate PR focused on that package.
Docstring Coverage	⚠️ Warning	Docstring coverage is 45.83% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is related to creating the CPF utilities package, but it has a typo and is slightly unclear.
Linked Issues check	✅ Passed	The PR implements the class-based cpf-utilities package with format, generate, and validate APIs as requested in #11.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/cpf-utilities

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 10

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/cpf-utilities/README.md`:
- Around line 329-360: Replace the commented CpfUtils::DomainError/NameError
examples in packages/cpf-utilities/README.md lines 329-360 with a standalone
rescue example using an actual bundled package DomainError or leaf error. Add
the equivalent Portuguese example in packages/cpf-utilities/README.pt.md lines
314-344, keeping both examples consistent with the real component error API and
existing rescue-granularity guidance.
- Around line 385-391: The propagated-error references are incomplete in both
documentation files. Update packages/cpf-utilities/README.md lines 385-391 and
packages/cpf-utilities/README.pt.md lines 370-376 to document every propagated
leaf and callback-delivered error with its inheritance, category, trigger,
example, and rescue guidance; provide equivalent Portuguese content in the
latter file while preserving the existing Validation false-return and formatting
on_fail behavior.
- Around line 261-266: Align both error tables with the API contract: in
packages/cpf-utilities/README.md lines 261-266 and
packages/cpf-utilities/README.pt.md lines 248-251, alphabetize the misuse
entries and distinguish constructor Hash settings from per-call option
instances; in packages/cpf-utilities/README.md lines 304-308 and
packages/cpf-utilities/README.pt.md lines 289-293, correct the
InvalidArgumentCombinationError trigger description to reflect the actual
combination of settings/options and keyword arguments.

In `@packages/cpf-utilities/src/cpf-utilities.rb`:
- Around line 23-28: Declare CpfUtils as a class in version.rb, keeping VERSION
defined on that class, so it can be safely reopened regardless of require order.
Remove the CpfUtils module-to-class promotion logic from cpf-utilities.rb,
including the VERSION capture and remove_const flow.

In `@packages/cpf-utilities/src/cpf-utilities/cpf_utils.rb`:
- Around line 344-348: Update the documentation for the mutable
CpfUtils::DEFAULT singleton to state that its configuration is process-wide and
shared across threads, so mutations can affect concurrent callers. Advise
threaded or isolated work to use CpfUtils.new or per-call options instead.
- Around line 338-342: Update the RuboCop directives surrounding the is_valid
method to use the pinned version’s supported Naming/PredicateName cop instead of
Naming/PredicatePrefix, preserving suppression of the public API’s predicate
naming offense.
- Around line 102-114: Reject unrecognized keywords instead of silently
discarding them in both formatting and constructor settings flows. Add an
ensure_known_keywords! validation call in resolve_settings using SETTINGS_KEYS,
and update the compact_keyword_overrides/Helpers.compact_settings paths as
needed so unknown keys such as hiden or formater raise at the call site while
recognized options retain their current behavior.
- Around line 75-100: Update resolve_formatter, resolve_generator, and
resolve_validator so their duck-typed fallback returns the injected object only
when it responds to the delegated method: format, generate, or is_valid
respectively. Otherwise raise the existing TypeMismatchError used by CpfUtils,
while preserving the nil, concrete-class, and supported-options handling.

In `@packages/cpf-utilities/tests/cpf_utils.spec.rb`:
- Around line 1251-1301: Add smoke examples in the `describe 'package smoke'`
block that verify `described_class` is a `Class`, can be instantiated with
`described_class.new`, and retains a string `VERSION` matching semantic-version
digits. Use aggregate failures for the class and instantiation assertions, and
leave the existing formatting, generation, and validation coverage unchanged.
- Around line 245-247: Update the CpfValidatorOptions assertion in the “does not
expose CpfValidatorOptions” example to call const_defined? with ancestor lookup
disabled, so it checks only constants defined directly on CpfUtils and remains
unaffected by top-level constants.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ecf03c24-d134-461b-a7b2-7eceecc0d8d1

📥 Commits

Reviewing files that changed from the base of the PR and between cea7d8c and 4b4359b.

📒 Files selected for processing (15)

• packages/br-utilities/Gemfile
• packages/cpf-utilities/CHANGELOG.md
• packages/cpf-utilities/Gemfile
• packages/cpf-utilities/README.md
• packages/cpf-utilities/README.pt.md
• packages/cpf-utilities/cpf-utilities.gemspec
• packages/cpf-utilities/src/cpf-utilities.rb
• packages/cpf-utilities/src/cpf-utilities/cpf_fmt.rb
• packages/cpf-utilities/src/cpf-utilities/cpf_gen.rb
• packages/cpf-utilities/src/cpf-utilities/cpf_utils.rb
• packages/cpf-utilities/src/cpf-utilities/cpf_val.rb
• packages/cpf-utilities/src/cpf-utilities/errors.rb
• packages/cpf-utilities/src/cpf-utilities/version.rb
• packages/cpf-utilities/tests/cpf_utilities.spec.rb
• packages/cpf-utilities/tests/cpf_utils.spec.rb

💤 Files with no reviewable changes (3)

• packages/cpf-utilities/tests/cpf_utilities.spec.rb
• packages/cpf-utilities/Gemfile
• packages/br-utilities/Gemfile

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/cpf-utilities/README.md`:
- Around line 392-402: The propagated-error summary tables in
packages/cpf-utilities/README.md lines 392-402 and
packages/cpf-utilities/README.pt.md lines 377-387 must use identical ordering:
place every API-misuse error before every domain error, sorting entries
alphabetically by error name within each category; update both tables
consistently.
- Around line 404-420: The propagated error inheritance chains in
packages/cpf-utilities/README.md lines 404-420 and
packages/cpf-utilities/README.pt.md lines 389-404 are incomplete. Update both
references for CpfFmt::DomainError and CpfFmt::TypeMismatchError to include the
native StandardError link while retaining each package Error marker and the
existing inheritance relationships.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5b7ad473-5043-438d-8742-1aaaeaaa1b3d

📥 Commits

Reviewing files that changed from the base of the PR and between 4b4359b and d9b44f4.

📒 Files selected for processing (5)

• packages/cpf-utilities/CHANGELOG.md
• packages/cpf-utilities/README.md
• packages/cpf-utilities/README.pt.md
• packages/cpf-utilities/src/cpf-utilities.rb
• packages/cpf-utilities/src/cpf-utilities/version.rb

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/cpf-utilities/README.md`:
- Around line 399-401: Complete the inheritance and marker documentation for
every domain-error leaf in packages/cpf-utilities/README.md lines 399-401 and
packages/cpf-utilities/README.pt.md lines 384-386. Update each English and
Portuguese table entry to show the full chain from the leaf through its package
DomainError to RangeError and StandardError, and include the corresponding
package marker (CpfFmt::Error or CpfGen::Error).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 15e8ca47-a3fd-4a8f-95fc-32b96d8b6e10

📥 Commits

Reviewing files that changed from the base of the PR and between d9b44f4 and c30aaeb.

📒 Files selected for processing (10)

• packages/cnpj-utilities/CHANGELOG.md
• packages/cnpj-utilities/README.md
• packages/cnpj-utilities/README.pt.md
• packages/cnpj-utilities/src/cnpj-utilities/cnpj_utils.rb
• packages/cnpj-utilities/tests/cnpj_utils.spec.rb
• packages/cpf-utilities/CHANGELOG.md
• packages/cpf-utilities/README.md
• packages/cpf-utilities/README.pt.md
• packages/cpf-utilities/src/cpf-utilities/cpf_utils.rb
• packages/cpf-utilities/tests/cpf_utils.spec.rb

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/cpf-utilities/README.md (1)

404-415: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

issue (blocking): Complete the required examples for public DomainError ancestors.

• packages/cpf-utilities/README.md#L404-L415,529-L540: Add concrete formatter and generator calls that raise descendant errors.
• packages/cpf-utilities/README.pt.md#L389-L400,514-L525: Add the equivalent Portuguese examples.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/cpf-utilities/README.md` around lines 404 - 415, Complete the public
DomainError ancestor examples by adding concrete formatter and generator calls
that raise descendant errors in packages/cpf-utilities/README.md ranges 404-415
and 529-540, and add equivalent Portuguese examples in
packages/cpf-utilities/README.pt.md ranges 389-400 and 514-525. Use the
documented descendant types, including OutOfRangeError, ValidationError, and
InvalidLengthError where applicable.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@packages/cpf-utilities/README.md`:
- Around line 404-415: Complete the public DomainError ancestor examples by
adding concrete formatter and generator calls that raise descendant errors in
packages/cpf-utilities/README.md ranges 404-415 and 529-540, and add equivalent
Portuguese examples in packages/cpf-utilities/README.pt.md ranges 389-400 and
514-525. Use the documented descendant types, including OutOfRangeError,
ValidationError, and InvalidLengthError where applicable.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: bc8a1628-8196-4920-a5ed-72cbf329fffe

📥 Commits

Reviewing files that changed from the base of the PR and between c30aaeb and 216ab13.

📒 Files selected for processing (3)

• packages/cpf-utilities/CHANGELOG.md
• packages/cpf-utilities/README.md
• packages/cpf-utilities/README.pt.md