Skip to main content

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​

  1. Auto-detection: Tools are automatically discovered
  2. Availability checking: Only use tools that are installed
  3. Language filtering: Tools only run on supported languages
  4. 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

Next: External Tool Integration →