treesearchlib 1.1.0__py3-none-any.whl

treesearch/parsers/__init__.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+"""
+@author:XuMing(xuming624@qq.com)
+@description: Parser registry for file-type-aware indexing and pre-filter routing.
+
+Provides a unified interface for file parsers and automatic routing of
+file types to appropriate parser + pre-filter combinations.
+"""
+from .registry import (
+    ParserRegistry,
+    get_parser,
+    SOURCE_TYPE_MAP,
+    PREFILTER_ROUTING,
+    get_prefilters_for_source_type,
+)
+from .ast_parser import parse_python_structure
+from .anydoc_parser import anydoc_to_tree, ANYDOC_EXTENSIONS
+
+# PDF parser (optional)
+try:
+    from .pdf_parser import extract_pdf_text, PDF_EXTENSIONS
+    _has_pdf = True
+except ImportError:
+    _has_pdf = False
+
+# Excel parser (optional)
+try:
+    from .excel_parser import excel_to_tree, EXCEL_EXTENSIONS
+    _has_excel = True
+except ImportError:
+    _has_excel = False
+
+# Tree-sitter parser (optional)
+try:
+    from .treesitter_parser import (
+        parse_treesitter_structure,
+        treesitter_code_to_tree,
+        EXT_TO_LANGUAGE,
+    )
+    _has_treesitter = True
+except ImportError:
+    _has_treesitter = False
+
+__all__ = [
+    "ParserRegistry",
+    "get_parser",
+    "SOURCE_TYPE_MAP",
+    "PREFILTER_ROUTING",
+    "get_prefilters_for_source_type",
+    "parse_python_structure",
+    "anydoc_to_tree",
+    "ANYDOC_EXTENSIONS",
+]
+
+if _has_pdf:
+    __all__ += ["extract_pdf_text", "PDF_EXTENSIONS"]
+
+if _has_excel:
+    __all__ += ["excel_to_tree", "EXCEL_EXTENSIONS"]
+
+if _has_treesitter:
+    __all__ += ["parse_treesitter_structure", "treesitter_code_to_tree", "EXT_TO_LANGUAGE"]

treesearch/parsers/anydoc_parser.py

