ara-cli 0.1.10.5__py3-none-any.whl → 0.1.14.0__py3-none-any.whl

ara_cli/children_contribution_updater.py

@@ -0,0 +1,737 @@
+"""
+Children Contribution Updater Module
+
+This module handles updating children artefacts' contribution field when their parent's
+classifier changes during artefact conversion. It follows Single Responsibility Principle
+by separating this concern from the main ArtefactConverter class.
+
+Supports both interactive (CLI) and non-interactive (API) modes.
+"""
+
+import os
+import json
+import sys
+from typing import Optional, Dict, List, Tuple, Literal
+from enum import Enum
+from ara_cli.classifier import Classifier
+from ara_cli.artefact_reader import ArtefactReader
+from ara_cli.directory_navigator import DirectoryNavigator
+from ara_cli.file_classifier import FileClassifier
+
+# Import readline for tab completion (Unix) or pyreadline3 (Windows)
+try:
+    import readline
+except ImportError:
+    try:
+        import pyreadline3 as readline
+    except ImportError:
+        readline = None
+
+
+class InputCompleter:
+    """
+    A simple completer for readline tab completion.
+    Provides completion for a list of options.
+    """
+
+    def __init__(self, options: List[str]):
+        self.options = sorted(options)
+        self.matches: List[str] = []
+
+    def complete(self, text: str, state: int) -> Optional[str]:
+        """Return the next possible completion for 'text'."""
+        if state == 0:
+            # First call for this text - compute matches
+            if text:
+                self.matches = [o for o in self.options if o.startswith(text)]
+            else:
+                self.matches = self.options[:]
+
+        try:
+            return self.matches[state]
+        except IndexError:
+            return None
+
+
+def _setup_completer(options: List[str]) -> None:
+    """Setup readline completer with the given options."""
+    if readline is None:
+        return
+
+    completer = InputCompleter(options)
+    readline.set_completer(completer.complete)
+    readline.set_completer_delims(" \t\n")
+
+    # Enable tab completion
+    if sys.platform == "darwin":
+        readline.parse_and_bind("bind ^I rl_complete")
+    else:
+        readline.parse_and_bind("tab: complete")
+
+
+def _clear_completer() -> None:
+    """Clear the readline completer."""
+    if readline is None:
+        return
+    readline.set_completer(None)
+
+
+class ChildrenAction(str, Enum):
+    """Actions for handling children when converting to leaf-node types."""
+
+    CANCEL = "cancel"
+    CLEAR = "clear"
+    REASSIGN = "reassign"
+
+
+class ChildrenContributionUpdater:
+    """
+    Handles updating children's contribution field when parent artefact is converted.
+
+    Responsibilities:
+    - Find children of a parent artefact
+    - Update children's contribution classifier to new parent type
+    - Handle edge cases when new parent type cannot have children (task/issue)
+    - Clear contribution rule if new parent doesn't support rules
+    """
+
+    # User choice constants for edge case handling
+    CHOICE_CANCEL = "1"
+    CHOICE_CLEAR_CONTRIBUTION = "2"
+    CHOICE_SELECT_NEW_PARENT = "3"
+
+    def __init__(self, file_system=None):
+        self.file_system = file_system or os
+
+    def get_children_info(
+        self, artefact_name: str, old_classifier: str, new_classifier: str
+    ) -> Dict:
+        """
+        Get information about children for preview/modal display.
+        Used by API to show children info before conversion.
+
+        Returns:
+            Dict with children info for frontend display:
+            {
+                "has_children": bool,
+                "children_count": int,
+                "children": {classifier: [{name, title}]},
+                "target_can_have_children": bool,
+                "requires_action": bool,
+                "valid_new_parent_classifiers": [str],
+                "target_exists": bool,
+                "message": str
+            }
+        """
+        children = self._find_children(artefact_name, old_classifier)
+        children_count = self._count_children(children)
+        target_can_have_children = Classifier.can_have_children(new_classifier)
+        target_exists = self._check_target_exists(artefact_name, new_classifier)
+        requires_action = children_count > 0 and not target_can_have_children
+
+        return {
+            "has_children": children_count > 0,
+            "children_count": children_count,
+            "children": self._format_children_for_display(children),
+            "target_can_have_children": target_can_have_children,
+            "requires_action": requires_action,
+            "valid_new_parent_classifiers": self._get_valid_parents_for_children(
+                children
+            ),
+            "target_exists": target_exists,
+            "message": self._build_info_message(
+                target_exists,
+                requires_action,
+                children_count,
+                new_classifier,
+                artefact_name,
+            ),
+        }
+
+    def _format_children_for_display(self, children: Dict) -> Dict:
+        children_formatted = {}
+        for classifier, artefacts in children.items():
+            children_formatted[classifier] = [
+                {
+                    "name": getattr(a, "title", "Unknown"),
+                    "title": getattr(a, "title", "Unknown"),
+                }
+                for a in artefacts
+            ]
+        return children_formatted
+
+    def _get_valid_parents_for_children(self, children: Dict) -> List[str]:
+        child_classifiers = [c for c in children.keys() if children[c]]
+        return (
+            self._get_common_valid_parents(child_classifiers)
+            if child_classifiers
+            else []
+        )
+
+    def _build_info_message(
+        self,
+        target_exists: bool,
+        requires_action: bool,
+        children_count: int,
+        new_classifier: str,
+        artefact_name: str,
+    ) -> str:
+        messages = []
+        if target_exists:
+            messages.append(
+                f"Target {new_classifier} '{artefact_name}' already exists. Choose 'Override' or 'Merge'."
+            )
+        if requires_action:
+            messages.append(
+                f"Converting to '{new_classifier}' requires handling {children_count} children artefacts."
+            )
+        elif children_count > 0:
+            messages.append(
+                f"Found {children_count} children. They will be updated to reference the new classifier."
+            )
+        return " ".join(messages) if messages else ""
+
+    def _check_target_exists(self, artefact_name: str, classifier: str) -> bool:
+        """Check if target artefact already exists."""
+        from ara_cli.artefact_reader import ArtefactReader
+
+        reader = ArtefactReader(file_system=self.file_system)
+        _, artefact_info = reader.read_artefact_data(artefact_name, classifier)
+        return artefact_info is not None
+
+    def get_available_parents_for_reassign(self, child_classifiers: List[str]) -> Dict:
+        """
+        Get available artefacts that can be assigned as new parents.
+        Used by API to populate reassign dropdown.
+
+        Returns:
+            Dict with available parents:
+            {
+                "valid_classifiers": [str],
+                "available_artefacts": {classifier: [{name, title}]}
+            }
+        """
+        valid_classifiers = self._get_common_valid_parents(child_classifiers)
+        available = self._get_available_parents(valid_classifiers)
+
+        # Format for response
+        available_formatted = {}
+        for classifier, artefacts in available.items():
+            available_formatted[classifier] = [
+                {"name": a.get("title", "Unknown"), "title": a.get("title", "Unknown")}
+                for a in artefacts
+            ]
+
+        return {
+            "valid_classifiers": valid_classifiers,
+            "available_artefacts": available_formatted,
+        }
+
+    def update_children_contributions(
+        self,
+        artefact_name: str,
+        old_classifier: str,
+        new_classifier: str,
+        force: bool = False,
+        children_action: Optional[str] = None,
+        new_parent_classifier: Optional[str] = None,
+        new_parent_name: Optional[str] = None,
+        json_output: bool = False,
+    ) -> bool:
+        """
+        Update all children's contribution field after parent conversion.
+
+        Args:
+            artefact_name: Name of the parent artefact being converted
+            old_classifier: Original classifier of the parent
+            new_classifier: New classifier of the parent
+            force: If True, automatically clear contributions for leaf-node conversions
+            children_action: Non-interactive mode action (cancel/clear/reassign)
+            new_parent_classifier: For reassign action, the new parent's classifier
+            new_parent_name: For reassign action, the new parent's name
+            json_output: If True, output JSON instead of text messages
+
+        Returns:
+            bool: True if conversion should continue, False if cancelled
+        """
+        # Find all children contributing to this parent
+        children = self._find_children(artefact_name, old_classifier)
+
+        if not children:
+            return True  # No children, continue conversion
+
+        children_count = self._count_children(children)
+        if not json_output:
+            print(
+                f"\n📦 Found {children_count} children contributing to '{artefact_name}' {old_classifier}."
+            )
+
+        # Check if new classifier can have children
+        if not Classifier.can_have_children(new_classifier):
+            return self._handle_leaf_node_conversion(
+                artefact_name,
+                old_classifier,
+                new_classifier,
+                children,
+                force,
+                children_action,
+                new_parent_classifier,
+                new_parent_name,
+                json_output,
+            )
+
+        # Normal case: update children's contribution to new classifier
+        return self._update_children_to_new_classifier(
+            artefact_name, old_classifier, new_classifier, children
+        )
+
+    def _find_children(self, artefact_name: str, classifier: str) -> Dict[str, List]:
+        """Find all children artefacts contributing to the parent."""
+        return ArtefactReader(self.file_system).find_children(artefact_name, classifier)
+
+    def _count_children(self, children: Dict[str, List]) -> int:
+        """Count total number of children across all classifiers."""
+        return sum(len(artefacts) for artefacts in children.values())
+
+    def _handle_leaf_node_conversion(
+        self,
+        artefact_name: str,
+        old_classifier: str,
+        new_classifier: str,
+        children: Dict[str, List],
+        force: bool,
+        children_action: Optional[str] = None,
+        new_parent_classifier: Optional[str] = None,
+        new_parent_name: Optional[str] = None,
+        json_output: bool = False,
+    ) -> bool:
+        """
+        Handle conversion to task/issue when parent has children.
+
+        Since task and issue cannot have children, user must choose:
+        1. Cancel the operation
+        2. Clear children's contribution field (--force default)
+        3. Select a new parent for children
+
+        Non-interactive mode: Use children_action parameter directly.
+        """
+        if not json_output:
+            print(f"\n⚠️  Warning: '{new_classifier}' artefacts cannot have children.")
+
+        # Non-interactive mode (API)
+        if children_action:
+            return self._handle_non_interactive_action(
+                children,
+                children_action,
+                new_parent_classifier,
+                new_parent_name,
+                json_output,
+            )
+
+        if force:
+            if not json_output:
+                print("🔄 Force mode: Clearing children's contribution fields...")
+            self._clear_children_contributions(children, json_output)
+            return True
+
+        # Interactive mode - Present options to user
+        print("\nPlease choose an option:")
+        print(f"  [{self.CHOICE_CANCEL}] Cancel the conversion")
+        print(
+            f"  [{self.CHOICE_CLEAR_CONTRIBUTION}] Clear children's contribution field"
+        )
+        print(f"  [{self.CHOICE_SELECT_NEW_PARENT}] Select a new parent for children")
+
+        choice = input("\nEnter your choice (1/2/3): ").strip()
+
+        if choice == self.CHOICE_CANCEL:
+            print("\n❌ Conversion cancelled. No changes were made.")
+            return False
+
+        elif choice == self.CHOICE_CLEAR_CONTRIBUTION:
+            self._clear_children_contributions(children, json_output)
+            return True
+
+        elif choice == self.CHOICE_SELECT_NEW_PARENT:
+            return self._select_new_parent_for_children(children, old_classifier)
+
+        else:
+            print("\n❌ Invalid choice. Conversion cancelled.")
+            return False
+
+    def _handle_non_interactive_action(
+        self,
+        children: Dict[str, List],
+        children_action: str,
+        new_parent_classifier: Optional[str],
+        new_parent_name: Optional[str],
+        json_output: bool = False,
+    ) -> bool:
+        """Handle children action in non-interactive (API) mode."""
+        action = children_action.lower()
+
+        action_handlers = {
+            ChildrenAction.CANCEL.value: lambda: self._action_cancel(json_output),
+            ChildrenAction.CLEAR.value: lambda: self._action_clear(
+                children, json_output
+            ),
+            ChildrenAction.REASSIGN.value: lambda: self._action_reassign(
+                children, new_parent_classifier, new_parent_name, json_output
+            ),
+        }
+
+        handler = action_handlers.get(action)
+        if handler:
+            return handler()
+
+        self._output_message(
+            json_output, "error", f"Invalid children_action: {children_action}"
+        )
+        return False
+
+    def _action_cancel(self, json_output: bool) -> bool:
+        """Handle cancel action."""
+        self._output_message(
+            json_output,
+            "cancelled",
+            "Conversion cancelled by user choice.",
+            text_msg="❌ Conversion cancelled by children_action parameter.",
+        )
+        return False
+
+    def _action_clear(self, children: Dict[str, List], json_output: bool) -> bool:
+        """Handle clear action."""
+        if not json_output:
+            print("🔄 Clearing children's contribution fields...")
+        self._clear_children_contributions(children, json_output)
+        return True
+
+    def _action_reassign(
+        self,
+        children: Dict[str, List],
+        new_parent_classifier: Optional[str],
+        new_parent_name: Optional[str],
+        json_output: bool,
+    ) -> bool:
+        """Handle reassign action."""
+        if not new_parent_classifier or not new_parent_name:
+            self._output_message(
+                json_output,
+                "error",
+                "new_parent_classifier and new_parent_name required for reassign action.",
+                text_msg="❌ Error: new_parent_classifier and new_parent_name are required for reassign action.",
+            )
+            return False
+
+        if not self._validate_parent_exists(new_parent_name, new_parent_classifier):
+            self._output_message(
+                json_output,
+                "error",
+                f"Artefact '{new_parent_name}' of type '{new_parent_classifier}' does not exist.",
+            )
+            return False
+
+        self._reassign_children_to_parent(
+            children, new_parent_name, new_parent_classifier, json_output
+        )
+        return True
+
+    def _output_message(
+        self,
+        json_output: bool,
+        status: str,
+        message: str,
+        text_msg: Optional[str] = None,
+    ) -> None:
+        """Output message in JSON or text format."""
+        if json_output:
+            print(json.dumps({"status": status, "message": message}))
+        else:
+            print(f"\n{text_msg or f'❌ {message}'}")
+
+    def _clear_children_contributions(
+        self, children: Dict[str, List], json_output: bool = False
+    ) -> None:
+        """Clear contribution field for all children artefacts."""
+        if not json_output:
+            print("\n🗑️  Clearing contributions...")
+
+        # Save current directory and navigate to target
+        original_dir = self.file_system.getcwd()
+        try:
+            navigator = DirectoryNavigator()
+            navigator.navigate_to_target()
+
+            for classifier, artefacts in children.items():
+                for artefact in artefacts:
+                    artefact_title = getattr(artefact, "title", "Unknown")
+                    artefact.contribution = None
+                    self._save_artefact(artefact, classifier)
+                    if not json_output:
+                        print(
+                            f"   ✓ Cleared contribution for '{artefact_title}' {classifier}"
+                        )
+
+            if not json_output:
+                print(f"\n✅ Cleared contribution for all children.")
+        finally:
+            # Restore original directory
+            self.file_system.chdir(original_dir)
+
+    def _select_new_parent_for_children(
+        self, children: Dict[str, List], old_classifier: str
+    ) -> bool:
+        """
+        Allow user to select a new parent for all children.
+        Prompts for classifier and artefact name instead of listing all options.
+        """
+        child_classifiers = [c for c in children.keys() if children[c]]
+        if not child_classifiers:
+            return True
+
+        valid_parents = self._get_common_valid_parents(child_classifiers)
+        if not valid_parents:
+            print(
+                "\n❌ No valid parent types available for children. Conversion cancelled."
+            )
+            return False
+
+        try:
+            classifier_input = self._prompt_for_classifier(valid_parents)
+            if not classifier_input:
+                return False
+
+            artefact_name = self._prompt_for_artefact_name(classifier_input)
+            if not artefact_name:
+                return False
+
+            self._reassign_children_to_parent(children, artefact_name, classifier_input)
+            return True
+        except (ValueError, EOFError, KeyboardInterrupt):
+            print("\n❌ Input cancelled. Conversion cancelled.")
+            return False
+
+    def _prompt_for_classifier(self, valid_parents: List[str]) -> Optional[str]:
+        """Prompt user to select a valid classifier."""
+        print(f"\nValid parent types for children: {', '.join(valid_parents)}")
+        print("(Use Tab for autocomplete)")
+
+        _setup_completer(valid_parents)
+        classifier_input = input("\nEnter parent classifier: ").strip().lower()
+        _clear_completer()
+
+        if not classifier_input:
+            print("\n❌ No classifier provided. Conversion cancelled.")
+            return None
+
+        if classifier_input not in valid_parents:
+            print(
+                f"\n❌ Invalid classifier '{classifier_input}'. Must be one of: {', '.join(valid_parents)}"
+            )
+            print("Conversion cancelled.")
+            return None
+
+        return classifier_input
+
+    def _prompt_for_artefact_name(self, classifier: str) -> Optional[str]:
+        """Prompt user to enter an artefact name and validate it exists."""
+        available_parents = self._get_available_parents([classifier])
+        artefact_options = [
+            a.get("title", "")
+            for a in available_parents.get(classifier, [])
+            if a.get("title")
+        ]
+
+        _setup_completer(artefact_options)
+        artefact_name = input(f"Enter {classifier} artefact name: ").strip()
+        _clear_completer()
+
+        if not artefact_name:
+            print("\n❌ No artefact name provided. Conversion cancelled.")
+            return None
+
+        if not self._validate_parent_exists(artefact_name, classifier):
+            print(
+                f"\n❌ Artefact '{artefact_name}' of type '{classifier}' does not exist."
+            )
+            print("Conversion cancelled.")
+            return None
+
+        return artefact_name
+
+    def _validate_parent_exists(self, artefact_name: str, classifier: str) -> bool:
+        """Validate that the specified parent artefact exists by checking if file exists."""
+        import os.path as ospath
+
+        sub_directory = Classifier.get_sub_directory(classifier)
+
+        # Check if file exists in ara directory (relative to current working directory)
+        file_path = ospath.join("ara", sub_directory, f"{artefact_name}.{classifier}")
+        return ospath.exists(file_path)
+
+    def _get_common_valid_parents(self, child_classifiers: List[str]) -> List[str]:
+        """Get parent classifiers that are valid for all children."""
+        if not child_classifiers:
+            return []
+
+        # Start with valid parents of first child
+        common_parents = set(
+            Classifier.get_valid_parent_classifiers(child_classifiers[0])
+        )
+
+        # Intersect with valid parents of other children
+        for classifier in child_classifiers[1:]:
+            valid_parents = set(Classifier.get_valid_parent_classifiers(classifier))
+            common_parents = common_parents.intersection(valid_parents)
+
+        # Filter out leaf-node classifiers (task, issue)
+        return [p for p in common_parents if Classifier.can_have_children(p)]
+
+    def _get_available_parents(self, valid_classifiers: List[str]) -> Dict[str, List]:
+        """Get available artefacts that can be assigned as parents."""
+        # Save current directory and navigate to target
+        original_dir = self.file_system.getcwd()
+        try:
+            navigator = DirectoryNavigator()
+            navigator.navigate_to_target()
+
+            file_classifier = FileClassifier(self.file_system)
+            all_classified_files = file_classifier.classify_files()
+
+            # Filter to only valid parent classifiers
+            classified_files = {
+                k: v for k, v in all_classified_files.items() if k in valid_classifiers
+            }
+
+            # Filter out empty classifiers
+            return {k: v for k, v in classified_files.items() if v}
+        finally:
+            # Restore original directory
+            self.file_system.chdir(original_dir)
+
+    def _reassign_children_to_parent(
+        self,
+        children: Dict[str, List],
+        new_parent_name: str,
+        new_parent_classifier: str,
+        json_output: bool = False,
+    ) -> None:
+        """Reassign all children to a new parent artefact."""
+        if not json_output:
+            print(
+                f"\n🔄 Reassigning children to '{new_parent_name}' {new_parent_classifier}..."
+            )
+
+        original_dir = self.file_system.getcwd()
+        try:
+            DirectoryNavigator().navigate_to_target()
+            supports_rules = new_parent_classifier in ["epic", "userstory"]
+
+            for classifier, artefacts in children.items():
+                for artefact in artefacts:
+                    self._reassign_single_child(
+                        artefact,
+                        classifier,
+                        new_parent_name,
+                        new_parent_classifier,
+                        supports_rules,
+                        json_output,
+                    )
+
+            if not json_output:
+                print("\n✅ All children reassigned successfully.")
+        finally:
+            self.file_system.chdir(original_dir)
+
+    def _reassign_single_child(
+        self,
+        artefact,
+        classifier: str,
+        new_parent_name: str,
+        new_parent_classifier: str,
+        supports_rules: bool,
+        json_output: bool,
+    ) -> None:
+        """Reassign a single child to new parent."""
+        artefact_title = getattr(artefact, "title", "Unknown")
+        current_rule = self._get_artefact_rule(artefact)
+        rule_to_set = current_rule if supports_rules else None
+
+        artefact.set_contribution(new_parent_name, new_parent_classifier, rule_to_set)
+        self._save_artefact(artefact, classifier)
+
+        if not json_output:
+            print(
+                f"   ✓ '{artefact_title}' {classifier} → '{new_parent_name}' {new_parent_classifier}"
+            )
+
+    def _get_artefact_rule(self, artefact) -> Optional[str]:
+        """Extract rule from artefact contribution if exists."""
+        if hasattr(artefact, "contribution") and artefact.contribution:
+            return getattr(artefact.contribution, "rule", None)
+        return None
+
+    def _update_children_to_new_classifier(
+        self,
+        artefact_name: str,
+        old_classifier: str,
+        new_classifier: str,
+        children: Dict[str, List],
+    ) -> bool:
+        """Update children's contribution to point to new classifier."""
+        print(
+            f"\n🔄 Updating children's contribution to new classifier '{new_classifier}'..."
+        )
+
+        # Save current directory and navigate to target
+        original_dir = self.file_system.getcwd()
+        try:
+            navigator = DirectoryNavigator()
+            navigator.navigate_to_target()
+
+            # Determine if new parent supports rules
+            supports_rules = new_classifier in ["epic", "userstory"]
+
+            for classifier, artefacts in children.items():
+                for artefact in artefacts:
+                    artefact_title = getattr(artefact, "title", "Unknown")
+
+                    # Get current rule if exists
+                    current_rule = None
+                    if hasattr(artefact, "contribution") and artefact.contribution:
+                        current_rule = getattr(artefact.contribution, "rule", None)
+
+                    # Clear rule if new parent doesn't support rules
+                    rule_to_set = current_rule if supports_rules else None
+
+                    if not supports_rules and current_rule:
+                        print(
+                            f"   ⚠️  Clearing rule '{current_rule}' for '{artefact_title}' (new parent doesn't support rules)"
+                        )
+
+                    artefact.set_contribution(
+                        artefact_name, new_classifier, rule_to_set
+                    )
+                    self._save_artefact(artefact, classifier)
+                    print(
+                        f"   ✓ '{artefact_title}' {classifier} contribution updated to '{new_classifier}'"
+                    )
+
+            print(f"\n✅ All children's contributions updated successfully.")
+            return True
+        finally:
+            # Restore original directory
+            self.file_system.chdir(original_dir)
+
+    def _save_artefact(self, artefact, classifier: str) -> None:
+        """Save artefact to file. Assumes navigate_to_target() was already called."""
+        sub_directory = Classifier.get_sub_directory(classifier)
+        artefact_title = getattr(artefact, "title", "Unknown")
+        file_path = self.file_system.path.join(
+            sub_directory, f"{artefact_title}.{classifier}"
+        )
+
+        content = artefact.serialize()
+
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(content)