sarj-python-lint 1.7.2__tar.gz → 1.7.4__tar.gz

{sarj_python_lint-1.7.2 → sarj_python_lint-1.7.4}/PKG-INFO

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

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

{sarj_python_lint-1.7.2 → sarj_python_lint-1.7.4}/src/sarj_python_lint/__main__.py

@@ -161,6 +161,7 @@ _DIAGNOSTIC_PRECEDENCE = MappingProxyType(
         # an all-rules run emits one actionable diagnostic for this overlap.
         "SARJ447": frozenset({"SARJ008"}),
         "SARJ457": frozenset({"SARJ045"}),
+        "SARJ465": frozenset({"SARJ071"}),
     }
 )
 

{sarj_python_lint-1.7.2 → sarj_python_lint-1.7.4}/src/sarj_python_lint/rules/_imports.py

@@ -9,6 +9,10 @@ from typing import Self
 from sarj_python_lint.rules._ast_index import walk as walk_ast
 
 
+ABC_SOURCES = frozenset({"abc"})
+TYPING_SOURCES = frozenset({"typing", "typing_extensions"})
+
+
 @dataclass(frozen=True, slots=True)
 class _ImportTarget:
     module: str

{sarj_python_lint-1.7.2 → sarj_python_lint-1.7.4}/src/sarj_python_lint/rules/_project_index.py

@@ -77,8 +77,9 @@ class LoadedSource:
 
 @final
 class ProjectIndexSet:
-    def __init__(self, units: Mapping[Path, SourceUnit]) -> None:
+    def __init__(self, units: Mapping[Path, SourceUnit], roots: Sequence[Path] = ()) -> None:
         self._units = MappingProxyType(dict(units))
+        self._roots = tuple(roots)
         by_module = {unit.module: unit for unit in units.values() if unit.module is not None}
         self._by_module = MappingProxyType(by_module)
         classes: dict[SymbolRef, ClassSummary] = {}
@@ -104,7 +105,7 @@ class ProjectIndexSet:
                 continue
         for root in roots:
             _load_root_sources(root, sources)
-        return cls(_units(sources, roots))
+        return cls(_units(sources, roots), roots)
 
     @classmethod
     def single(cls, path: Path, source: str) -> Self:
@@ -119,6 +120,21 @@ class ProjectIndexSet:
         except OSError:
             return None
 
+    def unit_or_source(self, path: Path, source: str, tree: ast.Module) -> SourceUnit | None:
+        indexed = self.unit(path)
+        if indexed is not None:
+            return indexed
+        module = _module_name(path, self._roots)
+        if module is None:
+            return None
+        return SourceUnit(
+            path=path,
+            module=module,
+            source=source,
+            tree=tree,
+            imports=MappingProxyType(_imports(module, tree, is_package=path.name == "__init__.py")),
+        )
+
     def nominal_for_field(self, name: str) -> SymbolRef | None:
         matches = self._nominals.get(name)
         return next(iter(matches)) if matches is not None and len(matches) == 1 else None

{sarj_python_lint-1.7.2 → sarj_python_lint-1.7.4}/src/sarj_python_lint/rules/_registry.py

@@ -150,7 +150,9 @@ from sarj_python_lint.rules.redundant_module_docstring import RedundantModuleDoc
 from sarj_python_lint.rules.repeated_kwarg_heavy_call_in_test import RepeatedKwargHeavyCallInTest
 from sarj_python_lint.rules.repeated_static_call_cases import RepeatedStaticCallCases
 from sarj_python_lint.rules.repeated_test_composition import RepeatedTestComposition
+from sarj_python_lint.rules.require_explicit_contract_implementation import RequireExplicitContractImplementation
 from sarj_python_lint.rules.require_explicit_psycopg_transaction import RequireExplicitPsycopgTransaction
+from sarj_python_lint.rules.require_explicit_service_contract import RequireExplicitServiceContract
 from sarj_python_lint.rules.require_keyword_only_swap_prone_params import (
     RequireKeywordOnlySwapProneParams,
 )
@@ -158,6 +160,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_public_dependency_contract import RequirePublicDependencyContract
 from sarj_python_lint.rules.require_pydantic_for_external_json import (
     RequirePydanticForExternalJson,
 )
