claude-dev-env 1.42.0 → 1.44.0

package/hooks/blocking/md_path_exemptions.py

@@ -0,0 +1,205 @@
+"""Shared exemption rules for the .md blocker and its post-write companion.
+
+Both `md_to_html_blocker.py` (PreToolUse) and `md_to_html_companion.py`
+(PostToolUse) must agree on which file paths bypass the .md → .html policy.
+This module is the single source of truth for that decision.
+"""
+
+import os
+import sys
+from pathlib import Path, PureWindowsPath
+
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from hooks_constants.md_to_html_blocker_constants import (  # noqa: E402
+    ALL_CLAUDE_CODE_SOURCE_TOP_DIRECTORIES,
+    ALL_EXEMPT_ANYWHERE_FILENAMES_LOWER,
+    ALL_EXEMPT_HOME_DIRECTORY_PATH_PREFIXES,
+    ALL_EXEMPT_PLUGIN_DIRECTORY_SEGMENTS,
+    ALL_EXEMPT_ROOT_FILENAMES_LOWER,
+    CLAUDE_DEV_ENV_REPO_NAME_SEGMENT,
+    CLAUDE_DIRECTORY_PATH_PREFIX,
+    CLAUDE_DIRECTORY_SEGMENT_MARKER,
+    MINIMUM_SEGMENT_COUNT_TO_MATCH_INDICATOR,
+    PACKAGES_TOP_LEVEL_SEGMENT,
+    PLUGIN_DIRECTORY_PATH_PREFIX,
+    PLUGIN_DIRECTORY_SEGMENT_MARKER,
+    PLUGIN_ROOT_MARKER_DIRECTORY_NAME,
+    REPO_ROOT_MARKER_NAME,
+    RESOLVED_HOME_DIRECTORY_LOWER,
+    RESOLVED_TEMP_DIRECTORY_PATH_PREFIX,
+)
+
+
+def is_exempt_path(file_path: str) -> bool:
+    """Return True when the .md file path is exempt from the blocker policy.
+
+    Exemption sources, in order of evaluation:
+    - Any segment under `.claude/` or `.claude-plugin/` (case-insensitive)
+    - Basename in `ALL_EXEMPT_ANYWHERE_FILENAMES` (e.g. SKILL.md)
+    - Anchored under `packages/claude-dev-env/<one of
+      ALL_CLAUDE_CODE_SOURCE_TOP_DIRECTORIES>/...` (docs, rules,
+      system-prompts source files in this repo)
+    - Path segment in `ALL_EXEMPT_PLUGIN_DIRECTORY_SEGMENTS` (agents/skills/commands)
+    - Canonical path under a home-relative exempt directory
+      (`ALL_EXEMPT_HOME_RELATIVE_DIRECTORIES`)
+    - Canonical path under the OS temp directory
+    - Ancestor directory contains `.claude-plugin/` (plugin-root marker walk)
+    - Basename in `ALL_EXEMPT_ROOT_FILENAMES` and directory is a repo root
+
+    Args:
+        file_path: Raw file path from the hook payload. May contain tilde,
+            backslashes, or be relative.
+
+    Returns:
+        True when the path is exempt, False when the policy applies.
+    """
+    expanded_path = os.path.expanduser(file_path)
+    normalized = os.path.normpath(expanded_path).replace("\\", "/")
+    lower_normalized = normalized.lower()
+    if (
+        CLAUDE_DIRECTORY_SEGMENT_MARKER in lower_normalized
+        or lower_normalized.startswith(CLAUDE_DIRECTORY_PATH_PREFIX)
+    ):
+        return True
+    if (
+        PLUGIN_DIRECTORY_SEGMENT_MARKER in lower_normalized
+        or lower_normalized.startswith(PLUGIN_DIRECTORY_PATH_PREFIX)
+    ):
+        return True
+    basename_lower = os.path.basename(normalized).lower()
+    if basename_lower in ALL_EXEMPT_ANYWHERE_FILENAMES_LOWER:
+        return True
+    if _is_under_claude_dev_env_source_subdirectory(expanded_path, lower_normalized):
+        return True
+    if _has_plugin_directory_segment(lower_normalized):
+        return True
+    canonical_normalized_path = os.path.realpath(expanded_path).replace("\\", "/")
+    canonical_lower_path = canonical_normalized_path.lower()
+    if _is_under_exempt_home_directory(canonical_lower_path):
+        return True
+    if canonical_lower_path.startswith(RESOLVED_TEMP_DIRECTORY_PATH_PREFIX):
+        return True
+    if _is_under_plugin_root_marker(canonical_normalized_path):
+        return True
+    if basename_lower in ALL_EXEMPT_ROOT_FILENAMES_LOWER:
+        absolute_directory = _resolve_absolute_directory(normalized)
+        if _is_repo_root_directory(absolute_directory):
+            return True
+    return False
+
+
+def _resolve_absolute_directory(normalized_path: str) -> str:
+    directory = os.path.dirname(normalized_path)
+    if not directory or directory == ".":
+        return os.getcwd()
+    if os.path.isabs(directory):
+        return directory
+    return os.path.abspath(directory)
+
+
+def _has_plugin_directory_segment(lower_normalized_path: str) -> bool:
+    for each_directory_segment in ALL_EXEMPT_PLUGIN_DIRECTORY_SEGMENTS:
+        segment_marker = f"/{each_directory_segment}/"
+        if segment_marker in lower_normalized_path:
+            return True
+        if lower_normalized_path.startswith(f"{each_directory_segment}/"):
+            return True
+    return False
+
+
+def _is_absolute_path_cross_platform(file_path: str) -> bool:
+    """Detect absolute paths in both POSIX and Windows drive-letter forms.
+
+    ``os.path.isabs`` is platform-dependent: on Linux/macOS it classifies a
+    Windows drive-letter path like ``Y:\\repo\\foo`` as relative. The anchored
+    source-subdirectory exemption must scan every starting segment for
+    absolute paths regardless of host OS, so a path's absoluteness must be
+    decided cross-platform.
+
+    Args:
+        file_path: Tilde-expanded file path.
+
+    Returns:
+        True when the path is absolute under POSIX rules or carries a Windows
+        drive-letter root (``[A-Za-z]:[\\\\/]...``).
+    """
+    if os.path.isabs(file_path):
+        return True
+    return PureWindowsPath(file_path).is_absolute()
+
+
+def _is_under_claude_dev_env_source_subdirectory(
+    expanded_file_path: str, lower_normalized_path: str
+) -> bool:
+    """Anchored exemption for ``packages/claude-dev-env/<source-dir>/...``.
+
+    The match requires segment-anchored matching at the start of the path
+    (relative) or at the root of an absolute path. A nested path like
+    ``notes/packages/claude-dev-env/docs/foo.md`` is NOT exempt — only the
+    full three-segment anchor matches.
+
+    Args:
+        expanded_file_path: Tilde-expanded file path; ``os.path.isabs`` on
+            this form classifies the path as absolute or relative on the
+            current platform.
+        lower_normalized_path: Same path lowercased and with separators
+            normalized to forward slashes.
+
+    Returns:
+        True when the path is anchored under
+        ``packages/claude-dev-env/<one of
+        ALL_CLAUDE_CODE_SOURCE_TOP_DIRECTORIES>/``.
+    """
+    all_segments = [
+        each_segment
+        for each_segment in lower_normalized_path.split("/")
+        if each_segment
+    ]
+    if not all_segments:
+        return False
+    if _is_absolute_path_cross_platform(expanded_file_path):
+        starting_segment_index_options = list(range(len(all_segments)))
+    else:
+        starting_segment_index_options = [0]
+    for each_starting_index in starting_segment_index_options:
+        if (
+            len(all_segments) >= each_starting_index + MINIMUM_SEGMENT_COUNT_TO_MATCH_INDICATOR
+            and all_segments[each_starting_index] == PACKAGES_TOP_LEVEL_SEGMENT
+            and all_segments[each_starting_index + 1] == CLAUDE_DEV_ENV_REPO_NAME_SEGMENT
+            and all_segments[each_starting_index + 2] in ALL_CLAUDE_CODE_SOURCE_TOP_DIRECTORIES
+        ):
+            return True
+    return False
+
+
+def _is_under_plugin_root_marker(normalized_path: str) -> bool:
+    directory = os.path.dirname(normalized_path)
+    visited_directories: set[str] = set()
+    while directory and directory not in visited_directories:
+        visited_directories.add(directory)
+        marker_path = os.path.join(directory, PLUGIN_ROOT_MARKER_DIRECTORY_NAME)
+        if os.path.isdir(marker_path):
+            return True
+        parent_directory = os.path.dirname(directory)
+        if parent_directory == directory:
+            break
+        directory = parent_directory
+    return False
+
+
+def _is_under_exempt_home_directory(lower_normalized_path: str) -> bool:
+    if not RESOLVED_HOME_DIRECTORY_LOWER:
+        return False
+    for each_exempt_path_prefix in ALL_EXEMPT_HOME_DIRECTORY_PATH_PREFIXES:
+        if lower_normalized_path.startswith(each_exempt_path_prefix):
+            return True
+    return False
+
+
+def _is_repo_root_directory(directory_path: str) -> bool:
+    git_marker_path = os.path.join(directory_path, REPO_ROOT_MARKER_NAME)
+    return os.path.exists(git_marker_path)

