0
# CLI Tools
1

2
CrossHair provides comprehensive command-line tools for analyzing Python code, checking contracts, generating tests, and comparing function behaviors. The tools integrate with development workflows and provide IDE support through an LSP server.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
Primary command-line interface for CrossHair with support for multiple subcommands.
9

10
```python { .api }
11
def main(cmd_args=None):
12
    """
13
    Main CLI entry point for CrossHair.
14
    
15
    Parameters:
16
    - cmd_args: Optional list of command line arguments. If None, uses sys.argv
17
    
18
    Provides access to all CrossHair subcommands: check, watch, cover, 
19
    diffbehavior, and server.
20
    """
21
```
22

23
**Usage Examples:**
24

25
```bash
26
# Basic function checking
27
crosshair check mymodule.py::my_function
28

29
# Check all functions in a module
30
crosshair check mymodule.py
31

32
# Check with specific analysis options
33
crosshair check --analysis_kind=PEP316 mymodule.py
34

35
# Enable verbose output
36
crosshair check --verbose mymodule.py
37
```
38

39
### Contract Checking
40

41
Verify preconditions and postconditions for functions with contracts.
42

43
```python { .api }
44
def check(args, options, stdout, stderr):
45
    """
46
    Check command implementation for contract verification.
47
    
48
    Parameters:
49
    - args: Parsed command line arguments
50
    - options: AnalysisOptions configuration
51
    - stdout: Output stream for results
52
    - stderr: Error stream for diagnostics
53
    
54
    Returns:
55
    Exit code (0 for success, non-zero for failures/errors)
56
    
57
    Analyzes functions for contract violations using symbolic execution.
58
    Finds counterexamples where preconditions are satisfied but 
59
    postconditions fail.
60
    """
61
```
62

63
**Usage Examples:**
64

65
```bash
66
# Check single function
67
crosshair check mymodule.py::calculate_interest
68

69
# Check with time limit
70
crosshair check --per_condition_timeout=10 mymodule.py
71

72
# Check specific contract types
73
crosshair check --analysis_kind=icontract mymodule.py
74

75
# Check with detailed output
76
crosshair check --report_all --report_verbose mymodule.py
77
```
78

79
**Sample Function with Contracts:**
80

81
```python
82
def divide(a: float, b: float) -> float:
83
    """
84
    Divide two numbers.
85
    
86
    pre: b != 0.0
87
    post: abs(__return__ * b - a) < 1e-10
88
    """
89
    return a / b
90

91
# CrossHair will verify this contract and report violations
92
```
93

94
### File Watching
95

96
Continuously monitor files for changes and automatically re-run analysis.
97

98
```python { .api }
99
def watch(args, options, max_watch_iterations=sys.maxsize):
100
    """
101
    Watch command implementation for continuous analysis.
102
    
103
    Parameters:
104
    - args: Parsed command line arguments
105
    - options: AnalysisOptions configuration  
106
    - max_watch_iterations: Maximum number of watch cycles
107
    
108
    Monitors specified files/modules for changes and automatically
109
    re-runs contract checking when modifications are detected.
110
    """
111
```
112

113
**Usage Examples:**
114

115
```bash
116
# Watch a single module
117
crosshair watch mymodule.py
118

119
# Watch with custom check interval
120
crosshair watch --watch_timeout=5 mymodule.py
121

122
# Watch multiple files
123
crosshair watch mymodule.py othermodule.py
124

125
# Watch with specific analysis options
126
crosshair watch --analysis_kind=deal mymodule.py
127
```
128

129
### Test Generation and Coverage
130

131
Generate unit tests and analyze code coverage for symbolic execution paths.
132

