solokit 0.1.1__py3-none-any.whl

solokit/core/constants.py

@@ -0,0 +1,291 @@
+"""
+Centralized constants and configuration values for Solokit
+
+This module contains all magic numbers, default values, paths, and
+configuration constants used throughout the Solokit codebase.
+"""
+
+from pathlib import Path
+from typing import Final
+
+# ============================================================================
+# Directory and Path Constants
+# ============================================================================
+
+# Session directory name
+SESSION_DIR_NAME: Final[str] = ".session"
+
+# Subdirectories within session directory
+TRACKING_DIR_NAME: Final[str] = "tracking"
+SPECS_DIR_NAME: Final[str] = "specs"
+CONFIG_DIR_NAME: Final[str] = "config"
+LEARNINGS_DIR_NAME: Final[str] = "learnings"
+BRIEFINGS_DIR_NAME: Final[str] = "briefings"
+STATUS_DIR_NAME: Final[str] = "status"
+
+# Tracking file names
+WORK_ITEMS_FILE: Final[str] = "work_items.json"
+LEARNINGS_FILE: Final[str] = "learnings.json"
+STATUS_UPDATE_FILE: Final[str] = "status_update.json"
+SESSIONS_FILE: Final[str] = "sessions.json"
+CONFIG_FILE: Final[str] = "config.json"
+
+# ============================================================================
+# Git Operation Timeouts (in seconds)
+# ============================================================================
+
+# Quick git operations (status, diff, log)
+GIT_QUICK_TIMEOUT: Final[int] = 5
+
+# Standard git operations (add, commit)
+GIT_STANDARD_TIMEOUT: Final[int] = 10
+
+# Long-running git operations (push, pull, clone)
+GIT_LONG_TIMEOUT: Final[int] = 30
+
+# ============================================================================
+# Learning Curator Constants
+# ============================================================================
+
+# Maximum age of learnings before archiving (in sessions)
+MAX_LEARNING_AGE_SESSIONS: Final[int] = 50
+
+# Auto-curation threshold (number of uncategorized learnings)
+AUTO_CURATE_THRESHOLD: Final[int] = 10
+
+# Similarity thresholds for learning deduplication
+JACCARD_SIMILARITY_THRESHOLD: Final[float] = 0.6
+CONTAINMENT_SIMILARITY_THRESHOLD: Final[float] = 0.8
+
+# Minimum similarity score for related learnings
+MIN_RELATED_SIMILARITY: Final[float] = 0.3
+
+# ============================================================================
+# Session and Briefing Constants
+# ============================================================================
+
+# Maximum spec keywords to display
+MAX_SPEC_KEYWORDS: Final[int] = 500
+
+# Maximum number of recent learnings to show in briefing
+MAX_RECENT_LEARNINGS: Final[int] = 10
+
+# Maximum number of recent commits to show
+MAX_RECENT_COMMITS: Final[int] = 20
+
+# Maximum work items to show in status
+MAX_STATUS_WORK_ITEMS: Final[int] = 15
+
+# ============================================================================
+# Quality Gate Constants
+# ============================================================================
+
+# Minimum test coverage percentage
+MIN_TEST_COVERAGE: Final[float] = 80.0
+
+# Maximum cyclomatic complexity per function
+MAX_CYCLOMATIC_COMPLEXITY: Final[int] = 10
+
+# Maximum line length
+MAX_LINE_LENGTH: Final[int] = 100
+
+# ============================================================================
+# Performance Testing Constants
+# ============================================================================
+
+# Default performance regression threshold (1.1 = 10% slower)
+PERFORMANCE_REGRESSION_THRESHOLD: Final[float] = 1.1
+
+# Performance test timeout
+PERFORMANCE_TEST_TIMEOUT: Final[int] = 10
+
+# Number of warmup runs for performance tests
+PERFORMANCE_WARMUP_RUNS: Final[int] = 3
+
+# Number of measurement runs for performance tests
+PERFORMANCE_MEASUREMENT_RUNS: Final[int] = 10
+
+# ============================================================================
+# API and HTTP Constants
+# ============================================================================
+
+# Default HTTP request timeout
+HTTP_REQUEST_TIMEOUT: Final[int] = 5
+
+# API endpoint timeout
+API_ENDPOINT_TIMEOUT: Final[int] = 10
+
+# ============================================================================
+# Work Item Constants
+# ============================================================================
+
+# Work item types
+WORK_ITEM_TYPES: Final[tuple[str, ...]] = (
+    "feature",
+    "bug",
+    "refactor",
+    "security",
+    "integration_test",
+    "deployment",
+)
+
+# Priority levels (in order from highest to lowest)
+PRIORITY_LEVELS: Final[tuple[str, ...]] = (
+    "critical",
+    "high",
+    "medium",
+    "low",
+)
+
+# Work item statuses
+WORK_ITEM_STATUSES: Final[tuple[str, ...]] = (
+    "not_started",
+    "in_progress",
+    "completed",
+    "blocked",
+)
+
+# Maximum work item ID length (for slug generation)
+MAX_WORK_ITEM_ID_LENGTH: Final[int] = 40
+
+# ============================================================================
+# CLI and User Interface Constants
+# ============================================================================
+
+# Minimum arguments for CLI commands
+MIN_CLI_ARGS: Final[int] = 1
+
+# Progress bar length
+PROGRESS_BAR_LENGTH: Final[int] = 20
+
+# ============================================================================
+# File Size and Limit Constants
+# ============================================================================
+
+# Maximum file size for parsing (in bytes) - 10MB
+MAX_FILE_SIZE_BYTES: Final[int] = 10 * 1024 * 1024
+
+# Maximum number of files to process in batch
+MAX_BATCH_FILE_COUNT: Final[int] = 100
+
+# ============================================================================
+# Subprocess and Process Constants
+# ============================================================================
+
+# Default subprocess timeout (for general operations)
+DEFAULT_SUBPROCESS_TIMEOUT: Final[int] = 10
+
+# Exit codes
+EXIT_SUCCESS: Final[int] = 0
+EXIT_FAILURE: Final[int] = 1
+
+# ============================================================================
+# Quality Gate Timeouts (in seconds)
+# ============================================================================
+
+# Quick quality checks (version checks, git operations)
+QUALITY_CHECK_QUICK_TIMEOUT: Final[int] = 5
+
+# Standard quality checks (linting, formatting)
+QUALITY_CHECK_STANDARD_TIMEOUT: Final[int] = 30
+
+# Long-running quality checks (formatting tools, complex linting)
+QUALITY_CHECK_LONG_TIMEOUT: Final[int] = 60
+
+# Very long quality checks (full formatting, security scans)
+QUALITY_CHECK_VERY_LONG_TIMEOUT: Final[int] = 120
+
+# Test runner timeout (20 minutes for full test suites)
+TEST_RUNNER_TIMEOUT: Final[int] = 1200
+
+# ============================================================================
+# Integration Testing Timeouts (in seconds)
+# ============================================================================
+
+# Docker command timeout (ps, version checks)
+DOCKER_COMMAND_TIMEOUT: Final[int] = 5
+
+# Docker compose up/down timeout
+DOCKER_COMPOSE_TIMEOUT: Final[int] = 180
+
+# Fixture setup timeout
+FIXTURE_SETUP_TIMEOUT: Final[int] = 30
+
+# Integration test execution timeout (10 minutes)
+INTEGRATION_TEST_TIMEOUT: Final[int] = 600
+
+# Cleanup operation timeout
+CLEANUP_TIMEOUT: Final[int] = 60
+
+# ============================================================================
+# Session and Workflow Timeouts (in seconds)
+# ============================================================================
+
+# Session status checks
+SESSION_STATUS_TIMEOUT: Final[int] = 5
+
+# Session completion operations
+SESSION_COMPLETE_TIMEOUT: Final[int] = 30
+
+# Learning extraction timeout
+LEARNING_EXTRACTION_TIMEOUT: Final[int] = 60
+
+# Briefing generation timeout
+BRIEFING_GENERATION_TIMEOUT: Final[int] = 30
+
+# ============================================================================
+# Project Initialization Timeouts (in seconds)
+# ============================================================================
+
+# Stack detection timeout (quick check)
+STACK_DETECTION_TIMEOUT: Final[int] = 2
+
+# Tree generation timeout
+TREE_GENERATION_TIMEOUT: Final[int] = 30
+
+# Dependency graph generation timeout
+DEPENDENCY_GRAPH_TIMEOUT: Final[int] = 30
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+
+def get_session_dir(project_root: Path) -> Path:
+    """Get the session directory path for a project"""
+    return project_root / SESSION_DIR_NAME
+
+
+def get_tracking_dir(project_root: Path) -> Path:
+    """Get the tracking directory path for a project"""
+    return get_session_dir(project_root) / TRACKING_DIR_NAME
+
+
+def get_specs_dir(project_root: Path) -> Path:
+    """Get the specs directory path for a project"""
+    return get_session_dir(project_root) / SPECS_DIR_NAME
+
+
+def get_briefings_dir(project_root: Path) -> Path:
+    """Get the briefings directory path for a project"""
+    return get_session_dir(project_root) / BRIEFINGS_DIR_NAME
+
+
+def get_status_dir(project_root: Path) -> Path:
+    """Get the status directory path for a project"""
+    return get_session_dir(project_root) / STATUS_DIR_NAME
+
+
+def get_work_items_file(project_root: Path) -> Path:
+    """Get the work items file path"""
+    return get_tracking_dir(project_root) / WORK_ITEMS_FILE
+
+
+def get_learnings_file(project_root: Path) -> Path:
+    """Get the learnings file path"""
+    return get_tracking_dir(project_root) / LEARNINGS_FILE
+
+
+def get_config_file(project_root: Path) -> Path:
+    """Get the config file path"""
+    return get_session_dir(project_root) / CONFIG_FILE