@@ -188,6 +191,9 @@ if TYPE_CHECKING:
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        RequireExplicitContractImplementation.id: RequireExplicitContractImplementation,
+        RequirePublicDependencyContract.id: RequirePublicDependencyContract,
+        RequireExplicitServiceContract.id: RequireExplicitServiceContract,
         AsyncCleanupRegisteredSynchronously.id: AsyncCleanupRegisteredSynchronously,
         SubprocessKillWithoutReap.id: SubprocessKillWithoutReap,
         NoSwallowedAsyncioCancellation.id: NoSwallowedAsyncioCancellation,

{sarj_python_lint-1.7.2 → sarj_python_lint-1.7.4}/src/sarj_python_lint/rules/no_service_behavior_in_settings.py

@@ -17,7 +17,6 @@ from sarj_python_lint.rule_base import (
     Severity,
     is_suppressed,
 )
-from sarj_python_lint.rules._ast_index import walk as walk_ast
 from sarj_python_lint.rules._paths import is_test_path, is_test_support_path
 
 
@@ -66,7 +65,7 @@ class NoServiceBehaviorInSettings(Rule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Only direct module classes named *Settings, *Config, *Configuration, or *Options are checked.",
-            "A finding requires a typed collaborator field and an ordinary public method that calls that field; pure computations, properties, validators, serializers, factories, generated files, and tests are excluded.",
+            "A finding requires a typed collaborator field and an ordinary public method that calls that field; pure computations, properties, validators, serializers, factories, generated files, and tests are excluded. Nested scopes, containers of collaborators, class objects, and methods that rebind self are not inferred.",
             "The rule does not require every data object to use a particular record library and does not infer behavior from a filename alone.",
         ),
         examples=(
@@ -180,10 +179,19 @@ def _collaborator_fields(node: ast.ClassDef) -> frozenset[str]:
 def _is_collaborator_annotation(annotation: ast.expr | None) -> bool:
     if annotation is None:
         return False
-    return any(
-        _COLLABORATOR_RE.search(_dotted_tail(candidate) or "") is not None
-        for candidate in walk_ast(annotation)
-        if isinstance(candidate, (ast.Name, ast.Attribute))
+    if isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
+        return _is_collaborator_annotation(annotation.left) or _is_collaborator_annotation(annotation.right)
+    if isinstance(annotation, ast.Subscript):
+        wrapper = _dotted_tail(annotation.value)
+        if wrapper in {"Optional", "Union"}:
+            members = annotation.slice.elts if isinstance(annotation.slice, ast.Tuple) else [annotation.slice]
+            return any(_is_collaborator_annotation(member) for member in members)
+        if wrapper == "Annotated" and isinstance(annotation.slice, ast.Tuple) and annotation.slice.elts:
+            return _is_collaborator_annotation(annotation.slice.elts[0])
+        return _is_collaborator_annotation(annotation.value)
+    return (
+        isinstance(annotation, (ast.Name, ast.Attribute))
+        and _COLLABORATOR_RE.search(_dotted_tail(annotation) or "") is not None
     )
 
 
@@ -198,9 +206,22 @@ def _is_behavioral_method(method: ast.FunctionDef | ast.AsyncFunctionDef) -> boo
 
 
 def _calls_collaborator(method: ast.FunctionDef | ast.AsyncFunctionDef, fields: frozenset[str]) -> bool:
+    nodes: list[ast.AST] = []
+    pending: list[ast.AST] = list(method.body)
+    while pending:
+        node = pending.pop()
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)):
+            continue
+        nodes.append(node)
+        pending.extend(ast.iter_child_nodes(node))
+    if any(
+        isinstance(node, ast.Name) and node.id == "self" and isinstance(node.ctx, (ast.Store, ast.Del))
+        for node in nodes
+    ):
+        return False
     return any(
         (field := _self_field(call.func)) is not None and field in fields
-        for call in walk_ast(method)
+        for call in nodes
         if isinstance(call, ast.Call)
     )
 

{sarj_python_lint-1.7.2 → sarj_python_lint-1.7.4}/src/sarj_python_lint/rules/no_unnecessary_docstring.py

@@ -219,14 +219,14 @@ def _is_syntax_required(owner: ast.Module | ast.ClassDef | ast.FunctionDef | ast
 def _owner_keys(tree: ast.Module) -> dict[int, str]:
     keys = {id(tree): "__doc__"}
 
-    def visit(body: list[ast.stmt], prefix: tuple[str, ...]) -> None:
-        for statement in body:
-            if isinstance(statement, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
-                qualified = (*prefix, statement.name)
-                keys[id(statement)] = ".".join(qualified)
-                visit(statement.body, qualified)
-
-    visit(tree.body, ())
+    def visit(node: ast.AST, prefix: tuple[str, ...]) -> None:
+        if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+            prefix = (*prefix, node.name)
+            keys[id(node)] = ".".join(prefix)
+        for child in ast.iter_child_nodes(node):
+            visit(child, prefix)
+
+    visit(tree, ())
     return keys
 
 

sarj_python_lint-1.7.4/src/sarj_python_lint/rules/require_explicit_contract_implementation.py

@@ -0,0 +1,333 @@
+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,
+    ProjectRule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._imports import ABC_SOURCES, TYPING_SOURCES, ImportIndex
+from sarj_python_lint.rules.require_port_for_service import annotation_tail
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._project_index import ClassSummary, ProjectIndexSet, SourceUnit, SymbolRef
+
+
+@final
+class RequireExplicitContractImplementation(ProjectRule):
+    id = "require-explicit-contract-implementation"
+    code = "SARJ467"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Require owned substitutes to explicitly inherit their injected contract.",
+        rationale=(
+            "Structural matching only checks a fake where it is passed. Explicit inheritance makes its obligation "
+            "visible at the class declaration and catches missing abstract operations at instantiation."
+        ),
+        remediation="Make the owned implementation inherit the exact ABC or Protocol expected by the consumer.",
+        category=RuleCategory.ARCHITECTURE,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only direct constructor arguments and unreassigned local constructor results supplied to a resolvable typed parameter are checked.",
+            "Dynamic factories, containers, casts, unresolved ancestry, and third-party implementations are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="structural-fake-at-injection",
+                title="A fake is supplied without declaring its contract",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python("app/__init__.py", "# package\n"),
+                    ExampleFile.python(
+                        "app/consumer.py",
+                        "from typing import Protocol\nclass Publisher(Protocol):\n    def publish(self) -> None: ...\nclass Consumer:\n    def __init__(self, publisher: Publisher) -> None:\n        self.publisher = publisher\n",
+                    ),
+                    ExampleFile.python("app/fake.py", "class FakePublisher:\n    def publish(self) -> None: ...\n"),
+                    ExampleFile.python(
+                        "app/usage.py",
+                        "from app.consumer import Consumer\nfrom app.fake import FakePublisher\ndef setup() -> None:\n    Consumer(publisher=FakePublisher())\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/usage.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="explicit-fake-at-injection",
+                title="The fake declares the actual contract",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python("app/__init__.py", "# package\n"),
+                    ExampleFile.python(
+                        "app/consumer.py",
+                        "from typing import Protocol\nclass Publisher(Protocol):\n    def publish(self) -> None: ...\nclass Consumer:\n    def __init__(self, publisher: Publisher) -> None:\n        self.publisher = publisher\n",
+                    ),
+                    ExampleFile.python(
+                        "app/fake.py",
+                        "from app.consumer import Publisher\nclass FakePublisher(Publisher):\n    def publish(self) -> None: ...\n",
+                    ),
+                    ExampleFile.python(
+                        "app/usage.py",
+                        "from app.consumer import Consumer\nfrom app.fake import FakePublisher\ndef setup() -> None:\n    Consumer(publisher=FakePublisher())\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/usage.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.generated or context.tree is None or context.session.project is None:
+            return []
+        project = context.session.project
+        unit = project.unit_or_source(context.path, context.source, context.tree)
+        if unit is None:
+            return []
+        visitor = _InjectionVisitor(context, unit, project, self.code)
+        visitor.visit(context.tree)
+        return visitor.findings
+
+
+@final
+class _InjectionVisitor(ast.NodeVisitor):
+    def __init__(self, context: PythonFileContext, unit: SourceUnit, project: ProjectIndexSet, code: str) -> None:
+        self.context = context
+        self.unit = unit
+        self.project = project
+        self.code = code
+        self.findings: list[Diagnostic] = []
+        self.origins: dict[str, ClassSummary] = {}
+        self.local_any_names: frozenset[str] = frozenset()
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._visit_function(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._visit_function(node)
+
+    def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        previous = self.origins
+        previous_any = self.local_any_names
+        self.origins = {}
+        self.local_any_names = frozenset(
+            alias.asname or alias.name
+            for statement in node.body
+            if isinstance(statement, ast.ImportFrom) and statement.module in {"typing", "typing_extensions"}
+            for alias in statement.names
+            if alias.name == "Any"
+        )
+        for statement in node.body:
+            self.visit(statement)
+        self.origins = previous
+        self.local_any_names = previous_any
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        self.visit(node.value)
+        origin = self._origin(node.value)
+        for target in node.targets:
+            if isinstance(target, ast.Name):
+                if origin is None:
+                    self.origins.pop(target.id, None)
+                else:
+                    self.origins[target.id] = origin
+            else:
+                for name in (item.id for item in ast.walk(target) if isinstance(item, ast.Name)):
+                    self.origins.pop(name, None)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        if node.value is None:
+            return
+        self.visit(node.value)
+        if isinstance(node.target, ast.Name):
+            if self.context.imports.resolves(node.annotation, sources=TYPING_SOURCES, symbol="Any") or (
+                isinstance(node.annotation, ast.Name) and node.annotation.id in self.local_any_names
+            ):
+                self.origins.pop(node.target.id, None)
+                return
+            origin = self._origin(node.value)
+            if origin is None:
+                self.origins.pop(node.target.id, None)
+            else:
+                self.origins[node.target.id] = origin
+
+    def visit_If(self, node: ast.If) -> None:
+        self.visit(node.test)
+        before = self.origins.copy()
+        for statement in node.body:
+            self.visit(statement)
+        after_body = self.origins
+        self.origins = before.copy()
+        for statement in node.orelse:
+            self.visit(statement)
+        after_else = self.origins
+        self.origins = {name: origin for name, origin in after_body.items() if after_else.get(name) == origin}
+
+    def visit_For(self, node: ast.For) -> None:
+        self._visit_uncertain_flow(node)
+
+    def visit_AsyncFor(self, node: ast.AsyncFor) -> None:
+        self._visit_uncertain_flow(node)
+
+    def visit_While(self, node: ast.While) -> None:
+        self._visit_uncertain_flow(node)
+
+    def visit_Try(self, node: ast.Try) -> None:
+        self._visit_uncertain_flow(node)
+
+    def visit_TryStar(self, node: ast.TryStar) -> None:
+        self._visit_uncertain_flow(node)
+
+    def visit_Match(self, node: ast.Match) -> None:
+        self._visit_uncertain_flow(node)
+
+    def _visit_uncertain_flow(self, node: ast.stmt) -> None:
+        self.generic_visit(node)
+        for child in ast.walk(node):
+            if isinstance(child, ast.Name) and isinstance(child.ctx, (ast.Store, ast.Del)):
+                self.origins.pop(child.id, None)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        target = self.project.class_for(self.unit, node.func)
+        if target is not None:
+            target_unit = self.project.source_unit(target.symbol.module)
+            if target_unit is not None and target_unit.tree is not None:
+                declaration = next(
+                    (
+                        item
+                        for item in target_unit.tree.body
+                        if isinstance(item, ast.ClassDef) and item.name == target.symbol.name
+                    ),
+                    None,
+                )
+                if declaration is not None:
+                    self._check_constructor(node, declaration, target_unit)
+        self.generic_visit(node)
+
+    def _check_constructor(self, call: ast.Call, declaration: ast.ClassDef, target_unit: SourceUnit) -> None:
+        constructor = next(
+            (item for item in declaration.body if isinstance(item, ast.FunctionDef) and item.name == "__init__"),
+            None,
+        )
+        if constructor is None:
+            return
+        positional = [*constructor.args.posonlyargs, *constructor.args.args][1:]
+        parameters = {argument.arg: argument for argument in (*positional, *constructor.args.kwonlyargs)}
+        supplied = [
+            (parameters.get(keyword.arg), keyword.value) for keyword in call.keywords if keyword.arg is not None
+        ]
+        supplied.extend((parameter, value) for parameter, value in zip(positional, call.args, strict=False))
+        for parameter, value in supplied:
+            self._check_argument(parameter, value, target_unit)
+
+    def _check_argument(self, parameter: ast.arg | None, value: ast.expr, target_unit: SourceUnit) -> None:
+        if parameter is None or parameter.annotation is None:
+            return
+        name = annotation_tail(parameter.annotation)
+        if name is None:
+            return
+        contract = self.project.class_for(target_unit, ast.Name(id=name, ctx=ast.Load()))
+        if contract is None or not _is_direct_contract(contract, self.project):
+            return
+        origin = self._origin(value)
+        if origin is None:
+            return
+        inherits = _inherits_contract(origin, contract.symbol, self.project, set())
+        if inherits is not False or is_suppressed(self.context.source_lines, value.lineno, self.code):
+            return
+        self.findings.append(
+            Diagnostic(
+                path=self.context.path,
+                line=value.lineno,
+                col=value.col_offset + 1,
+                code=self.code,
+                severity=Severity.WARNING,
+                message=(
+                    f"`{origin.symbol.name}` is supplied as `{contract.symbol.name}` without explicitly "
+                    "inheriting that contract. Declare the relationship on the implementation class."
+                ),
+            )
+        )
+
+    def _origin(self, value: ast.expr) -> ClassSummary | None:
+        if isinstance(value, ast.Name):
+            return self.origins.get(value.id)
+        if isinstance(value, ast.Call):
+            return self.project.class_for(self.unit, value.func)
+        return None
+
+
+def _is_direct_contract(summary: ClassSummary, project: ProjectIndexSet) -> bool:
+    protocol = any(
+        (base.module, base.name) in {("typing", "Protocol"), ("typing_extensions", "Protocol")}
+        for base in summary.bases
+    )
+    abc = any((base.module, base.name) == ("abc", "ABC") for base in summary.bases)
+    if not protocol and not abc:
+        return False
+    unit = project.source_unit(summary.symbol.module)
+    if unit is None or unit.tree is None:
+        return False
+    declaration = next(
+        (item for item in unit.tree.body if isinstance(item, ast.ClassDef) and item.name == summary.symbol.name),
+        None,
+    )
+    if declaration is None:
+        return False
+    imports = ImportIndex.from_tree(unit.tree, module_scope_only=True)
+    return any(
+        isinstance(member, ast.FunctionDef | ast.AsyncFunctionDef)
+        and not member.name.startswith("_")
+        and (
+            protocol
+            or any(
+                imports.resolves(decorator, sources=ABC_SOURCES, symbol="abstractmethod")
+                for decorator in member.decorator_list
+            )
+        )
+        for member in declaration.body
+    )
+
+
+def _inherits_contract(
+    implementation: ClassSummary,
+    target: SymbolRef,
+    project: ProjectIndexSet,
+    seen: set[SymbolRef],
+) -> bool | None:
+    if implementation.symbol == target:
+        return True
+    if implementation.symbol in seen:
+        return None
+    seen.add(implementation.symbol)
+    unknown = False
+    for base in implementation.bases:
+        if base == target:
+            return True
+        if (base.module, base.name) in {("abc", "ABC"), ("typing", "Generic"), ("builtins", "object")}:
+            continue
+        unit = project.source_unit(base.module)
+        ancestor = project.class_for(unit, ast.Name(id=base.name, ctx=ast.Load())) if unit is not None else None
+        if ancestor is None:
+            unknown = True
+            continue
+        relationship = _inherits_contract(ancestor, target, project, seen)
+        if relationship is True:
+            return True
+        unknown |= relationship is None
+    return None if unknown else False

{sarj_python_lint-1.7.2 → sarj_python_lint-1.7.4}/src/sarj_python_lint/rules/require_explicit_psycopg_transaction.py

@@ -55,7 +55,7 @@ class RequireExplicitPsycopgTransaction(Rule):
             "Inspects literal SQL, simple local/module constants, and psycopg.sql.SQL wrappers. Dynamic SQL and unsupported SQL syntax are excluded.",
             "A locking SELECT followed by a write on the same connection outside transaction() is reported; a single statement containing a mutation is treated as atomic. Multiple writes on a reachable local path are a warning because independent writes can be intentional.",
             "Loops, exception handlers, match statements, comprehensions, and nested closures are not analyzed as execution paths. Manual BEGIN/commit protocols are not inferred. Tests, support fixtures, and generated files are excluded.",
-            "The rule cannot prove isolation level, database constraints, or application-level atomicity; fault-injection integration tests remain necessary.",
+            "Non-autocommit connections can already provide implicit transaction protection. A manual commit is not itself evidence of a defect or of safety in autocommit mode; document the proven connection configuration when retaining that protocol. The rule cannot prove isolation level, database constraints, or application-level atomicity; fault-injection integration tests remain necessary.",
         ),
         examples=(
             RuleExample(