[cpf-val] Create package to validate CPF

[juliolmuller]

Resolves #10

Summary by CodeRabbit

• New Features
  • Added CPF validation for 11-digit Brazilian CPFs with plain, formatted, and Array<String> inputs.
  • Added a public cpf_val helper alongside the OO validator API; invalid CPF data returns false.
  • Introduced public input type predicates (CpfInput, CnpjInput) with accept?/===, plus structured type mismatch errors.
• Documentation
  • Added comprehensive English and Portuguese docs for the CPF validation utility (v1.0.0) and updated export sections for CPF/CNPJ formatter/validator packages.
• Tests
  • Expanded RSpec coverage for helpers, validators, type predicates, and error behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 169b18ae-cd0f-43d8-9203-378e837ebe30

📥 Commits

Reviewing files that changed from the base of the PR and between 50e47fd and 9d98a9c.

📒 Files selected for processing (8)

• packages/cnpj-fmt/README.md
• packages/cnpj-fmt/README.pt.md
• packages/cnpj-val/README.md
• packages/cnpj-val/README.pt.md
• packages/cpf-fmt/README.md
• packages/cpf-fmt/README.pt.md
• packages/cpf-val/README.md
• packages/cpf-val/README.pt.md

---

📝 Walkthrough

Walkthrough

Introduces the cpf-val Ruby gem with class-based and functional CPF validation, typed misuse errors, check-digit delegation, public API wiring, comprehensive tests, bilingual documentation, and 1.0.0 metadata. Related formatter and validator packages gain runtime input predicates.

Changes

CPF validation package

