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

simple_module_core/diagnostics/_module.py

@@ -0,0 +1,252 @@
+"""Structural diagnostics that validate discovered modules against invariants."""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics._coupling import check_framework_module_coupling
+from simple_module_core.diagnostics._inertia_api import check_inertia_api_calls
+from simple_module_core.diagnostics._js_workspace import check_js_workspace_files
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+
+def _iter_render_components(tree: ast.Module) -> list[str]:
+    """Yield ``X.render(component, ...)`` first-arg values, resolving Name constants."""
+    consts = {
+        s.targets[0].id: s.value.value
+        for s in tree.body
+        if isinstance(s, ast.Assign)
+        and len(s.targets) == 1
+        and isinstance(s.targets[0], ast.Name)
+        and isinstance(s.value, ast.Constant)
+        and isinstance(s.value.value, str)
+    }
+    found: list[str] = []
+    for node in ast.walk(tree):
+        if not (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and node.func.attr == "render"
+            and node.args
+        ):
+            continue
+        first = node.args[0]
+        if isinstance(first, ast.Constant) and isinstance(first.value, str):
+            found.append(first.value)
+        elif isinstance(first, ast.Name) and first.id in consts:
+            found.append(consts[first.id])
+    return found
+
+
+class ModuleDiagnostics:
+    """Validates module structure and configuration."""
+
+    def run(self, modules: list[ModuleBase]) -> list[Diagnostic]:
+        diagnostics: list[Diagnostic] = []
+        diagnostics.extend(self._check_duplicate_names(modules))
+        diagnostics.extend(self._check_schema_conflicts(modules))
+        diagnostics.extend(self._check_empty_modules(modules))
+        diagnostics.extend(self._check_missing_meta(modules))
+        diagnostics.extend(check_framework_module_coupling(modules))
+
+        # File-based checks (need to find module source directories)
+        for mod in modules:
+            src_dir = self._find_source_dir(mod)
+            if src_dir:
+                rendered_pages = self._find_render_calls(mod, src_dir)
+                diagnostics.extend(self._check_orphan_pages(mod, src_dir, rendered_pages))
+                diagnostics.extend(self._check_phantom_renders(mod, src_dir, rendered_pages))
+                diagnostics.extend(check_js_workspace_files(mod, src_dir))
+                diagnostics.extend(check_inertia_api_calls(mod, src_dir))
+
+        return diagnostics
+
+    def _check_duplicate_names(self, modules: list[ModuleBase]) -> list[Diagnostic]:
+        seen: dict[str, str] = {}
+        diags: list[Diagnostic] = []
+        for mod in modules:
+            name = mod.meta.name
+            cls_name = type(mod).__qualname__
+            if name in seen:
+                diags.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.ERROR,
+                        code="SM008",
+                        message=f"Duplicate module name '{name}' (also in {seen[name]})",
+                        module_name=cls_name,
+                        suggestion="Each module must have a unique meta.name",
+                    )
+                )
+            seen[name] = cls_name
+        return diags
+
+    def _check_schema_conflicts(self, modules: list[ModuleBase]) -> list[Diagnostic]:
+        """Check for modules that would create conflicting DB schemas."""
+        prefixes: dict[str, str] = {}
+        diags: list[Diagnostic] = []
+        for mod in modules:
+            prefix = mod.meta.name.lower()
+            if prefix in prefixes:
+                diags.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.ERROR,
+                        code="SM008",
+                        message=(
+                            f"Schema/table prefix '{prefix}' conflicts "
+                            f"with module '{prefixes[prefix]}'"
+                        ),
+                        module_name=mod.meta.name,
+                        suggestion="Use unique module names to avoid DB schema conflicts",
+                    )
+                )
+            prefixes[prefix] = mod.meta.name
+        return diags
+
+    def _check_empty_modules(self, modules: list[ModuleBase]) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        for mod in modules:
+            cls = type(mod)
+            overridden = [
+                name
+                for name in (
+                    "register_routes",
+                    "register_menu_items",
+                    "register_permissions",
+                    "register_feature_flags",
+                    "register_event_handlers",
+                    "register_middleware",
+                    "register_health_checks",
+                    "register_exception_handlers",
+                    "register_settings",
+                    "template_dirs",
+                    "static_mounts",
+                    "locale_dirs",
+                    "on_startup",
+                    "on_shutdown",
+                )
+                if name in cls.__dict__
+            ]
+            if not overridden:
+                diags.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.INFO,
+                        code="SM007",
+                        message="Module exists but overrides no registration methods",
+                        module_name=mod.meta.name,
+                        suggestion="Override register_routes() or other methods to add functionality",  # noqa: E501
+                    )
+                )
+        return diags
+
+    def _check_missing_meta(self, modules: list[ModuleBase]) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        for mod in modules:
+            if not hasattr(mod, "meta"):
+                diags.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.ERROR,
+                        code="SM001",
+                        message="Module missing 'meta' class attribute",
+                        module_name=type(mod).__qualname__,
+                        suggestion="Add: meta = ModuleMeta(name='YourModule')",
+                    )
+                )
+        return diags
+
+    def _find_package_dir(self, package_name: str) -> Path | None:
+        """Locate the source directory for a top-level package."""
+        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 _collect_tsx_pages(self, pages_dir: Path) -> set[str]:
+        """Collect .tsx page identifiers relative to pages_dir, without extension.
+
+        Nested files are represented with forward slashes so the set compares
+        directly against inertia.render("Module/Sub/Page") keys. Subdirectories
+        whose names start with a lowercase letter (e.g. ``components/``,
+        ``hooks/``) are treated as helper folders — not Inertia page roots —
+        and skipped, matching the PascalCase convention Inertia uses.
+        """
+        if not pages_dir.exists():
+            return set()
+        pages: set[str] = set()
+        for f in pages_dir.rglob("*.tsx"):
+            rel = f.relative_to(pages_dir)
+            if any(part[:1].islower() for part in rel.parts[:-1]):
+                continue
+            pages.add(rel.with_suffix("").as_posix())
+        return pages
+
+    def _check_orphan_pages(
+        self,
+        mod: ModuleBase,
+        src_dir: Path,
+        rendered_pages: set[str],
+    ) -> list[Diagnostic]:
+        """Find .tsx pages that aren't referenced by any inertia.render() call."""
+        pages_dir = src_dir / "pages"
+        tsx_pages = self._collect_tsx_pages(pages_dir)
+        orphans = tsx_pages - rendered_pages
+
+        return [
+            Diagnostic(
+                level=DiagnosticLevel.WARNING,
+                code="SM003",
+                message=f"Page '{name}.tsx' exists but no matching inertia.render() found",
+                module_name=mod.meta.name,
+                file=str(pages_dir / f"{name}.tsx"),
+                suggestion=f'Add inertia.render("{mod.meta.name}/{name}", ...) in a view endpoint',
+            )
+            for name in orphans
+        ]
+
+    def _check_phantom_renders(
+        self,
+        mod: ModuleBase,
+        src_dir: Path,
+        rendered_pages: set[str],
+    ) -> list[Diagnostic]:
+        """Find inertia.render() calls that reference non-existent pages."""
+        pages_dir = src_dir / "pages"
+        tsx_pages = self._collect_tsx_pages(pages_dir)
+        phantoms = rendered_pages - tsx_pages
+
+        return [
+            Diagnostic(
+                level=DiagnosticLevel.WARNING,
+                code="SM004",
+                message=f'inertia.render("{mod.meta.name}/{name}") but no {name}.tsx exists',
+                module_name=mod.meta.name,
+                suggestion=f"Create {pages_dir / f'{name}.tsx'}",
+            )
+            for name in phantoms
+        ]
+
+    def _find_render_calls(self, mod: ModuleBase, src_dir: Path) -> set[str]:
+        """Find inertia.render("Module/Page") calls, resolving module-level string consts."""
+        rendered: set[str] = set()
+        prefix = f"{mod.meta.name}/"
+        for py_file in src_dir.rglob("*.py"):
+            try:
+                tree = ast.parse(py_file.read_text(), filename=str(py_file))
+            except SyntaxError:
+                continue
+            for component in _iter_render_components(tree):
+                if component.startswith(prefix):
+                    rendered.add(component[len(prefix) :])
+        return rendered
+
+    def _find_source_dir(self, mod: ModuleBase) -> Path | None:
+        """Locate the source directory for a module's package."""
+        pkg_name = type(mod).__module__.rsplit(".", 1)[0]
+        return self._find_package_dir(pkg_name)