@@ -0,0 +1,193 @@
+# -*- coding: utf-8 -*-
+"""
+@author:XuMing(xuming624@qq.com)
+@description: anydoc-based parser for TreeSearch.
+
+Uses Firecrawl's ``anydoc`` (pure Rust, PyPI: firecrawl-anydoc) to convert
+legacy/office-adjacent documents to Markdown, then feeds the result into the
+existing ``md_to_tree`` pipeline.
+
+Covers: .doc/.docm (Word 97-2003), .ppt/.pps/.pot (PowerPoint 97-2003),
+.xls (Excel 97-2003), .rtf, .epub.
+
+Requires dependency: ``pip install firecrawl-anydoc``（主依赖，ADR-0013）。
+
+Notes:
+- anydoc 按内容识别格式（扩展名标错也能转），无需显式 format 参数。
+- ppt 老格式输出为扁平段落（无 slide 边界/标题），直接走 md_to_tree，
+  不做 pptx 式的根节点包裹（markitdown 每 slide 一个 ``#`` 标题才可包裹）。
+- anydoc 的 Markdown 序列化器不输出图片引用（仅保留 alt 文本），内嵌图片
+  经 ``to_document().assets`` 提取落盘后统一附加到文档末尾。
+"""
+
+import io
+import logging
+import os
+import re
+import zipfile
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from .image_store import ImagePart, ImageStore
+
+logger = logging.getLogger(__name__)
+
+# Extensions handled by anydoc
+ANYDOC_EXTENSIONS = {
+    ".doc", ".docm",                    # Word 97-2003
+    ".ppt", ".pps", ".pot",             # PowerPoint 97-2003
+    ".xls",                             # Excel 97-2003
+    ".rtf",
+    ".epub",
+}
+
+# anydoc Asset.media_type → 落盘扩展名（仅 image/* 会落盘，其余跳过）
+_MEDIA_TYPE_TO_EXT = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "image/bmp": "bmp",
+    "image/tiff": "tiff",
+    "image/svg+xml": "svg",
+    "image/x-emf": "emf",
+    "image/x-wmf": "wmf",
+}
+
+
+def _convert(data: bytes) -> tuple[str, object]:
+    """anydoc 转换：(markdown, document)。ConvertError 记具体原因后抛出。"""
+    import anydoc
+
+    try:
+        md_content = anydoc.to_markdown_bytes(data)
+        document = anydoc.to_document(data)
+    except anydoc.EncryptedError as e:
+        logger.warning("anydoc: encrypted document, skipped: %s", e)
+        raise
+    except anydoc.ConvertError as e:
+        logger.warning("anydoc conversion failed (%s): %s", type(e).__name__, e)
+        raise
+    return md_content or "", document
+
+
+def _check_epub_drm(data: bytes) -> None:
+    """epub(zip) 含 META-INF/encryption.xml → 全书 DRM 加密，抛清晰错误。
+
+    anydoc 对加密 epub 只会报误导性的 "malformed document: no rootfile entry"
+    （container.xml 本身也是密文）。此处预检给出真实原因；error message 会被
+    indexer 记入 failed_files.last_error 并在 UI 展示。
+    """
+    try:
+        with zipfile.ZipFile(io.BytesIO(data)) as z:
+            if "META-INF/encryption.xml" not in z.namelist():
+                return
+            vendor = ""
+            try:
+                enc_xml = z.read("META-INF/encryption.xml").decode("utf-8", errors="replace")
+                m = re.search(r"<Proprietary>([^<]+)</Proprietary>", enc_xml)
+                if m:
+                    vendor = f"（{m.group(1)}）"
+            except Exception:  # noqa: BLE001
+                pass
+    except zipfile.BadZipFile:
+        return  # 非 zip 留给 anydoc 自己报错
+    raise RuntimeError(f"EPUB 含 DRM 加密{vendor}，内容为密文，不支持解析")
+
+
+def _extract_images(document: object, image_store: "ImageStore", rel_path: str) -> list[str]:
+    """提取 assets 中的图片落盘，返回 inline_md 列表（文档序）。
+
+    仅 image/* 媒体类型落盘；OLE 对象等非图 asset 跳过。
+    anydoc 不提供图片在正文中的位置，disp_w 未知（前端退回 naturalWidth）。
+    """
+    from .image_store import ImagePart
+
+    parts: list["ImagePart"] = []
+    for asset in document.assets:
+        media_type = (asset.media_type or "").lower()
+        if not media_type.startswith("image/"):
+            logger.debug("skip non-image asset: %s (%s)", asset.origin_part, media_type)
+            continue
+        parts.append(
+            ImagePart(
+                blob=asset.data,
+                ext=_MEDIA_TYPE_TO_EXT.get(media_type, "png"),
+                source_ref=str(asset.id),
+                disp_w=None,
+            )
+        )
+    if not parts:
+        return []
+    refs = image_store.extract_for_doc(rel_path, parts)
+    return [refs[p.source_ref].inline_md for p in parts if p.source_ref in refs]
+
+
+async def anydoc_to_tree(
+    file_path: str,
+    *,
+    model: Optional[str] = None,
+    if_add_node_summary: bool = True,
+    summary_chars_threshold: int = 600,
+    if_add_doc_description: bool = False,
+    if_add_node_text: bool = False,
+    if_add_node_id: bool = True,
+    image_store: "ImageStore | None" = None,
+    rel_path: str | None = None,
+    **kwargs,
+) -> dict:
+    """Build a tree index from a document via anydoc.
+
+    Converts the document to Markdown using ``anydoc``, extracts embedded
+    images to ImageStore, then delegates to ``md_to_tree`` for structure
+    extraction.
+
+    Returns:
+        {'doc_name': str, 'structure': list, 'source_path': str}
+    """
+    try:
+        import anydoc  # noqa: F401
+    except ImportError:
+        raise ImportError(
+            "anydoc support requires 'firecrawl-anydoc'. "
+            "Install with: pip install firecrawl-anydoc"
+        )
+
+    doc_name = os.path.splitext(os.path.basename(file_path))[0]
+    logger.debug("Parsing with anydoc: %s", file_path)
+
+    with open(file_path, "rb") as f:
+        data = f.read()
+
+    if file_path.lower().endswith(".epub"):
+        _check_epub_drm(data)
+
+    md_content, document = _convert(data)
+    if not md_content.strip():
+        logger.warning("anydoc returned empty content for: %s", file_path)
+        md_content = ""
+
+    # 内嵌图片提取：anydoc 的 md 不含图片位置，统一附加到文档末尾
+    if image_store is not None and rel_path:
+        try:
+            image_mds = _extract_images(document, image_store, rel_path)
+            if image_mds:
+                md_content = md_content.rstrip() + "\n\n" + "\n\n".join(image_mds)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("anydoc image extraction failed for %s: %s", file_path, e)
+
+    from ..indexer import md_to_tree
+
+    tree_result = await md_to_tree(
+        md_content=md_content,
+        model=model,
+        if_add_node_summary=if_add_node_summary,
+        summary_chars_threshold=summary_chars_threshold,
+        if_add_doc_description=if_add_doc_description,
+        if_add_node_text=if_add_node_text,
+        if_add_node_id=if_add_node_id,
+        **kwargs,
+    )
+    tree_result["doc_name"] = doc_name
+    tree_result["source_path"] = os.path.abspath(file_path)
+    return tree_result

