sarj-python-lint 0.67.12__tar.gz → 0.67.14__tar.gz

{sarj_python_lint-0.67.12 → sarj_python_lint-0.67.14}/PKG-INFO

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

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

{sarj_python_lint-0.67.12 → sarj_python_lint-0.67.14}/src/sarj_python_lint/rules/_registry.py

@@ -24,12 +24,12 @@ 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,
 )
-from sarj_python_lint.rules.no_apirouter_root_trailing_slash import (
-    NoApirouterRootTrailingSlash,
-)
 from sarj_python_lint.rules.no_comment_cruft import NoCommentCruft
 from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
     NoCorsWildcardWithCredentials,
@@ -108,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
@@ -124,6 +125,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
 
 
@@ -154,7 +156,6 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         SourceCoupledTest.id: SourceCoupledTest,
         NoQueryWithManyJoins.id: NoQueryWithManyJoins,
         NoAggregationInStoreQuery.id: NoAggregationInStoreQuery,
-        NoApirouterRootTrailingSlash.id: NoApirouterRootTrailingSlash,
         NoSelectStar.id: NoSelectStar,
         NoGenericSingleExportModule.id: NoGenericSingleExportModule,
         Stepdown.id: Stepdown,
@@ -208,6 +209,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.67.14/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.67.14/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

sarj_python_lint-0.67.14/src/sarj_python_lint/rules/uncontrolled_randomness_in_test.py

