sarj-python-lint 1.10.0__tar.gz → 1.12.0__tar.gz

{sarj_python_lint-1.10.0 → sarj_python_lint-1.12.0}/PKG-INFO

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

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

{sarj_python_lint-1.10.0 → sarj_python_lint-1.12.0}/src/sarj_python_lint/rules/_registry.py

@@ -79,6 +79,7 @@ from sarj_python_lint.rules.no_restated_comment import NoRestatedComment
 from sarj_python_lint.rules.no_secret_in_log import NoSecretInLog
 from sarj_python_lint.rules.no_select_star import NoSelectStar
 from sarj_python_lint.rules.no_service_behavior_in_settings import NoServiceBehaviorInSettings
+from sarj_python_lint.rules.no_shallow_container_type_guard import NoShallowContainerTypeGuard
 from sarj_python_lint.rules.no_string_concat_in_loop import NoStringConcatInLoop
 from sarj_python_lint.rules.no_swallowed_asyncio_cancellation import NoSwallowedAsyncioCancellation
 from sarj_python_lint.rules.no_tautological_expect import NoTautologicalExpect
@@ -164,6 +165,7 @@ from sarj_python_lint.rules.require_nodecode_for_splitting_settings_field import
     RequireNoDecodeForSplittingSettingsField,
 )
 from sarj_python_lint.rules.require_port_for_service import RequirePortForService
