siada-cli 0.0.1__py3-none-any.whl

siada/support/spinner.py

@@ -0,0 +1,320 @@
+#!/usr/bin/env python
+
+"""
+Thread-based, killable spinner utility with beautiful animations and colors.
+
+Features:
+- Unicode braille patterns for smooth animation
+- Color support with automatic terminal detection
+- Graceful fallback to ASCII for limited terminals
+- Thread-safe operation
+
+Use it like:
+
+    from siada.support.spinner import WaitingSpinner
+
+    spinner = WaitingSpinner("Waiting for LLM")
+    spinner.start()
+    ...  # long task
+    spinner.stop()
+    
+Or as a context manager:
+
+    with WaitingSpinner("Processing...") as spinner:
+        # long task
+        pass
+"""
+
+import os
+import sys
+import threading
+import time
+
+from rich.console import Console
+from rich.text import Text
+
+
+class Spinner:
+    """
+    Modern, colorful spinner with smooth unicode animations.
+
+    Features:
+    - Uses unicode braille patterns for smooth, professional animation
+    - Automatic color detection and beautiful color cycling
+    - Graceful fallback to ASCII for limited terminals
+    - Optimized rendering with Rich console integration
+    """
+
+    last_frame_idx = 0  # Class variable to store the last frame index
+
+    def __init__(self, text: str, text_color: str = "bright_white"):
+        self.text = text
+        self.text_color = text_color
+        self.start_time = time.time()
+        self.last_update = 0.0
+        self.visible = False
+        self.is_tty = sys.stdout.isatty()
+        self.console = Console()
+        self.use_colors = self._supports_colors()
+
+        # Modern spinner patterns with better visual appeal
+        if self._supports_unicode() and self.use_colors:
+            # Beautiful unicode spinner with colors
+            self.frames = [
+                "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"
+            ]
+            self.colors = ["cyan", "bright_cyan", "blue", "bright_blue", "magenta", "bright_magenta"]
+            self.scan_char = "⠋"
+        elif self._supports_unicode():
+            # Unicode without colors
+            self.frames = [
+                "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"
+            ]
+            self.colors = None
+            self.scan_char = "⠋"
+        else:
+            # Fallback to ASCII with improved pattern
+            self.frames = [
+                "|", "/", "-", "\\", "|", "/", "-", "\\"
+            ]
+            self.colors = None
+            self.scan_char = "|"
+
+        self.frame_idx = Spinner.last_frame_idx  # Initialize from class variable
+        self.animation_len = 1  # Single character spinner
+        self.last_display_len = 0  # Length of the last spinner line (frame + text)
+
+    def _supports_unicode(self) -> bool:
+        """Check if terminal supports unicode without side effects."""
+        if not self.is_tty:
+            return False
+        try:
+            # Test encoding capability without actually writing to stdout
+            test_char = "⠋"
+            test_char.encode(sys.stdout.encoding or 'utf-8')
+            return True
+        except (UnicodeEncodeError, AttributeError, LookupError):
+            return False
+        except Exception:
+            return False
+
+    def _supports_colors(self) -> bool:
+        """Check if terminal supports colors"""
+        if not self.is_tty:
+            return False
+        # Check environment variables that indicate color support
+        term = os.environ.get('TERM', '').lower()
+        colorterm = os.environ.get('COLORTERM', '').lower()
+        return (
+            'color' in term or 
+            term in ('xterm', 'xterm-256color', 'screen', 'tmux') or
+            colorterm in ('truecolor', '24bit') or
+            hasattr(sys.stdout, 'isatty') and sys.stdout.isatty()
+        )
+
+    def _next_frame(self) -> str:
+        """Get the next frame without applying colors (colors applied in step method)."""
+        frame = self.frames[self.frame_idx]
+        self.frame_idx = (self.frame_idx + 1) % len(self.frames)
+        Spinner.last_frame_idx = self.frame_idx  # Update class variable
+        return frame
+    
+    def _get_current_color(self) -> str:
+        """Get the current color for the spinner frame."""
+        if self.use_colors and self.colors:
+            return self.colors[self.frame_idx % len(self.colors)]
+        return "white"
+    
+    def set_text_color(self, color: str):
+        """Set the color for the spinner text."""
+        self.text_color = color
+    
+    def set_text(self, text: str, color: str = None):
+        """Set the spinner text and optionally change its color."""
+        self.text = text
+        if color is not None:
+            self.text_color = color
+
+    def step(self, text: str = None) -> None:
+        """Update the spinner animation and optionally change the text."""
+        if text is not None:
+            self.text = text
+
+        if not self.is_tty:
+            return
+
+        try:
+            now = time.time()
+            if not self.visible and now - self.start_time >= 0.5:
+                self.visible = True
+                self.last_update = 0.0
+                if self.is_tty:
+                    self.console.show_cursor(False)
+
+            if not self.visible or now - self.last_update < 0.1:
+                return
+
+            self.last_update = now
+            frame_str = self._next_frame()
+        except Exception:
+            # If anything goes wrong, just skip this frame
+            return
+
+        # Create the spinner line with consistent formatting
+        if self.use_colors and self.colors:
+            # For colored output, use rich text formatting
+            current_color = self._get_current_color()
+            text_content = Text()
+            text_content.append(frame_str, style=f"bold {current_color}")
+            text_content.append(f" {self.text}", style=self.text_color)
+            
+            # Clear the line and print with rich
+            sys.stdout.write("\r")
+            with self.console.capture() as capture:
+                self.console.print(text_content, end="")
+            output = capture.get()
+            sys.stdout.write(output)
+            self.last_display_len = len(frame_str) + 1 + len(self.text)  # Approximate length
+        else:
+            # Simple output for terminals without color support
+            line_to_display = f"{frame_str} {self.text}"
+            
+            # Determine the maximum width for the spinner line
+            max_spinner_width = self.console.width - 2 if self.console.width > 2 else 0
+            if max_spinner_width > 0 and len(line_to_display) > max_spinner_width:
+                line_to_display = line_to_display[:max_spinner_width]
+
+            # Calculate padding to clear any remnants from a longer previous line
+            padding_to_clear = " " * max(0, self.last_display_len - len(line_to_display))
+
+            # Write the spinner frame and text
+            sys.stdout.write(f"\r{line_to_display}{padding_to_clear}")
+            self.last_display_len = len(line_to_display)
+
+        sys.stdout.flush()
+
+    def end(self) -> None:
+        """Stop the spinner and clean up the display."""
+        try:
+            if self.visible and self.is_tty:
+                # Clear the current line more reliably
+                sys.stdout.write("\r\033[K")  # \033[K clears from cursor to end of line
+                sys.stdout.flush()
+                self.console.show_cursor(True)
+        except Exception:
+            # If cleanup fails, just continue - better than crashing
+            pass
+        finally:
+            self.visible = False
+
+
+class WaitingSpinner:
+    """Background spinner that can be started/stopped safely and restarted."""
+
+    def __init__(self, text: str = "Waiting for LLM", delay: float = 0.15, text_color: str = "bright_cyan"):
+        self.text = text
+        self.text_color = text_color
+        self.delay = delay
+        self.spinner = None
+        self._stop_event = None
+        self._thread = None
+
+    def _spin(self):
+        """Internal spinning loop."""
+        if self.spinner is None:
+            return
+        while not self._stop_event.is_set():
+            self.spinner.step()
+            time.sleep(self.delay)
+        self.spinner.end()
+
+    def start(self):
+        """Start the spinner in a background thread."""
+        if self._thread is not None and self._thread.is_alive():
+            return  # Already running
+            
+        # Create fresh instances for restart capability
+        self.spinner = Spinner(self.text, self.text_color)
+        self._stop_event = threading.Event()
+        self._thread = threading.Thread(target=self._spin, daemon=True)
+        self._thread.start()
+
+    def stop(self):
+        """Request the spinner to stop and wait briefly for the thread to exit."""
+        if self._stop_event is not None:
+            self._stop_event.set()
+        if self._thread is not None and self._thread.is_alive():
+            self._thread.join(timeout=self.delay * 2)  # Give more time for cleanup
+        if self.spinner is not None:
+            self.spinner.end()
+            
+    def update_text(self, text: str, color: str = None):
+        """Update the spinner text dynamically and optionally change its color."""
+        self.text = text
+        if color is not None:
+            self.text_color = color
+        if self.spinner is not None:
+            if color is not None:
+                self.spinner.set_text(text, color)
+            else:
+                self.spinner.text = text
+    
+    def set_text_color(self, color: str):
+        """Set the color for the spinner text."""
+        self.text_color = color
+        if self.spinner is not None:
+            self.spinner.set_text_color(color)
+
+    # Allow use as a context-manager
+    def __enter__(self):
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.stop()
+
+
+def main():
+    """Demo the improved spinner with colors and unicode."""
+    print("🎨 Testing the colorful spinner...")
+    print("Press Ctrl+C to stop")
+    
+    # Test the basic Spinner with different text colors
+    print("\n🔸 Testing basic Spinner with color changes...")
+    spinner = Spinner("Starting with white text...", "bright_white")
+    try:
+        for i in range(100):
+            time.sleep(0.1)
+            if i == 20:
+                spinner.set_text("Now in green! 🟢", "bright_green")
+            elif i == 40:
+                spinner.set_text("Switching to red! 🔴", "bright_red")
+            elif i == 60:
+                spinner.set_text("Beautiful blue! 🔵", "bright_blue")
+            elif i == 80:
+                spinner.set_text("Magnificent magenta! 🟣", "bright_magenta")
+            else:
+                spinner.step()
+        spinner.end()
+        print("✅ Color-changing spinner test completed!")
+        
+        # Test the WaitingSpinner with color changes
+        print("\n🔸 Testing WaitingSpinner with dynamic colors...")
+        with WaitingSpinner("Starting in cyan...", text_color="bright_cyan") as waiting_spinner:
+            time.sleep(1)
+            waiting_spinner.update_text("Now in yellow! ⚡", "bright_yellow")
+            time.sleep(1)
+            waiting_spinner.set_text_color("bright_red")
+            waiting_spinner.update_text("Finishing in red! 🚀")
+            time.sleep(1)
+        
+        print("✅ All colorful tests completed successfully! 🌈")
+        
+    except KeyboardInterrupt:
+        print("\n❌ Interrupted by user.")
+    finally:
+        spinner.end()
+
+
+if __name__ == "__main__":
+    main()

