simple-module-core 0.0.1__py3-none-any.whl

simple_module_core/__init__.py

@@ -0,0 +1,76 @@
+"""SimpleModule Core - Module system, menu, permissions, events, and diagnostics."""
+
+from simple_module_core.diagnostics import (
+    DiagnosticLevel,
+    MigrationDiagnostics,
+    print_diagnostics,
+    run_diagnostics,
+)
+from simple_module_core.discovery import (
+    discover_modules,
+    get_module_package_name,
+    topological_sort,
+)
+from simple_module_core.events import Event, EventBus
+from simple_module_core.exceptions import (
+    CircularDependencyError,
+    FrameworkVersionError,
+    InvalidModuleError,
+    ModuleError,
+    NotFoundError,
+    ValidationError,
+)
+from simple_module_core.feature_flags import (
+    FeatureFlagDefinition,
+    FeatureFlagRegistry,
+    feature_flag,
+    flag_enabled,
+    is_flag_enabled,
+    require_flag,
+)
+from simple_module_core.health import HealthCheck, HealthCheckResult, HealthRegistry, HealthStatus
+from simple_module_core.i18n import I18nRegistry, Translator
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.permissions import PermissionRegistry
+from simple_module_core.services import Services
+from simple_module_core.versioning import FRAMEWORK_API_VERSION, check_framework_compatibility
+
+__all__ = [
+    "FRAMEWORK_API_VERSION",
+    "CircularDependencyError",
+    "DiagnosticLevel",
+    "Event",
+    "EventBus",
+    "FeatureFlagDefinition",
+    "FeatureFlagRegistry",
+    "FrameworkVersionError",
+    "HealthCheck",
+    "HealthCheckResult",
+    "HealthRegistry",
+    "HealthStatus",
+    "I18nRegistry",
+    "InvalidModuleError",
+    "MenuItem",
+    "MenuRegistry",
+    "MenuSection",
+    "MigrationDiagnostics",
+    "ModuleBase",
+    "ModuleError",
+    "ModuleMeta",
+    "NotFoundError",
+    "PermissionRegistry",
+    "Services",
+    "Translator",
+    "ValidationError",
+    "check_framework_compatibility",
+    "discover_modules",
+    "feature_flag",
+    "flag_enabled",
+    "get_module_package_name",
+    "is_flag_enabled",
+    "print_diagnostics",
+    "require_flag",
+    "run_diagnostics",
+    "topological_sort",
+]

simple_module_core/__main__.py

