Set patch versions for internal packages dependencies

[juliolmuller]

@coderabbitai, describe this issue with a implementation proposal:

• Issue: packages depending on each other internally are using minimum value support, like cnpj-utils depends on cnpj-fmt@^1.0, which means that a minor version increases in cnpj-utils can insert unexpectedly new features to the aggregator package, which is not an issue from a CI/stability perspective, but is bad from a product perspective, due to changelogs and documentationlacking information.
• My Proposal: fix dependencies version to the exact or patch-level version on internal packages.

[coderabbitai]

🔗 Related PRs

#44 - [cnpj-gen] Upgrade dependencies and deprecate resources [merged]
#51 - Add changelog documentation for v1.0.0 releases [merged]

---

📝 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.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 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!

[coderabbitai]

Coding Plan

Summary

• Adopt tilde notation (~X.Y.Z) for all internal package dependencies to lock minor versions while allowing patch updates
• Update dependency policy documentation first to establish the new convention
• Systematically update all nine packages with internal dependencies, working from leaf packages up through aggregators
• Regenerate lockfiles and add changelog entries for each affected package

Design Choices

Design Choice 1: Which version constraint format should be used for internal dependencies?

Options Considered:

1. Exact versions (e.g., 1.2.3): Most restrictive; requires manual update for every release including patches
2. Tilde operator (e.g., ~1.2.3): Allows patch updates (>=1.2.3, <1.3.0) but locks minor version
3. Patch wildcard (e.g., 1.2.*): Similar effect to tilde; allows any patch within the minor

Chosen Option: 2

Rationale: This satisfies the "patch-level" requirement while still allowing bug fixes to flow through automatically. It prevents unexpected minor-version feature additions (the core concern) without creating excessive maintenance burden from exact version pinning.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Update Dependency Policy Documentation

Establish the new versioning convention in documentation before applying changes to packages, ensuring future contributions follow the updated pattern.

Update Dependency Guidelines

Document the new tilde-based version constraint requirement for internal package dependencies.

• Update agents/dependencies.md to specify that internal dependencies must use tilde notation (~X.Y.Z) instead of caret notation (^X.Y)
• Add rationale explaining that this prevents minor version features from unexpectedly propagating to dependent packages without changelog visibility
• Update any example snippets showing internal dependency declarations to use the new format
• Clarify that when bumping an internal dependency, the full X.Y.Z version must be specified based on the currently published release

🤖 Prompt for AI agents

Update the dependency policy documentation in `agents/dependencies.md` to
reflect the new tilde-based version constraint convention for internal packages.

- Replace any references to caret notation (`^X.Y`) for internal dependencies
with tilde notation (`~X.Y.Z`)
- Add or update rationale text explaining that tilde notation prevents
unexpected minor-version feature additions from propagating to dependent
packages without changelog visibility
- Update any example snippets that show internal dependency declarations to use
the `~X.Y.Z` format
- Add a clarification that when bumping an internal dependency, the full `X.Y.Z`
version must be specified based on the currently published release

Phase 2: Update Package Dependencies

Apply the new versioning convention to all packages with internal dependencies, ensuring each constraint specifies the current latest released version with tilde notation.

Task 1: Determine Current Released Versions

Identify the latest released version of each internal package to use as the basis for tilde constraints.

• Query git tags using format git tag -l 'lacus/<pkg>@*' | sort -V | tail -n 1 for each package
• Document the current latest version for: utils, cpf-dv, cnpj-dv, cpf-fmt, cnpj-fmt, cpf-gen, cnpj-gen, cpf-val, cnpj-val, cpf-utils, cnpj-utils
• These versions will be used as the X.Y.Z in ~X.Y.Z constraints

Task 2: Update Leaf Package Dependencies

Update packages that depend only on utils or single internal packages.

• Update packages/cpf-dv/composer.json: Change lacus/utils from ^1.0 to ~X.Y.Z (using current utils version)
• Update packages/cnpj-dv/composer.json: Change lacus/utils from ^1.0 to ~X.Y.Z
• Update packages/cnpj-fmt/composer.json: Change lacus/utils from ^1.0 to ~X.Y.Z
• Update packages/cpf-val/composer.json: Change lacus/cpf-gen from ^1.0 to ~X.Y.Z
• Run composer install --working-dir=packages/<pkg> for each updated package to regenerate lockfiles

Task 3: Update Mid-Level Package Dependencies

Update packages with multiple internal dependencies.

