sarj-python-lint 0.78.0__tar.gz → 0.78.2__tar.gz

{sarj_python_lint-0.78.0 → sarj_python_lint-0.78.2}/PKG-INFO

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

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

{sarj_python_lint-0.78.0 → sarj_python_lint-0.78.2}/src/sarj_python_lint/rules/_registry.py

@@ -3,50 +3,43 @@ from __future__ import annotations
 from types import MappingProxyType
 from typing import TYPE_CHECKING
 
-from sarj_python_lint.rules.created_at_order_requires_tiebreaker import (
-    CreatedAtOrderRequiresTiebreaker,
-)
-from sarj_python_lint.rules.defect_xfail_requires_strict import DefectXfailRequiresStrict
+from sarj_python_lint.rules.defect_xfail_requires_explicit_strict import DefectXfailRequiresExplicitStrict
 from sarj_python_lint.rules.docstring_args_restate_signature import (
     DocstringArgsRestateSignature,
 )
 from sarj_python_lint.rules.docstring_returns_restate_signature import (
     DocstringReturnsRestateSignature,
 )
-from sarj_python_lint.rules.duplicate_test_body import DuplicateTestBody
-from sarj_python_lint.rules.duplicated_override_docstring import (
-    DuplicatedOverrideDocstring,
-)
-from sarj_python_lint.rules.fastapi_openapi_contract import FastapiOpenapiContract
-from sarj_python_lint.rules.fixture_returns_bare_tuple import FixtureReturnsBareTuple
-from sarj_python_lint.rules.get_delegates_to_get_many import GetDelegatesToGetMany
+from sarj_python_lint.rules.fakes_in_shared_location import FakesInSharedLocation
+from sarj_python_lint.rules.fastapi_explicit_openapi_contract import FastapiExplicitOpenapiContract
 from sarj_python_lint.rules.iac_source_coupled_test import IacSourceCoupledTest
 from sarj_python_lint.rules.invalid_pydantic_field_default import (
     InvalidPydanticFieldDefault,
 )
-from sarj_python_lint.rules.kwarg_heavy_construction_in_test import KwargHeavyConstructionInTest
 from sarj_python_lint.rules.mock_without_spec import MockWithoutSpec
 from sarj_python_lint.rules.negative_only_http_status_assertion import (
     NegativeOnlyHttpStatusAssertion,
 )
-from sarj_python_lint.rules.no_aggregation_in_store_query import (
-    NoAggregationInStoreQuery,
+from sarj_python_lint.rules.no_analytical_aggregation_in_postgres_store import (
+    NoAnalyticalAggregationInPostgresStore,
 )
 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_copied_inherited_docstring import NoCopiedInheritedDocstring
 from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
     NoCorsWildcardWithCredentials,
 )
 from sarj_python_lint.rules.no_duplicate_dunder_all_entry import NoDuplicateDunderAllEntry
 from sarj_python_lint.rules.no_fastapi_on_event import NoFastapiOnEvent
-from sarj_python_lint.rules.no_file_level_escape_hatch_noqa import NoFileLevelEscapeHatchNoqa
+from sarj_python_lint.rules.no_file_level_escape_hatch_suppression import (
+    NoFileLevelEscapeHatchSuppression,
+)
 from sarj_python_lint.rules.no_first_party_private_import import (
     NoFirstPartyPrivateImport,
 )
 from sarj_python_lint.rules.no_frozen_after_validator_field_write import (
     NoFrozenAfterValidatorFieldWrite,
 )
