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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.90.1
+Version: 1.92.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-1.90.1 → sarj_python_lint-1.92.0}/pyproject.toml

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

{sarj_python_lint-1.90.1 → sarj_python_lint-1.92.0}/src/sarj_python_lint/__main__.py

@@ -233,6 +233,7 @@ _DIAGNOSTIC_PRECEDENCE = MappingProxyType(
         "SARJ086": frozenset({"SARJ420"}),
         "SARJ087": frozenset({"SARJ420"}),
         "SARJ088": frozenset({"SARJ050", "SARJ085", "SARJ420"}),
+        "SARJ089": frozenset({"SARJ551"}),
         "SARJ092": frozenset({"SARJ086", "SARJ087", "SARJ420"}),
         "SARJ093": frozenset({"SARJ034"}),
         # Visible FastAPI operations have a route-aware contract diagnostic.
@@ -251,7 +252,7 @@ _DIAGNOSTIC_PRECEDENCE = MappingProxyType(
         "SARJ447": frozenset({"SARJ008"}),
         "SARJ450": frozenset({"SARJ521", "SARJ535"}),
         "SARJ521": frozenset({"SARJ535"}),
-        "SARJ457": frozenset({"SARJ045"}),
+        "SARJ457": frozenset({"SARJ045", "SARJ526"}),
         "SARJ465": frozenset({"SARJ071"}),
         "SARJ491": frozenset({"SARJ400"}),
     }

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

@@ -61,6 +61,7 @@ from sarj_python_lint.rules.no_fixed_sleep_in_loop import NoFixedSleepInLoop
 from sarj_python_lint.rules.no_frozen_after_validator_field_write import (
     NoFrozenAfterValidatorFieldWrite,
 )
+from sarj_python_lint.rules.no_generic_json_parser import NoGenericJsonParser
 from sarj_python_lint.rules.no_generic_single_export_module import NoGenericSingleExportModule
 from sarj_python_lint.rules.no_hidden_constructor_fallback import (
     NoHiddenConstructorFallback,
@@ -73,6 +74,7 @@ from sarj_python_lint.rules.no_loguru_exc_info import NoLoguruExcInfo
 from sarj_python_lint.rules.no_loguru_printf_format import NoLoguruPrintfFormat
 from sarj_python_lint.rules.no_mocked_pydantic_value_object import NoMockedPydanticValueObject
 from sarj_python_lint.rules.no_mutating_container_transform import NoMutatingContainerTransform
+from sarj_python_lint.rules.no_mutating_input_with_result import NoMutatingInputWithResult
 from sarj_python_lint.rules.no_nested_pydantic_field_validator import NoNestedPydanticFieldValidator
 from sarj_python_lint.rules.no_nullable_dependency_fallback import NoNullableDependencyFallback
 from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
@@ -83,6 +85,7 @@ from sarj_python_lint.rules.no_psycopg_execution_outside_injected_owner import (
 from sarj_python_lint.rules.no_random_uuid_in_sql import NoRandomUuidInSql
 from sarj_python_lint.rules.no_raw_connection_in_tests import NoRawConnectionInTests
 from sarj_python_lint.rules.no_raw_source_text_test_oracle import NoRawSourceTextTestOracle
+from sarj_python_lint.rules.no_redundant_attribute_unpacking import NoRedundantAttributeUnpacking
 from sarj_python_lint.rules.no_redundant_literal_description import NoRedundantLiteralDescription
 from sarj_python_lint.rules.no_redundant_module_alias_exports import NoRedundantModuleAliasExports
 from sarj_python_lint.rules.no_repeated_string_literal import NoRepeatedStringLiteral
@@ -95,6 +98,7 @@ from sarj_python_lint.rules.no_shallow_container_type_guard import NoShallowCont
 from sarj_python_lint.rules.no_string_concat_in_loop import NoStringConcatInLoop
 from sarj_python_lint.rules.no_swallowed_asyncio_cancellation import NoSwallowedAsyncioCancellation
 from sarj_python_lint.rules.no_tautological_expect import NoTautologicalExpect
+from sarj_python_lint.rules.no_test_comments import NoTestComments
 from sarj_python_lint.rules.no_test_method_grafting import NoTestMethodGrafting
 from sarj_python_lint.rules.no_typed_doc_sections import NoTypedDocSections
 from sarj_python_lint.rules.no_unique_violation_message_match import (
@@ -149,6 +153,7 @@ from sarj_python_lint.rules.prefer_non_nullable_collection import (
 )
 from sarj_python_lint.rules.prefer_or_pattern import PreferOrPattern
 from sarj_python_lint.rules.prefer_pydantic_json_value import PreferPydanticJsonValue
+from sarj_python_lint.rules.prefer_pytest_fixture_contract import PreferPytestFixtureContract
 from sarj_python_lint.rules.prefer_pytest_fixture_injection import PreferPytestFixtureInjection
 from sarj_python_lint.rules.prefer_regex_fullmatch import PreferRegexFullmatch
 from sarj_python_lint.rules.prefer_required_constructor_parameters import PreferRequiredConstructorParameters
@@ -175,6 +180,7 @@ from sarj_python_lint.rules.redundant_module_docstring import RedundantModuleDoc
 from sarj_python_lint.rules.repeated_kwarg_heavy_call_in_test import RepeatedKwargHeavyCallInTest
 from sarj_python_lint.rules.repeated_static_call_cases import RepeatedStaticCallCases
 from sarj_python_lint.rules.repeated_test_composition import RepeatedTestComposition
+from sarj_python_lint.rules.require_constrained_api_integer import RequireConstrainedApiInteger
 from sarj_python_lint.rules.require_explicit_contract_implementation import RequireExplicitContractImplementation
 from sarj_python_lint.rules.require_explicit_psycopg_transaction import RequireExplicitPsycopgTransaction
 from sarj_python_lint.rules.require_explicit_service_contract import RequireExplicitServiceContract
@@ -437,6 +443,12 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreferNativeStringCheck.id: PreferNativeStringCheck,
         PreferSelfDocumentingConstant.id: PreferSelfDocumentingConstant,
         NoDuplicateDunderAllEntry.id: NoDuplicateDunderAllEntry,
+        PreferPytestFixtureContract.id: PreferPytestFixtureContract,
+        NoTestComments.id: NoTestComments,
+        NoGenericJsonParser.id: NoGenericJsonParser,
+        RequireConstrainedApiInteger.id: RequireConstrainedApiInteger,
+        NoRedundantAttributeUnpacking.id: NoRedundantAttributeUnpacking,
+        NoMutatingInputWithResult.id: NoMutatingInputWithResult,
         NoDunderAll.id: NoDunderAll,
         NoDeleteStatement.id: NoDeleteStatement,
         NoBroadKeywordCapture.id: NoBroadKeywordCapture,

sarj_python_lint-1.92.0/src/sarj_python_lint/rules/no_generic_json_parser.py

@@ -0,0 +1,148 @@
+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,
+)
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+_PYDANTIC = frozenset({"pydantic", "pydantic.root_model", "pydantic.type_adapter", "pydantic.types"})
+_TYPING = frozenset({"typing", "typing_extensions"})
+
+
+@final
+class NoGenericJsonParser(Rule):
+    id = "no-generic-json-parser"
+    code = "SARJ552"
+    documentation = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Parse consumed JSON fields with a bespoke declarative model instead of an open JSON parser.",
+        rationale="An open JSON domain validates syntax and value kinds without declaring required fields or their relationships; consumers must then reconstruct the contract manually.",
+        remediation="Declare only the fields the consumer needs in a named Pydantic model and use model_validate_json or model_validate. Allow unrelated fields when the wire contract permits them. Document an exact-code exception for genuinely schema-agnostic infrastructure.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Reports import-proven TypeAdapter construction and RootModel bases containing JsonValue, Json, Any or object, including module-local explicit type aliases. Tests remain in scope; generated files are excluded.",
+            "Typed dictionaries of domain values, model fields storing arbitrary JSON, opaque imported aliases and custom parser classes are excluded. Recursive arbitrary unions without a canonical open type are not inferred.",
+            "Generic schema infrastructure may need a reasoned local suppression. No model or complete request schema is synthesized automatically.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="generic-response-parser",
+                title="An open JSON mapping does not declare the response fields",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_api.py",
+                        "from pydantic import JsonValue, RootModel\nclass Response(RootModel[dict[str, JsonValue]]):\n    pass\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_api.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="partial-declarative-response",
+                title="Declare just the field this consumer needs",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_api.py",
+                        "from pydantic import BaseModel\nclass Response(BaseModel):\n    version: int\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_api.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.generated or context.tree is None:
+            return []
+        imports = context.imports
+        aliases = {
+            statement.name.id: statement.value
+            for statement in context.tree.body
+            if isinstance(statement, ast.TypeAlias)
+        }
+        candidates = _open_parser_nodes(context, imports, aliases)
+        return [
+            Diagnostic(
+                context.path,
+                node.lineno,
+                node.col_offset + 1,
+                self.code,
+                "Replace this open JSON parser with a named model declaring the consumed fields.",
+                severity=Severity.WARNING,
+            )
+            for node in candidates
+            if not is_suppressed(context.source_lines, node.lineno, self.code)
+        ]
+
+
+def _open_parser_nodes(
+    context: PythonFileContext, imports: ImportIndex, aliases: dict[str, ast.expr]
+) -> list[ast.expr]:
+    candidates: list[ast.expr] = []
+    for call in context.nodes(ast.Call):
+        if not imports.resolves(call.func, sources=_PYDANTIC, symbol="TypeAdapter"):
+            continue
+        schema = call.args[0] if call.args else next((kw.value for kw in call.keywords if kw.arg == "type"), None)
+        if schema is not None and _open_schema(schema, imports, aliases):
+            candidates.append(call)
+    for owner in context.nodes(ast.ClassDef):
+        candidates.extend(_open_root_bases(owner, imports, aliases))
+    return sorted(candidates, key=lambda node: (node.lineno, node.col_offset))
+
+
+def _open_root_bases(owner: ast.ClassDef, imports: ImportIndex, aliases: dict[str, ast.expr]) -> list[ast.Subscript]:
+    return [
+        base
+        for base in owner.bases
+        if isinstance(base, ast.Subscript)
+        and imports.resolves(base.value, sources=_PYDANTIC, symbol="RootModel")
+        and _open_schema(base.slice, imports, aliases)
+    ]
+
+
+def _open_schema(
+    node: ast.expr, imports: ImportIndex, aliases: dict[str, ast.expr], seen: frozenset[str] = frozenset()
+) -> bool:
+    for item in ast.walk(node):
+        if not isinstance(item, ast.expr):
+            continue
+        if any(imports.resolves(item, sources=_PYDANTIC, symbol=name) for name in ("JsonValue", "Json")):
+            return True
+        if imports.resolves(item, sources=_TYPING, symbol="Any"):
+            return True
+        if isinstance(item, ast.Name):
+            if item.id == "object" and imports.builtin_is_unshadowed("object"):
+                return True
+            if (
+                item.id in aliases
+                and item.id not in seen
+                and _open_schema(aliases[item.id], imports, aliases, seen | {item.id})
+            ):
+                return True
+    return False

sarj_python_lint-1.92.0/src/sarj_python_lint/rules/no_mutating_input_with_result.py

@@ -0,0 +1,139 @@
+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,
+    ProjectRule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._test_composition import direct_nodes
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_MAX_ALIAS_DEPTH = 8
+_BAD = "from attrs import define\n@define\nclass Request:\n    expected_version: int\ndef send_update(body: Request) -> Response:\n    body.expected_version = 2\n    return send(body)\n"
+_GOOD = "from attrs import define, evolve\n@define\nclass Request:\n    expected_version: int\ndef send_update(body: Request) -> Response:\n    updated = evolve(body, expected_version=2)\n    return send(updated)\n"
+
+
+@final
+class NoMutatingInputWithResult(ProjectRule):
+    id = "no-mutating-input-with-result"
+    code = "SARJ555"
+    documentation = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Separate input attribute mutation from functions that return a result.",
+        rationale="Returning an operation result can hide writes to a request object retained by the caller. Reusing that input then observes state changed by an earlier call.",
+        remediation="Build and return a replacement input before sending it, or expose a deliberate in-place command returning None. Preserve response values and input contracts; do not discard the result to silence the rule.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Checks direct attribute assignments, augmented assignments and deletions through a parameter or an unambiguously assigned local alias in functions with an explicit non-None annotation and at least one value return. No class-name or model-library inference is needed.",
+            "Pydantic writes and before-validator writes keep their existing SARJ481/SARJ482 owners. Builtin-container item mutation remains with SARJ520; this rule does not duplicate subscript diagnostics.",
+            "None-returning commands, receiver state named self/cls, fresh copies, nested attributes, opaque mutator calls, generators, missing return annotations and unresolved or more than eight alias links are excluded.",
+            "Intentional mutation-and-result APIs may retain a reasoned exact suppression. Warnings require review; no copying, return-type change or lifecycle rewrite is automatic.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="attrs-request-mutated-before-response",
+                title="Sending a generated request changes the caller's request",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("api.py", _BAD),),
+                focus_path=PurePosixPath("api.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="attrs-request-replaced-before-response",
+                title="Send a replacement and keep the input unchanged",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("api.py", _GOOD),),
+                focus_path=PurePosixPath("api.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:
+            return []
+        owned = {mutation.node for mutation in context.copy_on_write.mutations}
+        findings: list[Diagnostic] = []
+        for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
+            if not _returns_result(function, context):
+                continue
+            for target in _attribute_writes(function):
+                if target in owned or is_suppressed(context.source_lines, target.lineno, self.code):
+                    continue
+                name = _input_owner(target.value, function, context)
+                if name is not None:
+                    findings.append(
+                        Diagnostic(
+                            context.path,
+                            target.lineno,
+                            target.col_offset + 1,
+                            self.code,
+                            f"This result-returning function also mutates input `{name}`; return a replacement or make the in-place command's None contract explicit.",
+                            severity=Severity.WARNING,
+                        )
+                    )
+        return findings
+
+
+def _returns_result(function: ast.FunctionDef | ast.AsyncFunctionDef, context: PythonFileContext) -> bool:
+    annotation = context.annotation_semantics.resolve_alias(function.returns)
+    if annotation is None or (isinstance(annotation, ast.Constant) and annotation.value is None):
+        return False
+    nodes = tuple(direct_nodes(function))
+    if any(isinstance(node, ast.Yield | ast.YieldFrom) for node in nodes):
+        return False
+    return any(
+        isinstance(node, ast.Return)
+        and node.value is not None
+        and not (isinstance(node.value, ast.Constant) and node.value.value is None)
+        for node in nodes
+    )
+
+
+def _attribute_writes(function: ast.FunctionDef | ast.AsyncFunctionDef) -> tuple[ast.Attribute, ...]:
+    return tuple(
+        node
+        for node in direct_nodes(function)
+        if isinstance(node, ast.Attribute)
+        and isinstance(node.ctx, ast.Store | ast.Del)
+        and isinstance(node.value, ast.Name)
+    )
+
+
+def _input_owner(
+    expression: ast.expr,
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    context: PythonFileContext,
+    depth: int = 0,
+) -> str | None:
+    if not isinstance(expression, ast.Name) or depth >= _MAX_ALIAS_DEPTH:
+        return None
+    binding = context.static_resource_provenance.binding(expression.id, expression)
+    if isinstance(binding, ast.arg):
+        arguments = (*function.args.posonlyargs, *function.args.args, *function.args.kwonlyargs)
+        return binding.arg if binding in arguments and binding.arg not in {"self", "cls"} else None
+    if isinstance(binding, ast.Name):
+        value = context.static_resource_provenance.assignment_value(binding, expression)
+        if value is not None:
+            return _input_owner(value, function, context, depth + 1)
+    return None

sarj_python_lint-1.92.0/src/sarj_python_lint/rules/no_redundant_attribute_unpacking.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+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,
+)
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_MIN_ATTRIBUTES = 2
+
+
+@dataclass(frozen=True)
+class _AttributeAlias:
+    target: str
+    receiver: str
+
+
+@final
+class NoRedundantAttributeUnpacking(Rule):
+    id = "no-redundant-attribute-unpacking"
+    code = "SARJ554"
+    documentation = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Use an aggregate's named attributes instead of repeating their names in tuple aliases.",
+        rationale="A tuple assignment that repeats every attribute name adds parallel bindings without describing a transformation or a new concept.",
+        remediation="Read the aggregate's named attributes directly. Retain intentional value snapshots with an explained local suppression.",
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Reports unconditional tuple/list assignments directly in function bodies only when every element aliases an identically named attribute of the same simple receiver and no target rebinds that receiver.",
+            "Conditional/loop/context-manager aliases can normalize branch results or preserve resource scopes and are excluded. Renamed attributes, mixed receivers, nested unpacking, calls, module/class bindings, generated source and malformed source are excluded.",
+            "This is an explicitly requested warning-level style preference. A retained snapshot can be meaningful when the aggregate changes; no autofix or claim of behavioral equivalence is made.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="repeated-attribute-names",
+                title="Keep the named result aggregate",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_save.py",
+                        "def test_save(seeded):\n    scenario, current = seeded.scenario, seeded.current\n    assert scenario.id == current.id\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_save.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="direct-attribute-use",
+                title="Read names on their owner",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_save.py",
+                        "def test_save(seeded):\n    assert seeded.scenario.id == seeded.current.id\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_save.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:
+            return []
+        findings: list[Diagnostic] = []
+        for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
+            for node in function.body:
+                if (
+                    not isinstance(node, ast.Assign)
+                    or not _redundant_unpacking(node)
+                    or is_suppressed(context.source_lines, node.lineno, self.code)
+                ):
+                    continue
+                findings.append(
+                    Diagnostic(
+                        context.path,
+                        node.lineno,
+                        node.col_offset + 1,
+                        self.code,
+                        "Use these named attributes on their aggregate directly; retain intentional snapshots with an explained exception.",
+                        severity=Severity.WARNING,
+                    )
+                )
+        return list({(finding.line, finding.col): finding for finding in findings}.values())
+
+
+def _redundant_unpacking(node: ast.Assign) -> bool:
+    if len(node.targets) != 1:
+        return False
+    target = node.targets[0]
+    if not isinstance(target, ast.Tuple | ast.List) or not isinstance(node.value, ast.Tuple | ast.List):
+        return False
+    if len(target.elts) < _MIN_ATTRIBUTES or len(target.elts) != len(node.value.elts):
+        return False
+    receivers: set[str] = set()
+    targets: set[str] = set()
+    for left, right in zip(target.elts, node.value.elts, strict=True):
+        pair = _attribute_alias(left, right)
+        if pair is None:
+            return False
+        targets.add(pair.target)
+        receivers.add(pair.receiver)
+    return len(receivers) == 1 and receivers.isdisjoint(targets)
+
+
+def _attribute_alias(left: ast.expr, right: ast.expr) -> _AttributeAlias | None:
+    if not isinstance(left, ast.Name) or not isinstance(right, ast.Attribute) or not isinstance(right.value, ast.Name):
+        return None
+    return _AttributeAlias(left.id, right.value.id) if left.id == right.attr else None

sarj_python_lint-1.92.0/src/sarj_python_lint/rules/no_test_comments.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+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,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._comments import PositionedComment, comment_runs, has_legal_notice
+from sarj_python_lint.rules._paths import is_test_path, is_test_support_path
+from sarj_python_lint.rules._pytest import collected_tests
+from sarj_python_lint.rules._suppression_comments import scan_comments_or_none
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._suppression_comments import Comment
+
+
+_DIRECTIVE = re.compile(
+    r"^(?:!|.*?coding[:=]|(?:sarj-noqa|noqa|ruff|pyright|basedpyright|type|fmt|isort|pragma|"
+    r"mypy|pylint|nosec|doctest|pytest|uv|region|endregion)\s*[:\[]|(?:fmt|isort):|%%)",
+    re.IGNORECASE,
+)
+
+
+@final
+class NoTestComments(Rule):
+    id = "no-test-comments"
+    code = "SARJ551"
+    documentation = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Express test behavior in names and assertions instead of ordinary comments.",
+        rationale="Test prose can drift from the setup and assertion it describes; executable contracts keep the explanation checked.",
+        remediation="Remove the comment, clarify the test or helper name, or express the invariant with an assertion. Preserve legal notices and required tool directives.",
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Checks real comment tokens in recognized test and test-support paths, including inline comments; string contents and docstrings are outside this policy.",
+            "Ambiguous test-like filenames require collected test declarations; test and test-support directories and conftest own their source independently of declarations.",
+            "Generated files, malformed source, legal notices, shebangs, encoding declarations and tool directives are excluded. Existing comment rules retain their own diagnostic ownership.",
+            "This is an explicitly requested style policy, released as a warning. No automatic deletion of potentially useful rationale is offered.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="comment-narrates-test",
+                title="Name the tested behavior",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_save.py",
+                        "def test_save():\n    # A stale save is rejected.\n    assert save_is_rejected()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_save.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="behavior-in-test-name",
+                title="The assertion documents the behavior",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_save.py", "def test_stale_save_is_rejected():\n    assert save_is_rejected()\n"
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_save.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.generated or context.tree is None or not _test_comment_source(context):
+            return []
+        comments = scan_comments_or_none(context.source) or ()
+        legal_lines = _legal_comment_lines(comments)
+        return [
+            Diagnostic(
+                path=context.path,
+                line=comment.line,
+                col=comment.col,
+                code=self.code,
+                message="Move this test comment's meaning into a test name, helper or assertion.",
+                severity=Severity.WARNING,
+            )
+            for comment in comments
+            if comment.body.strip()
+            and comment.line not in legal_lines
+            and not _DIRECTIVE.search(comment.body)
+            and not has_legal_notice(comment.body)
+            and not is_suppressed(context.source_lines, comment.line, self.code)
+        ]
+
+
+def _test_comment_source(context: PythonFileContext) -> bool:
+    directory = context.path.with_name("__init__.py")
+    if context.path.name == "conftest.py" or is_test_path(directory) or is_test_support_path(directory):
+        return True
+    return context.tree is not None and is_test_path(context.path) and any(collected_tests(context.tree.body))
+
+
+def _legal_comment_lines(comments: Sequence[Comment]) -> set[int]:
+    standalone = [
+        PositionedComment(comment.line, comment.col, comment.body) for comment in comments if comment.standalone
+    ]
+    protected: set[int] = set()
+    for run in comment_runs(standalone):
+        if any(has_legal_notice(body) for _, _, body in run):
+            protected.update(line for line, _, _ in run)
+    return protected