@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,629 @@
+#!/usr/bin/env python3
+"""
+Phase 7A validation script.
+
+Supports two modes:
+- confluence: validates Confluence XHTML (main.html + ios.html)
+- wiki: validates wiki markdown ({ComponentName}.md)
+
+Usage:
+    # Confluence mode (default)
+    python3 validate-phase7a.py \
+        --confluence-path "path/to/confluence" \
+        --component-name "ComponentName"
+
+    # Wiki mode
+    python3 validate-phase7a.py \
+        --wiki-path "path/to/wiki/component" \
+        --component-name "ComponentName" \
+        --mode wiki
+
+Exit codes:
+    0 = all checks pass
+    1 = validation failures found (details in JSON stdout)
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple
+
+
+def find_image_references(html_content: str) -> List[str]:
+    """Extract all ri:filename values from <ac:image> and <ri:attachment> tags."""
+    return re.findall(r'ri:filename="([^"]+)"', html_content)
+
+
+def find_template_variables(html_content: str) -> List[str]:
+    """Find unreplaced template variables like {ComponentName}, {DESCRIPTION}, etc."""
+    # Match {WORD} but exclude known Confluence macro params like {printable}
+    confluence_params = {"true", "false", "disc", "circle", "square", "none"}
+    matches = re.findall(r"\{([A-Z][A-Za-z_]+)\}", html_content)
+    return [f"{{{m}}}" for m in matches if m.lower() not in confluence_params]
+
+
+def find_html_comments(html_content: str) -> List[str]:
+    """Find remaining HTML comments (template conditionals)."""
+    return re.findall(r"<!--\s*(IF|END|ELSE)[^>]*-->", html_content)
+
+
+def find_swift_code_leaks(html_content: str) -> List[str]:
+    """Detect Swift code patterns that shouldn't be in main.html."""
+    patterns = [
+        (r"import\s+UIComponents", "import UIComponents"),
+        (r"\.accessibilityIdentifier\(", ".accessibilityIdentifier("),
+        (r"func\s+test_", "func test_"),
+        (r"@testable\s+import", "@testable import"),
+    ]
+    leaks = []
+    for pattern, label in patterns:
+        if re.search(pattern, html_content):
+            leaks.append(label)
+    return leaks
+
+
+def check_required_sections(html_content: str, required: List[str]) -> Tuple[List[str], List[str]]:
+    """Check which required <h2> sections are present/missing."""
+    present = []
+    missing = []
+    for section in required:
+        if f"<h2>{section}</h2>" in html_content:
+            present.append(section)
+        else:
+            missing.append(section)
+    return present, missing
+
+
+def check_unescaped_ampersands(html_content: str) -> List[str]:
+    """Find unescaped & in XML attribute values."""
+    violations = []
+    # Check ri:filename and ri:content-title attributes for bare &
+    for attr in ["ri:filename", "ri:content-title"]:
+        for match in re.finditer(rf'{attr}="([^"]*)"', html_content):
+            value = match.group(1)
+            # Find bare & (not &amp; &lt; &gt; &quot; &apos; &#...)
+            if re.search(r"&(?!amp;|lt;|gt;|quot;|apos;|#)", value):
+                violations.append(f'{attr}="{value}"')
+    return violations
+
+
+def validate_snapshot_coverage(
+    assets_dir: Path,
+    snapshot_source_dir: Optional[str],
+    ios_html: str,
+    component_name: str,
+) -> dict:
+    """Validate snapshot test coverage: every variant has assets + XHTML references."""
+    result = {
+        "variants_found": [],
+        "missing_assets": [],
+        "missing_references": [],
+        "orphan_assets": [],
+        "rtl_variants_found": [],
+        "rtl_missing_assets": [],
+        "rtl_missing_references": [],
+    }
+
+    # Collect all ios_ prefixed assets
+    ios_assets = set()
+    if assets_dir.exists():
+        for f in assets_dir.iterdir():
+            if f.name.startswith("ios_") and f.name.endswith(".png"):
+                ios_assets.add(f.name)
+
+    # Extract image references from ios.html
+    ios_refs = set(find_image_references(ios_html))
+    ios_image_refs = {r for r in ios_refs if r.startswith("ios_")}
+
+    # Determine variants from asset files
+    # Pattern: ios_light_{variant}.png, ios_dark_{variant}.png
+    light_variants = set()
+    dark_variants = set()
+    rtl_light_variants = set()
+    rtl_dark_variants = set()
+
+    for asset in ios_assets:
+        name = asset[:-4]  # strip .png
+        if name.startswith("ios_rtl_light_"):
+            rtl_light_variants.add(name[len("ios_rtl_light_"):])
+        elif name.startswith("ios_rtl_dark_"):
+            rtl_dark_variants.add(name[len("ios_rtl_dark_"):])
+        elif name.startswith("ios_light_"):
+            light_variants.add(name[len("ios_light_"):])
+        elif name.startswith("ios_dark_"):
+            dark_variants.add(name[len("ios_dark_"):])
+
+    # All variants = union of light and dark
+    all_variants = light_variants | dark_variants
+    result["variants_found"] = sorted(all_variants)
+
+    # Check each variant has both light and dark assets
+    for variant in sorted(all_variants):
+        light_file = f"ios_light_{variant}.png"
+        dark_file = f"ios_dark_{variant}.png"
+        if light_file not in ios_assets:
+            result["missing_assets"].append(light_file)
+        if dark_file not in ios_assets:
+            result["missing_assets"].append(dark_file)
+        # Check XHTML references
+        if light_file not in ios_image_refs:
+            result["missing_references"].append(light_file)
+        if dark_file not in ios_image_refs:
+            result["missing_references"].append(dark_file)
+
+    # RTL variants
+    all_rtl = rtl_light_variants | rtl_dark_variants
+    result["rtl_variants_found"] = sorted(all_rtl)
+
+    for variant in sorted(all_rtl):
+        light_file = f"ios_rtl_light_{variant}.png"
+        dark_file = f"ios_rtl_dark_{variant}.png"
+        if light_file not in ios_assets:
+            result["rtl_missing_assets"].append(light_file)
+        if dark_file not in ios_assets:
+            result["rtl_missing_assets"].append(dark_file)
+        if light_file not in ios_image_refs:
+            result["rtl_missing_references"].append(light_file)
+        if dark_file not in ios_image_refs:
+            result["rtl_missing_references"].append(dark_file)
+
+    # Orphan check: ios_ assets not referenced in XHTML
+    for asset in sorted(ios_assets):
+        if asset not in ios_image_refs:
+            result["orphan_assets"].append(asset)
+
+    return result
+
+
+def find_wiki_image_references(md_content: str) -> List[str]:
+    """Extract all asset filenames from wiki image syntax [[/path/assets/file.png]] or [[/path/assets/file.png|alt]]."""
+    matches = re.findall(r'\[\[/[^|\]]*?/assets/([^|\]]+?)(?:\|[^\]]*?)?\]\]', md_content)
+    return matches
+
+
+def check_required_md_sections(md_content: str, required: List[str]) -> Tuple[List[str], List[str]]:
+    """Check which required ## sections are present/missing in markdown."""
+    present = []
+    missing = []
+    for section in required:
+        pattern = rf'^## {re.escape(section)}\s*$'
+        if re.search(pattern, md_content, re.MULTILINE):
+            present.append(section)
+        else:
+            missing.append(section)
+    return present, missing
+
+
+def check_required_md_subsections(md_content: str, required: List[str]) -> Tuple[List[str], List[str]]:
+    """Check which required ### sections are present/missing in markdown."""
+    present = []
+    missing = []
+    for section in required:
+        pattern = rf'^### {re.escape(section)}\s*$'
+        if re.search(pattern, md_content, re.MULTILINE):
+            present.append(section)
+        else:
+            missing.append(section)
+    return present, missing
+
+
+def validate_wiki_snapshot_coverage(
+    assets_dir: Path,
+    md_content: str,
+    component_name: str,
+) -> dict:
+    """Validate snapshot test coverage in wiki markdown."""
+    result = {
+        "variants_found": [],
+        "missing_assets": [],
+        "missing_references": [],
+        "orphan_assets": [],
+        "rtl_variants_found": [],
+        "rtl_missing_assets": [],
+        "rtl_missing_references": [],
+    }
+
+    ios_assets = set()
+    if assets_dir.exists():
+        for f in assets_dir.iterdir():
+            if f.name.startswith("ios_") and f.name.endswith(".png"):
+                ios_assets.add(f.name)
+
+    md_refs = set(find_wiki_image_references(md_content))
+    ios_image_refs = {r for r in md_refs if r.startswith("ios_")}
+
+    light_variants = set()
+    dark_variants = set()
+    rtl_light_variants = set()
+    rtl_dark_variants = set()
+
+    for asset in ios_assets:
+        name = asset[:-4]
+        if name.startswith("ios_rtl_light_"):
+            rtl_light_variants.add(name[len("ios_rtl_light_"):])
+        elif name.startswith("ios_rtl_dark_"):
+            rtl_dark_variants.add(name[len("ios_rtl_dark_"):])
+        elif name.startswith("ios_light_"):
+            light_variants.add(name[len("ios_light_"):])
+        elif name.startswith("ios_dark_"):
+            dark_variants.add(name[len("ios_dark_"):])
+
+    all_variants = light_variants | dark_variants
+    result["variants_found"] = sorted(all_variants)
+
+    for variant in sorted(all_variants):
+        light_file = f"ios_light_{variant}.png"
+        dark_file = f"ios_dark_{variant}.png"
+        if light_file not in ios_assets:
+            result["missing_assets"].append(light_file)
+        if dark_file not in ios_assets:
+            result["missing_assets"].append(dark_file)
+        if light_file not in ios_image_refs:
+            result["missing_references"].append(light_file)
+        if dark_file not in ios_image_refs:
+            result["missing_references"].append(dark_file)
+
+    all_rtl = rtl_light_variants | rtl_dark_variants
+    result["rtl_variants_found"] = sorted(all_rtl)
+
+    for variant in sorted(all_rtl):
+        light_file = f"ios_rtl_light_{variant}.png"
+        dark_file = f"ios_rtl_dark_{variant}.png"
+        if light_file not in ios_assets:
+            result["rtl_missing_assets"].append(light_file)
+        if dark_file not in ios_assets:
+            result["rtl_missing_assets"].append(dark_file)
+        if light_file not in ios_image_refs:
+            result["rtl_missing_references"].append(light_file)
+        if dark_file not in ios_image_refs:
+            result["rtl_missing_references"].append(dark_file)
+
+    for asset in sorted(ios_assets):
+        if asset not in ios_image_refs:
+            result["orphan_assets"].append(asset)
+
+    return result
+
+
+def validate_wiki(wiki_path: Path, component_name: str) -> dict:
+    """Validate wiki markdown documentation."""
+    violations = []
+    warnings = []
+    stats = {}
+
+    assets_dir = wiki_path / "assets"
+    md_file = wiki_path / f"{component_name}.md"
+    screenshot_file = assets_dir / "screenshot.png"
+
+    if not md_file.exists():
+        violations.append(f"{component_name}.md does not exist")
+        return {"status": "FAIL", "violations": violations, "warnings": warnings, "stats": stats}
+
+    if not screenshot_file.exists():
+        violations.append("assets/screenshot.png does not exist")
+
+    md_content = md_file.read_text(encoding="utf-8")
+
+    # Required ## sections
+    required_sections = [
+        "Overview", "Testing Identifiers", "Localization Keys",
+        "Accessibility", "Analytics Events", "Sub-Components",
+        "Platform Implementations", "Changelog", "iOS Implementation",
+    ]
+    present, missing = check_required_md_sections(md_content, required_sections)
+
+    # Allow placeholder text as alternative
+    for section in list(missing):
+        placeholders = {
+            "Testing Identifiers": "No testing identifiers",
+            "Localization Keys": "No localization keys",
+            "Accessibility": "No dedicated accessibility keys",
+            "Analytics Events": "No analytics events",
+            "Sub-Components": "No nested View components",
+        }
+        if section in placeholders and placeholders[section] in md_content:
+            missing.remove(section)
+            present.append(f"{section} (placeholder)")
+
+    if missing:
+        violations.append(f"Missing sections: {missing}")
+    stats["sections"] = len(present)
+
+    # iOS subsections (under ## iOS Implementation)
+    ios_start = md_content.find("## iOS Implementation")
+    if ios_start >= 0:
+        ios_content = md_content[ios_start:]
+        ios_required = ["Initializer", "Usage"]
+        ios_present, ios_missing = check_required_md_subsections(ios_content, ios_required)
+        if ios_missing:
+            violations.append(f"iOS missing subsections: {ios_missing}")
+
+        has_snapshot_assets = any(
+            f.startswith("ios_") and f.endswith(".png")
+            for f in (os.listdir(assets_dir) if assets_dir.exists() else [])
+        )
+        has_snapshot_section = "## Snapshot Tests" in ios_content or "### Snapshot Tests" in md_content
+        if has_snapshot_assets and not has_snapshot_section:
+            violations.append("Missing Snapshot Tests section but snapshot assets exist")
+    else:
+        violations.append("Missing ## iOS Implementation split marker")
+
+    # Template variables
+    template_vars = find_template_variables(md_content)
+    if template_vars:
+        violations.append(f"Unreplaced template variables: {template_vars}")
+
+    # HTML comments
+    html_comments = find_html_comments(md_content)
+    if html_comments:
+        violations.append(f"Remaining template comments: {html_comments}")
+
+    # Asset reference integrity
+    md_refs = set(find_wiki_image_references(md_content))
+    existing_assets = set()
+    if assets_dir.exists():
+        existing_assets = {f.name for f in assets_dir.iterdir() if f.is_file()}
+
+    missing_assets = md_refs - existing_assets
+    if missing_assets:
+        violations.append(f"Referenced but missing from assets/: {sorted(missing_assets)}")
+
+    orphan_assets = existing_assets - md_refs
+    if orphan_assets:
+        warnings.append(f"Assets not referenced in markdown: {sorted(orphan_assets)}")
+
+    stats["assets_total"] = len(existing_assets)
+    stats["assets_referenced"] = len(md_refs & existing_assets)
+    stats["assets_orphaned"] = len(orphan_assets)
+
+    # Snapshot coverage
+    snapshot_result = validate_wiki_snapshot_coverage(assets_dir, md_content, component_name)
+    stats["snapshot_variants"] = len(snapshot_result["variants_found"])
+    stats["snapshot_rtl_variants"] = len(snapshot_result["rtl_variants_found"])
+
+    if snapshot_result["missing_assets"]:
+        violations.append(f"Snapshot variants missing asset files: {snapshot_result['missing_assets']}")
+    if snapshot_result["missing_references"]:
+        violations.append(f"Snapshot assets not referenced in markdown: {snapshot_result['missing_references']}")
+    if snapshot_result["rtl_missing_assets"]:
+        violations.append(f"RTL snapshot variants missing asset files: {snapshot_result['rtl_missing_assets']}")
+    if snapshot_result["rtl_missing_references"]:
+        violations.append(f"RTL snapshot assets not referenced in markdown: {snapshot_result['rtl_missing_references']}")
+    if snapshot_result["orphan_assets"]:
+        warnings.append(f"ios_ assets not referenced in markdown: {snapshot_result['orphan_assets']}")
+
+    # Variant screenshots
+    variant_assets = {a for a in existing_assets if not a.startswith("ios_") and a != "screenshot.png"}
+    if variant_assets:
+        variant_refs = {r for r in md_refs if not r.startswith("ios_") and r != "screenshot.png"}
+        missing_variant_refs = variant_assets - variant_refs
+        if missing_variant_refs:
+            warnings.append(f"Variant assets not referenced in markdown: {sorted(missing_variant_refs)}")
+        stats["variant_screenshots"] = len(variant_assets)
+    else:
+        stats["variant_screenshots"] = 0
+
+    status = "PASS" if not violations else "FAIL"
+    return {
+        "status": status,
+        "violations": violations,
+        "warnings": warnings,
+        "stats": stats,
+        "snapshot_coverage": {
+            "variants": snapshot_result["variants_found"],
+            "rtl_variants": snapshot_result["rtl_variants_found"],
+            "missing_assets": snapshot_result["missing_assets"],
+            "missing_references": snapshot_result["missing_references"],
+        },
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Validate Phase 7A output (wiki or confluence)")
+    parser.add_argument("--confluence-path", default=None, help="Path to confluence output directory")
+    parser.add_argument("--wiki-path", default=None, help="Path to wiki component directory")
+    parser.add_argument("--snapshot-dir", default=None, help="Path to __Snapshots__/ComponentSnapshotTests/ (optional)")
+    parser.add_argument("--component-name", required=True, help="Component name (e.g., LabelBadge)")
+    parser.add_argument("--mode", default="confluence", choices=["confluence", "wiki"], help="Validation mode")
+    args = parser.parse_args()
+
+    if args.mode == "wiki":
+        if not args.wiki_path:
+            print(json.dumps({"status": "FAIL", "violations": ["--wiki-path required for wiki mode"]}))
+            sys.exit(1)
+        output = validate_wiki(Path(args.wiki_path), args.component_name)
+        print(json.dumps(output, indent=2))
+        sys.exit(0 if output["status"] == "PASS" else 1)
+
+    # Confluence mode (original behavior)
+    if not args.confluence_path:
+        print(json.dumps({"status": "FAIL", "violations": ["--confluence-path required for confluence mode"]}))
+        sys.exit(1)
+
+    confluence_path = Path(args.confluence_path)
+    assets_dir = confluence_path / "assets"
+
+    violations = []
+    warnings = []
+    stats = {}
+
+    # --- 1. File existence ---
+    main_file = confluence_path / "main.html"
+    ios_file = confluence_path / "ios.html"
+    screenshot_file = assets_dir / "screenshot.png"
+
+    if not main_file.exists():
+        violations.append("main.html does not exist")
+    if not ios_file.exists():
+        violations.append("ios.html does not exist")
+    if not screenshot_file.exists():
+        violations.append("assets/screenshot.png does not exist")
+
+    if not main_file.exists() or not ios_file.exists():
+        print(json.dumps({
+            "status": "FAIL",
+            "violations": violations,
+            "warnings": warnings,
+        }, indent=2))
+        sys.exit(1)
+
+    main_html = main_file.read_text(encoding="utf-8")
+    ios_html = ios_file.read_text(encoding="utf-8")
+
+    # --- 2. main.html required sections ---
+    main_required = [
+        "Variants", "Overview", "Testing Identifiers", "Localization Keys",
+        "Accessibility", "Analytics Events", "Sub-Components",
+        "Platform Implementations", "Changelog",
+    ]
+    main_present, main_missing = check_required_sections(main_html, main_required)
+    # Sections can be replaced with placeholder text, check for that
+    for section in list(main_missing):
+        # Allow "No ..." placeholder as alternative to <h2> section
+        placeholders = {
+            "Testing Identifiers": "No testing identifiers",
+            "Localization Keys": "No localization keys",
+            "Accessibility": "No dedicated accessibility keys",
+            "Analytics Events": "No analytics events",
+            "Sub-Components": "No nested View components",
+        }
+        if section in placeholders and placeholders[section] in main_html:
+            main_missing.remove(section)
+            main_present.append(f"{section} (placeholder)")
+
+    if main_missing:
+        violations.append(f"main.html missing sections: {main_missing}")
+    stats["main_sections"] = len(main_present)
+
+    # --- 3. ios.html required sections ---
+    ios_required = ["Initializer", "Usage", "Changelog"]
+    ios_present, ios_missing = check_required_sections(ios_html, ios_required)
+    if ios_missing:
+        violations.append(f"ios.html missing sections: {ios_missing}")
+
+    # Back-link check
+    if "ri:content-title=" not in ios_html or "Back to" not in ios_html:
+        violations.append("ios.html missing back-link to main page")
+
+    # Snapshot Tests section (required if snapshot assets exist)
+    has_snapshot_assets = any(
+        f.startswith("ios_") and f.endswith(".png")
+        for f in (os.listdir(assets_dir) if assets_dir.exists() else [])
+    )
+    has_snapshot_section = "<h2>Snapshot Tests</h2>" in ios_html
+    if has_snapshot_assets and not has_snapshot_section:
+        violations.append("ios.html missing <h2>Snapshot Tests</h2> section but snapshot assets exist")
+    if has_snapshot_section:
+        ios_present.append("Snapshot Tests")
+    stats["ios_sections"] = len(ios_present)
+
+    # Code Connect section (optional but tracked)
+    if "<h2>Code Connect</h2>" in ios_html:
+        ios_present.append("Code Connect")
+
+    # --- 4. Template variables ---
+    main_vars = find_template_variables(main_html)
+    ios_vars = find_template_variables(ios_html)
+    if main_vars:
+        violations.append(f"main.html has unreplaced template variables: {main_vars}")
+    if ios_vars:
+        violations.append(f"ios.html has unreplaced template variables: {ios_vars}")
+
+    # --- 5. HTML comments ---
+    main_comments = find_html_comments(main_html)
+    ios_comments = find_html_comments(ios_html)
+    if main_comments:
+        violations.append(f"main.html has remaining template comments: {main_comments}")
+    if ios_comments:
+        violations.append(f"ios.html has remaining template comments: {ios_comments}")
+
+    # --- 6. Swift code leaks (main.html only) ---
+    leaks = find_swift_code_leaks(main_html)
+    if leaks:
+        violations.append(f"main.html contains Swift code patterns: {leaks}")
+
+    # --- 7. Unescaped ampersands ---
+    main_amps = check_unescaped_ampersands(main_html)
+    ios_amps = check_unescaped_ampersands(ios_html)
+    if main_amps:
+        violations.append(f"main.html has unescaped & in attributes: {main_amps}")
+    if ios_amps:
+        violations.append(f"ios.html has unescaped & in attributes: {ios_amps}")
+
+    # --- 8. Asset reference integrity ---
+    main_refs = set(find_image_references(main_html))
+    ios_refs = set(find_image_references(ios_html))
+    all_refs = main_refs | ios_refs
+
+    existing_assets = set()
+    if assets_dir.exists():
+        existing_assets = {f.name for f in assets_dir.iterdir() if f.is_file()}
+
+    # Referenced but missing
+    missing_assets = all_refs - existing_assets
+    if missing_assets:
+        violations.append(f"Referenced in XHTML but missing from assets/: {sorted(missing_assets)}")
+
+    # Existing but unreferenced (orphans)
+    orphan_assets = existing_assets - all_refs
+    if orphan_assets:
+        warnings.append(f"Assets not referenced in any XHTML: {sorted(orphan_assets)}")
+
+    stats["assets_total"] = len(existing_assets)
+    stats["assets_referenced"] = len(all_refs & existing_assets)
+    stats["assets_orphaned"] = len(orphan_assets)
+
+    # --- 9. Snapshot coverage ---
+    snapshot_result = validate_snapshot_coverage(
+        assets_dir, args.snapshot_dir, ios_html, args.component_name
+    )
+    stats["snapshot_variants"] = len(snapshot_result["variants_found"])
+    stats["snapshot_rtl_variants"] = len(snapshot_result["rtl_variants_found"])
+
+    if snapshot_result["missing_assets"]:
+        violations.append(f"Snapshot variants missing asset files: {snapshot_result['missing_assets']}")
+    if snapshot_result["missing_references"]:
+        violations.append(f"Snapshot assets not referenced in ios.html: {snapshot_result['missing_references']}")
+    if snapshot_result["rtl_missing_assets"]:
+        violations.append(f"RTL snapshot variants missing asset files: {snapshot_result['rtl_missing_assets']}")
+    if snapshot_result["rtl_missing_references"]:
+        violations.append(f"RTL snapshot assets not referenced in ios.html: {snapshot_result['rtl_missing_references']}")
+    if snapshot_result["orphan_assets"]:
+        warnings.append(f"ios_ assets not referenced in ios.html: {snapshot_result['orphan_assets']}")
+
+    # --- 10. Variant section in main.html ---
+    # If variant screenshots exist (non-ios_, non-screenshot.png), Variants section should have <ac:image>
+    variant_assets = {a for a in existing_assets if not a.startswith("ios_") and a != "screenshot.png"}
+    if variant_assets:
+        variant_images_in_main = {r for r in main_refs if not r.startswith("ios_") and r != "screenshot.png"}
+        missing_variant_refs = variant_assets - variant_images_in_main
+        if missing_variant_refs:
+            warnings.append(f"Variant assets not referenced in main.html: {sorted(missing_variant_refs)}")
+        stats["variant_screenshots"] = len(variant_assets)
+    else:
+        stats["variant_screenshots"] = 0
+
+    # --- Output ---
+    status = "PASS" if not violations else "FAIL"
+    output = {
+        "status": status,
+        "violations": violations,
+        "warnings": warnings,
+        "stats": stats,
+        "snapshot_coverage": {
+            "variants": snapshot_result["variants_found"],
+            "rtl_variants": snapshot_result["rtl_variants_found"],
+            "missing_assets": snapshot_result["missing_assets"],
+            "missing_references": snapshot_result["missing_references"],
+        },
+    }
+
+    print(json.dumps(output, indent=2))
+    sys.exit(0 if status == "PASS" else 1)
+
+
+if __name__ == "__main__":
+    main()