sarj-python-lint 1.77.2__tar.gz → 1.79.0__tar.gz

{sarj_python_lint-1.77.2 → sarj_python_lint-1.79.0}/PKG-INFO

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

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

{sarj_python_lint-1.77.2 → sarj_python_lint-1.79.0}/src/sarj_python_lint/__init__.py

@@ -3,3 +3,7 @@ from sarj_python_lint._fixes import apply_fixes as apply_fixes, python_source_ha
 from sarj_python_lint._ratchet_cli import run_ratchet as run_ratchet
 from sarj_python_lint._source import python_source_encoding as python_source_encoding
 from sarj_python_lint._version import __version__ as __version__
+from sarj_python_lint.application_logging import (
+    ApplicationLoggingUse as ApplicationLoggingUse,
+    application_logging_uses as application_logging_uses,
+)

{sarj_python_lint-1.77.2 → sarj_python_lint-1.79.0}/src/sarj_python_lint/__main__.py

@@ -166,6 +166,7 @@ def analyze(
 
 _DIAGNOSTIC_PRECEDENCE = MappingProxyType(
     {
+        "SARJ020": frozenset({"SARJ437"}),
         "SARJ054": frozenset({"SARJ419"}),
         "SARJ448": frozenset({"SARJ419"}),
         "SARJ523": frozenset({"SARJ419"}),

{sarj_python_lint-1.77.2 → sarj_python_lint-1.79.0}/src/sarj_python_lint/_file_context.py

@@ -109,7 +109,7 @@ class PythonFileContext:
     def test_provenance(self) -> TestProvenance:
         from sarj_python_lint.rules._test_provenance import TestProvenance  # ruff: ignore[import-outside-top-level] — defer test analysis until requested
 
-        return TestProvenance(self)
+        return TestProvenance(self, borrow_context=True)
 
     def _valid_tree(self) -> ast.Module:
         tree = self.tree
@@ -122,7 +122,7 @@ class PythonFileContext:
     def copy_on_write(self) -> CopyOnWriteAnalysis:
         from sarj_python_lint.rules._copy_on_write import CopyOnWriteAnalysis  # ruff: ignore[import-outside-top-level] — share ownership analysis only when requested
 
-        return CopyOnWriteAnalysis(self)
+        return CopyOnWriteAnalysis(self, borrow_context=True)
 
     @cached_property
     def resource_provenance(self) -> ResourceProvenance:

sarj_python_lint-1.79.0/src/sarj_python_lint/application_logging.py

@@ -0,0 +1,379 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_PUBLIC_EMITTERS = frozenset({"debug", "info", "warning", "warn", "error", "exception", "critical", "fatal", "log"})
+_MODULE_EMITTERS = frozenset("logging." + name for name in _PUBLIC_EMITTERS)
+_LOGGER_FACTORIES = frozenset({"logging.getLogger", "logging.Logger"})
+_BUILTIN_SINKS = frozenset({"logging.StreamHandler", "logging.FileHandler"})
+_ROUTING_ATTRIBUTES = frozenset({"handlers", "filters", "level", "disabled", "propagate", "name"})
+_ROUTING_METHODS = frozenset(
+    {
+        "setLevel",
+        "addHandler",
+        "removeHandler",
+        "addFilter",
+        "removeFilter",
+        "isEnabledFor",
+        "getEffectiveLevel",
+        "hasHandlers",
+    }
+)
+_SCOPES = (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)
+_MAX_SOURCE_CHARACTERS = 500_000
+_MIN_ATTRIBUTE_MUTATION_ARGS = 2
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationLoggingUse:
+    line: int
+    column: int
+    operation: str
+    kind: Literal["event", "sink"]
+
+
+@dataclass(frozen=True, slots=True)
+class _ModuleImportState:
+    import_lines: dict[str, int]
+    star_import_line: int
+    module_names: frozenset[str]
+    root_names: frozenset[str]
+
+
+@dataclass(frozen=True, slots=True)
+class _LoggerBinding:
+    scope: ast.AST
+    name: str
+    assignment: ast.Assign | ast.AnnAssign
+
+
+def application_logging_uses(path: Path, source: str, *, root: Path) -> tuple[ApplicationLoggingUse, ...]:
+    from sarj_python_lint._file_context import PythonFileContext  # ruff: ignore[import-outside-top-level] -- load native AST helpers only when library policy selects Python source.
+    from sarj_python_lint.rules._paths import is_test_path  # ruff: ignore[import-outside-top-level] -- preserve the engine-owned test scope without cross-package private imports.
+
+    if not path.is_absolute() or not root.is_absolute() or ".." in path.parts or ".." in root.parts:
+        msg = "logging policy requires canonical absolute source and root paths"
+        raise ValueError(msg)
+    try:
+        relative = path.relative_to(root)
+    except ValueError as exc:
+        msg = "logging policy source escapes repository root"
+        raise ValueError(msg) from exc
+    if relative.suffix not in {".py", ".pyi"} or len(source) > _MAX_SOURCE_CHARACTERS:
+        msg = "logging policy requires a bounded selected Python source"
+        raise ValueError(msg)
+    if relative.suffix == ".pyi":
+        return ()
+    context = PythonFileContext(path, source)
+    if is_test_path(relative) or context.generated:
+        return ()
+    if context.tree is None:
+        msg = f"selected Python source could not be parsed: {path}"
+        raise ValueError(msg)
+    return _LoggingProvenance(context).uses()
+
+
+class _LoggingProvenance:
+    def __init__(self, context: PythonFileContext) -> None:
+        self.context = context
+        tree = context.tree
+        if tree is None:
+            msg = "logging provenance requires a parsed Python syntax tree"
+            raise ValueError(msg)
+        self.tree = tree
+        self.parents = context.parents
+        self.imports = context.imports
+        self.nodes = context.nodes(ast.AST)
+        self.import_state = self._module_import_state()
+        self.escaped_names = self._escaped_module_names()
+        self.mutated_operations: set[str] = set()
+        self._collect_mutations()
+        self.binding_counts: dict[tuple[ast.AST, str], int] = {}
+        self.binding_loads: dict[_LoggerBinding, list[ast.Name]] = {}
+        self.bindings = self._logger_bindings()
+
+    def uses(self) -> tuple[ApplicationLoggingUse, ...]:
+        findings = [use for call in self.context.nodes(ast.Call) if (use := self._call_use(call)) is not None]
+        return tuple(sorted(set(findings), key=lambda item: (item.line, item.column, item.operation)))
+
+    def _call_use(self, call: ast.Call) -> ApplicationLoggingUse | None:
+        qualified = self._qualified(call.func)
+        if qualified in _BUILTIN_SINKS:
+            return self._use(call, qualified, "sink")
+        if qualified == "logging.basicConfig" and self._uses_default_handlers(call):
+            return self._use(call, qualified, "sink")
+        if qualified in _MODULE_EMITTERS:
+            return self._use(call, qualified, "event")
+        if not isinstance(call.func, ast.Attribute) or call.func.attr not in _PUBLIC_EMITTERS:
+            return None
+        operation = "logging.Logger." + call.func.attr
+        if operation in self.mutated_operations or not self._logger_receiver(call.func.value):
+            return None
+        return self._use(call, operation, "event")
+
+    @staticmethod
+    def _uses_default_handlers(call: ast.Call) -> bool:
+        handlers = next((keyword.value for keyword in call.keywords if keyword.arg == "handlers"), None)
+        default_handlers = handlers is None or (isinstance(handlers, ast.Constant) and handlers.value is None)
+        return default_handlers and not any(keyword.arg is None for keyword in call.keywords)
+
+    def _use(self, call: ast.Call, operation: str, kind: Literal["event", "sink"]) -> ApplicationLoggingUse:
+        line = self.context.source_lines[call.lineno - 1]
+        column = len(line.encode("utf-8")[: call.col_offset].decode("utf-8")) + 1
+        return ApplicationLoggingUse(call.lineno, column, operation, kind)
+
+    def _scope(self, node: ast.AST) -> ast.AST:
+        current = self.parents.get(node)
+        while current is not None and not isinstance(current, _SCOPES):
+            current = self.parents.get(current)
+        return self.tree if current is None else current
+
+    def _module_import_state(self) -> _ModuleImportState:
+        lines: dict[str, int] = {}
+        star_line = 0
+        for statement in self.tree.body:
+            match statement:
+                case ast.Import():
+                    for alias in statement.names:
+                        lines[alias.asname or alias.name.partition(".")[0]] = statement.lineno
+                case ast.ImportFrom():
+                    for alias in statement.names:
+                        if alias.name == "*":
+                            star_line = max(star_line, statement.lineno)
+                        else:
+                            lines[alias.asname or alias.name] = statement.lineno
+                case _:
+                    pass
+        return _ModuleImportState(lines, star_line, self._logging_module_aliases(), self._logging_root_aliases())
+
+    def _logging_module_aliases(self) -> frozenset[str]:
+        return frozenset(
+            alias.asname or alias.name.partition(".")[0]
+            for statement in self.tree.body
+            if isinstance(statement, ast.Import)
+            for alias in statement.names
+            if alias.name == "logging" or alias.name.startswith("logging.")
+        )
+
+    def _logging_root_aliases(self) -> frozenset[str]:
+        return frozenset(
+            alias.asname or alias.name
+            for statement in self.tree.body
+            if isinstance(statement, ast.ImportFrom) and statement.level == 0 and statement.module == "logging"
+            for alias in statement.names
+            if alias.name == "root"
+        )
+
+    def _escaped_module_names(self) -> frozenset[str]:
+        module_names = self.import_state.module_names
+        root_names = self.import_state.root_names
+        imported_names = module_names | root_names
+        escaped: set[str] = set()
+        for node in self.context.nodes(ast.Name):
+            if node.id not in imported_names or not isinstance(node.ctx, ast.Load):
+                continue
+            parent = self.parents.get(node)
+            if not isinstance(parent, ast.Attribute):
+                escaped.add(node.id)
+                continue
+            if (node.id in module_names and parent.attr == "__dict__") or (
+                node.id in root_names and self._root_reference_escapes(parent)
+            ):
+                escaped.add(node.id)
+        escaped_targets = {
+            (target.module, target.symbol)
+            for name in escaped
+            if (target := self.imports.bindings.get(name)) is not None
+        }
+        return frozenset(
+            name
+            for name in imported_names
+            if name in escaped
+            or (
+                (target := self.imports.bindings.get(name)) is not None
+                and (target.module, target.symbol) in escaped_targets
+            )
+        )
+
+    def _root_reference_escapes(self, parent: ast.Attribute) -> bool:
+        if parent.attr not in _PUBLIC_EMITTERS | _ROUTING_METHODS:
+            return parent.attr not in _ROUTING_ATTRIBUTES
+        call = self.parents.get(parent)
+        return isinstance(parent.ctx, ast.Load) and (not isinstance(call, ast.Call) or call.func is not parent)
+
+    def _qualified(self, expression: ast.expr) -> str | None:
+        root = expression
+        while isinstance(root, ast.Attribute):
+            root = root.value
+        if not isinstance(root, ast.Name) or root.id in self.escaped_names:
+            return None
+        if self.import_state.import_lines.get(root.id, 0) <= self.import_state.star_import_line:
+            return None
+        name = self.imports.resolved_qualified_name(expression)
+        if name is None:
+            return None
+        parts = name.split(".")
+        if any(".".join(parts[:end]) in self.mutated_operations for end in range(1, len(parts) + 1)):
+            return None
+        return name
+
+    def _collect_mutations(self) -> None:
+        for node in self.context.nodes(ast.Attribute):
+            if node.attr == "__dict__" and (
+                self._factory_receiver(node.value) or self.imports.resolved_qualified_name(node.value) == "logging.root"
+            ):
+                self.mutated_operations.update("logging.Logger." + name for name in _PUBLIC_EMITTERS)
+            if isinstance(node.ctx, (ast.Store, ast.Del)):
+                self._record_attribute_mutation(node)
+        for call in self.context.nodes(ast.Call):
+            attribute = self._mutation_call_attribute(call)
+            if attribute is not None:
+                self._record_attribute_mutation(attribute)
+
+    def _record_attribute_mutation(self, attribute: ast.Attribute) -> None:
+        qualified = self._qualified(attribute)
+        if self._factory_receiver(attribute.value):
+            qualified = "logging.Logger." + attribute.attr
+        if qualified is not None:
+            self.mutated_operations.add(qualified)
+
+    def _mutation_call_attribute(self, call: ast.Call) -> ast.Attribute | None:
+        if not isinstance(call.func, ast.Name) or call.func.id not in {"setattr", "delattr"}:
+            return None
+        if not self.imports.builtin_is_unshadowed(call.func.id) or len(call.args) < _MIN_ATTRIBUTE_MUTATION_ARGS:
+            return None
+        name = call.args[1]
+        if not isinstance(name, ast.Constant) or not isinstance(name.value, str):
+            return None
+        return ast.Attribute(value=call.args[0], attr=name.value, ctx=ast.Load())
+
+    def _factory_receiver(self, expression: ast.expr) -> bool:
+        return (
+            isinstance(expression, ast.Call) and self._qualified(expression.func) in _LOGGER_FACTORIES
+        ) or self._qualified(expression) == "logging.root"
+
+    def _logger_bindings(self) -> dict[tuple[ast.AST, str], _LoggerBinding]:
+        assignments = self._index_bindings()
+        candidates: dict[tuple[ast.AST, str], _LoggerBinding] = {}
+        for binding in assignments:
+            if self._is_logger_binding(binding):
+                candidates[binding.scope, binding.name] = binding
+        self.bindings = candidates
+        self.binding_loads = {}
+        for node in self.context.nodes(ast.Name):
+            if isinstance(node.ctx, ast.Load) and (binding := self._binding(node)) is not None:
+                self.binding_loads.setdefault(binding, []).append(node)
+        return {key: binding for key, binding in candidates.items() if self._nonescaping(binding)}
+
+    def _index_bindings(self) -> list[_LoggerBinding]:
+        counts: dict[tuple[ast.AST, str], int] = {}
+        assignments: list[_LoggerBinding] = []
+        for node in self.nodes:
+            name = self._bound_name(node)
+            if name is not None:
+                key = (self._scope(node), name)
+                counts[key] = counts.get(key, 0) + 1
+            match node:
+                case ast.Global() | ast.Nonlocal():
+                    for name in node.names:
+                        counts[self._scope(node), name] = 2
+                case ast.Import() | ast.ImportFrom():
+                    for alias in node.names:
+                        local = alias.asname or alias.name.partition(".")[0]
+                        key = (self._scope(node), local)
+                        counts[key] = counts.get(key, 0) + 1
+                case _:
+                    pass
+            assignment = self._logger_assignment(node)
+            if assignment is not None:
+                assignments.append(assignment)
+        self.binding_counts = counts
+        return assignments
+
+    @staticmethod
+    def _bound_name(node: ast.AST) -> str | None:
+        match node:
+            case ast.Name(id=name, ctx=ast.Store() | ast.Del()):
+                return name
+            case ast.arg(arg=name):
+                return name
+            case (
+                ast.FunctionDef(name=name)
+                | ast.AsyncFunctionDef(name=name)
+                | ast.ClassDef(name=name)
+                | ast.ExceptHandler(name=name)
+                | ast.MatchAs(name=name)
+                | ast.MatchStar(name=name)
+            ):
+                return name
+            case ast.MatchMapping(rest=name):
+                return name
+            case _:
+                pass
+        return None
+
+    def _logger_assignment(self, node: ast.AST) -> _LoggerBinding | None:
+        match node:
+            case ast.Assign(targets=[ast.Name(id=name)]):
+                return _LoggerBinding(self._scope(node), name, node)
+            case ast.AnnAssign(target=ast.Name(id=name), value=value) if value is not None:
+                return _LoggerBinding(self._scope(node), name, node)
+            case _:
+                pass
+        return None
+
+    def _is_logger_binding(self, binding: _LoggerBinding) -> bool:
+        assignment = binding.assignment
+        if binding.scope is self.tree and assignment.lineno <= self.import_state.star_import_line:
+            return False
+        if self.binding_counts.get((binding.scope, binding.name)) != 1:
+            return False
+        if self.parents.get(assignment) is not binding.scope:
+            return False
+        return isinstance(assignment.value, ast.Call) and self._qualified(assignment.value.func) in _LOGGER_FACTORIES
+
+    def _binding(self, node: ast.Name) -> _LoggerBinding | None:
+        scope = self._scope(node)
+        origin = scope
+        while scope is not None:
+            if not (isinstance(scope, ast.ClassDef) and scope is not origin):
+                key = (scope, node.id)
+                if key in self.binding_counts:
+                    return self.bindings.get(key)
+            parent = self._scope(scope)
+            scope = None if parent is scope else parent
+        return None
+
+    def _nonescaping(self, binding: _LoggerBinding) -> bool:
+        for node in self.binding_loads.get(binding, ()):
+            parent = self.parents.get(node)
+            if not isinstance(parent, ast.Attribute):
+                return False
+            if parent.attr in _PUBLIC_EMITTERS:
+                call = self.parents.get(parent)
+                if not isinstance(parent.ctx, ast.Load) or not isinstance(call, ast.Call) or call.func is not parent:
+                    return False
+            elif parent.attr in _ROUTING_METHODS:
+                call = self.parents.get(parent)
+                if not isinstance(call, ast.Call) or call.func is not parent:
+                    return False
+            elif parent.attr not in _ROUTING_ATTRIBUTES:
+                return False
+        return True
+
+    def _logger_receiver(self, expression: ast.expr) -> bool:
+        if self._factory_receiver(expression):
+            return True
+        if isinstance(expression, ast.Name):
+            binding = self._binding(expression)
+            return binding is not None and binding.assignment.lineno < expression.lineno
+        return False

{sarj_python_lint-1.77.2 → sarj_python_lint-1.79.0}/src/sarj_python_lint/rules/_copy_on_write.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass, replace
 from functools import cached_property
 from types import MappingProxyType
 from typing import TYPE_CHECKING, final
+from weakref import ReferenceType, ref
 
 from sarj_python_lint._analysis_session import AnalysisSession
 from sarj_python_lint._file_context import PythonFileContext
@@ -359,8 +360,10 @@ def _contains_model(shape: _Shape) -> bool:
 
 @final
 class CopyOnWriteAnalysis:
-    def __init__(self, context: PythonFileContext) -> None:
-        self.context = context
+    def __init__(self, context: PythonFileContext, *, borrow_context: bool = False) -> None:
+        self._context: PythonFileContext | ReferenceType[PythonFileContext] = (
+            ref(context) if borrow_context else context
+        )
         self.models = _Models(context)
         self.mutations: list[Mutation] = []
         self.discarded: list[ast.Call] = []
@@ -374,6 +377,14 @@ class CopyOnWriteAnalysis:
         for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
             self._function(function)
 
+    @property
+    def context(self) -> PythonFileContext:
+        context = self._context() if isinstance(self._context, ReferenceType) else self._context
+        if context is None:
+            msg = "The copy-on-write file context has been released"
+            raise ReferenceError(msg)
+        return context
+
     @cached_property
     def _validator_provider(self) -> ResourceProvenance:
         return self.context.static_resource_provenance

{sarj_python_lint-1.77.2 → sarj_python_lint-1.79.0}/src/sarj_python_lint/rules/_nominal_project.py

@@ -100,21 +100,34 @@ 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]] = {}
+        self._sources: dict[tuple[Path, bool], dict[str, NominalSource]] = {}
+        self._scopes: dict[tuple[Path, bool], dict[str, NominalSource]] = {}
 
-    def sources(self, path: Path, first_party: FirstPartyFacts) -> dict[str, NominalSource]:
+    def sources(
+        self, path: Path, first_party: FirstPartyFacts, *, include_generated: bool = False
+    ) -> 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]
+        key = (owner, include_generated)
+        if key in self._scopes:
+            return self._scopes[key]
         distributions = self._accessible_distributions(owner, root)
