hwpkit-dev 0.0.1

package/src/encoders/md/MdEncoder.ts

@@ -0,0 +1,108 @@
+import type { Encoder } from '../../contract/encoder';
+import type { DocRoot, ParaNode, SpanNode, GridNode, ContentNode, ImgNode } from '../../model/doc-tree';
+import type { Outcome } from '../../contract/result';
+import { succeed, fail } from '../../contract/result';
+import { TextKit } from '../../toolkit/TextKit';
+import { registry } from '../../pipeline/registry';
+
+export class MdEncoder implements Encoder {
+  readonly format = 'md';
+
+  async encode(doc: DocRoot): Promise<Outcome<Uint8Array>> {
+    try {
+      const warns: string[] = [];
+      const parts: string[] = [];
+      for (const sheet of doc.kids) {
+        // Warn about header/footer loss
+        if (sheet.header && sheet.header.length > 0) warns.push('[SHIELD] MD: 머리글(header) 표현 불가 — 손실됨');
+        if (sheet.footer && sheet.footer.length > 0) warns.push('[SHIELD] MD: 바닥글(footer) 표현 불가 — 손실됨');
+
+        for (const kid of sheet.kids) parts.push(encodeContent(kid, warns));
+      }
+      return succeed(TextKit.encode(parts.join('\n\n')), warns);
+    } catch (e: any) {
+      return fail(`MD encode error: ${e?.message ?? String(e)}`);
+    }
+  }
+}
+
+function encodeContent(node: ContentNode, warns: string[]): string {
+  return node.tag === 'grid' ? encodeGrid(node, warns) : encodePara(node, warns);
+}
+
+function encodePara(para: ParaNode, warns: string[]): string {
+  const text = para.kids.map(k => {
+    if (k.tag === 'span') return encodeSpan(k, warns);
+    if (k.tag === 'img') return encodeImage(k);
+    return '';
+  }).join('');
+
+  if (para.props.heading) return `${'#'.repeat(para.props.heading)} ${text}`;
+
+  if (para.props.listOrd !== undefined) {
+    const indent = '  '.repeat(para.props.listLv ?? 0);
+    return `${indent}${para.props.listOrd ? '1.' : '-'} ${text}`;
+  }
+
+  // Alignment: use HTML fallback for non-left
+  if (para.props.align && para.props.align !== 'left' && para.props.align !== 'justify') {
+    return `<div align="${para.props.align}">${text}</div>`;
+  }
+
+  return text;
+}
+
+function encodeSpan(span: SpanNode, warns: string[]): string {
+  // Warn about properties that can't be represented in MD
+  if (span.props.font) warns.push(`[SHIELD] MD: 글꼴(${span.props.font}) 표현 불가 — 손실됨`);
+  if (span.props.pt) warns.push(`[SHIELD] MD: 글자 크기(${span.props.pt}pt) 표현 불가 — 손실됨`);
+  if (span.props.color) warns.push(`[SHIELD] MD: 글자 색상(#${span.props.color}) 표현 불가 — 손실됨`);
+  if (span.props.bg) warns.push(`[SHIELD] MD: 배경 색상(#${span.props.bg}) 표현 불가 — 손실됨`);
+
+  let hasPageNum = false;
+  const textParts: string[] = [];
+  for (const kid of span.kids) {
+    if (kid.tag === 'txt') textParts.push(kid.content);
+    else if (kid.tag === 'pagenum') {
+      hasPageNum = true;
+      warns.push('[SHIELD] MD: 페이지 번호 표현 불가 — 손실됨');
+    }
+  }
+
+  let r = textParts.join('');
+  if (hasPageNum && r === '') r = '[페이지 번호]';
+
+  if (span.props.b && span.props.i) r = `***${r}***`;
+  else if (span.props.b) r = `**${r}**`;
+  else if (span.props.i) r = `*${r}*`;
+  if (span.props.s) r = `~~${r}~~`;
+  if (span.props.u) r = `<u>${r}</u>`;
+  if (span.props.sup) r = `<sup>${r}</sup>`;
+  if (span.props.sub) r = `<sub>${r}</sub>`;
+
+  return r;
+}
+
+function encodeImage(img: ImgNode): string {
+  return `![${img.alt ?? ''}](data:${img.mime};base64,${img.b64})`;
+}
+
+function encodeGrid(grid: GridNode, warns: string[]): string {
+  if (grid.kids.length === 0) return '';
+
+  // Warn about table style loss
+  if (grid.props.look) warns.push('[SHIELD] MD: 표 스타일(색상, 테두리, 머리행 강조) 표현 불가 — 손실됨');
+
+  const rows = grid.kids.map(row =>
+    `| ${row.kids.map(cell => cell.kids.map(p => encodePara(p, warns)).join(' ')).join(' | ')} |`,
+  );
+
+  if (rows.length > 0) {
+    const cols = grid.kids[0].kids.length;
+    rows.splice(1, 0, `| ${Array(cols).fill('---').join(' | ')} |`);
+  }
+
+  return rows.join('\n');
+}
+
+registry.registerEncoder(new MdEncoder());

