simple-module-core 0.0.33__tar.gz → 0.0.35__tar.gz

{simple_module_core-0.0.33 → simple_module_core-0.0.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_core
-Version: 0.0.33
+Version: 0.0.35
 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.33 → simple_module_core-0.0.35}/pyproject.toml

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

{simple_module_core-0.0.33 → simple_module_core-0.0.35}/simple_module_core/__init__.py

@@ -36,6 +36,11 @@ from simple_module_core.feature_flags import (
 )
 from simple_module_core.health import HealthCheck, HealthCheckResult, HealthRegistry, HealthStatus
 from simple_module_core.i18n import I18nRegistry, Translator
+from simple_module_core.invalidation import (
+    Invalidation,
+    InvalidationBus,
+    InvalidationTransport,
+)
 from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
 from simple_module_core.module import ModuleBase, ModuleMeta
 from simple_module_core.permissions import PermissionRegistry
@@ -66,6 +71,9 @@ __all__ = [
     "HealthStatus",
     "I18nRegistry",
     "InvalidModuleError",
+    "Invalidation",
+    "InvalidationBus",
+    "InvalidationTransport",
     "LabelResolver",
     "MenuItem",
     "MenuRegistry",

{simple_module_core-0.0.33 → simple_module_core-0.0.35}/simple_module_core/__main__.py

@@ -7,10 +7,14 @@ Usage::
 
 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 the project root (``SM_PROJECT_ROOT``, else the
-directory of the discovered ``.env``, else the current working dir).
+i18n checks always run. ``SM_I18N_SUPPORTED_LOCALES`` (env or ``.env``)
+declares the locale set this install promises, which also enables SM013 for a
+namespace that never shipped one; with it unset, each namespace is checked
+against the locale files it actually has, so key drift between two shipped
+translations is still caught. Host-level ``host/locales/`` and shared
+``packages/ui/locales/`` are picked up relative to the project root
+(``SM_PROJECT_ROOT``, else the directory of the discovered ``.env``, else the
+current working dir).
 """
 
 from __future__ import annotations
@@ -36,8 +40,14 @@ from simple_module_core.dotenv import find_env_file, parse_dotenv
 from simple_module_core.exceptions import InvalidModuleError
 
 
-def _load_i18n_settings_from_env() -> tuple[list[str], str] | tuple[None, None]:
-    """Return ``(supported_locales, default_locale)`` or ``(None, None)`` if unset.
+def _load_i18n_settings_from_env() -> tuple[list[str] | None, str]:
+    """Return ``(supported_locales, default_locale)``.
+
+    ``supported_locales`` is ``None`` when ``SM_I18N_SUPPORTED_LOCALES`` is
+    unset or unparseable — the diagnostic then falls back to the locale files
+    each namespace ships rather than running no locale checks at all. The
+    default locale always has a value, because a parity comparison needs to
+    know which side is the source of truth.
 
     Reads env vars directly to avoid a dependency on ``simple_module_hosting``.
     Honors ``.env`` by merging it into ``os.environ`` if present (pydantic-
@@ -46,9 +56,10 @@ def _load_i18n_settings_from_env() -> tuple[list[str], str] | tuple[None, None]:
     for key, value in parse_dotenv().items():
         os.environ.setdefault(key, value)
 
+    default = os.environ.get("SM_I18N_DEFAULT_LOCALE", "en")
     supported_raw = os.environ.get("SM_I18N_SUPPORTED_LOCALES")
     if not supported_raw:
-        return None, None
+        return None, default
 
     try:
         supported = json.loads(supported_raw)
@@ -57,9 +68,8 @@ def _load_i18n_settings_from_env() -> tuple[list[str], str] | tuple[None, None]:
         supported = [s.strip() for s in supported_raw.split(",") if s.strip()]
 
     if not isinstance(supported, list) or not supported:
-        return None, None
+        return None, default
 
-    default = os.environ.get("SM_I18N_DEFAULT_LOCALE", "en")
     return supported, default
 
 

{simple_module_core-0.0.33 → simple_module_core-0.0.35}/simple_module_core/audit_links.py

@@ -11,10 +11,15 @@ A module declares where its rows live via
 collects them into one registry at boot and stores it on
 ``app.state.sm.audit_links``.
 
-**The registry maps model class names to URL templates, nothing more.** It does
-not verify the row exists or that the reader may open it — following a link to a
-deleted record lands on that screen's own 404, and permissions are enforced by
-the target route as usual.
+**A link is a route, not an authorisation.** The registry does not verify the
+row exists or that the reader may open it — following a link to a deleted
+record lands on that screen's own 404, and permissions are enforced by the
+target route as usual.
+
+The one exception is ``label_permission``: the *name* of a row travels in the
+audit payload itself, so no downstream route ever gets the chance to refuse it.
+A module whose row names disclose something it gates elsewhere says so there,
+and readers without that permission see the id instead.
 """
 
 from __future__ import annotations
@@ -76,6 +81,15 @@ class AuditLink:
             a closure, and two boots would build two unequal objects out of one
             module — a registry conflict is about two modules claiming one
             entity type, which the identity fields already express.
+        label_permission: Permission a reader must hold before
+            ``label_resolver`` is *run* for them. Empty — the default — means
+            the name is safe for anyone allowed to read the audit trail at all.
+            Set it when naming the row discloses something the module gates
+            elsewhere: ``users`` names an account by ``full_name or email``, so
+            without this an ``audit_log.view`` grant is a back door onto the
+            user directory that ``users.manage`` guards at the front. Denied
+            readers still see the row, the action and the id — the audit trail
+            stays complete, it just stops volunteering the name.
     """
 
     entity_type: str
@@ -84,6 +98,7 @@ class AuditLink:
     label_key: str = ""
     table_name: str | None = None
     label_resolver: LabelResolver | None = field(default=None, compare=False)
+    label_permission: str = ""
 
     def __post_init__(self) -> None:
         if self.url_template and _ID_PLACEHOLDER not in self.url_template:

{simple_module_core-0.0.33 → simple_module_core-0.0.35}/simple_module_core/diagnostics/_i18n.py

@@ -25,19 +25,28 @@ class I18nDiagnostics:
 
     def __init__(
         self,
-        supported_locales: list[str],
+        supported_locales: list[str] | None,
         default_locale: str,
         extra_sources: list[tuple[str, str, Path]] | None = None,
     ) -> None:
         """Build the diagnostic.
 
+        ``supported_locales`` is the set of locales this install promises to
+        ship. ``None`` means *nobody declared one* — each namespace is then
+        checked against the locale files it actually has on disk. SM013 is
+        skipped in that mode (a locale nothing promised cannot be missing),
+        but SM014/SM015 still hold every shipped translation to the default
+        locale's key set. Without this, an install that never set
+        ``SM_I18N_SUPPORTED_LOCALES`` ran no locale checks at all and drift
+        accumulated with nothing to flag it.
+
         ``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.supported_locales = None if supported_locales is None else list(supported_locales)
         self.default_locale = default_locale
         self.extra_sources = list(extra_sources or [])
 
@@ -55,10 +64,14 @@ class I18nDiagnostics:
     ) -> list[Diagnostic]:
         findings: list[Diagnostic] = []
         per_locale_keys: dict[str, set[str]] = {}
