sarj-python-lint 0.67.13__tar.gz → 0.68.0__tar.gz

{sarj_python_lint-0.67.13 → sarj_python_lint-0.68.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.67.13
+Version: 0.68.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.67.13 → sarj_python_lint-0.68.0}/pyproject.toml

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

{sarj_python_lint-0.67.13 → sarj_python_lint-0.68.0}/src/sarj_python_lint/rules/_registry.py

@@ -24,6 +24,9 @@ from sarj_python_lint.rules.invalid_pydantic_field_default import (
 )
 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,
 )
@@ -105,6 +108,7 @@ from sarj_python_lint.rules.prefer_walrus_comprehension_filter import (
 )
 from sarj_python_lint.rules.prefer_walrus_regex_match import PreferWalrusRegexMatch
 from sarj_python_lint.rules.prefer_walrus_stream_loop import PreferWalrusStreamLoop
+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.redundant_class_docstring import RedundantClassDocstring
 from sarj_python_lint.rules.redundant_docstring import RedundantDocstring
@@ -113,6 +117,9 @@ from sarj_python_lint.rules.require_keyword_only_swap_prone_params import (
     RequireKeywordOnlySwapProneParams,
 )
 from sarj_python_lint.rules.require_port_for_service import RequirePortForService
+from sarj_python_lint.rules.require_pydantic_for_external_json import (
+    RequirePydanticForExternalJson,
+)
 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.stepdown import Stepdown
@@ -121,6 +128,7 @@ from sarj_python_lint.rules.store_insert_requires_on_conflict import (
 )
 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
 from sarj_python_lint.rules.unused_mock_setup import UnusedMockSetup
 
 
@@ -157,6 +165,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoRepeatedStringLiteral.id: NoRepeatedStringLiteral,
         PreferMatchAssertNever.id: PreferMatchAssertNever,
         RequireKeywordOnlySwapProneParams.id: RequireKeywordOnlySwapProneParams,
+        RequirePydanticForExternalJson.id: RequirePydanticForExternalJson,
         NoFileLevelSuppression.id: NoFileLevelSuppression,
         PreferModuleLevelConstant.id: PreferModuleLevelConstant,
         PreferImmutableModuleConstant.id: PreferImmutableModuleConstant,
@@ -204,6 +213,9 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoTypedDocSections.id: NoTypedDocSections,
         PreferNominalIdTypes.id: PreferNominalIdTypes,
         NoUniqueViolationMessageMatch.id: NoUniqueViolationMessageMatch,
+        NegativeOnlyHttpStatusAssertion.id: NegativeOnlyHttpStatusAssertion,
+        ProductionDerivedTestCases.id: ProductionDerivedTestCases,
+        UncontrolledRandomnessInTest.id: UncontrolledRandomnessInTest,
     }
 )
 

sarj_python_lint-0.68.0/src/sarj_python_lint/rules/negative_only_http_status_assertion.py