package/src/index.ts

@@ -0,0 +1,47 @@
+// ─── 공개 API ───────────────────────────────────────────────
+
+// Pipeline
+export { Pipeline } from './pipeline/Pipeline';
+export { registry } from './pipeline/registry';
+
+// Side-effect imports: register all decoders/encoders
+import './decoders/md/MdDecoder';
+import './decoders/hwpx/HwpxDecoder';
+import './decoders/docx/DocxDecoder';
+import './decoders/hwp/HwpScanner';
+import './encoders/md/MdEncoder';
+import './encoders/hwpx/HwpxEncoder';
+import './encoders/docx/DocxEncoder';
+import './encoders/hwp/HwpEncoder';
+
+// Model
+export type {
+  DocRoot, SheetNode, ParaNode, SpanNode, GridNode, RowNode, CellNode,
+  ImgNode, LinkNode, TxtNode, BrNode, PbNode, PageNumNode, ContentNode, AnyNode, BlockTag,
+} from './model/doc-tree';
+export type {
+  TextProps, ParaProps, CellProps, GridProps, TableLook, PageDims, DocMeta,
+  Align, VAlign, Heading, StrokeKind, Stroke,
+} from './model/doc-props';
+export { A4, A4_LANDSCAPE, DEFAULT_STROKE, normalizeDims } from './model/doc-props';
+export { buildRoot, buildSheet, buildPara, buildSpan, buildImg, buildGrid, buildRow, buildCell, buildPageNum, buildBr, buildPb } from './model/builders';
+
+// Contract
+export type { Decoder } from './contract/decoder';
+export type { Encoder } from './contract/encoder';
+export type { Outcome, Ok, Fail } from './contract/result';
+export { succeed, fail } from './contract/result';
+
+// Safety
+export { ShieldedParser } from './safety/ShieldedParser';
+export { Metric, safeHex, safeAlign, safeFont, safeFontToKr, safeStrokeHwpx, safeStrokeDocx } from './safety/StyleBridge';
+
+// Walk
+export { TreeWalker, walkNode } from './walk/TreeWalker';
+export { countNodes, validateRoot } from './walk/tree-ops';
+
+// Toolkit
+export { XmlKit } from './toolkit/XmlKit';
+export { ArchiveKit } from './toolkit/ArchiveKit';
+export { BinaryKit } from './toolkit/BinaryKit';
+export { TextKit } from './toolkit/TextKit';

package/src/model/builders.ts

