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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.42.2"
+version = "1.43.1"
 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.1}/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.42.2 → sarj_python_lint-1.43.1}/src/sarj_python_lint/rules/_resource_provenance.py

@@ -56,6 +56,15 @@ _RESOURCE_OWNERS = MappingProxyType(
 )
 
 
+def builtin_namespace_untouched(context: PythonFileContext) -> bool:
+    return not any(
+        (isinstance(node, ast.Import) and any(alias.name == "builtins" for alias in node.names))
+        or (isinstance(node, ast.ImportFrom) and node.module == "builtins")
+        or (isinstance(node, ast.Name) and node.id == "__builtins__")
+        for node in context.nodes(ast.Import, ast.ImportFrom, ast.Name)
+    )
+
+
 @final
 class ResourceProvenance:
     def __init__(self, context: PythonFileContext, *, require_static_namespace: bool = False) -> None:
@@ -86,12 +95,7 @@ class ResourceProvenance:
 
     @cached_property
     def builtin_namespace_untouched(self) -> bool:
-        return not any(
-            (isinstance(node, ast.Import) and any(alias.name == "builtins" for alias in node.names))
-            or (isinstance(node, ast.ImportFrom) and node.module == "builtins")
-            or (isinstance(node, ast.Name) and node.id == "__builtins__")
-            for node in self.context.nodes(ast.Import, ast.ImportFrom, ast.Name)
-        )
+        return builtin_namespace_untouched(self.context)
 
     def scope(self, node: ast.AST) -> ast.AST | None:
         parent = self.context.parents.get(node)

sarj_python_lint-1.43.1/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.42.2 → sarj_python_lint-1.43.1}/src/sarj_python_lint/rules/async_mock_call_without_await_assertion.py

@@ -21,7 +21,7 @@ from sarj_python_lint.rule_base import (
 from sarj_python_lint.rules._ast_index import walk as walk_ast
 from sarj_python_lint.rules._imports import ImportIndex
 from sarj_python_lint.rules._pytest import collected_tests
-from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance, builtin_namespace_untouched
 
 
 if TYPE_CHECKING:
@@ -97,13 +97,44 @@ class AsyncMockCallWithoutAwaitAssertion(Rule):
             "Requires a fresh local unittest.mock.AsyncMock constructor with unshadowed imports; aliases, reassignment, reset, and ambiguous configuration are excluded.",
             "Visible provider replacement, escape or unresolved lexical ownership retains WARNING; only the closed canonical AsyncMock provider proof blocks.",
             "Only the mock itself and unchanged immediate children of unspecced, unwrapped mocks are inferred; spec children, return values, and deeper chains are excluded.",
-            "Positive call evidence includes direct assertion methods and literal integer or boolean call-state checks; unresolved call expectations are excluded.",
-            "Await evidence excludes provably vacuous checks, including zero or nonnegative counts and empty expected await sequences; unresolved expectations are accepted without inferring their values.",
+            "Positive call evidence includes direct assertion methods and literal numeric or boolean call-state checks; unresolved call expectations are excluded.",
+            "Await evidence excludes provably vacuous checks, including non-None count/list state, zero or nonnegative numeric bounds, and empty expected await sequences; unresolved expectations are accepted without inferring their values.",
+            "Length comparisons over await_args_list use count semantics only for an unshadowed builtin len without visible builtin namespace access; custom length functions remain unresolved.",
             "Conjunctions need one accepted await branch; disjunctions need accepted evidence for the same mock in every branch. Argument equality and assertion strength are not compared.",
             "Compound negation and custom expression semantics remain unresolved; no variable values or fixture graphs are inferred.",
             "Custom assertion helpers and intentional scheduling contracts may require a reasoned local suppression.",
         ),
         examples=(
+            RuleExample(
+                example_id="vacuous-await-length",
+                scenario="await-length-evidence",
+                title="An empty await history still has nonnegative length",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_delivery.py",
+                        "from unittest.mock import AsyncMock\nasync def test_delivery():\n    send = AsyncMock()\n    await deliver(send)\n    send.assert_called_once()\n    assert len(send.await_args_list) >= 0\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_delivery.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="positive-await-length",
+                scenario="await-length-evidence",
+                title="A positive await-history length distinguishes a dropped coroutine",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_delivery.py",
+                        "from unittest.mock import AsyncMock\nasync def test_delivery():\n    send = AsyncMock()\n    await deliver(send)\n    send.assert_called_once()\n    assert len(send.await_args_list) == 1\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_delivery.py"),
+                expected_count=0,
+                public=True,
+            ),
             RuleExample(
                 example_id="spaced-positive-called-state",
                 scenario="called-attribute-spacing",
@@ -212,6 +243,7 @@ class AsyncMockCallWithoutAwaitAssertion(Rule):
         if tree is None:
             return []
         imports = context.module_imports
+        builtin_len = builtin_namespace_untouched(context)
         writes = {
             _reference(node)
             for node in context.nodes(ast.AST)
@@ -221,14 +253,20 @@ class AsyncMockCallWithoutAwaitAssertion(Rule):
             finding
             for test in collected_tests(tree.body)
             if not _is_pytest_fixture(test, imports)
-            for finding in _test_diagnostics(test, context, imports, writes, self.code)
+            for finding in _test_diagnostics(test, context, imports, writes, self.code, builtin_len=builtin_len)
         ]
 
 
 def _test_diagnostics(
-    test: _TestFunction, context: PythonFileContext, imports: ImportIndex, writes: set[_Reference], code: str
+    test: _TestFunction,
+    context: PythonFileContext,
+    imports: ImportIndex,
+    writes: set[_Reference],
+    code: str,
+    *,
+    builtin_len: bool,
 ) -> list[Diagnostic]:
-    calls = tuple(_uncovered_calls(_test_imports(imports, test), test, writes))
+    calls = tuple(_uncovered_calls(_test_imports(imports, test), test, writes, builtin_len=builtin_len))
     if not calls:
         return []
     severity = Severity.ERROR if _mock_provider_proven(test, context) else Severity.WARNING
@@ -281,11 +319,11 @@ def _test_imports(module: ImportIndex, test: _TestFunction) -> ImportIndex:
 
 
 def _uncovered_calls(
-    imports: ImportIndex, test: _TestFunction, writes: set[_Reference]
+    imports: ImportIndex, test: _TestFunction, writes: set[_Reference], *, builtin_len: bool
 ) -> Iterator[ast.Call | ast.Attribute]:
     nodes = tuple(walk_ast(test))
     bindings = _mock_bindings(imports, test.body, writes)
-    covered = _await_oracles(test.body)
+    covered = _await_oracles(test.body, builtin_len=builtin_len and imports.builtin_is_unshadowed("len"))
     reported: set[_Reference] = set()
     for statement in test.body:
         for reference, oracle in _call_oracles(statement):
@@ -375,7 +413,7 @@ def _is_async_reference(reference: _Reference, constructor: ast.Call) -> bool:
     )
 
 