• Update packages/cnpj-val/composer.json: Change lacus/cnpj-dv from ^1.1 to ~X.Y.Z and lacus/utils from ^1.0 to ~X.Y.Z
• Update packages/cnpj-gen/composer.json: Change lacus/cnpj-dv from ^1.1 to ~X.Y.Z and lacus/utils from ^1.0 to ~X.Y.Z
• Run composer install --working-dir=packages/<pkg> for each updated package to regenerate lockfiles

Task 4: Update Aggregator Package Dependencies

Update the aggregator packages that compose multiple sub-packages.

• Update packages/cpf-utils/composer.json: Change all three internal deps (cpf-fmt, cpf-gen, cpf-val) from ^1.0 to their respective ~X.Y.Z versions
• Update packages/cnpj-utils/composer.json: Change cnpj-fmt from ^2.0, cnpj-gen from ^2.1, and cnpj-val from ^2.0 to their respective ~X.Y.Z versions
• Update packages/br-utils/composer.json: Change cnpj-utils from ^2.0 and cpf-utils from ^1.1 to their respective ~X.Y.Z versions
• Run composer install --working-dir=packages/<pkg> for each updated package to regenerate lockfiles

🤖 Prompt for AI agents

Apply tilde version constraints to all `composer.json` files for internal
package dependencies across the monorepo, working from leaf packages up through
aggregators. First, determine the latest released version for each internal
package by running `git tag -l 'lacus/<pkg>@*' | sort -V | tail -n 1` for each
of: `utils`, `cpf-dv`, `cnpj-dv`, `cpf-fmt`, `cnpj-fmt`, `cpf-gen`, `cnpj-gen`,
`cpf-val`, `cnpj-val`, `cpf-utils`, `cnpj-utils`. Use the resolved versions as
`X.Y.Z` in all `~X.Y.Z` constraints below.

**Leaf packages** — update the following `composer.json` files:
- `packages/cpf-dv/composer.json`: `lacus/utils` `^1.0` → `~X.Y.Z`
- `packages/cnpj-dv/composer.json`: `lacus/utils` `^1.0` → `~X.Y.Z`
- `packages/cnpj-fmt/composer.json`: `lacus/utils` `^1.0` → `~X.Y.Z`
- `packages/cpf-val/composer.json`: `lacus/cpf-gen` `^1.0` → `~X.Y.Z`
- Run `composer install --working-dir=packages/<pkg>` for each to regenerate
lockfiles

**Mid-level packages** — update the following `composer.json` files:
- `packages/cnpj-val/composer.json`: `lacus/cnpj-dv` `^1.1` → `~X.Y.Z`,
`lacus/utils` `^1.0` → `~X.Y.Z`
- `packages/cnpj-gen/composer.json`: `lacus/cnpj-dv` `^1.1` → `~X.Y.Z`,
`lacus/utils` `^1.0` → `~X.Y.Z`
- Run `composer install --working-dir=packages/<pkg>` for each to regenerate
lockfiles

**Aggregator packages** — update the following `composer.json` files:
- `packages/cpf-utils/composer.json`: `cpf-fmt`, `cpf-gen`, `cpf-val` all `^1.0`
→ respective `~X.Y.Z`
- `packages/cnpj-utils/composer.json`: `cnpj-fmt` `^2.0`, `cnpj-gen` `^2.1`,
`cnpj-val` `^2.0` → respective `~X.Y.Z`
- `packages/br-utils/composer.json`: `cnpj-utils` `^2.0`, `cpf-utils` `^1.1` →
respective `~X.Y.Z`
- Run `composer install --working-dir=packages/<pkg>` for each to regenerate
lockfiles

Phase 3: Changelog Updates

Add changelog entries for all packages with modified dependencies, following the established convention that runtime dependency changes require documentation.

Add Changelog Entries

Document the dependency constraint changes in each affected package's changelog.

• Add entries to the unreleased section of CHANGELOG.md for each package updated in Phase 2
• Per agents/changelogs.md, changing runtime "require" constraints is a patch-level change
• Use consistent wording such as: "Changed internal dependency version constraints from caret to tilde notation for more predictable feature propagation"
• Packages requiring changelog updates: cpf-dv, cnpj-dv, cnpj-fmt, cpf-val, cnpj-val, cnpj-gen, cpf-utils, cnpj-utils, br-utils

🤖 Prompt for AI agents

Add patch-level changelog entries to the unreleased section of `CHANGELOG.md`
for each package whose `composer.json` was modified in Phase 2.

