claude-dev-env 2.35.0 → 4.0.0

package/scripts/policy_lint/adapters.py

@@ -0,0 +1,376 @@
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from types import ModuleType
+
+from . import adapter_configuration, adapter_detectors, adapter_pairing, adapter_support
+from .config import constants
+from .model import Diagnostic, Document, DocumentSet
+
+_document_path = adapter_support._document_path
+_line_number = adapter_support._line_number
+_diagnostics_for_messages = adapter_support._diagnostics_for_messages
+_source_line_for_phrase = adapter_support._source_line_for_phrase
+_diagnostics_for_state_messages = adapter_support._diagnostics_for_state_messages
+
+
+def _hooks_module(module_name: str) -> ModuleType:
+    hooks_directory = str(Path(__file__).resolve().parents[1].parent / "hooks")
+    if hooks_directory not in sys.path:
+        sys.path.insert(0, hooks_directory)
+    return importlib.import_module(module_name)
+
+
+def _pr_loop_script_module(module_name: str) -> ModuleType:
+    package_directory = Path(__file__).resolve().parent.parent.parent
+    scripts_directory = str(
+        package_directory.joinpath(*constants.ALL_PR_LOOP_SCRIPTS_PATH_SEGMENTS)
+    )
+    if scripts_directory not in sys.path:
+        sys.path.insert(0, scripts_directory)
+    return importlib.import_module(module_name)
+
+
+def validator_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Run the fast validator set on one document.
+
+    Args:
+        document: Current source text and path.
+        repository_root: Request repository root for configuration resolution.
+
+    Returns:
+        Path-normalized diagnostics for failed validators.
+    """
+    return adapter_detectors.validator_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def code_rule_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Run the code-rule engine on one document.
+
+    Args:
+        document: Current text and optional prior text.
+        repository_root: Request repository root for sibling-file resolution.
+
+    Returns:
+        Diagnostics from the code-rule engine.
+    """
+    return adapter_detectors.code_rule_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def state_description_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Run the state-description detector on one document.
+
+    Args:
+        document: Current document text.
+        repository_root: Request repository root for document-path resolution.
+
+    Returns:
+        State-description diagnostics.
+    """
+    return adapter_detectors.state_description_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def plain_language_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Run the stored-prose detector on one document.
+
+    Args:
+        document: Current document text.
+        repository_root: Request repository root for document-path resolution.
+
+    Returns:
+        Plain-language diagnostics.
+    """
+    return adapter_detectors.plain_language_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def docstring_gate_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Run the docstring gate-count detector on one document.
+
+    Args:
+        document: Current document text.
+        repository_root: Request repository root for document-path resolution.
+
+    Returns:
+        Docstring gate diagnostics.
+    """
+    return adapter_detectors.docstring_gate_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def workflow_substitution_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Run the workflow substitution detector on one document.
+
+    Args:
+        document: Current document text.
+        repository_root: Request repository root for document-path resolution.
+
+    Returns:
+        Workflow substitution diagnostics.
+    """
+    return adapter_detectors.workflow_substitution_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def rmtree_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Run the Windows cleanup detectors on one document.
+
+    Args:
+        document: Current text.
+        repository_root: Request repository root for document-path resolution.
+
+    Returns:
+        Cleanup safety diagnostics.
+    """
+    return adapter_detectors.rmtree_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def subprocess_budget_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Run the subprocess budget detector on one document.
+
+    Args:
+        document: Current text.
+        repository_root: Request repository root for document-path resolution.
+
+    Returns:
+        Subprocess budget diagnostics.
+    """
+    return adapter_detectors.subprocess_budget_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def hook_prose_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Run the hook-prose consistency detector on one document.
+
+    Args:
+        document: Current text.
+        repository_root: Request repository root for document-path resolution.
+
+    Returns:
+        Hook-prose diagnostics.
+    """
+    return adapter_detectors.hook_prose_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def open_question_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Run the open-question plan detector on one document.
+
+    Args:
+        document: Current plan text.
+        repository_root: Request repository root for document-path resolution.
+
+    Returns:
+        Plan question diagnostics.
+    """
+    return adapter_detectors.open_question_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def hook_configuration_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Check hook configuration for policy decision fields.
+
+    Args:
+        document: Current hook configuration text.
+        repository_root: Request repository root for document-path resolution.
+
+    Returns:
+        Hook configuration diagnostics.
+    """
+    return adapter_configuration.hook_configuration_diagnostics(
+        document, repository_root
+    )
+
+
+def test_pairing_diagnostics(document_set: DocumentSet) -> tuple[Diagnostic, ...]:
+    """Report changed production files without a changed matching test.
+
+    Args:
+        document_set: Staged or base change selection.
+
+    Returns:
+        Test-pairing diagnostics for unmatched production files.
+    """
+    return adapter_pairing.test_pairing_diagnostics(document_set, _hooks_module)
+
+
+def terminology_diagnostics(document_set: DocumentSet) -> tuple[Diagnostic, ...]:
+    """Report staged prose that near-misses a newly introduced identifier.
+
+    Args:
+        document_set: Candidate staged documents and repository root.
+
+    Returns:
+        Diagnostics that name the prose file and line.
+    """
+    return adapter_detectors.terminology_diagnostics(
+        document_set, _pr_loop_script_module
+    )
+
+
+def hook_format_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Check one settings document for a nonportable hook command.
+
+    Args:
+        document: Current settings text and path.
+        repository_root: Request repository root for document-path resolution.
+
+    Returns:
+        A diagnostic when the command uses a home-relative Python script path.
+    """
+    return adapter_detectors.hook_format_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def accepts_python(document: Document) -> bool:
+    return document.path.suffix.lower() == constants.PYTHON_SUFFIX
+
+
+def accepts_code(document: Document) -> bool:
+    """Return whether the document contains supported source code.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for a supported source extension.
+    """
+    return document.path.suffix.lower() in constants.ALL_CODE_SUFFIXES
+
+
+def accepts_markdown(document: Document) -> bool:
+    return document.path.suffix.lower() in constants.ALL_MARKDOWN_SUFFIXES
+
+
+def accepts_source_or_markdown(document: Document) -> bool:
+    """Return whether a state-description rule can inspect the document.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for supported source or Markdown.
+    """
+    return accepts_code(document) or accepts_markdown(document)
+
+
+def accepts_stored_prompt(document: Document) -> bool:
+    """Return whether the document is stored prompt prose.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for Markdown in an instruction directory.
+    """
+    normalized_path = f"/{document.path.as_posix().lower()}"
+    return accepts_markdown(document) and any(
+        each_segment in normalized_path
+        for each_segment in constants.ALL_STORED_PROMPT_SEGMENTS
+    )
+
+
+def accepts_hook_configuration(document: Document) -> bool:
+    return document.path.name == "hooks.json"
+
+
+def accepts_hook_format(document: Document) -> bool:
+    """Return whether the document is Claude settings JSON.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for ``settings.json`` under a ``.claude`` directory.
+    """
+    settings_file_name = "settings.json"
+    claude_directory_segment = "/.claude/"
+    normalized_path = f"/{document.path.as_posix().lower()}"
+    return (
+        document.path.name.lower() == settings_file_name
+        and claude_directory_segment in normalized_path
+    )
+
+
+def accepts_workflow(document: Document) -> bool:
+    """Return whether the document is a workflow substitution template.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for a ``.workflow.js`` path.
+    """
+    workflow_constants = _hooks_module(
+        "hooks_constants.workflow_substitution_slot_blocker_constants"
+    )
+    return document.path.as_posix().lower().endswith(
+        workflow_constants.WORKFLOW_FILE_SUFFIX
+    )
+
+
+def accepts_plans(document: Document) -> bool:
+    """Return whether the document lives in a plan directory.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for repository ``docs/plans`` or ``.claude/plans`` paths.
+    """
+    plans_constants = _hooks_module(
+        "hooks_constants.open_questions_in_plans_blocker_constants"
+    )
+    normalized_path = f"/{document.path.as_posix().lower()}"
+    relative_path = document.path.as_posix().lower()
+    return (
+        plans_constants.PLANS_PATH_SEGMENT in normalized_path
+        or plans_constants.DOCS_PLANS_PATH_SEGMENT in normalized_path
+        or relative_path.startswith(
+            (
+                plans_constants.PLANS_PATH_PREFIX,
+                plans_constants.DOCS_PLANS_PATH_PREFIX,
+            )
+        )
+    )