133
```python { .api }
134
def cover(args, options, stdout, stderr):
135
    """
136
    Cover command implementation for test generation.
137
    
138
    Parameters:
139
    - args: Parsed command line arguments
140
    - options: AnalysisOptions configuration
141
    - stdout: Output stream for generated tests
142
    - stderr: Error stream for diagnostics
143
    
144
    Returns:
145
    Exit code (0 for success, non-zero for errors)
146
    
147
    Generates unit tests that achieve high symbolic execution coverage
148
    of the target functions. Can output in various formats including
149
    pytest and unittest.
150
    """
151
```
152

153
**Usage Examples:**
154

155
```bash
156
# Generate pytest tests
157
crosshair cover --coverage_type=pytest mymodule.py::my_function
158

159
# Generate unittest tests
160
crosshair cover --coverage_type=unittest mymodule.py
161

162
# Generate tests with specific coverage goals
163
crosshair cover --per_path_timeout=5 mymodule.py::complex_function
164

165
# Output tests to file
166
crosshair cover mymodule.py > test_generated.py
167
```
168

169
**Example Generated Test:**
170

171
```python
172
# Generated by CrossHair
173
import pytest
174
from mymodule import calculate_score
175

176
def test_calculate_score():
177
    # Test case found by symbolic execution
178
    result = calculate_score(age=25, experience=3, performance=0.85)
179
    assert result >= 0
180
    
181
def test_calculate_score_edge_case():
182
    # Edge case discovered by symbolic execution
183
    result = calculate_score(age=0, experience=0, performance=0.0)
184
    assert result == 0
185
```
186

187
### Behavioral Comparison
188

189
Compare the behavior of different function implementations to find differences.
190

191
```python { .api }
192
def diffbehavior(args, options, stdout, stderr):
193
    """
194
    Diff behavior command for comparing function implementations.
195
    
196
    Parameters:
197
    - args: Parsed command line arguments containing function pairs
198
    - options: AnalysisOptions configuration
199
    - stdout: Output stream for comparison results
200
    - stderr: Error stream for diagnostics
201
    
202
    Returns:
203
    Exit code (0 for identical behavior, non-zero for differences)
204
    
205
    Compares two function implementations to find inputs where they
206
    produce different outputs or exhibit different exception behavior.
207
    """
208
```
209

210
**Usage Examples:**
211

212
```bash
213
# Compare two functions
214
crosshair diffbehavior mymodule.py::old_function mymodule.py::new_function
215

216
# Compare with exception equivalence options
217
crosshair diffbehavior --exception_equivalence=SAME_TYPE old.py::func new.py::func
218

219
# Compare with timeout limits
220
crosshair diffbehavior --per_path_timeout=10 func1 func2
221
```
222

223
**Sample Comparison Output:**
224

225
```
226
Found difference between old_sort and new_sort:
227
Input: items=[3, 1, 2], reverse=True
228
old_sort returns: [3, 2, 1]  
229
new_sort returns: [1, 2, 3]
230

231
Reason: new_sort ignores reverse parameter
232
```
233

234
### Path Search
235

236
Search for specific execution paths or conditions in code.
237

238
```python { .api }
239
def search(args, options, stdout, stderr):
240
    """
241
    Search command implementation for path exploration.
242
    
243
    Parameters:
244
    - args: Parsed command line arguments
245
    - options: AnalysisOptions configuration
246
    - stdout: Output stream for search results  
247
    - stderr: Error stream for diagnostics
248
    
249
    Searches for execution paths that satisfy specific conditions
250
    or reach particular code locations.
251
    """
252
```
253

254
**Usage Examples:**
255

256
```bash
257
# Search for paths leading to exceptions
258
crosshair search --target_exceptions mymodule.py::risky_function
259

260
# Search for specific return values
261
crosshair search --target_returns="lambda x: x < 0" mymodule.py::compute
262

263
# Search with path constraints
264
crosshair search --path_depth=10 mymodule.py::complex_logic
265
```
266

267
### LSP Server
268

269
Language Server Protocol implementation for IDE integration.
270

