sarj-python-lint 0.75.0__tar.gz → 0.76.0__tar.gz

{sarj_python_lint-0.75.0 → sarj_python_lint-0.76.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 0.75.0
+Version: 0.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/

{sarj_python_lint-0.75.0 → sarj_python_lint-0.76.0}/pyproject.toml

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

{sarj_python_lint-0.75.0 → sarj_python_lint-0.76.0}/src/sarj_python_lint/rules/_registry.py

@@ -33,6 +33,7 @@ from sarj_python_lint.rules.no_aggregation_in_store_query import (
     NoAggregationInStoreQuery,
 )
 from sarj_python_lint.rules.no_comment_cruft import NoCommentCruft
+from sarj_python_lint.rules.no_conftest_test_module_import import NoConftestTestModuleImport
 from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
     NoCorsWildcardWithCredentials,
 )
@@ -51,11 +52,13 @@ from sarj_python_lint.rules.no_hidden_constructor_fallback import (
 )
 from sarj_python_lint.rules.no_isinstance_union_chain import NoIsinstanceUnionChain
 from sarj_python_lint.rules.no_long_comment import NoLongComment
+from sarj_python_lint.rules.no_nested_pydantic_field_validator import NoNestedPydanticFieldValidator
 from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
 from sarj_python_lint.rules.no_optional_tenant_predicate import (
     NoOptionalTenantPredicate,
 )
 from sarj_python_lint.rules.no_query_with_many_joins import NoQueryWithManyJoins
+from sarj_python_lint.rules.no_redundant_literal_description import NoRedundantLiteralDescription
 from sarj_python_lint.rules.no_repeated_string_literal import NoRepeatedStringLiteral
 from sarj_python_lint.rules.no_restated_comment import NoRestatedComment
 from sarj_python_lint.rules.no_secret_in_log import NoSecretInLog
@@ -125,6 +128,9 @@ from sarj_python_lint.rules.repeated_static_call_cases import RepeatedStaticCall
 from sarj_python_lint.rules.require_keyword_only_swap_prone_params import (
     RequireKeywordOnlySwapProneParams,
 )
+from sarj_python_lint.rules.require_nodecode_for_splitting_settings_field import (
+    RequireNoDecodeForSplittingSettingsField,
+)
 from sarj_python_lint.rules.require_port_for_service import RequirePortForService
 from sarj_python_lint.rules.require_pydantic_for_external_json import (
     RequirePydanticForExternalJson,
@@ -169,6 +175,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreferTimedeltaForDurations.id: PreferTimedeltaForDurations,
         PreferStructOverNamedtuple.id: PreferStructOverNamedtuple,
         NoCommentCruft.id: NoCommentCruft,
+        NoConftestTestModuleImport.id: NoConftestTestModuleImport,
         StoreInsertRequiresOnConflict.id: StoreInsertRequiresOnConflict,
         SourceCoupledTest.id: SourceCoupledTest,
         IacSourceCoupledTest.id: IacSourceCoupledTest,
@@ -226,6 +233,8 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         RestatedTestDocstring.id: RestatedTestDocstring,
         TestPhaseLabelComment.id: TestPhaseLabelComment,
         NoLongComment.id: NoLongComment,
+        NoNestedPydanticFieldValidator.id: NoNestedPydanticFieldValidator,
+        NoRedundantLiteralDescription.id: NoRedundantLiteralDescription,
         NoTypedDocSections.id: NoTypedDocSections,
         NoUnnecessaryDocstring.id: NoUnnecessaryDocstring,
         PreferNominalIdTypes.id: PreferNominalIdTypes,
@@ -239,6 +248,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreserveDeclaredNominalId.id: PreserveDeclaredNominalId,
         PreserveEnumTypes.id: PreserveEnumTypes,
         RequirePydanticOrdinalLowerBound.id: RequirePydanticOrdinalLowerBound,
+        RequireNoDecodeForSplittingSettingsField.id: RequireNoDecodeForSplittingSettingsField,
         NoVagueSuppressionDescription.id: NoVagueSuppressionDescription,
     }
 )

sarj_python_lint-0.76.0/src/sarj_python_lint/rules/no_conftest_test_module_import.py