@@ -0,0 +1,96 @@
+"""Run module diagnostics from the command line.
+
+Usage::
+
+    python -m simple_module_core        # discover modules, run diagnostics
+    make doctor                         # same thing, wrapped
+
+Exits with status 1 if any ERROR-level diagnostics are reported.
+
+i18n checks are included when ``SM_I18N_SUPPORTED_LOCALES`` is set in env
+(or ``.env``). Host-level ``host/locales/`` and shared ``packages/ui/locales/``
+are picked up relative to ``SM_PROJECT_ROOT`` (or the current working dir).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from simple_module_core.diagnostics import (
+    DiagnosticLevel,
+    print_diagnostics,
+    run_diagnostics,
+)
+from simple_module_core.discovery import discover_modules, topological_sort
+from simple_module_core.dotenv import parse_dotenv
+
+
+def _load_i18n_settings_from_env() -> tuple[list[str], str] | tuple[None, None]:
+    """Return ``(supported_locales, default_locale)`` or ``(None, None)`` if unset.
+
+    Reads env vars directly to avoid a dependency on ``simple_module_hosting``.
+    Honors ``.env`` by merging it into ``os.environ`` if present (pydantic-
+    settings isn't imported here).
+    """
+    for key, value in parse_dotenv().items():
+        os.environ.setdefault(key, value)
+
+    supported_raw = os.environ.get("SM_I18N_SUPPORTED_LOCALES")
+    if not supported_raw:
+        return None, None
+
+    try:
+        supported = json.loads(supported_raw)
+    except json.JSONDecodeError:
+        # Also accept comma-separated (e.g. "en,es,de").
+        supported = [s.strip() for s in supported_raw.split(",") if s.strip()]
+
+    if not isinstance(supported, list) or not supported:
+        return None, None
+
+    default = os.environ.get("SM_I18N_DEFAULT_LOCALE", "en")
+    return supported, default
+
+
+def _discover_extra_locale_sources() -> list[tuple[str, str, Path]]:
+    """Return ``[(reporter, namespace, path), ...]`` for host + ui locale dirs."""
+    root = Path(os.environ.get("SM_PROJECT_ROOT") or Path.cwd())
+    out: list[tuple[str, str, Path]] = []
+    host_locales = root / "host" / "locales"
+    if host_locales.is_dir():
+        out.append(("host", "host", host_locales))
+    ui_locales = root / "packages" / "ui" / "locales"
+    if ui_locales.is_dir():
+        out.append(("packages/ui", "ui", ui_locales))
+    return out
+
+
+def main() -> int:
+    modules = discover_modules()
+    if not modules:
+        print("No modules discovered. Is the project installed (`uv sync --all-packages`)?")
+        return 0
+
+    # Topological sort surfaces CircularDependencyError early.
+    modules = topological_sort(modules)
+
+    supported, default = _load_i18n_settings_from_env()
+    extra = _discover_extra_locale_sources()
+
+    diagnostics = run_diagnostics(
+        modules,
+        i18n_supported_locales=supported,
+        i18n_default_locale=default,
+        i18n_extra_sources=extra,
+    )
+    print_diagnostics(diagnostics)
+
+    errors = [d for d in diagnostics if d.level == DiagnosticLevel.ERROR]
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

simple_module_core/diagnostics/__init__.py

@@ -0,0 +1,24 @@
+"""Module diagnostics — validates structure and patterns at startup or via CLI.
+
+This is the public surface re-exported from the submodules below.
+Callers import from ``simple_module_core.diagnostics`` and should not
+need to reach into ``._module`` or ``._migration`` directly.
+"""
+
+from __future__ import annotations
+
+from simple_module_core.diagnostics._i18n import I18nDiagnostics
+from simple_module_core.diagnostics._migration import MigrationDiagnostics
+from simple_module_core.diagnostics._module import ModuleDiagnostics
+from simple_module_core.diagnostics._runner import print_diagnostics, run_diagnostics
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+__all__ = [
+    "Diagnostic",
+    "DiagnosticLevel",
+    "I18nDiagnostics",
+    "MigrationDiagnostics",
+    "ModuleDiagnostics",
+    "print_diagnostics",
+    "run_diagnostics",
+]

simple_module_core/diagnostics/_coupling.py

@@ -0,0 +1,81 @@
+"""SM009: detect framework packages that import from plugin module packages."""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+FRAMEWORK_PACKAGES = ("simple_module_core", "simple_module_hosting", "simple_module_db")
+
+
+def _find_package_dir(package_name: str) -> Path | None:
+    spec = importlib.util.find_spec(package_name)
+    if spec and spec.submodule_search_locations:
+        locations = list(spec.submodule_search_locations)
+        if locations:
+            return Path(locations[0])
+    return None
+
+
+def _imported_plugin_pkg(node: ast.AST, module_packages: dict[str, str]) -> str | None:
+    if isinstance(node, ast.Import):
+        for alias in node.names:
+            top = alias.name.split(".")[0]
+            if top in module_packages:
+                return top
+    elif isinstance(node, ast.ImportFrom) and node.module:
+        top = node.module.split(".")[0]
+        if top in module_packages:
+            return top
+    return None
+
+
+def check_framework_module_coupling(modules: list[ModuleBase]) -> list[Diagnostic]:
+    """The framework (core, hosting, db) must never import from a plugin module."""
+    module_packages: dict[str, str] = {
+        type(mod).__module__.split(".")[0]: mod.meta.name for mod in modules
+    }
+    if not module_packages:
+        return []
+
+    framework_dirs: list[tuple[str, Path]] = []
+    for fw_pkg in FRAMEWORK_PACKAGES:
+        fw_dir = _find_package_dir(fw_pkg)
+        if fw_dir:
+            framework_dirs.append((fw_pkg, fw_dir))
+
+    diags: list[Diagnostic] = []
+    for fw_pkg, fw_dir in framework_dirs:
+        for py_file in fw_dir.rglob("*.py"):
+            try:
+                tree = ast.parse(py_file.read_text(), filename=str(py_file))
+            except SyntaxError:
+                continue
+            for node in ast.walk(tree):
+                imported_pkg = _imported_plugin_pkg(node, module_packages)
+                if imported_pkg:
+                    diags.append(
+                        Diagnostic(
+                            level=DiagnosticLevel.ERROR,
+                            code="SM009",
+                            message=(
+                                f"Framework package '{fw_pkg}' directly imports "
+                                f"from module package '{imported_pkg}'"
+                            ),
+                            module_name=module_packages[imported_pkg],
+                            file=str(py_file),
+                            suggestion=(
+                                "Use a ModuleBase lifecycle hook "
+                                "(register_middleware, register_routes, etc.) "
+                                "instead of importing module code from the framework"
+                            ),
+                        )
+                    )
+    return diags

simple_module_core/diagnostics/_i18n.py

@@ -0,0 +1,121 @@
+"""Diagnostics that validate i18n locale file coverage and consistency."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+from simple_module_core.i18n import flatten_messages
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+
+class I18nDiagnostics:
+    """Validates locale file coverage per module.
+
+    Codes:
+    - SM013: missing locale file for a supported locale.
+    - SM014: non-default locale is missing keys present in the default.
+    - SM015: non-default locale has keys not present in the default.
+    - SM016: locale JSON fails to parse or has non-string leaves.
+    """
+
+    def __init__(
+        self,
+        supported_locales: list[str],
+        default_locale: str,
+        extra_sources: list[tuple[str, str, Path]] | None = None,
+    ) -> None:
+        """Build the diagnostic.
+
+        ``extra_sources`` is an optional list of ``(reporter_name, namespace,
+        locale_dir)`` triples for locale directories that aren't owned by any
+        ``ModuleBase`` instance — notably the host's ``host/locales/`` and
+        the shared ``packages/ui/locales/``. ``reporter_name`` is used as the
+        ``module_name`` field on findings for display purposes.
+        """
+        self.supported_locales = list(supported_locales)
+        self.default_locale = default_locale
+        self.extra_sources = list(extra_sources or [])
+
+    def run(self, modules: list[ModuleBase]) -> list[Diagnostic]:
+        findings: list[Diagnostic] = []
+        for mod in modules:
+            for namespace, locale_dir in mod.locale_dirs().items():
+                findings.extend(self._check_namespace(mod.meta.name, namespace, Path(locale_dir)))
+        for reporter_name, namespace, locale_dir in self.extra_sources:
+            findings.extend(self._check_namespace(reporter_name, namespace, Path(locale_dir)))
+        return findings
+
+    def _check_namespace(
+        self, module_name: str, namespace: str, locale_dir: Path
+    ) -> list[Diagnostic]:
+        findings: list[Diagnostic] = []
+        per_locale_keys: dict[str, set[str]] = {}
+
+        for locale in self.supported_locales:
+            path = locale_dir / f"{locale}.json"
+            if not path.is_file():
+                findings.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.WARNING,
+                        code="SM013",
+                        message=(f"Missing locale file {locale}.json for namespace '{namespace}'"),
+                        module_name=module_name,
+                        file=str(path),
+                        suggestion=f"Create {path} (even if empty: '{{}}')",
+                    )
+                )
+                continue
+            try:
+                raw = json.loads(path.read_text(encoding="utf-8"))
+                if not isinstance(raw, dict):
+                    raise ValueError("top-level JSON must be an object")
+                flat = flatten_messages(raw)
+            except (json.JSONDecodeError, ValueError) as exc:
+                findings.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.ERROR,
+                        code="SM016",
+                        message=f"Invalid locale JSON in {path}: {exc}",
+                        module_name=module_name,
+                        file=str(path),
+                    )
+                )
+                continue
+            per_locale_keys[locale] = set(flat.keys())
+
+        default_keys = per_locale_keys.get(self.default_locale, set())
+        for locale, keys in per_locale_keys.items():
+            if locale == self.default_locale:
+                continue
+            missing = default_keys - keys
+            extra = keys - default_keys
+            if missing:
+                findings.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.WARNING,
+                        code="SM014",
+                        message=(
+                            f"Locale '{locale}' in namespace '{namespace}' is missing keys: "
+                            f"{', '.join(sorted(missing))}"
+                        ),
+                        module_name=module_name,
+                    )
+                )
+            if extra:
+                findings.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.WARNING,
+                        code="SM015",
+                        message=(
+                            f"Locale '{locale}' in namespace '{namespace}' has keys not in "
+                            f"default: {', '.join(sorted(extra))}"
+                        ),
+                        module_name=module_name,
+                    )
+                )
+        return findings

