claude-dev-env 7.3.0 → 7.4.1

package/hooks/blocking/env_var_table_code_drift_blocker.py

@@ -25,22 +25,23 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
-from hooks_constants.env_var_table_code_drift_constants import (  # noqa: E402
-    ALL_CODE_FILE_EXTENSIONS,
+from env_var_table_rows import (
+    _code_file_reference_in_cell,
+    _env_var_name_in_cell,
+    _is_separator_row,
+    _row_cells,
+    iter_env_var_table_rows,
+)
+from hooks_constants.env_var_table_code_drift_constants import (
     ALL_NOISE_DIRECTORY_NAMES,
-    BACKTICK_TOKEN_PATTERN,
-    CODE_FENCE_PATTERN,
     DRIFT_ADDITIONAL_CONTEXT,
     DRIFT_MESSAGE_TEMPLATE,
     DRIFT_SYSTEM_MESSAGE,
-    ENV_VAR_NAME_PATTERN,
     GIT_DIRECTORY_NAME,
     MARKDOWN_FILE_EXTENSION,
     MAX_DRIFT_ISSUES,
     MAX_SUBTREE_FILES_SCANNED,
     MINIMUM_ENV_VAR_ROW_CELL_COUNT,
-    SEPARATOR_CELL_PATTERN,
-    TABLE_ROW_PATTERN,
 )
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.multi_edit_reconstruction import (  # noqa: E402
@@ -65,87 +66,6 @@ def is_markdown_file(file_path: str) -> bool:
     return extension.lower() == MARKDOWN_FILE_EXTENSION
 
 
-def _row_cells(table_line: str) -> list[str]:
-    """Return the trimmed cells of one markdown table row.
-
-    Args:
-        table_line: A single line that begins with a pipe character.
-
-    Returns:
-        The text of each pipe-delimited cell, stripped, with the empty leading
-        and trailing segments a bounding pipe produces removed.
-    """
-    stripped_line = table_line.strip()
-    inner = stripped_line.strip("|")
-    return [each_cell.strip() for each_cell in inner.split("|")]
-
-
-def _first_backtick_token(cell_text: str) -> str | None:
-    """Return the first backtick-wrapped token in a cell, when it has one.
-
-    Args:
-        cell_text: The trimmed text of a table cell.
-
-    Returns:
-        The text inside the first pair of backticks, or None when the cell
-        carries no backtick-wrapped token.
-    """
-    token_match = BACKTICK_TOKEN_PATTERN.search(cell_text)
-    if token_match is None:
-        return None
-    inner_text = token_match.group(1).strip()
-    return inner_text or None
-
-
-def _env_var_name_in_cell(cell_text: str) -> str | None:
-    """Return the environment-variable name a cell names, when it names one.
-
-    Args:
-        cell_text: The trimmed text of a table cell.
-
-    Returns:
-        The UPPER_SNAKE variable name inside the first backticks, or None when
-        the cell names no variable-shaped token.
-    """
-    token = _first_backtick_token(cell_text)
-    if token is None:
-        return None
-    if ENV_VAR_NAME_PATTERN.match(token) is None:
-        return None
-    return token
-
-
-def _code_file_reference_in_cell(cell_text: str) -> str | None:
-    """Return the code-file path a cell names, when it names one.
-
-    Args:
-        cell_text: The trimmed text of a table cell.
-
-    Returns:
-        The relative code-file path inside the first backticks, or None when the
-        token carries no recognized code-file extension.
-    """
-    token = _first_backtick_token(cell_text)
-    if token is None:
-        return None
-    _, extension = os.path.splitext(token)
-    if extension.lower() not in ALL_CODE_FILE_EXTENSIONS:
-        return None
-    return token
-
-
-def _is_separator_row(all_cells: list[str]) -> bool:
-    """Return whether every cell is a markdown table header-separator cell.
-
-    Args:
-        all_cells: The trimmed cells of one table row.
-
-    Returns:
-        True when each cell holds only dashes, colons, and whitespace.
-    """
-    return all(SEPARATOR_CELL_PATTERN.match(each_cell) is not None for each_cell in all_cells)
-
-
 def _resolve_scan_root(markdown_directory: Path) -> Path:
     """Return the repository directory whose subtree bounds the code-file search.
 
@@ -248,8 +168,8 @@ def _code_file_reads_variable(code_file: Path, variable_name: str) -> bool | Non
 def find_drift_rows(content: str, markdown_directory: Path) -> list[str]:
     """Return each env-var table row whose code file does not read the variable.
 
-    Walks the markdown content line by line, skipping lines inside a fenced code
-    block. A table row counts when its first cell names an UPPER_SNAKE variable and
+    Reads environment-variable tables and headerless edit fragments outside code
+    fences. A row counts when its first cell names an UPPER_SNAKE variable and
     a later cell names a code file with a recognized extension. The row drifts when
     that code file resolves under the scan root yet its source never references the
     variable name; a row whose code file does not resolve, or cannot be read, is
@@ -266,15 +186,7 @@ def find_drift_rows(content: str, markdown_directory: Path) -> list[str]:
     scan_root = _resolve_scan_root(markdown_directory)
     drift_rows: list[str] = []
     already_reported: set[str] = set()
-    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 None:
-            continue
+    for each_line in iter_env_var_table_rows(content):
         each_finding = _drift_finding_for_row(each_line, scan_root)
         if each_finding is None or each_finding in already_reported:
             continue

package/hooks/blocking/env_var_table_rows.py

@@ -0,0 +1,130 @@
+"""Recognize Markdown environment-variable tables and parse their cells."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+
+from hooks_constants.env_var_table_code_drift_constants import (
+    ALL_CODE_FILE_EXTENSIONS,
+    ALL_GENERIC_ENV_VAR_HEADERS,
+    BACKTICK_TOKEN_PATTERN,
+    CODE_FENCE_PATTERN,
+    ENV_VAR_HEADER_PATTERN,
+    ENV_VAR_HEADING_PATTERN,
+    ENV_VAR_NAME_PATTERN,
+    SEPARATOR_CELL_PATTERN,
+    TABLE_ROW_PATTERN,
+)
+
+
+def _row_cells(table_line: str) -> list[str]:
+    """Return the trimmed cells of one markdown table row.
+
+    Args:
+        table_line: A single line that begins with a pipe character.
+
+    Returns:
+        The text of each pipe-delimited cell, stripped, with the empty leading
+        and trailing segments a bounding pipe produces removed.
+    """
+    stripped_line = table_line.strip()
+    inner = stripped_line.strip("|")
+    return [each_cell.strip() for each_cell in inner.split("|")]
+
+
+def _first_backtick_token(cell_text: str) -> str | None:
+    """Return the first backtick-wrapped token in a cell, when it has one.
+
+    Args:
+        cell_text: The trimmed text of a table cell.
+
+    Returns:
+        The text inside the first pair of backticks, or None when the cell
+        carries no backtick-wrapped token.
+    """
+    token_match = BACKTICK_TOKEN_PATTERN.search(cell_text)
+    if token_match is None:
+        return None
+    inner_text = token_match.group(1).strip()
+    return inner_text or None
+
+
+def _env_var_name_in_cell(cell_text: str) -> str | None:
+    """Return the environment-variable name a cell names, when it names one.
+
+    Args:
+        cell_text: The trimmed text of a table cell.
+
+    Returns:
+        The UPPER_SNAKE variable name inside the first backticks, or None when
+        the cell names no variable-shaped token.
+    """
+    token = _first_backtick_token(cell_text)
+    if token is None:
+        return None
+    if ENV_VAR_NAME_PATTERN.match(token) is None:
+        return None
+    return token
+
+
+def _code_file_reference_in_cell(cell_text: str) -> str | None:
+    """Return the code-file path a cell names, when it names one.
+
+    Args:
+        cell_text: The trimmed text of a table cell.
+
+    Returns:
+        The relative code-file path inside the first backticks, or None when the
+        token carries no recognized code-file extension.
+    """
+    token = _first_backtick_token(cell_text)
+    if token is None:
+        return None
+    _, extension = os.path.splitext(token)
+    if extension.lower() not in ALL_CODE_FILE_EXTENSIONS:
+        return None
+    return token
+
+
+def _is_separator_row(all_cells: list[str]) -> bool:
+    """Return whether every cell is a markdown table header-separator cell.
+
+    Args:
+        all_cells: The trimmed cells of one table row.
+
+    Returns:
+        True when each cell holds only dashes, colons, and whitespace.
+    """
+    return all(SEPARATOR_CELL_PATTERN.match(each_cell) is not None for each_cell in all_cells)
+
+
+def iter_env_var_table_rows(content: str) -> Iterator[str]:
+    """Yield environment-table rows and headerless edit fragments outside code fences."""
+    is_inside_code_fence = False
+    is_environment_table: bool | None = None
+    is_environment_section = 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
+            is_environment_table = None
+            continue
+        if is_inside_code_fence:
+            continue
+        if each_line.lstrip().startswith("#"):
+            is_environment_section = ENV_VAR_HEADING_PATTERN.search(each_line) is not None
+        if TABLE_ROW_PATTERN.match(each_line) is None:
+            is_environment_table = None
+            continue
+        all_cells = _row_cells(each_line)
+        if not all_cells or _is_separator_row(all_cells):
+            continue
+        if is_environment_table is None:
+            header = all_cells[0].strip("`* ")
+            is_environment_table = (
+                ENV_VAR_HEADER_PATTERN.fullmatch(header) is not None
+                or _env_var_name_in_cell(all_cells[0]) is not None
+                or (is_environment_section and header.casefold() in ALL_GENERIC_ENV_VAR_HEADERS)
+            )
+        if is_environment_table:
+            yield each_line

package/hooks/blocking/pii_scanner.py

@@ -18,10 +18,9 @@ if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
 from hooks_constants.local_identity import nas_host  # noqa: E402
-from hooks_constants.pii_prevention_constants import (  # noqa: E402
+from hooks_constants.pii_prevention_constants import (
     ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES,
     ALL_EXACT_LEGAL_NOTICE_BASENAMES,
-    ALL_HOME_DIRECTORY_PATH_MARKERS,
     ALL_PLACEHOLDER_HOME_USERNAMES,
     ALL_REDACTED_PREVIEW_CATEGORIES,
     ALL_RFC1918_NETWORK_CIDRS,
@@ -37,6 +36,8 @@ from hooks_constants.pii_prevention_constants import (  # noqa: E402
     CONFTEST_BASENAME,
     EMAIL_PATTERN,
     HOME_PATH_PATTERN,
+    HOME_USERNAME_MARKER_PATTERN,
+    INTERPOLATED_HOME_USERNAME_PATTERN,
     IPV4_PATTERN,
     IPV4_VERSION_NUMBER,
     MAXIMUM_FINDINGS_PER_SCAN,
@@ -90,9 +91,7 @@ def is_path_exempt_from_pii_scan(file_path: str) -> bool:
         return False
     normalized_path = file_path.replace("\\", "/").lower()
     path_for_suffix_match = (
-        normalized_path
-        if normalized_path.startswith("/")
-        else f"/{normalized_path}"
+        normalized_path if normalized_path.startswith("/") else f"/{normalized_path}"
     )
     basename = os.path.basename(file_path)
     basename_lower = basename.lower()
@@ -106,9 +105,7 @@ def is_path_exempt_from_pii_scan(file_path: str) -> bool:
         or basename_lower.endswith(TEST_MODULE_BASENAME_SUFFIX)
     ):
         return True
-    if TESTS_PATH_SEGMENT in normalized_path or normalized_path.startswith(
-        TESTS_PATH_PREFIX
-    ):
+    if TESTS_PATH_SEGMENT in normalized_path or normalized_path.startswith(TESTS_PATH_PREFIX):
         return True
     if basename_lower.endswith(ALL_SOURCE_TEST_FILE_SUFFIXES) and (
         SPEC_BASENAME_MARKER in basename_lower or TEST_BASENAME_MARKER in basename_lower
@@ -130,11 +127,7 @@ def _redact_sensitive_preview(matched_text: str) -> str:
         return REDACTED_SHORT_PREVIEW
     prefix_length = REDACTED_PREVIEW_PREFIX_LENGTH
     suffix_length = REDACTED_PREVIEW_SUFFIX_LENGTH
-    return (
-        matched_text[:prefix_length]
-        + REDACTED_PREVIEW_ELLIPSIS
-        + matched_text[-suffix_length:]
-    )
+    return matched_text[:prefix_length] + REDACTED_PREVIEW_ELLIPSIS + matched_text[-suffix_length:]
 
 
 def _build_preview(matched_text: str, category: str) -> str:
@@ -161,8 +154,7 @@ def _is_safe_email_domain(domain_name: str) -> bool:
     if domain_name in ALL_SAFE_EMAIL_DOMAINS:
         return True
     return any(
-        domain_name.endswith("." + each_safe_domain)
-        for each_safe_domain in ALL_SAFE_EMAIL_DOMAINS
+        domain_name.endswith("." + each_safe_domain) for each_safe_domain in ALL_SAFE_EMAIL_DOMAINS
     )
 
 
@@ -180,8 +172,8 @@ def _home_username_offset(matched_path: str) -> tuple[int, str] | None:
 
         C:\\Users\\Users\\file.txt  ->  (9, "Users")   the second Users, not the first
 
-    Replacing backslashes with forward slashes preserves length, so the marker
-    offset computed on the normalized path indexes *matched_path* directly.
+    The marker match consumes repeated separators, so the username starts after
+    both ordinary and escaped Windows path separators.
 
     Args:
         matched_path: The matched home-path substring.
@@ -189,18 +181,14 @@ def _home_username_offset(matched_path: str) -> tuple[int, str] | None:
     Returns:
         The username's start index and value, or None when no marker is found.
     """
-    normalized_path = matched_path.replace("\\", "/")
-    lowered_path = normalized_path.lower()
-    for each_marker in ALL_HOME_DIRECTORY_PATH_MARKERS:
-        marker_index = lowered_path.find(each_marker)
-        if marker_index < 0:
-            continue
-        username_start = marker_index + len(each_marker)
-        username = normalized_path[username_start:].split("/", 1)[0]
-        if not username:
-            return None
-        return username_start, username
-    return None
+    marker = HOME_USERNAME_MARKER_PATTERN.search(matched_path)
+    if marker is None:
+        return None
+    username_start = marker.end()
+    username = matched_path[username_start:].replace("\\", "/").split("/", 1)[0]
+    if not username:
+        return None
+    return username_start, username
 
 
 def _username_from_home_path(matched_path: str) -> str | None:
@@ -226,6 +214,8 @@ def _redact_home_path_username(matched_text: str) -> str:
 
 
 def _is_placeholder_home_username(username: str) -> bool:
+    if INTERPOLATED_HOME_USERNAME_PATTERN.fullmatch(username) is not None:
+        return True
     if ANGLE_BRACKET_PLACEHOLDER_PATTERN.match(username) is not None:
         return True
     lowered_username = username.lower()

package/hooks/blocking/test_env_var_table_code_drift_blocker.py

@@ -125,9 +125,10 @@ def test_production_entrypoint_denies_drifted_table(tmp_path: Path) -> None:
     hook_specific_output = parsed_payload["hookSpecificOutput"]
     assert completed.returncode == 0, completed.stderr
     assert hook_specific_output["permissionDecision"] == "deny"
-    assert "GOOGLE_APPLICATION_CREDENTIALS -> auth/google_auth.py" in hook_specific_output[
-        "permissionDecisionReason"
-    ]
+    assert (
+        "GOOGLE_APPLICATION_CREDENTIALS -> auth/google_auth.py"
+        in hook_specific_output["permissionDecisionReason"]
+    )
     assert_hook_deny_log_contains(tmp_path, "env_var_table_code_drift_blocker.py")
 
 
@@ -159,3 +160,80 @@ def test_ignores_row_whose_second_cell_is_not_a_code_file(tmp_path: Path) -> Non
         "| `SOME_FLAG` | `enables the thing` | off |\n"
     )
     assert find_drift_rows(content, doc_path.parent) == []
+
+
+def test_constant_tables_do_not_claim_environment_consumers(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = (
+        "| Symbol | Imported by |\n"
+        "| --- | --- |\n"
+        "| `PROCESSING_VISIBLE` | `workflow.py` |\n\n"
+        "| Component | Location | Purpose |\n"
+        "| --- | --- | --- |\n"
+        "| `ACCOUNT_LINK_PRIMARY` | `workflow.py` | Selector |\n\n"
+        "| Constant | Value | Source |\n"
+        "| --- | --- | --- |\n"
+        "| `UPLOAD_DELAY_SECONDS` | 5 | `workflow.py` |\n"
+    )
+    assert find_drift_rows(content, tmp_path) == []
+
+
+def test_environment_table_after_constants_still_reports_drift(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = (
+        "| Constant | Source |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_DELAY_SECONDS` | `workflow.py` |\n\n"
+        "| Environment variable | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert find_drift_rows(content, tmp_path) == ["UPLOAD_TOKEN -> workflow.py"]
+
+
+def test_environment_section_supports_name_header(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = (
+        "## Environment variables\n\n"
+        "| Name | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert find_drift_rows(content, tmp_path) == ["UPLOAD_TOKEN -> workflow.py"]
+
+
+def test_headerless_edit_fragment_still_reports_drift(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    assert find_drift_rows(content, tmp_path) == ["UPLOAD_TOKEN -> workflow.py"]
+
+
+def test_descriptive_environment_header_reports_drift(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = (
+        "| Environment Variable Name | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert find_drift_rows(content, tmp_path) == ["UPLOAD_TOKEN -> workflow.py"]
+
+
+def test_explicit_source_header_overrides_environment_section(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = (
+        "## Environment variables\n\n"
+        "| Name | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n\n"
+        "The source also defines a delay constant.\n\n"
+        "| Constant | Source |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_DELAY_SECONDS` | `workflow.py` |\n"
+    )
+    assert find_drift_rows(content, tmp_path) == ["UPLOAD_TOKEN -> workflow.py"]

package/hooks/blocking/test_env_var_table_rows.py

@@ -0,0 +1,100 @@
+"""Tests for environment-variable table row recognition.
+
+Each test drives ``iter_env_var_table_rows`` against markdown text and asserts
+the exact rows it yields. The behavior under test is table context: which
+markdown tables read as environment-variable summaries, and which read as
+source, constant, or component tables that name no environment consumer.
+"""
+
+from __future__ import annotations
+
+from env_var_table_rows import iter_env_var_table_rows
+
+
+def test_environment_variable_header_yields_data_rows() -> None:
+    content = (
+        "| Environment variable | Consumer |\n| --- | --- |\n| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == [
+        "| Environment variable | Consumer |",
+        "| `UPLOAD_TOKEN` | `workflow.py` |",
+    ]
+
+
+def test_constant_table_yields_nothing() -> None:
+    content = (
+        "| Constant | Value | Source |\n"
+        "| --- | --- | --- |\n"
+        "| `UPLOAD_DELAY_SECONDS` | 5 | `workflow.py` |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == []
+
+
+def test_component_table_yields_nothing() -> None:
+    content = (
+        "| Component | Location | Purpose |\n"
+        "| --- | --- | --- |\n"
+        "| `ACCOUNT_LINK_PRIMARY` | `workflow.py` | Selector |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == []
+
+
+def test_generic_name_header_under_environment_heading_yields_rows() -> None:
+    content = (
+        "## Environment variables\n\n"
+        "| Name | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == [
+        "| Name | Consumer |",
+        "| `UPLOAD_TOKEN` | `workflow.py` |",
+    ]
+
+
+def test_generic_name_header_without_environment_heading_yields_nothing() -> None:
+    content = (
+        "## Selectors\n\n"
+        "| Name | Consumer |\n"
+        "| --- | --- |\n"
+        "| `ACCOUNT_LINK_PRIMARY` | `workflow.py` |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == []
+
+
+def test_headerless_fragment_naming_a_variable_yields_the_row() -> None:
+    content = "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    assert list(iter_env_var_table_rows(content)) == ["| `UPLOAD_TOKEN` | `workflow.py` |"]
+
+
+def test_rows_inside_a_code_fence_yield_nothing() -> None:
+    content = (
+        "```markdown\n"
+        "| Environment variable | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+        "```\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == []
+
+
+def test_constant_table_after_an_environment_table_yields_nothing_extra() -> None:
+    content = (
+        "| Environment variable | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n\n"
+        "| Constant | Source |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_DELAY_SECONDS` | `workflow.py` |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == [
+        "| Environment variable | Consumer |",
+        "| `UPLOAD_TOKEN` | `workflow.py` |",
+    ]
+
+
+def test_separator_row_is_never_yielded() -> None:
+    content = (
+        "| Environment variable | Consumer |\n| :--- | ---: |\n| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert "| :--- | ---: |" not in list(iter_env_var_table_rows(content))