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

{sarj_python_lint-0.86.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.86.0 → sarj_python_lint-0.87.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 0.86.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/
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.14
 Requires-Dist: packaging==26.3
-Requires-Dist: ruff>=0.16.7
+Requires-Dist: ruff>=0.16.8
 Requires-Dist: sqlglot==30.18.0
 Requires-Dist: typer==0.27.2
 Description-Content-Type: text/markdown

{sarj_python_lint-0.86.0 → sarj_python_lint-0.87.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.86.0"
+version = "0.87.1"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
@@ -15,7 +15,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Quality Assurance",
 ]
-dependencies = ["packaging==26.3", "ruff>=0.16.7", "sqlglot==30.18.0", "typer==0.27.2"]
+dependencies = ["packaging==26.3", "ruff>=0.16.8", "sqlglot==30.18.0", "typer==0.27.2"]
 
 [project.scripts]
 sarj-python-lint = "sarj_python_lint.__main__:main"
@@ -31,8 +31,8 @@ Issues = "https://github.com/sarj-ai/code-standards/issues"
 [dependency-groups]
 dev = [
   "pytest>=9.1.1",
-  "ruff>=0.16.7",
-  "basedpyright>=1.39.10",
+  "ruff>=0.16.8",
+  "basedpyright>=1.40.1",
 ]
 
 [build-system]

{sarj_python_lint-0.86.0 → sarj_python_lint-0.87.1}/src/sarj_python_lint/rules/_project_index.py

@@ -162,6 +162,47 @@ class ProjectIndexSet:
             consumers.update(_unit_constructor_consumers(candidate, candidate.tree, target))
         return frozenset(consumers)
 
+    def direct_subclasses(self, unit: SourceUnit, name: str) -> frozenset[tuple[Path, str]]:
+        if unit.module is None:
+            return frozenset()
+        target = SymbolRef(unit.module, name)
+        return frozenset(
+            (candidate.path, node.name)
+            for candidate in self._units.values()
+            if candidate.tree is not None and name in candidate.source
+            for node in candidate.tree.body
+            if isinstance(node, ast.ClassDef)
+            and any(_direct_base_symbol(candidate, base) == target for base in node.bases)
+        )
+
+    def typed_class_consumers(self, unit: SourceUnit, name: str) -> frozenset[tuple[Path, str]]:
+        if unit.module is None:
+            return frozenset()
+        target = SymbolRef(unit.module, name)
+        return frozenset(
+            (candidate.path, owner.name)
+            for candidate in self._units.values()
+            if candidate.tree is not None and name in candidate.source
+            for owner in candidate.tree.body
+            if isinstance(owner, ast.ClassDef) and _class_has_typed_dependency(candidate, owner, target)
+        )
+
+    def test_mock_specs(self, unit: SourceUnit, name: str) -> frozenset[Path]:
+        if unit.module is None:
+            return frozenset()
+        target = SymbolRef(unit.module, name)
+        return frozenset(
+            candidate.path
+            for candidate in self._units.values()
+            if candidate.tree is not None
+            and name in candidate.source
+            and any(
+                _is_mock_spec_for(candidate, call, target)
+                for call in ast.walk(candidate.tree)
+                if isinstance(call, ast.Call)
+            )
+        )
+
     def class_inherits_from(self, unit: SourceUnit, name: str, qualified_bases: frozenset[str]) -> bool:
         if unit.module is None:
             return False
@@ -213,6 +254,9 @@ def _is_index_candidate(source: str, matched_classes: set[str]) -> bool:
     return (
         "NewType(" in source
         or "class " in source
+        or "spec=" in source
+        or "spec_set=" in source
+        or "create_autospec(" in source
         or ("match " in source and "str(" in source)
         or any(f"class {name}" in source for name in matched_classes)
     )
@@ -223,6 +267,9 @@ def _module_name(path: Path, roots: Sequence[Path]) -> str | None:
     root = next((candidate for candidate in roots if resolved == candidate or candidate in resolved.parents), None)
     if root is not None:
         try:
+            project_module = _project_module_name(resolved, root)
+            if project_module is not None:
+                return project_module
             package_dir = _outer_package_directory(resolved, root)
         except OSError:
             return None
@@ -233,6 +280,23 @@ def _module_name(path: Path, roots: Sequence[Path]) -> str | None:
     return _package_module_name(path)
 
 
+def _project_module_name(resolved: Path, root: Path) -> str | None:
+    # PEP 420 namespace directories do not have __init__.py. The closest
+    # Python project boundary preserves their complete importable path.
+    project = next(
+        (ancestor for ancestor in resolved.parents if (ancestor / "pyproject.toml").is_file()),
+        None,
+    )
+    if project is None or not (project == root or root in project.parents):
+        return None
+    relative = resolved.relative_to(project)
+    parts = relative.parts[1:] if relative.parts[0] == "src" else relative.parts
+    if not parts:
+        return None
+    suffix = parts[:-1] if parts[-1] == "__init__.py" else (*parts[:-1], Path(parts[-1]).stem)
+    return ".".join(suffix) or None
+
+
 def _package_module_name(path: Path) -> str | None:
     parts: list[str] = []
     parent = path.parent
@@ -324,6 +388,21 @@ def _resolve(unit: SourceUnit, expression: ast.expr) -> SymbolRef | None:
     return None
 
 
+def _direct_base_symbol(unit: SourceUnit, expression: ast.expr) -> SymbolRef | None:
+    resolved = _resolve(unit, expression)
+    if resolved is not None or not isinstance(expression, ast.Name) or unit.tree is None:
+        return resolved
+    # Test support modules need not be packages. Absolute imports still prove
+    # the base identity even when the file itself has no importable module name.
+    for statement in _module_import_statements(unit.tree):
+        if not isinstance(statement, ast.ImportFrom) or statement.level or statement.module is None:
+            continue
+        for alias in statement.names:
+            if (alias.asname or alias.name) == expression.id:
+                return SymbolRef(statement.module, alias.name)
+    return None
+
+
 def _collect_unit_symbols(
     units: Mapping[Path, SourceUnit], classes: dict[SymbolRef, ClassSummary], nominals: dict[str, set[SymbolRef]]
 ) -> None:
@@ -458,6 +537,75 @@ def _unit_constructor_consumers(
             yield (candidate.path, owner.name)
 
 
+def _class_has_typed_dependency(unit: SourceUnit, owner: ast.ClassDef, target: SymbolRef) -> bool:
+    for statement in owner.body:
+        if isinstance(statement, ast.AnnAssign) and _annotation_contains_symbol(unit, statement.annotation, target):
+            return True
+        if not isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        parameters = (*statement.args.posonlyargs, *statement.args.args, *statement.args.kwonlyargs)
+        if any(
+            parameter.arg not in {"self", "cls"} and _annotation_contains_symbol(unit, parameter.annotation, target)
+            for parameter in parameters
+        ):
+            return True
+    return False
+
+
+def _is_mock_spec_for(unit: SourceUnit, call: ast.Call, target: SymbolRef) -> bool:
+    mock_name = _mock_function_name(unit, call.func)
+    if mock_name is None:
+        return False
+    return any(
+        keyword.arg in {"spec", "spec_set"} and _direct_base_symbol(unit, keyword.value) == target
+        for keyword in call.keywords
+    ) or (mock_name == "create_autospec" and bool(call.args) and _direct_base_symbol(unit, call.args[0]) == target)
+
+
+def _mock_function_name(unit: SourceUnit, function: ast.expr) -> str | None:
+    if isinstance(function, ast.Name):
+        return _imported_mock_name(unit, function.id)
+    if not isinstance(function, ast.Attribute) or not isinstance(function.value, ast.Name):
+        return None
+    return _module_mock_name(unit, function.value.id, function.attr)
+
+
+def _imported_mock_name(unit: SourceUnit, name: str) -> str | None:
+    imported = _direct_import_symbol(unit, name)
+    if imported is None or imported.module != "unittest.mock":
+        return None
+    return imported.name if imported.name in {"Mock", "MagicMock", "AsyncMock", "create_autospec"} else None
+
+
+def _module_mock_name(unit: SourceUnit, module_name: str, method_name: str) -> str | None:
+    imported = _direct_import_symbol(unit, module_name)
+    if imported not in {SymbolRef("unittest", "mock"), SymbolRef("unittest.mock", "")}:
+        return None
+    return method_name if method_name in {"Mock", "MagicMock", "AsyncMock", "create_autospec"} else None
+
+
+def _direct_import_symbol(unit: SourceUnit, name: str) -> SymbolRef | None:
+    imported = unit.imports.get(name)
+    if imported is not None or unit.tree is None:
+        return imported
+    for statement in _module_import_statements(unit.tree):
+        if (matched := _absolute_import_symbol(statement, name)) is not None:
+            return matched
+    return None
+
+
+def _absolute_import_symbol(statement: ast.stmt, name: str) -> SymbolRef | None:
+    if isinstance(statement, ast.ImportFrom) and statement.level == 0 and statement.module is not None:
+        for alias in statement.names:
+            if (alias.asname or alias.name) == name:
+                return SymbolRef(statement.module, alias.name)
+    if isinstance(statement, ast.Import):
+        for alias in statement.names:
+            if (alias.asname or alias.name.partition(".")[0]) == name:
+                return SymbolRef(alias.name if alias.asname else alias.name.partition(".")[0], "")
+    return None
+
+
 def _annotation_contains_symbol(unit: SourceUnit, annotation: ast.expr | None, target: SymbolRef) -> bool:
     if annotation is None:
         return False

{sarj_python_lint-0.86.0 → sarj_python_lint-0.87.1}/src/sarj_python_lint/rules/no_any_mapping_types.py

@@ -57,7 +57,8 @@ class NoAnyMappingTypes(Rule):
             ),
             (
                 "Unique unconditional module-level PEP 695 and explicit TypeAlias chains are resolved with cycle "
-                "guards; generic, imported, conditional, rebound, and ambiguous aliases are excluded."
+                "guards. Plain module assignments are checked only when they directly define an Any-valued mapping "
+                "used in a module-level annotation; imported, conditional, rebound, and ambiguous aliases are excluded."
             ),
             "Generated and vendored sources are excluded; exact local suppressions remain auditable.",
         ),