treesearch/parsers/ast_parser.py

@@ -0,0 +1,136 @@
+# -*- coding: utf-8 -*-
+"""
+@author:XuMing(xuming624@qq.com)
+@description: Python AST-based code structure parser.
+
+Uses the built-in ``ast`` module to extract classes and functions from
+Python source files, replacing regex-based detection for `.py` files.
+Falls back to regex if AST parsing fails (e.g. syntax errors).
+"""
+import ast
+import logging
+import warnings
+
+logger = logging.getLogger(__name__)
+
+
+def parse_python_structure(source: str) -> list[dict]:
+    """Parse Python source code using AST and return a flat heading list.
+
+    Returns:
+        list of {'title': str, 'line_num': int, 'level': int}
+        level 1 = class, level 2 = function/method
+    """
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", SyntaxWarning)
+            tree = ast.parse(source)
+    except SyntaxError as e:
+        logger.debug("AST parse failed (syntax error at line %s), falling back to regex", e.lineno)
+        return []
+
+    headings = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            # Build class signature with bases
+            bases = ", ".join(_name_of(b) for b in node.bases) if node.bases else ""
+            title = f"class {node.name}({bases})" if bases else f"class {node.name}"
+            headings.append({
+                "title": title,
+                "line_num": node.lineno,
+                "level": 1,
+            })
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            prefix = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
+            args_str = _format_args(node.args)
+            # Return annotation
+            ret = ""
+            if node.returns:
+                ret = f" -> {_name_of(node.returns)}"
+            title = f"{prefix} {node.name}({args_str}){ret}"
+            # Truncate long signatures
+            if len(title) > 120:
+                title = title[:117] + "..."
+            headings.append({
+                "title": title,
+                "line_num": node.lineno,
+                "level": 2,
+            })
+
+    # Sort by line number (ast.walk doesn't guarantee order)
+    headings.sort(key=lambda h: h["line_num"])
+    return headings
+
+
+def _name_of(node) -> str:
+    """Extract a readable name from an AST node."""
+    if isinstance(node, ast.Name):
+        return node.id
+    elif isinstance(node, ast.Attribute):
+        return f"{_name_of(node.value)}.{node.attr}"
+    elif isinstance(node, ast.Constant):
+        return repr(node.value)
+    elif isinstance(node, ast.Subscript):
+        return f"{_name_of(node.value)}[{_name_of(node.slice)}]"
+    elif isinstance(node, ast.Tuple):
+        return ", ".join(_name_of(e) for e in node.elts)
+    elif isinstance(node, ast.List):
+        return "[" + ", ".join(_name_of(e) for e in node.elts) + "]"
+    elif isinstance(node, ast.Starred):
+        return f"*{_name_of(node.value)}"
+    elif isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+        return f"{_name_of(node.left)} | {_name_of(node.right)}"
+    return "..."
+
+
+def _format_args(args: ast.arguments) -> str:
+    """Format function arguments to a readable string."""
+    parts = []
+
+    # Positional-only
+    for a in args.posonlyargs:
+        parts.append(a.arg)
+    if args.posonlyargs:
+        parts.append("/")
+
+    # Regular args
+    defaults_offset = len(args.args) - len(args.defaults)
+    for i, a in enumerate(args.args):
+        name = a.arg
+        if a.annotation:
+            name += f": {_name_of(a.annotation)}"
+        di = i - defaults_offset
+        if di >= 0 and di < len(args.defaults):
+            name += f"={_name_of(args.defaults[di])}"
+        parts.append(name)
+
+    # *args
+    if args.vararg:
+        parts.append(f"*{args.vararg.arg}")
+    elif args.kwonlyargs:
+        parts.append("*")
+
+    # Keyword-only
+    for i, a in enumerate(args.kwonlyargs):
+        name = a.arg
+        if a.annotation:
+            name += f": {_name_of(a.annotation)}"
+        if i < len(args.kw_defaults) and args.kw_defaults[i] is not None:
+            name += f"={_name_of(args.kw_defaults[i])}"
+        parts.append(name)
+
+    # **kwargs
+    if args.kwarg:
+        parts.append(f"**{args.kwarg.arg}")
+
+    result = ", ".join(parts)
+    # Skip 'self' / 'cls' at the beginning for readability
+    for prefix in ("self, ", "cls, "):
+        if result.startswith(prefix):
+            result = result[len(prefix):]
+            break
+    if result in ("self", "cls"):
+        result = ""
+
+    return result

