specfact-cli 0.4.2__py3-none-any.whl

specfact_cli/utils/__init__.py

@@ -0,0 +1,58 @@
+"""
+SpecFact CLI utilities.
+
+This package contains utility functions for git operations,
+YAML processing, console output, and interactive prompts.
+"""
+
+from specfact_cli.utils.console import console, print_validation_report
+from specfact_cli.utils.feature_keys import (
+    convert_feature_keys,
+    find_feature_by_normalized_key,
+    normalize_feature_key,
+    to_classname_key,
+    to_sequential_key,
+    to_underscore_key,
+)
+from specfact_cli.utils.git import GitOperations
+from specfact_cli.utils.prompts import (
+    display_summary,
+    print_error,
+    print_info,
+    print_section,
+    print_success,
+    print_warning,
+    prompt_confirm,
+    prompt_dict,
+    prompt_list,
+    prompt_text,
+)
+from specfact_cli.utils.yaml_utils import YAMLUtils, dump_yaml, load_yaml, string_to_yaml, yaml_to_string
+
+
+__all__ = [
+    "GitOperations",
+    "YAMLUtils",
+    "console",
+    "convert_feature_keys",
+    "display_summary",
+    "dump_yaml",
+    "find_feature_by_normalized_key",
+    "load_yaml",
+    "normalize_feature_key",
+    "print_error",
+    "print_info",
+    "print_section",
+    "print_success",
+    "print_validation_report",
+    "print_warning",
+    "prompt_confirm",
+    "prompt_dict",
+    "prompt_list",
+    "prompt_text",
+    "string_to_yaml",
+    "to_classname_key",
+    "to_sequential_key",
+    "to_underscore_key",
+    "yaml_to_string",
+]

specfact_cli/utils/console.py

@@ -0,0 +1,70 @@
+"""
+Console output utilities.
+
+This module provides helpers for rich console output.
+"""
+
+from __future__ import annotations
+
+from beartype import beartype
+from icontract import require
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from specfact_cli.models.deviation import DeviationSeverity, ValidationReport
+
+
+# Shared console instance
+console = Console()
+
+
+@beartype
+@require(lambda report: isinstance(report, ValidationReport), "Report must be ValidationReport instance")
+def print_validation_report(report: ValidationReport) -> None:
+    """
+    Print a formatted validation report.
+
+    Args:
+        report: Validation report to print
+    """
+    # Create summary table
+    table = Table(title="Validation Summary")
+    table.add_column("Severity", style="cyan")
+    table.add_column("Count", justify="right")
+
+    if report.high_count > 0:
+        table.add_row("HIGH", str(report.high_count), style="bold red")
+    if report.medium_count > 0:
+        table.add_row("MEDIUM", str(report.medium_count), style="yellow")
+    if report.low_count > 0:
+        table.add_row("LOW", str(report.low_count), style="blue")
+
+    console.print(table)
+
+    # Print deviations
+    if report.deviations:
+        console.print("\n[bold]Deviations:[/bold]\n")
+
+        for i, deviation in enumerate(report.deviations, 1):
+            severity_color = {
+                DeviationSeverity.HIGH: "bold red",
+                DeviationSeverity.MEDIUM: "yellow",
+                DeviationSeverity.LOW: "blue",
+            }[deviation.severity]
+
+            console.print(f"[{severity_color}]{i}. [{deviation.severity}][/{severity_color}] {deviation.description}")
+
+            if deviation.location:
+                console.print(f"   [dim]Location: {deviation.location}[/dim]")
+
+            if hasattr(deviation, "fix_hint") and deviation.fix_hint:
+                console.print(f"   [green]→ Suggestion: {deviation.fix_hint}[/green]")
+
+            console.print()
+
+    # Print overall result
+    if report.passed:
+        console.print(Panel("[bold green]✓ Validation PASSED[/bold green]", border_style="green"))
+    else:
+        console.print(Panel("[bold red]✗ Validation FAILED[/bold red]", border_style="red"))

specfact_cli/utils/feature_keys.py