package/scripts/policy_lint/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration values for the policy linter."""

package/scripts/policy_lint/config/constants.py

@@ -0,0 +1,77 @@
+import re
+
+INCOMPLETE_EXIT_CODE = 3
+INVALID_INPUT_EXIT_CODE = 2
+GIT_EXECUTABLE = "git"
+UTF8_ENCODING = "utf-8"
+PATH_SEPARATOR = "/"
+NUL_BYTE = b"\0"
+ALL_GIT_ROOT_ARGUMENTS = ("rev-parse", "--show-toplevel")
+ALL_GIT_HEAD_ARGUMENTS = ("rev-parse", "--verify", "HEAD")
+ALL_UNBORN_HEAD_ERROR_FRAGMENTS = ("needed a single revision",)
+GIT_MERGE_BASE_ARGUMENT = "merge-base"
+GIT_HEAD_REFERENCE = "HEAD"
+GIT_INDEX_REFERENCE_PREFIX = ""
+GIT_ENVIRONMENT_VARIABLE_PREFIX = "GIT_"
+ALL_GIT_BLOB_ARGUMENTS = ("cat-file", "blob")
+ALL_MISSING_BLOB_ERROR_FRAGMENTS = (
+    "does not exist in",
+    "does not exist (at stage",
+    "exists on disk, but not in",
+)
+GIT_DIFF_ARGUMENT = "diff"
+GIT_CACHED_FLAG = "--cached"
+GIT_NAME_STATUS_FLAG = "--name-status"
+GIT_FIND_RENAMES_FLAG = "--find-renames"
+GIT_ZERO_TERMINATED_FLAG = "-z"
+GIT_FILES_ARGUMENT = "ls-files"
+GIT_SEPARATOR = "--"
+ALL_DIFF_CHANGED_TAGS = frozenset({"replace", "insert"})
+NEW_DOCUMENT_ORIGIN_LINE = 1
+RENAME_PATH_COUNT = 2
+PYTHON_SUFFIX = ".py"
+ALL_CODE_SUFFIXES = frozenset({".py", ".js", ".jsx", ".ts", ".tsx", ".mjs"})
+ALL_MARKDOWN_SUFFIXES = frozenset({".md", ".mdx"})
+ALL_STORED_PROMPT_SEGMENTS = (
+    "/.agents/",
+    "/commands/",
+    "/rules/",
+    "/system-prompts/",
+)
+ALL_HOOK_REGISTRATION_KEYS = frozenset({"command", "path", "script", "entrypoint"})
+ALL_DECISION_REGISTRATION_KEYS = frozenset(
+    {"permissionDecision", "permission_decision", "decision"}
+)
+ALL_ACTION_BOUNDARY_SEGMENTS = frozenset(
+    {
+        "deny",
+        "block",
+        "ask",
+        "blocking",
+        "blocker",
+        "permissiondecision",
+        "permission_decision",
+        "pre_tool_use_dispatcher",
+    }
+)
+ALL_ACTION_BOUNDARY_PREFIXES = ("deny_", "block_", "ask_")
+ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
+ALL_TEST_FILE_PREFIXES = ("test_",)
+ALL_TEST_FILE_SUFFIXES = ("_test.py",)
+POLICY_LINT_DIRECTORY_NAME = "policy_lint"
+POLICY_LINT_RULES_TEST_PREFIX = "test_policy_lint_rules"
+POLICY_LINT_SELECTION_TEST_PREFIX = "test_policy_lint_selection"
+RUN_ALL_VALIDATORS_STEM = "run_all_validators"
+FAST_SAVE_VALIDATORS_STEM = "fast_save_validators"
+ALL_OVERLAPPING_VALIDATOR_NAMES = frozenset(
+    {"Python Style", "Magic Values", "Type Safety", "Test Safety", "React"}
+)
+ALL_PR_LOOP_SCRIPTS_PATH_SEGMENTS = ("_shared", "pr-loop", "scripts")
+TERMINOLOGY_SWEEP_MODULE_NAME = "terminology_sweep"
+TERMINOLOGY_SWEEP_RULE_ID = "terminology-sweep"
+TERMINOLOGY_FINDING_PATTERN = re.compile(
+    r"^(?P<path>.+):(?P<line_number>\d+): (?P<message>.+)$"
+)
+TERMINOLOGY_PATH_GROUP = "path"
+TERMINOLOGY_LINE_NUMBER_GROUP = "line_number"
+TERMINOLOGY_MESSAGE_GROUP = "message"

package/scripts/policy_lint/engine.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+
+from .model import (
+    ChangeSetRule,
+    Diagnostic,
+    Document,
+    DocumentRule,
+    DocumentSet,
+    LintReport,
+    LintRequest,
+    RepositoryRule,
+    Rule,
+    SelectionKind,
+)
+from .registry import default_registry, selected_rules
+from .selection import select_documents
+
+
+def lint(
+    request: LintRequest,
+    all_registry: Sequence[Rule] | None = None,
+) -> LintReport:
+    """Run the selected rules on one source selection.
+
+    Args:
+        request: Repository root, source, and rule sets.
+        all_registry: Optional registry replacement.
+
+    Returns:
+        A report of diagnostics and rule execution state.
+    """
+    document_set = select_documents(request)
+    candidate_rules = tuple(all_registry) if all_registry is not None else default_registry()
+    selected = selected_rules(candidate_rules, request.rule_sets)
+    all_diagnostics, executed, failed, skipped = _run_selected_rules(selected, document_set)
+    return LintReport(
+        1,
+        tuple(sorted(all_diagnostics, key=_diagnostic_sort_key)),
+        tuple(each_document.path for each_document in document_set.documents),
+        executed,
+        failed,
+        skipped,
+    )
+
+
+def _run_selected_rules(
+    all_rules: tuple[Rule, ...], document_set: DocumentSet
+) -> tuple[list[Diagnostic], tuple[str, ...], tuple[str, ...], tuple[str, ...]]:
+    resolved_repository_root = document_set.repository_root.resolve()
+    all_diagnostics: list[Diagnostic] = []
+    all_executed_rules: list[str] = []
+    all_failed_rules: list[str] = []
+    all_skipped_rules: list[str] = []
+    for each_rule in all_rules:
+        _run_rule(
+            each_rule,
+            document_set,
+            resolved_repository_root,
+            all_diagnostics,
+            all_executed_rules,
+            all_failed_rules,
+            all_skipped_rules,
+        )
+    return (
+        all_diagnostics,
+        tuple(all_executed_rules),
+        tuple(all_failed_rules),
+        tuple(all_skipped_rules),
+    )
+
+
+def _run_rule(
+    rule: Rule,
+    document_set: DocumentSet,
+    resolved_repository_root: Path,
+    all_diagnostics: list[Diagnostic],
+    all_executed_rules: list[str],
+    all_failed_rules: list[str],
+    all_skipped_rules: list[str],
+) -> None:
+    pending_diagnostics: list[Diagnostic] = []
+    all_skipped_before = len(all_skipped_rules)
+    if _rule_execution_failed(
+        rule,
+        document_set,
+        resolved_repository_root,
+        pending_diagnostics,
+        all_skipped_rules,
+    ):
+        all_failed_rules.append(rule.rule_id)
+        return
+    if len(all_skipped_rules) != all_skipped_before:
+        return
+    all_diagnostics.extend(pending_diagnostics)
+    all_executed_rules.append(rule.rule_id)
+
+
+def _rule_execution_failed(
+    rule: Rule,
+    document_set: DocumentSet,
+    resolved_repository_root: Path,
+    all_diagnostics: list[Diagnostic],
+    all_skipped_rules: list[str],
+) -> bool:
+    try:
+        _execute_rule(
+            rule,
+            document_set,
+            resolved_repository_root,
+            all_diagnostics,
+            all_skipped_rules,
+        )
+    except (
+        AttributeError,
+        ImportError,
+        KeyError,
+        OSError,
+        RuntimeError,
+        SyntaxError,
+        TypeError,
+        UnicodeError,
+        ValueError,
+    ):
+        return True
+    return False
+
+
+def _execute_rule(
+    rule: Rule,
+    document_set: DocumentSet,
+    resolved_repository_root: Path,
+    all_diagnostics: list[Diagnostic],
+    all_skipped_rules: list[str],
+) -> None:
+    if isinstance(rule, DocumentRule):
+        _run_document_rule(
+            rule,
+            document_set,
+            resolved_repository_root,
+            all_diagnostics,
+            all_skipped_rules,
+        )
+        return
+    if isinstance(rule, ChangeSetRule):
+        _run_changeset_rule(rule, document_set, all_diagnostics, all_skipped_rules)
+        return
+    _run_repository_rule(rule, document_set, all_diagnostics, all_skipped_rules)
+
+
+def _run_document_rule(
+    rule: DocumentRule,
+    document_set: DocumentSet,
+    resolved_repository_root: Path,
+    all_diagnostics: list[Diagnostic],
+    all_skipped_rules: list[str],
+) -> None:
+    all_documents = tuple(
+        each_document
+        for each_document in document_set.documents
+        if rule.accepts(each_document)
+    )
+    if not all_documents:
+        all_skipped_rules.append(rule.rule_id)
+        return
+    for each_document in all_documents:
+        all_diagnostics.extend(
+            _scoped_diagnostics(
+                rule.check(each_document, resolved_repository_root),
+                each_document,
+            )
+        )
+
+
+def _run_changeset_rule(
+    rule: ChangeSetRule,
+    document_set: DocumentSet,
+    all_diagnostics: list[Diagnostic],
+    all_skipped_rules: list[str],
+) -> None:
+    if document_set.selection not in rule.selections:
+        all_skipped_rules.append(rule.rule_id)
+        return
+    all_diagnostics.extend(rule.check(document_set))
+
+
+def _run_repository_rule(
+    rule: RepositoryRule,
+    document_set: DocumentSet,
+    all_diagnostics: list[Diagnostic],
+    all_skipped_rules: list[str],
+) -> None:
+    if document_set.selection is not SelectionKind.REPOSITORY:
+        all_skipped_rules.append(rule.rule_id)
+        return
+    all_diagnostics.extend(rule.check(document_set))
+
+
+def _scoped_diagnostics(
+    all_diagnostics: Iterable[Diagnostic],
+    document: Document,
+) -> tuple[Diagnostic, ...]:
+    if document.changed_lines is None or not document.changed_lines:
+        return tuple(all_diagnostics)
+    return tuple(
+        each_diagnostic
+        for each_diagnostic in all_diagnostics
+        if each_diagnostic.location is None
+        or each_diagnostic.location.start_line in document.changed_lines
+    )
+
+
+def _diagnostic_sort_key(diagnostic: Diagnostic) -> tuple[str, int, int, str, str]:
+    if diagnostic.location is None:
+        return ("", 0, 0, diagnostic.rule_id, diagnostic.message)
+    return (
+        diagnostic.location.path.as_posix(),
+        diagnostic.location.start_line,
+        diagnostic.location.start_column,
+        diagnostic.rule_id,
+        diagnostic.message,
+    )