simple_module_core/diagnostics/_inertia_api.py

@@ -0,0 +1,73 @@
+"""SM018: flag Inertia ``router.{post,patch,put,delete}('/api/...')`` calls.
+
+Inertia's client-side router (``@inertiajs/react``'s ``router.*``) expects
+Inertia-shaped responses or redirects — a raw JSON body from the REST
+API layer triggers ``All Inertia requests must receive a valid Inertia
+response``. The fix is to point the call at a module **view** endpoint
+that returns ``RedirectResponse(..., status_code=303)``.
+
+This check regex-scans each module's ``pages/**/*.tsx`` files for the
+anti-pattern. It is textual (not AST) because a full TSX parser in
+Python is not worth the dependency — the pattern is unambiguous enough
+that string matching catches it reliably.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+# Matches calls like:
+#   router.post('/api/datasets/', ...)
+#   router.patch(`/api/datasets/${id}`, ...)
+#   router.delete("/api/datasets/" + id)
+# The quote character is captured so we only match string-literal URLs
+# (backtick, single, or double) — variable URLs don't count.
+_ROUTER_API_CALL = re.compile(
+    r"router\.(?P<method>post|patch|put|delete)\s*\(\s*[`'\"]/api/",
+)
+
+
+def check_inertia_api_calls(mod: ModuleBase, src_dir: Path) -> list[Diagnostic]:
+    """Warn when a page uses Inertia's router against a JSON API endpoint."""
+    pages_dir = src_dir / "pages"
+    if not pages_dir.exists():
+        return []
+
+    diags: list[Diagnostic] = []
+    for tsx in sorted(pages_dir.rglob("*.tsx")):
+        try:
+            source = tsx.read_text()
+        except OSError:
+            continue
+        for lineno, line in enumerate(source.splitlines(), start=1):
+            match = _ROUTER_API_CALL.search(line)
+            if not match:
+                continue
+            method = match.group("method").upper()
+            diags.append(
+                Diagnostic(
+                    level=DiagnosticLevel.WARNING,
+                    code="SM018",
+                    message=(
+                        f"router.{method.lower()}() targets a JSON API endpoint — "
+                        "Inertia will reject the response"
+                    ),
+                    module_name=mod.meta.name,
+                    file=f"{tsx}:{lineno}",
+                    suggestion=(
+                        "Point the call at a view endpoint (e.g. '/"
+                        f"{mod.meta.name.lower()}/...') that returns "
+                        "RedirectResponse(..., status_code=303). Or, if you "
+                        "really need the JSON payload, use fetch() instead of "
+                        "Inertia's router."
+                    ),
+                )
+            )
+    return diags