-def _await_oracles(statements: list[ast.stmt]) -> set[_Reference]:
+def _await_oracles(statements: list[ast.stmt], *, builtin_len: bool) -> set[_Reference]:
     covered: set[_Reference] = set()
     for statement in statements:
         match statement:
@@ -385,7 +423,7 @@ def _await_oracles(statements: list[ast.stmt]) -> set[_Reference]:
                 if method != "assert_has_awaits" or _calls_evidence(call) is not _Evidence.INSUFFICIENT:
                     covered.add(_reference(receiver))
             case ast.Assert(test=condition):
-                covered.update(_asserted_states(condition, _AWAIT_STATE))
+                covered.update(_asserted_states(condition, _AWAIT_STATE, builtin_len=builtin_len))
             case _:
                 pass
     return covered
@@ -409,17 +447,21 @@ def _sequence_evidence(node: ast.expr) -> _Evidence:
     return _Evidence.UNRESOLVED
 
 
-def _asserted_states(condition: ast.expr, states: frozenset[str]) -> set[_Reference]:
+def _asserted_states(condition: ast.expr, states: frozenset[str], *, builtin_len: bool = False) -> set[_Reference]:
     match condition:
         case ast.UnaryOp(op=ast.Not(), operand=ast.UnaryOp(op=ast.Not(), operand=operand)):
-            return _asserted_states(operand, states)
+            return _asserted_states(operand, states, builtin_len=builtin_len)
         case ast.UnaryOp(op=ast.Not(), operand=ast.Compare(left=left, ops=[operator], comparators=[right])):
             inverse = _negated_operator(operator)
-            return _comparison_states(left, inverse, right, states) if inverse is not None else set()
+            return (
+                _comparison_states(left, inverse, right, states, builtin_len=builtin_len)
+                if inverse is not None
+                else set()
+            )
         case ast.UnaryOp(op=ast.Not(), operand=ast.Attribute(attr=attribute)) if attribute in states:
             return set()
         case ast.BoolOp(op=operator, values=values):
