sarj-python-lint 1.16.0__tar.gz → 1.16.1__tar.gz

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.1}/PKG-INFO

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

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

sarj_python_lint-1.16.1/src/sarj_python_lint/rules/discourage_nullable_constructor_parameters.py

@@ -0,0 +1,171 @@
+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,
+)
+from sarj_python_lint.rules._paths import is_test_path
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_REJECTED = (
+    "class Service:\n"
+    "    def __init__(self, store: Store | None = None) -> None:\n"
+    "        if store is None:\n"
+    "            raise ValueError('store is required')\n"
+    "        self.store = store\n"
+)
+
+
+@final
+class DiscourageNullableConstructorParameters(Rule):
+    id = "discourage-nullable-constructor-parameters"
+    code = "SARJ468"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Make constructor inputs required when their None default is immediately rejected.",
+        rationale=(
+            "A constructor that immediately rejects its None default advertises omission even though it cannot "
+            "construct an instance from that default. Static typing permits the omitted call."
+        ),
+        remediation=(
+            "Make the rejected input required and non-nullable. Keep deliberate optional state nullable; "
+            "no wrapper, interface, or alternate constructor is needed."
+        ),
+        category=RuleCategory.ARCHITECTURE,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Requires a PEP604 nullable parameter with a literal None default and immediate explicit rejection in an undecorated synchronous __init__ body.",
+            "Only a first executable `if parameter is None: raise ...` or `assert parameter is not None` is checked; docstrings and simple assignments preparing a raised error are allowed. Compound guards, later validation, fallbacks, and required nullable inputs are excluded.",
+            "An assertion expresses rejection in normal assertions-enabled execution; Python -O can remove it. No autofix changes a public constructor signature or error type.",
+            "Tests, generated code, decorated classes, and constructors with decorators are excluded. Nullable state that is stored or handled is valid.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="rejected-constructor-default",
+                title="The constructor immediately rejects its advertised default",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/service.py", _REJECTED),),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="required-constructor-input",
+                title="The signature requires the input that construction needs",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/service.py", _REJECTED.replace("Store | None = None", "Store")),),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.generated or context.tree is None or is_test_path(context.path):
+            return []
+        findings: list[Diagnostic] = []
+        for owner in context.nodes(ast.ClassDef):
+            if owner.decorator_list:
+                continue
+            for method in owner.body:
+                if not isinstance(method, ast.FunctionDef) or method.name != "__init__" or method.decorator_list:
+                    continue
+                parameter = _rejected_default(method)
+                if parameter is None:
+                    continue
+                findings.append(
+                    Diagnostic(
+                        path=context.path,
+                        line=parameter.lineno,
+                        col=parameter.col_offset + 1,
+                        code=self.code,
+                        severity=Severity.WARNING,
+                        message=f"Constructor input `{parameter.arg}` defaults to None but immediately rejects it; make this input required and non-nullable instead of adding an abstraction.",
+                    )
+                )
+        return findings
+
+
+def _rejected_default(method: ast.FunctionDef) -> ast.arg | None:
+    rejected = _immediately_rejected_parameter(method)
+    if rejected is None:
+        return None
+    positional = (*method.args.posonlyargs, *method.args.args)
+    defaulted = positional[-len(method.args.defaults) :] if method.args.defaults else ()
+    defaults = (
+        *zip(defaulted, method.args.defaults, strict=True),
+        *zip(method.args.kwonlyargs, method.args.kw_defaults, strict=True),
+    )
+    for parameter, default in defaults:
+        if parameter.arg != rejected or (positional and parameter is positional[0]):
+            continue
+        if (
+            not isinstance(default, ast.Constant)
+            or default.value is not None
+            or parameter.annotation is None
+            or not _is_nullable_union(parameter.annotation)
+        ):
+            continue
+        return parameter
+    return None
+
+
+def _immediately_rejected_parameter(method: ast.FunctionDef) -> str | None:
+    body = method.body
+    if (
+        body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+    ):
+        body = body[1:]
+    if not body:
+        return None
+    first = body[0]
+    if (
+        isinstance(first, ast.If)
+        and isinstance(first.body[-1], ast.Raise)
+        and all(isinstance(statement, (ast.Assign, ast.AnnAssign)) for statement in first.body[:-1])
+    ):
+        condition, operator = first.test, ast.Is
+    elif isinstance(first, ast.Assert):
+        condition, operator = first.test, ast.IsNot
+    else:
+        return None
+    if not isinstance(condition, ast.Compare) or len(condition.ops) != 1 or not isinstance(condition.ops[0], operator):
+        return None
+    left, right = condition.left, condition.comparators[0]
+    for name, absent in ((left, right), (right, left)):
+        if isinstance(name, ast.Name) and isinstance(absent, ast.Constant) and absent.value is None:
+            return name.id
+    return None
+
+
+def _is_nullable_union(annotation: ast.expr) -> bool:
+    if not isinstance(annotation, ast.BinOp) or not isinstance(annotation.op, ast.BitOr):
+        return False
+    return _is_none_union_member(annotation.left) or _is_none_union_member(annotation.right)
+
+
+def _is_none_union_member(annotation: ast.expr) -> bool:
+    if isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
+        return _is_none_union_member(annotation.left) or _is_none_union_member(annotation.right)
+    return isinstance(annotation, ast.Constant) and annotation.value is None

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.1}/src/sarj_python_lint/rules/no_database_programmability.py

