claude-dev-env 1.28.0 → 1.29.0

package/hooks/session/test_untracked_repo_detector.py

@@ -0,0 +1,192 @@
+"""Tests for untracked_repo_detector — SessionStart hook for new repo detection."""
+
+import json
+import sys
+from io import StringIO
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import untracked_repo_detector as detector
+from config.project_paths_reader import registry_file_path
+from config.setup_project_paths_constants import GIT_DIRECTORY_SEGMENT_NAME
+
+
+def _run_main_with_cwd(cwd: str, known_registry: dict) -> tuple[str, str, int]:
+    """Return (stdout, stderr, exit_code) from running main() with patched cwd and registry."""
+    captured_stdout = StringIO()
+    captured_stderr = StringIO()
+    exit_code = 0
+    try:
+        with (
+            patch(
+                "untracked_repo_detector.current_working_directory", return_value=cwd
+            ),
+            patch("untracked_repo_detector.load_registry", return_value=known_registry),
+            patch("sys.stdout", captured_stdout),
+            patch("sys.stderr", captured_stderr),
+        ):
+            detector.main()
+    except SystemExit as e:
+        exit_code = e.code or 0
+    return captured_stdout.getvalue(), captured_stderr.getvalue(), exit_code
+
+
+class TestFindGitRoot:
+    def test_returns_none_when_no_git_directory_found(self, tmp_path: Path) -> None:
+        non_repo_path = tmp_path / "not-a-repo"
+        non_repo_path.mkdir()
+        original_exists = Path.exists
+
+        def exists_without_ambient_git(self_path: Path) -> bool:
+            if self_path.name == ".git" and tmp_path.resolve() not in self_path.resolve().parents and self_path.resolve().parent != tmp_path.resolve():
+                return False
+            return original_exists(self_path)
+
+        with patch.object(Path, "exists", exists_without_ambient_git):
+            found_root = detector.find_git_root(str(non_repo_path))
+        assert found_root is None
+
+    def test_returns_root_when_dot_git_exists(self, tmp_path: Path) -> None:
+        repo_root = tmp_path / "my-repo"
+        repo_root.mkdir()
+        (repo_root / ".git").mkdir()
+        found_root = detector.find_git_root(str(repo_root))
+        assert found_root is not None
+        assert Path(found_root).resolve() == repo_root.resolve()
+
+    def test_returns_root_when_cwd_is_subdirectory(self, tmp_path: Path) -> None:
+        repo_root = tmp_path / "my-repo"
+        nested_directory = repo_root / "src" / "deep"
+        nested_directory.mkdir(parents=True)
+        (repo_root / ".git").mkdir()
+        found_root = detector.find_git_root(str(nested_directory))
+        assert found_root is not None
+        assert Path(found_root).resolve() == repo_root.resolve()
+
+
+class TestRegistryContainsRepo:
+    def test_cwd_inside_tracked_repo_produces_no_output(self, tmp_path: Path) -> None:
+        repo_root = tmp_path / "tracked-repo"
+        repo_root.mkdir()
+        (repo_root / ".git").mkdir()
+        known_registry = {"tracked-repo": str(repo_root)}
+        stdout, _, _ = _run_main_with_cwd(str(repo_root), known_registry)
+        assert stdout.strip() == ""
+
+    def test_cwd_outside_any_git_repo_produces_no_output(self, tmp_path: Path) -> None:
+        non_repo = tmp_path / "not-a-repo"
+        non_repo.mkdir()
+        with patch("untracked_repo_detector.find_git_root", return_value=None):
+            stdout, _, _ = _run_main_with_cwd(str(non_repo), {})
+        assert stdout.strip() == ""
+
+
+class TestUntrackedRepoDetection:
+    def test_cwd_inside_untracked_repo_produces_additional_context(
+        self, tmp_path: Path
+    ) -> None:
+        repo_root = tmp_path / "new-repo"
+        repo_root.mkdir()
+        (repo_root / ".git").mkdir()
+        stdout, _, _ = _run_main_with_cwd(str(repo_root), {})
+        assert stdout.strip() != ""
+        emitted = json.loads(stdout)
+        assert "additionalContext" in emitted
+
+    def test_emitted_context_names_the_detected_repo_path(self, tmp_path: Path) -> None:
+        repo_root = tmp_path / "new-repo"
+        repo_root.mkdir()
+        (repo_root / ".git").mkdir()
+        stdout, _, _ = _run_main_with_cwd(str(repo_root), {})
+        emitted = json.loads(stdout)
+        context_text = emitted["additionalContext"]
+        assert str(repo_root) in context_text
+
+    def test_emitted_context_names_the_config_file_path(self, tmp_path: Path) -> None:
+        repo_root = tmp_path / "new-repo"
+        repo_root.mkdir()
+        (repo_root / ".git").mkdir()
+        stdout, _, _ = _run_main_with_cwd(str(repo_root), {})
+        emitted = json.loads(stdout)
+        context_text = emitted["additionalContext"]
+        assert "project-paths.json" in context_text
+
+    def test_emitted_context_instructs_claude_to_use_ask_user_question(
+        self, tmp_path: Path
+    ) -> None:
+        repo_root = tmp_path / "new-repo"
+        repo_root.mkdir()
+        (repo_root / ".git").mkdir()
+        stdout, _, _ = _run_main_with_cwd(str(repo_root), {})
+        emitted = json.loads(stdout)
+        context_text = emitted["additionalContext"]
+        assert "AskUserQuestion" in context_text
+
+    def test_emitted_context_states_hook_has_written_nothing(
+        self, tmp_path: Path
+    ) -> None:
+        repo_root = tmp_path / "new-repo"
+        repo_root.mkdir()
+        (repo_root / ".git").mkdir()
+        stdout, _, _ = _run_main_with_cwd(str(repo_root), {})
+        emitted = json.loads(stdout)
+        context_text = emitted["additionalContext"]
+        assert (
+            "written nothing" in context_text.lower()
+            or "has not written" in context_text.lower()
+        )
+
+
+class TestSharedRegistryPath:
+    def test_config_file_path_not_a_module_level_attribute(self) -> None:
+        """Pin PR #230 round 7: _CONFIG_FILE_PATH inlined into _build_confirm_instruction.
+
+        Single-consumer module-level constant moved to local per file-global-constants rule.
+        """
+        assert not hasattr(detector, "_CONFIG_FILE_PATH")
+
+    def test_confirm_instruction_contains_registry_file_path(
+        self, tmp_path: Path
+    ) -> None:
+        repo_root = str(tmp_path / "some-repo")
+        instruction_text = detector._build_confirm_instruction(repo_root)
+        assert str(registry_file_path()) in instruction_text
+
+    def test_confirm_instruction_contains_project_paths_json(
+        self, tmp_path: Path
+    ) -> None:
+        repo_root = str(tmp_path / "some-repo")
+        instruction_text = detector._build_confirm_instruction(repo_root)
+        assert "project-paths.json" in instruction_text
+
+
+class TestSharedGitDirectoryConstant:
+    def test_find_git_root_uses_shared_git_directory_constant(self, tmp_path: Path) -> None:
+        """Pin: find_git_root must use GIT_DIRECTORY_SEGMENT_NAME from shared constants."""
+        repo_root = tmp_path / "uses-shared-constant"
+        repo_root.mkdir()
+        (repo_root / GIT_DIRECTORY_SEGMENT_NAME).mkdir()
+        found_root = detector.find_git_root(str(repo_root))
+        assert found_root is not None
+
+
+class TestPathNormalization:
+    def test_windows_and_posix_forms_of_same_path_compare_equal(
+        self, tmp_path: Path
+    ) -> None:
+        repo_root = tmp_path / "cross-platform-repo"
+        repo_root.mkdir()
+        (repo_root / ".git").mkdir()
+        windows_path = str(repo_root)
+        posix_path = str(repo_root).replace("\\", "/")
+        registry_with_posix = {"cross-platform-repo": posix_path}
+        stdout, _, _ = _run_main_with_cwd(windows_path, registry_with_posix)
+        assert stdout.strip() == ""

