Repository navigation
feat(#563): graceful setup experience for unconfigured projects - #573
Conversation
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
WalkthroughAdds GitHub label audit and creation endpoints to the settings router with matching UI in settings.html, using GitHub CLI for label diffing and creation with concurrency control. Also fixes supervisor graph node-selection persistence, adds a 503 setup-required panel, and centralizes epic badge dimension constants. ChangesGitHub Label Management
Estimated code review effort: 3 (Moderate) | ~25 minutes Supervisor Graph Fixes
Estimated code review effort: 2 (Simple) | ~12 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
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. Comment |
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@sova/dashboard/routers/settings.py`:
- Around line 301-448: Add tests covering the new audit_labels and
create_missing_labels endpoints, mocking sova.utils.shell.run and related
GitHub/config dependencies. Exercise missing GitHub configuration (400),
unavailable CLI, malformed JSON, invalid label colors, permission-denied
creation failures, and truncation at _MAX_LABEL_ERRORS, while verifying async
behavior and response payloads.
- Around line 369-379: Extract the audit and missing-label computation from
audit_labels() into a private helper that accepts the already loaded cfg and
returns the missing-labels result. Update audit_labels() to load and validate
cfg once before calling the helper, and update create_missing_labels() to pass
its existing cfg directly instead of calling audit_labels(), preserving the
current error handling and label-creation behavior.
- Around line 84-97: Import ProjectConfig from sova.config.models and update the
cfg parameter of _validate_github_config to use the ProjectConfig type hint,
preserving the existing validation logic and return annotation.
- Around line 316-331: Update audit_labels around the run("gh", ...) call to
catch FileNotFoundError raised when the GitHub CLI is unavailable, returning
{"error": "GitHub CLI not available or not authenticated", "missing": []}
instead of propagating the exception. Preserve the existing result.success and
stderr handling for commands that return a ShellResult.
In `@sova/dashboard/templates/supervisor.html`:
- Around line 406-410: Update the “Setup Required” panel in the supervisor
template to use generic project-configuration guidance rather than asserting
that the task source adapter is missing. Align the message with the HTTP 503
`_ConfigError` response from the dependencies router, covering malformed or
unavailable project configuration without selecting a specific adapter cause.
- Around line 417-419: Update the non-503 error branch in loadGraph() to clear
errorEl’s existing contents before setting the generic HTTP failure message,
ensuring stale “Setup Required” heading and link markup is removed while
preserving the current paragraph text.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 9d08e050-bf62-4ebe-aaed-4a324ecdb497
📒 Files selected for processing (3)
sova/dashboard/routers/settings.pysova/dashboard/templates/settings.htmlsova/dashboard/templates/supervisor.html
xsovad06
left a comment
There was a problem hiding this comment.
PR Summary
This PR by xsovad06 adds graceful setup experience for unconfigured SOVA projects with 7 commits, 768 additions, and 10 deletions. It fixes a JavaScript temporal dead zone crash on the supervisor page, adds a setup guidance panel for 503 errors, and implements GitHub label audit and creation endpoints with comprehensive test coverage.
Findings
[HIGH] Correctness: FileNotFoundError not caught in label audit
Location: sova/dashboard/routers/settings.py:307
Problem: asyncio.create_subprocess_exec raises FileNotFoundError when gh is not installed, bypassing the ShellResult return path. The audit endpoint returns a 500 with the raw subprocess exception instead of the graceful "GitHub CLI not available or not authenticated" message at line 312.
Suggestion: Wrap the await run() call in a try/except block that catches FileNotFoundError and returns the error dict early:
try:
result = await run("gh", "label", "list", "--repo", cfg.github_repo, "--json", "name", env=env)
except FileNotFoundError:
return {"error": "GitHub CLI not available or not authenticated"}[HIGH] Performance: Duplicate config loading and audit in create_missing_labels
Location: sova/dashboard/routers/settings.py:426-431
Problem: create_missing_labels() loads config at line 427, validates it at line 428, then calls _fetch_existing_labels(cfg) at line 431. But _fetch_existing_labels is also called by audit_labels(), which independently loads config and validates again. This results in two load_config() calls, two _validate_github_config() calls, and two gh label list API roundtrips whenever the create endpoint is used (the audit runs first from the UI).
Suggestion: Extract the audit and missing-label computation from audit_labels() into a private helper _compute_missing_labels(cfg) that accepts the already-loaded config and returns the missing-labels result. Have audit_labels() load config once and call the helper. Have create_missing_labels() pass its existing cfg directly to the helper instead of calling _fetch_existing_labels(). This eliminates the duplicate work while preserving the same error handling and response structure.
[MEDIUM] Consistency: Missing ProjectConfig type hint
Location: sova/dashboard/routers/settings.py:84
Problem: The cfg parameter of _validate_github_config is untyped. The function receives a project configuration object and has a return type hint, but the parameter is plain cfg.
Suggestion: Import ProjectConfig from sova.config.models and add the type hint: def _validate_github_config(cfg: ProjectConfig) -> None:.
[MEDIUM] Correctness: 503 setup panel assumes task source adapter is missing
Location: sova/dashboard/templates/supervisor.html:408-409
Problem: The setup panel text says "Project configuration is unavailable. Check your settings to ensure the project is properly configured." But the HTTP 503 _ConfigError response from dependencies.py lines 199-227 can be raised for any malformed configuration, not just a missing task source adapter. If the config file has syntax errors or other validation failures, this panel reports the wrong cause.
Suggestion: Use more generic project-configuration guidance that doesn't assert a specific failure mode. The current message is already fairly generic, so this is a minor concern. Alternatively, parse the 503 response detail to identify the specific error type and show a targeted message.
[MEDIUM] Correctness: Non-503 error path doesn't clear stale HTML
Location: sova/dashboard/templates/supervisor.html:418
Problem: When loadGraph() receives a non-503 bad response, it only updates errorEl.innerHTML with a generic failure text. If the previous errorEl.innerHTML contained the "Setup Required" markup (heading, link, icon), the non-503 path doesn't explicitly clear it first. While innerHTML = assignment replaces the content, it's safer to explicitly clear to avoid any edge cases where previous markup persists.
Suggestion: Explicitly clear before setting the generic failure text: errorEl.innerHTML = ''; errorEl.innerHTML = \
Failed to load graph: HTTP ${res.status}
`;`. Or more concisely, ensure the assignment fully replaces the content (which it does in this case, so this is a low-priority nitpick).Confirmed Bot Findings
Agree with CodeRabbit on sova/dashboard/routers/settings.py:84: Add ProjectConfig type hint. See my MEDIUM finding above.
Agree with CodeRabbit on sova/dashboard/routers/settings.py:307: Handle FileNotFoundError. See my HIGH finding above.
Agree with CodeRabbit on sova/dashboard/routers/settings.py:379: Avoid re-running audit in create_missing_labels. See my HIGH finding above.
Agree with CodeRabbit on sova/dashboard/templates/supervisor.html:408: Generic 503 message assumption. See my MEDIUM finding above.
Agree with CodeRabbit on sova/dashboard/templates/supervisor.html:418: Clear errorEl before non-503 errors. See my MEDIUM finding above.
Disagree with CodeRabbit on sova/dashboard/routers/settings.py:458: Tests WERE added. Commits b255304 and 3c0f342 added 11 comprehensive tests covering audit_labels, create_missing_labels, error cases, truncation, and all edge cases. The bot's comment about missing tests is incorrect.
Verdict
Request changes: two HIGH findings (FileNotFoundError not caught, duplicate config loading) and three MEDIUM findings (missing type hint, 503 message assumption, stale HTML not cleared) must be addressed before merge. The HIGH findings affect correctness and performance; the MEDIUM findings improve code quality and error handling clarity.
(Posted as comment: GitHub does not allow self-reviews with formal approval/rejection state.)
What's Done Well
Excellent test coverage with 11 new tests covering all edge cases including auth failures, permission denied, error truncation, and mixed success/failure scenarios. The tests brought SonarCloud coverage from 10.6% to 93.5% on new code.
Good use of async concurrency control with asyncio.Semaphore to limit parallel label creation requests, preventing rate limit issues while maintaining performance.
Clean separation of concerns with helper functions _fetch_existing_labels, _create_single_label, and _build_label_response extracted to module level for reusability and testability.
Add two new REST endpoints to settings router for managing GitHub labels: - GET /settings/labels/audit: checks for missing SOVA required labels - POST /settings/labels/create: creates all missing labels in parallel Includes validation helpers, error handling with truncation, and concurrency limits to prevent rate limiting. Supports graceful degradation when GitHub CLI is unavailable or not authenticated.
Extract _compute_missing_labels helper to eliminate duplicate logic between audit and create endpoints. Add type hint to _validate_github_config and FileNotFoundError handling to _fetch_existing_labels for better error recovery. Reduces cognitive complexity score from 12 to 7.
Add interactive card to settings page showing: - Missing label count with color-coded list - Create button to batch-create missing labels - Success/error toast notifications - Auto-refresh on completion Integrates with new /settings/labels/audit and /settings/labels/create endpoints.
…rror paths Replace querySelector-based error message updates with innerHTML assignment to prevent null reference errors when error element structure changes. Improves HTTP 503 handling with styled setup guidance card.
Replace generic "Project configuration is unavailable" with actionable message explaining that task source adapter needs configuration. Guides users to configure GitHub or Jira integration.
… endpoints Add 14 test cases covering: - GitHub adapter validation (not GitHub, missing repo) - GitHub CLI availability and authentication - JSON parsing errors - Permission denied scenarios - Invalid color format validation - Error truncation (max 10 errors) - Message length truncation (max 200 chars) - Partial success handling - Success path with no missing labels Achieves full coverage of _fetch_existing_labels, _create_single_label, _build_label_response, _compute_missing_labels, audit_labels, and create_missing_labels endpoints.
|
Findings addressed in latest push.



Summary
EPIC_BADGE_WIDTHbeing referenced before declarationChanges
Supervisor page (
supervisor.html)EPIC_BADGE_WIDTHconstant declaration before first use (line 842 → 835) to fix TDZ crash affecting any project with priority labelsLabel management API (
routers/settings.py)_REQUIRED_LABELSconstant defining 24 SOVA labels (type, priority, area, agent state, review verdict)GET /settings/labels/auditendpoint to detect missing labels via GitHub CLIPOST /settings/labels/createendpoint with parallel creation (semaphore limit: 5), comprehensive error handling, and truncated error reporting_validate_github_config()helper rejecting Jira projects (label operations GitHub-only for now)Settings UI (
settings.html)Review guidance
EPIC_BADGE_WIDTHdeclaration now precedes all references (check lines 835 vs 842, 858)Test plan
Closes #563