claude-dev-env 2.34.0 → 2.36.0

package/scripts/policy_lint/model.py

@@ -0,0 +1,387 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path, PurePosixPath
+from typing import TypeAlias
+
+from .config.constants import INCOMPLETE_EXIT_CODE
+
+
+class SelectionKind(StrEnum):
+    FILES = "files"
+    STAGED = "staged"
+    BASE = "base"
+    REPOSITORY = "repository"
+    TEXT = "text"
+
+
+class ContentOrigin(StrEnum):
+    WORKTREE = "worktree"
+    INDEX = "index"
+    REVISION_DIFF = "revision_diff"
+    TRACKED_TREE = "tracked_tree"
+    EDITOR = "editor"
+
+
+class Severity(StrEnum):
+    ERROR = "error"
+    WARNING = "warning"
+
+
+class RuleScope(StrEnum):
+    DOCUMENT = "document"
+    CHANGESET = "changeset"
+    REPOSITORY = "repository"
+
+
+@dataclass(frozen=True)
+class ExplicitFiles:
+    paths: tuple[Path, ...]
+
+
+@dataclass(frozen=True)
+class StagedChanges:
+    pass
+
+
+@dataclass(frozen=True)
+class BaseChanges:
+    revision: str
+
+
+@dataclass(frozen=True)
+class RepositoryTree:
+    pass
+
+
+@dataclass(frozen=True)
+class TextDocument:
+    path: Path
+    text: str
+
+
+LintSource: TypeAlias = (
+    ExplicitFiles | StagedChanges | BaseChanges | RepositoryTree | TextDocument
+)
+
+
+@dataclass(frozen=True)
+class Document:
+    path: PurePosixPath
+    text: str
+    prior_text: str | None
+    changed_lines: frozenset[int] | None
+    origin: ContentOrigin
+    prior_path: PurePosixPath | None = None
+
+    @classmethod
+    def from_text(
+        cls,
+        path: str | PurePosixPath,
+        text: str,
+        origin: ContentOrigin = ContentOrigin.EDITOR,
+    ) -> Document:
+        """Build a document from an unsaved text buffer.
+
+        Args:
+            path: Repository-relative document path.
+            text: Unsaved document text.
+            origin: Content source label.
+
+        Returns:
+            A document with no prior content.
+        """
+        normalized_path = PurePosixPath(
+            path.as_posix() if isinstance(path, PurePosixPath) else path
+        )
+        return cls(normalized_path, text, None, None, origin)
+
+
+@dataclass(frozen=True)
+class DocumentSet:
+    documents: tuple[Document, ...]
+    selection: SelectionKind
+    repository_root: Path
+    deleted_paths: tuple[PurePosixPath, ...] = ()
+    renamed_paths: tuple[tuple[PurePosixPath, PurePosixPath], ...] = ()
+
+
+@dataclass(frozen=True)
+class LintRequest:
+    repository_root: Path
+    source: LintSource | DocumentSet
+    rule_sets: frozenset[str] = frozenset({"changed"})
+
+    @classmethod
+    def files(
+        cls,
+        repository_root: Path,
+        all_paths: Sequence[Path],
+        all_rule_sets: frozenset[str] = frozenset({"changed"}),
+    ) -> LintRequest:
+        """Build a request for current worktree files.
+
+        Args:
+            repository_root: Repository root.
+            all_paths: Files to read.
+            all_rule_sets: Rule sets requested by the caller.
+
+        Returns:
+            A file-selection request.
+        """
+        return cls(repository_root, ExplicitFiles(tuple(all_paths)), all_rule_sets)
+
+    @classmethod
+    def staged(
+        cls,
+        repository_root: Path,
+        all_rule_sets: frozenset[str] = frozenset({"changed"}),
+    ) -> LintRequest:
+        """Build a request for staged index content.
+
+        Args:
+            repository_root: Repository root.
+            all_rule_sets: Rule sets requested by the caller.
+
+        Returns:
+            A staged-selection request.
+        """
+        return cls(repository_root, StagedChanges(), all_rule_sets)
+
+    @classmethod
+    def base(
+        cls,
+        repository_root: Path,
+        revision: str,
+        all_rule_sets: frozenset[str] = frozenset({"changed"}),
+    ) -> LintRequest:
+        """Build a request for changes against a base revision.
+
+        Args:
+            repository_root: Repository root.
+            revision: Revision that identifies the merge-base comparison.
+            all_rule_sets: Rule sets requested by the caller.
+
+        Returns:
+            A base-selection request.
+        """
+        return cls(repository_root, BaseChanges(revision), all_rule_sets)
+
+    @classmethod
+    def repository(
+        cls,
+        repository_root: Path,
+        all_rule_sets: frozenset[str] = frozenset({"repository"}),
+    ) -> LintRequest:
+        """Build a request for tracked worktree files.
+
+        Args:
+            repository_root: Repository root.
+            all_rule_sets: Rule sets requested by the caller.
+
+        Returns:
+            A repository-selection request.
+        """
+        return cls(repository_root, RepositoryTree(), all_rule_sets)
+
+    @classmethod
+    def documents(
+        cls,
+        repository_root: Path,
+        all_documents: Sequence[Document],
+        all_rule_sets: frozenset[str] = frozenset({"changed"}),
+    ) -> LintRequest:
+        """Build a request from already selected documents.
+
+        Args:
+            repository_root: Repository root.
+            all_documents: Documents available to rules.
+            all_rule_sets: Rule sets requested by the caller.
+
+        Returns:
+            A document-set request.
+        """
+        document_set = DocumentSet(
+            tuple(all_documents), SelectionKind.TEXT, repository_root
+        )
+        return cls(repository_root, document_set, all_rule_sets)
+
+
+@dataclass(frozen=True)
+class Location:
+    path: PurePosixPath
+    start_line: int
+    start_column: int = 1
+    end_line: int | None = None
+    end_column: int | None = None
+
+    def normalized(self) -> Location:
+        """Fill omitted range endpoints with the start position.
+
+        Returns:
+            A location with complete source-range endpoints.
+        """
+        return Location(
+            self.path,
+            self.start_line,
+            self.start_column,
+            self.end_line if self.end_line is not None else self.start_line,
+            self.end_column if self.end_column is not None else self.start_column,
+        )
+
+    def as_dict(self) -> dict[str, object]:
+        """Return a JSON-compatible source location.
+
+        Returns:
+            The normalized location mapping.
+        """
+        normalized_location = self.normalized()
+        return {
+            "path": normalized_location.path.as_posix(),
+            "start_line": normalized_location.start_line,
+            "start_column": normalized_location.start_column,
+            "end_line": normalized_location.end_line,
+            "end_column": normalized_location.end_column,
+        }
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    rule_id: str
+    severity: Severity
+    message: str
+    location: Location | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        """Return a JSON-compatible diagnostic.
+
+        Returns:
+            The diagnostic mapping.
+        """
+        return {
+            "rule_id": self.rule_id,
+            "severity": self.severity.value,
+            "message": self.message,
+            "location": None if self.location is None else self.location.as_dict(),
+        }
+
+
+DocumentChecker: TypeAlias = Callable[[Document, Path], Iterable[Diagnostic]]
+DocumentSetChecker: TypeAlias = Callable[[DocumentSet], Iterable[Diagnostic]]
+
+
+@dataclass(frozen=True)
+class DocumentRule:
+    rule_id: str
+    rule_sets: frozenset[str]
+    accepts: Callable[[Document], bool]
+    check: DocumentChecker
+
+
+@dataclass(frozen=True)
+class ChangeSetRule:
+    rule_id: str
+    rule_sets: frozenset[str]
+    check: DocumentSetChecker
+
+
+@dataclass(frozen=True)
+class RepositoryRule:
+    rule_id: str
+    rule_sets: frozenset[str]
+    check: DocumentSetChecker
+
+
+Rule: TypeAlias = DocumentRule | ChangeSetRule | RepositoryRule
+
+
+@dataclass(frozen=True)
+class EditorDiagnostic:
+    path: PurePosixPath
+    line: int
+    column: int
+    message: str
+    severity: Severity
+    rule_id: str
+
+    def as_dict(self) -> dict[str, object]:
+        """Return an editor-compatible diagnostic mapping.
+
+        Returns:
+            The editor diagnostic mapping.
+        """
+        return {
+            "path": self.path.as_posix(),
+            "line": self.line,
+            "column": self.column,
+            "message": self.message,
+            "severity": self.severity.value,
+            "rule_id": self.rule_id,
+        }
+
+
+@dataclass(frozen=True)
+class LintReport:
+    schema_version: int
+    diagnostics: tuple[Diagnostic, ...]
+    checked_documents: tuple[PurePosixPath, ...]
+    executed_rules: tuple[str, ...]
+    failed_rules: tuple[str, ...]
+    skipped_rules: tuple[str, ...]
+
+    @property
+    def exit_code(self) -> int:
+        """Return the process exit code for this report.
+
+        Returns:
+            Zero for clean output, one for findings, or three for rule failure.
+        """
+        if self.failed_rules:
+            return INCOMPLETE_EXIT_CODE
+        if self.diagnostics:
+            return 1
+        return 0
+
+    def as_dict(self) -> dict[str, object]:
+        """Return the JSON result.
+
+        Returns:
+            The complete report mapping.
+        """
+        return {
+            "schema_version": self.schema_version,
+            "diagnostics": [
+                each_diagnostic.as_dict() for each_diagnostic in self.diagnostics
+            ],
+            "checked_documents": [
+                each_path.as_posix() for each_path in self.checked_documents
+            ],
+            "executed_rules": list(self.executed_rules),
+            "failed_rules": list(self.failed_rules),
+            "skipped_rules": list(self.skipped_rules),
+        }
+
+    def editor_diagnostics(self) -> tuple[EditorDiagnostic, ...]:
+        """Return source-located diagnostics in editor wire format.
+
+        Returns:
+            Diagnostics that carry a source location.
+        """
+        all_editor_diagnostics: list[EditorDiagnostic] = []
+        for each_diagnostic in self.diagnostics:
+            if each_diagnostic.location is None:
+                continue
+            normalized_location = each_diagnostic.location.normalized()
+            all_editor_diagnostics.append(
+                EditorDiagnostic(
+                    path=normalized_location.path,
+                    line=normalized_location.start_line,
+                    column=normalized_location.start_column,
+                    message=each_diagnostic.message,
+                    severity=each_diagnostic.severity,
+                    rule_id=each_diagnostic.rule_id,
+                )
+            )
+        return tuple(all_editor_diagnostics)

