@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.1

package/pipeline/skills/figma-ios/figma-to-component/scripts/phase3-scripts.py

@@ -1,1089 +0,0 @@
-#!/usr/bin/env python3
-"""Phase 3 scriptable sub-phases: 3B (tokens), 3E (assets), 3F (utilities), 3G (coverage).
-
-Usage:
-    python3 phase3-scripts.py 3b --artifact-path /path/to/artifacts
-    python3 phase3-scripts.py 3e --artifact-path /path/to/artifacts
-    python3 phase3-scripts.py 3f --artifact-path /path/to/artifacts
-    python3 phase3-scripts.py 3g --artifact-path /path/to/artifacts
-    python3 phase3-scripts.py wave1 --artifact-path /path/to/artifacts  # runs 3b+3e+3f
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-import subprocess
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Optional
-
-# --- Constants ---
-
-SCRIPT_DIR = Path(__file__).parent
-REPO_ROOT = SCRIPT_DIR.parent.parent.parent.parent  # .instructions/figma/figma-to-swiftui/scripts -> repo root
-CONFIG_PKG = REPO_ROOT / "{repos.packagesContainer}" / "Packages" / "{project.slug}-common"
-CLI_BINARY = CONFIG_PKG / ".build" / "debug" / "FigmaRegistryUtility"
-ASSET_CATALOG_ROOT = CONFIG_PKG / "iOS" / "Sources" / "UIAssets" / "Generated" / "Resources" / "Images"
-
-ISO_DATE = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-DATE_SHORT = datetime.now(timezone.utc).strftime("%Y-%m-%d")
-
-
-# --- CLI helpers ---
-
-def run_cli(command: str, args: list[str]) -> dict | None:
-    """Run FigmaRegistryUtility command from config package dir."""
-    cmd = [str(CLI_BINARY), command] + args
-    try:
-        result = subprocess.run(
-            cmd, capture_output=True, text=True, timeout=30,
-            cwd=str(CONFIG_PKG)
-        )
-        if result.returncode == 0 and result.stdout.strip():
-            return json.loads(result.stdout)
-    except (subprocess.TimeoutExpired, json.JSONDecodeError, FileNotFoundError) as e:
-        print(f"  [warn] CLI {command} failed: {e}", file=sys.stderr)
-    return None
-
-
-def ensure_cli():
-    """Build CLI if binary doesn't exist."""
-    if not CLI_BINARY.exists():
-        print("  Building FigmaRegistryUtility...", file=sys.stderr)
-        subprocess.run(
-            ["swift", "build", "--product", "FigmaRegistryUtility"],
-            cwd=str(CONFIG_PKG), capture_output=True, timeout=120
-        )
-
-
-# --- 3B: Token Mapping ---
-
-def classify_variable(name: str, value: str) -> str | None:
-    """Classify a variable_defs entry by type."""
-    if value.startswith("#") and len(value) in (4, 7, 9):
-        return "color"
-    if value.startswith("Font("):
-        return "typography_composite"
-    if name.startswith("Font/") or name.startswith("[TBD]Font/"):
-        return "font_primitive"
-    if name.startswith("Spacing/"):
-        return "spacing"
-    if name.startswith("Radius/"):
-        return "radius"
-    # Try to parse as number
-    try:
-        float(value)
-        return "number"
-    except ValueError:
-        pass
-    # String values (font family names etc)
-    if not value.startswith("{") and not value.startswith("["):
-        return "font_family"
-    return None
-
-
-def run_3b(artifact_path: str) -> bool:
-    """Phase 3B: Variable Token Mapping."""
-    print("Phase 3B: Token Mapping")
-    ap = Path(artifact_path)
-
-    # Read inputs
-    var_defs_path = ap / "pass1" / "variable_defs_response.json"
-    if not var_defs_path.exists():
-        print("  [error] variable_defs_response.json not found", file=sys.stderr)
-        return False
-
-    with open(var_defs_path) as f:
-        var_defs = json.load(f)
-
-    # Get component name from component_properties.json
-    comp_name = "(from artifacts)"
-    comp_props_path = ap / "pass1" / "component_properties.json"
-    if comp_props_path.exists():
-        with open(comp_props_path) as f:
-            comp_name = json.load(f).get("componentName", comp_name)
-
-    # Classify variables
-    colors, spacings, radii, font_prims, typo_composites, font_families = [], [], [], [], [], []
-    lookup_vars = []
-
-    for name, value in var_defs.items():
-        vtype = classify_variable(name, value)
-        if vtype == "color":
-            colors.append(name)
-            lookup_vars.append(name)
-        elif vtype == "spacing":
-            spacings.append(name)
-            lookup_vars.append(name)
-        elif vtype == "radius":
-            radii.append(name)
-            lookup_vars.append(name)
-        elif vtype == "number":
-            lookup_vars.append(name)
-        elif vtype == "typography_composite":
-            typo_composites.append(name)
-        elif vtype == "font_primitive":
-            font_prims.append(name)
-            lookup_vars.append(name)
-        elif vtype == "font_family":
-            font_families.append(name)
-
-    # Batch CLI lookup for all non-composite variables
-    token_map = {}
-    if lookup_vars:
-        result = run_cli("ui-token-lookup", ["--variables", ",".join(lookup_vars), "--json"])
-        if result:
-            token_map = result
-
-    # Typography lookup for composite styles  -  pass the raw Figma variable names
-    # through untransformed. Resolution is the CLI's job, not ours.
-    typo_map = {}
-    if typo_composites:
-        result = run_cli("typography-lookup", ["--styles", ",".join(typo_composites), "--json"])
-        if result:
-            typo_map = result
-
-    # Build output sections
-    lines = [
-        f"# Token Mapping\n",
-        f"Component: {comp_name}",
-        f"Generated: {ISO_DATE}",
-        f"Source: pass1/variable_defs_response.json, pass1/design_context_response.json\n",
-    ]
-
-    # Typography section
-    lines.append("## Typography\n")
-    typo_count = 0
-    lines.append("| Figma Style | Token Type | Swift Modifier | Swift Font |")
-    lines.append("|-------------|------------|----------------|------------|")
-    for tc_name in typo_composites:
-        entry = typo_map.get(tc_name)
-        if entry and entry.get("status") == "found":
-            swift_token = entry["swiftToken"]  # e.g. ".smallBold"
-            lines.append(f"| {tc_name} | typography | `.typographyStyle({swift_token})` | `Font{swift_token}` |")
-            typo_count += 1
-        else:
-            lines.append(f"| {tc_name} | typography | ⚠️ not found | ⚠️ not found |")
-    if not typo_composites:
-        lines.append("| (none) |  -  |  -  |  -  |")
-    lines.append("")
-
-    # Colors section
-    lines.append("## Colors\n")
-    lines.append("| Figma Variable | Token Type | Swift Usage |")
-    lines.append("|----------------|------------|-------------|")
-    color_count = 0
-    for var_name in colors:
-        token = token_map.get(var_name)
-        if token:
-            # token format: "color:.Text.textSuccess"
-            type_prefix, swift_path = token.split(":", 1)
-            lines.append(f"| {var_name} | {type_prefix} | `Color{swift_path}` |")
-            color_count += 1
-        else:
-            lines.append(f"| {var_name} | color | ⚠️ not found |")
-    if not colors:
-        lines.append("| (none) |  -  |  -  |")
-    lines.append("")
-
-    # Spacing section
-    lines.append("## Spacing\n")
-    lines.append("| Figma Variable | Token Type | Swift Token |")
-    lines.append("|----------------|------------|-------------|")
-    spacing_count = 0
-    for var_name in spacings:
-        token = token_map.get(var_name)
-        if token:
-            type_prefix, swift_path = token.split(":", 1)
-            lines.append(f"| {var_name} | {type_prefix} | `{swift_path}` |")
-            spacing_count += 1
-        else:
-            lines.append(f"| {var_name} | number | ⚠️ not found |")
-    if not spacings:
-        lines.append("| (none) |  -  |  -  |")
-    lines.append("")
-
-    # Radius section
-    lines.append("## Radius\n")
-    lines.append("| Figma Variable | Token Type | Swift Token |")
-    lines.append("|----------------|------------|-------------|")
-    radius_count = 0
-    for var_name in radii:
-        token = token_map.get(var_name)
-        if token:
-            type_prefix, swift_path = token.split(":", 1)
-            lines.append(f"| {var_name} | {type_prefix} | `{swift_path}` |")
-            radius_count += 1
-        else:
-            lines.append(f"| {var_name} | number | ⚠️ not found |")
-    if not radii:
-        lines.append("| (none) |  -  |  -  |")
-    lines.append("")
-
-    # Images section
-    lines.append("## Images / Icons\n")
-    lines.append("None detected in variable definitions.\n")
-
-    # Font primitives section
-    if font_prims:
-        lines.append("## Font Primitives (Sub-tokens)\n")
-        lines.append("These are typography sub-properties. Not used directly  -  encapsulated by composite typography tokens above.\n")
-        lines.append("| Figma Variable | Token Type | Swift Token | Note |")
-        lines.append("|----------------|------------|-------------|------|")
-        for var_name in font_prims:
-            token = token_map.get(var_name)
-            if token:
-                type_prefix, swift_path = token.split(":", 1)
-                lines.append(f"| {var_name} | {type_prefix} | `{swift_path}` | Font primitive (use composite token instead) |")
-            else:
-                lines.append(f"| {var_name} |  -  | N/A | Font primitive  -  not a standalone token |")
-        lines.append("")
-
-    # Font families
-    if font_families:
-        lines.append("## Font Families\n")
-        for name in font_families:
-            lines.append(f"- `{name}`: \"{var_defs[name]}\"  -  font family reference, not a standalone token\n")
-
-    # Missing tokens  -  exclude font primitives and font families (encapsulated by composite)
-    missing = []
-    for var_name in lookup_vars:
-        token = token_map.get(var_name)
-        if token is None:
-            vtype = classify_variable(var_name, var_defs[var_name])
-            # Font family refs and font primitives are encapsulated by composite typography
-            if vtype in ("font_family", "font_primitive"):
-                continue
-            missing.append((var_name, vtype or "unknown"))
-    for tc_name in typo_composites:
-        entry = typo_map.get(tc_name)
-        if not entry or entry.get("status") != "found":
-            missing.append((tc_name, "typography"))
-
-    # Font primitives/families that returned null are NOT missing  -  they're encapsulated
-    font_null_note = []
-    for var_name in lookup_vars:
-        token = token_map.get(var_name)
-        if token is None:
-            vtype = classify_variable(var_name, var_defs[var_name])
-            if vtype in ("font_family", "font_primitive"):
-                font_null_note.append((var_name, vtype))
-
-    lines.append("## Missing Tokens\n")
-    if missing:
-        lines.append("| Token | Type | Resolution |")
-        lines.append("|-------|------|------------|")
-        for name, ttype in missing:
-            lines.append(f"| {name} | {ttype} | See reference/missing-tokens.md |")
-    else:
-        if font_null_note:
-            lines.append(f"All tokens resolved. ({len(font_null_note)} font primitive/family references excluded  -  encapsulated by composite typography token.)\n")
-        else:
-            lines.append("All tokens resolved.\n")
-
-    # Summary
-    mapped_prims = sum(1 for v in font_prims if token_map.get(v) is not None)
-    actionable_missing = [m for m in missing if m[1] != "font_family"]
-
-    lines.append("## Summary\n")
-    lines.append(f"- Typography: {typo_count} mapped")
-    lines.append(f"- Colors: {color_count} mapped")
-    lines.append(f"- Spacing: {spacing_count} mapped")
-    lines.append(f"- Radius: {radius_count} mapped")
-    lines.append(f"- Images: 0 mapped")
-    if font_prims:
-        lines.append(f"- Font Primitives: {mapped_prims} mapped (sub-tokens of typography)")
-    lines.append(f"- Missing: {len(actionable_missing)} actionable")
-
-    # Write
-    os.makedirs(ap / "pass3", exist_ok=True)
-    out_path = ap / "pass3" / "02_token_mapping.md"
-    with open(out_path, "w") as f:
-        f.write("\n".join(lines) + "\n")
-
-    print(f"  ✅ {out_path} ({typo_count + color_count + spacing_count + radius_count} tokens mapped, {len(actionable_missing)} missing)")
-    return True
-
-
-# --- 3E: Asset Inventory ---
-
-def parse_asset_filename(filename: str) -> str:
-    """Try to identify an asset from its filename (hash or named)."""
-    # Strip extension
-    stem = Path(filename).stem
-    # If it's a hex hash, we need to inspect SVG content or check code_connect_map
-    if re.match(r'^[a-f0-9]{30,}$', stem):
-        return stem  # hash-named, needs further resolution
-    return stem
-
-
-def run_3e(artifact_path: str) -> bool:
-    """Phase 3E: Asset Inventory."""
-    print("Phase 3E: Asset Inventory")
-    ap = Path(artifact_path)
-
-    assets_txt = ap / "pass1" / "design_context_assets.txt"
-    if not assets_txt.exists() or assets_txt.stat().st_size == 0:
-        # Write placeholder
-        os.makedirs(ap / "pass3", exist_ok=True)
-        out_path = ap / "pass3" / "06_assets.md"
-        with open(out_path, "w") as f:
-            f.write(f"# Asset Inventory\n\nNo downloadable assets found for this component.\nGenerated: {ISO_DATE}\n")
-        print(f"  ⏭️  No assets  -  placeholder written")
-        return True
-
-    # Parse asset entries
-    assets = []
-    with open(assets_txt) as f:
-        for line in f:
-            line = line.strip()
-            if not line or line.startswith("#"):
-                continue
-            # Format: "filename | url" or "filename | local:path"
-            parts = line.split("|", 1)
-            filename = parts[0].strip()
-            url = parts[1].strip() if len(parts) > 1 else ""
-            assets.append({"filename": filename, "url": url})
-
-    if not assets:
-        os.makedirs(ap / "pass3", exist_ok=True)
-        out_path = ap / "pass3" / "06_assets.md"
-        with open(out_path, "w") as f:
-            f.write(f"# Asset Inventory\n\nNo downloadable assets found for this component.\nGenerated: {ISO_DATE}\n")
-        print(f"  ⏭️  No assets  -  placeholder written")
-        return True
-
-    # Try to identify assets via code_connect_map (for icon names)
-    # Icon entries have snippet like "Image.plusCircle" with empty source
-    icon_names = set()
-    ccm_path = ap / "pass1" / "code_connect_map_response.json"
-    if ccm_path.exists():
-        with open(ccm_path) as f:
-            ccm = json.load(f)
-        for entry in ccm.values():
-            # Check componentName field
-            name = entry.get("componentName", "")
-            if name.startswith("Image."):
-                icon_names.add(name.replace("Image.", ""))
-            # Also check snippet field for "Image.xxx" patterns (icon entries use this)
-            snippet = entry.get("snippet", "")
-            m = re.match(r'^Image\.(\w+)$', snippet.strip())
-            if m:
-                icon_names.add(m.group(1))
-
-    # Check each asset against registry and catalog
-    results = []
-    for asset in assets:
-        filename = asset["filename"]
-        stem = parse_asset_filename(filename)
-        ext = Path(filename).suffix.lstrip(".")
-
-        # Check SVG content for icon identification (if local file exists)
-        local_path = asset["url"].replace("local:", "") if asset["url"].startswith("local:") else None
-        svg_identified_name = None
-
-        # Try registry lookup for known icon names from code_connect_map
-        status = "Unknown"
-        target = "N/A"
-        identified_name = stem
-        swift_accessor = None
-
-        for icon_name in icon_names:
-            lookup = run_cli("ui-token-lookup", ["--variables", icon_name, "--json"])
-            if lookup:
-                val = lookup.get(icon_name)
-                if val and val.startswith("image:"):
-                    swift_path = val.split(":", 1)[1]
-                    identified_name = icon_name
-                    swift_accessor = f"Image{swift_path}"
-                    status = "Existing"
-                    break
-
-        # Also search asset catalog directly if hash-named
-        if status == "Unknown" and re.match(r'^[a-f0-9]{30,}$', stem):
-            # Check if any icon from code_connect_map exists in catalog
-            for icon_name in icon_names:
-                # Convert camelCase to kebab-case for catalog search
-                kebab = re.sub(r'([A-Z])', r'-\1', icon_name).lower().lstrip("-")
-                matches = list(ASSET_CATALOG_ROOT.rglob(f"*{kebab}*")) if ASSET_CATALOG_ROOT.exists() else []
-                if matches:
-                    identified_name = kebab
-                    status = "Existing"
-                    target = str(matches[0].relative_to(CONFIG_PKG))
-                    break
-
-        results.append({
-            "filename": filename,
-            "ext": ext,
-            "identified_name": identified_name,
-            "status": status,
-            "target": target,
-            "swift_accessor": swift_accessor,
-        })
-
-    # Write output
-    new_count = sum(1 for r in results if r["status"] == "New")
-    existing_count = sum(1 for r in results if r["status"] == "Existing")
-    unknown_count = sum(1 for r in results if r["status"] == "Unknown")
-
-    lines = [
-        f"# Asset Inventory\n",
-        f"Generated: {ISO_DATE}",
-        f"Source: pass1/design_context_assets.txt\n",
-        "## Assets\n",
-        "| File | Type | Identified As | Status | Swift Accessor |",
-        "|------|------|---------------|--------|----------------|",
-    ]
-
-    for r in results:
-        accessor = r["swift_accessor"] or " - "
-        lines.append(f"| {r['filename']} | {r['ext']} | {r['identified_name']} | {r['status']} | `{accessor}` |" if r["swift_accessor"] else
-                     f"| {r['filename']} | {r['ext']} | {r['identified_name']} | {r['status']} |  -  |")
-
-    lines.extend([
-        "",
-        "## Summary\n",
-        f"- Total assets: {len(results)}",
-        f"- New (to add): {new_count}",
-        f"- Existing (no action): {existing_count}",
-        f"- Unknown (check manually): {unknown_count}",
-    ])
-
-    if new_count > 0:
-        lines.extend(["", "## Action Items\n"])
-        for r in results:
-            if r["status"] == "New":
-                lines.append(f"- [ ] Add `{r['identified_name']}` to asset catalog")
-
-    if new_count == 0:
-        lines.extend(["", "## Action Items\n", "No new assets need to be added."])
-
-    os.makedirs(ap / "pass3", exist_ok=True)
-    out_path = ap / "pass3" / "06_assets.md"
-    with open(out_path, "w") as f:
-        f.write("\n".join(lines) + "\n")
-
-    print(f"  ✅ {out_path} ({new_count} new, {existing_count} existing, {unknown_count} unknown)")
-    return True
-
-
-# --- 3F: Utility Integration ---
-
-def run_3f(artifact_path: str) -> bool:
-    """Phase 3F: Utility Integration Summary."""
-    print("Phase 3F: Utility Integration")
-    ap = Path(artifact_path)
-
-    # Primary source: component-utilities.json (structured, from Phase 2)
-    utils_json = ap / "pass2" / "component-utilities.json"
-    if not utils_json.exists():
-        print(f"  [error] pass2/component-utilities.json not found", file=sys.stderr)
-        return False
-
-    with open(utils_json) as f:
-        utils = json.load(f)
-
-    component_name = utils.get("componentName", "Unknown")
-    if isinstance(component_name, dict):
-        component_name = component_name.get("ios", "Unknown")
-
-    testing_ids = utils.get("testingIdentifiers", [])
-    loc_keys = utils.get("localizationKeys", [])
-    a11y_keys = utils.get("accessibilityKeys", [])
-    analytics = utils.get("analyticsEvents", [])
-
-    # Build element-to-utility mapping table
-    # Collect all unique elements from all utility categories
-    elements = {}  # element_name -> {testing, localization, accessibility, analytics}
-
-    for tid in testing_ids:
-        key = tid.get("key", "")
-        elem = tid.get("usage", key.split(".")[-1] if "." in key else key)
-        if elem not in elements:
-            elements[elem] = {"testing": None, "localization": None, "accessibility": None, "analytics": None}
-        elements[elem]["testing"] = f"`.{key}`"
-
-    for lk in loc_keys:
-        key = lk.get("key", "")
-        elem = lk.get("usage", key.split(".")[-1] if "." in key else key)
-        if elem not in elements:
-            elements[elem] = {"testing": None, "localization": None, "accessibility": None, "analytics": None}
-        elements[elem]["localization"] = f"`.{key}`"
-
-    for ak in a11y_keys:
-        key = ak.get("key", "")
-        elem = ak.get("usage", ak.get("purpose", key.split(".")[-1] if "." in key else key))
-        if elem not in elements:
-            elements[elem] = {"testing": None, "localization": None, "accessibility": None, "analytics": None}
-        elements[elem]["accessibility"] = f"`.{key}`"
-
-    for ae in analytics:
-        elem = ae.get("element", "unknown")
-        if elem not in elements:
-            elements[elem] = {"testing": None, "localization": None, "accessibility": None, "analytics": None}
-        elements[elem]["analytics"] = ae.get("event", " - ")
-
-    lines = [
-        f"# Utility Integration\n",
-        f"Component: {component_name}",
-        f"Generated: {ISO_DATE}",
-        f"Source: pass2/component-utilities.json\n",
-    ]
-
-    # Element mapping table
-    if elements:
-        lines.append("## Element-to-Utility Mapping\n")
-        lines.append("| Element | Testing ID | Localization Key | Accessibility | Analytics |")
-        lines.append("|---------|------------|------------------|---------------|-----------|")
-        for elem, utils_map in elements.items():
-            t = utils_map["testing"] or " - "
-            l = utils_map["localization"] or " - "
-            a = utils_map["accessibility"] or " - "
-            an = utils_map["analytics"] or " - "
-            lines.append(f"| {elem} | {t} | {l} | {a} | {an} |")
-        lines.append("")
-
-    # Testing Identifiers
-    lines.append("## Testing Identifiers\n")
-    if testing_ids:
-        lines.append("| Key | Value | Usage |")
-        lines.append("|-----|-------|-------|")
-        for tid in testing_ids:
-            lines.append(f"| {tid.get('key', '')} | {tid.get('value', '')} | `.accessibilityIdentifier(.{tid.get('key', '')})` |")
-    else:
-        lines.append("No testing identifiers.")
-    lines.append("")
-
-    # Localization Keys
-    lines.append("## Localization Keys\n")
-    if loc_keys:
-        lines.append("| Key | Pattern |")
-        lines.append("|-----|---------|")
-        for lk in loc_keys:
-            lines.append(f"| {lk.get('key', '')} | {lk.get('pattern', '')} |")
-    else:
-        lines.append("No localization keys (dynamic text only).")
-    lines.append("")
-
-    # Accessibility
-    lines.append("## Accessibility\n")
-    if a11y_keys:
-        lines.append("| Key | Purpose |")
-        lines.append("|-----|---------|")
-        for ak in a11y_keys:
-            lines.append(f"| {ak.get('key', '')} | {ak.get('purpose', '')} |")
-    else:
-        lines.append("No dedicated keys  -  using runtime accessibility patterns.")
-    lines.append("")
-
-    # Analytics
-    lines.append("## Analytics Events\n")
-    if analytics:
-        lines.append("| Element | Event | Identifier Key |")
-        lines.append("|---------|-------|----------------|")
-        for ae in analytics:
-            lines.append(f"| {ae.get('element', '')} | {ae.get('event', '')} | {ae.get('identifierKey', '')} |")
-    else:
-        lines.append("No analytics events (no interactive elements).")
-    lines.append("")
-
-    # Summary
-    lines.append("## Summary\n")
-    lines.append("| Category | Count |")
-    lines.append("|----------|-------|")
-    lines.append(f"| Testing Identifiers | {len(testing_ids)} |")
-    lines.append(f"| Localization Keys | {len(loc_keys)} |")
-    lines.append(f"| Accessibility Keys | {len(a11y_keys)} |")
-    lines.append(f"| Analytics Events | {len(analytics)} |")
-
-    os.makedirs(ap / "pass3", exist_ok=True)
-    out_path = ap / "pass3" / "08_utility_integration.md"
-    with open(out_path, "w") as f:
-        f.write("\n".join(lines) + "\n")
-
-    print(f"  ✅ {out_path} ({len(testing_ids)} testing, {len(loc_keys)} loc, {len(a11y_keys)} a11y, {len(analytics)} analytics)")
-    return True
-
-
-# --- 3G: Property Coverage ---
-
-def run_3g(artifact_path: str) -> bool:
-    """Phase 3G: Property Coverage Verification."""
-    print("Phase 3G: Property Coverage")
-    ap = Path(artifact_path)
-
-    # Read component_properties.json (Phase 1 output)
-    comp_props_path = ap / "pass1" / "component_properties.json"
-    if not comp_props_path.exists():
-        print(f"  [error] component_properties.json not found", file=sys.stderr)
-        return False
-
-    with open(comp_props_path) as f:
-        comp_props = json.load(f)
-
-    # Read 3D's structured JSON output
-    arch_json_path = ap / "pass3" / "04b_component_architecture.json"
-    if not arch_json_path.exists():
-        print(f"  [error] 04b_component_architecture.json not found (3D must emit this)", file=sys.stderr)
-        return False
-
-    with open(arch_json_path) as f:
-        arch = json.load(f)
-
-    # Extract all Figma properties
-    prop_defs = comp_props.get("componentPropertyDefinitions", {})
-    arch_props = {p["figmaKey"]: p for p in arch.get("properties", [])}
-
-    component_name = comp_props.get("componentName", "Unknown")
-
-    # Match each Figma property against architecture
-    properties = []
-    unmapped = []
-
-    for figma_key, figma_def in prop_defs.items():
-        prop_type = figma_def.get("type", "UNKNOWN")
-        # Clean display name from figma_key (remove #nodeId suffix)
-        display_name = re.sub(r'#\d+:\d+$', '', figma_key).strip()
-        # Remove leading arrow for instance swaps
-        display_name_clean = display_name.lstrip("↪ ").strip()
-
-        if figma_key in arch_props:
-            ap_entry = arch_props[figma_key]
-            properties.append({
-                "name": display_name,
-                "type": prop_type,
-                "figmaKey": figma_key,
-                "status": ap_entry.get("status", "IMPLEMENT"),
-                "swiftType": ap_entry.get("swiftType"),
-                "reason": ap_entry.get("reason"),
-            })
-        else:
-            # Not found in architecture  -  unmapped
-            unmapped.append({
-                "name": display_name,
-                "type": prop_type,
-                "figmaKey": figma_key,
-            })
-
-    # Include LAYER_TEXT entries from architecture (dynamic layer texts not in Figma properties)
-    for arch_prop in arch.get("properties", []):
-        if arch_prop.get("type") == "LAYER_TEXT" and arch_prop.get("status") == "IMPLEMENT":
-            properties.append({
-                "name": arch_prop["name"],
-                "type": "LAYER_TEXT",
-                "figmaKey": None,
-                "status": "IMPLEMENT",
-                "swiftType": arch_prop.get("swiftType"),
-                "reason": None,
-            })
-
-    # Counts
-    implemented = sum(1 for p in properties if p["status"] == "IMPLEMENT")
-    skipped = sum(1 for p in properties if p["status"] == "SKIP")
-    deferred = sum(1 for p in properties if p["status"] == "DEFER")
-    total = len(properties)
-
-    # Validate
-    if unmapped:
-        print(f"  [error] {len(unmapped)} unmapped properties:", file=sys.stderr)
-        for u in unmapped:
-            print(f"    - {u['name']} ({u['type']}): {u['figmaKey']}", file=sys.stderr)
-        # Still write the file but include unmapped
-
-    # Validate SKIP/DEFER have reasons
-    missing_reasons = [p for p in properties if p["status"] in ("SKIP", "DEFER") and not p.get("reason")]
-    if missing_reasons:
-        print(f"  [warn] {len(missing_reasons)} SKIP/DEFER properties missing reasons", file=sys.stderr)
-
-    # Write output
-    output = {
-        "componentName": component_name,
-        "generated": DATE_SHORT,
-        "totalProperties": total,
-        "implemented": implemented,
-        "skipped": skipped,
-        "deferred": deferred,
-        "properties": properties,
-        "unmapped": unmapped,
-    }
-
-    os.makedirs(ap / "pass3", exist_ok=True)
-    out_path = ap / "pass3" / "00_property_coverage.json"
-    with open(out_path, "w") as f:
-        json.dump(output, f, indent=2, ensure_ascii=False)
-
-    status = "✅" if not unmapped else "⚠️"
-    print(f"  {status} {out_path} ({implemented} implement, {skipped} skip, {deferred} defer, {len(unmapped)} unmapped)")
-    return len(unmapped) == 0
-
-
-# --- spec: Implementation Spec Compilation ---
-
-def extract_md_value(filepath: Path, field: str) -> str:
-    """Extract a value from a markdown table row like '| Field | Value |'."""
-    if not filepath.exists():
-        return ""
-    with open(filepath) as f:
-        for line in f:
-            if f"| {field} |" in line or f"| {field.lower()} |" in line.lower():
-                parts = [p.strip() for p in line.split("|")]
-                if len(parts) >= 3:
-                    return parts[2]
-    return ""
-
-
-def extract_md_section_lines(filepath: Path, heading: str) -> list[str]:
-    """Extract lines under a markdown ## heading until next heading."""
-    if not filepath.exists():
-        return []
-    lines = []
-    in_section = False
-    with open(filepath) as f:
-        for line in f:
-            if line.startswith("## ") and heading.lower() in line.lower():
-                in_section = True
-                continue
-            elif line.startswith("## ") and in_section:
-                break
-            elif in_section:
-                lines.append(line.rstrip())
-    return lines
-
-
-def generate_api_shape_code(arch: dict) -> str:
-    """Generate Swift API shape code from architecture JSON."""
-    lines = []
-    lines.append("```swift")
-
-    # Enums
-    for enum in arch.get("enums", []):
-        cases = ", ".join(f".{c}" for c in enum["cases"])
-        lines.append(f"public enum {enum['name']}: String, CaseIterable, Sendable {{")
-        for case in enum["cases"]:
-            lines.append(f"    case {case}")
-        lines.append("}")
-        lines.append("")
-
-    # Configuration struct (if COMPLEX)
-    api = arch.get("apiDesign", {})
-    config = api.get("configurationStruct")
-    if config:
-        lines.append(f"public struct {config['name']}: Sendable {{")
-        for prop in config.get("properties", []):
-            lines.append(f"    public let {prop['name']}: {prop['swiftType']}")
-        lines.append("")
-        # Init
-        init_params = []
-        for prop in config.get("properties", []):
-            default = prop.get("default")
-            if default:
-                init_params.append(f"        {prop['name']}: {prop['swiftType']} = {default}")
-            else:
-                init_params.append(f"        {prop['name']}: {prop['swiftType']}")
-        lines.append("    public init(")
-        lines.append(",\n".join(init_params))
-        lines.append("    ) { ... }")
-        lines.append("}")
-        lines.append("")
-
-    # Component struct
-    comp = api.get("componentStruct", {})
-    comp_name = comp.get("name", arch.get("componentName", "Component"))
-    lines.append(f"public struct {comp_name}: View {{")
-    if config:
-        lines.append(f"    private let configuration: {config['name']}")
-        lines.append("")
-        lines.append(f"    public init(configuration: {config['name']}) {{")
-        lines.append("        self.configuration = configuration")
-        lines.append("    }")
-    else:
-        # SIMPLE  -  direct init params
-        for param in comp.get("initParameters", []):
-            lines.append(f"    private let {param['name']}: {param['swiftType']}")
-    lines.append("}")
-    lines.append("```")
-
-    return "\n".join(lines)
-
-
-def run_spec(artifact_path: str) -> bool:
-    """Compile 07_implementation_spec.md from pass3 structured files."""
-    print("Phase 3 Spec: Compiling implementation spec")
-    ap = Path(artifact_path)
-
-    # Read architecture JSON (primary data source)
-    arch_path = ap / "pass3" / "04b_component_architecture.json"
-    if not arch_path.exists():
-        print("  [error] 04b_component_architecture.json not found", file=sys.stderr)
-        return False
-
-    with open(arch_path) as f:
-        arch = json.load(f)
-
-    comp_name = arch.get("componentName", "Unknown")
-    complexity = arch.get("complexity", "SIMPLE")
-    prop_count = arch.get("propertyCount", 0)
-
-    # Read component_summary.json for dimensions
-    summary_path = ap / "pass1" / "component_summary.json"
-    dimensions = "unknown"
-    node_id = ""
-    if summary_path.exists():
-        with open(summary_path) as f:
-            summary = json.load(f)
-        w = summary.get("dimensions", {}).get("width", "?")
-        h = summary.get("dimensions", {}).get("height", "?")
-        dimensions = f"{w} x {h} (component set)"
-        node_id = summary.get("nodeId", "")
-
-    # Read component location
-    loc_path = ap / "pass3" / "01_component_location.md"
-    comp_location = extract_md_value(loc_path, "Location")
-    if not comp_location:
-        comp_location = "(see 01_component_location.md)"
-
-    # Read property coverage
-    cov_path = ap / "pass3" / "00_property_coverage.json"
-    if cov_path.exists():
-        with open(cov_path) as f:
-            cov = json.load(f)
-    else:
-        cov = {}
-
-    # Generate API shape code
-    api_code = generate_api_shape_code(arch)
-
-    # Build variant mapping table
-    variant_lines = []
-    variant_lines.append("| Figma Property | Swift Property | Type |")
-    variant_lines.append("|----------------|---------------|------|")
-
-    all_props = arch.get("properties", []) + arch.get("implicitProperties", [])
-    for prop in all_props:
-        status = prop.get("status", "IMPLEMENT")
-        if status == "SKIP":
-            # Show merged info
-            reason = prop.get("reason", "")
-            swift_type = " - "
-            swift_name = " - "
-            if "merged" in reason.lower():
-                # Find the implicit property this was merged into
-                for ip in arch.get("implicitProperties", []):
-                    if ip.get("figmaKey") == prop.get("figmaKey"):
-                        swift_name = ip["name"]
-                        swift_type = f"{ip['swiftType']} (merged  -  nil = hidden)"
-                        break
-            variant_lines.append(f"| {prop['name']} ({prop['type']}) | {swift_name} | {swift_type} |")
-        else:
-            swift_type = prop.get("swiftType", "?")
-            figma_key = prop.get("figmaKey", prop.get("name", ""))
-            # Swift property name
-            swift_name = prop.get("name", "")
-            # camelCase the name
-            if swift_name and " " in swift_name:
-                parts = swift_name.split()
-                swift_name = parts[0].lower() + "".join(p.capitalize() for p in parts[1:])
-            elif swift_name:
-                swift_name = swift_name[0].lower() + swift_name[1:]
-
-            if prop.get("type") == "BOOLEAN_MERGED":
-                continue  # Already shown via the SKIP entry
-            type_desc = f"{swift_type} enum" if prop.get("values") else swift_type
-            if prop.get("values"):
-                vals = "/".join(f".{v}" for v in (arch.get("enums", [{}])[0].get("cases", []) if False else []))
-                # Find the matching enum
-                for e in arch.get("enums", []):
-                    if e.get("name") == swift_type:
-                        vals = "/".join(f".{c}" for c in e["cases"])
-                        type_desc = f"{swift_type} enum ({vals})"
-                        break
-            if swift_type == "Bool" and prop.get("values"):
-                type_desc = "Bool (Yes→true, No→false)"
-
-            variant_lines.append(f"| {prop['name']} ({prop['type']}) | {swift_name} | {type_desc} |")
-
-    # Nested dependencies
-    nested_path = ap / "pass3" / "03_nested_components.md"
-    nested_lines = extract_md_section_lines(nested_path, "Connected")
-    if not nested_lines or all(not l.strip() or l.startswith("|--") for l in nested_lines):
-        nested_section = "Self-contained component. No nested dependencies."
-    else:
-        nested_section = "\n".join(nested_lines)
-
-    # Check for inline elements mention
-    nested_full = ""
-    if nested_path.exists():
-        with open(nested_path) as f:
-            nested_full = f.read()
-    inline_mention = ""
-    if "inline" in nested_full.lower():
-        for line in nested_full.split("\n"):
-            if "inline" in line.lower() and not line.startswith("#"):
-                inline_mention = line.strip().lstrip("- ")
-                break
-
-    # Assets
-    assets_path = ap / "pass3" / "06_assets.md"
-    asset_summary_lines = extract_md_section_lines(assets_path, "Summary")
-    asset_summary = "\n".join(l for l in asset_summary_lines if l.strip())
-    if not asset_summary:
-        asset_summary = "No assets."
-
-    # Token summary
-    token_path = ap / "pass3" / "02_token_mapping.md"
-    token_summary_lines = extract_md_section_lines(token_path, "Summary")
-    token_summary = "\n".join(l for l in token_summary_lines if l.strip())
-
-    # Missing tokens
-    missing_lines = extract_md_section_lines(token_path, "Missing Tokens")
-    missing_count = sum(1 for l in missing_lines if l.strip().startswith("|") and "⚠️" not in l and "Token" not in l and "---" not in l)
-    # Parse from summary
-    token_mapped = 0
-    token_missing = 0
-    for l in token_summary_lines:
-        if "mapped" in l.lower():
-            m = re.search(r'(\d+)\s+mapped', l)
-            if m:
-                token_mapped += int(m.group(1))
-        if "missing" in l.lower():
-            m = re.search(r'(\d+)\s+(?:actionable|missing)', l)
-            if m:
-                token_missing += int(m.group(1))
-
-    # Data models
-    api_design = arch.get("apiDesign", {})
-    sub_configs = api_design.get("subConfigurations", [])
-    list_types = api_design.get("listTypes", [])
-    if not sub_configs and not list_types:
-        data_models = "No list inference. No sub-configurations. All properties are flat within the configuration struct."
-    else:
-        parts = []
-        if sub_configs:
-            parts.append(f"Sub-configurations: {', '.join(sc.get('name', '?') for sc in sub_configs)}")
-        if list_types:
-            parts.append(f"List types: {', '.join(lt.get('name', '?') for lt in list_types)}")
-        data_models = " ".join(parts)
-
-    # Files to create
-    files_to_create = [f"- `{comp_name}.swift` (main view)"]
-    if complexity == "COMPLEX":
-        config_name = arch.get("configurationStruct", f"{comp_name}Configuration")
-        files_to_create.append(f"- `{config_name}.swift` (configuration struct + enums)")
-    files_to_create.append("- `FIGMA.md` (documentation)")
-
-    # Workflow
-    if complexity == "COMPLEX":
-        config_name = arch.get("configurationStruct", f"{comp_name}Configuration")
-        workflow = f"COMPLEX → Configuration struct pattern. {config_name} wraps all {prop_count} parameters."
-    else:
-        workflow = f"SIMPLE → Direct init parameters. {prop_count} parameters passed to init."
-
-    # --- COMPILE SPEC ---
-    spec = f"""# Implementation Spec
-
-Component: {comp_name}
-Generated: {DATE_SHORT}
-
-## Component
-
-| Field | Value |
-|-------|-------|
-| Name | {comp_name} |
-| Path | {comp_location} |
-| Node ID | {node_id} |
-| Dimensions | {dimensions} |
-| Complexity | {complexity} |
-| Properties | {prop_count} (after pattern reduction) |
-
-## Files to Create
-
-{chr(10).join(files_to_create)}
-
-## API Shape
-
-{api_code}
-
-## Variant Mapping
-
-{chr(10).join(variant_lines)}
-
-## Data Models
-
-{data_models}
-
-## Nested Dependencies
-
-{nested_section}
-{f'{chr(10)}{inline_mention}' if inline_mention else ''}
-
-## New Assets
-
-{asset_summary}
-
-## Token Mapping
-
-- Mapped: {token_mapped}
-- Missing: {token_missing}
-
-## Workflow
-
-{workflow}
-"""
-
-    out_path = ap / "pass3" / "07_implementation_spec.md"
-    with open(out_path, "w") as f:
-        f.write(spec)
-
-    print(f"  ✅ {out_path}")
-    return True
-
-
-# --- Main ---
-
-def main():
-    parser = argparse.ArgumentParser(description="Phase 3 scriptable sub-phases")
-    parser.add_argument("subphase", choices=["3b", "3e", "3f", "3g", "spec", "wave1", "all"],
-                        help="Which sub-phase to run")
-    parser.add_argument("--artifact-path", required=True, help="Path to artifact directory")
-
-    args = parser.parse_args()
-
-    ensure_cli()
-
-    results = {}
-
-    if args.subphase in ("3b", "wave1", "all"):
-        results["3b"] = run_3b(args.artifact_path)
-
-    if args.subphase in ("3e", "wave1", "all"):
-        results["3e"] = run_3e(args.artifact_path)
-
-    if args.subphase in ("3f", "wave1", "all"):
-        results["3f"] = run_3f(args.artifact_path)
-
-    if args.subphase in ("3g", "all"):
-        results["3g"] = run_3g(args.artifact_path)
-
-    if args.subphase in ("spec", "all"):
-        results["spec"] = run_spec(args.artifact_path)
-
-    # Summary
-    print(f"\n{'='*50}")
-    for phase, ok in results.items():
-        status = "✅ PASS" if ok else "❌ FAIL"
-        print(f"  {phase}: {status}")
-
-    if all(results.values()):
-        print(f"\nAll sub-phases complete.")
-    else:
-        failed = [k for k, v in results.items() if not v]
-        print(f"\nFailed: {', '.join(failed)}", file=sys.stderr)
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()