treesearch/parsers/docx_parser.py

@@ -0,0 +1,304 @@
+# -*- coding: utf-8 -*-
+"""
+@author:XuMing(xuming624@qq.com)
+@description: DOCX parser for TreeSearch.
+
+Requires optional dependency: ``pip install python-docx``
+Extracts paragraphs and headings from DOCX and builds tree structure.
+"""
+import logging
+import os
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .image_store import ImagePart, ImageStore
+
+logger = logging.getLogger(__name__)
+
+
+def _escape_md_cell(s: str) -> str:
+    """转义 md table 单元格：``|`` → ``\\|``，换行 → 空格，回车删除。
+
+    与 csv/xlsx 在 preview_synthesizer._escape_md_cell 的口径一致。
+    """
+    return s.replace("|", "\\|").replace("\n", " ").replace("\r", "")
+
+
+def _table_to_text(table) -> str:
+    """Convert a docx Table to a GitHub-flavored markdown table string.
+
+    首行视为 header，输出形如::
+
+        | h1 | h2 |
+        | --- | --- |
+        | v1 | v2 |
+
+    这样前端 ``<md-viewer>`` 才能识别为真正的表格（缺 separator 行只会被
+    当成软换行段落）。单元格里的 ``|`` 转义为 ``\\|``，换行替换为空格。
+    """
+    rows = []
+    ncols = 0
+    for row in table.rows:
+        cells = [_escape_md_cell(cell.text.strip()) for cell in row.cells]
+        ncols = max(ncols, len(cells))
+        rows.append("| " + " | ".join(cells) + " |")
+    if not rows or ncols == 0:
+        return ""
+    separator = "| " + " | ".join(["---"] * ncols) + " |"
+    return "\n".join([rows[0], separator, *rows[1:]])
+
+
+def _paragraph_image_rids(para) -> list[str]:
+    """段落内所有图片的 rId（按文档顺序，含 inline + anchor）。"""
+    from docx.oxml.ns import qn
+    return [blip.get(qn("r:embed"))
+            for blip in para._p.findall(".//" + qn("a:blip"))
+            if blip.get(qn("r:embed"))]
+
+
+def _list_marker(para) -> str:
+    """列表段落 → md 列表符号前缀（按 ilvl 缩进）；非列表 → ''。
+
+    ``para.text`` 不含项目符号/编号（numPr 由 Word 渲染期生成），导致 docx
+    列表在索引与预览里退化为普通段落。检测段落级 ``w:numPr``（Word 列表的
+    常规编码）或 List 系样式名，补回 ``- `` 前缀——与 anydoc 的 docx→md
+    输出口径一致（统一 ``-``，不区分有序/无序）。标题样式直接跳过（编号
+    标题不应变成列表项）。
+    """
+    from docx.oxml.ns import qn
+
+    style_name = ((para.style.name if para.style else "") or "").lower()
+    if style_name.startswith("heading"):
+        return ""
+
+    pPr = para._p.pPr
+    numPr = pPr.find(qn("w:numPr")) if pPr is not None else None
+    if numPr is None:
+        return "- " if "list" in style_name else ""
+    ilvl = 0
+    ilvl_el = numPr.find(qn("w:ilvl"))
+    if ilvl_el is not None:
+        try:
+            ilvl = int(ilvl_el.get(qn("w:val"), 0))
+        except (ValueError, TypeError):
+            ilvl = 0
+    return "  " * ilvl + "- "
+
+
+def _docx_part_blob_ext(doc, rid: str) -> tuple[bytes, str] | None:
+    """按 rId 取 image part 的 (blob, ext)，失败返回 None。"""
+    try:
+        part = doc.part.related_parts.get(rid)
+        if part is None:
+            return None
+        blob = part.blob
+        ext = ""
+        try:
+            ext = part.image.ext
+        except Exception:
+            partname = getattr(part, "partname", None)
+            ext = partname.ext.lstrip(".") if partname and partname.ext else ""
+        return blob, (ext or "png")
+    except Exception as e:
+        logger.warning("Failed to extract docx image part %s: %s", rid, e)
+        return None
+
+
+def _docx_rid_disp_w_map(doc) -> dict[str, int]:
+    """遍历 body 内所有 drawing，返回 {rId: 显示宽 px}（EMU÷9525）。
+
+    每个 ``<w:drawing>`` 内 ``<wp:extent cx>`` 与 ``<a:blip r:embed>`` 关联，
+    覆盖 inline 与 anchor 两种锚定方式；取不到 extent 的图不在映射里（disp_w=None）。
+    """
+    from docx.oxml.ns import qn
+
+    mapping: dict[str, int] = {}
+    for drawing in doc.element.body.findall(".//" + qn("w:drawing")):
+        extent = drawing.find(".//" + qn("wp:extent"))
+        blip = drawing.find(".//" + qn("a:blip"))
+        if extent is None or blip is None:
+            continue
+        rid = blip.get(qn("r:embed"))
+        cx = extent.get("cx")
+        if not rid or not cx:
+            continue
+        try:
+            mapping[rid] = round(int(cx) / 9525)
+        except (ValueError, TypeError):
+            continue
+    return mapping
+
+
+def _extract_docx_headings(
+    docx_path: str,
+    image_store: "ImageStore | None" = None,
+    rel_path: str | None = None,
+) -> tuple[list[dict], list[str]]:
+    """Extract headings and text from a DOCX file.
+
+    Iterates document body elements in order so that tables are
+    interleaved with paragraphs at the correct position.
+
+    Returns:
+        (headings, lines) where headings is a list of
+        {'title': str, 'line_num': int, 'level': int}
+    """
+    try:
+        from docx import Document as DocxDocument
+        from docx.oxml.ns import qn
+        from docx.table import Table
+        from docx.text.paragraph import Paragraph
+    except ImportError:
+        raise ImportError(
+            "DOCX support requires 'python-docx'. Install with: pip install python-docx"
+        )
+
+    doc = DocxDocument(docx_path)
+    lines = []
+    headings = []
+    para_image_rids: list[list[str]] = []
+
+    for child in doc.element.body:
+        tag = child.tag.split("}")[-1] if "}" in child.tag else child.tag
+
+        if tag == "p":
+            para = Paragraph(child, doc)
+            text = para.text.strip()
+            if text:
+                text = _list_marker(para) + text
+            rids = _paragraph_image_rids(para)
+            line_num = len(lines) + 1
+            lines.append(text)
+            para_image_rids.append(rids)
+
+            style_name = (para.style.name if para.style else "") or ""
+            style_name = style_name.lower()
+            if style_name.startswith("heading"):
+                try:
+                    level = int(style_name.split()[-1])
+                except (ValueError, IndexError):
+                    level = 1
+                if text:
+                    headings.append({
+                        "title": text,
+                        "line_num": line_num,
+                        "level": level,
+                    })
+
+        elif tag == "tbl":
+            table = Table(child, doc)
+            table_text = _table_to_text(table)
+            if table_text.strip():
+                line_num = len(lines) + 1
+                lines.append(table_text)
+                para_image_rids.append([])
+
+    # 图片提取 + 段落级锚定
+    if image_store is not None and rel_path:
+        unique_rids: list[str] = []
+        seen: set[str] = set()
+        for rids in para_image_rids:
+            for r in rids:
+                if r and r not in seen:
+                    seen.add(r)
+                    unique_rids.append(r)
+        disp_map = _docx_rid_disp_w_map(doc)
+        parts_list = []
+        for rid in unique_rids:
+            be = _docx_part_blob_ext(doc, rid)
+            if be is not None:
+                from .image_store import ImagePart
+                parts_list.append(
+                    ImagePart(
+                        blob=be[0], ext=be[1], source_ref=rid,
+                        disp_w=disp_map.get(rid),
+                    )
+                )
+        refs = image_store.extract_for_doc(rel_path, parts_list) if parts_list else {}
+        for i, rids in enumerate(para_image_rids):
+            mds = [refs[r].inline_md for r in rids if r in refs]
+            if mds:
+                base = lines[i]
+                lines[i] = (base + "\n\n" + " ".join(mds)) if base else " ".join(mds)
+
+    return headings, lines
+
+
+async def docx_to_tree(
+    docx_path: str,
+    *,
+    model: Optional[str] = None,
+    if_add_node_summary: bool = True,
+    summary_chars_threshold: int = 600,
+    if_add_doc_description: bool = False,
+    if_add_node_text: bool = False,
+    if_add_node_id: bool = True,
+    image_store: "ImageStore | None" = None,
+    rel_path: str | None = None,
+    **kwargs,
+) -> dict:
+    """Build a tree index from a DOCX file.
+
+    Extracts headings via ``python-docx`` paragraph styles. If no headings
+    are found, falls back to ``text_to_tree`` with plain text content.
+
+    Returns:
+        {'doc_name': str, 'structure': list, 'source_path': str}
+    """
+    doc_name = os.path.splitext(os.path.basename(docx_path))[0]
+    logger.debug("Parsing DOCX: %s", docx_path)
+
+    headings, lines = _extract_docx_headings(docx_path, image_store=image_store, rel_path=rel_path)
+
+    if not headings:
+        # No DOCX headings found, fall back to text_to_tree.
+        # 用 \n\n 分段（过滤空段），让 text_to_tree 和下游 preview 都能正确识别段落边界。
+        text_content = "\n\n".join(ln for ln in lines if ln.strip())
+        from ..indexer import text_to_tree
+        result = await text_to_tree(
+            text_content=text_content,
+            model=model,
+            if_add_node_summary=if_add_node_summary,
+            summary_chars_threshold=summary_chars_threshold,
+            if_add_doc_description=if_add_doc_description,
+            if_add_node_text=if_add_node_text,
+            if_add_node_id=if_add_node_id,
+            **kwargs,
+        )
+        result["doc_name"] = doc_name
+        result["source_path"] = os.path.abspath(docx_path)
+        return result
+
+    # Build nodes from headings
+    from ..indexer import _build_tree, _finalize_tree
+
+    nodes = []
+    for i, hd in enumerate(headings):
+        start = hd["line_num"] - 1
+        end = headings[i + 1]["line_num"] - 1 if i + 1 < len(headings) else len(lines)
+        # 用 \n\n 分隔非空段落，保留 docx 段落结构。
+        # 否则 preview synthesizer 输出单 \n，CommonMark 渲染会把多段合并成一段。
+        # 表格项作为整体参与连接（内部保持单 \n），与相邻段落正确分段。
+        paragraphs = [ln for ln in lines[start:end] if ln.strip()]
+        text = "\n\n".join(paragraphs).strip()
+        nodes.append({
+            "title": hd["title"],
+            "line_num": hd["line_num"],
+            "line_start": hd["line_num"],
+            "line_end": end,
+            "level": hd["level"],
+            "text": text,
+        })
+
+    tree = _build_tree(nodes)
+
+    return _finalize_tree(
+        tree, doc_name,
+        source_path=os.path.abspath(docx_path),
+        source_type="docx",
+        if_add_node_id=if_add_node_id,
+        if_add_node_summary=if_add_node_summary,
+        summary_chars_threshold=summary_chars_threshold,
+        if_add_node_text=if_add_node_text,
+        if_add_doc_description=if_add_doc_description,
+    )