patch-linter 1.0.0__tar.gz

patch_linter-1.0.0/.gitignore

@@ -0,0 +1,53 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+*.manifest
+*.spec
+pip-log.txt
+pip-delete-this-directory.txt
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+*.mo
+*.pot
+*.log
+.venv
+env/
+venv/
+ENV/
+.env
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.idea/
+.vscode/

patch_linter-1.0.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [1.0.0] - 2026-08-17
+
+### Added
+
+- Detect `unittest.mock.patch` usage in tests (decorators, context managers, `patch.object` /
+  `patch.dict` / `patch.multiple` / `patch.stopall`), including import aliases.
+- Detect pytest `monkeypatch` mutation methods (`setattr`, `delattr`, `setitem`, …).
+- CLI `patch-linter` with clickable `path:line:col: PATCH001 …` diagnostics.
+- Flake8 plugin (`PATCH` / `PATCH001`).
+- Suppress with `# noqa` or `# noqa: PATCH001`.

patch_linter-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pavel Maksimov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

patch_linter-1.0.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: patch-linter
+Version: 1.0.0
+Summary: Static analyzer that forbids unittest.mock.patch and pytest monkeypatch in tests
+Project-URL: Homepage, https://github.com/pavelmaksimov/patch-linter
+Project-URL: Bug Tracker, https://github.com/pavelmaksimov/patch-linter/issues
+Author-email: Pavel Maksimov <vur21@yandex.ru>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: flake8
+Requires-Dist: flake8>=7.2.0; extra == 'flake8'
+Description-Content-Type: text/markdown
+
+# Patch Linter
+
+Static analyzer that forbids **`unittest.mock.patch`** and **pytest `monkeypatch`**
+mutations in tests. Prefer real dependency injection over patching.
+
+## Why
+
+Patching reaches into other modules and couples tests to implementation details.
+Refactoring becomes harder, and failures become brittle. Inject dependencies
+(fakes, stubs, or test doubles passed as arguments) instead.
+
+## What is reported
+
+| Pattern | Example |
+|---|---|
+| `unittest.mock.patch` | `@patch(...)`, `with patch(...)` |
+| Import aliases | `from unittest.mock import patch as p` → `p(...)` |
+| Via module | `mock.patch(...)`, `unittest.mock.patch(...)` |
+| Patch helpers | `patch.object` / `patch.dict` / `patch.multiple` / `patch.stopall` |
+| pytest monkeypatch | `monkeypatch.setattr(...)`, `setenv`, `delattr`, … |
+
+Not reported (by design): `mocker` (pytest-mock), bare `Mock` / `MagicMock`,
+freezegun, your own functions named `patch`, HTTP `client.patch(...)`.
+
+Code: **`PATCH001`**.
+
+## Installation
+
+```bash
+pip install patch-linter
+# optional flake8 plugin:
+pip install "patch-linter[flake8]"
+```
+
+## Usage
+
+### CLI
+
+```bash
+patch-linter tests/
+patch-linter tests/unit tests/test_foo.py
+```
+
+Output (clickable in Cursor / VS Code / PyCharm):
+
+```text
+/abs/path/to/tests/test_foo.py:12:5: PATCH001 Patch usage in tests: @patch('module.function')
+```
+
+Exit code `1` if problems are found.
+
+### Flake8
+
+```bash
+flake8 --select=PATCH tests/
+```
+
+### Suppress a line
+
+```python
+@patch("module.function")  # noqa: PATCH001
+def test_legacy(mock_fn):
+    ...
+```
+
+Bare `# noqa` also suppresses the finding on that line.
+
+## Correct approaches
+
+```python
+def process_data(repository):
+    return repository.get_all()
+
+
+def test_process_data():
+    class FakeRepo:
+        def get_all(self):
+            return [1, 2, 3]
+
+    assert process_data(FakeRepo()) == [1, 2, 3]
+```
+
+## License
+
+MIT

patch_linter-1.0.0/README.md

