feat(plugin-loader): warn when a plugin declares a newer core requirement

src/__init__.py

@@ -4,5 +4,5 @@
 Core source package for the LED Matrix Display project.
 """
 
-__version__ = "1.0.0"
+__version__ = "3.1.0"
 

src/plugin_system/plugin_loader.py

@@ -683,6 +683,55 @@ def instantiate_plugin(
             self.logger.error(error_msg, exc_info=True)
             raise PluginError(error_msg, plugin_id=plugin_id) from e
 
+    @staticmethod
+    def _parse_semver(value: Any) -> Optional[Tuple[int, int, int]]:
+        """Parse 'X.Y.Z' (extra parts/suffixes ignored) into a comparable
+        3-tuple, or None when unparseable."""
+        if not isinstance(value, str):
+            return None
+        parts = value.strip().lstrip('v').split('.')
+        try:
+            nums = [int(''.join(ch for ch in p if ch.isdigit()) or 0) for p in parts[:3]]
+        except ValueError:
+            return None
+        while len(nums) < 3:
+            nums.append(0)
+        return tuple(nums)  # type: ignore[return-value]
+
+    def _warn_if_incompatible(self, plugin_id: str, manifest: Dict[str, Any]) -> None:
+        """Log one warning when a plugin declares a minimum LEDMatrix version
+        newer than the running core. Advisory only — never raises — so a
+        plugin that guards optional features with try/except keeps working.
+        """
+        declared = (
+            manifest.get('min_ledmatrix_version')
+            or manifest.get('requires', {}).get('min_ledmatrix_version')
+        )
+        if not declared:
+            versions = manifest.get('versions') or []
+            if versions and isinstance(versions[0], dict):
+                declared = (versions[0].get('ledmatrix_min_version')
+                            or versions[0].get('ledmatrix_min'))
+        needed = self._parse_semver(declared)
+        if needed is None:
+            return
+
+        from src import __version__ as core_version
+        current = self._parse_semver(core_version)
+        # Anti-spam guard: if the core's own version number is stale (below
+        # the ecosystem floor every shipped plugin declares), comparing would
+        # warn on nearly everything — skip with a debug note instead.
+        if current is None or current < (2, 0, 0):
+            self.logger.debug(
+                "Skipping version compatibility check for %s: core __version__ "
+                "(%s) is below the ecosystem floor", plugin_id, core_version)
+            return
+        if needed > current:
+            self.logger.warning(
+                "Plugin %s declares min LEDMatrix version %s but this core is %s — "
+                "features it relies on may be missing; update the core or expect "
+                "degraded fallbacks", plugin_id, declared, core_version)
+
     def load_plugin(
         self,
         plugin_id: str,
@@ -715,6 +764,8 @@ def load_plugin(
         Raises:
             PluginError: If loading fails
         """
+        self._warn_if_incompatible(plugin_id, manifest)
+
         # Install dependencies if needed
         if install_deps:
             if plugins_dir is None:

test/test_loader_compat_warning.py

@@ -0,0 +1,70 @@
+"""Tests for the plugin loader's advisory version-compatibility warning."""
+
+import logging
+
+import pytest
+
+from src.plugin_system.plugin_loader import PluginLoader
+
+
+@pytest.fixture
+def loader():
+    return PluginLoader(logger=logging.getLogger("test-loader"))
+
+
+def _warnings(caplog):
+    return [r for r in caplog.records if r.levelno == logging.WARNING]
+
+
+class TestParseSemver:
+    def test_basic(self, loader):
+        assert loader._parse_semver("3.1.0") == (3, 1, 0)
+        assert loader._parse_semver("v2.0") == (2, 0, 0)
+        assert loader._parse_semver("2.0.0-beta.1") == (2, 0, 0)
+
+    def test_unparseable(self, loader):
+        assert loader._parse_semver(None) is None
+        assert loader._parse_semver(123) is None
+
+
+class TestWarnIfIncompatible:
+    def test_warns_when_plugin_needs_newer_core(self, loader, caplog, monkeypatch):
+        import src
+        monkeypatch.setattr(src, "__version__", "3.1.0")
+        with caplog.at_level(logging.WARNING, logger="test-loader"):
+            loader._warn_if_incompatible("p", {"min_ledmatrix_version": "9.0.0"})
+        assert len(_warnings(caplog)) == 1
+        assert "9.0.0" in _warnings(caplog)[0].message
+
+    def test_silent_when_compatible(self, loader, caplog, monkeypatch):
+        import src
+        monkeypatch.setattr(src, "__version__", "3.1.0")
+        with caplog.at_level(logging.WARNING, logger="test-loader"):
+            loader._warn_if_incompatible("p", {"min_ledmatrix_version": "2.0.0"})
+        assert not _warnings(caplog)
+
+    def test_silent_when_field_absent(self, loader, caplog):
+        with caplog.at_level(logging.WARNING, logger="test-loader"):
+            loader._warn_if_incompatible("p", {"name": "no version fields"})
+        assert not _warnings(caplog)
+
+    def test_reads_requires_and_versions_spellings(self, loader, caplog, monkeypatch):
+        import src
+        monkeypatch.setattr(src, "__version__", "3.1.0")
+        with caplog.at_level(logging.WARNING, logger="test-loader"):
+            loader._warn_if_incompatible(
+                "a", {"requires": {"min_ledmatrix_version": "9.0.0"}})
+            loader._warn_if_incompatible(
+                "b", {"versions": [{"ledmatrix_min_version": "9.0.0"}]})
+            loader._warn_if_incompatible(
+                "c", {"versions": [{"ledmatrix_min": "9.0.0"}]})
+        assert len(_warnings(caplog)) == 3
+
+    def test_stale_core_version_skips_comparison(self, loader, caplog, monkeypatch):
+        # Anti-spam guard: a core whose __version__ is below the ecosystem
+        # floor must not warn about every plugin.
+        import src
+        monkeypatch.setattr(src, "__version__", "1.0.0")
+        with caplog.at_level(logging.WARNING, logger="test-loader"):
+            loader._warn_if_incompatible("p", {"min_ledmatrix_version": "2.0.0"})
+        assert not _warnings(caplog)