@harmonyos-arkts/d2h 0.1.11 → 0.1.12

package/skills/d2h-utg-ai-generate/scripts/build_page_json.py

@@ -1,314 +1,314 @@
-#!/usr/bin/env python3
-"""Build and validate a deterministic runtime capture plan from a UTG pair.
-
-`page.json` is deliberately produced before any device work.  It is the bridge
-between source-derived reachability (`utg.json` + `click_paths.json`) and the
-standalone ADB replay script that captures screenshots and UIAutomator trees.
-"""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import re
-import sys
-from pathlib import Path
-from typing import Any
-
-from utg_common import UtgError, atomic_write_json, load_json, validate_pair, replay_action_reason
-
-
-SCHEMA_VERSION = "d2h-page-plan/v1"
-NON_CAPTURE_KINDS = {"nav-graph", "sentinel", "host-activity"}
-CONTAINMENT_MECHANISMS = {
-    "navhost-start",
-    "nav-graph-start",
-    "nav-component-start",
-    "fragment-embed",
-}
-ARRIVAL_RULES = {
-    "text_any",
-    "text_all",
-    "content_desc_any",
-    "resource_id_any",
-    "activity_any",
-}
-
-
-def _slug(node_id: str) -> str:
-    readable = re.sub(r"[^A-Za-z0-9._-]+", "_", node_id).strip("._-") or "page"
-    digest = hashlib.sha256(node_id.encode("utf-8")).hexdigest()[:8]
-    return f"{readable[:72]}-{digest}"
-
-
-def _non_capture_reason(node: dict[str, Any], utg: dict[str, Any]) -> str | None:
-    kind = node["kind"]
-    if kind in NON_CAPTURE_KINDS:
-        return f"non-capture-kind:{kind}"
-    # A single-Activity app often models both the launcher host and the real
-    # start route. They render the same screen. Capturing both either duplicates
-    # the snapshot or triggers the crawler's duplicate-signature rejection.
-    if kind == "activity" and any(
-        edge["source"] == node["id"] and edge["mechanism"] in CONTAINMENT_MECHANISMS
-        for edge in utg["links"]
-    ):
-        return "container-node:activity"
-    return None
-
-
-def _capture_reason(node, utg, path):
-    reason = _non_capture_reason(node, utg)
-    if reason or (node.get('extra') or {}).get('capture_policy') != 'strict':
-        return reason
-    if not any(isinstance(node.get('expected', {}).get(rule), list)
-               and node['expected'][rule] for rule in ARRIVAL_RULES):
-        return 'missing-arrival-rules'
-    for step in (path or {}).get('steps', []):
-        action_reason = replay_action_reason(step)
-        if action_reason:
-            return action_reason
-    return None
-
-
-def build_page_plan(
-    utg: dict[str, Any],
-    click_paths: dict[str, Any],
-    *,
-    utg_path: str,
-    click_paths_path: str,
-) -> dict[str, Any]:
-    """Return a page plan whose order is stable for the exact UTG pair."""
-    nodes = utg["nodes"]
-    paths = click_paths["paths"]
-    unreachable = set(click_paths["unreachable"])
-    source_order = {node["id"]: index for index, node in enumerate(nodes)}
-
-    ordered = sorted(
-        nodes,
-        key=lambda node: (
-            1 if node["id"] in unreachable else 0,
-            paths.get(node["id"], {}).get("depth", 1 << 30),
-            source_order[node["id"]],
-        ),
-    )
-
-    pages: list[dict[str, Any]] = []
-    capture_index = 0
-    excluded_by_kind: dict[str, int] = {}
-    for node in ordered:
-        node_id = node["id"]
-        kind = node["kind"]
-        reachable = node_id in paths
-        non_capture_reason = _capture_reason(node, utg, paths.get(node_id))
-        capture = reachable and non_capture_reason is None
-        if non_capture_reason is not None:
-            excluded_key = f"{kind}(container)" if non_capture_reason.startswith("container-node") else kind
-            excluded_by_kind[excluded_key] = excluded_by_kind.get(excluded_key, 0) + 1
-        if capture:
-            capture_index += 1
-        path = paths.get(node_id)
-        labels = path.get("labels", []) if path else []
-        pages.append(
-            {
-                "node_id": node_id,
-                "kind": kind,
-                "label": node["label"],
-                "declared_at": node["declared_at"],
-                "required_state": node.get("required_state", []),
-                "expected": node.get("expected", {}),
-                "reachable": reachable,
-                "capture": capture,
-                "capture_key": (
-                    f"page_{capture_index:04d}_{_slug(node_id)}" if capture else None
-                ),
-                "depth": path.get("depth") if path else None,
-                "ui_sequence": " → ".join(labels) if labels else node["label"],
-                "path_text": path.get("path_text") if path else None,
-                "steps": path.get("steps", []) if path else [],
-                "skip_reason": (
-                    None
-                    if capture
-                    else "unreachable-from-root"
-                    if not reachable
-                    else non_capture_reason
-                ),
-            }
-        )
-
-    return {
-        "schema_version": SCHEMA_VERSION,
-        "source": {
-            "utg": utg_path,
-            "click_paths": click_paths_path,
-            "root": click_paths["root"],
-            "app": utg["graph"]["app"],
-            "package": utg["graph"].get("package", ""),
-            "architecture": utg["graph"]["architecture"],
-            "version_name": utg["graph"].get("version_name", ""),
-            "build_variant": utg["graph"].get("build_variant", ""),
-        },
-        "summary": {
-            "nodes": len(nodes),
-            "capture_planned": capture_index,
-            "unreachable": len(unreachable),
-            "excluded_by_kind": dict(sorted(excluded_by_kind.items())),
-        },
-        "pages": pages,
-    }
-
-
-def validate_page_plan(
-    plan: dict[str, Any],
-    utg: dict[str, Any],
-    click_paths: dict[str, Any],
-    *,
-    utg_path: str | None = None,
-    click_paths_path: str | None = None,
-) -> list[str]:
-    errors: list[str] = []
-    if plan.get("schema_version") != SCHEMA_VERSION:
-        errors.append(f"page.schema_version must be {SCHEMA_VERSION!r}")
-    source = plan.get("source")
-    pages = plan.get("pages")
-    if not isinstance(source, dict):
-        return errors + ["page.source must be an object"]
-    if utg_path is not None and source.get("utg") != utg_path:
-        errors.append("page.source.utg does not match the validated utg.json")
-    if click_paths_path is not None and source.get("click_paths") != click_paths_path:
-        errors.append("page.source.click_paths does not match the validated click_paths.json")
-    if source.get("root") != click_paths.get("root"):
-        errors.append("page.source.root must equal click_paths.root")
-    if not isinstance(pages, list):
-        return errors + ["page.pages must be an array"]
-
-    nodes = {node["id"]: node for node in utg["nodes"]}
-    ids: set[str] = set()
-    capture_keys: set[str] = set()
-    last_order: tuple[int, int] = (-1, -1)
-    source_order = {node["id"]: index for index, node in enumerate(utg["nodes"])}
-    for index, page in enumerate(pages):
-        where = f"page.pages[{index}]"
-        if not isinstance(page, dict):
-            errors.append(f"{where} must be an object")
-            continue
-        node_id = page.get("node_id")
-        if not isinstance(node_id, str) or node_id not in nodes:
-            errors.append(f"{where}.node_id references a missing UTG node: {node_id!r}")
-            continue
-        if node_id in ids:
-            errors.append(f"duplicate page node_id: {node_id}")
-        ids.add(node_id)
-        path = click_paths["paths"].get(node_id)
-        reachable = path is not None
-        expected_capture = reachable and _capture_reason(nodes[node_id], utg, path) is None
-        if page.get("reachable") is not reachable:
-            errors.append(f"{where}.reachable does not match click_paths")
-        if page.get("capture") is not expected_capture:
-            errors.append(f"{where}.capture does not match reachability/kind")
-        if page.get("steps") != (path.get("steps", []) if path else []):
-            errors.append(f"{where}.steps are not copied from click_paths")
-        if page.get("expected") != nodes[node_id].get("expected", {}):
-            errors.append(f"{where}.expected is not copied from the UTG node")
-        if expected_capture:
-            expected = page.get("expected")
-            has_arrival_rule = isinstance(expected, dict) and any(
-                isinstance(expected.get(rule), list)
-                and bool(expected[rule])
-                and all(isinstance(value, str) and value for value in expected[rule])
-                for rule in ARRIVAL_RULES
-            )
-            if not has_arrival_rule:
-                errors.append(
-                    f"{where}.expected must contain a supported non-empty arrival rule "
-                    "for runtime capture"
-                )
-        capture_key = page.get("capture_key")
-        if expected_capture:
-            if not isinstance(capture_key, str) or not capture_key:
-                errors.append(f"{where}.capture_key must be non-empty for capture pages")
-            elif capture_key in capture_keys:
-                errors.append(f"duplicate capture_key: {capture_key}")
-            else:
-                capture_keys.add(capture_key)
-        elif capture_key is not None:
-            errors.append(f"{where}.capture_key must be null when capture=false")
-        order = (
-            1 if not reachable else 0,
-            path.get("depth", 1 << 30) if path else 1 << 30,
-            source_order[node_id],
-        )
-        comparable = (order[0], order[1])
-        if comparable < last_order:
-            errors.append("page.pages must be ordered by reachable/depth")
-        last_order = comparable
-
-    if ids != set(nodes):
-        errors.append(
-            "page.pages must cover every UTG node; "
-            f"missing={sorted(set(nodes) - ids)}, extra={sorted(ids - set(nodes))}"
-        )
-    # The plan is entirely derived. Catch mutations to labels, summaries,
-    # directory numbering, copied path fields, or skip reasons by rebuilding
-    # the expected value from the validated pair.
-    expected = build_page_plan(
-        utg,
-        click_paths,
-        utg_path=utg_path or str(source.get("utg", "")),
-        click_paths_path=click_paths_path or str(source.get("click_paths", "")),
-    )
-    if plan != expected:
-        errors.append("page.json is not the deterministic plan for this UTG pair")
-    return errors
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description="Build page.json from a validated utg.json/click_paths.json pair."
-    )
-    parser.add_argument("--utg", required=True, type=Path)
-    parser.add_argument("--click-paths", required=True, type=Path)
-    parser.add_argument("--output", required=True, type=Path)
-    parser.add_argument("--project-root", type=Path)
-    return parser.parse_args()
-
-
-def main() -> int:
-    args = parse_args()
-    try:
-        utg_path = args.utg.resolve()
-        click_paths_path = args.click_paths.resolve()
-        utg = load_json(utg_path)
-        click_paths = load_json(click_paths_path)
-        project_root = args.project_root.resolve() if args.project_root else None
-        pair_errors = validate_pair(utg, click_paths, project_root)
-        if pair_errors:
-            raise UtgError("UTG pair is invalid:\n- " + "\n- ".join(pair_errors))
-        plan = build_page_plan(
-            utg,
-            click_paths,
-            utg_path=str(utg_path),
-            click_paths_path=str(click_paths_path),
-        )
-        errors = validate_page_plan(
-            plan,
-            utg,
-            click_paths,
-            utg_path=str(utg_path),
-            click_paths_path=str(click_paths_path),
-        )
-        if errors:
-            raise UtgError("page plan is invalid:\n- " + "\n- ".join(errors))
-        atomic_write_json(args.output.resolve(), plan)
-    except UtgError as exc:
-        print(f"ERROR: {exc}", file=sys.stderr)
-        return 2
-    print(
-        f"valid page plan: capture={plan['summary']['capture_planned']} "
-        f"unreachable={plan['summary']['unreachable']}"
-    )
-    print(args.output.resolve())
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+#!/usr/bin/env python3
+"""Build and validate a deterministic runtime capture plan from a UTG pair.
+
+`page.json` is deliberately produced before any device work.  It is the bridge
+between source-derived reachability (`utg.json` + `click_paths.json`) and the
+standalone ADB replay script that captures screenshots and UIAutomator trees.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+from utg_common import UtgError, atomic_write_json, load_json, validate_pair, replay_action_reason
+
+
+SCHEMA_VERSION = "d2h-page-plan/v1"
+NON_CAPTURE_KINDS = {"nav-graph", "sentinel", "host-activity"}
+CONTAINMENT_MECHANISMS = {
+    "navhost-start",
+    "nav-graph-start",
+    "nav-component-start",
+    "fragment-embed",
+}
+ARRIVAL_RULES = {
+    "text_any",
+    "text_all",
+    "content_desc_any",
+    "resource_id_any",
+    "activity_any",
+}
+
+
+def _slug(node_id: str) -> str:
+    readable = re.sub(r"[^A-Za-z0-9._-]+", "_", node_id).strip("._-") or "page"
+    digest = hashlib.sha256(node_id.encode("utf-8")).hexdigest()[:8]
+    return f"{readable[:72]}-{digest}"
+
+
+def _non_capture_reason(node: dict[str, Any], utg: dict[str, Any]) -> str | None:
+    kind = node["kind"]
+    if kind in NON_CAPTURE_KINDS:
+        return f"non-capture-kind:{kind}"
+    # A single-Activity app often models both the launcher host and the real
+    # start route. They render the same screen. Capturing both either duplicates
+    # the snapshot or triggers the crawler's duplicate-signature rejection.
+    if kind == "activity" and any(
+        edge["source"] == node["id"] and edge["mechanism"] in CONTAINMENT_MECHANISMS
+        for edge in utg["links"]
+    ):
+        return "container-node:activity"
+    return None
+
+
+def _capture_reason(node, utg, path):
+    reason = _non_capture_reason(node, utg)
+    if reason or (node.get('extra') or {}).get('capture_policy') != 'strict':
+        return reason
+    if not any(isinstance(node.get('expected', {}).get(rule), list)
+               and node['expected'][rule] for rule in ARRIVAL_RULES):
+        return 'missing-arrival-rules'
+    for step in (path or {}).get('steps', []):
+        action_reason = replay_action_reason(step)
+        if action_reason:
+            return action_reason
+    return None
+
+
+def build_page_plan(
+    utg: dict[str, Any],
+    click_paths: dict[str, Any],
+    *,
+    utg_path: str,
+    click_paths_path: str,
+) -> dict[str, Any]:
+    """Return a page plan whose order is stable for the exact UTG pair."""
+    nodes = utg["nodes"]
+    paths = click_paths["paths"]
+    unreachable = set(click_paths["unreachable"])
+    source_order = {node["id"]: index for index, node in enumerate(nodes)}
+
+    ordered = sorted(
+        nodes,
+        key=lambda node: (
+            1 if node["id"] in unreachable else 0,
+            paths.get(node["id"], {}).get("depth", 1 << 30),
+            source_order[node["id"]],
+        ),
+    )
+
+    pages: list[dict[str, Any]] = []
+    capture_index = 0
+    excluded_by_kind: dict[str, int] = {}
+    for node in ordered:
+        node_id = node["id"]
+        kind = node["kind"]
+        reachable = node_id in paths
+        non_capture_reason = _capture_reason(node, utg, paths.get(node_id))
+        capture = reachable and non_capture_reason is None
+        if non_capture_reason is not None:
+            excluded_key = f"{kind}(container)" if non_capture_reason.startswith("container-node") else kind
+            excluded_by_kind[excluded_key] = excluded_by_kind.get(excluded_key, 0) + 1
+        if capture:
+            capture_index += 1
+        path = paths.get(node_id)
+        labels = path.get("labels", []) if path else []
+        pages.append(
+            {
+                "node_id": node_id,
+                "kind": kind,
+                "label": node["label"],
+                "declared_at": node["declared_at"],
+                "required_state": node.get("required_state", []),
+                "expected": node.get("expected", {}),
+                "reachable": reachable,
+                "capture": capture,
+                "capture_key": (
+                    f"page_{capture_index:04d}_{_slug(node_id)}" if capture else None
+                ),
+                "depth": path.get("depth") if path else None,
+                "ui_sequence": " → ".join(labels) if labels else node["label"],
+                "path_text": path.get("path_text") if path else None,
+                "steps": path.get("steps", []) if path else [],
+                "skip_reason": (
+                    None
+                    if capture
+                    else "unreachable-from-root"
+                    if not reachable
+                    else non_capture_reason
+                ),
+            }
+        )
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "source": {
+            "utg": utg_path,
+            "click_paths": click_paths_path,
+            "root": click_paths["root"],
+            "app": utg["graph"]["app"],
+            "package": utg["graph"].get("package", ""),
+            "architecture": utg["graph"]["architecture"],
+            "version_name": utg["graph"].get("version_name", ""),
+            "build_variant": utg["graph"].get("build_variant", ""),
+        },
+        "summary": {
+            "nodes": len(nodes),
+            "capture_planned": capture_index,
+            "unreachable": len(unreachable),
+            "excluded_by_kind": dict(sorted(excluded_by_kind.items())),
+        },
+        "pages": pages,
+    }
+
+
+def validate_page_plan(
+    plan: dict[str, Any],
+    utg: dict[str, Any],
+    click_paths: dict[str, Any],
+    *,
+    utg_path: str | None = None,
+    click_paths_path: str | None = None,
+) -> list[str]:
+    errors: list[str] = []
+    if plan.get("schema_version") != SCHEMA_VERSION:
+        errors.append(f"page.schema_version must be {SCHEMA_VERSION!r}")
+    source = plan.get("source")
+    pages = plan.get("pages")
+    if not isinstance(source, dict):
+        return errors + ["page.source must be an object"]
+    if utg_path is not None and source.get("utg") != utg_path:
+        errors.append("page.source.utg does not match the validated utg.json")
+    if click_paths_path is not None and source.get("click_paths") != click_paths_path:
+        errors.append("page.source.click_paths does not match the validated click_paths.json")
+    if source.get("root") != click_paths.get("root"):
+        errors.append("page.source.root must equal click_paths.root")
+    if not isinstance(pages, list):
+        return errors + ["page.pages must be an array"]
+
+    nodes = {node["id"]: node for node in utg["nodes"]}
+    ids: set[str] = set()
+    capture_keys: set[str] = set()
+    last_order: tuple[int, int] = (-1, -1)
+    source_order = {node["id"]: index for index, node in enumerate(utg["nodes"])}
+    for index, page in enumerate(pages):
+        where = f"page.pages[{index}]"
+        if not isinstance(page, dict):
+            errors.append(f"{where} must be an object")
+            continue
+        node_id = page.get("node_id")
+        if not isinstance(node_id, str) or node_id not in nodes:
+            errors.append(f"{where}.node_id references a missing UTG node: {node_id!r}")
+            continue
+        if node_id in ids:
+            errors.append(f"duplicate page node_id: {node_id}")
+        ids.add(node_id)
+        path = click_paths["paths"].get(node_id)
+        reachable = path is not None
+        expected_capture = reachable and _capture_reason(nodes[node_id], utg, path) is None
+        if page.get("reachable") is not reachable:
+            errors.append(f"{where}.reachable does not match click_paths")
+        if page.get("capture") is not expected_capture:
+            errors.append(f"{where}.capture does not match reachability/kind")
+        if page.get("steps") != (path.get("steps", []) if path else []):
+            errors.append(f"{where}.steps are not copied from click_paths")
+        if page.get("expected") != nodes[node_id].get("expected", {}):
+            errors.append(f"{where}.expected is not copied from the UTG node")
+        if expected_capture:
+            expected = page.get("expected")
+            has_arrival_rule = isinstance(expected, dict) and any(
+                isinstance(expected.get(rule), list)
+                and bool(expected[rule])
+                and all(isinstance(value, str) and value for value in expected[rule])
+                for rule in ARRIVAL_RULES
+            )
+            if not has_arrival_rule:
+                errors.append(
+                    f"{where}.expected must contain a supported non-empty arrival rule "
+                    "for runtime capture"
+                )
+        capture_key = page.get("capture_key")
+        if expected_capture:
+            if not isinstance(capture_key, str) or not capture_key:
+                errors.append(f"{where}.capture_key must be non-empty for capture pages")
+            elif capture_key in capture_keys:
+                errors.append(f"duplicate capture_key: {capture_key}")
+            else:
+                capture_keys.add(capture_key)
+        elif capture_key is not None:
+            errors.append(f"{where}.capture_key must be null when capture=false")
+        order = (
+            1 if not reachable else 0,
+            path.get("depth", 1 << 30) if path else 1 << 30,
+            source_order[node_id],
+        )
+        comparable = (order[0], order[1])
+        if comparable < last_order:
+            errors.append("page.pages must be ordered by reachable/depth")
+        last_order = comparable
+
+    if ids != set(nodes):
+        errors.append(
+            "page.pages must cover every UTG node; "
+            f"missing={sorted(set(nodes) - ids)}, extra={sorted(ids - set(nodes))}"
+        )
+    # The plan is entirely derived. Catch mutations to labels, summaries,
+    # directory numbering, copied path fields, or skip reasons by rebuilding
+    # the expected value from the validated pair.
+    expected = build_page_plan(
+        utg,
+        click_paths,
+        utg_path=utg_path or str(source.get("utg", "")),
+        click_paths_path=click_paths_path or str(source.get("click_paths", "")),
+    )
+    if plan != expected:
+        errors.append("page.json is not the deterministic plan for this UTG pair")
+    return errors
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build page.json from a validated utg.json/click_paths.json pair."
+    )
+    parser.add_argument("--utg", required=True, type=Path)
+    parser.add_argument("--click-paths", required=True, type=Path)
+    parser.add_argument("--output", required=True, type=Path)
+    parser.add_argument("--project-root", type=Path)
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        utg_path = args.utg.resolve()
+        click_paths_path = args.click_paths.resolve()
+        utg = load_json(utg_path)
+        click_paths = load_json(click_paths_path)
+        project_root = args.project_root.resolve() if args.project_root else None
+        pair_errors = validate_pair(utg, click_paths, project_root)
+        if pair_errors:
+            raise UtgError("UTG pair is invalid:\n- " + "\n- ".join(pair_errors))
+        plan = build_page_plan(
+            utg,
+            click_paths,
+            utg_path=str(utg_path),
+            click_paths_path=str(click_paths_path),
+        )
+        errors = validate_page_plan(
+            plan,
+            utg,
+            click_paths,
+            utg_path=str(utg_path),
+            click_paths_path=str(click_paths_path),
+        )
+        if errors:
+            raise UtgError("page plan is invalid:\n- " + "\n- ".join(errors))
+        atomic_write_json(args.output.resolve(), plan)
+    except UtgError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    print(
+        f"valid page plan: capture={plan['summary']['capture_planned']} "
+        f"unreachable={plan['summary']['unreachable']}"
+    )
+    print(args.output.resolve())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())