claude-dev-env 2.36.0 → 4.1.0

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

package/scripts/repository_checks/package_inventory.py

@@ -0,0 +1,118 @@
+"""Package inventory checks for committed trees."""
+
+from __future__ import annotations
+
+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 (
+    ALL_ARCHIVED_SKILL_DIRECTORY_SEGMENTS,
+    CHECK_ID_PACKAGE_INVENTORY,
+    PACKAGE_INVENTORY_CONSTANTS_MODULE_NAME,
+    PACKAGE_INVENTORY_DETECTION_MODULE_NAME,
+    PACKAGE_INVENTORY_MESSAGE_TEMPLATE,
+    WINDOWS_PATH_SEPARATOR,
+)
+from repository_checks.hook_modules import load_hooks_module
+from repository_checks.models import RepositoryFinding
+
+
+def collect_package_inventory_findings(
+    repository_root: Path, all_tracked_paths: Sequence[str]
+) -> list[RepositoryFinding]:
+    """Return tracked production files missing from package inventories.
+
+    Args:
+        repository_root: Git repository root.
+        all_tracked_paths: Repository-relative tracked paths.
+
+    Returns:
+        Findings for production files absent from their inventories.
+    """
+    detection = load_hooks_module(PACKAGE_INVENTORY_DETECTION_MODULE_NAME)
+    inventory_constants = load_hooks_module(PACKAGE_INVENTORY_CONSTANTS_MODULE_NAME)
+    all_findings: list[RepositoryFinding] = []
+    for each_relative_path in all_tracked_paths:
+        maybe_finding = find_inventory_finding_for_path(
+            repository_root,
+            each_relative_path,
+            detection,
+            inventory_constants,
+        )
+        if maybe_finding is not None:
+            all_findings.append(maybe_finding)
+    return all_findings
+
+
+def find_inventory_finding_for_path(
+    repository_root: Path,
+    relative_path: str,
+    detection: ModuleType,
+    inventory_constants: ModuleType,
+) -> RepositoryFinding | None:
+    """Return an inventory finding for one tracked production file.
+
+    Args:
+        repository_root: Git repository root.
+        relative_path: Repository-relative production path.
+        detection: Existing inventory detector module.
+        inventory_constants: Existing detector constants module.
+
+    Returns:
+        The finding when the file is missing from its inventory.
+    """
+    if _is_archived_skill_path(relative_path):
+        return None
+    absolute_path = repository_root / relative_path
+    if not absolute_path.is_file():
+        return None
+    if not detection.is_inventoried_production_file(str(absolute_path)):
+        return None
+    _require_readable_inventory_documents(absolute_path.parent, inventory_constants)
+    if detection.find_stale_inventory(str(absolute_path)) is None:
+        return None
+    return _build_finding(relative_path)
+
+
+def _build_finding(relative_path: str) -> RepositoryFinding:
+    return RepositoryFinding(
+        CHECK_ID_PACKAGE_INVENTORY,
+        relative_path.replace(WINDOWS_PATH_SEPARATOR, PATH_SEPARATOR),
+        PACKAGE_INVENTORY_MESSAGE_TEMPLATE,
+    )
+
+
+def _is_archived_skill_path(relative_path: str) -> bool:
+    all_path_segments = relative_path.replace(
+        WINDOWS_PATH_SEPARATOR, PATH_SEPARATOR
+    ).split(PATH_SEPARATOR)
+    segment_count = len(ALL_ARCHIVED_SKILL_DIRECTORY_SEGMENTS)
+    last_start_index = len(all_path_segments) - segment_count
+    for each_start_index in range(max(last_start_index + 1, 0)):
+        compared_segments = tuple(
+            all_path_segments[each_start_index : each_start_index + segment_count]
+        )
+        if compared_segments == ALL_ARCHIVED_SKILL_DIRECTORY_SEGMENTS:
+            return True
+    return False
+
+
+def _require_readable_inventory_documents(
+    package_directory: Path, inventory_constants: ModuleType
+) -> None:
+    for each_inventory_name in inventory_constants.ALL_INVENTORY_DOCUMENT_NAMES:
+        inventory_path = package_directory / each_inventory_name
+        if not inventory_path.is_file():
+            continue
+        inventory_path.read_text(encoding=UTF8_ENCODING)
+    if package_directory.name != inventory_constants.SCRIPTS_SUBDIRECTORY_NAME:
+        return
+    skill_inventory_path = (
+        package_directory.parent / inventory_constants.SKILL_INVENTORY_DOCUMENT_NAME
+    )
+    if not skill_inventory_path.is_file():
+        return
+    skill_inventory_path.read_text(encoding=UTF8_ENCODING)