@@ -41,7 +41,7 @@ class NoDatabaseProgrammability(Rule):
         default_level=Severity.ERROR,
         summary="Keep stored SQL functions and triggers out of embedded SQL.",
         rationale="SQL hidden in Python can bypass migration-only architecture rules. Procedural fault fixtures require extra database objects and cleanup when a declarative constraint suffices.",
-        remediation="Use declarative constraints or explicit transactional application behavior, including in test fixtures. Use an exact SARJ470 suppression for an approved compatibility exception.",
+        remediation="Prefer declarative constraints or explicit transactional application behavior where equivalent, including in test fixtures. Preserve transaction atomicity and database-enforced integrity; use an exact SARJ470 suppression for an approved database-owned invariant or compatibility exception.",
         category=RuleCategory.ARCHITECTURE,
         autofix=AutofixPolicy.NONE,
         limitations=(
@@ -92,7 +92,7 @@ class NoDatabaseProgrammability(Rule):
                     col=node.col_offset + 1,
                     code=self.code,
                     severity=Severity.ERROR,
-                    message="Stored SQL functions and triggers are prohibited by project architecture, including in test fixtures; use a declarative constraint or explicit transactional application code.",
+                    message="Project architecture prefers declarative constraints or explicit transactional application behavior, including in test fixtures. Preserve atomicity and database-enforced integrity; use an exact SARJ470 suppression for an approved database-owned invariant or compatibility exception.",
                 )
             )
         return sorted(diagnostics, key=lambda item: (item.line, item.col))

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.1}/src/sarj_python_lint/rules/no_injected_module_loader.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import ast
+from itertools import chain
 from pathlib import PurePosixPath
 from typing import TYPE_CHECKING, ClassVar, final, override
 
@@ -45,13 +46,14 @@ class NoInjectedModuleLoader(Rule):
     code = "SARJ471"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         default_level=Severity.WARNING,
-        summary="Keep Python module loaders out of application parameter defaults.",
-        rationale="Exposing Python's import machinery as an injectable dependency expands the callable contract and hides the concrete imported API behind a generic loader.",
-        remediation="Use a normal or lazy import inside the implementation; pass the concrete configuration, object, or domain factory when callers need a real dependency boundary.",
+        summary="Avoid a generic module-loader parameter used only to import one fixed module.",
+        rationale="When every direct use imports the same literal module, a generic importer can be unnecessary customization rather than a domain dependency. Dynamic plugin/import APIs legitimately need import hooks.",
+        remediation="Consider owning the fixed import inside the implementation when import-hook substitution is unnecessary. Preserve intentional import hooks and plugin APIs; do not add wrapper factories or Protocols just to silence this advisory.",
         category=RuleCategory.ARCHITECTURE,
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Flags defaults resolving to importlib.import_module, importlib.__import__, or builtins.__import__, including stable module-level import and single-assignment aliases and unshadowed __import__.",
+            "Every body reference to the parameter must be a direct call with one identical literal module name. Dynamic names, multiple module names, forwarding, returned/captured hooks, rebinding, unpacking and unused defaults are excluded.",
             "Tests, test support, and generated code are excluded. Required loader parameters, application loaders, wrapper lambdas, alias chains, comprehensions, and imports local to enclosing scopes are not inferred.",
             "Conservatively skips shadowed or rebound names, wildcard-import files, reassigned loader attributes, conflicting conditional or relative imports, and exception or pattern captures of importer roots, symbols or assignment aliases. Identical repeated importer imports remain valid. A relevant-name capture in an unrelated local scope can cause a false negative because capture checks are file-wide.",
             "Assignment aliases require one module binding and precede use by line and column. Defaults use their enclosing evaluation scope: earlier statements in the nearest executing class body can shadow loaders; methods and nested classes do not close over class attributes. Enclosing function body bindings remain conservative exclusions, but a function's parameters do not shadow its own defaults. Relevant global declarations and walrus writes exclude sensitive importer names. Compound class statements can cause conservative omissions. Dynamic namespace mutation is not inferred. No autofix: changing arguments or import placement can alter API and initialization behavior.",
