sarj-python-lint 1.68.0__tar.gz → 1.69.1__tar.gz

{sarj_python_lint-1.68.0 → sarj_python_lint-1.69.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.68.0
+Version: 1.69.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/

{sarj_python_lint-1.68.0 → sarj_python_lint-1.69.1}/pyproject.toml

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

{sarj_python_lint-1.68.0 → sarj_python_lint-1.69.1}/src/sarj_python_lint/__main__.py

@@ -96,7 +96,7 @@ def _canonical_rule_ids(rule_ids: list[str]) -> list[str]:
     return list(dict.fromkeys(rid if rid in REGISTRY else aliases.get(rid, rid) for rid in rule_ids))
 
 
-def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
+def _check(rule_ids: list[str], paths: list[Path], *, jobs: int = 1) -> list[Diagnostic]:
     rule_ids = _canonical_rule_ids(rule_ids)
     unknown = [rid for rid in rule_ids if rid not in REGISTRY]
     if unknown:
@@ -116,6 +116,12 @@ def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
         session.project = indexes
         for rule in project_rules:
             rule.prepare(indexes)
+    if jobs > 1 and len(loaded) > 1:
+        from sarj_python_lint._parallel import check_parallel  # ruff: ignore[import-outside-top-level] -- serial API users do not need multiprocessing.
+
+        parallel = check_parallel([type(rule) for rule in rules], loaded, session.project, jobs=jobs)
+        if parallel is not None:
+            return parallel
     diags: list[Diagnostic] = []
     for p, source in loaded.items():
         diags.extend(check_source(rules, p, source, session=session))
@@ -144,8 +150,12 @@ def analyze(
     *,
     baseline: Path | None = None,
     root: Path | None = None,
+    jobs: int = 1,
 ) -> list[Diagnostic]:
-    diagnostics = _check(rule_ids, paths)
+    if jobs < 1:
+        msg = "jobs must be at least 1"
+        raise ValueError(msg)
+    diagnostics = _check(rule_ids, paths, jobs=jobs)
     return diagnostics if baseline is None else _apply_baseline(diagnostics, _read_baseline(baseline), root=root)
 
 
@@ -481,9 +491,11 @@ def _apply_baseline(
     return out
 
 
-def _run_check(rule: list[str], files: list[Path], baseline: Path | None, update_baseline: Path | None) -> int:
+def _run_check(
+    rule: list[str], files: list[Path], baseline: Path | None, update_baseline: Path | None, *, jobs: int = 1
+) -> int:
     try:
-        diags = analyze(rule, files)
+        diags = analyze(rule, files, jobs=jobs)
     except (OSError, ValueError, SyntaxError) as exc:
         sys.stderr.write(f"error: {exc}\n")
         return 2
@@ -554,14 +566,16 @@ def _check_command(
     context: typer.Context,
     files: Annotated[list[Path], typer.Argument()],
     rule: Annotated[list[str], typer.Option("--rule", help="Rule ID (repeat for multiple).")],
+    *,
     baseline: Annotated[
         Path | None, typer.Option(help="Per-file shrink-only baseline JSON: {path: {CODE: count}}.")
     ] = None,
     update_baseline: Annotated[
         Path | None, typer.Option(help="Write current per-file diagnostic counts to JSON and exit 0.")
     ] = None,
+    jobs: Annotated[int, typer.Option(min=1, help="Analysis worker budget (up to 2); default is serial.")] = 1,
 ) -> None:
-    context.ensure_object(_Result).code = _run_check(rule, files, baseline, update_baseline)
+    context.ensure_object(_Result).code = _run_check(rule, files, baseline, update_baseline, jobs=jobs)
 
 
 def main(argv: list[str] | None = None) -> int:

sarj_python_lint-1.69.1/src/sarj_python_lint/_parallel.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from concurrent.futures import ProcessPoolExecutor
+from dataclasses import dataclass
+import multiprocessing
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sarj_python_lint._analysis_session import AnalysisSession
+from sarj_python_lint.rule_base import Diagnostic, ProjectRule, Rule
+from sarj_python_lint.rules._local_source import LOCAL_SOURCE_CACHE_LIMIT
+from sarj_python_lint.rules._paths import clear_path_caches
+from sarj_python_lint.rules._project_index import ProjectIndexSet
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint.rules._project_index import ProjectSourceSnapshot
+
+
+type _ResolutionKey = tuple[Path, str | None, int]
+
+
+@dataclass
+class _WorkerState:
+    rules: list[Rule]
+    session: AnalysisSession
+    resolutions: frozenset[_ResolutionKey] = frozenset()
+    modules: frozenset[Path] = frozenset()
+
+
+@dataclass(frozen=True, slots=True)
+class _FileResult:
+    diagnostics: list[Diagnostic]
+    resolutions: frozenset[_ResolutionKey]
+    modules: frozenset[Path]
+
+
+_state: _WorkerState | None = None
+
+
+def _initialize(rule_types: list[type[Rule]], snapshot: ProjectSourceSnapshot | None) -> None:
+    global _state  # ruff: ignore[global-statement] -- each spawned process owns one initialized session.
+    rules = [rule_type() for rule_type in rule_types]
+    session = AnalysisSession()
+    for rule in rules:
+        rule.prepare_session(session)
+    clear_path_caches()
+    project = ProjectIndexSet.from_source_snapshot(snapshot) if snapshot is not None else None
+    session.project = project
+    for rule in rules:
+        if isinstance(rule, ProjectRule) and project is not None:
+            rule.prepare(project)
+    _state = _WorkerState(rules, session)
+
+
+def _check_file(item: tuple[Path, str]) -> _FileResult:
+    from sarj_python_lint.__main__ import check_source  # ruff: ignore[import-outside-top-level] -- keep spawn targets in an importable module.
+
+    if _state is None:
+        msg = "Python analysis worker was not initialized"
+        raise RuntimeError(msg)
+    path, source = item
+    diagnostics = check_source(_state.rules, path, source, session=_state.session)
+    keys = _state.session.local_source.cache_keys()
+    result = _FileResult(diagnostics, keys.resolutions - _state.resolutions, keys.modules - _state.modules)
+    _state.resolutions, _state.modules = keys.resolutions, keys.modules
+    return result
+
+
+def check_parallel(
+    rule_types: list[type[Rule]],
+    loaded: dict[Path, str],
+    project: ProjectIndexSet | None,
+    *,
+    jobs: int,
+) -> list[Diagnostic] | None:
+    # The untouched parent rules/session remain the serial fallback. Workers
+    # receive the same complete project snapshot and selected source strings.
+    workers = min(jobs, 2, len(loaded))
+    pool = ProcessPoolExecutor(
+        max_workers=workers,
+        mp_context=multiprocessing.get_context("spawn"),
+        initializer=_initialize,
+        initargs=(rule_types, project.source_snapshot() if project is not None else None),
+    )
+    diagnostics: list[Diagnostic] = []
+    resolutions: set[_ResolutionKey] = set()
+    modules: set[Path] = set()
+    try:
+        for result in pool.map(_check_file, loaded.items(), chunksize=1, buffersize=workers):
+            resolutions.update(result.resolutions)
+            modules.update(result.modules)
+            # A worker cannot hit either order-dependent limit when the whole
+            # union stays strictly below it. At the boundary, discard all output.
+            if len(resolutions) >= LOCAL_SOURCE_CACHE_LIMIT or len(modules) >= LOCAL_SOURCE_CACHE_LIMIT:
+                return None
+            diagnostics.extend(result.diagnostics)
+        return diagnostics
+    finally:
+        # Bound queued work and reap before fallback/error return. Running file
+        # checks finish normally; group cancellation belongs to the supervisor.
+        pool.shutdown(wait=True, cancel_futures=True)

{sarj_python_lint-1.68.0 → sarj_python_lint-1.69.1}/src/sarj_python_lint/rules/_local_source.py

@@ -15,7 +15,7 @@ if TYPE_CHECKING:
 
 _MAX_ANCESTORS = 24
 _MAX_MODULE_BYTES = 256_000
-_MAX_MODULES = 512
+LOCAL_SOURCE_CACHE_LIMIT = 512
 
 
 @dataclass(frozen=True, slots=True)
@@ -26,6 +26,12 @@ class LocalModule:
     runtime_imports: ImportIndex
 
 
+@dataclass(frozen=True, slots=True)
+class LocalSourceKeys:
+    resolutions: frozenset[tuple[Path, str | None, int]]
+    modules: frozenset[Path]
+
+
 @final
 class LocalSourceFacts:
     def __init__(self) -> None:
@@ -40,7 +46,7 @@ class LocalSourceFacts:
         key = (current, module, level)
         if key in self._resolutions:
             return self._resolutions[key]
-        if len(self._resolutions) >= _MAX_MODULES:
+        if len(self._resolutions) >= LOCAL_SOURCE_CACHE_LIMIT:
             return None
         result = _resolve_module(current, module, level, facts=facts)
         self._resolutions[key] = result
@@ -49,12 +55,16 @@ class LocalSourceFacts:
     def read_module(self, path: Path) -> LocalModule | None:
         if path in self._modules:
             return self._modules[path]
-        if len(self._modules) >= _MAX_MODULES:
+        if len(self._modules) >= LOCAL_SOURCE_CACHE_LIMIT:
             return None
         module = _read_module(path)
         self._modules[path] = module
         return module
 
+    def cache_keys(self) -> LocalSourceKeys:
+        # Failed lookups consume the same semantic budgets as successful ones.
+        return LocalSourceKeys(frozenset(self._resolutions), frozenset(self._modules))
+
 
 def _resolve_module(current: Path, module: str | None, level: int, *, facts: FirstPartyFacts) -> Path | None:
     if ".." in current.parts or level > _MAX_ANCESTORS:

{sarj_python_lint-1.68.0 → sarj_python_lint-1.69.1}/src/sarj_python_lint/rules/_project_index.py

@@ -154,6 +154,20 @@ class LoadedSource:
     source: str
 
 
+@dataclass(frozen=True, slots=True)
+class _IndexedSource:
+    key: Path
+    path: Path
+    module: str | None
+    source: str
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectSourceSnapshot:
+    roots: tuple[Path, ...]
+    units: tuple[_IndexedSource, ...]
+
+
 @dataclass(frozen=True, slots=True)
 class _ClassValueUse:
     reference: ast.Name | ast.Attribute
@@ -196,6 +210,30 @@ class ProjectIndexSet:
         self._classes = MappingProxyType(classes)
         self._nominals = MappingProxyType({key: frozenset(value) for key, value in nominals.items()})
 
+    def source_snapshot(self) -> ProjectSourceSnapshot:
+        # Rebuild memoized facts without rescanning roots or changing the
+        # module identities/order of the complete prepared source graph.
+        return ProjectSourceSnapshot(
+            self._roots,
+            tuple(_IndexedSource(key, unit.path, unit.module, unit.source) for key, unit in self._units.items()),
+        )
+
+    @classmethod
+    def from_source_snapshot(cls, snapshot: ProjectSourceSnapshot) -> Self:
+        units: dict[Path, SourceUnit] = {}
+        for source in snapshot.units:
+            tree: ast.Module | None = None
+            with suppress(SyntaxError):
+                tree = ast.parse(source.source, filename=str(source.path))
+            units[source.key] = SourceUnit(
+                path=source.path,
+                module=source.module,
+                source=source.source,
+                tree=tree,
+                imports=MappingProxyType(_imports(source.module, tree, is_package=source.path.name == "__init__.py")),
+            )
+        return cls(units, snapshot.roots)
+
     @classmethod
     def build(
         cls,

sarj_python_lint-1.69.1/src/sarj_python_lint/rules/prefer_direct_import_module.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import ast
+from keyword import iskeyword
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, final, override
+from unicodedata import is_normalized
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+)
+from sarj_python_lint.rules._namespace_access import dynamic_namespace_access
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+@final
+class PreferDirectImportModule(Rule):
+    id = "prefer-direct-import-module"
+    code = "SARJ529"
+    documentation = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Prefer static imports for eager module loads with a literal module name.",
+        rationale="Static imports expose known dependencies to readers and tooling without dynamic loader indirection.",
+        remediation="Replace a fixed eager module load with a module-level import, preserving its binding: plugin = importlib.import_module('plugins.billing') becomes import plugins.billing as plugin. Keep dynamic loading when module selection or import timing requires it.",
+        category=RuleCategory.STYLE,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Checks direct module-level assignments and expression statements calling the proven stdlib import_module function, through qualified or directly imported names, with one literal absolute module name.",
+            "Function/class bodies, conditional or guarded imports, variable module names, relative imports, callback references, shadowed or mutated providers and generated code are excluded. Static import syntax must be valid for every module-name segment.",
+            "This is a warning without automatic rewriting: moving an import can change execution order, optional-dependency behavior or cycle handling. The rule does not prefer one spelling of genuinely dynamic import_module calls.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="literal-eager-loader",
+                title="A known eager dependency is loaded dynamically",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app.py", "import importlib\nplugin = importlib.import_module('plugins.billing')\n"
+                    ),
+                ),
+                focus_path=PurePosixPath("app.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="static-module-import",
+                title="A static import preserves the module binding",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app.py", "import plugins.billing as plugin\n"),),
+                focus_path=PurePosixPath("app.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 "import_module" not in context.symbol_source:
+            return []
+        loader_references = {
+            reference
+            for call in context.nodes(ast.Call)
+            if context.imports.resolved_qualified_name(call.func) == "importlib.import_module"
+            for reference in ast.walk(call.func)
+        }
+        if dynamic_namespace_access(
+            (node for node in context.nodes(ast.AST) if node not in loader_references),
+            context.imports,
+            context.parents,
+        ):
+            return []
+        return [
+            Diagnostic(
+                context.path,
+                node.lineno,
+                node.col_offset + 1,
+                self.code,
+                f"Use a module-level static import for the known module '{module}'; preserve the binding with 'import {module} as plugin' when needed.",
+                severity=Severity.WARNING,
+            )
+            for statement in context.tree.body
+            if isinstance(statement, ast.Assign | ast.AnnAssign | ast.Expr)
+            and isinstance(node := statement.value, ast.Call)
+            and (module := _literal_module(node)) is not None
+            and context.resource_provenance.runtime_import_name(node.func) == "importlib.import_module"
+        ]
+
+
+def _literal_module(call: ast.Call) -> str | None:
+    match call:
+        case ast.Call(args=[ast.Constant(value=str() as module)], keywords=[]):
+            pass
+        case ast.Call(args=[], keywords=[ast.keyword(arg="name", value=ast.Constant(value=str() as module))]):
+            pass
+        case _:
+            return None
+    if not is_normalized("NFKC", module):
+        return None
+    return module if all(part.isidentifier() and not iskeyword(part) for part in module.split(".")) else None

sarj_python_lint-1.68.0/src/sarj_python_lint/rules/prefer_direct_import_module.py

@@ -1,83 +0,0 @@
-from __future__ import annotations
-
-import ast
-from pathlib import PurePosixPath
-from typing import TYPE_CHECKING, final, override
-
-from sarj_python_lint.rule_base import (
-    AutofixPolicy,
-    Diagnostic,
-    ExampleFile,
-    ExampleOutcome,
-    Rule,
-    RuleCategory,
-    RuleDocumentation,
-    RuleExample,
-    Severity,
-)
-
-
-if TYPE_CHECKING:
-    from sarj_python_lint._file_context import PythonFileContext
-
-
-@final
-class PreferDirectImportModule(Rule):
-    id = "prefer-direct-import-module"
-    code = "SARJ529"
-    documentation = RuleDocumentation(
-        default_level=Severity.WARNING,
-        summary="Import import_module directly instead of accessing importlib.import_module.",
-        rationale="A focused import makes the loader dependency explicit and removes repeated module qualification.",
-        remediation="Use 'from importlib import import_module' and annotate importer callables with 'Callable[[str], ModuleType]'. Keep intentional module patching behind an explained local exception.",
-        category=RuleCategory.STYLE,
-        autofix=AutofixPolicy.NONE,
-        limitations=(
-            "Only provenance-resolved importlib.import_module attribute reads are checked. Other importlib APIs, direct imports, shadowed or mutated namespaces and generated code are preserved. No automatic rewrite because changing the lookup can change monkeypatch behavior.",
-        ),
-        examples=(
-            RuleExample(
-                example_id="qualified-loader",
-                title="The module loader is qualified at each use",
-                outcome=ExampleOutcome.MATCH,
-                files=(ExampleFile.python("app.py", "import importlib\nloader = importlib.import_module\n"),),
-                focus_path=PurePosixPath("app.py"),
-                expected_count=1,
-                public=True,
-            ),
-            RuleExample(
-                example_id="focused-loader",
-                title="Import only the loader",
-                outcome=ExampleOutcome.NO_MATCH,
-                files=(ExampleFile.python("app.py", "from importlib import import_module\nloader = import_module\n"),),
-                focus_path=PurePosixPath("app.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 "import_module" not in context.symbol_source:
-            return []
-        provenance = context.static_resource_provenance
-        return [
-            Diagnostic(
-                context.path,
-                node.lineno,
-                node.col_offset + 1,
-                self.code,
-                "Use 'from importlib import import_module' and call 'import_module(...)' directly.",
-                severity=Severity.WARNING,
-            )
-            for node in context.nodes(ast.Attribute)
-            if node.attr == "import_module"
-            and isinstance(node.ctx, ast.Load)
-            and context.imports.resolved_qualified_name(node) == "importlib.import_module"
-            and isinstance(node.value, ast.Name)
-            and isinstance(provenance.binding(node.value.id, node), ast.alias)
-            and node.value.id not in provenance.mutated
-            and not provenance.wildcard
-        ]