From 739b7a04090d3f1062c3b9fa6b30d6ac569de4fa Mon Sep 17 00:00:00 2001 From: JK Date: Tue, 10 Feb 2026 22:23:47 +0900 Subject: [PATCH 1/3] =?UTF-8?q?docs(skills):=20XHTML=20Beautify-Diff=20Vie?= =?UTF-8?q?wer=20=EC=82=AC=EC=9A=A9=20=EA=B0=80=EC=9D=B4=EB=93=9C=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit reverse-sync 패치 검증, 테스트케이스 diff 확인 등에 활용하는 xhtml_beautify_diff.py 도구의 사용법을 skill 문서로 정리 Co-Authored-By: Claude Opus 4.6 --- .claude/skills/README.md | 2 + .claude/skills/xhtml-beautify-diff.md | 93 +++++++++++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 .claude/skills/xhtml-beautify-diff.md diff --git a/.claude/skills/README.md b/.claude/skills/README.md index 7b09e1c31..90bcd5779 100644 --- a/.claude/skills/README.md +++ b/.claude/skills/README.md @@ -14,6 +14,7 @@ ### 개발 Skills - **code-review.md** - 코드 변경 사항 검토 가이드라인 +- **xhtml-beautify-diff.md** - XHTML Beautify-Diff Viewer 사용 가이드 ## Skills과 참조 문서 관계 @@ -27,6 +28,7 @@ | sync-ko-to-en-ja.md | [docs/translation.md](/docs/translation.md) | | mdx-skeleton-comparison.md | [docs/translation.md](/docs/translation.md) | | documentation.md | [docs/DEVELOPMENT.md](/docs/DEVELOPMENT.md) | +| xhtml-beautify-diff.md | [confluence-mdx/bin/xhtml_beautify_diff.py](/confluence-mdx/bin/xhtml_beautify_diff.py) | | commit.md (commands) | [docs/commit-pr-guide.md](/docs/commit-pr-guide.md) (Commit 및 PR 작성) | ## 사용법 diff --git a/.claude/skills/xhtml-beautify-diff.md b/.claude/skills/xhtml-beautify-diff.md new file mode 100644 index 000000000..73da758d0 --- /dev/null +++ b/.claude/skills/xhtml-beautify-diff.md @@ -0,0 +1,93 @@ +# XHTML Beautify-Diff Viewer 사용 가이드 + +## 개요 + +`xhtml_beautify_diff.py`는 두 Confluence XHTML 파일의 **의미적 차이**만 비교하는 도구다. +XML serializer 부산물(속성 순서, self-closing 태그, entity 인코딩)을 정규화하여 소거하고, +실제 구조/텍스트 변경만 unified diff로 출력한다. + +## 사용법 + +```bash +cd confluence-mdx +python bin/xhtml_beautify_diff.py +``` + +### Exit codes + +| Code | 의미 | +|------|------| +| 0 | 차이 없음 | +| 1 | 차이 있음 (diff 출력) | +| 2 | 오류 (파일 없음 등) | + +## 주요 활용 시나리오 + +### 1. reverse-sync 패치 결과 검증 + +reverse-sync가 XHTML에 적용한 패치를 원본과 비교: + +```bash +python bin/xhtml_beautify_diff.py \ + var//page.xhtml \ + var//reverse-sync.patched.xhtml +``` + +### 2. Confluence 원본 vs 패치된 XHTML 비교 + +특정 페이지의 원본과 패치 결과를 비교하여 의도한 변경만 적용되었는지 확인: + +```bash +# 예: administrator-manual 페이지 +python bin/xhtml_beautify_diff.py \ + var/544178405/page.xhtml \ + var/544178405/reverse-sync.patched.xhtml +``` + +### 3. 테스트케이스의 expected diff 확인 + +각 테스트케이스 디렉토리에는 `expected.beautify-diff` 파일이 있다. +이 파일은 `page.xhtml`과 `expected.reverse-sync.patched.xhtml` 간의 기대 diff를 담고 있다: + +```bash +# 테스트케이스의 실제 diff와 기대 diff 비교 +python bin/xhtml_beautify_diff.py \ + tests/testcases//page.xhtml \ + tests/testcases//expected.reverse-sync.patched.xhtml +``` + +## 정규화 동작 + +이 도구가 자동으로 소거하는 serializer 부산물: + +- **속성 순서 차이**: `ac:align="center" ac:layout="center"` vs `ac:layout="center" ac:align="center"` → 동일 +- **Self-closing 태그**: `` vs `` → 동일 +- **Entity 인코딩**: `&`, `<`, `>`는 보존, `"` 등은 유니코드로 디코딩 + +## 출력 예시 + +```diff +--- var/544112828/page.xhtml ++++ var/544112828/reverse-sync.patched.xhtml +@@ -5,7 +5,7 @@ + Overview + +

