sarj-python-lint 1.43.1__tar.gz → 1.44.1__tar.gz

{sarj_python_lint-1.43.1 → sarj_python_lint-1.44.1}/PKG-INFO

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

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

sarj_python_lint-1.44.1/src/sarj_python_lint/rules/_type_guard_symbols.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import ast
+from collections import Counter
+from typing import TYPE_CHECKING
+
+from sarj_python_lint.rules._imports import TYPING_SOURCES
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+_NAMESPACE_IMPORT_CAPABILITIES = frozenset(
+    {"__dict__", "__builtins__", "__getattribute__", "__setattr__", "__delattr__"}
+)
+_NAMESPACE_RETURNING_FUNCTIONS = frozenset({"__lazy_import__"})
+_BUILTIN_NAMESPACE_FUNCTIONS = frozenset(
+    {
+        "__build_class__",
+        "__import__",
+        "__lazy_import__",
+        "abs",
+        "aiter",
+        "all",
+        "anext",
+        "any",
+        "ascii",
+        "bin",
+        "breakpoint",
+        "callable",
+        "chr",
+        "compile",
+        "delattr",
+        "dir",
+        "divmod",
+        "eval",
+        "exec",
+        "format",
+        "getattr",
+        "globals",
+        "hasattr",
+        "hash",
+        "hex",
+        "id",
+        "input",
+        "isinstance",
+        "issubclass",
+        "iter",
+        "len",
+        "locals",
+        "max",
+        "min",
+        "next",
+        "oct",
+        "ord",
+        "pow",
+        "print",
+        "repr",
+        "round",
+        "setattr",
+        "sorted",
+        "sum",
+        "vars",
+    }
+)
+
+
+def builtin_guard_symbol(node: ast.expr | None, imports: ImportIndex, builtin_symbols: frozenset[str]) -> str | None:
+    if node is None:
+        return None
+    symbol = imports.resolved_symbol(node, sources=frozenset({"builtins"}))
+    if symbol in builtin_symbols:
+        return symbol
+    if isinstance(node, ast.Name) and node.id in builtin_symbols and imports.builtin_is_unshadowed(node.id):
+        return node.id
+    return None
+
+
+def unique_guard_function_names(context: PythonFileContext) -> frozenset[str]:
+    if context.tree is None:
+        return frozenset()
+    counts: Counter[str] = Counter()
+    pending: list[ast.AST] = list(context.tree.body)
+    while pending:
+        node = pending.pop()
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            counts[node.name] += 1
+        elif not isinstance(node, (ast.ClassDef, ast.Lambda)):
+            pending.extend(ast.iter_child_nodes(node))
+    return frozenset(name for name, count in counts.items() if count == 1)
+
+
+def guard_symbols_ambiguous(
+    context: PythonFileContext,
+    builtin_symbols: frozenset[str],
+    *,
+    typing_symbols: frozenset[str] = frozenset({"TypeGuard", "TypeIs"}),
+) -> bool:
+    namespace_names = _namespace_import_names(context)
+    if _namespace_escapes(context, namespace_names):
+        return True
+    mutation_targets = (
+        {f"builtins.{symbol}" for symbol in builtin_symbols}
+        | {f"{module}.{symbol}" for module in TYPING_SOURCES for symbol in typing_symbols}
+        | {f"{module}.__class__" for module in TYPING_SOURCES | {"builtins"}}
+    )
+    sensitive_names = (
+        builtin_symbols
+        | namespace_names
+        | {
+            name
+            for name, target in context.module_imports.bindings.items()
+            if target.module in TYPING_SOURCES | {"builtins"}
+            and (target.symbol is None or target.symbol in builtin_symbols | typing_symbols)
+        }
+    )
+    return any(
+        _ambiguous_node(node, context, mutation_targets, sensitive_names)
+        for node in context.nodes(
+            ast.Import,
+            ast.ImportFrom,
+            ast.Attribute,
+            ast.ExceptHandler,
+            ast.MatchAs,
+            ast.MatchStar,
+            ast.MatchMapping,
+            ast.NamedExpr,
+        )
+    )
+
+
+def _namespace_import_names(context: PythonFileContext) -> frozenset[str]:
+    return frozenset(
+        alias.asname or alias.name
+        for node in context.nodes(ast.Import)
+        for alias in node.names
+        if alias.name in TYPING_SOURCES | {"builtins"}
+    )
+
+
+def _namespace_escapes(context: PythonFileContext, namespace_names: frozenset[str]) -> bool:
+    if context.dynamic_namespace or any(node.id == "__builtins__" for node in context.nodes(ast.Name)):
+        return True
+    if any(
+        node.level == 0
+        and node.module in TYPING_SOURCES | {"builtins"}
+        and any(alias.name in _NAMESPACE_IMPORT_CAPABILITIES for alias in node.names)
+        for node in context.nodes(ast.ImportFrom)
+    ):
+        return True
+    if _native_function_escapes(context):
+        return True
+    for name in context.nodes(ast.Name):
+        if name.id not in namespace_names:
+            continue
+        parent = context.parents.get(name)
+        if not isinstance(parent, ast.Attribute) or parent.value is not name or parent.attr == "__dict__":
+            return True
+    return False
+
+
+def _native_function_escapes(context: PythonFileContext) -> bool:
+    function_names = _possible_native_function_names(context)
+    namespace_function_names = _possible_native_function_names(context, symbols=_NAMESPACE_RETURNING_FUNCTIONS)
+    module_names = frozenset(
+        alias.asname or alias.name
+        for node in context.nodes(ast.Import)
+        for alias in node.names
+        if alias.name == "builtins"
+    )
+    for node in context.nodes(ast.Name, ast.Attribute):
+        if isinstance(node, ast.Attribute) and (
+            not isinstance(node.value, ast.Name) or node.attr not in _BUILTIN_NAMESPACE_FUNCTIONS
+        ):
+            continue
+        if not isinstance(node.ctx, ast.Load) or not _possible_native_function(node, function_names, module_names):
+            continue
+        parent = context.parents.get(node)
+        if (
+            not isinstance(parent, ast.Call)
+            or parent.func is not node
+            or _namespace_returning_function(node, namespace_function_names)
+        ):
+            return True
+    return False
+
+
+def _possible_native_function_names(
+    context: PythonFileContext, *, symbols: frozenset[str] = _BUILTIN_NAMESPACE_FUNCTIONS
+) -> frozenset[str]:
+    return symbols | frozenset(
+        alias.asname or alias.name
+        for node in context.nodes(ast.ImportFrom)
+        if node.level == 0 and node.module == "builtins"
+        for alias in node.names
+        if alias.name in symbols
+    )
+
+
+def _namespace_returning_function(node: ast.Name | ast.Attribute, function_names: frozenset[str]) -> bool:
+    if isinstance(node, ast.Name):
+        return node.id in function_names
+    return node.attr in _NAMESPACE_RETURNING_FUNCTIONS
+
+
+def _possible_native_function(
+    node: ast.Name | ast.Attribute,
+    function_names: frozenset[str],
+    module_names: frozenset[str],
+) -> bool:
+    if isinstance(node, ast.Name):
+        return node.id in function_names
+    return (
+        isinstance(node.value, ast.Name) and node.value.id in module_names and node.attr in _BUILTIN_NAMESPACE_FUNCTIONS
+    )
+
+
+def _ambiguous_node(
+    node: ast.AST, context: PythonFileContext, mutation_targets: set[str], sensitive_names: frozenset[str]
+) -> bool:
+    match node:
+        case ast.Import() | ast.ImportFrom():
+            return _ambiguous_import(node, context.module_imports, sensitive_names)
+        case ast.Attribute(ctx=(ast.Store() | ast.Del())):
+            return context.module_imports.resolved_qualified_name(node) in mutation_targets
+        case (
+            ast.ExceptHandler(name=name)
+            | ast.MatchAs(name=name)
+            | ast.MatchStar(name=name)
+            | ast.MatchMapping(rest=name)
+            | ast.NamedExpr(target=ast.Name(id=name))
+        ):
+            return name in sensitive_names
+        case _:
+            return False
+
+
+def _ambiguous_import(node: ast.Import | ast.ImportFrom, imports: ImportIndex, sensitive_names: frozenset[str]) -> bool:
+    if isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names):
+        return True
+    for alias in node.names:
+        name = alias.asname or alias.name.partition(".")[0]
+        if name not in sensitive_names:
+            continue
+        if not _preserves_canonical_import(node, alias, imports):
+            return True
+    return False
+
+
+def _preserves_canonical_import(node: ast.Import | ast.ImportFrom, alias: ast.alias, imports: ImportIndex) -> bool:
+    if isinstance(node, ast.ImportFrom):
+        if node.level:
+            return False
+        module, symbol = node.module, alias.name
+    else:
+        module, symbol = alias.name, None
+    name = alias.asname or alias.name.partition(".")[0]
+    target = imports.bindings.get(name)
+    if target is None:
+        return module == "builtins" and symbol == name
+    return target.module == module and target.symbol == symbol

