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

apple_resource_resolver.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Read-only Apple asset, color, localization, and symbol resolution."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+IGNORED_DIRS = {".git", ".build", ".swiftpm", ".ui-design-workbench", "build", "DerivedData", "Pods", "vendor"}
+FILE_LIMIT = 30000
+
+
+@dataclass(frozen=True)
+class AppleResource:
+    value: str
+    source: str
+    confidence: str = "high"
+
+
+def _component(value: Any) -> int:
+    raw = str(value or "0").strip()
+    try:
+        number = int(raw, 16) / 255 if raw.lower().startswith("0x") else float(raw)
+    except ValueError:
+        number = 0
+    return max(0, min(255, round(number * 255)))
+
+
+def _color_value(payload: dict[str, Any]) -> str | None:
+    components = payload.get("components", {}) if isinstance(payload, dict) else {}
+    if not isinstance(components, dict):
+        return None
+    red, green, blue = (_component(components.get(key)) for key in ("red", "green", "blue"))
+    alpha = _component(components.get("alpha", 1))
+    return f"#{red:02x}{green:02x}{blue:02x}" if alpha == 255 else f"#{red:02x}{green:02x}{blue:02x}{alpha:02x}"
+
+
+class AppleResourceCatalog:
+    def __init__(self, root: Path):
+        self.root = root.resolve()
+        self.images: dict[str, AppleResource] = {}
+        self.colors: dict[str, AppleResource] = {}
+        self.strings: dict[str, AppleResource] = {}
+        self.diagnostics: list[dict[str, Any]] = []
+
+    @classmethod
+    def discover(cls, root: Path) -> "AppleResourceCatalog":
+        catalog = cls(root)
+        seen = 0
+        for directory, names, files in os.walk(catalog.root):
+            names[:] = [name for name in names if name not in IGNORED_DIRS and not name.startswith(".")]
+            folder = Path(directory)
+            for filename in files:
+                seen += 1
+                if seen > FILE_LIMIT:
+                    catalog.diagnostics.append({"reason": "apple-resource-file-limit", "limit": FILE_LIMIT})
+                    return catalog
+                path = folder / filename
+                if filename == "Contents.json" and folder.suffix.lower() in {".imageset", ".colorset"}:
+                    catalog._read_asset(path)
+                elif path.suffix.lower() == ".strings" and folder.name.lower().endswith(".lproj"):
+                    catalog._read_strings(path)
+        return catalog
+
+    def _relative(self, path: Path) -> str:
+        try:
+            return path.resolve().relative_to(self.root).as_posix()
+        except ValueError:
+            return path.name
+
+    def _read_asset(self, path: Path) -> None:
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            self.diagnostics.append({"reason": "invalid-apple-asset-catalog", "file": self._relative(path)})
+            return
+        name = path.parent.stem
+        if path.parent.suffix.lower() == ".imageset":
+            candidates = [item for item in payload.get("images", []) if isinstance(item, dict) and item.get("filename")]
+            candidates.sort(key=lambda item: ({"1x": 0, "2x": 1, "3x": 2}.get(str(item.get("scale")), -1), item.get("idiom") == "universal"), reverse=True)
+            if candidates:
+                image = path.parent / str(candidates[0]["filename"])
+                if image.is_file():
+                    self.images[name] = AppleResource(self._relative(image), self._relative(path))
+        else:
+            candidates = [item for item in payload.get("colors", []) if isinstance(item, dict) and isinstance(item.get("color"), dict)]
+            universal = next((item for item in candidates if item.get("idiom") == "universal"), candidates[0] if candidates else None)
+            value = _color_value(universal["color"]) if universal else None
+            if value:
+                self.colors[name] = AppleResource(value, self._relative(path))
+
+    def _read_strings(self, path: Path) -> None:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return
+        source = self._relative(path)
+        for match in re.finditer(r'"((?:\\.|[^"\\])*)"\s*=\s*"((?:\\.|[^"\\])*)"\s*;', text):
+            try:
+                key = json.loads(f'"{match.group(1)}"')
+                value = json.loads(f'"{match.group(2)}"')
+            except json.JSONDecodeError:
+                continue
+            self.strings.setdefault(key, AppleResource(value, source))
+
+    def image(self, name: str) -> AppleResource | None:
+        return self.images.get(str(name or "").strip())
+
+    def color(self, name: str) -> AppleResource | None:
+        return self.colors.get(str(name or "").strip())
+
+    def localized(self, key: str) -> AppleResource | None:
+        return self.strings.get(str(key or "").strip())
+
+
+SF_SYMBOL_PATHS = {
+    "plus": "M12 5v14M5 12h14",
+    "xmark": "M6 6l12 12M18 6L6 18",
+    "checkmark": "M5 12l4 4L19 6",
+    "magnifyingglass": "M10.5 4a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13M15.5 15.5L21 21",
+    "house": "M3 11.5L12 4l9 7.5V21h-6v-6H9v6H3z",
+    "gearshape": "M12 8a4 4 0 1 0 0 8 4 4 0 0 0 0-8M12 2v3M12 19v3M2 12h3M19 12h3M5 5l2 2M17 17l2 2M19 5l-2 2M7 17l-2 2",
+    "trash": "M5 7h14M9 7V4h6v3M7 7l1 14h8l1-14M10 10v7M14 10v7",
+    "pencil": "M4 20l4-1 11-11-3-3L5 16zM14 7l3 3",
+}
+
+
+def sf_symbol_asset(name: str) -> str | None:
+    key = str(name or "").split(".", 1)[0].lower()
+    path = SF_SYMBOL_PATHS.get(key)
+    if not path:
+        return None
+    fill = ' fill="currentColor"' if key == "house" else ' fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"'
+    svg = f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="{path}"{fill}/></svg>'
+    return "data:image/svg+xml;base64," + base64.b64encode(svg.encode("utf-8")).decode("ascii")