@@ -0,0 +1,176 @@
+"""SARJ410 — Repeated unseeded PRNG sampling makes a test probabilistic.
+
+Examples: https://github.com/sarj-ai/standards/blob/main/packages/python/tests/rules/test_uncontrolled_randomness_in_test.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
+
+
+_PRNG_FUNCTIONS = frozenset({"choice", "choices", "randint", "random", "randrange", "sample", "shuffle", "uniform"})
+_REPEAT_NODES = (ast.For, ast.AsyncFor, ast.While, ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)
+
+
+def _random_aliases(tree: ast.Module) -> tuple[set[str], set[str], set[str]]:
+    modules: set[str] = set()
+    functions: set[str] = set()
+    seeds: set[str] = set()
+    for node in tree.body:
+        if isinstance(node, ast.Import):
+            modules.update(alias.asname or alias.name for alias in node.names if alias.name == "random")
+        elif isinstance(node, ast.ImportFrom) and node.module == "random":
+            for alias in node.names:
+                local = alias.asname or alias.name
+                if alias.name in _PRNG_FUNCTIONS:
+                    functions.add(local)
+                elif alias.name == "seed":
+                    seeds.add(local)
+    return modules, functions, seeds
+
+
+def _is_prng_call(node: ast.Call, modules: set[str], functions: set[str]) -> bool:
+    if isinstance(node.func, ast.Name):
+        return node.func.id in functions
+    return (
+        isinstance(node.func, ast.Attribute)
+        and node.func.attr in _PRNG_FUNCTIONS
+        and isinstance(node.func.value, ast.Name)
+        and node.func.value.id in modules
+    )
+
+
+def _is_seed_call(node: ast.Call, modules: set[str], seeds: set[str]) -> bool:
+    if isinstance(node.func, ast.Name):
+        return node.func.id in seeds
+    return (
+        isinstance(node.func, ast.Attribute)
+        and node.func.attr == "seed"
+        and isinstance(node.func.value, ast.Name)
+        and node.func.value.id in modules
+    )
+
+
+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 UncontrolledRandomnessInTest(Rule):
+    id = "uncontrolled-randomness-in-test"
+    code = "SARJ410"
+    documentation = RuleDocumentation(
+        summary="Test repeatedly samples the standard PRNG without a seed or injected deterministic random source.",
+        rationale=(
+            "Repeated unseeded sampling makes pass/fail outcomes vary across identical runs and broad frequency "
+            "bounds can conceal heavily biased behavior."
+        ),
+        remediation="Inject a deterministic RNG, seed it explicitly, or use a property framework that records failing seeds.",
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only standard-library `random` calls nested in loops or comprehensions in collected tests are checked.",
+            "Single draws, injected RNG objects, Hypothesis tests, and cryptographic randomness are excluded.",
+            "A seed anywhere in the test suppresses the finding; interprocedural seeding is not inferred.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="seeded-random-sampling",
+                title="Make repeated random sampling reproducible",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_selector.py",
+                        "import random\n\ndef test_distribution():\n    random.seed(17)\n    values = [random.random() for _ in range(50)]\n    assert values\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_selector.py"),
+                expected_count=0,
+                public=True,
+            ),
+            RuleExample(
+                example_id="unseeded-random-sampling",
+                title="Do not repeat probabilistic trials without reproducibility",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_selector.py",
+                        "import random\n\ndef test_distribution():\n    values = [random.random() for _ in range(50)]\n    assert values\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_selector.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 []
+        modules, functions, seeds = _random_aliases(tree)
+        if not modules and not functions:
+            return []
+        findings: list[Diagnostic] = []
+        for test in ast.walk(tree):
+            if not isinstance(test, (ast.FunctionDef, ast.AsyncFunctionDef)) or not test.name.startswith("test_"):
+                continue
+            nodes = list(_test_nodes(test))
+            if any(isinstance(node, ast.Call) and _is_seed_call(node, modules, seeds) for node in nodes):
+                continue
+            for repeated in (node for node in nodes if isinstance(node, _REPEAT_NODES)):
+                calls = [
+                    node
+                    for node in ast.walk(repeated)
+                    if isinstance(node, ast.Call) and _is_prng_call(node, modules, functions)
+                ]
+                findings.extend(
+                    Diagnostic(
+                        path=path,
+                        line=call.lineno,
+                        col=call.col_offset + 1,
+                        code=self.code,
+                        severity=Severity.WARNING,
+                        message=(
+                            "this test repeatedly samples an unseeded PRNG, so the same code can pass or fail across "
+                            "runs; inject a deterministic RNG, set an explicit seed, or use a property-testing "
+                            "framework with recorded seeds."
+                        ),
+                    )
+                    for call in calls
+                )
+        unique = {(finding.line, finding.col): finding for finding in findings}
+        return [unique[key] for key in sorted(unique)]

sarj_python_lint-0.67.12/src/sarj_python_lint/rules/no_apirouter_root_trailing_slash.py

@@ -1,120 +0,0 @@
-"""SARJ405 — APIRouter collection roots use an empty path, not ``/``.
-
-Examples: https://github.com/sarj-ai/standards/blob/main/packages/python/tests/rules/test_no_apirouter_root_trailing_slash.py
-"""
-
-from __future__ import annotations
-
-import ast
-from pathlib import PurePosixPath
-from typing import TYPE_CHECKING, ClassVar, 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._ast_index import nodes
-from sarj_python_lint.rules._fastapi import FastapiIndex
-from sarj_python_lint.rules._paths import is_generated, is_test_path
-
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-_DOCUMENTATION_EXAMPLE_DIR_NAMES = frozenset({"docs_src"})
-
-
-@final
-class NoApirouterRootTrailingSlash(Rule):
-    id: str = "no-apirouter-root-trailing-slash"
-    code: str = "SARJ405"
-    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="APIRouter collection-root operations should use an empty path instead of `/`.",
-        rationale=(
-            "A `/` path beneath an APIRouter prefix makes the prefix without its trailing slash redirect, "
-            "rather than serving the canonical collection URL directly."
-        ),
-        remediation="Declare the APIRouter operation path as an empty string so the prefix itself is canonical.",
-        category=RuleCategory.CORRECTNESS,
-        autofix=AutofixPolicy.NONE,
-        limitations=(
-            "Only FastAPI and APIRouter bindings whose constructor provenance is visible in one module are resolved.",
-            "Dynamic route paths are ignored because their runtime value cannot be proven.",
-            "Tests, generated sources, and FastAPI documentation-source examples are excluded.",
-        ),
-        examples=(
-            RuleExample(
-                example_id="router-root-trailing-slash",
-                title="APIRouter root operation adds a trailing slash",
-                outcome=ExampleOutcome.MATCH,
-                files=(
-                    ExampleFile.python(
-                        "api.py",
-                        "from fastapi import APIRouter\n\nrouter = APIRouter(prefix='/items')\n\n"
-                        "@router.get('/')\nasync def list_items() -> list[str]:\n    return []\n",
-                    ),
-                ),
-                focus_path=PurePosixPath("api.py"),
-                expected_count=1,
-                public=True,
-            ),
-            RuleExample(
-                example_id="canonical-router-root",
-                title="APIRouter root operation uses its prefix directly",
-                outcome=ExampleOutcome.NO_MATCH,
-                files=(
-                    ExampleFile.python(
-                        "api.py",
-                        "from fastapi import APIRouter\n\nrouter = APIRouter(prefix='/items')\n\n"
-                        "@router.get('')\nasync def list_items() -> list[str]:\n    return []\n",
-                    ),
-                ),
-                focus_path=PurePosixPath("api.py"),
-                expected_count=0,
-                public=True,
-            ),
-        ),
-    )
-    description: str = documentation.summary
-
-    @override
-    def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if (
-            is_test_path(path)
-            or is_generated(path, source)
-            or any(part.lower() in _DOCUMENTATION_EXAMPLE_DIR_NAMES for part in path.parts)
-        ):
-            return []
-        tree = parse_or_none(path, source)
-        if tree is None:
-            return []
-        index = FastapiIndex(tree, path=path)
-        decorators: dict[int, ast.Call] = {}
-        for function in nodes(tree, ast.FunctionDef, ast.AsyncFunctionDef):
-            for route in index.routes(function):
-                if route.receiver_kind == "APIRouter" and route.path == "/":
-                    decorators[id(route.decorator)] = route.decorator
-
-        return [
-            Diagnostic(
-                path=path,
-                line=decorator.lineno,
-                col=decorator.col_offset + 1,
-                code=self.code,
-                severity=Severity.WARNING,
-                message=(
-                    "APIRouter collection-root path is `/`, so the prefix without a slash redirects — "
-                    "declare the path as an empty string. Suppress with `# sarj-noqa: SARJ405`."
-                ),
-            )
-            for decorator in sorted(decorators.values(), key=lambda node: (node.lineno, node.col_offset))
-        ]