[v2][br-utils] Upgrade to latest API and add support to alphanumeric CNPJ format

[juliolmuller]

Summary by CodeRabbit

• Documentation

  • Added Portuguese docs and rewrote English README with expanded CPF/CNPJ usage, options and examples

• New Features

  • Support for alphanumeric CNPJ formats

• Improvements

  • Require PHP ^8.2
  • Refactored public package API surface and updated façade/usage patterns

• Tests

  • Test suite modernized (Pest-driven specs + updated PHPUnit layout)

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR modernizes br-utils to v2: it requires PHP ^8.2 and strict types, refactors the BrUtils facade (namespace and constructor), reorganizes CPF utilities and helpers, removes local CNPJ wrappers, migrates tests to Pest (with legacy PHPUnit namespaces), and updates README/CHANGELOG (EN/PT).

Changes

br-utils Version 2.0.0 Upgrade

Layer / File(s)	Summary
v2 PHP standards and project wiring AGENTS.md, packages/br-utils/composer.json, packages/br-utils/.pest.config.xml, packages/br-utils/.phpunit.config.xml	Adds agent guidance and package config requiring PHP ^8.2, mandates declare(strict_types=1); and typed signatures, consolidates runtime deps, configures Pest/JUnit output and PHPUnit discovery, and updates composer scripts/config.
BrUtils facade refactor packages/br-utils/src/BrUtils.php	Moves BrUtils namespace, updates imports, reorders and types constructor to accept `CpfUtils
CPF utilities and helpers packages/br-utils/src/BrUtils/Cpf/CpfUtils.php, packages/br-utils/src/BrUtils/Cpf/CpfFormatterOptions.php, packages/br-utils/src/BrUtils/Cpf/CpfGeneratorOptions.php, packages/br-utils/src/BrUtils/Cpf/cpf-fmt.php, packages/br-utils/src/BrUtils/Cpf/cpf-gen.php, packages/br-utils/src/BrUtils/Cpf/cpf-val.php	Rehomes CpfUtils to Lacus\BrUtils\Cpf, adds thin option-wrapper classes extending base *Options, and introduces strict-typed helper functions (cpf_fmt, cpf_gen, cpf_val) delegating to underlying implementations.
Removal of local CNPJ wrappers packages/br-utils/src/Cnpj/CnpjFormatter.php, packages/br-utils/src/Cnpj/CnpjGenerator.php, packages/br-utils/src/Cnpj/CnpjValidator.php, packages/br-utils/src/Cnpj/cnpj_utils.php, packages/br-utils/src/CnpjUtils.php	Deletes legacy CNPJ wrapper classes and helper functions; consumers should use bundled lacus/cnpj-utils v2 API directly.
Test migration and spec additions packages/br-utils/tests/Pest.php, packages/br-utils/tests/phpunit/Cpf/*, packages/br-utils/tests/specs/BrUtils.spec.php	Adds Pest bootstrap, moves existing PHPUnit CPF tests under Lacus\BrUtils\Tests\Legacy\Cpf, removes old shared/ CNPJ PHPUnit suites, and adds a new comprehensive Pest spec (BrUtils.spec.php) covering constructor wiring and CPF/CNPJ behavior forwarding.
Docs & changelogs packages/br-utils/CHANGELOG.md, packages/br-utils/README.md, packages/br-utils/README.pt.md, packages/cnpj-utils/CHANGELOG.md	Adds a v2.0.0 changelog, rewrites README with quick start and detailed CPF/CNPJ API docs, adds Portuguese README, and expands cnpj-utils changelog to document bundled v2 behaviors.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• LacusSolutions/br-utils-php#45: Related migration aligning br-utils with Pest/test layout and autoload-dev PSR-4 changes.
• LacusSolutions/br-utils-php#43: Related CNPJ validator v2 API migration that aligns with removal of local CNPJ wrappers.
• LacusSolutions/br-utils-php#39: Related CNPJ generator/namespace v2 migration referenced by this refactor.

"A rabbit taps a keyboard bright,
Hopping through namespaces by moonlight,
CPF helpers nest with strict delight,
Pest specs bloom, docs in bilingual sight,
V2 hops forward — code trimmed and light." 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: upgrading br-utils to v2 API with alphanumeric CNPJ support, which is reflected throughout the changeset (namespace restructuring, new helpers, composer dependencies updated to v2, documentation updates).
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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/br-utils-v2

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 5

🤖 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/br-utils/composer.json`:
- Around line 54-58: The test:cov script in composer.json currently writes both
Pest and PHPUnit HTML coverage to the same output directory, causing the second
report to overwrite the first; update the test:cov array so the Pest HTML
coverage uses a different directory than PHPUnit (for example use distinct
folders like coverage/pest-html and coverage/phpunit-html or include timestamped
subfolders) by modifying the two commands that run pest with --coverage-html and
phpunit with --coverage-html in the test:cov script so each produces its own
unique output directory.

