confluence-mdx: roundtrip verifier 정규화를 정비합니다

[jk-kim0]

Description

bin/reverse-sync verify --branch=split/ko-proofread-20260221-administrator-manual-general 실행 시 발생하는 verify diff의 원인을 조사하고, roundtrip verifier 정규화를 정비합니다.

목표

verifier 정규화를 정비하여, MDX 교정이 실질적으로 Confluence XHTML 수정으로 이어지는지 검증 가능하게 합니다. 장기적으로는 패처/변환기의 근본 원인을 수정하여 정규화를 줄여나가는 것이 목표입니다.

불일치 현상 및 원인

--no-normalize 모드(PR #983)로 정규화를 전부 비활성화하면 45건 중 6건 FAIL (총 diff 11쌍)이 발생합니다. 유형별 분석:

참고: PR #974 최초 작성 시 11건 FAIL이었으나, PR #985(인라인 공백 감지), #982(Badge roundtrip) 등이 main에 머지되면서 5건이 해소되어 현재 6건입니다.

유형 A: <li><p> 선행 공백 (3건, diff 3쌍)

Confluence XHTML 원본의 <li><p> 안에 선행 공백이 있어 FC가 이중 공백을 출력하는 패턴입니다.

파일	XHTML 원본	diff (improved → verify)	원인
api-token.mdx	<li><p> Admin >	* Admin → * Admin	<p> 내 선행 공백
integrating-with-google-saml.mdx	<p>7. 생성이	7. 생성이 → 7. 생성이	<p> 내 이중 공백
custom-attribute.mdx	<li><p> Workflow	* Workflow → * Workflow	<p> 내 선행 공백

기본 모드 처리: _normalize_consecutive_spaces_in_text (연속 공백 → 단일 공백)
근본 해결: 패처가 XHTML <p> 내 선행/연속 공백을 정규화하여 패치, 또는 FC가 <p> 내 leading whitespace를 trim

유형 B: <br/> 인접 공백 (2건, diff 3쌍)

FC가 XHTML의 <br/> 태그 전후 텍스트 노드를 결합할 때 공백이 추가/변형되는 패턴입니다.

파일	XHTML 원본	diff (improved → verify)	원인
integrating-with-event-callback.mdx	<code>Delete</code>버튼을 클릭합니다</p><ac:image (XHTML에 <br/> 없음)	클릭합니다.<br/> → 클릭합니다. <br/>	FC가 <br/> 앞에 공백 추가
setting-up-multi-factor-authentication.mdx (2쌍)	인 경우<br /> </p>, 경우<br /></p>	<br/> <br/> → <br/> <br/>	FC가 <br/> 사이 공백 노드를 이중 공백으로 출력

기본 모드 처리: _normalize_br_space (<br/> 앞 공백 제거)
근본 해결: FC의 <br/> 인접 공백 처리 개선, 또는 패처가 <br/> 인접 공백을 정규화

유형 C: 테이블 셀 패딩 (1건, diff 5쌍)

FC의 컬럼 폭 계산(_display_width)과 improved.mdx의 수동 패딩이 수 글자 차이나는 패턴입니다.

파일	diff	원인
maintenance.mdx	헤더 행 + 구분자 행 + 데이터 행 3개의 셀 패딩 공백 수 차이	FC와 improved.mdx의 CJK 포함 컬럼 폭 계산이 2~4자 차이

기본 모드 처리: _normalize_table_cell_padding (셀 패딩 공백 정규화)
근본 해결: 테이블 패딩은 시각적 서식이므로 정규화가 올바른 접근 (해결 불필요)

유형별 요약

유형	건수	diff 쌍	기본 모드 정규화	근본 해결 방향
A: <li><p> 선행 공백	3	3	_normalize_consecutive_spaces_in_text	패처/FC 개선
B: <br/> 인접 공백	2	3	_normalize_br_space	FC 개선
C: 테이블 셀 패딩	1	5	_normalize_table_cell_padding	정규화 유지 (해결 불필요)

변경 내용

roundtrip_verifier.py:

• _normalize_empty_list_items: 빈 줄 치환(^([ \t]+)\d+\.\s*$ → '') → 줄째 제거(^[ \t]+\d+\.\s*\n → '')로 개선 — 기존 정규식은 빈 줄을 남겨서 연속 빈 줄 문제를 유발
• _normalize_consecutive_blank_lines 추가: 3개 이상 연속 개행 → 2개로 정규화
• _normalize_blank_line_after_br 추가: <br/> 뒤 빈 줄 제거

test_reverse_sync_roundtrip_verifier.py:

• _normalize_empty_list_items 단위 테스트 3건
• _normalize_consecutive_blank_lines 단위 테스트 3건
• _normalize_blank_line_after_br 단위 테스트 3건
• verify_roundtrip 통합 테스트 3건 (각 패턴이 정규화로 PASS되는지 검증)

검증

main 기준 (PR #974 적용 전):
  기본 모드: 45/45 PASS
  --no-normalize: 39/45 (6 FAIL — 유형 A:3 B:2 C:1)

PR #974 브랜치 기준:
  기본 모드: 45/45 PASS
  --no-normalize: 39/45 (6 FAIL — 동일)

참고: PR #974의 정규화 추가분(_normalize_consecutive_blank_lines, _normalize_blank_line_after_br, _normalize_empty_list_items 수정)은 현재 main에서 이미 해결된 문제를 다루고 있어 FAIL/PASS 결과에 영향을 주지 않습니다. 이 PR을 머지할 실질적 이유가 남아 있는지 재검토가 필요합니다.

Added/updated tests?

• Yes — 단위 테스트 9건 + 통합 테스트 3건 추가

Additional notes

• 테이블 셀 CJK 패딩 원인인 FC len() → _display_width() 수정은 별도 PR #975로 머지 완료
• PR #982에서 heading 내 Badge 컴포넌트 roundtrip 소실이 수정되어, 기존 FAIL(alerts.mdx)이 해소됨
• PR #985에서 인라인 공백 감지가 수정되어, 기존 유형 A의 5건이 3건으로 감소 (general.mdx, identity-providers.mdx, approval-rules.mdx, workflow-configurations.mdx, integrating-with-okta.mdx 해소)
• --no-normalize 옵션은 PR #983에서 별도로 추가

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
querypie-docs	Ready	Preview, Comment	Apr 6, 2026 3:30pm