-            branches = [_asserted_states(value, states) for value in values]
+            branches = [_asserted_states(value, states, builtin_len=builtin_len) for value in values]
             return (
                 branches[0].union(*branches[1:])
                 if isinstance(operator, ast.And)
@@ -430,7 +472,7 @@ def _asserted_states(condition: ast.expr, states: frozenset[str]) -> set[_Refere
         case ast.Compare(left=left, ops=operators, comparators=rights):
             result: set[_Reference] = set()
             for first, operator, second in zip((left, *rights[:-1]), operators, rights, strict=True):
-                result.update(_comparison_states(first, operator, second, states))
+                result.update(_comparison_states(first, operator, second, states, builtin_len=builtin_len))
             return result
         case _:
             # Preserve acceptance of unresolved await-state assertions, such as
@@ -453,18 +495,37 @@ def _negated_operator(operator: ast.cmpop) -> ast.cmpop | None:
     return factory() if factory is not None else None
 
 
-def _comparison_states(left: ast.expr, operator: ast.cmpop, right: ast.expr, states: frozenset[str]) -> set[_Reference]:
+def _comparison_states(
+    left: ast.expr, operator: ast.cmpop, right: ast.expr, states: frozenset[str], *, builtin_len: bool = False
+) -> set[_Reference]:
     result: set[_Reference] = set()
     for node, comparison, expected in ((left, operator, right), (right, _reversed_operator(operator), left)):
-        if isinstance(node, ast.Attribute) and node.attr in states:
-            evidence = _state_evidence(node.attr, comparison, expected)
+        state = _state_operand(node, states, builtin_len=builtin_len)
+        if state is not None:
+            evidence = _state_evidence(
+                "await_count" if isinstance(node, ast.Call) else state.attr, comparison, expected
+            )
             if evidence is _Evidence.POSITIVE or (states == _AWAIT_STATE and evidence is _Evidence.UNRESOLVED):
-                result.add(_reference(node.value))
+                result.add(_reference(state.value))
         else:
             result.update(_unresolved_await_states(node, states))
     return result
 
 
+def _state_operand(node: ast.expr, states: frozenset[str], *, builtin_len: bool) -> ast.Attribute | None:
+    if isinstance(node, ast.Attribute) and node.attr in states:
+        return node
+    if builtin_len and states == _AWAIT_STATE:
+        match node:
+            case ast.Call(
+                func=ast.Name(id="len"), args=[ast.Attribute(attr="await_args_list") as argument], keywords=[]
+            ):
+                return argument
+            case _:
+                pass
+    return None
+
+
 def _reversed_operator(operator: ast.cmpop) -> ast.cmpop:
     match operator:
         case ast.Lt():
@@ -489,12 +550,14 @@ def _unresolved_await_states(node: ast.expr, states: frozenset[str]) -> set[_Ref
 
 def _state_evidence(attribute: str, operator: ast.cmpop, expected: ast.expr) -> _Evidence:
     positive: bool
-    if (
-        attribute in {"call_count", "await_count"}
+    if attribute in {"call_count", "await_count"} and (value := _literal_number(expected)) is not None:
+        positive = _proves_positive_count(operator, value)
+    elif (
+        attribute in {"call_count", "await_count", "await_args_list"}
         and isinstance(expected, ast.Constant)
-        and isinstance(expected.value, int)
+        and expected.value is None
     ):
-        positive = _proves_positive_count(operator, expected.value)
+        return _Evidence.INSUFFICIENT
     elif attribute == "called" and isinstance(expected, ast.Constant) and isinstance(expected.value, bool):
         positive = (isinstance(operator, (ast.Eq, ast.Is)) and expected.value) or (
             isinstance(operator, (ast.NotEq, ast.IsNot)) and not expected.value
@@ -513,7 +576,20 @@ def _state_evidence(attribute: str, operator: ast.cmpop, expected: ast.expr) ->
     return _Evidence.POSITIVE if positive else _Evidence.INSUFFICIENT
 
 
-def _proves_positive_count(operator: ast.cmpop, value: int) -> bool:
+def _literal_number(node: ast.expr) -> int | float | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+        return node.value
+    if isinstance(node, ast.UnaryOp) and isinstance(node.operand, ast.Constant):
+        value = node.operand.value
+        if isinstance(value, (int, float)):
+            if isinstance(node.op, ast.USub):
+                return -value
+            if isinstance(node.op, ast.UAdd):
+                return +value
+    return None
+
+
+def _proves_positive_count(operator: ast.cmpop, value: float) -> bool:
     match operator:
         case ast.Eq() | ast.GtE():
             return value > 0

sarj_python_lint-1.43.1/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