package/scripts/policy_lint/registry.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import PurePosixPath
+
+from . import adapters, model
+
+
+def build_document_rule(
+    rule_id: str,
+    accepts: Callable[[model.Document], bool],
+    check: model.DocumentChecker,
+) -> model.DocumentRule:
+    """Build a document rule for changed and repository selections.
+
+    Args:
+        rule_id: Stable rule identifier.
+        accepts: Predicate for documents handled by the rule.
+        check: Pure document checker.
+
+    Returns:
+        A configured document rule.
+    """
+    return model.DocumentRule(
+        rule_id, frozenset({"changed", "repository"}), accepts, check
+    )
+
+
+def repository_path_diagnostics(
+    document_set: model.DocumentSet,
+) -> tuple[model.Diagnostic, ...]:
+    """Report tracked paths that differ only by case.
+
+    Args:
+        document_set: Repository documents to compare.
+
+    Returns:
+        Path collision diagnostics.
+    """
+    path_by_lower_name: dict[str, PurePosixPath] = {}
+    all_diagnostics: list[model.Diagnostic] = []
+    for each_document in document_set.documents:
+        lower_name = each_document.path.as_posix().lower()
+        previous_path = path_by_lower_name.get(lower_name)
+        if previous_path is not None and previous_path != each_document.path:
+            all_diagnostics.append(
+                model.Diagnostic(
+                    "repository-path-collision",
+                    model.Severity.ERROR,
+                    f"Repository paths differ only by case: {previous_path}",
+                    model.Location(each_document.path, 1, 1),
+                )
+            )
+        path_by_lower_name[lower_name] = each_document.path
+    return tuple(all_diagnostics)
+
+
+def _python_document_rules() -> tuple[model.Rule, ...]:
+    return (
+        build_document_rule(
+            "validators", adapters.accepts_python, adapters.validator_diagnostics
+        ),
+        build_document_rule(
+            "code-rules", adapters.accepts_code, adapters.code_rule_diagnostics
+        ),
+        build_document_rule(
+            "docstring-gate-count",
+            adapters.accepts_markdown,
+            adapters.docstring_gate_diagnostics,
+        ),
+        build_document_rule(
+            "rmtree-safety", adapters.accepts_python, adapters.rmtree_diagnostics
+        ),
+        build_document_rule(
+            "subprocess-budget",
+            adapters.accepts_python,
+            adapters.subprocess_budget_diagnostics,
+        ),
+        build_document_rule(
+            "hook-prose-consistency",
+            adapters.accepts_python,
+            adapters.hook_prose_diagnostics,
+        ),
+    )
+
+
+def _text_document_rules() -> tuple[model.Rule, ...]:
+    return (
+        build_document_rule(
+            "state-description",
+            adapters.accepts_source_or_markdown,
+            adapters.state_description_diagnostics,
+        ),
+        build_document_rule(
+            "plain-language",
+            adapters.accepts_stored_prompt,
+            adapters.plain_language_diagnostics,
+        ),
+        build_document_rule(
+            "open-questions", adapters.accepts_plans, adapters.open_question_diagnostics
+        ),
+        build_document_rule(
+            "workflow-substitution",
+            adapters.accepts_workflow,
+            adapters.workflow_substitution_diagnostics,
+        ),
+    )
+
+
+def _configuration_document_rules() -> tuple[model.Rule, ...]:
+    return (
+        build_document_rule(
+            "hook-configuration",
+            adapters.accepts_hook_configuration,
+            adapters.hook_configuration_diagnostics,
+        ),
+        build_document_rule(
+            "hook-format",
+            adapters.accepts_hook_format,
+            adapters.hook_format_diagnostics,
+        ),
+    )
+
+
+def default_registry() -> tuple[model.Rule, ...]:
+    """Return the default policy rules in a fixed order.
+
+    Returns:
+        The default policy rules.
+    """
+    return (
+        *_python_document_rules(),
+        *_text_document_rules(),
+        *_configuration_document_rules(),
+        model.ChangeSetRule(
+            "test-pairing", frozenset({"changed"}), adapters.test_pairing_diagnostics
+        ),
+        model.RepositoryRule(
+            "repository-path-collision",
+            frozenset({"repository"}),
+            repository_path_diagnostics,
+        ),
+    )
+
+
+def selected_rules(
+    all_rules: tuple[model.Rule, ...], all_rule_sets: frozenset[str]
+) -> tuple[model.Rule, ...]:
+    """Select rules that belong to one requested rule set.
+
+    Args:
+        all_rules: Candidate registry entries.
+        all_rule_sets: Rule sets requested by the caller.
+
+    Returns:
+        Matching rules in registry order.
+    """
+    return tuple(
+        each_rule
+        for each_rule in all_rules
+        if each_rule.rule_sets.intersection(all_rule_sets)
+    )