simple_module_core/diagnostics/_runner.py

@@ -0,0 +1,81 @@
+"""Entry points that assemble and print diagnostic output."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics._migration import MigrationDiagnostics
+from simple_module_core.diagnostics._module import ModuleDiagnostics
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+logger = logging.getLogger(__name__)
+
+
+def run_diagnostics(
+    modules: list[ModuleBase],
+    *,
+    migration_state: dict | None = None,
+    module_tables: set[str] | None = None,
+    migrated_tables: set[str] | None = None,
+    i18n_supported_locales: list[str] | None = None,
+    i18n_default_locale: str | None = None,
+    i18n_extra_sources: list[tuple[str, str, Path]] | None = None,
+) -> list[Diagnostic]:
+    """Convenience function to run all diagnostics.
+
+    When ``migration_state`` is provided, also runs migration diagnostics.
+    When ``i18n_supported_locales`` and ``i18n_default_locale`` are provided,
+    also runs i18n locale coverage diagnostics. ``i18n_extra_sources`` lets
+    callers include host/ui locale dirs that aren't owned by a ``ModuleBase``.
+    """
+    diagnostics = ModuleDiagnostics().run(modules)
+
+    if i18n_supported_locales and i18n_default_locale:
+        from simple_module_core.diagnostics._i18n import I18nDiagnostics
+
+        diagnostics.extend(
+            I18nDiagnostics(
+                supported_locales=i18n_supported_locales,
+                default_locale=i18n_default_locale,
+                extra_sources=i18n_extra_sources,
+            ).run(modules)
+        )
+
+    if migration_state is not None:
+        migration_diag = MigrationDiagnostics()
+        diagnostics.extend(
+            migration_diag.check_revision_mismatch(
+                current_revision=migration_state.get("current_revision"),
+                head_revision=migration_state.get("head_revision"),
+            )
+        )
+        if module_tables is not None and migrated_tables is not None:
+            diagnostics.extend(migration_diag.check_table_coverage(module_tables, migrated_tables))
+
+    return diagnostics
+
+
+def print_diagnostics(diagnostics: list[Diagnostic]) -> None:
+    """Pretty-print diagnostics to stderr."""
+    if not diagnostics:
+        logger.info("\u2713 No module diagnostics issues found")
+        return
+
+    errors = [d for d in diagnostics if d.level == DiagnosticLevel.ERROR]
+    warnings = [d for d in diagnostics if d.level == DiagnosticLevel.WARNING]
+    infos = [d for d in diagnostics if d.level == DiagnosticLevel.INFO]
+
+    for d in diagnostics:
+        print(str(d), file=sys.stderr)
+        print(file=sys.stderr)
+
+    print(
+        f"Results: {len(errors)} error(s), {len(warnings)} warning(s), {len(infos)} info",
+        file=sys.stderr,
+    )

simple_module_core/diagnostics/_types.py

@@ -0,0 +1,33 @@
+"""Core diagnostic types: level enum and finding dataclass."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class DiagnosticLevel(StrEnum):
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+@dataclass
+class Diagnostic:
+    """A single diagnostic finding."""
+
+    level: DiagnosticLevel
+    code: str
+    message: str
+    module_name: str
+    file: str | None = None
+    suggestion: str | None = None
+
+    def __str__(self) -> str:
+        prefix = {"error": "\u2717", "warning": "\u26a0", "info": "\u2139"}[self.level]
+        parts = [f"{prefix} {self.code} [{self.level.upper()}] {self.module_name}: {self.message}"]
+        if self.file:
+            parts.append(f"  \u21b3 {self.file}")
+        if self.suggestion:
+            parts.append(f"  \u21b3 Suggestion: {self.suggestion}")
+        return "\n".join(parts)