@@ -0,0 +1,212 @@
+"""
+Feature key normalization and conversion utilities.
+
+Provides functions to normalize feature keys across different formats
+to enable consistent comparison and merging of plans.
+"""
+
+import re
+from typing import Any
+
+from beartype import beartype
+
+
+@beartype
+def normalize_feature_key(key: str) -> str:
+    """
+    Normalize feature keys for comparison by removing prefixes and underscores.
+
+    Converts various formats to a canonical form:
+    - `000_CONTRACT_FIRST_TEST_MANAGER` -> `CONTRACTFIRSTTESTMANAGER`
+    - `FEATURE-CONTRACTFIRSTTESTMANAGER` -> `CONTRACTFIRSTTESTMANAGER`
+    - `FEATURE-001` -> `001`
+    - `CONTRACT_FIRST_TEST_MANAGER` -> `CONTRACTFIRSTTESTMANAGER`
+
+    Args:
+        key: Feature key in any format
+
+    Returns:
+        Normalized key (uppercase, no prefixes, no underscores)
+
+    Examples:
+        >>> normalize_feature_key("000_CONTRACT_FIRST_TEST_MANAGER")
+        'CONTRACTFIRSTTESTMANAGER'
+        >>> normalize_feature_key("FEATURE-CONTRACTFIRSTTESTMANAGER")
+        'CONTRACTFIRSTTESTMANAGER'
+        >>> normalize_feature_key("FEATURE-001")
+        '001'
+    """
+    # Remove common prefixes
+    key = key.replace("FEATURE-", "").replace("000_", "").replace("001_", "")
+
+    # Remove underscores and spaces, convert to uppercase
+    return re.sub(r"[_\s-]", "", key).upper()
+
+
+@beartype
+def to_sequential_key(key: str, index: int) -> str:
+    """
+    Convert any feature key to sequential format (FEATURE-001, FEATURE-002, ...).
+
+    Args:
+        key: Original feature key
+        index: Sequential index (1-based)
+
+    Returns:
+        Sequential feature key (e.g., FEATURE-001)
+
+    Examples:
+        >>> to_sequential_key("000_CONTRACT_FIRST_TEST_MANAGER", 1)
+        'FEATURE-001'
+        >>> to_sequential_key("FEATURE-CONTRACTFIRSTTESTMANAGER", 5)
+        'FEATURE-005'
+    """
+    return f"FEATURE-{index:03d}"
+
+
+@beartype
+def to_classname_key(class_name: str) -> str:
+    """
+    Convert class name to feature key format (FEATURE-CLASSNAME).
+
+    Args:
+        class_name: Class name (e.g., ContractFirstTestManager)
+
+    Returns:
+        Feature key (e.g., FEATURE-CONTRACTFIRSTTESTMANAGER)
+
+    Examples:
+        >>> to_classname_key("ContractFirstTestManager")
+        'FEATURE-CONTRACTFIRSTTESTMANAGER'
+        >>> to_classname_key("CodeAnalyzer")
+        'FEATURE-CODEANALYZER'
+    """
+    return f"FEATURE-{class_name.upper()}"
+
+
+@beartype
+def to_underscore_key(title: str, prefix: str = "000") -> str:
+    """
+    Convert feature title to underscore format (000_FEATURE_NAME).
+
+    Args:
+        title: Feature title (e.g., "Contract First Test Manager")
+        prefix: Prefix to use (default: "000")
+
+    Returns:
+        Feature key (e.g., 000_CONTRACT_FIRST_TEST_MANAGER)
+
+    Examples:
+        >>> to_underscore_key("Contract First Test Manager")
+        '000_CONTRACT_FIRST_TEST_MANAGER'
+        >>> to_underscore_key("User Authentication", "001")
+        '001_USER_AUTHENTICATION'
+    """
+    # Convert title to uppercase and replace spaces with underscores
+    key = title.upper().replace(" ", "_")
+
+    return f"{prefix}_{key}"
+
+
+@beartype
+def find_feature_by_normalized_key(features: list, target_key: str) -> dict | None:
+    """
+    Find a feature in a list by matching normalized keys.
+
+    Useful for comparing features across plans with different key formats.
+
+    Args:
+        features: List of feature dictionaries with 'key' field
+        target_key: Target key to find (will be normalized)
+
+    Returns:
+        Feature dictionary if found, None otherwise
+
+    Examples:
+        >>> features = [{"key": "000_CONTRACT_FIRST_TEST_MANAGER", "title": "..."}]
+        >>> find_feature_by_normalized_key(features, "FEATURE-CONTRACTFIRSTTESTMANAGER")
+        {'key': '000_CONTRACT_FIRST_TEST_MANAGER', 'title': '...'}
+    """
+    target_normalized = normalize_feature_key(target_key)
+
+    for feature in features:
+        if "key" not in feature:
+            continue
+
+        feature_normalized = normalize_feature_key(feature["key"])
+        if feature_normalized == target_normalized:
+            return feature
+
+    return None
+
+
+@beartype
+def convert_feature_keys(features: list, target_format: str = "sequential", start_index: int = 1) -> list:
+    """
+    Convert feature keys to a consistent format.
+
+    Args:
+        features: List of feature dictionaries with 'key' field
+        target_format: Target format ('sequential', 'classname', or 'underscore')
+        start_index: Starting index for sequential format (default: 1)
+
+    Returns:
+        List of features with converted keys
+
+    Examples:
+        >>> features = [{"key": "000_CONTRACT_FIRST_TEST_MANAGER", "title": "Contract First Test Manager"}]
+        >>> convert_feature_keys(features, "sequential")
+        [{'key': 'FEATURE-001', 'title': 'Contract First Test Manager', ...}]
+    """
+    converted: list[dict[str, Any]] = []
+    current_index = start_index
+
+    for feature in features:
+        if "key" not in feature:
+            continue
+
+        original_key = feature["key"]
+        title = feature.get("title", "")
+
+        if target_format == "sequential":
+            new_key = to_sequential_key(original_key, current_index)
+            current_index += 1
+        elif target_format == "classname":
+            # Extract class name from original key if possible
+            class_name = _extract_class_name(original_key, title)
+            new_key = to_classname_key(class_name)
+        elif target_format == "underscore":
+            prefix = str(current_index - 1).zfill(3)
+            new_key = to_underscore_key(title, prefix)
+            current_index += 1
+        else:
+            # Keep original key if format not recognized
+            new_key = original_key
+
+        new_feature = feature.copy()
+        new_feature["key"] = new_key
+        converted.append(new_feature)
+
+    return converted
+
+
+def _extract_class_name(key: str, title: str) -> str:
+    """Extract class name from feature key or title."""
+    # Try to extract from key first
+    if "FEATURE-" in key:
+        class_part = key.replace("FEATURE-", "")
+        # Convert to PascalCase if needed
+        if "_" in class_part or "-" in class_part:
+            # Convert underscore/hyphen to PascalCase
+            parts = re.split(r"[_-]", class_part.lower())
+            return "".join(word.capitalize() for word in parts)
+        # Already class-like (uppercase), convert to PascalCase
+        return class_part.title()
+
+    # Fall back to title
+    if title:
+        # Convert title to PascalCase class name
+        parts = re.split(r"[_\s-]", title)
+        return "".join(word.capitalize() for word in parts)
+
+    return "UnknownClass"