In `@packages/br-utils/src/BrUtils.php`:
- Around line 42-57: Update the PHPDoc for the $cpf parameter so the nested
formatter and generator option element types are nullable to match
CpfUtils/CpfFormatter/CpfGenerator behavior: in the docblock for the
CpfUtils|array $cpf parameter (referencing CpfFormatterOptions and
CpfGeneratorOptions and the 'formatter' and 'generator' keys) add |null to any
option element types currently documented as non-nullable (e.g., make escape?:
bool|null, hidden?: bool|null, hiddenKey?: string|null, hiddenStart?: int|null,
hiddenEnd?: int|null, dotKey?: string|null, dashKey?: string|null, onFail?:
Closure|null and format?: bool|null, prefix?: string|null) so the PHPDoc aligns
with the constructors that accept nullable values.

In `@packages/br-utils/src/BrUtils/Cpf/cpf-fmt.php`:
- Around line 19-26: The PHPDoc `@param` list in
packages/br-utils/src/BrUtils/Cpf/cpf-fmt.php is out of order compared to the
actual function signature (parameters like $escape and
$hidden/$hiddenKey/$hiddenStart/$hiddenEnd are misaligned); update the PHPDoc
for the cpf formatting function (cpf_fmt or the function declared in this file)
so the `@param` entries appear in the exact same order and types as the function
signature (e.g., place $escape where it appears in the signature and then list
$hidden, $hiddenKey, $hiddenStart, $hiddenEnd, $dotKey, $dashKey, $onFail
accordingly), and apply the same ordering fix to the duplicate block covering
lines 31-39.

In `@packages/br-utils/src/BrUtils/Cpf/CpfFormatterOptions.php`:
- Around line 9-11: Override the merge() method in CpfFormatterOptions to
preserve the wrapper class instead of instantiating the base type: implement
CpfFormatterOptions::merge(...) to perform the same merge logic but instantiate
the result with new static(...) (or by delegating to parent::merge and
re-wrapping into static) so callers that expect
Lacus\BrUtils\Cpf\CpfFormatterOptions keep that concrete type; reference the
existing BaseCpfFormatterOptions::merge and Lacus\CpfFmt\CpfFormatterOptions
constructors to replicate the merge behavior while returning the wrapper class.

In `@packages/br-utils/tests/specs/BrUtils.spec.php`:
- Around line 185-197: The failing static analysis is caused by passing
intentionally invalid typed literals into the BrUtils constructor in the
negative tests; modify the three offending expect(...) calls that instantiate
new BrUtils(...) (the ones asserting CnpjGeneratorOptionTypeInvalidException,
CnpjGeneratorOptionsTypeError, and CnpjValidatorOptionTypeInvalidException) to
avoid PHPStan type checks by either prefixing each offending line with a
localized PHPStan ignore comment (e.g. /** `@phpstan-ignore-next-line` */) or by
casting the invalid argument to mixed (e.g. new BrUtils(cnpj: (mixed)
['generator' => ['type' => 'invalid']]) ), so the runtime assertions still run
but static analysis no longer flags those calls.

🪄 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: 68cd5c45-fecd-46c1-a8b6-a6b1c996dfb4

📥 Commits

Reviewing files that changed from the base of the PR and between 412fbb3 and bd6df62.

📒 Files selected for processing (41)

