sarj-python-lint 1.42.2__tar.gz → 1.43.0__tar.gz

{sarj_python_lint-1.42.2 → sarj_python_lint-1.43.0}/PKG-INFO

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

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

{sarj_python_lint-1.42.2 → sarj_python_lint-1.43.0}/src/sarj_python_lint/rules/_registry.py

@@ -214,7 +214,10 @@ if TYPE_CHECKING:
 from sarj_python_lint.rules.duplicate_adjacent_exception_handler import DuplicateAdjacentExceptionHandler
 from sarj_python_lint.rules.duplicate_closed_pure_helper import DuplicateClosedPureHelper
 from sarj_python_lint.rules.no_conflicting_pydantic_alias_validation import NoConflictingPydanticAliasValidation
+from sarj_python_lint.rules.no_contradictory_type_guard import NoContradictoryTypeGuard
 from sarj_python_lint.rules.no_impossible_pydantic_field_bounds import NoImpossiblePydanticFieldBounds
+from sarj_python_lint.rules.no_invalid_pydantic_bypass import NoInvalidPydanticBypass
+from sarj_python_lint.rules.no_partial_type_is import NoPartialTypeIs
 from sarj_python_lint.rules.no_unknown_pydantic_validator_field import NoUnknownPydanticValidatorField
 from sarj_python_lint.rules.prefer_discriminated_model_union import PreferDiscriminatedModelUnion
 from sarj_python_lint.rules.redundant_test_constructor_forwarder import RedundantTestConstructorForwarder
@@ -226,6 +229,9 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
         NoExplicitTestOracle.id: NoExplicitTestOracle,
         PreferDiscriminatedModelUnion.id: PreferDiscriminatedModelUnion,