specfact_cli/utils/git.py

@@ -0,0 +1,241 @@
+"""
+Git operations utilities.
+
+This module provides helpers for common Git operations used by the CLI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import git
+from beartype import beartype
+from git import Repo
+from icontract import ensure, require
+
+
+class GitOperations:
+    """Helper class for Git operations."""
+
+    @beartype
+    @require(lambda repo_path: isinstance(repo_path, (Path, str)), "Repo path must be Path or str")
+    def __init__(self, repo_path: Path | str = ".") -> None:
+        """
+        Initialize Git operations.
+
+        Args:
+            repo_path: Path to the Git repository
+        """
+        self.repo_path = Path(repo_path)
+        self.repo: Repo | None = None
+
+        if self._is_git_repo():
+            self.repo = Repo(self.repo_path)
+
+    def _is_git_repo(self) -> bool:
+        """
+        Check if path is a Git repository.
+
+        Returns:
+            True if path is a Git repository
+        """
+        try:
+            _ = Repo(self.repo_path)
+            return True
+        except git.exc.InvalidGitRepositoryError:
+            return False
+
+    def init(self) -> None:
+        """Initialize a new Git repository."""
+        self.repo = Repo.init(self.repo_path)
+
+    @beartype
+    @require(
+        lambda branch_name: isinstance(branch_name, str) and len(branch_name) > 0,
+        "Branch name must be non-empty string",
+    )
+    @require(lambda self: self.repo is not None, "Git repository must be initialized")
+    def create_branch(self, branch_name: str, checkout: bool = True) -> None:
+        """
+        Create a new branch.
+
+        Args:
+            branch_name: Name of the new branch
+            checkout: Whether to checkout the new branch
+
+        Raises:
+            ValueError: If repository is not initialized
+        """
+        if self.repo is None:
+            raise ValueError("Git repository not initialized")
+
+        new_branch = self.repo.create_head(branch_name)
+        if checkout:
+            new_branch.checkout()
+
+    @beartype
+    @require(
+        lambda branch_name: isinstance(branch_name, str) and len(branch_name) > 0,
+        "Branch name must be non-empty string",
+    )
+    @require(lambda self: self.repo is not None, "Git repository must be initialized")
+    def checkout(self, branch_name: str) -> None:
+        """
+        Checkout an existing branch.
+
+        Args:
+            branch_name: Name of the branch to checkout
+
+        Raises:
+            ValueError: If repository is not initialized
+        """
+        if self.repo is None:
+            raise ValueError("Git repository not initialized")
+
+        self.repo.heads[branch_name].checkout()
+
+    @beartype
+    @require(lambda files: isinstance(files, (list, Path, str)), "Files must be list, Path, or str")
+    @require(lambda self: self.repo is not None, "Git repository must be initialized")
+    def add(self, files: list[Path | str] | Path | str) -> None:
+        """
+        Add files to the staging area.
+
+        Args:
+            files: File(s) to add
+
+        Raises:
+            ValueError: If repository is not initialized
+        """
+        if self.repo is None:
+            raise ValueError("Git repository not initialized")
+
+        if isinstance(files, (Path, str)):
+            files = [files]
+
+        for file_path in files:
+            self.repo.index.add([str(file_path)])
+
+    @beartype
+    @require(lambda message: isinstance(message, str) and len(message) > 0, "Commit message must be non-empty string")
+    @require(lambda self: self.repo is not None, "Git repository must be initialized")
+    @ensure(lambda result: result is not None, "Must return commit object")
+    def commit(self, message: str) -> Any:
+        """
+        Commit staged changes.
+
+        Args:
+            message: Commit message
+
+        Returns:
+            Commit object
+
+        Raises:
+            ValueError: If repository is not initialized
+        """
+        if self.repo is None:
+            raise ValueError("Git repository not initialized")
+
+        return self.repo.index.commit(message)
+
+    @beartype
+    @require(lambda remote: isinstance(remote, str) and len(remote) > 0, "Remote name must be non-empty string")
+    @require(
+        lambda branch: branch is None or (isinstance(branch, str) and len(branch) > 0),
+        "Branch name must be None or non-empty string",
+    )
+    @require(lambda self: self.repo is not None, "Git repository must be initialized")
+    def push(self, remote: str = "origin", branch: str | None = None) -> None:
+        """
+        Push commits to remote repository.
+
+        Args:
+            remote: Remote name (default: origin)
+            branch: Branch name (default: current branch)
+
+        Raises:
+            ValueError: If repository is not initialized
+        """
+        if self.repo is None:
+            raise ValueError("Git repository not initialized")
+
+        if branch is None:
+            branch = self.repo.active_branch.name
+
+        origin = self.repo.remote(name=remote)
+        origin.push(branch)
+
+    @beartype
+    @require(lambda self: self.repo is not None, "Git repository must be initialized")
+    @ensure(lambda result: isinstance(result, str) and len(result) > 0, "Must return non-empty branch name")
+    def get_current_branch(self) -> str:
+        """
+        Get the name of the current branch.
+
+        Returns:
+            Current branch name
+
+        Raises:
+            ValueError: If repository is not initialized
+        """
+        if self.repo is None:
+            raise ValueError("Git repository not initialized")
+
+        return self.repo.active_branch.name
+
+    @beartype
+    @require(lambda self: self.repo is not None, "Git repository must be initialized")
+    @ensure(lambda result: isinstance(result, list), "Must return list")
+    @ensure(lambda result: all(isinstance(b, str) for b in result), "All items must be strings")
+    def list_branches(self) -> list[str]:
+        """
+        List all branches.
+
+        Returns:
+            List of branch names
+
+        Raises:
+            ValueError: If repository is not initialized
+        """
+        if self.repo is None:
+            raise ValueError("Git repository not initialized")
+
+        return [str(head) for head in self.repo.heads]
+
+    @beartype
+    @require(lambda self: self.repo is not None, "Git repository must be initialized")
+    @ensure(lambda result: isinstance(result, bool), "Must return boolean")
+    def is_clean(self) -> bool:
+        """
+        Check if the working directory is clean.
+
+        Returns:
+            True if working directory is clean
+
+        Raises:
+            ValueError: If repository is not initialized
+        """
+        if self.repo is None:
+            raise ValueError("Git repository not initialized")
+
+        return not self.repo.is_dirty()
+
+    @beartype
+    @require(lambda self: self.repo is not None, "Git repository must be initialized")
+    @ensure(lambda result: isinstance(result, list), "Must return list")
+    @ensure(lambda result: all(isinstance(f, str) for f in result), "All items must be strings")
+    def get_changed_files(self) -> list[str]:
+        """
+        Get list of changed files.
+
+        Returns:
+            List of changed file paths
+
+        Raises:
+            ValueError: If repository is not initialized
+        """
+        if self.repo is None:
+            raise ValueError("Git repository not initialized")
+
+        return [item.a_path for item in self.repo.index.diff(None) if item.a_path is not None]