@@ -110,7 +112,8 @@ class NoInjectedModuleLoader(Rule):
                     and (aliases[default.id].lineno, aliases[default.id].col_offset)
                     < (function.lineno, function.col_offset)
                 )
-                if not (direct or aliased) or _shadowed(default, function, context):
+                module_name = _fixed_module_name(context, function, argument.arg)
+                if not (direct or aliased) or _shadowed(default, function, context) or module_name is None:
                     continue
                 findings.append(
                     Diagnostic(
@@ -118,13 +121,43 @@ class NoInjectedModuleLoader(Rule):
                         line=argument.lineno,
                         col=argument.col_offset + 1,
                         code=self.code,
-                        message=f"Parameter `{argument.arg}` exposes Python's module loader; import directly or pass a concrete domain dependency.",
+                        message=(
+                            f"Parameter `{argument.arg}` exposes a generic module loader but only imports "
+                            f"`{module_name}`; consider an internal import unless this import hook is intentional."
+                        ),
                         severity=Severity.WARNING,
                     )
                 )
         return sorted(findings, key=lambda finding: (finding.line, finding.col))
 
 
+def _fixed_module_name(
+    context: PythonFileContext, function: ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda, name: str
+) -> str | None:
+    body = [function.body] if isinstance(function, ast.Lambda) else function.body
+    module_names: set[str] = set()
+    for reference in chain.from_iterable(ast.walk(statement) for statement in body):
+        if not isinstance(reference, ast.Name) or reference.id != name:
+            continue
+        call = context.parents.get(reference)
+        if not isinstance(reference.ctx, ast.Load) or not isinstance(call, ast.Call) or call.func is not reference:
+            return None
+        if (
+            call.keywords
+            or len(call.args) != 1
+            or not isinstance(call.args[0], ast.Constant)
+            or not isinstance(call.args[0].value, str)
+        ):
+            return None
+        parent = context.parents.get(call)
+        while parent is not None and parent is not function:
+            if isinstance(parent, _LEXICAL_SCOPES):
+                return None
+            parent = context.parents.get(parent)
+        module_names.add(call.args[0].value)
+    return next(iter(module_names)) if len(module_names) == 1 else None
+
+
 def _ambiguous_loader_bindings(context: PythonFileContext, aliases: Mapping[str, ast.stmt]) -> bool:
     if any(alias.name == "*" for node in context.nodes(ast.ImportFrom) for alias in node.names):
         return True

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.1}/src/sarj_python_lint/rules/no_nullable_dependency_fallback.py

@@ -66,7 +66,7 @@ class NoNullableDependencyFallback(Rule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Warns for None-defaulted function parameters with a fallback used as a callable or a proven application-settings fallback; genuine absent state is allowed.",
-            "Constructors remain owned by SARJ095 and SARJ468. Decorated functions, tests, generated code, nested scope captures, non-callable object fallbacks, and interprocedural forwarding are excluded.",
+            "Constructor settings fallbacks remain owned by SARJ095; constructor nullability alone is not a defect. Decorated functions, tests, generated code, nested scope captures, non-callable object fallbacks, and interprocedural forwarding are excluded.",
             "Callable use through a local assignment, annotation or None guard requires at most one body binding for that name and a call after the binding statement completes. Rebinding, deletion, imports, definitions, pattern or exception captures, global/nonlocal declarations and nested-scope bindings conservatively exclude that inference; direct inline calls remain independent. Settings provenance also excludes enclosing bindings and names written by a function declaring them global, while read-only global declarations remain valid.",
             "No autofix: removing explicit None acceptance changes the callable contract, and moving a fallback can change initialization timing or error handling.",
         ),

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.1}/src/sarj_python_lint/rules/no_unused_underscored_keyword_parameter.py

