Summary
Redesign the shared error hierarchy for the CNPJ utility gems so the aggregator-level contract sits at the top of the hierarchy and errors raised by component gems participate as leaf errors beneath that shared contract.
Rationale
cnpj-utilities currently aggregates cnpj-fmt, cnpj-gen, and cnpj-val, whose errors propagate unchanged. This prevents consumers of the aggregator from reliably rescuing one unified domain error family while retaining native error specificity.
The redesign likely requires a separate shared error-contract package (or equivalent dependency-neutral abstraction) so component gems can depend on the common hierarchy without depending on the aggregator itself. Because this changes public exception ancestry and inverts dependencies, it is a breaking change and should be planned for a later major release.
Affected areas
packages/cnpj-utilities — façade documentation and aggregator-facing error contractpackages/cnpj-fmt — formatter errorspackages/cnpj-gen — generator errorspackages/cnpj-val — validator errors- Any related CPF packages if a shared Brazilian-document error contract is selected
Required changes
- Decide and document the ownership and package location of the shared error contract.
- Define a domain root error and marker/module strategy that remains compatible with Ruby native error classes (all library errors must remain descendants of
StandardError).
- Update component error classes so they inherit from or otherwise participate in the shared contract without introducing a dependency from leaves to the aggregator.
- Define a migration and versioning plan for consumers rescuing existing component-specific errors.
- Update public documentation and tests to show the full inheritance chains, marker inclusion, precise trigger conditions, and rescue granularity.
Acceptance criteria
- A dependency-neutral architecture is selected and documented.
- Component errors can be rescued both at their native/component-specific granularity and through a unified domain-level contract.
- No component package depends on the top-level aggregator package.
- Public errors descend from
StandardError; neither direct inheritance from nor rescue of Exception is introduced.
- Compatibility impact, deprecations, and target major-version releases are documented.
- Tests and package READMEs cover the new hierarchy and rescue behavior.
Context
Requested by @juliolmuller during review of #25.
Summary
Redesign the shared error hierarchy for the CNPJ utility gems so the aggregator-level contract sits at the top of the hierarchy and errors raised by component gems participate as leaf errors beneath that shared contract.
Rationale
cnpj-utilitiescurrently aggregatescnpj-fmt,cnpj-gen, andcnpj-val, whose errors propagate unchanged. This prevents consumers of the aggregator from reliably rescuing one unified domain error family while retaining native error specificity.The redesign likely requires a separate shared error-contract package (or equivalent dependency-neutral abstraction) so component gems can depend on the common hierarchy without depending on the aggregator itself. Because this changes public exception ancestry and inverts dependencies, it is a breaking change and should be planned for a later major release.
Affected areas
packages/cnpj-utilities— façade documentation and aggregator-facing error contractpackages/cnpj-fmt— formatter errorspackages/cnpj-gen— generator errorspackages/cnpj-val— validator errorsRequired changes
StandardError).Acceptance criteria
StandardError; neither direct inheritance from nor rescue ofExceptionis introduced.Context
Requested by @juliolmuller during review of #25.
cnpj-utils] Create package to consolidate itilities for CNPJ #25cnpj-utils] Create package to consolidate itilities for CNPJ #25 (comment)