fix(config): add warning for multiple configuration files and update documentation

[nicoleman0]

Description

This PR implements a warning system that detects when multiple configuration files exist in the project directory (excluding pyproject.toml) and displays a warning message identifying which file is being used.

The implementation follows the consensus from issue #1702 where maintainers agreed that "we should have one and only one configuration file" and decided to add a warning when multiple config files are detected.

Checklist

• I have read the contributing guidelines

Code Changes

• Add test cases to all the changes you introduce
• Run uv run poe all locally to ensure this change passes linter check and tests
• Manually test the changes:
  • Verify the feature/bug fix works as expected in real-world scenarios
  • Test edge cases and error conditions
  • Ensure backward compatibility is maintained
  • Document any manual testing steps performed
• Update the documentation for the changes

Documentation Changes

• Run uv run poe doc locally to ensure the documentation pages renders correctly
• Check and fix any broken links (internal or external) in the documentation

Expected Behavior

When multiple configuration files are detected (e.g., .cz.toml and .cz.json), commitizen will display a warning message like:

Multiple config files detected: .cz.toml, .cz.json. Using config file: '.cz.toml'.

• The warning only appears when multiple config files exist (excluding pyproject.toml)
• The warning lists all detected config files in the order they would be checked
• The warning clearly indicates which file will be used (the first one in the priority order)
• If a config file is explicitly specified via the --config flag, no warning is displayed
• If only one config file exists (or only pyproject.toml plus one other), no warning is displayed
• The file priority order follows the standard commitizen config file precedence.

---

Fixes #1771

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.93%. Comparing base (63c529d) to head (9afa4f9).
⚠️ Report is 5 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1773      +/-   ##
==========================================
+ Coverage   97.88%   97.93%   +0.04%     
==========================================
  Files          60       60              
  Lines        2606     2611       +5     
==========================================
+ Hits         2551     2557       +6     
+ Misses         55       54       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[bearomorphism]

Great but need some refactoring

[bearomorphism]

Could you add the expected behavior in the PR description? Thanks!

[nicoleman0]

Could you add the expected behavior in the PR description? Thanks!

I just updated the PR with the expected behavior (sorry about that, completely forgot to add that part), and also refactored my code with the suggestions that you all gave.

If I missed anything, let me know again.

[bearomorphism]

Could you add the expected behavior in the PR description? Thanks!

I just updated the PR with the expected behavior (sorry about that, completely forgot to add that part), and also refactored my code with the suggestions that you all gave.

If I missed anything, let me know again.

@nicoleman0 you're doing it great! But the pipeline is failing because some of the commit messages does not follow the requirements. Could you fix the commit messages? Thanks!

[nicoleman0]

Could you add the expected behavior in the PR description? Thanks!

I just updated the PR with the expected behavior (sorry about that, completely forgot to add that part), and also refactored my code with the suggestions that you all gave.
If I missed anything, let me know again.

@nicoleman0 you're doing it great! But the pipeline is failing because some of the commit messages does not follow the requirements. Could you fix the commit messages? Thanks!

@bearomorphism I believe I've fixed the generic commit messages and I also refactored the read_cfg function.

The redundant if filepath is None: check has been removed. The code now performs the multiple config file check in both cases, though it will only ever warn when filepath is None.