0
# Analysis Runner
1

2
Core functionality for running code analysis with the main Prospector class. This handles tool orchestration, configuration management, and result aggregation.
3

4
## Capabilities
5

6
### Prospector Class
7

8
Main orchestrator class that coordinates the execution of multiple static analysis tools and aggregates their results.
9

10
```python { .api }
11
class Prospector:
12
    def __init__(self, config: ProspectorConfig) -> None
13
```
14

15
Creates a new Prospector instance with the provided configuration.
16

17
**Parameters:**
18
- `config`: ProspectorConfig - Configuration object containing analysis settings
19

20
**Properties:**
21
- `config`: ProspectorConfig - The configuration object
22
- `summary`: Optional[dict[str, Any]] - Analysis summary information  
23
- `messages`: list[Message] - Collection of analysis messages
24

25
```python { .api }
26
def execute(self) -> None
27
```
28

29
Executes the analysis by running all configured tools and processing their results. This method:
30
1. Discovers files to analyze using FileFinder
31
2. Runs each enabled tool on the discovered files
32
3. Processes and filters the resulting messages
33
4. Generates summary information
34

35
```python { .api }
36
def get_messages(self) -> list[Message]
37
```
38

39
Returns all analysis messages found during execution.
40

41
**Returns:**
42
- `list[Message]` - List of all messages from analysis tools
43

44
```python { .api }
45
def get_summary(self) -> Optional[dict[str, Any]]
46
```
47

48
Returns summary information about the analysis run.
49

50
**Returns:**
51
- `Optional[dict[str, Any]]` - Dictionary containing:
52
  - `started`: datetime - When analysis started
53
  - `completed`: datetime - When analysis completed  
54
  - `time_taken`: str - Duration in seconds
55
  - `message_count`: int - Total number of messages
56
  - `libraries`: list[str] - Detected libraries
57
  - `strictness`: Optional[str] - Strictness level used
58
  - `profiles`: str - Comma-separated list of profiles
59
  - `tools`: list[str] - Tools that were run
60
  - `formatter`: str - Output formatter used
61
  - `external_config`: str - External config files used (if any)
62

63
```python { .api }
64
def print_messages(self) -> None
65
```
66

67
Prints analysis results using the configured output formatters. Handles multiple output formats and files as specified in configuration.
68

69
```python { .api }
70
def write_to(self, formatter: Formatter, target: TextIO) -> None
71
```
72

73
Writes formatted output to a specific target.
74

75
**Parameters:**
76
- `formatter`: Formatter - The formatter to use for output
77
- `target`: TextIO - The target stream to write to
78

79
```python { .api }
80
def process_messages(self, found_files: FileFinder, messages: list[Message], 
81
                    tools: dict[str, ToolBase]) -> list[Message]
82
```
83

84
Processes raw messages from tools by applying blending and filtering.
85

86
**Parameters:**
87
- `found_files`: FileFinder - File discovery object
88
- `messages`: list[Message] - Raw messages from tools
89
- `tools`: dict[str, ToolBase] - Dictionary of tools that were run
90

91
**Returns:**
92
- `list[Message]` - Processed and filtered messages
93

94
### Main Entry Point
95

96
```python { .api }
97
def main() -> None
98
```
99

100
Main entry point function for the prospector command-line tool. This function:
101
1. Creates a ProspectorConfig from command-line arguments
102
2. Validates input paths (multi-path mode requires files, not directories)  
103
3. Creates and executes a Prospector instance
104
4. Prints results and exits with appropriate code
105

106
**Exit Codes:**
107
- `0` - Success (no issues found or --zero-exit flag used)
108
- `1` - Analysis completed but issues were found
109
- `2` - Fatal error or invalid arguments
110

111
### Parser Access
112

113
```python { .api }
114
def get_parser() -> argparse.ArgumentParser
115
```
116

117
Returns the argparse parser used by prospector. This is primarily used for documentation generation with Sphinx.
118

119
**Returns:**
120
- `argparse.ArgumentParser` - The argument parser with all prospector options
121

122
## Usage Examples
123

124
### Basic Programmatic Usage
125

126
```python
127
from prospector.config import ProspectorConfig
128
from prospector.run import Prospector
129

130
# Create default configuration
131
config = ProspectorConfig()
132

133
# Run analysis
134
prospector = Prospector(config)
135
prospector.execute()
136

137
# Process results
138
messages = prospector.get_messages()
139
for message in messages:
140
    print(f"{message.source}: {message.message}")
141

142
# Get summary
143
summary = prospector.get_summary()
144
print(f"Analysis took {summary['time_taken']} seconds")
145
print(f"Found {summary['message_count']} issues")
146
```
147

148
### Custom Configuration
149

150
```python
151
from pathlib import Path
152
from prospector.config import ProspectorConfig
153
from prospector.run import Prospector
154

155
# Create configuration with custom working directory
156
workdir = Path("/path/to/project")
157
config = ProspectorConfig(workdir=workdir)
158

159
# Run analysis
160
prospector = Prospector(config)
161
prospector.execute()
162

163
# Print results using configured formatters
164
prospector.print_messages()
165
```
166

167
### Error Handling
168

169
```python
170
from prospector.config import ProspectorConfig
171
from prospector.run import Prospector
172
from prospector.exceptions import FatalProspectorException
173

174
try:
175
    config = ProspectorConfig()
176
    prospector = Prospector(config)
177
    prospector.execute()
178
    
179
    messages = prospector.get_messages()
180
    if messages:
181
        print(f"Found {len(messages)} issues")
182
    else:
183
        print("No issues found!")
184
        
185
except FatalProspectorException as e:
186
    print(f"Fatal error: {e.message}")
187
except Exception as e:
188
    print(f"Unexpected error: {e}")
189
```