[cnpj-gen] Create package to generate valid CNPJ

[juliolmuller]

Summary by CodeRabbit

• New Features
  • Added cnpj-gen with CNPJ generation supporting numeric, alphabetic, and alphanumeric types, optional prefixes, masked formatting, and check-digit handling.
• Documentation
  • Expanded English/Portuguese READMEs and changelogs for cnpj-gen and clarified option precedence and error behavior in cnpj-fmt.
• Bug Fixes / Behavior Changes
  • Enforced that passing an options object together with keyword overrides raises InvalidArgumentCombinationError.
  • Updated option setters so nil inputs raise TypeMismatchError.
• Tests
  • Added/expanded RSpec coverage for generation, option resolution, utilities, and the public error hierarchy.
• Chores
  • Updated gem packaging metadata and tightened dependency constraints; removed local path dependencies.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: 70ab72e9-7c0f-4124-94cb-ad0d306fddab

📥 Commits

Reviewing files that changed from the base of the PR and between 75cbe7b and d759801.

📒 Files selected for processing (4)

• packages/cnpj-fmt/tests/cnpj_formatter_options.spec.rb
• packages/cnpj-fmt/tests/utils.spec.rb
• packages/cnpj-gen/tests/cnpj_generator_options.spec.rb
• packages/cnpj-gen/tests/errors.spec.rb

---

📝 Walkthrough

Walkthrough

This PR adds the cnpj-gen Ruby generator, structured errors, option validation, retry handling, and documentation. It also changes cnpj-fmt option resolution to reject mixed argument styles, updates related tests, and removes local cnpj-dv Gemfile dependencies.

Changes

cnpj-gen

Layer / File(s)	Summary
Generator contracts and errors packages/cnpj-gen/src/cnpj-gen/{types.rb,errors.rb}, packages/cnpj-gen/src/cnpj-gen.rb	Defines supported types, public constants, input contracts, and structured exception classes.
Option resolution and generation packages/cnpj-gen/src/cnpj-gen/cnpj_generator_options.rb, packages/cnpj-gen/src/cnpj-gen/utils.rb, packages/cnpj-gen/src/cnpj-gen/cnpj_generator.rb, packages/cnpj-gen/src/cnpj-gen/cnpj_gen.rb	Adds option merging, prefix validation, CNPJ generation, formatting, check-digit computation, and retry behavior.
Validation and packaging support packages/cnpj-gen/tests/*, packages/cnpj-gen/README*, packages/cnpj-gen/CHANGELOG.md, packages/cnpj-gen/cnpj-gen.gemspec	Adds generator, options, utility, and error coverage, plus package metadata and API documentation.

cnpj-fmt

Layer / File(s)	Summary
Formatter option resolution packages/cnpj-fmt/src/cnpj-fmt/cnpj_formatter_options.rb, packages/cnpj-fmt/src/cnpj-fmt/utils.rb	Adds layered option resolution, explicit defaults, setter validation, and hidden-range normalization.
Argument exclusivity packages/cnpj-fmt/src/cnpj-fmt/cnpj_formatter.rb, packages/cnpj-fmt/src/cnpj-fmt/cnpj_fmt.rb	Rejects calls that provide positional options together with non-nil keyword overrides.
Tests and documentation packages/cnpj-fmt/tests/*, packages/cnpj-fmt/README*, packages/cnpj-fmt/CHANGELOG.md	Updates expectations for invalid combinations and nil setters, and documents the revised API behavior.

Package cleanup

Layer / File(s)	Summary
Dependency declarations packages/*/Gemfile, packages/cnpj-gen/cnpj-gen.gemspec, packages/cnpj-val/cnpj-val.gemspec	Removes local cnpj-dv path dependencies, adds cnpj-gen packaging metadata, and tightens runtime dependency ranges.

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

Possibly related issues

• Implement package cnpj-gen #4 — Requests the cnpj-gen generator implemented here.
• Implement package cnpj-utilities #6 — Covers the broader cnpj-utilities packaging, including cnpj-gen.

Possibly related PRs