+from sarj_python_lint.rules.require_precise_factory_signature import RequirePreciseFactorySignature
 from sarj_python_lint.rules.require_public_dependency_contract import RequirePublicDependencyContract
 from sarj_python_lint.rules.require_pydantic_for_external_json import (
     RequirePydanticForExternalJson,
@@ -199,6 +201,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         RequireExplicitContractImplementation.id: RequireExplicitContractImplementation,
         DiscourageNullableConstructorParameters.id: DiscourageNullableConstructorParameters,
         RequirePublicDependencyContract.id: RequirePublicDependencyContract,
+        RequirePreciseFactorySignature.id: RequirePreciseFactorySignature,
         RequireExplicitServiceContract.id: RequireExplicitServiceContract,
         AsyncCleanupRegisteredSynchronously.id: AsyncCleanupRegisteredSynchronously,
         SubprocessKillWithoutReap.id: SubprocessKillWithoutReap,
@@ -260,6 +263,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoHiddenConstructorFallback.id: NoHiddenConstructorFallback,
         NoInjectedModuleLoader.id: NoInjectedModuleLoader,
         NoNullableDependencyFallback.id: NoNullableDependencyFallback,
+        NoShallowContainerTypeGuard.id: NoShallowContainerTypeGuard,
         NoFileLevelEscapeHatchSuppression.id: NoFileLevelEscapeHatchSuppression,
         NoInvalidArgumentNameSuppression.id: NoInvalidArgumentNameSuppression,
         NoFastapiOnEvent.id: NoFastapiOnEvent,

{sarj_python_lint-1.10.0 → sarj_python_lint-1.12.0}/src/sarj_python_lint/rules/no_injected_module_loader.py

@@ -20,12 +20,23 @@ from sarj_python_lint.rules.no_hidden_constructor_fallback import LocalBindingCo
 
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Mapping
 
     from sarj_python_lint._file_context import PythonFileContext
 
 
 _LOADER_TARGETS = frozenset({"importlib.import_module", "importlib.__import__", "builtins.__import__"})
+_LEXICAL_SCOPES = (
+    ast.Module,
+    ast.FunctionDef,
+    ast.AsyncFunctionDef,
+    ast.ClassDef,
+    ast.Lambda,
+    ast.ListComp,
+    ast.SetComp,
+    ast.DictComp,
+    ast.GeneratorExp,
+)
 
 
 @final
@@ -42,7 +53,8 @@ class NoInjectedModuleLoader(Rule):
         limitations=(
             "Flags defaults resolving to importlib.import_module, importlib.__import__, or builtins.__import__, including stable module-level import and single-assignment aliases and unshadowed __import__.",
             "Tests, test support, and generated code are excluded. Required loader parameters, application loaders, wrapper lambdas, alias chains, comprehensions, and imports local to enclosing scopes are not inferred.",
-            "Conservatively skips shadowed or rebound names, wildcard-import files, and files that reassign loader attributes. No autofix: removing an argument changes the callable contract and moving imports can change initialization timing.",
+            "Conservatively skips shadowed or rebound names, wildcard-import files, reassigned loader attributes, and exception or pattern captures of importer roots, symbols or assignment aliases. A relevant-name capture in an unrelated local scope can cause a false negative because capture checks are file-wide.",
+            "Assignment aliases require one module binding and precede use by line and column. Defaults use their enclosing evaluation scope: earlier statements in the nearest executing class body can shadow loaders; methods and nested classes do not close over class attributes. Enclosing function body bindings remain conservative exclusions, but a function's parameters do not shadow its own defaults. Relevant global declarations and walrus writes exclude sensitive importer names. Compound class statements can cause conservative omissions. Dynamic namespace mutation is not inferred. No autofix: changing arguments or import placement can alter API and initialization behavior.",
         ),
         examples=(
             RuleExample(
@@ -83,15 +95,21 @@ class NoInjectedModuleLoader(Rule):
             or context.generated
             or is_test_path(context.path)
             or is_test_support_path(context.path)
-            or _ambiguous_loader_bindings(context)
         ):
             return []
         aliases = _stable_loader_aliases(context)
+        if _ambiguous_loader_bindings(context, aliases):
+            return []
         findings: list[Diagnostic] = []
         for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda):
             for argument, default in _defaults(function.args):
                 direct = _is_loader(default, context)
-                aliased = isinstance(default, ast.Name) and aliases.get(default.id, function.lineno) < function.lineno
+                aliased = (
+                    isinstance(default, ast.Name)
+                    and default.id in aliases
+                    and (aliases[default.id].lineno, aliases[default.id].col_offset)
+                    < (function.lineno, function.col_offset)
+                )
                 if not (direct or aliased) or _shadowed(default, function, context):
                     continue
                 findings.append(
@@ -107,9 +125,28 @@ class NoInjectedModuleLoader(Rule):
         return sorted(findings, key=lambda finding: (finding.line, finding.col))
 
 
-def _ambiguous_loader_bindings(context: PythonFileContext) -> bool:
+def _ambiguous_loader_bindings(context: PythonFileContext, aliases: Mapping[str, ast.stmt]) -> bool:
     if any(alias.name == "*" for node in context.nodes(ast.ImportFrom) for alias in node.names):
         return True
+    sensitive_names = {"__import__", *aliases} | {
+        name
+        for name, target in context.module_imports.bindings.items()
+        if (target.module in {"importlib", "builtins"} and target.symbol is None)
+        or f"{target.module}.{target.symbol}" in _LOADER_TARGETS
+    }
+    if any(sensitive_names.intersection(node.names) for node in context.nodes(ast.Global)):
+        return True
+    for node in context.nodes(ast.ExceptHandler, ast.MatchAs, ast.MatchStar, ast.MatchMapping, ast.NamedExpr):
+        match node:
+            case (
+                ast.ExceptHandler(name=name)
+                | ast.MatchAs(name=name)
+                | ast.MatchStar(name=name)
+                | ast.MatchMapping(rest=name)
+                | ast.NamedExpr(target=ast.Name(id=name))
+            ):
+                if name in sensitive_names:
+                    return True
     return any(
         isinstance(node.ctx, (ast.Store, ast.Del))
         and context.module_imports.resolved_qualified_name(node) in _LOADER_TARGETS
@@ -144,27 +181,51 @@ def _shadowed(default: ast.expr, function: ast.AST, context: PythonFileContext)
         root = root.value
     if not isinstance(root, ast.Name):
         return True
-    parent = context.parents.get(function)
+    child = function
+    parent = context.parents.get(child)
+    class_scope_visible = True
     while parent is not None:
         if isinstance(parent, (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)):
             return True
         if isinstance(parent, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
-            if root.id in scope_bindings(parent):
-                return True
-        elif isinstance(parent, ast.ClassDef):
-            collector = LocalBindingCollector()
-            for statement in parent.body:
-                collector.visit(statement)
-            if root.id in collector.names:
+            if _in_scope_body(parent, child):
+                if root.id in scope_bindings(parent):
+                    return True
+                class_scope_visible = False
+        elif isinstance(parent, ast.ClassDef) and _in_scope_body(parent, child):
+            if class_scope_visible and _class_prefix_shadows(parent, child, root.id):
                 return True
+            class_scope_visible = False
+        child = parent
         parent = context.parents.get(parent)
     return False
 
 
-def _stable_loader_aliases(context: PythonFileContext) -> dict[str, int]:
+def _in_scope_body(scope: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | ast.Lambda, child: ast.AST) -> bool:
+    # Defaults and class headers execute outside the scope being defined.
+    return scope.body is child if isinstance(scope, ast.Lambda) else child in scope.body
+
+
+def _class_prefix_shadows(owner: ast.ClassDef, containing: ast.AST, name: str) -> bool:
+    collector = LocalBindingCollector()
+    for statement in owner.body:
+        if statement is containing:
+            match statement:
+                case ast.Assign(value=value) | ast.AnnAssign(value=ast.expr() as value):
+                    collector.visit(value)
+                case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.ClassDef():
+                    pass
+                case _:
+                    collector.visit(statement)
+            break
+        collector.visit(statement)
+    return name in collector.names
+
+
+def _stable_loader_aliases(context: PythonFileContext) -> dict[str, ast.stmt]:
     if context.tree is None:
         return {}
-    aliases: dict[str, int] = {}
+    aliases: dict[str, ast.stmt] = {}
     for statement in context.tree.body:
         match statement:
             case (
@@ -173,16 +234,16 @@ def _stable_loader_aliases(context: PythonFileContext) -> dict[str, int]:
             ):
                 if (
                     _is_loader(value, context)
-                    and _loader_import_precedes(value, statement.lineno, context)
+                    and _loader_import_precedes(value, statement, context)
                     and _binding_count(name, context) == 1
                 ):
-                    aliases[name] = statement.lineno
+                    aliases[name] = statement
             case _:
                 pass
     return aliases
 
 
-def _loader_import_precedes(value: ast.expr, line: int, context: PythonFileContext) -> bool:
+def _loader_import_precedes(value: ast.expr, assignment: ast.stmt, context: PythonFileContext) -> bool:
     root = value
     while isinstance(root, ast.Attribute):
         root = root.value
@@ -191,7 +252,7 @@ def _loader_import_precedes(value: ast.expr, line: int, context: PythonFileConte
     if root.id == "__import__" and context.module_imports.builtin_is_unshadowed(root.id):
         return True
     return any(
-        statement.lineno < line
+        (statement.lineno, statement.col_offset) < (assignment.lineno, assignment.col_offset)
         and any((alias.asname or alias.name.split(".")[0]) == root.id for alias in statement.names)
         for statement in context.tree.body
         if isinstance(statement, (ast.Import, ast.ImportFrom))
@@ -200,14 +261,47 @@ def _loader_import_precedes(value: ast.expr, line: int, context: PythonFileConte
 
 def _binding_count(name: str, context: PythonFileContext) -> int:
     return (
-        sum(node.id == name and isinstance(node.ctx, (ast.Store, ast.Del)) for node in context.nodes(ast.Name))
-        + sum(node.arg == name for node in context.nodes(ast.arg))
-        + sum((node.asname or node.name.split(".")[0]) == name for node in context.nodes(ast.alias))
-        + sum(
-            node.name == name
+        sum(
+            _binds_name(node, name) and _is_module_binding(node, context)
             for node in context.nodes(
-                ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.ExceptHandler, ast.MatchAs, ast.MatchStar
+                ast.Name,
+                ast.alias,
+                ast.FunctionDef,
+                ast.AsyncFunctionDef,
+                ast.ClassDef,
+                ast.ExceptHandler,
+                ast.MatchAs,
+                ast.MatchStar,
+                ast.MatchMapping,
             )
         )
-        + sum(node.rest == name for node in context.nodes(ast.MatchMapping))
+        + sum(name in node.names for node in context.nodes(ast.Global))
+        + sum(node.target.id == name for node in context.nodes(ast.NamedExpr))
     )
+
+
+def _binds_name(node: ast.AST, name: str) -> bool:
+    match node:
+        case (
+            ast.Name(id=bound, ctx=(ast.Store() | ast.Del()))
+            | ast.FunctionDef(name=bound)
+            | ast.AsyncFunctionDef(name=bound)
+            | ast.ClassDef(name=bound)
+            | ast.ExceptHandler(name=bound)
+            | ast.MatchAs(name=bound)
+            | ast.MatchStar(name=bound)
+            | ast.MatchMapping(rest=bound)
+        ):
+            return bound == name
+        case ast.alias(name=imported, asname=alias):
+            return (alias or imported.partition(".")[0]) == name
+        case _:
+            return False
+
+
+def _is_module_binding(node: ast.AST, context: PythonFileContext) -> bool:
+    while node in context.parents:
+        node = context.parents[node]
+        if isinstance(node, _LEXICAL_SCOPES):
+            return isinstance(node, ast.Module)
+    return False

sarj_python_lint-1.12.0/src/sarj_python_lint/rules/no_shallow_container_type_guard.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, 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
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+_CONTAINERS = frozenset({"dict", "list", "set"})
+_MAPPING_SLOTS = 2
+_SLOTS = frozenset({"object", "str", "int", "bool", "float", "bytes"})
+_BUILTINS = _SLOTS | _CONTAINERS | {"isinstance"}
+_MUTATION_TARGETS = {f"builtins.{symbol}" for symbol in _BUILTINS} | {
+    "typing.TypeGuard",
+    "typing.TypeIs",
+    "typing_extensions.TypeGuard",
+    "typing_extensions.TypeIs",
+}
+_BAD = "from typing import TypeGuard\ndef is_mapping(value: object) -> TypeGuard[dict[str, object]]:\n    return isinstance(value, dict)\n"
+_GOOD = _BAD.replace("dict[str, object]", "dict[object, object]")
+
+
+@final
+class NoShallowContainerTypeGuard(Rule):
+    id = "no-shallow-container-type-guard"
+    code = "SARJ472"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Do not claim typed container contents from a container-only type guard.",
+        rationale="TypeGuard and TypeIs let callers trust their declared narrowing. Checking only dict, list, or set does not validate keys, values, or elements, so callers can perform operations that fail at runtime.",
+        remediation="Use object for unchecked container slots, or validate their contents when the narrower contract is required. Keep constrained input types that already prove the contents.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Checks top-level, undecorated, non-generic synchronous functions with one positional parameter proven to be builtin object and a single return isinstance(parameter, builtin_container), optionally after a docstring.",
+            "The TypeGuard or TypeIs target must be a matching builtin dict, list, or set whose slots all resolve to object, str, int, bool, float, or bytes; at least one slot must be narrower than object.",
+            "Includes authored tests; generated and vendor source is excluded. String annotations, constrained input types, unions, Any, TypeVars, Protocols, assignment aliases, nested definitions, and content validators are not inferred.",
+            "Annotation imports include TYPE_CHECKING imports. Runtime imports use conservative file-wide shadow facts, so unrelated local rebinding can cause false negatives. Wildcard imports, explicit writes to relevant builtin or typing attributes, and exception, pattern or walrus bindings that shadow relevant names or imported aliases exclude the file; dynamic namespace mutation is not inferred.",
+            "No autofix: widening the return contract can require caller changes, while adding content validation changes behavior and cost.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="unchecked-dictionary-keys",
+                title="A container check does not prove string keys",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/values.py", _BAD),),
+                focus_path=PurePosixPath("app/values.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="honest-dictionary-keys",
+                title="Unchecked keys retain their object type",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/values.py", _GOOD),),
+                focus_path=PurePosixPath("app/values.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.tree is None or context.generated or _ambiguous_symbols(context):
+            return []
+        findings: list[Diagnostic] = []
+        for function in context.tree.body:
+            if not isinstance(function, ast.FunctionDef):
+                continue
+            statement = _shallow_guard(function, context)
+            if statement is None or is_suppressed(context.source_lines, statement.lineno, self.code):
+                continue
+            findings.append(
+                Diagnostic(
+                    path=context.path,
+                    line=statement.lineno,
+                    col=statement.col_offset + 1,
+                    code=self.code,
+                    message="Container-only isinstance check does not validate the declared container contents; use object for unchecked slots or validate the contents required by the return type.",
+                    severity=Severity.WARNING,
+                )
+            )
+        return findings
+
+
+def _shallow_guard(function: ast.FunctionDef, context: PythonFileContext) -> ast.Return | None:
+    arguments = function.args
+    positional = (*arguments.posonlyargs, *arguments.args)
+    if function.decorator_list or function.type_params or len(positional) != 1:
+        return None
+    if arguments.kwonlyargs or arguments.vararg is not None or arguments.kwarg is not None:
+        return None
+    parameter = positional[0]
+    if _builtin_symbol(parameter.annotation, context.module_imports) != "object":
+        return None
+    name = _guarded_container(function.returns, context.module_imports)
+    if name is None:
+        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:]
+    if len(body) != 1 or not isinstance(body[0], ast.Return):
+        return None
+    statement = body[0]
+    call = statement.value
+    if not isinstance(call, ast.Call) or call.keywords:
+        return None
+    match call.args:
+        case [ast.Name(id=guarded_name), checked_container] if (
+            guarded_name == parameter.arg
+            and _builtin_symbol(call.func, context.imports) == "isinstance"
+            and _builtin_symbol(checked_container, context.imports) == name
+        ):
+            return statement
+        case _:
+            return None
+
+
+def _guarded_container(annotation: ast.expr | None, imports: ImportIndex) -> str | None:
+    if not isinstance(annotation, ast.Subscript) or imports.resolved_symbol(
+        annotation.value, sources=TYPING_SOURCES
+    ) not in {"TypeGuard", "TypeIs"}:
+        return None
+    container = annotation.slice
+    if not isinstance(container, ast.Subscript):
+        return None
+    name = _builtin_symbol(container.value, imports)
+    if name not in _CONTAINERS:
+        return None
+    slots = container.slice.elts if isinstance(container.slice, ast.Tuple) else [container.slice]
+    kinds = [_builtin_symbol(slot, imports) for slot in slots]
+    if (
+        len(kinds) != (_MAPPING_SLOTS if name == "dict" else 1)
+        or any(kind not in _SLOTS for kind in kinds)
+        or all(kind == "object" for kind in kinds)
+    ):
+        return None
+    return name
+
+
+def _builtin_symbol(node: ast.expr | None, imports: ImportIndex) -> str | None:
+    if node is None:
+        return None
+    symbol = imports.resolved_symbol(node, sources=frozenset({"builtins"}))
+    if symbol in _BUILTINS:
+        return symbol
+    if isinstance(node, ast.Name) and node.id in _BUILTINS and imports.builtin_is_unshadowed(node.id):
+        return node.id
+    return None
+
+
+def _ambiguous_symbols(context: PythonFileContext) -> bool:
+    sensitive_names = _BUILTINS | {
+        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 _BUILTINS | {"TypeGuard", "TypeIs"})
+    }
+    for node in context.nodes(
+        ast.ImportFrom, ast.Attribute, ast.ExceptHandler, ast.MatchAs, ast.MatchStar, ast.MatchMapping, ast.NamedExpr
+    ):
+        match node:
+            case ast.ImportFrom(names=aliases):
+                if any(alias.name == "*" for alias in aliases):
+                    return True
+            case ast.Attribute(ctx=(ast.Store() | ast.Del())):
+                if context.module_imports.resolved_qualified_name(node) in _MUTATION_TARGETS:
+                    return True
+            case (
+                ast.ExceptHandler(name=name)
+                | ast.MatchAs(name=name)
+                | ast.MatchStar(name=name)
+                | ast.MatchMapping(rest=name)
+                | ast.NamedExpr(target=ast.Name(id=name))
+            ):
+                if name in sensitive_names:
+                    return True
+            case _:
+                pass
+    return False