sarj-python-lint 1.3.0__tar.gz → 1.3.3__tar.gz

{sarj_python_lint-1.3.0 → sarj_python_lint-1.3.3}/PKG-INFO

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

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

sarj_python_lint-1.3.3/src/sarj_python_lint/rules/_set_fields.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING
+
+from sarj_python_lint.rules._ast_index import walk as walk_ast
+from sarj_python_lint.rules._imports import ImportIndex
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._project_index import ClassSummary, ProjectIndexSet, SourceUnit
+
+
+def declared_set_fields(
+    function: ast.FunctionDef | ast.AsyncFunctionDef, project: ProjectIndexSet, context: PythonFileContext
+) -> set[str]:
+    changed = _changed_roots(function)
+    fields: set[str] = set()
+    for argument in (*function.args.posonlyargs, *function.args.args, *function.args.kwonlyargs):
+        if argument.arg in changed or argument.annotation is None:
+            continue
+        summary = _field_class(argument.annotation, project, context)
+        if summary is None:
+            continue
+        owner = project.source_unit(summary.symbol.module)
+        if owner is None or owner.tree is None:
+            continue
+        for name, annotation in summary.fields.items():
+            if _builtin_set_annotation(annotation, owner) and _plain_field(owner, summary.symbol.name, name):
+                fields.add(f"{argument.arg}.{name}")
+    return fields
+
+
+def _field_class(annotation: ast.expr, project: ProjectIndexSet, context: PythonFileContext) -> ClassSummary | None:
+    root = annotation
+    while isinstance(root, ast.Attribute):
+        root = root.value
+    if not isinstance(root, ast.Name) or any(
+        node.id == root.id and isinstance(node.ctx, (ast.Store, ast.Del)) for node in context.nodes(ast.Name)
+    ):
+        return None
+    qualified = context.module_imports.resolved_qualified_name(annotation)
+    unit = project.unit(context.path)
+    if qualified is not None:
+        module, _, name = qualified.rpartition(".")
+        unit = project.source_unit(module)
+        annotation = ast.Name(id=name, ctx=ast.Load())
+    return project.class_for(unit, annotation) if unit is not None else None
+
+
+def _builtin_set_annotation(annotation: ast.expr, unit: SourceUnit) -> bool:
+    if unit.tree is None:
+        return False
+    base = annotation.value if isinstance(annotation, ast.Subscript) else annotation
+    return (
+        isinstance(base, ast.Name)
+        and base.id in {"set", "frozenset"}
+        and ImportIndex.from_tree(unit.tree, module_scope_only=True).builtin_is_unshadowed(base.id)
+    )
+
+
+def _plain_field(unit: SourceUnit, class_name: str, name: str) -> bool:
+    if unit.tree is None:
+        return False
+    owner = next((node for node in unit.tree.body if isinstance(node, ast.ClassDef) and node.name == class_name), None)
+    if owner is None:
+        return False
+    for statement in owner.body:
+        if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)) and statement.name in {
+            name,
+            "__getattribute__",
+            "__getattr__",
+        }:
+            return False
+        if isinstance(statement, ast.Assign) and any(
+            isinstance(target, ast.Name) and target.id in {name, "set", "frozenset"} for target in statement.targets
+        ):
+            return False
+    return True
+
+
+def _changed_roots(function: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
+    changed: set[str] = set()
+    for node in (node for statement in function.body for node in walk_ast(statement)):
+        match node:
+            case ast.Name(id=name, ctx=ast.Store() | ast.Del()):
+                changed.add(name)
+            case ast.Attribute(ctx=ast.Store() | ast.Del()):
+                root = node.value
+                while isinstance(root, ast.Attribute):
+                    root = root.value
+                if isinstance(root, ast.Name):
+                    changed.add(root.id)
+            case ast.Import(names=aliases) | ast.ImportFrom(names=aliases):
+                changed.update(alias.asname or alias.name.split(".")[0] for alias in aliases)
+            case (
+                ast.ExceptHandler(name=str(name))
+                | ast.MatchAs(name=str(name))
+                | ast.MatchStar(name=str(name))
+                | ast.MatchMapping(rest=str(name))
+                | ast.arg(arg=name)
+                | ast.FunctionDef(name=name)
+                | ast.AsyncFunctionDef(name=name)
+                | ast.ClassDef(name=name)
+            ):
+                changed.add(name)
+            case _:
+                pass
+    return changed

{sarj_python_lint-1.3.0 → sarj_python_lint-1.3.3}/src/sarj_python_lint/rules/no_hidden_constructor_fallback.py

@@ -91,7 +91,7 @@ class NoHiddenConstructorFallback(Rule):
         remediation="Require the constructor argument and resolve any default at the composition root or call site.",
         category=RuleCategory.ARCHITECTURE,
         limitations=(
-            "Detection requires a proven local settings provider, an optional parameter defaulting to None, and a first-party composition call.",
+            "Detection requires a proven local settings provider and a first-party composition call; covers None fallbacks and settings attributes captured directly in module-level class constructor defaults.",
             "Tests, generated files, migrations, descriptors, library environment fallbacks, and unconstructed classes are excluded.",
         ),
         examples=(
@@ -186,7 +186,8 @@ class NoHiddenConstructorFallback(Rule):
                 )
                 if init is None or _is_descriptor(init):
                     continue
-                hidden = _hidden_parameters(init, resolver)
+                default_shadowed = _default_scope(class_node, init) if class_node in tree.body else None
+                hidden = _hidden_parameters(init, resolver, default_shadowed)
                 if not hidden or not _has_composition_call(path, class_node.name, first_party, facts):
                     continue
                 diagnostics.append(
@@ -208,23 +209,38 @@ def _is_descriptor(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
     return any(_tail(decorator) in _DESCRIPTOR_DECORATORS for decorator in node.decorator_list)
 
 
+def _default_scope(owner: ast.ClassDef, init: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
+    collector = _LocalBindingCollector()
+    for statement in owner.body:
+        if statement is init:
+            break
+        collector.visit(statement)
+    return collector.names
+
+
 def _hidden_parameters(
     init: ast.FunctionDef | ast.AsyncFunctionDef,
     resolver: _RuntimeConfigResolver,
+    default_shadowed: set[str] | None = None,
 ) -> list[_HiddenParameter]:
     positional = (*init.args.posonlyargs, *init.args.args)
     defaulted_positional = positional[-len(init.args.defaults) :] if init.args.defaults else ()
     positional_defaults = zip(defaulted_positional, init.args.defaults, strict=True)
+    defaults = (*positional_defaults, *zip(init.args.kwonlyargs, init.args.kw_defaults, strict=True))
+    captured = [
+        _HiddenParameter(parameter, uses_boolean_or=False)
+        for parameter, default in defaults
+        if default is not None
+        and default_shadowed is not None
+        and resolver.is_runtime_config(default, default_shadowed)
+    ]
     candidates = {
         parameter.arg: parameter
-        for parameter, default in (
-            *positional_defaults,
-            *zip(init.args.kwonlyargs, init.args.kw_defaults, strict=True),
-        )
+        for parameter, default in defaults
         if isinstance(default, ast.Constant) and default.value is None
     }
     if not candidates:
-        return []
+        return captured
 
     hidden: dict[str, bool] = {}
     rebound: set[str] = set()
@@ -239,7 +255,9 @@ def _hidden_parameters(
             hidden[name] = hidden.get(name, False) or uses_boolean_or
         rebound.update(_directly_bound_names(statement) & candidates.keys())
         shadowed.update(_directly_bound_names(statement))
-    return [_HiddenParameter(parameter, hidden[name]) for name, parameter in candidates.items() if name in hidden]
+    return captured + [
+        _HiddenParameter(parameter, hidden[name]) for name, parameter in candidates.items() if name in hidden
+    ]
 
 
 def _statement_fallbacks(

{sarj_python_lint-1.3.0 → sarj_python_lint-1.3.3}/src/sarj_python_lint/rules/prefer_injected_dependency_over_monkeypatch.py

@@ -57,7 +57,7 @@ class PreferInjectedDependencyOverMonkeypatch(Rule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Only maintained test paths are analyzed; generated files and production helpers are excluded.",
-            "The rule recognizes pytest monkeypatch and statically resolved unittest.mock or pytest-mock patch APIs.",
+            "The rule recognizes pytest monkeypatch fixtures, unambiguous local MonkeyPatch constructors and context handles, and statically resolved unittest.mock or pytest-mock patch APIs.",
             "Environment, mapping, import-path, and working-directory mutations are intentionally allowed.",
             "Untyped handles are recognized only on pytest tests or fixtures; directly parametrized values are excluded.",
             "A nested function that captures a monkeypatch handle from an outer scope is not inferred.",
@@ -109,10 +109,13 @@ class PreferInjectedDependencyOverMonkeypatch(Rule):
             return []
         imports = context.module_imports
         parents = parent_map(tree, index=context.node_index)
+        has_factory = "MonkeyPatch" in context.source and any(
+            _creates_monkeypatch(call, imports) for call in context.nodes(ast.Call)
+        )
         replacements = [
             (call, f"monkeypatch.{_operation(call)}")
             for function in _functions(tree, node_index=context.node_index)
-            for call in _attribute_mutations(function, imports, parents)
+            for call in _attribute_mutations(function, imports, parents, has_factory=has_factory)
         ]
         replacements.extend((call, label) for call, label in _patch_calls(tree, imports, node_index=context.node_index))
         diagnostics = [
@@ -264,9 +267,11 @@ def _attribute_mutations(
     function: ast.FunctionDef | ast.AsyncFunctionDef,
     imports: ImportIndex,
     parents: Mapping[ast.AST, ast.AST],
+    *,
+    has_factory: bool,
 ) -> list[ast.Call]:
     parameters = _parameter_handles(function, imports, parents)
-    if not parameters:
+    if not parameters and not has_factory:
         return []
     nodes = tuple(_lexical_body_nodes(function))
     handles = set(parameters)
@@ -278,11 +283,73 @@ def _attribute_mutations(
         and isinstance(node.func, ast.Attribute)
         and node.func.attr in _ATTRIBUTE_MUTATIONS
         and isinstance(node.func.value, ast.Name)
-        and node.func.value.id in handles
+        and (
+            node.func.value.id in handles
+            or _constructed_reference(
+                node.func.value.id, node, function, nodes=nodes, imports=imports, parents=parents, seen=frozenset()
+            )
+        )
         and not _parameter_rebound_before(node, node.func.value.id, nodes, parameters)
     ]
 
 
+def _creates_monkeypatch(call: ast.Call, imports: ImportIndex) -> bool:
+    callee = call.func
+    if isinstance(callee, ast.Attribute) and callee.attr == "context":
+        callee = callee.value
+    return imports.resolves(callee, sources=_PYTEST, symbol="MonkeyPatch")
+
+
+def _constructed_reference(
+    name: str,
+    use: ast.AST,
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    *,
+    nodes: tuple[ast.AST, ...],
+    imports: ImportIndex,
+    parents: Mapping[ast.AST, ast.AST],
+    seen: frozenset[str],
+) -> bool:
+    if name in seen or name in {arg.arg for arg in _arguments(function.args)}:
+        return False
+    definitions = [node for node in nodes if name in _bound_targets(node)]
+    if len(definitions) != 1 or _position(definitions[0]) >= _position(use):
+        return False
+    definition = definitions[0]
+    value: ast.expr | None = None
+    if isinstance(definition, (ast.Assign, ast.AnnAssign)) and parents.get(definition) is function:
+        value = definition.value
+    elif isinstance(definition, ast.withitem) and _within(use, parents.get(definition), parents):
+        expression = definition.context_expr
+        if (
+            isinstance(expression, ast.Call)
+            and isinstance(expression.func, ast.Attribute)
+            and expression.func.attr == "context"
+        ):
+            value = expression.func.value
+            if imports.resolves(value, sources=_PYTEST, symbol="MonkeyPatch"):
+                value = ast.Call(func=value, args=[], keywords=[])
+    if isinstance(value, ast.Name):
+        return _constructed_reference(
+            value.id, definition, function, nodes=nodes, imports=imports, parents=parents, seen=seen | {name}
+        )
+    return (
+        isinstance(value, ast.Call)
+        and imports.resolves(value.func, sources=_PYTEST, symbol="MonkeyPatch")
+        and not _import_shadowed(value.func, parents, {})
+    )
+
+
+def _within(node: ast.AST, ancestor: ast.AST | None, parents: Mapping[ast.AST, ast.AST]) -> bool:
+    if ancestor is None:
+        return False
+    while (parent := parents.get(node)) is not None:
+        if parent is ancestor:
+            return True
+        node = parent
+    return False
+
+
 def _parameter_handles(
     function: ast.FunctionDef | ast.AsyncFunctionDef,
     imports: ImportIndex,

{sarj_python_lint-1.3.0 → sarj_python_lint-1.3.3}/src/sarj_python_lint/rules/prefer_set_isdisjoint.py

@@ -9,7 +9,7 @@ from sarj_python_lint.rule_base import (
     Diagnostic,
     ExampleFile,
     ExampleOutcome,
-    Rule,
+    ProjectRule,
     RuleCategory,
     RuleDocumentation,
     RuleExample,
@@ -17,6 +17,8 @@ from sarj_python_lint.rule_base import (
     is_suppressed,
 )
 from sarj_python_lint.rules._ast_index import walk as walk_ast
+from sarj_python_lint.rules._project_index import ProjectIndexSet
+from sarj_python_lint.rules._set_fields import declared_set_fields
 
 
 if TYPE_CHECKING:
@@ -45,7 +47,7 @@ _TRACKED_BUILTINS = frozenset(
 
 
 @final
-class PreferSetIsdisjoint(Rule):
+class PreferSetIsdisjoint(ProjectRule):
     id = "prefer-set-isdisjoint"
     code = "SARJ431"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
@@ -56,19 +58,19 @@ class PreferSetIsdisjoint(Rule):
         category=RuleCategory.STYLE,
         autofix=AutofixPolicy.SUGGESTION,
         limitations=(
-            "Built-in set identity must be proven from a literal, comprehension, constructor, or one dominating local assignment.",
-            "For binary `&`, the left operand must be a proven built-in set and the right operand must be a literal, comprehension, built-in iterable constructor, standard no-argument collection view, or proven set; annotations, parameters, attributes, subclasses, branch-merged bindings, stored intersections, and generated files are excluded.",
+            "Set receivers must come from a literal, comprehension, constructor, dominating local assignment, or an unchanged parameter's directly declared first-party set/frozenset field.",
+            "Declared fields rely on the annotated contract. Unknown or union field types, properties, explicit owner/field reassignment, branch-merged bindings, stored intersections, and generated files are excluded. The other operand must be a known iterable.",
             "The suggestion is intentionally not an autofix because short-circuiting may make custom element equality or hashing side effects observable.",
         ),
         examples=(
             RuleExample(
                 example_id="discarded-intersection",
-                title="Set intersection is used only for an emptiness test",
+                title="A declared set field is used only for an overlap test",
                 outcome=ExampleOutcome.MATCH,
                 files=(
                     ExampleFile.python(
                         "app/policy.py",
-                        "allowed = {'read', 'write'}\nrequested = set(scopes)\nif not (allowed & requested):\n    deny()\n",
+                        "class AccessCase:\n    tags: frozenset[str]\n\ndef accepts(case: AccessCase):\n    if case.tags & {'read', 'write'}:\n        allow()\n",
                     ),
                 ),
                 focus_path=PurePosixPath("app/policy.py"),
@@ -102,7 +104,12 @@ class PreferSetIsdisjoint(Rule):
         tree = context.tree
         if tree is None:
             return []
-        scanner = _Scanner(path, context.source_lines, _shadowed_builtins(tree, node_index=context.node_index))
+        project = context.session.project or ProjectIndexSet.single(path, source)
+        fields = {
+            node: declared_set_fields(node, project, context)
+            for node in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef)
+        }
+        scanner = _Scanner(path, context.source_lines, _shadowed_builtins(tree, node_index=context.node_index), fields)
         scanner.scan_body(tree.body, set())
         scanner.diagnostics.sort(key=lambda item: (item.line, item.col))
         return scanner.diagnostics
@@ -110,12 +117,19 @@ class PreferSetIsdisjoint(Rule):
 
 @final
 class _Scanner:
-    def __init__(self, path: Path, source_lines: list[str], shadowed: frozenset[str]) -> None:
+    def __init__(
+        self,
+        path: Path,
+        source_lines: list[str],
+        shadowed: frozenset[str],
+        fields: dict[ast.FunctionDef | ast.AsyncFunctionDef, set[str]],
+    ) -> None:
         self.path = path
         self.source_lines = source_lines
         self.shadowed = shadowed
         self.diagnostics: list[Diagnostic] = []
         self.reported: set[int] = set()
+        self.fields = fields
 
     def scan_body(self, body: list[ast.stmt], exact: set[str]) -> None:
         local = set(exact)
@@ -139,7 +153,9 @@ class _Scanner:
             case ast.Assert(test=test):
                 self._scan_boolean(test, exact)
                 self._scan_embedded(test, exact)
-            case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.ClassDef():
+            case ast.FunctionDef() | ast.AsyncFunctionDef():
+                self.scan_body(statement.body, self.fields.get(statement, set()))
+            case ast.ClassDef():
                 self.scan_body(statement.body, set())
             case ast.For() | ast.AsyncFor():
                 self._scan_embedded(statement.iter, exact)
@@ -292,6 +308,8 @@ def _is_builtin_bool_call(node: ast.expr, shadowed: frozenset[str]) -> bool:
 
 
 def _is_exact_set(node: ast.expr, exact: set[str], shadowed: frozenset[str]) -> bool:
+    if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name):
+        return f"{node.value.id}.{node.attr}" in exact
     if isinstance(node, ast.Set | ast.SetComp):
         return True
     if isinstance(node, ast.Name):

{sarj_python_lint-1.3.0 → sarj_python_lint-1.3.3}/src/sarj_python_lint/rules/prefer_walrus_awaited_none_guard.py

@@ -272,11 +272,11 @@ class _NameUsage(ast.NodeVisitor):
 
     @override
     def visit_Lambda(self, node: ast.Lambda) -> None:
-        _ = node
+        """Skip the deferred lambda body when tracking immediate name usage."""
 
     @override
     def visit_GeneratorExp(self, node: ast.GeneratorExp) -> None:
-        _ = node
+        """Skip the deferred generator body when tracking immediate name usage."""
 
     def visit_Import(self, node: ast.Import) -> None:
         self.rebound |= any((alias.asname or alias.name.split(".", maxsplit=1)[0]) == self.name for alias in node.names)

{sarj_python_lint-1.3.0 → sarj_python_lint-1.3.3}/src/sarj_python_lint/rules/repeated_test_composition.py

@@ -61,7 +61,7 @@ class RepeatedTestComposition(ProjectRule):
             "Requires three sibling tests with equivalent wiring of at least two stored and invoked first-party ABC/Protocol dependencies.",
             "Collaborators must resolve to equivalent fixture parameters or first-party constructor expressions, optionally through unambiguous local aliases.",
             "Requires an unconditional construction followed by a subject method call; dynamic arguments, parametrized tests, constructor validation, multiple instances, mutated dependencies, fixtures, helpers, generated files, and inherited test classes are excluded.",
-            "HTTPX detection requires a managed AsyncClient with an inline ASGITransport and equivalent options except its app.",
+            "HTTPX detection requires a managed AsyncClient with an inline or unchanged local ASGITransport and equivalent options except its app; unambiguous constructor aliases are accepted.",
         ),
         examples=(
             RuleExample(
@@ -159,8 +159,11 @@ def _candidate(
     callee = unalias(node.func, aliases)
     if shadowed(callee, available.parameters | available.blocked):
         return None
-    if context.imports.resolves(node.func, sources=_HTTPX, symbol="AsyncClient"):
-        key = _client_key(context, node) if _unconditional(context, node, function) else None
+    if context.imports.resolves(callee, sources=_HTTPX, symbol="AsyncClient"):
+        blocked = available.parameters | available.blocked
+        changed = changed_before(function, node, aliases)
+        stable = {name: value for name, value in aliases.items() if name not in changed}
+        key = _client_key(context, node, stable, blocked) if _unconditional(context, node, function) else None
         return "httpx.AsyncClient", key
     spec = constructor(context, callee, project)
     if spec is None:
@@ -238,9 +241,9 @@ def _subject_called(context: PythonFileContext, function: Function, call: ast.Ca
     )
 
 
-def _client_key(context: PythonFileContext, call: ast.Call) -> str | None:
-    if not context.imports.resolves(call.func, sources=_HTTPX, symbol="AsyncClient"):
-        return None
+def _client_key(
+    context: PythonFileContext, call: ast.Call, aliases: dict[str, ast.expr], blocked: frozenset[str]
+) -> str | None:
     parent = context.parents.get(call)
     if (
         not isinstance(parent, ast.withitem)
@@ -259,7 +262,7 @@ def _client_key(context: PythonFileContext, call: ast.Call) -> str | None:
                 return None
             options.append((keyword.arg, ast.dump(keyword.value)))
             continue
-        transport_options = _transport_options(context, keyword.value)
+        transport_options = _transport_options(context, unalias(keyword.value, aliases), aliases, blocked)
         if transport_options is None:
             return None
         found_transport = True
@@ -267,10 +270,14 @@ def _client_key(context: PythonFileContext, call: ast.Call) -> str | None:
     return repr(sorted(options)) if found_transport else None
 
 
-def _transport_options(context: PythonFileContext, transport: ast.expr) -> list[tuple[str, str]] | None:
-    if not isinstance(transport, ast.Call) or not context.imports.resolves(
-        transport.func, sources=_HTTPX, symbol="ASGITransport"
-    ):
+def _transport_options(
+    context: PythonFileContext, transport: ast.expr, aliases: dict[str, ast.expr], blocked: frozenset[str]
+) -> list[tuple[str, str]] | None:
+    if not isinstance(transport, ast.Call):
+        return None
+    earlier = {name: value for name, value in aliases.items() if value.lineno < transport.lineno}
+    callee = unalias(transport.func, earlier)
+    if shadowed(callee, blocked) or not context.imports.resolves(callee, sources=_HTTPX, symbol="ASGITransport"):
         return None
     if transport.args or any(option.arg is None for option in transport.keywords):
         return None