@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/phaser/skills/playable-verify-ui/scripts/verify_tile_consistency.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""
+Tile silhouette consistency — compares bounding boxes across assets/images/tiles/*.
+
+Pure local CV (PIL alpha bbox). Fails when same-type gems have wildly different aspect ratios
+(test11 B12: hex/diamond/square/drop mixed).
+
+Usage:
+  python3 skills/playable-verify-ui/scripts/verify_tile_consistency.py [--root .]
+
+Exit 0 = pass or skip
+Exit 2 = fail
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+# Run-as-script: the manifest helper lives next to this file.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from asset_manifest import entry_for_path, load_manifest  # noqa: E402
+
+
+# Tiles named by color are recolor variants of a single silhouette and MUST stay
+# consistent in shape (test11 B12 mixed hex/diamond/square/drop). Tiles named by
+# shape are intentionally different silhouettes (e.g. memory/flip faces) and are
+# exempt from the silhouette-uniformity check.
+COLOR_NAMES = {
+    "red", "orange", "yellow", "green", "blue", "purple", "pink", "cyan",
+    "teal", "magenta", "violet", "indigo", "gold", "silver", "white", "black",
+    "brown", "lime", "navy", "crimson", "aqua", "amber", "rose", "grey", "gray",
+}
+SHAPE_NAMES = {
+    "circle", "square", "triangle", "diamond", "star", "hex", "hexagon",
+    "drop", "heart", "oval", "round", "back", "club", "spade", "rect",
+    "pentagon", "octagon", "cross", "moon", "leaf", "gem",
+}
+
+
+def make_issue(
+    *,
+    issue_id: str,
+    class_name: str,
+    message: str,
+    source_path: str,
+    evidence_type: str = "asset",
+    box: list[float] | None = None,
+    sources: list[dict] | None = None,
+    metrics: dict | None = None,
+    severity: str = "P1",
+) -> dict:
+    issue = {
+        "id": issue_id,
+        "status": "fail",
+        "severity": severity,
+        "className": class_name,
+        "message": message,
+        "evidenceType": evidence_type,
+        "sourcePath": source_path,
+        "recommendedSkill": "playable-verify-ui",
+        "alphaStrategy": "n-a",
+    }
+    if box is not None:
+        issue["box"] = [float(v) for v in box]
+    if sources is not None:
+        issue["sources"] = sources
+    if metrics is not None:
+        issue["metrics"] = metrics
+    return issue
+
+
+def manifest_issue(message: str, source_path: str = "assets/asset-manifest.json") -> dict:
+    return make_issue(
+        issue_id=f"asset_manifest:{source_path}",
+        class_name="asset_manifest_invalid",
+        message=message,
+        source_path=source_path,
+    )
+
+
+def classify_tile(stem: str) -> str:
+    """Return 'color' (uniform silhouette expected), 'shape' (variety expected) or 'other'."""
+    tokens = {t for t in stem.lower().replace("-", "_").split("_") if t}
+    if tokens & SHAPE_NAMES:
+        return "shape"
+    if tokens & COLOR_NAMES:
+        return "color"
+    return "other"
+
+
+def load_pil() -> Any | None:
+    try:
+        from PIL import Image
+
+        return Image
+    except ImportError:
+        return None
+
+
+def content_bbox(image_mod: Any, path: Path) -> dict | None:
+    img = image_mod.open(path).convert("RGBA")
+    w, h = img.size
+    pixels = img.load()
+    min_x, min_y, max_x, max_y = w, h, 0, 0
+    found = False
+    for y in range(h):
+        for x in range(w):
+            if pixels[x, y][3] > 16:
+                found = True
+                min_x = min(min_x, x)
+                min_y = min(min_y, y)
+                max_x = max(max_x, x)
+                max_y = max(max_y, y)
+    if not found:
+        return None
+    bw = max_x - min_x + 1
+    bh = max_y - min_y + 1
+    opaque = 0
+    for y in range(min_y, max_y + 1):
+        for x in range(min_x, max_x + 1):
+            if pixels[x, y][3] > 16:
+                opaque += 1
+    # bboxOccupancy = opaque pixels / bounding-box area — a silhouette-shape
+    # discriminator (square ~1.0, circle ~0.79, diamond ~0.5) that bbox aspect
+    # ratio alone cannot capture.
+    return {
+        "box": [float(min_x), float(min_y), float(max_x + 1), float(max_y + 1)],
+        "width": bw,
+        "height": bh,
+        "aspect": round(bw / bh, 4) if bh else 0,
+        "fillRatio": round((bw * bh) / (w * h), 4),
+        "bboxOccupancy": round(opaque / (bw * bh), 4) if bw and bh else 0,
+        "kind": classify_tile(path.stem),
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", default=".")
+    parser.add_argument("--aspect-spread-max", type=float, default=0.35)
+    parser.add_argument("--occupancy-spread-max", type=float, default=0.20)
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    tiles_dir = root / "assets" / "images" / "tiles"
+    image_mod = load_pil()
+    if image_mod is None:
+        issue = make_issue(
+            issue_id="tile_consistency:pillow_missing",
+            class_name="validator_dependency_missing",
+            message="Pillow required",
+            source_path="project",
+            severity="P0",
+        )
+        print(json.dumps({"ok": False, "issues": [issue], "failures": ["Pillow required"]}))
+        return 2
+
+    # A malformed/stale manifest is a contract failure — surface it before the
+    # "fewer than 2 tiles" early return so it is always caught.
+    manifest, manifest_errors = load_manifest(root)
+    if manifest_errors:
+        print(
+            json.dumps(
+                {
+                    "ok": False,
+                    "manifestErrors": manifest_errors,
+                    "issues": [manifest_issue(err) for err in manifest_errors],
+                    "failures": manifest_errors,
+                },
+                indent=2,
+            )
+        )
+        return 2
+
+    all_tiles = sorted(tiles_dir.glob("*.webp")) + sorted(tiles_dir.glob("*.png"))
+    failures: list[str] = []
+    issues: list[dict] = []
+    skipped_by_manifest: list[dict] = []
+    tiles: list[Path] = []
+    # With a manifest, only declared runtime tiles are in scope; reference-only and
+    # non-tile images are skipped, and an undeclared tile under tiles/ is a failure.
+    for t in all_tiles:
+        if manifest is not None:
+            rel = str(t.relative_to(root))
+            entry = entry_for_path(manifest, rel)
+            if entry is None:
+                message = (
+                    f"{rel}: tile present under assets/images/tiles/ but not declared in "
+                    "asset-manifest.json (every runtime tile must declare role/usage)"
+                )
+                failures.append(message)
+                issues.append(
+                    make_issue(
+                        issue_id=f"asset_manifest_undeclared:{rel}",
+                        class_name="asset_manifest_undeclared",
+                        message=message,
+                        source_path=rel,
+                    )
+                )
+                continue
+            if entry.get("usage", "runtime") == "reference-only":
+                skipped_by_manifest.append({"name": t.name, "reason": "reference-only", "id": entry.get("id")})
+                continue
+            if entry.get("role") != "tile":
+                skipped_by_manifest.append({"name": t.name, "reason": f"role={entry.get('role')}", "id": entry.get("id")})
+                continue
+        tiles.append(t)
+
+    if len(tiles) < 2:
+        out = {
+            "ok": len(failures) == 0,
+            "skipped": len(failures) == 0,
+            "note": "fewer than 2 in-scope tile assets",
+            "skippedByManifest": skipped_by_manifest,
+            "issues": issues,
+            "failures": failures,
+        }
+        print(json.dumps(out, indent=2))
+        return 0 if out["ok"] else 2
+
+    metrics: dict[str, dict] = {}
+    for t in tiles:
+        bbox = content_bbox(image_mod, t)
+        if bbox is None:
+            rel = str(t.relative_to(root))
+            message = f"{t.name}: empty/fully transparent tile"
+            failures.append(message)
+            issues.append(
+                make_issue(
+                    issue_id=f"tile_empty:{rel}",
+                    class_name="tile_empty",
+                    message=message,
+                    source_path=rel,
+                )
+            )
+            continue
+        metrics[t.name] = bbox
+
+    # Silhouette-uniformity is enforced only over the color-named (recolor-variant)
+    # group; shape-named tiles are intentionally different and are skipped.
+    uniform = {name: m for name, m in metrics.items() if m.get("kind") == "color"}
+    silhouette_group = uniform if len(uniform) >= 2 else {}
+    skipped_shape = sorted(name for name, m in metrics.items() if m.get("kind") == "shape")
+
+    aspects = [m["aspect"] for m in silhouette_group.values() if m["aspect"] > 0]
+    spread_metrics: dict[str, float] = {}
+    group_messages: list[str] = []
+    if len(aspects) >= 2:
+        spread = max(aspects) - min(aspects)
+        spread_metrics["aspectSpread"] = round(spread, 4)
+        if spread > args.aspect_spread_max:
+            group_messages.append(
+                f"tile aspect spread {spread:.3f} > {args.aspect_spread_max} — mixed silhouettes "
+                f"(min={min(aspects):.3f} max={max(aspects):.3f})"
+            )
+
+    occupancies = [m["bboxOccupancy"] for m in silhouette_group.values() if m["bboxOccupancy"] > 0]
+    if len(occupancies) >= 2:
+        occ_spread = max(occupancies) - min(occupancies)
+        spread_metrics["bboxOccupancySpread"] = round(occ_spread, 4)
+        if occ_spread > args.occupancy_spread_max:
+            lo = min(silhouette_group.items(), key=lambda kv: kv[1]["bboxOccupancy"])
+            hi = max(silhouette_group.items(), key=lambda kv: kv[1]["bboxOccupancy"])
+            group_messages.append(
+                f"tile bbox-occupancy spread {occ_spread:.3f} > {args.occupancy_spread_max} — "
+                f"mixed silhouettes among color-named tiles "
+                f"(e.g. {hi[0]}={hi[1]['bboxOccupancy']:.2f} vs {lo[0]}={lo[1]['bboxOccupancy']:.2f})"
+            )
+
+    fills = [m["fillRatio"] for m in silhouette_group.values()]
+    if len(fills) >= 2:
+        fill_spread = max(fills) - min(fills)
+        spread_metrics["fillRatioSpread"] = round(fill_spread, 4)
+        if fill_spread > 0.25:
+            group_messages.append(f"tile fill-ratio spread {fill_spread:.3f} > 0.25 — inconsistent content size in cell")
+
+    if group_messages:
+        failures.extend(group_messages)
+        sources = [
+            {
+                "sourcePath": str((tiles_dir / name).relative_to(root)),
+                "name": name,
+                "box": metrics[name].get("box"),
+                "metrics": {k: v for k, v in metrics[name].items() if k != "box"},
+            }
+            for name in sorted(silhouette_group.keys())
+            if name in metrics
+        ]
+        issues.append(
+            make_issue(
+                issue_id="tile_inconsistent_silhouette:color_group",
+                class_name="tile_inconsistent_silhouette",
+                message="; ".join(group_messages),
+                source_path="assets/images/tiles",
+                evidence_type="asset-group",
+                sources=sources,
+                metrics={
+                    **spread_metrics,
+                    "aspectSpreadMax": args.aspect_spread_max,
+                    "occupancySpreadMax": args.occupancy_spread_max,
+                    "tileMetrics": metrics,
+                },
+            )
+        )
+
+    out = {
+        "ok": len(failures) == 0,
+        "tiles": metrics,
+        "silhouetteGroup": sorted(silhouette_group.keys()),
+        "skippedShapeTiles": skipped_shape,
+        "skippedByManifest": skipped_by_manifest,
+        "issues": issues,
+        "failures": failures,
+    }
+    print(json.dumps(out, indent=2))
+    return 0 if out["ok"] else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())