+        declared = self.supported_locales is not None
+        locales = self.supported_locales if declared else self._locales_on_disk(locale_dir)
 
-        for locale in self.supported_locales:
+        for locale in locales or ():
             path = locale_dir / f"{locale}.json"
             if not path.is_file():
+                if not declared:
+                    continue
                 findings.append(
                     Diagnostic(
                         level=DiagnosticLevel.WARNING,
@@ -119,3 +132,14 @@ class I18nDiagnostics:
                     )
                 )
         return findings
+
+    @staticmethod
+    def _locales_on_disk(locale_dir: Path) -> list[str]:
+        """Locale tags a directory actually ships, from its ``<tag>.json`` files.
+
+        The default locale sorts first only by accident of the alphabet, which
+        does not matter: the parity comparison below looks it up by name.
+        """
+        if not locale_dir.is_dir():
+            return []
+        return sorted(path.stem for path in locale_dir.glob("*.json"))

{simple_module_core-0.0.33 → simple_module_core-0.0.35}/simple_module_core/diagnostics/_module.py

@@ -11,6 +11,7 @@ from simple_module_core.diagnostics._css import check_module_css
 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._tenancy import check_tenant_unique_keys, module_tables
 from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
 
 if TYPE_CHECKING:
@@ -29,6 +30,8 @@ class ModuleDiagnostics:
         diagnostics.extend(self._check_views_without_menu(modules))
         diagnostics.extend(self._check_auth_provider_conflict(modules))
         diagnostics.extend(check_framework_module_coupling(modules))