package/hooks/session/untracked_repo_detector.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""SessionStart hook: detect git repos not present in ~/.claude/project-paths.json.
+
+When Claude Code opens inside a git repo that is not registered, emits an
+additionalContext instruction asking Claude to confirm the mapping with the
+user via AskUserQuestion before persisting anything. The hook itself never
+writes to the config file.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).resolve().parent.parent
+    hooks_tree_string = str(hooks_tree)
+    if hooks_tree_string not in sys.path:
+        sys.path.insert(0, hooks_tree_string)
+
+
+_insert_hooks_tree_for_imports()
+
+from config.dynamic_stderr_handler import DynamicStderrHandler
+from config.project_paths_reader import (
+    load_registry,
+    registry_contains_path,
+    registry_file_path,
+)
+from config.setup_project_paths_constants import GIT_DIRECTORY_SEGMENT_NAME
+
+
+_logger = logging.getLogger("untracked_repo_detector")
+if not _logger.handlers:
+    _stderr_handler = DynamicStderrHandler()
+    _stderr_handler.setFormatter(logging.Formatter("%(name)s: %(message)s"))
+    _logger.addHandler(_stderr_handler)
+    _logger.setLevel(logging.INFO)
+    _logger.propagate = False
+
+
+def current_working_directory() -> str:
+    """Return the process working directory as a string."""
+    return os.getcwd()
+
+
+def find_git_root(start_path: str) -> str | None:
+    """Walk upward from start_path looking for a .git directory.
+
+    The walk is bounded by the user's home directory: once the candidate
+    reaches the home directory without finding ``.git``, the search stops.
+    This prevents a stray ``.git`` above the user's home (for example a
+    parent dotfiles repo) from being falsely reported as the session's repo.
+
+    Returns the absolute path of the repo root, or None if not found.
+    """
+    home_directory = Path.home().resolve()
+    candidate = Path(start_path).resolve()
+    while True:
+        if (candidate / GIT_DIRECTORY_SEGMENT_NAME).exists():
+            return str(candidate)
+        if candidate == home_directory:
+            return None
+        parent = candidate.parent
+        if parent == candidate:
+            return None
+        candidate = parent
+
+
+def _build_confirm_instruction(repo_root: str) -> str:
+    config_file_path = str(registry_file_path())
+    return (
+        f"UNTRACKED REPO DETECTED: The current session is running inside a git "
+        f"repository at '{repo_root}' that is not present in {config_file_path}. "
+        f"Use AskUserQuestion with two options — 'Save mapping' (recommended) and "
+        f"'Skip for this session' — to confirm whether to persist this repo path. "
+        f"On approval, append a new entry to {config_file_path} mapping the "
+        f"repository leaf name to '{repo_root}'. This hook has written nothing."
+    )
+
+
+def main() -> None:
+    try:
+        session_cwd = current_working_directory()
+        git_root = find_git_root(session_cwd)
+        if git_root is None:
+            sys.exit(0)
+        known_registry = load_registry()
+        if registry_contains_path(known_registry, git_root):
+            sys.exit(0)
+        instruction = _build_confirm_instruction(git_root)
+        print(json.dumps({"additionalContext": instruction}))
+    except Exception as e:
+        _logger.error("%s", e)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/validators/exempt_paths.py