solokit/core/error_formatter.py

@@ -0,0 +1,279 @@
+"""
+Format exceptions for CLI display.
+
+Separates presentation concerns from business logic. Business logic raises
+structured exceptions, CLI layer formats them for user display.
+
+Usage:
+    from solokit.core.error_formatter import ErrorFormatter
+
+    try:
+        # Business logic
+        do_something()
+    except SolokitError as e:
+        ErrorFormatter.print_error(e, verbose=args.verbose)
+        sys.exit(e.exit_code)
+"""
+
+import sys
+from typing import Any, Optional
+
+from solokit.core.exceptions import ErrorCategory, SolokitError
+
+
+class ErrorFormatter:
+    """Format exceptions for CLI output"""
+
+    @staticmethod
+    def format_error(error: Exception, verbose: bool = False) -> str:
+        """
+        Format exception for display.
+
+        Args:
+            error: Exception to format
+            verbose: Include full context and stack trace
+
+        Returns:
+            Formatted error message
+
+        Example:
+            >>> from solokit.core.exceptions import WorkItemNotFoundError
+            >>> error = WorkItemNotFoundError("my_feature")
+            >>> print(ErrorFormatter.format_error(error))
+            🔍 Work item 'my_feature' not found
+            💡 Use 'sk work-list' to see available work items
+        """
+        if isinstance(error, SolokitError):
+            return ErrorFormatter._format_solokit_error(error, verbose)
+        else:
+            return ErrorFormatter._format_generic_error(error, verbose)
+
+    @staticmethod
+    def _format_solokit_error(error: SolokitError, verbose: bool) -> str:
+        """Format SolokitError with structured data"""
+        lines = []
+
+        # Error symbol based on category
+        symbol = ErrorFormatter._get_error_symbol(error.category)
+        lines.append(f"{symbol} {error.message}")
+
+        # Context (if verbose or critical info)
+        if verbose and error.context:
+            lines.append("\nContext:")
+            for key, value in error.context.items():
+                # Format lists and dicts nicely
+                if isinstance(value, list):
+                    lines.append(f"  {key}:")
+                    for item in value[:10]:  # Limit to 10 items
+                        lines.append(f"    - {item}")
+                    if len(value) > 10:
+                        lines.append(f"    ... and {len(value) - 10} more")
+                elif isinstance(value, dict):
+                    lines.append(f"  {key}:")
+                    for k, v in list(value.items())[:10]:
+                        lines.append(f"    {k}: {v}")
+                    if len(value) > 10:
+                        lines.append(f"    ... and {len(value) - 10} more items")
+                else:
+                    lines.append(f"  {key}: {value}")
+
+        # Remediation (always show if available)
+        if error.remediation:
+            lines.append(f"\n💡 {error.remediation}")
+
+        # Error code (if verbose)
+        if verbose:
+            lines.append(f"\nError Code: {error.code.name} ({error.code.value})")
+            lines.append(f"Category: {error.category.value}")
+
+        # Cause (if present)
+        if verbose and error.cause:
+            lines.append(f"\nCaused by: {error.cause}")
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def _format_generic_error(error: Exception, verbose: bool) -> str:
+        """Format generic exception"""
+        if verbose:
+            import traceback
+
+            return f"❌ {type(error).__name__}: {error}\n\n{traceback.format_exc()}"
+        else:
+            return f"❌ {type(error).__name__}: {error}"
+
+    @staticmethod
+    def _get_error_symbol(category: ErrorCategory) -> str:
+        """Get emoji symbol for error category"""
+        symbols = {
+            ErrorCategory.VALIDATION: "⚠️",
+            ErrorCategory.NOT_FOUND: "🔍",
+            ErrorCategory.CONFIGURATION: "⚙️",
+            ErrorCategory.SYSTEM: "💥",
+            ErrorCategory.GIT: "🔀",
+            ErrorCategory.DEPENDENCY: "🔗",
+            ErrorCategory.SECURITY: "🔒",
+            ErrorCategory.TIMEOUT: "⏱️",
+            ErrorCategory.ALREADY_EXISTS: "📋",
+            ErrorCategory.PERMISSION: "🔐",
+        }
+        return symbols.get(category, "❌")
+
+    @staticmethod
+    def print_error(error: Exception, verbose: bool = False, file: Any = None) -> None:
+        """
+        Print formatted error to stderr.
+
+        Args:
+            error: Exception to print
+            verbose: Include full context
+            file: Output stream (default: stderr)
+
+        Example:
+            >>> try:
+            ...     raise ValidationError("Invalid input")
+            ... except SolokitError as e:
+            ...     ErrorFormatter.print_error(e)
+        """
+        import logging
+
+        if file is None:
+            file = sys.stderr
+
+        formatted = ErrorFormatter.format_error(error, verbose)
+        logger = logging.getLogger(__name__)
+
+        try:
+            print(formatted, file=file)
+        except (ValueError, OSError) as e:
+            # Handle closed file (e.g., in tests with capsys)
+            logger.warning(f"Could not write to stderr: {e}, trying stdout")
+            try:
+                print(formatted, file=sys.stdout)
+            except (ValueError, OSError) as e2:
+                # Both are closed - log the error instead of silently suppressing
+                logger.error(f"Could not write error to stderr or stdout: {e2}")
+                logger.error(f"Original error message: {formatted}")
+
+    @staticmethod
+    def get_exit_code(error: Exception) -> int:
+        """
+        Get appropriate exit code for error.
+
+        Args:
+            error: Exception to get exit code for
+
+        Returns:
+            Exit code (0 for success, >0 for errors)
+
+        Example:
+            >>> from solokit.core.exceptions import ValidationError, ErrorCode
+            >>> error = ValidationError("test", code=ErrorCode.INVALID_WORK_ITEM_ID)
+            >>> ErrorFormatter.get_exit_code(error)
+            2
+        """
+        if isinstance(error, SolokitError):
+            return error.exit_code
+        else:
+            return 1  # Generic error
+
+
+def format_validation_errors(errors: list[str], header: Optional[str] = None) -> str:
+    """
+    Format a list of validation errors for display.
+
+    Args:
+        errors: List of error messages
+        header: Optional header to display before errors
+
+    Returns:
+        Formatted error message
+
+    Example:
+        >>> errors = ["Missing field 'name'", "Invalid value for 'age'"]
+        >>> print(format_validation_errors(errors, "Validation failed"))
+        ⚠️ Validation failed
+
+          1. Missing field 'name'
+          2. Invalid value for 'age'
+    """
+    lines = []
+
+    if header:
+        lines.append(f"⚠️ {header}")
+        lines.append("")
+
+    for i, error in enumerate(errors, 1):
+        lines.append(f"  {i}. {error}")
+
+    return "\n".join(lines)
+
+
+def format_progress_message(current: int, total: int, message: str) -> str:
+    """
+    Format a progress message with count.
+
+    Args:
+        current: Current item number
+        total: Total number of items
+        message: Progress message
+
+    Returns:
+        Formatted progress message
+
+    Example:
+        >>> print(format_progress_message(3, 10, "Processing files"))
+        [3/10] Processing files...
+    """
+    return f"[{current}/{total}] {message}..."
+
+
+def format_success_message(message: str) -> str:
+    """
+    Format a success message.
+
+    Args:
+        message: Success message
+
+    Returns:
+        Formatted success message with checkmark
+
+    Example:
+        >>> print(format_success_message("Work item created"))
+        ✅ Work item created
+    """
+    return f"✅ {message}"
+
+
+def format_warning_message(message: str) -> str:
+    """
+    Format a warning message.
+
+    Args:
+        message: Warning message
+
+    Returns:
+        Formatted warning message with icon
+
+    Example:
+        >>> print(format_warning_message("Config file not found, using defaults"))
+        ⚠️ Config file not found, using defaults
+    """
+    return f"⚠️ {message}"
+
+
+def format_info_message(message: str) -> str:
+    """
+    Format an info message.
+
+    Args:
+        message: Info message
+
+    Returns:
+        Formatted info message with icon
+
+    Example:
+        >>> print(format_info_message("Loading configuration"))
+        ℹ️ Loading configuration
+    """
+    return f"ℹ️ {message}"