@@ -0,0 +1,169 @@
+"""SARJ408 — A negative-only HTTP status assertion permits wrong non-500 responses.
+
+Examples: https://github.com/sarj-ai/standards/blob/main/packages/python/tests/rules/test_negative_only_http_status_assertion.py
+"""
+
+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,
+    parse_or_none,
+)
+from sarj_python_lint.rules._paths import is_test_path
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+
+_SERVER_ERROR_MIN = 500
+_SERVER_ERROR_MAX = 599
+
+
+def _int(node: ast.expr) -> int | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, int) and not isinstance(node.value, bool):
+        return node.value
+    return None
+
+
+def _negative_only(compare: ast.Compare) -> bool:
+    if len(compare.ops) != 1 or len(compare.comparators) != 1:
+        return False
+    left = compare.left
+    right = compare.comparators[0]
+    op = compare.ops[0]
+    match op:
+        case ast.NotEq():
+            return (_status_code(left) and _int(right) == _SERVER_ERROR_MIN) or (
+                _int(left) == _SERVER_ERROR_MIN and _status_code(right)
+            )
+        case ast.Lt() if _status_code(left):
+            return _int(right) == _SERVER_ERROR_MIN
+        case ast.LtE() if _status_code(left):
+            return _int(right) == _SERVER_ERROR_MIN - 1
+        case ast.NotIn() if _status_code(left):
+            return _all_server_errors(right)
+        case _:
+            return False
+
+
+def _status_code(node: ast.expr) -> bool:
+    return isinstance(node, ast.Attribute) and node.attr == "status_code"
+
+
+def _all_server_errors(node: ast.expr) -> bool:
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "range":
+        values = [_int(arg) for arg in node.args]
+        return values == [_SERVER_ERROR_MIN, _SERVER_ERROR_MAX + 1]
+    if not isinstance(node, (ast.Set, ast.List, ast.Tuple)) or not node.elts:
+        return False
+    values = [_int(elt) for elt in node.elts]
+    return all(value is not None and _SERVER_ERROR_MIN <= value <= _SERVER_ERROR_MAX for value in values)
+
+
+def _test_nodes(test: ast.FunctionDef | ast.AsyncFunctionDef) -> Iterator[ast.AST]:
+    """Walk one collected test without attributing nested helpers to it."""
+    stack: list[ast.AST] = [*reversed(test.body)]
+    while stack:
+        node = stack.pop()
+        yield node
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            continue
+        stack.extend(reversed(list(ast.iter_child_nodes(node))))
+
+
+@final
+class NegativeOnlyHttpStatusAssertion(Rule):
+    id = "negative-only-http-status-assertion"
+    code = "SARJ408"
+    documentation = RuleDocumentation(
+        summary="HTTP test assertion only excludes a server error instead of identifying the intended response.",
+        rationale=(
+            "Authentication, routing, validation, and domain failures can all replace the intended response while "
+            "a negative-only status assertion remains green."
+        ),
+        remediation="Assert the intended exact status and the relevant domain payload or side effect.",
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only assertions on an attribute named `status_code` in collected Python tests are checked.",
+            "Exact status contracts, finite success sets, arbitrary `.status` attributes, and locally suppressed chaos tests are excluded.",
+            "The intended status cannot be inferred safely, so the rule has no autofix.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="exact-validation-status",
+                title="Assert the intended validation response",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_route.py",
+                        "def test_invalid_payload(client):\n    response = client.post('/items', json={})\n    assert response.status_code == 422\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_route.py"),
+                expected_count=0,
+                public=True,
+            ),
+            RuleExample(
+                example_id="negative-only-server-status",
+                title="Do not accept every non-server-error response",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_route.py",
+                        "def test_invalid_payload(client):\n    response = client.post('/items', json={})\n    assert response.status_code != 500\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_route.py"),
+                expected_count=1,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if not is_test_path(path):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        tests = {
+            child
+            for child in ast.walk(tree)
+            if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)) and child.name.startswith("test_")
+        }
+        findings: list[Diagnostic] = []
+        for test in tests:
+            findings.extend(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    severity=Severity.WARNING,
+                    message=(
+                        "this assertion proves only that the response avoided one server-error shape; assert the "
+                        "intended exact status and, when relevant, its domain payload or side effect."
+                    ),
+                )
+                for node in _test_nodes(test)
+                if isinstance(node, ast.Assert) and isinstance(node.test, ast.Compare) and _negative_only(node.test)
+            )
+        findings.sort(key=lambda finding: (finding.line, finding.col))
+        return findings

sarj_python_lint-0.68.0/src/sarj_python_lint/rules/production_derived_test_cases.py