- Target packages: `cpf-dv`, `cnpj-dv`, `cnpj-fmt`, `cpf-val`, `cnpj-val`,
`cnpj-gen`, `cpf-utils`, `cnpj-utils`, `br-utils`
- Per `agents/changelogs.md`, changes to runtime `"require"` constraints are
classified as **patch-level** changes
- Use consistent wording across all entries, such as: "Changed internal
dependency version constraints from caret to tilde notation for more predictable
feature propagation"
- Place each entry in the appropriate unreleased section of the respective
package's `CHANGELOG.md`

Research

This is a PHP monorepo containing Brazilian document utilities organized as composable packages. The dependency hierarchy flows from utils → {cpf,cnpj}-dv → {cpf,cnpj}-{fmt,gen,val} → {cpf,cnpj}-utils → br-utils. All internal dependencies currently use caret (^) version constraints (e.g., ^1.0, ^2.0), which allow minor version updates to flow through automatically. The project follows SemVer and documents dependency policies in agents/dependencies.md.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Update the dependency policy documentation in `agents/dependencies.md` to
reflect the new tilde-based version constraint convention for internal packages.

- Replace any references to caret notation (`^X.Y`) for internal dependencies
with tilde notation (`~X.Y.Z`)
- Add or update rationale text explaining that tilde notation prevents
unexpected minor-version feature additions from propagating to dependent
packages without changelog visibility
- Update any example snippets that show internal dependency declarations to use
the `~X.Y.Z` format
- Add a clarification that when bumping an internal dependency, the full `X.Y.Z`
version must be specified based on the currently published release
===============================================================================

Task: 2

Apply tilde version constraints to all `composer.json` files for internal
package dependencies across the monorepo, working from leaf packages up through
aggregators. First, determine the latest released version for each internal
package by running `git tag -l 'lacus/<pkg>@*' | sort -V | tail -n 1` for each
of: `utils`, `cpf-dv`, `cnpj-dv`, `cpf-fmt`, `cnpj-fmt`, `cpf-gen`, `cnpj-gen`,
`cpf-val`, `cnpj-val`, `cpf-utils`, `cnpj-utils`. Use the resolved versions as
`X.Y.Z` in all `~X.Y.Z` constraints below.

**Leaf packages** — update the following `composer.json` files:
- `packages/cpf-dv/composer.json`: `lacus/utils` `^1.0` → `~X.Y.Z`
- `packages/cnpj-dv/composer.json`: `lacus/utils` `^1.0` → `~X.Y.Z`
- `packages/cnpj-fmt/composer.json`: `lacus/utils` `^1.0` → `~X.Y.Z`
- `packages/cpf-val/composer.json`: `lacus/cpf-gen` `^1.0` → `~X.Y.Z`
- Run `composer install --working-dir=packages/<pkg>` for each to regenerate
lockfiles

**Mid-level packages** — update the following `composer.json` files:
- `packages/cnpj-val/composer.json`: `lacus/cnpj-dv` `^1.1` → `~X.Y.Z`,
`lacus/utils` `^1.0` → `~X.Y.Z`
- `packages/cnpj-gen/composer.json`: `lacus/cnpj-dv` `^1.1` → `~X.Y.Z`,
`lacus/utils` `^1.0` → `~X.Y.Z`
- Run `composer install --working-dir=packages/<pkg>` for each to regenerate
lockfiles

**Aggregator packages** — update the following `composer.json` files:
- `packages/cpf-utils/composer.json`: `cpf-fmt`, `cpf-gen`, `cpf-val` all `^1.0`
→ respective `~X.Y.Z`
- `packages/cnpj-utils/composer.json`: `cnpj-fmt` `^2.0`, `cnpj-gen` `^2.1`,
`cnpj-val` `^2.0` → respective `~X.Y.Z`
- `packages/br-utils/composer.json`: `cnpj-utils` `^2.0`, `cpf-utils` `^1.1` →
respective `~X.Y.Z`
- Run `composer install --working-dir=packages/<pkg>` for each to regenerate
lockfiles
===============================================================================

Task: 3

Add patch-level changelog entries to the unreleased section of `CHANGELOG.md`
for each package whose `composer.json` was modified in Phase 2.

- Target packages: `cpf-dv`, `cnpj-dv`, `cnpj-fmt`, `cpf-val`, `cnpj-val`,
`cnpj-gen`, `cpf-utils`, `cnpj-utils`, `br-utils`
- Per `agents/changelogs.md`, changes to runtime `"require"` constraints are
classified as **patch-level** changes
- Use consistent wording across all entries, such as: "Changed internal
dependency version constraints from caret to tilde notation for more predictable
feature propagation"
- Place each entry in the appropriate unreleased section of the respective
package's `CHANGELOG.md`

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!