hwp2hwpx-js

HWP 파일을 HWPX로 변환하는 도구입니다. hwplib / hwp2hwpx / hwpxlib Java 라이브러리의 JavaScript 포트입니다.

설치

npm install

사용법

node src/index.js <입력.hwp> [출력.hwpx]

node src/index.js document.hwp output.hwpx

지원 기능

• 문서 정보 (DocInfo) 파싱 — 글꼴, 글자 모양, 문단 모양, 스타일, 글머리표, 테두리/배경, 메모 등
• 본문 (BodyText) 파싱 — 섹션, 문단, 텍스트, 표(셀 내용 포함), 구역 정의, 각주/미주 등
• GSO 개체 (도형, 그림, OLE, 텍스트 아트, 컨테이너, 수식, 글자겹침 등) 및 Form 컨트롤 변환
• 머리말/꼬리말, 필드, 숨은 설명, 덧말, 쪽 번호/숨김 등 컨트롤 변환
• 표 캡션(hp:caption), 개체 캡션, 바탕쪽(마스터 페이지) 지원
• HWPX XML 생성 — header.xml, section.xml, content.hpf, settings.xml 등
• 임베디드 바이너리(BinData) 추출 및 zlib 압축 해제, content.hpf 미디어 타입 처리
• ZIP 패키징

검증

realsample/의 HWP 문서를 기준으로, 원본 hwp2hwpx Java 도구의 출력(api_converted_hwpx)과 모든 XML·바이너리 파일이 바이트 단위로 일치합니다. 현재 70개 샘플 전부가 실패 항목 0으로 검증됩니다.

• 모든 파일의 header.xml / section.xml / content.hpf / settings.xml 비교
• BinData(이미지 등) 바이너리 동일성 검증
• 비교 스크립트: realsample/*.hwp 변환 → 압축 해제 → XML 정렬(pretty-print) → diff

Java 참조 구현의 동작을 그대로 재현하기 위해 다음 사항을 반영했습니다:

• 공유 변환 상태(shared state) — 표·개체 내부 재귀 변환 시 Java ForChars 인스턴스 상태가 덮어써지는(clobber) 동작을 그대로 모사하여, 표 뒤 텍스트가 마지막 셀의 run으로 누수되는 현상 등을 재현
• 부호/비트 필드 처리 — lineseg flags, tabItem pos, 머리글 적용 쪽(applyPageType), 캡션 fullSz, 취소선/밑줄 모양 비트 등
• 비연속 enum 값 매핑 — slash/backSlash 대각선 타입, 글자 모양 속성 등 Java enum의 실제 정수 값을 조회
• 속성 생략 규칙 — Java XMLStringBuilder.attribute()는 null이면 속성을 생략하므로, checkedChar/binaryItemIDRef/fieldBegin type 등 빈 속성 대신 속성 자체를 생략
• UTF-16LE 디코딩 — 고립 서로게이트(예: 글자겹침 문자)를 Java와 동일하게 U+FFFD로 치환
• BinData 압축 — 위치 기반(리스트 순번) 압축 방식 조회, 실패 시 Java와 동일하게 512바이트 스킵 + 0 패딩 fallback 재현
• 개체/그림 배치 — 캡션 방향·정렬·텍스트 방향, 그림 여백(Java의 right←top 오류 포함), 개체 zOrder 등

테스트

npm test

node --test 기반 단위 테스트 43개가 포함되어 있습니다.

• test/streamreader.test.js — 스트림 판독기 기본 읽기, 레코드 헤더(4095 확장), HWP 문자열/와이드 문자, 비트/비트필드 헬퍼
• test/controltypes.test.js — 컨트롤 ID, 문자 타입 분류(일반/확장/인라인/제어), 필드/GSO/폼 판별
• test/xmlwriter.test.js — XML 생성, 속성 생략 규칙(null 생략), 이스케이프, 네임스페이스
• test/conversion.test.js — 통합 변환(빈 문서·표·각주·필드·다중 섹션 등), 매니페스트 검증

변경 내역

• 0.1.0 — 초기 릴리스: 70개 샘플 전부가 Java 참조 구현과 바이트 단위로 일치 (실패 0)
  • shared-state clobber 모사 — 표·개체 재귀 변환 시 ForChars 상태 덮어쓰기 동작을 재현해 표 뒤 텍스트 누수 현상까지 동일하게 출력
  • GSO 개체 누락 재현 — 중첩 개체 변환 후 덮어써진 문단의 컨트롤 목록을 참조해, Java가 버리는 개체를 동일하게 생략
  • 부호/비트 필드 — lineseg flags, tabItem pos, applyPageType, 캡션 fullSz, 취소선/밑줄 비트
  • 비연속 enum 값 — slash/backSlash, 글자 모양 속성의 실제 정수 값 조회
  • 속성 생략 규칙 — checkedChar/binaryItemIDRef/fieldBegin type 등 null 속성 생략
  • UTF-16LE 디코딩 — 고립 서로게이트를 Java와 동일하게 U+FFFD 치환 (글자겹침 등)
  • BinData 처리 — 확장자 대소문자 구분 media-type, 압축 실패 시 512바이트 스킵 + 0 패딩 fallback
  • 표 캡션/수식 — 캡션 파싱·정렬·방향, 수식 zOrder
  • npm 배포 준비 — files 필드로 패키지 크기 축소(28.2MB → 46.6kB), MIT 라이선스, repository 메타데이터
• 0.1.1 — BinData 압축 판별 버그 수정: 리스트 순번(id-1)이 아닌 각 binData의 compress 필드를 사용
  • Java 참조 구현은 binDataList.get(id-1) 위치 기반 조회로, id 순서가 꼬인 파일(예: 00005)에서 잘못된 압축 방식을 적용해 이미지를 손상시켰음
  • 이제 각 binData 항목의 자체 compress 필드(0=기본, 1=압축, 2=무압축)로 판별 — 00005의 image1.png/image3.bmp가 정상 추출됨 (참조 구현과는 의도적으로 어긋남)

제한사항 (현재 JS 포트)

• 암호 문서 미지원 (원본과 동일)

라이선스

MIT