@@ -0,0 +1,66 @@
+import type {
+  DocRoot, SheetNode, ParaNode, SpanNode, ImgNode,
+  GridNode, RowNode, CellNode, ContentNode, TxtNode, PageNumNode, BrNode, PbNode,
+} from './doc-tree';
+import type { TextProps, ParaProps, CellProps, GridProps, DocMeta, PageDims, ImgLayout } from './doc-props';
+import { A4 } from './doc-props';
+
+export function buildRoot(meta: DocMeta = {}, kids: SheetNode[] = []): DocRoot {
+  return { tag: 'root', meta, kids };
+}
+
+export function buildSheet(
+  kids: ContentNode[] = [],
+  dims: PageDims = A4,
+  opts?: { header?: ParaNode[]; footer?: ParaNode[] },
+): SheetNode {
+  const node: SheetNode = { tag: 'sheet', dims, kids };
+  if (opts?.header) node.header = opts.header;
+  if (opts?.footer) node.footer = opts.footer;
+  return node;
+}
+
+export function buildPageNum(format?: PageNumNode['format']): PageNumNode {
+  return { tag: 'pagenum', format };
+}
+
+export function buildBr(): BrNode { return { tag: 'br' }; }
+export function buildPb(): PbNode { return { tag: 'pb' }; }
+
+export function buildPara(kids: ParaNode['kids'] = [], props: ParaProps = {}): ParaNode {
+  return { tag: 'para', props, kids };
+}
+
+export function buildSpan(content: string, props: TextProps = {}): SpanNode {
+  const txt: TxtNode = { tag: 'txt', content };
+  return { tag: 'span', props, kids: [txt] };
+}
+
+export function buildImg(
+  b64: string,
+  mime: ImgNode['mime'],
+  w: number,
+  h: number,
+  alt?: string,
+  layout?: ImgLayout,
+): ImgNode {
+  const node: ImgNode = { tag: 'img', b64, mime, w, h };
+  if (alt) node.alt = alt;
+  if (layout) node.layout = layout;
+  return node;
+}
+
+export function buildGrid(kids: RowNode[], props: GridProps = {}): GridNode {
+  return { tag: 'grid', props, kids };
+}
+
+export function buildRow(kids: CellNode[]): RowNode {
+  return { tag: 'row', kids };
+}
+
+export function buildCell(
+  kids: ParaNode[],
+  opts: { cs?: number; rs?: number; props?: CellProps } = {},
+): CellNode {
+  return { tag: 'cell', cs: opts.cs ?? 1, rs: opts.rs ?? 1, props: opts.props ?? {}, kids };
+}

package/src/model/doc-props.ts