• LacusSolutions/br-utils-ruby#15 — Provides the external CnpjDV dependency consumed by cnpj-gen.
• LacusSolutions/br-utils-ruby#16 — Introduces the overlapping cnpj-fmt package and classes revised here.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant CnpjGen
  participant CnpjGenerator
  participant CnpjDV
  Caller->>CnpjGen: cnpj_gen(options, keywords)
  CnpjGen->>CnpjGenerator: create generator and call generate
  CnpjGenerator->>CnpjDV: compute check digits
  CnpjDV-->>CnpjGenerator: digits or exception
  CnpjGenerator-->>Caller: formatted or raw CNPJ

Loading

Poem

A rabbit hops through digits bright,
Formats dots and dashes right.
Options merge, then errors speak,
Check digits retry when paths are bleak.
CNPJ seeds now bloom anew!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 59.00% 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: adding the new cnpj-gen package to generate valid CNPJ 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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/cnpj-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: 8

🤖 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/cnpj-gen/src/cnpj-gen/cnpj_generator_options.rb`:
- Around line 93-100: apply_initial_options in CnpjGeneratorOptions is returning
before applying the format, prefix, and type keyword overrides when options is a
Hash or CnpjGeneratorOptions. Update the method so
copy_options/apply_hash_options load the base values first, then apply any
non-nil keyword args as overrides instead of dropping them. Also add coverage
around CnpjGeneratorOptions.new and CnpjGenerator#initialize for the
hash-plus-keywords case, e.g. when passing a Hash with format: true.

In `@packages/cnpj-gen/src/cnpj-gen/cnpj_generator.rb`:
- Around line 54-61: The initializer in CnpjGenerator currently ignores keyword
overrides when options is already a CnpjGeneratorOptions instance. Update
CnpjGenerator#initialize to either merge any provided format/prefix/type
keywords into a copied options object when keywords are present, or explicitly
document in the constructor docs that keyword args are ignored in that case;
keep the behavior consistent with the `@param` docs and the CnpjGeneratorOptions
path.
- Around line 129-135: The with_check_digits retry path can recurse forever when
CnpjDV::CnpjCheckDigitsException keeps happening, so add a bounded retry
strategy instead of calling generate blindly. Update
CnpjGenerator#with_check_digits to track attempts and stop after a small
maximum, then fail explicitly or delegate to a private helper that enforces the
limit while preserving the existing generate/options/format/prefix/type flow.
Keep the change localized around with_check_digits and generate so the retry
behavior is safe and predictable.

In `@packages/cnpj-gen/src/cnpj-gen/exceptions.rb`:
- Around line 114-122: The CNPJGen::TypeError initializer currently duplicates
an already-frozen expected_values array, leaving the stored attr_reader
potentially mutable. Update the initialize method in CNPJGen::TypeError to
either keep the original frozen reference directly or, if defensive copying is
intended, freeze the duplicated array before assigning it to `@expected_values` so
callers cannot mutate it through the reader.

In `@packages/cnpj-gen/src/cnpj-gen/generator_options_validation.rb`:
- Around line 73-85: The naming in validate_prefix_non_repeated_digits! is
inconsistent with the sibling validate_prefix_* methods, which all use
partial_cnpj. Rename the parameter and update its local references in
generator_options_validation.rb so the method follows the same naming convention
as the other prefix validators, improving readability and consistency.

In `@packages/cnpj-gen/src/cnpj-gen/types.rb`:
- Around line 12-15: The CNPJ type constants are currently the same frozen
object, so CNPJ_TYPE_OPTIONS_ORDER is only an alias of CNPJ_TYPE_VALUES. Update
the constants in types.rb so CNPJ_TYPE_OPTIONS_ORDER is explicitly independent
if that is intended, using the CNPJ_TYPE_VALUES definition and the
CNPJ_TYPE_OPTIONS_ORDER constant as the reference points; otherwise keep only
one constant if no separate ordering is needed.

In `@packages/cnpj-gen/tests/cnpj_generator_options.spec.rb`:
- Around line 80-97: The current specs for CnpjGeneratorOptions only cover
hash-only and keyword-only initialization, so they miss the hash + keyword
combination that can trigger the apply_initial_options keyword-dropping bug. Add
a new example in cnpj_generator_options.spec.rb that initializes
CnpjGeneratorOptions with both a positional hash and keyword args, then asserts
all expected options are preserved via expect_options_match, using the existing
described_class and apply_initial_options behavior as the target path.

In `@packages/cnpj-gen/tests/exceptions.spec.rb`:
- Around line 1-5: TYPE_INVALID_EXPECTED_VALUES is duplicating the allowed type
list from CnpjGen::CNPJ_TYPE_VALUES, so update the spec to reference the source
constant directly or otherwise derive the expected values from it. If you keep
the local constant intentionally for independent verification in
exceptions.spec.rb, add a brief comment near TYPE_INVALID_EXPECTED_VALUES
explaining that the duplication is deliberate.

🪄 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: 105ccf96-0773-4550-b189-bd9b0962f424

📥 Commits

Reviewing files that changed from the base of the PR and between 2e7dcb1 and 44453b2.

📒 Files selected for processing (21)

• packages/br-utilities/Gemfile
• packages/cnpj-gen/CHANGELOG.md
• packages/cnpj-gen/Gemfile
• packages/cnpj-gen/README.md
• packages/cnpj-gen/README.pt.md
• packages/cnpj-gen/cnpj-gen.gemspec
• packages/cnpj-gen/src/cnpj-gen.rb
• packages/cnpj-gen/src/cnpj-gen/cnpj_gen.rb
• packages/cnpj-gen/src/cnpj-gen/cnpj_generator.rb
• packages/cnpj-gen/src/cnpj-gen/cnpj_generator_option_properties.rb
• packages/cnpj-gen/src/cnpj-gen/cnpj_generator_options.rb
• packages/cnpj-gen/src/cnpj-gen/exceptions.rb
• packages/cnpj-gen/src/cnpj-gen/generator_options_validation.rb
• packages/cnpj-gen/src/cnpj-gen/types.rb
• packages/cnpj-gen/tests/cnpj_gen.spec.rb
• packages/cnpj-gen/tests/cnpj_generator.spec.rb
• packages/cnpj-gen/tests/cnpj_generator_options.spec.rb
• packages/cnpj-gen/tests/exceptions.spec.rb
• packages/cnpj-utilities/Gemfile
• packages/cnpj-val/Gemfile
• packages/cnpj-val/cnpj-val.gemspec

💤 Files with no reviewable changes (4)

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

[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/cnpj-gen/src/cnpj-gen/cnpj_generator.rb`:
- Around line 135-136: Update the CnpjDV::DomainError handling around generate
so retries are bounded: move recursive retry behavior into a private helper that
tracks attempts, preserves the existing options and keywords, and raises a
deterministic terminal error after the configured retry limit instead of
recursing indefinitely.

