LEDMatrix/test/test_discovery_path_contract.py

"""
Drift guard: three components independently answer "where is plugin X?" and
their answers must stay coherent — plus the `.standalone-backup-` naming
contract that install/rollback shares with discovery.

The three resolvers:
1. PluginManager._scan_directory_for_plugins — scans ONLY the configured dir.
2. PluginStoreManager._find_plugin_path — configured dir, then a sibling
   `plugins/` fallback derived from the configured dir's parent.
3. SchemaManager.get_schema_path — configured dir, then project-root
   `plugins/`, then `plugin-repos/`, then case-insensitive scans.

The divergence is characterized (a plugin visible to the store/schema
fallbacks but invisible to discovery is a real support-issue shape) so any
change to the fallback chains is a deliberate one.

The `.standalone-backup-` contract: store_manager renames a plugin dir aside
with that substring during install/rollback; discovery MUST skip such dirs
or a half-finished install would surface a ghost plugin. The substring now
lives once, as plugin_dirs.BACKUP_MARKER, which both sides import; its value
is pinned because debris already on devices carries exactly that text.

All of them now resolve through src/plugin_system/plugin_dirs.py; the
per-caller differences pinned here are explicit arguments there. The rules
themselves are covered table-style in test_plugin_dirs.py.
"""

import json
import logging
import threading
from pathlib import Path

import pytest

from src.plugin_system.plugin_manager import PluginManager
from src.plugin_system.schema_manager import SchemaManager
from src.plugin_system.store_manager import PluginStoreManager


def _write_plugin(base: Path, plugin_id: str, dir_name: str = None):
    plugin_dir = base / (dir_name or plugin_id)
    plugin_dir.mkdir(parents=True)
    (plugin_dir / "manifest.json").write_text(json.dumps({
        "id": plugin_id, "name": plugin_id, "version": "1.0.0",
    }))
    (plugin_dir / "config_schema.json").write_text(json.dumps({
        "type": "object", "properties": {"enabled": {"type": "boolean"}},
    }))
    return plugin_dir


def _scanner():
    """A PluginManager stripped to just its discovery machinery — the full
    constructor wires config/schema/health managers this test doesn't need."""
    pm = object.__new__(PluginManager)
    pm.logger = logging.getLogger("test_discovery_path_contract")
    pm._discovery_lock = threading.Lock()
    pm.plugin_manifests = {}
    pm.plugin_directories = {}
    return pm


class TestResolversAgreeOnConfiguredDir:
    def test_all_three_find_a_plugin_in_the_configured_dir(self, tmp_path):
        plugins_dir = tmp_path / "plugin-repos"
        plugin_dir = _write_plugin(plugins_dir, "demo-plugin")

        found = _scanner()._scan_directory_for_plugins(plugins_dir)
        assert found == ["demo-plugin"]

        store = PluginStoreManager(
            plugins_dir=str(plugins_dir),
            uninstalled_registry_path=str(tmp_path / "uninstalled.json"))
        assert store._find_plugin_path("demo-plugin") == plugin_dir

        schema = SchemaManager(plugins_dir=plugins_dir, project_root=tmp_path)
        assert schema.get_schema_path("demo-plugin") == \
            plugin_dir / "config_schema.json"


class TestFallbackDivergence:
    def test_plugin_only_in_plugins_dir_fallback(self, tmp_path):
        """Characterized divergence: configured dir is plugin-repos/, but the
        plugin sits in a sibling plugins/. The store and schema fallbacks
        find it; discovery does NOT — so the plugin is installable/
        configurable but never loads. Pinned so a change to any fallback
        chain shows up here."""
        configured = tmp_path / "plugin-repos"
        configured.mkdir()
        legacy_dir = _write_plugin(tmp_path / "plugins", "legacy-plugin")

        # Discovery: invisible.
        assert _scanner()._scan_directory_for_plugins(configured) == []

        # Store fallback: visible (parent-of-configured / 'plugins').
        store = PluginStoreManager(
            plugins_dir=str(configured),
            uninstalled_registry_path=str(tmp_path / "uninstalled.json"))
        assert store._find_plugin_path("legacy-plugin") == legacy_dir

        # Schema fallback: visible (project_root / 'plugins').
        schema = SchemaManager(plugins_dir=configured, project_root=tmp_path)
        assert schema.get_schema_path("legacy-plugin") == \
            legacy_dir / "config_schema.json"

    def test_schema_manager_probes_plugins_before_plugin_repos(self, tmp_path):
        # Documented order (also in CLAUDE.md): plugins/ wins over
        # plugin-repos/ when the same id exists in both.
        in_plugins = _write_plugin(tmp_path / "plugins", "dupe")
        _write_plugin(tmp_path / "plugin-repos", "dupe")
        schema = SchemaManager(plugins_dir=None, project_root=tmp_path)
        assert schema.get_schema_path("dupe") == \
            in_plugins / "config_schema.json"

    def test_schema_manager_case_insensitive_fallback(self, tmp_path):
        plugin_dir = _write_plugin(tmp_path / "plugins", "MyPlugin",
                                   dir_name="MyPlugin")
        schema = SchemaManager(plugins_dir=None, project_root=tmp_path)
        assert schema.get_schema_path("myplugin") == \
            plugin_dir / "config_schema.json"


