feat: ir-diff --summary / --max-lines 출력 가드 추가

[planet6897]

요약

PR #659 (Task #653 — ir-diff 표 속성/컨트롤 식별 비교) 머지 후 보강. local/task653 (planet6897 의 미PR 브랜치) 에서 도입된 출력 가드 옵션을 stream/devel 정합 형식으로 이식.

동기

rhwp ir-diff 의 광범위 회귀 검증 시 (예: aift.hwpx vs aift.hwp 707 건 차이) 출력량 폭증으로 본질 영역 식별이 어렵다. 카테고리별 카운트 + 출력 라인 제한 모드를 추가하여 처음 검사 / 회귀 측정 효율 개선.

기능

--summary

카테고리별 차이 카운트만 출력. paragraph 헤더 + 개별 차이 라인 생략.

$ rhwp ir-diff samples/hwpx/aift.hwpx samples/aift.hwp --summary
=== 카테고리별 차이 요약 ===
    260건  char_shapes count
     69건  ml
     61건  indent
     48건  tbl page_break
     44건  ps_id
     ...

=== 비교 완료: 차이 707 건 ===

--max-lines <N>

출력 라인 수를 N 으로 제한. 초과 시 truncation 마커 표시. === 비교 완료 합계 라인은 항상 출력 (가드 외부).

$ rhwp ir-diff samples/hwpx/aift.hwpx samples/aift.hwp --max-lines 10
=== IR 비교: aift.hwpx vs aift.hwp ===

--- 문단 0.0 --- "  * 사업계획서 제출 시 상기 문구 삭제"
  [차이] cc: A=32 vs B=56
  [차이] char_offsets[0]: A=8 vs B=32
  ...
... 이하 생략 (--max-lines 10 도달)

=== 비교 완료: 차이 707 건 ===

구현

src/main.rs::ir_diff

• summary_mode / max_lines 플래그 파싱 추가
• 함수 내부에 emit_header! / emit_diff! 매크로 도입
• 기존 println! 사이트 6곳을 매크로로 교체 (차이 검출 로직 무변경)
• 카테고리 추출: ":" 앞쪽 prefix 의 "]" 이후 (예: controls[N].xxx → xxx)
• summary 모드 마지막에 BTreeMap 정렬 후 출력 (count 내림차순 → 알파벳)

tests/ir_diff_summary_mode.rs (신규)

3건 통합 테스트:

• summary_mode_categorizes_diffs — 요약 헤더 + 카운트 라인 + paragraph 헤더 부재
• max_lines_truncates — truncation 마커 + 합계 라인 보존
• no_flags_preserves_full_output — 회귀 가드: 옵션 없으면 기존 형식 보존

문서

• mydocs/manual/ir_diff_command.md: 옵션 표 + 사용 예 추가
• CLAUDE.md: 디버깅 워크플로우 ir-diff 예시 +2 줄

검증

$ cargo test --release
test result: ok. (22 스위트, 0 failures)

$ cargo test --release --test ir_diff_summary_mode
test result: ok. 3 passed; 0 failed

영향 범위

• ir-diff 차이 검출 로직 무변경 (PR feat: ir-diff 표 속성 / 컨트롤 식별 비교 추가 (closes #653) #659 의 비교 영역 그대로 보존)
• 옵션 없으면 기존 출력 형식 100% 보존 (회귀 가드 테스트로 입증)
• 새 옵션은 출력 단계 가드만 적용 (orthogonal 추가)

Test plan

• cargo test --release 전체 22 스위트 0 failures
• --summary aift 권위 케이스 707 건 → 22 카테고리 요약 정상
• --max-lines 20 truncation 마커 + 합계 라인 보존 확인
• 옵션 없을 때 기존 형식 (IR 비교 헤더 + 문단 헤더 + 차이 라인) 보존

[edwardkim]

@planet6897 PR 머지 완료되었습니다 (devel 2ca126c3, --no-ff merge).

처리 결과

• 옵션 A — 1 commit cherry-pick + no-ff merge
• 회귀 가드 tests/ir_diff_summary_mode.rs 3/3 PASS
• 시각 판정 게이트 면제 (UI 무관 CLI 옵션 추가)

검증

• cargo test --release: lib 1166 + 통합 ALL GREEN, failed 0
• cargo test --release --test ir_diff_summary_mode: 3/3 PASS
• cargo clippy --release: 신규 경고 0
• 수동 검증 PR 본문 정합:
  • --summary 22 카테고리 카운트 출력 (260 char_shapes count + 69 ml + 61 indent + ...)
  • --max-lines 20 truncation 마커 + === 비교 완료: 차이 707 건 === 합계 보존
  • 옵션 부재 시 1436 라인 (기존 형식 100% 보존)

메모리 룰 정합

• feedback_visual_regression_grows: UI 무관 CLI 옵션 → 시각 판정 게이트 면제
• feedback_pr_supersede_chain: PR feat: ir-diff 표 속성 / 컨트롤 식별 비교 추가 (closes #653) #659 (Task ir-diff 보강 — 표 속성 / paragraph line_segs / controls 식별 가능 단위 비교 영역 추가 #653) → PR feat: ir-diff --summary / --max-lines 출력 가드 추가 #695 (출력 가드 후속 보강) 신규 사례

광범위 회귀 검증 효율 개선되었습니다. 처리 보고서: mydocs/pr/archives/pr_695_report.md. 감사합니다.