simple_module_core/diagnostics/_js_workspace.py

@@ -0,0 +1,35 @@
+"""SM017: warn modules shipping .tsx pages but missing npm workspace files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+
+def check_js_workspace_files(mod: ModuleBase, src_dir: Path) -> list[Diagnostic]:
+    """Warn when a module ships .tsx pages but is missing npm workspace files."""
+    pages_dir = src_dir / "pages"
+    if not pages_dir.exists() or not any(pages_dir.rglob("*.tsx")):
+        return []
+    module_dir = src_dir.parent
+    return [
+        Diagnostic(
+            level=DiagnosticLevel.WARNING,
+            code="SM017",
+            message=f"Module ships pages/*.tsx but has no {fn}",
+            module_name=mod.meta.name,
+            file=str(module_dir / fn),
+            suggestion=(
+                f"Create {module_dir / fn} — without it npm won't treat the "
+                "module as a workspace member and Vite may fail to resolve "
+                "@simple-module-py/ui subpath imports"
+            ),
+        )
+        for fn in ("package.json", "tsconfig.json")
+        if not (module_dir / fn).exists()
+    ]

simple_module_core/diagnostics/_migration.py

@@ -0,0 +1,45 @@
+"""Alembic migration-state diagnostics (SM010, SM011)."""
+
+from __future__ import annotations
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+
+class MigrationDiagnostics:
+    """Validates database migration state."""
+
+    def check_revision_mismatch(
+        self,
+        current_revision: str | None,
+        head_revision: str | None,
+    ) -> list[Diagnostic]:
+        """SM010: Error if database is not at the migration head."""
+        if current_revision == head_revision:
+            return []
+        return [
+            Diagnostic(
+                level=DiagnosticLevel.ERROR,
+                code="SM010",
+                message=(f"Database at revision {current_revision!r}, expected {head_revision!r}"),
+                module_name="migrations",
+                suggestion="Run: make migrate",
+            )
+        ]
+
+    def check_table_coverage(
+        self,
+        module_tables: set[str],
+        migrated_tables: set[str],
+    ) -> list[Diagnostic]:
+        """SM011: Warning if module tables are missing from migration history."""
+        missing = module_tables - migrated_tables
+        return [
+            Diagnostic(
+                level=DiagnosticLevel.WARNING,
+                code="SM011",
+                message=f"Table '{table}' declared in models but not found in migration history",
+                module_name="migrations",
+                suggestion=f'Run: make migration msg="add {table}"',
+            )
+            for table in sorted(missing)
+        ]