kordoc 4.0.8 → 4.2.0

package/README.md

@@ -84,6 +84,21 @@ MCP 등록 대신 스킬(SKILL.md) 형태로 쓰려면:
 
 ---
 
+## v4.2.0 변경사항
+
+- **👓 내장 텍스트 OCR (PP-OCRv5 korean)**: 스캔/이미지 PDF를 **API 키 없이 로컬 추론**으로 읽습니다 — `parse(buffer, { ocr: true })` / CLI `--ocr` / MCP `parse_document`의 `ocr` 옵션. 모델 ~18MB는 첫 사용 시 자동 다운로드+SHA 검증. 품질 신호가 가리키는 페이지(스캔·글꼴 매핑 깨짐)만 정밀 OCR 하고 정상 페이지는 그대로 두며, OCR 라인 좌표를 표 감지 파이프라인에 태워 **스캔본에서도 표가 복원**됩니다. 한국어 사전 11,945자(완성형 한글 전량), 1페이지 ≈1초.
+- **🩹 HWP3 구버전 파서 정합 3종**: 탭/필드코드/책갈피의 스트림 소비 결함으로 이후 텍스트가 통째로 오염되던 것과, 로마숫자(Ⅰ~Ⅹ)·원문자(①~⑩)·따옴표·글머리가 증발하던 것을 원저장소(rhwp) 후속 패치 반영으로 수리.
+- **🐛 수식 OCR 페이지 off-by-one 수리**: `--pages` 필터가 한 페이지 밀리고 수식이 이전 페이지에 붙던 잠복 결함. XLSX/XLS `--keep-empty-cols` 배선 누락도 수리.
+
+## v4.1.0 변경사항
+
+- **👁️ `render_document` MCP 도구 신설**: 생성·패치·양식 채움 결과 HWPX를 조판 그대로 **PNG 이미지로 응답에 직접 반환** — AI가 자기가 만든 문서를 눈으로 확인하고 다시 고치는 루프가 MCP 안에서 닫힙니다 (한컴 저장본은 조판 캐시, 생성본은 reflow 조판, 검색어 형광펜 지원).
+- **🕶️ `kordoc redact` + `redact_document` MCP 신설**: 개인정보(주민번호·전화·이메일·카드·계좌, 여권·운전면허 opt-in)를 탐지해 **원본 서식 그대로 마스킹**(`850315-●●●●●●●`)한 HWPX/HWP를 출력합니다. 생년월일·Luhn 검증으로 오탐 축소, 리포트에 원본 개인정보 미포함. 자동 검출 보조 도구 — 최종 공개 전 사람 확인 필수.
+- **📦 `--format chunks` + `parse_chunks` MCP 신설**: RAG용 구조 청크 JSON — 헤딩·개조식 위계(□○- / 1.·가.·1))를 breadcrumb 경로로 보존하고 표는 독립 청크로 분리합니다.
+- **📋 표 오른쪽 끝 빈 열 보존 (#47)**: 서식 문서의 빈 입력란 열이 파싱에서 통째로 삭제되던 문제 — `keepTrailingEmptyCols` 파싱 옵션(CLI `--keep-empty-cols`)으로 보존할 수 있고, **양식 경로(parse_form·fill)는 항상 보존**해 fill이 채울 수 있는 필드가 목록에서 빠지지 않습니다. 제보 [@jumaniac](https://github.com/jumaniac).
+- **📅 XLSX/XLS 날짜 변환**: 날짜 셀이 시리얼 숫자("45306")로 나오던 것을 ISO("2024-01-15")로 변환합니다 (내장·커스텀 numFmt 감지, date1904 반영).
+- **🛡️ 프로덕션 전면 리뷰 ~80건 수정**: 악성 파일 대응(수식 정규식 ReDoS·HTML 표 span 폭주·HWP3 압축 폭탄·XLSX 그리드 폭주), 표-전용 PDF의 OCR 오판, HWP5 제어문자(하이픈/고정폭 공백) 매핑, DOCX 변경추적 삽입 유실, 양식 채움 라벨 오탐 4종, HWP5 패치 삭제 텍스트 잔존 제로화, MCP 쓰기 경로 검증, PDF 괘선 표 성능(62,500 교차점 3.1s→0.2s) 등 — 자세한 내역은 [CHANGELOG](CHANGELOG.md).
+
 ## v4.0.8 변경사항
 
 - **🖼️ PDF 이미지 추출 신설**: 종전에는 이미지 영역 좌표만 계산하고 바이너리는 전량 유실되던 것을, 이미지 XObject를 디코딩 픽셀로 받아 순수 JS PNG 인코딩으로 추출합니다 (pdfjs 비동기 디코딩 대기 포함 — 코퍼스 52 PDF 중 45파일 731장 실측). 페이지 말미 위치에 `![image](...)` 참조, 로고·워터마크 페이지 간 중복 억제, 페이지 경계 표 병합 비간섭.
@@ -482,7 +497,7 @@ MCP 등록 대신 스킬(SKILL.md) 형태로 쓰려면:
 - **구조화 파싱** — `IRBlock[]`과 `DocumentMetadata`에 직접 접근. 마크다운 넘어선 데이터 활용.
 - **페이지 범위** — `parse(buffer, { pages: "1-3" })` — 필요한 페이지만 빠르게.
 - **Markdown → HWPX** — 역변환. AI가 생성한 내용을 바로 공문서로.
-- **OCR 연동** — 이미지 기반 PDF도 텍스트 추출 (Tesseract, Claude Vision 등 프로바이더 직접 제공).
+- **OCR** — 스캔/이미지 PDF 텍스트 추출. 내장 엔진(`ocr: true`, PP-OCRv5 korean) 또는 외부 프로바이더(Tesseract, Claude Vision 등).
 - **Watch 모드** — `kordoc watch ./수신함 -d ./변환결과 --webhook https://...`
 - **MCP 7개 도구** — parse_document, detect_format, parse_metadata, parse_pages, parse_table, compare_documents, parse_form
 - **에러 코드** — `"ENCRYPTED"`, `"ZIP_BOMB"`, `"IMAGE_BASED_PDF"` 등 구조화된 에러 핸들링
@@ -495,11 +510,12 @@ MCP 등록 대신 스킬(SKILL.md) 형태로 쓰려면:
 
 ```bash
 npm install kordoc
-
-# PDF 파싱이 필요하면 (선택)
-npm install pdfjs-dist
 ```
 
+PDF 파싱(pdfjs-dist)·수식 OCR 등 선택 의존성은 **기본 설치**됩니다 (optionalDependencies).
+설치 용량을 줄이려면 `npm install kordoc --omit=optional` 로 스킵할 수 있습니다 —
+이 경우 PDF 파싱·수식 OCR·인쇄 렌더 등 일부 기능이 제한됩니다.
+
 ## 빠른 시작
 
 ### 문서 파싱
@@ -509,7 +525,7 @@ import { parse } from "kordoc"
 import { readFileSync } from "fs"
 
 const buffer = readFileSync("사업계획서.hwpx")
-const result = await parse(buffer.buffer)
+const result = await parse(buffer)
 
 if (result.success) {
   console.log(result.markdown)       // 마크다운 텍스트
@@ -552,15 +568,15 @@ import { readFileSync, writeFileSync } from "fs"
 const template = readFileSync("신청서.hwpx")
 
 // HWPX 원본 서식 보존 모드 — 글꼴, 크기, 정렬 100% 유지
-const result = await fillForm(template.buffer, {
+const result = await fillForm(template, {
   성명: "홍길동",
   주민등록번호: "900101-1234567",
   주소: "서울특별시 광진구 능동로 120",
-}, { format: "hwpx-preserve" })
+}, "hwpx-preserve")
 
-writeFileSync("신청서_작성완료.hwpx", Buffer.from(result.buffer!))
-// result.filled → [{ label: "성명", value: "홍길동" }, ...]
-// result.unmatched → 매칭 실패한 키 목록
+writeFileSync("신청서_작성완료.hwpx", Buffer.from(result.output as ArrayBuffer))
+// result.fill.filled → [{ label: "성명", value: "홍길동" }, ...]
+// result.fill.unmatched → 매칭 실패한 키 목록
 ```
 
 ### HWPX 생성 (역변환)
@@ -628,12 +644,26 @@ const result = await parse(buffer, { pages: "1-3" })      // 1~3 페이지만
 const result = await parse(buffer, { pages: [1, 5, 10] })  // 특정 페이지
 ```
 
-### OCR (이미지 PDF)
+### OCR (스캔/이미지 PDF) — 내장 엔진 (v4.2.0+)
+
+```typescript
+// 내장 OCR (PP-OCRv5 korean, 첫 사용 시 모델 ~18MB 자동 다운로드)
+const result = await parse(buffer, { ocr: true })     // OCR 필요 페이지만 자동 판정
+const result = await parse(buffer, { ocr: "force" })  // 전 페이지 강제 OCR
+```
+
+- **API 키·외부 서비스 불필요** — det(선 검출)+rec(CTC 인식) ONNX 를 로컬 CPU 로 추론합니다
+  (PaddlePaddle 공식 변환본, Apache-2.0 / 한국어 사전 11,945자 — 완성형 한글 전량).
+- **페이지 단위 정밀 적용** — 텍스트층이 없는 스캔 페이지, ToUnicode 가 깨진 페이지
+  (`needsOcr` 신호)만 OCR 하고 정상 페이지의 파싱 결과는 그대로 유지합니다.
+- **표 복원** — OCR 라인 좌표를 기존 블록 파이프라인(xy-cut 읽기 순서 + 클러스터 표
+  감지)에 태우므로 스캔본에서도 표 구조가 복원됩니다.
+- 외부 OCR 을 쓰고 싶으면 종전대로 프로바이더 함수를 전달하세요:
 
 ```typescript
 const result = await parse(buffer, {
   ocr: async (pageImage, pageNumber, mimeType) => {
-    return await myOcrService.recognize(pageImage)
+    return await myOcrService.recognize(pageImage) // Claude Vision, Tesseract 등
   }
 })
 ```
@@ -645,8 +675,8 @@ PDF는 텍스트층이 있어도 ToUnicode/CMap이 깨졌거나 NUL 등 제어
 ```typescript
 const r = await parsePdf(buffer)
 if (r.success && r.qualitySummary?.needsOcr) {
-  // OCR 큐로 라우팅 (kordoc은 OCR을 기본 탑재하지 않음)
-  await routeToOcr(buffer, r.qualitySummary.ocrCandidatePages)
+  // 내장 OCR 로 재시도 (v4.2.0+) — 또는 외부 OCR 큐로 라우팅
+  const retried = await parse(buffer, { ocr: true })
 }
 
 // 페이지 단위 신호
@@ -714,7 +744,7 @@ npx -y kordoc setup
 }
 ```
 
-**11개 도구:**
+**15개 도구:**
 
 | 도구 | 설명 |
 |------|------|
@@ -727,8 +757,12 @@ npx -y kordoc setup
 | `parse_form` | 양식 필드를 JSON으로 추출 |
 | `fill_form` | 양식 템플릿에 값 채우기 (HWPX 원본 서식 보존, 서식/유일성 가드) |
 | `patch_document` | 편집된 마크다운을 원본 HWPX/HWP에 서식 보존 반영 (v3.3) |
+| `extract_profile` | 참조 HWPX에서 표 서식 프로필(JSON) 추출 — generate_document의 profile_path로 재현 |
 | `generate_document` | 마크다운(표·수식·차트 포함) → HWPX 생성, 공문서 프리셋 (v3.5) |
 | `place_seal` | 도장/서명 이미지를 앵커 문구 위에 부유 배치 (v3.16) |
+| `render_document` | HWPX를 조판 그대로 PNG 이미지/SVG로 렌더 — 생성·수정 결과를 AI가 눈으로 검증 (v4.1) |
+| `redact_document` | 개인정보(주민번호·전화·이메일·카드·계좌) 탐지 + 서식 보존 마스킹, 리포트 반환 (v4.1) |
+| `parse_chunks` | RAG용 구조 청크 JSON — 헤딩·개조식 위계 breadcrumb + 표 독립 청크 (v4.1) |
 
 ## API
 
@@ -754,7 +788,7 @@ npx -y kordoc setup
 | `compare(bufferA, bufferB, options?)` | IR 레벨 문서 비교 |
 | `extractFormFields(blocks)` | IRBlock[]에서 양식 필드 인식 |
 | `extractFormSchema(blocks)` | 양식 필드 인식 + 타입/필수/빈값 추론 (v3.1) |
-| `fillForm(buffer, values, options?)` | 양식 템플릿에 값 채우기 (markdown/hwpx/hwpx-preserve) |
+| `fillForm(input, values, outputFormat?)` | 양식 템플릿에 값 채우기 — outputFormat: `"markdown"`(기본)/`"hwpx"`/`"hwpx-preserve"`, 반환 `{ output, format, fill }` |
 | `fillFormFields(blocks, values)` | IRBlock[] 기반 필드 값 교체 |
 | `fillHwpx(buffer, values)` | HWPX XML 직접 조작 (원본 서식 보존) |
 | `patchHwpx(original, editedMarkdown, options?)` | 편집 마크다운 → 원본 HWPX 서식 보존 in-place 패치 (v3.0) |

package/dist/{-LE4RLXVA.js → -SXQIZHYA.js}

@@ -39,10 +39,9 @@ import {
   renderHtml,
   unknownFontWarnings,
   validateHwpx
-} from "./chunk-7S3M4N4E.js";
-import {
-  blocksToMarkdown
-} from "./chunk-UEIYETCQ.js";
+} from "./chunk-IGGRLWT5.js";
+import "./chunk-7FCNOKOR.js";
+import "./chunk-4VNLZ2GZ.js";
 import {
   detectFormat,
   detectOle2Format,
@@ -51,7 +50,7 @@ import {
   isOldHwpFile,
   isPdfFile,
   isZipFile
-} from "./chunk-MEPHGCPQ.js";
+} from "./chunk-YOO6ET6M.js";
 import "./chunk-MOL7MDBG.js";
 import {
   applySplices,
@@ -59,7 +58,18 @@ import {
   buildRangeSplices,
   placeSealHwpx,
   scanSectionXml
-} from "./chunk-D35VBACN.js";
+} from "./chunk-WQLHPOMJ.js";
+import {
+  DEFAULT_REDACT_RULES,
+  redactMarkdown,
+  redactText
+} from "./chunk-DZIXKL7E.js";
+import {
+  blocksToChunks
+} from "./chunk-ELOV2GIJ.js";
+import {
+  blocksToMarkdown
+} from "./chunk-CMN3SYZ3.js";
 import {
   SPACE_EM_FIXED,
   SPACE_EM_FONT,
@@ -69,12 +79,13 @@ import {
   renderHwpxToSvg,
   simulateWrap,
   simulateWrapKeepWord
-} from "./chunk-2DZQF6YJ.js";
-import "./chunk-BNU5QGIZ.js";
+} from "./chunk-6SHO3BNV.js";
+import "./chunk-V6U6YS5B.js";
 import {
   VERSION
-} from "./chunk-HMUEU7D7.js";
+} from "./chunk-FSXLSHCW.js";
 export {
+  DEFAULT_REDACT_RULES,
   HwpxSession,
   PRESET_ALIAS,
   SPACE_EM_FIXED,
@@ -82,6 +93,7 @@ export {
   VERSION,
   ValueCursor,
   applySplices,
+  blocksToChunks,
   blocksToMarkdown,
   blocksToPdf,
   buildParagraphSplices,
@@ -129,6 +141,8 @@ export {
   patchHwpx,
   patchHwpxBlocks,
   placeSealHwpx,
+  redactMarkdown,
+  redactText,
   renderHtml,
   renderHwpxToSvg,
   scanSectionXml,
@@ -137,4 +151,4 @@ export {
   unknownFontWarnings,
   validateHwpx
 };
-//# sourceMappingURL=-LE4RLXVA.js.map
+//# sourceMappingURL=-SXQIZHYA.js.map