moai-adk 0.35.1__py3-none-any.whl

moai_adk/core/git/__init__.py

@@ -0,0 +1,31 @@
+"""
+Git management module.
+
+Manage Git workflows using GitPython.
+
+SPEC: .moai/specs/SPEC-CORE-GIT-001/spec.md
+"""
+
+from moai_adk.core.git.branch import generate_branch_name
+from moai_adk.core.git.branch_manager import BranchManager
+from moai_adk.core.git.checkpoint import CheckpointManager
+from moai_adk.core.git.commit import format_commit_message
+from moai_adk.core.git.conflict_detector import (
+    ConflictFile,
+    ConflictSeverity,
+    GitConflictDetector,
+)
+from moai_adk.core.git.event_detector import EventDetector
+from moai_adk.core.git.manager import GitManager
+
+__all__ = [
+    "GitManager",
+    "generate_branch_name",
+    "format_commit_message",
+    "BranchManager",
+    "CheckpointManager",
+    "EventDetector",
+    "GitConflictDetector",
+    "ConflictFile",
+    "ConflictSeverity",
+]

moai_adk/core/git/branch.py

@@ -0,0 +1,25 @@
+"""
+Branch naming utilities.
+
+SPEC: .moai/specs/SPEC-CORE-GIT-001/spec.md
+"""
+
+
+def generate_branch_name(spec_id: str) -> str:
+    """
+    Generate a branch name from a SPEC ID.
+
+    Args:
+        spec_id: SPEC identifier (e.g., "AUTH-001").
+
+    Returns:
+        Branch name in the feature/SPEC-XXX format.
+
+    Examples:
+        >>> generate_branch_name("AUTH-001")
+        'feature/SPEC-AUTH-001'
+
+        >>> generate_branch_name("CORE-GIT-001")
+        'feature/SPEC-CORE-GIT-001'
+    """
+    return f"feature/SPEC-{spec_id}"

moai_adk/core/git/branch_manager.py

@@ -0,0 +1,129 @@
+"""
+Branch Manager - Manage local checkpoint branches.
+
+SPEC: .moai/specs/SPEC-CHECKPOINT-EVENT-001/spec.md
+"""
+
+from datetime import datetime
+
+import git
+
+
+class BranchManager:
+    """Manage local checkpoint branches."""
+
+    MAX_CHECKPOINTS = 10
+    CHECKPOINT_PREFIX = "before-"
+
+    def __init__(self, repo: git.Repo):
+        """
+        Initialize the BranchManager.
+
+        Args:
+            repo: GitPython Repo instance.
+        """
+        self.repo = repo
+        self._old_branches: set[str] = set()
+
+    def create_checkpoint_branch(self, operation: str) -> str:
+        """
+        Create a checkpoint branch.
+
+        SPEC requirement: before-{operation}-{timestamp} format for local branches.
+
+        Args:
+            operation: Operation name (delete, refactor, merge, etc.).
+
+        Returns:
+            Name of the created branch.
+        """
+        timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+        branch_name = f"{self.CHECKPOINT_PREFIX}{operation}-{timestamp}"
+
+        # Create the branch from the current HEAD
+        self.repo.create_head(branch_name)
+
+        # Remove old checkpoints using FIFO order
+        self._enforce_max_checkpoints()
+
+        return branch_name
+
+    def branch_exists(self, branch_name: str) -> bool:
+        """
+        Check if a branch exists.
+
+        Args:
+            branch_name: Name of the branch to check.
+
+        Returns:
+            True when the branch exists, otherwise False.
+        """
+        return branch_name in [head.name for head in self.repo.heads]
+
+    def has_remote_tracking(self, branch_name: str) -> bool:
+        """
+        Determine whether a remote tracking branch exists.
+
+        SPEC requirement: checkpoints must remain local-only branches.
+
+        Args:
+            branch_name: Branch name to inspect.
+
+        Returns:
+            True if a tracking branch exists, otherwise False.
+        """
+        try:
+            branch = self.repo.heads[branch_name]
+            return branch.tracking_branch() is not None
+        except (IndexError, AttributeError):
+            return False
+
+    def list_checkpoint_branches(self) -> list[str]:
+        """
+        List all checkpoint branches.
+
+        Returns:
+            Names of checkpoint branches.
+        """
+        return [head.name for head in self.repo.heads if head.name.startswith(self.CHECKPOINT_PREFIX)]
+
+    def mark_as_old(self, branch_name: str) -> None:
+        """
+        Mark a branch as old (used for tests).
+
+        Args:
+            branch_name: Branch to flag as old.
+        """
+        self._old_branches.add(branch_name)
+
+    def cleanup_old_checkpoints(self, max_count: int) -> None:
+        """
+        Clean up old checkpoint branches.
+
+        SPEC requirement: delete using FIFO when exceeding the maximum count.
+
+        Args:
+            max_count: Maximum number of checkpoints to retain.
+        """
+        checkpoints = self.list_checkpoint_branches()
+
+        # Sort in chronological order (branches marked via mark_as_old first)
+        sorted_checkpoints = sorted(checkpoints, key=lambda name: (name not in self._old_branches, name))
+
+        # Delete the excess branches
+        to_delete = sorted_checkpoints[: len(sorted_checkpoints) - max_count]
+        for branch_name in to_delete:
+            if branch_name in [head.name for head in self.repo.heads]:
+                self.repo.delete_head(branch_name, force=True)
+
+    def _enforce_max_checkpoints(self) -> None:
+        """Maintain the maximum number of checkpoints (internal)."""
+        checkpoints = self.list_checkpoint_branches()
+
+        if len(checkpoints) > self.MAX_CHECKPOINTS:
+            # Sort alphabetically (older timestamps first)
+            sorted_checkpoints = sorted(checkpoints)
+            to_delete = sorted_checkpoints[: len(sorted_checkpoints) - self.MAX_CHECKPOINTS]
+
+            for branch_name in to_delete:
+                self.repo.delete_head(branch_name, force=True)

