기능: cat --with-segments 세그먼트 맵 + 표 행 한 줄 불변식 고정

[YeolHanMyeong]

배경

외부 소비자(문서 코퍼스 → LLM 추출 → 관계형 DB 파이프라인)가 hwp cat --format markdown 출력을 코퍼스로 쓰면서 추출 근거를 "verbatim 인용 + 원본 문서 좌표(섹션/문단 인덱스)"로 기록한다. 이를 위한 두 계약을 추가한다.

요청 A — 세그먼트 맵 출력 모드

hwp cat <file> --format markdown --with-segments → stdout에 한 줄 컴팩트 JSON 봉투:

{"markdown": "...", "segments": [{"kind": "para", "section": 0, "para": 12, "start": 345, "end": 512}, ...]}

• 오프셋은 유니코드 스칼라(문자) 단위 — Python str 인덱싱과 동일(바이트 아님). 한국어 픽스처로 테스트 고정.
• 좌표는 IR(--format json)의 sections[]/paragraphs[] 인덱스 — 출력 블록 순번이 아닌 원본 안정 좌표.
• 정렬·비중첩·범위 내, 간극(빈 줄·구역 구분 등 미귀속) 허용. 후행 공백은 트림.
• 표가 만든 줄은 표를 담은 문단 인덱스 상속, 각주/미주 정의는 참조 문단 귀속, 머리말/꼬리말 기본 제외.
• markdown 필드는 무옵션 출력과 바이트 동일 — 방출 코어(emit_markdown)를 to_markdown_with와 공유해 구조적으로 보장.

구현 핵심: 방출 중 문단별 바이트 범위 기록 → cleanup(빈 줄 정리)을 삭제 구간 맵 산출형으로 확장해 오프셋 재매핑 → 최종 문자열에서 바이트→문자 단일 패스 변환.

요청 B — 표 행 한 줄 불변식

검증 중 main의 기존 출력이 불변식을 완전히 지키지 못함을 확인: 중첩 표가 바깥 <tr>을 여러 줄로 쪼개 report-tables.hwpx 기준 4개 줄에서 행 한 줄 균형이 깨져 있었다(의뢰 측 32/32 측정은 중첩 케이스 미포착 — <tr 태그 총수는 37). 중첩 표를 개행 없이 바깥 행 줄에 인라인 직렬화하도록 수정해 위반 0을 만들고, 그 외 출력은 구버전과 바이트 동일하다.

• 픽스처 전수 테스트: 모든 줄에서 <tr 수 == </tr> 수, GFM 파이프 행은 한 줄 완결. report-tables <tr> 총수 37 회귀 핀.
• README markdown 매핑 절에 보장 명시 + --with-segments 계약 소절 신설.

버전

0.1.0 → 0.2.0. 머지 후 v0.2.0 태그 예정(소비 측 hwp --version 고정용).

검증

• scripts/check.sh(fmt+clippy+test = CI 게이트) 통과.
• 소비자 시나리오 실검증: 봉투를 Python json.load 후 md[start:end] 코드포인트 슬라이싱으로 43개 세그먼트 전부 정합(정렬·비중첩·범위·후행 트림), 각주 정의 귀속·표 문단 상속 실출력 확인.
• 구버전(main) 바이너리와 report-tables 출력 비교 — 차이는 중첩 표 인라인화 영역뿐.

🤖 Generated with Claude Code