package/scripts/policy_lint/render.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from enum import StrEnum
+
+from .model import Diagnostic, EditorDiagnostic, LintReport
+
+
+class ReportFormat(StrEnum):
+    TEXT = "text"
+    JSON = "json"
+    EDITOR = "editor"
+
+
+def render(report: LintReport, report_format: ReportFormat) -> str:
+    """Render a lint report.
+
+    ::
+
+        json   -> {"diagnostics": [...], "schema_version": 1, ...}
+        editor -> src/app.py:4:2: error: located finding [rule-a]
+        text   -> editor lines plus diagnostics with no location
+
+    Args:
+        report: Lint report from the engine.
+        report_format: text, json, or editor.
+
+    Returns:
+        The formatted report body.
+    """
+    if report_format is ReportFormat.JSON:
+        return _render_json(report)
+    if report_format is ReportFormat.EDITOR:
+        return _render_editor(report)
+    return _render_text(report)
+
+
+def _render_json(report: LintReport) -> str:
+    line_separator = "\n"
+    return json.dumps(report.as_dict(), sort_keys=True) + line_separator
+
+
+def _render_editor(report: LintReport) -> str:
+    all_lines = [
+        _editor_line(each_diagnostic)
+        for each_diagnostic in report.editor_diagnostics()
+    ]
+    all_lines.extend(
+        f"cde-lint:1:1: error: rule failed: {each_rule_id}"
+        for each_rule_id in report.failed_rules
+    )
+    return _join_lines(all_lines)
+
+
+def _render_text(report: LintReport) -> str:
+    all_lines = [
+        _text_line(each_diagnostic) for each_diagnostic in report.diagnostics
+    ]
+    all_lines.extend(
+        f"error: rule failed: {each_rule_id}" for each_rule_id in report.failed_rules
+    )
+    return _join_lines(all_lines)
+
+
+def _join_lines(all_lines: Iterable[str]) -> str:
+    line_separator = "\n"
+    all_collected_lines = list(all_lines)
+    if not all_collected_lines:
+        return ""
+    return line_separator.join(all_collected_lines) + line_separator
+
+
+def _editor_line(diagnostic: EditorDiagnostic) -> str:
+    return (
+        f"{diagnostic.path.as_posix()}:{diagnostic.line}:{diagnostic.column}: "
+        f"{diagnostic.severity.value}: {diagnostic.message} [{diagnostic.rule_id}]"
+    )
+
+
+def _text_line(diagnostic: Diagnostic) -> str:
+    if diagnostic.location is None:
+        return (
+            f"{diagnostic.severity.value}: {diagnostic.message} [{diagnostic.rule_id}]"
+        )
+    normalized_location = diagnostic.location.normalized()
+    return (
+        f"{normalized_location.path.as_posix()}:{normalized_location.start_line}:"
+        f"{normalized_location.start_column}: {diagnostic.severity.value}: "
+        f"{diagnostic.message} [{diagnostic.rule_id}]"
+    )