coverage_report.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Build a deterministic UI translation coverage report from ui-ir.json."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from quality_common import hierarchy_issues, navigation_graph_issues, read_json, walk_tree_screen_ids, write_json
+from render_preview import fidelity_audit
+from validate_platform_profiles import validate_profiles
+
+
+def gate(gate_id: str, label: str, passed: bool, actual: Any, expected: Any, details: Any = None) -> dict[str, Any]:
+    value = {"id": gate_id, "label": label, "status": "pass" if passed else "fail", "actual": actual, "expected": expected}
+    if details:
+        value["details"] = details
+    return value
+
+
+def build_report(ir: dict[str, Any], purpose: str = "projection") -> dict[str, Any]:
+    if purpose not in {"projection", "review"}:
+        raise ValueError(f"Unknown coverage purpose: {purpose}")
+    audit = fidelity_audit(ir)
+    profiles = validate_profiles(ir)
+    screen_ids = [str(item.get("id")) for item in ir.get("screens", []) if item.get("id")]
+    tree_ids = walk_tree_screen_ids(ir.get("screenTree", []))
+    tree_counts = Counter(tree_ids)
+    missing_tree = sorted(set(screen_ids) - set(tree_ids))
+    duplicate_tree = sorted(item for item, count in tree_counts.items() if count > 1)
+    unknown_tree = sorted(set(tree_ids) - set(screen_ids))
+    hierarchy = hierarchy_issues(ir)
+    graph_issues = navigation_graph_issues(ir)
+    mode = ir.get("design", {}).get("mode", "reconstruct")
+    needs_design_evidence = purpose == "review" and mode in {"generate", "redesign"}
+    needs_source = mode == "reconstruct"
+    visual_verification = ir.get("visualVerification", {}) if isinstance(ir.get("visualVerification"), dict) else {}
+    visual_status = str(visual_verification.get("status") or "unverified")
+
+    gates = [
+        gate("fidelity", "Renderer fidelity audit", audit.get("status") == "reviewable", audit.get("status"), "reviewable", audit.get("reasons")),
+        gate("screen-tree", "Every screen appears once in screenTree", not missing_tree and not duplicate_tree and not unknown_tree, len(tree_ids), len(screen_ids), {"missing": missing_tree, "duplicates": duplicate_tree, "unknown": unknown_tree}),
+        gate("screen-hierarchy", "screenTree preserves source navigation hierarchy", not hierarchy, len(hierarchy), 0, hierarchy),
+        gate("navigation-graph", "Source navigation graph covers nested logical views", not graph_issues, len(graph_issues), 0, graph_issues),
+        gate("screens", "Translated screen coverage", audit.get("screenCoverage", 0) == 1, audit.get("screenCoverage", 0), 1, audit.get("missingScreens")),
+        gate("screen-accountability", "Discovered screens translated or explicitly excluded", audit.get("screenAccountabilityCoverage", 0) == 1, audit.get("screenAccountabilityCoverage", 0), 1, audit.get("missingScreens")),
+        gate("routes", "Discovered route coverage", audit.get("routeCoverage", 0) == 1, audit.get("routeCoverage", 0), 1, audit.get("missingRoutes")),
+        gate("navigation", "Discovered navigation coverage", audit.get("navigationCoverage", 0) == 1, audit.get("navigationCoverage", 0), 1, audit.get("missingNavigationTargets")),
+        gate("components", "Mapped component coverage", audit.get("componentCoverage", 0) == 1, audit.get("componentCoverage", 0), 1),
+        gate("appearance", "Explicit appearance coverage", audit.get("appearanceCoverage", 0) >= .9, audit.get("appearanceCoverage", 0), .9),
+        gate("profiles", "Platform profiles", profiles.get("status") == "pass", profiles.get("status"), "pass", profiles.get("issues")),
+    ]
+    if needs_source:
+        gates.append(gate("source", "Source mapping coverage", audit.get("sourceCoverage", 0) >= .8, audit.get("sourceCoverage", 0), .8))
+    if needs_design_evidence:
+        gates.extend([
+            gate("evidence", "Design evidence coverage", audit.get("evidenceCoverage", 0) >= .9, audit.get("evidenceCoverage", 0), .9),
+            gate("semantics", "Interactive semantics coverage", audit.get("semanticCoverage", 0) == 1, audit.get("semanticCoverage", 0), 1),
+            gate("standards", "Platform-standard coverage", audit.get("standardCoverage", 0) == 1, audit.get("standardCoverage", 0), 1),
+            gate("targets", "Interactive target coverage", audit.get("targetCoverage", 0) == 1, audit.get("targetCoverage", 0), 1, audit.get("targetFailures")),
+            gate("contrast", "Resolvable contrast coverage", audit.get("contrastCoverage", 0) == 1 and not audit.get("contrastFailures"), audit.get("contrastCoverage", 0), 1, {"failures": audit.get("contrastFailures"), "unresolved": audit.get("contrastUnresolved")}),
+            gate("states", "Declared scenario coverage", audit.get("stateCoverage", 0) == 1, audit.get("stateCoverage", 0), 1, audit.get("missingStates")),
+        ])
+
+    failed = [item for item in gates if item["status"] == "fail"]
+    return {
+        "version": 1,
+        "status": "blocked" if failed else "pass",
+        "project": ir.get("project", {}).get("name", "Project"),
+        "designMode": mode,
+        "purpose": purpose,
+        "verification": {
+            "sourceProjection": "pass" if audit.get("status") == "reviewable" else "blocked",
+            "visualParity": visual_status,
+            "reason": visual_verification.get("reason") or (None if visual_status != "unverified" else "No Layoutlib, emulator screenshot, or golden-image comparison was supplied."),
+        },
+        "summary": {"passed": len(gates) - len(failed), "failed": len(failed), "total": len(gates)},
+        "inventory": {
+            "screens": len(screen_ids),
+            "treeEntries": len(tree_ids),
+            "nodes": len(ir.get("nodes", {})),
+            "components": len(ir.get("componentCatalog", {}).get("components", [])),
+            "actions": audit.get("interactionActions", 0),
+            "navigationActions": audit.get("navigationActions", 0),
+        },
+        "coverage": {key: value for key, value in audit.items() if key.endswith("Coverage")},
+        "gates": gates,
+        "platformProfiles": profiles,
+        "fidelityAudit": audit,
+    }
+
+
+def markdown(report: dict[str, Any]) -> str:
+    lines = [
+        f"# UI coverage · {report['project']}",
+        "",
+        f"Status: **{report['status']}** · passed {report['summary']['passed']} / {report['summary']['total']}",
+        "",
+        "| Gate | Status | Actual | Expected |",
+        "| --- | --- | ---: | ---: |",
+    ]
+    for item in report["gates"]:
+        lines.append(f"| {item['label']} | {item['status']} | {item['actual']} | {item['expected']} |")
+    failed = [item for item in report["gates"] if item["status"] == "fail"]
+    if failed:
+        lines.extend(["", "## Blocking details", ""])
+        for item in failed:
+            lines.append(f"- **{item['label']}**: {item.get('details') or 'threshold not met'}")
+    return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("ir", help="Path to ui-ir.json")
+    parser.add_argument("--output", required=True, help="Path for ui-coverage.json")
+    parser.add_argument("--markdown", help="Optional Markdown summary path")
+    parser.add_argument("--mode", choices=("projection", "review"), default="projection", help="Projection checks transfer only; review also evaluates design-quality coverage")
+    parser.add_argument("--strict", action="store_true", help="Exit non-zero when a gate fails")
+    args = parser.parse_args()
+    report = build_report(read_json(args.ir), args.mode)
+    write_json(args.output, report)
+    if args.markdown:
+        target = Path(args.markdown)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(markdown(report), encoding="utf-8")
+    print(f"Coverage: {report['status']} | {report['summary']['passed']}/{report['summary']['total']} gates")
+    return 2 if args.strict and report["status"] != "pass" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fidelity_adapter_api.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Stable provider-neutral API for deterministic source-to-IR adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class SourceContext:
+    root: Path
+    path: Path
+    source: str
+    text: str
+    platforms: tuple[str, ...]
+    role: str
+
+
+@dataclass
+class AdapterResult:
+    adapter: str
+    screens: list[dict[str, Any]] = field(default_factory=list)
+    nodes: dict[str, dict[str, Any]] = field(default_factory=dict)
+    tokens: dict[str, dict[str, Any]] = field(default_factory=lambda: {"colors": {}, "spacing": {}, "radii": {}, "typography": {}})
+    themes: list[dict[str, Any]] = field(default_factory=list)
+    components: list[dict[str, Any]] = field(default_factory=list)
+    unsupported: list[dict[str, Any]] = field(default_factory=list)
+
+
+class UiSourceAdapter(Protocol):
+    id: str
+
+    def supports(self, context: SourceContext) -> bool: ...
+    def translate(self, context: SourceContext) -> AdapterResult: ...
+
+
+_ADAPTERS: list[UiSourceAdapter] = []
+
+
+def register_adapter(adapter: UiSourceAdapter) -> None:
+    if any(current.id == adapter.id for current in _ADAPTERS):
+        raise ValueError(f"Adapter already registered: {adapter.id}")
+    _ADAPTERS.append(adapter)
+
+
+def registered_adapters() -> tuple[UiSourceAdapter, ...]:
+    return tuple(_ADAPTERS)
+
+
+def adapter_capabilities() -> list[dict[str, Any]]:
+    return [
+        {
+            "id": adapter.id,
+            "platforms": list(getattr(adapter, "platforms", ())),
+            "extensions": list(getattr(adapter, "extensions", ())),
+            "maturity": str(getattr(adapter, "maturity", "conservative")),
+            "structuralTier": str(getattr(adapter, "structural_tier", "translated")),
+            "visualTier": str(getattr(adapter, "visual_tier", "none")),
+            "nativeEvidenceRequired": bool(getattr(adapter, "native_evidence_required", False)),
+            "nativeProviders": list(getattr(adapter, "native_providers", ())),
+            "resourceResolution": list(getattr(adapter, "resource_resolution", ())),
+            "layoutFeatures": list(getattr(adapter, "layout_features", ())),
+            "limitations": list(getattr(adapter, "limitations", ())),
+        }
+        for adapter in _ADAPTERS
+    ]
+
+
+def translate_sources(contexts: list[SourceContext]) -> AdapterResult:
+    combined = AdapterResult(adapter="registry")
+    for adapter in _ADAPTERS:
+        prepare = getattr(adapter, "prepare", None)
+        if callable(prepare):
+            prepare(contexts)
+    for context in contexts:
+        adapter = next((candidate for candidate in _ADAPTERS if candidate.supports(context)), None)
+        if adapter is None:
+            continue
+        result = adapter.translate(context)
+        combined.screens.extend(result.screens)
+        combined.nodes.update(result.nodes)
+        for group, values in result.tokens.items():
+            combined.tokens.setdefault(group, {}).update(values if isinstance(values, dict) else {})
+        combined.themes.extend(result.themes)
+        combined.components.extend(result.components)
+        combined.unsupported.extend(result.unsupported)
+    return combined