Navegador

navegador / docs / guide / analysis.md
Source Rendered
Blame History Raw 288 lines
1
# Structural Analysis
2
3
Navegador's analysis commands answer questions about how code fits together: what breaks if this function changes, where does data flow, which code is never called, and which tests cover what.
4
5
All analysis commands work against the live graph. Run `navegador ingest` first to populate it.
6
7
---
8
9
## Impact analysis
10
11
`navegador impact` traces the downstream effect of changing a function, class, or file. It follows `CALLS`, `INHERITS`, and `IMPORTS` edges to find everything that depends on the target — directly or transitively.
12
13
```bash
14
navegador impact validate_token
15
navegador impact PaymentProcessor --depth 3
16
navegador impact src/auth/service.py --format json
17
```
18
19
### Options
20
21
| Flag | Effect |
22
|---|---|
23
| `--depth N` | How many hops to follow (default: unlimited) |
24
| `--format json` | Machine-readable output |
25
| `--include-tests` | Include test files in the impact set |
26
27
### Output
28
29
```
30
validate_token (Function — src/auth/service.py:42)
31
Direct dependents (3):
32
check_permissions src/auth/permissions.py:18
33
require_auth src/auth/decorators.py:7
34
middleware_auth src/middleware/auth.py:31
35
36
Transitive dependents (11):
37
process_payment src/payments/processor.py:56
38
create_order src/orders/service.py:23
39
... (8 more)
40
41
Affected files (5):
42
src/auth/permissions.py
43
src/auth/decorators.py
44
src/middleware/auth.py
45
src/payments/processor.py
46
src/orders/service.py
47
```
48
49
### Use cases
50
51
- Before refactoring: understand the blast radius before changing a shared utility
52
- Code review: verify a PR's changes are limited to the expected scope
53
- Dependency triage: identify high-fan-out functions that deserve extra test coverage
54
55
---
56
57
## Flow tracing
58
59
`navegador flow` traces the execution path from one function to another, returning every call chain that connects them.
60
61
```bash
62
navegador flow create_order process_payment
63
navegador flow handle_request save_to_db --max-paths 5
64
```
65
66
### Options
67
68
| Flag | Effect |
69
|---|---|
70
| `--max-paths N` | Maximum number of paths to return (default: 3) |
71
| `--format json` | Machine-readable output |
72
73
### Output
74
75
```
76
Paths from create_order to process_payment:
77
78
Path 1 (3 hops):
79
create_order → validate_cart → charge_card → process_payment
80
81
Path 2 (4 hops):
82
create_order → apply_discount → charge_card → process_payment
83
```
84
85
### Use cases
86
87
- Debugging: find all code paths that reach a problematic function
88
- Security review: trace every path to a sensitive operation (e.g., `delete_user`, `transfer_funds`)
89
- Onboarding: understand how a high-level action maps to low-level implementation
90
91
---
92
93
## Dead code detection
94
95
`navegador dead-code` finds functions and classes that are never called, never imported, and not decorated as entry points.
96
97
```bash
98
navegador dead-code ./src
99
navegador dead-code ./src --exclude-tests --format json
100
```
101
102
### Options
103
104
| Flag | Effect |
105
|---|---|
106
| `--exclude-tests` | Skip test files |
107
| `--min-age-days N` | Only report code not called in the last N days (requires git history) |
108
| `--format json` | Machine-readable output |
109
| `--threshold N` | Minimum confidence score to report (0–100, default: 80) |
110
111
### Output
112
113
```
114
Potentially dead code (12 items):
115
116
[Function] legacy_hash_password src/auth/legacy.py:14
117
[Function] _format_receipt_v1 src/payments/receipt.py:88
118
[Class] OldPaymentAdapter src/payments/adapters.py:201
119
...
120
```
121
122
!!! note
123
Navegador performs static call graph analysis. Dynamic dispatch, `getattr`, and string-based imports are not traced. Review candidates before deleting them.
124
125
### Use cases
126
127
- Codebase cleanup: identify safe-to-delete code before a release
128
- Migration audits: find old adapter classes after a library upgrade
129
130
---
131
132
## Cycle detection
133
134
`navegador cycles` finds circular dependency chains in the call graph and import graph.
135
136
```bash
137
navegador cycles ./src
138
navegador cycles ./src --type imports
139
navegador cycles ./src --type calls --format json
140
```
141
142
### Options
143
144
| Flag | Effect |
145
|---|---|
146
| `--type calls` | Find circular call chains (default) |
147
| `--type imports` | Find circular import chains |
148
| `--type both` | Find both |
149
| `--min-length N` | Only report cycles with at least N nodes (default: 2) |
150
| `--format json` | Machine-readable output |
151
152
### Output
153
154
```
155
Import cycles (2 found):
156
157
Cycle 1 (length 3):
158
src/payments/processor.py
159
→ src/payments/validators.py
160
→ src/payments/utils.py
161
→ src/payments/processor.py
162
163
Cycle 2 (length 2):
164
src/auth/service.py
165
→ src/auth/models.py
166
→ src/auth/service.py
167
```
168
169
### Use cases
170
171
- CI gate: fail builds that introduce new circular imports
172
- Refactoring prep: identify modules to split before a large restructure
173
174
---
175
176
## Test mapping
177
178
`navegador test-map` maps test functions to the production code they exercise, using call graph analysis.
179
180
```bash
181
navegador test-map ./src ./tests
182
navegador test-map ./src ./tests --target process_payment
183
navegador test-map ./src ./tests --format json
184
```
185
186
### Options
187
188
| Flag | Effect |
189
|---|---|
190
| `--target <name>` | Only show tests that cover a specific function |
191
| `--uncovered` | Show production functions with no covering tests |
192
| `--format json` | Machine-readable output |
193
194
### Output
195
196
```
197
Test coverage map:
198
199
process_payment (src/payments/processor.py:56)
200
tests/payments/test_processor.py::test_process_payment_success
201
tests/payments/test_processor.py::test_process_payment_duplicate
202
tests/integration/test_checkout.py::test_full_checkout_flow
203
204
validate_token (src/auth/service.py:42)
205
tests/auth/test_service.py::test_validate_token_valid
206
tests/auth/test_service.py::test_validate_token_expired
207
208
Uncovered functions (4):
209
legacy_hash_password src/auth/legacy.py:14
210
_format_receipt_v1 src/payments/receipt.py:88
211
...
212
```
213
214
### Use cases
215
216
- Coverage by semantics, not just lines: see which tests actually call a function
217
- Regression targeting: when a function changes, which tests should run?
218
- Review prep: check that new code has corresponding tests before merging
219
220
---
221
222
## Combining analysis with knowledge
223
224
All analysis commands understand the knowledge layer. Add `--include-knowledge` to see rules, concepts, and decisions linked to the affected nodes:
225
226
```bash
227
navegador impact process_payment --include-knowledge
228
```
229
230
Output will include knowledge nodes like:
231
232
```
233
Governed by:
234
Rule: RequireIdempotencyKey (critical)
235
Concept: Idempotency
236
Decisions:
237
UseStripeForPayments (accepted, 2025-01-15)
238
```
239
240
---
241
242
## Python API
243
244
```python
245
from navegador.graph import GraphStore
246
from navegador.analysis import (
247
ImpactAnalyzer,
248
FlowTracer,
249
DeadCodeDetector,
250
CycleDetector,
251
TestMapper,
252
)
253
254
store = GraphStore.sqlite(".navegador/navegador.db")
255
256
# impact analysis
257
analyzer = ImpactAnalyzer(store)
258
result = analyzer.analyze("validate_token", depth=3)
259
print(result.direct_dependents)
260
print(result.transitive_dependents)
261
262
# flow tracing
263
tracer = FlowTracer(store)
264
paths = tracer.trace("create_order", "process_payment", max_paths=5)
265
for path in paths:
266
print(" -> ".join(path.nodes))
267
268
# dead code
269
detector = DeadCodeDetector(store)
270
candidates = detector.find("./src", exclude_tests=True)
271
for item in candidates:
272
print(f"{item.label}: {item.name} {item.file}:{item.line}")
273
274
# cycle detection
275
cycle_detector = CycleDetector(store)
276
cycles = cycle_detector.find_import_cycles("./src")
277
for cycle in cycles:
278
print(" -> ".join(cycle.path))
279
280
# test mapping
281
mapper = TestMapper(store)
282
coverage = mapper.map("./src", "./tests")
283
for fn, tests in coverage.items():
284
print(f"{fn}: {len(tests)} tests")
285
```
286
287
See the [Analysis API reference](../api/analysis.md) for full method signatures.
288

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button