feat: improve codecov configuration for more reliable PR coverage checks (#646)

## ℹ️ Description
*Improve codecov configuration to address erratic PR blocking behavior
and provide better developer visibility into coverage impact.*

- Addresses inconsistent flag definitions between codecov.yml and
workflow
- Resolves confusing threshold values and separate flag status checks
- Improves developer experience with comprehensive PR comments

## 📋 Changes Summary

- Replace separate flag checks with single combined project coverage
check (70% target)
- Add patch coverage check (80% target) to catch regressions in changed
code
- Add comprehensive PR comments showing project, patch, and file-level
coverage
- Configure flag carryforward for better handling of partial test runs
- Remove confusing 0.2% integration threshold and separate flag status
checks
- Validate configuration with Codecov's official endpoint

### ⚙️ Type of Change
Select the type(s) of change(s) included in this pull request:
- [ ] 🐞 Bug fix (non-breaking change which fixes an issue)
- [x] ✨ New feature (adds new functionality without breaking existing
usage)
- [ ] 💥 Breaking change (changes that might break existing user setups,
scripts, or configurations)

## ✅ Checklist
Before requesting a review, confirm the following:
- [x] I have reviewed my changes to ensure they meet the project's
standards.
- [x] I have tested my changes and ensured that all tests pass (`pdm run
test`).
- [x] I have formatted the code (`pdm run format`).
- [x] I have verified that linting passes (`pdm run lint`).
- [x] I have updated documentation where necessary.

By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.

codecov.yml

@@ -10,11 +10,37 @@ coverage:
   precision: 2
   round: down
   range: "70...100"  # https://docs.codecov.com/docs/codecovyml-reference#coveragerange
+
   status:
+    # Combined project coverage check (all flags together)
     project:
       default:
-        threshold: "0%"
+        target: 70%                    # Minimum 70% absolute coverage required
-        flags: ["unit-tests"]
+        threshold: 1.5%                # Allow up to 1.5% coverage drop
-      integration:
+        informational: false           # Block PRs that fail this check
-        flags: ["integration-tests"]
+        # No flags specified = combines all flags (unit, integration, smoke)
-        threshold: "0.2%"  # https://docs.codecov.com/docs/commit-status#threshold
+
+    # Patch coverage: check coverage on changed lines only
+    patch:
+      default:
+        target: 80%                    # Require 80% coverage on new/changed code
+        threshold: 0%                  # Don't allow any drop in patch coverage
+        informational: false           # Block PRs that fail this check
+
+# PR Comment Configuration
+comment:
+  layout: "header, diff, flags, files, footer"  # Show comprehensive breakdown
+  behavior: default                              # Update existing comment
+  require_changes: false                         # Always post comment
+  require_base: false                            # Post even without base report
+  require_head: true                             # Only post if head report exists
+  hide_project_coverage: false                   # Show both project and patch
+
+# Flag configuration for visibility (not for status checks)
+flags:
+  unit-tests:
+    carryforward: true  # Reuse previous results if not run
+  integration-tests:
+    carryforward: true
+  smoke-tests:
+    carryforward: true