sarj-python-lint 0.82.4__tar.gz → 0.82.6__tar.gz

{sarj_python_lint-0.82.4 → sarj_python_lint-0.82.6}/PKG-INFO

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

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

{sarj_python_lint-0.82.4 → sarj_python_lint-0.82.6}/src/sarj_python_lint/_ratchet_cli.py

@@ -63,6 +63,7 @@ def _run(args: _Options) -> int:
             packages=baseline.packages,
             per_file_ceiling=args.per_file_ceiling,
             file_exceptions=baseline.file_exceptions,
+            file_selector_ceilings=baseline.file_selector_ceilings,
             excluded_subtrees=baseline.excluded_subtrees,
         )
 
@@ -85,6 +86,7 @@ def _run(args: _Options) -> int:
         packages=baseline.packages,
         per_file_ceiling=baseline.per_file_ceiling,
         file_exceptions=baseline.file_exceptions,
+        file_selector_ceilings=baseline.file_selector_ceilings,
         excluded_subtrees=excluded_subtrees,
     )
     try:
@@ -182,7 +184,10 @@ class _Result:
 
 
 app = typer.Typer(
-    help="Ratchet on lint/type suppressions: per-code, per-package and per-file ceilings that may only shrink.",
+    help=(
+        "Ratchet on lint/type suppressions: per-selector, per-package, per-file, and per-file-selector ceilings that "
+        "may only shrink."
+    ),
     add_completion=False,
     no_args_is_help=False,
     pretty_exceptions_enable=False,

{sarj_python_lint-0.82.4 → sarj_python_lint-0.82.6}/src/sarj_python_lint/ratchet.py

@@ -69,6 +69,7 @@ class Measurement:
     codes: Counter[str]
     packages: Counter[str]
     files: dict[str, int]
+    file_selectors: dict[str, Counter[str]]
 
     @property
     def total(self) -> int:
@@ -82,6 +83,7 @@ class Baseline:
     packages: dict[str, int] = field(default_factory=dict[str, int])
     per_file_ceiling: int = DEFAULT_PER_FILE_CEILING
     file_exceptions: dict[str, int] = field(default_factory=dict[str, int])
+    file_selector_ceilings: dict[str, dict[str, int]] | None = None
     excluded_subtrees: tuple[str, ...] = ()
 
 
@@ -113,6 +115,10 @@ _REMEDIATION: Final[Mapping[str, str]] = MappingProxyType(
             "burn one down here, or grandfather the file explicitly in the baseline's "
             "`files.exceptions`."
         ),
+        "file-selector": (
+            "A suppression for this selector is new to this file. Fix the finding instead of moving suppression debt "
+            "between files or selectors, or get the exact ceiling raise reviewed explicitly (`--update --allow-increase`)."
+        ),
     }
 )
 
@@ -128,6 +134,7 @@ def measure(
     codes: Counter[str] = Counter()
     package_counts: Counter[str] = Counter()
     files: dict[str, int] = {}
+    file_selectors: dict[str, Counter[str]] = {}
     excluded = tuple(_normalized_subtree(value) for value in excluded_subtrees)
     for package in packages:
         package_counts[package] = 0
@@ -142,7 +149,8 @@ def measure(
             n = sum(found.values())
             package_counts[package] += n
             files[relative] = n
-    return Measurement(codes=codes, packages=package_counts, files=files)
+            file_selectors[relative] = found
+    return Measurement(codes=codes, packages=package_counts, files=files, file_selectors=file_selectors)
 
 
 def count_source(source: str, *, ruff_aliases: Mapping[str, str] | None = None) -> Counter[str]:
@@ -173,6 +181,13 @@ def gate(measurement: Measurement, baseline: Baseline) -> list[Failure]:
         for key, n in sorted(measurement.files.items())
         if n > (ceiling := baseline.file_exceptions.get(key, baseline.per_file_ceiling))
     ]
+    if baseline.file_selector_ceilings is not None:
+        failures += [
+            Failure(dimension="file-selector", key=f"{path} [{code}]", ceiling=ceiling, actual=actual)
+            for path, codes in sorted(measurement.file_selectors.items())
+            for code, actual in sorted(codes.items())
+            if actual > (ceiling := baseline.file_selector_ceilings.get(path, {}).get(code, 0))
+        ]
     return failures
 
 
@@ -193,6 +208,9 @@ def seed(measurement: Measurement, baseline: Baseline) -> Baseline:
         packages=dict(sorted(measurement.packages.items())),
         per_file_ceiling=baseline.per_file_ceiling,
         file_exceptions=dict(sorted(exceptions.items())),
+        file_selector_ceilings={
+            path: dict(sorted(codes.items())) for path, codes in sorted(measurement.file_selectors.items())
+        },
         excluded_subtrees=baseline.excluded_subtrees,
     )
 
