ui-design-workbench-cli 0.5.0__py3-none-any.whl

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/scripts/native_render_apple.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Read-only Apple native-render provider discovery."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import Any, Iterator
+
+
+IGNORED_DIRS = {".git", ".build", ".idea", ".ui-design-workbench", "build", "DerivedData", "node_modules", "Pods", "vendor"}
+TEXT_LIMIT = 2 * 1024 * 1024
+FILE_LIMIT = 30000
+
+
+def _relative(path: Path, root: Path) -> str:
+    return path.resolve().relative_to(root.resolve()).as_posix()
+
+
+def _files(root: Path) -> Iterator[Path]:
+    seen = 0
+    for directory, names, files in os.walk(root):
+        names[:] = [name for name in names if name not in IGNORED_DIRS and not name.startswith(".")]
+        for name in files:
+            seen += 1
+            if seen > FILE_LIMIT:
+                return
+            yield Path(directory) / name
+
+
+def _bundles(root: Path) -> tuple[list[Path], list[Path]]:
+    projects: list[Path] = []
+    workspaces: list[Path] = []
+    for directory, names, _ in os.walk(root):
+        names[:] = [name for name in names if name not in IGNORED_DIRS and not name.startswith(".")]
+        current = Path(directory)
+        for name in list(names):
+            path = current / name
+            if name.endswith(".xcodeproj"):
+                projects.append(path)
+                names.remove(name)
+            elif name.endswith(".xcworkspace"):
+                workspaces.append(path)
+                names.remove(name)
+    return projects, workspaces
+
+
+def _read(path: Path) -> str:
+    try:
+        if path.stat().st_size > TEXT_LIMIT:
+            return ""
+        return path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def _fingerprint(root: Path, files: list[Path]) -> str:
+    digest = hashlib.sha256()
+    for path in sorted(set(files)):
+        try:
+            stat = path.stat()
+        except OSError:
+            continue
+        digest.update(f"{_relative(path, root)}\0{stat.st_size}\0{stat.st_mtime_ns}\n".encode("utf-8"))
+    return digest.hexdigest()
+
+
+def discover_apple(root: Path, host_platform: str | None = None) -> dict[str, Any]:
+    root = root.resolve()
+    host = host_platform or sys.platform
+    all_files = list(_files(root))
+    swift_files = [path for path in all_files if path.suffix.lower() == ".swift"]
+    interfaces = [path for path in all_files if path.suffix.lower() in {".storyboard", ".xib"}]
+    package_files = [path for path in all_files if path.name in {"Package.swift", "Package.resolved", "Podfile"}]
+    projects, workspaces = _bundles(root)
+    detected = bool(swift_files or interfaces or projects or workspaces)
+    preview_entries: list[dict[str, Any]] = []
+    snapshot_markers = 0
+    swiftui_views = 0
+    source_inputs: list[Path] = []
+    for path in swift_files:
+        text = _read(path)
+        if not text:
+            continue
+        if "SwiftUI" in text or "#Preview" in text or "PreviewProvider" in text or "SnapshotTesting" in text:
+            source_inputs.append(path)
+        swiftui_views += len(re.findall(r"\bstruct\s+\w+\s*:\s*View\b", text))
+        snapshot_markers += len(re.findall(r"(?:SnapshotTesting|assertSnapshot|iOSSnapshotTestCase|FBSnapshotTestCase)", text))
+        for match in re.finditer(r"#Preview(?:\s*\(\s*[\"']([^\"']+)[\"'][^)]*\))?", text):
+            preview_entries.append({"symbol": match.group(1) or "#Preview", "file": _relative(path, root)})
+        for match in re.finditer(r"\bstruct\s+(\w+)\s*:\s*PreviewProvider\b", text):
+            preview_entries.append({"symbol": match.group(1), "file": _relative(path, root)})
+    package_text = "\n".join(_read(path) for path in package_files)
+    snapshot_configured = snapshot_markers > 0 or "swift-snapshot-testing" in package_text.lower()
+    mac_host = host == "darwin"
+    xcode_ready = bool(mac_host and shutil.which("xcodebuild"))
+    simulator_ready = bool(xcode_ready and shutil.which("xcrun"))
+
+    def status(configured: bool, requires_host: bool = True) -> str:
+        if not detected:
+            return "not-applicable"
+        if requires_host and not mac_host:
+            return "host-required"
+        return "configured" if configured else "not-configured"
+
+    providers = [
+        {
+            "id": "xcode-preview",
+            "platform": "apple",
+            "status": status(bool(preview_entries) and xcode_ready),
+            "availableFidelityTier": "native-preview",
+            "supports": ["swiftui"],
+            "reason": "Xcode and SwiftUI preview entries are available." if preview_entries and xcode_ready else "Requires a macOS Xcode worker and a SwiftUI Preview entry point.",
+            "execution": "explicit-only",
+        },
+        {
+            "id": "swift-snapshot-testing",
+            "platform": "apple",
+            "status": status(snapshot_configured and xcode_ready),
+            "availableFidelityTier": "native-preview",
+            "supports": ["swiftui", "uikit", "appkit"],
+            "reason": "Snapshot test markers and Xcode are available." if snapshot_configured and xcode_ready else "Requires a configured snapshot-test target on a macOS Xcode worker.",
+            "execution": "explicit-only",
+        },
+        {
+            "id": "apple-simulator",
+            "platform": "apple",
+            "status": status(simulator_ready),
+            "availableFidelityTier": "device-verified",
+            "supports": ["swiftui", "uikit", "appkit", "runtime-state"],
+            "reason": "Xcode simulator tooling is available." if simulator_ready else "Requires an explicit run on a macOS Xcode worker.",
+            "execution": "explicit-only",
+        },
+    ]
+    configured = [provider["id"] for provider in providers if provider["status"] == "configured"]
+    inputs = swift_files + interfaces + package_files
+    return {
+        "platform": "apple",
+        "status": "detected" if detected else "not-applicable",
+        "sourceFingerprint": _fingerprint(root, inputs),
+        "project": {
+            "hostPlatform": host,
+            "requiresMacOSWorker": bool(detected and not mac_host),
+            "xcodeProjectCount": len(projects),
+            "xcodeWorkspaceCount": len(workspaces),
+            "swiftFileCount": len(swift_files),
+            "swiftUIViewCount": swiftui_views,
+            "previewEntryCount": len(preview_entries),
+            "interfaceResourceCount": len(interfaces),
+            "snapshotTestMarkerCount": snapshot_markers,
+        },
+        "entryPoints": preview_entries[:200],
+        "providers": providers,
+        "recommendedProvider": configured[0] if configured else None,
+        "currentFidelityTier": "structural",
+        "nativeExecutionStarted": False,
+        "limitations": [
+            "Windows and Linux can discover Apple UI but cannot render it natively.",
+            "A configured provider is capability evidence, not visual fidelity evidence.",
+        ],
+    }

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/scripts/native_render_contracts.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Provider-neutral contracts for opt-in native UI rendering.
+
+Native artifacts are deliberately stored outside the baseline UI IR. Source
+adapters may reconstruct structure, but only a native provider can supply
+evidence for pixel appearance.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+
+NATIVE_STATE_SCHEMA_VERSION = 1
+CAPTURE_STATUSES = {"ready", "blocked", "failed", "stale"}
+PROVIDER_STATUSES = {"configured", "available", "not-configured", "host-required", "not-applicable"}
+NATIVE_FIDELITY_TIERS = {"native-preview", "device-verified"}
+
+
+def _relative_artifact(value: str) -> str:
+    normalized = value.replace("\\", "/").strip()
+    if not normalized:
+        raise ValueError("native artifact reference must not be empty")
+    if normalized.startswith("/") or re.match(r"^[A-Za-z]:/", normalized):
+        raise ValueError(f"native artifact reference must be relative: {value}")
+    parts = [part for part in normalized.split("/") if part not in {"", "."}]
+    if not parts or ".." in parts:
+        raise ValueError(f"native artifact reference escapes its bundle: {value}")
+    return "/".join(parts)
+
+
+@dataclass(frozen=True)
+class NativeRenderRequest:
+    provider_id: str
+    platform: str
+    screen_id: str
+    state_id: str = "default"
+    variant: str = "default"
+    viewport: dict[str, Any] = field(default_factory=dict)
+    locale: str = ""
+    theme: str = ""
+
+    def cache_key(self, source_fingerprint: str, provider_version: str = "") -> str:
+        payload = {
+            **asdict(self),
+            "sourceFingerprint": source_fingerprint,
+            "providerVersion": provider_version,
+        }
+        encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+
+class NativeRenderProvider(Protocol):
+    id: str
+    platforms: tuple[str, ...]
+
+    def discover(self, root: Path) -> dict[str, Any]: ...
+
+    def capture(self, root: Path, request: NativeRenderRequest, output_dir: Path) -> dict[str, Any]: ...
+
+
+def empty_native_state(repo_root: Path) -> dict[str, Any]:
+    return {
+        "schemaVersion": NATIVE_STATE_SCHEMA_VERSION,
+        "type": "ui-design-workbench-native-render-state",
+        "repository": {"root": str(repo_root.resolve())},
+        "status": "not-applicable",
+        "currentFidelityTier": "structural",
+        "nativeExecutionStarted": False,
+        "platforms": [],
+        "providers": [],
+        "captures": [],
+    }
+
+
+def validate_native_state(state: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if state.get("schemaVersion") != NATIVE_STATE_SCHEMA_VERSION:
+        errors.append(f"schemaVersion must be {NATIVE_STATE_SCHEMA_VERSION}")
+    if state.get("type") != "ui-design-workbench-native-render-state":
+        errors.append("type must be ui-design-workbench-native-render-state")
+    if state.get("nativeExecutionStarted") not in {True, False}:
+        errors.append("nativeExecutionStarted must be boolean")
+    providers = state.get("providers", [])
+    if not isinstance(providers, list):
+        errors.append("providers must be an array")
+        providers = []
+    for index, provider in enumerate(providers):
+        if not isinstance(provider, dict):
+            errors.append(f"providers[{index}] must be an object")
+            continue
+        if not provider.get("id") or not provider.get("platform"):
+            errors.append(f"providers[{index}] requires id and platform")
+        if provider.get("status") not in PROVIDER_STATUSES:
+            errors.append(f"providers[{index}].status is invalid")
+    captures = state.get("captures", [])
+    if not isinstance(captures, list):
+        errors.append("captures must be an array")
+        captures = []
+    for index, capture in enumerate(captures):
+        if not isinstance(capture, dict):
+            errors.append(f"captures[{index}] must be an object")
+            continue
+        for key in ("id", "providerId", "platform", "screenId", "sourceFingerprint"):
+            if not capture.get(key):
+                errors.append(f"captures[{index}].{key} is required")
+        if capture.get("status") not in CAPTURE_STATUSES:
+            errors.append(f"captures[{index}].status is invalid")
+        if capture.get("fidelityTier") not in NATIVE_FIDELITY_TIERS:
+            errors.append(f"captures[{index}].fidelityTier is invalid")
+        for key in ("image", "semantics", "geometry"):
+            value = capture.get("artifacts", {}).get(key) if isinstance(capture.get("artifacts"), dict) else None
+            if value:
+                try:
+                    _relative_artifact(str(value))
+                except ValueError as exc:
+                    errors.append(f"captures[{index}].artifacts.{key}: {exc}")
+        if capture.get("status") == "ready" and not isinstance(capture.get("artifacts"), dict):
+            errors.append(f"captures[{index}].artifacts is required for a ready capture")
+    return errors
+
+
+def load_native_state(path: Path, repo_root: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return empty_native_state(repo_root)
+    return payload if isinstance(payload, dict) and not validate_native_state(payload) else empty_native_state(repo_root)
+
+
+def write_native_state(path: Path, state: dict[str, Any]) -> None:
+    errors = validate_native_state(state)
+    if errors:
+        raise ValueError("; ".join(errors))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        temporary.write_text(json.dumps(state, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        os.replace(temporary, path)
+    finally:
+        if temporary.exists():
+            temporary.unlink()

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/scripts/native_render_registry.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Native renderer discovery and cache-state orchestration."""
+
+from __future__ import annotations
+
+import copy
+from pathlib import Path
+from typing import Any
+
+from native_render_android import discover_android
+from native_render_apple import discover_apple
+from native_render_contracts import empty_native_state, load_native_state, write_native_state
+
+
+def discover_native_render(root: Path) -> dict[str, Any]:
+    platforms = [discover_android(root), discover_apple(root)]
+    detected = [item for item in platforms if item.get("status") == "detected"]
+    providers = [provider for item in platforms for provider in item.get("providers", [])]
+    configured = [provider for provider in providers if provider.get("status") == "configured"]
+    host_required = [provider for provider in providers if provider.get("status") == "host-required"]
+    if configured:
+        next_action = "Choose one configured provider and explicitly request a native capture."
+    elif host_required:
+        next_action = "Configure a macOS Xcode worker before requesting Apple native captures."
+    elif detected:
+        next_action = "Configure a supported screenshot provider; source projection remains structural-only."
+    else:
+        next_action = "No Android or Apple native project was detected."
+    return {
+        "schemaVersion": 1,
+        "type": "ui-design-workbench-native-render-state",
+        "repository": {"root": str(root.resolve())},
+        "status": "pass" if detected else "not-applicable",
+        "currentFidelityTier": "structural",
+        "nativeExecutionStarted": False,
+        "platforms": platforms,
+        "providers": providers,
+        "captures": [],
+        "summary": {
+            "detectedPlatforms": [item["platform"] for item in detected],
+            "configuredProviders": [item["id"] for item in configured],
+            "hostRequiredProviders": [item["id"] for item in host_required],
+            "nativeCaptureCount": 0,
+            "staleCaptureCount": 0,
+        },
+        "next": next_action,
+    }
+
+
+def native_render_status(root: Path, state_file: Path, platform: str = "all") -> dict[str, Any]:
+    root = root.resolve()
+    previous = load_native_state(state_file, root)
+    discovered = discover_native_render(root)
+    current_fingerprints = {
+        item.get("platform"): item.get("sourceFingerprint")
+        for item in discovered.get("platforms", [])
+        if item.get("platform")
+    }
+    captures: list[dict[str, Any]] = []
+    for original in previous.get("captures", []):
+        capture = copy.deepcopy(original)
+        platform_name = capture.get("platform")
+        if capture.get("status") == "ready" and current_fingerprints.get(platform_name) != capture.get("sourceFingerprint"):
+            capture["status"] = "stale"
+        captures.append(capture)
+    discovered["captures"] = captures
+    discovered["summary"]["nativeCaptureCount"] = sum(1 for item in captures if item.get("status") == "ready")
+    discovered["summary"]["staleCaptureCount"] = sum(1 for item in captures if item.get("status") == "stale")
+    comparable_previous = {key: value for key, value in previous.items() if key != "cache"}
+    cache_status = "reused" if comparable_previous == discovered else "updated" if state_file.is_file() else "created"
+    discovered["cache"] = {"status": cache_status, "stateFile": str(state_file.resolve())}
+    if cache_status != "reused":
+        write_native_state(state_file, {key: value for key, value in discovered.items() if key != "cache"})
+    if platform != "all":
+        selected = copy.deepcopy(discovered)
+        selected["platforms"] = [item for item in selected["platforms"] if item.get("platform") == platform]
+        selected["providers"] = [item for item in selected["providers"] if item.get("platform") == platform]
+        selected["captures"] = [item for item in selected["captures"] if item.get("platform") == platform]
+        selected["summary"]["detectedPlatforms"] = [item for item in selected["summary"]["detectedPlatforms"] if item == platform]
+        selected["summary"]["configuredProviders"] = [item["id"] for item in selected["providers"] if item.get("status") == "configured"]
+        selected["summary"]["hostRequiredProviders"] = [item["id"] for item in selected["providers"] if item.get("status") == "host-required"]
+        selected["summary"]["nativeCaptureCount"] = sum(1 for item in selected["captures"] if item.get("status") == "ready")
+        selected["summary"]["staleCaptureCount"] = sum(1 for item in selected["captures"] if item.get("status") == "stale")
+        selected["status"] = "pass" if selected["summary"]["detectedPlatforms"] else "not-applicable"
+        return selected
+    return discovered

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/scripts/quality_common.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""Shared deterministic helpers for UI Design Workbench quality gates."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Iterable
+
+
+def resolve_profile_catalog() -> Path:
+    candidates = []
+    if os.environ.get("UIDW_HOME"):
+        candidates.append(Path(os.environ["UIDW_HOME"]).expanduser() / "references" / "platform-profiles.json")
+    candidates.extend([
+        Path(__file__).resolve().parent.parent / "references" / "platform-profiles.json",
+        Path(__file__).resolve().parent / "share" / "ui-design-workbench" / "references" / "platform-profiles.json",
+        Path(sys.prefix) / "share" / "ui-design-workbench" / "references" / "platform-profiles.json",
+    ])
+    return next((item for item in candidates if item.is_file()), candidates[0])
+
+
+PROFILE_CATALOG_PATH = resolve_profile_catalog()
+
+
+def read_json(path: str | Path) -> dict[str, Any]:
+    value = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError(f"Expected a JSON object in {path}")
+    return value
+
+
+def write_json(path: str | Path, value: Any) -> None:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def profile_catalog() -> dict[str, Any]:
+    return read_json(PROFILE_CATALOG_PATH)
+
+
+def platform_family(value: Any) -> str | None:
+    platform = str(value or "").strip().lower()
+    if any(marker in platform for marker in ("android-tv", "compose-tv", "leanback", "react-native", "react_native", "mac-catalyst")):
+        return None
+    if platform in {"windows", "windows-winui", "windows-wpf", "windows-xaml", "winui", "winui3", "wpf", "windows-app-sdk"} or platform.startswith("windows-"):
+        return "windows"
+    if platform in {"macos", "swiftui-macos", "appkit"} or "macos" in platform:
+        return "macos"
+    if "android" in platform:
+        return "android"
+    if platform in {"ios", "swiftui", "uikit"} or "apple" in platform:
+        return "ios"
+    if platform == "flutter":
+        return "flutter"
+    if platform in {"web", "react-web", "vue", "svelte"}:
+        return "web"
+    return None
+
+
+def target_families(ir: dict[str, Any]) -> set[str]:
+    explicit = ir.get("design", {}).get("targetPlatforms", [])
+    values = explicit or ir.get("platforms", [])
+    families = {platform_family(item) for item in values}
+    families.discard(None)
+    return families
+
+
+def framework_adapters(ir: dict[str, Any]) -> set[str]:
+    known = profile_catalog().get("frameworkAdapters", {})
+    found: set[str] = set()
+    for value in ir.get("platforms", []):
+        normalized = str(value or "").strip().lower()
+        if normalized in known:
+            found.add(normalized)
+        elif "flutter" in normalized:
+            found.add("flutter")
+    return found
+
+
+def walk_tree_screen_ids(items: Iterable[Any]) -> list[str]:
+    result: list[str] = []
+    for item in items or []:
+        if not isinstance(item, dict):
+            continue
+        screen_id = item.get("screenId") or item.get("screen")
+        if screen_id:
+            result.append(str(screen_id))
+        result.extend(walk_tree_screen_ids(item.get("children", [])))
+    return result
+
+
+def walk_tree_screen_paths(items: Iterable[Any], path: tuple[str, ...] = ()) -> dict[str, list[str]]:
+    result: dict[str, list[str]] = {}
+    for item in items or []:
+        if not isinstance(item, dict):
+            continue
+        screen_id = item.get("screenId") or item.get("screen")
+        if screen_id:
+            result[str(screen_id)] = list(path)
+            continue
+        label = str(item.get("label") or item.get("name") or item.get("id") or "").strip()
+        result.update(walk_tree_screen_paths(item.get("children", []), (*path, label) if label else path))
+    return result
+
+
+def hierarchy_issues(ir: dict[str, Any]) -> list[dict[str, Any]]:
+    """Compare authored screenTree paths with source-evidenced hierarchy metadata."""
+    paths = walk_tree_screen_paths(ir.get("screenTree", []))
+    screens = ir.get("screens", [])
+    discovered = [item for item in ir.get("discoveredScreens", []) if isinstance(item, dict)]
+    screen_by_evidence: dict[tuple[str, str], str] = {}
+    screen_by_fragment: dict[str, str] = {}
+    for screen in screens:
+        screen_id = str(screen.get("id") or "")
+        source = screen.get("source", {}) if isinstance(screen.get("source"), dict) else {}
+        screen_by_evidence[(str(source.get("file") or ""), str(source.get("symbol") or screen.get("name") or ""))] = screen_id
+        if screen.get("fragment"):
+            screen_by_fragment[str(screen["fragment"])] = screen_id
+
+    def normalized(values: Iterable[Any]) -> list[str]:
+        return [re.sub(r"[^\w]+", " ", str(value).casefold()).strip() for value in values if str(value).strip()]
+
+    def contains_path(actual: list[str], expected: list[str]) -> bool:
+        if not expected:
+            return True
+        return any(actual[index:index + len(expected)] == expected for index in range(len(actual) - len(expected) + 1))
+
+    issues: list[dict[str, Any]] = []
+    evidence_by_fragment = {str(item.get("fragment")): item for item in discovered if item.get("fragment")}
+    for candidate in discovered:
+        key = (str(candidate.get("file") or ""), str(candidate.get("name") or ""))
+        screen_id = screen_by_evidence.get(key) or screen_by_fragment.get(str(candidate.get("fragment") or ""))
+        if not screen_id or screen_id not in paths:
+            continue
+        expected = normalized(candidate.get("groupPath", []))
+        actual = normalized(paths[screen_id])
+        if expected and not contains_path(actual, expected):
+            issues.append({
+                "code": "group-path-mismatch",
+                "screenId": screen_id,
+                "expected": candidate.get("groupPath", []),
+                "actual": paths[screen_id],
+            })
+        parent_fragment = str(candidate.get("parentFragment") or "")
+        if not parent_fragment:
+            continue
+        parent_candidate = evidence_by_fragment.get(parent_fragment, {})
+        parent_key = (str(parent_candidate.get("file") or ""), str(parent_candidate.get("name") or ""))
+        parent_id = screen_by_evidence.get(parent_key) or screen_by_fragment.get(parent_fragment)
+        if not parent_id or parent_id not in paths:
+            continue
+        parent_path = normalized(paths[parent_id])
+        child_path = normalized(paths[screen_id])
+        if len(child_path) <= len(parent_path) or child_path[:len(parent_path)] != parent_path:
+            issues.append({
+                "code": "parent-hierarchy-flattened",
+                "screenId": screen_id,
+                "parentScreenId": parent_id,
+                "parentPath": paths[parent_id],
+                "actual": paths[screen_id],
+            })
+    return issues
+
+
+def navigation_graph_issues(ir: dict[str, Any]) -> list[dict[str, Any]]:
+    discovered = [item for item in ir.get("discoveredScreens", []) if isinstance(item, dict)]
+    nested = [item for item in discovered if item.get("parentFragment")]
+    graph = ir.get("navigationGraph")
+    if not nested and graph is None:
+        return []
+    if not isinstance(graph, dict):
+        return [{"code": "navigation-graph-missing"}]
+    screen_ids = {str(item.get("id")) for item in ir.get("screens", []) if item.get("id")}
+    graph_ids = {str(item.get("screenId")) for item in graph.get("nodes", []) if isinstance(item, dict) and item.get("screenId")}
+    issues: list[dict[str, Any]] = []
+    if graph_ids != screen_ids:
+        issues.append({"code": "navigation-graph-node-mismatch", "missing": sorted(screen_ids - graph_ids), "unknown": sorted(graph_ids - screen_ids)})
+    edges = {
+        (str(item.get("from")), str(item.get("to")), str(item.get("kind")))
+        for item in graph.get("edges", []) if isinstance(item, dict)
+    }
+    for source, target, kind in edges:
+        if source not in screen_ids or target not in screen_ids:
+            issues.append({"code": "navigation-graph-edge-invalid", "from": source, "to": target, "kind": kind})
+    screen_by_fragment = {str(item.get("fragment")): str(item.get("id")) for item in ir.get("screens", []) if item.get("fragment")}
+    candidate_screen = {
+        str(item.get("fragment")): screen_by_fragment.get(str(item.get("fragment")))
+        for item in discovered if item.get("fragment")
+    }
+    for item in nested:
+        child_id = candidate_screen.get(str(item.get("fragment")))
+        parent_id = candidate_screen.get(str(item.get("parentFragment")))
+        if child_id and parent_id and (parent_id, child_id, "open-logical-view") not in edges:
+            issues.append({"code": "navigation-parent-edge-missing", "from": parent_id, "to": child_id})
+    return issues
+
+
+def node_screen_map(ir: dict[str, Any]) -> dict[str, set[str]]:
+    nodes = ir.get("nodes", {})
+    result: dict[str, set[str]] = {str(node_id): set() for node_id in nodes}
+
+    def visit(node_id: str, screen_id: str, seen: set[str]) -> None:
+        if node_id in seen or node_id not in nodes:
+            return
+        seen.add(node_id)
+        result.setdefault(node_id, set()).add(screen_id)
+        for child in nodes[node_id].get("children", []):
+            visit(str(child), screen_id, seen)
+
+    for screen in ir.get("screens", []):
+        visit(str(screen.get("root", "")), str(screen.get("id", "")), set())
+    return result