Fix ImportError with conflicting clang-format packages and improve error handling

[Copilot]

This PR resolves the ImportError: cannot import name 'clang_format' from 'clang_format' issue that occurs when users have conflicting PyPI packages installed alongside cpp-linter-hooks.

Root Cause

The error occurs when users have conflicting clang-format scripts from PyPI packages (like clang-format==21.1.0) that use incompatible import structures. These conflicts often stem from previous installations of version 1.0.0, which included clang tools as direct dependencies, leaving behind conflicting scripts in user environments.

Solution

1. Comprehensive Documentation

Added a detailed troubleshooting section to the README with three solution approaches:

• Remove conflicting packages: pip uninstall clang-format clang-tidy clang-tools
• Manual script cleanup: Instructions for identifying and removing conflicting scripts
• Configuration verification: Ensuring users have the correct pre-commit configuration

2. Intelligent Conflict Detection

Implemented smart conflict detection that:

• Automatically identifies conflicting clang-format scripts that contain problematic imports
• Only shows warnings when CLANG_FORMAT_HOOK_DEBUG=1 is set (no noise in normal usage)
• Provides actionable guidance with specific pip uninstall commands and documentation links

# Enable debug mode to see conflict warnings
CLANG_FORMAT_HOOK_DEBUG=1 clang-format-hook --help

3. Enhanced Error Handling

Improved error messages throughout the codebase:

• More informative FileNotFoundError messages with helpful hints
• Better exception handling in both clang_format.py and clang_tidy.py
• Clear guidance for tool installation issues

4. Version Consistency

Updated all README examples to consistently use the latest version v1.1.1.

Testing

• All existing tests pass (73/73)
• Manual verification of conflict detection functionality
• User scenario simulation testing confirms the solution works correctly
• The hooks operate correctly as clang-format-hook and clang-tidy-hook entry points, avoiding namespace conflicts entirely

This solution maintains backward compatibility while providing users clear paths to resolve conflicts.

Fixes #108.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

@shenxianpeng 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.

[codecov]

Codecov Report

❌ Patch coverage is 13.04348% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.33%. Comparing base (c42c695) to head (fcc5d65).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
cpp_linter_hooks/clang_format.py	15.00%	17 Missing ⚠️
cpp_linter_hooks/clang_tidy.py	0.00%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #109       +/-   ##
===========================================
- Coverage   94.48%   83.33%   -11.15%     
===========================================
  Files           3        3               
  Lines         145      168       +23     
===========================================
+ Hits          137      140        +3     
- Misses          8       28       +20     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud