Navegador

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

Keyboard Shortcuts

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