증상
hwp2md to-hwpx로 생성한 .hwpx 파일을 실제 한컴오피스 한글 프로그램에서 열면 "파일이 손상되었습니다" 오류로 열리지 않음. 실사용(마크다운 문서를 hwpx로 변환해 실제 배포)에서 발견됨.
문제는 hwp2md check가 해당 파일에 대해 OK를 반환한다는 점 — 즉 도구 자체의 검증으로는 잡히지 않는 결함.
재현 방법
cat > repro.md << 'EOF'
# 샘플 제목
## 1. 개요
ㅇ 테스트 문단입니다. 한글과 영문 mixed text 확인.
| 구분 | 항목A | 항목B |
|---|---|---|
| 행1 | 값1 | 값2 |
| 행2 | 값3 | 값4 |
- 목록 항목 1
- 목록 항목 2
**굵게** 및 *기울임* 텍스트.
EOF
hwp2md to-hwpx repro.md -o repro.hwpx
hwp2md check repro.hwpx # → OK (자체 검증 통과)
repro.hwpx를 실제 한컴오피스 한글로 열면 손상 오류가 발생함(제보 환경 기준). 표/서식이 섞인 실제 업무 문서에서도 동일 증상 재현됨 — 위 repro는 증상 재현을 위한 최소 합성 예시이며 실제 문제 문서는 별도.
zip 구조 자체는 육안상 이상 없음
mimetype (Stored, "application/hwp+zip")
META-INF/container.xml
version.xml
Contents/header.xml
Contents/content.hpf
Contents/section0.xml
mimetype이 압축 없이 첫 엔트리로 저장돼 있고, container.xml이 content.hpf를 올바르게 가리키며, 각 XML의 네임스페이스(http://www.hancom.co.kr/hwpml/2011/*)도 그럴듯해 보임 — 즉 "육안 검사"로는 원인을 특정하기 어려움. 실제 OWPML 스키마 위반이거나, 한컴 파서가 요구하는 필수 요소/순서가 자체 파서보다 더 엄격할 가능성이 높음.
근본 원인 추정 — 이미 알려진 갭
PLAN.md/PROGRESS.md에 이미 명시돼 있음:
한계: hwp2md가 한컴오피스로 원본을 렌더·대조할 수 없어 자율 완료 불가. 자기참조 골든을 끊으려면 사람이 검증한 정답 골든 필요.
R5: 사람 검증 골든 준비 — ... 사람 검증 단계는 사용자 위임(한컴 렌더 대조 불가).
즉 to-hwpx 경로는 실제 한컴오피스로 열어본 적이 없는 상태로 릴리즈됨(v0.5.0/v0.6.0 포함). check가 자기 자신이 쓴 파일을 자기 자신의 리더로 재파싱하는 자기참조 검증이라, "hwp2md 관점에서 유효"와 "한컴 관점에서 유효"가 분리돼 있었던 게 실사용에서 처음으로 드러난 사례.
영향도
to-hwpx를 실사용(실제 문서 배포)에 쓴 사용자가 변환 성공 로그 + check: OK를 보고 신뢰했다가, 받는 쪽에서 파일이 아예 안 열리는 것을 뒤늦게 발견함 — 조용한 실패(silent failure)로는 가장 나쁜 유형.- README/CLI에 이 갭이 사용자에게 고지되지 않음.
제안 — 이슈 해결 아이디어
- 실제 한컴 저작 hwpx 샘플과의 구조적 diff (가장 저비용·고효율): 공개적으로 배포되는 정부/공공기관 hwpx 서식 파일(예: 각 부처 공고문 hwpx 템플릿) 몇 개를 수집해, hwp2md가 생성한 최소 hwpx와 섹션별(특히
header.xml의 필수 refList 하위요소 순서, section0.xml의 hp:p/hp:run 필수 속성, hp:linesegarray 존재 여부)로 diff. 한컴 소프트웨어 라이선스 없이도 시도 가능.
- OWPML(KS X 6101) 스키마 검증 추가:
PLAN.md 참조 링크에 이미 있는 OWPML 스펙에서 XSD를 구할 수 있으면, to-hwpx 출력에 대해 자체 파서 재검증이 아니라 스키마 검증을 추가 — 자기참조 검증의 근본 한계를 스키마 레벨에서 부분적으로 해소.
- 제3자 hwpx 리더와의 교차검증: 한컴 없이도 hwpx를 읽을 수 있는 도구(예: 오피스 오픈소스 뷰어,
docs/en/...에 참조된 hwpforge/hwpConverter 등 3rd-party 라이브러리)가 있다면, 그 라이브러리로 hwp2md 출력물을 읽어보는 것만으로도 "자기참조"를 깨는 값싼 교차검증이 됨.
- 한컴오피스 체험판/평가판 확보 검토: 정식 라이선스가 없어도 한컴이 무료 체험판을 제공한다면, 최소 1회성 수동 검증 파이프라인(사람이 열어서 확인) 구축을 검토 — R5가 "사용자 위임"으로 막힌 근본 이유가 이거라, 이 자체를 sprint 목표로 삼을 가치가 있음.
- 당장의 완화책 — 사용자 고지: 근본 해결 전까지,
to-hwpx 실행 시 CLI 경고("이 출력은 실제 한컴오피스로 검증되지 않았습니다")를 추가하고 README에 명시 — 최소한 이번처럼 사용자가 실사용 배포 후에야 발견하는 일을 막음.
우선순위
HIGH — 정확성이 아니라 **"기능이 동작한다고 주장하지만 실제로는 산출물이 무용지물"**인 신뢰성 결함. to-hwpx를 실사용에 쓴 첫 실사례에서 바로 발견됨.
증상
hwp2md to-hwpx로 생성한.hwpx파일을 실제 한컴오피스 한글 프로그램에서 열면 "파일이 손상되었습니다" 오류로 열리지 않음. 실사용(마크다운 문서를 hwpx로 변환해 실제 배포)에서 발견됨.문제는
hwp2md check가 해당 파일에 대해OK를 반환한다는 점 — 즉 도구 자체의 검증으로는 잡히지 않는 결함.재현 방법
repro.hwpx를 실제 한컴오피스 한글로 열면 손상 오류가 발생함(제보 환경 기준). 표/서식이 섞인 실제 업무 문서에서도 동일 증상 재현됨 — 위 repro는 증상 재현을 위한 최소 합성 예시이며 실제 문제 문서는 별도.zip 구조 자체는 육안상 이상 없음
mimetype이 압축 없이 첫 엔트리로 저장돼 있고,container.xml이content.hpf를 올바르게 가리키며, 각 XML의 네임스페이스(http://www.hancom.co.kr/hwpml/2011/*)도 그럴듯해 보임 — 즉 "육안 검사"로는 원인을 특정하기 어려움. 실제 OWPML 스키마 위반이거나, 한컴 파서가 요구하는 필수 요소/순서가 자체 파서보다 더 엄격할 가능성이 높음.근본 원인 추정 — 이미 알려진 갭
PLAN.md/PROGRESS.md에 이미 명시돼 있음:즉
to-hwpx경로는 실제 한컴오피스로 열어본 적이 없는 상태로 릴리즈됨(v0.5.0/v0.6.0 포함).check가 자기 자신이 쓴 파일을 자기 자신의 리더로 재파싱하는 자기참조 검증이라, "hwp2md 관점에서 유효"와 "한컴 관점에서 유효"가 분리돼 있었던 게 실사용에서 처음으로 드러난 사례.영향도
to-hwpx를 실사용(실제 문서 배포)에 쓴 사용자가 변환 성공 로그 +check: OK를 보고 신뢰했다가, 받는 쪽에서 파일이 아예 안 열리는 것을 뒤늦게 발견함 — 조용한 실패(silent failure)로는 가장 나쁜 유형.제안 — 이슈 해결 아이디어
header.xml의 필수 refList 하위요소 순서,section0.xml의hp:p/hp:run필수 속성,hp:linesegarray존재 여부)로 diff. 한컴 소프트웨어 라이선스 없이도 시도 가능.PLAN.md참조 링크에 이미 있는 OWPML 스펙에서 XSD를 구할 수 있으면,to-hwpx출력에 대해 자체 파서 재검증이 아니라 스키마 검증을 추가 — 자기참조 검증의 근본 한계를 스키마 레벨에서 부분적으로 해소.docs/en/...에 참조된hwpforge/hwpConverter등 3rd-party 라이브러리)가 있다면, 그 라이브러리로 hwp2md 출력물을 읽어보는 것만으로도 "자기참조"를 깨는 값싼 교차검증이 됨.to-hwpx실행 시 CLI 경고("이 출력은 실제 한컴오피스로 검증되지 않았습니다")를 추가하고 README에 명시 — 최소한 이번처럼 사용자가 실사용 배포 후에야 발견하는 일을 막음.우선순위
HIGH — 정확성이 아니라 **"기능이 동작한다고 주장하지만 실제로는 산출물이 무용지물"**인 신뢰성 결함.
to-hwpx를 실사용에 쓴 첫 실사례에서 바로 발견됨.