🪄 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: 69c2005c-77c0-4de7-a7a3-aa38a33f06c4

📥 Commits

Reviewing files that changed from the base of the PR and between 835bad9 and 869bc13.

📒 Files selected for processing (4)

• packages/cnpj-gen/cnpj-gen.gemspec
• packages/cnpj-gen/src/cnpj-gen/cnpj_generator.rb
• packages/cnpj-gen/tests/cnpj_generator.spec.rb
• packages/cnpj-val/cnpj-val.gemspec

[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/cnpj-gen/tests/cnpj_generator_options.spec.rb`:
- Around line 46-49: Make invalid-type expectations independent of production
constants: in packages/cnpj-gen/tests/cnpj_generator_options.spec.rb lines
46-49, build CNPJ_GENERATOR_OPTIONS_TYPE_INVALID_MESSAGE from a test-owned
literal values list; in packages/cnpj-gen/tests/errors.spec.rb line 5, replace
CnpjGen::CNPJ_TYPE_VALUES with that same independent expected-values list. Keep
both tests aligned while ensuring implementation constant changes cannot
silently update the expected results.

🪄 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: 735655ee-12b2-4cc8-85a5-e464e50be1ff

📥 Commits

Reviewing files that changed from the base of the PR and between 869bc13 and 75cbe7b.

📒 Files selected for processing (6)

• packages/cnpj-fmt/src/cnpj-fmt/errors.rb
• packages/cnpj-gen/src/cnpj-gen/errors.rb
• packages/cnpj-gen/src/cnpj-gen/types.rb
• packages/cnpj-gen/src/cnpj-gen/utils.rb
• packages/cnpj-gen/tests/cnpj_generator_options.spec.rb
• packages/cnpj-gen/tests/errors.spec.rb