hwpkit-dev 0.0.1

package/ .npmignore

@@ -0,0 +1,11 @@
+node_modules
+dist
+*.hml
+*.hml.md
+*.hwpx
+*.pdf
+*.zip
+.claude
+tests
+data
+playground

package/README.md

@@ -0,0 +1,223 @@
+# HWPKit
+
+[![npm version](https://img.shields.io/npm/v/hwpkit.svg)](https://www.npmjs.com/package/hwpkit)
+[![license](https://img.shields.io/npm/l/hwpkit.svg)](https://github.com/INMD1/hwpkit/blob/main/license.md)
+
+**HWP / HWPX / DOCX / Markdown 양방향 문서 변환 라이브러리**
+
+한국 문서 포맷(HWP, HWPX)과 국제 표준(DOCX, Markdown)을 상호 변환하는 TypeScript 라이브러리입니다.
+브라우저와 Node.js 환경 모두에서 동작하며, 데이터 무결성과 무중단 변환을 최우선으로 설계했습니다.
+
+---
+
+## 주요 특징
+
+- **Pipeline 체이닝 API** - `Pipeline.open(file).to('hwpx')` 한 줄로 변환
+- **데이터 무결성 100%** - 텍스트, 표, 이미지 누락 없이 변환
+- **무중단 변환** - 어떤 입력이 들어와도 크래시 없이 `Outcome<T>` 반환
+- **4단계 표 폴백** - Full > Grid > Flat > Text 순서로 안전 변환
+- **Result 모나드** - null/throw 대신 `Ok | Fail` 명시적 결과 처리
+- **TypeScript 완전 지원** - 모든 노드 타입과 API에 대한 타입 정의
+
+---
+
+## 변환 지원 현황
+
+| 입력 \ 출력 | HWPX | DOCX | Markdown |
+|------------|:----:|:----:|:--------:|
+| **HWPX**   | -    | O    | O        |
+| **HWP**    | O    | O    | O        |
+| **DOCX**   | O    | -    | O        |
+| **Markdown** | O  | O    | -        |
+
+---
+
+## 설치
+
+```bash
+npm install hwpkit
+```
+
+---
+
+## 사용법
+
+### Pipeline API (권장)
+
+```typescript
+import { Pipeline } from 'hwpkit';
+
+// 파일 변환
+const result = await Pipeline.open(uint8ArrayData, 'docx').to('hwpx');
+
+if (result.ok) {
+  // result.data: Uint8Array (변환된 파일)
+  // result.warns: string[] (폴백 발생 시 경고 목록)
+  saveFile(result.data);
+} else {
+  console.error(result.error);
+}
+
+// 문서 구조만 추출 (인코딩 없이)
+const inspectResult = await Pipeline.open(data, 'docx').inspect();
+if (inspectResult.ok) {
+  console.log(inspectResult.data); // DocRoot
+}
+
+// File/Blob 입력 (비동기)
+const pipeline = await Pipeline.openAsync(file, 'hwpx');
+const converted = await pipeline.to('docx');
+
+// Markdown 문자열 직접 입력
+const mdResult = await Pipeline.open('# Hello\n\nWorld').to('docx');
+```
+
+### Decoder / Encoder 직접 사용
+
+```typescript
+import { DocxDecoder } from 'hwpkit';
+import { MdEncoder } from 'hwpkit';
+
+const decoder = new DocxDecoder();
+const encoder = new MdEncoder();
+
+const docResult = await decoder.decode(docxBytes);
+if (!docResult.ok) throw new Error(docResult.error);
+
+const mdResult = await encoder.encode(docResult.data);
+if (mdResult.ok) {
+  const mdText = new TextDecoder().decode(mdResult.data);
+}
+```
+
+### 문서 모델 직접 구성
+
+```typescript
+import { buildRoot, buildSheet, buildPara, buildSpan, buildGrid, buildRow, buildCell } from 'hwpkit';
+
+const doc = buildRoot({ title: '제목' }, [
+  buildSheet([
+    buildPara([buildSpan('Hello World', { b: true, pt: 14 })], { heading: 1 }),
+    buildPara([buildSpan('본문 텍스트입니다.')]),
+    buildGrid([
+      buildRow([
+        buildCell([buildPara([buildSpan('A1')])]),
+        buildCell([buildPara([buildSpan('B1')])]),
+      ]),
+      buildRow([
+        buildCell([buildPara([buildSpan('A2')])]),
+        buildCell([buildPara([buildSpan('B2')])]),
+      ]),
+    ]),
+  ]),
+]);
+```
+
+### 트리 순회
+
+```typescript
+import { TreeWalker, walkNode, countNodes, validateRoot } from 'hwpkit';
+
+// 텍스트 추출
+const walker = new TreeWalker();
+const text = walker.extractText(docRoot);
+
+// 노드 통계
+const counts = countNodes(docRoot);
+// { root: 1, sheet: 1, para: 5, span: 5, txt: 5, grid: 1, row: 2, cell: 4 }
+
+// 유효성 검증
+const errors = validateRoot(docRoot);
+```
+
+---
+
+## 아키텍처
+
+```
+입력 파일 --> [ Decoder ] --> [ DocRoot ] --> [ Encoder ] --> 출력 파일
+                                  |
+                            Pipeline.inspect()
+```
+
+### 문서 추상 모델 (Doc Model)
+
+모든 문서는 `DocRoot` 트리로 변환되어 포맷 간 변환의 중간 표현으로 사용됩니다.
+
+```
+DocRoot
+  └─ SheetNode (섹션/페이지)
+       ├─ ParaNode (문단)
+       │    ├─ SpanNode (텍스트 런)
+       │    │    └─ TxtNode / BrNode / PbNode
+       │    ├─ ImgNode (이미지)
+       │    └─ LinkNode (하이퍼링크)
+       └─ GridNode (표)
+            └─ RowNode
+                 └─ CellNode
+                      └─ ParaNode ...
+```
+
+### 안전 계층
+
+- **ShieldedParser** - 개별 노드 파싱 실패가 전체를 중단시키지 않음
+- **StyleBridge** - 포맷 간 스타일/단위 변환 (`Metric.*`)
+- **Outcome<T>** - 모든 결과를 `Ok | Fail`로 감싸 null/throw 제거
+
+### 디렉토리 구조
+
+```
+src/
+├── model/          # 문서 추상 모델 (DocRoot, 속성, 빌더)
+├── contract/       # Decoder/Encoder 인터페이스, Result 모나드
+├── pipeline/       # Pipeline 오케스트레이터, 포맷 레지스트리
+├── decoders/       # 입력 포맷 → DocRoot
+│   ├── docx/       #   DocxDecoder
+│   ├── hwpx/       #   HwpxDecoder
+│   ├── hwp/        #   HwpScanner
+│   └── md/         #   MdDecoder
+├── encoders/       # DocRoot → 출력 포맷
+│   ├── docx/       #   DocxEncoder
+│   ├── hwpx/       #   HwpxEncoder
+│   └── md/         #   MdEncoder
+├── walk/           # 트리 순회 (TreeWalker, walkNode)
+├── safety/         # ShieldedParser, StyleBridge
+└── toolkit/        # XmlKit, ArchiveKit, BinaryKit, TextKit
+```
+
+---
+
+## 개발
+
+```bash
+# 의존성 설치
+npm install
+
+# 타입 체크
+npm run typecheck
+
+# 테스트 실행
+npm test
+
+# 빌드 (ESM + CJS + d.ts)
+npm run build
+
+# 개발 모드 (watch)
+npm run dev
+```
+
+### 의존성
+
+| 패키지 | 용도 |
+|--------|------|
+| `pako` | ZIP inflate/deflate |
+| `xml2js` | XML 파싱/빌드 |
+| `saxes` | SAX 스트리밍 파서 (대용량 XML) |
+| `tsup` | 빌드 (esbuild 기반) |
+| `vitest` | 테스트 프레임워크 |
+
+---
+
+## 라이선스
+
+이 프로젝트는 **LGPL-2.1** 라이선스를 따릅니다. 자세한 내용은 [`license.md`](./license.md)를 참고하세요.

package/dist/index.d.mts

@@ -0,0 +1,313 @@
+type Align = 'left' | 'center' | 'right' | 'justify';
+type VAlign = 'top' | 'mid' | 'bot';
+type Heading = 1 | 2 | 3 | 4 | 5 | 6;
+type StrokeKind = 'solid' | 'dash' | 'dot' | 'double' | 'none';
+interface TextProps {
+    b?: boolean;
+    i?: boolean;
+    u?: boolean;
+    s?: boolean;
+    sup?: boolean;
+    sub?: boolean;
+    font?: string;
+    pt?: number;
+    color?: string;
+    bg?: string;
+}
+interface ParaProps {
+    align?: Align;
+    heading?: Heading;
+    indentPt?: number;
+    spaceBefore?: number;
+    spaceAfter?: number;
+    lineHeight?: number;
+    listLv?: number;
+    listOrd?: boolean;
+    listMark?: string;
+}
+interface Stroke {
+    kind: StrokeKind;
+    pt: number;
+    color: string;
+}
+interface CellProps {
+    top?: Stroke;
+    bot?: Stroke;
+    left?: Stroke;
+    right?: Stroke;
+    bg?: string;
+    padPt?: number;
+    align?: Align;
+    va?: VAlign;
+    isHeader?: boolean;
+}
+interface TableLook {
+    firstRow?: boolean;
+    lastRow?: boolean;
+    firstCol?: boolean;
+    lastCol?: boolean;
+    bandedRows?: boolean;
+    bandedCols?: boolean;
+}
+interface GridProps {
+    widthPct?: number;
+    colWidths?: number[];
+    defaultStroke?: Stroke;
+    look?: TableLook;
+    headerRow?: boolean;
+}
+interface PageDims {
+    wPt: number;
+    hPt: number;
+    mt: number;
+    mb: number;
+    ml: number;
+    mr: number;
+    orient?: 'portrait' | 'landscape';
+}
+interface DocMeta {
+    title?: string;
+    author?: string;
+    subject?: string;
+    desc?: string;
+    keywords?: string;
+    created?: string;
+    modified?: string;
+}
+declare const A4: PageDims;
+declare const DEFAULT_STROKE: Stroke;
+
+type BlockTag = 'root' | 'sheet' | 'para' | 'span' | 'txt' | 'img' | 'link' | 'grid' | 'row' | 'cell' | 'br' | 'pb' | 'pagenum';
+interface TxtNode {
+    tag: 'txt';
+    content: string;
+}
+interface BrNode {
+    tag: 'br';
+}
+interface PbNode {
+    tag: 'pb';
+}
+interface PageNumNode {
+    tag: 'pagenum';
+    format?: 'decimal' | 'roman' | 'romanCaps';
+}
+interface ImgNode {
+    tag: 'img';
+    b64: string;
+    mime: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/bmp';
+    w: number;
+    h: number;
+    alt?: string;
+}
+interface SpanNode {
+    tag: 'span';
+    props: TextProps;
+    kids: (TxtNode | BrNode | PbNode | PageNumNode)[];
+}
+interface LinkNode {
+    tag: 'link';
+    href: string;
+    kids: SpanNode[];
+}
+interface ParaNode {
+    tag: 'para';
+    props: ParaProps;
+    kids: (SpanNode | ImgNode | LinkNode)[];
+}
+interface CellNode {
+    tag: 'cell';
+    cs: number;
+    rs: number;
+    props: CellProps;
+    kids: ParaNode[];
+}
+interface RowNode {
+    tag: 'row';
+    kids: CellNode[];
+}
+interface GridNode {
+    tag: 'grid';
+    props: GridProps;
+    kids: RowNode[];
+}
+type ContentNode = ParaNode | GridNode;
+interface SheetNode {
+    tag: 'sheet';
+    dims: PageDims;
+    kids: ContentNode[];
+    header?: ParaNode[];
+    footer?: ParaNode[];
+}
+interface DocRoot {
+    tag: 'root';
+    meta: DocMeta;
+    kids: SheetNode[];
+}
+type AnyNode = DocRoot | SheetNode | ParaNode | SpanNode | TxtNode | ImgNode | LinkNode | GridNode | RowNode | CellNode | BrNode | PbNode | PageNumNode;
+
+type Outcome<T> = Ok<T> | Fail;
+interface Ok<T> {
+    ok: true;
+    data: T;
+    warns: string[];
+}
+interface Fail {
+    ok: false;
+    error: string;
+    warns: string[];
+}
+declare function succeed<T>(data: T, warns?: string[]): Ok<T>;
+declare function fail(error: string, warns?: string[]): Fail;
+
+interface Decoder {
+    readonly format: string;
+    decode(data: Uint8Array): Promise<Outcome<DocRoot>>;
+}
+
+interface Encoder {
+    readonly format: string;
+    encode(doc: DocRoot): Promise<Outcome<Uint8Array>>;
+}
+
+declare class Pipeline {
+    private raw;
+    private srcFmt;
+    private constructor();
+    /** 파일을 열고 포맷을 자동 감지하거나 명시 */
+    static open(input: Uint8Array | string, fmt?: string): Pipeline;
+    /** File/Blob 비동기 입력 */
+    static openAsync(input: File | Blob | Uint8Array | string, fmt?: string): Promise<Pipeline>;
+    /** 목표 포맷으로 변환 */
+    to(targetFmt: string): Promise<Outcome<Uint8Array>>;
+    /** DocRoot만 추출 (인코딩 없이) */
+    inspect(): Promise<Outcome<DocRoot>>;
+}
+
+declare class FormatRegistry {
+    private decoders;
+    private encoders;
+    registerDecoder(d: Decoder): void;
+    registerEncoder(e: Encoder): void;
+    getDecoder(fmt: string): Decoder | undefined;
+    getEncoder(fmt: string): Encoder | undefined;
+    supportedInputs(): string[];
+    supportedOutputs(): string[];
+}
+declare const registry: FormatRegistry;
+
+declare function buildRoot(meta?: DocMeta, kids?: SheetNode[]): DocRoot;
+declare function buildSheet(kids?: ContentNode[], dims?: PageDims, opts?: {
+    header?: ParaNode[];
+    footer?: ParaNode[];
+}): SheetNode;
+declare function buildPageNum(format?: PageNumNode['format']): PageNumNode;
+declare function buildPara(kids?: ParaNode['kids'], props?: ParaProps): ParaNode;
+declare function buildSpan(content: string, props?: TextProps): SpanNode;
+declare function buildImg(b64: string, mime: ImgNode['mime'], w: number, h: number, alt?: string): ImgNode;
+declare function buildGrid(kids: RowNode[], props?: GridProps): GridNode;
+declare function buildRow(kids: CellNode[]): RowNode;
+declare function buildCell(kids: ParaNode[], opts?: {
+    cs?: number;
+    rs?: number;
+    props?: CellProps;
+}): CellNode;
+
+declare class ShieldedParser {
+    private log;
+    /** 단일 요소 안전 파싱 */
+    guard<T>(fn: () => T, fallback: T, label: string): T;
+    /** 배열 각 요소 독립 파싱 (하나 실패해도 나머지 계속) */
+    guardAll<I, O>(items: I[], fn: (x: I, i: number) => O, fb: (x: I, i: number) => O, label: string): O[];
+    /**
+     * 표 전용 4단계 폴백
+     *   Lv1: Full → Lv2: Grid → Lv3: Flat → Lv4: Text
+     */
+    guardGrid<T>(node: unknown, lv1Full: (n: unknown) => T, lv2Grid: (n: unknown) => T, lv3Flat: (n: unknown) => T, lv4Text: (n: unknown) => T, label: string): {
+        value: T;
+        level: 1 | 2 | 3 | 4;
+    };
+    /** 이미지 안전 파싱 */
+    guardImg<T>(node: unknown, fn: (n: unknown) => T, placeholder: (alt: string) => T, label: string): T;
+    private warn;
+    flush(): string[];
+}
+
+declare const Metric: {
+    readonly hwpToPt: (v: number) => number;
+    readonly ptToHwp: (v: number) => number;
+    readonly hwpToDxa: (v: number) => number;
+    readonly dxaToHwp: (v: number) => number;
+    readonly hwpToEmu: (v: number) => number;
+    readonly emuToHwp: (v: number) => number;
+    readonly dxaToPt: (v: number) => number;
+    readonly ptToDxa: (v: number) => number;
+    readonly dxaToEmu: (v: number) => number;
+    readonly emuToDxa: (v: number) => number;
+    readonly emuToPt: (v: number) => number;
+    readonly ptToEmu: (v: number) => number;
+    readonly hHeightToPt: (v: number) => number;
+    readonly ptToHHeight: (v: number) => number;
+    readonly halfPtToPt: (v: number) => number;
+    readonly ptToHalfPt: (v: number) => number;
+};
+declare function safeHex(raw: string | number | null | undefined): string | undefined;
+declare function safeAlign(raw?: string): Align;
+declare function safeStrokeHwpx(type?: string, w?: number, c?: string): Stroke;
+declare function safeStrokeDocx(val?: string, sz?: number, c?: string): Stroke;
+declare function safeFont(raw?: string): string;
+declare function safeFontToKr(raw?: string): string;
+
+type WalkCallback = (node: AnyNode, parent: AnyNode | null, depth: number) => void | 'stop';
+declare function walkNode(node: AnyNode, cb: WalkCallback, parent?: AnyNode | null, depth?: number): boolean;
+declare class TreeWalker {
+    walk(root: DocRoot, cb: WalkCallback): void;
+    findAll<T extends AnyNode>(root: DocRoot, predicate: (n: AnyNode) => n is T): T[];
+    extractText(root: DocRoot): string;
+}
+
+declare function countNodes(root: DocRoot): Record<string, number>;
+declare function validateRoot(root: DocRoot): string[];
+
+declare const XmlKit: {
+    /** @deprecated Use parseStrict instead */
+    parse(xml: string): Promise<unknown>;
+    parseStrict(xml: string): Promise<unknown>;
+    attr(node: Record<string, unknown>, key: string): string | undefined;
+    text(node: Record<string, unknown> | string | undefined): string;
+};
+
+interface ZipEntry {
+    name: string;
+    data: Uint8Array;
+}
+declare const ArchiveKit: {
+    inflate(compressed: Uint8Array): Promise<Uint8Array>;
+    deflate(data: Uint8Array): Promise<Uint8Array>;
+    unzip(zipData: Uint8Array): Promise<Map<string, Uint8Array>>;
+    zip(entries: ZipEntry[]): Promise<Uint8Array>;
+};
+
+/**
+ * OLE2 Compound File Binary Format (CFB) parser.
+ * Used for legacy HWP 5.0 files.
+ */
+declare const BinaryKit: {
+    readU16LE(buf: Uint8Array, offset: number): number;
+    readU32LE(buf: Uint8Array, offset: number): number;
+    isOle2(data: Uint8Array): boolean;
+    parseCfb(data: Uint8Array): Map<string, Uint8Array>;
+};
+
+declare const TextKit: {
+    decode(data: Uint8Array, encoding?: string): string;
+    encode(text: string): Uint8Array;
+    escapeXml(s: string): string;
+    unescapeXml(s: string): string;
+    normalizeWhitespace(s: string): string;
+    stripControl(s: string): string;
+    base64Encode(data: Uint8Array): string;
+    base64Decode(b64: string): Uint8Array;
+};
+
+export { A4, type Align, type AnyNode, ArchiveKit, BinaryKit, type BlockTag, type BrNode, type CellNode, type CellProps, type ContentNode, DEFAULT_STROKE, type Decoder, type DocMeta, type DocRoot, type Encoder, type Fail, type GridNode, type GridProps, type Heading, type ImgNode, type LinkNode, Metric, type Ok, type Outcome, type PageDims, type PageNumNode, type ParaNode, type ParaProps, type PbNode, Pipeline, type RowNode, type SheetNode, ShieldedParser, type SpanNode, type Stroke, type StrokeKind, type TableLook, TextKit, type TextProps, TreeWalker, type TxtNode, type VAlign, XmlKit, buildCell, buildGrid, buildImg, buildPageNum, buildPara, buildRoot, buildRow, buildSheet, buildSpan, countNodes, fail, registry, safeAlign, safeFont, safeFontToKr, safeHex, safeStrokeDocx, safeStrokeHwpx, succeed, validateRoot, walkNode };