@@ -214,6 +232,7 @@ def load_baseline(path: Path) -> Baseline:
         if isinstance(ceiling, int) and not isinstance(ceiling, bool)
         else DEFAULT_PER_FILE_CEILING,
         file_exceptions=_int_map(_get(files, "exceptions")),
+        file_selector_ceilings=_optional_nested_int_map(_get(files, "selectors")),
         excluded_subtrees=_string_tuple(_get(raw, "excluded_subtrees")),
     )
 
@@ -231,7 +250,8 @@ def dump_baseline(baseline: Baseline, packages: Iterable[str]) -> str:
             "Suppression ceilings, written by `sarj-ratchet --update`. Counts may "
             "only go DOWN: `codes` is per dialect+code, `packages` is per "
             "top-level package, `files.per_file_ceiling` caps any single file "
-            "with `files.exceptions` grandfathering the pre-existing hot spots. "
+            "with `files.exceptions` grandfathering the pre-existing hot spots, and "
+            "`files.selectors` prevents debt from moving between files or lint rules. "
             "Raising a ceiling requires `--update --allow-increase` and review."
         ),
         "packages_scanned": sorted(packages),
@@ -241,6 +261,7 @@ def dump_baseline(baseline: Baseline, packages: Iterable[str]) -> str:
         "files": {
             "per_file_ceiling": baseline.per_file_ceiling,
             "exceptions": baseline.file_exceptions,
+            "selectors": baseline.file_selector_ceilings or {},
         },
     }
     return json.dumps(payload, indent=2) + "\n"