@@ -0,0 +1,105 @@
+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,
+    parse_or_none,
+)
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@final
+class NoConftestTestModuleImport(Rule):
+    id = "no-conftest-test-module-import"
+    code = "SARJ426"
+    documentation = RuleDocumentation(
+        summary="Do not import individual test modules from conftest.py.",
+        rationale=(
+            "pytest imports conftest for every test module in its scope; importing a specific test from conftest "
+            "turns that test into global collection infrastructure and creates cycles and order dependence."
+        ),
+        remediation="Move shared fixtures or helpers into conftest.py or a dedicated support module.",
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only files named conftest.py are inspected.",
+            "A test module is recognized only when an explicit module-path component begins with `test_` or ends with `_test`.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="conftest-imports-test-module",
+                title="Conftest imports a specific test module",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("tests/conftest.py", "from tests.test_api import make_client\n"),),
+                focus_path=PurePosixPath("tests/conftest.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="conftest-imports-support-module",
+                title="Conftest imports dedicated support code",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("tests/conftest.py", "from tests.helpers import make_client\n"),),
+                focus_path=PurePosixPath("tests/conftest.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if path.name != "conftest.py":
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        diagnostics: list[Diagnostic] = []
+        for statement in tree.body:
+            targets: list[str] = []
+            match statement:
+                case ast.Import(names=names):
+                    targets.extend(alias.name for alias in names if _module_has_test_leaf(alias.name))
+                case ast.ImportFrom(module=module, names=names):
+                    if module is not None and _module_has_test_leaf(module):
+                        targets.append(module)
+                case _:
+                    continue
+            if not targets:
+                continue
+            diagnostics.append(
+                Diagnostic(
+                    path=path,
+                    line=statement.lineno,
+                    col=statement.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        f"conftest.py imports test module `{targets[0]}`; move shared fixtures or helpers to "
+                        "conftest or a dedicated support module."
+                    ),
+                )
+            )
+        return diagnostics
+
+
+def _module_has_test_leaf(module: str) -> bool:
+    parts = module.split(".")
+    return any(_is_test_module_name(part) for part in parts)
+
+
+def _is_test_module_name(name: str) -> bool:
+    return name.startswith("test_") or name.endswith("_test")

sarj_python_lint-0.76.0/src/sarj_python_lint/rules/no_nested_pydantic_field_validator.py

@@ -0,0 +1,171 @@
+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,
+    parse_or_none,
+)
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_PYDANTIC_BASE_MODEL_SOURCES = frozenset({"pydantic", "pydantic.main"})
+_PYDANTIC_SOURCES = frozenset({"pydantic", "pydantic.functional_validators"})
+
+
+@final
+class NoNestedPydanticFieldValidator(Rule):
+    id = "no-nested-pydantic-field-validator"
+    code = "SARJ425"
+    documentation = RuleDocumentation(
+        summary="Do not place an outer Pydantic model's field validator inside a nested helper class.",
+        rationale=(
+            "A decorator indented into a nested class registers on that class, not on the outer Pydantic model, "
+            "so the declared field silently loses validation."
+        ),
+        remediation="Move the field-validator method into the outer model class.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only direct BaseModel subclasses and validators directly owned by one nested class are inspected.",
+            "Nested classes with bases are excluded because inherited Pydantic fields cannot be resolved locally.",
+            "Test and generated files are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="validator-nested-in-config",
+                title="Validator accidentally belongs to Config",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/models.py",
+                        "from pydantic import BaseModel, field_validator\n\n"
+                        "class Settings(BaseModel):\n"
+                        "    language: str\n"
+                        "    class Config:\n"
+                        "        extra = 'forbid'\n"
+                        "        @field_validator('language')\n"
+                        "        @classmethod\n"
+                        "        def normalize(cls, value):\n"
+                        "            return value.lower()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/models.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="validator-owned-by-model",
+                title="Validator belongs to the model",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/models.py",
+                        "from pydantic import BaseModel, field_validator\n\n"
+                        "class Settings(BaseModel):\n"
+                        "    language: str\n"
+                        "    @field_validator('language')\n"
+                        "    @classmethod\n"
+                        "    def normalize(cls, value):\n"
+                        "        return value.lower()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/models.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_test_path(path) or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        imports = ImportIndex.from_tree(tree)
+        diagnostics: list[Diagnostic] = []
+        for outer in (node for node in ast.walk(tree) if isinstance(node, ast.ClassDef)):
+            if not _is_direct_model(outer, imports):
+                continue
+            outer_fields = _direct_fields(outer)
+            for nested in (statement for statement in outer.body if isinstance(statement, ast.ClassDef)):
+                # A based nested class may be an indirect Pydantic model whose inherited
+                # fields are unavailable to this file-local analysis. Only base-less
+                # Config/helper classes provide a deterministic ownership mistake.
+                if nested.bases:
+                    continue
+                nested_fields = _direct_fields(nested)
+                for function in (
+                    statement
+                    for statement in nested.body
+                    if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef))
+                ):
+                    for decorator, fields in _field_validators(function, imports):
+                        misplaced = sorted((fields & outer_fields) - nested_fields)
+                        if not misplaced:
+                            continue
+                        diagnostics.append(
+                            Diagnostic(
+                                path=path,
+                                line=decorator.lineno,
+                                col=decorator.col_offset + 1,
+                                code=self.code,
+                                message=(
+                                    f"Validator for outer field(s) {', '.join(f'`{name}`' for name in misplaced)} "
+                                    f"is nested inside `{nested.name}`; move it to `{outer.name}`."
+                                ),
+                            )
+                        )
+        return diagnostics
+
+
+def _is_direct_model(node: ast.ClassDef, imports: ImportIndex) -> bool:
+    return len(node.bases) == 1 and imports.resolves(
+        node.bases[0], sources=_PYDANTIC_BASE_MODEL_SOURCES, symbol="BaseModel"
+    )
+
+
+def _direct_fields(node: ast.ClassDef) -> frozenset[str]:
+    return frozenset(
+        statement.target.id
+        for statement in node.body
+        if isinstance(statement, ast.AnnAssign)
+        and isinstance(statement.target, ast.Name)
+        and not statement.target.id.startswith("_")
+        and statement.target.id != "model_config"
+    )
+
+
+def _field_validators(
+    node: ast.FunctionDef | ast.AsyncFunctionDef, imports: ImportIndex
+) -> tuple[tuple[ast.Call, frozenset[str]], ...]:
+    validators: list[tuple[ast.Call, frozenset[str]]] = []
+    for decorator in node.decorator_list:
+        if not isinstance(decorator, ast.Call) or not imports.resolves(
+            decorator.func, sources=_PYDANTIC_SOURCES, symbol="field_validator"
+        ):
+            continue
+        fields = frozenset(
+            argument.value
+            for argument in decorator.args
+            if isinstance(argument, ast.Constant) and isinstance(argument.value, str)
+        )
+        validators.append((decorator, fields))
+    return tuple(validators)