package/hooks/blocking/md_to_html_blocker.py

@@ -6,27 +6,44 @@ that markdown flattens. See https://thariqs.github.io/html-effectiveness/
 """
 
 import json
-import os
 import sys
+from pathlib import Path
 from typing import TextIO
 
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
 
-_markdown_extension = ".md"
-_html_effectiveness_url = "https://thariqs.github.io/html-effectiveness/"
-_exempt_root_filenames = ("readme.md", "changelog.md")
+_blocking_directory = str(Path(__file__).resolve().parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+
+from hooks_constants.md_to_html_blocker_constants import (  # noqa: E402
+    ALL_CLAUDE_CODE_SOURCE_TOP_DIRECTORIES,
+    ALL_EXEMPT_ANYWHERE_FILENAMES,
+    ALL_EXEMPT_HOME_RELATIVE_DIRECTORIES,
+    ALL_EXEMPT_PLUGIN_DIRECTORY_SEGMENTS,
+    CLAUDE_DEV_ENV_REPO_NAME_SEGMENT,
+    CLAUDE_DIRECTORY_NAME,
+    PACKAGES_TOP_LEVEL_SEGMENT,
+    PLUGIN_ROOT_MARKER_DIRECTORY_NAME,
+)
+from md_path_exemptions import is_exempt_path  # noqa: E402
 
 
-def _is_exempt_path(file_path: str) -> bool:
-    normalized = os.path.normpath(file_path).replace("\\", "/")
-    lower_normalized = normalized.lower()
-    if "/.claude/" in lower_normalized or lower_normalized.startswith(".claude/"):
-        return True
-    basename = os.path.basename(normalized)
-    if basename.lower() in _exempt_root_filenames:
-        directory = os.path.dirname(normalized)
-        if directory in ("", "."):
-            return True
-    return False
+_markdown_extension = ".md"
+_html_effectiveness_url = "https://thariqs.github.io/html-effectiveness/"
+_exempt_anywhere_filenames_summary = ", ".join(ALL_EXEMPT_ANYWHERE_FILENAMES)
+_exempt_plugin_segments_summary = ", ".join(
+    f"{each_segment}/" for each_segment in ALL_EXEMPT_PLUGIN_DIRECTORY_SEGMENTS
+)
+_exempt_home_directories_summary = ", ".join(
+    f"~/{each_directory}/" for each_directory in ALL_EXEMPT_HOME_RELATIVE_DIRECTORIES
+)
+_claude_dev_env_source_directories_summary = (
+    f"{PACKAGES_TOP_LEVEL_SEGMENT}/{CLAUDE_DEV_ENV_REPO_NAME_SEGMENT}/"
+    f"{{{','.join(sorted(ALL_CLAUDE_CODE_SOURCE_TOP_DIRECTORIES))}}}/"
+)
 
 
 def _block_reason(file_path: str) -> str:
@@ -46,8 +63,14 @@ def _block_context() -> str:
         "Reference for HTML effectiveness patterns:\n"
         f"{_html_effectiveness_url}\n"
         "Exceptions (.md still allowed):\n"
-        "- Files inside .claude/ directories\n"
-        "- README.md and CHANGELOG.md at repo root"
+        f"- Files inside {CLAUDE_DIRECTORY_NAME}/ or {PLUGIN_ROOT_MARKER_DIRECTORY_NAME}/ directories\n"
+        f"- {_exempt_anywhere_filenames_summary} anywhere\n"
+        f"- Files under {_exempt_plugin_segments_summary} directories\n"
+        f"- Files under {_claude_dev_env_source_directories_summary} source directories\n"
+        f"- Files under any directory whose ancestor contains {PLUGIN_ROOT_MARKER_DIRECTORY_NAME}/\n"
+        "- README.md and CHANGELOG.md at any repo root\n"
+        f"- Files under {_exempt_home_directories_summary}\n"
+        "- Files under the OS temp directory"
     )
 
 
@@ -55,8 +78,13 @@ def _block_system_message() -> str:
     return (
         ".md files are blocked in this project — generate a self-contained .html "
         f"file instead. See {_html_effectiveness_url} for "
-        "design patterns and examples. Exemptions: .claude/ infrastructure, "
-        "README.md, CHANGELOG.md at repo root."
+        f"design patterns and examples. Exemptions: {CLAUDE_DIRECTORY_NAME}/ and "
+        f"{PLUGIN_ROOT_MARKER_DIRECTORY_NAME}/ infrastructure, "
+        f"{_exempt_anywhere_filenames_summary} anywhere, {_exempt_plugin_segments_summary} trees, "
+        f"{_claude_dev_env_source_directories_summary} source trees, "
+        f"files under a {PLUGIN_ROOT_MARKER_DIRECTORY_NAME}/ root, "
+        f"README.md/CHANGELOG.md at any repo root, {_exempt_home_directories_summary}, "
+        "and the OS temp directory."
     )
 
 
@@ -92,7 +120,7 @@ def main() -> None:
     if not file_path.lower().endswith(_markdown_extension):
         sys.exit(0)
 
-    if _is_exempt_path(file_path):
+    if is_exempt_path(file_path):
         sys.exit(0)
 
     block_payload = {

package/hooks/blocking/pr_converge_bugteam_enforcer.py

@@ -25,17 +25,11 @@ import sys
 from pathlib import Path
 from typing import TextIO
 
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
 
-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.pr_converge_bugteam_enforcer_constants import (
+from hooks_constants.pr_converge_bugteam_enforcer_constants import (  # noqa: E402
     AGENT_TOOL_NAME,
     ALL_AUDIT_PROMPT_SUBSTRINGS,
     BUGTEAM_PHASE,
@@ -47,7 +41,7 @@ from config.pr_converge_bugteam_enforcer_constants import (
     STATE_FIELD_PHASE,
     STATE_FIELD_TICK_COUNT,
 )
-from config.pr_converge_bugteam_enforcer_state import (
+from hooks_constants.pr_converge_bugteam_enforcer_state import (  # noqa: E402
     load_state_dictionary,
     resolve_state_path,
 )