@@ -0,0 +1,138 @@
+export type Align = 'left' | 'center' | 'right' | 'justify';
+
+// ─── 이미지 배치 ────────────────────────────────────────────
+export type ImgWrap = 'inline' | 'square' | 'tight' | 'through' | 'none' | 'behind' | 'front';
+export type ImgHorzAlign = 'left' | 'center' | 'right';
+export type ImgVertAlign = 'top' | 'center' | 'bottom';
+export type ImgHorzRelTo = 'margin' | 'column' | 'page' | 'para';
+export type ImgVertRelTo = 'margin' | 'line' | 'page' | 'para';
+
+export interface ImgLayout {
+  wrap: ImgWrap;
+  horzAlign?: ImgHorzAlign;   // 정렬 기준 (xPt 없을 때)
+  vertAlign?: ImgVertAlign;   // 정렬 기준 (yPt 없을 때)
+  horzRelTo?: ImgHorzRelTo;   // 가로 기준점
+  vertRelTo?: ImgVertRelTo;   // 세로 기준점
+  xPt?: number;               // 명시적 가로 오프셋 (pt)
+  yPt?: number;               // 명시적 세로 오프셋 (pt)
+  distT?: number;             // 텍스트와의 거리 top (pt)
+  distB?: number;
+  distL?: number;
+  distR?: number;
+  behindDoc?: boolean;        // 텍스트 뒤에 배치
+  zOrder?: number;
+}
+export type VAlign = 'top' | 'mid' | 'bot';
+export type Heading = 1 | 2 | 3 | 4 | 5 | 6;
+export type StrokeKind = 'solid' | 'dash' | 'dot' | 'double' | 'none';
+
+export interface TextProps {
+  b?: boolean;
+  i?: boolean;
+  u?: boolean;
+  s?: boolean;
+  sup?: boolean;
+  sub?: boolean;
+  font?: string;
+  pt?: number;
+  color?: string;
+  bg?: string;
+}
+
+export interface ParaProps {
+  align?: Align;
+  heading?: Heading;
+  indentPt?: number;
+  spaceBefore?: number;
+  spaceAfter?: number;
+  lineHeight?: number;
+  listLv?: number;
+  listOrd?: boolean;
+  listMark?: string;
+}
+
+export interface Stroke {
+  kind: StrokeKind;
+  pt: number;
+  color: string;
+}
+
+export interface CellProps {
+  top?: Stroke;
+  bot?: Stroke;
+  left?: Stroke;
+  right?: Stroke;
+  bg?: string;
+  padPt?: number;
+  align?: Align;
+  va?: VAlign;
+  isHeader?: boolean;
+}
+
+export interface TableLook {
+  firstRow?: boolean;
+  lastRow?: boolean;
+  firstCol?: boolean;
+  lastCol?: boolean;
+  bandedRows?: boolean;
+  bandedCols?: boolean;
+}
+
+export interface GridProps {
+  widthPct?: number;
+  colWidths?: number[];   // column widths in points
+  defaultStroke?: Stroke;
+  look?: TableLook;
+  headerRow?: boolean;
+}
+
+export interface PageDims {
+  wPt: number;
+  hPt: number;
+  mt: number;
+  mb: number;
+  ml: number;
+  mr: number;
+  orient?: 'portrait' | 'landscape';
+}
+
+export interface DocMeta {
+  title?: string;
+  author?: string;
+  subject?: string;
+  desc?: string;
+  keywords?: string;
+  created?: string;
+  modified?: string;
+}
+
+export const A4: PageDims = {
+  wPt: 595.28, hPt: 841.89,
+  mt: 56.69, mb: 56.69, ml: 70.87, mr: 70.87,
+  orient: 'portrait',
+};
+
+export const A4_LANDSCAPE: PageDims = {
+  wPt: 841.89, hPt: 595.28,
+  mt: 56.69, mb: 56.69, ml: 70.87, mr: 70.87,
+  orient: 'landscape',
+};
+
+/**
+ * orient === 'landscape'일 때 wPt < hPt이면 swap,
+ * orient === 'portrait'일 때 wPt > hPt이면 swap하여
+ * 방향과 치수가 항상 일치하도록 정규화합니다.
+ */
+
+export function normalizeDims(dims: PageDims): PageDims {
+  const orient = dims.orient ?? 'portrait';
+  if (orient === 'landscape' && dims.wPt < dims.hPt) {
+    return { ...dims, wPt: dims.hPt, hPt: dims.wPt };
+  }
+  if (orient === 'portrait' && dims.wPt > dims.hPt) {
+    return { ...dims, wPt: dims.hPt, hPt: dims.wPt };
+  }
+  return dims;
+}
+
+export const DEFAULT_STROKE: Stroke = { kind: 'solid', pt: 0.5, color: '000000' };

package/src/model/doc-tree.ts

@@ -0,0 +1,90 @@
+import type { TextProps, ParaProps, CellProps, GridProps, PageDims, DocMeta, ImgLayout } from './doc-props';
+
+// ─── 노드 종류 ─────────────────────────────────────────────
+export type BlockTag =
+  | 'root' | 'sheet' | 'para' | 'span'
+  | 'txt' | 'img' | 'link'
+  | 'grid' | 'row' | 'cell'
+  | 'br' | 'pb' | 'pagenum';
+
+// ─── 리프 노드 ─────────────────────────────────────────────
+export interface TxtNode   { tag: 'txt'; content: string }
+export interface BrNode    { tag: 'br' }
+export interface PbNode    { tag: 'pb' }
+
+export interface PageNumNode {
+  tag: 'pagenum';
+  format?: 'decimal' | 'roman' | 'romanCaps';
+}
+
+export interface ImgNode {
+  tag: 'img';
+  b64: string;
+  mime: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/bmp';
+  w: number;
+  h: number;
+  alt?: string;
+  layout?: ImgLayout;  // 배치/위치 정보 (없으면 inline으로 취급)
+}
+
+// ─── 인라인 노드 ───────────────────────────────────────────
+export interface SpanNode {
+  tag: 'span';
+  props: TextProps;
+  kids: (TxtNode | BrNode | PbNode | PageNumNode)[];
+}
+
+export interface LinkNode {
+  tag: 'link';
+  href: string;
+  kids: SpanNode[];
+}
+
+// ─── 블록 노드 ─────────────────────────────────────────────
+export interface ParaNode {
+  tag: 'para';
+  props: ParaProps;
+  kids: (SpanNode | ImgNode | LinkNode)[];
+}
+
+// ─── 표(Grid) 노드 ─────────────────────────────────────────
+export interface CellNode {
+  tag: 'cell';
+  cs: number;
+  rs: number;
+  props: CellProps;
+  kids: ParaNode[];
+}
+
+export interface RowNode  { tag: 'row'; kids: CellNode[] }
+
+export interface GridNode {
+  tag: 'grid';
+  props: GridProps;
+  kids: RowNode[];
+}
+
+// ─── 섹션(Sheet) 노드 ──────────────────────────────────────
+export type ContentNode = ParaNode | GridNode;
+
+export interface SheetNode {
+  tag: 'sheet';
+  dims: PageDims;
+  kids: ContentNode[];
+  header?: ParaNode[];
+  footer?: ParaNode[];
+}
+
+// ─── 루트 노드 ─────────────────────────────────────────────
+export interface DocRoot {
+  tag: 'root';
+  meta: DocMeta;
+  kids: SheetNode[];
+}
+
+// ─── 모든 노드의 유니온 ─────────────────────────────────────
+export type AnyNode =
+  | DocRoot | SheetNode | ParaNode | SpanNode
+  | TxtNode | ImgNode | LinkNode
+  | GridNode | RowNode | CellNode
+  | BrNode | PbNode | PageNumNode;