@@ -108,7 +109,8 @@ class NoAnyMappingTypes(Rule):
         lines = source.splitlines()
         findings: list[Diagnostic] = []
         seen: set[tuple[int, int]] = set()
-        for expression, owner in _type_expressions(tree, imports, parents, scope_cache):
+        expressions = [*_type_expressions(tree, imports, parents, scope_cache), *_implicit_mapping_aliases(tree)]
+        for expression, owner in expressions:
             for mapping, location in _unshadowed_any_mappings(expression, owner, semantics, parents, scope_cache):
                 key = (location.lineno, location.col_offset)
                 if key in seen or is_suppressed(lines, location.lineno, self.code):
@@ -129,6 +131,55 @@ class NoAnyMappingTypes(Rule):
         return sorted(findings, key=lambda finding: (finding.line, finding.col))
 
 
+def _implicit_mapping_aliases(tree: ast.Module) -> list[tuple[ast.expr, ast.Assign]]:
+    bindings = [scope_bound_names([statement]) for statement in tree.body]
+    aliases: list[tuple[ast.expr, ast.Assign]] = []
+    for statement in tree.body:
+        if not isinstance(statement, ast.Assign) or len(statement.targets) != 1:
+            continue
+        target = statement.targets[0]
+        if not isinstance(target, ast.Name) or not isinstance(statement.value, ast.Subscript):
+            continue
+        if sum(target.id in names for names in bindings) != 1:
+            continue
+        if _used_in_module_annotation(tree, target.id):
+            aliases.append((statement.value, statement))
+    return aliases
+
+
+def _used_in_module_annotation(tree: ast.Module, name: str) -> bool:
+    return any(
+        _annotation_contains_name(annotation, name)
+        for statement in tree.body
+        for annotation in _module_statement_annotations(statement, name)
+    )
+
+
+def _module_statement_annotations(statement: ast.stmt, alias_name: str) -> list[ast.expr]:
+    if isinstance(statement, ast.AnnAssign):
+        return [statement.annotation]
+    if not isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return []
+    arguments = statement.args
+    parameters = (*arguments.posonlyargs, *arguments.args, *arguments.kwonlyargs)
+    if any(argument.arg == alias_name for argument in parameters):
+        return []
+    annotations = [argument.annotation for argument in parameters if argument.annotation is not None]
+    if statement.returns is not None:
+        annotations.append(statement.returns)
+    return annotations
+
+
+def _annotation_contains_name(annotation: ast.expr, name: str) -> bool:
+    parsed = annotation
+    if isinstance(annotation, ast.Constant) and isinstance(annotation.value, str):
+        try:
+            parsed = ast.parse(annotation.value, mode="eval").body
+        except SyntaxError:
+            return False
+    return any(isinstance(node, ast.Name) and node.id == name for node in ast.walk(parsed))
+
+
 def _unshadowed_any_mappings(
     expression: ast.expr,
     owner: ast.AST,

{sarj_python_lint-0.86.0 → sarj_python_lint-0.87.1}/src/sarj_python_lint/rules/no_delete_statement.py

@@ -93,7 +93,7 @@ class NoDeleteStatement(Rule):
                 line=node.lineno,
                 col=node.col_offset + 1,
                 code=self.code,
-                severity=Severity.WARNING,
+                severity=Severity.ERROR,
                 message=(
                     "`del` introduces mutation or hidden lifetime behavior — construct the desired value "
                     "immutably, or add an exact SARJ442 suppression explaining why deletion is required."

{sarj_python_lint-0.86.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