moai_adk/core/git/checkpoint.py

@@ -0,0 +1,134 @@
+"""
+Checkpoint Manager - Event-driven checkpoint system.
+
+SPEC: .moai/specs/SPEC-CHECKPOINT-EVENT-001/spec.md
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import git
+
+from moai_adk.core.git.branch_manager import BranchManager
+from moai_adk.core.git.event_detector import EventDetector
+
+
+class CheckpointManager:
+    """Manage creation and restoration of event-driven checkpoints."""
+
+    def __init__(self, repo: git.Repo, project_root: Path):
+        """
+        Initialize the CheckpointManager.
+
+        Args:
+            repo: GitPython Repo instance.
+            project_root: Project root directory.
+        """
+        self.repo = repo
+        self.project_root = project_root
+        self.event_detector = EventDetector()
+        self.branch_manager = BranchManager(repo)
+        self.log_file = project_root / ".moai" / "checkpoints.log"
+
+        # Ensure the log directory exists
+        self.log_file.parent.mkdir(parents=True, exist_ok=True)
+
+    def create_checkpoint_if_risky(
+        self,
+        operation: str,
+        deleted_files: Optional[list[str]] = None,
+        renamed_files: Optional[list[tuple[str, str]]] = None,
+        modified_files: Optional[list[Path]] = None,
+    ) -> Optional[str]:
+        """
+        Create a checkpoint when a risky operation is detected.
+
+        SPEC requirement: automatically create a checkpoint for risky actions.
+
+        Args:
+            operation: Operation type.
+            deleted_files: Files scheduled for deletion.
+            renamed_files: Files that will be renamed.
+            modified_files: Files that will be modified.
+
+        Returns:
+            Created checkpoint ID (branch name) or None when the operation is safe.
+        """
+        is_risky = False
+
+        # Identify large deletion operations
+        if deleted_files and self.event_detector.is_risky_deletion(deleted_files):
+            is_risky = True
+
+        # Identify large-scale refactoring
+        if renamed_files and self.event_detector.is_risky_refactoring(renamed_files):
+            is_risky = True
+
+        # Check for critical file modifications
+        if modified_files:
+            for file_path in modified_files:
+                if self.event_detector.is_critical_file(file_path):
+                    is_risky = True
+                    break
+
+        if not is_risky:
+            return None
+
+        # Create a checkpoint
+        checkpoint_id = self.branch_manager.create_checkpoint_branch(operation)
+
+        # Record checkpoint metadata
+        self._log_checkpoint(checkpoint_id, operation)
+
+        return checkpoint_id
+
+    def restore_checkpoint(self, checkpoint_id: str) -> None:
+        """
+        Restore the repository to the specified checkpoint.
+
+        SPEC requirement: capture the current state as a new checkpoint before restoring.
+
+        Args:
+            checkpoint_id: Target checkpoint ID (branch name).
+        """
+        # Save current state as a safety checkpoint before restoring
+        safety_checkpoint = self.branch_manager.create_checkpoint_branch("restore")
+        self._log_checkpoint(safety_checkpoint, "restore", is_safety=True)
+
+        # Check out the checkpoint branch
+        self.repo.git.checkout(checkpoint_id)
+
+    def list_checkpoints(self) -> list[str]:
+        """
+        List all checkpoints.
+
+        Returns:
+            List of checkpoint IDs.
+        """
+        return self.branch_manager.list_checkpoint_branches()
+
+    def _log_checkpoint(self, checkpoint_id: str, operation: str, is_safety: bool = False) -> None:
+        """
+        Append checkpoint metadata to the log file.
+
+        SPEC requirement: write metadata to .moai/checkpoints.log.
+
+        Args:
+            checkpoint_id: Checkpoint identifier.
+            operation: Operation type.
+            is_safety: Whether the checkpoint was created for safety.
+        """
+        timestamp = datetime.now().isoformat()
+
+        log_entry = f"""---
+checkpoint_id: {checkpoint_id}
+operation: {operation}
+timestamp: {timestamp}
+is_safety: {is_safety}
+---
+"""
+
+        # Append the entry to the log
+        with open(self.log_file, "a", encoding="utf-8") as f:
+            f.write(log_entry)

moai_adk/core/git/commit.py

@@ -0,0 +1,67 @@
+"""
+Commit message formatting utilities.
+
+SPEC: .moai/specs/SPEC-CORE-GIT-001/spec.md
+"""
+
+from typing import Literal
+
+
+def format_commit_message(
+    stage: Literal["red", "green", "refactor", "docs"],
+    description: str,
+    locale: str = "ko",
+) -> str:
+    """
+    Generate a commit message for each TDD stage.
+
+    Args:
+        stage: TDD stage (red, green, refactor, docs).
+        description: Commit description text.
+        locale: Language code (ko, en, ja, zh).
+
+    Returns:
+        Formatted commit message.
+
+    Examples:
+        >>> format_commit_message("red", "Add failing authentication test", "ko")
+        '🔴 RED: Add failing authentication test'
+
+        >>> format_commit_message("green", "Implement authentication", "en")
+        '🟢 GREEN: Implement authentication'
+
+        >>> format_commit_message("refactor", "Improve code structure", "ko")
+        '♻️ REFACTOR: Improve code structure'
+    """
+    templates = {
+        "ko": {
+            "red": "🔴 RED: {desc}",
+            "green": "🟢 GREEN: {desc}",
+            "refactor": "♻️ REFACTOR: {desc}",
+            "docs": "📝 DOCS: {desc}",
+        },
+        "en": {
+            "red": "🔴 RED: {desc}",
+            "green": "🟢 GREEN: {desc}",
+            "refactor": "♻️ REFACTOR: {desc}",
+            "docs": "📝 DOCS: {desc}",
+        },
+        "ja": {
+            "red": "🔴 RED: {desc}",
+            "green": "🟢 GREEN: {desc}",
+            "refactor": "♻️ REFACTOR: {desc}",
+            "docs": "📝 DOCS: {desc}",
+        },
+        "zh": {
+            "red": "🔴 RED: {desc}",
+            "green": "🟢 GREEN: {desc}",
+            "refactor": "♻️ REFACTOR: {desc}",
+            "docs": "📝 DOCS: {desc}",
+        },
+    }
+
+    template = templates.get(locale, templates["en"]).get(stage.lower())
+    if not template:
+        raise ValueError(f"Invalid stage: {stage}")
+
+    return template.format(desc=description)