Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

8.9 KB
Raw Blame
"""The module manifest is shared by packaging, runtime assembly and clients.

Reading the catalog never imports a feature or creates its services. Package
ownership is distinct from deployment selection and from execution readiness.
User authorization remains the responsibility of existing scoped adapters.
"""

from __future__ import annotations

from functools import cache
from importlib import metadata
import json
from pathlib import Path
import shutil
from typing import Any

from packaging.requirements import Requirement


class ModuleUnavailable(ValueError):
    pass


@cache
def manifests() -> dict[str, dict[str, Any]]:
    result = {}
    for path in sorted(Path(__file__).with_name("manifests").glob("*.json")):
        row = json.loads(path.read_text(encoding="utf-8"))
        if row["schema_version"] != 1 or row["id"] != path.stem:
            raise ValueError(f"Invalid module manifest: {path.name}")
        result[row["id"]] = row
    owners: dict[tuple[str, str], str] = {}
    for name, row in result.items():
        for dependency in [*row["requires"], *row["optional"]]:
            if dependency not in result or dependency == name:
                raise ValueError(f"Invalid module dependency: {name} -> {dependency}")
        for kind in ("tools", "capabilities", "loops"):
            for spec in row[kind].values():
                for dependency in spec.get("requires", []):
                    if dependency not in {*row["requires"], *row["optional"]}:
                        raise ValueError(
                            f"Undeclared contribution dependency: {name} -> {dependency}"
                        )
        for kind in ("capabilities", "loops", "tools", "paths"):
            for key in row[kind]:
                identity = (kind, key)
                if identity in owners:
                    raise ValueError(
                        f"Duplicate {kind} owner for {key}: {owners[identity]}, {name}"
                    )
                owners[identity] = name
        for prefix in row["paths"]:
            if prefix.startswith("/") or ".." in prefix.split("/"):
                raise ValueError(f"Invalid module path: {prefix}")
        for route in row["routes"]:
            if route["auth"] not in {"public", "authenticated", "learning", "admin"}:
                raise ValueError(f"Invalid route authorization policy: {name}")
    visiting: set[str] = set()
    visited: set[str] = set()

    def visit(name: str) -> None:
        if name in visiting:
            raise ValueError(f"Cyclic module dependency: {name}")
        if name in visited:
            return
        if name not in result:
            raise ValueError(f"Unknown required module: {name}")
        visiting.add(name)
        for dependency in result[name]["requires"]:
            visit(dependency)
        visiting.remove(name)
        visited.add(name)

    for name in result:
        visit(name)
    return result


@cache
def source_checkout() -> bool:
    root = Path(__file__).resolve().parents[2]
    # Docker and source archives deliberately omit Git metadata. Published
    # wheels contain neither the project file nor the source build script.
    return (root / "pyproject.toml").is_file() and (root / "scripts/build_modules.py").is_file()


def state_path() -> Path:
    from deeptutor.runtime.home import get_runtime_data_root

    return get_runtime_data_root() / "system" / "modules.json"


def selection() -> dict[str, bool]:
    path = state_path()
    if not path.exists():
        return {}
    raw = json.loads(path.read_text(encoding="utf-8"))
    if raw.get("schema_version") != 1 or not isinstance(raw.get("enabled"), dict):
        raise ValueError(f"Invalid module state: {path}")
    enabled = raw["enabled"]
    if any(name not in manifests() or type(value) is not bool for name, value in enabled.items()):
        raise ValueError(f"Invalid module selection: {path}")
    return enabled


def installed(name: str) -> bool:
    if name == "core":
        return True
    if source_checkout():
        return True
    try:
        metadata.distribution(manifests()[name]["distribution"])
        return True
    except metadata.PackageNotFoundError:
        return False


def module_enabled(name: str, *, selected: dict[str, bool] | None = None) -> bool:
    if name not in manifests():
        raise ValueError(f"Unknown module: {name}")
    if name == "core":
        return True
    selected = selection() if selected is None else selected
    if not installed(name) or not selected.get(name, True):
        return False
    if not source_checkout():
        from deeptutor.__version__ import __version__

        if metadata.version(manifests()[name]["distribution"]) != __version__:
            return False
    return all(module_enabled(dep, selected=selected) for dep in manifests()[name]["requires"])


def require_module(name: str) -> None:
    if not module_enabled(name):
        raise ModuleUnavailable(
            f"Module '{name}' is unavailable. Run `deeptutor module install {name}` "
            f"and `deeptutor module enable {name}`."
        )


@cache
def module_for_path(path: str) -> str:
    """Longest explicit path owns the file; unassigned shared code is core."""
    path = path.replace("\\", "/")
    candidates = [
        (len(prefix), name)
        for name, row in manifests().items()
        for prefix in row["paths"]
        if path == prefix or path.startswith(prefix + "/")
    ]
    return max(candidates)[1] if candidates else "core"


def contribution_owner(kind: str, name: str) -> str:
    for module, row in manifests().items():
        if name in row[kind]:
            return module
    return "core"


def contribution_enabled(kind: str, name: str) -> bool:
    owner = contribution_owner(kind, name)
    spec = manifests()[owner][kind].get(name, {})
    return module_enabled(owner) and all(
        module_enabled(dependency) for dependency in spec.get("requires", [])
    )


def dependency_order(names: list[str]) -> list[str]:
    ordered: list[str] = []

    def visit(name: str) -> None:
        if name not in manifests():
            raise ValueError(f"Unknown module: {name}")
        if name in ordered:
            return
        for dependency in manifests()[name]["requires"]:
            visit(dependency)
        ordered.append(name)

    for name in names:
        visit(name)
    return ordered


def dependents(name: str, *, enabled_only: bool = False) -> list[str]:
    return [
        key
        for key in manifests()
        if key != name
        and name in dependency_order([key])
        and (module_enabled(key) if enabled_only else installed(key))
    ]


def module_statuses() -> list[dict[str, Any]]:
    from deeptutor.__version__ import __version__

    selected = selection()
    rows = []
    for name, manifest in manifests().items():
        present = installed(name)
        enabled = module_enabled(name, selected=selected)
        issues = []
        for dependency in manifest["requires"]:
            if not module_enabled(dependency, selected=selected):
                issues.append(f"Required module unavailable: {dependency}")
        if present:
            if not source_checkout() and name != "core":
                version = metadata.version(manifest["distribution"])
                if version != __version__:
                    issues.append(f"Module version {version} must match core {__version__}")
            for raw in manifest["requirements"]:
                requirement = Requirement(raw)
                if requirement.marker and not requirement.marker.evaluate():
                    continue
                try:
                    version = metadata.version(requirement.name)
                    if version not in requirement.specifier:
                        issues.append(f"Requires {raw}; installed {version}")
                except metadata.PackageNotFoundError:
                    issues.append(f"Missing package: {raw}")
            for executable in manifest["executables"]:
                if shutil.which(executable) is None:
                    issues.append(f"Missing executable: {executable}")
        rows.append(
            {
                "id": name,
                "distribution": manifest["distribution"],
                "installed": present,
                "enabled": enabled,
                "ready": enabled and not issues,
                "issues": issues,
                "requires": manifest["requires"],
                "navigation": manifest["navigation"],
                "capabilities": list(manifest["capabilities"]),
                "source": source_checkout(),
            }
        )
    by_id = {row["id"]: row for row in rows}
    for name in dependency_order(list(by_id)):
        row = by_id[name]
        for dependency in row["requires"]:
            if by_id[dependency]["enabled"] and not by_id[dependency]["ready"]:
                row["issues"].append(f"Required module not ready: {dependency}")
                row["ready"] = False
    return rows