Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(hooks): catch aliased os imports in check-pathlib-usage (#4994)

LearningCircuitd6b1ebfd4d4b
diff --git a/.pre-commit-hooks/check-pathlib-usage.py b/.pre-commit-hooks/check-pathlib-usage.py
index 42347c818a..f2efaf2a28 100755
--- a/.pre-commit-hooks/check-pathlib-usage.py
+++ b/.pre-commit-hooks/check-pathlib-usage.py
@@ -11,7 +11,6 @@ import argparse
import ast
import sys
from pathlib import Path
-from typing import List, Tuple
class OsPathChecker(ast.NodeVisitor):
@@ -19,15 +18,17 @@ class OsPathChecker(ast.NodeVisitor):
def __init__(self, filename: str):
self.filename = filename
- self.violations: List[Tuple[int, str]] = []
- self.has_os_import = False
+ self.violations: list[tuple[int, str]] = []
+ # Local names bound to the ``os`` module. Includes aliases from
+ # ``import os as <alias>`` so they cannot bypass the check.
+ self.os_module_names: set[str] = set()
self.has_os_path_import = False
def visit_Import(self, node: ast.Import) -> None:
- """Check for 'import os' statements."""
+ """Check for 'import os' statements (incl. ``import os as <alias>``)."""
for alias in node.names:
if alias.name == "os":
- self.has_os_import = True
+ self.os_module_names.add(alias.asname or "os")
self.generic_visit(node)
def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
@@ -57,9 +58,8 @@ class OsPathChecker(ast.NodeVisitor):
"""Check for os.path.* usage."""
if (
isinstance(node.value, ast.Name)
- and node.value.id == "os"
+ and node.value.id in self.os_module_names
and node.attr == "path"
- and self.has_os_import
):
# This is os.path usage
# Try to get the specific method being called
@@ -88,7 +88,7 @@ class OsPathChecker(ast.NodeVisitor):
if (
isinstance(node.func.value, ast.Attribute)
and isinstance(node.func.value.value, ast.Name)
- and node.func.value.value.id == "os"
+ and node.func.value.value.id in self.os_module_names
and node.func.value.attr == "path"
):
method = node.func.attr
@@ -127,7 +127,7 @@ def get_pathlib_equivalent(os_path_call: str) -> str:
def check_file(
filepath: Path, allow_legacy: bool = False
-) -> List[Tuple[str, int, str]]:
+) -> list[tuple[str, int, str]]:
"""
Check a Python file for os.path usage.
diff --git a/changelog.d/+pathlib-hook-alias-detection.misc.md b/changelog.d/+pathlib-hook-alias-detection.misc.md
new file mode 100644
index 0000000000..9bab30c305
--- /dev/null
+++ b/changelog.d/+pathlib-hook-alias-detection.misc.md
@@ -0,0 +1 @@
+The `check-pathlib-usage` pre-commit hook now catches `import os as <alias>` followed by `<alias>.path.*`. Previously the AST matcher only flagged the literal name `os`, so an aliased import silently bypassed the check — which is how a `_os.path.join(...)` slipped into #4880 and had to be caught by human review instead.
diff --git a/tests/hooks/test_check_pathlib_usage.py b/tests/hooks/test_check_pathlib_usage.py
new file mode 100644
index 0000000000..6317b3cbad
--- /dev/null
+++ b/tests/hooks/test_check_pathlib_usage.py
@@ -0,0 +1,132 @@
+"""
+Tests for the check-pathlib-usage pre-commit hook.
+
+Covers the alias-bypass regression: ``import os as <alias>`` followed by
+``<alias>.path.*`` used to slip past the AST matcher because it only
+looked for the literal name ``os``. That is how a ``_os.path.join(...)``
+landed in #4880 and had to be caught by human review.
+"""
+
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+HOOK_SCRIPT = (
+ Path(__file__).parent.parent.parent
+ / ".pre-commit-hooks"
+ / "check-pathlib-usage.py"
+)
+
+
+def _run_hook(
+ content: str, filename: str = "service.py"
+) -> subprocess.CompletedProcess:
+ with tempfile.TemporaryDirectory() as d:
+ path = Path(d) / filename
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(content)
+ return subprocess.run(
+ [sys.executable, str(HOOK_SCRIPT), str(path)],
+ capture_output=True,
+ text=True,
+ )
+
+
+class TestPlainOsPath:
+ """Regression guards: the pre-existing ``os.path.*`` detection still works."""
+
+ def test_plain_os_path_join_is_caught(self):
+ result = _run_hook("import os\nx = os.path.join('a', 'b')\n")
+ assert result.returncode == 1
+ assert "os.path.join" in result.stdout
+
+ def test_from_os_import_path_is_caught(self):
+ result = _run_hook("from os import path\n")
+ assert result.returncode == 1
+ assert "from os import path" in result.stdout
+
+ def test_from_os_path_import_join_is_caught(self):
+ result = _run_hook("from os.path import join\n")
+ assert result.returncode == 1
+ assert "from os.path import join" in result.stdout
+
+ def test_expandvars_is_allowed(self):
+ """os.path.expandvars has no pathlib equivalent and must not be flagged."""
+ result = _run_hook("import os\nx = os.path.expandvars('$HOME')\n")
+ assert result.returncode == 0
+
+
+class TestAliasedOsImport:
+ """The bug: ``import os as <alias>`` used to bypass the matcher."""
+
+ def test_aliased_os_path_join_is_caught(self):
+ """The exact pattern that slipped into #4880."""
+ result = _run_hook("import os as _os\nx = _os.path.join('a', 'b')\n")
+ assert result.returncode == 1
+ assert "os.path.join" in result.stdout
+
+ def test_aliased_os_path_exists_is_caught(self):
+ result = _run_hook(
+ "import os as os_module\n"
+ "if os_module.path.exists('/x'):\n"
+ " pass\n"
+ )
+ assert result.returncode == 1
+ assert "os.path.exists" in result.stdout
+
+ def test_aliased_expandvars_is_allowed(self):
+ """Alias bypass must not extend the expandvars carve-out to new code
+ — but expandvars itself stays allowed regardless of how os is bound."""
+ result = _run_hook(
+ "import os as _os\nx = _os.path.expandvars('$HOME')\n"
+ )
+ assert result.returncode == 0
+
+ def test_multiple_aliases_in_one_import(self):
+ """``import os, sys`` style — os is still tracked."""
+ result = _run_hook("import os, sys\nx = os.path.join('a', 'b')\n")
+ assert result.returncode == 1
+ assert "os.path.join" in result.stdout
+
+
+class TestNoFalsePositives:
+ """Aliased ``os`` imports that do NOT touch ``.path`` must stay silent."""
+
+ def test_aliased_os_chmod_only(self):
+ result = _run_hook("import os as _os\n_os.chmod('/tmp/x', 0o644)\n")
+ assert result.returncode == 0
+
+ def test_aliased_os_environ_only(self):
+ result = _run_hook(
+ "import os as os_module\nci = os_module.environ.get('CI')\n"
+ )
+ assert result.returncode == 0
+
+ def test_clean_pathlib_code(self):
+ result = _run_hook("from pathlib import Path\np = Path('a') / 'b'\n")
+ assert result.returncode == 0
+
+ def test_no_os_import_at_all(self):
+ result = _run_hook("x = 'hello'\nprint(x)\n")
+ assert result.returncode == 0
+
+
+class TestAllowedFilesBypass:
+ """The ALLOWED_FILES list in the hook must still suppress violations
+ for the legacy exceptions."""
+
+ def test_log_utils_is_exempt(self):
+ result = _run_hook(
+ "import os\nx = os.path.join('a', 'b')\n",
+ filename="src/local_deep_research/utilities/log_utils.py",
+ )
+ assert result.returncode == 0
+
+ def test_paths_config_is_exempt(self):
+ result = _run_hook(
+ "import os\nx = os.path.join('a', 'b')\n",
+ filename="src/local_deep_research/config/paths.py",
+ )
+ assert result.returncode == 0