package/scripts/repository_checks/pytest_testpaths.py

@@ -0,0 +1,84 @@
+"""Pytest testpath checks for committed trees."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from types import ModuleType
+
+import tomllib
+from policy_lint.config import constants as policy_constants
+
+from repository_checks.config import constants as repository_constants
+from repository_checks.hook_modules import load_hooks_module
+from repository_checks.models import RepositoryFinding
+
+
+def collect_pytest_testpath_findings(
+    repository_root: Path, all_tracked_paths: Sequence[str]
+) -> list[RepositoryFinding]:
+    """Return tracked tests outside explicit package testpaths.
+
+    Args:
+        repository_root: Git repository root.
+        all_tracked_paths: Repository-relative tracked paths.
+
+    Returns:
+        Findings for tests excluded by their package testpaths.
+    """
+    pytest_module = load_hooks_module(repository_constants.PYTEST_TESTPATHS_MODULE_NAME)
+    all_findings: list[RepositoryFinding] = []
+    for each_relative_path in all_tracked_paths:
+        maybe_finding = _find_testpath_finding(
+            repository_root, each_relative_path, pytest_module
+        )
+        if maybe_finding is not None:
+            all_findings.append(maybe_finding)
+    return all_findings
+
+
+def _find_testpath_finding(
+    repository_root: Path,
+    relative_path: str,
+    pytest_module: ModuleType,
+) -> RepositoryFinding | None:
+    if not pytest_module.is_test_file(relative_path):
+        return None
+    absolute_path = repository_root / relative_path
+    if not absolute_path.is_file():
+        return None
+    _require_readable_inputs(absolute_path, repository_root)
+    if pytest_module.find_unregistered_test_directory(str(absolute_path)) is None:
+        return None
+    return RepositoryFinding(
+        repository_constants.CHECK_ID_PYTEST_TESTPATHS,
+        _to_posix_path(relative_path),
+        repository_constants.PYTEST_TESTPATH_MESSAGE_TEMPLATE,
+    )
+
+
+def _to_posix_path(relative_path: str) -> str:
+    return relative_path.replace(
+        repository_constants.WINDOWS_PATH_SEPARATOR,
+        policy_constants.PATH_SEPARATOR,
+    )
+
+
+def _require_readable_inputs(test_file: Path, repository_root: Path) -> None:
+    test_file.read_bytes()
+    resolved_repository_root = repository_root.resolve()
+    for each_directory in test_file.parents:
+        if not _is_inside_repository(each_directory, resolved_repository_root):
+            break
+        pyproject_path = each_directory / repository_constants.PYPROJECT_FILENAME
+        if not pyproject_path.is_file():
+            continue
+        tomllib.loads(pyproject_path.read_text(encoding=policy_constants.UTF8_ENCODING))
+
+
+def _is_inside_repository(directory: Path, resolved_repository_root: Path) -> bool:
+    try:
+        directory.resolve().relative_to(resolved_repository_root)
+    except ValueError:
+        return False
+    return True

package/scripts/repository_checks/reporting.py

@@ -0,0 +1,39 @@
+"""Stable text reports for committed-tree repository checks."""
+
+from __future__ import annotations
+
+from repository_checks.config import constants as repository_constants
+from repository_checks.models import RepositoryCheckReport
+
+
+def render_report(report: RepositoryCheckReport) -> str:
+    """Render findings and failed checks as newline-terminated text.
+
+    Args:
+        report: Findings and failed check identifiers.
+
+    Returns:
+        The report body, or an empty string when the tree is clean.
+    """
+    all_lines = [
+        repository_constants.FINDING_LINE_TEMPLATE.format(
+            check_id=each_finding.check_id,
+            relative_path=each_finding.relative_path,
+            message=each_finding.message,
+        )
+        for each_finding in report.all_findings
+    ]
+    all_lines.extend(_failed_check_lines(report))
+    if not all_lines:
+        return repository_constants.EMPTY_REPORT_TEXT
+    return (
+        repository_constants.REPORT_LINE_SEPARATOR.join(all_lines)
+        + repository_constants.REPORT_LINE_SEPARATOR
+    )
+
+
+def _failed_check_lines(report: RepositoryCheckReport) -> list[str]:
+    return [
+        repository_constants.RULE_FAILED_LINE_TEMPLATE.format(check_id=each_check_id)
+        for each_check_id in report.all_failed_check_ids
+    ]

package/scripts/repository_checks/runner.py

@@ -0,0 +1,93 @@
+"""Fail-closed runner for committed-tree repository checks."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+from repository_checks import tracked_tree
+from repository_checks.claude_md import collect_claude_md_orphan_findings
+from repository_checks.config import constants as repository_constants
+from repository_checks.env_var_documentation import (
+    collect_env_var_documentation_findings,
+)
+from repository_checks.models import RepositoryCheckReport, RepositoryFinding
+from repository_checks.package_inventory import collect_package_inventory_findings
+from repository_checks.pytest_testpaths import collect_pytest_testpath_findings
+from repository_checks.tracked_secrets import collect_tracked_secret_findings
+
+RepositoryCollector = Callable[[Path, Sequence[str]], list[RepositoryFinding]]
+
+
+def run_repository_checks(repository_root: Path) -> RepositoryCheckReport:
+    """Run every committed-tree check and fail closed on collector errors.
+
+    Args:
+        repository_root: Git repository root whose tracked files are scanned.
+
+    Returns:
+        Sorted findings and any check identifiers that failed closed.
+    """
+    try:
+        all_tracked_paths = tracked_tree.tracked_relative_paths(repository_root)
+    except repository_constants.ALL_FAIL_CLOSED_EXCEPTION_TYPES:
+        return RepositoryCheckReport((), repository_constants.ALL_CHECK_IDS)
+    all_findings, all_failed_check_ids = _run_collectors(
+        repository_root, all_tracked_paths
+    )
+    return RepositoryCheckReport(
+        _sort_findings(all_findings), tuple(all_failed_check_ids)
+    )
+
+
+def _run_collectors(
+    repository_root: Path, all_tracked_paths: Sequence[str]
+) -> tuple[list[RepositoryFinding], list[str]]:
+    all_findings: list[RepositoryFinding] = []
+    all_failed_check_ids: list[str] = []
+    for each_check_id, each_collector in _all_collectors():
+        try:
+            all_findings.extend(each_collector(repository_root, all_tracked_paths))
+        except repository_constants.ALL_FAIL_CLOSED_EXCEPTION_TYPES:
+            all_failed_check_ids.append(each_check_id)
+    return all_findings, all_failed_check_ids
+
+
+def _sort_findings(
+    all_findings: list[RepositoryFinding],
+) -> tuple[RepositoryFinding, ...]:
+    return tuple(
+        sorted(
+            all_findings,
+            key=lambda each_finding: (
+                each_finding.check_id,
+                each_finding.relative_path,
+                each_finding.message,
+            ),
+        )
+    )
+
+
+def _all_collectors() -> tuple[tuple[str, RepositoryCollector], ...]:
+    return (
+        (
+            repository_constants.CHECK_ID_CLAUDE_MD_ORPHANS,
+            collect_claude_md_orphan_findings,
+        ),
+        (
+            repository_constants.CHECK_ID_ENV_VAR_DOCUMENTATION,
+            collect_env_var_documentation_findings,
+        ),
+        (
+            repository_constants.CHECK_ID_PACKAGE_INVENTORY,
+            collect_package_inventory_findings,
+        ),
+        (
+            repository_constants.CHECK_ID_PYTEST_TESTPATHS,
+            collect_pytest_testpath_findings,
+        ),
+        (
+            repository_constants.CHECK_ID_TRACKED_PERSONAL_DATA,
+            collect_tracked_secret_findings,
+        ),
+    )