modao-prd-cli 0.1.0__py3-none-any.whl

modao_prd_cli/modao_prd/explorer.py

@@ -0,0 +1,300 @@
+"""Bounded, conservative exploration of public prototype states."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import time
+from typing import Any
+
+
+HIGH_RISK_RE = re.compile(
+    r"抽奖|支付|购买|充值|领取|赠送|提交|确认|保存|发布|删除|兑换|消耗|下单|立即|开始|发起|登录|注册|下载|上传|授权|同意|拒绝",
+    re.I,
+)
+SAFE_HINT_RE = re.compile(
+    r"详情|规则|说明|帮助|更多|展开|收起|关闭|信息|问号|tooltip|info|tab",
+    re.I,
+)
+
+
+def explore_safe(
+    page: Any,
+    context: Any,
+    *,
+    requested_url: str,
+    timeout_ms: int,
+    max_states: int,
+    max_depth: int,
+    max_actions: int,
+    max_duration_seconds: int,
+    evidence_mode: str,
+    evidence_writer: Any,
+    max_item: int,
+    max_total: int,
+    raw: dict[str, Any],
+) -> None:
+    """Explore only low-risk disclosure controls, reloading each branch."""
+
+    started = time.monotonic()
+    actions = 0
+    skipped: list[dict[str, str]] = []
+    transitions: list[dict[str, Any]] = []
+    queue: list[tuple[str, int, list[dict[str, Any]], list[dict[str, Any]]]] = [("state-001", 0, _candidates(page), [])]
+    seen = {_fingerprint(page)}
+
+    while queue and len(raw.get("states", [])) < max_states and actions < max_actions:
+        if time.monotonic() - started >= max_duration_seconds:
+            raw.setdefault("warnings", []).append("安全探索达到整体时长上限，未继续访问剩余状态。")
+            raw.setdefault("coverage", {})["partial_reason"] = "max_duration"
+            break
+        source_state, depth, candidates, path = queue.pop(0)
+        if depth >= max_depth:
+            continue
+        for candidate in candidates:
+            if actions >= max_actions or len(raw.get("states", [])) >= max_states:
+                break
+            if time.monotonic() - started >= max_duration_seconds:
+                raw.setdefault("warnings", []).append("安全探索达到整体时长上限，未继续访问剩余状态。")
+                raw.setdefault("coverage", {})["partial_reason"] = "max_duration"
+                break
+            decision = _risk_decision(candidate)
+            if decision != "allow":
+                skipped.append({"label": candidate.get("label", ""), "reason": decision})
+                continue
+
+            actions += 1
+            try:
+                page.goto(requested_url, wait_until="domcontentloaded", timeout=timeout_ms)
+                page.wait_for_timeout(min(400, timeout_ms))
+                navigation_guard = _install_navigation_guard(context, requested_url)
+                try:
+                    for replay in path:
+                        _scroll_page(page)
+                        locator = _locator_for_candidate(page, replay)
+                        locator.scroll_into_view_if_needed(timeout=timeout_ms)
+                        locator.click(timeout=timeout_ms)
+                        page.wait_for_timeout(min(250, timeout_ms))
+                    _scroll_page(page)
+                    locator = _locator_for_candidate(page, candidate)
+                    locator.scroll_into_view_if_needed(timeout=timeout_ms)
+                    before = _fingerprint(page)
+                    locator.click(timeout=timeout_ms)
+                finally:
+                    _remove_navigation_guard(context, navigation_guard)
+                page.wait_for_timeout(min(450, timeout_ms))
+                _scroll_page(page)
+                after = _fingerprint(page)
+                if not _is_supported_share_url(page.url, requested_url):
+                    skipped.append({"label": candidate.get("label", ""), "reason": "navigation_blocked"})
+                    continue
+                if after == before:
+                    continue
+                state_id = f"state-{len(raw.get('states', [])) + 1:03d}"
+                state = {
+                    "id": state_id,
+                    "url": page.url,
+                    "depth": depth + 1,
+                    "action_count": actions,
+                    "trigger": candidate.get("label", ""),
+                    "action": "安全探索控件点击",
+                    "evidence_ids": [],
+                }
+                raw.setdefault("states", []).append(state)
+                transitions.append(
+                    {
+                        "id": f"transition-{len(transitions) + 1:03d}",
+                        "source_state_id": source_state,
+                        "target_state_id": state_id,
+                        "trigger": candidate.get("label", ""),
+                        "action": "click",
+                        "result": "state_changed",
+                    }
+                )
+                fingerprint = after
+                if fingerprint in seen:
+                    continue
+                seen.add(fingerprint)
+                # State artifacts are captured by the browser callback attached
+                # in browser.py through this small local callback.
+                _capture_explored_state(
+                    page,
+                    context,
+                    raw=raw,
+                    state_id=state_id,
+                    requested_url=requested_url,
+                    evidence_mode=evidence_mode,
+                    evidence_writer=evidence_writer,
+                    max_item=max_item,
+                    max_total=max_total,
+                )
+                state["evidence_ids"] = list(raw.get("states", [])[-1].get("evidence_ids", []))
+                if depth + 1 < max_depth:
+                    queue.append((state_id, depth + 1, _candidates(page), path + [candidate]))
+            except Exception as exc:
+                raw.setdefault("warnings", []).append(
+                    f"安全探索跳过“{candidate.get('label', '')}”：{_short_error(exc)}"
+                )
+
+    raw.setdefault("coverage", {})["actions_attempted"] = actions
+    raw["coverage"]["transitions"] = transitions
+    raw["coverage"]["skipped_actions"] = skipped
+    if actions >= max_actions:
+        raw["coverage"]["partial_reason"] = "max_actions"
+    elif len(raw.get("states", [])) >= max_states:
+        raw["coverage"]["partial_reason"] = "max_states"
+
+
+def _capture_explored_state(
+    page: Any,
+    context: Any,
+    *,
+    raw: dict[str, Any],
+    state_id: str,
+    requested_url: str,
+    evidence_mode: str,
+    evidence_writer: Any,
+    max_item: int,
+    max_total: int,
+) -> None:
+    from .capture_evidence import capture_state_evidence
+
+    warnings = raw.setdefault("warnings", [])
+    network: list[dict[str, Any]] = []
+    evidence, dom, stats = capture_state_evidence(
+        page,
+        context,
+        writer=evidence_writer if evidence_mode != "none" else None,
+        state_id=state_id,
+        requested_url=requested_url,
+        evidence_mode=evidence_mode,
+        max_item=max_item,
+        max_total=max_total,
+        warnings=warnings,
+        network_records=network,
+        evidence_id_offset=len(raw.get("evidence", [])),
+    )
+    from .capture_evidence import merge_evidence
+
+    merge_evidence(raw.setdefault("evidence", []), evidence)
+    raw.setdefault("network", []).extend(network)
+    state_evidence_ids = [
+        item["id"]
+        for item in raw["evidence"]
+        if item.get("state_id") == state_id
+    ]
+    raw["states"][-1].update({"dom": dom, "evidence_stats": stats, "evidence_ids": state_evidence_ids})
+    try:
+        from .browser import _DOM_EXTRACTION_SCRIPT
+
+        extracted = page.evaluate(_DOM_EXTRACTION_SCRIPT)
+        records = raw.setdefault("records", [])
+        start_order = max((int(item.get("dom_order", -1)) for item in records), default=-1) + 1
+        for index, record in enumerate(extracted.get("records", [])):
+            records.append({**record, "state_id": state_id, "dom_order": start_order + index})
+    except Exception as exc:
+        warnings.append(f"状态 {state_id} 的结构化内容未提取：{_short_error(exc)}")
+    raw.setdefault("coverage", {})["state_count"] = len(raw["states"])
+
+
+def _candidates(page: Any) -> list[dict[str, Any]]:
+    try:
+        return page.evaluate(
+            """() => Array.from(document.querySelectorAll('button,[role=button],[role=tab],summary,[aria-expanded],a'))
+              .map((element, index) => {
+                const style = getComputedStyle(element);
+                const rect = element.getBoundingClientRect();
+                const label = (element.innerText || element.getAttribute('aria-label') || element.getAttribute('title') || '').trim();
+                return {index, tag: element.tagName.toLowerCase(), role: element.getAttribute('role') || '',
+                  label, expanded: element.getAttribute('aria-expanded'), visible: style.display !== 'none' &&
+                  style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0};
+              }).filter(item => item.visible)"""
+        )
+    except Exception:
+        return []
+
+
+def _risk_decision(candidate: dict[str, Any]) -> str:
+    label = str(candidate.get("label") or "").strip()
+    role = str(candidate.get("role") or "")
+    tag = str(candidate.get("tag") or "")
+    if not label and role not in {"tab"} and candidate.get("expanded") is None:
+        return "ambiguous_control"
+    if HIGH_RISK_RE.search(label):
+        return "high_risk_semantics"
+    if tag in {"input", "select", "textarea"}:
+        return "form_control"
+    if tag == "a":
+        return "navigation_skipped"
+    if role == "tab" or candidate.get("expanded") is not None or (tag == "summary" and SAFE_HINT_RE.search(label)):
+        return "allow"
+    if tag == "button" and SAFE_HINT_RE.search(label):
+        return "allow"
+    return "ambiguous_control"
+
+
+def _locator_for_candidate(page: Any, candidate: dict[str, Any]) -> Any:
+    # The index belongs to the exact selector list used in _candidates, so it
+    # remains deterministic after reloading the branch from the entry URL.
+    return page.locator("button,[role=button],[role=tab],summary,[aria-expanded],a").nth(int(candidate.get("index", 0)))
+
+
+def _fingerprint(page: Any) -> str:
+    try:
+        value = page.evaluate(
+            """() => ({url: location.href, text: (document.body?.innerText || '').slice(0, 20000),
+              visible: Array.from(document.querySelectorAll('[aria-selected],[aria-expanded],.mb-screen')).map(x =>
+                [x.tagName, x.getAttribute('aria-selected'), x.getAttribute('aria-expanded'), x.className]).join('|')})"""
+        )
+        return hashlib.sha256(repr(value).encode("utf-8", "replace")).hexdigest()
+    except Exception:
+        return str(time.monotonic_ns())
+
+
+def _scroll_page(page: Any) -> None:
+    try:
+        page.evaluate(
+            """() => {
+              const nodes = [document.scrollingElement, ...document.querySelectorAll('*')]
+                .filter(x => x && x.scrollHeight > x.clientHeight + 8 &&
+                  ['auto', 'scroll'].includes(getComputedStyle(x).overflowY));
+              for (const node of nodes.slice(0, 80)) node.scrollTop = node.scrollHeight;
+              window.scrollTo(0, 0);
+            }"""
+        )
+        page.wait_for_timeout(180)
+    except Exception:
+        pass
+
+
+def _short_error(exc: Exception, limit: int = 220) -> str:
+    text = " ".join(str(exc).split())
+    return text[:limit] + ("…" if len(text) > limit else "")
+
+
+def _is_supported_share_url(url: str, requested_url: str) -> bool:
+    from .browser import validate_share_url
+
+    try:
+        requested = validate_share_url(requested_url)
+        actual = validate_share_url(url)
+        return requested.project_id == actual.project_id
+    except Exception:
+        return False
+
+
+def _install_navigation_guard(context: Any, requested_url: str) -> Any:
+    from .capture_evidence import same_origin
+
+    def guard(route: Any) -> None:
+        if same_origin(route.request.url, requested_url):
+            route.continue_()
+        else:
+            route.abort()
+
+    context.route("**/*", guard)
+    return guard
+
+
+def _remove_navigation_guard(context: Any, guard: Any) -> None:
+    context.unroute("**/*", guard)