Skip to content

confluence-mdx: sidecar mapping을 텍스트 비교에서 타입 기반 순차 정렬로 교체합니다#901

Open
jk-kim0 wants to merge 5 commits intomainfrom
jk/feat-sidecar-type-based-core
Open

confluence-mdx: sidecar mapping을 텍스트 비교에서 타입 기반 순차 정렬로 교체합니다#901
jk-kim0 wants to merge 5 commits intomainfrom
jk/feat-sidecar-type-based-core

Conversation

@jk-kim0
Copy link
Contributor

@jk-kim0 jk-kim0 commented Mar 11, 2026

배경

generate_sidecar_mapping()이 XHTML 블록과 MDX 블록을 매칭할 때
텍스트 유사도 비교를 사용해 정확도가 낮고 유지보수가 어려웠습니다.

변경 내용

mapping.yaml v3 스키마

각 매핑 엔트리에 다음 필드 추가:

  • xhtml_type: XHTML 블록의 타입
  • mdx_line_start / mdx_line_end: 대응하는 MDX 블록의 줄 번호
  • children: 자식 블록 정렬 정보 (xhtml_xpath, xhtml_block_id, mdx_line_start, mdx_line_end)

타입 기반 two-pointer 알고리즘

_TYPE_COMPAT 테이블로 XHTML/MDX 블록 타입 호환성을 선언하고,
두 포인터(XHTML 순서 vs MDX 블록 순서)를 순차적으로 진행하며 매칭합니다.

heading   ↔ heading
paragraph ↔ paragraph
list      ↔ list
code      ↔ code_block
table     ↔ table | html_block
html_block ↔ callout | details | figure | badge | hr | ...

특수 케이스 처리

  • _SKIP_MACROS: TOC/children 매크로는 MDX 블록 없음으로 처리
  • 빈 단락(paragraph) XHTML 블록: MDX 콘텐츠 없음으로 처리
  • _align_children(): 자식 블록도 타입 기반으로 정렬
  • MDX H1 페이지 제목 헤딩 예외 처리 추가

Phase 2–3

  • sidecar 소비자 업데이트 및 텍스트 기반 폴백 제거
  • 기존 텍스트 기반 매칭 코드 삭제
  • page.v1.yaml 복사 및 blockquote 빈 줄 정규화

포함 커밋 (메인 구현만)

  1. sidecar mapping 생성 교체 (Phase 1)
  2. MDX H1 예외 처리 및 expected 파일 갱신
  3. Phase 2 — sidecar 소비자 업데이트 및 텍스트 기반 폴백 제거
  4. Phase 3 — 텍스트 기반 매칭 코드 삭제
  5. Phase 3 — page.v1.yaml 복사 및 blockquote 빈 줄 정규화

Added/updated tests?

  • Yes — sidecar 단위 테스트 및 expected 파일 갱신 포함

관련 PR

🤖 Generated with Claude Code

jk-kim0 and others added 5 commits March 11, 2026 19:13
@jk-kim0 @claude
confluence-mdx: sidecar mapping 생성을 텍스트 비교에서 타입 기반 순차 정렬로 교체합니다
d6f0889 
mapping.yaml v3 스키마를 도입하고, generate_sidecar_mapping()을
텍스트 유사도 매칭 대신 XHTML 블록 타입과 MDX 블록 타입의
호환성(_TYPE_COMPAT 테이블)을 기반으로 한 two-pointer 순차 정렬로
교체합니다.

