Skip to content

[303] refactor(errors): adopt 3-line standard (error / caused by / help)#306

Merged
erishforG merged 2 commits into
developfrom
303-refactor/error-3line-format
May 13, 2026
Merged

[303] refactor(errors): adopt 3-line standard (error / caused by / help)#306
erishforG merged 2 commits into
developfrom
303-refactor/error-3line-format

Conversation

@erishforG
Copy link
Copy Markdown
Owner

배경

`parsec` 의 user-facing 에러를 error: / caused by: / help: 3-line 포맷으로 표준화 (#303). 첫 사용자 마찰 ↓.

변경

  • `ParsecError` 에 `caused_by: Option` + `help: Option` 추가, builder 스타일 setter (`with_caused_by`, `with_help`).
  • `Display` 1~3-line 가변. caused_by/help 미설정이면 단일 line (기존 동작 유지).
  • `JsonError` 에 동일 필드 + `skip_serializing_if` 로 기존 JSON 소비자 호환.
  • `extract_full(&anyhow::Error) -> Option<&ParsecError>` 신규 helper. `extract_code` 는 그대로.
  • `main.rs`: typed error 면 `Display` 그대로 print (3-line 포맷 + code), 아니면 기존 `error: {err:#}`.
  • `bail_code!` 매크로 변경 없음.
  • `docs/error-format.md` 신규 (포맷, builder API, JSON shape, 레시피, do/don't).

출력 예

```
error: workspace 'CL-2283' not found [E005]
caused by: directory missing or .git/parsec/state.json out of sync (...)
help: run `parsec doctor`, or `parsec clean --orphans` to drop stale state
```

JSON:
```json
{ "error": true, "code": "E005", "message": "...", "caused_by": "...", "help": "..." }
```

테스트

  • 신규 9건 (1/2/3-line display, help-only, extract_full, JSON skip-if-none, bail_code 호환)
  • 전체 `cargo test`: 53 + 5 + 40 = 98 pass, 0 fail
  • `cargo fmt --check` clean

마이그레이션

  • 기존 `ParsecError::new(...)` 호출자 변경 X (additive)
  • 손 댈 때 `.with_caused_by(...).with_help(...)` 추가
  • 우선순위: `cli/commands/`, `worktree/` (highest user contact)
  • 별도 PR 시리즈로 점진 변환

관련

🤖 Generated with Claude Code

erishforG added 2 commits May 13, 2026 09:23
Issue #303. Add the infrastructure for the standard error format and
wire main.rs to render it. Existing call sites keep rendering as a
single line — migration is gradual (see docs/error-format.md).

Changes:
- `ParsecError` gains `caused_by: Option<String>` and `help: Option<String>`
  fields plus builder-style setters (`with_caused_by`, `with_help`).
  `Display` now writes one to three lines depending on which fields are
  populated.
- `JsonError` gains the same two fields with `skip_serializing_if =
  "Option::is_none"` so existing `--json` consumers see no schema change.
- `extract_full(&anyhow::Error) -> Option<&ParsecError>` helper for new
  callers; the legacy `extract_code` is kept untouched.
- `main.rs` prefers the typed error: when the error is a `ParsecError`,
  print it directly (its `Display` already includes the `error:` prefix
  + code); otherwise fall back to the legacy single-line `error: {err:#}`.
- `bail_code!` macro unchanged (for the "summary only" case).
- `docs/error-format.md` documents the format, builder API, JSON shape,
  recipes, and what NOT to do.

Tests: +9 in `errors::tests` covering 1/2/3-line display, help-only,
extract_full happy/None, backward-compat extract_code, JSON skip-if-none,
JSON with-fields, bail_code macro round-trip. Full suite 53 + 5 + 40 =
98 pass, fmt clean.

Migration: any existing `ParsecError::new(...)` site can opt in by
chaining `.with_caused_by(...)` and/or `.with_help(...)`. Prioritize
cli/commands/ and worktree/ first (highest user contact).
…act_code

Clippy `-D warnings` flagged `with_caused_by`, `with_help`, and
`extract_code` as never-used. Phase 1 of #303 is the infra-only PR —
call sites land in follow-up PRs. Annotation matches the existing
`#[allow(dead_code)]` on `ErrorCode` for the same forward-looking reason.
@erishforG erishforG merged commit 66d560b into develop May 13, 2026
11 checks passed
@erishforG erishforG deleted the 303-refactor/error-3line-format branch May 13, 2026 00:42
erishforG added a commit that referenced this pull request May 25, 2026
…317)

develop에 머지됐지만 CHANGELOG.md [Unreleased]에 누락된
항목 4개를 추가한다:

- parsec smartlog (alias sl): commit DAG 시각화 (#245, #305)
- parsec __complete: 동적 shell completion 헬퍼 (#291, #312)
- 에러 메시지 3줄 표준화 (error/caused by/help) (#303, #306)
- Windows VS2026 pre-validation CI job (#307, #311)

Closes #316

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant