sarj-python-lint 1.2.1__tar.gz → 1.2.6__tar.gz

{sarj_python_lint-1.2.1 → sarj_python_lint-1.2.6}/PKG-INFO

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

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

{sarj_python_lint-1.2.1 → sarj_python_lint-1.2.6}/src/sarj_python_lint/_analysis_session.py

@@ -4,6 +4,7 @@ from typing import TYPE_CHECKING, final
 
 from sarj_python_lint._python_target import PythonTargetFacts
 from sarj_python_lint.rules._first_party import FirstPartyFacts
+from sarj_python_lint.rules._nominal_project import NominalProjectFacts
 
 
 if TYPE_CHECKING:
@@ -16,3 +17,4 @@ class AnalysisSession:
         self.project: ProjectIndexSet | None = None
         self.first_party = FirstPartyFacts()
         self.python_target = PythonTargetFacts()
+        self.nominal_project = NominalProjectFacts()

sarj_python_lint-1.2.6/src/sarj_python_lint/rules/_nominal_project.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from functools import cached_property
+from pathlib import Path
+import tomllib
+from types import MappingProxyType
+from typing import TYPE_CHECKING, TypeGuard, final
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.utils import canonicalize_name
+
+from sarj_python_lint.rules._first_party import distribution_root
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint.rules._first_party import FirstPartyFacts
+
+
+_MAX_FILES = 5_000
+_MAX_DIRECTORIES = 3_000
+_MAX_BYTES = 500_000
+_MAX_TOTAL_BYTES = 25_000_000
+_SKIP = frozenset({"node_modules", "vendor", "vendored", "build", "dist", "__pycache__", "venv"})
+
+
+@dataclass(frozen=True)
+class NominalSource:
+    path: Path
+    text: str
+
+    @cached_property
+    def tree(self) -> ast.Module | None:
+        try:
+            tree = ast.parse(self.text, filename=str(self.path))
+        except SyntaxError:
+            return None
+        if any(
+            isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names)
+            for node in ast.walk(tree)
+        ):
+            return None
+        return tree
+
+    @cached_property
+    def imports(self) -> ImportIndex:
+        tree = self.tree
+        if tree is None:
+            return ImportIndex(MappingProxyType({}), frozenset())
+        imports = ImportIndex.from_tree(tree)
+        mutated = {
+            ast.unparse(node).partition(".")[0]
+            for node in ast.walk(tree)
+            if isinstance(node, ast.Attribute) and isinstance(node.ctx, (ast.Store, ast.Del))
+        }
+        return ImportIndex(
+            MappingProxyType({name: target for name, target in imports.bindings.items() if name not in mutated}),
+            imports.shadowed_names | mutated,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class _Workspace:
+    root: Path
+    members: tuple[str, ...]
+    excludes: tuple[str, ...]
+
+    def contains(self, path: Path) -> bool:
+        if path == self.root:
+            return True
+        if not path.is_relative_to(self.root):
+            return False
+        relative = path.relative_to(self.root)
+        return any(relative.full_match(pattern) for pattern in self.members) and not any(
+            relative.full_match(pattern) for pattern in self.excludes
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class _Distribution:
+    root: Path
+    name: str | None
+    dependencies: frozenset[str]
+    workspace: _Workspace | None
+
+
+@final
+class NominalProjectFacts:
+    # One request owns these caches; subsequent requests see source changes.
+    def __init__(self) -> None:
+        self._distributions: dict[Path, tuple[_Distribution, ...]] = {}
+        self._sources: dict[Path, dict[str, NominalSource]] = {}
+        self._scopes: dict[Path, dict[str, NominalSource]] = {}
+
+    def sources(self, path: Path, first_party: FirstPartyFacts) -> dict[str, NominalSource]:
+        owner = distribution_root(path, facts=first_party)
+        root = first_party.project_root(path)
+        if owner is None or root is None:
+            return {}
+        if owner in self._scopes:
+            return self._scopes[owner]
+        distributions = self._accessible_distributions(owner, root)
+        sources = self._merge_sources(distributions)
+        self._scopes[owner] = sources
+        return sources
+
+    def _accessible_distributions(self, owner: Path, root: Path) -> tuple[_Distribution, ...]:
+        if root not in self._distributions:
+            self._distributions[root] = tuple(
+                distribution
+                for manifest in _files(root, "pyproject.toml")
+                if (distribution := _distribution(manifest)) is not None
+            )
+        distributions = self._distributions[root]
+        own = next(
+            (
+                distribution
+                for distribution in distributions
+                if distribution.root == owner and distribution.name is not None
+            ),
+            None,
+        )
+        if own is None:
+            return ()
+        distributions = _workspace_distributions(distributions, owner)
+        return tuple(
+            distribution
+            for distribution in distributions
+            if distribution == own
+            or (
+                distribution.name in own.dependencies
+                and sum(candidate.name == distribution.name for candidate in distributions) == 1
+            )
+        )
+
+    def _merge_sources(self, distributions: tuple[_Distribution, ...]) -> dict[str, NominalSource]:
+        sources: dict[str, NominalSource] = {}
+        ambiguous: set[str] = set()
+        for distribution in distributions:
+            if distribution.root not in self._sources:
+                self._sources[distribution.root] = _sources(distribution.root)
+            for module, source in self._sources[distribution.root].items():
+                if module in sources:
+                    ambiguous.add(module)
+                sources[module] = source
+        return {module: source for module, source in sources.items() if module not in ambiguous}
+
+
+def _workspace_distributions(distributions: tuple[_Distribution, ...], owner: Path) -> tuple[_Distribution, ...]:
+    workspaces = [
+        distribution.workspace
+        for distribution in distributions
+        if distribution.workspace is not None and distribution.workspace.contains(owner)
+    ]
+    if workspaces:
+        workspace = max(workspaces, key=lambda scope: len(scope.root.parts))
+        distributions = tuple(distribution for distribution in distributions if workspace.contains(distribution.root))
+    return distributions
+
+
+def _distribution(manifest: Path) -> _Distribution | None:
+    try:
+        if manifest.is_symlink() or manifest.stat().st_size > _MAX_BYTES:
+            return None
+        document: object = tomllib.loads(manifest.read_text(encoding="utf-8"))
+    except OSError, ValueError:
+        return None
+    if not _is_mapping(document):
+        return None
+    workspace = _workspace(manifest.parent, document)
+    project = document.get("project")
+    if not _is_mapping(project):
+        return _Distribution(manifest.parent, None, frozenset(), workspace) if workspace is not None else None
+    name = project.get("name")
+    dependencies = project.get("dependencies", [])
+    if not isinstance(name, str) or not _is_list(dependencies):
+        return None
+    names: set[str] = set()
+    for dependency in dependencies:
+        if not isinstance(dependency, str):
+            continue
+        try:
+            names.add(canonicalize_name(Requirement(dependency).name))
+        except InvalidRequirement:
+            continue
+    return _Distribution(manifest.parent, canonicalize_name(name), frozenset(names), workspace)
+
+
+def _workspace(root: Path, document: dict[object, object]) -> _Workspace | None:
+    value: object = document
+    for key in ("tool", "uv", "workspace"):
+        if not _is_mapping(value):
+            return None
+        value = value.get(key)
+    if not _is_mapping(value):
+        return None
+    members = _patterns(value.get("members"))
+    excludes = _patterns(value.get("exclude", []))
+    if members is None or excludes is None:
+        return None
+    return _Workspace(root, members, excludes)
+
+
+def _patterns(value: object) -> tuple[str, ...] | None:
+    if not _is_list(value) or any(not isinstance(item, str) for item in value):
+        return None
+    return tuple(item for item in value if isinstance(item, str))
+
+
+def _files(root: Path, pattern: str) -> list[Path]:
+    found: list[Path] = []
+    try:
+        for count, (directory, directories, filenames) in enumerate(root.walk()):
+            if count >= _MAX_DIRECTORIES or len(found) >= _MAX_FILES:
+                # A partial inventory cannot establish uniqueness.
+                return []
+            directories[:] = sorted(name for name in directories if not name.startswith(".") and name not in _SKIP)
+            found.extend(directory / name for name in sorted(filenames) if Path(name).match(pattern))
+            if len(found) > _MAX_FILES:
+                return []
+    except OSError:
+        return []
+    return found
+
+
+def _sources(root: Path) -> dict[str, NominalSource]:
+    sources: dict[str, NominalSource] = {}
+    ambiguous: set[str] = set()
+    total_bytes = 0
+    for path in _files(root, "*.py"):
+        try:
+            total_bytes += path.stat().st_size
+        except OSError:
+            continue
+        if total_bytes > _MAX_TOTAL_BYTES:
+            return {}
+        module = _module_name(root, path)
+        if not module:
+            continue
+        source = _source(path)
+        if source is None:
+            continue
+        if module in sources:
+            ambiguous.add(module)
+        sources[module] = source
+    return {module: source for module, source in sources.items() if module not in ambiguous}
+
+
+def _module_name(root: Path, path: Path) -> str | None:
+    # A nested manifest owns its sources even when it uses the same namespace.
+    if any(
+        (parent / "pyproject.toml").is_file() for parent in path.parents if parent != root and root in parent.parents
+    ):
+        return None
+    relative = path.relative_to(root)
+    parts = relative.parts[1:] if relative.parts[0] == "src" else relative.parts
+    return ".".join(parts[:-1] if parts[-1] == "__init__.py" else (*parts[:-1], path.stem)) or None
+
+
+def _source(path: Path) -> NominalSource | None:
+    try:
+        if path.is_symlink() or path.stat().st_size > _MAX_BYTES:
+            return None
+        text = path.read_text(encoding="utf-8")
+        if is_generated(path, text):
+            return None
+    except OSError, UnicodeError:
+        return None
+    return NominalSource(path, text)
+
+
+def _is_mapping(value: object) -> TypeGuard[dict[object, object]]:
+    return isinstance(value, dict)
+
+
+def _is_list(value: object) -> TypeGuard[list[object]]:
+    return isinstance(value, list)

{sarj_python_lint-1.2.1 → sarj_python_lint-1.2.6}/src/sarj_python_lint/rules/_registry.py

@@ -75,6 +75,7 @@ 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_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
 from sarj_python_lint.rules.no_typed_doc_sections import NoTypedDocSections
 from sarj_python_lint.rules.no_unique_violation_message_match import (
@@ -181,6 +182,7 @@ if TYPE_CHECKING:
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        NoSwallowedAsyncioCancellation.id: NoSwallowedAsyncioCancellation,
         AsyncMockCallWithoutAwaitAssertion.id: AsyncMockCallWithoutAwaitAssertion,
         ComplexPostgresQueryRequiresArchitectureReview.id: ComplexPostgresQueryRequiresArchitectureReview,
         ExcessiveCommentary.id: ExcessiveCommentary,

sarj_python_lint-1.2.6/src/sarj_python_lint/rules/no_swallowed_asyncio_cancellation.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import ast
+from itertools import pairwise
+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._ast_index import nodes
+from sarj_python_lint.rules._paths import is_test_path, is_test_support_path
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+_ASYNCIO = frozenset({"asyncio", "asyncio.exceptions"})
+_SIMPLE_STATEMENTS = (ast.Expr, ast.Assign, ast.AnnAssign, ast.AugAssign, ast.Delete, ast.Pass)
+_MESSAGE = (
+    "CancelledError handler completes normally; re-raise caller cancellation after cleanup, "
+    "or guard intentional child cancellation with the current task's cancellation state."
+)
+
+
+@final
+class NoSwallowedAsyncioCancellation(Rule):
+    id = "no-swallowed-asyncio-cancellation"
+    code = "SARJ458"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Preserve cancellation when an async operation is cancelled.",
+        rationale=(
+            "Returning or falling through after catching CancelledError can make cancelled work look successful "
+            "and interfere with task groups and timeout shutdown. Child cancellation must be distinguished from "
+            "cancellation of the caller."
+        ),
+        remediation=(
+            "Re-raise after cleanup. If child cancellation is an expected result, first propagate cancellation "
+            "when asyncio.current_task().cancelling() is nonzero. Use an exact suppression for a documented "
+            "boundary that deliberately consumes cancellation."
+        ),
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only explicit, import-proven asyncio.CancelledError handlers in async functions are inspected; broad handlers, contextlib.suppress, tests, support fixtures, and generated files are excluded.",
+            "Only straight-line handlers with a return or normal fallthrough are reported. Compound handlers, re-raising, and translated exceptions are excluded. Any attribute call named uncancel is conservatively excluded without proving its receiver, so unrelated methods can hide a finding.",
+            "A single-name task created by asyncio.create_task, immediately cancelled before a try that only awaits it, is intentionally excluded as child cleanup; this does not prove concurrent caller cancellation cannot occur.",
+            "Try statements with control-transferring or compound finalizers are excluded, including handlers nested beneath them. Runtime helper effects and interprocedural task ownership are not inferred.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="cancelled-operation-returns-success",
+                title="Cancellation becomes a successful return",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "worker.py",
+                        "import asyncio\n\nasync def worker():\n    try:\n        await asyncio.sleep(10)\n    except asyncio.CancelledError:\n        return None\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("worker.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="cancelled-operation-reraises",
+                title="Cleanup preserves cancellation",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "worker.py",
+                        "import asyncio\n\nasync def worker():\n    try:\n        await asyncio.sleep(10)\n    except asyncio.CancelledError:\n        raise\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("worker.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if "CancelledError" not in context.source:
+            return []
+        if context.generated or is_test_path(context.path) or is_test_support_path(context.path):
+            return []
+        tree = context.tree
+        if tree is None:
+            return []
+        diagnostics: list[Diagnostic] = []
+        for function in nodes(tree, ast.AsyncFunctionDef, index=context.node_index):
+            diagnostics.extend(_function_diagnostics(function, context, self.code))
+        return sorted(diagnostics, key=lambda item: (item.line, item.col))
+
+
+def _function_diagnostics(function: ast.AsyncFunctionDef, context: PythonFileContext, code: str) -> list[Diagnostic]:
+    local = tuple(_local_nodes(function))
+    children = _owned_tasks(local, context.imports)
+    previous = _preceding_statements(local)
+    diagnostics: list[Diagnostic] = []
+    for node in local:
+        if not isinstance(node, ast.Try) or _owned_child_cleanup(node, previous.get(id(node)), children):
+            continue
+        for handler in node.handlers:
+            if not _catches_cancellation(handler.type, context.imports) or not _normal_exit(handler.body):
+                continue
+            if is_suppressed(context.source_lines, handler.lineno, code):
+                continue
+            diagnostics.append(
+                Diagnostic(
+                    path=context.path,
+                    line=handler.lineno,
+                    col=handler.col_offset + 1,
+                    code=code,
+                    message=_MESSAGE,
+                    severity=Severity.WARNING,
+                )
+            )
+    return diagnostics
+
+
+def _local_nodes(function: ast.AsyncFunctionDef) -> Iterator[ast.AST]:
+    stack: list[ast.AST] = list(reversed(function.body))
+    yield function
+    while stack:
+        node = stack.pop()
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | ast.Lambda):
+            continue
+        if isinstance(node, ast.Try | ast.TryStar) and any(
+            not isinstance(statement, _SIMPLE_STATEMENTS) for statement in node.finalbody
+        ):
+            continue
+        yield node
+        stack.extend(reversed(list(ast.iter_child_nodes(node))))
+
+
+def _catches_cancellation(exception: ast.expr | None, imports: ImportIndex) -> bool:
+    if isinstance(exception, ast.Tuple):
+        return any(_catches_cancellation(item, imports) for item in exception.elts)
+    return exception is not None and imports.resolves(exception, sources=_ASYNCIO, symbol="CancelledError")
+
+
+def _normal_exit(statements: list[ast.stmt]) -> bool:
+    for statement in statements:
+        if any(
+            isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == "uncancel"
+            for node in ast.walk(statement)
+        ):
+            return False
+        if isinstance(statement, ast.Return):
+            return True
+        if not isinstance(statement, _SIMPLE_STATEMENTS):
+            return False
+    return True
+
+
+def _owned_tasks(local: tuple[ast.AST, ...], imports: ImportIndex) -> frozenset[str]:
+    bindings: dict[str, list[ast.AST]] = {}
+    for node in local:
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store | ast.Del):
+            bindings.setdefault(node.id, []).append(node)
+        if (
+            isinstance(node, ast.Attribute)
+            and isinstance(node.ctx, ast.Store | ast.Del)
+            and isinstance(node.value, ast.Name)
+        ):
+            bindings.setdefault(node.value.id, []).append(node)
+    return frozenset(
+        node.targets[0].id
+        for node in local
+        if isinstance(node, ast.Assign)
+        and len(node.targets) == 1
+        and isinstance(node.targets[0], ast.Name)
+        and len(bindings[node.targets[0].id]) == 1
+        and isinstance(node.value, ast.Call)
+        and imports.resolves(node.value.func, sources=frozenset({"asyncio"}), symbol="create_task")
+    )
+
+
+def _preceding_statements(local: tuple[ast.AST, ...]) -> dict[int, ast.stmt]:
+    previous: dict[int, ast.stmt] = {}
+    for node in local:
+        for suite in _statement_suites(node):
+            for first, second in pairwise(suite):
+                previous[id(second)] = first
+    return previous
+
+
+def _owned_child_cleanup(node: ast.Try, previous: ast.stmt | None, children: frozenset[str]) -> bool:
+    if len(node.body) != 1:
+        return False
+    match node.body[0], previous:
+        case (
+            ast.Expr(value=ast.Await(value=ast.Name(id=awaited))),
+            ast.Expr(value=ast.Call(func=ast.Attribute(value=ast.Name(id=cancelled), attr="cancel"))),
+        ):
+            return awaited == cancelled and awaited in children
+        case _:
+            return False
+
+
+def _statement_suites(node: ast.AST) -> tuple[list[ast.stmt], ...]:
+    match node:
+        case ast.Try() | ast.TryStar():
+            return node.body, node.orelse, node.finalbody
+        case ast.If() | ast.For() | ast.AsyncFor() | ast.While():
+            return node.body, node.orelse
+        case ast.AsyncFunctionDef() | ast.With() | ast.AsyncWith() | ast.ExceptHandler() | ast.match_case():
+            return (node.body,)
+        case _:
+            return ()