sarj-python-lint 1.14.4__tar.gz → 1.15.1__tar.gz

{sarj_python_lint-1.14.4 → sarj_python_lint-1.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.14.4
+Version: 1.15.1
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://code-standards.sarj.ai/rules/python/
 Project-URL: Documentation, https://code-standards.sarj.ai/rules/python/

{sarj_python_lint-1.14.4 → sarj_python_lint-1.15.1}/pyproject.toml

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

{sarj_python_lint-1.14.4 → sarj_python_lint-1.15.1}/src/sarj_python_lint/_analysis_session.py

@@ -4,6 +4,7 @@ from typing import TYPE_CHECKING, final
 
 from sarj_python_lint._python_target import PythonTargetFacts
 from sarj_python_lint.rules._first_party import FirstPartyFacts
+from sarj_python_lint.rules._local_source import LocalSourceFacts
 from sarj_python_lint.rules._nominal_project import NominalProjectFacts
 
 
@@ -16,5 +17,6 @@ class AnalysisSession:
     def __init__(self) -> None:
         self.project: ProjectIndexSet | None = None
         self.first_party = FirstPartyFacts()
+        self.local_source = LocalSourceFacts()
         self.python_target = PythonTargetFacts()
         self.nominal_project = NominalProjectFacts()

sarj_python_lint-1.15.1/src/sarj_python_lint/rules/_local_source.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, final
+
+from sarj_python_lint.rules._imports import ImportIndex
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint.rules._first_party import FirstPartyFacts
+
+
+_MAX_ANCESTORS = 24
+_MAX_MODULE_BYTES = 256_000
+_MAX_MODULES = 512
+
+
+@dataclass(frozen=True, slots=True)
+class LocalModule:
+    path: Path
+    source: str
+    tree: ast.Module
+    runtime_imports: ImportIndex
+
+
+@final
+class LocalSourceFacts:
+    def __init__(self) -> None:
+        self._resolutions: dict[tuple[Path, str | None, int], Path | None] = {}
+        self._modules: dict[Path, LocalModule | None] = {}
+
+    def resolve_module(self, current: Path, module: str | None, level: int, *, facts: FirstPartyFacts) -> Path | None:
+        try:
+            current = current.absolute()
+        except OSError:
+            return None
+        key = (current, module, level)
+        if key in self._resolutions:
+            return self._resolutions[key]
+        if len(self._resolutions) >= _MAX_MODULES:
+            return None
+        result = _resolve_module(current, module, level, facts=facts)
+        self._resolutions[key] = result
+        return result
+
+    def read_module(self, path: Path) -> LocalModule | None:
+        if path in self._modules:
+            return self._modules[path]
+        if len(self._modules) >= _MAX_MODULES:
+            return None
+        module = _read_module(path)
+        self._modules[path] = module
+        return module
+
+
+def _resolve_module(current: Path, module: str | None, level: int, *, facts: FirstPartyFacts) -> Path | None:
+    if ".." in current.parts or level > _MAX_ANCESTORS:
+        return None
+    root = facts.project_root(current)
+    if root is None or not _safe_path(current, root):
+        return None
+    parts = module.split(".") if module else []
+    if any(not part.isidentifier() for part in parts):
+        return None
+    candidates: set[Path] = set()
+    for base in _import_bases(current, root, level):
+        target = base.joinpath(*parts)
+        for candidate in (target.with_suffix(".py"), target / "__init__.py"):
+            if _safe_path(candidate, root) and candidate.is_file():
+                candidates.add(candidate)
+    return next(iter(candidates)) if len(candidates) == 1 else None
+
+
+def _import_bases(current: Path, root: Path, level: int) -> list[Path]:
+    if level:
+        base = current.parent
+        for _ in range(level - 1):
+            if base == root:
+                return []
+            base = base.parent
+        return [base]
+    bases: list[Path] = []
+    for ancestor in list(current.parents)[:_MAX_ANCESTORS]:
+        if not ancestor.is_relative_to(root):
+            break
+        bases.append(ancestor)
+        if (ancestor / "pyproject.toml").is_file():
+            bases.append(ancestor / "src")
+        if ancestor == root:
+            break
+    return bases
+
+
+def _safe_path(path: Path, root: Path) -> bool:
+    if not path.is_relative_to(root):
+        return False
+    try:
+        for entry in (path, *list(path.parents)[:_MAX_ANCESTORS]):
+            if entry == root:
+                return True
+            if entry.is_symlink() or (entry != path and (entry / ".git").exists()):
+                return False
+    except OSError:
+        return False
+    return False
+
+
+def _read_module(path: Path) -> LocalModule | None:
+    try:
+        with path.open("rb") as stream:
+            data = stream.read(_MAX_MODULE_BYTES + 1)
+        if len(data) > _MAX_MODULE_BYTES:
+            return None
+        source = data.decode("utf-8")
+        tree = ast.parse(source, filename=str(path))
+    except OSError, UnicodeError, SyntaxError:
+        return None
+    runtime_imports = ast.Module(
+        body=[node for node in tree.body if isinstance(node, (ast.Import, ast.ImportFrom))], type_ignores=[]
+    )
+    return LocalModule(path, source, tree, ImportIndex.from_tree(runtime_imports))

{sarj_python_lint-1.14.4 → sarj_python_lint-1.15.1}/src/sarj_python_lint/rules/_registry.py

@@ -133,6 +133,7 @@ from sarj_python_lint.rules.prefer_non_nullable_collection import (
 )
 from sarj_python_lint.rules.prefer_or_pattern import PreferOrPattern
 from sarj_python_lint.rules.prefer_pydantic_json_value import PreferPydanticJsonValue
+from sarj_python_lint.rules.prefer_pytest_fixture_injection import PreferPytestFixtureInjection
 from sarj_python_lint.rules.prefer_regex_fullmatch import PreferRegexFullmatch
 from sarj_python_lint.rules.prefer_self_documenting_constant import (
     PreferSelfDocumentingConstant,
@@ -278,6 +279,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoRepeatedTestBody.id: NoRepeatedTestBody,
         UnusedMockSetup.id: UnusedMockSetup,
         UnusedTestFactoryOption.id: UnusedTestFactoryOption,
+        PreferPytestFixtureInjection.id: PreferPytestFixtureInjection,
         PreferFstringOverConcat.id: PreferFstringOverConcat,
         PreferOrPattern.id: PreferOrPattern,
         PreferPydanticJsonValue.id: PreferPydanticJsonValue,

sarj_python_lint-1.15.1/src/sarj_python_lint/rules/prefer_pytest_fixture_injection.py

@@ -0,0 +1,452 @@
+from __future__ import annotations
+
+import ast
+from collections import Counter
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, NamedTuple, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+)
+from sarj_python_lint.rules._paths import is_generated, is_test_support_path
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._local_source import LocalModule
+
+
+type Function = ast.FunctionDef | ast.AsyncFunctionDef
+_POOL_CONSTRUCTORS = frozenset({"psycopg_pool.ConnectionPool", "psycopg_pool.AsyncConnectionPool"})
+_SETUP_AND_CONSUMER = 2
+_SUPPORT_SOURCE = (
+    "from psycopg_pool import ConnectionPool\n\n"
+    "def pool() -> ConnectionPool[object]:\n"
+    "    return ConnectionPool[object](open=False)\n"
+)
+
+
+class _HelperImport(NamedTuple):
+    local: str
+    symbol: str
+    module: str
+    level: int
+
+
+class PreferPytestFixtureInjection(Rule):
+    id: str = "prefer-pytest-fixture-injection"
+    code: str = "SARJ476"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Request shared database-pool setup through a pytest fixture.",
+        rationale=(
+            "Calling a shared conftest pool helper during initial test setup bypasses an explicit pytest "
+            "fixture dependency for that setup."
+        ),
+        remediation=(
+            "Request one function-scoped fixture visible to the test, preserving initial pool state, creation "
+            "timing, and cleanup ownership. Use yield teardown when the fixture owns cleanup; keep factories "
+            "for variants or fresh instances."
+        ),
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only directly collected module-level test functions in conventional pytest module names are checked.",
+            "Only unshadowed runtime imports from a uniquely resolved local conftest module are followed.",
+            "Helpers must be undecorated synchronous functions with no formal inputs and one direct return of an imported psycopg_pool pool constructor.",
+            "Setup must be the first executable statement and immediately feed a plain call, or appear inline as a direct argument of that first call.",
+            "Class tests, decorated helpers, unknown test decorators, dynamic imports, re-exports, and ambiguous or out-of-bound source paths are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="manual-shared-generic-pool",
+                title="A test calls shared generic pool setup",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python("tests/conftest.py", _SUPPORT_SOURCE),
+                    ExampleFile.python(
+                        "tests/test_app.py",
+                        "from tests.conftest import pool\n\n"
+                        "def test_app():\n    resource = pool()\n    app = Application(resource)\n    assert app\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_app.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="injected-generic-pool",
+                title="A test requests its shared resource",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/conftest.py",
+                        "import pytest\nfrom psycopg_pool import ConnectionPool\n\n"
+                        "@pytest.fixture\ndef pool() -> ConnectionPool[object]:\n"
+                        "    return ConnectionPool[object](open=False)\n",
+                    ),
+                    ExampleFile.python(
+                        "tests/test_app.py", "def test_app(pool):\n    app = Application(pool)\n    assert app\n"
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_app.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description: str = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if (
+            context.path.suffix != ".py"
+            or not (context.path.name.startswith("test_") or context.path.name.endswith("_test.py"))
+            or is_test_support_path(context.path)
+            or context.generated
+            or context.tree is None
+        ):
+            return []
+        tree = context.tree
+        helpers = _resource_helpers(context)
+        if not helpers:
+            return []
+        module_bindings = _scope_bindings(tree)
+        if "__test__" in module_bindings or any(
+            isinstance(node, ast.Attribute) and node.attr == "__test__" and isinstance(node.ctx, (ast.Store, ast.Del))
+            for node in ast.walk(tree)
+        ):
+            return []
+        diagnostics: list[Diagnostic] = []
+        for statement in tree.body:
+            if (
+                not isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef))
+                or module_bindings[statement.name] != 1
+                or _module_reference(tree, statement.name)
+            ):
+                continue
+            call = _setup_call(context, statement, helpers)
+            if call is not None:
+                diagnostics.append(
+                    Diagnostic(
+                        path=context.path,
+                        line=call.lineno,
+                        col=call.col_offset + 1,
+                        code=self.code,
+                        message=(
+                            "test calls a shared conftest pool helper during initial setup; request one visible "
+                            "function-scoped fixture by parameter, preserving initial pool state, creation timing, "
+                            "and cleanup ownership; keep factories for variants or fresh instances."
+                        ),
+                        severity=Severity.WARNING,
+                    )
+                )
+        return diagnostics
+
+
+def _resource_helpers(context: PythonFileContext) -> frozenset[str]:
+    tree = context.tree
+    if tree is None:
+        return frozenset()
+    references = tuple(_helper_imports(tree))
+    if not references:
+        return frozenset()
+    bindings = _scope_bindings(tree)
+    helpers: set[str] = set()
+    for reference in references:
+        if bindings[reference.local] != 1 or _root_mutated(tree, reference.local):
+            continue
+        target = context.session.local_source.resolve_module(
+            context.path, reference.module, reference.level, facts=context.session.first_party
+        )
+        module = (
+            context.session.local_source.read_module(target)
+            if target is not None and target.name == "conftest.py"
+            else None
+        )
+        if module is not None and _is_resource_helper(module, reference.symbol):
+            helpers.add(reference.local)
+    return frozenset(helpers)
+
+
+def _helper_imports(tree: ast.Module) -> Iterator[_HelperImport]:
+    candidates: list[_HelperImport] = []
+    for statement in tree.body:
+        if not isinstance(statement, ast.ImportFrom):
+            continue
+        module = statement.module
+        if module is None or module.rsplit(".", 1)[-1] != "conftest":
+            continue
+        candidates.extend(
+            _HelperImport(alias.asname or alias.name, alias.name, module, statement.level) for alias in statement.names
+        )
+    if not candidates or _has_wildcard(tree):
+        return
+    yield from candidates
+
+
+def _is_resource_helper(module: LocalModule, symbol: str) -> bool:
+    if (
+        is_generated(module.path, module.source)
+        or _scope_bindings(module.tree)[symbol] != 1
+        or _has_wildcard(module.tree)
+        or _root_mutated(module.tree, symbol)
+    ):
+        return False
+    helper = next(
+        (node for node in module.tree.body if isinstance(node, ast.FunctionDef) and node.name == symbol), None
+    )
+    if helper is None or helper.decorator_list:
+        return False
+    arguments = helper.args
+    if arguments.posonlyargs or arguments.args or arguments.kwonlyargs or arguments.vararg or arguments.kwarg:
+        return False
+    body = _executable_body(helper)
+    if len(body) != 1 or not isinstance(body[0], ast.Return) or not isinstance(body[0].value, ast.Call):
+        return False
+    constructor = body[0].value.func
+    if isinstance(constructor, ast.Subscript):
+        constructor = constructor.value
+    root = _root_name(constructor)
+    return (
+        root is not None
+        and _scope_bindings(module.tree)[root] == 1
+        and not _root_mutated(module.tree, root)
+        and module.runtime_imports.resolved_qualified_name(constructor) in _POOL_CONSTRUCTORS
+    )
+
+
+def _setup_call(context: PythonFileContext, function: Function, helpers: frozenset[str]) -> ast.Call | None:
+    if not function.name.startswith("test_") or any(
+        not _pytest_mark(context, decorator) for decorator in function.decorator_list
+    ):
+        return None
+    bindings = _scope_bindings(function)
+    available = helpers - bindings.keys()
+    # Looking through nested scopes here conservatively excludes captures and callable escapes.
+    uses = [node for node in ast.walk(function) if isinstance(node, ast.Name) and node.id in available]
+    if len(uses) != 1:
+        return None
+    body = _executable_body(function)
+    if not body:
+        return None
+    first = body[0]
+    setup = _plain_call(first)
+    if setup is None:
+        return None
+    if _helper_call(setup, available):
+        return _assigned_dependency_call(context, body, bindings, setup)
+    if not _unshadowed_consumer(context, setup, bindings):
+        return None
+    inline = [arg for arg in _arguments(setup) if isinstance(arg, ast.Call) and _helper_call(arg, available)]
+    return inline[0] if len(inline) == 1 else None
+
+
+def _assigned_dependency_call(
+    context: PythonFileContext, body: list[ast.stmt], bindings: Counter[str], setup: ast.Call
+) -> ast.Call | None:
+    resource = _assignment_name(body[0])
+    if resource is None or bindings[resource] != 1 or len(body) < _SETUP_AND_CONSUMER:
+        return None
+    consumer = _plain_call(body[1])
+    if consumer is None or not _unshadowed_consumer(context, consumer, bindings):
+        return None
+    for argument in _arguments(consumer):
+        if isinstance(argument, ast.Name) and argument.id == resource:
+            return setup
+    return None
+
+
+def _pytest_mark(context: PythonFileContext, decorator: ast.expr) -> bool:
+    target = decorator.func if isinstance(decorator, ast.Call) else decorator
+    qualified = context.module_imports.resolved_qualified_name(target)
+    tree = context.tree
+    root = _root_name(target)
+    if (
+        qualified is None
+        or not qualified.startswith("pytest.mark.")
+        or tree is None
+        or root is None
+        or _scope_bindings(tree)[root] != 1
+    ):
+        return False
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.Attribute, ast.Subscript)) or not isinstance(node.ctx, (ast.Store, ast.Del)):
+            continue
+        if isinstance(node, ast.Subscript) and _root_name(node.value) == root:
+            return False
+        changed = context.module_imports.resolved_qualified_name(node)
+        if changed is not None and (qualified == changed or qualified.startswith(f"{changed}.")):
+            return False
+    return True
+
+
+def _unshadowed_consumer(context: PythonFileContext, call: ast.Call, bindings: Counter[str]) -> bool:
+    root = _root_name(call.func)
+    tree = context.tree
+    return (
+        root is not None
+        and root not in bindings
+        and tree is not None
+        and _scope_bindings(tree)[root] <= 1
+        and not _root_mutated(tree, root)
+    )
+
+
+def _module_reference(tree: ast.Module, name: str) -> bool:
+    return any(
+        isinstance(node, ast.Name) and node.id == name and isinstance(node.ctx, ast.Load)
+        for statement in tree.body
+        if not isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))
+        for node in ast.walk(statement)
+    )
+
+
+def _helper_call(call: ast.Call, helpers: frozenset[str] | set[str]) -> bool:
+    return isinstance(call.func, ast.Name) and call.func.id in helpers and not call.args and not call.keywords
+
+
+def _arguments(call: ast.Call) -> Iterator[ast.expr]:
+    yield from call.args
+    yield from (keyword.value for keyword in call.keywords if keyword.arg is not None)
+
+
+def _plain_call(statement: ast.stmt) -> ast.Call | None:
+    if (
+        isinstance(statement, (ast.Expr, ast.Assign, ast.AnnAssign))
+        and isinstance(statement.value, ast.Call)
+        and isinstance(statement.value.func, (ast.Name, ast.Attribute))
+    ):
+        return statement.value
+    return None
+
+
+def _assignment_name(statement: ast.stmt) -> str | None:
+    if isinstance(statement, ast.Assign) and len(statement.targets) == 1 and isinstance(statement.targets[0], ast.Name):
+        return statement.targets[0].id
+    if isinstance(statement, ast.AnnAssign) and isinstance(statement.target, ast.Name):
+        return statement.target.id
+    return None
+
+
+def _root_name(expression: ast.expr) -> str | None:
+    while isinstance(expression, ast.Attribute):
+        expression = expression.value
+    return expression.id if isinstance(expression, ast.Name) else None
+
+
+def _executable_body(function: Function) -> list[ast.stmt]:
+    body = function.body
+    if (
+        body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+    ):
+        return body[1:]
+    return body
+
+
+def _scope_bindings(scope: ast.Module | Function) -> Counter[str]:
+    names: Counter[str] = Counter()
+    if isinstance(scope, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        arguments = scope.args
+        names.update(arg.arg for arg in (*arguments.posonlyargs, *arguments.args, *arguments.kwonlyargs))
+        names.update(arg.arg for arg in (arguments.vararg, arguments.kwarg) if arg is not None)
+    for statement in scope.body:
+        _collect_bindings(statement, names)
+    if isinstance(scope, ast.Module):
+        names.update(_global_writes(scope))
+    return names
+
+
+def _global_writes(tree: ast.Module) -> Counter[str]:
+    if not any(isinstance(node, ast.Global) for node in ast.walk(tree)):
+        return Counter()
+    writes: Counter[str] = Counter()
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        names: Counter[str] = Counter()
+        declarations: set[str] = set()
+        for statement in node.body:
+            _collect_bindings(statement, names)
+            declarations.update(_global_names(statement))
+        writes.update(dict.fromkeys(declarations & names.keys(), 2))
+    return writes
+
+
+def _global_names(node: ast.AST) -> Iterator[str]:
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)):
+        return
+    if isinstance(node, ast.Global):
+        yield from node.names
+    for child in ast.iter_child_nodes(node):
+        yield from _global_names(child)
+
+
+def _collect_bindings(node: ast.AST, names: Counter[str]) -> None:
+    match node:
+        case ast.FunctionDef(name=name) | ast.AsyncFunctionDef(name=name) | ast.ClassDef(name=name):
+            names[name] += 1
+            for expression in _definition_expressions(node):
+                _collect_bindings(expression, names)
+            return
+        case ast.Lambda():
+            for expression in _definition_expressions(node):
+                _collect_bindings(expression, names)
+            return
+        case ast.Import(names=aliases) | ast.ImportFrom(names=aliases):
+            names.update(alias.asname or alias.name.partition(".")[0] for alias in aliases)
+        case (
+            ast.Name(id=name, ctx=(ast.Store() | ast.Del()))
+            | ast.ExceptHandler(name=str(name))
+            | ast.MatchAs(name=str(name))
+            | ast.MatchStar(name=str(name))
+            | ast.MatchMapping(rest=str(name))
+        ):
+            names[name] += 1
+        case ast.comprehension():
+            _collect_bindings(node.iter, names)
+            for condition in node.ifs:
+                _collect_bindings(condition, names)
+            return
+        case _:
+            pass
+    for child in ast.iter_child_nodes(node):
+        _collect_bindings(child, names)
+
+
+def _definition_expressions(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | ast.Lambda) -> list[ast.AST]:
+    if isinstance(node, ast.ClassDef):
+        return [*node.decorator_list, *node.bases, *node.keywords]
+    defaults: list[ast.AST] = [
+        *node.args.defaults,
+        *(default for default in node.args.kw_defaults if default is not None),
+    ]
+    return defaults if isinstance(node, ast.Lambda) else [*node.decorator_list, *defaults]
+
+
+def _has_wildcard(tree: ast.Module) -> bool:
+    return any(
+        isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names) for node in ast.walk(tree)
+    )
+
+
+def _root_mutated(tree: ast.Module, root: str) -> bool:
+    return any(
+        isinstance(node, (ast.Attribute, ast.Subscript))
+        and isinstance(node.ctx, (ast.Store, ast.Del))
+        and _root_name(node.value) == root
+        for node in ast.walk(tree)
+    )