271
```python { .api }
272
def server(args, options, stdout, stderr):
273
    """
274
    LSP server implementation for IDE integration.
275
    
276
    Parameters:
277
    - args: Parsed command line arguments
278
    - options: AnalysisOptions configuration
279
    - stdout: Output stream (used for LSP communication)
280
    - stderr: Error stream for server diagnostics
281
    
282
    Returns:
283
    Does not return (NoReturn) - runs until terminated
284
    
285
    Runs a Language Server Protocol server that provides real-time
286
    CrossHair analysis integration for IDEs like VS Code and PyCharm.
287
    """
288
```
289

290
**Usage Examples:**
291

292
```bash
293
# Start LSP server
294
crosshair server
295

296
# Start LSP server with custom options
297
crosshair server --analysis_kind=icontract
298

299
# Start server with debug logging
300
crosshair server --verbose
301
```
302

303
**IDE Integration Features:**
304
- Real-time contract checking as you type
305
- Inline error reporting for contract violations
306
- Hover information showing symbolic execution results
307
- Code actions for generating tests
308

309
### MyPy Integration
310

311
Enhanced integration with MyPy for combined type and contract checking.
312

313
```python { .api }
314
def mypy_and_check(cmd_args=None):
315
    """
316
    MyPy integration command (mypycrosshair console command).
317
    
318
    Parameters:
319
    - cmd_args: Optional command line arguments
320
    
321
    Runs MyPy type checking followed by CrossHair contract analysis,
322
    providing comprehensive static analysis combining type safety
323
    and contract verification.
324
    """
325
```
326

327
**Usage Examples:**
328

329
```bash
330
# Run MyPy then CrossHair
331
mypycrosshair mymodule.py
332

333
# With custom MyPy configuration
334
mypycrosshair --mypy-config=mypy.ini mymodule.py
335

336
# Skip MyPy and run only CrossHair
337
mypycrosshair --skip-mypy mymodule.py
338
```
339

340
## Analysis Options
341

342
Configure analysis behavior through command-line options and AnalysisOptions.
343

344
```python { .api }
345
class AnalysisOptions:
346
    """
347
    Configuration options for CrossHair analysis.
348
    
349
    Controls various aspects of symbolic execution including timeouts,
350
    analysis depth, output verbosity, and contract interpretation.
351
    """
352

353
class AnalysisKind(enum.Enum):
354
    """
355
    Types of contract analysis supported.
356
    
357
    - PEP316: PEP 316 style docstring contracts
358
    - icontract: icontract library contracts  
359
    - deal: deal library contracts
360
    - hypothesis: Hypothesis property testing integration
361
    - asserts: Python assert statement checking
362
    """
363
    PEP316 = "PEP316"
364
    icontract = "icontract"
365
    deal = "deal"
366
    hypothesis = "hypothesis"
367
    asserts = "asserts"
368

369
DEFAULT_OPTIONS = AnalysisOptions()
370
```
371

372
**Common CLI Options:**
373

374
```bash
375
# Analysis behavior
376
--analysis_kind=PEP316|icontract|deal|hypothesis|asserts
377
--per_condition_timeout=SECONDS
378
--per_path_timeout=SECONDS
379

380
# Output control  
381
--verbose                 # Detailed output
382
--report_all             # Report all findings
383
--report_verbose         # Verbose error reporting
384
--extra_plugin_dir=PATH  # Additional plugin directory
385

386
# Coverage options
387
--coverage_type=pytest|unittest|doctest
388
--cover_loops            # Include loop coverage
389

390
# Behavioral comparison
391
--exception_equivalence=SAME_TYPE|SAME_TYPE_AND_MESSAGE|EXACT
392
```
393

394
**Example Analysis Configuration:**
395

396
```python
397
from crosshair.options import AnalysisOptions, AnalysisKind
398

399
options = AnalysisOptions(
400
    analysis_kind=AnalysisKind.icontract,
401
    per_condition_timeout=10.0,
402
    report_all=True,
403
    verbose=True
404
)
405
```