+- QueryPie Agent를 설치하면, DataGrip, DBeaver와 같은 SQL Client... ++ QueryPie Agent를 설정하면, DataGrip, DBeaver와 같은 SQL Client... +

+``` + +## Python API + +스크립트 내에서 직접 사용할 수도 있다: + +```python +from xhtml_beautify_diff import beautify_xhtml, xhtml_diff + +# 단일 XHTML 정규화 +pretty = beautify_xhtml(xhtml_string) + +# 두 XHTML 비교 (차이 없으면 빈 리스트) +diff_lines = xhtml_diff(text_a, text_b, label_a="original", label_b="patched") +``` From 4ae1795a7752ead3417238690a3605f52a3843e1 Mon Sep 17 00:00:00 2001 From: JK Date: Tue, 10 Feb 2026 22:26:07 +0900 Subject: [PATCH 2/3] =?UTF-8?q?docs(skills):=20reverse-sync=20verify=20?= =?UTF-8?q?=ED=9B=84=20=ED=8C=A8=EC=B9=98=20=EB=B6=84=EC=84=9D=20=EC=9B=8C?= =?UTF-8?q?=ED=81=AC=ED=94=8C=EB=A1=9C=EC=9A=B0=20=EC=98=88=EC=8B=9C=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit verify 실행 → 산출물 구조 → beautify-diff 비교 → 출력 해석까지의 실전 워크플로우를 단계별로 기술 Co-Authored-By: Claude Opus 4.6 --- .claude/skills/xhtml-beautify-diff.md | 66 +++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/.claude/skills/xhtml-beautify-diff.md b/.claude/skills/xhtml-beautify-diff.md index 73da758d0..b1720f533 100644 --- a/.claude/skills/xhtml-beautify-diff.md +++ b/.claude/skills/xhtml-beautify-diff.md @@ -56,6 +56,72 @@ python bin/xhtml_beautify_diff.py \ tests/testcases//expected.reverse-sync.patched.xhtml ``` +## 실전 예시: reverse-sync verify 후 패치 분석 + +`reverse-sync verify`를 실행하면 `var//` 에 중간 산출물이 생성된다. +이 중 `page.xhtml`(원본)과 `reverse-sync.patched.xhtml`(패치 결과)를 비교하면 +XHTML 레벨에서 어떤 텍스트가 변경되었는지 직접 확인할 수 있다. + +### Step 1: verify 실행 + +```bash +cd confluence-mdx +python bin/reverse_sync_cli.py verify \ + "jk/fix-typo-and-grammar:src/content/ko/administrator-manual.mdx" +``` + +이 명령은 `var/544178405/` 디렉토리에 다음 파일들을 생성한다: + +``` +var/544178405/ +├── page.xhtml # Confluence 원본 XHTML +├── reverse-sync.diff.yaml # MDX 블록 변경 목록 +├── reverse-sync.mapping.original.yaml # 원본 XHTML 블록 매핑 +├── reverse-sync.patched.xhtml # 패치된 XHTML ← 비교 대상 +├── reverse-sync.mapping.patched.yaml # 패치 후 매핑 +├── reverse-sync.result.yaml # 검증 결과 +└── verify.mdx # 패치된 XHTML → MDX 재변환 결과 +``` + +### Step 2: beautify-diff로 XHTML 변경 확인 + +```bash +python bin/xhtml_beautify_diff.py \ + var/544178405/page.xhtml \ + var/544178405/reverse-sync.patched.xhtml +``` + +### Step 3: 출력 읽기 + +```diff +@@ -2,7 +2,7 @@ + 환영합니다. + +