sarj_python_lint-0.76.0/src/sarj_python_lint/rules/no_redundant_literal_description.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+import re
+from typing import TYPE_CHECKING, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    parse_or_none,
+)
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_PYDANTIC_BASE_MODEL_SOURCES = frozenset({"pydantic", "pydantic.main"})
+_PYDANTIC_FIELD_SOURCES = frozenset({"pydantic", "pydantic.fields"})
+_TYPING_SOURCES = frozenset({"typing", "typing_extensions"})
+_ENUM_SOURCES = frozenset({"enum"})
+_DOMAIN_ONLY = re.compile(r"^\s*(?:must|should)\s+be(?:\s+one\s+of)?\s+(?P<body>.+?)\s*[.!]?\s*$", re.IGNORECASE)
+_QUOTED_VALUE = re.compile(r"(['\"])(?P<value>.+?)\1")
+
+
+@final
+class NoRedundantLiteralDescription(Rule):
+    id = "no-redundant-literal-description"
+    code = "SARJ423"
+    documentation = RuleDocumentation(
+        summary="Do not restate a Literal or Enum field's closed domain in its Pydantic description.",
+        rationale=(
+            "Pydantic already publishes literal and enum domains in JSON Schema; duplicate must-be prose can "
+            "contradict the generated contract after a value changes."
+        ),
+        remediation="Remove the domain-only description or replace it with rationale not encoded by the field type.",
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only direct fields on direct BaseModel subclasses are inspected.",
+            "Enum fields are inspected only when their direct string-valued enum class is declared in the same module.",
+            "Descriptions are reported only when they begin with a narrow 'must be' or 'should be' restatement.",
+            "Test and generated files are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="literal-domain-restated",
+                title="Literal domain repeated in prose",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/models.py",
+                        "from typing import Literal\nfrom pydantic import BaseModel, Field\n\n"
+                        "class Request(BaseModel):\n"
+                        "    kind: Literal['call'] = Field(description=\"Must be 'call'\")\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/models.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="literal-rationale-described",
+                title="Description adds rationale",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/models.py",
+                        "from typing import Literal\nfrom pydantic import BaseModel, Field\n\n"
+                        "class Request(BaseModel):\n"
+                        "    kind: Literal['call'] = Field(description='Routes through the realtime provider.')\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/models.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_test_path(path) or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        imports = ImportIndex.from_tree(tree)
+        enum_domains = _local_enum_domains(tree, imports)
+        diagnostics: list[Diagnostic] = []
+        for model in (node for node in ast.walk(tree) if isinstance(node, ast.ClassDef)):
+            if not _is_direct_model(model, imports):
+                continue
+            for statement in model.body:
+                if not isinstance(statement, ast.AnnAssign) or not isinstance(statement.target, ast.Name):
+                    continue
+                domain = _closed_domain(statement.annotation, imports, enum_domains)
+                if domain is None:
+                    continue
+                for field_call in _field_calls(statement, imports):
+                    description = next(
+                        (keyword.value for keyword in field_call.keywords if keyword.arg == "description"), None
+                    )
+                    if not (
+                        isinstance(description, ast.Constant)
+                        and isinstance(description.value, str)
+                        and _repeats_domain(description.value, domain)
+                    ):
+                        continue
+                    diagnostics.append(
+                        Diagnostic(
+                            path=path,
+                            line=description.lineno,
+                            col=description.col_offset + 1,
+                            code=self.code,
+                            message=(
+                                f"`{statement.target.id}` repeats its closed type domain in `description`; "
+                                "remove the restatement or document rationale not present in the schema."
+                            ),
+                        )
+                    )
+        return diagnostics
+
+
+def _is_direct_model(node: ast.ClassDef, imports: ImportIndex) -> bool:
+    return len(node.bases) == 1 and imports.resolves(
+        node.bases[0], sources=_PYDANTIC_BASE_MODEL_SOURCES, symbol="BaseModel"
+    )
+
+
+def _local_enum_domains(tree: ast.Module, imports: ImportIndex) -> dict[str, frozenset[str]]:
+    domains: dict[str, frozenset[str]] = {}
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef) or not any(
+            imports.resolves(base, sources=_ENUM_SOURCES, symbol=symbol)
+            for base in node.bases
+            for symbol in ("Enum", "IntEnum", "StrEnum")
+        ):
+            continue
+        values: set[str] = set()
+        complete = True
+        for statement in node.body:
+            value = statement.value if isinstance(statement, (ast.Assign, ast.AnnAssign)) else None
+            if value is None:
+                continue
+            if not isinstance(value, ast.Constant) or not isinstance(value.value, str):
+                complete = False
+                break
+            values.add(value.value)
+        if complete and values:
+            domains[node.name] = frozenset(values)
+    return domains
+
+
+def _closed_domain(
+    node: ast.expr, imports: ImportIndex, enum_domains: dict[str, frozenset[str]]
+) -> frozenset[str] | None:
+    if isinstance(node, ast.Name):
+        return enum_domains.get(node.id)
+    if not isinstance(node, ast.Subscript):
+        return None
+    if imports.resolves(node.value, sources=_TYPING_SOURCES, symbol="Literal"):
+        members = node.slice.elts if isinstance(node.slice, ast.Tuple) else (node.slice,)
+        values: set[str] = set()
+        for member in members:
+            if not isinstance(member, ast.Constant) or not isinstance(member.value, str):
+                return None
+            values.add(member.value)
+        return frozenset(values)
+    if imports.resolves(node.value, sources=_TYPING_SOURCES, symbol="Annotated"):
+        members = node.slice.elts if isinstance(node.slice, ast.Tuple) else (node.slice,)
+        return _closed_domain(members[0], imports, enum_domains) if members else None
+    return None
+
+
+def _repeats_domain(description: str, domain: frozenset[str]) -> bool:
+    match = _DOMAIN_ONLY.fullmatch(description)
+    if match is None:
+        return False
+    body = match.group("body")
+    values = frozenset(item.group("value") for item in _QUOTED_VALUE.finditer(body))
+    if values != domain:
+        return False
+    residue = _QUOTED_VALUE.sub("", body)
+    residue = re.sub(r"\b(?:and|or)\b|[\s,\[\](){}]", "", residue, flags=re.IGNORECASE)
+    return not residue
+
+
+def _field_calls(statement: ast.AnnAssign, imports: ImportIndex) -> tuple[ast.Call, ...]:
+    candidates: list[ast.expr] = []
+    if statement.value is not None:
+        candidates.append(statement.value)
+    annotation = statement.annotation
+    if isinstance(annotation, ast.Subscript) and imports.resolves(
+        annotation.value, sources=_TYPING_SOURCES, symbol="Annotated"
+    ):
+        members = annotation.slice.elts if isinstance(annotation.slice, ast.Tuple) else (annotation.slice,)
+        candidates.extend(members[1:])
+    return tuple(
+        candidate
+        for candidate in candidates
+        if isinstance(candidate, ast.Call)
+        and imports.resolves(candidate.func, sources=_PYDANTIC_FIELD_SOURCES, symbol="Field")
+    )