sarj-python-lint 1.14.0__tar.gz → 1.14.2__tar.gz

{sarj_python_lint-1.14.0 → sarj_python_lint-1.14.2}/PKG-INFO

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

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

{sarj_python_lint-1.14.0 → sarj_python_lint-1.14.2}/src/sarj_python_lint/rules/_registry.py

@@ -88,6 +88,7 @@ from sarj_python_lint.rules.no_unique_violation_message_match import (
     NoUniqueViolationMessageMatch,
 )
 from sarj_python_lint.rules.no_unnecessary_docstring import NoUnnecessaryDocstring
+from sarj_python_lint.rules.no_unused_underscored_keyword_parameter import NoUnusedUnderscoredKeywordParameter
 from sarj_python_lint.rules.no_unused_value_marker import NoUnusedValueMarker
 from sarj_python_lint.rules.no_vague_suppression_description import (
     NoVagueSuppressionDescription,
@@ -306,6 +307,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoTypedDocSections.id: NoTypedDocSections,
         NoUnnecessaryDocstring.id: NoUnnecessaryDocstring,
         NoUnusedValueMarker.id: NoUnusedValueMarker,
+        NoUnusedUnderscoredKeywordParameter.id: NoUnusedUnderscoredKeywordParameter,
         PreferNominalIdTypes.id: PreferNominalIdTypes,
         NoAnyMappingTypes.id: NoAnyMappingTypes,
         NoUniqueViolationMessageMatch.id: NoUniqueViolationMessageMatch,

{sarj_python_lint-1.14.0 → sarj_python_lint-1.14.2}/src/sarj_python_lint/rules/no_nullable_dependency_fallback.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import ast
+from collections import Counter
 from dataclasses import dataclass
 from pathlib import PurePosixPath
 from typing import TYPE_CHECKING, ClassVar, final, override
@@ -48,7 +49,7 @@ _FALLBACK_VALUES = 2
 @dataclass(frozen=True, slots=True)
 class _ScopeUsage:
     parents: dict[ast.AST, ast.AST]
-    called: set[str]
+    calls: dict[str, list[ast.Call]]
 
 
 @final
@@ -66,6 +67,7 @@ class NoNullableDependencyFallback(Rule):
         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.",
+            "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 and proven settings fallbacks remain independent.",
             "No autofix: removing explicit None acceptance changes the callable contract, and moving a fallback can change initialization timing or error handling.",
         ),
         examples=(
@@ -163,6 +165,8 @@ def _hidden_dependencies(
         guard = _guarded_fallback(statement, candidates)
         bindings = LocalBindingCollector()
         bindings.visit(statement)
+        bindings.names.update(name for node in _scope_nodes(statement) for name in _binding_names(node))
+        bindings.names.update(node.target.id for node in ast.walk(statement) if isinstance(node, ast.NamedExpr))
         # 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)
@@ -177,7 +181,7 @@ def _hidden_dependencies(
         )
         if guard is not None:
             name, value = guard
-            if name in usage.called or _is_settings_fallback(value, resolver, shadowed):
+            if _called_after(name, statement, usage) or _is_settings_fallback(value, resolver, shadowed):
                 hidden.add(name)
         candidates.difference_update(bindings.names)
     return hidden
@@ -186,8 +190,41 @@ def _hidden_dependencies(
 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)
+    bindings = Counter(
+        name for statement in function.body for node in ast.walk(statement) for name in _binding_names(node)
+    )
+    calls: dict[str, list[ast.Call]] = {}
+    for node in nodes:
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and bindings[node.func.id] <= 1:
+            calls.setdefault(node.func.id, []).append(node)
+    return _ScopeUsage(parents=parents, calls=calls)
+
+
+def _called_after(name: str, binding: ast.stmt, usage: _ScopeUsage) -> bool:
+    end = (binding.end_lineno or binding.lineno, binding.end_col_offset or binding.col_offset)
+    return any((call.lineno, call.col_offset) > end for call in usage.calls.get(name, ()))
+
+
+def _binding_names(node: ast.AST) -> Iterator[str]:
+    match node:
+        case (
+            ast.Name(id=name, ctx=(ast.Store() | ast.Del()))
+            | ast.arg(arg=name)
+            | ast.FunctionDef(name=name)
+            | ast.AsyncFunctionDef(name=name)
+            | ast.ClassDef(name=name)
+            | ast.ExceptHandler(name=str() as name)
+            | ast.MatchAs(name=str() as name)
+            | ast.MatchStar(name=str() as name)
+            | ast.MatchMapping(rest=str() as name)
+        ):
+            yield name
+        case ast.alias(name=imported, asname=alias):
+            yield alias or imported.partition(".")[0]
+        case ast.Global(names=names) | ast.Nonlocal(names=names):
+            yield from names
+        case _:
+            return
 
 
 def _expression_dependencies(
@@ -270,7 +307,10 @@ 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
+    match parent:
+        case (
+            ast.Assign(targets=[ast.Name(id=name)], value=value) | ast.AnnAssign(target=ast.Name(id=name), value=value)
+        ) if value is node:
+            return _called_after(name, parent, usage)
+        case _:
+            return False

sarj_python_lint-1.14.2/src/sarj_python_lint/rules/no_unused_underscored_keyword_parameter.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import ast
+from itertools import chain
+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,
+    is_suppressed,
+)
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+@final
+class NoUnusedUnderscoredKeywordParameter(Rule):
+    id = "no-unused-underscored-keyword-parameter"
+    code = "SARJ475"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Remove unused underscore-prefixed keyword-only parameters instead of hiding them from lint.",
+        rationale=(
+            "A keyword-only parameter requires callers to use its declared name. Prefixing an unused input with an "
+            "underscore silences unused-argument lint while retaining an input whose value has no effect. Removing "
+            "the dead input and its callers keeps the callable's interface honest."
+        ),
+        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."
+        ),
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only underscore-prefixed keyword-only declarations are checked; positional and variadic callback slots are excluded.",
+            "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.",
+            "Generated and vendored files are excluded; test source is checked.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="discarded-keyword-input",
+                title="An ignored keyword input is kept just to silence unused-argument lint",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/sink.py", "def emit(*, _email=None):\n    return 'ready'\n"),),
+                focus_path=PurePosixPath("app/sink.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="removed-keyword-input",
+                title="The callable exposes only inputs it uses",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/sink.py", "def emit():\n    return 'ready'\n"),),
+                focus_path=PurePosixPath("app/sink.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.generated or "_" not in context.source or context.tree is None:
+            return []
+        findings: list[Diagnostic] = []
+        for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
+            for argument in _unused_parameters(context, function):
+                if is_suppressed(context.source_lines, argument.lineno, self.code):
+                    continue
+                findings.append(
+                    Diagnostic(
+                        path=context.path,
+                        line=argument.lineno,
+                        col=argument.col_offset + 1,
+                        code=self.code,
+                        severity=Severity.WARNING,
+                        message=(
+                            f"keyword-only parameter `{argument.arg}` is never referenced; remove the unused input "
+                            "and its callers instead of hiding it from unused-argument lint"
+                        ),
+                    )
+                )
+        return sorted(findings, key=lambda item: (item.line, item.col))
+
+
+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):
+        return ()
+    body = list(chain.from_iterable(ast.walk(statement) for statement in function.body))
+    if _reads_dynamic_locals(context, body):
+        return ()
+    references = {node.id for node in body if isinstance(node, ast.Name)}
+    return tuple(argument for argument in candidates if argument.arg not in references)
+
+
+def _has_contract(context: PythonFileContext, function: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    parent = context.parents.get(function)
+    while parent is not None and not isinstance(
+        parent, ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef | ast.Module
+    ):
+        parent = context.parents.get(parent)
+    if isinstance(parent, ast.ClassDef) and parent.bases:
+        return True
+    return any(
+        not (
+            isinstance(decorator, ast.Name)
+            and decorator.id in {"staticmethod", "classmethod"}
+            and context.imports.builtin_is_unshadowed(decorator.id)
+        )
+        for decorator in function.decorator_list
+    )
+
+
+def _is_stub(function: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    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)
+    ):
+        body = body[1:]
+    if len(body) != 1:
+        return False
+    match body[0]:
+        case ast.Pass() | ast.Return(value=None) | ast.Return(value=ast.Constant(value=None)):
+            return True
+        case ast.Expr(value=ast.Constant(value=value)):
+            return value is Ellipsis
+        case ast.Raise(exc=exception):
+            if isinstance(exception, ast.Call):
+                exception = exception.func
+            return isinstance(exception, ast.Name) and exception.id == "NotImplementedError"
+        case _:
+            return False
+
+
+def _reads_dynamic_locals(context: PythonFileContext, body: list[ast.AST]) -> bool:
+    return any(
+        isinstance(node, ast.expr)
+        and (
+            (
+                isinstance(node, ast.Name)
+                and node.id in {"locals", "vars", "eval", "exec"}
+                and context.module_imports.builtin_is_unshadowed(node.id)
+            )
+            or context.module_imports.resolved_symbol(node, sources=frozenset({"builtins"}))
+            in {"locals", "vars", "eval", "exec"}
+        )
+        for node in body
+    )