@@ -39,7 +39,8 @@ class NoUnusedUnderscoredKeywordParameter(Rule):
         ),
         remediation=(
             "Remove the unused keyword-only parameter and update callers together. If an external contract requires "
-            "the input, preserve its required spelling and use a narrow, reasoned unused-argument suppression."
+            "the input, preserve its required spelling and use a narrow, reasoned unused-argument suppression. "
+            "Do not erase a precise callback signature with **kwargs or add dummy reads to silence this warning."
         ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
@@ -48,7 +49,7 @@ class NoUnusedUnderscoredKeywordParameter(Rule):
             "Decorated functions other than unshadowed builtin staticmethod/classmethod, inherited methods, and intentional stubs are excluded.",
             "Any reference within the body counts as use, including nested scopes; shadowing and reassignment can produce false negatives.",
             "Functions accessing locals, vars, eval, or exec through recognized builtin bindings are excluded.",
-            "Call sites, lambda parameters, unknown dynamic reflection, and cross-module callback contracts are not resolved.",
+            "Callables referenced as values are excluded because their external keyword contract is unknown. Lambda parameters, unknown dynamic reflection, and cross-module callback contracts are not resolved.",
             "Generated and vendored files are excluded; test source is checked.",
         ),
         examples=(
@@ -103,7 +104,12 @@ def _unused_parameters(
     context: PythonFileContext, function: ast.FunctionDef | ast.AsyncFunctionDef
 ) -> tuple[ast.arg, ...]:
     candidates = [argument for argument in function.args.kwonlyargs if argument.arg.startswith("_")]
-    if not candidates or _has_contract(context, function) or _is_stub(function):
+    if (
+        not candidates
+        or _has_contract(context, function)
+        or _is_stub(function)
+        or _escapes_as_callback(context, function)
+    ):
         return ()
     body = list(chain.from_iterable(ast.walk(statement) for statement in function.body))
     if _reads_dynamic_locals(context, function, body):
@@ -174,3 +180,15 @@ def _reads_dynamic_locals(
         )
         for node in body
     )
+
+
+def _escapes_as_callback(context: PythonFileContext, function: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    for reference in context.nodes(ast.Name, ast.Attribute):
+        if (isinstance(reference, ast.Name) and reference.id != function.name) or (
+            isinstance(reference, ast.Attribute) and reference.attr != function.name
+        ):
+            continue
+        parent = context.parents.get(reference)
+        if isinstance(reference.ctx, ast.Load) and not (isinstance(parent, ast.Call) and parent.func is reference):
+            return True
+    return False

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.1}/src/sarj_python_lint/rules/no_unused_value_marker.py

@@ -46,6 +46,7 @@ class NoUnusedValueMarker(Rule):
             "Plain and annotated assignments whose standalone target is `_` are reported, including chained assignments.",
             "Formal-parameter references are reported too, including positional, keyword-only, and variadic parameters.",
             "Unpacking placeholders, loop targets, wildcard imports, and underscore-prefixed names are excluded.",
+            "A binding read in the same enclosing scope is not a discard. Reads in nested scopes conservatively preserve it, even when shadowing cannot be resolved.",
             "Generated and vendored files are excluded.",
         ),
         examples=(
@@ -148,7 +149,9 @@ class NoUnusedValueMarker(Rule):
         markers = [
             node
             for node in context.nodes(ast.AST)
-            if isinstance(node, (ast.Assign, ast.AnnAssign)) and _is_unused_value_marker(node)
+            if isinstance(node, (ast.Assign, ast.AnnAssign))
+            and _is_unused_value_marker(node)
+            and not _scope_reads_marker(context, node)
         ]
         if not markers:
             return []
@@ -173,3 +176,14 @@ def _is_unused_value_marker(node: ast.Assign | ast.AnnAssign) -> bool:
     if isinstance(node, ast.AnnAssign):
         return node.value is not None and isinstance(node.target, ast.Name) and node.target.id == "_"
     return any(isinstance(target, ast.Name) and target.id == "_" for target in node.targets)
+
+
+def _scope_reads_marker(context: PythonFileContext, marker: ast.Assign | ast.AnnAssign) -> bool:
+    scope: ast.AST = marker
+    while (parent := context.parents.get(scope)) is not None:
+        scope = parent
+        if isinstance(scope, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | ast.Module):
+            break
+    return any(
+        isinstance(node, ast.Name) and node.id == "_" and isinstance(node.ctx, ast.Load) for node in ast.walk(scope)
+    )

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.1}/src/sarj_python_lint/rules/prefer_match_type_dispatch.py

