sarj-python-lint 0.88.0__tar.gz → 1.1.1__tar.gz

{sarj_python_lint-0.88.0 → sarj_python_lint-1.1.1}/.gitignore

@@ -1,4 +1,4 @@
-node_modules/
+node_modules
 .astro/
 dist/
 build/

{sarj_python_lint-0.88.0 → sarj_python_lint-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 0.88.0
+Version: 1.1.1
 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/
@@ -19,6 +19,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.14
 Requires-Dist: packaging==26.3
 Requires-Dist: ruff>=0.16.8
+Requires-Dist: sarj-rule-contracts==0.1.0
 Requires-Dist: sqlglot==30.19.0
 Requires-Dist: typer==0.27.2
 Description-Content-Type: text/markdown

{sarj_python_lint-0.88.0 → sarj_python_lint-1.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.88.0"
+version = "1.1.1"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
@@ -15,7 +15,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Quality Assurance",
 ]
-dependencies = ["packaging==26.3", "ruff>=0.16.8", "sqlglot==30.19.0", "typer==0.27.2"]
+dependencies = ["sarj-rule-contracts==0.1.0", "packaging==26.3", "ruff>=0.16.8", "sqlglot==30.19.0", "typer==0.27.2"]
 
 [project.scripts]
 sarj-python-lint = "sarj_python_lint.__main__:main"
@@ -69,3 +69,6 @@ extend = "../../.ruff-strict.toml"
 # Ruff is invoked at runtime through `sys.executable -m ruff`, which Deptry's
 # import analysis cannot observe.
 DEP002 = ["ruff"]
+
+[tool.uv.sources]
+sarj-rule-contracts = { path = "../contracts", editable = true }

{sarj_python_lint-0.88.0 → sarj_python_lint-1.1.1}/src/sarj_python_lint/__main__.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import ast
 from collections import Counter
 from dataclasses import dataclass
+from fnmatch import fnmatch
 import json
 from pathlib import Path
 import sys
@@ -13,6 +14,7 @@ import typer
 
 from sarj_python_lint import __version__
 from sarj_python_lint._analysis_session import AnalysisSession
+from sarj_python_lint._file_context import PythonFileContext
 from sarj_python_lint._filesystem import atomic_write_text
 from sarj_python_lint.json_boundary import is_object_mapping, parse_json
 from sarj_python_lint.rule_base import Diagnostic, ProjectRule, Rule, Severity, is_suppressed
@@ -47,7 +49,7 @@ SKIP_DIR_NAMES = frozenset(
 _MAX_FILE_BYTES = 500_000
 
 
-def _expand_paths(paths: list[Path]) -> list[Path]:
+def expand_paths(paths: list[Path]) -> list[Path]:
     out: list[Path] = []
     for p in paths:
         if not p.exists():
@@ -65,19 +67,21 @@ def _expand_paths(paths: list[Path]) -> list[Path]:
 
 
 def _python_files(p: Path) -> list[Path]:
+    if not SKIP_DIR_NAMES.isdisjoint(p.parts):
+        return []
     out: list[Path] = []
-    for child in p.rglob("*.py"):
-        if not child.is_file():
-            continue
-        if any(part in SKIP_DIR_NAMES for part in child.parts):
-            continue
-        try:
-            if child.stat().st_size > _MAX_FILE_BYTES:
+    for directory, directories, filenames in p.walk():
+        directories[:] = [name for name in directories if name not in SKIP_DIR_NAMES]
+        for name in filenames:
+            if not fnmatch(name, "*.py"):
                 continue
-        except OSError:
-            continue
-        out.append(child)
-    return out
+            child = directory / name
+            try:
+                if child.is_file() and child.stat().st_size <= _MAX_FILE_BYTES:
+                    out.append(child)
+            except OSError:
+                continue
+    return sorted(out)
 
 
 def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
@@ -91,7 +95,7 @@ def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
     for rule in rules:
         rule.prepare_session(session)
     clear_path_caches()
-    expanded = _expand_paths(paths)
+    expanded = expand_paths(paths)
     loaded: dict[Path, str] = {}
     for path in expanded:
         try:
@@ -101,17 +105,21 @@ def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
     project_rules = [rule for rule in rules if isinstance(rule, ProjectRule)]
     if project_rules:
         indexes = ProjectIndexSet.build(expanded, loaded, facts=session.first_party)
+        session.project = indexes
         for rule in project_rules:
             rule.prepare(indexes)
     diags: list[Diagnostic] = []
     for p, source in loaded.items():
-        diags.extend(_check_source(rules, p, source))
+        diags.extend(check_source(rules, p, source, session=session))
     return diags
 
 
-def _check_source(rules: list[Rule], p: Path, source: str) -> list[Diagnostic]:
-    source_lines = source.splitlines()
-    raw = [diagnostic for rule in rules for diagnostic in rule.check(p, source)]
+def check_source(
+    rules: list[Rule], p: Path, source: str, *, session: AnalysisSession | None = None
+) -> list[Diagnostic]:
+    context = PythonFileContext(p, source, session)
+    source_lines = context.source_lines
+    raw = [diagnostic for rule in rules for diagnostic in rule.check_context(context)]
     return deduplicate_diagnostics(
         [
             diagnostic

{sarj_python_lint-0.88.0 → sarj_python_lint-1.1.1}/src/sarj_python_lint/_analysis_session.py

@@ -1,13 +1,18 @@
 from __future__ import annotations
 
-from typing import final
+from typing import TYPE_CHECKING, final
 
 from sarj_python_lint._python_target import PythonTargetFacts
 from sarj_python_lint.rules._first_party import FirstPartyFacts
 
 
+if TYPE_CHECKING:
+    from sarj_python_lint.rules._project_index import ProjectIndexSet
+
+
 @final
 class AnalysisSession:
     def __init__(self) -> None:
+        self.project: ProjectIndexSet | None = None
         self.first_party = FirstPartyFacts()
         self.python_target = PythonTargetFacts()

sarj_python_lint-1.1.1/src/sarj_python_lint/_file_context.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import ast
+from functools import cached_property
+from typing import TYPE_CHECKING, final
+
+from sarj_python_lint._analysis_session import AnalysisSession
+from sarj_python_lint.rules._ast_index import NodeIndex
+from sarj_python_lint.rules._fastapi import FastapiIndex
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+
+@final
+class PythonFileContext:
+    def __init__(self, path: Path, source: str, session: AnalysisSession | None = None) -> None:
+        self.path = path
+        self.source = source
+        self.session = session if session is not None else AnalysisSession()
+
+    @cached_property
+    def tree(self) -> ast.Module | None:
+        if self.session.project is not None:
+            unit = self.session.project.unit(self.path)
+            if unit is not None and unit.source == self.source:
+                return unit.tree
+        try:
+            return ast.parse(self.source, filename=str(self.path))
+        except SyntaxError:
+            return None
+
+    @cached_property
+    def source_lines(self) -> list[str]:
+        return self.source.splitlines()
+
+    @cached_property
+    def generated(self) -> bool:
+        return is_generated(self.path, self.source)
+
+    @cached_property
+    def node_index(self) -> NodeIndex:
+        return NodeIndex(self._valid_tree())
+
+    def nodes[NodeT: ast.AST](self, *types: type[NodeT]) -> list[NodeT]:
+        return [node for node in self.node_index.query(types) if isinstance(node, types)]
+
+    @property
+    def parents(self) -> Mapping[ast.AST, ast.AST]:
+        return self.node_index.parents
+
+    @cached_property
+    def imports(self) -> ImportIndex:
+        return ImportIndex.from_tree(self._valid_tree())
+
+    @cached_property
+    def module_imports(self) -> ImportIndex:
+        return ImportIndex.from_tree(self._valid_tree(), module_scope_only=True)
+
+    @cached_property
+    def fastapi(self) -> FastapiIndex:
+        return FastapiIndex(self._valid_tree(), path=self.path)
+
+    def _valid_tree(self) -> ast.Module:
+        tree = self.tree
+        if tree is None:
+            msg = "syntax-dependent facts require a successfully parsed source file"
+            raise ValueError(msg)
+        return tree

sarj_python_lint-1.1.1/src/sarj_python_lint/benchmark.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import hashlib
+import json
+from os.path import commonpath
+from pathlib import Path
+from statistics import median
+import sys
+from time import perf_counter
+from typing import Annotated
+
+import typer
+
+from sarj_python_lint.__main__ import analyze, expand_paths
+from sarj_python_lint.rules import REGISTRY
+
+
+@dataclass(frozen=True, slots=True)
+class BenchmarkSample:
+    seconds: float
+    diagnostics: int
+    diagnostic_digest: str
+    peak_memory_bytes: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class BenchmarkReport:
+    files: int
+    source_bytes: int
+    source_digest: str
+    rules: tuple[str, ...]
+    samples: tuple[BenchmarkSample, ...]
+    median_seconds: float
+
+
+def peak_memory_bytes() -> int | None:
+    try:
+        import resource  # ruff: ignore[import-outside-top-level] — optional Unix-only memory instrumentation.
+    except ImportError:
+        return None
+    peak = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    return peak if sys.platform == "darwin" else peak * 1024
+
+
+def measure(paths: list[Path], rule_ids: list[str] | None = None, *, repeats: int = 5) -> BenchmarkReport:
+    if repeats < 1:
+        msg = "repeats must be positive"
+        raise ValueError(msg)
+    selected = sorted(REGISTRY) if rule_ids is None else sorted(rule_ids)
+    unknown = sorted(set(selected) - REGISTRY.keys())
+    if unknown:
+        msg = f"unknown rule(s): {', '.join(unknown)}"
+        raise ValueError(msg)
+    expanded = sorted(set(expand_paths(paths)))
+    if not expanded:
+        msg = "benchmark requires at least one Python source file"
+        raise ValueError(msg)
+    corpus_root = Path(commonpath([path.absolute().parent for path in expanded]))
+    source_digest = hashlib.sha256()
+    source_bytes = 0
+    for path in expanded:
+        source = path.read_bytes()
+        source_bytes += len(source)
+        source_digest.update(str(path.absolute().relative_to(corpus_root)).encode())
+        source_digest.update(b"\0")
+        source_digest.update(source)
+        source_digest.update(b"\0")
+    samples: list[BenchmarkSample] = []
+    for _ in range(repeats):
+        start = perf_counter()
+        diagnostics = analyze(selected, expanded)
+        elapsed = perf_counter() - start
+        digest = hashlib.sha256()
+        for diagnostic in diagnostics:
+            digest.update(
+                json.dumps(
+                    [
+                        str(diagnostic.path.absolute().relative_to(corpus_root)),
+                        diagnostic.line,
+                        diagnostic.col,
+                        diagnostic.code,
+                        diagnostic.message,
+                        diagnostic.severity.value,
+                        diagnostic.column_encoding.value,
+                    ],
+                    ensure_ascii=False,
+                ).encode()
+            )
+            digest.update(b"\n")
+        samples.append(BenchmarkSample(elapsed, len(diagnostics), digest.hexdigest(), peak_memory_bytes()))
+    if len({sample.diagnostic_digest for sample in samples}) != 1:
+        msg = "diagnostics changed between benchmark repetitions"
+        raise RuntimeError(msg)
+    return BenchmarkReport(
+        len(expanded),
+        source_bytes,
+        source_digest.hexdigest(),
+        tuple(selected),
+        tuple(samples),
+        median(sample.seconds for sample in samples),
+    )
+
+
+def _run(
+    paths: Annotated[list[Path], typer.Argument(help="Python files or directories to analyze.")],
+    repeats: Annotated[int, typer.Option(min=1)] = 5,
+    rule: Annotated[list[str] | None, typer.Option(help="Repeat to select rules; defaults to all rules.")] = None,
+) -> None:
+    try:
+        report = measure(paths, rule, repeats=repeats)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    typer.echo(json.dumps(asdict(report), indent=2))
+
+
+if __name__ == "__main__":
+    typer.run(_run)

sarj_python_lint-1.1.1/src/sarj_python_lint/rule_base.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+import ast
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+import re
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from sarj_rule_contracts import (
+    AutofixPolicy as AutofixPolicy,
+    ExampleFile as ExampleFile,
+    ExampleOutcome as ExampleOutcome,
+    NativeRuleSpec as NativeRuleSpec,
+    RuleCategory as RuleCategory,
+    RuleDocumentation as RuleDocumentation,
+    RuleExample as RuleExample,
+    Severity as Severity,
+)
+
+from sarj_python_lint._python_target import PythonTargetFacts
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from sarj_python_lint._analysis_session import AnalysisSession
+    from sarj_python_lint._file_context import PythonFileContext
+    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/code-standards/blob/main"
+TESTS_DIR: Final = "packages/python/tests/rules"
+
+
+# Keep SARJ suppressions separate because Ruff removes unknown `noqa` codes.
+_SARJ_NOQA_RE = re.compile(
+    r"#\s*sarj-noqa(?::\s*([A-Za-z0-9_, ]+))?",
+    re.IGNORECASE,
+)
+
+
+def is_suppressed(source_lines: Sequence[str], line: int, code: str) -> bool:
+    if line < 1 or line > len(source_lines):
+        return False
+    text = source_lines[line - 1]
+    m = _SARJ_NOQA_RE.search(text)
+    if not m:
+        return False
+    codes_str = m.group(1)
+    if not codes_str:
+        # A bare sarj-noqa intentionally suppresses every SARJ code on its line.
+        return True
+    codes = {val.upper() for c in codes_str.split(",") if (val := c.strip())}
+    return code.upper() in codes
+
+
+class ColumnEncoding(StrEnum):
+    UTF8_BYTES = "utf8-bytes"
+    CODEPOINTS = "codepoints"
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    path: Path
+    line: int
+    col: int
+    code: str
+    message: str
+    severity: Severity = Severity.ERROR
+    column_encoding: ColumnEncoding = ColumnEncoding.UTF8_BYTES
+
+    def format(self) -> str:
+        label = "warning: " if self.severity is Severity.WARNING else ""
+        return f"{self.path}:{self.line}:{self.col}: {self.code} {label}{self.message}"
+
+
+class Rule(ABC):
+    id: str
+    code: str
+    description: str
+    documentation: ClassVar[RuleDocumentation | None] = None
+    _analysis_session: AnalysisSession | None = None
+
+    def prepare_session(self, session: AnalysisSession) -> None:
+        self._analysis_session = session
+
+    def has_declared_python_support_before(self, path: Path, minimum: tuple[int, int]) -> bool:
+        facts = self._analysis_session.python_target if self._analysis_session is not None else PythonTargetFacts()
+        return facts.has_declared_support_before(path, minimum)
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        from sarj_python_lint._file_context import PythonFileContext  # ruff: ignore[import-outside-top-level] — avoids registry import cycle
+
+        context = PythonFileContext(path, source, self._analysis_session)
+        if isinstance(self, ProjectRule):
+            context.session.project = self.project_indexes
+        return self.check_context(context)
+
+    @abstractmethod
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        raise NotImplementedError
+
+    @classmethod
+    def examples_path(cls) -> str:
+        return f"{TESTS_DIR}/test_{cls.__module__.rpartition('.')[2]}.py"
+
+    @classmethod
+    def examples_url(cls) -> str:
+        return f"{REPO_BLOB}/{cls.examples_path()}"
+
+    @classmethod
+    def native_spec(cls) -> NativeRuleSpec | None:
+        authored = cls.documentation
+        if authored is None:
+            return None
+        if cls.id in authored.aliases:
+            msg = f"{cls.id}: a live rule ID cannot also be a historical alias"
+            raise ValueError(msg)
+        if authored.summary != cls.description:
+            msg = f"{cls.id}: description must be the authored documentation summary"
+            raise ValueError(msg)
+        return NativeRuleSpec(
+            engine="python",
+            rule_id=cls.id,
+            code=cls.code,
+            summary=authored.summary,
+            rationale=authored.rationale,
+            remediation=authored.remediation,
+            category=authored.category,
+            default_level=authored.default_level,
+            autofix=authored.autofix,
+            aliases=authored.aliases,
+            limitations=authored.limitations,
+            examples=authored.examples,
+        )
+
+    @classmethod
+    def public_examples(cls) -> tuple[RuleExample, ...]:
+        spec = cls.native_spec()
+        return () if spec is None else spec.public_examples
+
+
+class ProjectRule(Rule, ABC):
+    project_indexes: ProjectIndexSet | None = None
+
+    def prepare(self, indexes: ProjectIndexSet) -> None:
+        self.project_indexes = indexes
+
+
+def parse_or_none(path: Path, source: str) -> ast.Module | None:
+    try:
+        tree = ast.parse(source, filename=str(path))
+    except SyntaxError:
+        tree = None
+    return tree

{sarj_python_lint-0.88.0 → sarj_python_lint-1.1.1}/src/sarj_python_lint/rules/_ast_index.py

@@ -3,11 +3,12 @@
 from __future__ import annotations
 
 import ast
+from types import MappingProxyType
 from typing import TYPE_CHECKING, TypeIs, final
 
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Mapping
 
 
 _AST = ast.AST
@@ -28,7 +29,10 @@ def children(node: ast.AST) -> list[ast.AST]:
     return out
 
 
-def walk(node: ast.AST) -> Iterator[ast.AST]:
+def walk(node: ast.AST, *, index: NodeIndex | None = None) -> Iterator[ast.AST]:
+    if index is not None and index.tree is node:
+        yield from index.query((ast.AST,))
+        return
     queue: list[ast.AST] = [node]
     i = 0
     while i < len(queue):
@@ -39,10 +43,11 @@ def walk(node: ast.AST) -> Iterator[ast.AST]:
 
 
 @final
-class _NodeIndex:
-    __slots__ = ("_buckets", "_flat", "_queries")
+class NodeIndex:
+    __slots__ = ("_buckets", "_flat", "_parents", "_queries", "tree")
 
     def __init__(self, tree: ast.AST) -> None:
+        self.tree = tree
         buckets: dict[type[ast.AST], list[ast.AST]] = {}
         flat: list[ast.AST] = [tree]
         i = 0
@@ -58,8 +63,15 @@ class _NodeIndex:
             flat += children(current)
         self._buckets: dict[type[ast.AST], list[ast.AST]] = buckets
         self._flat: list[ast.AST] = flat
+        self._parents: Mapping[ast.AST, ast.AST] | None = None
         self._queries: dict[tuple[type[ast.AST], ...], list[ast.AST]] = {}
 
+    @property
+    def parents(self) -> Mapping[ast.AST, ast.AST]:
+        if self._parents is None:
+            self._parents = MappingProxyType({child: parent for parent in self._flat for child in children(parent)})
+        return self._parents
+
     def query(self, types: tuple[type[ast.AST], ...]) -> list[ast.AST]:
         hit = self._queries.get(types)
         if hit is not None:
@@ -80,13 +92,11 @@ class _NodeIndex:
         return result
 
 
-_last_index: tuple[ast.AST, _NodeIndex] | None = None
-# The strong tree reference prevents a recycled object id from ever reusing a stale index.
+def nodes[NodeT: ast.AST](tree: ast.AST, *types: type[NodeT], index: NodeIndex | None = None) -> list[NodeT]:
+    selected = index if index is not None and index.tree is tree else NodeIndex(tree)
+    return [node for node in selected.query(types) if isinstance(node, types)]
 
 
-def nodes[NodeT: ast.AST](tree: ast.AST, *types: type[NodeT]) -> list[NodeT]:
-    global _last_index  # ruff: ignore[global-statement] — single-slot memo, mirroring `parse_or_none`
-    if _last_index is None or _last_index[0] is not tree:
-        _last_index = (tree, _NodeIndex(tree))
-    # The `isinstance` pass is what narrows `list[ast.AST]` to `list[NodeT]`
-    return [node for node in _last_index[1].query(types) if isinstance(node, types)]
+def parent_map(tree: ast.AST, *, index: NodeIndex | None = None) -> Mapping[ast.AST, ast.AST]:
+    selected = index if index is not None and index.tree is tree else NodeIndex(tree)
+    return selected.parents

{sarj_python_lint-0.88.0 → sarj_python_lint-1.1.1}/src/sarj_python_lint/rules/_fastapi.py

@@ -5,6 +5,7 @@ from collections import Counter
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Literal, NamedTuple
 
+from sarj_python_lint.rules._ast_index import walk as walk_ast
 from sarj_python_lint.rules._imports import ImportIndex
 
 
@@ -153,7 +154,7 @@ class FastapiIndex:
         visit(tree, 0, None)
 
     def _read_imports(self, tree: ast.Module) -> None:
-        for node in ast.walk(tree):
+        for node in walk_ast(tree):
             if self._node_scopes[id(node)] != 0:
                 continue
             if isinstance(node, ast.Import):
@@ -197,7 +198,7 @@ class FastapiIndex:
 
     def _read_aliases(self, tree: ast.Module) -> None:
         assignments: list[tuple[int, str, ast.expr]] = []
-        for node in ast.walk(tree):
+        for node in walk_ast(tree):
             self._read_bound_names(node)
             assignment = self._alias_assignment(node)
             if assignment is not None:
@@ -638,7 +639,7 @@ def _statement_binds(statement: ast.stmt, name: str) -> bool:
 
 def _stored_names(node: ast.expr) -> frozenset[str]:
     return frozenset(
-        child.id for child in ast.walk(node) if isinstance(child, ast.Name) and isinstance(child.ctx, ast.Store)
+        child.id for child in walk_ast(node) if isinstance(child, ast.Name) and isinstance(child.ctx, ast.Store)
     )