Validate unknown keyword options consistently across CPF/CNPJ utility packages

[coderabbitai]

Summary

Introduce consistent validation for unrecognized keyword arguments in the options-bearing packages, while preserving the existing options-object call path.

This is intentionally deferred from PR #27 because silently ignoring unknown keywords is existing behavior in published packages. The change should be designed and released as a coordinated compatibility/breaking-change effort rather than altering only cpf-utilities.

Rationale

Calls such as a misspelled keyword can currently be silently ignored when keywords are normalized into option overrides. Rejecting those keys will surface API misuse at the call site, but doing so in only one package would make behavior inconsistent across the monorepo and may break existing consumers.

Affected packages

• cnpj-fmt
• cnpj-gen
• cnpj-val
• cnpj-utilities
• cpf-fmt
• cpf-gen
• cpf-val
• cpf-utilities
• br-utilities

Required behavior

• Validate unknown keys only when the caller is using the keyword-argument path; do not apply this validation merely because an options instance argument was supplied.
• Treat an unrecognized key as invalid even when its value is nil.
• Raise the package-specific custom API-misuse error that inherits from ArgumentError (not native ArgumentError directly), following each package's error hierarchy and marker-module conventions.
• Keep recognized keyword behavior unchanged.

Acceptance criteria

• Each affected package rejects unknown keyword arguments on its keyword-based options/settings APIs.
• An unknown keyword with a nil value raises the appropriate package-specific custom ArgumentError.
• Passing an options instance continues to follow its existing contract without keyword-key validation being incorrectly applied.
• The package-specific error conforms to the repository error hierarchy: correct ArgumentError inheritance and package Error marker inclusion.
• Unit tests cover valid keywords, unknown non-nil keywords, unknown nil keywords, and options-instance behavior for every affected package.
• The release/versioning plan explicitly accounts for this behavior change in already published packages.

Backlinks

• Requested by @juliolmuller in PR [cpf-utils] Create package to consolidate itilities for CPF #27: [cpf-utils] Create package to consolidate itilities for CPF #27
• Review discussion: [cpf-utils] Create package to consolidate itilities for CPF #27 (comment)

[coderabbitai]

🔗 Related PRs

#16 - [cnpj fmt] Create package to format CNPJ [merged]
#17 - [cnpj-gen] Create package to generate valid CNPJ [merged]
#20 - [cnpj-val] Create package to validate CNPJ [merged]
#23 - [cpf-gen] Create package to generate valid CPF [merged]
#27 - [cpf-utils] Create package to consolidate itilities for CPF [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!