@@ -101,7 +101,7 @@ class PreferMatchTypeDispatch(Rule):
         limitations=(
             "General dispatch requires three or more adjacent, unguarded `isinstance` branches over the same simple name. Two arms are checked only for an exact `ast.Name.id` / `ast.Attribute.attr` projection followed by a None-returning fallback.",
             "A terminating sibling prefix may precede a two-arm if/elif tail whose bodies can fall through. Preserve nested checks inside case bodies rather than moving them into case guards.",
-            "The checked types must be unshadowed builtins, unshadowed module-local classes, or proven stdlib ast classes; unresolved imports, runtime type groups, repeated type references, generated files, and non-terminating sibling checks are excluded.",
+            "The checked types must be unshadowed builtins, undecorated module-local classes without an explicit metaclass, or proven stdlib ast classes; unresolved imports, runtime type groups, repeated type references, generated files, and non-terminating sibling checks are excluded.",
             "Nested attribute-validation guards are excluded: converting them to keyword class patterns can turn attribute errors into match fallthrough, and an imported isinstance operand may be a runtime tuple rather than a class.",
             "A terminal-looking context-manager body does not prove a sibling branch terminates: exceptions can be suppressed. An unconditional return or raise after the context manager remains eligible.",
             "Declared support for Python before 3.10 suppresses this recommendation when proven by the nearest project metadata or exact installed-distribution ownership. Missing or ambiguous target metadata retains advisory behavior; it does not prove a modern target.",
@@ -288,19 +288,27 @@ class PreferMatchTypeDispatch(Rule):
 
 
 def _unshadowed_module_classes(tree: ast.Module, all_nodes: tuple[ast.AST, ...]) -> frozenset[str]:
-    classes = [statement.name for statement in tree.body if isinstance(statement, ast.ClassDef)]
-    rebound = {
-        candidate.id
-        for candidate in all_nodes
-        if isinstance(candidate, ast.Name) and isinstance(candidate.ctx, (ast.Store, ast.Del))
-    }
-    rebound.update(candidate.arg for candidate in all_nodes if isinstance(candidate, ast.arg))
-    rebound.update(
-        candidate.name
-        for candidate in all_nodes
-        if isinstance(candidate, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))
-        and (not isinstance(candidate, ast.ClassDef) or candidate not in tree.body)
-    )
+    classes = [
+        statement.name
+        for statement in tree.body
+        if isinstance(statement, ast.ClassDef)
+        and not statement.decorator_list
+        and not any(keyword.arg in {"metaclass", None} for keyword in statement.keywords)
+    ]
+    rebound: set[str] = set()
+    for node in all_nodes:
+        match node:
+            case (
+                ast.Name(id=name, ctx=ast.Store() | ast.Del())
+                | ast.arg(arg=name)
+                | ast.FunctionDef(name=name)
+                | ast.AsyncFunctionDef(name=name)
+            ):
+                rebound.add(name)
+            case ast.ClassDef(name=name) if node not in tree.body:
+                rebound.add(name)
+            case _:
+                pass
     _add_module_import_bindings(tree, rebound)
     return frozenset(name for name in classes if classes.count(name) == 1 and name not in rebound)
 

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.1}/src/sarj_python_lint/rules/prefer_pytest_fixture_injection.py

@@ -51,21 +51,26 @@ class PreferPytestFixtureInjection(Rule):
         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."
+            "fixture dependency, per-test caching, and fixture overrides, even when the helper already "
+            "centralizes allocation. This preference does not establish a resource leak."
         ),
         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."
