sarj-python-lint 0.81.14__tar.gz → 0.81.16__tar.gz

{sarj_python_lint-0.81.14 → sarj_python_lint-0.81.16}/PKG-INFO

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

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

{sarj_python_lint-0.81.14 → sarj_python_lint-0.81.16}/src/sarj_python_lint/rules/_registry.py

@@ -154,6 +154,7 @@ from sarj_python_lint.rules.trailing_value_narration import TrailingValueNarrati
 from sarj_python_lint.rules.typed_error_reasons import TypedErrorReasons
 from sarj_python_lint.rules.uncontrolled_randomness_in_test import UncontrolledRandomnessInTest
 from sarj_python_lint.rules.unused_mock_setup import UnusedMockSetup
+from sarj_python_lint.rules.unused_test_factory_option import UnusedTestFactoryOption
 
 
 if TYPE_CHECKING:
@@ -219,6 +220,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoFrozenAfterValidatorFieldWrite.id: NoFrozenAfterValidatorFieldWrite,
         NoRepeatedTestBody.id: NoRepeatedTestBody,
         UnusedMockSetup.id: UnusedMockSetup,
+        UnusedTestFactoryOption.id: UnusedTestFactoryOption,
         PreferFstringOverConcat.id: PreferFstringOverConcat,
         PreferOrPattern.id: PreferOrPattern,
         RequirePortForService.id: RequirePortForService,

{sarj_python_lint-0.81.14 → sarj_python_lint-0.81.16}/src/sarj_python_lint/rules/no_repeated_test_body.py

@@ -44,6 +44,7 @@ _MIN_STATEMENTS = 3
 
 # Members of a normalized-body group before it counts as copy-paste.
 _MIN_GROUP = 2
+_MIN_SHORT_CASE_GROUP = 3
 
 # Small source-checker pairs often read better as individually named contracts.
 # A longer uninterrupted run is a case table whose repeated shell obscures the cases.
