0
# Core Analysis Engine
1

2
The heart of refurb's code analysis, managing integration with Mypy, check execution, and error collection through a sophisticated AST-based analysis pipeline.
3

4
## Capabilities
5

6
### Main Analysis Function
7

8
The primary function that orchestrates the entire analysis process from Mypy integration through error collection and filtering.
9

10
```python { .api }
11
def run_refurb(settings: Settings) -> Sequence[Error | str]:
12
    """
13
    Execute refurb analysis on specified files using Mypy for parsing and type analysis.
14
    
15
    This function:
16
    1. Configures and runs Mypy to parse source files and generate ASTs
17
    2. Loads and filters checks based on settings
18
    3. Visits each AST node with applicable checks
19
    4. Collects and filters errors based on ignore rules
20
    5. Sorts results according to specified criteria
21
    
22
    Parameters:
23
    - settings: Configuration object containing files to analyze, enabled/disabled checks,
24
               output formatting preferences, and all other analysis options
25
    
26
    Returns:
27
    Sequence containing Error objects for code issues found, or error strings for
28
    system-level problems (file access, parsing failures, etc.)
29
    
30
    Raises:
31
    - CompileError: When Mypy encounters fatal parsing or compilation errors
32
    - RecursionError: Caught and handled gracefully for deeply nested code structures
33
    """
34
```
35

36
### Error Processing Functions
37

38
Functions that handle error filtering, sorting, and output formatting.
39

40
```python { .api }
41
def should_ignore_error(error: Error | str, settings: Settings) -> bool:
42
    """
43
    Determine if an error should be ignored based on comment directives and settings.
44
    
45
    Parameters:
46
    - error: Error object or error string to check
47
    - settings: Settings containing ignore rules and amendment configurations
48
    
49
    Returns:
50
    True if error should be ignored, False otherwise
51
    """
52

53
def is_ignored_via_comment(error: Error) -> bool:
54
    """
55
    Check if error is ignored via '# noqa' style comments in source code.
56
    
57
    Supports formats like:
58
    - # noqa (ignores all errors on line)
59
    - # noqa: FURB105 (ignores specific error)
60
    - # noqa: FURB105,FURB123 (ignores multiple errors)
61
    
62
    Parameters:
63
    - error: Error object with filename and line information
64
    
65
    Returns:
66
    True if error is suppressed by comment, False otherwise
67
    """
68

69
def is_ignored_via_amend(error: Error, settings: Settings) -> bool:
70
    """
71
    Check if error is ignored via path-specific amendment rules in configuration.
72
    
73
    Parameters:
74
    - error: Error object with filename and error code information
75
    - settings: Settings containing amendment rules mapping paths to ignored errors
76
    
77
    Returns:
78
    True if error is suppressed by amendment rule, False otherwise
79
    """
80

81
def sort_errors(error: Error | str, settings: Settings) -> tuple[str | int, ...]:
82
    """
83
    Generate sort key for error based on settings sort preference.
84
    
85
    Parameters:
86
    - error: Error object or error string to generate key for
87
    - settings: Settings containing sort_by preference ("filename" or "error")
88
    
89
    Returns:
90
    Tuple suitable for use as sort key, ordered by filename then location,
91
    or by error code then location, depending on settings
92
    """
93
```
94

95
### Source Code Analysis
96

97
Utility functions for analyzing source code and extracting contextual information.
98

99
```python { .api }
100
def get_source_lines(filepath: str) -> list[str]:
101
    """
102
    Read and cache source file contents for error processing.
103
    
104
    Uses LRU caching to avoid repeated file reads during analysis.
105
    
106
    Parameters:
107
    - filepath: Path to source file to read
108
    
109
    Returns:
110
    List of source code lines (without line endings)
111
    """
112
```
113

114
### Output Formatting
115

116
Functions that format analysis results for different output targets and integrations.
117

118
```python { .api }
119
def format_errors(errors: Sequence[Error | str], settings: Settings) -> str:
120
    """
121
    Format error sequence for output based on settings preferences.
122
    
123
    Parameters:
124
    - errors: Sequence of Error objects and error strings to format
125
    - settings: Settings containing format preferences and display options
126
    
127
    Returns:
128
    Formatted string ready for display, including help text when appropriate
129
    """
130

131
def format_as_github_annotation(error: Error | str) -> str:
132
    """
133
    Format error as GitHub Actions annotation for CI integration.
134
    
135
    Parameters:
136
    - error: Error object or error string to format
137
    
138
    Returns:
139
    GitHub Actions annotation string with file, line, column, and message
140
    """
141

142
def format_with_color(error: Error | str) -> str:
143
    """
144
    Format error with ANSI color codes for terminal display.
145
    
146
    Highlights file paths, line numbers, error codes, and diff suggestions
147
    with appropriate colors for improved readability.
148
    
149
    Parameters:
150
    - error: Error object or error string to format
151
    
152
    Returns:
153
    ANSI color-formatted string for terminal display
154
    """
155
```
156

157
### Performance Analysis
158

159
Functions for analyzing and reporting performance metrics during analysis.
160

161
```python { .api }
162
def output_timing_stats(
163
    settings: Settings,
164
    mypy_total_time_spent: float,
165
    mypy_timing_stats: Path | None,
166
    refurb_timing_stats_in_ms: dict[str, int]
167
) -> None:
168
    """
169
    Export detailed timing information to JSON file for performance analysis.
170
    
171
    Generates comprehensive timing data including:
172
    - Total Mypy build time
173
    - Per-module Mypy parsing time
174
    - Per-file refurb checking time
175
    
176
    Parameters:
177
    - settings: Settings containing timing_stats file path
178
    - mypy_total_time_spent: Total time spent in Mypy build phase
179
    - mypy_timing_stats: Path to Mypy's detailed timing data
180
    - refurb_timing_stats_in_ms: Per-file refurb checking times in milliseconds
181
    """
182
```
183

184
### Analysis Pipeline Integration
185

186
The analysis process integrates tightly with Mypy's type checker:
187

188
1. **Mypy Configuration**: Sets incremental parsing, cache options, and Python version
189
2. **AST Generation**: Uses Mypy to parse source files into typed AST nodes
190
3. **Type Information**: Leverages Mypy's type analysis for sophisticated checks
191
4. **Error Context**: Maintains file paths and line information throughout analysis
192
5. **Performance Monitoring**: Tracks timing for both Mypy and refurb phases
193

194
### Usage Examples
195

196
```python
197
from refurb.main import run_refurb
198
from refurb.settings import load_settings
199

200
# Basic analysis
201
settings = load_settings(["src/"])
202
errors = run_refurb(settings)
203

204
# Analysis with custom options
205
settings = load_settings([
206
    "src/", 
207
    "--ignore", "FURB105,FURB123",
208
    "--format", "github",
209
    "--timing-stats", "timing.json"
210
])
211
errors = run_refurb(settings)
212

213
# Process results
214
for error in errors:
215
    if isinstance(error, str):
216
        print(f"System error: {error}")
217
    else:
218
        print(f"Issue at {error.filename}:{error.line}: {error.msg}")
219
```