orca/docs/commit-failure-summary.md

# Commit Failure Summary

## Problem

In Source Control, commit failures are stored per worktree in `commitErrors` (`Record<string, string | null>`) and rendered inline by `CommitArea` as raw text (`src/renderer/src/components/right-sidebar/SourceControl.tsx`, `handleCommit` and `commit-area-error`).

`git.commit` failures can include full hook/lint output (multi-line, ANSI-colored, very long). Rendering raw output inline expands the sidebar and pushes core controls out of view.

## Goal

Show a short inline failure summary while keeping the full raw error available in a modal dialog.

## Non-goals

- No IPC/runtime/provider contract changes (`git.commit` stays `{ success, error? }`).
- No exhaustive parser for every hook/linter format.
- No changes to remote-action errors or AI commit-generation errors.

## Constraints from current code

- `handleCommit` already stores raw commit error per worktree and clears it at commit start/success.
- `CommitArea` currently renders `commitError` verbatim in `#commit-area-error` with `role="alert"` and `aria-live="polite"`.
- `commitError`, `remoteActionError`, and `generateError` are independent and all can be referenced by textarea `aria-describedby`.
- Worktree-local state is intentionally preserved across worktree switches; stale keys are pruned when worktrees disappear.

## Design

1. Add `src/renderer/src/components/right-sidebar/commit-failure-summary.ts`:
   - `summarizeCommitFailure(raw: string): string`
   - `hasExpandedCommitFailureDetails(raw: string, summary: string): boolean`

2. Keep parser scope strict and deterministic:
   - Strip ANSI/control sequences and trim whitespace.
   - Split to non-empty lines and ignore low-signal noise (for example npm env-replacement warnings) only when stronger failure lines exist.
   - Detect common commit-hook/lint failures (`pre-commit`, `husky`, `lint-staged`, `eslint`, `oxlint`, generic `lint`/`Found N errors`).
   - Return `Lint failed during commit.` for clear lint/hook lint failures.
   - Return `Pre-commit hook failed.` for hook failures without a clearer lint signal.
   - Otherwise return the first meaningful line.
   - Empty input fallback: `Commit failed.`

3. Render behavior in `CommitArea`:
   - Replace inline raw error block with compact alert row using `TriangleAlert`, summary text, and optional `Details` button.
   - Preserve `id="commit-area-error"`, `role="alert"`, `aria-live="polite"` for accessibility continuity.
   - Keep summary single-line/truncated to avoid sidebar growth.

4. Details dialog:
   - Use existing `Dialog` primitive from `src/renderer/src/components/ui/dialog.tsx`.
   - Title: `Commit Failed`.
   - Description: summary.
   - Body: scrollable `<pre>` with raw error (`whitespace-pre-wrap`, mono styling, bounded height).
   - Footer close button via existing `DialogFooter`/`DialogClose` patterns.
   - Dialog open state is local to `CommitArea` and auto-resets closed when the active worktree changes or `commitError` changes/clears.
   - Reset key should include both worktree identity and error identity (for example `${worktreeId}:${commitError}`), not only error text.

5. Derivation and state rules:
   - Do not add new persisted error state in `SourceControl`; derive summary/details from current `commitError` only.
   - Compute summary with `useMemo` keyed by `commitError` for stable render behavior.
   - Keep raw error as source of truth; summary/details-visibility are derived every render.
   - If hooks are introduced inside `CommitArea` (dialog open state, memoized summary), update tests to render through React (`<CommitArea {...props} />`) instead of direct function invocation (`CommitArea(props)`), because direct invocation cannot run hookful components.

## Edge cases

- ANSI escape sequences in hook output.
- Errors emitted on either stderr or stdout (already possible in `commitChanges`).
- One-line failures: no `Details` button when normalized raw text is effectively the same as summary.
- Very large error payloads: inline remains bounded; full text stays dialog-only.
- Worktree switch while dialog open: details must reflect active worktree error; close dialog when error identity changes.
- Concurrent commit attempts:
  - same worktree is already guarded (`commitInFlightRef`).
  - different windows/processes can still mutate repo externally; UI must treat summaries as best-effort snapshots and refresh on next commit/status cycle.

## Feasibility

- All work is renderer-only and compatible with current API boundaries.
- String normalization/parsing is cheap relative to render cost; no runtime or IPC latency impact.
- Existing dialog/button primitives cover required UX; no new UI infrastructure needed.

## Tests

1. New unit tests for formatter module:
   - lint-staged/husky/oxlint sample collapses to `Lint failed during commit.`
   - pre-commit non-lint sample collapses to `Pre-commit hook failed.`
   - generic non-hook error falls back to first meaningful line.
   - ANSI stripping and empty-input fallback.
   - details visibility predicate correctness.

2. Update `CommitArea` tests:
   - inline shows summary, not raw multiline payload.
   - details trigger appears only when expanded details exist.
   - `commit-area-error` a11y attributes remain present.
   - dialog closes when `commitError` clears/changes.
   - tests render `CommitArea` as a React component (not direct function call) once hooks are added.

3. Keep existing generate/remote error behavior unchanged (regression check).

## Rollout

1. Add formatter + tests.
2. Integrate summary row + details dialog in `CommitArea`.
3. Update commit-area tests.
4. Run focused tests (`CommitArea*`, formatter tests), then `pnpm typecheck` and `pnpm lint`.