@@ -114,21 +115,22 @@ class NoRepeatedTestBody(Rule):
         limitations=(
             "Only substantial sibling test bodies in one non-generated module are compared.",
             "A run of at least five two-statement embedded-source checker cases is compared because the source documents are natural parameter values.",
+            "At least three consecutive call-and-literal-equality cases with corroborating behavior names are compared even with only two statements.",
             "Meaningful docstring or comment differences keep tests distinct.",
             "Two-test groups with varying literals require corroborating behavior names; long scenario prose and distinct API resources remain separate contracts.",
         ),
         examples=(
             RuleExample(
-                example_id="copy-pasted-tests",
-                title="Copy-pasted tests hide the changing case dimension",
+                example_id="short-literal-cases",
+                title="Consecutive short cases repeat the same call and assertion",
                 outcome=ExampleOutcome.MATCH,
                 files=(
                     ExampleFile.python(
-                        "tests/test_permissions.py",
-                        'def test_rejects_blank_role():\n    role = parse_role("")\n    result = validate(role)\n    assert result.invalid\n\ndef test_rejects_space_role():\n    role = parse_role(" ")\n    result = validate(role)\n    assert result.invalid\n\ndef test_rejects_tab_role():\n    role = parse_role("\\t")\n    result = validate(role)\n    assert result.invalid\n',
+                        "tests/test_parser.py",
+                        'def test_parse_one():\n    result = parse("a")\n    assert result == 1\n\ndef test_parse_two():\n    result = parse("b")\n    assert result == 2\n\ndef test_parse_three():\n    result = parse("c")\n    assert result == 3\n',
                     ),
                 ),
-                focus_path=PurePosixPath("tests/test_permissions.py"),
+                focus_path=PurePosixPath("tests/test_parser.py"),
                 expected_count=1,
                 public=True,
             ),
@@ -349,7 +351,7 @@ def _duplicate_groups(tree: ast.Module, source: str) -> list[list[_Shape]]:
         if in_test_case or _uses_unittest_api(node):
             continue
         outline = _Outline(node, container)
-        if outline.statements < _MIN_STATEMENTS and not outline.embedded_source_checker:
+        if outline.statements < _MIN_STATEMENTS and not (outline.embedded_source_checker or _is_short_case(node)):
             continue
         outlines.setdefault(outline.key, []).append(outline)
 
@@ -366,11 +368,22 @@ def _duplicate_groups(tree: ast.Module, source: str) -> list[list[_Shape]]:
             shape = _Shape(outline.node, comments, imports)
             groups.setdefault(shape.key, []).append(shape)
         for members in groups.values():
-            candidates = (
-                _consecutive_embedded_source_groups(members, positions)
-                if all(member.embedded_source_checker for member in members)
-                else [members]
-            )
+            if all(_is_short_case(member.node) for member in members):
+                candidates = [
+                    run
+                    for run in _consecutive_groups(members, positions)
+                    if len(run) >= _MIN_SHORT_CASE_GROUP
+                    and _test_name_tokens(run[0].node.name).intersection(
+                        *(_test_name_tokens(member.node.name) for member in run[1:])
+                    )
+                    - _WEAK_TEST_NAME_TOKENS
+                ]
+            else:
+                candidates = (
+                    _consecutive_embedded_source_groups(members, positions)
+                    if all(member.embedded_source_checker for member in members)
+                    else [members]
+                )
             found.extend(
                 candidate
                 for candidate in candidates
@@ -391,13 +404,21 @@ def duplicate_test_owner_ids(tree: ast.Module, source: str) -> frozenset[int]:
 
 
 def _consecutive_embedded_source_groups(members: list[_Shape], positions: dict[int, int]) -> list[list[_Shape]]:
+    return [
+        run
+        for run in _consecutive_groups(members, positions)
+        if len(run) >= _MIN_EMBEDDED_SOURCE_GROUP and _shares_embedded_source_signal(run)
+    ]
+
+
+def _consecutive_groups(members: list[_Shape], positions: dict[int, int]) -> list[list[_Shape]]:
     ordered = sorted(members, key=lambda member: positions[id(member.node)])
     runs: list[list[_Shape]] = []
     for member in ordered:
         if not runs or positions[id(member.node)] != positions[id(runs[-1][-1].node)] + 1:
             runs.append([])
         runs[-1].append(member)
-    return [run for run in runs if len(run) >= _MIN_EMBEDDED_SOURCE_GROUP and _shares_embedded_source_signal(run)]
+    return runs
 
 
 def _shares_embedded_source_signal(members: list[_Shape]) -> bool:
@@ -546,6 +567,19 @@ def _body_without_docstring(node: ast.FunctionDef | ast.AsyncFunctionDef) -> lis
     return body
 
 
+def _is_short_case(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    match _body_without_docstring(node):
+        case [
+            ast.Assign(targets=[ast.Name(id=name)], value=ast.Call()),
+            ast.Assert(
+                test=ast.Compare(left=ast.Name(id=result), ops=[ast.Eq()], comparators=[ast.Constant()]), msg=None
+            ),
+        ]:
+            return name == result
+        case _:
+            return False
+
+
 def _is_embedded_source_checker(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
     match _body_without_docstring(node):
         case [

sarj_python_lint-0.81.16/src/sarj_python_lint/rules/unused_test_factory_option.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, TypeGuard, final
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+    parse_or_none,
+)
+from sarj_python_lint.rules._ast_index import nodes
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_MIN_INVARIANT_CALLS = 2
+
+_REFLECTION = frozenset({"globals", "locals", "vars", "eval", "exec", "getattr", "__import__", "__all__"})
+
+
+@final
+class UnusedTestFactoryOption(Rule):
+    id = "unused-test-factory-option"
+    code = "SARJ443"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="A private test factory exposes a literal option that visible callers never vary.",
+        rationale="Unused customization obscures the values that actually distinguish test scenarios.",
+        remediation="Keep the value in the factory's construction instead of exposing an unused option; retain it if external callers need it.",
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only module-level private _make_ and _build_ helpers consisting of a single return call are considered.",
+            "Only literal defaults with direct, unambiguous calls in this file are reported. Explicit options require at least two calls with the same effective literal value. Decorators, rebinding, callable escapes, reflection, and argument unpacking exclude the helper.",
+            "Cross-module callers cannot be proven absent. Shared helpers require an exact suppression; this advisory never autofixes signatures or changes default evaluation timing.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="invariant-size-option",
+                title="Repeated calls never vary the option",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_widget.py",
+                        "def _make_widget(*, size=3):\n    return Widget(size=size)\n\n_make_widget()\n_make_widget(size=3)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_widget.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="exercised-size-option",
+                title="Keep customization that a caller exercises",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_widget.py",
+                        "def _make_widget(*, size=3):\n    return Widget(size=size)\n\ndef test_widget():\n    assert _make_widget(size=4)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_widget.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if not is_test_path(path) or is_generated(path, source) or not ("_make_" in source or "_build_" in source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None or (
+            any(node.id in _REFLECTION for node in nodes(tree, ast.Name))
+            or any(node.attr in _REFLECTION or node.attr == "__dict__" for node in nodes(tree, ast.Attribute))
+            or any(node.name in _REFLECTION or node.name == "*" for node in nodes(tree, ast.alias))
+        ):
+            return []
+        lines = source.splitlines()
+        findings: list[Diagnostic] = []
+        for function in tree.body:
+            if not _is_factory(function):
+                continue
+            calls = _direct_calls(tree, function)
+            if not calls:
+                continue
+            bound = _bound_calls(function, calls)
+            if bound is None:
+                continue
+            supplied = {name for arguments in bound for name in arguments}
+            positional = [*function.args.posonlyargs, *function.args.args]
+            defaults = [
+                *zip(positional[len(positional) - len(function.args.defaults) :], function.args.defaults, strict=True),
+                *zip(function.args.kwonlyargs, function.args.kw_defaults, strict=True),
+            ]
+            used = {node.id for node in nodes(function, ast.Name) if isinstance(node.ctx, ast.Load)}
+            for argument, default in defaults:
+                if argument.arg not in used or not isinstance(default, ast.Constant):
+                    continue
+                if default.value is not None and not isinstance(default.value, (str, bytes, int, float)):
+                    continue
+                explicitly_supplied = argument.arg in supplied
+                if explicitly_supplied:
+                    values = [arguments.get(argument.arg, default) for arguments in bound]
+                    if len(values) < _MIN_INVARIANT_CALLS or any(
+                        not isinstance(value, ast.Constant) or ast.dump(value) != ast.dump(values[0])
+                        for value in values
+                    ):
+                        continue
+                if is_suppressed(lines, argument.lineno, self.code):
+                    continue
+                findings.append(
+                    Diagnostic(
+                        path=path,
+                        line=argument.lineno,
+                        col=argument.col_offset + 1,
+                        code=self.code,
+                        severity=Severity.WARNING,
+                        message=(
+                            f"Direct callers in this file always use the same literal for `{function.name}.{argument.arg}`; "
+                            "consider keeping that value in the factory instead of repeating an invariant option. Retain it if external callers need it."
+                            if explicitly_supplied
+                            else f"No direct caller in this file supplies `{function.name}.{argument.arg}`; keep its literal value in the factory instead of exposing an unused option. Retain it if external callers need it."
+                        ),
+                    )
+                )
+        return sorted(findings, key=lambda item: (item.line, item.col))
+
+
+def _is_factory(node: ast.stmt) -> TypeGuard[ast.FunctionDef]:
+    return (
+        isinstance(node, ast.FunctionDef)
+        and node.name.startswith(("_make_", "_build_"))
+        and not node.decorator_list
+        and node.args.vararg is None
+        and node.args.kwarg is None
+        and len(node.body) == 1
+        and isinstance(node.body[0], ast.Return)
+        and isinstance(node.body[0].value, ast.Call)
+    )
+
+
+def _direct_calls(tree: ast.Module, function: ast.FunctionDef) -> list[ast.Call]:
+    name = function.name
+    if sum(node.name == name for node in nodes(tree, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) != 1:
+        return []
+    if any(node.arg == name for node in nodes(tree, ast.arg)):
+        return []
+    if any((node.asname or node.name.split(".")[0]) == name for node in nodes(tree, ast.alias)):
+        return []
+    if any(node.attr == name for node in nodes(tree, ast.Attribute)):
+        return []
+    if any(node.value == name for node in nodes(tree, ast.Constant)):
+        return []
+    if any(node.name == name for node in nodes(tree, ast.MatchAs, ast.MatchStar, ast.ExceptHandler)):
+        return []
+    if any(node.rest == name for node in nodes(tree, ast.MatchMapping)):
+        return []
+    references = [node for node in nodes(tree, ast.Name) if node.id == name]
+    calls = [node for node in nodes(tree, ast.Call) if isinstance(node.func, ast.Name) and node.func.id == name]
+    if not calls or len(references) != len(calls) or any(not isinstance(node.ctx, ast.Load) for node in references):
+        return []
+    if any(
+        any(isinstance(arg, ast.Starred) for arg in call.args) or any(kw.arg is None for kw in call.keywords)
+        for call in calls
+    ):
+        return []
+    if any(function.lineno <= call.lineno <= (function.end_lineno or function.lineno) for call in calls):
+        return []
+    return calls
+
+
+def _bound_calls(function: ast.FunctionDef, calls: list[ast.Call]) -> list[dict[str, ast.expr]] | None:
+    positional = [*function.args.posonlyargs, *function.args.args]
+    keywords = {arg.arg for arg in (*function.args.args, *function.args.kwonlyargs)}
+    required = {arg.arg for arg in positional[: len(positional) - len(function.args.defaults)]}
+    required.update(
+        arg.arg
+        for arg, default in zip(function.args.kwonlyargs, function.args.kw_defaults, strict=True)
+        if default is None
+    )
+    bound: list[dict[str, ast.expr]] = []
+    for call in calls:
+        if len(call.args) > len(positional):
+            return None
+        arguments = {arg.arg: value for arg, value in zip(positional[: len(call.args)], call.args, strict=True)}
+        for keyword in call.keywords:
+            if keyword.arg not in keywords or keyword.arg in arguments:
+                return None
+            arguments[keyword.arg] = keyword.value
+        if not required <= arguments.keys():
+            return None
+        bound.append(arguments)
+    return bound