Navegador

navegador / docs / guide / context-loading.md
Source Rendered
Blame History Raw 314 lines
1
# Loading Context
2
3
These commands retrieve structured context from the graph. All commands support `--format json` for machine-readable output (useful in agent tool definitions) and default to rich terminal output.
4
5
---
6
7
## explain — universal lookup
8
9
`explain` is the single command for "what is this thing?" It works for any node type: functions, classes, files, concepts, rules, decisions, and domains.
10
11
```bash
12
navegador explain AuthService
13
navegador explain validate_token
14
navegador explain src/auth/service.py
15
navegador explain PaymentsMustBeIdempotent
16
```
17
18
Output includes:
19
- Node type, name, and properties
20
- Source location and docstring (for code nodes)
21
- Related knowledge (concepts, rules, decisions) via ANNOTATES edges
22
- Related code (for knowledge nodes) that implements or is governed by the node
23
24
```bash
25
navegador explain AuthService --format json
26
navegador explain AuthService --file src/auth/service.py # disambiguate by file
27
```
28
29
---
30
31
## context — file contents
32
33
Returns everything navegador knows about a file: the file node, its modules, classes, functions, imports, and their relationships.
34
35
```bash
36
navegador context src/auth/service.py
37
navegador context src/auth/service.py --format json
38
navegador context src/auth/service.py --format markdown
39
```
40
41
Useful as a pre-edit context load: give the agent the full graph context for a file before it starts editing.
42
43
---
44
45
## function — call graph view
46
47
Returns a function node with its callers, callees, decorators, containing class, and source.
48
49
```bash
50
navegador function validate_token
51
navegador function validate_token --file src/auth/service.py
52
navegador function validate_token --depth 2
53
navegador function validate_token --format json
54
```
55
56
`--depth` controls how many hops of the call graph to traverse (default: 1). At depth 2, you get callers-of-callers and callees-of-callees.
57
58
---
59
60
## class — hierarchy and references
61
62
Returns a class node with its methods, base classes, subclasses, and references from other files.
63
64
```bash
65
navegador class PaymentProcessor
66
navegador class PaymentProcessor --file src/payments/processor.py
67
navegador class PaymentProcessor --format json
68
```
69
70
Output includes:
71
- Class properties (file, line, docstring)
72
- Methods with signatures
73
- INHERITS chain (parents and children)
74
- IMPLEMENTS edges (for abstract base classes / interfaces)
75
- Files that import or reference this class
76
77
---
78
79
## concept — knowledge + implementing code
80
81
Returns a concept node with its rules, linked wiki pages, and annotated code nodes.
82
83
```bash
84
navegador concept Idempotency
85
navegador concept Idempotency --format json
86
```
87
88
Output includes:
89
- Concept description and domain
90
- Rules in the same domain that reference this concept
91
- WikiPage nodes linked via DOCUMENTS
92
- All code nodes (functions, classes, files) annotated with this concept via ANNOTATES edges
93
94
---
95
96
## domain — everything in a domain
97
98
Returns a domain and all nodes belonging to it: concepts, rules, decisions, people, and code annotated via those knowledge nodes.
99
100
```bash
101
navegador domain Payments
102
navegador domain Payments --format json
103
```
104
105
Useful for onboarding: a new contributor can run `navegador domain Payments` to get the full business context before reading any code.
106
107
---
108
109
## search — text search across the graph
110
111
```bash
112
navegador search "rate limit"
113
```
114
115
By default, searches function and class names. Flags expand the scope:
116
117
| Flag | What it searches |
118
|---|---|
119
| (default) | Function, class, method names |
120
| `--all` | Names + docstrings + knowledge layer (concepts, rules, decisions, wiki) |
121
| `--docs` | Docstrings and wiki page content only |
122
| `--limit N` | Max results (default: 20) |
123
| `--format json` | JSON output |
124
125
Examples:
126
127
```bash
128
# find anything about rate limiting, anywhere
129
navegador search "rate limit" --all
130
131
# find code with docstrings mentioning retry logic
132
navegador search "retry" --docs
133
134
# search with a higher limit
135
navegador search "auth" --all --limit 50 --format json
136
```
137
138
---
139
140
## decorated — find by decorator
141
142
Find all functions and classes that use a specific decorator:
143
144
```bash
145
navegador decorated login_required
146
navegador decorated pytest.mark.parametrize
147
navegador decorated --format json login_required
148
```
149
150
Returns function/class nodes with their file paths, line numbers, and the full decorator expression.
151
152
---
153
154
## impact — blast radius analysis
155
156
Return the set of code nodes that could be affected if a given node changes, traversing CALLS, IMPORTS, and INHERITS edges transitively.
157
158
```bash
159
navegador impact validate_token
160
navegador impact validate_token --depth 3
161
navegador impact validate_token --format json
162
```
163
164
Useful before a refactor to understand the blast radius.
165
166
---
167
168
## trace — execution flow
169
170
Trace the execution path through the call graph from a starting function:
171
172
```bash
173
navegador trace process_payment
174
navegador trace process_payment --depth 4 --format json
175
```
176
177
Output shows the call chain as a tree, with each node annotated by file and line.
178
179
---
180
181
## diff — graph diff between refs
182
183
Show what changed in the graph between two Git refs:
184
185
```bash
186
navegador diff HEAD~1 HEAD
187
navegador diff main feature-branch
188
```
189
190
Reports added, removed, and changed nodes and edges.
191
192
---
193
194
## churn — code churn analysis
195
196
Identify files and functions that change most frequently, based on Git history:
197
198
```bash
199
navegador churn
200
navegador churn --days 30
201
navegador churn --format json
202
```
203
204
High-churn nodes are often candidates for stabilization or better test coverage.
205
206
---
207
208
## deadcode — find unreachable code
209
210
Find functions and classes with no callers and no references from outside their defining file:
211
212
```bash
213
navegador deadcode
214
navegador deadcode --format json
215
```
216
217
---
218
219
## cycles — dependency cycle detection
220
221
Detect cycles in the IMPORTS and CALLS graphs:
222
223
```bash
224
navegador cycles
225
navegador cycles --format json
226
```
227
228
Reports each cycle as an ordered list of node names.
229
230
---
231
232
## testmap — test-to-source mapping
233
234
Map test functions to the source functions they exercise (based on naming conventions and import analysis):
235
236
```bash
237
navegador testmap
238
navegador testmap src/auth/service.py
239
navegador testmap --format json
240
```
241
242
Creates `TESTS` edges between test functions and their targets.
243
244
---
245
246
## semantic-search — vector similarity search
247
248
Search using natural language against embeddings of docstrings and code. Requires `pip install "navegador[llm]"`.
249
250
```bash
251
navegador semantic-search "functions that validate user input"
252
navegador semantic-search "payment retry logic" --limit 10
253
```
254
255
---
256
257
## ask — NLP query interface
258
259
Ask a natural language question about the codebase. Requires `pip install "navegador[llm]"`.
260
261
```bash
262
navegador ask "What handles authentication in this codebase?"
263
navegador ask "Which functions touch the database?"
264
```
265
266
The answer is grounded in graph queries — not hallucinated from code text.
267
268
---
269
270
## rename — coordinated rename
271
272
Rename a function or class across the graph and get a list of all files that reference the old name:
273
274
```bash
275
navegador rename validate_token validate_access_token
276
```
277
278
Output is a structured change plan. The command does not modify source files — it produces the list of locations to update.
279
280
---
281
282
## codeowners — ownership queries
283
284
Query CODEOWNERS assignments and domain ownership:
285
286
```bash
287
navegador codeowners src/auth/service.py
288
navegador codeowners AuthService
289
```
290
291
Returns owning teams and people from CODEOWNERS file and from `Person` nodes annotated to the matching code nodes.
292
293
---
294
295
## communities — module cluster detection
296
297
Detect communities of highly-coupled modules using graph clustering:
298
299
```bash
300
navegador communities
301
navegador communities --format json
302
```
303
304
---
305
306
## explore — interactive graph explorer
307
308
Open an interactive graph explorer in the terminal:
309
310
```bash
311
navegador explore
312
navegador explore --start AuthService
313
```
314

Keyboard Shortcuts

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