-        sources = self._merge_sources(distributions)
-        self._scopes[owner] = sources
+        sources = self._merge_sources(distributions, include_generated=include_generated)
+        self._scopes[key] = sources
         return sources
 
+    def owns_source(self, path: Path, source: Path, first_party: FirstPartyFacts) -> bool:
+        owner = distribution_root(path, facts=first_party)
+        root = first_party.project_root(path)
+        target = distribution_root(source, facts=first_party)
+        if owner is None or root is None or target is None:
+            return False
+        # Source ownership also applies to generated wrappers; nominal inventories
+        # deliberately keep their separate generated-source exclusion.
+        return any(distribution.root == target for distribution in self._accessible_distributions(owner, root))
+
     def _accessible_distributions(self, owner: Path, root: Path) -> tuple[_Distribution, ...]:
         if root not in self._distributions:
             self._distributions[root] = tuple(
@@ -144,13 +157,16 @@ class NominalProjectFacts:
             )
         )
 
-    def _merge_sources(self, distributions: tuple[_Distribution, ...]) -> dict[str, NominalSource]:
+    def _merge_sources(
+        self, distributions: tuple[_Distribution, ...], *, include_generated: bool = False
+    ) -> 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():
+            key = (distribution.root, include_generated)
+            if key not in self._sources:
+                self._sources[key] = _sources(distribution.root, include_generated=include_generated)
+            for module, source in self._sources[key].items():
                 if module in sources:
                     ambiguous.add(module)
                 sources[module] = source