-from sarj_python_lint.rules.no_gen_random_uuid_in_sql import NoGenRandomUuidInSql
 from sarj_python_lint.rules.no_generic_single_export_module import NoGenericSingleExportModule
 from sarj_python_lint.rules.no_hidden_constructor_fallback import (
     NoHiddenConstructorFallback,
@@ -59,8 +52,11 @@ 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_random_uuid_in_sql import NoRandomUuidInSql
+from sarj_python_lint.rules.no_raw_connection_in_tests import NoRawConnectionInTests
 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_repeated_test_body import NoRepeatedTestBody
 from sarj_python_lint.rules.no_restated_comment import NoRestatedComment
 from sarj_python_lint.rules.no_secret_in_log import NoSecretInLog
 from sarj_python_lint.rules.no_select_star import NoSelectStar
@@ -80,6 +76,7 @@ from sarj_python_lint.rules.opaque_parametrize_case_needs_id import OpaqueParame
 from sarj_python_lint.rules.over_mocked_test import OverMockedTest
 from sarj_python_lint.rules.phase_label_comment import TestPhaseLabelComment
 from sarj_python_lint.rules.prefer_class_row import PreferClassRow
+from sarj_python_lint.rules.prefer_collection_comprehension import PreferCollectionComprehension
 from sarj_python_lint.rules.prefer_constant_time_secret_compare import (
     PreferConstantTimeSecretCompare,
 )
@@ -122,9 +119,11 @@ from sarj_python_lint.rules.preserve_declared_nominal_id import PreserveDeclared
 from sarj_python_lint.rules.preserve_enum_types import PreserveEnumTypes
 from sarj_python_lint.rules.production_derived_test_cases import ProductionDerivedTestCases
 from sarj_python_lint.rules.pydantic_at_boundaries import PydanticAtBoundaries
+from sarj_python_lint.rules.pytest_fixture_returns_bare_tuple import PytestFixtureReturnsBareTuple
 from sarj_python_lint.rules.redundant_class_docstring import RedundantClassDocstring
 from sarj_python_lint.rules.redundant_docstring import RedundantDocstring
 from sarj_python_lint.rules.redundant_module_docstring import RedundantModuleDocstring
+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.require_keyword_only_swap_prone_params import (
     RequireKeywordOnlySwapProneParams,
@@ -144,9 +143,11 @@ from sarj_python_lint.rules.restated_test_docstring import RestatedTestDocstring
 from sarj_python_lint.rules.source_coupled_test import SourceCoupledTest
 from sarj_python_lint.rules.sql_requires_injected_pool_owner import SqlRequiresInjectedPoolOwner
 from sarj_python_lint.rules.stepdown import Stepdown
+from sarj_python_lint.rules.store_get_delegates_to_bulk_read import StoreGetDelegatesToBulkRead
 from sarj_python_lint.rules.store_insert_requires_on_conflict import (
     StoreInsertRequiresOnConflict,
 )
+from sarj_python_lint.rules.timestamp_order_requires_tiebreaker import TimestampOrderRequiresTiebreaker
 from sarj_python_lint.rules.trailing_value_narration import TrailingValueNarration
 from sarj_python_lint.rules.trivially_true_assertion import TriviallyTrueAssertion
 from sarj_python_lint.rules.uncontrolled_randomness_in_test import UncontrolledRandomnessInTest
@@ -160,16 +161,18 @@ if TYPE_CHECKING:
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
-        CreatedAtOrderRequiresTiebreaker.id: CreatedAtOrderRequiresTiebreaker,
+        TimestampOrderRequiresTiebreaker.id: TimestampOrderRequiresTiebreaker,
         NoStringConcatInLoop.id: NoStringConcatInLoop,
         PreferClassRow.id: PreferClassRow,
+        PreferCollectionComprehension.id: PreferCollectionComprehension,
         PreferStrEnum.id: PreferStrEnum,
         NoIsinstanceUnionChain.id: NoIsinstanceUnionChain,
         NoOffsetPagination.id: NoOffsetPagination,
         PreferNamedtupleOverTupleReturn.id: PreferNamedtupleOverTupleReturn,
         NoCorsWildcardWithCredentials.id: NoCorsWildcardWithCredentials,
         PydanticAtBoundaries.id: PydanticAtBoundaries,
-        FastapiOpenapiContract.id: FastapiOpenapiContract,
+        FastapiExplicitOpenapiContract.id: FastapiExplicitOpenapiContract,
+        FakesInSharedLocation.id: FakesInSharedLocation,
         NoSentinelReturnOnExcept.id: NoSentinelReturnOnExcept,
         PreferConstantTimeSecretCompare.id: PreferConstantTimeSecretCompare,
         NoSecretInLog.id: NoSecretInLog,
@@ -181,7 +184,8 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         SourceCoupledTest.id: SourceCoupledTest,
         IacSourceCoupledTest.id: IacSourceCoupledTest,
         NoQueryWithManyJoins.id: NoQueryWithManyJoins,
-        NoAggregationInStoreQuery.id: NoAggregationInStoreQuery,
+        NoRawConnectionInTests.id: NoRawConnectionInTests,
+        NoAnalyticalAggregationInPostgresStore.id: NoAnalyticalAggregationInPostgresStore,
         NoSelectStar.id: NoSelectStar,
         NoGenericSingleExportModule.id: NoGenericSingleExportModule,
         Stepdown.id: Stepdown,
@@ -193,19 +197,19 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreferImmutableModuleConstant.id: PreferImmutableModuleConstant,
         MockWithoutSpec.id: MockWithoutSpec,
         OpaqueParametrizeCaseNeedsId.id: OpaqueParametrizeCaseNeedsId,
-        FixtureReturnsBareTuple.id: FixtureReturnsBareTuple,
-        GetDelegatesToGetMany.id: GetDelegatesToGetMany,
+        PytestFixtureReturnsBareTuple.id: PytestFixtureReturnsBareTuple,
+        StoreGetDelegatesToBulkRead.id: StoreGetDelegatesToBulkRead,
         PreferOneForRequiredRow.id: PreferOneForRequiredRow,
-        KwargHeavyConstructionInTest.id: KwargHeavyConstructionInTest,
-        DefectXfailRequiresStrict.id: DefectXfailRequiresStrict,
+        RepeatedKwargHeavyCallInTest.id: RepeatedKwargHeavyCallInTest,
+        DefectXfailRequiresExplicitStrict.id: DefectXfailRequiresExplicitStrict,
         NoFirstPartyPrivateImport.id: NoFirstPartyPrivateImport,
         NoRestatedComment.id: NoRestatedComment,
         RedundantDocstring.id: RedundantDocstring,
         TrailingValueNarration.id: TrailingValueNarration,
         NoStdlibLogging.id: NoStdlibLogging,
-        NoGenRandomUuidInSql.id: NoGenRandomUuidInSql,
+        NoRandomUuidInSql.id: NoRandomUuidInSql,
         NoHiddenConstructorFallback.id: NoHiddenConstructorFallback,
-        NoFileLevelEscapeHatchNoqa.id: NoFileLevelEscapeHatchNoqa,
+        NoFileLevelEscapeHatchSuppression.id: NoFileLevelEscapeHatchSuppression,
         NoFastapiOnEvent.id: NoFastapiOnEvent,
         NoOptionalTenantPredicate.id: NoOptionalTenantPredicate,
         NoTautologicalExpect.id: NoTautologicalExpect,
@@ -214,7 +218,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         InvalidPydanticFieldDefault.id: InvalidPydanticFieldDefault,
         NoFrozenAfterValidatorFieldWrite.id: NoFrozenAfterValidatorFieldWrite,
         TriviallyTrueAssertion.id: TriviallyTrueAssertion,
-        DuplicateTestBody.id: DuplicateTestBody,
+        NoRepeatedTestBody.id: NoRepeatedTestBody,
         UnusedMockSetup.id: UnusedMockSetup,
         PreferFstringOverConcat.id: PreferFstringOverConcat,
         PreferOrPattern.id: PreferOrPattern,
@@ -227,7 +231,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreferSelfTypeAnnotation.id: PreferSelfTypeAnnotation,
         PreferSelfDocumentingConstant.id: PreferSelfDocumentingConstant,
         NoDuplicateDunderAllEntry.id: NoDuplicateDunderAllEntry,
-        DuplicatedOverrideDocstring.id: DuplicatedOverrideDocstring,
+        NoCopiedInheritedDocstring.id: NoCopiedInheritedDocstring,
         RedundantClassDocstring.id: RedundantClassDocstring,
         RedundantModuleDocstring.id: RedundantModuleDocstring,
         DocstringArgsRestateSignature.id: DocstringArgsRestateSignature,

sarj_python_lint-0.78.0/src/sarj_python_lint/rules/defect_xfail_requires_strict.py → sarj_python_lint-0.78.2/src/sarj_python_lint/rules/defect_xfail_requires_explicit_strict.py

@@ -38,7 +38,7 @@ _GITHUB_ISSUE_RE = re.compile(r"https?://github\.com/[^/\s]+/[^/\s]+/issues/\d+\
 _NONDETERMINISM_RE = re.compile(r"intermittent|flak|sometimes|non-?deterministic|varies", re.IGNORECASE)
 
 # Sibling markers that declare a nondeterministic dependency.
-_NONDETERMINISTIC_MARKERS = frozenset({"real_llm", "flaky", "network", "integration"})
+_NONDETERMINISTIC_MARKERS = frozenset({"real_llm", "flaky", "network"})
 
 # Hypothesis' entry point.
 _PROPERTY_DECORATORS = frozenset({"given"})
@@ -53,19 +53,23 @@ _FUNC_NODES = (ast.FunctionDef, ast.AsyncFunctionDef)
 _PYTESTMARK = "pytestmark"
 
 
-class DefectXfailRequiresStrict(Rule):
-    id: str = "defect-xfail-requires-strict"
+class DefectXfailRequiresExplicitStrict(Rule):
+    id: str = "defect-xfail-requires-explicit-strict"
     code: str = "SARJ046"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="Bug-pinning `xfail` without `strict=True` — an XPASS reports as a pass and the pin rots.",
-        rationale="A non-strict defect pin stays green after the defect is fixed, leaving stale coverage and markers behind.",
+        summary="Defect-pinning `xfail` must explicitly set `strict=True` so an XPASS cannot silently pass.",
+        rationale=(
+            "A defect pin that relies on pytest's configurable strictness default can stay green after the defect is "
+            "fixed, leaving stale coverage and markers behind. Local strictness keeps the invariant attached to the pin."
+        ),
         remediation="Set `strict=True` so an unexpected pass fails and prompts removal of the obsolete marker.",
         category=RuleCategory.TESTING,
-        aliases=("xfail-requires-strict",),
+        aliases=("defect-xfail-requires-strict", "xfail-requires-strict"),
         limitations=(
             "Only markers resolved through an unambiguous pytest or pytest.mark import are analyzed.",
             "Only xfail reasons that explicitly identify a defect are analyzed.",
-            "Nondeterministic, property-based, integration, network, and environment-gated tests are excluded.",
+            "Nondeterministic, property-based, network, environment-gated, run=False, and statically disabled pins are excluded.",
+            "Repository-level strict_xfail / xfail_strict configuration is intentionally not consulted: defect pins remain locally explicit.",
         ),
         examples=(
             RuleExample(
@@ -134,6 +138,7 @@ def _rotting_bug_pins(tree: ast.Module, imports: ImportIndex) -> list[ast.Call]:
             hits.extend(_rotting_markers(node.decorator_list, imports))
     for node in nodes(tree, *_FUNC_NODES):
         hits.extend(_rotting_markers(node.decorator_list, imports))
+        hits.extend(_rotting_param_markers(node.decorator_list, imports))
     return hits
 
 
@@ -143,6 +148,18 @@ def _rotting_markers(markers: list[ast.expr], imports: ImportIndex) -> list[ast.
     return [marker for marker in markers if isinstance(marker, ast.Call) and _is_rotting_xfail(marker, imports)]
 
 
+def _rotting_param_markers(decorators: list[ast.expr], imports: ImportIndex) -> list[ast.Call]:
+    if _has_nondeterministic_marker(decorators, imports):
+        return []
+    return [
+        nested
+        for decorator in decorators
+        if _pytest_marker_name(decorator, imports) == _PARAMETRIZE_ATTR
+        for nested in walk(decorator)
+        if isinstance(nested, ast.Call) and nested is not decorator and _is_rotting_xfail(nested, imports)
+    ]
+
+
 def _module_pytest_markers(tree: ast.Module, imports: ImportIndex) -> list[ast.expr]:
     values: list[ast.expr] = []
     for statement in tree.body:
@@ -191,7 +208,7 @@ def _pytest_marker_name(dec: ast.expr, imports: ImportIndex) -> str | None:
 def _is_rotting_xfail(dec: ast.expr, imports: ImportIndex) -> bool:
     if not isinstance(dec, ast.Call) or _pytest_marker_name(dec, imports) != _XFAIL:
         return False
-    if _is_strict(dec) or _is_environment_gated(dec):
+    if _is_strict(dec) or _cannot_xpass(dec) or _is_environment_gated(dec):
         return False
     reason = _reason_text(dec)
     if reason is None or _NONDETERMINISM_RE.search(reason):
@@ -235,6 +252,15 @@ def _is_strict(dec: ast.Call) -> bool:
     return False
 
 
+def _cannot_xpass(dec: ast.Call) -> bool:
+    for kw in dec.keywords:
+        if kw.arg == "run" and isinstance(kw.value, ast.Constant) and kw.value.value is False:
+            return True
+        if kw.arg == "condition" and isinstance(kw.value, ast.Constant) and kw.value.value is False:
+            return True
+    return bool(dec.args and isinstance(dec.args[0], ast.Constant) and dec.args[0].value is False)
+
+
 def _reason_text(dec: ast.Call) -> str | None:
     for kw in dec.keywords:
         if kw.arg == "reason":

sarj_python_lint-0.78.2/src/sarj_python_lint/rules/fakes_in_shared_location.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+import re
+from typing import TYPE_CHECKING, ClassVar, 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._paths import is_generated, is_test_path, is_test_support_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_DOUBLE_NAME_RE = re.compile(r"^(?:Fake|Stub|Mock|InMemory|Recording|Scripted)[A-Z0-9]")
+_SHARED_SUPPORT_NAMES = frozenset({"helpers", "support", "test_support", "test_utils"})
+
+
+@final
+class FakesInSharedLocation(Rule):
+    id = "fakes-in-shared-location"
+    code = "SARJ428"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Define reusable test doubles in a shared testing-support module.",
+        rationale=(
+            "A fake embedded in one test module silently becomes a private second implementation of a contract. "
+            "A named support module makes the double discoverable, reusable, and reviewable as test infrastructure."
+        ),
+        remediation=(
+            "Move the class to a testing, fakes, stubs, mocks, doubles, or test_utils module and import it. "
+            "Use an exact SARJ428 suppression only when the double is intentionally coupled to one scenario."
+        ),
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only top-level classes in test files with an explicit Fake, Stub, Mock, InMemory, Recording, or Scripted prefix are classified as doubles.",
+            "conftest.py and conventional shared-support paths are already shared locations and are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="local-fake-service",
+                title="A test module privately defines a named fake",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_checkout.py",
+                        "class FakePaymentGateway:\n    async def charge(self, amount: int) -> None:\n        pass\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_checkout.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="shared-fake-service",
+                title="A shared support module owns the fake",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/fakes/payment.py",
+                        "class FakePaymentGateway:\n    async def charge(self, amount: int) -> None:\n        pass\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/fakes/payment.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if not is_test_path(path) or _is_shared_support(path) or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        return [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                message=(
+                    f"test double `{node.name}` is private to this test module; move it to shared testing support "
+                    "or add an exact SARJ428 suppression for a deliberately scenario-local double"
+                ),
+            )
+            for node in tree.body
+            if isinstance(node, ast.ClassDef) and _DOUBLE_NAME_RE.match(node.name)
+        ]
+
+
+def _is_shared_support(path: Path) -> bool:
+    names = {part.lower() for part in path.parts}
+    return (
+        path.name == "conftest.py"
+        or path.stem.lower() in _SHARED_SUPPORT_NAMES
+        or bool(names & _SHARED_SUPPORT_NAMES)
+        or is_test_support_path(path)
+    )

sarj_python_lint-0.78.0/src/sarj_python_lint/rules/fastapi_openapi_contract.py → sarj_python_lint-0.78.2/src/sarj_python_lint/rules/fastapi_explicit_openapi_contract.py

@@ -44,6 +44,8 @@ _CONTAINERS = frozenset({"list", "List", "set", "Set", "tuple", "Tuple", "Sequen
 _BODY_MARKERS = frozenset({"Body", "Form", "File"})
 _NO_CONTENT_STATUSES = frozenset({204, 304})
 _STATUS_CODE_DIGITS = 3
+_MIN_HTTP_STATUS = 100
+_MAX_HTTP_STATUS = 599
 _DOCUMENTATION_EXAMPLE_DIR_NAMES = frozenset({"docs_src"})
 _CONVERTER_PATTERNS = MappingProxyType(
     {
@@ -62,14 +64,18 @@ class _Finding:
     message: str
 
 
-class FastapiOpenapiContract(Rule):
-    id: str = "fastapi-openapi-contract"
+class FastapiExplicitOpenapiContract(Rule):
+    id: str = "fastapi-explicit-openapi-contract"
     code: str = "SARJ094"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="FastAPI operations must publish accurate request, response, and status contracts.",
-        rationale="Typed routes and explicit response behavior keep generated OpenAPI accurate without duplicating self-documenting names in prose.",
+        summary="FastAPI operations must make request, response, and status contracts explicit in generated OpenAPI.",
+        rationale=(
+            "Locally explicit route metadata keeps generated OpenAPI reviewable and stable across framework defaults "
+            "without duplicating self-documenting names in prose."
+        ),
         remediation="Declare status codes, typed parameters, response schemas, and alternate responses raised directly by the handler.",
         category=RuleCategory.CORRECTNESS,
+        aliases=("fastapi-openapi-contract",),
         limitations=(
             "Hidden routes, WebSocket handlers, tests, generated files, documentation-source examples, and unrelated decorators are excluded.",
             "Dynamic response mappings are accepted when their contents cannot be resolved statically.",
@@ -134,8 +140,9 @@ class FastapiOpenapiContract(Rule):
             findings.extend(_check_raw_request(function, routes, index))
             findings.extend(_check_direct_responses(function, routes, index))
             for route in _operations(routes):
-                findings.extend(_check_metadata(route))
+                findings.extend(_check_metadata(route, index))
                 findings.extend(_check_projection(route))
+                findings.extend(_check_response_statuses(route, index))
         findings.extend(_check_route_conflicts(declared))
         return [
             Diagnostic(
@@ -155,11 +162,15 @@ def _operations(routes: tuple[Route, ...]) -> tuple[Route, ...]:
     return tuple({id(route.decorator): route for route in routes}.values())
 
 
-def _check_metadata(route: Route) -> list[_Finding]:
-    if route.has_unpack:
-        return []
+def _check_metadata(route: Route, index: FastapiIndex) -> list[_Finding]:
     keywords = route.keywords
-    if "status_code" in keywords and not _literal_none(keywords["status_code"]):
+    status_node = keywords.get("status_code")
+    if status_node is not None and not _literal_none(status_node):
+        status = _status_code(status_node, index)
+        if status is not None and not _valid_http_status(status):
+            return [_Finding(status_node, f"[status] {status} is outside the HTTP status range 100..599.")]
+        return []
+    if route.has_unpack:
         return []
     return [_Finding(route.decorator, "[metadata] operation requires explicit status_code.")]
 
@@ -454,6 +465,7 @@ def _check_direct_responses(
     index: FastapiIndex,
 ) -> list[_Finding]:
     statuses: set[int] = set()
+    invalid: dict[int, ast.Call] = {}
     stack: list[ast.AST] = list(function.body)
     while stack:
         current = stack.pop()
@@ -465,16 +477,25 @@ def _check_direct_responses(
         if isinstance(call, ast.Call) and index.is_http_exception(call.func):
             status = _status_code(_keyword(call, "status_code") or (call.args[0] if call.args else None), index)
             if status is not None:
-                statuses.add(status)
+                if _valid_http_status(status):
+                    statuses.add(status)
+                else:
+                    invalid.setdefault(status, call)
         returned = current.value if isinstance(current, ast.Return) else None
         if isinstance(returned, ast.Call) and index.is_response(returned.func):
             status = _status_code(_keyword(returned, "status_code"), index)
             if status is not None:
-                statuses.add(status)
+                if _valid_http_status(status):
+                    statuses.add(status)
+                else:
+                    invalid.setdefault(status, returned)
         stack.extend(children(current))
+    findings = [
+        _Finding(node, f"[status] {status} is outside the HTTP status range 100..599.")
+        for status, node in invalid.items()
+    ]
     if not statuses:
-        return []
-    findings: list[_Finding] = []
+        return findings
     for route in _operations(routes):
         responses = route.keywords.get("responses")
         if responses is not None and not isinstance(responses, ast.Dict):
@@ -492,6 +513,22 @@ def _check_direct_responses(
     return findings
 
 
+def _check_response_statuses(route: Route, index: FastapiIndex) -> list[_Finding]:
+    responses = route.keywords.get("responses")
+    if not isinstance(responses, ast.Dict):
+        return []
+    findings: list[_Finding] = []
+    for key in responses.keys:
+        status = _status_code(key, index)
+        if key is not None and status is not None and not _valid_http_status(status):
+            findings.append(_Finding(key, f"[status] {status} is outside the HTTP status range 100..599."))
+    return findings
+
+
+def _valid_http_status(status: int) -> bool:
+    return _MIN_HTTP_STATUS <= status <= _MAX_HTTP_STATUS
+
+
 def _status_code(node: ast.expr | None, index: FastapiIndex) -> int | None:
     if isinstance(node, ast.Constant) and isinstance(node.value, int):
         return node.value

{sarj_python_lint-0.78.0 → sarj_python_lint-0.78.2}/src/sarj_python_lint/rules/iac_source_coupled_test.py

@@ -33,7 +33,8 @@ class IacSourceCoupledTest(Rule):
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         summary="Test asserts on raw IaC source text instead of a parsed plan, provider state, or runtime behavior.",
         rationale=(
-            "Substring and regex checks can pass on comments, formatting, or unreachable Terraform configuration while clients fail silently."
+            "Substring and regex checks can pass on comments, formatting, or unreachable Terraform configuration "
+            "without proving the plan or deployed behavior."
         ),
         remediation="Parse rendered plan JSON, query the provider, or exercise the deployed runtime contract.",
         category=RuleCategory.TESTING,
@@ -45,7 +46,7 @@ class IacSourceCoupledTest(Rule):
         examples=(
             RuleExample(
                 example_id="rendered-plan-contract",
-                title="Assert on rendered Terraform plan behavior",
+                title="Assert on structured Terraform plan behavior",
                 outcome=ExampleOutcome.NO_MATCH,
                 files=(
                     ExampleFile.python(