@@ -258,13 +279,17 @@ def discover_packages(root: Path, excluded_dir_names: frozenset[str] = DEFAULT_E
 
 
 def _int_map(value: object) -> dict[str, int]:
-    if not isinstance(value, dict):
+    if not _is_string_object_mapping(value):
         return {}
-    return {
-        key: count
-        for key, count in value.items()  # pyright: ignore[reportUnknownVariableType] — json leaves are Any; narrowed in the guard
-        if isinstance(key, str) and isinstance(count, int) and not isinstance(count, bool)
-    }
+    return {key: count for key, count in value.items() if isinstance(count, int) and not isinstance(count, bool)}
+
+
+def _optional_nested_int_map(value: object) -> dict[str, dict[str, int]] | None:
+    if value is None:
+        return None
+    if not _is_string_object_mapping(value):
+        return {}
+    return {path: counts for path, raw_counts in value.items() if (counts := _int_map(raw_counts))}
 
 
 def _string_tuple(value: object) -> tuple[str, ...]:
@@ -282,6 +307,13 @@ def _is_object_list(value: object) -> TypeGuard[list[object]]:
     return isinstance(value, list)
 
 
+def _is_string_object_mapping(value: object) -> TypeGuard[dict[str, object]]:
+    return isinstance(value, dict) and all(
+        isinstance(key, str)
+        for key in value  # pyright: ignore[reportUnknownVariableType] — runtime validation narrows untyped JSON keys.
+    )
+
+
 def _normalized_subtree(value: str) -> str:
     return value.strip("/")
 

{sarj_python_lint-0.82.4 → sarj_python_lint-0.82.6}/src/sarj_python_lint/rules/_registry.py

@@ -103,6 +103,9 @@ from sarj_python_lint.rules.prefer_match_value_dispatch import PreferMatchValueD
 from sarj_python_lint.rules.prefer_module_level_constant import (
     PreferModuleLevelConstant,
 )
+from sarj_python_lint.rules.prefer_monkeypatch_for_process_state_in_test import (
+    PreferMonkeypatchForProcessStateInTest,
+)
 from sarj_python_lint.rules.prefer_namedtuple_over_tuple_return import (
     PreferNamedtupleOverTupleReturn,
 )
@@ -204,6 +207,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreferModuleLevelConstant.id: PreferModuleLevelConstant,
         PreferImmutableModuleConstant.id: PreferImmutableModuleConstant,
         PreferInjectedDependencyOverMonkeypatch.id: PreferInjectedDependencyOverMonkeypatch,
+        PreferMonkeypatchForProcessStateInTest.id: PreferMonkeypatchForProcessStateInTest,
         MockWithoutSpec.id: MockWithoutSpec,
         OpaqueParametrizeCaseNeedsId.id: OpaqueParametrizeCaseNeedsId,
         PytestFixtureReturnsBareTuple.id: PytestFixtureReturnsBareTuple,

sarj_python_lint-0.82.6/src/sarj_python_lint/rules/prefer_monkeypatch_for_process_state_in_test.py

@@ -0,0 +1,367 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, NamedTuple, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    parse_or_none,
+)
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+    from pathlib import Path
+
+
+_OS = frozenset({"os"})
+_SYS = frozenset({"sys"})
+_SCOPE_NODES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)
+
+
+class _Mutation(NamedTuple):
+    node: ast.expr
+    family: str
+    subject: str
+    remedy: str
+    identity: str | None = None
+
+
+@final
+class PreferMonkeypatchForProcessStateInTest(Rule):
+    id = "prefer-monkeypatch-for-process-state-in-test"
+    code = "SARJ446"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Test mutates process-wide state without a restoring test scope.",
+        rationale=(
+            "The working directory and Python import registries are shared by every test in the process. A direct "
+            "mutation can survive an assertion or setup failure, making later tests depend on execution order."
+        ),
+        remediation=(
+            "Use pytest's monkeypatch.chdir, monkeypatch.syspath_prepend, monkeypatch.setitem, or "
+            "monkeypatch.delitem so teardown restores the previous state even when the test fails. A deliberate "
+            "manual restoration may remain when it is enclosed by a matching try/finally."
+        ),
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only maintained test paths are analyzed; generated files, production code, and module/class bootstrap mutations are excluded.",
+            "The rule covers os.chdir, sys.path.insert(0, ...), and direct sys.modules set, delete, or unused pop operations with an equivalent pytest restoring helper.",
+            "Environment variables remain owned by Ruff TID251/B003; argv, locale, timezone, warning filters, and process APIs without an equivalent helper are outside this rule.",
+            "Imports and import aliases are resolved conservatively. Indirect container aliases and dynamically selected modules are not inferred.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="direct-module-registry-mutation",
+                title="Test installs a module without guaranteed restoration",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_plugin.py",
+                        "import sys\n\ndef test_plugin(fake_plugin):\n    sys.modules['optional_plugin'] = fake_plugin\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_plugin.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="scoped-module-registry-mutation",
+                title="Pytest restores the module registry after the test",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_plugin.py",
+                        "import sys\n\ndef test_plugin(monkeypatch, fake_plugin):\n"
+                        "    monkeypatch.setitem(sys.modules, 'optional_plugin', fake_plugin)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_plugin.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if not is_test_path(path) or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+
+        module_imports = ImportIndex.from_tree(tree, module_scope_only=True)
+        mutations = [
+            mutation for function in _functions(tree) for mutation in _function_mutations(function, module_imports)
+        ]
+        diagnostics = [
+            Diagnostic(
+                path=path,
+                line=mutation.node.lineno,
+                col=mutation.node.col_offset + 1,
+                code=self.code,
+                message=(
+                    f"Direct {mutation.subject} mutation can leak into later tests when this scope exits early. "
+                    f"Use {mutation.remedy} so pytest restores the previous process state automatically."
+                ),
+                severity=Severity.WARNING,
+            )
+            for mutation in mutations
+        ]
+        diagnostics.sort(key=lambda diagnostic: (diagnostic.line, diagnostic.col))
+        return diagnostics
+
+
+def _functions(tree: ast.Module) -> Iterator[ast.FunctionDef | ast.AsyncFunctionDef]:
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            yield node
+
+
+def _function_mutations(
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    module_imports: ImportIndex,
+) -> list[_Mutation]:
+    local_tree = ast.Module(body=function.body, type_ignores=[])
+    local_imports = ImportIndex.from_tree(local_tree)
+    nodes = tuple(_lexical_nodes(function))
+    parents = {child: parent for parent in nodes for child in ast.iter_child_nodes(parent)}
+    mutations: list[_Mutation] = []
+    for node in nodes:
+        mutation = _mutation(node, parents, module_imports, local_imports)
+        if mutation is None or _import_root_rebound_before(function, mutation.node, module_imports, local_imports):
+            continue
+        mutations.append(mutation)
+    restored = _restored_mutations(nodes, mutations, module_imports, local_imports)
+    return [mutation for mutation in mutations if mutation.node not in restored]
+
+
+def _lexical_nodes(function: ast.FunctionDef | ast.AsyncFunctionDef) -> Iterator[ast.AST]:
+    stack: list[ast.AST] = [node for node in reversed(function.body) if not isinstance(node, _SCOPE_NODES)]
+    while stack:
+        node = stack.pop()
+        yield node
+        for child in reversed(list(ast.iter_child_nodes(node))):
+            if isinstance(child, _SCOPE_NODES):
+                continue
+            stack.append(child)
+
+
+def _mutation(
+    node: ast.AST,
+    parents: dict[ast.AST, ast.AST],
+    module_imports: ImportIndex,
+    local_imports: ImportIndex,
+) -> _Mutation | None:
+    if isinstance(node, ast.Call):
+        mutation = _call_mutation(node, parents, module_imports, local_imports)
+        if mutation is not None:
+            return mutation
+    target: ast.expr | None = None
+    if isinstance(node, ast.Assign):
+        target = next((item for item in node.targets if _is_modules_item(item, module_imports, local_imports)), None)
+    elif isinstance(node, (ast.AnnAssign, ast.AugAssign)):
+        target = node.target
+    if target is not None and _is_modules_item(target, module_imports, local_imports):
+        return _Mutation(
+            target,
+            "modules",
+            "sys.modules",
+            "monkeypatch.setitem(sys.modules, key, value)",
+            _item_key(target),
+        )
+    if isinstance(node, ast.Delete):
+        target = next((item for item in node.targets if _is_modules_item(item, module_imports, local_imports)), None)
+        if target is not None:
+            return _Mutation(
+                target,
+                "modules",
+                "sys.modules",
+                "monkeypatch.delitem(sys.modules, key)",
+                _item_key(target),
+            )
+    return None
+
+
+def _call_mutation(
+    call: ast.Call,
+    parents: dict[ast.AST, ast.AST],
+    module_imports: ImportIndex,
+    local_imports: ImportIndex,
+) -> _Mutation | None:
+    if _resolves(call.func, module_imports, local_imports, sources=_OS, symbol="chdir"):
+        return _Mutation(call, "cwd", "working-directory", "monkeypatch.chdir(path)")
+    if (
+        isinstance(call.func, ast.Attribute)
+        and call.func.attr == "insert"
+        and _resolves(call.func.value, module_imports, local_imports, sources=_SYS, symbol="path")
+        and call.args
+        and _is_zero(call.args[0])
+    ):
+        identity = ast.dump(call.args[1], include_attributes=False) if len(call.args) > 1 else None
+        return _Mutation(call, "path", "sys.path", "monkeypatch.syspath_prepend(path)", identity)
+    if (
+        isinstance(call.func, ast.Attribute)
+        and call.func.attr == "pop"
+        and _resolves(call.func.value, module_imports, local_imports, sources=_SYS, symbol="modules")
+        and isinstance(parents.get(call), ast.Expr)
+    ):
+        identity = ast.dump(call.args[0], include_attributes=False) if call.args else None
+        return _Mutation(
+            call,
+            "modules",
+            "sys.modules",
+            "monkeypatch.delitem(sys.modules, key, raising=False)",
+            identity,
+        )
+    return None
+
+
+def _is_modules_item(node: ast.expr, module_imports: ImportIndex, local_imports: ImportIndex) -> bool:
+    return isinstance(node, ast.Subscript) and _resolves(
+        node.value,
+        module_imports,
+        local_imports,
+        sources=_SYS,
+        symbol="modules",
+    )
+
+
+def _item_key(node: ast.expr) -> str | None:
+    return ast.dump(node.slice, include_attributes=False) if isinstance(node, ast.Subscript) else None
+
+
+def _is_zero(node: ast.expr) -> bool:
+    return isinstance(node, ast.Constant) and not isinstance(node.value, bool) and node.value == 0
+
+
+def _resolves(
+    node: ast.expr,
+    module_imports: ImportIndex,
+    local_imports: ImportIndex,
+    *,
+    sources: frozenset[str],
+    symbol: str,
+) -> bool:
+    return module_imports.resolves(node, sources=sources, symbol=symbol) or local_imports.resolves(
+        node,
+        sources=sources,
+        symbol=symbol,
+    )
+
+
+def _import_root_rebound_before(
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    use: ast.AST,
+    module_imports: ImportIndex,
+    local_imports: ImportIndex,
+) -> bool:
+    roots = {
+        node.id
+        for node in ast.walk(use)
+        if isinstance(node, ast.Name) and (node.id in module_imports.bindings or node.id in local_imports.bindings)
+    }
+    parameters = {
+        argument.arg
+        for argument in (
+            *function.args.posonlyargs,
+            *function.args.args,
+            *function.args.kwonlyargs,
+        )
+    }
+    if not roots.isdisjoint(parameters):
+        return True
+    use_position = _position(use)
+    return any(
+        isinstance(node, ast.Name)
+        and isinstance(node.ctx, (ast.Store, ast.Del))
+        and node.id in roots
+        and _position(node) < use_position
+        for node in _lexical_nodes(function)
+    )
+
+
+def _position(node: ast.AST) -> tuple[int, int]:
+    return (getattr(node, "lineno", 0), getattr(node, "col_offset", 0))
+
+
+def _restored_mutations(
+    nodes: tuple[ast.AST, ...],
+    mutations: list[_Mutation],
+    module_imports: ImportIndex,
+    local_imports: ImportIndex,
+) -> set[ast.AST]:
+    restored: set[ast.AST] = set()
+    for node in nodes:
+        if not isinstance(node, (ast.Try, ast.TryStar)) or not node.finalbody:
+            continue
+        restored.update(_restored_for_try(node, mutations, module_imports, local_imports))
+    return restored
+
+
+def _restored_for_try(
+    node: ast.Try | ast.TryStar,
+    mutations: list[_Mutation],
+    module_imports: ImportIndex,
+    local_imports: ImportIndex,
+) -> set[ast.AST]:
+    protected_nodes = set(_descendants(node.body))
+    final_nodes = set(_descendants(node.finalbody))
+    protected = [mutation for mutation in mutations if mutation.node in protected_nodes]
+    final = [mutation for mutation in mutations if mutation.node in final_nodes]
+    restored: set[ast.AST] = set()
+    for mutation in protected:
+        matching = next((item for item in final if _same_state(mutation, item)), None)
+        if matching is not None:
+            restored.update((mutation.node, matching.node))
+            continue
+        if mutation.family == "path" and _finalbody_removes_path(
+            node.finalbody,
+            mutation.identity,
+            module_imports,
+            local_imports,
+        ):
+            restored.add(mutation.node)
+    return restored
+
+
+def _descendants(statements: Iterable[ast.stmt]) -> Iterator[ast.AST]:
+    for statement in statements:
+        yield from ast.walk(statement)
+
+
+def _same_state(left: _Mutation, right: _Mutation) -> bool:
+    return left.family == right.family and (left.identity is None or left.identity == right.identity)
+
+
+def _finalbody_removes_path(
+    statements: list[ast.stmt],
+    identity: str | None,
+    module_imports: ImportIndex,
+    local_imports: ImportIndex,
+) -> bool:
+    if identity is None:
+        return False
+    return any(
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr == "remove"
+        and _resolves(node.func.value, module_imports, local_imports, sources=_SYS, symbol="path")
+        and bool(node.args)
+        and ast.dump(node.args[0], include_attributes=False) == identity
+        for statement in statements
+        for node in ast.walk(statement)
+    )