feat: add health module

[olivermeyer]

In f781801 I install adr-tools to be used to document code/architecture decisions going forward.

In dce0037 I add the health module from Bridge. Please see the related decision document about the code structure.

[codecov]

Codecov Report

❌ Patch coverage is 98.21429% with 1 line in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/aignostics_foundry_core/health.py	98.21%	0 Missing and 1 partial ⚠️

Files with missing lines	Coverage Δ
src/aignostics_foundry_core/health.py	98.21% <98.21%> (ø)

[claude]

Claude finished @olivermeyer's task in 3m 2s —— View job

---

Code Review Complete ✅

Reviewed PR #5: feat: add health module

---

Summary

This PR successfully adds a well-designed health check module to Foundry Python Core. The code quality is excellent and meets all project standards. Both the implementation and tests demonstrate professional software engineering practices.

Verdict: ✅ Approved - Ready to Merge

---

Review Details

✅ Code Quality & Standards

Excellent adherence to project guidelines:

• ✅ SonarQube Compliance: All quality gates passed. No S1192 violations (string literals properly managed)
• ✅ Type Safety: Comprehensive type hints using Python 3.11+ features (Self, StrEnum)
• ✅ Code Style: Follows CODE_STYLE.md conventions (naming, formatting, documentation)
• ✅ DRY Principle: No code duplication; test constants properly extracted (lines 8-16 in health_test.py)

✅ Architecture & Design

Well-documented and thoughtful:

• ✅ ADR Documentation: Clear decision records for adopting ADR tooling (ADR-0001) and module structure (ADR-0002)
• ✅ Module Structure: Follows ADR-0002 (public modules pattern) consistently
• ✅ Pydantic Usage: Correct Pydantic v2 patterns (BaseModel, model_validator with mode="after", Field defaults)
• ✅ Design Patterns: Tree-structured health with recursive aggregation is elegant and maintainable

✅ Implementation Quality

src/aignostics_foundry_core/health.py:

• ✅ Logic Correctness: Health status propagation (DOWN > DEGRADED > UP) implemented correctly
• ✅ Validation: Proper model validation ensuring DOWN/DEGRADED require reasons, UP must not have one
• ✅ Error Messages: Clear, actionable error messages with component context
• ✅ Documentation: Complete Google-style docstrings for all public APIs
• ✅ Defensive Programming: Line 127's redundant check (and self.reason) is good defensive practice

✅ Test Quality

tests/aignostics_foundry_core/health_test.py:

• ✅ Test Markers: All 17 tests properly marked with @pytest.mark.unit (CI requirement met)
• ✅ Coverage: 98.21% patch coverage (excellent; 1 partial line is acceptable defensive code)
• ✅ Test Structure: Clear AAA pattern (Arrange-Act-Assert)
• ✅ Edge Cases: Comprehensive coverage including:
  • Validation rules (UP/DOWN/DEGRADED with/without reasons)
  • Single vs multiple component failures
  • Status precedence (DOWN trumps DEGRADED)
  • Recursive propagation through component trees
  • Pre-existing DOWN status preservation
• ✅ Test Constants: String literals properly extracted to module-level constants (SonarQube S1192 compliant)
• ✅ Descriptive Names: Test names clearly describe expected behavior

✅ Security

• ✅ No hardcoded secrets
• ✅ No injection vulnerabilities
• ✅ Input validation handled by Pydantic
• ✅ No external dependencies beyond pydantic

✅ Documentation

• ✅ README.md: Updated with health module example
• ✅ AGENTS.md: Comprehensive module documentation with usage examples
• ✅ ADR Documentation: Well-structured decision records
• ✅ Code Comments: Clear docstrings without over-commenting

✅ Dependency Management

• ✅ Added pydantic>=2,<3 with appropriate version constraints
• ✅ Lock files updated (uv.lock, mise.lock)
• ✅ Attributions updated

✅ Commit Quality

• ✅ Commit 1 (f781801): chore: use adr-tools - follows conventional commits
• ✅ Commit 2 (dce0037): feat: add health module - follows conventional commits
• ✅ Logical separation of concerns (tooling setup vs feature addition)

---

Observations (Non-Blocking)

Coverage Note

The 1 missing partial line (98.21% → 100%) is likely line 127 in health.py:

if self.status in {HealthStatus.DOWN, HealthStatus.DEGRADED} and self.reason:

The and self.reason check is technically redundant due to validation ensuring DOWN/DEGRADED always have reasons, but this defensive programming is acceptable and recommended for robustness.

Unused Field

The uptime_statistics: dict[str, dict[str, Any]] | None field is defined but not used in the health computation logic. This appears intentional for:

• Future enhancements (uptime tracking)
• External integration (e.g., Prometheus metrics)
• Extensibility without breaking changes

This is good forward-thinking design.

---

What Was Removed

• ✅ Properly removed placeholder greet.py module and tests
• ✅ Updated __init__.py to remove old exports
• ✅ Updated documentation to reflect new module structure

Clean removal with no orphaned references.

---

Testing Note

⚠️ Important: I cannot run linters or tests myself. However:

• ✅ SonarQube CI check passed (quality gate)
• ✅ Codecov CI check shows 98.21% coverage
• ✅ Code review confirms compliance with mise run lint requirements

The PR author should verify locally:

mise run lint              # Should pass
mise run test_unit         # Should pass with coverage ≥85%

---

Conclusion

This is production-ready code that demonstrates:

• Professional software engineering practices
• Thorough testing with excellent coverage
• Clear documentation and architectural decisions
• Adherence to all project standards

No blocking issues found. The code is ready to merge.

Great work! 🎉

---

Todo List

• Read CLAUDE.md and project documentation
• Review git diff and commit history
• Analyze health.py module
• Review health_test.py
• Check ADR documentation
• Verify code quality and best practices
• Compile final review feedback

---

[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