@@ -234,7 +250,7 @@ def _files(root: Path, pattern: str) -> list[Path]:
     return found
 
 
-def _sources(root: Path) -> dict[str, NominalSource]:
+def _sources(root: Path, *, include_generated: bool = False) -> dict[str, NominalSource]:
     sources: dict[str, NominalSource] = {}
     ambiguous: set[str] = set()
     total_bytes = 0
@@ -248,7 +264,7 @@ def _sources(root: Path) -> dict[str, NominalSource]:
         module = _module_name(root, path)
         if not module:
             continue
-        source = _source(path)
+        source = _source(path, include_generated=include_generated)
         if source is None:
             continue
         if module in sources:
@@ -268,12 +284,12 @@ def _module_name(root: Path, path: Path) -> str | None:
     return ".".join(parts[:-1] if parts[-1] == "__init__.py" else (*parts[:-1], path.stem)) or None
 
 
-def _source(path: Path) -> NominalSource | None:
+def _source(path: Path, *, include_generated: bool = False) -> NominalSource | None:
     try:
         if path.is_symlink() or path.stat().st_size > _MAX_BYTES:
             return None
         text = read_python_source(path)
-        if is_generated(path, text):
+        if not include_generated and is_generated(path, text):
             return None
     except OSError, UnicodeError, SyntaxError:
         return None