"""Core catalog contracts, independent of the editable example sites."""
import unittest
from pathlib import Path
from tempfile import TemporaryDirectory
from unittest.mock import patch
from site_engine.core.models import parse_fragment
from site_engine.core.registry import BUILTIN_DIR, load_site
from site_engine.errors import Report
from site_engine.parsing.yamlio import dump_yaml
class FragmentCatalogTest(unittest.TestCase):
def setUp(self):
temporary = TemporaryDirectory()
self.addCleanup(temporary.cleanup)
self.root = Path(temporary.name)
self.site = self.root / "site"
self.builtin = self.root / "builtin"
self.write(self.site / "site.yaml", "name: Catalog test\n")
def write(self, path, text):
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(text, encoding="utf-8")
def fragment(self, folder, fid="sample", *, builtin=False, **values):
base = self.builtin if builtin else self.site
directory = base / "fragments" / folder
manifest = directory / "fragment.yaml"
self.write(manifest, dump_yaml({"id": fid, "name": "Catalog name", **values}))
self.write(directory / "template.html.j2", "
Unused
") malformed = { "empty": "", "null": "null\n", "scalar": "false\n", "list": "- item\n", "no_id": "name: Missing ID\n", "yaml": "id: [\n", } for name, text in malformed.items(): self.write(self.site / f"fragments/category/{name}/fragment.yaml", text) reg = self.load() self.assertEqual(reg.fragments, {}) expected = { ("E_FRAGMENT_ID" if name == "no_id" else "E_YAML" if name == "yaml" else "E_FRAGMENT_SHAPE", f"fragments/category/{name}/fragment.yaml") for name in malformed } self.assertEqual({(i.code, i.path) for i in reg.report.issues}, expected) self.assertEqual(len(reg.report.issues), len(malformed)) def test_missing_template_reports_discovered_nested_manifest(self): manifest = self.fragment("Category/group/item") manifest.with_name("template.html.j2").unlink() self.assert_issues(self.load(), [ ("E_FRAGMENT_TEMPLATE", "fragments/Category/group/item/fragment.yaml"), ]) def test_inline_preview_compatibility_and_defaults_are_not_materialized(self): self.fragment("flat", fields=[ {"key": "title", "type": "text", "required": True}, {"key": "variant", "type": "select", "options": ["light", "dark"], "default": "light"}, ], preview={"title": "Inline"}) reg = self.load() self.assertTrue(reg.report.ok, reg.report.issues) fragment = reg.fragments["sample"] self.assertEqual(fragment.preview, {"title": "Inline"}) self.assertEqual(fragment.fields[1].default, "light") def test_sidecar_merge_is_per_prop_and_name_does_not_rename_fragment(self): manifest = self.fragment("Category/item", fields=[ {"key": "title", "type": "text"}, {"key": "keep", "type": "text"}, {"key": "name", "type": "text"}, {"key": "settings", "type": "group", "fields": [ {"key": "a", "type": "number"}, {"key": "b", "type": "number"}, ]}, {"key": "enabled", "type": "boolean", "default": True}, ], preview={"title": "Inline", "keep": "Kept", "settings": {"a": 1, "b": 2}}) self.sidecar(manifest, {"name": "Preview label", "props": { "title": "Sidecar", "name": "Name prop", "settings": {"a": 3}, "enabled": False, }}) reg = self.load() self.assertTrue(reg.report.ok, reg.report.issues) fragment = reg.fragments["sample"] self.assertEqual(fragment.name, "Catalog name") self.assertEqual(fragment.preview, { "title": "Sidecar", "keep": "Kept", "name": "Name prop", "settings": {"a": 3}, "enabled": False, }) self.assertNotIn("props", fragment.preview) self.assertTrue(fragment.fields[-1].default) def test_sidecar_without_name_or_inline_preview_for_builtin_and_site(self): for builtin, fid in ((True, "builtin_sample"), (False, "site_sample")): manifest = self.fragment("Category/item", fid, builtin=builtin, fields=[{"key": "title", "type": "text"}]) self.sidecar(manifest, {"props": {"title": fid}}) reg = self.load() self.assertTrue(reg.report.ok, reg.report.issues) for fid in ("builtin_sample", "site_sample"): self.assertEqual(reg.fragments[fid].preview, {"title": fid}) self.assertEqual(reg.fragments[fid].name, "Catalog name") def test_invalid_inline_preview_is_diagnosed_and_normalized_by_parser(self): manifest = self.fragment("item") for bad in (None, False, 0, "", "text", [], ["title"]): with self.subTest(preview=bad): report = Report() fragment = parse_fragment({"id": "sample", "preview": bad}, "fragments/item/fragment.yaml", manifest.parent, False, report) self.assertIsNotNone(fragment) self.assertEqual(fragment.preview, {}) self.assertEqual(fragment.preview.get("title"), None) self.assertEqual([(i.code, i.path) for i in report.issues], [ ("E_FRAGMENT_PREVIEW", "fragments/item/fragment.yaml:preview"), ]) def test_invalid_inline_does_not_prevent_valid_sidecar_loading(self): manifest = self.fragment("item", preview=["bad"], fields=[{"key": "title", "type": "text"}]) self.sidecar(manifest, {"props": {"title": "Valid"}}) reg = self.load() self.assertEqual(reg.fragments["sample"].preview, {"title": "Valid"}) self.assert_issues(reg, [("E_FRAGMENT_PREVIEW", "fragments/item/fragment.yaml:preview")]) def test_invalid_sidecar_envelope_and_props_shapes(self): manifest = self.fragment("Category/deeper/item", preview={"title": "Inline"}, fields=[{"key": "title", "type": "text"}]) rel = "fragments/Category/deeper/item/preview.yaml" cases = [(None, rel), (False, rel), ("text", rel), ([], rel), ({}, rel + ":props"), ({"name": "Only a label"}, rel + ":props")] cases += [({"props": bad}, rel + ":props") for bad in (None, False, 0, "", "text", [], ["item"])] for raw, path in cases: with self.subTest(raw=raw): self.sidecar(manifest, raw) reg = self.load() self.assertEqual(reg.fragments["sample"].preview, {"title": "Inline"}) self.assert_issues(reg, [("E_FRAGMENT_PREVIEW", path)]) def test_sidecar_name_and_unknown_keys_have_precise_paths(self): manifest = self.fragment("item") for name in (None, False, 12, [], {}): with self.subTest(name=name): self.sidecar(manifest, {"name": name, "props": {}}) self.assert_issues(self.load(), [ ("E_FRAGMENT_PREVIEW", "fragments/item/preview.yaml:name"), ]) self.sidecar(manifest, {"props": {}, "unknown": True}) self.assert_issues(self.load(), [ ("E_FRAGMENT_PREVIEW", "fragments/item/preview.yaml:unknown"), ]) def test_sidecar_yaml_errors_use_existing_yaml_diagnostics(self): manifest = self.fragment("Group/item", builtin=True, fields=[{"key": "title", "type": "text"}], preview={"title": "Inline"}) for text in ("props: [\n", "props: {}\nprops: {}\n", "props: &x {}\nname: *x\n", ""): with self.subTest(text=text): self.write(manifest.with_name("preview.yaml"), text) reg = self.load() self.assertEqual(reg.fragments["sample"].preview, {"title": "Inline"}) self.assert_issues(reg, [ ("E_FRAGMENT_PREVIEW" if text == "" else "E_YAML", "builtin/Group/item/preview.yaml"), ]) def test_sidecar_read_errors_are_reported_without_swallowing_them(self): manifest = self.fragment("item") sidecar = manifest.with_name("preview.yaml") self.sidecar(manifest, {"props": {}}) read_text = Path.read_text def unreadable(path, *args, **kwargs): if path == sidecar: raise PermissionError("test read denied") return read_text(path, *args, **kwargs) with patch.object(Path, "read_text", unreadable): reg = self.load() self.assert_issues(reg, [("E_YAML", "fragments/item/preview.yaml")]) self.assertIn("test read denied", reg.report.issues[0].message) self.assertEqual(reg.fragments["sample"].preview, {}) sidecar.write_bytes(b"props: \xff") self.assert_issues(self.load(), [("E_YAML", "fragments/item/preview.yaml")]) def test_preview_values_accept_core_types_without_resolving_references(self): fields, props = [], {} examples = { "text": "Title", "textarea": "Paragraph", "markdown": "**Text**", "slug": "a-slug", "color": "#fff", "icon": "star", "asset": "/missing.png", "number": 2.5, "boolean": False, "date": "2026-11-13", "datetime": "2026-11-13T10:00:00Z", "select": "one", "multiselect": ["one"], "ref": "missing-entry", "refs": ["missing-entry"], "link": {"page": "missing-page"}, "query": {"query": {"collection": "missing-collection", "limit": 2}}, "json": {"anything": [1, False]}, } for kind, value in examples.items(): field = {"key": kind, "type": kind} if kind in ("select", "multiselect"): field["options"] = ["one", "two"] if kind in ("ref", "refs"): field["to"] = "missing-collection" fields.append(field) props[kind] = value fields += [ {"key": "group", "type": "group", "fields": [{"key": "x", "type": "number"}]}, {"key": "list", "type": "list", "fields": [{"key": "x", "type": "boolean"}]}, {"key": "strings", "type": "list", "of": "text"}, {"key": "binding", "type": "text"}, {"key": "omitted_required", "type": "text", "required": True}, ] props.update(group={"x": 1}, list=[{"x": True}], strings=["a", "b"], binding={"bind": "entry.missing"}) for source in ("inline", "sidecar"): with self.subTest(source=source): manifest = self.fragment("item", fields=fields, **({"preview": props} if source == "inline" else {})) if source == "sidecar": self.sidecar(manifest, {"props": props}) reg = self.load() self.assertTrue(reg.report.ok, reg.report.issues) self.assertEqual(reg.fragments["sample"].preview, props) def test_invalid_preview_values_use_core_schema_paths_for_both_sources(self): cases = [ ({"type": "text"}, 12, "", "E_TYPE"), ({"type": "number"}, True, "", "E_TYPE"), ({"type": "boolean"}, "true", "", "E_TYPE"), ({"type": "select", "options": ["a", "b"]}, "c", "", "E_SELECT_VALUE"), ({"type": "multiselect", "options": ["a"]}, ["b"], "", "E_SELECT_VALUE"), ({"type": "date"}, 5, "", "E_TYPE"), ({"type": "datetime"}, [], "", "E_TYPE"), ({"type": "ref", "to": "missing"}, 12, "", "E_TYPE"), ({"type": "refs", "to": "missing"}, [1], "", "E_TYPE"), ({"type": "query"}, {"collection": "missing"}, "", "E_VALUE_SHAPE"), ({"type": "link"}, {"page": 12}, "", "E_VALUE_SHAPE"), ({"type": "text"}, {"bind": "unknown.x"}, "", "E_VALUE_SHAPE"), ({"type": "text"}, "{{ page.title }}", "", "E_TEMPLATE_IN_DATA"), ({"type": "group", "fields": [{"key": "n", "type": "number"}]}, {"n": "bad"}, ".n", "E_TYPE"), ({"type": "group", "fields": [{"key": "n", "type": "number"}]}, {"unknown": 1}, ".unknown", "E_PROP_UNKNOWN"), ({"type": "list", "of": "number"}, [1, "bad"], "[1]", "E_TYPE"), ({"type": "list", "fields": [{"key": "flag", "type": "boolean"}]}, [{"flag": "bad"}], "[0].flag", "E_TYPE"), ] for source in ("inline", "sidecar"): for schema, value, suffix, code in cases: with self.subTest(source=source, schema=schema, value=value): manifest = self.fragment("item", fields=[{"key": "value", **schema}], **({"preview": {"value": value}} if source == "inline" else {})) sidecar = manifest.with_name("preview.yaml") if source == "inline": sidecar.unlink(missing_ok=True) else: self.sidecar(manifest, {"props": {"value": value}}) reg = self.load() prefix = ("fragment.yaml:preview" if source == "inline" else "preview.yaml:props") self.assert_issues(reg, [(code, f"fragments/item/{prefix}.value{suffix}")]) def test_unknown_preview_props_are_diagnosed(self): manifest = self.fragment("item", preview={"unknown_inline": True}) self.sidecar(manifest, {"props": {"unknown_sidecar": True}}) self.assert_issues(self.load(), [ ("E_PROP_UNKNOWN", "fragments/item/fragment.yaml:preview.unknown_inline"), ("E_PROP_UNKNOWN", "fragments/item/preview.yaml:props.unknown_sidecar"), ]) def test_invalid_inline_value_is_reported_even_if_sidecar_overrides_it(self): manifest = self.fragment("item", fields=[{"key": "title", "type": "text"}], preview={"title": 42}) self.sidecar(manifest, {"props": {"title": "Override"}}) reg = self.load() self.assertEqual(reg.fragments["sample"].preview, {"title": "Override"}) self.assert_issues(reg, [("E_TYPE", "fragments/item/fragment.yaml:preview.title")]) def test_shipped_builtins_still_load_with_valid_flat_previews(self): reg = load_site(self.site, builtin_dir=BUILTIN_DIR) self.assertTrue(reg.report.ok, reg.report.issues) self.assertEqual(len(reg.fragments), len(list((BUILTIN_DIR / "fragments").rglob("fragment.yaml")))) self.assertTrue(reg.fragments) for fragment in reg.fragments.values(): self.assertTrue(fragment.builtin) self.assertIsInstance(fragment.preview, dict) if __name__ == "__main__": unittest.main()