sarj-python-lint 1.8.4__tar.gz → 1.9.0__tar.gz

{sarj_python_lint-1.8.4 → sarj_python_lint-1.9.0}/PKG-INFO

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

{sarj_python_lint-1.8.4 → sarj_python_lint-1.9.0}/pyproject.toml

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

{sarj_python_lint-1.8.4 → sarj_python_lint-1.9.0}/src/sarj_python_lint/rules/_registry.py

@@ -60,6 +60,7 @@ from sarj_python_lint.rules.no_hidden_constructor_fallback import (
 )
 from sarj_python_lint.rules.no_invalid_argument_name_suppression import NoInvalidArgumentNameSuppression
 from sarj_python_lint.rules.no_nested_pydantic_field_validator import NoNestedPydanticFieldValidator
+from sarj_python_lint.rules.no_nullable_dependency_fallback import NoNullableDependencyFallback
 from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
 from sarj_python_lint.rules.no_positional_psycopg_row_escape import NoPositionalPsycopgRowEscape
 from sarj_python_lint.rules.no_psycopg_execution_outside_injected_owner import (
@@ -254,6 +255,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoRandomUuidInSql.id: NoRandomUuidInSql,
         NoRedundantModuleAliasExports.id: NoRedundantModuleAliasExports,
         NoHiddenConstructorFallback.id: NoHiddenConstructorFallback,
+        NoNullableDependencyFallback.id: NoNullableDependencyFallback,
         NoFileLevelEscapeHatchSuppression.id: NoFileLevelEscapeHatchSuppression,
         NoInvalidArgumentNameSuppression.id: NoInvalidArgumentNameSuppression,
         NoFastapiOnEvent.id: NoFastapiOnEvent,

{sarj_python_lint-1.8.4 → sarj_python_lint-1.9.0}/src/sarj_python_lint/rules/no_hidden_constructor_fallback.py

@@ -74,7 +74,7 @@ class _CanonicalSymbol(NamedTuple):
 
 
 @dataclass(slots=True)
-class _ConstructorFacts:
+class RuntimeConfigFacts:
     modules: dict[Path, ast.Module] = field(default_factory=dict)
     composition_calls: dict[tuple[Path, str, str], bool] = field(default_factory=dict)
     canonical_symbols: dict[tuple[Path, str, str], _CanonicalSymbol] = field(default_factory=dict)
@@ -82,7 +82,7 @@ class _ConstructorFacts:
 
 @final
 class NoHiddenConstructorFallback(Rule):
-    _constructor_facts: _ConstructorFacts | None = None
+    _constructor_facts: RuntimeConfigFacts | None = None
     id = "no-hidden-constructor-fallback"
     code = "SARJ095"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
@@ -155,7 +155,7 @@ class NoHiddenConstructorFallback(Rule):
     @override
     def prepare_session(self, session: AnalysisSession) -> None:
         super().prepare_session(session)
-        self._constructor_facts = _ConstructorFacts()
+        self._constructor_facts = RuntimeConfigFacts()
 
     @override
     def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
@@ -169,8 +169,8 @@ class NoHiddenConstructorFallback(Rule):
         first_party = context.session.first_party
         facts = self._constructor_facts if self._analysis_session is context.session else None
         if facts is None:
-            facts = _ConstructorFacts()
-        resolver = _RuntimeConfigResolver(path, tree, first_party, facts)
+            facts = RuntimeConfigFacts()
+        resolver = RuntimeConfigResolver(path, tree, first_party, facts)
         diagnostics: list[Diagnostic] = []
 
         def collect_hidden_constructors() -> None:
@@ -210,7 +210,7 @@ def _is_descriptor(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
 
 
 def _default_scope(owner: ast.ClassDef, init: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
-    collector = _LocalBindingCollector()
+    collector = LocalBindingCollector()
     for statement in owner.body:
         if statement is init:
             break
@@ -220,7 +220,7 @@ def _default_scope(owner: ast.ClassDef, init: ast.FunctionDef | ast.AsyncFunctio
 
 def _hidden_parameters(
     init: ast.FunctionDef | ast.AsyncFunctionDef,
-    resolver: _RuntimeConfigResolver,
+    resolver: RuntimeConfigResolver,
     default_shadowed: set[str] | None = None,
 ) -> list[_HiddenParameter]:
     positional = (*init.args.posonlyargs, *init.args.args)
@@ -247,7 +247,7 @@ def _hidden_parameters(
     # Python decides every local binding for the whole function before it
     # executes. Seed the resolver with that complete scope so a branch-local
     # `settings = ...` cannot be mistaken for the imported settings object.
-    shadowed = set(_scope_bindings(init))
+    shadowed = set(scope_bindings(init))
     receiver = positional[0].arg if positional else None
     for statement in init.body:
         available = candidates.keys() - rebound
@@ -263,7 +263,7 @@ def _hidden_parameters(
 def _statement_fallbacks(
     statement: ast.stmt,
     candidates: set[str],
-    resolver: _RuntimeConfigResolver,
+    resolver: RuntimeConfigResolver,
     shadowed: set[str],
     receiver: str | None,
 ) -> dict[str, bool]:
@@ -291,7 +291,7 @@ def _statement_fallbacks(
 def _expression_fallbacks(
     expression: ast.expr,
     candidates: set[str],
-    resolver: _RuntimeConfigResolver,
+    resolver: RuntimeConfigResolver,
     shadowed: set[str],
 ) -> dict[str, bool]:
     if isinstance(expression, ast.BoolOp) and isinstance(expression.op, ast.Or):
@@ -386,13 +386,13 @@ def _is_fallback_target(expression: ast.expr, parameter: str, receiver: str | No
 
 
 @final
-class _RuntimeConfigResolver:
+class RuntimeConfigResolver:
     def __init__(
         self,
         path: Path,
         tree: ast.Module,
         first_party: FirstPartyFacts,
-        facts: _ConstructorFacts,
+        facts: RuntimeConfigFacts,
     ) -> None:
         self._path = path
         self._tree = tree
@@ -629,7 +629,7 @@ def _module_path(module: str, root: Path | None) -> Path | None:
     return next((candidate for candidate in candidates if candidate.is_file()), None)
 
 
-def _read_module(path: Path, facts: _ConstructorFacts) -> ast.Module:
+def _read_module(path: Path, facts: RuntimeConfigFacts) -> ast.Module:
     cached = facts.modules.get(path)
     if cached is not None:
         return cached
@@ -650,7 +650,7 @@ def _has_composition_call(
     path: Path,
     class_name: str,
     first_party: FirstPartyFacts,
-    facts: _ConstructorFacts,
+    facts: RuntimeConfigFacts,
 ) -> bool:
     root = distribution_root(path, facts=first_party)
     module = _module_name(path, root)
@@ -663,7 +663,7 @@ def _distribution_calls_class(
     root: Path,
     target_module: str,
     class_name: str,
-    facts: _ConstructorFacts,
+    facts: RuntimeConfigFacts,
 ) -> bool:
     key = (root, target_module, class_name)
     if key in facts.composition_calls:
@@ -677,7 +677,7 @@ def _distribution_calls_class_uncached(
     root: Path,
     target_module: str,
     class_name: str,
-    facts: _ConstructorFacts,
+    facts: RuntimeConfigFacts,
 ) -> bool:
     skip_directories = _SCAN_SKIP_PARTS | _MIGRATION_PARTS | {"test", "tests"}
     for directory, directory_names, file_names in os.walk(root):
@@ -692,7 +692,7 @@ def _distribution_calls_class_uncached(
 
 
 def _candidate_calls_class(
-    candidate: Path, root: Path, target_module: str, class_name: str, facts: _ConstructorFacts
+    candidate: Path, root: Path, target_module: str, class_name: str, facts: RuntimeConfigFacts
 ) -> bool:
     if is_test_path(candidate):
         return False
@@ -721,7 +721,7 @@ def _module_calls_class(
     target_module: str,
     *,
     class_name: str,
-    facts: _ConstructorFacts,
+    facts: RuntimeConfigFacts,
 ) -> bool:
     for node, shadowed in _calls_with_shadowing(tree):
         parts = _attribute_parts(node.func)
@@ -746,7 +746,7 @@ def _canonical_symbol(
     root: Path,
     module: str,
     symbol: str,
-    facts: _ConstructorFacts,
+    facts: RuntimeConfigFacts,
 ) -> _CanonicalSymbol:
     key = (root, module, symbol)
     cached = facts.canonical_symbols.get(key)
@@ -762,7 +762,7 @@ def _canonical_symbol_inner(
     module: str,
     symbol: str,
     seen: frozenset[tuple[str, str]],
-    facts: _ConstructorFacts,
+    facts: RuntimeConfigFacts,
 ) -> _CanonicalSymbol:
     key = (module, symbol)
     if key in seen:
@@ -793,7 +793,7 @@ def _calls_with_shadowing(
             for outer in outer_nodes:
                 yield from _calls_with_shadowing(outer, shadowed, nested_scope_base)
             lexical_parent = nested_scope_base if nested_scope_base is not None else shadowed
-            yield from _calls_with_shadowing(body, lexical_parent | _scope_bindings(node))
+            yield from _calls_with_shadowing(body, lexical_parent | scope_bindings(node))
             return
         case ast.FunctionDef() | ast.AsyncFunctionDef():
             yield from _function_calls(node, shadowed, nested_scope_base)
@@ -814,8 +814,8 @@ def _calls_with_shadowing(
         yield from _calls_with_shadowing(child, shadowed, nested_scope_base)
 
 
-def _scope_bindings(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda) -> frozenset[str]:
-    collector = _LocalBindingCollector()
+def scope_bindings(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda) -> frozenset[str]:
+    collector = LocalBindingCollector()
     for argument in (*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs):
         collector.names.add(argument.arg)
     if node.args.vararg is not None:
@@ -829,13 +829,13 @@ def _scope_bindings(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda) -
 
 
 def _class_bindings(node: ast.ClassDef) -> frozenset[str]:
-    collector = _LocalBindingCollector()
+    collector = LocalBindingCollector()
     for statement in node.body:
         collector.visit(statement)
     return frozenset(collector.names)
 
 
-class _LocalBindingCollector(ast.NodeVisitor):
+class LocalBindingCollector(ast.NodeVisitor):
     def __init__(self) -> None:
         self.names: set[str] = set()
         self.globals: set[str] = set()
@@ -928,7 +928,7 @@ def _function_calls(
     for outer in outer_nodes:
         yield from _calls_with_shadowing(outer, shadowed, nested_scope_base)
     lexical_parent = nested_scope_base if nested_scope_base is not None else shadowed
-    local_shadowed = lexical_parent | _scope_bindings(node)
+    local_shadowed = lexical_parent | scope_bindings(node)
     for statement in node.body:
         yield from _calls_with_shadowing(statement, local_shadowed)
     return

sarj_python_lint-1.9.0/src/sarj_python_lint/rules/no_nullable_dependency_fallback.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+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, is_test_support_path
+from sarj_python_lint.rules.no_hidden_constructor_fallback import (
+    LocalBindingCollector,
+    RuntimeConfigFacts,
+    RuntimeConfigResolver,
+    scope_bindings,
+)
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from sarj_python_lint._analysis_session import AnalysisSession
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_SCOPES = (
+    ast.FunctionDef,
+    ast.AsyncFunctionDef,
+    ast.ClassDef,
+    ast.Lambda,
+    ast.ListComp,
+    ast.SetComp,
+    ast.DictComp,
+    ast.GeneratorExp,
+)
+_FALLBACK_VALUES = 2
+
+
+@dataclass(frozen=True, slots=True)
+class _ScopeUsage:
+    parents: dict[ast.AST, ast.AST]
+    called: set[str]
+
+
+@final
+class NoNullableDependencyFallback(Rule):
+    _facts: RuntimeConfigFacts | None = None
+    id = "no-nullable-dependency-fallback"
+    code = "SARJ469"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Require concrete function dependencies instead of resolving a None default inside the function.",
+        rationale="A None dependency silently selects another implementation or ambient configuration, hiding wiring mistakes and adding unnecessary branches.",
+        remediation="Resolve the dependency at the call site and pass it explicitly; a concrete callable default is also valid when its lifetime is appropriate.",
+        category=RuleCategory.ARCHITECTURE,
+        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.",
+            "No autofix: removing explicit None acceptance changes the callable contract, and moving a fallback can change initialization timing or error handling.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="nullable-factory",
+                title="Omission silently selects an implementation",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/service.py",
+                        "def run(factory: Factory | None = None):\n    return (factory or DefaultFactory)()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="concrete-factory",
+                title="Caller supplies a concrete dependency",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/service.py", "def run(factory: Factory):\n    return factory()\n"),),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def prepare_session(self, session: AnalysisSession) -> None:
+        super().prepare_session(session)
+        self._facts = RuntimeConfigFacts()
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if (
+            context.tree is None
+            or context.generated
+            or is_test_path(context.path)
+            or is_test_support_path(context.path)
+        ):
+            return []
+        facts = self._facts if self._analysis_session is context.session else None
+        resolver = RuntimeConfigResolver(
+            context.path, context.tree, context.session.first_party, facts or RuntimeConfigFacts()
+        )
+        findings: list[Diagnostic] = []
+        for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
+            if function.name == "__init__" or function.decorator_list:
+                continue
+            parameters = _none_default_parameters(function.args)
+            if not parameters:
+                continue
+            hidden = _hidden_dependencies(function, parameters, resolver)
+            findings.extend(
+                Diagnostic(
+                    path=context.path,
+                    line=argument.lineno,
+                    col=argument.col_offset + 1,
+                    code=self.code,
+                    message=f"Dependency `{argument.arg}` defaults to None and selects a fallback; pass a concrete dependency from the caller or use a concrete callable default.",
+                    severity=Severity.WARNING,
+                )
+                for argument in parameters.values()
+                if argument.arg in hidden
+            )
+        return sorted(findings, key=lambda finding: (finding.line, finding.col))
+
+
+def _none_default_parameters(arguments: ast.arguments) -> dict[str, ast.arg]:
+    positional = (*arguments.posonlyargs, *arguments.args)
+    defaulted = positional[-len(arguments.defaults) :] if arguments.defaults else ()
+    return {
+        argument.arg: argument
+        for argument, default in (
+            *zip(defaulted, arguments.defaults, strict=True),
+            *zip(arguments.kwonlyargs, arguments.kw_defaults, strict=True),
+        )
+        if _is_none(default)
+    }
+
+
+def _hidden_dependencies(
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    parameters: dict[str, ast.arg],
+    resolver: RuntimeConfigResolver,
+) -> set[str]:
+    usage = _scope_usage(function)
+    candidates = set(parameters)
+    hidden: set[str] = set()
+    shadowed = set(scope_bindings(function))
+    for statement in function.body:
+        guard = _guarded_fallback(statement, candidates)
+        bindings = LocalBindingCollector()
+        bindings.visit(statement)
+        # Branch/loop bindings are conservatively local; do not infer data flow.
+        if not isinstance(statement, (ast.Assign, ast.AnnAssign)) and guard is None:
+            candidates.difference_update(bindings.names)
+        hidden.update(
+            _expression_dependencies(
+                statement,
+                candidates=candidates,
+                resolver=resolver,
+                shadowed=shadowed,
+                usage=usage,
+            )
+        )
+        if guard is not None:
+            name, value = guard
+            if name in usage.called or _is_settings_fallback(value, resolver, shadowed):
+                hidden.add(name)
+        candidates.difference_update(bindings.names)
+    return hidden
+
+
+def _scope_usage(function: ast.FunctionDef | ast.AsyncFunctionDef) -> _ScopeUsage:
+    nodes = [node for statement in function.body for node in _scope_nodes(statement)]
+    parents = {child: node for node in nodes for child in ast.iter_child_nodes(node)}
+    called = {node.func.id for node in nodes if isinstance(node, ast.Call) and isinstance(node.func, ast.Name)}
+    return _ScopeUsage(parents=parents, called=called)
+
+
+def _expression_dependencies(
+    statement: ast.stmt,
+    *,
+    candidates: set[str],
+    resolver: RuntimeConfigResolver,
+    shadowed: set[str],
+    usage: _ScopeUsage,
+) -> set[str]:
+    hidden: set[str] = set()
+    for node in _scope_nodes(statement):
+        fallback = _fallback(node, candidates)
+        if fallback is None:
+            continue
+        name, value = fallback
+        if _is_settings_fallback(value, resolver, shadowed) or _used_as_dependency(node, usage):
+            hidden.add(name)
+    return hidden
+
+
+def _is_settings_fallback(value: ast.expr, resolver: RuntimeConfigResolver, shadowed: set[str]) -> bool:
+    target = value.func if isinstance(value, ast.Call) else value
+    return resolver.is_runtime_config(target, shadowed)
+
+
+def _scope_nodes(statement: ast.AST) -> Iterator[ast.AST]:
+    if isinstance(statement, _SCOPES):
+        return
+    yield statement
+    for child in ast.iter_child_nodes(statement):
+        yield from _scope_nodes(child)
+
+
+def _guarded_fallback(statement: ast.stmt, candidates: set[str]) -> tuple[str, ast.expr] | None:
+    if not isinstance(statement, ast.If) or statement.orelse or len(statement.body) != 1:
+        return None
+    name = _none_guard(statement.test)
+    assignment = statement.body[0]
+    if name not in candidates or not isinstance(assignment, ast.Assign) or len(assignment.targets) != 1:
+        return None
+    target = assignment.targets[0]
+    if isinstance(target, ast.Name) and target.id == name:
+        return name, assignment.value
+    return None
+
+
+def _fallback(node: ast.AST, candidates: set[str]) -> tuple[str, ast.expr] | None:
+    if isinstance(node, ast.BoolOp) and isinstance(node.op, ast.Or) and len(node.values) == _FALLBACK_VALUES:
+        value, fallback = node.values
+        if isinstance(value, ast.Name) and value.id in candidates:
+            return value.id, fallback
+    if isinstance(node, ast.IfExp):
+        name = _none_guard(node.test)
+        value, fallback = node.orelse, node.body
+        if name is None:
+            name = _none_guard(node.test, inverse=True)
+            value, fallback = node.body, node.orelse
+        if name in candidates and isinstance(value, ast.Name) and value.id == name:
+            return name, fallback
+    return None
+
+
+def _none_guard(node: ast.AST, *, inverse: bool = False) -> str | None:
+    if not isinstance(node, ast.Compare) or len(node.ops) != 1 or len(node.comparators) != 1:
+        return None
+    if not isinstance(node.ops[0], ast.IsNot if inverse else ast.Is):
+        return None
+    for value, other in ((node.left, node.comparators[0]), (node.comparators[0], node.left)):
+        if isinstance(value, ast.Name) and _is_none(other):
+            return value.id
+    return None
+
+
+def _is_none(node: ast.AST | None) -> bool:
+    return isinstance(node, ast.Constant) and node.value is None
+
+
+def _used_as_dependency(node: ast.AST, usage: _ScopeUsage) -> bool:
+    parent = usage.parents.get(node)
+    if isinstance(parent, ast.Call) and parent.func is node:
+        return True
+    if isinstance(parent, ast.Assign) and parent.value is node and len(parent.targets) == 1:
+        target = parent.targets[0]
+        return isinstance(target, ast.Name) and target.id in usage.called
+    return False