Core Concepts
This document explains the key concepts and terminology used in Upsilon.
Issue Types and Severity Levels
Upsilon categorizes code issues into different types and severity levels to help prioritize fixes.
Severity Levels
- error 🚫: Critical issues that prevent code from running or cause failures
- warning ⚠️: Issues that should be addressed but don't prevent execution
- info ℹ️: Suggestions and minor improvements
Common Issue Types
Syntax Issues
- syntax_error: Code that violates language syntax rules
- compilation_error: Code that fails to compile
- missing_colon: Python-specific missing colon errors
- indentation_error: Incorrect indentation (Python)
Code Quality Issues
- unused_import: Imported modules/packages that aren't used
- unused_variable: Variables declared but never used
- unreachable_code: Code that can never be executed
- duplicate_code: Repeated code blocks that could be refactored
Style Issues
- naming_convention: Variables/functions not following naming conventions
- line_too_long: Lines exceeding recommended length
- missing_docstring: Functions/classes without documentation
- inconsistent_formatting: Inconsistent code formatting
Logic Issues
- potential_bug: Code patterns that might cause bugs
- type_mismatch: Type annotation inconsistencies
- null_pointer: Potential null/undefined access
- infinite_loop: Loops that might run forever
Security Issues
- hardcoded_secret: API keys or passwords in source code
- sql_injection: Potential SQL injection vulnerabilities
- path_traversal: Unsafe file path operations
- unsafe_deserialization: Dangerous data deserialization
Performance Issues
- inefficient_algorithm: Algorithms with poor time complexity
- memory_leak: Potential memory leaks
- blocking_io: Blocking I/O operations in async code
- excessive_allocation: Unnecessary object creation
Example Issue Object
{
"type": "unused_import",
"message": "Imported module 'os' is never used",
"severity": "warning",
"line": 1,
"column": 8,
"file": "src/main.py",
"tool": "ruff",
"suggestion": "Remove the unused import statement"
}
Tool Categories
Built-in Tools
Basic analysis tools that work without external dependencies:
SpellChecker
- Purpose: Detects typos in comments and strings
- Languages: All (extracts text based on language syntax)
- Configuration: Language setting for spell checking
- Example Issues: "teh" → "the", "recieve" → "receive"
SyntaxChecker
- Purpose: Basic syntax validation using language compilers
- Languages: Python (built-in), others recommend external tools
- Method: Uses
compile()function for Python - Example Issues: Missing colons, invalid syntax
ImportAnalyzer
- Purpose: Basic import pattern analysis
- Languages: Python, JavaScript, TypeScript
- Example Issues: Relative imports, missing file extensions
External Tools
Production-quality tools that provide comprehensive analysis:
Python Tools
-
mypy: Static type checking
- Detects type mismatches, missing annotations
- Command:
mypy --output=json {file}
-
ruff: Fast Python linter and formatter
- Code quality, style, and performance issues
- Command:
ruff check --output-format=json {file}
-
python compiler: Syntax validation
- Uses Python's built-in compilation
- Command:
python -m py_compile {file}
JavaScript/TypeScript Tools
- eslint: Comprehensive linting
- Code quality, style, and potential bugs
- Command:
eslint --format=json {file}
System Language Tools
-
rustc: Rust compiler
- Compilation errors, warnings, and suggestions
- Command:
rustc --emit=metadata --crate-type lib {file}
-
go build: Go compiler
- Compilation and type checking
- Command:
go build -o /dev/null {file}
-
julia: Julia compiler
- Syntax and type checking
- Command:
julia --check-bounds=yes --check-syntax=yes {file}
Review Workflow
1. File Processing
Input File → Language Detection → Tool Selection → Analysis
2. Tool Execution
- Parallel execution: Multiple tools run simultaneously
- Timeout handling: Prevents tools from hanging
- Error isolation: One tool failure doesn't affect others
3. LLM Analysis
Tool Results + Source Code → Claude Analysis → Function Calling → Final Report
4. Result Aggregation
- Issue deduplication: Remove duplicate findings
- Severity prioritization: Sort by importance
- Context enrichment: Add suggestions and explanations
Configuration Concepts
Tool Selection Strategy
- Auto-detection: Tools are automatically discovered
- Availability checking: Only use tools that are installed
- Language filtering: Tools only run on supported languages
- Graceful degradation: Missing tools don't break the workflow
Prompt Customization
Upsilon uses several prompt templates:
- system_prompt: Sets the AI's role and behavior
- review_prompt: Template for code review requests
- tool_selection_prompt: Guides tool selection decisions
- summary_prompt: Formats final review summary
Mock vs Real Mode
- Mock Mode (default): Fast, deterministic responses for testing
- Real Mode: Actual Claude API calls for production analysis
Output Formats
Text Format (Human-Readable)
📋 Review Results
├── main.py (python) - ✅ No issues
└── utils.py (python) - ⚠️ 2 warnings
├── 🔍 Issues
│ ├── Line 15: Unused import 'sys'
│ └── Line 23: Function missing docstring
└── 💡 Recommendations
└── Add documentation and remove unused imports
JSON Format (Machine-Readable)
[
{
"file_path": "utils.py",
"language": "python",
"issues": [
{
"type": "unused_import",
"message": "Unused import 'sys'",
"severity": "warning",
"line": 15,
"tool": "ruff"
}
],
"summary": "2 warnings found",
"overall_score": 8,
"recommendations": ["Add documentation", "Remove unused imports"]
}
]
Performance Considerations
Execution Speed
- Tool caching: Results cached by file content hash
- Parallel processing: Multiple tools run concurrently
- Timeout management: Prevents slow tools from blocking
Token Management
- Content chunking: Large files split for LLM processing
- Selective analysis: Focus on changed code in CI/CD
- Model selection: Faster models for pre-commit, powerful for detailed analysis
Memory Usage
- Streaming processing: Large codebases processed incrementally
- Temporary file cleanup: Automatic cleanup of intermediate files
- Resource limits: Configurable memory and time constraints