package/src/pipeline/Pipeline.ts

@@ -0,0 +1,71 @@
+import type { DocRoot } from '../model/doc-tree';
+import type { Outcome } from '../contract/result';
+import { fail } from '../contract/result';
+import { registry } from './registry';
+
+// Side-effect imports: auto-register all decoders and encoders
+import '../decoders/hwpx/HwpxDecoder';
+import '../decoders/hwp/HwpScanner';
+import '../decoders/docx/DocxDecoder';
+import '../decoders/md/MdDecoder';
+import '../encoders/hwpx/HwpxEncoder';
+import '../encoders/docx/DocxEncoder';
+import '../encoders/md/MdEncoder';
+
+export class Pipeline {
+  private constructor(private raw: Uint8Array, private srcFmt: string) {}
+
+  /** 파일을 열고 포맷을 자동 감지하거나 명시 */
+  static open(input: Uint8Array | string, fmt?: string): Pipeline {
+    if (typeof input === 'string') {
+      return new Pipeline(new TextEncoder().encode(input), fmt ?? 'md');
+    }
+    return new Pipeline(input, fmt ?? detectFormat(input));
+  }
+
+  /** File/Blob 비동기 입력 */
+  static async openAsync(input: File | Blob | Uint8Array | string, fmt?: string): Promise<Pipeline> {
+    if (input instanceof Uint8Array || typeof input === 'string') {
+      return Pipeline.open(input, fmt);
+    }
+    const buf = await input.arrayBuffer();
+    const data = new Uint8Array(buf);
+    const detectedFmt = fmt ?? (input instanceof File ? getExt(input.name) : undefined) ?? detectFormat(data);
+    return new Pipeline(data, detectedFmt);
+  }
+
+  /** 목표 포맷으로 변환 */
+  async to(targetFmt: string): Promise<Outcome<Uint8Array>> {
+    const decoder = registry.getDecoder(this.srcFmt);
+    const encoder = registry.getEncoder(targetFmt);
+
+    if (!decoder) return fail(`지원하지 않는 입력 포맷: ${this.srcFmt}`);
+    if (!encoder) return fail(`지원하지 않는 출력 포맷: ${targetFmt}`);
+
+    const docResult = await decoder.decode(this.raw);
+    if (!docResult.ok) return docResult;
+
+    const encResult = await encoder.encode(docResult.data);
+    if (!encResult.ok) return { ...encResult, warns: [...docResult.warns, ...encResult.warns] };
+
+    return { ...encResult, warns: [...docResult.warns, ...encResult.warns] };
+  }
+
+  /** DocRoot만 추출 (인코딩 없이) */
+  async inspect(): Promise<Outcome<DocRoot>> {
+    const decoder = registry.getDecoder(this.srcFmt);
+    if (!decoder) return fail(`디코더 없음: ${this.srcFmt}`);
+    return decoder.decode(this.raw);
+  }
+}
+
+function detectFormat(data: Uint8Array): string {
+  if (data[0] === 0x50 && data[1] === 0x4B) return 'zip';
+  if (data[0] === 0xD0 && data[1] === 0xCF && data[2] === 0x11 && data[3] === 0xE0) return 'hwp';
+  return 'md';
+}
+
+function getExt(name: string): string | undefined {
+  const parts = name.split('.');
+  return parts.length > 1 ? parts[parts.length - 1].toLowerCase() : undefined;
+}