• AGENTS.md
• packages/br-utils/.pest.config.xml
• packages/br-utils/.phpunit.config.xml
• packages/br-utils/CHANGELOG.md
• packages/br-utils/README.md
• packages/br-utils/README.pt.md
• packages/br-utils/composer.json
• packages/br-utils/src/BrUtils.php
• packages/br-utils/src/BrUtils/Cpf/CpfFormatter.php
• packages/br-utils/src/BrUtils/Cpf/CpfFormatterOptions.php
• packages/br-utils/src/BrUtils/Cpf/CpfGenerator.php
• packages/br-utils/src/BrUtils/Cpf/CpfGeneratorOptions.php
• packages/br-utils/src/BrUtils/Cpf/CpfUtils.php
• packages/br-utils/src/BrUtils/Cpf/CpfValidator.php
• packages/br-utils/src/BrUtils/Cpf/cpf-fmt.php
• packages/br-utils/src/BrUtils/Cpf/cpf-gen.php
• packages/br-utils/src/BrUtils/Cpf/cpf-val.php
• packages/br-utils/src/Cnpj/CnpjFormatter.php
• packages/br-utils/src/Cnpj/CnpjGenerator.php
• packages/br-utils/src/Cnpj/CnpjValidator.php
• packages/br-utils/src/Cnpj/cnpj_utils.php
• packages/br-utils/src/CnpjUtils.php
• packages/br-utils/src/Cpf/cpf_utils.php
• packages/br-utils/tests/BrUtilsTest.php
• packages/br-utils/tests/Cnpj/CnpjFormatterClassTest.php
• packages/br-utils/tests/Cnpj/CnpjFormatterFunctionTest.php
• packages/br-utils/tests/Cnpj/CnpjGeneratorClassTest.php
• packages/br-utils/tests/Cnpj/CnpjGeneratorFunctionTest.php
• packages/br-utils/tests/Cnpj/CnpjValidatorClassTest.php
• packages/br-utils/tests/Cnpj/CnpjValidatorFunctionTest.php
• packages/br-utils/tests/CnpjUtilsTest.php
• packages/br-utils/tests/Pest.php
• packages/br-utils/tests/phpunit/Cpf/CpfFormatterClassTest.php
• packages/br-utils/tests/phpunit/Cpf/CpfFormatterFunctionTest.php
• packages/br-utils/tests/phpunit/Cpf/CpfGeneratorClassTest.php
• packages/br-utils/tests/phpunit/Cpf/CpfGeneratorFunctionTest.php
• packages/br-utils/tests/phpunit/Cpf/CpfUtilsTest.php
• packages/br-utils/tests/phpunit/Cpf/CpfValidatorClassTest.php
• packages/br-utils/tests/phpunit/Cpf/CpfValidatorFunctionTest.php
• packages/br-utils/tests/specs/BrUtils.spec.php
• packages/cnpj-utils/CHANGELOG.md

💤 Files with no reviewable changes (14)

• packages/br-utils/tests/Cnpj/CnpjFormatterFunctionTest.php
• packages/br-utils/src/Cnpj/CnpjFormatter.php
• packages/br-utils/tests/Cnpj/CnpjGeneratorFunctionTest.php
• packages/br-utils/tests/Cnpj/CnpjValidatorFunctionTest.php
• packages/br-utils/tests/CnpjUtilsTest.php
• packages/br-utils/tests/BrUtilsTest.php
• packages/br-utils/src/Cnpj/cnpj_utils.php
• packages/br-utils/src/Cnpj/CnpjValidator.php
• packages/br-utils/src/CnpjUtils.php
• packages/br-utils/tests/Cnpj/CnpjValidatorClassTest.php
• packages/br-utils/tests/Cnpj/CnpjGeneratorClassTest.php
• packages/br-utils/src/Cnpj/CnpjGenerator.php
• packages/br-utils/src/Cpf/cpf_utils.php
• packages/br-utils/tests/Cnpj/CnpjFormatterClassTest.php

[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/br-utils/src/BrUtils/Cpf/cpf-fmt.php`:
- Line 28: Update the PHPDoc for cpf_fmt() to accurately describe when
InvalidArgumentException is thrown: state that \InvalidArgumentException is
thrown by CpfFormatterOptions::setHiddenRange() when hiddenStart/hiddenEnd are
out of allowed range (not for generic "invalid type"), and clarify that invalid
CPF length is handled by the onFail callback rather than thrown; locate the doc
block above the cpf_fmt() function and replace the current "`@throws`
InvalidArgumentException If any option has an invalid type." with the corrected
description.

🪄 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: 6f3924a5-51af-480a-8df9-b7fac73e3189

📥 Commits

Reviewing files that changed from the base of the PR and between bd6df62 and 6bd5e6b.

📒 Files selected for processing (4)

• packages/br-utils/CHANGELOG.md
• packages/br-utils/src/BrUtils/Cpf/CpfUtils.php
• packages/br-utils/src/BrUtils/Cpf/cpf-fmt.php
• packages/br-utils/tests/specs/BrUtils.spec.php