simple_module_core/discovery.py

@@ -0,0 +1,195 @@
+"""Module discovery via Python entry_points and dependency ordering."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from importlib.metadata import entry_points
+
+from simple_module_core.exceptions import CircularDependencyError, InvalidModuleError
+from simple_module_core.module import ModuleBase, ModuleMeta
+
+logger = logging.getLogger(__name__)
+
+ENTRY_POINT_GROUP = "simple_module"
+
+
+def get_module_package_name(module: ModuleBase) -> str:
+    """Return the top-level Python package a module instance belongs to.
+
+    Used by Alembic env.py, the frontend manifest generator, and diagnostics
+    to locate a module's files (models, pages, templates) on disk.
+    """
+    return type(module).__module__.split(".")[0]
+
+
+def discover_modules(
+    enabled: Sequence[str] | None = None,
+    *,
+    strict: bool = False,
+) -> list[ModuleBase]:
+    """Discover all installed modules via ``[project.entry-points.simple_module]``.
+
+    Returns instantiated module objects (unsorted). Raises
+    :class:`FrameworkVersionError` if any discovered module's
+    ``requires_framework`` spec rejects the current framework API version.
+
+    Parameters
+    ----------
+    enabled:
+        Optional allowlist of module names (case-insensitive matched against
+        ``ModuleMeta.name``). When ``None`` (default), every installed module
+        is loaded. When a list, only modules whose name appears in it are
+        loaded. Names that don't match any installed module log a warning.
+        An empty list loads nothing.
+    strict:
+        When ``True``, any invalid module (failed to load, not a
+        ``ModuleBase`` subclass, missing/invalid ``meta``) raises
+        :class:`InvalidModuleError` immediately. Callers in production
+        should pass ``strict=True`` so a broken deployment fails loudly
+        at boot rather than silently losing a feature.
+
+        When ``False`` (the default — preserves dev ergonomics), invalid
+        modules are logged and skipped.
+    """
+    # Imported here to avoid a circular import at module load time.
+    from simple_module_core.versioning import check_framework_compatibility
+
+    def fail(msg: str, exc: BaseException | None = None) -> None:
+        if strict:
+            raise InvalidModuleError(msg) from exc
+        if exc is not None:
+            logger.exception("%s — skipping", msg)
+        else:
+            logger.error("%s — skipping", msg)
+
+    eps = entry_points(group=ENTRY_POINT_GROUP)
+    modules: list[ModuleBase] = []
+    allowlist_lower = {name.lower() for name in enabled} if enabled is not None else None
+
+    for ep in eps:
+        try:
+            module_cls = ep.load()
+        except Exception as exc:
+            fail(f"Failed to load module entry point '{ep.name}': {exc}", exc)
+            continue
+
+        try:
+            instance = module_cls()
+        except Exception as exc:
+            fail(
+                f"Failed to instantiate module '{ep.name}' ({module_cls!r}): {exc}",
+                exc,
+            )
+            continue
+
+        if not isinstance(instance, ModuleBase):
+            fail(
+                f"Entry point '{ep.name}' loaded {module_cls!r} which is not a ModuleBase subclass"
+            )
+            continue
+
+        meta = getattr(instance, "meta", None)
+        if not isinstance(meta, ModuleMeta):
+            fail(
+                f"Module {module_cls.__qualname__!r} (entry point '{ep.name}') "
+                "is missing 'meta = ModuleMeta(...)'"
+            )
+            continue
+
+        if allowlist_lower is not None and meta.name.lower() not in allowlist_lower:
+            logger.info(
+                "Module '%s' is installed but not in modules_enabled — skipping",
+                meta.name,
+            )
+            continue
+
+        modules.append(instance)
+        logger.info("Discovered module: %s (v%s)", meta.name, meta.version)
+
+    # Warn about allowlist entries that didn't resolve to an installed module.
+    if allowlist_lower is not None:
+        loaded = {m.meta.name.lower() for m in modules}
+        missing = allowlist_lower - loaded
+        for name in missing:
+            logger.warning(
+                "modules_enabled references '%s' which is not installed — ignoring",
+                name,
+            )
+
+    check_framework_compatibility(modules)
+    return modules
+
+
+def topological_sort(modules: Sequence[ModuleBase]) -> list[ModuleBase]:
+    """Sort modules so dependencies come before dependents.
+
+    Raises ``CircularDependencyError`` if a cycle is detected.
+    """
+    by_name: dict[str, ModuleBase] = {m.meta.name: m for m in modules}
+
+    # Kahn's algorithm
+    in_degree: dict[str, int] = dict.fromkeys(by_name, 0)
+    dependents: dict[str, list[str]] = {name: [] for name in by_name}
+
+    for mod in modules:
+        for dep_name in mod.meta.depends_on:
+            if dep_name not in by_name:
+                logger.warning(
+                    "Module '%s' depends on '%s' which is not installed — ignoring",
+                    mod.meta.name,
+                    dep_name,
+                )
+                continue
+            in_degree[mod.meta.name] += 1
+            dependents[dep_name].append(mod.meta.name)
+
+    queue: list[str] = [name for name, deg in in_degree.items() if deg == 0]
+    result: list[str] = []
+
+    while queue:
+        # Sort queue for deterministic ordering
+        queue.sort()
+        current = queue.pop(0)
+        result.append(current)
+        for dependent in dependents[current]:
+            in_degree[dependent] -= 1
+            if in_degree[dependent] == 0:
+                queue.append(dependent)
+
+    if len(result) != len(by_name):
+        # Find the cycle for a helpful error message
+        remaining = set(by_name.keys()) - set(result)
+        cycle = _find_cycle(remaining, {n: m.meta.depends_on for n, m in by_name.items()})
+        raise CircularDependencyError(cycle)
+
+    return [by_name[name] for name in result]
+
+
+def _find_cycle(nodes: set[str], deps: dict[str, list[str]]) -> list[str]:
+    """Find one cycle in the dependency graph for error reporting."""
+    visited: set[str] = set()
+    path: list[str] = []
+
+    def dfs(node: str) -> list[str] | None:
+        if node in visited:
+            idx = path.index(node) if node in path else 0
+            return [*path[idx:], node]
+        visited.add(node)
+        path.append(node)
+        for dep in deps.get(node, []):
+            if dep in nodes:
+                result = dfs(dep)
+                if result:
+                    return result
+        path.pop()
+        return None
+
+    for node in nodes:
+        visited.clear()
+        path.clear()
+        cycle = dfs(node)
+        if cycle:
+            return cycle
+
+    return list(nodes)  # fallback

simple_module_core/dotenv.py

@@ -0,0 +1,38 @@
+"""Minimal ``.env`` parser — dependency-free.
+
+Used in places that can't or shouldn't pull in ``pydantic-settings`` (the
+diagnostics CLI runs before the host package is imported; the users-module
+bootstrap runs after settings are constructed and needs to read values that
+``UsersSettings`` deliberately omits from ``env_file``).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def parse_dotenv(path: Path | None = None) -> dict[str, str]:
+    """Parse a ``.env`` file into a dict. Empty dict if the file is missing.
+
+    Values surrounded by matching single or double quotes have the quotes
+    stripped. Does *not* handle escapes, ``export KEY=…``, or multiline
+    values — keep the file simple. Does *not* mutate ``os.environ``; the
+    caller decides whether to merge.
+
+    Without ``path``, looks up ``$SM_PROJECT_ROOT/.env`` (falling back to
+    ``$CWD/.env``) — the convention used by every tool in this repo.
+    """
+    if path is None:
+        root = Path(os.environ.get("SM_PROJECT_ROOT") or Path.cwd())
+        path = root / ".env"
+    if not path.is_file():
+        return {}
+    parsed: dict[str, str] = {}
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        parsed[key.strip()] = value.strip().strip('"').strip("'")
+    return parsed

simple_module_core/environments.py

@@ -0,0 +1,15 @@
+"""Shared environment-classification constants.
+
+Both the host and module settings validators need to know which ``SM_ENVIRONMENT``
+values are "non-prod" — anything outside this set is treated as production
+and subject to stricter defaults (e.g. placeholder-secret rejection).
+
+Duplicating this constant in each settings module would mean an operator who
+adds ``"staging"`` to one list but forgets the other gets inconsistent
+validation. Lives in ``simple_module_core`` because both the host package and
+module settings already depend on it.
+"""
+
+from __future__ import annotations
+
+NON_PROD_ENVIRONMENTS: frozenset[str] = frozenset({"development", "testing"})