feat(cli): upgrade doctor to state-aware diagnostic engine - #47
Merged
Conversation
Transitions `_analyze_logs` to accept a `seconds` parameter instead of `hours`. This allows for higher-resolution, dynamic lookback windows based on daemon configuration intervals.
Calculates the log analysis lookback window dynamically as a multiple of the daemon's configured `push_interval` (defaulting to 3 cycles). This adapts diagnostic sensitivity directly to the expected operational frequency of the system.
Reorders diagnostic checks in `run_doctor` to evaluate repository health before log events. If all repositories are healthy (no stalled backups), recent log errors are downgraded to a suppressed informational message, preventing alert fatigue from naturally resolved transient anomalies.
Introduces a diagnostic check to verify if the user account has systemd 'Linger' enabled. This prevents the daemon from being silently killed when the user's SSH or TTY session terminates.
Implements a topological check to scan the remote `wip/pulsar` namespace for backup streams originating from other machine IDs. Warns the user if a remote stream has a newer timestamp than the local working directory, prompting a synchronization.
Scans the local `.git/hooks/` directory for executable `pre-push` or `pre-commit` scripts. Alerts the user that strict hooks may intercept and hang the background daemon's automated subprocess calls.
Introduces tests for the `_check_systemd_linger` helper function. Verifies correct behavior across different platforms (ignoring macOS/Windows) and handles simulated `loginctl` outputs for enabled and disabled states.
Introduces tests for the `_check_remote_drift` helper. Validates the topological scanning logic by mocking remote ref fetches and timestamp comparisons to ensure divergence risks are properly flagged.
Introduces tests for the `_check_git_hooks` helper. Verifies the file system scanning logic to ensure executable pre-push and pre-commit hooks lacking bypass logic are correctly flagged as potential blockers.
Updates CLI tests to cover the dynamic lookback window and state/event correlation in `run_doctor`. Verifies that transient log errors are suppressed when the system state is healthy, and printed loudly when failures correlate.
Updates the testing documentation to include the verification strategy for `test_cli.py`. Outlines the approach for testing state/event correlation, execution environment sanity (systemd linger), topological drift detection, and git hook interference scanning.
Expands the module map documentation for `cli.py` to include its new role as the state-aware diagnostic engine. Adds a 5th architectural invariant detailing the priority of system state over transient event logs during health evaluations.
… detection Updates the main `README.md` to highlight the new capabilities of the `doctor` command. Adds a "State-Aware Diagnostics" feature bullet, expands the command reference, and marks the "Roaming Radar" roadmap item as completed since drift detection is now integrated into the health checks.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR significantly upgrades
git pulsar doctorfrom a static log parser into a state-aware diagnostic engine. It addresses the inherent issue of event-based monitoring in self-healing distributed systems by correlating historical log events with current repository state, suppressing alert fatigue from naturally resolved transient anomalies.Additionally, it introduces environmental and topological checks to preemptively identify pipeline blockers and remote state drift.
Key Changes
run_doctornow evaluates active repository health before parsing logs. It utilizes a dynamic lookback window calculated as a multiple of the daemon's configuredpush_interval. If the system state is healthy, active log errors within that window are downgraded to suppressed informational notices._check_systemd_lingerto verifysystemduser linger status on Linux, preventing silent daemon termination upon SSH disconnect._check_remote_driftto perform lightweight fetches of thewip/pulsarnamespace. It warns users if a remote machine has pushed a newer backup stream for the current branch, prompting async._check_git_hooksto scan.git/hooks/for executablepre-pushorpre-commitscripts lacking explicit bypass logic, warning users of potential background pipeline hangs.Testing
test_cli.pycoverage for all new helper functions usingpytestandmocker.run_doctortests to utilizetmp_pathfixtures instead of directly mocking read-onlyPosixPathattributes, ensuring robust filesystem simulation.Documentation
README.mdto reflect the "Roaming Radar" completion and new diagnostic capabilities.src/README.mdwith the 5th architectural invariant: "State Over Events".tests/README.mdto detail the CLI interaction and diagnostic mocking strategy.