Layer / File(s)	Summary
CPF contracts and validation packages/cpf-val/src/cpf-val/types.rb, packages/cpf-val/src/cpf-val/errors.rb, packages/cpf-val/src/cpf-val/cpf_validator.rb, packages/cpf-val/tests/*	Adds accepted input predicates, typed mismatch errors, normalization, length and check-digit validation, repeated-digit rejection, and comprehensive coverage.
Public entrypoints and API wiring packages/cpf-val/src/cpf-val.rb, packages/cpf-val/src/cpf-val/cpf_val.rb, packages/cpf-val/tests/cpf_val.spec.rb	Wires internal files, adds CpfVal.cpf_val, removes the previous hello helper, and verifies the exported API.
Package metadata and documentation packages/cpf-val/README*, packages/cpf-val/CHANGELOG.md, packages/cpf-val/cpf-val.gemspec	Adds bilingual usage documentation, release notes, gem metadata, Ruby requirements, and source URI metadata.

Shared input predicates

Layer / File(s)	Summary
CPF formatter input predicate packages/cpf-fmt/src/*, packages/cpf-fmt/tests/*, packages/cpf-fmt/README*	Replaces the placeholder input constant with accept? and ===, routes conversion through the predicate, and documents and tests it.
CNPJ formatter input predicate packages/cnpj-fmt/src/*, packages/cnpj-fmt/tests/*, packages/cnpj-fmt/README*	Adds runtime CNPJ input checks, integrates them into conversion, and documents and tests the public predicate.
CNPJ validator input predicate packages/cnpj-val/src/*, packages/cnpj-val/tests/*, packages/cnpj-val/README*	Adds the CNPJ predicate module, uses it during validator conversion, and updates related API documentation and tests.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Possibly related issues

• LacusSolutions/br-utils-java#7 — Covers the corresponding CPF validation package behavior.
• LacusSolutions/br-utils-java#12 — Relates to CPF check-digit delegation through cpf-dv.

Possibly related PRs

• LacusSolutions/br-utils-ruby#21 — Directly relates to the check-digit API and error handling used by CpfValidator.

Suggested labels: enhancement

Poem

A rabbit checks each CPF with care,
Strips dots and dashes from the air.
Digits hop, errors stay tame,
Check digits guard the validator’s name.
Stable code takes flight tonight!

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR also changes cpf-fmt, cnpj-fmt, and cnpj-val docs/code, which are unrelated to the cpf-val package request.	Remove or split the cpf-fmt, cnpj-fmt, and cnpj-val changes into separate PRs unless they are intentionally part of this issue.
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% 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 concise and accurately summarizes the main change: adding the cpf-val package for CPF validation.
Linked Issues check	✅ Passed	The PR implements the requested class-based cpf-val package and validation API described in issue #10.

✨ Finishing Touches

🧪 Generate unit tests (beta)

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

---

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: 4

🤖 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-val/README.md`:
- Around line 155-163: The documented TypeMismatchError messages must match the
exact message asserted by cpf_val.spec.rb. Update the examples at
packages/cpf-val/README.md lines 155-163 and packages/cpf-val/README.pt.md lines
142-150 to use that exact message in their respective documentation examples.
- Around line 150-152: Complete the public error hierarchy and rescue guidance
in packages/cpf-val/README.md (lines 150-152 and 176-190) and
packages/cpf-val/README.pt.md (lines 137-139 and 163-177): document each error’s
full native inheritance chain and explicit CpfVal::Error inclusion, and add the
DomainError rescue case or explicitly state that the package defines no domain
errors; keep the English and Portuguese sections consistent.

In `@packages/cpf-val/src/cpf-val/types.rb`:
- Line 14: Update the public CpfInput definition in CpfVal so it no longer uses
the overly broad Object alias; remove it or replace it with a predicate that
matches the validator’s accepted Array<String> contract, ensuring numeric inputs
are rejected consistently with CpfValidator#is_valid.

In `@packages/cpf-val/tests/cpf_val.spec.rb`:
- Around line 55-87: Add a regression example in the public-types context that
calls described_class.cpf_val with a non-String/Array input such as 123 and
asserts it raises described_class::TypeMismatchError. Keep the existing
valid/invalid helper behavior and error-class coverage unchanged.

🪄 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

Run ID: 1fa46a94-ff1a-44d8-a391-d38f95130c3c

📥 Commits

Reviewing files that changed from the base of the PR and between 5df03f3 and 0b24140.

📒 Files selected for processing (12)

• packages/cpf-val/CHANGELOG.md
• packages/cpf-val/README.md
• packages/cpf-val/README.pt.md
• packages/cpf-val/cpf-val.gemspec
• packages/cpf-val/src/cpf-val.rb
• packages/cpf-val/src/cpf-val/cpf_val.rb
• packages/cpf-val/src/cpf-val/cpf_validator.rb
• packages/cpf-val/src/cpf-val/errors.rb
• packages/cpf-val/src/cpf-val/types.rb
• packages/cpf-val/tests/cpf_val.spec.rb
• packages/cpf-val/tests/cpf_validator.spec.rb
• packages/cpf-val/tests/errors.spec.rb

[coderabbitai]

Actionable comments posted: 3

🤖 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-fmt/README.md`:
- Line 425: Update the predicate examples to use fully qualified names: in
packages/cpf-fmt/README.md lines 425-425, use CpfFmt::CpfInput.accept? and
CpfFmt::CpfInput ===; in packages/cnpj-fmt/README.md lines 434-434 and
packages/cnpj-fmt/README.pt.md lines 419-419, use CnpjFmt::CnpjInput.accept? and
CnpjFmt::CnpjInput ===.

In `@packages/cpf-val/README.md`:
- Around line 127-133: The error hierarchy documentation is incomplete in both
README language versions. Update the TypeMismatchError summary in
packages/cpf-val/README.md:127-133 and packages/cpf-val/README.pt.md:114-120 to
show CpfVal::TypeMismatchError < TypeError < StandardError and explicitly
include CpfVal::Error, keeping the surrounding leaf-section content consistent
in each language.
- Around line 179-194: The rescue-granularity examples are incomplete and make
narrower handlers unreachable. In packages/cpf-val/README.md lines 179-194,
create separate standalone begin/rescue/end examples using CpfVal.cpf_val(123),
covering native TypeError, CpfVal::Error, and CpfVal::TypeMismatchError; retain
CpfVal::DomainError as explicitly not applicable. Mirror the same independently
scoped executable examples in packages/cpf-val/README.pt.md lines 166-182,
translated into Portuguese.

🪄 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

Run ID: 86db9afd-1eef-4523-8006-b45bfab05040

📥 Commits

Reviewing files that changed from the base of the PR and between 0b24140 and 50e47fd.

📒 Files selected for processing (24)

• packages/cnpj-fmt/README.md
• packages/cnpj-fmt/README.pt.md
• packages/cnpj-fmt/src/cnpj-fmt.rb
• packages/cnpj-fmt/src/cnpj-fmt/types.rb
• packages/cnpj-fmt/src/cnpj-fmt/utils.rb
• packages/cnpj-fmt/tests/cnpj_fmt.spec.rb
• packages/cnpj-val/README.md
• packages/cnpj-val/README.pt.md
• packages/cnpj-val/src/cnpj-val.rb
• packages/cnpj-val/src/cnpj-val/cnpj_validator.rb
• packages/cnpj-val/src/cnpj-val/types.rb
• packages/cnpj-val/tests/cnpj_val.spec.rb
• packages/cpf-fmt/README.md
• packages/cpf-fmt/README.pt.md
• packages/cpf-fmt/src/cpf-fmt.rb
• packages/cpf-fmt/src/cpf-fmt/types.rb
• packages/cpf-fmt/src/cpf-fmt/utils.rb
• packages/cpf-fmt/tests/cpf_fmt.spec.rb
• packages/cpf-val/README.md
• packages/cpf-val/README.pt.md
• packages/cpf-val/src/cpf-val.rb
• packages/cpf-val/src/cpf-val/cpf_validator.rb
• packages/cpf-val/src/cpf-val/types.rb
• packages/cpf-val/tests/cpf_val.spec.rb