simple-module-core 0.0.3__tar.gz → 0.0.4__tar.gz

{simple_module_core-0.0.3 → simple_module_core-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_core
-Version: 0.0.3
+Version: 0.0.4
 Summary: Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python

{simple_module_core-0.0.3 → simple_module_core-0.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_core"
-version = "0.0.3"
+version = "0.0.4"
 description = "Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events"
 readme = "README.md"
 license = "MIT"

{simple_module_core-0.0.3 → simple_module_core-0.0.4}/simple_module_core/__main__.py

@@ -20,12 +20,14 @@ import sys
 from pathlib import Path
 
 from simple_module_core.diagnostics import (
+    Diagnostic,
     DiagnosticLevel,
     print_diagnostics,
     run_diagnostics,
 )
 from simple_module_core.discovery import discover_modules, topological_sort
 from simple_module_core.dotenv import parse_dotenv
+from simple_module_core.exceptions import InvalidModuleError
 
 
 def _load_i18n_settings_from_env() -> tuple[list[str], str] | tuple[None, None]:
@@ -69,7 +71,31 @@ def _discover_extra_locale_sources() -> list[tuple[str, str, Path]]:
 
 
 def main() -> int:
-    modules = discover_modules()
+    # ``make doctor`` exists specifically to surface broken modules. The
+    # default (lenient) discovery would silently skip a module whose entry
+    # point fails to load, so doctor would report "all clear" while a
+    # feature was missing from the boot. Use strict and translate the
+    # raised error into a diagnostic so the rest of the run still happens.
+    try:
+        modules = discover_modules(strict=True)
+    except InvalidModuleError as exc:
+        print_diagnostics(
+            [
+                Diagnostic(
+                    level=DiagnosticLevel.ERROR,
+                    code="SM001",
+                    message=str(exc),
+                    module_name="<discovery>",
+                    suggestion=(
+                        "Fix the entry point above (broken import, missing 'meta', "
+                        "or a class that isn't a ModuleBase subclass). Re-run "
+                        "`make doctor` once resolved."
+                    ),
+                )
+            ]
+        )
+        return 1
+
     if not modules:
         print("No modules discovered. Is the project installed (`uv sync --all-packages`)?")
         return 0

{simple_module_core-0.0.3 → simple_module_core-0.0.4}/simple_module_core/diagnostics/_module.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import ast
 import importlib.util
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -10,40 +9,13 @@ 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._pages import check_pages, find_render_calls
 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."""
 
@@ -53,15 +25,15 @@ class ModuleDiagnostics:
         diagnostics.extend(self._check_schema_conflicts(modules))
         diagnostics.extend(self._check_empty_modules(modules))
         diagnostics.extend(self._check_missing_meta(modules))
+        diagnostics.extend(self._check_views_without_menu(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))
+                rendered_pages = find_render_calls(mod, src_dir)
+                diagnostics.extend(check_pages(mod, src_dir, rendered_pages))
                 diagnostics.extend(check_js_workspace_files(mod, src_dir))
                 diagnostics.extend(check_inertia_api_calls(mod, src_dir))
 
@@ -144,6 +116,52 @@ class ModuleDiagnostics:
                 )
         return diags
 
+    def _check_views_without_menu(self, modules: list[ModuleBase]) -> list[Diagnostic]:
+        """Warn when a module ships view routes but is silently invisible.
+
+        A module that overrides ``register_routes`` and declares a non-empty
+        ``view_prefix`` produces user-facing pages. Without either
+        ``register_menu_items`` (so admins can navigate to it from the sidebar)
+        or ``register_permissions`` (so admins can see it in the role-permission
+        editor), the module is silently invisible from the admin UI.
+
+        Modules that surface their views as sub-pages of another module (e.g.
+        deep-link edit forms reached from buttons elsewhere) typically register
+        permissions even when they don't add a sidebar entry — that suffices to
+        keep them discoverable through the role editor.
+        """
+        diags: list[Diagnostic] = []
+        for mod in modules:
+            cls = type(mod)
+            meta = getattr(mod, "meta", None)
+            silently_invisible = (
+                meta is not None
+                and getattr(meta, "view_prefix", "")
+                and "register_routes" in cls.__dict__
+                and "register_menu_items" not in cls.__dict__
+                and "register_permissions" not in cls.__dict__
+            )
+            if not silently_invisible:
+                continue
+            diags.append(
+                Diagnostic(
+                    level=DiagnosticLevel.WARNING,
+                    code="SM019",
+                    message=(
+                        f"Module '{meta.name}' registers view routes "
+                        f"(view_prefix={meta.view_prefix!r}) but no menu items "
+                        "or permissions"
+                    ),
+                    module_name=meta.name,
+                    suggestion=(
+                        "Override register_menu_items() to surface this module "
+                        "in the sidebar, register_permissions() to surface it in "
+                        "the role editor, or clear view_prefix if it's API-only"
+                    ),
+                )
+            )
+        return diags
+
     def _check_missing_meta(self, modules: list[ModuleBase]) -> list[Diagnostic]:
         diags: list[Diagnostic] = []
         for mod in modules:
@@ -168,84 +186,6 @@ class ModuleDiagnostics:
                 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]

simple_module_core-0.0.4/simple_module_core/diagnostics/_pages.py

@@ -0,0 +1,121 @@
+"""SM003/SM004 page-vs-render diagnostics for Inertia view modules."""
+
+from __future__ import annotations
+
+import ast
+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 _module_level_str_consts(tree: ast.Module) -> dict[str, str]:
+    """Return ``{name: literal}`` for top-level ``NAME = "string"`` assignments."""
+    return {
+        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)
+    }
+
+
+def _iter_render_components(tree: ast.Module, consts: dict[str, str]) -> list[str]:
+    """Yield ``X.render(component, ...)`` first-arg values, resolving Name references."""
+    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
+
+
+def collect_tsx_pages(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 (``components/``, ``hooks/``,
+    ...) are treated as helper folders, not Inertia page roots, matching the
+    PascalCase convention Inertia uses.
+    """
+    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 find_render_calls(mod: ModuleBase, src_dir: Path) -> set[str]:
+    """Find inertia.render("Module/Page") calls in this module's source tree.
+
+    Resolves ``inertia.render(NAME)`` where ``NAME`` is a string constant
+    defined at module scope in any sibling .py file (e.g. ``constants.py``).
+    Each .py file is parsed once: a first pass collects every module-level
+    string const, a second pass walks render calls against the merged map.
+    """
+    trees: list[ast.Module] = []
+    for py_file in src_dir.rglob("*.py"):
+        try:
+            trees.append(ast.parse(py_file.read_text(), filename=str(py_file)))
+        except (SyntaxError, OSError):
+            continue
+    consts: dict[str, str] = {}
+    for tree in trees:
+        consts.update(_module_level_str_consts(tree))
+
+    prefix = f"{mod.meta.name}/"
+    rendered: set[str] = set()
+    for tree in trees:
+        for component in _iter_render_components(tree, consts):
+            if component.startswith(prefix):
+                rendered.add(component[len(prefix) :])
+    return rendered
+
+
+def check_pages(
+    mod: ModuleBase,
+    src_dir: Path,
+    rendered_pages: set[str],
+) -> list[Diagnostic]:
+    """Diff .tsx pages against rendered_pages — emits SM003 + SM004 in one pass."""
+    pages_dir = src_dir / "pages"
+    tsx_pages = collect_tsx_pages(pages_dir)
+    diags: list[Diagnostic] = [
+        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 tsx_pages - rendered_pages
+    ]
+    diags.extend(
+        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 rendered_pages - tsx_pages
+    )
+    return diags

{simple_module_core-0.0.3 → simple_module_core-0.0.4}/simple_module_core/dotenv.py

@@ -1,4 +1,4 @@
-"""Minimal ``.env`` parser — dependency-free.
+"""Minimal ``.env`` parser + env-var helpers — 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
@@ -11,6 +11,9 @@ from __future__ import annotations
 import os
 from pathlib import Path
 
+BOOL_LITERALS_TRUE = frozenset({"1", "true", "t", "yes", "y", "on"})
+BOOL_LITERALS_FALSE = frozenset({"0", "false", "f", "no", "n", "off"})
+
 
 def parse_dotenv(path: Path | None = None) -> dict[str, str]:
     """Parse a ``.env`` file into a dict. Empty dict if the file is missing.
@@ -36,3 +39,31 @@ def parse_dotenv(path: Path | None = None) -> dict[str, str]:
         key, _, value = line.partition("=")
         parsed[key.strip()] = value.strip().strip('"').strip("'")
     return parsed
+
+
+def load_dotenv_into_environ(path: Path | None = None) -> None:
+    """Merge ``parse_dotenv(path)`` into ``os.environ`` via ``setdefault``.
+
+    Same precedence as the web process under uvicorn: real environment wins
+    over file values. Worker entrypoints call this before importing settings.
+    """
+    for key, value in parse_dotenv(path).items():
+        os.environ.setdefault(key, value)
+
+
+def env_str(name: str, default: str) -> str:
+    """Return ``$name`` if set and non-empty, else ``default``."""
+    value = os.environ.get(name, "").strip()
+    return value or default
+
+
+def env_bool(name: str, default: bool = False) -> bool:
+    """Parse ``$name`` as a boolean, returning ``default`` when unset/blank."""
+    raw = os.environ.get(name, "").strip().lower()
+    if not raw:
+        return default
+    if raw in BOOL_LITERALS_TRUE:
+        return True
+    if raw in BOOL_LITERALS_FALSE:
+        return False
+    return default

{simple_module_core-0.0.3 → simple_module_core-0.0.4}/simple_module_core/feature_flags.py

@@ -144,6 +144,11 @@ def feature_flag(
     directly to the handler. The decorated function must accept a
     ``request: Request`` parameter (FastAPI injects it automatically).
 
+    For new code prefer ``Depends(require_flag(...))`` — it's the standard
+    FastAPI pattern, composes with ``dependencies=[]``, and avoids any
+    per-request signature inspection. The decorator stays for sites that
+    already use it.
+
     Usage::
 
         @router.post("/bulk")
@@ -164,11 +169,34 @@ def feature_flag(
                 f"'request: Request' parameter for the decorator to read tenant state"
             )
 
+        # Pre-compute the request param's positional index so the wrapper
+        # avoids a ``sig.bind`` call per request — sig.bind allocates a
+        # BoundArguments object and walks every parameter, which is
+        # measurable on hot endpoints under load.
+        positional_params = [
+            p.name
+            for p in sig.parameters.values()
+            if p.kind
+            in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+        ]
+        try:
+            request_index: int | None = positional_params.index(request_param)
+        except ValueError:
+            request_index = None
+
+        def _resolve_request(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Request:
+            if request_param in kwargs:
+                return kwargs[request_param]
+            if request_index is not None and request_index < len(args):
+                return args[request_index]
+            # Fallback for unusual call shapes (kw-only, partial application).
+            return sig.bind(*args, **kwargs).arguments[request_param]
+
         if inspect.iscoroutinefunction(fn):
 
             @functools.wraps(fn)
             async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
-                request = sig.bind(*args, **kwargs).arguments[request_param]
+                request = _resolve_request(args, kwargs)
                 if not is_flag_enabled(request, name):
                     raise HTTPException(status_code=404, detail="Feature not available")
                 return await fn(*args, **kwargs)
@@ -177,7 +205,7 @@ def feature_flag(
 
         @functools.wraps(fn)
         def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
-            request = sig.bind(*args, **kwargs).arguments[request_param]
+            request = _resolve_request(args, kwargs)
             if not is_flag_enabled(request, name):
                 raise HTTPException(status_code=404, detail="Feature not available")
             return fn(*args, **kwargs)

{simple_module_core-0.0.3 → simple_module_core-0.0.4}/simple_module_core/menu.py

@@ -33,6 +33,11 @@ class MenuItem:
     method: MenuItemMethod = "get"
     """HTTP method used when the item is activated. ``"post"`` renders as an
     Inertia form submission so the target endpoint can be POST-only (e.g. logout)."""
+    group: str = ""
+    """Sidebar group label. Empty = ungrouped (renders flat, no header).
+    Items in the same section that share a group are visually clustered under a
+    header in the order they already sort by ``order``; the group's own position
+    is set by the lowest-ordered item that belongs to it."""
 
 
 class MenuRegistry:
@@ -83,6 +88,7 @@ class MenuRegistry:
                     "url": item.url,
                     "icon": item.icon,
                     "method": item.method,
+                    "group": item.group,
                 }
             )
 

{simple_module_core-0.0.3 → simple_module_core-0.0.4}/simple_module_core/module.py

@@ -107,8 +107,13 @@ class ModuleBase(ABC):
     def register_feature_flags(self, registry: FeatureFlagRegistry) -> None:
         """Declare feature flags this module exposes."""
 
-    def register_event_handlers(self, bus: EventBus) -> None:
-        """Subscribe to events published by other modules."""
+    def register_event_handlers(self, bus: EventBus, app: FastAPI | None = None) -> None:
+        """Subscribe to events published by other modules.
+
+        ``app`` is optional for back-compat; pass it through to handlers
+        that need ``app.state.sm.db.session_factory`` to persist on the
+        framework's engine instead of building their own.
+        """
 
     def register_health_checks(self, registry: HealthRegistry) -> None:
         """Contribute health checks for the ``/health/ready`` endpoint."""

{simple_module_core-0.0.3 → simple_module_core-0.0.4}/tests/test_discovery.py

@@ -115,9 +115,9 @@ class TestDiscoverModules:
         """discover_modules() should find modules registered via entry_points."""
         modules = discover_modules()
         names = [m.meta.name for m in modules]
-        assert "Products" in names
         assert "Auth" in names
         assert "Dashboard" in names
+        assert "Users" in names
 
 
 class TestDiscoverModulesAdvanced:
@@ -221,7 +221,7 @@ class TestSelectiveModuleLoading:
         """Passing enabled=None keeps existing behaviour (load all installed modules)."""
         all_mods = discover_modules(enabled=None)
         names = {m.meta.name for m in all_mods}
-        assert {"Auth", "Products", "Dashboard"}.issubset(names)
+        assert {"Auth", "Users", "Dashboard"}.issubset(names)
 
     async def test_discover_with_allowlist_filters(self):
         """Passing enabled=['Auth'] loads only Auth, even if other modules are installed."""
@@ -234,9 +234,9 @@ class TestSelectiveModuleLoading:
         assert discover_modules(enabled=[]) == []
 
     async def test_discover_allowlist_case_insensitive(self):
-        """Allowlist matching ignores case so 'products' and 'Products' both work."""
-        names = [m.meta.name for m in discover_modules(enabled=["products"])]
-        assert names == ["Products"]
+        """Allowlist matching ignores case so 'dashboard' and 'Dashboard' both work."""
+        names = [m.meta.name for m in discover_modules(enabled=["dashboard"])]
+        assert names == ["Dashboard"]
 
     async def test_discover_unknown_name_logged_and_ignored(self, caplog):
         """Names in enabled that don't match any installed module log a warning but don't raise."""

{simple_module_core-0.0.3 → simple_module_core-0.0.4}/tests/test_menu.py

@@ -100,3 +100,17 @@ class TestMenuRegistryAdvanced:
         reg.add(MenuItem(label="Home", url="/", icon="home"))
         result = reg.get_for_user(is_authenticated=True)
         assert result["sidebar"][0]["icon"] == "home"
+
+    async def test_group_default_empty(self):
+        reg = MenuRegistry()
+        reg.add(MenuItem(label="Home", url="/"))
+        result = reg.get_for_user(is_authenticated=True)
+        assert result["sidebar"][0]["group"] == ""
+
+    async def test_group_serialized(self):
+        reg = MenuRegistry()
+        reg.add(MenuItem(label="Users", url="/users", group="Administration"))
+        reg.add(MenuItem(label="Settings", url="/settings", group="System"))
+        result = reg.get_for_user(is_authenticated=True)
+        groups = [i["group"] for i in result["sidebar"]]
+        assert groups == ["Administration", "System"]

{simple_module_core-0.0.3 → simple_module_core-0.0.4}/tests/test_module_diagnostics.py

@@ -33,6 +33,42 @@ def _mk_module_tree(root: Path, name: str, *, with_pkg_json: bool, with_tsconfig
     return src_dir
 
 
+class TestSm003PageRenderResolution:
+    """SM003 must resolve PAGE_X constants imported from sibling files."""
+
+    def _diags(self, src_dir: Path, mod_name: str):
+        from simple_module_core.diagnostics._pages import check_pages, find_render_calls
+
+        mod = _FakeModule(meta=_FakeMeta(name=mod_name))
+        rendered = find_render_calls(mod, src_dir)  # pyright: ignore[reportArgumentType]
+        return [d for d in check_pages(mod, src_dir, rendered) if d.code == "SM003"]  # pyright: ignore[reportArgumentType]
+
+    async def test_resolves_constant_imported_from_sibling_file(self, tmp_path: Path):
+        src_dir = tmp_path / "feature_flags" / "feature_flags"
+        (src_dir / "pages").mkdir(parents=True)
+        (src_dir / "pages" / "Browse.tsx").write_text("export default function B() {}")
+        (src_dir / "constants.py").write_text('PAGE_BROWSE = "FeatureFlags/Browse"\n')
+        endpoints = src_dir / "endpoints"
+        endpoints.mkdir()
+        (endpoints / "views.py").write_text(
+            "from feature_flags.constants import PAGE_BROWSE\n"
+            "async def view(inertia):\n"
+            "    return await inertia.render(PAGE_BROWSE, {})\n"
+        )
+        assert self._diags(src_dir, "FeatureFlags") == []
+
+    async def test_still_flags_truly_orphan_pages(self, tmp_path: Path):
+        src_dir = tmp_path / "m" / "m"
+        (src_dir / "pages").mkdir(parents=True)
+        (src_dir / "pages" / "Ghost.tsx").write_text("export default function G() {}")
+        (src_dir / "endpoints.py").write_text(
+            'async def view(inertia):\n    return await inertia.render("M/Other", {})\n'
+        )
+        results = self._diags(src_dir, "M")
+        assert [r.code for r in results] == ["SM003"]
+        assert "Ghost.tsx" in results[0].message
+
+
 class TestSm017JsWorkspaceFiles:
     async def test_fires_when_both_missing(self, tmp_path: Path):
         src_dir = _mk_module_tree(tmp_path, "orders", with_pkg_json=False, with_tsconfig=False)
@@ -144,3 +180,80 @@ class TestSM018InertiaApiCalls:
         results = check_inertia_api_calls(mod, src_dir)  # pyright: ignore[reportArgumentType]
 
         assert results == []
+
+
+class TestSM019ViewsWithoutMenu:
+    """SM019 fires when a module ships view routes but never registers a menu item."""
+
+    def _diags(self, modules):
+        from simple_module_core.diagnostics._module import ModuleDiagnostics
+
+        return list(ModuleDiagnostics()._check_views_without_menu(modules))
+
+    async def test_fires_when_views_present_but_no_menu(self):
+        from simple_module_core.module import ModuleBase, ModuleMeta
+
+        class ViewsNoMenu(ModuleBase):
+            meta = ModuleMeta(name="ViewsNoMenu", view_prefix="/views_no_menu")
+
+            def register_routes(self, api_router, view_router):
+                pass
+
+        results = self._diags([ViewsNoMenu()])
+        assert len(results) == 1
+        assert results[0].code == "SM019"
+        assert results[0].level == DiagnosticLevel.WARNING
+        assert "ViewsNoMenu" in results[0].message
+
+    async def test_silent_when_menu_registered(self):
+        from simple_module_core.module import ModuleBase, ModuleMeta
+
+        class WithMenu(ModuleBase):
+            meta = ModuleMeta(name="WithMenu", view_prefix="/with_menu")
+
+            def register_routes(self, api_router, view_router):
+                pass
+
+            def register_menu_items(self, registry):
+                pass
+
+        assert self._diags([WithMenu()]) == []
+
+    async def test_silent_when_api_only_module(self):
+        from simple_module_core.module import ModuleBase, ModuleMeta
+
+        class ApiOnly(ModuleBase):
+            meta = ModuleMeta(name="ApiOnly", route_prefix="/api/only", view_prefix="")
+
+            def register_routes(self, api_router, view_router):
+                pass
+
+        assert self._diags([ApiOnly()]) == []
+
+    async def test_silent_when_register_routes_not_overridden(self):
+        from simple_module_core.module import ModuleBase, ModuleMeta
+
+        class NoRoutes(ModuleBase):
+            meta = ModuleMeta(name="NoRoutes", view_prefix="/no_routes")
+
+        assert self._diags([NoRoutes()]) == []
+
+    async def test_silent_when_permissions_registered(self):
+        """A module that registers permissions is visible in the role editor.
+
+        This covers modules whose views are sub-pages of another module (e.g.
+        Permissions' RoleEdit/UserEdit views, reached from the Users admin
+        page) — they don't need a sidebar entry to be discoverable.
+        """
+        from simple_module_core.module import ModuleBase, ModuleMeta
+
+        class WithPermissions(ModuleBase):
+            meta = ModuleMeta(name="WithPermissions", view_prefix="/with_permissions")
+
+            def register_routes(self, api_router, view_router):
+                pass
+
+            def register_permissions(self, registry):
+                pass
+
+        assert self._diags([WithPermissions()]) == []