@@ -0,0 +1,85 @@
+# Patch Linter
+
+Static analyzer that forbids **`unittest.mock.patch`** and **pytest `monkeypatch`**
+mutations in tests. Prefer real dependency injection over patching.
+
+## Why
+
+Patching reaches into other modules and couples tests to implementation details.
+Refactoring becomes harder, and failures become brittle. Inject dependencies
+(fakes, stubs, or test doubles passed as arguments) instead.
+
+## What is reported
+
+| Pattern | Example |
+|---|---|
+| `unittest.mock.patch` | `@patch(...)`, `with patch(...)` |
+| Import aliases | `from unittest.mock import patch as p` → `p(...)` |
+| Via module | `mock.patch(...)`, `unittest.mock.patch(...)` |
+| Patch helpers | `patch.object` / `patch.dict` / `patch.multiple` / `patch.stopall` |
+| pytest monkeypatch | `monkeypatch.setattr(...)`, `setenv`, `delattr`, … |
+
+Not reported (by design): `mocker` (pytest-mock), bare `Mock` / `MagicMock`,
+freezegun, your own functions named `patch`, HTTP `client.patch(...)`.
+
+Code: **`PATCH001`**.
+
+## Installation
+
+```bash
+pip install patch-linter
+# optional flake8 plugin:
+pip install "patch-linter[flake8]"
+```
+
+## Usage
+
+### CLI
+
+```bash
+patch-linter tests/
+patch-linter tests/unit tests/test_foo.py
+```
+
+Output (clickable in Cursor / VS Code / PyCharm):
+
+```text
+/abs/path/to/tests/test_foo.py:12:5: PATCH001 Patch usage in tests: @patch('module.function')
+```
+
+Exit code `1` if problems are found.
+
+### Flake8
+
+```bash
+flake8 --select=PATCH tests/
+```
+
+### Suppress a line
+
+```python
+@patch("module.function")  # noqa: PATCH001
+def test_legacy(mock_fn):
+    ...
+```
+
+Bare `# noqa` also suppresses the finding on that line.
+
+## Correct approaches
+
+```python
+def process_data(repository):
+    return repository.get_all()
+
+
+def test_process_data():
+    class FakeRepo:
+        def get_all(self):
+            return [1, 2, 3]
+
+    assert process_data(FakeRepo()) == [1, 2, 3]
+```
+
+## License
+
+MIT