{sarj_python_lint-1.43.1 → sarj_python_lint-1.44.1}/src/sarj_python_lint/rules/no_contradictory_type_guard.py

@@ -17,7 +17,11 @@ from sarj_python_lint.rule_base import (
     is_suppressed,
 )
 from sarj_python_lint.rules._imports import TYPING_SOURCES
-from sarj_python_lint.rules._type_guard_symbols import builtin_guard_symbol, guard_symbols_ambiguous
+from sarj_python_lint.rules._type_guard_symbols import (
+    builtin_guard_symbol,
+    guard_symbols_ambiguous,
+    unique_guard_function_names,
+)
 
 
 if TYPE_CHECKING:
@@ -33,7 +37,7 @@ _WITNESSES: Final = {
     "str": frozenset({"str"}),
     "bytes": frozenset({"bytes"}),
 }
-_ALL_WITNESSES = frozenset({"int", "bool", "str", "bytes"})
+_ALL_WITNESSES = frozenset({"int", "bool", "str", "bytes", "none"})
 _MAX_INPUT_NODES = 4096
 _BAD = (
     "from typing import TypeGuard\ndef is_text(value: object) -> TypeGuard[str]:\n    return isinstance(value, int)\n"
@@ -47,9 +51,9 @@ class NoContradictoryTypeGuard(Rule):
     code = "SARJ513"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         default_level=Severity.WARNING,
-        summary="Primitive type guards must agree with the isinstance check they return.",
+        summary="Primitive type guards must agree with the builtin predicate they return.",
         rationale=(
-            "A guard annotation does not validate its implementation. Returning an incompatible isinstance "
+            "A guard annotation does not validate its implementation. Returning an incompatible primitive predicate "
             "check makes callers trust the wrong primitive; TypeIs also incorrectly excludes rejected target "
             "values in the false branch."
         ),
@@ -61,12 +65,14 @@ class NoContradictoryTypeGuard(Rule):
         category=RuleCategory.CORRECTNESS,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Checks undecorated, non-generic module functions with one parameter and a single returned direct builtin isinstance call, optionally after a docstring.",
+            "Checks undecorated, non-generic module functions with one parameter and a single returned direct builtin isinstance call, its unary not, or a bool constant, optionally after a docstring.",
             "Guard symbols must resolve to typing or typing_extensions TypeGuard or TypeIs. Targets and checked classes are builtin int, bool, str or bytes; bool is treated as an int subtype.",
-            "Inputs must be object or fully classified plain unions of those primitive types and None. Impossible isinstance tests and compiler-invalid TypeIs target/input relationships are excluded.",
+            "Inputs must be object or fully classified plain unions of those primitive types and None. Direct positive impossible isinstance tests and compiler-invalid TypeIs target/input relationships are excluded.",
             "Input unions are traversed iteratively with a bounded node budget; overly complex annotations are excluded.",
             "Literal and refined targets, aliases, custom classes, float numeric promotion, tuple isinstance tests, helper predicates, nested functions and complex bodies are not inferred.",
             "TypeGuard may intentionally recognize a subset of its target, so TypeGuard[int] with an isinstance bool test remains legal. Visible namespace mutation and ambiguous or shadowed symbols abstain conservatively.",
+            "Constant false remains legal for TypeGuard. Constant true is reported only with a proven incompatible primitive or None input; false TypeIs needs a proven inhabited target. Negated isinstance uses the same finite witness domains.",
+            "Repeated top-level function definition names abstain because overloads can constrain the public input more narrowly than the implementation input.",
             "Generated files are excluded; maintained tests remain checked. No autofix guesses a domain or changes false-branch behavior.",
         ),
         examples=(
@@ -88,6 +94,36 @@ class NoContradictoryTypeGuard(Rule):
                 expected_count=0,
                 public=True,
             ),
