claude-dev-env 1.95.0 → 2.0.0

package/hooks/blocking/claude_md_orphan_file_blocker_parts/CLAUDE.md

@@ -0,0 +1,28 @@
+# claude_md_orphan_file_blocker_parts
+
+The concern modules `claude_md_orphan_file_blocker.py` wires together to block a
+per-directory `CLAUDE.md` that names a file absent from its subtree. The entry
+hook imports them and re-exports their surface for the test suite.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `references.py` | Extracts the bare filenames a table cell names and the scripts a fenced run command invokes, honoring the `../` relative-path exemptions |
+| `subtree_scan.py` | Resolves the scan root and reports which referenced filenames are absent from it, with a bounded walk plus a direct probe fallback |
+| `scan_plan.py` | Builds the Write/Edit/MultiEdit scan plan and collects the orphan filenames the change introduces, excluding pre-existing orphans |
+| `decision.py` | Builds the deny payload listing the missing files and closing with the retry hint, and emits the decision JSON |
+| `__init__.py` | Package marker |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `config/` | The region-join newline, the retry hint the deny reason closes with, and the missing-name join separator (`orphan_blocker_constants.py`) |
+| `tests/` | pytest suite with one test module per module above |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/hooks/blocking/claude_md_orphan_file_blocker_parts/tests/
+```

package/hooks/blocking/claude_md_orphan_file_blocker_parts/__init__.py

@@ -0,0 +1 @@
+"""Concern modules the ``claude_md_orphan_file_blocker`` entry hook wires together."""

package/hooks/blocking/claude_md_orphan_file_blocker_parts/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration home for the CLAUDE.md orphan-file blocker parts constants."""

package/hooks/blocking/claude_md_orphan_file_blocker_parts/config/orphan_blocker_constants.py

@@ -0,0 +1,18 @@
+"""Constants for the CLAUDE.md orphan-file blocker parts.
+
+Holds the newline that joins a region's lines before scanning it for a
+relative-path source, the separator that joins the missing filenames in the deny
+reason, and the retry hint the deny reason closes with once the denied inventory
+row has been recorded as a pending intent.
+"""
+
+from __future__ import annotations
+
+NEWLINE_JOIN_SEPARATOR: str = "\n"
+
+MISSING_NAME_JOIN_SEPARATOR: str = ", "
+
+ROW_FIRST_RETRY_HINT: str = (
+    " This inventory row has been recorded: create the file it names now, and the "
+    "row will be allowed when you retry it."
+)

package/hooks/blocking/claude_md_orphan_file_blocker_parts/decision.py

@@ -0,0 +1,81 @@
+"""Build, record, and emit the CLAUDE.md orphan-file blocker's deny decision.
+
+The deny reason lists each missing file and closes with the retry hint telling
+the author to create the file now, since this row has been recorded.
+"""
+
+import json
+import sys
+from typing import TextIO
+
+from claude_md_orphan_file_blocker_parts.config.orphan_blocker_constants import (
+    MISSING_NAME_JOIN_SEPARATOR,
+    ROW_FIRST_RETRY_HINT,
+)
+
+from hooks_constants.claude_md_orphan_file_blocker_constants import (
+    ORPHAN_FILE_ADDITIONAL_CONTEXT,
+    ORPHAN_FILE_MESSAGE_TEMPLATE,
+    ORPHAN_FILE_SYSTEM_MESSAGE,
+)
+from hooks_constants.hook_block_logger import log_hook_block
+
+
+def deny_orphan_files(
+    tool_name: str, file_path: str, directory: str, all_missing_filenames: list[str]
+) -> None:
+    """Build, record, and emit the deny decision listing the missing files.
+
+    Args:
+        tool_name: The intercepted tool name, for the block log record.
+        file_path: The destination path of the CLAUDE.md.
+        directory: The resolved CLAUDE.md directory.
+        all_missing_filenames: The referenced filenames absent from the subtree.
+    """
+    block_payload = build_block_payload(all_missing_filenames, directory)
+    log_hook_block(
+        calling_hook_name="claude_md_orphan_file_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=block_payload["hookSpecificOutput"]["permissionDecisionReason"],
+        tool_name=tool_name,
+        offending_input_preview=file_path,
+    )
+    emit_hook_result(block_payload, sys.stdout)
+
+
+def build_block_payload(all_missing_filenames: list[str], directory: str) -> dict:
+    """Build the PreToolUse deny payload listing each missing filename.
+
+    Args:
+        all_missing_filenames: The referenced filenames absent from the subtree.
+        directory: The directory that holds the target CLAUDE.md.
+
+    Returns:
+        The hook-result dictionary the harness reads to deny the write, whose
+        reason closes with the retry hint.
+    """
+    formatted_missing = MISSING_NAME_JOIN_SEPARATOR.join(
+        f"`{each_name}`" for each_name in all_missing_filenames
+    )
+    reason = ORPHAN_FILE_MESSAGE_TEMPLATE.format(directory=directory, missing=formatted_missing)
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason + ROW_FIRST_RETRY_HINT,
+            "additionalContext": ORPHAN_FILE_ADDITIONAL_CONTEXT,
+        },
+        "systemMessage": ORPHAN_FILE_SYSTEM_MESSAGE,
+        "suppressOutput": True,
+    }
+
+
+def emit_hook_result(all_hook_data: dict, output_stream: TextIO) -> None:
+    """Write the hook result JSON to the given output stream.
+
+    Args:
+        all_hook_data: The hook-result dictionary to serialize.
+        output_stream: The stream the harness reads the decision from.
+    """
+    output_stream.write(json.dumps(all_hook_data) + "\n")
+    output_stream.flush()

package/hooks/blocking/claude_md_orphan_file_blocker_parts/references.py

@@ -0,0 +1,307 @@
+"""Extract the file references a per-directory CLAUDE.md makes.
+
+Two kinds of reference are collected: a bare filename a first-column table cell
+names in backticks, and a script an interpreter invocation inside a fenced run
+command names (``python script.py``). A table block or run-command fence that
+declares an explicit ``../`` relative-path source is left alone.
+"""
+
+import os
+
+from claude_md_orphan_file_blocker_parts.config.orphan_blocker_constants import (
+    NEWLINE_JOIN_SEPARATOR,
+)
+
+from hooks_constants.claude_md_orphan_file_blocker_constants import (
+    ALL_REFERENCED_FILE_EXTENSIONS,
+    ALL_RUN_COMMAND_SCRIPT_EXTENSIONS,
+    CLAUDE_MD_FILENAME,
+    CODE_FENCE_PATTERN,
+    FIRST_COLUMN_BACKTICK_PATTERN,
+    REGION_BOUNDARY_PATTERN,
+    RELATIVE_PATH_SOURCE_PATTERN,
+    RUN_COMMAND_SCRIPT_PATTERN,
+    SEPARATOR_CELL_PATTERN,
+    TABLE_ROW_PATTERN,
+)
+
+
+def is_claude_md_file(file_path: str) -> bool:
+    """Return whether *file_path* names a per-directory ``CLAUDE.md`` file.
+
+    Args:
+        file_path: The destination path of the write or edit.
+
+    Returns:
+        True when the path's basename is exactly ``CLAUDE.md``.
+    """
+    return os.path.basename(file_path) == CLAUDE_MD_FILENAME
+
+
+def _first_table_cell(table_line: str) -> str:
+    """Return the trimmed text of the first column cell in a markdown table row.
+
+    Args:
+        table_line: A single line that begins with a pipe character.
+
+    Returns:
+        The text between the leading pipe and the next pipe, stripped.
+    """
+    after_leading_pipe = table_line.strip().lstrip("|")
+    first_cell, _, _ = after_leading_pipe.partition("|")
+    return first_cell.strip()
+
+
+def _referenced_filename_in_cell(cell_text: str) -> str | None:
+    """Return the bare filename a table cell references, when it has one.
+
+    A cell references a bare filename only when its first backticked token has no
+    path separator, is not a slash-command, and carries a known file extension.
+
+    Args:
+        cell_text: The trimmed text of a first-column table cell.
+
+    Returns:
+        The bare filename to verify in the subtree, or None when the cell names
+        no bare file.
+    """
+    backtick_match = FIRST_COLUMN_BACKTICK_PATTERN.search(cell_text)
+    if backtick_match is None:
+        return None
+    inner_text = backtick_match.group(1).strip()
+    if not inner_text or inner_text.startswith("/"):
+        return None
+    if "/" in inner_text or "\\" in inner_text:
+        return None
+    _, extension = os.path.splitext(inner_text)
+    if extension.lower() not in ALL_REFERENCED_FILE_EXTENSIONS:
+        return None
+    return inner_text
+
+
+def _filename_in_table_row(table_line: str) -> str | None:
+    """Return the bare filename a markdown table row references, when it has one.
+
+    Args:
+        table_line: A single line that begins with a pipe character.
+
+    Returns:
+        The bare filename in the row's first column, or None when the row is a
+        header-separator row or names no bare file.
+    """
+    first_cell = _first_table_cell(table_line)
+    if not first_cell or SEPARATOR_CELL_PATTERN.match(first_cell):
+        return None
+    return _referenced_filename_in_cell(first_cell)
+
+
+def _declares_relative_path_source(text: str) -> bool:
+    """Return whether *text* declares an explicit relative-path file source.
+
+    Args:
+        text: A table block together with the prose that introduces it.
+
+    Returns:
+        True when *text* contains a ``../`` relative-path token.
+    """
+    return RELATIVE_PATH_SOURCE_PATTERN.search(text) is not None
+
+
+def _block_filenames(all_region_lines: list[str], all_block_lines: list[str]) -> list[str]:
+    """Return the bare filenames a table block contributes, honoring its exemption.
+
+    Args:
+        all_region_lines: The prose lines accumulated before this block.
+        all_block_lines: The consecutive table rows that form the block.
+
+    Returns:
+        Each bare filename the block's first-column cells name, or an empty list
+        when the block (with its introducing region) declares a ``../`` source.
+    """
+    if not all_block_lines:
+        return []
+    block_region = NEWLINE_JOIN_SEPARATOR.join(all_region_lines + all_block_lines)
+    if _declares_relative_path_source(block_region):
+        return []
+    block_filenames: list[str] = []
+    for each_line in all_block_lines:
+        each_filename = _filename_in_table_row(each_line)
+        if each_filename is not None:
+            block_filenames.append(each_filename)
+    return block_filenames
+
+
+def find_referenced_filenames(content: str) -> list[str]:
+    """Return each bare filename a CLAUDE.md table references, in order.
+
+    Args:
+        content: The CLAUDE.md content being written.
+
+    Returns:
+        Each referenced filename from a non-exempt table block, in order.
+    """
+    referenced_filenames: list[str] = []
+    pending_region: list[str] = []
+    current_block: list[str] = []
+    is_inside_code_fence = False
+    for each_line in content.splitlines():
+        if CODE_FENCE_PATTERN.match(each_line) is not None:
+            is_inside_code_fence = not is_inside_code_fence
+            continue
+        if is_inside_code_fence:
+            continue
+        if TABLE_ROW_PATTERN.match(each_line) is not None:
+            current_block.append(each_line)
+            continue
+        if current_block:
+            referenced_filenames.extend(_block_filenames(pending_region, current_block))
+            current_block, pending_region = [], []
+        if REGION_BOUNDARY_PATTERN.match(each_line) is not None:
+            pending_region = []
+        pending_region.append(each_line)
+    referenced_filenames.extend(_block_filenames(pending_region, current_block))
+    return referenced_filenames
+
+
+def _script_basename_from_token(script_token: str) -> str | None:
+    """Return the bare basename one captured script token names, when it has one.
+
+    A path-qualified script keeps only its final segment. A script named by an
+    explicit ``../`` relative-path source is exempt and yields None, as does a
+    token whose basename carries no recognized script extension.
+
+    Args:
+        script_token: One script path captured from an interpreter invocation.
+
+    Returns:
+        The bare script basename, or None when the token is relative-path-sourced
+        or carries no recognized extension.
+    """
+    if _declares_relative_path_source(script_token):
+        return None
+    basename = os.path.basename(script_token.replace("\\", "/").rstrip("/"))
+    if not basename:
+        return None
+    _, extension = os.path.splitext(basename)
+    if extension.lower() not in ALL_RUN_COMMAND_SCRIPT_EXTENSIONS:
+        return None
+    return basename
+
+
+def _next_quote_state(open_quote_character: str, each_character: str) -> str:
+    """Return the open-quote state after reading one character.
+
+    Args:
+        open_quote_character: The currently open quote character, or empty.
+        each_character: The character just read.
+
+    Returns:
+        The empty string when a matching close quote is read, the character when
+        it opens a quote, or the unchanged state otherwise.
+    """
+    if open_quote_character:
+        return "" if each_character == open_quote_character else open_quote_character
+    if each_character in ("'", '"'):
+        return each_character
+    return open_quote_character
+
+
+def _command_text_before_comment(fenced_line: str) -> str:
+    """Return the runnable portion of a fenced line, with any shell comment removed.
+
+    A shell comment starts at a ``#`` that begins a word outside any quoted span
+    and runs to end of line; the text from that ``#`` is dropped.
+
+    Args:
+        fenced_line: A single line drawn from inside a fenced code block.
+
+    Returns:
+        The line truncated at its first unquoted word-leading ``#``, or the whole
+        line when it carries no such comment marker.
+    """
+    open_quote_character = ""
+    previous_character = ""
+    for each_index, each_character in enumerate(fenced_line):
+        starts_word = each_index == 0 or previous_character.isspace()
+        if not open_quote_character and each_character == "#" and starts_word:
+            return fenced_line[:each_index]
+        open_quote_character = _next_quote_state(open_quote_character, each_character)
+        previous_character = each_character
+    return fenced_line
+
+
+def _run_command_filenames_in_line(fenced_line: str) -> list[str]:
+    """Return each script basename the interpreter invocations on this line name.
+
+    A shell comment's text contributes nothing; a chained line contributes each
+    invocation's basename in order.
+
+    Args:
+        fenced_line: A single line drawn from inside a fenced code block.
+
+    Returns:
+        Each bare script basename the line's invocations name, in order.
+    """
+    runnable_text = _command_text_before_comment(fenced_line)
+    line_filenames: list[str] = []
+    for each_match in RUN_COMMAND_SCRIPT_PATTERN.finditer(runnable_text):
+        each_basename = _script_basename_from_token(each_match.group(1).strip())
+        if each_basename is not None:
+            line_filenames.append(each_basename)
+    return line_filenames
+
+
+class _RunCommandScan:
+    """Walks CLAUDE.md lines and collects the script basenames fenced run commands name.
+
+    Attributes:
+        filenames: The script basenames collected so far, in order.
+    """
+
+    def __init__(self) -> None:
+        self.filenames: list[str] = []
+        self._pending_region: list[str] = []
+        self._is_inside_fence = False
+        self._is_region_relative_path_sourced = False
+
+    def _toggle_fence(self) -> None:
+        """Open or close the current fence, capturing its region's ``../`` source flag."""
+        if not self._is_inside_fence:
+            self._is_region_relative_path_sourced = _declares_relative_path_source(
+                NEWLINE_JOIN_SEPARATOR.join(self._pending_region)
+            )
+        else:
+            self._pending_region = []
+        self._is_inside_fence = not self._is_inside_fence
+
+    def consume(self, each_line: str) -> None:
+        """Fold one CLAUDE.md line into the scan state.
+
+        Args:
+            each_line: The next line of the CLAUDE.md content.
+        """
+        if CODE_FENCE_PATTERN.match(each_line) is not None:
+            self._toggle_fence()
+            return
+        if self._is_inside_fence:
+            if not self._is_region_relative_path_sourced:
+                self.filenames.extend(_run_command_filenames_in_line(each_line))
+            return
+        if REGION_BOUNDARY_PATTERN.match(each_line) is not None:
+            self._pending_region = []
+        self._pending_region.append(each_line)
+
+
+def find_run_command_filenames(content: str) -> list[str]:
+    """Return each script basename a fenced run command invokes, in order.
+
+    Args:
+        content: The CLAUDE.md content being written.
+
+    Returns:
+        Each script basename a fenced run command names, in the order it appears.
+    """
+    scan = _RunCommandScan()
+    for each_line in content.splitlines():
+        scan.consume(each_line)
+    return scan.filenames

package/hooks/blocking/claude_md_orphan_file_blocker_parts/scan_plan.py

@@ -0,0 +1,124 @@
+"""Build the orphan scan plan for a Write, Edit, or MultiEdit of a CLAUDE.md.
+
+For a Write the plan scans the full new content with no baseline. For an Edit or
+MultiEdit it scans the reconstructed post-edit file and records the orphans the
+file already held, so a pre-existing orphan on an untouched line is excluded and
+only an orphan the edit introduces is reported.
+"""
+
+from pathlib import Path
+
+from claude_md_orphan_file_blocker_parts.subtree_scan import find_missing_filenames
+
+from hooks_constants.claude_md_orphan_file_blocker_constants import (
+    MAX_ORPHAN_FILE_ISSUES,
+)
+from hooks_constants.multi_edit_reconstruction import (
+    apply_edits,
+    edits_for_tool,
+)
+
+
+def _read_existing_file_content(file_path: str) -> str | None:
+    """Return the current on-disk content of *file_path*, or None when unreadable.
+
+    Args:
+        file_path: The path of the file the edit targets.
+
+    Returns:
+        The file's text, or None when the file is missing or cannot be decoded.
+    """
+    try:
+        return Path(file_path).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def _edit_fragments(all_edits: list[dict]) -> list[str]:
+    """Return each MultiEdit ``new_string`` fragment present as a non-empty string.
+
+    Args:
+        all_edits: The MultiEdit ``edits`` list.
+
+    Returns:
+        Every ``new_string`` value that is a non-empty string, in list order.
+    """
+    all_fragments: list[str] = []
+    for each_edit in all_edits:
+        if not isinstance(each_edit, dict):
+            continue
+        new_string = each_edit.get("new_string", "")
+        if isinstance(new_string, str) and new_string:
+            all_fragments.append(new_string)
+    return all_fragments
+
+
+class _OrphanScanPlan:
+    """The contents to scan for orphans and the pre-existing orphans to exclude.
+
+    Attributes:
+        candidate_contents: Each content string whose table rows are scanned.
+        baseline_missing_filenames: The orphan filenames the file already held
+            before this edit; reporting excludes them.
+    """
+
+    def __init__(
+        self, all_candidate_contents: list[str], all_baseline_missing_filenames: set[str]
+    ) -> None:
+        self.candidate_contents = all_candidate_contents
+        self.baseline_missing_filenames = all_baseline_missing_filenames
+
+
+def build_orphan_scan_plan(
+    tool_name: str, tool_input: dict, file_path: str, claude_md_directory: Path
+) -> _OrphanScanPlan:
+    """Return the contents to scan and the pre-existing orphans to exclude.
+
+    Args:
+        tool_name: The intercepted tool — ``Write``, ``Edit``, or ``MultiEdit``.
+        tool_input: The tool's input payload.
+        file_path: The destination path of the write or edit.
+        claude_md_directory: The directory that holds the target CLAUDE.md.
+
+    Returns:
+        The scan plan pairing candidate contents with the baseline orphan set.
+    """
+    if tool_name == "Write":
+        content = tool_input.get("content", "")
+        candidate_contents = [content] if isinstance(content, str) and content else []
+        return _OrphanScanPlan(candidate_contents, set())
+    all_edits = edits_for_tool(tool_name, tool_input)
+    existing_content = _read_existing_file_content(file_path)
+    if existing_content is None:
+        return _OrphanScanPlan(_edit_fragments(all_edits), set())
+    baseline_missing = set(find_missing_filenames(existing_content, claude_md_directory))
+    return _OrphanScanPlan([apply_edits(existing_content, all_edits)], baseline_missing)
+
+
+def collect_missing_filenames(scan_plan: _OrphanScanPlan, claude_md_directory: Path) -> list[str]:
+    """Return every orphan filename the scan plan introduces, excluding baselines.
+
+    Args:
+        scan_plan: The candidate contents to scan paired with the baseline orphan
+            set to exclude.
+        claude_md_directory: The directory that holds the target CLAUDE.md.
+
+    Returns:
+        Each introduced orphan filename in first-seen order with duplicates
+        removed, capped at the issue budget.
+    """
+    all_candidate_missing: list[str] = []
+    for each_content in scan_plan.candidate_contents:
+        all_candidate_missing.extend(find_missing_filenames(each_content, claude_md_directory))
+    missing_filenames: list[str] = []
+    already_reported: set[str] = set()
+    for each_filename in all_candidate_missing:
+        if each_filename in scan_plan.baseline_missing_filenames:
+            continue
+        if each_filename in already_reported:
+            continue
+        already_reported.add(each_filename)
+        missing_filenames.append(each_filename)
+        if len(missing_filenames) >= MAX_ORPHAN_FILE_ISSUES:
+            break
+    return missing_filenames