@harmonyos-arkts/d2h 0.1.3 → 0.1.5

package/skills/d2h-utg-ai-generate/references/facts-contract.md

@@ -0,0 +1,96 @@
+# `utg-facts.json` contract
+
+The facts file is the only AI-authored data input. It describes source evidence; it is not the final UTG format.
+
+```json
+{
+  "schema_version": "d2h-utg-facts/v1",
+  "graph": {
+    "app": "Example",
+    "package": "com.example.app",
+    "architecture": "jetpack-compose/navigation-compose",
+    "root": "MainActivity",
+    "start_destination": "home",
+    "version_name": "1.4.2",
+    "build_variant": "debug"
+  },
+  "nodes": [
+    {
+      "id": "MainActivity",
+      "kind": "activity",
+      "label": "MainActivity (launcher)",
+      "declared_at": "app/src/main/java/com/example/MainActivity.kt:20",
+      "widgets": [],
+      "expected": {"activity_any": ["com.example.app/.MainActivity"]},
+      "required_state": [],
+      "extra": {"launcher": true},
+      "confidence": 1.0
+    }
+  ],
+  "edges": [
+    {
+      "source": "MainActivity",
+      "target": "home",
+      "mechanism": "navhost-start",
+      "trigger": "app/src/main/java/com/example/MainActivity.kt:45",
+      "guard": null,
+      "args": {
+        "action": "default",
+        "label": "Example",
+        "label_source": "string"
+      },
+      "confidence": 0.98
+    }
+  ],
+  "unresolved": [
+    {
+      "subject": "dynamic route from server config",
+      "reason": "target value is not present in source",
+      "evidence": "app/src/main/java/com/example/Router.kt:81"
+    }
+  ]
+}
+```
+
+## Graph
+
+Required fields are `app`, `architecture`, and `root`. `package` and `start_destination` may be empty only when the source ecosystem genuinely has no equivalent. Record `version_name` and `build_variant` when they are determinable from the analyzed source/build configuration; runtime replay refuses a non-empty version that differs from the installed package. Additional graph metadata is preserved.
+
+## Nodes
+
+Required:
+
+- `id`: stable, unique code identity. Do not use display text as identity.
+- `kind`: framework-independent semantic kind such as `activity`, `fragment`, `compose-route`, `voyager-screen`, `dialog`, `sheet`, `menu`, `mode`, `nav-graph`, `hybrid`, or `hybrid-page`.
+- `label`: human-readable description.
+- `declared_at`: project-relative `file:line` that declares or hosts the UI.
+
+Optional fields default to `status="static-only"`, `provenance="ai-source-analysis"`, empty `widgets`, empty `expected`, empty `required_state`, and `extra=null`. Use an object for `extra` only when the node has extension metadata. A node intended for runtime capture must not leave `expected` empty. Supported arrival rules are string arrays: `text_any`, `text_all`, `content_desc_any`, `resource_id_any`, and `activity_any`. Derive them from source literals/resources or stable component identities, not guesses.
+
+Use `required_state` only for a node-level state axis, such as `content`, `login`, `permission`, or `network`. Put edge-specific conditions on the edge guard.
+
+## Edges
+
+Required:
+
+- `source`, `target`: existing node IDs.
+- `mechanism`: navigation mechanism, not a prose summary.
+- `trigger`: project-relative navigation call-site `file:line`.
+- `confidence`: numeric `[0, 1]`.
+
+`guard` is either `null` or an object containing non-empty `kind` and `text`. `args` may contain:
+
+- `action`: `tap`, `back`, `default`, `launch`, `home`, `swipe`, or another concrete driver action.
+- `label`: visible text or URI. It is a compatibility selector only when `selector` is absent.
+- `label_source`: normally `string`, `content-description`, `system`, `code-name`, or `nl_hint`.
+- `label_ambiguous`: boolean.
+- `nl_hint`: source-grounded instruction for human interpretation. It is not executable.
+- `selector`: deterministic ADB selector. It may contain `text`, `text_any`, `content_desc`, `content_desc_any`, `resource_id`, or `resource_id_any`. `normalized_point: [x, y]` uses 0–1 screen fractions and is an explicitly enabled last resort, never an inferred default.
+- `direction`, `distance`, `duration_ms`, and `max_scrolls`: optional deterministic parameters for swipe/search behavior.
+- route arguments or other mechanism-specific metadata.
+
+The generator assigns parallel-edge `key` values. Do not supply them.
+
+## Unresolved findings
+
+Use `unresolved` when the source proves a boundary but not a safe graph fact: runtime/server routes, reflection, computed destinations, missing bundles, build-flavor-only pages, or ambiguous callback ownership. These entries remain in `generation-report.json` and never enter the graph silently.

