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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_core"
-version = "0.0.33"
+version = "0.0.34"
 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.34}/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.34}/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.34}/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.34}/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.33 → simple_module_core-0.0.34}/simple_module_core/permissions.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Collection
 from dataclasses import dataclass, field
 
 WILDCARD = "*"
@@ -26,6 +27,23 @@ def is_admin(roles: list[str] | None) -> bool:
     return bool(roles) and ADMIN_ROLE in roles
 
 
+def grants(held: Collection[str], required: str) -> bool:
+    """Whether a principal holding *held* satisfies *required*.
+
+    One place for the wildcard rule, so code that gates something *inside* a
+    response — a column, a label, a card — reads the grant the same way
+    ``RequiresPermission`` reads it at the door. Two hand-rolled ``in`` checks
+    are two chances to forget that ``admin`` holds ``*`` and nothing else.
+
+    An empty *required* is satisfied by anything: callers use it to mean "no
+    permission gates this", which is the default for a declaration that never
+    named one.
+    """
+    if not required:
+        return True
+    return WILDCARD in held or required in held
+
+
 @dataclass
 class PermissionGroup:
     """A named group of related permissions (typically one per module)."""

{simple_module_core-0.0.33 → simple_module_core-0.0.34}/tests/test_audit_links.py

@@ -113,6 +113,25 @@ class TestLabelResolver:
             )
         assert len(reg.all_links) == 1
 
+    def test_label_permission_defaults_to_ungated(self):
+        """Most row names disclose nothing a reader of the audit log should not
+        already see — a setting key, a filename — so declaring nothing means
+        "anyone who may read the trail may read the name"."""
+        assert AuditLink(entity_type="Setting", url_template="/s/{id}").label_permission == ""
+
+    def test_label_permission_is_part_of_the_claim(self):
+        """Unlike the resolver, it is compared: two modules disagreeing about
+        who may see a name is exactly the conflict the registry exists to
+        catch, and silently keeping the looser one would be the wrong answer."""
+        reg = AuditLinkRegistry()
+        reg.register(AuditLink(entity_type="User", url_template="/u/{id}"))
+        with pytest.raises(ValueError, match="Two modules claim"):
+            reg.register(
+                AuditLink(
+                    entity_type="User", url_template="/u/{id}", label_permission="users.manage"
+                )
+            )
+
     def test_genuinely_conflicting_claims_still_raise(self):
         reg = AuditLinkRegistry()
         reg.register(AuditLink(entity_type="User", url_template="/a/{id}"))

{simple_module_core-0.0.33 → simple_module_core-0.0.34}/tests/test_i18n_diagnostics.py

@@ -99,3 +99,43 @@ def test_extra_sources_detect_key_drift(tmp_path: Path) -> None:
     ).run([])
     codes = {f.code for f in findings}
     assert "SM014" in codes
+
+
+class TestUndeclaredLocaleSet:
+    """``supported_locales=None`` — nobody said which locales this install ships.
+
+    ``make doctor`` runs with no ``SM_I18N_SUPPORTED_LOCALES`` on a stock
+    checkout, and the whole diagnostic used to be skipped in that state: drift
+    between two catalogs that *are* both shipped went unreported because no
+    third file declared them. The files on disk are themselves the declaration.
+    """
+
+    def test_key_drift_is_reported_without_a_declared_locale_set(self, tmp_path: Path) -> None:
+        _write(tmp_path / "p", "en", {"a": "1"})
+        _write(tmp_path / "p", "es", {"a": "1", "orphan": "x"})
+        mod = _FakeModule("P", {"p": tmp_path / "p"})
+        findings = I18nDiagnostics(supported_locales=None, default_locale="en").run([mod])
+        assert {f.code for f in findings} == {"SM015"}
+
+    def test_a_locale_nobody_promised_is_not_reported_missing(self, tmp_path: Path) -> None:
+        """SM013 is a broken promise; with no declared set there is no promise."""
+        _write(tmp_path / "p", "en", {"a": "1"})
+        _write(tmp_path / "q", "en", {"a": "1"})
+        _write(tmp_path / "q", "es", {"a": "1"})
+        mod = _FakeModule("P", {"p": tmp_path / "p", "q": tmp_path / "q"})
+        findings = I18nDiagnostics(supported_locales=None, default_locale="en").run([mod])
+        assert findings == []
+
+    def test_extra_sources_are_auto_detected_too(self, tmp_path: Path) -> None:
+        _write(tmp_path / "ui_locales", "en", {"a": "1", "b": "2"})
+        _write(tmp_path / "ui_locales", "es", {"a": "1"})
+        findings = I18nDiagnostics(
+            supported_locales=None,
+            default_locale="en",
+            extra_sources=[("packages/ui", "ui", tmp_path / "ui_locales")],
+        ).run([])
+        assert [f.code for f in findings] == ["SM014"]
+
+    def test_a_missing_locale_dir_is_silently_skipped(self, tmp_path: Path) -> None:
+        mod = _FakeModule("P", {"p": tmp_path / "nope"})
+        assert I18nDiagnostics(supported_locales=None, default_locale="en").run([mod]) == []

{simple_module_core-0.0.33 → simple_module_core-0.0.34}/tests/test_permissions.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from simple_module_core.permissions import WILDCARD, PermissionRegistry
+from simple_module_core.permissions import WILDCARD, PermissionRegistry, grants
 
 
 class TestPermissionRegistry:
@@ -113,3 +113,31 @@ class TestPermissionRegistryMapRole:
         for key, val in result.items():
             assert isinstance(key, str)
             assert isinstance(val, list)
+
+
+class TestGrants:
+    """The wildcard rule, in one place.
+
+    Anything gating part of a *response* rather than a route reads grants
+    through here — a second hand-rolled ``in`` check is a second chance to
+    forget that ``admin`` holds ``*`` and no named permission at all.
+    """
+
+    async def test_a_held_permission_is_granted(self):
+        assert grants({"users.manage"}, "users.manage") is True
+
+    async def test_a_missing_permission_is_not(self):
+        assert grants({"audit_log.view"}, "users.manage") is False
+
+    async def test_the_wildcard_satisfies_anything(self):
+        assert grants({WILDCARD}, "users.manage") is True
+
+    async def test_an_empty_requirement_is_satisfied_by_nothing_held(self):
+        """Empty means "no permission gates this" — the default for a
+        declaration that never named one, not a requirement nobody meets."""
+        assert grants(set(), "") is True
+
+    async def test_it_reads_any_collection(self):
+        """Callers hand it whatever they have — the middleware caches a set,
+        a test hands a list."""
+        assert grants(["users.manage"], "users.manage") is True