Add reference-anchored concept generation

tools/test_scene_concepts.py

@@ -1,5 +1,7 @@
+import json
 import tempfile
 import unittest
+from unittest import mock
 from pathlib import Path
 
 from PIL import Image
@@ -31,6 +33,62 @@ class CatalogueTests(unittest.TestCase):
         self.assertTrue(sc.raw_path("asphalt").is_relative_to(sc.RAW_DIR))
 
 
+class ReferenceGateTests(unittest.TestCase):
+    ROOT = Path(sc.__file__).resolve().parent.parent
+
+    def test_refs_photo_listed_in_sidecar_passes_with_provenance(self):
+        result = sc._reference_source(
+            self.ROOT / "docs/screens/refs/hollywood/"
+            "el-capitan-facade-day-wikimedia-2009-10-27.jpg")
+        self.assertTrue(result["checked"])
+        self.assertEqual(result["licence"], "CC BY 2.0")
+        self.assertIn("commons.wikimedia.org", result["page"])
+
+    def test_refs_photo_missing_from_sidecar_is_refused(self):
+        with tempfile.TemporaryDirectory(dir=self.ROOT / "docs/screens/refs") as tmp:
+            path = Path(tmp) / "unlisted.jpg"
+            path.write_bytes(b"x")
+            with self.assertRaises(SystemExit):
+                sc._reference_source(path)
+
+    def test_outside_photo_requires_the_explicit_override(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "photo.jpg"
+            path.write_bytes(b"x")
+            with self.assertRaises(SystemExit):
+                sc._reference_source(path)
+            result = sc._reference_source(path, allow_unchecked=True)
+            self.assertFalse(result["checked"])
+            self.assertEqual(result["licence"], "unchecked")
+
+    def test_missing_file_is_refused(self):
+        with self.assertRaises(SystemExit):
+            sc._reference_source(self.ROOT / "docs/screens/refs/nope.jpg")
+
+    def test_generate_one_writes_reference_provenance(self):
+        reference = {"path": self.ROOT / "docs/screens/refs/hollywood/"
+                     "el-capitan-facade-day-wikimedia-2009-10-27.jpg",
+                     "licence": "CC BY 2.0", "page": "https://commons/x",
+                     "checked": True}
+        class FakeImage:
+            def convert(self, mode):
+                return Image.new("RGB", (1600, 900))
+        with tempfile.TemporaryDirectory() as tmp:
+            out = Path(tmp) / "hollywood_boulevard_entrance_day.png"
+            with mock.patch.object(sc.generate_textures, "generate_image",
+                                   return_value=FakeImage()) as mocked, \
+                    mock.patch.object(sc, "next_free_path", return_value=out), \
+                    mock.patch.object(sc, "_rel", side_effect=str):
+                sc.generate_one("hollywood_boulevard_entrance_day", "m", 1536,
+                                reference=reference)
+            call = mocked.call_args
+            self.assertIn("keep the building", call.args[0].lower())
+            self.assertEqual(call.kwargs["reference_path"], reference["path"])
+            provenance = json.loads(out.with_suffix(".refgen.json").read_text())
+            self.assertEqual(provenance["reference"]["licence"], "CC BY 2.0")
+            self.assertTrue(provenance["reference"]["licence_checked"])
+
+
 class NoOverwriteTests(unittest.TestCase):
     def test_next_free_path_never_returns_an_existing_file(self):
         with tempfile.TemporaryDirectory() as tmp: