itol-cli 0.2.0__py3-none-any.whl

itol_cli/lint.py

@@ -0,0 +1,250 @@
+"""itol lint — iTOL 注解文件本地校验器（差异化护城河：人/AI 手写模板的第一道关）。
+
+校验规则基于官方模板实证（workflows/itol_research/agent2_formats.md + downloads/templates/）：
+- 首行关键字是模板锚（不是文件名！）
+- 官方 CONNECTION 是单数；DOMAINS 不是 PROTEINDOMAINS
+- 默认 SPACE 分隔；SEPARATOR 行可改 TAB/COMMA
+- 内部节点一律 LCA 写法 ID1|ID2
+- DATA 段前全是 KEY VALUE 控制行
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# 官方模板类型（首行关键字，单一权威）——以 30 个官方模板实测全集为准（2026-11-02 校准）
+KNOWN_KEYWORDS = {
+    # 树本身控制
+    "TREE_COLORS", "DATASET_STYLE", "MULTI_STYLE", "LABELS", "POPUP_INFO", "COLLAPSE", "PRUNE", "SPACING",
+    "AUTO_TAXONOMY", "METADATA",
+    # 数据集
+    "DATASET_COLORSTRIP", "DATASET_BINARY", "DATASET_GRADIENT", "DATASET_HEATMAP",
+    "DATASET_SYMBOL", "DATASET_EXTERNALSHAPE", "DATASET_DOMAINS", "DATASET_SIMPLEBAR",
+    "DATASET_MULTIBAR", "DATASET_BOXPLOT", "DATASET_LINECHART", "DATASET_PIECHART",
+    "DATASET_ALIGNMENT", "DATASET_CONNECTION", "DATASET_IMAGE", "DATASET_TEXT",
+    "DATASET_ARROWS", "DATASET_RANGE", "DATASET_TANGLEGRAM", "DATASET_TIMESCALE",
+}
+# 常见写错/别名（给诊断建议）
+ALIASES = {
+    "DATASET_CONNECTIONS": "DATASET_CONNECTION（官方是单数！）",
+    "DATASET_PROTEINDOMAINS": "DATASET_DOMAINS",
+    "DATASET_COLOR_STRIP": "DATASET_COLORSTRIP",
+    "TREE_COLOR": "TREE_COLORS",
+}
+SEPARATORS = {"SPACE": None, "TAB": "\t", "COMMA": ","}  # None = 任意空白
+# 官方允许 hex / rgb() / rgba()（COLORSTRIP 模板实证：rgba(0,255,0,0.5) 合法）
+HEX_RE = re.compile(r"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$")
+RGB_RE = re.compile(r"^rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*(?:,\s*[\d.]+\s*)?\)$", re.IGNORECASE)
+
+
+def _is_color(s: str) -> bool:
+    return bool(HEX_RE.match(s) or RGB_RE.match(s))
+
+
+@dataclass
+class LintIssue:
+    level: str  # "error" | "warning"
+    line: int   # 0-based；-1 = 文件级
+    message: str
+
+
+@dataclass
+class LintReport:
+    path: str
+    keyword: str = ""
+    issues: list = field(default_factory=list)
+
+    @property
+    def errors(self):
+        return [i for i in self.issues if i.level == "error"]
+
+    @property
+    def warnings(self):
+        return [i for i in self.issues if i.level == "warning"]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def add(self, level: str, line: int, message: str) -> None:
+        self.issues.append(LintIssue(level, line, message))
+
+    def summary(self) -> str:
+        head = f"{'✅' if self.ok else '❌'} {self.path}  (类型: {self.keyword or '未知'})"
+        lines = [f"  L{i.line + 1}: [{i.level}] {i.message}" for i in self.issues]
+        return "\n".join([head] + lines)
+
+
+def _detect_separator(header_lines: list[str]) -> tuple[str, str | None]:
+    for ln in header_lines:
+        parts = ln.split(None, 1)
+        if parts and parts[0].upper() == "SEPARATOR" and len(parts) == 2:
+            val = parts[1].strip().upper()
+            if val in SEPARATORS:
+                return val, SEPARATORS[val]
+            return val, None  # 未知分隔符 → 按 SPACE 处理但告警
+    return "SPACE", None
+
+
+def lint_file(path: Path) -> LintReport:
+    path = Path(path)
+    rep = LintReport(path=str(path))
+    if not path.is_file():
+        rep.add("error", -1, "文件不存在")
+        return rep
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    lines = raw.splitlines()
+
+    # 1. 首行关键字
+    first = next((ln.strip() for ln in lines if ln.strip()), "")
+    if not first:
+        rep.add("error", -1, "空文件")
+        return rep
+    rep.keyword = first
+    if first not in KNOWN_KEYWORDS:
+        hint = ALIASES.get(first)
+        rep.add("error", 0, f"未知首行关键字 {first!r}" + (f"——你是不是想要 {hint}？" if hint else ""))
+
+    # 2. 找 DATA 段（官方模板示例形态可能连 DATA 标记行本身也被注释）
+    try:
+        data_idx = next(i for i, ln in enumerate(lines) if ln.strip().upper() == "DATA")
+    except StopIteration:
+        commented_data = next((i for i, ln in enumerate(lines) if ln.strip().lstrip("#").strip().upper() == "DATA"), None)
+        if commented_data is not None:
+            data_idx = commented_data
+            rep.add("warning", data_idx, "DATA 标记行被注释（官方模板示例形态）")
+        else:
+            rep.add("error", -1, "缺 DATA 段标记行（独立一行 'DATA'）")
+            return rep
+    header = [ln for ln in lines[1:data_idx] if ln.strip() and not ln.strip().startswith("#")]
+    data = [ln for ln in lines[data_idx + 1:] if ln.strip() and not ln.strip().startswith("#")]
+    if not data:
+        # 官方模板形态：示例数据行全部被 # 注释——是模板示例不是真数据，降级 warning
+        commented = [ln for ln in lines[data_idx + 1:] if ln.strip().startswith("#")]
+        if commented:
+            rep.add("warning", data_idx, "DATA 段数据行全部被注释（官方模板示例形态；实数据文件须有非注释数据行）")
+        else:
+            rep.add("error", data_idx, "DATA 段为空")
+
+    # 3. 分隔符一致性
+    sep_name, sep = _detect_separator(header)
+    if sep_name not in SEPARATORS:
+        rep.add("warning", -1, f"未知 SEPARATOR {sep_name!r}（官方只有 SPACE/TAB/COMMA），按 SPACE 校验")
+        sep_name, sep = "SPACE", None
+
+    def split_row(ln: str) -> list[str]:
+        return ln.split(sep) if sep else ln.split()
+
+    # 4. 数据行校验（ALIGNMENT 的 DATA 是 FASTA 序列，不做表格列数检查）
+    widths = set()
+    if rep.keyword != "DATASET_ALIGNMENT":
+        for i, ln in enumerate(data):
+            row = split_row(ln)
+            lineno = data_idx + 1 + i
+            if len(row) < 2:
+                rep.add("error", lineno, f"数据行列数不足（{len(row)} 列）：{ln[:60]!r}")
+                continue
+            widths.add(len(row))
+            # 节点 ID 列非空 + 内部节点 LCA 写法检查
+            nid = row[0]
+            if not nid:
+                rep.add("error", lineno, "节点 ID 为空")
+            if sep == "," and "|" not in nid and " " in nid:
+                rep.add("error", lineno, f"COMMA 分隔下节点 ID 含空格：{nid!r}——内部节点请用 LCA 写法 ID1|ID2")
+
+    # 4.5 类型必填项（官方模板 MANDATORY SETTINGS 区实证：20/20 dataset_* 模板全有 DATASET_LABEL）
+    header_keys = {re.split(r"[\s,]+", ln, maxsplit=1)[0].upper() for ln in header}
+    if rep.keyword.startswith("DATASET_") and "DATASET_LABEL" not in header_keys:
+        rep.add("error", -1, f"{rep.keyword} 缺 MANDATORY 字段 DATASET_LABEL（官方模板必填）")
+    if rep.keyword == "DATASET_COLORSTRIP" and "COLOR" not in header_keys:
+        rep.add("warning", -1, "COLORSTRIP 建议带 COLOR（图例/默认色，官方模板 MANDATORY 区）")
+    if ("LEGEND_COLORS" in header_keys or "LEGEND_LABELS" in header_keys) and "LEGEND_SHAPES" not in header_keys:
+        rep.add("warning", -1, "图例规范=每行 shape+color+label：有 LEGEND_COLORS/LABELS 建议补 LEGEND_SHAPES")
+
+    # 5. 类型特定校验
+    if rep.keyword == "DATASET_COLORSTRIP":
+        for i, ln in enumerate(data):
+            row = split_row(ln)
+            if len(row) >= 2 and not _is_color(row[1]):
+                rep.add("error", data_idx + 1 + i, f"COLORSTRIP 第 2 列应为颜色（hex/rgb/rgba）：{row[1]!r}")
+    if rep.keyword in ("DATASET_HEATMAP", "DATASET_MULTIBAR", "DATASET_BINARY"):
+        labels = None
+        for ln in header:
+            if ln.upper().startswith("FIELD_LABELS"):
+                labels = split_row(ln)[1:] if sep is None else ln.split(sep)[1].split(",")
+        if labels is None:
+            rep.add("warning", -1, f"{rep.keyword} 建议带 FIELD_LABELS（图例列名）")
+        elif widths and len(widths) == 1:
+            ncol = next(iter(widths)) - 1
+            if ncol != len(labels):
+                rep.add("error", -1, f"FIELD_LABELS 数（{len(labels)}）≠ 数据列数（{ncol}）")
+    if rep.keyword == "DATASET_CONNECTION":
+        for i, ln in enumerate(data):
+            row = split_row(ln)
+            lineno = data_idx + 1 + i
+            if len(row) < 2:
+                rep.add("error", lineno, f"CONNECTION 行需 ≥2 列（node1 node2…）：{ln[:60]!r}")
+                continue
+            if "|" in row[0] or "|" in row[1]:
+                rep.add("warning", lineno, "CONNECTION 的节点通常是叶名对，LCA 写法确认是否符合预期")
+            if len(row) >= 3 and row[2]:
+                try:
+                    float(row[2])
+                except ValueError:
+                    rep.add("error", lineno, f"CONNECTION 第 3 列 WIDTH 须为数字：{row[2]!r}")
+            if len(row) >= 4 and row[3] and not _is_color(row[3]):
+                rep.add("error", lineno, f"CONNECTION 颜色非 hex/rgb/rgba：{row[3]!r}")
+            if len(row) >= 5 and row[4] and row[4] not in ("normal", "dashed", "dotted"):
+                rep.add("warning", lineno, f"CONNECTION 线型 {row[4]!r} 不在 normal/dashed/dotted 内")
+    if rep.keyword == "DATASET_RANGE":
+        for i, ln in enumerate(data):
+            row = split_row(ln)
+            if len(row) < 2:
+                rep.add("error", data_idx + 1 + i, f"RANGE 行需 ≥2 列（start_node,end_node…）：{ln[:60]!r}")
+    if rep.keyword == "DATASET_TIMESCALE":
+        for i, ln in enumerate(data):
+            row = split_row(ln)
+            lineno = data_idx + 1 + i
+            if len(row) < 2:
+                rep.add("error", lineno, f"TIMESCALE 行需 ≥2 列（start end…）：{ln[:60]!r}")
+                continue
+            try:
+                s, e = float(row[0]), float(row[1])
+                if s <= e:
+                    rep.add("error", lineno, f"TIMESCALE 约定 start(老)>end(新)，此行 {s}<={e}")
+            except ValueError:
+                rep.add("error", lineno, f"TIMESCALE 区间端点须为数字：{row[:2]!r}")
+    if rep.keyword == "DATASET_DOMAINS":
+        for i, ln in enumerate(data):
+            row = split_row(ln)
+            lineno = data_idx + 1 + i
+            if len(row) < 3:
+                rep.add("error", lineno, f"DOMAINS 数据行需 ≥3 列（ID/蛋白长度/域定义…）：{ln[:60]!r}")
+                continue
+            try:
+                plen = int(row[1])
+            except ValueError:
+                rep.add("error", lineno, f"DOMAINS 第 2 列须为蛋白长度整数：{row[1]!r}")
+                continue
+            for d in row[2:]:
+                parts = d.split("|")
+                if len(parts) != 5:
+                    rep.add("error", lineno, f"域定义需 5 段 SHAPE|START|END|COLOR|LABEL：{d!r}")
+                    continue
+                try:
+                    s, e = int(parts[1]), int(parts[2])
+                    if s >= e:
+                        rep.add("error", lineno, f"域 START>=END：{d!r}")
+                    elif e > plen:
+                        rep.add("error", lineno, f"域 END>{plen}（超蛋白长度）：{d!r}")
+                except ValueError:
+                    rep.add("error", lineno, f"域 START/END 须为整数：{d!r}")
+                if not _is_color(parts[3]):
+                    rep.add("error", lineno, f"域颜色非 hex/rgb/rgba：{parts[3]!r}")
+
+    return rep
+
+
+def lint_paths(paths: list[Path]) -> list[LintReport]:
+    return [lint_file(p) for p in paths]

itol_cli/render.py

@@ -0,0 +1,137 @@
+"""浏览器自动化渲染：Xvfb 虚拟显示 + playwright headful Chrome 驱动 iTOL 树页出带注解图。
+
+突破点（2026-11-04）：iTOL 渲染引擎全在浏览器端，无头 SwiftShader 跑不动树页（~1MB JS），
+但 Xvfb 虚拟显示 + headful Chrome 可正常加载并 exportSVG。这是免费档出带注解图的唯一程序化路。
+
+坑位：DATASET_* 注解必须含 DATASET_LABEL 头行，否则 iTOL handler 静默拒绝注册
+（错误只进 UI 解析日志面板，无异常无返回值）。本模块注入前自动补 + 注册后校验。
+"""
+from __future__ import annotations
+
+import base64
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from .errors import ItolError
+
+CHROME = "/usr/bin/google-chrome"
+
+# 显示模式 → l1I1l.III111I 键值（1矩形/2环形/3无根）。JS 逆向实证：llII1ll(mode) 是官方设置函数
+# （@26599，全代码库反复调用）；@538204 实证 <100 叶强制矩形，≥100 叶默认环形。
+DISPLAY_MODES = {"rect": 1, "circular": 2, "unrooted": 3}
+
+
+def ensure_display(argv: list[str]) -> None:
+    """有 DISPLAY 直接返回；无则 xvfb-run 重跑本命令（结束后 SystemExit 替换当前进程）。"""
+    if os.environ.get("DISPLAY"):
+        return
+    if not shutil.which("xvfb-run"):
+        raise ItolError("IT006", "itol render 需显示环境或 xvfb（虚拟显示）",
+                        diagnosis="apt install xvfb；或改在有显示的环境跑")
+    code = subprocess.call(["xvfb-run", "-a", "--server-args=-screen 0 1600x1200x24",
+                            sys.executable, "-m", "itol_cli.cli", *argv])
+    raise SystemExit(code)
+
+
+def _ensure_dataset_label(path: str) -> str:
+    """DATASET_* 文件缺 DATASET_LABEL 则补（生成器本应已带，这里是安全网）。返回文件内容。"""
+    txt = Path(path).read_text(encoding="utf-8")
+    lines = txt.splitlines()
+    if not lines or not lines[0].startswith("DATASET_"):
+        return txt  # TREE_COLORS/LABELS 等非数据集类不需要
+    if "DATASET_LABEL" in "\n".join(lines[:20]):
+        return txt  # 已有
+    lines.insert(1, f"DATASET_LABEL\t{Path(path).stem}")
+    return "\n".join(lines) + "\n"
+
+
+def _status(msg: str) -> None:
+    """进度反馈（stderr，不污染 stdout 的 SVG 输出）——对标 csvtk/snakemake 的阶段提示。"""
+    import sys
+    print(f"  … {msg}", file=sys.stderr, flush=True)
+
+
+def render(tree_id: str, anno_files: list, out_svg: str | Path,
+           out_png: str | Path | None = None, wait: int = 60,
+           viewport: tuple[int, int] = (1600, 1200), mode: str | None = None) -> dict:
+    """核心渲染：加载树页 → 注入注解 → exportSVG。
+
+    返回 {injected:{文件名:bool}, svg, svg_chars, pageerrors, png?, png_warn?, ok}。
+    ok = 全部注解注入确认；单个失败不抛（由 CLI 汇总），硬失败（模型未就绪/导出失败）抛 ItolError。
+    """
+    try:
+        from playwright.sync_api import Error as PWError
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        raise ItolError("IT006", "itol render 需要 playwright（浏览器自动化渲染路）",
+                        diagnosis="pip install playwright") from None
+    url = f"https://itol.embl.de/tree/{tree_id}"
+    with sync_playwright() as p:
+        _status(f"启动浏览器（Xvfb+Chrome），打开 {url}")
+        browser = p.chromium.launch(headless=False, executable_path=CHROME,
+                                    args=["--no-sandbox", "--disable-dev-shm-usage"])
+        page = browser.new_page(viewport={"width": viewport[0], "height": viewport[1]})
+        errors: list[str] = []
+        page.on("pageerror", lambda e: errors.append(repr(e)[:200]))
+        try:
+            page.goto(url, timeout=90000, wait_until="domcontentloaded")
+            _status("树页已加载，等待数据模型就绪…")
+            ready = False
+            for _ in range(max(1, wait // 2)):
+                time.sleep(2)
+                try:
+                    ready = bool(page.evaluate(
+                        "() => typeof project!=='undefined'&&project&&"
+                        "typeof project.exportSVG==='function'&&"
+                        "typeof treeData!=='undefined'&&typeof lI1lll1==='function'"))
+                except PWError:
+                    ready = False  # 轮询期间瞬时 JS/上下文错误=未就绪，继续等
+                if ready:
+                    break
+            if not ready:
+                raise ItolError("IT003", f"iTOL 树页数据模型 {wait}s 未就绪",
+                                diagnosis="查树 ID 有效性/网络；大树（千叶级）可加 --wait")
+            _status("数据模型就绪，注入注解…")
+            # 显示模式切换（官方函数 llII1ll，含重算+重绘）
+            if mode:
+                _status(f"切换显示模式：{mode}")
+                page.evaluate("(m) => llII1ll(m)", DISPLAY_MODES[mode])
+                time.sleep(2)  # 等模式切换重渲
+            injected: dict[str, bool] = {}
+            for f in anno_files:
+                b64 = base64.b64encode(_ensure_dataset_label(f).encode()).decode()
+                pre = page.evaluate("() => Object.keys(currentData.info.datasets||{}).length")
+                r = page.evaluate(
+                    """(b64) => { try { lI1lll1({name:'a.txt',type:'text/plain',
+                         data:'data:text/plain;base64,'+b64}); return 'ok'; }
+                       catch(e){ return 'ERR '+e; } }""", b64)
+                time.sleep(1.5)
+                post = page.evaluate("() => Object.keys(currentData.info.datasets||{}).length")
+                tcp = page.evaluate("() => !!tree_changes_pending")
+                injected[Path(f).name] = (r == "ok") and (post > pre or tcp)
+            time.sleep(2)  # flush 渲染循环
+            _status("导出 SVG…")
+            svg = page.evaluate(
+                """() => { try { var a=project.exportSVG();
+                     return new XMLSerializer().serializeToString(a); }
+                   catch(e){ return 'ERR '+e; } }""")
+            if not (isinstance(svg, str) and svg.startswith("<")):
+                raise ItolError("IT003", f"exportSVG 失败：{str(svg)[:200]}")
+            Path(out_svg).write_text(svg, encoding="utf-8")
+            result: dict = {"injected": injected, "svg": str(out_svg),
+                            "svg_chars": len(svg), "pageerrors": len(errors),
+                            "ok": all(injected.values())}
+            if out_png:
+                if shutil.which("rsvg-convert"):
+                    subprocess.run(["rsvg-convert", "-b", "white", "-w", "1600", str(out_svg), "-o", str(out_png)],
+                                   check=True, capture_output=True)
+                    result["png"] = str(out_png)
+                else:
+                    result["png_warn"] = "rsvg-convert 未装，跳过 PNG（apt install librsvg2-bin）"
+            return result
+        finally:
+            browser.close()