FIX: cortex doctor - resolve dependency detection + add polished UI

[lu11y0]

Related Issue

Closes #332

Summary

• Case-insensitive package name mapping in SystemDoctor
• PyYAML → yaml, python-dotenv → dotenv...
• raw_name.replace("-", "_") fallback for hyphens

New Features:

• CX-styled "SYSTEM HEALTH CHECK" header
• Consistent cx_header() for all sections
• Full Cortex banner style integration

demo

Screen.Recording.2025-12-21.234242.mp4

Checklist

• Tests pass (pytest tests/test_cortex_doctor)
• PR title format: [#XX] Description
• MVP label added if closing MVP issue

Summary by CodeRabbit

• New Features

  • Enhanced system health check interface with improved visual branding and styling
  • Added real-time progress indicator during health checks
  • Improved package dependency validation with better name matching

• Style

  • Refreshed system health check display with updated header and message formatting

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

The cortex doctor command was refactored to introduce CX branding elements, implement a spinner-based display for health checks, and resolve case-sensitive package name detection issues by normalizing dependency validation logic.

Changes

Cohort / File(s)	Summary
Doctor Output & Execution Flow cortex/doctor.py	Introduced CX-branded headers and banner display; wrapped health check execution within a spinner context for batched, in-progress display; refactored _print_section to use CX header styling; updated check execution order (Python & Dependencies, GPU & Acceleration, AI & Services, System Resources) within spinner scope; enhanced status accounting with passes/warnings/failures lists.
Dependency Validation Enhancement cortex/doctor.py	Implemented package name normalization (lowercasing, hyphen/underscore conversion) in dependency validation; added mapping for python-dotenv to dotenv; improved import checks to handle case-sensitivity and naming inconsistencies, addressing false "missing packages" reports.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: cortex doctor - System Health Check  #306: Introduces the SystemDoctor class and core health check infrastructure that this PR extends with UI branding, spinner context management, and enhanced dependency validation.

Suggested reviewers

• mikejmorgan-ai

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly describes the two main changes: fixing dependency detection and adding polished UI improvements to cortex doctor.
Description check	✅ Passed	The PR description includes related issue, summary of changes, and a completed checklist, though the MVP label checkbox was not checked.
Linked Issues check	✅ Passed	The PR directly addresses issue #332 by implementing case-insensitive package name mapping with explicit mappings (PyYAML→yaml, python-dotenv→dotenv) and hyphen/underscore normalization.
Out of Scope Changes check	✅ Passed	The UI improvements (CX-styled headers, cx_header usage, banner integration) are enhancements beyond the core issue #332 but are reasonable polishing for the doctor module.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (3)

cortex/doctor.py (3)

14-14: Unused import: Status

The Status class is imported but not used directly. The spinner at line 74 uses console.status() which is a method on the Console object and doesn't require the Status import.

🔎 Proposed fix

-from rich.status import Status

---

60-61: Remove commented-out code.

The commented-out show_banner() call appears to be dead code from a previous implementation. If it's no longer needed, remove it to keep the codebase clean.

🔎 Proposed fix

-        # Show banner once
-        # show_banner()

---

181-184: Version specifier parsing may miss edge cases.

The current parsing doesn't handle all pip version specifiers (e.g., >=, ~=, !=) or extras syntax like requests[security]. For example, pkg[extra]>=1.0 would yield pkg[extra after splitting.

Consider using a more robust approach:

🔎 Proposed fix using regex

+import re
+
 def _check_dependencies(self) -> None:
     """Check packages from requirements.txt."""
     missing: list[str] = []
     requirements_path = Path("requirements.txt")
     ...
         try:
             with open(requirements_path) as f:
                 for line in f:
                     line = line.strip()
                     if line and not line.startswith("#"):
-                        raw_name = line.split("==")[0].split(">")[0].split("<")[0].strip()
+                        # Extract package name, handling version specifiers and extras
+                        match = re.match(r'^([a-zA-Z0-9_-]+)', line)
+                        if not match:
+                            continue
+                        raw_name = match.group(1)
                         pkg_name = name_overrides.get(
                             raw_name.lower(), raw_name.lower().replace("-", "_")
                         )

Alternatively, consider using packaging.requirements.Requirement from the packaging library for robust parsing if it's already a dependency.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 287a353 and 185a3da.

📒 Files selected for processing (1)

• cortex/doctor.py

🧰 Additional context used

📓 Path-based instructions (1)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Follow PEP 8 style guide
Type hints required in Python code
Docstrings required for all public APIs

Files:

• cortex/doctor.py

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: test (3.12)
• GitHub Check: test (3.10)
• GitHub Check: test (3.11)

🔇 Additional comments (5)

cortex/doctor.py (5)

73-92: Potential visual artifacts from printing inside spinner context.

Printing to the console while inside a console.status() spinner context can cause visual glitches—the spinner may overwrite or interleave with the printed output. Rich's status spinner is typically used for operations that don't produce intermediate output.

Consider either:

1. Running checks silently within the spinner, then printing all results afterward, or
2. Removing the spinner and keeping the sequential output as before.

Please verify the terminal output behavior to ensure the spinner and check messages display cleanly without flickering or overlap.

---

101-103: LGTM!

Good refactor—delegating to cx_header() centralizes header styling and follows DRY principles.

---

169-174: Good fix for the case-insensitive package detection issue.

The addition of python-dotenv → dotenv mapping and the case-normalized lookup with hyphen-to-underscore fallback correctly addresses issue #332's false missing-package reports.

---

239-243: LGTM!

Clear, informative warning message that correctly indicates CPU-only mode is supported while noting the performance impact.

---

324-328: LGTM!

Helpful suggestion that provides users with two options for configuring their API key.

[Suyashd999]

Thanks @kr16h