sarj-python-lint 0.87.0__tar.gz → 0.87.1__tar.gz

{sarj_python_lint-0.87.0 → sarj_python_lint-0.87.1}/.gitignore

@@ -32,9 +32,10 @@ Thumbs.db
 .zed/
 *.swp
 
-# Claude Code local state (shared settings.json is tracked)
-.claude/*
-!.claude/settings.json
+.claude/
+apps/docs/.wrangler/
+apps/docs/.dev.vars*
+!apps/docs/.dev.vars.example
 .worktrees/
 .sarj-private-refs.toml
 .sarj-standards-rollout.toml

{sarj_python_lint-0.87.0 → sarj_python_lint-0.87.1}/PKG-INFO

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

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

{sarj_python_lint-0.87.0 → sarj_python_lint-0.87.1}/src/sarj_python_lint/rules/no_unused_value_marker.py

@@ -32,7 +32,8 @@ class NoUnusedValueMarker(Rule):
         summary="Do not use standalone assignments to `_` to discard values.",
         rationale=(
             "A standalone `_ = value` assignment adds a binding without clarifying intent. A side-effecting call can "
-            "be invoked directly, while an unused parameter should be addressed at its declaration."
+            "be invoked directly. Pure references to formal parameters are excluded because callback and protocol "
+            "signatures may require names that Ruff otherwise reports as unused."
         ),
         remediation=(
             "Invoke calls directly instead of assigning their result to `_`. Remove or rename locally owned unused "
@@ -43,14 +44,15 @@ class NoUnusedValueMarker(Rule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Plain and annotated assignments whose standalone target is `_` are reported, including chained assignments.",
+            "Pure name or tuple references to the enclosing function's unchanged parameters are excluded.",
             "Unpacking placeholders, loop targets, wildcard imports, and underscore-prefixed names are excluded.",
             "Generated and vendored files are excluded.",
         ),
         examples=(
             RuleExample(
-                example_id="unused-parameter-marker",
-                title="Do not manufacture a use for interface parameters",
-                outcome=ExampleOutcome.MATCH,
+                example_id="callback-parameter-marker",
+                title="A callback keeps its required parameter names",
+                outcome=ExampleOutcome.NO_MATCH,
                 files=(
                     ExampleFile.python(
                         "app/adapter.py",
@@ -58,6 +60,15 @@ class NoUnusedValueMarker(Rule):
                     ),
                 ),
                 focus_path=PurePosixPath("app/adapter.py"),
+                expected_count=0,
+                public=False,
+            ),
+            RuleExample(
+                example_id="discarded-nonparameter-value",
+                title="A standalone discard binding is unnecessary",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/adapter.py", "value = 1\n_ = value\n"),),
+                focus_path=PurePosixPath("app/adapter.py"),
                 expected_count=1,
                 public=True,
             ),
@@ -116,6 +127,18 @@ class NoUnusedValueMarker(Rule):
         if tree is None:
             return []
         source_lines = source.splitlines()
+        markers = [
+            node
+            for node in ast.walk(tree)
+            if isinstance(node, (ast.Assign, ast.AnnAssign)) and _is_unused_value_marker(node)
+        ]
+        if not markers:
+            return []
+        parents = (
+            {child: parent for parent in ast.walk(tree) for child in ast.iter_child_nodes(parent)}
+            if any(isinstance(node, ast.Assign) and isinstance(node.value, (ast.Name, ast.Tuple)) for node in markers)
+            else {}
+        )
         return [
             Diagnostic(
                 path=path,
@@ -128,10 +151,8 @@ class NoUnusedValueMarker(Rule):
                     "directly or address unused values at their declaration."
                 ),
             )
-            for node in ast.walk(tree)
-            if isinstance(node, (ast.Assign, ast.AnnAssign))
-            and _is_unused_value_marker(node)
-            and not is_suppressed(source_lines, node.lineno, self.code)
+            for node in markers
+            if not _is_pure_parameter_marker(node, parents) and not is_suppressed(source_lines, node.lineno, self.code)
         ]
 
 
@@ -139,3 +160,42 @@ 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 _is_pure_parameter_marker(
+    node: ast.Assign | ast.AnnAssign,
+    parents: dict[ast.AST, ast.AST],
+) -> bool:
+    if not isinstance(node, ast.Assign) or len(node.targets) != 1:
+        return False
+    if not isinstance(node.targets[0], ast.Name) or node.targets[0].id != "_":
+        return False
+    names = _marker_reference_names(node.value)
+    if names is None:
+        return False
+    function = _enclosing_function(node, parents)
+    if function is None:
+        return False
+    parameters = {argument.arg for argument in ast.walk(function.args) if isinstance(argument, ast.arg)}
+    return names <= parameters and not any(
+        isinstance(child, ast.Name) and isinstance(child.ctx, ast.Store) and child.id in names
+        for child in ast.walk(function)
+    )
+
+
+def _marker_reference_names(value: ast.expr) -> set[str] | None:
+    values = value.elts if isinstance(value, ast.Tuple) else [value]
+    if not values or not all(isinstance(item, ast.Name) for item in values):
+        return None
+    return {item.id for item in values if isinstance(item, ast.Name)}
+
+
+def _enclosing_function(
+    node: ast.AST, parents: dict[ast.AST, ast.AST]
+) -> ast.FunctionDef | ast.AsyncFunctionDef | None:
+    current = node
+    while current in parents:
+        current = parents[current]
+        if isinstance(current, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            return current
+    return None