patch_linter-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "patch-linter"
+version = "1.0.0"
+description = "Static analyzer that forbids unittest.mock.patch and pytest monkeypatch in tests"
+readme = "README.md"
+authors = [
+    { name = "Pavel Maksimov", email = "vur21@yandex.ru" }
+]
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = []
+
+[project.optional-dependencies]
+flake8 = [
+    "flake8>=7.2.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/pavelmaksimov/patch-linter"
+"Bug Tracker" = "https://github.com/pavelmaksimov/patch-linter/issues"
+
+[project.entry-points."flake8.extension"]
+PATCH = "patch_linter.flake8_plugin:PatchLinter"
+
+[project.scripts]
+patch-linter = "patch_linter.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 100
+indent-width = 4
+target-version = "py311"
+include = ["src/**/*.py", "tests/**/*.py"]
+
+[tool.ruff.format]
+line-ending = "lf"

patch_linter-1.0.0/src/patch_linter/__init__.py

@@ -0,0 +1,6 @@
+"""Forbid unittest.mock.patch and pytest monkeypatch in test code."""
+
+__version__ = "1.0.0"
+
+CODE = "PATCH001"
+MESSAGE = "Patch usage in tests"

patch_linter-1.0.0/src/patch_linter/checker.py

@@ -0,0 +1,208 @@
+"""AST checker for forbidden patch / monkeypatch usage."""
+
+from __future__ import annotations
+
+import ast
+import re
+import sys
+from pathlib import Path
+
+from patch_linter import CODE, MESSAGE
+from patch_linter.imports import (
+    MONKEYPATCH_METHODS,
+    ImportBindings,
+    collect_imports,
+)
+from patch_linter.models import Issue
+
+SKIP_DIRS = frozenset({"__pycache__", ".venv", "venv", ".git", ".tox", ".mypy_cache", ".ruff_cache"})
+
+# flake8/ruff style: ``# noqa`` or ``# noqa: PATCH001,E501``
+_NOQA_RE = re.compile(
+    r"#\s*noqa\b(?::\s*(.*))?",
+    re.IGNORECASE,
+)
+_CODE_SPLIT_RE = re.compile(r"[,\s]+")
+
+
+def line_has_noqa(line: str, code: str = CODE) -> bool:
+    match = _NOQA_RE.search(line)
+    if not match:
+        return False
+    codes = match.group(1)
+    if codes is None or codes.strip() == "":
+        return True
+    return code.upper() in {c.strip().upper() for c in _CODE_SPLIT_RE.split(codes) if c.strip()}
+
+
+def analyze_source(
+    source: str,
+    filepath: Path,
+    *,
+    tree: ast.AST | None = None,
+) -> list[Issue]:
+    """Analyze Python source; return issues (empty on parse failure)."""
+    lines = source.splitlines()
+    if tree is None:
+        try:
+            tree = ast.parse(source, filename=str(filepath))
+        except SyntaxError as exc:
+            print(
+                f"Warning: skipping {filepath.resolve()}: syntax error: {exc}",
+                file=sys.stderr,
+            )
+            return []
+
+    bindings = collect_imports(tree)
+    visitor = PatchVisitor(bindings=bindings, filepath=filepath, lines=lines)
+    visitor.visit(tree)
+    return visitor.issues
+
+
+def analyze_file(filepath: Path) -> list[Issue]:
+    path = filepath.resolve()
+    try:
+        content = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        print(f"Warning: skipping {path}: decode error: {exc}", file=sys.stderr)
+        return []
+    return analyze_source(content, path)
+
+
+def iter_python_files(root: Path) -> list[Path]:
+    root = root.resolve()
+    if root.is_file():
+        return [root] if root.suffix == ".py" else []
+
+    files: list[Path] = []
+    for path in root.rglob("*.py"):
+        if any(part in SKIP_DIRS for part in path.parts):
+            continue
+        files.append(path)
+    return sorted(files)
+
+
+def analyze_paths(paths: list[Path]) -> list[Issue]:
+    issues: list[Issue] = []
+    for raw in paths:
+        path = Path(raw)
+        if not path.exists():
+            print(f"Warning: path does not exist: {path}", file=sys.stderr)
+            continue
+        for file in iter_python_files(path):
+            issues.extend(analyze_file(file))
+    return issues
+
+
+class PatchVisitor(ast.NodeVisitor):
+    def __init__(
+        self,
+        bindings: ImportBindings,
+        filepath: Path,
+        lines: list[str],
+    ) -> None:
+        self.bindings = bindings
+        self.filepath = filepath
+        self.lines = lines
+        self.issues: list[Issue] = []
+        # Names that refer to a MonkeyPatch fixture / instance
+        self._monkey_names: set[str] = {"monkeypatch"}
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._visit_function(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._visit_function(node)
+
+    def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        # Pytest injects the fixture by parameter name ``monkeypatch``.
+        for arg in _iter_args(node.args):
+            if arg.arg == "monkeypatch":
+                self._monkey_names.add("monkeypatch")
+        self.generic_visit(node)
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        if self._is_monkeypatch_ctor(node.value):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    self._monkey_names.add(target.id)
+        self.generic_visit(node)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        if node.value is not None and self._is_monkeypatch_ctor(node.value):
+            if isinstance(node.target, ast.Name):
+                self._monkey_names.add(node.target.id)
+        self.generic_visit(node)
+
+    def visit_With(self, node: ast.With) -> None:
+        self._visit_with(node)
+
+    def visit_AsyncWith(self, node: ast.AsyncWith) -> None:
+        self._visit_with(node)
+
+    def _visit_with(self, node: ast.With | ast.AsyncWith) -> None:
+        for item in node.items:
+            if self._is_monkeypatch_ctor(item.context_expr) and item.optional_vars is not None:
+                if isinstance(item.optional_vars, ast.Name):
+                    self._monkey_names.add(item.optional_vars.id)
+            # ``with monkeypatch.context() as m`` — context() is itself flagged
+            if (
+                isinstance(item.context_expr, ast.Call)
+                and self._is_monkeypatch_method_call(item.context_expr)
+                and item.optional_vars is not None
+                and isinstance(item.optional_vars, ast.Name)
+            ):
+                self._monkey_names.add(item.optional_vars.id)
+        self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        if self.bindings.is_patch_call_func(node.func):
+            self._maybe_add_issue(node)
+        elif self._is_monkeypatch_method_call(node):
+            self._maybe_add_issue(node)
+        self.generic_visit(node)
+
+    def _is_monkeypatch_ctor(self, node: ast.AST) -> bool:
+        return isinstance(node, ast.Call) and self.bindings.is_monkeypatch_class(node.func)
+
+    def _is_monkeypatch_method_call(self, node: ast.Call) -> bool:
+        func = node.func
+        if not isinstance(func, ast.Attribute):
+            return False
+        if func.attr not in MONKEYPATCH_METHODS:
+            return False
+        return self._is_monkeypatch_receiver(func.value)
+
+    def _is_monkeypatch_receiver(self, node: ast.AST) -> bool:
+        if isinstance(node, ast.Name):
+            return node.id in self._monkey_names
+        # MonkeyPatch().setattr(...)
+        if isinstance(node, ast.Call) and self.bindings.is_monkeypatch_class(node.func):
+            return True
+        return False
+
+    def _maybe_add_issue(self, node: ast.AST) -> None:
+        line_num = getattr(node, "lineno", 1)
+        col = getattr(node, "col_offset", 0) + 1
+        code_line = self.lines[line_num - 1] if 0 < line_num <= len(self.lines) else ""
+        if line_has_noqa(code_line):
+            return
+        self.issues.append(
+            Issue(
+                filepath=self.filepath,
+                line_num=line_num,
+                col=col,
+                message=f"{CODE} {MESSAGE}",
+                code_line=code_line.strip(),
+            )
+        )
+
+
+def _iter_args(args: ast.arguments):
+    yield from args.posonlyargs
+    yield from args.args
+    yield from args.kwonlyargs
+    if args.vararg is not None:
+        yield args.vararg
+    if args.kwarg is not None:
+        yield args.kwarg

patch_linter-1.0.0/src/patch_linter/cli.py

@@ -0,0 +1,36 @@
+"""Command-line entry point for patch-linter."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from patch_linter.checker import analyze_paths
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        description="Forbid unittest.mock.patch and pytest monkeypatch in tests",
+    )
+    parser.add_argument(
+        "paths",
+        nargs="+",
+        type=Path,
+        help="Test files or directories to analyze",
+    )
+    args = parser.parse_args(argv)
+
+    issues = analyze_paths(list(args.paths))
+    for issue in issues:
+        print(issue.format(), file=sys.stderr)
+
+    if issues:
+        print(f"Found {len(issues)} patch usage problem(s).", file=sys.stderr)
+        sys.exit(1)
+
+    print("All checks have been successful!")
+
+
+if __name__ == "__main__":
+    main()

patch_linter-1.0.0/src/patch_linter/flake8_plugin.py

@@ -0,0 +1,52 @@
+"""Flake8 plugin for patch-linter."""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Generator
+from pathlib import Path
+from typing import Any
+
+from patch_linter import __version__
+from patch_linter.checker import analyze_source
+
+
+class PatchLinter:
+    """Flake8 extension that reports PATCH001 for patch / monkeypatch usage."""
+
+    name = "patch-linter"
+    version = __version__
+
+    def __init__(
+        self,
+        tree: ast.AST,
+        filename: str = "stdin",
+        lines: list[str] | None = None,
+    ) -> None:
+        self.tree = tree
+        self.filename = filename
+        self.lines = lines
+
+    def run(self) -> Generator[tuple[int, int, str, type[Any]], None, None]:
+        if self.filename in {"stdin", "-", ""}:
+            return
+
+        path = Path(self.filename)
+        source: str | None = None
+        if self.lines is not None:
+            source = "\n".join(self.lines)
+            if self.lines and not source.endswith("\n"):
+                # Preserve last line without forcing an extra blank for AST
+                pass
+        else:
+            try:
+                source = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                return
+
+        if source is None:
+            return
+
+        for issue in analyze_source(source, path, tree=self.tree):
+            # Flake8 column is 0-based; our Issue.col is 1-based for CLI links.
+            yield issue.line_num, max(issue.col - 1, 0), issue.message, type(self)

patch_linter-1.0.0/src/patch_linter/imports.py

@@ -0,0 +1,107 @@
+"""Resolve import aliases for unittest.mock.patch and pytest.MonkeyPatch."""
+
+from __future__ import annotations
+
+import ast
+
+ModulePath = tuple[str, ...]
+
+PATCH_PATH: ModulePath = ("unittest", "mock", "patch")
+MONKEYPATCH_CLASS_PATH: ModulePath = ("pytest", "MonkeyPatch")
+
+PATCH_API_ATTRS = frozenset({"object", "dict", "multiple", "stopall"})
+
+MONKEYPATCH_METHODS = frozenset(
+    {
+        "setattr",
+        "delattr",
+        "setitem",
+        "delitem",
+        "setenv",
+        "delenv",
+        "syspath_prepend",
+        "chdir",
+        "context",
+        "undo",
+    }
+)
+
+
+class ImportBindings:
+    """Maps local names to dotted import paths."""
+
+    def __init__(self) -> None:
+        self._names: dict[str, ModulePath] = {}
+
+    def bind(self, name: str, path: ModulePath) -> None:
+        self._names[name] = path
+
+    def get(self, name: str) -> ModulePath | None:
+        return self._names.get(name)
+
+    def resolve(self, node: ast.AST) -> ModulePath | None:
+        """Resolve Name / Attribute chain to a module path, if known."""
+        parts = _attr_parts(node)
+        if not parts:
+            return None
+
+        head = self._names.get(parts[0])
+        if head is None:
+            # Bare ``unittest.mock.patch`` without import of ``unittest`` still
+            # works if the full chain is written out and unittest is a real
+            # top-level name we treat as itself when present as Name.
+            if parts[0] in {"unittest", "pytest"}:
+                return tuple(parts)
+            return None
+        return head + tuple(parts[1:])
+
+    def is_patch_root(self, node: ast.AST) -> bool:
+        return self.resolve(node) == PATCH_PATH
+
+    def is_patch_call_func(self, node: ast.AST) -> bool:
+        """True if ``node`` is patch(...) or patch.object/dict/multiple/stopall."""
+        if self.is_patch_root(node):
+            return True
+        if isinstance(node, ast.Attribute) and node.attr in PATCH_API_ATTRS:
+            return self.is_patch_root(node.value)
+        return False
+
+    def is_monkeypatch_class(self, node: ast.AST) -> bool:
+        return self.resolve(node) == MONKEYPATCH_CLASS_PATH
+
+
+def collect_imports(tree: ast.AST) -> ImportBindings:
+    bindings = ImportBindings()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                local = alias.asname or alias.name.split(".", 1)[0]
+                path = tuple(alias.name.split("."))
+                # ``import unittest.mock as um`` → um = (unittest, mock)
+                # ``import unittest`` → unittest = (unittest,)
+                if alias.asname:
+                    bindings.bind(alias.asname, path)
+                else:
+                    # Only bind the top-level name for ``import a.b.c``
+                    bindings.bind(local, (path[0],))
+        elif isinstance(node, ast.ImportFrom):
+            if node.module is None:
+                continue
+            base = tuple(node.module.split("."))
+            for alias in node.names:
+                if alias.name == "*":
+                    continue
+                local = alias.asname or alias.name
+                bindings.bind(local, base + (alias.name,))
+    return bindings
+
+
+def _attr_parts(node: ast.AST) -> list[str] | None:
+    if isinstance(node, ast.Name):
+        return [node.id]
+    if isinstance(node, ast.Attribute):
+        parent = _attr_parts(node.value)
+        if parent is None:
+            return None
+        return parent + [node.attr]
+    return None

patch_linter-1.0.0/src/patch_linter/models.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Issue:
+    """A single patch-usage finding."""
+
+    filepath: Path
+    line_num: int
+    col: int
+    message: str
+    code_line: str
+
+    def format(self) -> str:
+        """GCC/flake8-style line that IDEs treat as a clickable link."""
+        path = self.filepath.resolve()
+        return (
+            f"{path}:{self.line_num}:{self.col}: {self.message}: {self.code_line}"
+        )

patch_linter-1.0.0/tests/fixtures/bad_patches.py

@@ -0,0 +1,17 @@
+"""Bad examples: patch-linter must report PATCH001 for each marked line."""
+
+from unittest.mock import patch
+
+
+@patch("module.function")
+def test_decorator(mock_function):
+    mock_function.return_value = "mocked"
+
+
+def test_context_manager():
+    with patch("module.function") as mock_function:
+        mock_function.return_value = "mocked"
+
+
+def test_monkeypatch(monkeypatch):
+    monkeypatch.setattr("module.function", lambda: "mocked")

patch_linter-1.0.0/tests/fixtures/clean_tests.py

@@ -0,0 +1,35 @@
+"""Clean examples: patch-linter must report nothing."""
+
+
+def process_data(repository):
+    return repository.get_all()
+
+
+def test_with_injected_fake():
+    class FakeRepo:
+        def get_all(self):
+            return [1, 2, 3]
+
+    assert process_data(FakeRepo()) == [1, 2, 3]
+
+
+def patch(value):
+    """Local helper named patch — must not be flagged."""
+    return value
+
+
+def test_local_patch_helper():
+    assert patch("ok") == "ok"
+
+
+class Client:
+    def patch(self, url: str) -> str:
+        return url
+
+
+def test_client_patch_method():
+    assert Client().patch("/api") == "/api"
+
+
+def test_monkeypatch_unused(monkeypatch):
+    assert monkeypatch is not None

patch_linter-1.0.0/tests/test_checker.py

@@ -0,0 +1,243 @@
+from pathlib import Path
+
+from patch_linter.checker import analyze_file, analyze_source, line_has_noqa
+
+
+def _issues(tmp_path: Path, source: str):
+    path = tmp_path / "test_sample.py"
+    path.write_text(source, encoding="utf-8")
+    return analyze_file(path)
+
+
+def test_detects_unittest_patch_decorator(tmp_path: Path):
+    source = '''
+from unittest.mock import patch
+
+@patch("module.function")
+def test_function(mock_function):
+    mock_function.return_value = "mocked"
+'''
+    issues = _issues(tmp_path, source)
+    assert len(issues) == 1
+    assert "PATCH001" in issues[0].message
+    assert issues[0].col >= 1
+
+
+def test_detects_patch_alias(tmp_path: Path):
+    source = '''
+from unittest.mock import patch as p
+
+@p("module.function")
+def test_function(mock_function):
+    pass
+'''
+    issues = _issues(tmp_path, source)
+    assert len(issues) == 1
+
+
+def test_detects_mock_patch_via_module(tmp_path: Path):
+    source = '''
+from unittest import mock
+
+def test_function():
+    with mock.patch("module.function") as mocked:
+        mocked.return_value = 1
+'''
+    issues = _issues(tmp_path, source)
+    assert len(issues) == 1
+
+
+def test_detects_unittest_mock_patch_full(tmp_path: Path):
+    source = '''
+import unittest
+
+def test_function():
+    with unittest.mock.patch("module.function"):
+        pass
+'''
+    issues = _issues(tmp_path, source)
+    assert len(issues) == 1
+
+
+def test_detects_patch_object_dict_multiple_stopall(tmp_path: Path):
+    source = '''
+from unittest.mock import patch
+
+def test_function():
+    with patch.object(object, "x", 1):
+        pass
+    with patch.dict("os.environ", {"A": "1"}):
+        pass
+    with patch.multiple("module", a=1):
+        pass
+    patch.stopall()
+'''
+    issues = _issues(tmp_path, source)
+    assert len(issues) == 4
+
+
+def test_detects_import_unittest_mock_as(tmp_path: Path):
+    source = '''
+import unittest.mock as um
+
+def test_function():
+    with um.patch("module.function"):
+        pass
+'''
+    issues = _issues(tmp_path, source)
+    assert len(issues) == 1
+
+
+def test_detects_monkeypatch_setattr(tmp_path: Path):
+    source = '''
+def test_function(monkeypatch):
+    monkeypatch.setattr("module.function", lambda: "mocked")
+'''
+    issues = _issues(tmp_path, source)
+    assert len(issues) == 1
+
+
+def test_detects_monkeypatch_other_methods(tmp_path: Path):
+    source = '''
+def test_function(monkeypatch):
+    monkeypatch.setenv("A", "1")
+    monkeypatch.delenv("A", raising=False)
+    monkeypatch.chdir("/tmp")
+'''
+    issues = _issues(tmp_path, source)
+    assert len(issues) == 3
+
+
+def test_detects_monkeypatch_class_instance(tmp_path: Path):
+    source = '''
+from pytest import MonkeyPatch
+
+def test_function():
+    mp = MonkeyPatch()
+    mp.setattr("module.function", lambda: 1)
+'''
+    issues = _issues(tmp_path, source)
+    assert len(issues) == 1
+
+
+def test_noqa_patch001_suppresses(tmp_path: Path):
+    source = '''
+from unittest.mock import patch
+
+@patch("module.function")  # noqa: PATCH001
+def test_function(mock_function):
+    pass
+'''
+    issues = _issues(tmp_path, source)
+    assert issues == []
+
+
+def test_bare_noqa_suppresses(tmp_path: Path):
+    source = '''
+from unittest.mock import patch
+
+@patch("module.function")  # noqa
+def test_function(mock_function):
+    pass
+'''
+    issues = _issues(tmp_path, source)
+    assert issues == []
+
+
+def test_noqa_other_code_does_not_suppress(tmp_path: Path):
+    source = '''
+from unittest.mock import patch
+
+@patch("module.function")  # noqa: E501
+def test_function(mock_function):
+    pass
+'''
+    issues = _issues(tmp_path, source)
+    assert len(issues) == 1
+
+
+def test_ignores_custom_patch_function(tmp_path: Path):
+    source = '''
+def patch(x):
+    return x
+
+def test_function():
+    patch("hello")
+'''
+    issues = _issues(tmp_path, source)
+    assert issues == []
+
+
+def test_ignores_client_patch(tmp_path: Path):
+    source = '''
+class Client:
+    def patch(self, url):
+        return url
+
+def test_function():
+    Client().patch("/api")
+'''
+    issues = _issues(tmp_path, source)
+    assert issues == []
+
+
+def test_ignores_mocker_patch(tmp_path: Path):
+    source = '''
+def test_function(mocker):
+    mocker.patch("module.function")
+'''
+    issues = _issues(tmp_path, source)
+    assert issues == []
+
+
+def test_ignores_monkeypatch_param_without_call(tmp_path: Path):
+    source = '''
+def test_function(monkeypatch):
+    assert monkeypatch is not None
+'''
+    issues = _issues(tmp_path, source)
+    assert issues == []
+
+
+def test_syntax_error_returns_empty(tmp_path: Path, capsys):
+    path = tmp_path / "bad.py"
+    path.write_text("def (\n", encoding="utf-8")
+    assert analyze_file(path) == []
+    err = capsys.readouterr().err
+    assert "syntax error" in err.lower() or "Warning" in err
+
+
+def test_issue_format_is_clickable(tmp_path: Path):
+    source = '''
+from unittest.mock import patch
+
+@patch("x")
+def test_function(m):
+    pass
+'''
+    issues = _issues(tmp_path, source)
+    formatted = issues[0].format()
+    assert formatted.startswith(str(issues[0].filepath.resolve()))
+    assert ":PATCH001 " in formatted.replace(" ", "") or "PATCH001" in formatted
+    # path:line:col:
+    parts = formatted.split(":", 3)
+    assert parts[1].isdigit()
+    assert parts[2].isdigit()
+
+
+def test_line_has_noqa_helpers():
+    assert line_has_noqa("x  # noqa")
+    assert line_has_noqa("x  # noqa: PATCH001")
+    assert line_has_noqa("x  # noqa: E501, PATCH001")
+    assert not line_has_noqa("x  # noqa: E501")
+    assert not line_has_noqa("x  # no comment")
+
+
+def test_analyze_source_with_tree(tmp_path: Path):
+    import ast
+
+    source = "from unittest.mock import patch\n\n@patch('a')\ndef t(m):\n    pass\n"
+    tree = ast.parse(source)
+    path = tmp_path / "t.py"
+    issues = analyze_source(source, path, tree=tree)
+    assert len(issues) == 1

patch_linter-1.0.0/tests/test_integration.py

@@ -0,0 +1,98 @@
+"""End-to-end checks: fixtures + CLI behave as documented."""
+
+from __future__ import annotations
+
+import ast
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from patch_linter.checker import analyze_file, analyze_paths
+from patch_linter.cli import main
+from patch_linter.flake8_plugin import PatchLinter
+
+FIXTURES = Path(__file__).parent / "fixtures"
+BAD = FIXTURES / "bad_patches.py"
+CLEAN = FIXTURES / "clean_tests.py"
+
+
+def test_fixture_bad_patches_reports_expected_count():
+    issues = analyze_file(BAD)
+    assert len(issues) == 3
+    assert all("PATCH001" in i.message for i in issues)
+    lines = {i.line_num for i in issues}
+    # decorator, context manager, monkeypatch.setattr
+    assert lines == {6, 12, 17}
+
+
+def test_fixture_clean_tests_reports_nothing():
+    assert analyze_file(CLEAN) == []
+
+
+def test_analyze_paths_directory_finds_only_bad():
+    issues = analyze_paths([FIXTURES])
+    bad_only = [i for i in issues if i.filepath.resolve() == BAD.resolve()]
+    clean_hits = [i for i in issues if i.filepath.resolve() == CLEAN.resolve()]
+    assert len(bad_only) == 3
+    assert clean_hits == []
+
+
+def test_cli_fails_on_bad_fixture(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main([str(BAD)])
+    assert exc.value.code == 1
+    err = capsys.readouterr().err
+    assert "PATCH001" in err
+    assert str(BAD.resolve()) in err
+    # clickable path:line:col:
+    assert f"{BAD.resolve()}:" in err
+    assert err.count("PATCH001") == 3
+
+
+def test_cli_succeeds_on_clean_fixture(capsys):
+    main([str(CLEAN)])
+    out = capsys.readouterr().out
+    assert "All checks have been successful!" in out
+
+
+def test_cli_subprocess_matches_library():
+    result = subprocess.run(
+        [sys.executable, "-m", "patch_linter.cli", str(BAD)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 1
+    assert "PATCH001" in result.stderr
+    assert str(BAD.resolve()) in result.stderr
+
+    ok = subprocess.run(
+        [sys.executable, "-m", "patch_linter.cli", str(CLEAN)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert ok.returncode == 0
+    assert "successful" in ok.stdout.lower()
+
+
+def test_flake8_plugin_on_bad_fixture():
+    source = BAD.read_text(encoding="utf-8")
+    tree = ast.parse(source)
+    plugin = PatchLinter(tree=tree, filename=str(BAD), lines=source.splitlines())
+    findings = list(plugin.run())
+    assert len(findings) == 3
+    for line, col, message, checker in findings:
+        assert line in {6, 12, 17}
+        assert col >= 0
+        assert message.startswith("PATCH001")
+        assert checker is PatchLinter
+
+
+def test_flake8_plugin_on_clean_fixture():
+    source = CLEAN.read_text(encoding="utf-8")
+    tree = ast.parse(source)
+    plugin = PatchLinter(tree=tree, filename=str(CLEAN), lines=source.splitlines())
+    assert list(plugin.run()) == []

patch_linter-1.0.0/uv.lock

@@ -0,0 +1,127 @@
+version = 1
+revision = 1
+requires-python = ">=3.11"
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335 },
+]
+
+[[package]]
+name = "flake8"
+version = "7.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mccabe" },
+    { name = "pycodestyle" },
+    { name = "pyflakes" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9b/af/fbfe3c4b5a657d79e5c47a2827a362f9e1b763336a52f926126aa6dc7123/flake8-7.3.0.tar.gz", hash = "sha256:fe044858146b9fc69b551a4b490d69cf960fcb78ad1edcb84e7fbb1b4a8e3872", size = 48326 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9f/56/13ab06b4f93ca7cac71078fbe37fcea175d3216f31f85c3168a6bbd0bb9a/flake8-7.3.0-py2.py3-none-any.whl", hash = "sha256:b9696257b9ce8beb888cdbe31cf885c90d31928fe202be0889a7cdafad32f01e", size = 57922 },
+]
+
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484 },
+]
+
+[[package]]
+name = "mccabe"
+version = "0.7.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e7/ff/0ffefdcac38932a54d2b5eed4e0ba8a408f215002cd178ad1df0f2806ff8/mccabe-0.7.0.tar.gz", hash = "sha256:348e0240c33b60bbdf4e523192ef919f28cb2c3d7d5c7794f74009290f236325", size = 9658 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/27/1a/1f68f9ba0c207934b35b86a8ca3aad8395a3d6dd7921c0686e23853ff5a9/mccabe-0.7.0-py2.py3-none-any.whl", hash = "sha256:6c2d30ab6be0e4a46919781807b4f0d834ebdd6c6e3dca0bda5a15f863427b6e", size = 7350 },
+]
+
+[[package]]
+name = "packaging"
+version = "26.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/fa/3944b40b07da9ce895c0e6303a5ab7d53da063554f534556b134a54d6093/packaging-26.3.tar.gz", hash = "sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79", size = 313412 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c", size = 129956 },
+]
+
+[[package]]
+name = "patch-linter"
+version = "1.0.0"
+source = { editable = "." }
+
+[package.optional-dependencies]
+flake8 = [
+    { name = "flake8" },
+]
+
+[package.dev-dependencies]
+dev = [
+    { name = "pytest" },
+]
+
+[package.metadata]
+requires-dist = [{ name = "flake8", marker = "extra == 'flake8'", specifier = ">=7.2.0" }]
+provides-extras = ["flake8"]
+
+[package.metadata.requires-dev]
+dev = [{ name = "pytest", specifier = ">=8.3.5" }]
+
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538 },
+]
+
+[[package]]
+name = "pycodestyle"
+version = "2.14.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/11/e0/abfd2a0d2efe47670df87f3e3a0e2edda42f055053c85361f19c0e2c1ca8/pycodestyle-2.14.0.tar.gz", hash = "sha256:c4b5b517d278089ff9d0abdec919cd97262a3367449ea1c8b49b91529167b783", size = 39472 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d7/27/a58ddaf8c588a3ef080db9d0b7e0b97215cee3a45df74f3a94dbbf5c893a/pycodestyle-2.14.0-py2.py3-none-any.whl", hash = "sha256:dd6bf7cb4ee77f8e016f9c8e74a35ddd9f67e1d5fd4184d86c3b98e07099f42d", size = 31594 },
+]
+
+[[package]]
+name = "pyflakes"
+version = "3.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/45/dc/fd034dc20b4b264b3d015808458391acbf9df40b1e54750ef175d39180b1/pyflakes-3.4.0.tar.gz", hash = "sha256:b24f96fafb7d2ab0ec5075b7350b3d2d2218eab42003821c06344973d3ea2f58", size = 64669 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c2/2f/81d580a0fb83baeb066698975cb14a618bdbed7720678566f1b046a95fe8/pyflakes-3.4.0-py2.py3-none-any.whl", hash = "sha256:f742a7dbd0d9cb9ea41e9a24a918996e8170c799fa528688d40dd582c8265f4f", size = 63551 },
+]
+
+[[package]]
+name = "pygments"
+version = "2.20.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151 },
+]
+
+[[package]]
+name = "pytest"
+version = "9.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e4/47/b9efed96c114afcfa3c9d3fe98a76a1d14c74a9e266d397cf6eb64be5e01/pytest-9.1.1.tar.gz", hash = "sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313", size = 1636369 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536 },
+]