주요 변경 사항:
- _TYPE_COMPAT: XHTML → MDX 블록 타입 호환성 매핑 테이블 추가
- _SKIP_MACROS: TOC/children 매크로 스킵 처리 추가
- SidecarChildEntry 데이터클래스: 자식 블록 정렬 정보 저장
- SidecarEntry: mdx_line_start, mdx_line_end, children 필드 추가
- generate_sidecar_mapping(): 타입 기반 두 포인터 알고리즘으로 재작성
- load_sidecar_mapping(): v3 스키마 필드 읽기 지원 추가
- 빈 단락(paragraph) XHTML 블록은 MDX 콘텐츠 블록 없음으로 처리
- 테스트 업데이트: version 2→3, Callout MDX 형식, mdx_line_start 검증

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jk-kim0 @claude
confluence-mdx: MDX H1 페이지 제목 헤딩 예외 처리 및 expected 파일 갱신
2520a0d 
generate_sidecar_mapping()에서 MDX의 첫 번째 H1 헤딩(# 로 시작)은
Confluence XHTML 본문에 대응하지 않는 페이지 제목이므로, two-pointer
루프 시작 전에 건너뛰도록 예외 처리합니다.

이로 인해 사이드카 정렬이 모든 케이스에서 올바르게 동작하며,
integration test 16/16 통과 (기존 12/16 → 16/16).

544112828 expected 파일을 새 알고리즘 출력으로 갱신합니다.
(verification exact_match: true, 기존 expected는 구버전 알고리즘 기준)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jk-kim0 @claude
confluence-mdx: Phase 2 — sidecar 소비자 업데이트 및 텍스트 기반 폴백 제거
c896897 
- reverse_sync_cli.py: SidecarEntry 생성 시 children(SidecarChildEntry) 로드 추가
- patch_builder.py: _resolve_mapping_for_change() 단순화
  - callout 블록 조기 반환(containing 전략) 추가
  - mapping is None 시 _find_containing_mapping() 폴백 제거
  - 텍스트 불일치 시 _find_containing_mapping() 재매핑 제거
  - _resolve_child_mapping() import 복원(Phase 3 삭제 예정)
- list_patcher.py: build_list_item_patches()에서 _find_containing_mapping() 폴백 제거
- 테스트: 텍스트 폴백 제거에 따른 기대값 업데이트(skip/0 patches)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@jk-kim0 @claude
confluence-mdx: Phase 3 — 텍스트 기반 매칭 코드 삭제
13613fc 
- sidecar.py: _find_text_match(), _count_child_mdx_blocks(), _strip_all_ws() 삭제
- patch_builder.py: _find_containing_mapping(), _strip_block_markers() 삭제
  - _resolve_mapping_for_change() 서명에서 id_to_mapping 파라미터 제거
  - mapping.children 존재 시 containing 전략으로 단순화
- list_patcher.py: _resolve_child_mapping() 삭제
  - build_list_item_patches() 단순화: 항목 변경 시 전체 리스트 재생성
  - 미사용 import 제거 (collapse_ws, convert_inline, strip_list_marker, strip_for_compare)
- 테스트: 삭제된 함수 테스트 클래스 제거 및 기대값 업데이트

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@jk-kim0 @claude
confluence-mdx: Phase 3 — page.v1.yaml 복사 및 blockquote 빈 줄 정규화
9b6263c 
- `reverse_sync_cli.py`: 패치된 XHTML의 forward 변환 전, `page.v1.yaml`을
  `var/<page_id>/`로 복사합니다. Forward converter가 크로스 페이지 링크 해석 시
  `page.v1.yaml`을 XHTML과 같은 디렉터리에서 읽으므로, 이를 보장합니다.
- `roundtrip_verifier.py`: `_normalize_blank_line_after_blockquote()` 추가 —
  blockquote(`>`) 줄 바로 다음의 단일 빈 줄을 제거합니다. Forward converter가
  blockquote 뒤에 빈 줄을 체계적으로 추가하므로, 비교 시 이를 정규화합니다.

- 1454342158: `#unexpected-failure` 링크 → 정상 크로스 페이지 링크로 수정
- 1907294209: blockquote 뒤 빈 줄 차이 제거 → PASS

- feature/type-based-sidecar-mapping

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@jk-kim0 jk-kim0 mentioned this pull request Mar 11, 2026
Open
1 task
@vercel
Copy link

vercel bot commented Mar 11, 2026 •
edited
Loading

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

Project Deployment Actions Updated (UTC)
querypie-docs Ready Ready Preview, Comment Mar 11, 2026 10:18am

Request Review

@jk-kim0 jk-kim0 mentioned this pull request Mar 11, 2026
Open
1 task
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@keIIy-kim keIIy-kim Awaiting requested review from keIIy-kim keIIy-kim is a code owner

@robb-lee robb-lee Awaiting requested review from robb-lee robb-lee is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jk-kim0