1"""Unit tests for the shared SKILL.md frontmatter parser.
2 
3Run directly or via the standard library test runner:
4 
5    python3 -m unittest researcher.scripts.tests.test_skill_frontmatter
6    python3 researcher/scripts/tests/test_skill_frontmatter.py
7"""
8 
9from __future__ import annotations
10 
11import sys
12import unittest
13from pathlib import Path
14 
15SCRIPTS_DIR = Path(__file__).resolve().parents[1]
16REPO_ROOT = SCRIPTS_DIR.parents[1]
17if str(SCRIPTS_DIR) not in sys.path:
18    sys.path.insert(0, str(SCRIPTS_DIR))
19 
20import skill_frontmatter as sf  # noqa: E402
21 
22 
23VALID_DESC = "A valid description that is comfortably longer than the minimum."
24 
25 
26class SplitFrontmatterTests(unittest.TestCase):
27    def test_lf(self) -> None:
28        inner, body = sf.split_frontmatter(f"---\nname: foo\ndescription: {VALID_DESC}\n---\n# Body\ntext")
29        self.assertIn("name: foo", inner)
30        self.assertEqual(body, "# Body\ntext")
31 
32    def test_crlf(self) -> None:
33        text = f"---\r\nname: foo\r\ndescription: {VALID_DESC}\r\n---\r\n# Body\r\ntext"
34        inner, body = sf.split_frontmatter(text)
35        self.assertIn("name: foo", inner)
36        self.assertFalse(inner.endswith("\r"))
37        self.assertEqual(body, "# Body\r\ntext")
38 
39    def test_bom(self) -> None:
40        text = f"\ufeff---\nname: foo\ndescription: {VALID_DESC}\n---\nbody"
41        inner, body = sf.split_frontmatter(text)
42        self.assertIn("name: foo", inner)
43        self.assertEqual(body, "body")
44 
45    def test_no_frontmatter(self) -> None:
46        inner, body = sf.split_frontmatter("# Heading\nno frontmatter")
47        self.assertIsNone(inner)
48        self.assertEqual(body, "# Heading\nno frontmatter")
49 
50    def test_unterminated_frontmatter(self) -> None:
51        inner, _ = sf.split_frontmatter("---\nname: foo\nnever closes")
52        self.assertIsNone(inner)
53 
54    def test_longer_dash_line_is_not_a_closing_fence(self) -> None:
55        text = f"---\nname: foo\ndescription: {VALID_DESC}\n------\nbody"
56        inner, _ = sf.split_frontmatter(text)
57        self.assertIsNone(inner)
58 
59    def test_closing_fence_allows_trailing_spaces(self) -> None:
60        text = f"---\nname: foo\ndescription: {VALID_DESC}\n---   \nbody"
61        inner, body = sf.split_frontmatter(text)
62        self.assertIn("name: foo", inner)
63        self.assertEqual(body, "body")
64 
65 
66class ParseFrontmatterTests(unittest.TestCase):
67    def test_valid_plain(self) -> None:
68        data, issues = sf.parse_frontmatter(f"---\nname: foo\ndescription: {VALID_DESC}\n---\nbody")
69        self.assertEqual(issues, [])
70        self.assertEqual(data["name"], "foo")
71        self.assertEqual(data["description"], VALID_DESC)
72 
73    def test_quoted_description_with_colon(self) -> None:
74        text = '---\nname: foo\ndescription: "This skill: handles colons safely and clearly."\n---\nbody'
75        data, issues = sf.parse_frontmatter(text)
76        self.assertEqual(issues, [])
77        self.assertEqual(data["description"], "This skill: handles colons safely and clearly.")
78 
79    def test_block_scalar_description(self) -> None:
80        text = "---\nname: foo\ndescription: >\n  multi line\n  description text that is long enough\n---\nbody"
81        data, issues = sf.parse_frontmatter(text)
82        self.assertEqual(issues, [])
83        self.assertIn("multi line description", data["description"])
84 
85    def test_missing_frontmatter(self) -> None:
86        _data, issues = sf.parse_frontmatter("# No frontmatter")
87        self.assertTrue(any("delimiter" in i for i in issues))
88 
89    def test_missing_name(self) -> None:
90        _data, issues = sf.parse_frontmatter(f"---\ndescription: {VALID_DESC}\n---\nbody")
91        self.assertIn("missing name", issues)
92 
93    def test_missing_description(self) -> None:
94        _data, issues = sf.parse_frontmatter("---\nname: foo\n---\nbody")
95        self.assertIn("missing description", issues)
96 
97    def test_short_description(self) -> None:
98        _data, issues = sf.parse_frontmatter("---\nname: foo\ndescription: too short\n---\nbody")
99        self.assertTrue(any("too short" in i for i in issues))
100 
101    def test_non_mapping_frontmatter(self) -> None:
102        if sf.yaml is None:
103            self.skipTest("PyYAML required for mapping validation")
104        _data, issues = sf.parse_frontmatter("---\n- just\n- a\n- list\n---\nbody")
105        self.assertTrue(any("mapping" in i for i in issues))
106 
107    def test_non_string_name_is_rejected(self) -> None:
108        _data, issues = sf.parse_frontmatter(f"---\nname: true\ndescription: {VALID_DESC}\n---\nbody")
109        self.assertTrue(any("name must be a string" in i for i in issues), issues)
110 
111    def test_non_string_description_is_rejected(self) -> None:
112        _data, issues = sf.parse_frontmatter("---\nname: foo\ndescription: true\n---\nbody")
113        self.assertTrue(any("description must be a string" in i for i in issues), issues)
114 
115 
116@unittest.skipIf(sf.yaml is None, "PyYAML required for strict-YAML regression test")
117class StrictYamlRegressionTests(unittest.TestCase):
118    """Guards the exact bug fixed in this PR: unquoted colons in descriptions."""
119 
120    def test_unquoted_colon_is_rejected(self) -> None:
121        text = "---\nname: foo\ndescription: This skill: does several things without quoting\n---\nbody"
122        _data, issues = sf.parse_frontmatter(text)
123        self.assertTrue(any("invalid YAML" in i for i in issues), issues)
124 
125 
126class FallbackParserTests(unittest.TestCase):
127    def test_fallback_plain(self) -> None:
128        inner = f"name: foo\ndescription: {VALID_DESC}"
129        data, issues = sf._parse_frontmatter_fallback(inner, [])
130        self.assertEqual(issues, [])
131        self.assertEqual(data["description"], VALID_DESC)
132 
133    def test_fallback_block_scalar(self) -> None:
134        inner = "name: foo\ndescription: >\n  multi line\n  description long enough now"
135        data, issues = sf._parse_frontmatter_fallback(inner, [])
136        self.assertEqual(issues, [])
137        self.assertIn("multi line description", data["description"])
138 
139 
140class FormatFrontmatterTests(unittest.TestCase):
141    def test_round_trip_with_colon(self) -> None:
142        desc = "This skill: handles colons, commas, and 'quotes' all at once."
143        rendered = sf.format_frontmatter("foo-bar", desc)
144        data, issues = sf.parse_frontmatter(rendered + "body")
145        self.assertEqual(issues, [])
146        self.assertEqual(data["name"], "foo-bar")
147        self.assertEqual(data["description"], desc)
148 
149 
150class CorpusIntegrationTests(unittest.TestCase):
151    """Every published skill must parse cleanly with zero issues."""
152 
153    def test_all_skills_parse_clean(self) -> None:
154        skills_dir = REPO_ROOT / "skills"
155        skill_files = sorted(skills_dir.glob("*/SKILL.md"))
156        self.assertTrue(skill_files, "no skills found")
157        for path in skill_files:
158            with self.subTest(skill=path.parent.name):
159                text = path.read_text(encoding="utf-8")
160                data, issues = sf.parse_frontmatter(text)
161                self.assertEqual(issues, [], f"{path.parent.name}: {issues}")
162                self.assertEqual(data["name"], path.parent.name)
163                self.assertRegex(text, r'\ndescription: "')
164 
165    @unittest.skipIf(sf.yaml is None, "PyYAML required for strict example validation")
166    def test_example_and_template_frontmatter_is_strict_yaml(self) -> None:
167        """Demo and template skills must be strict-YAML parseable so developers can copy them."""
168        extra = [REPO_ROOT / "template" / "SKILL.md", REPO_ROOT / "SKILL.md"]
169        example_skills = sorted((REPO_ROOT / "examples").glob("**/SKILL.md"))
170        for path in extra + example_skills:
171            if not path.exists():
172                continue
173            with self.subTest(skill=str(path.relative_to(REPO_ROOT))):
174                text = path.read_text(encoding="utf-8")
175                inner, _ = sf.split_frontmatter(text)
176                self.assertIsNotNone(inner, f"{path} missing frontmatter")
177                loaded = sf.yaml.safe_load(inner)
178                self.assertIsInstance(loaded, dict)
179                self.assertTrue(str(loaded.get("description", "")).strip())
180                self.assertRegex(text, r'\ndescription: "')
181 
182 
183if __name__ == "__main__":
184    unittest.main()
185