package/src/pipeline/registry.ts

@@ -0,0 +1,18 @@
+import type { Decoder } from '../contract/decoder';
+import type { Encoder } from '../contract/encoder';
+
+class FormatRegistry {
+  private decoders = new Map<string, Decoder>();
+  private encoders = new Map<string, Encoder>();
+
+  registerDecoder(d: Decoder): void { this.decoders.set(d.format, d); }
+  registerEncoder(e: Encoder): void { this.encoders.set(e.format, e); }
+
+  getDecoder(fmt: string): Decoder | undefined { return this.decoders.get(fmt); }
+  getEncoder(fmt: string): Encoder | undefined { return this.encoders.get(fmt); }
+
+  supportedInputs(): string[]  { return [...this.decoders.keys()]; }
+  supportedOutputs(): string[] { return [...this.encoders.keys()]; }
+}
+
+export const registry = new FormatRegistry();

package/src/safety/ShieldedParser.ts

@@ -0,0 +1,91 @@
+export class ShieldedParser {
+  private log: string[] = [];
+
+  /** 단일 요소 안전 파싱 */
+  guard<T>(fn: () => T, fallback: T, label: string): T {
+    try {
+      const v = fn();
+      if (v == null) {
+        this.warn(label, 'returned null/undefined');
+        return fallback;
+      }
+      return v;
+    } catch (e: any) {
+      this.warn(label, e?.message ?? String(e));
+      return fallback;
+    }
+  }
+
+  /** 배열 각 요소 독립 파싱 (하나 실패해도 나머지 계속) */
+  guardAll<I, O>(
+    items: I[],
+    fn: (x: I, i: number) => O,
+    fb: (x: I, i: number) => O,
+    label: string,
+  ): O[] {
+    return items.map((x, i) =>
+      this.guard(() => fn(x, i), fb(x, i), `${label}[${i}]`),
+    );
+  }
+
+  /**
+   * 표 전용 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 } {
+    const levels: [(n: unknown) => T, 1 | 2 | 3 | 4][] = [
+      [lv1Full, 1], [lv2Grid, 2], [lv3Flat, 3], [lv4Text, 4],
+    ];
+
+    for (const [fn, lv] of levels) {
+      try {
+        const v = fn(node);
+        if (v != null) {
+          if (lv > 1) this.warn(label, `degraded to level ${lv}`);
+          return { value: v, level: lv };
+        }
+      } catch (e: any) {
+        this.warn(label, `Lv${lv} failed: ${e?.message ?? String(e)}`);
+      }
+    }
+
+    this.warn(label, 'ALL LEVELS FAILED — returning lv4Text forced');
+    return { value: lv4Text(null), level: 4 };
+  }
+
+  /** 이미지 안전 파싱 */
+  guardImg<T>(
+    node: unknown,
+    fn: (n: unknown) => T,
+    placeholder: (alt: string) => T,
+    label: string,
+  ): T {
+    try {
+      const v = fn(node);
+      if (v != null) return v;
+    } catch (e: any) {
+      this.warn(label, e?.message ?? String(e));
+    }
+    this.warn(label, 'using placeholder image');
+    return placeholder(`[이미지 로드 실패: ${label}]`);
+  }
+
+  private warn(label: string, msg: string): void {
+    const w = `[SHIELD] ${label}: ${msg}`;
+    console.warn(w);
+    this.log.push(w);
+  }
+
+  flush(): string[] {
+    const r = [...this.log];
+    this.log = [];
+    return r;
+  }
+}