+- QueryPie의 관리자는 QueryPie Web 또는 API를 통하여 리소스 및 권한, ... ++ QueryPie의 관리자는 QueryPie Web 또는 API를 통해 리소스 및 권한, ... +

+@@ -28,7 +28,7 @@ +

+- ... 설정해야하는 항목들이 있습니다. ... 설정하시는 것을 권장해 드립니다. ++ ... 설정해야 하는 항목들이 있습니다. ... 설정하는 것을 권장합니다. +

+``` + +이 diff를 통해 확인할 수 있는 것: + +- **패치가 올바른 위치에 적용되었는지**: `

` 태그 내의 정확한 텍스트가 변경됨 +- **의도하지 않은 변경이 없는지**: diff에 나타나지 않은 부분은 원본 그대로 보존됨 +- **인라인 구조가 보존되었는지**: ``, `` 등 인라인 태그가 유지됨 + +### verify 결과가 FAIL인 경우 + +verify가 FAIL이면 `reverse-sync.result.yaml`의 diff_report와 beautify-diff 출력을 함께 분석한다: + +1. **result.yaml의 diff_report** → MDX 레벨에서 어떤 텍스트가 기대와 다른지 확인 +2. **beautify-diff** → XHTML 레벨에서 패치가 실제로 어떻게 적용되었는지 확인 +3. 두 결과를 대조하여 패치 누락/오적용 원인을 특정 + ## 정규화 동작 이 도구가 자동으로 소거하는 serializer 부산물: From 1d27b6f41050761a804ec63ef47530dcbf346bc9 Mon Sep 17 00:00:00 2001 From: JK Date: Tue, 10 Feb 2026 22:27:27 +0900 Subject: [PATCH 3/3] =?UTF-8?q?docs(skills):=20python=20=E2=86=92=20python?= =?UTF-8?q?3=20=EC=9C=BC=EB=A1=9C=20=ED=86=B5=EC=9D=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 --- .claude/skills/xhtml-beautify-diff.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.claude/skills/xhtml-beautify-diff.md b/.claude/skills/xhtml-beautify-diff.md index b1720f533..7b8736b6e 100644 --- a/.claude/skills/xhtml-beautify-diff.md +++ b/.claude/skills/xhtml-beautify-diff.md @@ -10,7 +10,7 @@ XML serializer 부산물(속성 순서, self-closing 태그, entity 인코딩) ```bash cd confluence-mdx -python bin/xhtml_beautify_diff.py +python3 bin/xhtml_beautify_diff.py ``` ### Exit codes @@ -28,7 +28,7 @@ python bin/xhtml_beautify_diff.py reverse-sync가 XHTML에 적용한 패치를 원본과 비교: ```bash -python bin/xhtml_beautify_diff.py \ +python3 bin/xhtml_beautify_diff.py \ var//page.xhtml \ var//reverse-sync.patched.xhtml ``` @@ -39,7 +39,7 @@ python bin/xhtml_beautify_diff.py \ ```bash # 예: administrator-manual 페이지 -python bin/xhtml_beautify_diff.py \ +python3 bin/xhtml_beautify_diff.py \ var/544178405/page.xhtml \ var/544178405/reverse-sync.patched.xhtml ``` @@ -51,7 +51,7 @@ python bin/xhtml_beautify_diff.py \ ```bash # 테스트케이스의 실제 diff와 기대 diff 비교 -python bin/xhtml_beautify_diff.py \ +python3 bin/xhtml_beautify_diff.py \ tests/testcases//page.xhtml \ tests/testcases//expected.reverse-sync.patched.xhtml ``` @@ -66,7 +66,7 @@ XHTML 레벨에서 어떤 텍스트가 변경되었는지 직접 확인할 수 ```bash cd confluence-mdx -python bin/reverse_sync_cli.py verify \ +python3 bin/reverse_sync_cli.py verify \ "jk/fix-typo-and-grammar:src/content/ko/administrator-manual.mdx" ``` @@ -86,7 +86,7 @@ var/544178405/ ### Step 2: beautify-diff로 XHTML 변경 확인 ```bash -python bin/xhtml_beautify_diff.py \ +python3 bin/xhtml_beautify_diff.py \ var/544178405/page.xhtml \ var/544178405/reverse-sync.patched.xhtml ```