@@ -9,20 +9,28 @@ the two produced the "inconsistent verdicts" bug this module prevents.
 Matching is case-insensitive so paths like ``Config/foo.py`` or
 ``src/Tests/test_x.py`` are treated the same on case-preserving
 filesystems (macOS default, Windows NTFS) as on case-sensitive ones.
+
+``is_config_file`` canonical implementation lives in
+``hooks/blocking/code_rules_path_utils.py`` and is re-exported here so
+both the pre-write gate and the pre-push validator share identical logic.
 """
 
 from __future__ import annotations
 
+import sys
+from pathlib import Path
+
+
+def _ensure_blocking_package_on_path() -> None:
+    blocking_directory = str(Path(__file__).resolve().parent.parent / "blocking")
+    if blocking_directory not in sys.path:
+        sys.path.insert(0, blocking_directory)
+
+
+_ensure_blocking_package_on_path()
+
+from code_rules_path_utils import is_config_file  # type: ignore[import-not-found] # noqa: E402
 
-CONFIG_PATH_PATTERNS: frozenset[str] = frozenset(
-    {
-        "config/",
-        "config\\",
-        "/config.",
-        "\\config.",
-        "settings.py",
-    }
-)
 
 TEST_PATH_PATTERNS: frozenset[str] = frozenset(
     {
@@ -65,11 +73,6 @@ MIGRATION_PATH_PATTERNS: frozenset[str] = frozenset(
 )
 
 
-def is_config_file(file_path: str) -> bool:
-    path_lower = file_path.lower()
-    return any(pattern in path_lower for pattern in CONFIG_PATH_PATTERNS)
-
-
 def is_test_file(file_path: str) -> bool:
     path_lower = file_path.lower()
     return any(pattern in path_lower for pattern in TEST_PATH_PATTERNS)

package/hooks/validators/test_exempt_paths.py

@@ -0,0 +1,65 @@
+"""Tests for exempt_paths path-classification helpers.
+
+Covers the is_config_file() contract: only files whose parent directory
+segment is literally 'config' should match. A filename of 'config.py'
+outside a config/ directory must NOT match.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_BLOCKING_DIR = str(Path(__file__).resolve().parent.parent / "blocking")
+if _BLOCKING_DIR not in sys.path:
+    sys.path.insert(0, _BLOCKING_DIR)
+
+from validators.exempt_paths import is_config_file  # noqa: E402
+from code_rules_path_utils import is_config_file as path_utils_is_config_file  # noqa: E402
+
+
+def test_should_exempt_file_inside_config_directory() -> None:
+    assert is_config_file("project/config/constants.py") is True
+
+
+def test_should_exempt_file_inside_nested_config_directory() -> None:
+    assert is_config_file("packages/myapp/config/timing.py") is True
+
+
+def test_should_not_exempt_file_named_config_dot_py_outside_config_dir() -> None:
+    assert is_config_file("scripts/db/config.py") is False
+
+
+def test_should_not_exempt_file_with_config_in_filename_only() -> None:
+    assert is_config_file("src/app_config.py") is False
+
+
+def test_should_not_exempt_file_with_config_in_parent_partial_match() -> None:
+    assert is_config_file("src/reconfigured/constants.py") is False
+
+
+def test_should_exempt_settings_py_by_filename() -> None:
+    assert is_config_file("any/path/settings.py") is True
+
+
+def test_should_exempt_windows_path_inside_config_directory() -> None:
+    assert is_config_file("packages\\myapp\\config\\timing.py") is True
+
+
+def test_should_not_exempt_filename_ending_with_settings_py_but_not_exactly_settings_py() -> None:
+    assert is_config_file("mysettings.py") is False
+
+
+def test_should_exempt_bare_settings_py_filename() -> None:
+    assert is_config_file("settings.py") is True
+
+
+def test_should_exempt_settings_py_in_nested_path() -> None:
+    assert is_config_file("path/to/settings.py") is True
+
+
+def test_is_config_file_is_identical_function_object_from_path_utils() -> None:
+    """After refactor, exempt_paths.is_config_file must be the same object as path_utils."""
+    assert is_config_file is path_utils_is_config_file, (
+        "exempt_paths.is_config_file must be imported from code_rules_path_utils, not re-defined"
+    )

