code-compass-cli 0.1.0__py3-none-any.whl

src/docs/doc_generator.py

@@ -0,0 +1,734 @@
+"""Auto-generates documentation for the codebase."""
+
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Any, Optional
+from datetime import datetime
+
+
+class DocumentationGenerator:
+    """Generates comprehensive documentation for a Python project."""
+
+    def __init__(self, repo_path: str = "."):
+        """Initialize the documentation generator.
+
+        Args:
+            repo_path: Path to repository to analyze
+        """
+        self.repo_path = Path(repo_path)
+        self.docs_path = self.repo_path / "docs"
+        self.modules: Dict[str, Dict[str, Any]] = {}
+        self.project_name = self.repo_path.name
+        self._analyze_project()
+
+    def _analyze_project(self) -> None:
+        """Analyze the project structure and modules."""
+        for root, _, files in os.walk(self.repo_path):
+            # Skip venv and hidden directories
+            if "venv" in root or "/.git" in root or "/docs" in root:
+                continue
+
+            for file in files:
+                if file.endswith(".py"):
+                    filepath = Path(root) / file
+                    rel_path = filepath.relative_to(self.repo_path)
+                    module_name = str(rel_path).replace(".py", "").replace("/", ".")
+
+                    try:
+                        with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+                            content = f.read()
+                            self.modules[module_name] = self._extract_module_info(content, file)
+                    except (IOError, OSError):
+                        continue
+
+    def _extract_module_info(self, content: str, filename: str) -> Dict[str, Any]:
+        """Extract module information from file content.
+
+        Args:
+            content: File content
+            filename: Name of the file
+
+        Returns:
+            Dictionary with module information
+        """
+        lines = content.split("\n")
+        docstring = self._extract_docstring(content)
+        functions = self._extract_functions(content)
+        classes = self._extract_classes(content)
+
+        return {
+            "filename": filename,
+            "docstring": docstring,
+            "functions": functions,
+            "classes": classes,
+            "lines": len(lines),
+        }
+
+    def _extract_docstring(self, content: str) -> str:
+        """Extract module docstring.
+
+        Args:
+            content: File content
+
+        Returns:
+            Docstring or empty string
+        """
+        match = re.search(r'"""(.+?)"""', content, re.DOTALL)
+        if match:
+            return match.group(1).strip()
+        return ""
+
+    def _extract_functions(self, content: str) -> List[Dict[str, str]]:
+        """Extract function definitions.
+
+        Args:
+            content: File content
+
+        Returns:
+            List of function definitions
+        """
+        functions = []
+        lines = content.split("\n")
+
+        for i, line in enumerate(lines):
+            func_match = re.match(r"^\s*def\s+(\w+)\s*\(([^)]*)\)", line)
+            if func_match and not line.strip().startswith("#"):
+                func_name = func_match.group(1)
+                params = func_match.group(2)
+                docstring = ""
+
+                # Try to extract docstring from next lines
+                if i + 1 < len(lines):
+                    doc_match = re.search(r'"""(.+?)"""', "\n".join(lines[i+1:i+10]), re.DOTALL)
+                    if doc_match:
+                        docstring = doc_match.group(1).strip().split("\n")[0]
+
+                functions.append({
+                    "name": func_name,
+                    "params": params.strip(),
+                    "docstring": docstring,
+                })
+
+        return functions
+
+    def _extract_classes(self, content: str) -> List[Dict[str, Any]]:
+        """Extract class definitions.
+
+        Args:
+            content: File content
+
+        Returns:
+            List of class definitions
+        """
+        classes = []
+        lines = content.split("\n")
+
+        for i, line in enumerate(lines):
+            class_match = re.match(r"^\s*class\s+(\w+)\s*[\(:]", line)
+            if class_match and not line.strip().startswith("#"):
+                class_name = class_match.group(1)
+                docstring = ""
+
+                # Try to extract docstring from next lines
+                if i + 1 < len(lines):
+                    doc_match = re.search(r'"""(.+?)"""', "\n".join(lines[i+1:i+10]), re.DOTALL)
+                    if doc_match:
+                        docstring = doc_match.group(1).strip().split("\n")[0]
+
+                classes.append({
+                    "name": class_name,
+                    "docstring": docstring,
+                })
+
+        return classes
+
+    def generate(self) -> Dict[str, str]:
+        """Generate all documentation files.
+
+        Returns:
+            Dictionary with generated documentation content
+        """
+        # Create docs directory
+        self.docs_path.mkdir(exist_ok=True)
+
+        docs = {
+            "README.md": self._generate_readme(),
+            "ARCHITECTURE.md": self._generate_architecture(),
+            "SETUP.md": self._generate_setup(),
+        }
+
+        # Write files
+        for filename, content in docs.items():
+            filepath = self.docs_path / filename
+            try:
+                with open(filepath, "w", encoding="utf-8") as f:
+                    f.write(content)
+            except (IOError, OSError) as e:
+                print(f"Error writing {filename}: {e}")
+
+        return docs
+
+    def _generate_readme(self) -> str:
+        """Generate README.md.
+
+        Returns:
+            README content
+        """
+        project_name = self.project_name.replace("-", " ").title()
+
+        content = f"""# {project_name}
+
+A Python CLI tool for code analysis and navigation.
+
+## Overview
+
+{project_name} provides intelligent code analysis, navigation, and quality checking tools for Python projects.
+
+### Features
+
+- **Code Querying**: Search your codebase with natural language queries
+- **Flow Tracing**: Trace execution paths through your code
+- **Quality Analysis**: Detect security issues, performance problems, and code smells
+- **Auto-Documentation**: Generate comprehensive project documentation
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+### Basic Usage
+
+```bash
+# Scan repository structure
+python3 src/cli/main.py scan .
+
+# Query codebase
+python3 src/cli/main.py query "find FlowTracer" .
+
+# Trace execution flow
+python3 src/cli/main.py trace execute .
+
+# Analyze code quality
+python3 src/cli/main.py analyze .
+
+# Generate documentation
+python3 src/cli/main.py gendocs .
+```
+
+## Commands
+
+### scan
+Scan a repository for code structure.
+```bash
+python3 src/cli/main.py scan <path>
+```
+
+### query
+Query code with natural language.
+```bash
+python3 src/cli/main.py query "<question>" <path>
+```
+
+### trace
+Trace execution flow for a symbol.
+```bash
+python3 src/cli/main.py trace <function_name> <path>
+```
+
+### analyze
+Analyze code quality (security, performance, code smells).
+```bash
+python3 src/cli/main.py analyze <path>
+```
+
+### gendocs
+Generate documentation for the project.
+```bash
+python3 src/cli/main.py gendocs <path>
+```
+
+## Project Structure
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed project architecture and module descriptions.
+
+## Setup & Installation
+
+See [SETUP.md](SETUP.md) for detailed setup instructions.
+
+## Requirements
+
+- Python 3.7+
+- click>=8.1.0
+- rich>=13.0.0
+
+## License
+
+MIT License
+
+---
+
+Generated on {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+"""
+        return content
+
+    def _generate_architecture(self) -> str:
+        """Generate ARCHITECTURE.md.
+
+        Returns:
+            ARCHITECTURE content
+        """
+        content = """# Architecture
+
+## Project Structure
+
+```
+code-compass/
+├── src/
+│   ├── __init__.py           # Package initialization
+│   ├── cli/
+│   │   ├── __init__.py
+│   │   └── main.py           # CLI entry point and command definitions
+│   ├── scanner/
+│   │   ├── __init__.py
+│   │   └── repo_scanner.py   # Repository scanning and analysis
+│   ├── query/
+│   │   ├── __init__.py
+│   │   └── copilot_query.py  # NLP query engine
+│   ├── visualizer/
+│   │   ├── __init__.py
+│   │   └── flow_tracer.py    # Execution flow tracing
+│   ├── quality/
+│   │   ├── __init__.py
+│   │   └── analyzer.py       # Code quality analysis
+│   └── docs/
+│       ├── __init__.py
+│       └── doc_generator.py  # Documentation generation
+├── requirements.txt          # Project dependencies
+└── README.md
+```
+
+## Module Overview
+
+### CLI Module (`src/cli/main.py`)
+
+**Purpose**: Command-line interface for all CodeCompass features.
+
+**Key Components**:
+- `cli()`: Main entry point, creates click command group
+- `scan()`: Repository structure scanning
+- `query()`: Natural language code search
+- `trace()`: Execution flow visualization
+- `analyze()`: Code quality analysis
+- `gendocs()`: Auto-documentation generation
+
+**Dependencies**: click, rich
+
+### Scanner Module (`src/scanner/repo_scanner.py`)
+
+**Purpose**: Analyzes repository structure and file organization.
+
+**Key Classes**:
+- `RepoScanner`: Walks repository and collects file/directory information
+
+**Key Methods**:
+- `scan()`: Returns structure information
+- `_collect_files()`: Gathers all project files
+- `_collect_directories()`: Gathers all directories
+
+### Query Module (`src/query/copilot_query.py`)
+
+**Purpose**: Intelligent code querying with natural language understanding.
+
+**Key Classes**:
+- `CopilotQuery`: Executes queries against codebase
+
+**Key Methods**:
+- `execute()`: Routes queries to appropriate handler
+- `_search_query()`: Keyword-based search
+- `_definition_query()`: Find class/function definitions
+- `_import_query()`: Find imports and dependencies
+- `_general_query()`: Answer general project questions
+
+**Capabilities**:
+- Searches code for keywords with line numbers
+- Finds function and class definitions
+- Identifies import statements
+- Answers questions about project purpose
+
+### Visualizer Module (`src/visualizer/flow_tracer.py`)
+
+**Purpose**: Traces and visualizes code execution flows.
+
+**Key Classes**:
+- `FlowTracer`: Analyzes call chains and execution paths
+- `Node`: Represents a function/class in the execution graph
+
+**Key Methods**:
+- `trace()`: Analyzes execution flow from entry point
+- `_scan_codebase()`: Finds all definitions and calls
+- `_extract_definitions()`: Locates functions and classes
+- `_extract_calls()`: Identifies function calls
+- `_build_call_chain()`: Creates execution tree
+
+**Capabilities**:
+- Maps function calls and dependencies
+- Shows execution paths with file/line references
+- Prevents infinite recursion with depth limits
+- Filters out built-in functions
+
+### Quality Module (`src/quality/analyzer.py`)
+
+**Purpose**: Detects code quality issues and security vulnerabilities.
+
+**Key Classes**:
+- `CodeAnalyzer`: Analyzes code for issues
+- `Issue`: Represents a detected problem
+
+**Issue Types**:
+1. **Security** (Critical/Warning)
+   - SQL injection patterns
+   - Hardcoded secrets/API keys
+   - XSS vulnerabilities
+
+2. **Performance** (Warning/Info)
+   - N+1 query patterns
+   - Nested loops and inefficiency
+
+3. **Code Smells** (Info)
+   - Long functions (>30 lines)
+   - Large classes (>50 lines)
+   - Duplicate code
+
+**Each Issue Includes**:
+- File path and line number
+- Severity level
+- Category
+- Description
+- Fix suggestion
+
+### Documentation Module (`src/docs/doc_generator.py`)
+
+**Purpose**: Auto-generates project documentation.
+
+**Key Classes**:
+- `DocumentationGenerator`: Analyzes project and generates docs
+
+**Generated Files**:
+- `README.md`: Project overview and quick start
+- `ARCHITECTURE.md`: Detailed architecture guide
+- `SETUP.md`: Installation and setup instructions
+
+**Key Methods**:
+- `generate()`: Creates all documentation files
+- `_analyze_project()`: Scans and analyzes project structure
+- `_extract_module_info()`: Extracts info from modules
+- `_extract_docstring()`: Gets module docstrings
+- `_extract_functions()`: Lists functions
+- `_extract_classes()`: Lists classes
+
+## Data Flow
+
+### Query Processing
+```
+User Input
+    ↓
+Query Command
+    ↓
+CopilotQuery.execute()
+    ↓
+Query Type Detection (search/definition/import/general)
+    ↓
+Appropriate Handler Method
+    ↓
+Codebase Analysis
+    ↓
+Rich Formatted Output
+```
+
+### Flow Tracing
+```
+User Input (function name)
+    ↓
+Trace Command
+    ↓
+FlowTracer.trace()
+    ↓
+Codebase Scanning
+    ↓
+Definition Extraction
+    ↓
+Call Analysis
+    ↓
+Call Chain Building
+    ↓
+Tree Visualization
+    ↓
+Rich Formatted Output
+```
+
+### Quality Analysis
+```
+User Input (repository path)
+    ↓
+Analyze Command
+    ↓
+CodeAnalyzer.analyze()
+    ↓
+File-by-File Analysis
+    ↓
+Security Checks
+    ↓
+Performance Checks
+    ↓
+Code Smell Detection
+    ↓
+Issue Categorization by Severity
+    ↓
+Rich Formatted Output
+```
+
+## Technology Stack
+
+- **Language**: Python 3.7+
+- **CLI Framework**: Click
+- **Output Formatting**: Rich
+- **Pattern Matching**: Regular Expressions
+- **File I/O**: Standard Python libraries
+
+## Design Principles
+
+1. **Modularity**: Each feature in its own module with clear responsibilities
+2. **Extensibility**: Easy to add new query types, checks, or commands
+3. **User-Friendly**: Rich terminal output with colors, tables, and formatting
+4. **Non-Invasive**: Reads files, doesn't modify them (except docs generation)
+5. **Performance**: Efficient file scanning and pattern matching
+
+---
+
+Generated documentation - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+"""
+        return content
+
+    def _generate_setup(self) -> str:
+        """Generate SETUP.md.
+
+        Returns:
+            SETUP content
+        """
+        content = """# Setup & Installation Guide
+
+## Requirements
+
+- Python 3.7 or higher
+- pip (Python package manager)
+
+## Installation Steps
+
+### 1. Clone or Download the Repository
+
+```bash
+cd code-compass
+```
+
+### 2. Create a Virtual Environment (Recommended)
+
+```bash
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\\\\Scripts\\\\activate
+```
+
+### 3. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 4. Verify Installation
+
+```bash
+python3 src/cli/main.py --help
+```
+
+You should see the help menu with all available commands.
+
+## Project Dependencies
+
+### Required Packages
+
+- **click** (>=8.1.0): Command-line interface framework
+  - Used for creating CLI commands
+  - Handles argument and option parsing
+
+- **rich** (>=13.0.0): Rich text and formatting library
+  - Beautiful terminal output with colors
+  - Tables, panels, trees for visualization
+
+### Development (Optional)
+
+For development and testing:
+```bash
+pip install pytest  # For running tests
+pip install flake8  # For linting
+pip install black   # For code formatting
+```
+
+## Quick Start
+
+After installation, try these commands:
+
+### 1. Scan the Repository
+
+```bash
+python3 src/cli/main.py scan .
+```
+
+Shows repository structure and files.
+
+### 2. Query the Codebase
+
+```bash
+python3 src/cli/main.py query "find FlowTracer" .
+```
+
+Searches for code patterns using natural language.
+
+### 3. Trace a Function
+
+```bash
+python3 src/cli/main.py trace execute .
+```
+
+Shows the execution flow of a function.
+
+### 4. Analyze Code Quality
+
+```bash
+python3 src/cli/main.py analyze .
+```
+
+Detects security issues, performance problems, and code smells.
+
+### 5. Generate Documentation
+
+```bash
+python3 src/cli/main.py gendocs .
+```
+
+Auto-generates README, ARCHITECTURE, and SETUP documentation.
+
+## Using with Other Projects
+
+To analyze another Python project:
+
+```bash
+python3 src/cli/main.py query "what does this project do" /path/to/project
+python3 src/cli/main.py analyze /path/to/project
+python3 src/cli/main.py trace main /path/to/project
+```
+
+## Troubleshooting
+
+### ModuleNotFoundError: No module named 'click'
+
+**Solution**: Install dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### Virtual Environment Not Activated
+
+**Solution**: Activate the virtual environment
+```bash
+source venv/bin/activate  # Linux/Mac
+venv\\\\Scripts\\\\activate      # Windows
+```
+
+### Permission Denied on venv/bin/activate
+
+**Solution**: Make it executable
+```bash
+chmod +x venv/bin/activate
+```
+
+### Python 3 Not Found
+
+**Solution**: Use python3 explicitly or check your Python installation
+```bash
+python3 --version
+which python3
+```
+
+## Environment Setup for Different Operating Systems
+
+### Linux/macOS
+
+```bash
+# Create venv
+python3 -m venv venv
+
+# Activate venv
+source venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run
+python3 src/cli/main.py --help
+```
+
+### Windows (PowerShell)
+
+```bash
+# Create venv
+python -m venv venv
+
+# Activate venv
+.\\\\venv\\\\Scripts\\\\Activate.ps1
+
+# If you get execution policy error, run:
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run
+python src\\\\cli\\\\main.py --help
+```
+
+### Windows (Command Prompt)
+
+```bash
+# Create venv
+python -m venv venv
+
+# Activate venv
+venv\\\\Scripts\\\\activate.bat
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run
+python src\\\\cli\\\\main.py --help
+```
+
+## Next Steps
+
+1. Read README.md for feature overview
+2. Read ARCHITECTURE.md for technical details
+3. Start using commands to analyze your code!
+
+## Getting Help
+
+- Use `--help` flag with any command for usage information
+- Check command docstrings in `src/cli/main.py`
+- Review module docstrings for implementation details
+
+---
+
+Setup guide generated - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+"""
+        return content