+        for mod in modules:
+            diagnostics.extend(check_tenant_unique_keys(module_tables(mod), mod.meta.name))
 
         # File-based checks (need to find module source directories)
         for mod in modules:
@@ -95,6 +98,7 @@ class ModuleDiagnostics:
                     "register_permissions",
                     "register_feature_flags",
                     "register_event_handlers",
+                    "register_invalidations",
                     "register_middleware",
                     "register_health_checks",
                     "register_public_routes",

{simple_module_core-0.0.33 → simple_module_core-0.0.35}/simple_module_core/diagnostics/_pages.py

@@ -89,6 +89,15 @@ def _iter_render_components(tree: ast.Module, consts: dict[str, str]) -> list[st
     return found
 
 
+#: A ``*.test.tsx``/``*.spec.tsx`` beside a page is a test, not a page —
+#: mirrors ``simple_module_hosting.page_globs.TEST_FILE_SUFFIXES``, which
+#: excludes the same files from the Vite glob. Duplicated rather than
+#: imported: ``simple_module_hosting`` depends on ``simple_module_core``,
+#: not the other way around, so importing it here would invert the package
+#: layering.
+_TEST_FILE_SUFFIXES = (".test.tsx", ".spec.tsx")
+
+
 def collect_tsx_pages(pages_dir: Path) -> set[str]:
     """Collect .tsx page identifiers relative to pages_dir, without extension.
 
@@ -96,10 +105,15 @@ def collect_tsx_pages(pages_dir: Path) -> set[str]:
     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.
+    PascalCase convention Inertia uses. Files ending in ``.test.tsx`` or
+    ``.spec.tsx`` are colocated tests, not pages, and are excluded the same
+    way the Vite glob excludes them — otherwise a colocated test with no
+    matching ``inertia.render()`` call is flagged as an SM003 orphan page.
     """
     pages: set[str] = set()
     for f in pages_dir.rglob("*.tsx"):
+        if f.name.endswith(_TEST_FILE_SUFFIXES):
+            continue
         rel = f.relative_to(pages_dir)
         if any(part[:1].islower() for part in rel.parts[:-1]):
             continue

{simple_module_core-0.0.33 → simple_module_core-0.0.35}/simple_module_core/diagnostics/_runner.py

@@ -30,18 +30,20 @@ def run_diagnostics(
     """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``.
+    ``i18n_default_locale`` turns on the locale checks; ``i18n_supported_locales``
+    is the declared locale set, and leaving it empty runs those checks against
+    whatever locale files are on disk instead of skipping them entirely (see
+    :class:`I18nDiagnostics`). ``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:
+    if i18n_default_locale:
         from simple_module_core.diagnostics._i18n import I18nDiagnostics
 
         diagnostics.extend(
             I18nDiagnostics(
-                supported_locales=i18n_supported_locales,
+                supported_locales=i18n_supported_locales or None,
                 default_locale=i18n_default_locale,
                 extra_sources=i18n_extra_sources,
             ).run(modules)

simple_module_core-0.0.35/simple_module_core/diagnostics/_tenancy.py

@@ -0,0 +1,108 @@
+"""SM024: a unique key on a tenant-scoped table that ignores the tenant.
+
+On a ``MultiTenantMixin`` table every business key is per tenant. A unique
+constraint without ``tenant_id`` in it means the first tenant to claim a value
+(a slug, a filename, a name) locks every other tenant out of it — and the
+resulting IntegrityError tells the second tenant the value exists elsewhere.
+
+Duck-typed on SQLAlchemy ``Table`` objects (core does not depend on
+SQLAlchemy). Only tables of models that inherit ``MultiTenantMixin`` count: a
+plain ``tenant_id`` column (``users_user``'s legacy one, the ``tenants``
+registry's own tables) carries no isolation and no per-tenant key rule.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+from collections.abc import Iterable, Iterator
+from typing import TYPE_CHECKING, Any
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+logger = logging.getLogger(__name__)
+
+TENANT_COLUMN = "tenant_id"
+
+
+def _unique_keys(table: Any) -> Iterator[tuple[str, set[str]]]:
+    """Yield ``(label, column names)`` for every unique key except the PK."""
+    for col in table.columns:
+        if col.unique and not col.primary_key:
+            yield f"column '{col.name}'", {col.name}
+    for constraint in table.constraints:
+        if type(constraint).__name__ == "UniqueConstraint":
+            cols = {c.name for c in constraint.columns}
+            yield f"unique constraint {sorted(cols)}", cols
+    for index in table.indexes:
+        if index.unique:
+            cols = {c.name for c in index.columns}
+            label = f"unique index '{index.name}'"
+            # Expression indexes (lower(email)) expose no plain columns; treat
+            # them as not containing the tenant — they are just as global.
+            yield label, cols
+
+
+def check_tenant_unique_keys(tables: Iterable[Any], module_name: str) -> list[Diagnostic]:
+    diags: list[Diagnostic] = []
+    for table in tables:
+        if TENANT_COLUMN not in table.columns:
+            continue
+        reported: set[frozenset[str]] = set()
+        for label, cols in _unique_keys(table):
+            # ``unique=True`` surfaces both as a column flag and as a
+            # UniqueConstraint; report each key once. Expression indexes have
+            # no plain columns and are always reported.
+            key = frozenset(cols)
+            if TENANT_COLUMN in cols or (cols and key in reported):
+                continue
+            reported.add(key)
+            diags.append(
+                Diagnostic(
+                    level=DiagnosticLevel.WARNING,
+                    code="SM024",
+                    message=(
+                        f"Tenant-scoped table '{table.name}' has a {label} that does "
+                        f"not include '{TENANT_COLUMN}' — two tenants cannot both own a value"
+                    ),
+                    module_name=module_name,
+                    suggestion=(
+                        "Make the key per tenant: add tenant_id to the constraint, "
+                        "e.g. Index(..., 'tenant_id', 'slug', unique=True)"
+                    ),
+                )
+            )
+    return diags
+
+
+def _is_tenant_scoped(cls: type) -> bool:
+    return any(base.__name__ == "MultiTenantMixin" for base in cls.__mro__[1:])
+
+
+def module_tables(mod: ModuleBase) -> list[Any]:
+    """Tables of the ``MultiTenantMixin`` models in the module's ``models``."""
+    pkg = type(mod).__module__.rsplit(".", 1)[0]
+    try:
+        models = importlib.import_module(f"{pkg}.models")
+    except ModuleNotFoundError:
+        return []
+    except Exception:  # pragma: no cover - a broken models module fails elsewhere, loudly
+        logger.debug("Could not import %s.models for SM024", pkg, exc_info=True)
+        return []
+    seen: dict[str, Any] = {}
+    for value in vars(models).values():
+        table = getattr(value, "__table__", None)
+        if (
+            isinstance(value, type)
+            and table is not None
+            and hasattr(table, "columns")
+            and _is_tenant_scoped(value)
+        ):
+            seen.setdefault(table.name, table)
+    return list(seen.values())
+
+
+__all__ = ["check_tenant_unique_keys", "module_tables"]