package/hooks/validators/test_git_checks.py

@@ -19,7 +19,7 @@ from .git_checks import (
 class TestSingleCommitWhenPrExists:
     """Test that PR branches have exactly 1 commit ahead of base."""
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_no_pr_returns_empty(self, mock_run: MagicMock) -> None:
         """When no PR exists, check should return empty list."""
         mock_run.side_effect = [
@@ -31,7 +31,7 @@ class TestSingleCommitWhenPrExists:
 
         assert violations == []
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_single_commit_ahead_passes(self, mock_run: MagicMock) -> None:
         """Exactly 1 commit ahead should pass."""
         mock_run.side_effect = [
@@ -44,7 +44,7 @@ class TestSingleCommitWhenPrExists:
 
         assert violations == []
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_zero_commits_ahead_fails(self, mock_run: MagicMock) -> None:
         """Zero commits ahead should fail."""
         mock_run.side_effect = [
@@ -61,7 +61,7 @@ class TestSingleCommitWhenPrExists:
         assert "exactly 1 commit" in violations[0].message
         assert "0 commits" in violations[0].message
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_multiple_commits_ahead_fails(self, mock_run: MagicMock) -> None:
         """More than 1 commit ahead should fail."""
         mock_run.side_effect = [
@@ -76,7 +76,7 @@ class TestSingleCommitWhenPrExists:
         assert "exactly 1 commit" in violations[0].message
         assert "3 commits" in violations[0].message
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_gh_cli_not_available_returns_empty(self, mock_run: MagicMock) -> None:
         """When gh CLI not available, should return empty (warning, not failure)."""
         mock_run.side_effect = [
@@ -88,7 +88,7 @@ class TestSingleCommitWhenPrExists:
 
         assert violations == []
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_git_not_available_returns_empty(self, mock_run: MagicMock) -> None:
         """When git not available, should return empty."""
         mock_run.side_effect = [
@@ -101,7 +101,7 @@ class TestSingleCommitWhenPrExists:
 
         assert violations == []
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_extracts_base_branch_from_pr_info(self, mock_run: MagicMock) -> None:
         """Should extract base branch name from gh pr list JSON output, falling back to main when absent."""
         mock_run.side_effect = [
@@ -140,7 +140,7 @@ class TestSingleCommitWhenPrExists:
             timeout=30,
         )
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_non_numeric_commit_count_returns_empty(self, mock_run: MagicMock) -> None:
         """When git rev-list returns non-numeric output, should return empty."""
         mock_run.side_effect = [
@@ -153,7 +153,7 @@ class TestSingleCommitWhenPrExists:
 
         assert violations == []
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_gh_timeout_returns_empty(self, mock_run: MagicMock) -> None:
         """When gh CLI times out, should return empty (warning, not failure)."""
         mock_run.side_effect = [
@@ -165,7 +165,7 @@ class TestSingleCommitWhenPrExists:
 
         assert violations == []
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_git_timeout_returns_empty(self, mock_run: MagicMock) -> None:
         """When git times out, should return empty (warning, not failure)."""
         mock_run.side_effect = [
@@ -178,7 +178,7 @@ class TestSingleCommitWhenPrExists:
 
         assert violations == []
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_passes_resolved_branch_name_to_gh(self, mock_run: MagicMock) -> None:
         """gh pr list must receive the resolved branch name, never the literal 'HEAD'."""
         mock_run.side_effect = [
@@ -197,7 +197,7 @@ class TestSingleCommitWhenPrExists:
             timeout=30,
         )
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_unresolved_branch_returns_empty(self, mock_run: MagicMock) -> None:
         """When current branch cannot be resolved, should return empty."""
         mock_run.side_effect = [
@@ -213,7 +213,7 @@ class TestSingleCommitWhenPrExists:
 class TestDraftPrState:
     """Test that PR is in draft state when pushing review fixes."""
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_no_pr_returns_empty(self, mock_run: MagicMock) -> None:
         """When no PR exists, check should return empty list."""
         mock_run.return_value = MagicMock(returncode=0, stdout="[]", stderr="")
@@ -222,7 +222,7 @@ class TestDraftPrState:
 
         assert violations == []
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_draft_pr_passes(self, mock_run: MagicMock) -> None:
         """Draft PR should pass."""
         mock_run.return_value = MagicMock(
@@ -235,7 +235,7 @@ class TestDraftPrState:
 
         assert violations == []
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_non_draft_pr_fails(self, mock_run: MagicMock) -> None:
         """Non-draft PR should fail."""
         mock_run.return_value = MagicMock(
@@ -252,7 +252,7 @@ class TestDraftPrState:
         assert "draft" in violations[0].message.lower()
         assert "gh pr ready --undo" in violations[0].message
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_gh_cli_not_available_returns_empty(self, mock_run: MagicMock) -> None:
         """When gh CLI not available, should return empty (warning, not failure)."""
         mock_run.side_effect = FileNotFoundError("gh not found")
@@ -261,7 +261,7 @@ class TestDraftPrState:
 
         assert violations == []
 
-    @patch("git_checks.subprocess.run")
+    @patch("validators.git_checks.subprocess.run")
     def test_gh_timeout_returns_empty(self, mock_run: MagicMock) -> None:
         """When gh CLI times out, should return empty (warning, not failure)."""
         mock_run.side_effect = subprocess.TimeoutExpired(cmd=["gh", "pr", "list"], timeout=30)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.28.0",
+    "version": "1.29.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/config/__init__.py

@@ -0,0 +1 @@
+"""Scripts configuration package — home for scalar constants per CODE_RULES."""