package/skills/d2h-utg-ai-generate/references/page-schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hometrans.local/schemas/page-plan-v1.json",
+  "title": "HomeTrans UTG-directed runtime capture plan",
+  "type": "object",
+  "required": ["schema_version", "source", "summary", "pages"],
+  "properties": {
+    "schema_version": {"const": "d2h-page-plan/v1"},
+    "source": {
+      "type": "object",
+      "required": ["utg", "click_paths", "root", "app", "package", "architecture", "version_name", "build_variant"],
+      "properties": {
+        "utg": {"type": "string", "minLength": 1},
+        "click_paths": {"type": "string", "minLength": 1},
+        "root": {"type": "string", "minLength": 1},
+        "app": {"type": "string", "minLength": 1},
+        "package": {"type": "string"},
+        "architecture": {"type": "string", "minLength": 1},
+        "version_name": {"type": "string"},
+        "build_variant": {"type": "string"}
+      },
+      "additionalProperties": false
+    },
+    "summary": {
+      "type": "object",
+      "required": ["nodes", "capture_planned", "unreachable", "excluded_by_kind"],
+      "properties": {
+        "nodes": {"type": "integer", "minimum": 1},
+        "capture_planned": {"type": "integer", "minimum": 0},
+        "unreachable": {"type": "integer", "minimum": 0},
+        "excluded_by_kind": {"type": "object", "additionalProperties": {"type": "integer", "minimum": 0}}
+      },
+      "additionalProperties": false
+    },
+    "pages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["node_id", "kind", "label", "declared_at", "required_state", "expected", "reachable", "capture", "capture_key", "depth", "ui_sequence", "path_text", "steps", "skip_reason"],
+        "properties": {
+          "node_id": {"type": "string", "minLength": 1},
+          "kind": {"type": "string", "minLength": 1},
+          "label": {"type": "string", "minLength": 1},
+          "declared_at": {"type": "string", "pattern": ":[1-9][0-9]*$"},
+          "required_state": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
+          "expected": {"type": "object"},
+          "reachable": {"type": "boolean"},
+          "capture": {"type": "boolean"},
+          "capture_key": {"type": ["string", "null"]},
+          "depth": {"type": ["integer", "null"], "minimum": 0},
+          "ui_sequence": {"type": "string", "minLength": 1},
+          "path_text": {"type": ["string", "null"]},
+          "steps": {"type": "array"},
+          "skip_reason": {"type": ["string", "null"]}
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/skills/d2h-utg-ai-generate/references/utg-schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hometrans.local/schemas/utg-v2.json",
+  "title": "HomeTrans source-derived UTG",
+  "type": "object",
+  "required": ["directed", "multigraph", "graph", "nodes", "links"],
+  "properties": {
+    "directed": {"const": true},
+    "multigraph": {"const": true},
+    "graph": {
+      "type": "object",
+      "required": ["app", "architecture", "root"],
+      "properties": {
+        "app": {"type": "string", "minLength": 1},
+        "package": {"type": "string"},
+        "architecture": {"type": "string", "minLength": 1},
+        "root": {"type": "string", "minLength": 1},
+        "start_destination": {"type": "string"},
+        "version_name": {"type": "string"},
+        "build_variant": {"type": "string"}
+      },
+      "additionalProperties": true
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "label", "declared_at", "status", "provenance", "widgets", "expected", "required_state", "extra"],
+        "properties": {
+          "id": {"type": "string", "minLength": 1},
+          "kind": {"type": "string", "minLength": 1},
+          "label": {"type": "string", "minLength": 1},
+          "declared_at": {"type": "string", "pattern": ":[1-9][0-9]*$"},
+          "status": {"type": "string", "minLength": 1},
+          "provenance": {"type": "string", "minLength": 1},
+          "widgets": {"type": "array"},
+          "expected": {
+            "type": "object",
+            "properties": {
+              "text_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+              "text_all": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+              "content_desc_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+              "resource_id_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+              "activity_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}
+            },
+            "additionalProperties": false
+          },
+          "required_state": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
+          "extra": {"type": ["object", "null"]}
+        },
+        "additionalProperties": true
+      }
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source", "target", "mechanism", "trigger", "guard", "args", "confidence", "provenance", "key", "status"],
+        "properties": {
+          "source": {"type": "string", "minLength": 1},
+          "target": {"type": "string", "minLength": 1},
+          "mechanism": {"type": "string", "minLength": 1},
+          "trigger": {"type": "string", "pattern": ":[1-9][0-9]*$"},
+          "guard": {
+            "oneOf": [
+              {"type": "null"},
+              {
+                "type": "object",
+                "required": ["kind", "text"],
+                "properties": {
+                  "kind": {"type": "string", "minLength": 1},
+                  "text": {"type": "string", "minLength": 1}
+                },
+                "additionalProperties": true
+              }
+            ]
+          },
+          "args": {"type": "object"},
+          "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+          "provenance": {"type": "string", "minLength": 1},
+          "key": {"type": "integer", "minimum": 0},
+          "status": {"type": "string", "minLength": 1}
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": false
+}

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

@@ -0,0 +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())