siada/tools/ast/README.md

@@ -0,0 +1,345 @@
+# AST Code Definition Extraction Tool
+
+This module provides code definition extraction functionality based on tree-sitter and pygments, primarily used for analyzing source code files and extracting function, class, method, and other definition information.
+
+## Main Features
+
+### `_list_code_definition_names(fname, rel_fname=None)`
+
+Parses a source code file and returns a summary of its code definitions.
+
+#### Parameters
+- `fname` (str): Absolute path to the source file
+- `rel_fname` (str, optional): Relative path to the source file, defaults to filename
+
+#### Returns
+- `str`: Formatted string containing file structure and code definitions
+
+## Parsing Principles
+
+### 1. Dual Parsing Strategy
+- **Primary Parser**: Uses tree-sitter for syntax tree parsing, providing precise code structure analysis
+- **Fallback Parser**: Uses pygments for lexical analysis as a backup for reference extraction
+
+### 2. Parsing Workflow
+1. **Language Detection**: Identifies programming language based on file extension
+2. **Syntax Parsing**: Uses tree-sitter to build Abstract Syntax Tree (AST)
+3. **Query Execution**: Runs predefined query patterns to extract definitions and references
+4. **Fallback Processing**: Uses pygments to supplement reference information if only definitions are found
+5. **Format Output**: Uses TreeContext to generate code tree structure with context
+
+### 3. Core Components
+- **Tag Model**: Data structure representing code identifiers
+- **TreeContext**: Provides code context and formatting functionality
+- **Query Files**: .scm files stored in `siada/queries/` directory, defining parsing rules for each language
+
+## Supported Programming Languages
+
+Based on tree-sitter language support, including but not limited to:
+
+### Fully Supported Languages
+- **Python** (.py) - functions, classes, methods, decorators, async functions, etc.
+- **JavaScript** (.js) - functions, classes, arrow functions, object methods, etc.
+- **TypeScript** (.ts) - type definitions, interfaces, classes, functions, etc.
+- **Java** (.java) - classes, methods, interfaces, enums, etc.
+- **C/C++** (.c, .cpp, .h, .hpp) - functions, structs, classes, etc.
+- **Go** (.go) - functions, structs, methods, interfaces, etc.
+- **Rust** (.rs) - functions, structs, traits, impl, etc.
+- **Ruby** (.rb) - classes, methods, modules, etc.
+
+### Partially Supported Languages
+- **C#** (.cs) - classes, methods, properties, etc.
+- **PHP** (.php) - classes, functions, methods, etc.
+- **Scala** (.scala) - classes, objects, traits, methods, etc.
+- **Kotlin** (.kt) - classes, functions, objects, etc.
+
+### Query File Locations
+- `siada/queries/tree-sitter-language-pack/` - Primary query files
+- `siada/queries/tree-sitter-languages/` - Fallback query files
+
+## Output Formats
+
+### 1. Standard Format (when definitions exist)
+```
+File: <filename>
+Definitions: <definition_count>, References: <reference_count>
+
+<code_tree_structure>
+```
+
+### 2. Simplified Format (fallback mode)
+```
+File: <filename>
+Definitions: <definition_count>, References: <reference_count>
+
+Definitions found:
+  - <definition_name> (line <line_number>)
+  - <definition_name> (line <line_number>)
+  ...
+```
+
+### 3. Error Format (no definitions or errors)
+```
+No code definitions found in <filename>
+```
+
+## Output Examples
+
+### Python File Example
+
+**Input File** (`calculator.py`):
+```python
+"""A simple calculator module with multiple classes and functions."""
+
+class Calculator:
+    """Basic calculator with arithmetic operations."""
+    
+    def __init__(self):
+        self.history = []
+    
+    def add(self, a, b):
+        result = a + b
+        self.history.append(f"{a} + {b} = {result}")
+        return result
+    
+    def multiply(self, a, b):
+        result = a * b
+        self.history.append(f"{a} * {b} = {result}")
+        return result
+
+class ScientificCalculator(Calculator):
+    """Extended calculator with scientific functions."""
+    
+    def power(self, base, exponent):
+        result = base ** exponent
+        self.history.append(f"{base} ^ {exponent} = {result}")
+        return result
+
+def create_calculator(scientific=False):
+    """Factory function to create calculator instances."""
+    if scientific:
+        return ScientificCalculator()
+    return Calculator()
+
+# Global configuration
+DEFAULT_PRECISION = 2
+```
+
+**Parsed Output**:
+```
+File: calculator.py
+Definitions: 6, References: 15
+
+⋮
+│class Calculator:
+│    """Basic calculator with arithmetic operations."""
+│
+│    def __init__(self):
+⋮
+│    def add(self, a, b):
+⋮
+│    def multiply(self, a, b):
+⋮
+│class ScientificCalculator(Calculator):
+│    """Extended calculator with scientific functions."""
+│
+│    def power(self, base, exponent):
+⋮
+│def create_calculator(scientific=False):
+⋮
+```
+
+**Key Differences from Source**:
+- Shows only definition signatures, omitting implementation details
+- Displays statistical summary (6 definitions, 15 references)
+- Uses `⋮` to indicate omitted code sections
+- Focuses on structural overview rather than complete code
+
+### JavaScript File Example
+
+**Input File** (`user-manager.js`):
+```javascript
+/**
+ * User management system with authentication
+ */
+
+class User {
+    constructor(username, email) {
+        this.username = username;
+        this.email = email;
+        this.isActive = true;
+    }
+    
+    activate() {
+        this.isActive = true;
+        console.log(`User ${this.username} activated`);
+    }
+    
+    deactivate() {
+        this.isActive = false;
+        console.log(`User ${this.username} deactivated`);
+    }
+}
+
+class UserManager {
+    constructor() {
+        this.users = new Map();
+    }
+    
+    addUser(username, email) {
+        const user = new User(username, email);
+        this.users.set(username, user);
+        return user;
+    }
+    
+    static getInstance() {
+        if (!UserManager.instance) {
+            UserManager.instance = new UserManager();
+        }
+        return UserManager.instance;
+    }
+}
+
+const authService = {
+    login: function(username, password) {
+        // Authentication logic here
+        return true;
+    },
+    
+    logout: (username) => {
+        // Logout logic here
+        console.log(`${username} logged out`);
+    }
+};
+
+async function initializeSystem() {
+    const manager = UserManager.getInstance();
+    return manager;
+}
+```
+
+**Parsed Output**:
+```
+File: user-manager.js
+Definitions: 9, References: 8
+
+⋮
+│class User {
+│    constructor(username, email) {
+│        this.username = username;
+│        this.email = email;
+│        this.isActive = true;
+│    }
+│
+│    activate() {
+⋮
+│    deactivate() {
+⋮
+│class UserManager {
+│    constructor() {
+│        this.users = new Map();
+│    }
+│
+│    addUser(username, email) {
+⋮
+│    static getInstance() {
+⋮
+│const authService = {
+│    login: function(username, password) {
+⋮
+│    logout: (username) => {
+⋮
+│async function initializeSystem() {
+⋮
+```
+
+**Key Differences from Source**:
+- Extracts 9 definitions (classes, methods, functions, object properties)
+- Counts 8 references to other identifiers
+- Omits implementation details and comments
+- Shows structural hierarchy and method signatures
+
+### Empty or Unsupported File Example
+
+**Output**:
+```
+No code definitions found in empty_file.py
+```
+
+## Usage Examples
+
+### Basic Usage
+```python
+from siada.tools.ast.ast_tool import _list_code_definition_names
+
+# Analyze Python file
+result = _list_code_definition_names("/path/to/file.py")
+print(result)
+
+# Specify relative path
+result = _list_code_definition_names("/absolute/path/to/file.py", "src/file.py")
+print(result)
+```
+
+### Batch Processing
+```python
+import os
+from pathlib import Path
+
+def analyze_project(project_dir):
+    """Analyze all Python files in a project"""
+    for py_file in Path(project_dir).rglob("*.py"):
+        rel_path = py_file.relative_to(project_dir)
+        result = _list_code_definition_names(str(py_file), str(rel_path))
+        print(f"\n{'='*50}")
+        print(result)
+
+# Usage example
+analyze_project("/path/to/your/project")
+```
+
+### Error Handling
+```python
+def safe_analyze(file_path):
+    """Safely analyze file with error handling"""
+    try:
+        result = _list_code_definition_names(file_path)
+        if "No code definitions found" in result:
+            print(f"No definitions found in {file_path}")
+        else:
+            print(result)
+    except Exception as e:
+        print(f"Error analyzing {file_path}: {e}")
+```
+
+## Technical Details
+
+### Dependencies
+- `grep-ast`: Provides TreeContext and language identification functionality
+- `pygments`: Provides lexical analysis fallback functionality
+- `tree-sitter`: Underlying syntax parsing engine
+
+### Performance Characteristics
+- **Memory Efficiency**: Uses generator pattern for processing large files
+- **Error Tolerance**: Syntax errors don't completely prevent parsing
+- **Cache Optimization**: TreeContext provides context caching
+- **Line Length Limiting**: Automatically truncates overly long lines to prevent excessive output
+
+### Limitations and Considerations
+1. **File Encoding**: Only supports UTF-8 encoded files
+2. **File Size**: May have performance impact on very large files
+3. **Language Support**: Depends on availability of tree-sitter query files
+4. **Accuracy**: Complex macro definitions or dynamic code may not be accurately identified
+
+## Related Modules
+
+- `models.py`: Defines Tag data model
+- `../../../queries/`: Stores tree-sitter query files for various languages
+- `../../../tests/tools/ast/`: Complete test suite
+
+## Changelog
+
+- Support for multiple programming languages code definition extraction
+- Implementation of dual parsing strategy for improved accuracy
+- Added error handling and fallback mechanisms
+- Optimized output format and performance