Align tooling with engine package semantics

Author: airmang

.github/workflows/tests.yml

@@ -36,8 +36,8 @@ jobs:
 
       - name: Run tests and keep summary log
         env:
-          # 단계적 도입: 기준을 50 -> 60 -> 70으로 상향합니다.
-          COVERAGE_FAIL_UNDER: 50
+          # 이번 hardening 범위에서 안정적으로 지킬 수 있는 수준까지 현실적으로 상향합니다.
+          COVERAGE_FAIL_UNDER: 60
         run: |
           pytest -v -ra --cov=hwpx --cov-report=term-missing --cov-fail-under=${COVERAGE_FAIL_UNDER} 2>&1 | tee pytest-summary.log
 

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 모든 중요한 변경 사항은 이 문서에 기록됩니다. 형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)과 [Semantic Versioning](https://semver.org/lang/ko/)을 따릅니다.
 
+## [2.8] - 2026-03-08
+### 변경
+- `HwpxPackage`와 OXML 로딩/저장이 rootfile/manifest-relative 경로를 실제로 따르도록 정렬했습니다.
+- `hwpx-analyze-template --extract-dir`가 pack-ready 작업 디렉터리와 `.hwpx-pack-metadata.json`을 생성하도록 확장했습니다.
+- `hwpx-validate-package`를 엔진 정합 기준으로 재작성해 dynamic rootfile/manifest 관계, CRC, fallback warning을 구분하도록 했습니다.
+- `hwpx-unpack` 기본값을 raw-byte preserving으로 바꾸고 `--pretty-xml` opt-in을 추가했습니다.
+- tooling/OPC 회귀 테스트를 확대하고, coverage threshold를 60으로 올렸으며, pyright는 touched OPC/tooling 범위에서 `basic`으로 상향했습니다.
+
 ## [2.7.1] - 2026-03-08
 ### 변경
 - 공개 저장소와 배포 산출물에서 내부 감사 문서를 제거했습니다.

README.md

@@ -217,12 +217,15 @@ hwpx-validate 문서.hwpx
 # ZIP/OPC/HWPX 패키지 구조 검사
 hwpx-validate-package 문서.hwpx
 
-# HWPX 풀기 / 다시 묶기
+# HWPX 풀기 / 다시 묶기 (기본값: XML/HWPF 바이트 보존)
 hwpx-unpack 문서.hwpx ./unpacked
+hwpx-unpack 문서.hwpx ./pretty-unpacked --pretty-xml
 hwpx-pack ./unpacked ./repacked.hwpx
 
-# 레퍼런스 템플릿 분석과 파트 추출
+# 레퍼런스 템플릿 분석과 pack-ready 추출
 hwpx-analyze-template 문서.hwpx --extract-dir ./template-parts --json
+hwpx-pack ./template-parts ./template-roundtrip.hwpx
+hwpx-validate-package ./template-roundtrip.hwpx
 
 # plain / markdown 텍스트 추출
 hwpx-text-extract 문서.hwpx --format markdown --output 문서.md
@@ -233,6 +236,10 @@ hwpx-page-guard --reference 원본.hwpx --output 결과.hwpx
 
 `hwpx-page-guard`는 렌더된 실제 쪽수를 계산하지 않습니다. 대신 단락 수, 표 수, shape/control 수, 명시적 page/column break, 텍스트 길이 통계를 비교해 레이아웃 드리프트 위험을 탐지하는 프록시 도구입니다.
 
+`hwpx-validate-package`는 `Contents/content.hpf` 같은 고정 경로를 강제하지 않고, `META-INF/container.xml`과 선택된 rootfile/manifest 관계를 따라가며 검사합니다. 엔진이 fallback으로 열 수 있는 비표준 패키지는 가능한 경우 경고로 구분합니다.
+
+`hwpx-analyze-template --extract-dir`는 covered fixture 기준으로 `hwpx-pack`과 `hwpx-validate-package`, 그리고 엔진 open 경로에 다시 투입할 수 있는 pack-ready 작업 디렉터리를 만듭니다. 이건 재패킹 가능성을 목표로 한 것이지, 렌더링 fidelity를 보장한다는 뜻은 아닙니다.
+
 ## 문서
 
 | | |

docs/usage.md

@@ -10,12 +10,15 @@ python-hwpx는 HWPX 컨테이너를 검증하고 편집하기 위한 여러 계
 # 패키지 구조 점검
 hwpx-validate-package sample.hwpx
 
-# XML-first 편집용 unpack / pack
+# XML-first 편집용 unpack / pack (기본값: XML/HWPF 바이트 보존)
 hwpx-unpack sample.hwpx ./sample-unpacked
+hwpx-unpack sample.hwpx ./sample-pretty --pretty-xml
 hwpx-pack ./sample-unpacked ./sample-repacked.hwpx
 
-# 템플릿 분석과 파트 추출
+# 템플릿 분석과 pack-ready 작업 디렉터리 추출
 hwpx-analyze-template sample.hwpx --extract-dir ./template-parts --json
+hwpx-pack ./template-parts ./template-roundtrip.hwpx
+hwpx-validate-package ./template-roundtrip.hwpx
 
 # 텍스트 추출
 hwpx-text-extract sample.hwpx --format markdown --output sample.md
@@ -26,6 +29,10 @@ hwpx-page-guard --reference sample.hwpx --output edited.hwpx
 
 `hwpx-page-guard`는 실제 렌더러의 쪽수를 계산하지 않고, 구조 및 텍스트 통계를 비교해 레이아웃 변화 위험을 탐지하는 프록시 검사기입니다.
 
+`hwpx-validate-package`는 고정 기본 경로를 가정하지 않고 `container.xml`과 rootfile/manifest 관계를 따라가며 검사합니다. 엔진이 fallback으로 열 수 있는 비표준 패키지는 에러 대신 경고로 분리할 수 있습니다.
+
+`hwpx-analyze-template --extract-dir`는 `mimetype`, `META-INF/container.xml`, rootfile, manifest-related parts, 중요 자산, `.hwpx-pack-metadata.json`을 포함한 pack-ready 작업 디렉터리를 만듭니다. covered fixture 기준으로 재패킹/재검증 가능한 범위를 목표로 하며, 렌더링 fidelity를 보장하지는 않습니다.
+
 ## 빠른 예제 모음
 
 ### 예제 1: 문단 수 세기

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "2.7.1"
+version = "2.8"
 description = "Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }
@@ -78,15 +78,37 @@ testpaths = ["tests"]
 
 [tool.mypy]
 python_version = "3.10"
-files = ["src/hwpx/document.py", "src/hwpx/oxml/document.py"]
+files = [
+    "src/hwpx/document.py",
+    "src/hwpx/oxml/document.py",
+    "src/hwpx/opc/package.py",
+    "src/hwpx/opc/relationships.py",
+    "src/hwpx/tools/archive_cli.py",
+    "src/hwpx/tools/package_validator.py",
+    "src/hwpx/tools/page_guard.py",
+    "src/hwpx/tools/template_analyzer.py",
+    "src/hwpx/tools/text_extract_cli.py",
+    "src/hwpx/tools/text_extractor.py",
+]
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
 module = ["hwpx.document", "hwpx.oxml.document"]
 ignore_errors = true
 
 [tool.pyright]
-include = ["src/hwpx/document.py", "src/hwpx/oxml/document.py"]
+# Keep basic pyright focused on OPC/tooling modules that currently pass
+# without suppressing their real diagnostics.
+include = [
+    "src/hwpx/opc/package.py",
+    "src/hwpx/opc/relationships.py",
+    "src/hwpx/tools/archive_cli.py",
+    "src/hwpx/tools/package_validator.py",
+    "src/hwpx/tools/page_guard.py",
+    "src/hwpx/tools/template_analyzer.py",
+    "src/hwpx/tools/text_extract_cli.py",
+    "src/hwpx/tools/text_extractor.py",
+]
 pythonVersion = "3.10"
-typeCheckingMode = "off"
+typeCheckingMode = "basic"
 reportMissingTypeStubs = false