class TestRegistryIdVersusDirectoryName:
    """install_plugin() renames a plugin's directory to the MANIFEST id when it
    differs from the REGISTRY id, so `stocks` in the registry lands in
    `ledmatrix-stocks/`. Every path lookup is by directory name, so
    update_plugin("stocks") used to find nothing and report the plugin as not
    installed -- silently. Four installed plugins hit this in practice
    (leaderboard, music, stocks, weather): the user clicks update, nothing
    happens, no error, and they stay on a stale version indefinitely.
    """

    def test_resolves_a_plugin_whose_directory_name_differs_from_its_id(self, tmp_path):
        configured = tmp_path / "plugin-repos"
        configured.mkdir()
        plugin_dir = _write_plugin(configured, "stocks", dir_name="ledmatrix-stocks")

        store = PluginStoreManager(plugins_dir=str(configured))
        assert store._find_plugin_path("stocks") == plugin_dir

    def test_direct_directory_hit_still_wins(self, tmp_path):
        """The manifest scan is a last resort. A directory named for the id
        must still be preferred, so the two documented lookups above keep
        their exact meaning."""
        configured = tmp_path / "plugin-repos"
        configured.mkdir()
        direct = _write_plugin(configured, "demo", dir_name="demo")
        # A second directory whose manifest claims the same id.
        _write_plugin(configured, "demo", dir_name="zz-other-demo")

        store = PluginStoreManager(plugins_dir=str(configured))
        assert store._find_plugin_path("demo") == direct

    def test_unknown_id_is_still_not_found(self, tmp_path):
        configured = tmp_path / "plugin-repos"
        configured.mkdir()
        _write_plugin(configured, "stocks", dir_name="ledmatrix-stocks")

        store = PluginStoreManager(plugins_dir=str(configured))
        assert store._find_plugin_path("no-such-plugin") is None

    def test_half_finished_installs_are_not_resurrected(self, tmp_path):
        """A directory renamed aside during install/rollback carries a valid
        manifest. Matching one would report a ghost plugin as installed."""
        configured = tmp_path / "plugin-repos"
        configured.mkdir()
        _write_plugin(configured, "ghost",
                      dir_name="ghost.standalone-backup-1234")

        store = PluginStoreManager(plugins_dir=str(configured))
        assert store._find_plugin_path("ghost") is None

    def test_unreadable_manifest_does_not_break_the_scan(self, tmp_path):
        configured = tmp_path / "plugin-repos"
        configured.mkdir()
        broken = configured / "broken-plugin"
        broken.mkdir()
        (broken / "manifest.json").write_text("{ not json")
        wanted = _write_plugin(configured, "stocks", dir_name="ledmatrix-stocks")

        store = PluginStoreManager(plugins_dir=str(configured))
        assert store._find_plugin_path("stocks") == wanted

    def test_sibling_plugins_dir_is_searched_too(self, tmp_path):
        configured = tmp_path / "plugin-repos"
        configured.mkdir()
        legacy = _write_plugin(tmp_path / "plugins", "weather",
                               dir_name="ledmatrix-weather")

        store = PluginStoreManager(plugins_dir=str(configured))
        assert store._find_plugin_path("weather") == legacy


class TestStandaloneBackupContract:
    def test_discovery_skips_backup_dirs(self, tmp_path):
        plugins_dir = tmp_path / "plugins"
        _write_plugin(plugins_dir, "real-plugin")
        # A rollback-in-progress dir with a valid manifest must NOT surface.
        _write_plugin(plugins_dir, "real-plugin",
                      dir_name="real-plugin.standalone-backup-migrating")

        found = _scanner()._scan_directory_for_plugins(plugins_dir)
        assert found == ["real-plugin"]

    def test_backup_marker_is_shared_and_unchanged(self):
        """store_manager (rename-aside names) and every lookup (skip check)
        must agree on the marker. Both now import one constant; the value is
        pinned because renaming it would make existing debris on devices
        visible as plugins again."""
        from src.plugin_system import plugin_dirs
        assert plugin_dirs.BACKUP_MARKER == '.standalone-backup-'
        root = Path(__file__).resolve().parents[1]
        sm_text = (root / "src/plugin_system/store_manager.py").read_text(encoding="utf-8")
        assert "{BACKUP_MARKER}preinstall" in sm_text
        assert "{BACKUP_MARKER}migrating" in sm_text
        assert plugin_dirs.is_ignored_dir_name(
            "demo" + plugin_dirs.BACKUP_MARKER + "preinstall")