+        NoInvalidPydanticBypass.id: NoInvalidPydanticBypass,
+        NoPartialTypeIs.id: NoPartialTypeIs,
+        NoContradictoryTypeGuard.id: NoContradictoryTypeGuard,
         NoConflictingPydanticAliasValidation.id: NoConflictingPydanticAliasValidation,
         NoUnknownPydanticValidatorField.id: NoUnknownPydanticValidatorField,
         NoImpossiblePydanticFieldBounds.id: NoImpossiblePydanticFieldBounds,

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

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import ast
+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
+
+
+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 guard_symbols_ambiguous(context: PythonFileContext, builtin_symbols: frozenset[str]) -> bool:
+    if _namespace_escapes(context):
+        return True
+    mutation_targets = {f"builtins.{symbol}" for symbol in builtin_symbols} | {
+        f"{module}.{symbol}" for module in TYPING_SOURCES for symbol in ("TypeGuard", "TypeIs")
+    }
+    sensitive_names = builtin_symbols | {
+        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 | {"TypeGuard", "TypeIs"})
+    }
+    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_escapes(context: PythonFileContext) -> bool:
+    if context.dynamic_namespace or any(node.id == "__builtins__" for node in context.nodes(ast.Name)):
+        return True
+    namespace_names = {
+        name
+        for name, target in context.module_imports.bindings.items()
+        if target.symbol is None and target.module in TYPING_SOURCES | {"builtins"}
+    }
+    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 _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.0/src/sarj_python_lint/rules/no_contradictory_type_guard.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, Final, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    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
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+_SCALARS = frozenset({"int", "bool", "str", "bytes"})
+_BUILTINS = _SCALARS | {"object", "isinstance"}
+_WITNESSES: Final = {
+    "int": frozenset({"int", "bool"}),
+    "bool": frozenset({"bool"}),
+    "str": frozenset({"str"}),
+    "bytes": frozenset({"bytes"}),
+}
+_ALL_WITNESSES = frozenset({"int", "bool", "str", "bytes"})
+_MAX_INPUT_NODES = 4096
+_BAD = (
+    "from typing import TypeGuard\ndef is_text(value: object) -> TypeGuard[str]:\n    return isinstance(value, int)\n"
+)
+_GOOD = _BAD.replace("isinstance(value, int)", "isinstance(value, str)")
+
+
+@final
+class NoContradictoryTypeGuard(Rule):
+    id = "no-contradictory-type-guard"
+    code = "SARJ513"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Primitive type guards must agree with the isinstance check they return.",
+        rationale=(
+            "A guard annotation does not validate its implementation. Returning an incompatible isinstance "
+            "check makes callers trust the wrong primitive; TypeIs also incorrectly excludes rejected target "
+            "values in the false branch."
+        ),
+        remediation=(
+            "Align the declared target and runtime test. For an intentional partial predicate, TypeGuard may "
+            "narrow only the true branch; TypeIs must recognize every target value admitted by its input. "
+            "Review callers before changing the narrowing contract."
+        ),
+        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.",
+            "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.",
+            "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.",
+            "Generated files are excluded; maintained tests remain checked. No autofix guesses a domain or changes false-branch behavior.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="wrong-primitive-promise",
+                title="An integer test does not prove a string",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/guards.py", _BAD),),
+                focus_path=PurePosixPath("app/guards.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="consistent-primitive-promise",
+                title="Recognize the primitive promised to callers",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/guards.py", _GOOD),),
+                focus_path=PurePosixPath("app/guards.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.generated or not any(symbol in context.symbol_source for symbol in ("TypeGuard", "TypeIs")):
+            return []
+        if context.tree is None or guard_symbols_ambiguous(context, _BUILTINS):
+            return []
+        findings: list[Diagnostic] = []
+        for function in context.tree.body:
+            if not isinstance(function, ast.FunctionDef):
+                continue
+            statement = _contradictory_return(function, context)
+            if statement is None or is_suppressed(context.source_lines, statement.lineno, self.code):
+                continue
+            findings.append(
+                Diagnostic(
+                    context.path,
+                    statement.lineno,
+                    statement.col_offset + 1,
+                    self.code,
+                    "This guard's isinstance test contradicts its primitive narrowing promise; align the target "
+                    "and test, preserving TypeIs false-branch behavior and intentional TypeGuard partial predicates.",
+                    severity=Severity.WARNING,
+                )
+            )
+        return findings
+
+
+def _contradictory_return(function: ast.FunctionDef, context: PythonFileContext) -> ast.Return | None:
+    parameter = _sole_parameter(function)
+    annotation = function.returns
+    if parameter is None or not isinstance(annotation, ast.Subscript):
+        return None
+    guard = context.module_imports.resolved_symbol(annotation.value, sources=TYPING_SOURCES)
+    if guard not in {"TypeGuard", "TypeIs"}:
+        return None
+    target_kind = builtin_guard_symbol(annotation.slice, context.module_imports, _BUILTINS)
+    target = _WITNESSES.get(target_kind) if target_kind is not None else None
+    inputs = _input_witnesses(parameter.annotation, context.module_imports)
+    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:
+        return None
+    accepts_wrong = bool((inputs & checked) - target)
+    rejects_target = guard == "TypeIs" and bool((inputs & target) - checked)
+    return statement if accepts_wrong or rejects_target else None
+
+
+def _sole_parameter(function: ast.FunctionDef) -> ast.arg | None:
+    args = function.args
+    positional = [*args.posonlyargs, *args.args]
+    if function.decorator_list or function.type_params or len(positional) != 1:
+        return None
+    if args.kwonlyargs or args.vararg is not None or args.kwarg is not None:
+        return None
+    return positional[0]
+
+
+def _single_return(function: ast.FunctionDef) -> ast.Return | None:
+    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:]
+    return body[0] if len(body) == 1 and isinstance(body[0], ast.Return) else None
+
+
+def _input_witnesses(annotation: ast.expr | None, imports: ImportIndex) -> frozenset[str] | None:
+    pending = [annotation]
+    visited = 0
+    witnesses: set[str] = set()
+    while pending:
+        member = pending.pop()
+        visited += 1
+        if visited > _MAX_INPUT_NODES:
+            return None
+        if isinstance(member, ast.Constant) and member.value is None:
+            continue
+        if isinstance(member, ast.BinOp) and isinstance(member.op, ast.BitOr):
+            pending.extend((member.left, member.right))
+            continue
+        kind = builtin_guard_symbol(member, imports, _BUILTINS)
+        if kind == "object":
+            witnesses.update(_ALL_WITNESSES)
+        elif kind in _WITNESSES:
+            witnesses.update(_WITNESSES[kind])
+        else:
+            return None
+    return frozenset(witnesses)
+
+
+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:
+            if builtin_guard_symbol(func, context.imports, _BUILTINS) == "isinstance":
+                return builtin_guard_symbol(target, context.imports, _BUILTINS)
+        case _:
+            pass
+    return None