[cpf-gen] Create package to generate valid CPF

[juliolmuller]

Summary by CodeRabbit

• New Features
  • Added CPF generation via CpfGen.cpf_gen, with numeric or masked output, optional prefixes, and keyword/option configuration.
  • Includes prefix validation, structured CPF-specific errors, and automatic retry when check-digit computation needs a fresh attempt.
• Documentation
  • Expanded English and Portuguese guides and added a documented stable 1.0.0 release for CPF generation.
  • Clarified “options vs non-nil keywords” argument rules for CPF/CNPJ formatting and validation helpers.
• Compatibility
  • Tightened CPF check-digit dependency version ranges and removed local gem path wiring.

[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: 66327b79-d4d9-4d1b-b4ac-b33e5759f2bd

📥 Commits

Reviewing files that changed from the base of the PR and between e044835 and 5a4a8d3.

📒 Files selected for processing (10)

• packages/cnpj-fmt/README.md
• packages/cnpj-fmt/README.pt.md
• packages/cnpj-gen/README.md
• packages/cnpj-gen/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-gen/README.md
• packages/cpf-gen/README.pt.md

---

📝 Walkthrough

Walkthrough

The PR replaces the cpf-gen stub with a configurable CPF generator, adds option resolution and validation errors, introduces CPF formatting and retry behavior, adds comprehensive RSpec coverage and bilingual documentation, and constrains cpf-dv dependencies across related gems.

Changes

CPF generator release

Layer / File(s)	Summary
Public packaging and documentation packages/cpf-gen/README*, packages/cpf-gen/CHANGELOG.md, packages/*/Gemfile, packages/cpf-gen/cpf-gen.gemspec, packages/cpf-val/cpf-val.gemspec, packages/{cnpj-fmt,cnpj-gen,cnpj-val,cpf-fmt}/README*	Updates gem metadata and bounded cpf-dv requirements, removes redundant local Gemfile entries, and documents generator and argument-combination behavior.
Options, validation, and errors packages/cpf-gen/src/cpf-gen/{types.rb,errors.rb,cpf_generator_options.rb,utils.rb}, packages/cpf-gen/tests/{errors,utils,cpf_generator_options}.spec.rb	Adds typed option inputs, layered resolution, prefix sanitization and validation, boolean normalization, CPF formatting, custom errors, and tests.
CPF generation flow packages/cpf-gen/src/cpf-gen.rb, packages/cpf-gen/src/cpf-gen/{cpf_gen.rb,cpf_generator.rb}, packages/cpf-gen/tests/{cpf_gen,cpf_generator}.spec.rb	Adds public helper and generator APIs that build CPF values, compute check digits, apply formatting, reject ambiguous arguments, and retry after domain failures.

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

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant CpfGen
  participant CpfGenerator
  participant CpfDV
  Caller->>CpfGen: cpf_gen(options, keywords)
  CpfGen->>CpfGenerator: initialize and generate
  CpfGenerator->>CpfGenerator: resolve options and build base CPF
  CpfGenerator->>CpfDV: compute check digits
  CpfDV-->>CpfGenerator: check digits or DomainError
  CpfGenerator-->>Caller: CPF result
  CpfGenerator->>CpfGenerator: retry after DomainError

Loading

Possibly related issues

• Issue 11 — Implements the CPF utilities package dependencies and generator functionality.
• Issue 9 — Adds the requested cpf-gen generator class, APIs, documentation, dependencies, and tests.
• Java issue 6 — Implements the corresponding class-based CPF generator package.

Possibly related PRs

• LacusSolutions/br-utils-ruby#20 — Documents the same options-versus-keywords argument-combination behavior.
• LacusSolutions/br-utils-ruby#21 — Provides the CpfDV::CpfCheckDigits API and domain-error behavior used by this generator.

Poem

A rabbit reviews each CPF with delight,
Digits hop neatly from morning to night.
Prefixes are washed, check digits align,
Errors wear badges in a tidy design.
Retry paws dance when calculations fail—
A fluffy release leaves a polished trail!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 43.24% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: introducing the cpf-gen package for generating valid CPF values.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

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

---

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: 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-gen/README.md`:
- Line 1: Add a top-level H1 before the cover image in
packages/cpf-gen/README.md and use “cpf-gen” as its title; make the
corresponding change in packages/cpf-gen/README.pt.md with a
Portuguese-equivalent title.
- Line 96: Update the option-conflict descriptions to consistently specify
non-nil keywords: in packages/cpf-gen/README.md at lines 96, 179, and 185, and
packages/cpf-gen/README.pt.md at lines 81, 164, and 170. Apply the requested
non-nil qualifier to each detailed description and summary-table trigger without
changing the documented behavior.

In `@packages/cpf-gen/README.pt.md`:
- Line 3: Translate the remaining English text in README.pt.md into Portuguese,
including the documentation link text near the top and the two inline code
comments at the referenced locations. Preserve the existing link target, code
behavior, and formatting.

🪄 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: 4378c6f1-39e5-4ee3-adf6-b8e7a7361716

📥 Commits

Reviewing files that changed from the base of the PR and between 3298142 and e044835.

📒 Files selected for processing (21)

• packages/br-utilities/Gemfile
• packages/cpf-gen/CHANGELOG.md
• packages/cpf-gen/Gemfile
• packages/cpf-gen/README.md
• packages/cpf-gen/README.pt.md
• packages/cpf-gen/cpf-gen.gemspec
• packages/cpf-gen/src/cpf-gen.rb
• packages/cpf-gen/src/cpf-gen/cpf_gen.rb
• packages/cpf-gen/src/cpf-gen/cpf_generator.rb
• packages/cpf-gen/src/cpf-gen/cpf_generator_options.rb
• packages/cpf-gen/src/cpf-gen/errors.rb
• packages/cpf-gen/src/cpf-gen/types.rb
• packages/cpf-gen/src/cpf-gen/utils.rb
• packages/cpf-gen/tests/cpf_gen.spec.rb
• packages/cpf-gen/tests/cpf_generator.spec.rb
• packages/cpf-gen/tests/cpf_generator_options.spec.rb
• packages/cpf-gen/tests/errors.spec.rb
• packages/cpf-gen/tests/utils.spec.rb
• packages/cpf-utilities/Gemfile
• packages/cpf-val/Gemfile
• packages/cpf-val/cpf-val.gemspec

💤 Files with no reviewable changes (4)

• packages/cpf-val/Gemfile
• packages/cpf-utilities/Gemfile
• packages/br-utilities/Gemfile
• packages/cpf-gen/Gemfile