sarj-python-lint 1.88.20__tar.gz → 1.90.1__tar.gz

{sarj_python_lint-1.88.20 → sarj_python_lint-1.90.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.88.20
+Version: 1.90.1
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://code-standards.sarj.ai/rules/python/
 Project-URL: Documentation, https://code-standards.sarj.ai/rules/python/

{sarj_python_lint-1.88.20 → sarj_python_lint-1.90.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.88.20"
+version = "1.90.1"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]

{sarj_python_lint-1.88.20 → sarj_python_lint-1.90.1}/src/sarj_python_lint/rules/_ast_index.py

@@ -59,8 +59,8 @@ def comprehension_results(node: ast.ListComp | ast.SetComp | ast.DictComp | ast.
     return [child for child in children(node) if isinstance(child, ast.expr)]
 
 
-def has_own_yield(function: ast.AsyncFunctionDef) -> bool:
-    pending: list[ast.AST] = list(function.body)
+def has_own_yield(function: ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda) -> bool:
+    pending: list[ast.AST] = [function.body] if isinstance(function, ast.Lambda) else list(function.body)
     while pending:
         match pending.pop():
             case ast.Yield() | ast.YieldFrom():

{sarj_python_lint-1.88.20 → sarj_python_lint-1.90.1}/src/sarj_python_lint/rules/_registry.py

@@ -225,6 +225,7 @@ from sarj_python_lint.rules.duplicate_closed_pure_helper import DuplicateClosedP
 from sarj_python_lint.rules.duplicate_pytest_fixture_params import DuplicatePytestFixtureParams
 from sarj_python_lint.rules.failed_probe_zero_threshold import FailedProbeZeroThreshold
 from sarj_python_lint.rules.nan_hidden_by_builtin_min import NanHiddenByBuiltinMin
+from sarj_python_lint.rules.no_async_client_in_constructor import NoAsyncClientInConstructor
 from sarj_python_lint.rules.no_conflicting_pydantic_alias_validation import NoConflictingPydanticAliasValidation
 from sarj_python_lint.rules.no_contradictory_type_guard import NoContradictoryTypeGuard
 from sarj_python_lint.rules.no_create_verb_in_post_path import NoCreateVerbInPostPath
@@ -274,6 +275,7 @@ from sarj_python_lint.rules.test_without_explicit_oracle import NoExplicitTestOr
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        NoAsyncClientInConstructor.id: NoAsyncClientInConstructor,
         NoDiscardedTaggedOutcome.id: NoDiscardedTaggedOutcome,
         StoreInsertRequiresExplicitConflictPolicy.id: StoreInsertRequiresExplicitConflictPolicy,
         StoreMutationCommandFanout.id: StoreMutationCommandFanout,

sarj_python_lint-1.90.1/src/sarj_python_lint/rules/no_async_client_in_constructor.py

@@ -0,0 +1,340 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._ast_index import has_own_yield
+from sarj_python_lint.rules._resource_provenance import import_name_for_binding
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_CLIENTS = frozenset({"httpx.AsyncClient", "httpx._client.AsyncClient"})
+_MODULES = frozenset({"httpx", "httpx._client"})
+_COMPREHENSIONS = (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)
+_MAX_ALIAS_DEPTH = 32
+_BAD = "import httpx\nclass Service:\n    def __init__(self):\n        self.client = httpx.AsyncClient()\n"
+_GOOD = "from contextlib import asynccontextmanager\nimport httpx\nclass Service:\n    def __init__(self, client: httpx.AsyncClient):\n        self.client = client\n@asynccontextmanager\nasync def service_scope(endpoint):\n    async with httpx.AsyncClient(base_url=endpoint) as client:\n        yield Service(client)\n"
+
+
+@final
+class NoAsyncClientInConstructor(Rule):
+    id = "no-async-client-in-constructor"
+    code = "SARJ549"
+    documentation = RuleDocumentation(
+        default_level=Severity.ERROR,
+        summary="Inject an HTTPX AsyncClient instead of constructing one in __init__.",
+        rationale="Constructor-owned clients repeat transport setup for each service instance and hide the boundary that owns pooling and asynchronous cleanup.",
+        remediation="Create and close an appropriately scoped AsyncClient at the async composition boundary, and inject it into consumers. Keep tenant credentials, cookies, event loops and independent ownership boundaries separate; do not replace them with a global client.",
+        category=RuleCategory.ARCHITECTURE,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "This is an explicit architecture policy for import-proven HTTPX AsyncClient calls executed by synchronous nongenerator class __init__ methods, including import aliases and stable constructor assignment aliases bounded to 32 links, eager comprehensions and nested definition defaults/decorators.",
+            "One-hop same-file undecorated synchronous factories with stable lexical bindings are followed only when their sole statement after an optional docstring returns a proven constructor call. Zero-argument lambda factories are supported when invoked; deferred function/lambda/generator bodies are not constructor execution.",
+            "Unknown or imported factory implementations, overridable methods, wrapper chains, dynamic namespace access, wildcard imports, ambiguous/rebound aliases and visible namespace mutation are not inferred. A generator's first iterable is eager; other generator expressions remain deferred even when a caller might consume them immediately.",
+            "Constructor parameter defaults execute at class definition, not on each constructor call, and are outside this rule. No automatic ownership transfer, sharing decision or lifecycle rewrite is safe.",
+            "Annotations and lazy type-alias/type-parameter expressions are excluded: their source location does not prove constructor-time execution. Framework-driven evaluation of annotations is not inferred.",
+            "Escaped HTTPX module objects cause conservative abstention, including module-object assignment aliases. Constructor aliases must remain confined to calls, annotations, attribute access or stable single-name aliases; unknown argument, return or storage escapes and visible mutation invalidate the import proof.",
+            "Nested class bodies are followed only without bases or metaclass keywords, because custom class namespace preparation can replace imported names. Method bodies still use their normal lexical bindings. Generator factories and lambdas create deferred generators rather than clients and are excluded.",
+            "HTTPX recommends scoped client reuse and explicit asynchronous closure; its API does not universally prohibit constructor ownership. This stricter constructor boundary is the requested policy. See https://www.python-httpx.org/async/ . Ruff ASYNC212 instead owns blocking HTTPX use in async functions.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="constructor-allocation",
+                title="Do not hide client allocation in a service constructor",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/service.py", _BAD),),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="scoped-injection",
+                title="Inject a client owned by the async composition scope",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/service.py", _GOOD),),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if "__init__" not in context.symbol_source or "AsyncClient" not in context.symbol_source:
+            return []
+        if context.generated or context.tree is None or context.has_wildcard_import or context.dynamic_namespace:
+            return []
+        if not _imports_untouched(context):
+            return []
+        constructors = frozenset(
+            node
+            for node in context.nodes(ast.FunctionDef)
+            if node.name == "__init__"
+            and isinstance(context.parents.get(node), ast.ClassDef)
+            and not has_own_yield(node)
+        )
+        factories: dict[ast.FunctionDef | ast.Lambda, bool] = {}
+        findings = [
+            Diagnostic(
+                path=context.path,
+                line=call.lineno,
+                col=call.col_offset + 1,
+                code=self.code,
+                severity=Severity.ERROR,
+                message="httpx.AsyncClient construction in __init__; inject a caller-owned, appropriately scoped AsyncClient and close it at the async composition boundary",
+            )
+            for call in context.nodes(ast.Call)
+            if _in_constructor(context, call, constructors)
+            and _allocates(context, call, follow_factory=True, factories=factories)
+            and not is_suppressed(context.source_lines, call.lineno, self.code)
+        ]
+        return sorted(findings, key=lambda finding: (finding.line, finding.col))
+
+
+def _imports_untouched(context: PythonFileContext) -> bool:
+    safe: dict[ast.alias | ast.Name, bool] = {}
+    for binding in context.nodes(ast.alias):
+        expression = ast.Name(id=binding.asname or binding.name, ctx=ast.Load())
+        qualified = import_name_for_binding(expression, binding, context.parents.get(binding))
+        if (
+            qualified is not None
+            and qualified in _MODULES | _CLIENTS
+            and not _alias_untouched(context, binding, qualified, safe, remaining=_MAX_ALIAS_DEPTH)
+        ):
+            return False
+    return True
+
+
+def _alias_untouched(
+    context: PythonFileContext,
+    binding: ast.alias | ast.Name,
+    qualified: str,
+    safe: dict[ast.alias | ast.Name, bool],
+    *,
+    remaining: int,
+) -> bool:
+    if binding in safe:
+        return safe[binding]
+    safe[binding] = False
+    name = binding.id if isinstance(binding, ast.Name) else binding.asname or binding.name.partition(".")[0]
+    if remaining == 0 or name in context.binding_inventory.mutated:
+        return False
+    safe[binding] = all(
+        _reference_untouched(context, read, qualified, safe, remaining=remaining)
+        for read in context.nodes(ast.Name)
+        if isinstance(read.ctx, ast.Load) and read.id == name and _binding(context, name, read) is binding
+    )
+    return safe[binding]
+
+
+def _reference_untouched(
+    context: PythonFileContext,
+    expression: ast.expr,
+    qualified: str,
+    safe: dict[ast.alias | ast.Name, bool],
+    *,
+    remaining: int,
+) -> bool:
+    if not _runtime_expression(context, expression):
+        return True
+    while qualified in _MODULES:
+        parent = context.parents.get(expression)
+        if not isinstance(parent, ast.Attribute) or parent.value is not expression:
+            return False
+        expression, qualified = parent, f"{qualified}.{parent.attr}"
+    if qualified not in _CLIENTS:
+        return True
+    parent = context.parents.get(expression)
+    if (isinstance(parent, ast.Call) and parent.func is expression) or (
+        isinstance(parent, ast.Attribute) and parent.value is expression
+    ):
+        return True
+    target = _alias_target(context, parent, expression)
+    return target is not None and _alias_untouched(context, target, qualified, safe, remaining=remaining - 1)
+
+
+def _alias_target(context: PythonFileContext, statement: ast.AST | None, value: ast.expr) -> ast.Name | None:
+    if isinstance(statement, ast.Assign) and len(statement.targets) == 1 and statement.value is value:
+        target = statement.targets[0]
+    elif isinstance(statement, ast.AnnAssign) and statement.value is value:
+        target = statement.target
+    else:
+        return None
+    if not isinstance(context.parents.get(statement), ast.Module | ast.FunctionDef | ast.AsyncFunctionDef):
+        return None
+    return target if isinstance(target, ast.Name) and _binding(context, target.id, target) is target else None
+
+
+def _in_constructor(context: PythonFileContext, call: ast.Call, constructors: frozenset[ast.FunctionDef]) -> bool:
+    if not _runtime_expression(context, call):
+        return False
+    scope = context.binding_inventory.scope(call)
+    while isinstance(scope, (ast.ClassDef, *_COMPREHENSIONS)):
+        if isinstance(scope, ast.ClassDef) and (scope.bases or scope.keywords):
+            return False
+        if isinstance(scope, ast.GeneratorExp) and not context.resource_provenance.contains(
+            scope.generators[0].iter, call
+        ):
+            return False
+        scope = context.binding_inventory.scope(scope)
+    return scope in constructors
+
+
+def _runtime_expression(context: PythonFileContext, expression: ast.expr) -> bool:
+    child: ast.AST = expression
+    parent = context.parents.get(child)
+    while parent is not None:
+        if isinstance(parent, ast.TypeAlias | ast.type_param):
+            return False
+        if isinstance(parent, ast.AnnAssign | ast.arg) and parent.annotation is child:
+            return False
+        if isinstance(parent, ast.FunctionDef | ast.AsyncFunctionDef) and parent.returns is child:
+            return False
+        child, parent = parent, context.parents.get(parent)
+    return True
+
+
+def _allocates(
+    context: PythonFileContext,
+    call: ast.Call,
+    *,
+    follow_factory: bool,
+    factories: dict[ast.FunctionDef | ast.Lambda, bool],
+) -> bool:
+    target = _target(context, call.func)
+    if isinstance(target, str):
+        return target in _CLIENTS
+    if not follow_factory or not isinstance(target, ast.FunctionDef | ast.Lambda):
+        return False
+    if isinstance(target, ast.Lambda):
+        arguments = target.args
+        if any(
+            (
+                call.args,
+                call.keywords,
+                arguments.posonlyargs,
+                arguments.args,
+                arguments.kwonlyargs,
+                arguments.vararg,
+                arguments.kwarg,
+            )
+        ):
+            return False
+    if target not in factories:
+        factories[target] = _factory_allocates(context, target, factories)
+    return factories[target]
+
+
+def _factory_allocates(
+    context: PythonFileContext,
+    target: ast.FunctionDef | ast.Lambda,
+    factories: dict[ast.FunctionDef | ast.Lambda, bool],
+) -> bool:
+    if has_own_yield(target):
+        return False
+    if isinstance(target, ast.Lambda):
+        return isinstance(target.body, ast.Call) and _allocates(
+            context, target.body, follow_factory=False, factories=factories
+        )
+    if target.decorator_list:
+        return False
+    body = target.body
+    if (
+        body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+    ):
+        body = body[1:]
+    return (
+        len(body) == 1
+        and isinstance(body[0], ast.Return)
+        and isinstance(body[0].value, ast.Call)
+        and _allocates(context, body[0].value, follow_factory=False, factories=factories)
+    )
+
+
+def _target(context: PythonFileContext, expression: ast.expr) -> str | ast.FunctionDef | ast.Lambda | None:
+    for _ in range(_MAX_ALIAS_DEPTH):
+        if isinstance(expression, ast.Lambda):
+            return expression
+        root = expression
+        while isinstance(root, ast.Attribute):
+            root = root.value
+        if not isinstance(root, ast.Name) or root.id in context.binding_inventory.mutated:
+            return None
+        binding = _binding(context, root.id, expression)
+        if isinstance(binding, ast.alias):
+            return import_name_for_binding(expression, binding, context.parents.get(binding))
+        if not isinstance(expression, ast.Name):
+            return None
+        if isinstance(binding, ast.FunctionDef):
+            return _factory_binding(context, binding, expression)
+        if not isinstance(binding, ast.Name):
+            return None
+        value = context.resource_provenance.assignment_value(binding, expression)
+        if value is None:
+            return None
+        expression = value
+    return None
+
+
+def _factory_binding(context: PythonFileContext, definition: ast.FunctionDef, at: ast.expr) -> ast.FunctionDef | None:
+    parent = context.parents.get(definition)
+    if parent is context.tree:
+        return definition
+    if isinstance(parent, ast.FunctionDef | ast.AsyncFunctionDef) and definition.lineno < at.lineno:
+        return definition
+    return None
+
+
+def _binding(context: PythonFileContext, name: str, at: ast.AST) -> ast.AST | None:
+    if (binding := context.resource_provenance.runtime_binding(name, at)) is not None:
+        return binding
+    scope = context.binding_inventory.scope(at)
+    lambda_body = False
+    while isinstance(scope, (*_COMPREHENSIONS, ast.Lambda)):
+        lambda_body |= isinstance(scope, ast.Lambda)
+        first_iterable = isinstance(scope, _COMPREHENSIONS) and context.resource_provenance.contains(
+            scope.generators[0].iter, at
+        )
+        if not first_iterable and name in context.binding_inventory.bindings.get(scope, {}):
+            return None
+        scope = context.binding_inventory.scope(scope)
+    bindings = context.runtime_bindings.lookup(scope, name)
+    if bindings is None and lambda_body:
+        return _lambda_module_binding(context, scope, name)
+    return bindings[0] if bindings is not None and len(bindings) == 1 else None
+
+
+def _lambda_module_binding(context: PythonFileContext, scope: ast.AST | None, name: str) -> ast.AST | None:
+    if name in context.binding_inventory.external_bindings:
+        return None
+    while scope is not context.tree:
+        if scope is None:
+            return None
+        if isinstance(scope, ast.FunctionDef | ast.AsyncFunctionDef) and name in context.binding_inventory.bindings.get(
+            scope, {}
+        ):
+            return None
+        scope = context.binding_inventory.scope(scope)
+    bindings = context.runtime_bindings.lookup(scope, name)
+    return bindings[0] if bindings is not None and len(bindings) == 1 else None

sarj_python_lint-1.90.1/src/sarj_python_lint/rules/prefer_grouped_settings.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import ast
+from collections import defaultdict
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    ProjectRule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._declared_contracts import SETTINGS_BASES, DeclaredContracts
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._declared_contracts import DeclaredClass
+    from sarj_python_lint.rules._project_index import ProjectIndexSet
+
+
+_MIN_GROUP_FIELDS = 2
+_MODIFIER_PREFIXES = frozenset(
+    {"is", "has", "min", "max", "num", "total", "default", "enable", "disable", "expected", "use"}
+)
+
+
+@final
+class PreferGroupedSettings(ProjectRule):
+    id = "prefer-grouped-settings"
+    code = "SARJ532"
+    documentation = RuleDocumentation(
+        default_level=Severity.ERROR,
+        summary="Group settings fields that share a Python namespace prefix into a nested settings object.",
+        rationale=(
+            "Repeated namespace prefixes flatten one component's configuration across the parent settings API. "
+            "A focused settings object gives that component an explicit boundary."
+        ),
+        remediation=(
+            "Move the related fields into a focused nested settings object, normally constructed with "
+            "Field(default_factory=...). Preserve existing environment aliases, prefixes, validation, defaults "
+            "and source precedence, and verify real environment loading before changing the settings API."
+        ),
+        category=RuleCategory.ARCHITECTURE,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only source-proven Pydantic BaseSettings classes and directly owned public fields are checked. Two distinct fields must share the first complete snake-case namespace token; character prefixes, environment aliases, inherited fields and unrelated data classes do not establish a group.",
+            "Boolean, expectation and quantitative modifiers such as is, has, use, expected, min, max, num, total and default do not establish component namespaces. A prefix already present as a field is left for explicit API review.",
+            "ClassVar, Final, private attributes, model_config, computed fields, tests, generated code, unknown decorators and unresolved bases are excluded. Each namespace produces one error, anchored at its first field; an exact class or first-field suppression is honored.",
+            "Source-proven nested BaseSettings fields do not count as flat candidates. A source-proven nested child already groups a namespace when its parent field has the same first complete Python namespace token, or when its public directly owned fields share that prefix apart from bare fields that are not other source-proven nested settings objects. A competing namespace or nested settings component under a different parent namespace retains subgroup findings. Class names alone, unknown annotations and unknown parent types do not establish ownership.",
+            "There is no automatic rewrite: nesting may change environment-variable decoding, aliases, source precedence and consumer access paths.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="flat-component-settings",
+                title="Related settings expose a repeated component namespace",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/settings.py",
+                        "from pydantic_settings import BaseSettings\n"
+                        "class Settings(BaseSettings):\n"
+                        "    embedder_url: str\n"
+                        "    embedder_token: str\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/settings.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="nested-component-settings",
+                title="The component owns its settings and environment prefix",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/settings.py",
+                        "from pydantic import Field\n"
+                        "from pydantic_settings import BaseSettings, SettingsConfigDict\n"
+                        "class EmbedderSettings(BaseSettings):\n"
+                        "    model_config = SettingsConfigDict(env_prefix='EMBEDDER_')\n"
+                        "    url: str\n"
+                        "    token: str\n"
+                        "class Settings(BaseSettings):\n"
+                        "    embedder: EmbedderSettings = Field(default_factory=EmbedderSettings)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/settings.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    def __init__(self) -> None:
+        self._ownership_project: ProjectIndexSet | None = None
+        self._ownership: dict[tuple[Path, str], frozenset[str]] = {}
+
+    @override
+    def prepare(self, indexes: ProjectIndexSet) -> None:
+        super().prepare(indexes)
+        self._ownership_project = None
+        self._ownership.clear()
+
+    def _namespaces(self, contracts: DeclaredContracts, model: DeclaredClass) -> frozenset[str]:
+        if self._ownership_project is not contracts.project:
+            self._ownership = _nested_ownership_index(contracts)
+            self._ownership_project = contracts.project
+        return self._ownership.get((model.unit.path, model.declaration.name), frozenset())
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.tree is None or context.generated or is_test_path(context.path):
+            return []
+        contracts = DeclaredContracts(context)
+        findings: list[Diagnostic] = []
+        for model in _settings_models(contracts):
+            if not is_suppressed(context.source_lines, model.declaration.lineno, self.code):
+                findings.extend(self._model_diagnostics(context, contracts, model))
+        return findings
+
+    def _model_diagnostics(
+        self, context: PythonFileContext, contracts: DeclaredContracts, model: DeclaredClass
+    ) -> list[Diagnostic]:
+        fields = contracts.model_fields(model)
+        nested_fields = frozenset(
+            name
+            for name, field in fields.items()
+            if (child := contracts.annotation(field.annotation, model.unit)) is not None
+            and contracts.inherits(child, SETTINGS_BASES)
+        )
+        groups = _settings_groups(fields, nested_fields=nested_fields)
+        if not groups:
+            return []
+        namespaces = self._namespaces(contracts, model)
+        findings: list[Diagnostic] = []
+        for prefix, members in groups.items():
+            if _already_grouped(prefix, fields, namespaces, nested_fields=nested_fields):
+                continue
+            first = next(iter(members.values()))
+            if is_suppressed(context.source_lines, first.lineno, self.code):
+                continue
+            names = ", ".join(f"`{name}`" for name in members)
+            findings.append(
+                Diagnostic(
+                    context.path,
+                    first.lineno,
+                    first.col_offset + 1,
+                    self.code,
+                    f"Settings fields {names} share the `{prefix}_` namespace; group them under a focused `{prefix}` settings object while preserving environment loading.",
+                    Severity.ERROR,
+                )
+            )
+        return findings
+
+
+def _settings_models(contracts: DeclaredContracts) -> Iterator[DeclaredClass]:
+    unit = contracts.unit
+    if unit is None or unit.tree is None:
+        return
+    for declaration in unit.tree.body:
+        if not isinstance(declaration, ast.ClassDef):
+            continue
+        model = contracts.class_type(ast.Name(id=declaration.name))
+        if model is not None and contracts.inherits(model, SETTINGS_BASES):
+            yield model
+
+
+def _already_grouped(
+    prefix: str, fields: dict[str, ast.AnnAssign], namespaces: frozenset[str], *, nested_fields: frozenset[str]
+) -> bool:
+    if any(name.partition("_")[0] == prefix for name in namespaces):
+        return True
+    return bool(namespaces) and all(
+        name.startswith(f"{prefix}_") or ("_" not in name and name not in nested_fields) for name in fields
+    )
+
+
+def _settings_groups(
+    fields: dict[str, ast.AnnAssign], *, nested_fields: frozenset[str] = frozenset()
+) -> dict[str, dict[str, ast.AnnAssign]]:
+    groups: dict[str, dict[str, ast.AnnAssign]] = defaultdict(dict)
+    for name, field in fields.items():
+        if name in nested_fields:
+            continue
+        prefix, separator, tail = name.partition("_")
+        if separator and tail and prefix not in _MODIFIER_PREFIXES and prefix not in fields:
+            groups[prefix][name] = field
+    return {prefix: members for prefix, members in groups.items() if len(members) >= _MIN_GROUP_FIELDS}
+
+
+def _nested_ownership_index(contracts: DeclaredContracts) -> dict[tuple[Path, str], frozenset[str]]:
+    from sarj_python_lint._file_context import PythonFileContext  # ruff: ignore[import-outside-top-level] -- defer the context import until the rule registry and analysis session finish initializing.
+
+    ownership: dict[tuple[Path, str], set[str]] = defaultdict(set)
+    for source in contracts.project.source_snapshot().units:
+        unit = contracts.project.unit(source.key)
+        if unit is None or unit.tree is None or is_test_path(unit.path) or is_generated(unit.path, unit.source):
+            continue
+        context = PythonFileContext(unit.path, unit.source)
+        context.session.project = contracts.project
+        local = DeclaredContracts(context)
+        for parent in _settings_models(local):
+            for name, field in local.model_fields(parent).items():
+                child = local.annotation(field.annotation)
+                if child is not None:
+                    ownership[child.unit.path, child.declaration.name].add(name)
+    return {identity: frozenset(namespaces) for identity, namespaces in ownership.items()}