claude-dev-env 2.36.0 → 4.0.0

package/scripts/policy_lint/registry.py

@@ -133,7 +133,16 @@ def default_registry() -> tuple[model.Rule, ...]:
         *_text_document_rules(),
         *_configuration_document_rules(),
         model.ChangeSetRule(
-            "test-pairing", frozenset({"changed"}), adapters.test_pairing_diagnostics
+            "test-pairing",
+            frozenset({"changed"}),
+            frozenset({model.SelectionKind.STAGED, model.SelectionKind.BASE}),
+            adapters.test_pairing_diagnostics,
+        ),
+        model.ChangeSetRule(
+            "terminology-sweep",
+            frozenset({"changed"}),
+            frozenset({model.SelectionKind.STAGED}),
+            adapters.terminology_diagnostics,
         ),
         model.RepositoryRule(
             "repository-path-collision",

package/scripts/repository_checks/__init__.py

@@ -0,0 +1 @@
+"""Committed-tree repository checks used by the repository_policy command."""

package/scripts/repository_checks/claude_md.py

@@ -0,0 +1,108 @@
+"""CLAUDE.md reference checks for committed trees."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Sequence
+from pathlib import Path
+from types import ModuleType
+
+from policy_lint.config.constants import PATH_SEPARATOR, UTF8_ENCODING
+
+from repository_checks.config.constants import (
+    CHECK_ID_CLAUDE_MD_ORPHANS,
+    CLAUDE_MD_CONSTANTS_MODULE_NAME,
+    CLAUDE_MD_MISSING_FILE_MESSAGE_TEMPLATE,
+    CLAUDE_MD_SCAN_MODULE_NAME,
+    WINDOWS_PATH_SEPARATOR,
+)
+from repository_checks.hook_modules import load_hooks_module
+from repository_checks.models import RepositoryFinding
+
+
+def collect_claude_md_orphan_findings(
+    repository_root: Path, all_tracked_paths: Sequence[str]
+) -> list[RepositoryFinding]:
+    """Return missing CLAUDE.md references in the tracked tree.
+
+    Args:
+        repository_root: Git repository root.
+        all_tracked_paths: Repository-relative tracked paths.
+
+    Returns:
+        Findings for references whose files are absent.
+    """
+    subtree_scan = load_hooks_module(CLAUDE_MD_SCAN_MODULE_NAME)
+    claude_md_constants = load_hooks_module(CLAUDE_MD_CONSTANTS_MODULE_NAME)
+    all_findings: list[RepositoryFinding] = []
+    for each_relative_path in all_tracked_paths:
+        all_findings.extend(
+            find_orphan_findings_for_path(
+                repository_root,
+                each_relative_path,
+                subtree_scan,
+                claude_md_constants,
+            )
+        )
+    return all_findings
+
+
+def find_orphan_findings_for_path(
+    repository_root: Path,
+    relative_path: str,
+    subtree_scan: ModuleType,
+    claude_md_constants: ModuleType,
+) -> list[RepositoryFinding]:
+    """Return missing files named by one CLAUDE.md file.
+
+    Args:
+        repository_root: Git repository root.
+        relative_path: Repository-relative path to inspect.
+        subtree_scan: Existing reference detector module.
+        claude_md_constants: Existing detector constants module.
+
+    Returns:
+        Findings for referenced files that are absent from the scan root.
+    """
+    if Path(relative_path).name != claude_md_constants.CLAUDE_MD_FILENAME:
+        return []
+    absolute_path = repository_root / relative_path
+    if not absolute_path.is_file():
+        return []
+    return _find_orphans_in_claude_md(absolute_path, relative_path, subtree_scan)
+
+
+def _find_orphans_in_claude_md(
+    absolute_path: Path,
+    relative_path: str,
+    subtree_scan: ModuleType,
+) -> list[RepositoryFinding]:
+    content = absolute_path.read_text(encoding=UTF8_ENCODING)
+    claude_md_directory = absolute_path.parent
+    subtree_root = _subtree_root_for(claude_md_directory)
+    subtree_root.stat()
+    deque(subtree_root.rglob("*"), maxlen=0)
+    all_missing_filenames = subtree_scan.find_missing_filenames(
+        content, claude_md_directory
+    )
+    return _build_findings(relative_path, all_missing_filenames)
+
+
+def _subtree_root_for(claude_md_directory: Path) -> Path:
+    parent_directory = claude_md_directory.parent
+    if parent_directory == claude_md_directory:
+        return claude_md_directory
+    return parent_directory
+
+
+def _build_findings(
+    relative_path: str, all_missing_filenames: Sequence[str]
+) -> list[RepositoryFinding]:
+    return [
+        RepositoryFinding(
+            CHECK_ID_CLAUDE_MD_ORPHANS,
+            relative_path.replace(WINDOWS_PATH_SEPARATOR, PATH_SEPARATOR),
+            CLAUDE_MD_MISSING_FILE_MESSAGE_TEMPLATE.format(filename=each_filename),
+        )
+        for each_filename in all_missing_filenames
+    ]

package/scripts/repository_checks/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration for the committed-tree repository checker."""

package/scripts/repository_checks/config/constants.py

@@ -0,0 +1,150 @@
+"""Stable identifiers, report tokens, and committed-tree exemption tables."""
+
+from policy_lint.config.constants import (
+    GIT_FILES_ARGUMENT,
+    GIT_ZERO_TERMINATED_FLAG,
+    INCOMPLETE_EXIT_CODE,
+    INVALID_INPUT_EXIT_CODE,
+)
+
+CHECK_ID_CLAUDE_MD_ORPHANS = "claude-md-orphans"
+CHECK_ID_ENV_VAR_DOCUMENTATION = "env-var-documentation"
+CHECK_ID_PACKAGE_INVENTORY = "package-inventory"
+CHECK_ID_PYTEST_TESTPATHS = "pytest-testpaths"
+CHECK_ID_TRACKED_PERSONAL_DATA = "tracked-secrets"
+
+ALL_CHECK_IDS = (
+    CHECK_ID_CLAUDE_MD_ORPHANS,
+    CHECK_ID_ENV_VAR_DOCUMENTATION,
+    CHECK_ID_PACKAGE_INVENTORY,
+    CHECK_ID_PYTEST_TESTPATHS,
+    CHECK_ID_TRACKED_PERSONAL_DATA,
+)
+
+SUCCESS_EXIT_CODE = 0
+FINDINGS_EXIT_CODE = 1
+FAILED_CHECK_EXIT_CODE = INCOMPLETE_EXIT_CODE
+USAGE_EXIT_CODE = INVALID_INPUT_EXIT_CODE
+
+REPOSITORY_ROOT_FLAG = "--repository-root"
+FINDING_LINE_TEMPLATE = "{check_id}: {relative_path}: {message}"
+RULE_FAILED_LINE_TEMPLATE = "error: rule failed: {check_id}"
+REPORT_LINE_SEPARATOR = "\n"
+EMPTY_REPORT_TEXT = ""
+TRACKED_MATCH_MESSAGE_TEMPLATE = "[{category}] {preview}"
+CLAUDE_MD_MISSING_FILE_MESSAGE_TEMPLATE = "references missing file {filename}"
+PACKAGE_INVENTORY_MESSAGE_TEMPLATE = "production file is absent from package inventory"
+PYTEST_TESTPATH_MESSAGE_TEMPLATE = (
+    "test file is outside the package testpaths allowlist"
+)
+ALL_GIT_LS_FILES_ARGUMENTS = (GIT_FILES_ARGUMENT, GIT_ZERO_TERMINATED_FLAG)
+PYPROJECT_FILENAME = "pyproject.toml"
+WINDOWS_PATH_SEPARATOR = "\\"
+
+CLAUDE_MD_SCAN_MODULE_NAME = "blocking.claude_md_orphan_file_blocker_parts.subtree_scan"
+CLAUDE_MD_CONSTANTS_MODULE_NAME = (
+    "hooks_constants.claude_md_orphan_file_blocker_constants"
+)
+ENV_VAR_DRIFT_MODULE_NAME = "blocking.env_var_table_code_drift_blocker"
+ENV_VAR_DRIFT_CONSTANTS_MODULE_NAME = (
+    "hooks_constants.env_var_table_code_drift_constants"
+)
+PACKAGE_INVENTORY_DETECTION_MODULE_NAME = (
+    "blocking.package_inventory_stale_blocker_parts.inventory_detection"
+)
+PACKAGE_INVENTORY_CONSTANTS_MODULE_NAME = (
+    "hooks_constants.package_inventory_stale_blocker_constants"
+)
+PYTEST_TESTPATHS_MODULE_NAME = "blocking.pytest_testpaths_orphan_blocker"
+PII_SCANNER_MODULE_NAME = "blocking.pii_scanner"
+REPOSITORY_EXEMPTION_MODULE_NAME = (
+    "blocking.pii_prevention_blocker_parts.repository_exemption"
+)
+
+ALL_FAIL_CLOSED_EXCEPTION_TYPES = (
+    AttributeError,
+    ImportError,
+    KeyError,
+    OSError,
+    RuntimeError,
+    SyntaxError,
+    TypeError,
+    UnicodeError,
+    ValueError,
+)
+
+ALL_ARCHIVED_SKILL_DIRECTORY_SEGMENTS = (".agents", "skills-archived")
+ALL_TRACKED_SECRET_EXACT_EXEMPTIONS: frozenset[tuple[str, str, str]] = frozenset(
+    (
+        (
+            "packages/claude-dev-env/.agents/skills-archived/pr-converge/reference/per-tick.md",
+            "email",
+            "3de132cd98be7bf26b6f08e81c31c799a891bc32046b61f0b6fe3671ca2e44b5",
+        ),
+        (
+            "packages/claude-dev-env/.agents/skills/_shared/pr-loop/prompts/pr-consistency-audit.xml",
+            "home-path",
+            "805e3271caeec55a94438e221726e9349e46fa4970592bd03ffd3adac5e0ea8a",
+        ),
+        (
+            "packages/claude-dev-env/.agents/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/path_resolver_constants.py",
+            "home-path",
+            "a4f1f978f88b601288424144a5f5066cdc9154868cf2aaab6e0869a103be72a5",
+        ),
+        (
+            "packages/claude-dev-env/.agents/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/path_resolver_constants.py",
+            "home-path",
+            "665e48f1b198dd2a6526e25700fbcb86566d1f8b47d4475a6cc318b1634a4546",
+        ),
+        (
+            "packages/claude-dev-env/_shared/pr-loop/scripts/_claude_permissions_common.py",
+            "home-path",
+            "9c48917645524d03ea0a4f4d8755aa8f0d59f3108e1aa976202a02e613c1444d",
+        ),
+        (
+            "packages/claude-dev-env/_shared/pr-loop/scripts/_claude_permissions_common.py",
+            "home-path",
+            "07ba214cb23325675bc68e5513c030e968eccf2760cb5917d932ae5da29d5af1",
+        ),
+        (
+            "packages/claude-dev-env/_shared/pr-loop/scripts/_claude_permissions_common.py",
+            "home-path",
+            "d41ce8d0f21de2d5320bdd8cd4e8693a2f3d6ea59db6df5ea102a7d2be4b2c22",
+        ),
+        (
+            "packages/claude-dev-env/audit-rubrics/prompts/category-n-test-name-scenario-verifier.md",
+            "home-path",
+            "550c7b16a2a04e1d05a8a6b4f5b764b8d4fdef65e9d79d09e5dbb3a15a855812",
+        ),
+        (
+            "packages/claude-dev-env/audit-rubrics/prompts/category-n-test-name-scenario-verifier.md",
+            "home-path",
+            "b8bbdd1a7ebdad16f4e51377a3f21d05dd35992d89e35971b28b05f53245c69d",
+        ),
+        (
+            "packages/claude-dev-env/bin/expand_home_directory_tokens.mjs",
+            "home-path",
+            "10d5571e7126d2018ee7fb06aa29c72a9d503cac79a4e52d6848602ee10e8832",
+        ),
+        (
+            "packages/claude-dev-env/bin/expand_home_directory_tokens.mjs",
+            "home-path",
+            "09f83c224a02c370d3d63de5c330e1a830fc92866330fc7963b5b5fd20ffcb91",
+        ),
+        (
+            "packages/claude-dev-env/hooks/blocking/volatile_path_in_post_blocker.py",
+            "home-path",
+            "ed9203c8078e4c6b832600085f28f24656d679aa8dca82ecc2557afc3df25036",
+        ),
+        (
+            "packages/claude-dev-env/hooks/hooks_constants/hardcoded_user_path_constants.py",
+            "home-path",
+            "0967160658d782c558722232cad7d47dc19267943d4667b41d3eff1e605be2f4",
+        ),
+        (
+            "packages/claude-dev-env/hooks/hooks_constants/hardcoded_user_path_constants.py",
+            "home-path",
+            "a541acfac2e649581bca0cd03e4c3dcf306344915017d9cd6be4ad57a8fd7379",
+        ),
+    )
+)

package/scripts/repository_checks/env_var_documentation.py

@@ -0,0 +1,243 @@
+"""Environment-variable documentation checks for committed trees."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from pathlib import Path
+from types import ModuleType
+
+from policy_lint.config.constants import PATH_SEPARATOR, UTF8_ENCODING
+
+from repository_checks.config.constants import (
+    CHECK_ID_ENV_VAR_DOCUMENTATION,
+    ENV_VAR_DRIFT_CONSTANTS_MODULE_NAME,
+    ENV_VAR_DRIFT_MODULE_NAME,
+    WINDOWS_PATH_SEPARATOR,
+)
+from repository_checks.hook_modules import load_hooks_module
+from repository_checks.models import RepositoryFinding
+
+
+def collect_env_var_documentation_findings(
+    repository_root: Path, all_tracked_paths: Sequence[str]
+) -> list[RepositoryFinding]:
+    """Return drifted environment-variable rows in tracked documentation.
+
+    Args:
+        repository_root: Git repository root.
+        all_tracked_paths: Repository-relative tracked paths.
+
+    Returns:
+        Findings for table rows whose code file does not read the variable.
+    """
+    drift_module = load_hooks_module(ENV_VAR_DRIFT_MODULE_NAME)
+    drift_constants = load_hooks_module(ENV_VAR_DRIFT_CONSTANTS_MODULE_NAME)
+    all_findings: list[RepositoryFinding] = []
+    for each_relative_path in all_tracked_paths:
+        all_findings.extend(
+            find_documentation_findings_for_path(
+                repository_root,
+                each_relative_path,
+                drift_module,
+                drift_constants,
+            )
+        )
+    return all_findings
+
+
+def find_documentation_findings_for_path(
+    repository_root: Path,
+    relative_path: str,
+    drift_module: ModuleType,
+    drift_constants: ModuleType,
+) -> list[RepositoryFinding]:
+    """Return documentation rows whose code file does not read the variable.
+
+    Args:
+        repository_root: Git repository root.
+        relative_path: Repository-relative documentation path.
+        drift_module: Documentation drift detector module.
+        drift_constants: Documentation drift constants module.
+
+    Returns:
+        Findings for table rows whose code file does not read the variable.
+    """
+    if not drift_module.is_markdown_file(relative_path):
+        return []
+    absolute_path = repository_root / relative_path
+    if not absolute_path.is_file():
+        return []
+    return _find_documentation_file_findings(
+        repository_root,
+        relative_path,
+        absolute_path,
+        drift_module,
+        drift_constants,
+    )
+
+
+def _find_documentation_file_findings(
+    repository_root: Path,
+    relative_path: str,
+    absolute_path: Path,
+    drift_module: ModuleType,
+    drift_constants: ModuleType,
+) -> list[RepositoryFinding]:
+    content = absolute_path.read_text(encoding=UTF8_ENCODING)
+    _require_readable_code_files(
+        content,
+        repository_root,
+        drift_module,
+        drift_constants,
+    )
+    all_drift_rows = drift_module.find_drift_rows(content, absolute_path.parent)
+    return _build_findings(relative_path, all_drift_rows)
+
+
+def _build_findings(
+    relative_path: str, all_drift_rows: Sequence[str]
+) -> list[RepositoryFinding]:
+    return [
+        RepositoryFinding(
+            CHECK_ID_ENV_VAR_DOCUMENTATION,
+            relative_path.replace(WINDOWS_PATH_SEPARATOR, PATH_SEPARATOR),
+            each_drift_row,
+        )
+        for each_drift_row in all_drift_rows
+    ]
+
+
+def _require_readable_code_files(
+    content: str,
+    repository_root: Path,
+    drift_module: ModuleType,
+    drift_constants: ModuleType,
+) -> None:
+    resolved_repository_root = repository_root.resolve(strict=True)
+    for each_code_reference in _iter_env_var_code_references(
+        content,
+        drift_module,
+        drift_constants,
+    ):
+        maybe_code_file = _resolve_code_file(
+            repository_root,
+            each_code_reference,
+            drift_constants,
+        )
+        if maybe_code_file is None:
+            continue
+        resolved_code_file = _resolve_inside_repository(
+            resolved_repository_root,
+            maybe_code_file,
+        )
+        resolved_code_file.read_text(encoding=UTF8_ENCODING)
+
+
+def _iter_env_var_code_references(
+    content: str,
+    drift_module: ModuleType,
+    drift_constants: ModuleType,
+) -> Iterator[str]:
+    is_inside_code_fence = False
+    for each_line in content.splitlines():
+        if drift_constants.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 drift_constants.TABLE_ROW_PATTERN.match(each_line) is None:
+            continue
+        maybe_code_reference = _code_reference_for_env_var_row(
+            each_line,
+            drift_module,
+            drift_constants,
+        )
+        if maybe_code_reference is not None:
+            yield maybe_code_reference
+
+
+def _code_reference_for_env_var_row(
+    table_line: str,
+    drift_module: ModuleType,
+    drift_constants: ModuleType,
+) -> str | None:
+    all_cells = drift_module._row_cells(table_line)
+    if len(all_cells) < drift_constants.MINIMUM_ENV_VAR_ROW_CELL_COUNT:
+        return None
+    if drift_module._is_separator_row(all_cells):
+        return None
+    if drift_module._env_var_name_in_cell(all_cells[0]) is None:
+        return None
+    for each_cell in all_cells[1:]:
+        maybe_code_reference = drift_module._code_file_reference_in_cell(each_cell)
+        if maybe_code_reference is not None:
+            return maybe_code_reference
+    return None
+
+
+def _resolve_inside_repository(
+    resolved_repository_root: Path,
+    candidate_path: Path,
+) -> Path:
+    resolved_candidate_path = candidate_path.resolve(strict=True)
+    try:
+        resolved_candidate_path.relative_to(resolved_repository_root)
+    except ValueError as e:
+        raise OSError(candidate_path) from e
+    return resolved_candidate_path
+
+
+def _resolve_code_file(
+    repository_root: Path,
+    code_reference: str,
+    drift_constants: ModuleType,
+) -> Path | None:
+    normalized_reference = code_reference.replace(
+        WINDOWS_PATH_SEPARATOR, PATH_SEPARATOR
+    ).lstrip(PATH_SEPARATOR)
+    direct_path = repository_root / normalized_reference
+    if direct_path.is_file():
+        return direct_path
+    reference_basename = Path(normalized_reference).name
+    if not reference_basename:
+        return None
+    return _find_suffix_match(
+        repository_root,
+        normalized_reference,
+        reference_basename,
+        drift_constants,
+    )
+
+
+def _find_suffix_match(
+    repository_root: Path,
+    normalized_reference: str,
+    reference_basename: str,
+    drift_constants: ModuleType,
+) -> Path | None:
+    suffix_marker = PATH_SEPARATOR + normalized_reference
+    scanned_count = 0
+    for each_match in repository_root.rglob(reference_basename):
+        if _is_under_noise_directory(repository_root, each_match, drift_constants):
+            continue
+        scanned_count += 1
+        if scanned_count > drift_constants.MAX_SUBTREE_FILES_SCANNED:
+            return None
+        if not each_match.is_file():
+            continue
+        match_text = PATH_SEPARATOR + each_match.as_posix()
+        if match_text.endswith(suffix_marker):
+            return each_match
+    return None
+
+
+def _is_under_noise_directory(
+    repository_root: Path,
+    candidate_path: Path,
+    drift_constants: ModuleType,
+) -> bool:
+    all_relative_segments = candidate_path.relative_to(repository_root).parts
+    return any(
+        each_segment in drift_constants.ALL_NOISE_DIRECTORY_NAMES
+        for each_segment in all_relative_segments
+    )

package/scripts/repository_checks/hook_modules.py

@@ -0,0 +1,34 @@
+"""Import a hooks module after putting the hook package paths on sys.path."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from types import ModuleType
+
+
+def load_hooks_module(module_name: str) -> ModuleType:
+    """Import a hooks module after placing ``hooks/`` and ``blocking/`` on ``sys.path``.
+
+    ::
+
+        load_hooks_module("blocking.pii_scanner")
+        ok:   hooks/ is on sys.path, blocking.pii_scanner imports
+        flag: importing a hook main() and printing a deny payload
+
+    Args:
+        module_name: Dotted module name under ``hooks/``, such as
+            ``blocking.pii_scanner``.
+
+    Returns:
+        The imported module.
+    """
+    package_root = Path(__file__).resolve().parent.parent.parent
+    hooks_directory = str(package_root / "hooks")
+    blocking_directory = str(package_root / "hooks" / "blocking")
+    if blocking_directory not in sys.path:
+        sys.path.insert(0, blocking_directory)
+    if hooks_directory not in sys.path:
+        sys.path.insert(0, hooks_directory)
+    return importlib.import_module(module_name)

package/scripts/repository_checks/models.py

@@ -0,0 +1,37 @@
+"""Shared report types for committed-tree repository checks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from repository_checks.config.constants import (
+    FAILED_CHECK_EXIT_CODE,
+    FINDINGS_EXIT_CODE,
+    SUCCESS_EXIT_CODE,
+)
+
+
+@dataclass(frozen=True)
+class RepositoryFinding:
+    """One committed-tree finding with a stable check id and relative path."""
+
+    check_id: str
+    relative_path: str
+    message: str
+
+
+@dataclass(frozen=True)
+class RepositoryCheckReport:
+    """Sorted findings and the check ids that failed while they ran."""
+
+    all_findings: tuple[RepositoryFinding, ...]
+    all_failed_check_ids: tuple[str, ...]
+
+    @property
+    def exit_code(self) -> int:
+        """Return the process status for this report."""
+        if self.all_failed_check_ids:
+            return FAILED_CHECK_EXIT_CODE
+        if self.all_findings:
+            return FINDINGS_EXIT_CODE
+        return SUCCESS_EXIT_CODE