+            RuleExample(
+                example_id="constant-true-claims-text",
+                scenario="constant-predicate",
+                title="A constant result does not prove a primitive type",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/guards.py",
+                        "from typing import TypeGuard\ndef is_text(value: object) -> TypeGuard[str]:\n    return True\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/guards.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="constant-false-is-legal-partial-guard",
+                scenario="constant-predicate",
+                title="TypeGuard can intentionally recognize no inputs",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/guards.py",
+                        "from typing import TypeGuard\ndef is_text(value: object) -> TypeGuard[str]:\n    return False\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/guards.py"),
+                expected_count=0,
+                public=True,
+            ),
         ),
     )
     description = documentation.summary
@@ -99,8 +135,9 @@ class NoContradictoryTypeGuard(Rule):
         if context.tree is None or guard_symbols_ambiguous(context, _BUILTINS):
             return []
         findings: list[Diagnostic] = []
+        unique_names = unique_guard_function_names(context)
         for function in context.tree.body:
-            if not isinstance(function, ast.FunctionDef):
+            if not isinstance(function, ast.FunctionDef) or function.name not in unique_names:
                 continue
             statement = _contradictory_return(function, context)
             if statement is None or is_suppressed(context.source_lines, statement.lineno, self.code):
@@ -111,7 +148,7 @@ class NoContradictoryTypeGuard(Rule):
                     statement.lineno,
                     statement.col_offset + 1,
                     self.code,