+            "Request one function-scoped fixture visible to the test. Declare required setup ordering as "
+            "fixture dependencies and preserve initial pool state and cleanup ownership. An unopened "
+            "allocation fixture should return the pool without opening or closing it when application "
+            "lifespan owns that lifecycle. Use yield teardown only 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.",
+            "Only unshadowed runtime imports from a uniquely resolved conftest in the test's ancestor directories are followed under conventional pytest discovery.",
             "Helpers must be undecorated synchronous functions with no formal inputs and one direct return of an imported psycopg_pool pool constructor.",
+            "Async pools require an explicit literal open=False, no unpacked arguments, and no calls inside constructor arguments; opened or dynamically configured async pools need lifecycle-specific fixture design.",
             "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.",
+            "Command-line conftest discovery overrides and external pytest plugin registrations are not inferred.",
         ),
         examples=(
             RuleExample(
@@ -84,6 +89,50 @@ class PreferPytestFixtureInjection(Rule):
                 expected_count=1,
                 public=True,
             ),
+            RuleExample(
+                example_id="manual-pool-with-application-lifespan",
+                scenario="application-lifecycle",
+                title="Application-owned lifecycle still uses a fixture dependency",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/conftest.py", _SUPPORT_SOURCE.replace("ConnectionPool", "AsyncConnectionPool")
+                    ),
+                    ExampleFile.python(
+                        "tests/test_app.py",
+                        "from tests.conftest import pool\n\n"
+                        "async def test_app():\n    resource = pool()\n    app = Application(resource)\n"
+                        "    async with lifespan(app):\n        assert not resource.closed\n"
+                        "    assert resource.closed\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_app.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="allocation-fixture-keeps-application-lifespan",
+                scenario="application-lifecycle",
+                title="An unopened fixture leaves open and close ownership with the application",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/conftest.py",
+                        "import pytest\nfrom psycopg_pool import AsyncConnectionPool\n\n"
+                        "@pytest.fixture\ndef pool() -> AsyncConnectionPool[object]:\n"
+                        "    return AsyncConnectionPool[object](open=False)\n",
+                    ),
+                    ExampleFile.python(
+                        "tests/test_app.py",
+                        "async def test_app(pool):\n    app = Application(pool)\n    assert pool.closed\n"
+                        "    async with lifespan(app):\n        assert not pool.closed\n"
+                        "    assert pool.closed\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_app.py"),
+                expected_count=0,
+                public=True,
+            ),
             RuleExample(
                 example_id="injected-generic-pool",
                 title="A test requests its shared resource",
@@ -145,8 +194,10 @@ class PreferPytestFixtureInjection(Rule):
                         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."
+                            "function-scoped fixture by parameter for caching and overrides; declare required "
+                            "setup dependencies and preserve initial pool state and cleanup ownership; leave "
+                            "open/close with application lifespan when it owns them; keep factories for variants "
+                            "or fresh instances."
                         ),
                         severity=Severity.WARNING,
                     )
@@ -171,7 +222,9 @@ def _resource_helpers(context: PythonFileContext) -> frozenset[str]:
         )
         module = (
             context.session.local_source.read_module(target)
-            if target is not None and target.name == "conftest.py"
+            if (
+                target is not None and target.name == "conftest.py" and target.parent in context.path.absolute().parents
+            )
             else None
         )
         if module is not None and _is_resource_helper(module, reference.symbol):
@@ -214,15 +267,30 @@ def _is_resource_helper(module: LocalModule, symbol: str) -> bool:
     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
+    allocation = body[0].value
+    constructor = allocation.func
     if isinstance(constructor, ast.Subscript):
         constructor = constructor.value
     root = _root_name(constructor)
+    qualified = module.runtime_imports.resolved_qualified_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
+        and qualified in _POOL_CONSTRUCTORS
+        and (qualified != "psycopg_pool.AsyncConnectionPool" or _unopened_async_allocation(allocation))
+    )
+
+
+def _unopened_async_allocation(allocation: ast.Call) -> bool:
+    return (
+        not any(isinstance(argument, ast.Starred) for argument in allocation.args)
+        and all(keyword.arg is not None for keyword in allocation.keywords)
+        and any(
+            keyword.arg == "open" and isinstance(keyword.value, ast.Constant) and keyword.value.value is False
+            for keyword in allocation.keywords
+        )
+        and not any(isinstance(node, ast.Call) for argument in _arguments(allocation) for node in ast.walk(argument))
     )