spec-to-ui 0.1.0 → 0.2.0

package/skills/ui-ux-pro-max/scripts/tests/test_design_system_stack.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Regression tests for the dropped --stack flag in --design-system mode (issue #484).
+
+`search.py "<query>" --design-system --stack nextjs` used to exit successfully
+without any indication that the stack was never applied, so a caller following
+SKILL.md's "never assume a stack" guidance could believe stack guidance was
+part of the generated design system. The combination must stay valid, but it
+must say that --stack was ignored.
+
+Stdlib-only (unittest, not pytest) to match test_core.py -- this project ships
+with zero external dependencies.
+
+Run with:
+    python -m unittest discover -s scripts/tests -v
+or directly:
+    python scripts/tests/test_design_system_stack.py
+"""
+
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+SCRIPTS_DIR = Path(__file__).resolve().parent.parent
+SEARCH = SCRIPTS_DIR / "search.py"
+
+
+class TestStackFlagWithDesignSystem(unittest.TestCase):
+    def run_search(self, *args):
+        # The child forces UTF-8 on its streams (search.py), so decode as UTF-8
+        # regardless of the parent's locale on Windows.
+        return subprocess.run(
+            [sys.executable, str(SEARCH), *map(str, args)],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+
+    def test_design_system_with_stack_succeeds_and_says_stack_is_ignored(self):
+        proc = self.run_search("platform engineer dashboard", "--design-system", "--stack", "nextjs")
+        self.assertEqual(proc.returncode, 0, proc.stderr)
+        self.assertIn("--stack", proc.stderr)
+        self.assertIn("ignored", proc.stderr.lower())
+
+    def test_design_system_without_stack_stays_quiet(self):
+        proc = self.run_search("platform engineer dashboard", "--design-system")
+        self.assertEqual(proc.returncode, 0, proc.stderr)
+        self.assertNotIn("ignored", proc.stderr.lower())
+
+    def test_stack_search_alone_never_warns(self):
+        proc = self.run_search("dashboard table density", "--stack", "nextjs")
+        self.assertEqual(proc.returncode, 0, proc.stderr)
+        self.assertNotIn("ignored", proc.stderr.lower())
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/ui-ux-pro-max/scripts/tests/test_native_desktop_stack_freshness.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Freshness and migration contracts for native, desktop, and 3D stacks."""
+
+import csv
+import sys
+import unittest
+from pathlib import Path
+from urllib.parse import urlsplit
+
+SCRIPTS_DIR = Path(__file__).resolve().parents[1]
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+from core import (DATA_DIR, STACK_CONFIG, STACK_CURRENT_APPLICABILITY,
+                  search_stack)  # noqa: E402
+from validate_data import STACK_OFFICIAL_HOSTS  # noqa: E402
+
+STACKS = {
+    "react-native", "flutter", "swiftui", "jetpack-compose", "avalonia",
+    "uwp", "winui", "wpf", "uno", "javafx", "threejs", "laravel",
+}
+
+
+def _rows(stack):
+    path = DATA_DIR / STACK_CONFIG[stack]["file"]
+    with path.open(encoding="utf-8", newline="") as handle:
+        return list(csv.DictReader(handle))
+
+
+class TestNativeDesktopStackFreshness(unittest.TestCase):
+    def test_rows_have_final_freshness_metadata(self):
+        for stack in STACKS:
+            for row in _rows(stack):
+                with self.subTest(stack=stack, row=row["No"]):
+                    expected = "deprecated" if stack == "uwp" else "active"
+                    self.assertEqual(row["Status"], expected)
+                    self.assertTrue(row["Applies To"].startswith(
+                        STACK_CURRENT_APPLICABILITY[stack]))
+                    self.assertRegex(row["Verified At"], r"^\d{4}-\d{2}-\d{2}$")
+                    self.assertEqual("legacy" in row["Applies To"], stack == "uwp")
+
+    def test_high_impact_rows_use_official_sources(self):
+        for stack in STACKS:
+            for row in _rows(stack):
+                if row["Severity"] not in {"Critical", "High"}:
+                    continue
+                with self.subTest(stack=stack, row=row["No"]):
+                    parsed = urlsplit(row["Docs URL"])
+                    self.assertEqual(parsed.scheme, "https")
+                    self.assertIn(parsed.hostname, STACK_OFFICIAL_HOSTS[stack])
+
+    def test_current_mobile_contracts(self):
+        cases = {
+            ("react-native", "Hermes bundled default engine"): "hermes",
+            ("flutter", "predictive back result callback"): "onpopinvokedwithresult",
+            ("flutter", "accessible nonlinear text scaling"): "textscaler",
+            ("swiftui", "multicolumn navigation sidebar detail"): "navigationsplitview",
+        }
+        for (stack, query), expected in cases.items():
+            with self.subTest(stack=stack):
+                result = search_stack(query, stack, max_results=1)
+                self.assertEqual(result["count"], 1)
+                recommended = " ".join(
+                    result["results"][0][field]
+                    for field in ("Guideline", "Do", "Code Good")
+                ).casefold()
+                self.assertIn(expected, recommended)
+
+    def test_windows_current_and_maintenance_lanes_are_visible(self):
+        current = search_stack("new Windows desktop app Windows App SDK", "winui")
+        legacy = search_stack("UWP maintenance x:Bind migration", "uwp")
+        self.assertGreater(current["count"], 0)
+        self.assertGreater(legacy["count"], 0)
+        self.assertEqual({row["Status"] for row in current["results"]}, {"active"})
+        self.assertEqual({row["Status"] for row in legacy["results"]}, {"deprecated"})
+        self.assertTrue(any("winui" in " ".join(row.values()).casefold()
+                            for row in legacy["results"]))
+        successor = search_stack(
+            "which Windows UI framework should a brand new app choose instead of legacy UWP",
+            "uwp", max_results=1,
+        )
+        self.assertEqual("Prefer WinUI 3 for new projects", successor["results"][0]["Guideline"])
+
+    def test_old_version_without_curated_rows_abstains(self):
+        cases = {
+            "react-native": "React Native 0.75 Hermes",
+            "flutter": "Flutter SDK 3.22 back navigation",
+            "swiftui": "iOS 15 SwiftUI navigation",
+            "avalonia": "Avalonia UI v11 storage picker",
+            "winui": "WinUI SDK 2 desktop app",
+            "javafx": "JavaFX SDK 21 table view",
+            "threejs": "Three.js r128 OrbitControls",
+            "laravel": "Laravel 12 validation",
+        }
+        for stack, query in cases.items():
+            with self.subTest(stack=stack):
+                self.assertEqual(search_stack(query, stack)["count"], 0)
+
+    def test_migration_intent_returns_current_replacements(self):
+        cases = {
+            "flutter": "replace deprecated WillPopScope with current Flutter API",
+            "react-native": "upgrade legacy Hermes configuration",
+            "threejs": "replace deprecated outputEncoding with current color space",
+        }
+        for stack, query in cases.items():
+            with self.subTest(stack=stack):
+                result = search_stack(query, stack)
+                self.assertGreater(result["count"], 0)
+                self.assertEqual({row["Status"] for row in result["results"]}, {"active"})
+
+        versioned_cases = {
+            "react-native": "upgrade React Native 0.75 to React Native 0.86 Hermes",
+            "flutter": "upgrade Flutter 3.22 to Flutter 3.44 predictive back",
+            "threejs": "upgrade Three.js r128 to r185 outputColorSpace",
+        }
+        for stack, query in versioned_cases.items():
+            with self.subTest(stack=stack, query=query):
+                result = search_stack(query, stack)
+                self.assertGreater(result["count"], 0)
+                self.assertEqual({row["Status"] for row in result["results"]}, {"active"})
+
+    def test_standalone_current_and_deprecated_identifiers_resolve_replacement(self):
+        cases = {
+            ("flutter", "onPopInvokedWithResult"): "PopScope",
+            ("flutter", "TextScaler"): "large fonts",
+            ("threejs", "outputColorSpace"): "Color Space",
+            ("threejs", "outputEncoding"): "Color Space",
+        }
+        for (stack, query), guideline in cases.items():
+            with self.subTest(stack=stack, query=query):
+                result = search_stack(query, stack, max_results=1)
+                self.assertEqual(result["count"], 1)
+                self.assertIn(guideline.casefold(), result["results"][0]["Guideline"].casefold())
+
+    def test_current_threejs_uses_supported_module_and_color_apis(self):
+        cases = {
+            "Three.js current OrbitControls addon import": "three/addons/",
+            "Three.js current renderer color space": "outputcolorspace",
+            "Three.js frame-rate independent delta time": "three.timer",
+        }
+        for query, expected in cases.items():
+            with self.subTest(query=query):
+                result = search_stack(query, "threejs", max_results=1)
+                self.assertEqual(result["count"], 1)
+                recommended = " ".join(
+                    result["results"][0][field]
+                    for field in ("Guideline", "Do", "Code Good")
+                ).casefold()
+                self.assertIn(expected, recommended)
+
+    def test_deprecated_symbols_are_not_recommended_by_current_rows(self):
+        forbidden = {
+            "react-native": ("hermes_enabled",),
+            "flutter": ("willpopscope", "onpopinvoked:", "textscalefactor"),
+            "swiftui": ("navigationview", "presentationmode"),
+            "winui": ("dispatcher.runasync", "system.windows"),
+            "uno": ("system.windows", 'requestedtheme="default"'),
+            "javafx": ("fxpermission", "javadoc/21"),
+            "threejs": (
+                "r128", "three.orbitcontrols", "outputencoding",
+                "three.srgbencoding", "examples/js/controls",
+                "three.clock", "clock.getdelta", "clock.getelapsedtime",
+                "pcfsoftshadowmap", "three/examples/jsm/",
+            ),
+        }
+        for stack, tokens in forbidden.items():
+            for row in _rows(stack):
+                if row["Status"] != "active":
+                    continue
+                recommended = " ".join(
+                    row[field] for field in ("Guideline", "Do", "Code Good")
+                ).casefold()
+                for token in tokens:
+                    with self.subTest(stack=stack, row=row["No"], token=token):
+                        self.assertNotIn(token, recommended)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/ui-ux-pro-max/scripts/tests/test_relevance_evaluator.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""Unit tests for metric math and relevance fixture validation."""
+
+import importlib.util
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = next(parent for parent in Path(__file__).resolve().parents
+            if (parent / "scripts/evaluate-relevance.py").exists())
+MODULE_PATH = ROOT / "scripts/evaluate-relevance.py"
+SPEC = importlib.util.spec_from_file_location("evaluate_relevance", MODULE_PATH)
+evaluator = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(evaluator)
+
+
+class TestMetricMath(unittest.TestCase):
+    def test_precision_counts_missing_ranks_as_non_relevant(self):
+        self.assertEqual(evaluator.precision_at_k([2], 1), 1.0)
+        self.assertAlmostEqual(evaluator.precision_at_k([2], 3), 1 / 3)
+        self.assertEqual(evaluator.precision_at_k([], 3), 0.0)
+        self.assertEqual(evaluator.precision_at_k([2], 0), 0.0)
+
+    def test_reciprocal_rank_stops_at_k(self):
+        self.assertEqual(evaluator.reciprocal_rank([0, 2, 0]), 0.5)
+        self.assertEqual(evaluator.reciprocal_rank([0, 0, 0, 2]), 0.0)
+        self.assertEqual(evaluator.reciprocal_rank([]), 0.0)
+
+    def test_ndcg_uses_graded_gain_and_handles_empty_ideal(self):
+        self.assertEqual(evaluator.ndcg_at_k([2, 1], [2, 1]), 1.0)
+        self.assertLess(evaluator.ndcg_at_k([1, 2], [2, 1]), 1.0)
+        self.assertEqual(evaluator.ndcg_at_k([], [], 3), 0.0)
+
+    def test_result_grades_match_identity_subsets(self):
+        results = [
+            {"Category": "State", "Guideline": "Use useState", "Severity": "Medium"},
+            {"Category": "State", "Guideline": "Use useReducer", "Severity": "Medium"},
+        ]
+        judgments = [
+            {"identity": {"Guideline": "Use useReducer"}, "grade": 2},
+            {"identity": {"Category": "State"}, "grade": 1},
+        ]
+        self.assertEqual(evaluator.grades_for_results(results, judgments), [1, 2])
+
+
+class TestFixtureValidation(unittest.TestCase):
+    @staticmethod
+    def valid_fixture():
+        case = {
+            "id": "domain-style-minimal",
+            "split": "calibration",
+            "mode": "domain",
+            "domain": "style",
+            "query": "minimal grid",
+            "judgments": [{"identity": {"Style Category": "Minimalism"}, "grade": 2}],
+        }
+        return {
+            "schemaVersion": 1,
+            "globalNegativeApplicability": {"domains": ["style"], "stacks": []},
+            "cases": [dict(case, id=f"case-{index}") for index in range(60)],
+        }
+
+    def test_valid_schema(self):
+        self.assertEqual(evaluator.validate_fixture(self.valid_fixture(), {"style": {}}, []), [])
+
+    def test_rejects_bad_count_duplicate_id_and_grade(self):
+        fixture = self.valid_fixture()
+        fixture["cases"] = fixture["cases"][:2]
+        fixture["cases"][1]["id"] = fixture["cases"][0]["id"]
+        fixture["cases"][0]["judgments"][0]["grade"] = 3
+        errors = "\n".join(evaluator.validate_fixture(fixture, {"style": {}}, []))
+        self.assertIn("60-100", errors)
+        self.assertIn("duplicate case id", errors)
+        self.assertIn("grade 1 or 2", errors)
+
+
+class TestThresholdGate(unittest.TestCase):
+    def test_runtime_fingerprint_binds_reasoning_contract(self):
+        original = evaluator.ROOT, evaluator.RUNTIME_DIR, evaluator.DATA_DIR
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            runtime = root / "src/ui-ux-pro-max/scripts"
+            data = root / "src/ui-ux-pro-max/data"
+            runtime.mkdir(parents=True)
+            data.mkdir(parents=True)
+            for name in ("core.py", "design_system.py", "reasoning_contract.py"):
+                (runtime / name).write_text(name, encoding="utf-8")
+            (data / "styles.csv").write_text("No,Style\n1,Test\n", encoding="utf-8")
+            evaluator.ROOT, evaluator.RUNTIME_DIR, evaluator.DATA_DIR = root, runtime, data
+            try:
+                before = evaluator.runtime_fingerprint()
+                (runtime / "reasoning_contract.py").write_text("changed", encoding="utf-8")
+                self.assertNotEqual(before, evaluator.runtime_fingerprint())
+            finally:
+                evaluator.ROOT, evaluator.RUNTIME_DIR, evaluator.DATA_DIR = original
+
+    def test_oracle_fingerprint_hashes_the_selected_cases_file(self):
+        canonical = evaluator.FIXTURE_DIR / "relevance-cases.json"
+        with tempfile.TemporaryDirectory() as tmp:
+            selected = Path(tmp) / "cases.json"
+            selected.write_bytes(canonical.read_bytes())
+            self.assertEqual(
+                evaluator.oracle_fingerprint(selected), evaluator.oracle_fingerprint(canonical))
+            selected.write_bytes(canonical.read_bytes() + b" ")
+            self.assertNotEqual(
+                evaluator.oracle_fingerprint(selected), evaluator.oracle_fingerprint(canonical))
+
+    def test_metric_sample_and_locked_case_failures_are_actionable(self):
+        report = {
+            "metrics": {"precisionAt1": 0.5},
+            "samples": {"retrieval": 1},
+            "cases": [{"id": "locked", "grades": [0], "actual": [{"Style Category": "Wrong"}]}],
+        }
+        manifest = {
+            "metrics": {"precisionAt1": {"floor": 0.8, "tolerance": 0.01}},
+            "sampleMinimums": {"retrieval": 2},
+            "lockedCases": {"locked": {"withinTop": 1, "minimumGrade": 2}},
+        }
+        manifest["splits"] = {"calibration": {"metrics": {}, "sampleMinimums": {}},
+                              "held_out": {"metrics": {}, "sampleMinimums": {}}}
+        report["splits"] = {"calibration": {"metrics": {}, "samples": {}},
+                            "held_out": {"metrics": {}, "samples": {}}}
+        failures = evaluator.check_thresholds(report, manifest)
+        self.assertEqual(len(failures), 3)
+        self.assertTrue(any("Wrong" in failure for failure in failures))
+
+    def test_manifest_rejects_missing_contract_sections(self):
+        errors = evaluator.validate_manifest({}, "fingerprint")
+        self.assertTrue(any("missing sections" in error for error in errors))
+        self.assertTrue(any("missing metrics" in error for error in errors))
+
+    def test_manifest_rejects_non_finite_and_invalid_sample_values(self):
+        manifest = {
+            "schemaVersion": 1,
+            "status": "approved",
+            "approvingMaintainer": "maintainer",
+            "units": "ratios",
+            "splitPolicy": {},
+            "runtimeFingerprint": "fingerprint",
+            "oracleFingerprint": "oracle",
+            "baselineRevision": "97eb2a2",
+            "metrics": {name: {"floor": float("nan")} for name in evaluator.REQUIRED_METRICS},
+            "sampleMinimums": {"cases": True},
+            "lockedCases": {"case": {}},
+            "splits": {
+                split: {
+                    "metrics": {name: {"floor": 0.0} for name in evaluator.REQUIRED_METRICS},
+                    "sampleMinimums": {"cases": 1},
+                } for split in ("calibration", "held_out")
+            },
+        }
+        errors = evaluator.validate_manifest(manifest, "fingerprint", "oracle")
+        self.assertTrue(any("finite" in error for error in errors))
+        self.assertTrue(any("non-negative integer" in error for error in errors))
+
+    def test_manifest_binds_oracle_and_validates_baseline_revision(self):
+        manifest = {
+            "schemaVersion": 1,
+            "status": "approved",
+            "approvingMaintainer": "maintainer",
+            "units": "ratios",
+            "splitPolicy": {},
+            "runtimeFingerprint": "runtime",
+            "oracleFingerprint": "wrong",
+            "baselineRevision": "not-a-revision",
+            "metrics": {name: {"floor": 0.0} for name in evaluator.REQUIRED_METRICS},
+            "sampleMinimums": {"cases": 1},
+            "lockedCases": {"case": {}},
+            "splits": {
+                split: {
+                    "metrics": {name: {"floor": 0.0} for name in evaluator.REQUIRED_METRICS},
+                    "sampleMinimums": {"cases": 1},
+                } for split in ("calibration", "held_out")
+            },
+        }
+        errors = evaluator.validate_manifest(manifest, "runtime", "expected")
+        self.assertTrue(any("oracleFingerprint" in error for error in errors))
+        self.assertTrue(any("baselineRevision" in error for error in errors))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/ui-ux-pro-max/scripts/tests/test_skill_script_paths.py

@@ -0,0 +1,82 @@
+"""Every script invocation in the shipped skill markdown resolves from the skill directory.
+
+Regression test for #474. The sub-skills ship in two copies (.claude/skills/<skill>/
+for the plugin, cli/assets/skills/<skill>/ for CLI installs) and land in layouts where
+neither the project root nor ~/.claude/skills/ is a valid anchor: the plugin cache, a
+project's .claude/skills/, ~/.claude/skills/ (--global), or a manual copy. The one anchor
+that exists in all of them is the skill's own directory, so documented commands use
+`scripts/<file>` for the skill's own scripts and `../<skill>/scripts/<file>` for a
+sibling sub-skill (the sub-skills are always installed side by side).
+
+This test extracts every `python|python3|node|bash <path>` invocation from every
+markdown file under both trees and asserts that the path is skill-relative and names a
+file that ships. The core skill's `${CLAUDE_PLUGIN_ROOT}/.claude/skills/...` form is
+resolved against the repository root, which is what that variable denotes under a
+plugin install - and accepted only in that file, because the sub-skills also ship
+through the CLI, where the variable does not exist. The grep-based path contract in check-asset-sync.yml is the negative
+side (no home-, project- or variable-rooted paths anywhere, code included); this is
+the positive side (every documented invocation points at a real file).
+"""
+
+import re
+import unittest
+from pathlib import Path
+
+REPO = next(
+    parent for parent in Path(__file__).resolve().parents
+    if (parent / "scripts" / "generate-catalog-summary.py").is_file()
+)
+SKILL_TREES = ("cli/assets/skills", ".claude/skills")
+# The only file that may use the plugin-root form: hand-authored for the plugin install
+# and not shipped by the CLI (sync-assets.mjs mirrors data/ and scripts/, never SKILL.md).
+# (Built from segments: the path contract in check-asset-sync.yml scans this file too.)
+PLUGIN_ONLY_FILE = Path(".claude") / "skills" / "ui-ux-pro-max" / "SKILL.md"
+INVOCATION = re.compile(r'(?<![\w/.-])(?:python3?|node|bash)\s+"?([^\s"`\']+\.(?:py|cjs|js|mjs|sh))')
+PLUGIN_ROOT = "${CLAUDE_PLUGIN_ROOT}/"
+
+
+def shipped_invocations():
+    for tree in SKILL_TREES:
+        for skill_dir in sorted((REPO / tree).iterdir()):
+            if not skill_dir.is_dir():
+                continue
+            for md in sorted(skill_dir.rglob("*.md")):
+                for lineno, line in enumerate(md.read_text(encoding="utf-8").splitlines(), 1):
+                    for match in INVOCATION.finditer(line):
+                        yield skill_dir, md, lineno, match.group(1)
+
+
+def resolve(skill_dir, md, path):
+    """Return (target, None) for a skill-relative path, or (None, reason)."""
+    if path.startswith(PLUGIN_ROOT):
+        if md.relative_to(REPO) != PLUGIN_ONLY_FILE:
+            return None, "the ${CLAUDE_PLUGIN_ROOT} form is only valid in the plugin-only core SKILL.md"
+        return REPO / path[len(PLUGIN_ROOT):], None
+    if path.startswith("scripts/"):
+        return skill_dir / path, None
+    if path.startswith("../"):
+        parts = path.split("/")
+        if len(parts) > 3 and parts[2] == "scripts" and (skill_dir.parent / parts[1]).is_dir():
+            return skill_dir.parent / parts[1] / "/".join(parts[2:]), None
+        return None, "a sibling invocation must be ../<skill>/scripts/<file> and the sibling must ship"
+    return None, "not skill-relative (expected scripts/<file> or ../<skill>/scripts/<file>)"
+
+
+class SkillScriptPathsTest(unittest.TestCase):
+    def test_every_shipped_markdown_invocation_resolves_from_the_skill_directory(self):
+        problems, seen = [], 0
+        for skill_dir, md, lineno, path in shipped_invocations():
+            seen += 1
+            target, reason = resolve(skill_dir, md, path)
+            if reason is None and not target.is_file():
+                reason = f"no such file: {target}"
+            if reason:
+                problems.append(f"{md.relative_to(REPO)}:{lineno}: {path} -- {reason}")
+        # Guard against a silently broken extractor: the two trees carry well over
+        # a hundred documented invocations between them.
+        self.assertGreater(seen, 100, f"extractor found only {seen} invocations")
+        self.assertEqual(problems, [], "\n" + "\n".join(problems))
+
+
+if __name__ == "__main__":
+    unittest.main()