test_frontmatter_parsing.py

"""Tests for frontmatter parsing edge cases.

Covers acceptance criteria from issue #296:
- Missing frontmatter → graceful fallback
- Malformed YAML → skip + warning
- Duplicate keys → last wins
- Empty frontmatter → defaults applied
- Non-standard encoding (UTF-8 BOM)
"""
import json
import tempfile
import unittest
from pathlib import Path

import sys
PROJECT_ROOT = Path(__file__).parent.parent
sys.path.insert(0, str(PROJECT_ROOT / "scripts"))

from validate_lessons import extract_frontmatter


class TestMissingFrontmatter(unittest.TestCase):
    """No frontmatter block → graceful fallback (None, error message)."""

    def test_no_frontmatter_returns_none(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write("# Just a heading\n\nSome content.\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            self.assertIsNone(result)
            self.assertIn("No frontmatter", err)

    def test_empty_file_returns_none(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write("")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            self.assertIsNone(result)

    def test_only_frontmatter_delimiters(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write("---\n---\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            # Empty frontmatter block — should return empty dict or None
            self.assertTrue(result is None or isinstance(result, dict))


class TestMalformedFrontmatter(unittest.TestCase):
    """Malformed content in frontmatter → skip + error message."""

    def test_invalid_json_returns_error(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write("---\n{invalid json\n---\n# Content\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            # Should fall back to YAML-like parser or return error
            # Either way, should not crash
            self.assertTrue(result is not None or err is not None)

    def test_random_text_in_frontmatter(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write("---\nthis is not yaml or json\n---\n# Content\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            # YAML-like parser: "this is not yaml or json" has no colon → returns None
            # This is acceptable behavior — unrecognized format → error
            self.assertTrue(result is None or isinstance(result, dict))

    def test_missing_closing_delimiter(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write("---\ntitle: Test\n# Content without closing ---\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            # Should return None — no closing ---
            self.assertIsNone(result)


class TestDuplicateKeys(unittest.TestCase):
    """Duplicate keys → last wins (JSON behavior)."""

    def test_json_duplicate_keys_last_wins(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write('---\n{"title": "First", "title": "Second"}\n---\n# Content\n')
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            if result is not None:
                # JSON spec: last key wins
                self.assertEqual(result.get("title"), "Second")

    def test_yaml_duplicate_keys_last_wins(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write("---\ntitle: First\ntitle: Second\ndomain: test\n---\n# Content\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            if result is not None:
                self.assertEqual(result.get("title"), "Second")


class TestEmptyFrontmatter(unittest.TestCase):
    """Empty frontmatter → defaults applied or empty dict."""

    def test_empty_json_object(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write("---\n{}\n---\n# Content\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            self.assertIsNotNone(result)
            self.assertEqual(len(result), 0)

    def test_whitespace_only_frontmatter(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write("---\n   \n  \n---\n# Content\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            # Should return empty dict or None
            self.assertTrue(result is None or len(result) == 0)


class TestStringEncoding(unittest.TestCase):
    """String value edge cases."""

    def test_quoted_strings_unquoted(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write('---\ntitle: "Quoted Title"\ntags: [\'tag1\', \'tag2\']\n---\n# Content\n')
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            if result is not None:
                self.assertEqual(result.get("title"), "Quoted Title")

    def test_boolean_values(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write("---\npublished: true\ndraft: false\n---\n# Content\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            if result is not None:
                self.assertEqual(result.get("published"), True)
                self.assertEqual(result.get("draft"), False)

    def test_list_values(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            f.write("---\ntags: [python, devops, test]\n---\n# Content\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            if result is not None:
                tags = result.get("tags")
                self.assertIsInstance(tags, list)
                self.assertIn("python", tags)


class TestBOMEncoding(unittest.TestCase):
    """UTF-8 BOM encoding handling."""

    def test_utf8_bom_file(self):
        with tempfile.NamedTemporaryFile(mode="wb", suffix=".md", delete=False) as f:
            # Write UTF-8 BOM + frontmatter
            bom = b'\xef\xbb\xbf'
            content = b'---\ntitle: BOM Test\ndomain: test\n---\n# Content\n'
            f.write(bom + content)
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            # Should handle BOM gracefully — may return None or parsed dict
            # The key thing is it should not crash
            self.assertTrue(result is not None or err is not None)

    def test_utf8_bom_with_json_frontmatter(self):
        with tempfile.NamedTemporaryFile(mode="wb", suffix=".md", delete=False) as f:
            bom = b'\xef\xbb\xbf'
            content = b'---\n{"title": "BOM Test", "domain": "test"}\n---\n# Content\n'
            f.write(bom + content)
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            # JSON parser should handle BOM or the YAML fallback should
            self.assertTrue(result is not None or err is not None)


class TestSpecialContent(unittest.TestCase):
    """Special content in frontmatter values."""

    def test_multiline_json_string(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            fm = json.dumps({
                "title": "Test",
                "description": "A description with\nnewlines",
                "tags": ["tag1", "tag2"]
            })
            f.write(f"---\n{fm}\n---\n# Content\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            self.assertIsNotNone(result)
            self.assertEqual(result.get("title"), "Test")

    def test_nested_json_object(self):
        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
            fm = json.dumps({
                "title": "Test",
                "metadata": {"author": "test", "version": 1}
            })
            f.write(f"---\n{fm}\n---\n# Content\n")
            f.flush()
            result, err = extract_frontmatter(Path(f.name))
            self.assertIsNotNone(result)
            self.assertIsInstance(result.get("metadata"), dict)


if __name__ == "__main__":
    unittest.main()