sarj-python-lint 1.75.0__tar.gz → 1.76.0__tar.gz

{sarj_python_lint-1.75.0 → sarj_python_lint-1.76.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.75.0
+Version: 1.76.0
 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/
@@ -19,7 +19,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.14
 Requires-Dist: packaging==26.3
 Requires-Dist: ruff>=0.17.2
-Requires-Dist: sarj-rule-contracts==0.4.0
+Requires-Dist: sarj-rule-contracts==0.4.1
 Requires-Dist: sqlglot==30.24.0
 Requires-Dist: typer==0.27.3
 Description-Content-Type: text/markdown

{sarj_python_lint-1.75.0 → sarj_python_lint-1.76.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.75.0"
+version = "1.76.0"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
@@ -15,7 +15,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Quality Assurance",
 ]
-dependencies = ["sarj-rule-contracts==0.4.0", "packaging==26.3", "ruff>=0.17.2", "sqlglot==30.24.0", "typer==0.27.3"]
+dependencies = ["sarj-rule-contracts==0.4.1", "packaging==26.3", "ruff>=0.17.2", "sqlglot==30.24.0", "typer==0.27.3"]
 
 [project.scripts]
 sarj-python-lint = "sarj_python_lint.__main__:main"

{sarj_python_lint-1.75.0 → sarj_python_lint-1.76.0}/src/sarj_python_lint/__main__.py

@@ -9,8 +9,9 @@ import json
 from pathlib import Path
 import sys
 from types import MappingProxyType
-from typing import Annotated, NamedTuple
+from typing import TYPE_CHECKING, Annotated, NamedTuple
 
+from sarj_rule_contracts import RuleId
 import typer
 
 from sarj_python_lint import __version__
@@ -26,6 +27,10 @@ from sarj_python_lint.rules._project_index import ProjectIndexSet
 from sarj_python_lint.suppression_policy import PROTECTED_SUPPRESSION_CODES
 
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
 SKIP_DIR_NAMES = frozenset(
     {
         "node_modules",
@@ -86,18 +91,18 @@ def _python_files(p: Path) -> list[Path]:
     return sorted(out)
 
 
-def _canonical_rule_ids(rule_ids: list[str]) -> list[str]:
+def _canonical_rule_ids(rule_names: Sequence[str]) -> list[RuleId]:
     aliases = {
         alias: rule_id
         for rule_id, cls in REGISTRY.items()
         if (documentation := cls.documentation) is not None
         for alias in documentation.aliases
     }
-    return list(dict.fromkeys(rid if rid in REGISTRY else aliases.get(rid, rid) for rid in rule_ids))
+    return list(dict.fromkeys(RuleId(name if name in REGISTRY else aliases.get(name, name)) for name in rule_names))
 
 
-def _check(rule_ids: list[str], paths: list[Path], *, jobs: int = 1) -> list[Diagnostic]:
-    rule_ids = _canonical_rule_ids(rule_ids)
+def _check(rule_names: Sequence[str], paths: list[Path], *, jobs: int = 1) -> list[Diagnostic]:
+    rule_ids = _canonical_rule_ids(rule_names)
     unknown = [rid for rid in rule_ids if rid not in REGISTRY]
     if unknown:
         sys.stderr.write(f"unknown rule(s): {', '.join(unknown)}\n")
@@ -145,7 +150,7 @@ def check_source(
 
 
 def analyze(
-    rule_ids: list[str],
+    rule_ids: Sequence[str],  # sarj-noqa: SARJ093 -- Public parsing boundary accepts raw names.
     paths: list[Path],
     *,
     baseline: Path | None = None,

{sarj_python_lint-1.75.0 → sarj_python_lint-1.76.0}/src/sarj_python_lint/benchmark.py

@@ -8,14 +8,19 @@ from pathlib import Path
 from statistics import median
 import sys
 from time import perf_counter
-from typing import Annotated
+from typing import TYPE_CHECKING, Annotated
 
+from sarj_rule_contracts import RuleId
 import typer
 
 from sarj_python_lint.__main__ import analyze, expand_paths
 from sarj_python_lint.rules import REGISTRY
 
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
 @dataclass(frozen=True, slots=True)
 class BenchmarkSample:
     seconds: float
@@ -43,11 +48,16 @@ def peak_memory_bytes() -> int | None:
     return peak if sys.platform == "darwin" else peak * 1024
 
 
-def measure(paths: list[Path], rule_ids: list[str] | None = None, *, repeats: int = 5) -> BenchmarkReport:
+def measure(
+    paths: list[Path],
+    rule_ids: Sequence[str] | None = None,  # sarj-noqa: SARJ093 -- Public input accepts raw rule names.
+    *,
+    repeats: int = 5,
+) -> BenchmarkReport:
     if repeats < 1:
         msg = "repeats must be positive"
         raise ValueError(msg)
-    selected = sorted(REGISTRY) if rule_ids is None else sorted(rule_ids)
+    selected = [RuleId(name) for name in sorted(REGISTRY if rule_ids is None else rule_ids)]
     unknown = sorted(set(selected) - REGISTRY.keys())
     if unknown:
         msg = f"unknown rule(s): {', '.join(unknown)}"

{sarj_python_lint-1.75.0 → sarj_python_lint-1.76.0}/src/sarj_python_lint/rules/_registry.py

@@ -240,6 +240,7 @@ from sarj_python_lint.rules.no_work_verb_get_route import NoWorkVerbGetRoute
 from sarj_python_lint.rules.prefer_bulk_upsert import PreferBulkUpsert
 from sarj_python_lint.rules.prefer_direct_import_module import PreferDirectImportModule
 from sarj_python_lint.rules.prefer_discriminated_model_union import PreferDiscriminatedModelUnion
+from sarj_python_lint.rules.prefer_grouped_settings import PreferGroupedSettings
 from sarj_python_lint.rules.prefer_precise_object_contract import PreferPreciseObjectContract
 from sarj_python_lint.rules.prefer_psycopg_executemany import PreferPsycopgExecutemany
 from sarj_python_lint.rules.prefer_pydantic_model_assertion import PreferPydanticModelAssertion
@@ -255,6 +256,7 @@ from sarj_python_lint.rules.test_without_explicit_oracle import NoExplicitTestOr
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        PreferGroupedSettings.id: PreferGroupedSettings,
         NoRedundantLocalAlias.id: NoRedundantLocalAlias,
         PytestFixtureReturnsClosedResource.id: PytestFixtureReturnsClosedResource,
         DuplicatePytestFixtureParams.id: DuplicatePytestFixtureParams,

{sarj_python_lint-1.75.0 → sarj_python_lint-1.76.0}/src/sarj_python_lint/rules/prefer_fstring_over_concat.py

@@ -15,6 +15,7 @@ from sarj_python_lint.rule_base import (
     RuleDocumentation,
     RuleExample,
     Severity,
+    is_suppressed,
 )
 from sarj_python_lint.rules._ast_index import walk, walk as walk_ast
 from sarj_python_lint.rules._logging import LOG_METHODS, is_logger_expr
@@ -32,8 +33,22 @@ if TYPE_CHECKING:
 _SQL_RE = re.compile(
     r"^\s*(?:(?i:(?:select\b.+\bfrom|insert\s+into|update\s+\S+\s+set|delete\s+from|merge\s+into)\b|"
     r"with\s+\w+\s+as\s*\(|(?:create|alter|drop)\s+(?:table|index|view|schema|type|database)\b|"
-    r"explain\s+(?:select|insert|update|delete|with)\b)|(?:FROM|JOIN|ORDER\s+BY|GROUP\s+BY|VALUES)\b)",
+    r"explain\s+(?:select|insert|update|delete|with)\b)|(?:SELECT|FROM|JOIN|ORDER\s+BY|GROUP\s+BY|VALUES)\b|CAST\s*\()",
 )
+_SOURCE_FRAGMENT_RE = re.compile(
+    r"(?:^|\n)[ \t]*(?:(?:async[ \t]+)?def[ \t]+\w+|class[ \t]+\w+[ \t]*[(:]|"
+    r"from[ \t]+[\w.]+[ \t]+import\b|import[ \t]+[\w.]+(?:[ \t]+as[ \t]+\w+)?[ \t]*(?:\n|$)|"
+    r"(?:return|yield|raise|assert)[ \t]+\w+[ \t]*\(|"
+    r"\#[^\r\n]*(?:\r\n?|\n)|"
+    r"(?:\#[ \t]*@generated|--[ \t]*(?:@generated|generated))\b)"
+)
+_CONFIG_FRAGMENT_RE = re.compile(
+    r"(?m)^[ \t]*(?:[^\W\d][\w.-]*[ \t]*=|"
+    r"\[{1,2}[A-Za-z_][\w.\"'-]*\]{1,2}[ \t]*(?:\n|$)|"
+    r"[A-Za-z_][\w.-]*:[ \t]*[\[{])"
+)
+_MAPPING_FIELD_RE = re.compile(r"(?m)^[ \t]*[A-Za-z_][\w.-]*:[ \t]*(?:\S|$)")
+_MIN_CONFIG_FIELDS = 2
 
 # Calls returning a lazy translation proxy or an escape-aware SafeString.
 _LAZY_CALLS = frozenset(
@@ -118,11 +133,16 @@ class _RegexBindings(NamedTuple):
     scoped_names: frozenset[str]
 
 
+class _InterpolationParts(NamedTuple):
+    literals: list[str]
+    dynamic: list[ast.expr]
+
+
 class PreferFstringOverConcat(Rule):
     id: str = "prefer-fstring-over-concat"
     code: str = "SARJ068"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        default_level=Severity.WARNING,
+        default_level=Severity.ERROR,
         summary="Prefer f-strings for short human-readable interpolation when they make the result clearer.",
         rationale="For prose-like strings, f-strings keep interpolated values and surrounding text visible together.",
         remediation=(
@@ -136,12 +156,13 @@ class PreferFstringOverConcat(Rule):
         limitations=(
             "Safe fixes require every runtime operand to be an explicit unshadowed builtin str, repr or ascii conversion of a proven exact native primitive. Bare strings, subclasses, custom operators and formatting contracts remain review-only.",
             "Runtime operands must have concrete string evidence.",
+            "Unique literal-string bindings and aliases supply surrounding text, including module prefixes. Rebinding, global/nonlocal writers, conditional assignments, imported values, and unresolved scopes are not inferred.",
             "String evidence alone does not prove custom concatenation and formatting equivalence; only exact-native-primitive builtin-conversion subsets are fixed.",
             (
-                "Logging, common direct SQL and regular-expression forms, lazy strings, ORM expressions, generated files, long "
+                "Logging, source and configuration fragments, generated headers, common direct SQL and regular-expression forms, lazy strings, ORM expressions, generated files, long "
                 "literals, and punctuation-oriented fragment composition are excluded."
             ),
-            "The warning is stylistic and intentionally leaves URL, path, protocol, and declarative fragments alone.",
+            "The policy is stylistic and intentionally leaves URL, path, protocol and declarative fragments alone. Stable aliases of join-built strings retain the fragment-composition exclusion; unresolved or rebound values are not inferred.",
         ),
         examples=(
             RuleExample(
@@ -170,6 +191,36 @@ class PreferFstringOverConcat(Rule):
                 expected_count=0,
                 public=True,
             ),
+            RuleExample(
+                example_id="named-literal-prefix",
+                scenario="literal-prefix",
+                title="A literal prefix still participates in interpolation",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "src/render.py",
+                        'PREFIX = "Question: "\ndef render(value: str) -> str:\n    return PREFIX + value\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("src/render.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="formatted-literal-prefix",
+                scenario="literal-prefix",
+                title="The prefix and value share one f-string",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "src/render.py",
+                        'PREFIX = "Question: "\ndef render(value: str) -> str:\n    return f"{PREFIX}{value}"\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("src/render.py"),
+                expected_count=0,
+                public=True,
+            ),
             RuleExample(
                 example_id="safe-autofix-subset",
                 title="A proven subset has a convergent automatic fix",
@@ -218,12 +269,14 @@ class PreferFstringOverConcat(Rule):
         for node in adds:
             if id(node) in inner or id(node) in excluded:
                 continue
+            if is_suppressed(context.source_lines, node.lineno, self.code):
+                continue
             if not _in_callable_scope(node, parents):
                 continue
             if module_evidence is None:
                 shadowed = _shadowed_producers(tree.body, None)
                 module_evidence = _StringEvidence(frozenset(), shadowed, _imported_modules(tree.body, None) - shadowed)
-            message = _verdict(node, _string_evidence(node, parents, module_evidence, scope_shadowing))
+            message = _verdict(node, _string_evidence(node, parents, module_evidence, scope_shadowing), context)
             if message is None:
                 continue
             diags.append(
@@ -232,7 +285,7 @@ class PreferFstringOverConcat(Rule):
                     line=node.lineno,
                     col=node.col_offset + 1,
                     code=self.code,
-                    severity=Severity.WARNING,
+                    severity=Severity.ERROR,
                     message=message,
                 )
             )
@@ -353,20 +406,13 @@ def _in_callable_scope(node: ast.AST, parents: Mapping[ast.AST, ast.AST]) -> boo
     return False
 
 
-def _verdict(node: ast.BinOp, evidence: _StringEvidence) -> str | None:
-    literals: list[str] = []
-    dynamic: list[ast.expr] = []
+def _verdict(node: ast.BinOp, evidence: _StringEvidence, context: PythonFileContext) -> str | None:
     operands = _flatten(node)
-    for operand in operands:
-        if isinstance(operand, ast.Constant):
-            if not isinstance(operand.value, str):
-                # A bytes/int/float literal is positive evidence this `+` is not
-                # string concatenation at all.
-                return None
-            literals.append(operand.value)
-        else:
-            dynamic.append(operand)
-    if _unsupported_interpolation_operands(literals, dynamic, evidence):
+    parts = _interpolation_parts(operands, evidence, context)
+    if parts is None:
+        return None
+    literals, dynamic = parts
+    if _unsupported_interpolation_operands(literals, dynamic, evidence) or _has_bound_join(dynamic, context):
         return None
     if len(operands) == _TERMINATOR_OPERANDS and all(not text.strip() for text in literals):
         return None
@@ -389,12 +435,70 @@ def _verdict(node: ast.BinOp, evidence: _StringEvidence) -> str | None:
     return message
 
 
+def _interpolation_parts(
+    operands: list[ast.expr], evidence: _StringEvidence, context: PythonFileContext
+) -> _InterpolationParts | None:
+    literals: list[str] = []
+    dynamic: list[ast.expr] = []
+    inline_literal = any(isinstance(operand, ast.Constant) and isinstance(operand.value, str) for operand in operands)
+    for operand in operands:
+        literal = (
+            None
+            if inline_literal and not isinstance(operand, ast.Constant) and _is_string_expr(operand, evidence)
+            else _literal_string(operand, context)
+        )
+        if literal is not None:
+            literals.append(literal)
+        elif isinstance(operand, ast.Constant):
+            # A bytes/int/float literal is positive evidence this `+` is not
+            # string concatenation at all.
+            return None
+        else:
+            dynamic.append(operand)
+    return _InterpolationParts(literals, dynamic)
+
+
+def _literal_string(expression: ast.expr, context: PythonFileContext) -> str | None:
+    value = _bound_value(expression, context)
+    return value.value if isinstance(value, ast.Constant) and isinstance(value.value, str) else None
+
+
+def _bound_value(expression: ast.expr, context: PythonFileContext) -> ast.expr | None:
+    seen: set[ast.AST] = set()
+    while isinstance(expression, ast.Name):
+        provenance = context.static_resource_provenance
+        if provenance.dynamic_namespace:
+            return None
+        binding = provenance.runtime_binding(expression.id, expression)
+        if not isinstance(binding, ast.Name) or binding in seen:
+            return None
+        seen.add(binding)
+        value = provenance.assignment_value(binding, expression)
+        if value is None:
+            return None
+        expression = value
+    return expression
+
+
+def _has_bound_join(dynamic: list[ast.expr], context: PythonFileContext) -> bool:
+    if not any(_is_join_call(call) for call in context.nodes(ast.Call)):
+        return False
+    return any(_is_join_call(_bound_value(expression, context)) for expression in dynamic)
+
+
 def _is_structural_fragment(literals: list[str]) -> bool:
+    if any(
+        _SOURCE_FRAGMENT_RE.search(text)
+        or _CONFIG_FRAGMENT_RE.search(text)
+        or len(_MAPPING_FIELD_RE.findall(text)) >= _MIN_CONFIG_FIELDS
+        for text in literals
+    ):
+        return True
     substantive = "".join(literals)
     return bool(substantive) and (
         "\\" in substantive
         or any(marker in substantive for marker in ("(?:", "(?=", "(?!", ".*", ".+", "^", "$"))
-        or not any(character.isalpha() or character.isspace() for character in substantive)
+        or not any(character.isalpha() for character in substantive)
     )
 
 
@@ -463,7 +567,7 @@ def _unsupported_interpolation_operands(
     return bool(any(isinstance(expr, ast.IfExp | ast.BoolOp) for expr in dynamic))
 
 
-def _is_join_call(expr: ast.expr) -> bool:
+def _is_join_call(expr: ast.expr | None) -> bool:
     return isinstance(expr, ast.Call) and isinstance(expr.func, ast.Attribute) and expr.func.attr == "join"
 
 
@@ -573,9 +677,11 @@ def _string_evidence(
 
 
 def _annotation_is_string(annotation: ast.expr, shadowed: frozenset[str]) -> bool:
-    if isinstance(annotation, ast.Name):
-        return annotation.id == "str" and "str" not in shadowed
-    return False
+    match annotation:
+        case ast.Name(id="str") | ast.Constant(value="str"):
+            return "str" not in shadowed
+        case _:
+            return False
 
 
 def _is_string_expr(expr: ast.expr, evidence: _StringEvidence) -> bool:
@@ -681,18 +787,6 @@ def _collect_string_parameters(
     for arg in (*args.posonlyargs, *args.args, *args.kwonlyargs):
         if arg.annotation is not None and _annotation_is_string(arg.annotation, shadowed):
             known.add(arg.arg)
-    if (
-        args.vararg is not None
-        and args.vararg.annotation is not None
-        and _annotation_is_string(args.vararg.annotation, shadowed)
-    ):
-        known.add(args.vararg.arg)
-    if (
-        args.kwarg is not None
-        and args.kwarg.annotation is not None
-        and _annotation_is_string(args.kwarg.annotation, shadowed)
-    ):
-        known.add(args.kwarg.arg)
 
 
 def _update_string_bindings(

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

@@ -0,0 +1,137 @@
+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_test_path
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_MIN_GROUP_FIELDS = 2
+_MODIFIER_PREFIXES = frozenset({"is", "has", "min", "max", "num", "total", "default", "enable", "disable"})
+
+
+@final
+class PreferGroupedSettings(ProjectRule):
+    id = "prefer-grouped-settings"
+    code = "SARJ532"
+    documentation = RuleDocumentation(
+        default_level=Severity.WARNING,
+        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 and quantitative modifiers such as is, has, 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 warning, anchored at its first field; an exact class or first-field suppression is honored.",
+            "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
+
+    @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 declaration in context.tree.body:
+            if not isinstance(declaration, ast.ClassDef):
+                continue
+            model = contracts.class_type(ast.Name(id=declaration.name))
+            if model is None or not contracts.inherits(model, SETTINGS_BASES):
+                continue
+            if is_suppressed(context.source_lines, declaration.lineno, self.code):
+                continue
+            for prefix, members in _settings_groups(contracts.model_fields(model)).items():
+                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.WARNING,
+                    )
+                )
+        return findings
+
+
+def _settings_groups(fields: dict[str, ast.AnnAssign]) -> dict[str, dict[str, ast.AnnAssign]]:
+    groups: dict[str, dict[str, ast.AnnAssign]] = defaultdict(dict)
+    for name, field in fields.items():
+        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}