-                    "This guard's isinstance test contradicts its primitive narrowing promise; align the target "
+                    "This guard's builtin predicate contradicts its primitive narrowing promise; align the target "
                     "and test, preserving TypeIs false-branch behavior and intentional TypeGuard partial predicates.",
                     severity=Severity.WARNING,
                 )
@@ -133,12 +170,11 @@ def _contradictory_return(function: ast.FunctionDef, context: PythonFileContext)
     if target is None or inputs is None or (guard == "TypeIs" and not target <= inputs):
         return None
     statement = _single_return(function)
-    checked_kind = _checked_kind(statement.value, parameter.arg, context) if statement is not None else None
-    checked = _WITNESSES.get(checked_kind) if checked_kind is not None else None
-    if checked is None or not inputs & checked:
+    accepted = _accepted_witnesses(statement.value, parameter.arg, inputs, context) if statement is not None else None
+    if accepted is None:
         return None
-    accepts_wrong = bool((inputs & checked) - target)
-    rejects_target = guard == "TypeIs" and bool((inputs & target) - checked)
+    accepts_wrong = bool(accepted - target)
+    rejects_target = guard == "TypeIs" and bool((inputs & target) - accepted)
     return statement if accepts_wrong or rejects_target else None
 
 
@@ -174,6 +210,7 @@ def _input_witnesses(annotation: ast.expr | None, imports: ImportIndex) -> froze
         if visited > _MAX_INPUT_NODES:
             return None
         if isinstance(member, ast.Constant) and member.value is None:
+            witnesses.add("none")
             continue
         if isinstance(member, ast.BinOp) and isinstance(member.op, ast.BitOr):
             pending.extend((member.left, member.right))
@@ -188,6 +225,20 @@ def _input_witnesses(annotation: ast.expr | None, imports: ImportIndex) -> froze
     return frozenset(witnesses)
 
 
+def _accepted_witnesses(
+    node: ast.expr | None, parameter: str, inputs: frozenset[str], context: PythonFileContext
+) -> frozenset[str] | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, bool):
+        return inputs if node.value else frozenset()
+    negate = isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.Not)
+    expression = node.operand if negate and isinstance(node, ast.UnaryOp) else node
+    checked_kind = _checked_kind(expression, parameter, context)
+    checked = _WITNESSES.get(checked_kind) if checked_kind is not None else None
+    if checked is None or (not negate and not inputs & checked):
+        return None
+    return inputs - checked if negate else inputs & checked
+
+
 def _checked_kind(node: ast.expr | None, parameter: str, context: PythonFileContext) -> str | None:
     match node:
         case ast.Call(func=func, args=[ast.Name(id=name), target], keywords=[]) if name == parameter: