ui-mirror-skill 1.0.0

package/skill/scripts/generate_migration.py

@@ -0,0 +1,580 @@
+#!/usr/bin/env python3
+"""
+generate_migration.py — Transform a token diff into a prioritized migration plan.
+
+Usage:
+    python3 generate_migration.py <token_diff.json>
+
+Input:  Token diff JSON file (output of compare_tokens.py)
+Output: Markdown migration plan to stdout.
+
+Dependencies: Python 3 standard library only.
+"""
+
+import json
+import sys
+import re
+from collections import OrderedDict
+from datetime import date
+
+
+# ---------------------------------------------------------------------------
+# 1. Complexity weights for effort estimation
+# ---------------------------------------------------------------------------
+
+COMPLEXITY_WEIGHTS = {
+    "colors": 1,       # CSS variable change — lowest risk
+    "radius": 1,       # CSS variable change
+    "shadows": 1,      # CSS variable change
+    "typography": 2,    # May require font import + multiple class changes
+    "spacing": 2,       # Affects layout
+    "components": 3,    # Requires per-component code changes
+    "layout": 4,        # Structural changes — highest risk
+}
+
+# Effort labels
+def effort_label(points: int) -> str:
+    if points <= 5:
+        return "Small (~30 min)"
+    if points <= 15:
+        return "Medium (~1-2 hr)"
+    if points <= 30:
+        return "Large (~3-5 hr)"
+    return "XL (~1 day+)"
+
+
+# ---------------------------------------------------------------------------
+# 2. Phase 1: CSS Token Overrides
+# ---------------------------------------------------------------------------
+
+def generate_phase1_css(diff: dict) -> tuple[str, int]:
+    """
+    Generate :root { } CSS with color/radius/shadow overrides.
+    Returns (css_block, change_count).
+    """
+    lines = []
+    count = 0
+
+    # --- Colors ---
+    color_mods = diff.get("colors", {}).get("modify", [])
+    color_adds = diff.get("colors", {}).get("add", [])
+
+    if color_mods or color_adds:
+        lines.append("  /* ── Colors ── */")
+        for item in color_mods:
+            name = item.get("name", "unknown")
+            bench = item.get("benchmark", "")
+            current = item.get("current", "")
+            delta = item.get("deltaE")
+            delta_str = " (deltaE: {:.3f})".format(delta) if delta is not None else ""
+            lines.append("  --{}: {};  /* was: {}{} */".format(name, bench, current, delta_str))
+            count += 1
+
+        for item in color_adds:
+            name = item.get("name", "unknown")
+            bench = item.get("benchmark", "")
+            lines.append("  --mirror-{}: {};  /* NEW from benchmark */".format(name, bench))
+            count += 1
+
+    # --- Radius ---
+    radius_mods = diff.get("radius", {}).get("modify", [])
+    radius_adds = diff.get("radius", {}).get("add", [])
+
+    if radius_mods or radius_adds:
+        lines.append("")
+        lines.append("  /* ── Border Radius ── */")
+        for item in radius_mods:
+            name = item.get("name", "unknown")
+            bench = _summarize(item.get("benchmark"))
+            current = _summarize(item.get("current"))
+            lines.append("  --radius-{}: {}px;  /* was: {} */".format(
+                name, _extract_px(bench), current
+            ))
+            count += 1
+
+        for item in radius_adds:
+            name = item.get("name", "unknown")
+            bench = _summarize(item.get("benchmark"))
+            lines.append("  --radius-{}: {}px;  /* NEW */".format(name, _extract_px(bench)))
+            count += 1
+
+    # --- Shadows ---
+    shadow_mods = diff.get("shadows", {}).get("modify", [])
+    shadow_adds = diff.get("shadows", {}).get("add", [])
+
+    if shadow_mods or shadow_adds:
+        lines.append("")
+        lines.append("  /* ── Shadows ── */")
+        for item in shadow_mods:
+            name = item.get("name", "unknown")
+            bench = _summarize(item.get("benchmark"))
+            current = _summarize(item.get("current"))
+            lines.append("  --shadow-{}: {};  /* was: {} */".format(name, bench, current))
+            count += 1
+
+        for item in shadow_adds:
+            name = item.get("name", "unknown")
+            bench = _summarize(item.get("benchmark"))
+            lines.append("  --shadow-{}: {};  /* NEW */".format(name, bench))
+            count += 1
+
+    if not lines:
+        return "", 0
+
+    css = ":root {\n" + "\n".join(lines) + "\n}"
+    return css, count
+
+
+# ---------------------------------------------------------------------------
+# 3. Phase 2: Component Modifications
+# ---------------------------------------------------------------------------
+
+def generate_phase2_components(diff: dict) -> tuple[list[dict], int]:
+    """
+    Generate component-level modification instructions.
+    Returns (list of component change dicts, change_count).
+    """
+    changes = []
+    count = 0
+
+    # Typography changes
+    typo_mods = diff.get("typography", {}).get("modify", [])
+    for item in typo_mods:
+        name = item.get("name", "")
+        diffs = item.get("diffs", {})
+        instructions = []
+
+        for field, vals in diffs.items():
+            bench = vals.get("benchmark", "")
+            current = vals.get("current", "")
+            if field == "size":
+                instructions.append("Change `text-{}` → `text-{}`".format(current, bench))
+            elif field == "weight":
+                weight_map = {
+                    "100": "thin", "200": "extralight", "300": "light",
+                    "400": "normal", "500": "medium", "510": "[510]",
+                    "590": "[590]", "600": "semibold", "700": "bold",
+                    "800": "extrabold", "900": "black",
+                }
+                b_tw = weight_map.get(str(bench), "[{}]".format(bench))
+                s_tw = weight_map.get(str(current), "[{}]".format(current))
+                instructions.append("Change `font-{}` → `font-{}`".format(s_tw, b_tw))
+            elif field == "family":
+                instructions.append("Update font-family from `{}` → `{}`".format(current, bench))
+            elif field == "lineHeight":
+                instructions.append("Update line-height from `{}` → `{}`".format(current, bench))
+            elif field == "letterSpacing":
+                instructions.append("Update letter-spacing from `{}` → `{}`".format(current, bench))
+            else:
+                instructions.append("Update {} from `{}` → `{}`".format(field, current, bench))
+
+        if instructions:
+            changes.append({
+                "component": "Typography / {}".format(name),
+                "instructions": instructions,
+            })
+            count += len(instructions)
+
+    # Spacing changes
+    spacing_mods = diff.get("spacing", {}).get("modify", [])
+    for item in spacing_mods:
+        name = item.get("name", "")
+        bench = _summarize(item.get("benchmark"))
+        current = _summarize(item.get("current"))
+        changes.append({
+            "component": "Spacing / {}".format(name),
+            "instructions": [
+                "Change spacing from `{}` → `{}` (Tailwind units)".format(current, bench),
+            ],
+        })
+        count += 1
+
+    # Component-level changes
+    comp_mods = diff.get("components", {}).get("modify", [])
+    for item in comp_mods:
+        name = item.get("name", "")
+        diffs = item.get("diffs", {})
+        instructions = []
+
+        if isinstance(diffs, dict):
+            for field, vals in diffs.items():
+                if isinstance(vals, dict) and "benchmark" in vals:
+                    bench = _summarize(vals.get("benchmark"))
+                    current = _summarize(vals.get("current"))
+                    instructions.append("Update `{}`: `{}` → `{}`".format(field, current, bench))
+                else:
+                    instructions.append("Update `{}`: {}".format(field, _summarize(vals)))
+
+        if instructions:
+            changes.append({
+                "component": "Component / {}".format(name),
+                "instructions": instructions,
+            })
+            count += len(instructions)
+
+    # Component additions
+    comp_adds = diff.get("components", {}).get("add", [])
+    for item in comp_adds:
+        name = item.get("name", "")
+        bench = item.get("benchmark", "")
+        changes.append({
+            "component": "Component / {} (NEW)".format(name),
+            "instructions": [
+                "Create new component styling based on benchmark: {}".format(
+                    _summarize(bench)
+                ),
+            ],
+        })
+        count += 1
+
+    return changes, count
+
+
+# ---------------------------------------------------------------------------
+# 4. Phase 3: Layout Changes
+# ---------------------------------------------------------------------------
+
+def generate_phase3_layout(diff: dict) -> tuple[list[dict], int]:
+    """
+    Generate layout-level structural change instructions.
+    Returns (list of layout change dicts, change_count).
+    """
+    changes = []
+    count = 0
+
+    layout_mods = diff.get("layout", {}).get("modify", [])
+    for item in layout_mods:
+        name = item.get("name", "")
+        bench = _summarize(item.get("benchmark"))
+        current = _summarize(item.get("current"))
+        changes.append({
+            "property": name,
+            "from": current,
+            "to": bench,
+            "risk": "HIGH" if name in ("maxWidth", "gridColumns") else "MEDIUM",
+            "note": "Structural change — requires visual regression testing",
+        })
+        count += 1
+
+    layout_adds = diff.get("layout", {}).get("add", [])
+    for item in layout_adds:
+        name = item.get("name", "")
+        bench = _summarize(item.get("benchmark"))
+        changes.append({
+            "property": name,
+            "from": "(none)",
+            "to": bench,
+            "risk": "HIGH",
+            "note": "New layout constraint — verify across breakpoints",
+        })
+        count += 1
+
+    return changes, count
+
+
+# ---------------------------------------------------------------------------
+# 5. Conflict resolution
+# ---------------------------------------------------------------------------
+
+def generate_conflict_section(diff: dict) -> list[dict]:
+    """Generate conflict resolution proposals."""
+    conflicts = diff.get("conflicts", [])
+    resolutions = []
+
+    for c in conflicts:
+        rule_id = c.get("ruleId", "")
+        rule = c.get("rule", "")
+        bench_val = c.get("benchmarkValue", "")
+        component = c.get("component", "")
+        resolution = c.get("resolution", "")
+
+        resolutions.append({
+            "ruleId": rule_id,
+            "rule": rule,
+            "benchmarkValue": bench_val,
+            "component": component,
+            "proposedChange": resolution,
+            "file": "FRONTEND_CONSISTENCY.md",
+        })
+
+    return resolutions
+
+
+# ---------------------------------------------------------------------------
+# 6. Effort estimation
+# ---------------------------------------------------------------------------
+
+def estimate_effort(diff: dict) -> dict:
+    """Calculate effort estimation from the diff."""
+    total_points = 0
+    breakdown = {}
+
+    for category, weight in COMPLEXITY_WEIGHTS.items():
+        cat_data = diff.get(category, {})
+        if isinstance(cat_data, dict):
+            mod_count = len(cat_data.get("modify", []))
+            add_count = len(cat_data.get("add", []))
+            change_count = mod_count + add_count
+            points = change_count * weight
+            if change_count > 0:
+                breakdown[category] = {
+                    "changes": change_count,
+                    "weight": weight,
+                    "points": points,
+                }
+            total_points += points
+
+    conflict_count = len(diff.get("conflicts", []))
+    if conflict_count > 0:
+        conflict_points = conflict_count * 2  # Conflicts need discussion/decision
+        breakdown["conflicts"] = {
+            "changes": conflict_count,
+            "weight": 2,
+            "points": conflict_points,
+        }
+        total_points += conflict_points
+
+    return {
+        "totalPoints": total_points,
+        "label": effort_label(total_points),
+        "breakdown": breakdown,
+    }
+
+
+# ---------------------------------------------------------------------------
+# 7. Markdown generation
+# ---------------------------------------------------------------------------
+
+def render_markdown(diff: dict) -> str:
+    """Render the full migration plan as markdown."""
+    summary = diff.get("summary", {})
+    today = date.today().isoformat()
+
+    parts = []
+
+    # Header
+    parts.append("# UI Mirror — Migration Plan")
+    parts.append("")
+    parts.append("> Generated: {}".format(today))
+    parts.append("> Tokens compared: {} | Match: {} | Modify: {} | Add: {} | Conflicts: {}".format(
+        summary.get("total", 0),
+        summary.get("match", 0),
+        summary.get("modify", 0),
+        summary.get("add", 0),
+        summary.get("conflicts", 0),
+    ))
+    parts.append("")
+    parts.append("---")
+    parts.append("")
+
+    # Effort estimation
+    effort = estimate_effort(diff)
+    parts.append("## Effort Estimation")
+    parts.append("")
+    parts.append("**Total: {} ({} points)**".format(effort["label"], effort["totalPoints"]))
+    parts.append("")
+    if effort["breakdown"]:
+        parts.append("| Category | Changes | Weight | Points |")
+        parts.append("|----------|---------|--------|--------|")
+        for cat, info in effort["breakdown"].items():
+            parts.append("| {} | {} | x{} | {} |".format(
+                cat, info["changes"], info["weight"], info["points"]
+            ))
+    parts.append("")
+    parts.append("---")
+    parts.append("")
+
+    # Phase 1: CSS Token Overrides
+    css_block, css_count = generate_phase1_css(diff)
+    parts.append("## Phase 1 — CSS Token Overrides")
+    parts.append("")
+    parts.append("> **Risk: LOW** | **Impact: HIGH** | Changes: {}".format(css_count))
+    parts.append(">")
+    parts.append("> Update `:root` variables in `src/app/globals.css`. No component code changes needed.")
+    parts.append("")
+
+    if css_block:
+        parts.append("```css")
+        parts.append(css_block)
+        parts.append("```")
+    else:
+        parts.append("*No CSS token overrides needed — all tokens match.*")
+    parts.append("")
+    parts.append("---")
+    parts.append("")
+
+    # Phase 2: Component Modifications
+    component_changes, comp_count = generate_phase2_components(diff)
+    parts.append("## Phase 2 — Component Modifications")
+    parts.append("")
+    parts.append("> **Risk: MEDIUM** | Changes: {}".format(comp_count))
+    parts.append(">")
+    parts.append("> Per-component Tailwind class and style updates.")
+    parts.append("")
+
+    if component_changes:
+        for change in component_changes:
+            parts.append("### {}".format(change["component"]))
+            parts.append("")
+            for instruction in change.get("instructions", []):
+                parts.append("- {}".format(instruction))
+            parts.append("")
+    else:
+        parts.append("*No component modifications needed.*")
+        parts.append("")
+
+    parts.append("---")
+    parts.append("")
+
+    # Phase 3: Layout Changes
+    layout_changes, layout_count = generate_phase3_layout(diff)
+    parts.append("## Phase 3 — Layout Changes")
+    parts.append("")
+    parts.append("> **Risk: HIGH** | Changes: {}".format(layout_count))
+    parts.append(">")
+    parts.append("> Structural grid/spacing/max-width changes. Requires careful visual regression testing.")
+    parts.append("")
+
+    if layout_changes:
+        parts.append("| Property | From | To | Risk | Note |")
+        parts.append("|----------|------|----|------|------|")
+        for lc in layout_changes:
+            parts.append("| {} | {} | {} | {} | {} |".format(
+                lc["property"], lc["from"], lc["to"], lc["risk"], lc["note"]
+            ))
+        parts.append("")
+        parts.append("**Testing checklist:**")
+        parts.append("- [ ] Desktop (1440px+)")
+        parts.append("- [ ] Laptop (1024px)")
+        parts.append("- [ ] Tablet (768px)")
+        parts.append("- [ ] Mobile (375px)")
+        parts.append("")
+    else:
+        parts.append("*No layout changes needed.*")
+        parts.append("")
+
+    parts.append("---")
+    parts.append("")
+
+    # Conflict Resolution
+    resolutions = generate_conflict_section(diff)
+    parts.append("## Conflict Resolution")
+    parts.append("")
+
+    if resolutions:
+        parts.append("> {} conflict(s) detected between benchmark design and FRONTEND_CONSISTENCY.md rules.".format(
+            len(resolutions)
+        ))
+        parts.append("")
+
+        for res in resolutions:
+            parts.append("### {} — {}".format(res["ruleId"], res["rule"]))
+            parts.append("")
+            parts.append("- **Benchmark value**: `{}`".format(res["benchmarkValue"]))
+            if res.get("component"):
+                parts.append("- **Component**: `{}`".format(res["component"]))
+            parts.append("- **Proposed change**: {}".format(res["proposedChange"]))
+            parts.append("- **File**: `{}`".format(res["file"]))
+            parts.append("")
+    else:
+        parts.append("*No conflicts detected.*")
+        parts.append("")
+
+    parts.append("---")
+    parts.append("")
+
+    # Summary of matched tokens (brief)
+    parts.append("## Matched Tokens (no action needed)")
+    parts.append("")
+    match_count = summary.get("match", 0)
+    if match_count > 0:
+        parts.append("{} tokens already match the benchmark. No changes required for these.".format(match_count))
+        parts.append("")
+
+        # List matched categories briefly
+        for cat in ["colors", "typography", "spacing", "radius", "shadows", "components", "layout"]:
+            cat_data = diff.get(cat, {})
+            matches = cat_data.get("match", []) if isinstance(cat_data, dict) else []
+            if matches:
+                names = [m.get("name", "?") for m in matches]
+                parts.append("- **{}**: {}".format(cat, ", ".join(names)))
+        parts.append("")
+    else:
+        parts.append("*No tokens matched. Full migration required.*")
+        parts.append("")
+
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# 8. Helpers
+# ---------------------------------------------------------------------------
+
+def _summarize(v) -> str:
+    """Produce a compact string summary of a token value."""
+    if v is None:
+        return "(none)"
+    if isinstance(v, str):
+        return v
+    if isinstance(v, (int, float)):
+        return str(v)
+    if isinstance(v, dict):
+        if "oklch" in v:
+            return str(v["oklch"])
+        if "px" in v and v["px"] is not None:
+            return "{}px".format(v["px"])
+        if "tailwind" in v:
+            return str(v["tailwind"])
+        # Compact JSON
+        return json.dumps(v, ensure_ascii=False)
+    if isinstance(v, list):
+        return json.dumps(v, ensure_ascii=False)
+    return str(v)
+
+
+def _extract_px(s: str) -> str:
+    """Extract numeric px value from a string, or return the string as-is."""
+    # Handle Tailwind size names that may arrive from _summarize
+    tw_to_px = {
+        "none": "0", "sm": "2", "DEFAULT": "4", "md": "6",
+        "lg": "8", "xl": "12", "2xl": "16", "3xl": "24", "full": "9999",
+    }
+    s_str = str(s).strip()
+    if s_str in tw_to_px:
+        return tw_to_px[s_str]
+    m = re.search(r"([\d.]+)", s_str)
+    return m.group(1) if m else s_str
+
+
+# ---------------------------------------------------------------------------
+# 9. Entry point
+# ---------------------------------------------------------------------------
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: {} <token_diff.json>".format(sys.argv[0]), file=sys.stderr)
+        print("  Transforms a token diff into a prioritized markdown migration plan.", file=sys.stderr)
+        sys.exit(1)
+
+    diff_path = sys.argv[1]
+
+    try:
+        with open(diff_path, "r", encoding="utf-8") as f:
+            diff = json.load(f)
+    except FileNotFoundError:
+        print("Error: File not found: {}".format(diff_path), file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print("Error: Invalid JSON in {}: {}".format(diff_path, e), file=sys.stderr)
+        sys.exit(1)
+
+    if not isinstance(diff, dict):
+        print("Error: Expected top-level JSON object, got {}".format(type(diff).__name__), file=sys.stderr)
+        sys.exit(1)
+
+    markdown = render_markdown(diff)
+    print(markdown)
+
+
+if __name__ == "__main__":
+    main()