@@ -0,0 +1,191 @@
+"""SARJ409 — Imported production collections are not independent parametrized test oracles.
+
+Examples: https://github.com/sarj-ai/standards/blob/main/packages/python/tests/rules/test_production_derived_test_cases.py
+"""
+
+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,
+    parse_or_none,
+)
+from sarj_python_lint.rules._paths import is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_COLLECTION_WRAPPERS = frozenset({"sorted", "set", "tuple"})
+_PARAMETRIZE_CASES_INDEX = 1
+_PARAMETRIZE_MIN_ARGS = 2
+
+
+def _imported_bindings(tree: ast.Module) -> set[str]:
+    bindings: set[str] = set()
+    for node in tree.body:
+        if (
+            isinstance(node, ast.ImportFrom)
+            and node.module is not None
+            and not node.module.startswith(("test", "tests"))
+        ):
+            bindings.update(alias.asname or alias.name for alias in node.names if alias.name != "*")
+    return bindings
+
+
+def _direct_imported_collection(node: ast.expr, imported: set[str]) -> ast.Name | None:
+    if isinstance(node, ast.Name) and node.id in imported and node.id.isupper() and not _is_registry(node.id):
+        return node
+    if isinstance(node, ast.Call) and _is_imported_collection_wrapper(node, imported):
+        # `list(Enum)` / `tuple(Enum)` is an intentional exhaustiveness sweep;
+        # only set/sorted/tuple over an ALL_CAPS collection is the risky shape.
+        candidate = node.args[0]
+        return (
+            candidate
+            if isinstance(candidate, ast.Name) and candidate.id.isupper() and not _is_registry(candidate.id)
+            else None
+        )
+    if isinstance(node, ast.BinOp) and isinstance(node.op, (ast.Sub, ast.BitOr, ast.BitAnd)):
+        for side in (node.left, node.right):
+            found = _direct_imported_collection(side, imported)
+            if found is not None and found.id.isupper():
+                return found
+    return None
+
+
+def _is_registry(name: str) -> bool:
+    return name == "REGISTRY" or name.endswith("_REGISTRY")
+
+
+def _is_imported_collection_wrapper(node: ast.Call, imported: set[str]) -> bool:
+    return (
+        isinstance(node.func, ast.Name)
+        and node.func.id in _COLLECTION_WRAPPERS
+        and len(node.args) == 1
+        and isinstance(node.args[0], ast.Name)
+        and node.args[0].id in imported
+    )
+
+
+def _parametrize_cases(decorator: ast.expr) -> ast.expr | None:
+    if not isinstance(decorator, ast.Call) or len(decorator.args) < _PARAMETRIZE_MIN_ARGS:
+        return None
+    func = decorator.func
+    if not isinstance(func, ast.Attribute) or func.attr != "parametrize":
+        return None
+    return decorator.args[_PARAMETRIZE_CASES_INDEX]
+
+
+def _independently_asserted_collections(tree: ast.Module, imported: set[str]) -> set[str]:
+    asserted: set[str] = set()
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Assert) or not isinstance(node.test, ast.Compare):
+            continue
+        compare = node.test
+        if len(compare.ops) != 1 or not isinstance(compare.ops[0], ast.Eq) or len(compare.comparators) != 1:
+            continue
+        for side in (compare.left, compare.comparators[0]):
+            if isinstance(side, ast.Name) and side.id in imported:
+                asserted.add(side.id)
+    return asserted
+
+
+@final
+class ProductionDerivedTestCases(Rule):
+    id = "production-derived-test-cases"
+    code = "SARJ409"
+    documentation = RuleDocumentation(
+        summary="Parametrized test cases come from the production collection whose membership they should protect.",
+        rationale=(
+            "Removing a production member can remove the corresponding test case too, allowing the same defect to "
+            "weaken both the implementation and its supposed oracle."
+        ),
+        remediation="Define an independent expected table, assert production equals it, and drive behavior from that table.",
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only direct imported collections, simple collection wrappers, and direct set expressions in pytest parametrization are checked.",
+            "Local expected tables, test-helper fixtures, enum exhaustiveness, names ending in `_REGISTRY`, and collections whose exact membership is asserted elsewhere in the module are excluded.",
+            "Project-wide relationships hidden behind helpers require judgment and remain unreported.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="independent-model-cases",
+                title="Drive behavior from an independent expected table",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_models.py",
+                        "EXPECTED_MODELS = ('a', 'b')\n\n@pytest.mark.parametrize('model', EXPECTED_MODELS)\ndef test_model(model):\n    assert build(model).tier == 'priority'\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_models.py"),
+                expected_count=0,
+                public=True,
+            ),
+            RuleExample(
+                example_id="production-derived-model-cases",
+                title="Do not derive cases from production eligibility",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_models.py",
+                        "from app.models import ELIGIBLE_MODELS\n\n@pytest.mark.parametrize('model', ELIGIBLE_MODELS)\ndef test_model(model):\n    assert build(model).tier == 'priority'\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_models.py"),
+                expected_count=1,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if not is_test_path(path):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        imported = _imported_bindings(tree)
+        independently_asserted = _independently_asserted_collections(tree, imported)
+        findings: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) or not node.name.startswith("test_"):
+                continue
+            for decorator in node.decorator_list:
+                cases = _parametrize_cases(decorator)
+                if cases is None:
+                    continue
+                collection = _direct_imported_collection(cases, imported)
+                if collection is None or collection.id in independently_asserted:
+                    continue
+                findings.append(
+                    Diagnostic(
+                        path=path,
+                        line=decorator.lineno,
+                        col=decorator.col_offset + 1,
+                        code=self.code,
+                        severity=Severity.WARNING,
+                        message=(
+                            f"`{collection.id}` supplies the cases from production, so removing a member can remove "
+                            "the test that should catch the regression; define an independent expected case table and "
+                            "assert the production collection equals it."
+                        ),
+                    )
+                )
+        findings.sort(key=lambda finding: (finding.line, finding.col))
+        return findings