specs/009-open-file-at-comment/spec.md
Ref: Size: 5.7 KiB
# Feature Specification: Open File at Inline Comment Location from Dashboard **Feature Branch**: `009-open-file-at-comment` **Created**: 2026-03-21 **Status**: Draft **Input**: User description: "When viewing a patch diff with inline comments in the TUI dashboard, pressing a key (e.g. 'e') on an inline comment should open the referenced file at the exact line in the user's $EDITOR." ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Open file at inline comment line (Priority: P1) As a code reviewer using the TUI dashboard, I want to press 'e' while viewing a patch diff to open the file referenced by the nearest inline comment at the exact line number in my $EDITOR, so I can quickly jump from reviewing to editing without manually locating the file and line. **Why this priority**: This is the core feature. Without it, the user must manually copy file paths and line numbers from the diff view, breaking their review flow. **Independent Test**: Can be fully tested by creating a patch with an inline comment on a known file and line, pressing 'e' in diff view, and verifying $EDITOR opens the correct file at the correct line. **Acceptance Scenarios**: 1. **Given** the user is viewing a patch diff that has an inline comment on `src/patch.rs:5`, **When** the user scrolls to that comment and presses 'e', **Then** the TUI suspends, `$EDITOR +5 src/patch.rs` is executed, and after the editor exits, the TUI resumes. 2. **Given** the user is viewing a patch diff with multiple inline comments, **When** the user scrolls to a specific comment and presses 'e', **Then** the editor opens at the file and line of the inline comment closest to (at or above) the current scroll position. 3. **Given** the user has `$EDITOR` set to `vim`, **When** they press 'e' on an inline comment, **Then** `vim +<line> <file>` is executed. 4. **Given** the user has `$VISUAL` set but `$EDITOR` is unset, **When** they press 'e', **Then** `$VISUAL` is used as the editor command. --- ### User Story 2 - Handle missing files and editor gracefully (Priority: P2) As a user, when I press 'e' on an inline comment that references a file that no longer exists or when no editor is configured, I want to see a clear status message rather than a crash. **Why this priority**: Error handling is important for robustness but is secondary to the core functionality. Users should never experience a panic from this feature. **Independent Test**: Can be tested by removing the referenced file or unsetting $EDITOR/$VISUAL, pressing 'e', and verifying a status message appears in the TUI footer. **Acceptance Scenarios**: 1. **Given** an inline comment references `src/deleted.rs:10` but that file does not exist on disk, **When** the user presses 'e', **Then** the TUI displays a status message like "File not found: src/deleted.rs" and does not crash or spawn an editor. 2. **Given** neither `$EDITOR` nor `$VISUAL` is set, **When** the user presses 'e', **Then** the TUI displays a status message like "No editor configured. Set $EDITOR or $VISUAL." and does not crash. 3. **Given** the editor command fails (exits with non-zero), **When** the editor exits, **Then** the TUI resumes normally and optionally shows a brief status message. --- ### Edge Cases - What happens when the user presses 'e' while not in diff view mode? The keypress should be ignored (no-op). - What happens when the user presses 'e' while viewing a diff with no inline comments? The keypress should be ignored (no-op). - What happens when the user presses 'e' on an orphan comment (comment on a file not in the diff)? The editor should still open the file at the referenced line, since the `InlineComment` struct contains the file path and line. - What happens when `$EDITOR` contains arguments (e.g., `code --wait`)? The command should be split and executed properly. - What happens when the scroll position is between two inline comments? The nearest comment at or above the scroll position should be selected. ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: System MUST bind the 'e' key in the TUI diff view to trigger the open-file-at-comment action. - **FR-002**: System MUST determine the inline comment nearest to (at or above) the current scroll position in the rendered diff. - **FR-003**: System MUST extract the `file` and `line` fields from the selected `InlineComment`. - **FR-004**: System MUST resolve the editor command from `$VISUAL` (preferred) or `$EDITOR` (fallback). - **FR-005**: System MUST suspend the TUI (restore terminal state), execute `<editor> +<line> <file>`, then restore the TUI after the editor exits. - **FR-006**: System MUST display a status message when no editor is configured or the referenced file does not exist. - **FR-007**: System MUST ignore 'e' keypresses when not in diff view mode or when no inline comments exist near the scroll position. ### Key Entities - **InlineComment**: Existing struct in `src/state.rs` with `file: String`, `line: u32`, `body: String`, `author: Author`, `timestamp: String`. No changes needed. - **App**: Existing TUI application state struct. May need a `status_message: Option<String>` field (or reuse existing mechanism) for transient user feedback. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Pressing 'e' on an inline comment in diff view opens the correct file at the correct line in under 1 second. - **SC-002**: The TUI suspends cleanly before editor launch and resumes correctly after editor exit with no visual artifacts. - **SC-003**: All error cases (missing file, missing editor, editor failure) are handled without panics and display a user-visible status message. - **SC-004**: Existing keybindings and TUI behavior are unaffected by this feature (no regressions).