sarj-python-lint 0.70.1__tar.gz → 0.72.0__tar.gz

{sarj_python_lint-0.70.1 → sarj_python_lint-0.72.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.70.1
+Version: 0.72.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-0.70.1 → sarj_python_lint-0.72.0}/pyproject.toml

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

{sarj_python_lint-0.70.1 → sarj_python_lint-0.72.0}/src/sarj_python_lint/__main__.py

@@ -9,12 +9,14 @@ import json
 from pathlib import Path
 import sys
 from types import MappingProxyType
+from typing import NamedTuple
 
 from sarj_python_lint import __version__
 from sarj_python_lint._filesystem import atomic_write_text
-from sarj_python_lint.rule_base import Diagnostic, Severity, is_suppressed
+from sarj_python_lint.rule_base import Diagnostic, ProjectRule, Severity, is_suppressed
 from sarj_python_lint.rules import REGISTRY
 from sarj_python_lint.rules._paths import clear_path_caches
+from sarj_python_lint.rules._project_index import ProjectIndexSet
 
 
 SKIP_DIR_NAMES = frozenset(
@@ -79,12 +81,19 @@ def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
     rules = [REGISTRY[rid]() for rid in rule_ids]
     clear_path_caches()
     expanded = _expand_paths(paths)
-    diags: list[Diagnostic] = []
-    for p in expanded:
+    loaded: dict[Path, str] = {}
+    for path in expanded:
         try:
-            source = p.read_text(encoding="utf-8", errors="replace")
+            loaded[path] = path.read_text(encoding="utf-8", errors="replace")
         except OSError:
             continue
+    project_rules = [rule for rule in rules if isinstance(rule, ProjectRule)]
+    if project_rules:
+        indexes = ProjectIndexSet.build(expanded, loaded)
+        for rule in project_rules:
+            rule.prepare(indexes)
+    diags: list[Diagnostic] = []
+    for p, source in loaded.items():
         source_lines = source.splitlines()
         raw = [diagnostic for rule in rules for diagnostic in rule.check(p, source)]
         diags.extend(
@@ -120,6 +129,11 @@ _DIAGNOSTIC_PRECEDENCE = MappingProxyType(
 )
 
 
+class _OwnerLocation(NamedTuple):
+    line: int
+    column: int
+
+
 def deduplicate_diagnostics(diags: list[Diagnostic], *, source: str | None = None) -> list[Diagnostic]:
     """Keep the most specific remediation at a source location."""
     codes = frozenset(diagnostic.code for diagnostic in diags)
@@ -130,15 +144,17 @@ def deduplicate_diagnostics(diags: list[Diagnostic], *, source: str | None = Non
         _function_signature_owner_locations(source) if source is not None and needs_signature_owners else {}
     )
 
-    def owner_location(diagnostic: Diagnostic) -> tuple[int, int]:
+    def owner_location(diagnostic: Diagnostic) -> _OwnerLocation:
         if diagnostic.code in {"SARJ034", "SARJ093"}:
-            return signature_owners.get(diagnostic.line, (diagnostic.line, diagnostic.col))
-        return docstring_owners.get(diagnostic.line, (diagnostic.line, diagnostic.col))
+            line, column = signature_owners.get(diagnostic.line, (diagnostic.line, diagnostic.col))
+        else:
+            line, column = docstring_owners.get(diagnostic.line, (diagnostic.line, diagnostic.col))
+        return _OwnerLocation(line, column)
 
     present: dict[tuple[Path, int, int], dict[str, set[Severity]]] = {}
     for diagnostic in diags:
-        line, col = owner_location(diagnostic)
-        by_code = present.setdefault((diagnostic.path, line, col), {})
+        location = owner_location(diagnostic)
+        by_code = present.setdefault((diagnostic.path, location.line, location.column), {})
         by_code.setdefault(diagnostic.code, set()).add(diagnostic.severity)
     suppressed = {
         (location, generic, generic_severity)
@@ -156,7 +172,8 @@ def deduplicate_diagnostics(diags: list[Diagnostic], *, source: str | None = Non
             (
                 (
                     diagnostic.path,
-                    *owner_location(diagnostic),
+                    owner_location(diagnostic).line,
+                    owner_location(diagnostic).column,
                 ),
                 diagnostic.code,
                 diagnostic.severity,

{sarj_python_lint-0.70.1 → sarj_python_lint-0.72.0}/src/sarj_python_lint/rule_base.py

@@ -14,6 +14,8 @@ from typing import TYPE_CHECKING, ClassVar, Final, Self
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
+    from sarj_python_lint.rules._project_index import ProjectIndexSet
+
 
 # Each rule points directly to its executable examples.
 REPO_BLOB: Final = "https://github.com/sarj-ai/standards/blob/main"
@@ -309,6 +311,16 @@ class Rule(ABC):
         return () if spec is None else spec.public_examples
 
 
+class ProjectRule(Rule):
+    """A rule that may resolve first-party symbols prepared once per CLI run."""
+
+    _project_indexes: ProjectIndexSet | None = None
+
+    def prepare(self, indexes: ProjectIndexSet) -> None:
+        """Attach immutable project symbols before checking the selected files."""
+        self._project_indexes = indexes
+
+
 _last_parse: tuple[str, str, ast.Module | None] | None = None
 
 

{sarj_python_lint-0.70.1 → sarj_python_lint-0.72.0}/src/sarj_python_lint/rules/_comments.py

@@ -314,15 +314,21 @@ class _CommentScan[T](NamedTuple):
     first_code_line: int
 
 
-_Scan = tuple[list[tuple[int, int, str]], list[tuple[int, int, str]], set[int], int, _Ordered]
+class _Scan(NamedTuple):
+    standalone: list[tuple[int, int, str]]
+    trailing: list[tuple[int, int, str]]
+    nested: set[int]
+    first_code_line: int
+    ordered: _Ordered
+
 
 _last_scan: tuple[str, _Scan] | None = None
 
 
 def all_comments(source: str) -> _CommentScan[_Ordered]:
     """Return every comment as `(line, col0, body, standalone)`, plus the first code line."""
-    _, _, _, first_code_line, ordered = _scan_memo(source)
-    return _CommentScan(ordered, first_code_line)
+    scan = _scan_memo(source)
+    return _CommentScan(scan.ordered, scan.first_code_line)
 
 
 def _scan_memo(source: str) -> _Scan:
@@ -361,23 +367,23 @@ def _scan(source: str) -> _Scan:
             prev_end_row = tok.end[0]
         if tok.type not in _NON_CODE_TOKENS:
             first_code_line = min(first_code_line, tok.start[0])
-    return standalone, trailing, nested, first_code_line, ordered
+    return _Scan(standalone, trailing, nested, first_code_line, ordered)
 
 
 def trailing_comments(source: str) -> list[tuple[int, int, str]]:
     """Return every comment that shares its line with code, as `(line, col, body)`."""
-    return _scan_memo(source)[1]
+    return _scan_memo(source).trailing
 
 
 def nested_comment_lines(source: str) -> set[int]:
     """Return the lines of comments sitting INSIDE a bracketed expression."""
-    return _scan_memo(source)[2]
+    return _scan_memo(source).nested
 
 
 def standalone_comments(source: str) -> _CommentScan[list[tuple[int, int, str]]]:
     """Return every own-line comment as `(line, col, body)`, plus the first code line."""
-    standalone, _, _, first_code_line, _ = _scan_memo(source)
-    return _CommentScan(standalone, first_code_line)
+    scan = _scan_memo(source)
+    return _CommentScan(scan.standalone, scan.first_code_line)
 
 
 def comment_runs(standalone: Sequence[tuple[int, int, str]]) -> list[list[tuple[int, int, str]]]:

{sarj_python_lint-0.70.1 → sarj_python_lint-0.72.0}/src/sarj_python_lint/rules/_fastapi.py

@@ -74,6 +74,16 @@ class ParameterMarker(NamedTuple):
     call: ast.Call
 
 
+class _ReceiverKey(NamedTuple):
+    scope: int
+    name: str
+
+
+class _DecoratorBinding(NamedTuple):
+    receiver: str
+    method: str
+
+
 @dataclass(frozen=True, slots=True)
 class _ImportedReference:
     module: str
@@ -113,12 +123,12 @@ class FastapiIndex:
         self.annotated: set[str] = set()
         self.symbols: dict[str, str] = {}
         self.type_aliases: dict[str, ast.expr] = {}
-        self.receivers: set[tuple[int, str]] = set()
-        self.receiver_origins: dict[tuple[int, str], tuple[int, str]] = {}
-        self.receiver_kinds: dict[tuple[int, str], Literal["FastAPI", "APIRouter"]] = {}
-        self.hidden_receivers: set[tuple[int, str]] = set()
-        self.decorators: dict[tuple[int, str], tuple[str, str]] = {}
-        self.bound_names: set[tuple[int, str]] = set()
+        self.receivers: set[_ReceiverKey] = set()
+        self.receiver_origins: dict[_ReceiverKey, _ReceiverKey] = {}
+        self.receiver_kinds: dict[_ReceiverKey, Literal["FastAPI", "APIRouter"]] = {}
+        self.hidden_receivers: set[_ReceiverKey] = set()
+        self.decorators: dict[_ReceiverKey, _DecoratorBinding] = {}
+        self.bound_names: set[_ReceiverKey] = set()
         self._node_scopes: dict[int, int] = {}
         self._node_classes: dict[int, int | None] = {}
         self._route_scopes: dict[int, int] = {}
@@ -182,31 +192,37 @@ class FastapiIndex:
         assignments: list[tuple[int, str, ast.expr]] = []
         for node in ast.walk(tree):
             if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-                self.bound_names.add((self._node_scopes[id(node)], node.name))
+                self.bound_names.add(_ReceiverKey(self._node_scopes[id(node)], node.name))
                 arguments = [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs]
                 if node.args.vararg is not None:
                     arguments.append(node.args.vararg)
                 if node.args.kwarg is not None:
                     arguments.append(node.args.kwarg)
-                self.bound_names.update((node.lineno, argument.arg) for argument in arguments)
+                self.bound_names.update(_ReceiverKey(node.lineno, argument.arg) for argument in arguments)
             elif isinstance(node, ast.ClassDef):
-                self.bound_names.add((self._node_scopes[id(node)], node.name))
+                self.bound_names.add(_ReceiverKey(self._node_scopes[id(node)], node.name))
             elif isinstance(node, (ast.Import, ast.ImportFrom)):
                 self.bound_names.update(
-                    (self._node_scopes[id(node)], alias.asname or alias.name.split(".")[0]) for alias in node.names
+                    _ReceiverKey(self._node_scopes[id(node)], alias.asname or alias.name.split(".")[0])
+                    for alias in node.names
                 )
             elif isinstance(node, (ast.For, ast.AsyncFor)):
-                self.bound_names.update((self._node_scopes[id(node)], name) for name in self._target_names(node.target))
+                self.bound_names.update(
+                    _ReceiverKey(self._node_scopes[id(node)], name) for name in self._target_names(node.target)
+                )
             elif isinstance(node, ast.With):
                 for item in node.items:
                     if item.optional_vars is not None:
                         self.bound_names.update(
-                            (self._node_scopes[id(node)], name) for name in self._target_names(item.optional_vars)
+                            _ReceiverKey(self._node_scopes[id(node)], name)
+                            for name in self._target_names(item.optional_vars)
                         )
             elif isinstance(node, ast.ExceptHandler) and node.name is not None:
-                self.bound_names.add((self._node_scopes[id(node)], node.name))
+                self.bound_names.add(_ReceiverKey(self._node_scopes[id(node)], node.name))
             elif isinstance(node, ast.NamedExpr):
-                self.bound_names.update((self._node_scopes[id(node)], name) for name in self._target_names(node.target))
+                self.bound_names.update(
+                    _ReceiverKey(self._node_scopes[id(node)], name) for name in self._target_names(node.target)
+                )
             if isinstance(node, ast.Assign) and len(node.targets) == 1:
                 name = _binding_name(node.targets[0])
                 if name:
@@ -219,12 +235,12 @@ class FastapiIndex:
                 assignments.append((self._node_scopes[id(node)], node.name.id, node.value))
 
         changed = True
-        counts = Counter((scope, name) for scope, name, _value in assignments)
+        counts = Counter(_ReceiverKey(scope, name) for scope, name, _value in assignments)
         self.bound_names.update(counts)
         while changed:
             changed = False
             for scope, name, value in assignments:
-                key = (scope, name)
+                key = _ReceiverKey(scope, name)
                 if counts[key] != 1:
                     continue
                 if key in self.receivers or key in self.decorators:
@@ -250,7 +266,7 @@ class FastapiIndex:
                 if isinstance(value, ast.Attribute) and value.attr in HTTP_METHODS:
                     receiver = _binding_name(value.value)
                     if self._receiver_key(scope, receiver) is not None:
-                        self.decorators[key] = (receiver, value.attr)
+                        self.decorators[key] = _DecoratorBinding(receiver, value.attr)
                         changed = True
                         continue
                 if self._is_annotated(value) or (isinstance(value, ast.Name) and value.id in self.type_aliases):
@@ -268,12 +284,12 @@ class FastapiIndex:
             return self._node_classes[id(node)] or self._node_scopes[id(node)]
         return self._node_scopes[id(node)]
 
-    def _receiver_key(self, scope: int, name: str) -> tuple[int, str] | None:
+    def _receiver_key(self, scope: int, name: str) -> _ReceiverKey | None:
         if not name:
             return None
         current: int | None = scope
         while current is not None:
-            binding = (current, name)
+            binding = _ReceiverKey(current, name)
             if binding in self.receivers:
                 return binding
             if binding in self.bound_names:
@@ -325,7 +341,8 @@ class FastapiIndex:
                 if receiver_key is not None:
                     method = decorator.func.attr
             elif isinstance(decorator.func, ast.Name) and (resolved := self._decorator(scope, decorator.func.id)):
-                receiver, method = resolved
+                receiver = resolved.receiver
+                method = resolved.method
                 receiver_key = self._receiver_key(scope, receiver)
             if method not in HTTP_METHODS or receiver_key is None:
                 continue
@@ -336,11 +353,11 @@ class FastapiIndex:
             )
             path = path_node.value if isinstance(path_node, ast.Constant) and isinstance(path_node.value, str) else None
             route_methods = self._route_methods(decorator) if method == "api_route" else (method,)
-            origin_scope, origin_name = self.receiver_origins[receiver_key]
+            origin = self.receiver_origins[receiver_key]
             routes.extend(
                 Route(
                     decorator=decorator,
-                    receiver=f"{origin_scope}:{origin_name}",
+                    receiver=f"{origin.scope}:{origin.name}",
                     method=route_method,
                     path=path,
                     receiver_kind=self.receiver_kinds[receiver_key],
@@ -350,10 +367,10 @@ class FastapiIndex:
             )
         return tuple(routes)
 
-    def _decorator(self, scope: int, name: str) -> tuple[str, str] | None:
+    def _decorator(self, scope: int, name: str) -> _DecoratorBinding | None:
         current: int | None = scope
         while current is not None:
-            binding = (current, name)
+            binding = _ReceiverKey(current, name)
             if binding in self.decorators:
                 return self.decorators[binding]
             if binding in self.bound_names:
@@ -473,7 +490,7 @@ class FastapiIndex:
         # it, so begin with that function's parent scope.
         scope: int | None = self._scope_parents.get(node_scope)
         while scope is not None and scope != 0:
-            if (scope, root) in self.bound_names:
+            if _ReceiverKey(scope, root) in self.bound_names:
                 return True
             scope = self._scope_parents.get(scope)
         return False

{sarj_python_lint-0.70.1 → sarj_python_lint-0.72.0}/src/sarj_python_lint/rules/_first_party.py

@@ -126,6 +126,11 @@ def has_first_party_source(module: str, path: Path) -> bool:
     )
 
 
+def project_root(path: Path) -> Path | None:
+    """Return the conservative repository/workspace root used by project-aware rules."""
+    return _project_root(path)
+
+
 def _declares_module(package_dir: Path, segments: list[str]) -> bool:
     target = package_dir.joinpath(*segments)
     try: