codegraph-nav 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- codegraph_nav/__init__.py +194 -0
- codegraph_nav/ast_grep_analyzer.py +448 -0
- codegraph_nav/cli.py +223 -0
- codegraph_nav/code_navigator.py +1328 -0
- codegraph_nav/code_search.py +1009 -0
- codegraph_nav/colors.py +209 -0
- codegraph_nav/completions.py +354 -0
- codegraph_nav/dart_analyzer.py +301 -0
- codegraph_nav/dependency_graph.py +814 -0
- codegraph_nav/domain/__init__.py +20 -0
- codegraph_nav/domain/routes.py +337 -0
- codegraph_nav/domain/schemas.py +229 -0
- codegraph_nav/domain/tags.py +87 -0
- codegraph_nav/exporters.py +563 -0
- codegraph_nav/go_analyzer.py +273 -0
- codegraph_nav/graph/__init__.py +72 -0
- codegraph_nav/graph/builder.py +409 -0
- codegraph_nav/graph/communities.py +402 -0
- codegraph_nav/graph/flows.py +311 -0
- codegraph_nav/graph/query.py +380 -0
- codegraph_nav/graph/schema.py +266 -0
- codegraph_nav/graph/search.py +257 -0
- codegraph_nav/graph/store.py +517 -0
- codegraph_nav/hints.py +195 -0
- codegraph_nav/import_resolver.py +891 -0
- codegraph_nav/js_ts_analyzer.py +564 -0
- codegraph_nav/line_reader.py +664 -0
- codegraph_nav/mcp/__init__.py +39 -0
- codegraph_nav/mcp/__main__.py +5 -0
- codegraph_nav/mcp/server.py +2228 -0
- codegraph_nav/py.typed +2 -0
- codegraph_nav/ruby_analyzer.py +259 -0
- codegraph_nav/rust_analyzer.py +379 -0
- codegraph_nav/token_efficient_renderer.py +743 -0
- codegraph_nav/watcher.py +382 -0
- codegraph_nav-0.1.0.dist-info/METADATA +487 -0
- codegraph_nav-0.1.0.dist-info/RECORD +41 -0
- codegraph_nav-0.1.0.dist-info/WHEEL +5 -0
- codegraph_nav-0.1.0.dist-info/entry_points.txt +4 -0
- codegraph_nav-0.1.0.dist-info/licenses/LICENSE +21 -0
- codegraph_nav-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,487 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: codegraph-nav
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Graph-intelligent, token-efficient code navigation for AI assistants. Surgical reading, execution flows, risk scoring, and micro-metadata rendering.
|
|
5
|
+
Author-email: Efren Bautista <ing.efrenbl@gmail.com>
|
|
6
|
+
Maintainer-email: Efren Bautista <ing.efrenbl@gmail.com>
|
|
7
|
+
License: MIT
|
|
8
|
+
Project-URL: Homepage, https://github.com/efrenbl/codegraph-nav
|
|
9
|
+
Project-URL: Documentation, https://github.com/efrenbl/codegraph-nav#readme
|
|
10
|
+
Project-URL: Repository, https://github.com/efrenbl/codegraph-nav.git
|
|
11
|
+
Project-URL: Issues, https://github.com/efrenbl/codegraph-nav/issues
|
|
12
|
+
Project-URL: Changelog, https://github.com/efrenbl/codegraph-nav/blob/main/CHANGELOG.md
|
|
13
|
+
Keywords: mcp,model-context-protocol,code-navigation,code-graph,token-optimization,ast,code-search,execution-flows,risk-scoring,developer-tools,ai-coding,claude
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Environment :: Console
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
18
|
+
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Topic :: Software Development
|
|
24
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
25
|
+
Classifier: Topic :: Text Processing :: Indexing
|
|
26
|
+
Classifier: Topic :: Utilities
|
|
27
|
+
Requires-Python: >=3.10
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
License-File: LICENSE
|
|
30
|
+
Provides-Extra: mcp
|
|
31
|
+
Requires-Dist: mcp>=1.0.0; extra == "mcp"
|
|
32
|
+
Provides-Extra: dev
|
|
33
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
34
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
35
|
+
Requires-Dist: black>=23.0.0; extra == "dev"
|
|
36
|
+
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
37
|
+
Requires-Dist: mypy>=1.0.0; extra == "dev"
|
|
38
|
+
Requires-Dist: build>=1.0.0; extra == "dev"
|
|
39
|
+
Requires-Dist: twine>=4.0.0; extra == "dev"
|
|
40
|
+
Requires-Dist: mcp>=1.0.0; extra == "dev"
|
|
41
|
+
Provides-Extra: ast
|
|
42
|
+
Requires-Dist: tree-sitter>=0.23.0; python_version >= "3.9" and extra == "ast"
|
|
43
|
+
Requires-Dist: tree-sitter-javascript>=0.23.0; python_version >= "3.9" and extra == "ast"
|
|
44
|
+
Requires-Dist: tree-sitter-typescript>=0.23.0; python_version >= "3.9" and extra == "ast"
|
|
45
|
+
Requires-Dist: tree-sitter-ruby>=0.23.0; python_version >= "3.9" and extra == "ast"
|
|
46
|
+
Requires-Dist: tree-sitter-go>=0.23.0; python_version >= "3.9" and extra == "ast"
|
|
47
|
+
Requires-Dist: tree-sitter-rust>=0.23.0; python_version >= "3.9" and extra == "ast"
|
|
48
|
+
Provides-Extra: dart
|
|
49
|
+
Requires-Dist: tree-sitter>=0.23.0; python_version >= "3.9" and extra == "dart"
|
|
50
|
+
Requires-Dist: tree-sitter-dart>=0.1.0; python_version >= "3.9" and extra == "dart"
|
|
51
|
+
Provides-Extra: graph
|
|
52
|
+
Requires-Dist: networkx>=3.0; extra == "graph"
|
|
53
|
+
Requires-Dist: numpy>=1.21; extra == "graph"
|
|
54
|
+
Requires-Dist: scipy>=1.7; extra == "graph"
|
|
55
|
+
Provides-Extra: fast
|
|
56
|
+
Requires-Dist: ast-grep-py>=0.40.0; extra == "fast"
|
|
57
|
+
Provides-Extra: all
|
|
58
|
+
Requires-Dist: mcp>=1.0.0; extra == "all"
|
|
59
|
+
Requires-Dist: tree-sitter>=0.23.0; extra == "all"
|
|
60
|
+
Requires-Dist: tree-sitter-javascript>=0.23.0; extra == "all"
|
|
61
|
+
Requires-Dist: tree-sitter-typescript>=0.23.0; extra == "all"
|
|
62
|
+
Requires-Dist: tree-sitter-ruby>=0.23.0; extra == "all"
|
|
63
|
+
Requires-Dist: tree-sitter-go>=0.23.0; extra == "all"
|
|
64
|
+
Requires-Dist: tree-sitter-rust>=0.23.0; extra == "all"
|
|
65
|
+
Requires-Dist: tree-sitter-dart>=0.1.0; extra == "all"
|
|
66
|
+
Requires-Dist: networkx>=3.0; extra == "all"
|
|
67
|
+
Requires-Dist: numpy>=1.21; extra == "all"
|
|
68
|
+
Requires-Dist: scipy>=1.7; extra == "all"
|
|
69
|
+
Requires-Dist: ast-grep-py>=0.40.0; extra == "all"
|
|
70
|
+
Dynamic: license-file
|
|
71
|
+
|
|
72
|
+
<p align="center">
|
|
73
|
+
<img src="https://img.shields.io/badge/MCP-1.0+-blue.svg" alt="MCP 1.0+">
|
|
74
|
+
<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+">
|
|
75
|
+
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
|
|
76
|
+
<img src="https://img.shields.io/badge/version-0.1.0-orange.svg" alt="Version 0.1.0">
|
|
77
|
+
<img src="https://img.shields.io/badge/tools-19-purple.svg" alt="19 MCP Tools">
|
|
78
|
+
</p>
|
|
79
|
+
|
|
80
|
+
<h1 align="center">codegraph-nav</h1>
|
|
81
|
+
|
|
82
|
+
<p align="center">
|
|
83
|
+
<strong>Graph-intelligent, token-efficient code navigation for AI assistants</strong>
|
|
84
|
+
</p>
|
|
85
|
+
|
|
86
|
+
<p align="center">
|
|
87
|
+
<em>Surgical reading, execution flows, blast radius, risk scoring — 97% fewer tokens</em>
|
|
88
|
+
</p>
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## What is codegraph-nav?
|
|
93
|
+
|
|
94
|
+
codegraph-nav is an **MCP server** that helps AI assistants explore codebases efficiently. Beyond basic search and read, it adds **graph intelligence**: blast radius analysis, execution flow tracing, risk-scored diffs, and community detection.
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
98
|
+
│ WITHOUT CODEGRAPH-NAV │
|
|
99
|
+
├─────────────────────────────────────────────────────────────┤
|
|
100
|
+
│ User: "Fix the payment bug" │
|
|
101
|
+
│ │
|
|
102
|
+
│ Claude reads: │
|
|
103
|
+
│ • payments.py (500 lines) → 7,500 tokens │
|
|
104
|
+
│ • billing.py (300 lines) → 4,500 tokens │
|
|
105
|
+
│ • models/order.py (200 lines) → 3,000 tokens │
|
|
106
|
+
│ ───────────────────────────────────────────── │
|
|
107
|
+
│ Total: 15,000 tokens │
|
|
108
|
+
└─────────────────────────────────────────────────────────────┘
|
|
109
|
+
|
|
110
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
111
|
+
│ WITH CODEGRAPH-NAV │
|
|
112
|
+
├─────────────────────────────────────────────────────────────┤
|
|
113
|
+
│ User: "Fix the payment bug" │
|
|
114
|
+
│ │
|
|
115
|
+
│ 1. codegraph_get_minimal_context → 100 tokens │
|
|
116
|
+
│ 2. codegraph_search("payment") → 100 tokens │
|
|
117
|
+
│ 3. codegraph_read(payments.py, 45, 89) → 400 tokens │
|
|
118
|
+
│ 4. codegraph_blast_radius → 100 tokens │
|
|
119
|
+
│ ───────────────────────────────────────────── │
|
|
120
|
+
│ Total: 700 tokens │
|
|
121
|
+
│ │
|
|
122
|
+
│ SAVINGS: 95% fewer tokens + impact analysis! │
|
|
123
|
+
└─────────────────────────────────────────────────────────────┘
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Quick Start
|
|
129
|
+
|
|
130
|
+
### 1. Install
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
pip install codegraph-nav[mcp] # MCP server + core
|
|
134
|
+
pip install codegraph-nav[all] # Everything (tree-sitter, networkx, ast-grep)
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### 2. Configure Claude Code (CLI)
|
|
138
|
+
|
|
139
|
+
Add to `~/.claude/mcp.json`:
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"mcpServers": {
|
|
144
|
+
"codegraph-nav": {
|
|
145
|
+
"command": "codegraph-nav-mcp"
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### 3. Configure Claude Desktop
|
|
152
|
+
|
|
153
|
+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
154
|
+
|
|
155
|
+
```json
|
|
156
|
+
{
|
|
157
|
+
"mcpServers": {
|
|
158
|
+
"codegraph-nav": {
|
|
159
|
+
"command": "codegraph-nav-mcp"
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### 4. Use It
|
|
166
|
+
|
|
167
|
+
In Claude, just ask to explore your codebase:
|
|
168
|
+
|
|
169
|
+
```
|
|
170
|
+
"Scan this project and find the payment function"
|
|
171
|
+
"What's the blast radius if I change auth.py?"
|
|
172
|
+
"Show me the architecture of this codebase"
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Claude will automatically use codegraph-nav's 19 tools to explore efficiently.
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Available Tools
|
|
180
|
+
|
|
181
|
+
### Core Navigation
|
|
182
|
+
|
|
183
|
+
| Tool | Purpose | When to Use |
|
|
184
|
+
|------|---------|-------------|
|
|
185
|
+
| `codegraph_get_minimal_context` | ~100 token project orientation | **Always use first** |
|
|
186
|
+
| `codegraph_scan` | Index codebase to `.codegraph.json` | First time on a project |
|
|
187
|
+
| `codegraph_search` | Find symbols by name/pattern | Looking for functions/classes |
|
|
188
|
+
| `codegraph_read` | Read specific line ranges | After finding symbol locations |
|
|
189
|
+
| `codegraph_stats` | Codebase size overview | Understanding project scale |
|
|
190
|
+
| `codegraph_get_hubs` | Find central files (PageRank) | Architecture analysis |
|
|
191
|
+
| `codegraph_get_structure` | File symbol outline | Before reading a file |
|
|
192
|
+
| `codegraph_get_dependencies` | Import/export graph | Understanding coupling |
|
|
193
|
+
| `codegraph_test_gaps` | Find untested symbols | Before/after changes |
|
|
194
|
+
|
|
195
|
+
### Graph Intelligence
|
|
196
|
+
|
|
197
|
+
| Tool | Purpose | When to Use |
|
|
198
|
+
|------|---------|-------------|
|
|
199
|
+
| `codegraph_graph_build` | Build graph DB (`.codegraph.db`) | Before heavy graph analysis |
|
|
200
|
+
| `codegraph_blast_radius` | Impact analysis (recursive CTE) | "What breaks if I change this?" |
|
|
201
|
+
| `codegraph_list_flows` | Execution flows + criticality | Understanding call chains |
|
|
202
|
+
| `codegraph_detect_changes` | Risk-scored git diff | Code review / PR analysis |
|
|
203
|
+
| `codegraph_search_graph` | FTS5 + fuzzy + RRF search | Search by concept, not just name |
|
|
204
|
+
|
|
205
|
+
### Architecture & Domain
|
|
206
|
+
|
|
207
|
+
| Tool | Purpose | When to Use |
|
|
208
|
+
|------|---------|-------------|
|
|
209
|
+
| `codegraph_list_communities` | Code communities + cohesion | Architecture grouping |
|
|
210
|
+
| `codegraph_get_community` | Community details + members | Explore a community |
|
|
211
|
+
| `codegraph_get_architecture_overview` | Architecture summary | High-level structure |
|
|
212
|
+
| `codegraph_list_routes` | HTTP routes (15+ frameworks) | API/route exploration |
|
|
213
|
+
| `codegraph_list_schemas` | ORM schemas (8+ ORMs) | Data model exploration |
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## How It Works
|
|
218
|
+
|
|
219
|
+
```mermaid
|
|
220
|
+
flowchart TB
|
|
221
|
+
subgraph SCAN["Step 1: Scan"]
|
|
222
|
+
A[(Codebase)] --> B[codegraph_scan]
|
|
223
|
+
B --> C[.codegraph.json]
|
|
224
|
+
end
|
|
225
|
+
|
|
226
|
+
subgraph NAVIGATE["Step 2: Navigate"]
|
|
227
|
+
D[codegraph_search] --> E[file:line locations]
|
|
228
|
+
E --> F[codegraph_read]
|
|
229
|
+
F --> G[Only needed code]
|
|
230
|
+
end
|
|
231
|
+
|
|
232
|
+
subgraph GRAPH["Step 3: Analyze"]
|
|
233
|
+
C --> H[codegraph_graph_build]
|
|
234
|
+
H --> I[.codegraph.db]
|
|
235
|
+
I --> J[blast_radius / flows / risk]
|
|
236
|
+
end
|
|
237
|
+
|
|
238
|
+
C --> D
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
1. **Scan once** - Creates `.codegraph.json` with all symbols indexed
|
|
242
|
+
2. **Search & read surgically** - Find symbols and load only the lines you need
|
|
243
|
+
3. **Graph analysis** - Build `.codegraph.db` for blast radius, flows, and risk scoring
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## Example Session
|
|
248
|
+
|
|
249
|
+
```
|
|
250
|
+
1. codegraph_get_minimal_context(path="/project", task="fix auth bug")
|
|
251
|
+
→ project: 142 files · 1847 symbols · py,js
|
|
252
|
+
→ hubs: config.py(8←), models.py(5←)
|
|
253
|
+
→ suggest: codegraph_search → codegraph_read → codegraph_get_dependencies
|
|
254
|
+
|
|
255
|
+
2. codegraph_search(query="authenticate")
|
|
256
|
+
→ src/auth.py:L10-30 [fn] authenticate
|
|
257
|
+
|
|
258
|
+
3. codegraph_read(file_path="src/auth.py", start_line=10, end_line=30)
|
|
259
|
+
→ Only those 20 lines (~200 tokens)
|
|
260
|
+
|
|
261
|
+
4. codegraph_blast_radius(path="/project", changed_files=["src/auth.py"])
|
|
262
|
+
→ blast(auth.py): 12 nodes · 5 files impacted
|
|
263
|
+
|
|
264
|
+
5. codegraph_detect_changes(path="/project")
|
|
265
|
+
→ risk: 0.78 HIGH | 3 files · 8 symbols changed
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
---
|
|
269
|
+
|
|
270
|
+
## Detail Levels
|
|
271
|
+
|
|
272
|
+
All tools accept a `detail_level` parameter:
|
|
273
|
+
|
|
274
|
+
- **`minimal`** (default) - Compact, token-efficient output
|
|
275
|
+
- **`standard`** - Adds signatures, language breakdown, bidirectional counts
|
|
276
|
+
- **`verbose`** - Adds docstrings, dependency chains, per-file details
|
|
277
|
+
|
|
278
|
+
---
|
|
279
|
+
|
|
280
|
+
## Workflow Prompts
|
|
281
|
+
|
|
282
|
+
5 built-in prompts that enforce token discipline:
|
|
283
|
+
|
|
284
|
+
| Prompt | Use Case |
|
|
285
|
+
|--------|----------|
|
|
286
|
+
| `investigate_bug` | Bug investigation: orient, search, read, dependencies |
|
|
287
|
+
| `add_feature` | Feature implementation: orient, search similar, structure, read |
|
|
288
|
+
| `review_changes` | Code review: orient, test gaps, search changed, read |
|
|
289
|
+
| `understand_architecture` | Architecture analysis: orient, hubs, dependencies, structure |
|
|
290
|
+
| `onboard_project` | Project onboarding: orient, stats, hubs, structure |
|
|
291
|
+
|
|
292
|
+
Each prompt starts with `codegraph_get_minimal_context` and defaults to `detail_level="minimal"`.
|
|
293
|
+
|
|
294
|
+
---
|
|
295
|
+
|
|
296
|
+
## Supported Languages
|
|
297
|
+
|
|
298
|
+
| Language | Analysis Type | Quality |
|
|
299
|
+
|----------|---------------|---------|
|
|
300
|
+
| Python | Full AST (stdlib) | ⭐⭐⭐⭐⭐ |
|
|
301
|
+
| JavaScript | AST (tree-sitter)* | ⭐⭐⭐⭐⭐ |
|
|
302
|
+
| TypeScript | AST (tree-sitter)* | ⭐⭐⭐⭐⭐ |
|
|
303
|
+
| Ruby | AST (tree-sitter)* | ⭐⭐⭐⭐ |
|
|
304
|
+
| Go | AST (tree-sitter)* | ⭐⭐⭐⭐ |
|
|
305
|
+
| Rust | AST (tree-sitter)* | ⭐⭐⭐⭐ |
|
|
306
|
+
| Dart / Flutter | AST (tree-sitter)** | ⭐⭐⭐⭐ |
|
|
307
|
+
| Java | Regex-based | ⭐⭐⭐ |
|
|
308
|
+
| C/C++ | Regex-based | ⭐⭐⭐ |
|
|
309
|
+
| PHP | Regex-based | ⭐⭐⭐ |
|
|
310
|
+
|
|
311
|
+
*Install tree-sitter support: `pip install codegraph-nav[ast]`
|
|
312
|
+
All tree-sitter analyzers fall back to regex when tree-sitter is not installed.
|
|
313
|
+
|
|
314
|
+
**Dart/Flutter ships as its own extra: `pip install codegraph-nav[dart]`. The
|
|
315
|
+
grammar (`tree-sitter-dart`) provides pre-compiled wheels for Linux/macOS/Windows
|
|
316
|
+
— no C compiler needed. Without it, Dart falls back to the regex analyzer
|
|
317
|
+
(classes, mixins, enums, extensions, top-level functions). Flutter needs no
|
|
318
|
+
separate grammar; widgets are ordinary Dart classes.
|
|
319
|
+
|
|
320
|
+
---
|
|
321
|
+
|
|
322
|
+
## Micro-Metadata Format
|
|
323
|
+
|
|
324
|
+
The scan output uses a compact ASCII tree with inline metadata:
|
|
325
|
+
|
|
326
|
+
```
|
|
327
|
+
my-project/
|
|
328
|
+
├── src/
|
|
329
|
+
│ ├── api/
|
|
330
|
+
│ │ ├── client.py [C:APIClient M:get,post] (5←)
|
|
331
|
+
│ │ └── routes.py [F:handle,validate] (3←)
|
|
332
|
+
│ └── core/
|
|
333
|
+
│ └── config.py [C:Config M:load] (Hub:8←)
|
|
334
|
+
└── tests/
|
|
335
|
+
└── test_api.py [F:test_client]
|
|
336
|
+
|
|
337
|
+
═══ Summary ═══
|
|
338
|
+
28 files · 142 symbols · 12 hubs
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
Each file shows: classes (C:), functions (F:), methods (M:), and importer count (N←).
|
|
342
|
+
|
|
343
|
+
---
|
|
344
|
+
|
|
345
|
+
## CLI Usage
|
|
346
|
+
|
|
347
|
+
```bash
|
|
348
|
+
# Generate code map
|
|
349
|
+
codegraph-nav scan /path/to/project
|
|
350
|
+
cgn scan . # Short alias
|
|
351
|
+
|
|
352
|
+
# Search for symbols
|
|
353
|
+
cgn search "process_payment"
|
|
354
|
+
cgn search -t class -o table
|
|
355
|
+
|
|
356
|
+
# Read specific lines
|
|
357
|
+
cgn read src/payments.py 45-89
|
|
358
|
+
cgn read src/payments.py 45-89 -c 3 # With context
|
|
359
|
+
|
|
360
|
+
# Get codebase stats
|
|
361
|
+
cgn stats
|
|
362
|
+
|
|
363
|
+
# Incremental update (only changed files)
|
|
364
|
+
cgn scan --incremental .
|
|
365
|
+
|
|
366
|
+
# Export as markdown
|
|
367
|
+
cgn export -f markdown -o docs/codebase.md
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
---
|
|
371
|
+
|
|
372
|
+
## Python API
|
|
373
|
+
|
|
374
|
+
```python
|
|
375
|
+
from codegraph_nav import CodeNavigator, CodeSearcher, LineReader
|
|
376
|
+
|
|
377
|
+
# Scan
|
|
378
|
+
navigator = CodeNavigator("/path/to/project")
|
|
379
|
+
code_map = navigator.scan()
|
|
380
|
+
|
|
381
|
+
# Search
|
|
382
|
+
searcher = CodeSearcher(".codegraph.json")
|
|
383
|
+
results = searcher.search_symbol("payment", symbol_type="function")
|
|
384
|
+
|
|
385
|
+
# Read surgically
|
|
386
|
+
reader = LineReader(root_path="/path/to/project")
|
|
387
|
+
content = reader.read_lines("src/pay.py", 45, 89)
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
### Graph API
|
|
391
|
+
|
|
392
|
+
```python
|
|
393
|
+
from codegraph_nav.graph import GraphStore, GraphBuilder, get_blast_radius, trace_flows
|
|
394
|
+
|
|
395
|
+
# Build graph from code map
|
|
396
|
+
store = GraphStore(".codegraph.db")
|
|
397
|
+
builder = GraphBuilder(store)
|
|
398
|
+
stats = builder.build_from_code_map(code_map)
|
|
399
|
+
|
|
400
|
+
# Blast radius
|
|
401
|
+
impact = get_blast_radius(store, changed_files=["src/auth.py"])
|
|
402
|
+
print(f"{impact['impacted_nodes']} nodes, {len(impact['impacted_files'])} files affected")
|
|
403
|
+
|
|
404
|
+
# Execution flows
|
|
405
|
+
flows = trace_flows(store)
|
|
406
|
+
for f in flows[:5]:
|
|
407
|
+
print(f"{f['name']} crit:{f['criticality']:.2f} depth:{f['depth']}")
|
|
408
|
+
|
|
409
|
+
store.close()
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
### Domain Intelligence API
|
|
413
|
+
|
|
414
|
+
```python
|
|
415
|
+
from codegraph_nav.domain import detect_routes, detect_schemas, infer_project_tags
|
|
416
|
+
|
|
417
|
+
# Detect routes (FastAPI, Express, Django, Gin, etc.)
|
|
418
|
+
routes = detect_routes(code_map, root_path="/path/to/project")
|
|
419
|
+
|
|
420
|
+
# Detect ORM schemas (SQLAlchemy, Django, Prisma, etc.)
|
|
421
|
+
schemas = detect_schemas(code_map, root_path="/path/to/project")
|
|
422
|
+
|
|
423
|
+
# Infer domain tags (auth, db, cache, api, etc.)
|
|
424
|
+
tags = infer_project_tags(code_map)
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
---
|
|
428
|
+
|
|
429
|
+
## Optional Dependencies
|
|
430
|
+
|
|
431
|
+
| Extra | What it adds |
|
|
432
|
+
|-------|-------------|
|
|
433
|
+
| `[mcp]` | MCP server (FastMCP) |
|
|
434
|
+
| `[ast]` | Tree-sitter analyzers (JS/TS/Ruby/Go/Rust) |
|
|
435
|
+
| `[graph]` | PageRank hub detection (networkx) |
|
|
436
|
+
| `[fast]` | ast-grep high-perf parsing |
|
|
437
|
+
| `[all]` | Everything above |
|
|
438
|
+
| `[dev]` | pytest, mypy, black, ruff, build, twine |
|
|
439
|
+
|
|
440
|
+
---
|
|
441
|
+
|
|
442
|
+
## Performance
|
|
443
|
+
|
|
444
|
+
Tested on real-world open source projects:
|
|
445
|
+
|
|
446
|
+
| Project | Files | Symbols | Map Size | Map Time |
|
|
447
|
+
|---------|-------|---------|----------|----------|
|
|
448
|
+
| Flask | 142 | 1,847 | 89 KB | 0.8s |
|
|
449
|
+
| Django | 2,156 | 28,493 | 1.2 MB | 8.2s |
|
|
450
|
+
| requests | 47 | 412 | 23 KB | 0.3s |
|
|
451
|
+
|
|
452
|
+
**Token savings:**
|
|
453
|
+
- Small projects (50-100 files): 85-90% reduction
|
|
454
|
+
- Medium projects (100-500 files): 92-96% reduction
|
|
455
|
+
- Large projects (500+ files): 97-99% reduction
|
|
456
|
+
|
|
457
|
+
---
|
|
458
|
+
|
|
459
|
+
## Development
|
|
460
|
+
|
|
461
|
+
```bash
|
|
462
|
+
git clone https://github.com/efrenbl/codegraph-nav.git
|
|
463
|
+
cd codegraph-nav
|
|
464
|
+
python3 -m venv .venv && source .venv/bin/activate
|
|
465
|
+
pip install -e ".[dev]"
|
|
466
|
+
python3 -m pytest tests/ -v
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
471
|
+
## Requirements
|
|
472
|
+
|
|
473
|
+
- Python 3.10+
|
|
474
|
+
- MCP SDK 1.0+ (for MCP server only)
|
|
475
|
+
|
|
476
|
+
---
|
|
477
|
+
|
|
478
|
+
## License
|
|
479
|
+
|
|
480
|
+
MIT License - see [LICENSE](LICENSE) for details.
|
|
481
|
+
|
|
482
|
+
---
|
|
483
|
+
|
|
484
|
+
<p align="center">
|
|
485
|
+
<strong>Stop burning tokens reading entire files.</strong><br>
|
|
486
|
+
<em>Scan once, search instantly, read surgically, analyze impact.</em>
|
|
487
|
+
</p>
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
codegraph_nav/__init__.py,sha256=ZuN7Re7TS1qrKWxTWdH7pVmUO9SwcVxLvqphnywWTp0,5412
|
|
2
|
+
codegraph_nav/ast_grep_analyzer.py,sha256=vQy-6B1kHg-nE3-sU1CZpjC5JAcgSsgIlx0ghh-chGI,15583
|
|
3
|
+
codegraph_nav/cli.py,sha256=EWrLsyMYJ9F2w-_4eAbV6RjrE-g-_3Q0Sni4rWaNwJo,8221
|
|
4
|
+
codegraph_nav/code_navigator.py,sha256=3_mQhUH0i7amqef_F9Sz9GxLa40IXuuBIuoMPogcQDY,46406
|
|
5
|
+
codegraph_nav/code_search.py,sha256=UlhKjzjGS7NPl2KFrgoPe6SzaYArg-AgclZITfCT668,36717
|
|
6
|
+
codegraph_nav/colors.py,sha256=WsaeB32x1GiXumXP-B5Zcam9tXwOCQMNL1xy4FvYQ6c,6170
|
|
7
|
+
codegraph_nav/completions.py,sha256=604d40Nl6MZBsl_hP45oWd9iQ20U0lK6nxm9A5AmGrQ,12960
|
|
8
|
+
codegraph_nav/dart_analyzer.py,sha256=R3p1lSQ2C-XgJ-YxF_501vcB-4nR9uOIeGpL6ADYGFw,10033
|
|
9
|
+
codegraph_nav/dependency_graph.py,sha256=zjnjw_aihSTF-Ak5ET5vAf_vLyGPPTJd_FhNJC29hxc,27769
|
|
10
|
+
codegraph_nav/exporters.py,sha256=Eadw9IZOAf0odLwlCol3Y-nJDr7zv32j9cupSWlZ73c,18908
|
|
11
|
+
codegraph_nav/go_analyzer.py,sha256=nxOdb4EiTQsl5vzncK8jy4-hVFSZJqI4TLYhDefn-Eg,9307
|
|
12
|
+
codegraph_nav/hints.py,sha256=79B7BqC3gmIxjhMxwXpUWCPtC3yIuh9gBwuQ5GgaZmM,5848
|
|
13
|
+
codegraph_nav/import_resolver.py,sha256=6EBCyAS1i9I3q7KrJK1cpbXnZ8bnyJL94B0dET66dYQ,31460
|
|
14
|
+
codegraph_nav/js_ts_analyzer.py,sha256=98mVVYiYOGOKXVmZMKETv9oJ3cr9uAGrV3gbWgRQXxY,17716
|
|
15
|
+
codegraph_nav/line_reader.py,sha256=IzTrSonYBqJjqHGHAYKqUT3FD7TlpIUVloZmkSDodwQ,23955
|
|
16
|
+
codegraph_nav/py.typed,sha256=ixa8YukDZ3kLo0WsFJRGohLMyHzbMur1ALmmASML2cs,64
|
|
17
|
+
codegraph_nav/ruby_analyzer.py,sha256=YN8IN-nQsGGIjbTNhcjqfav8E_QqyO230JHyeVzA28Y,8191
|
|
18
|
+
codegraph_nav/rust_analyzer.py,sha256=W_xCtVAuDhrY3v3YPkkFqD5Zm-W8YYa26E8eCJjPp4U,12438
|
|
19
|
+
codegraph_nav/token_efficient_renderer.py,sha256=t0GFBx8Hb0JPf9ufCOYownMqLpqxhq2gsHluyFvNhWg,25544
|
|
20
|
+
codegraph_nav/watcher.py,sha256=nyFDDBVVIUsGED1qnLtSWKVJf6IPKfLpUlxEX36Q-PI,13364
|
|
21
|
+
codegraph_nav/domain/__init__.py,sha256=uZLdlXBVRs0RsdQzEA7cXkfQlMj715d9dcidHGbU4Z8,597
|
|
22
|
+
codegraph_nav/domain/routes.py,sha256=QH4-hPV7GiTG3a8jlGgv75F0KC5qfDImgGOQh6QfG74,12149
|
|
23
|
+
codegraph_nav/domain/schemas.py,sha256=0MdDVzZaKb-W0_DSQgWQUlewkfYXkx8lRbuCizdyPtM,8398
|
|
24
|
+
codegraph_nav/domain/tags.py,sha256=ELfK-G_aU78x5xhqIOPrgpPqeDa7I-KfNBEGW0DEW3Q,2535
|
|
25
|
+
codegraph_nav/graph/__init__.py,sha256=5uBSxtelgV0pCAVNVoOFATd_-Zj1PdXaQyaBZ1OQRiM,1609
|
|
26
|
+
codegraph_nav/graph/builder.py,sha256=JNWwnXHJYNyANcEZRl2cMppA51VMEIZy0uTJK1KIIPA,14451
|
|
27
|
+
codegraph_nav/graph/communities.py,sha256=vHs9Gea2bopTcbprdzEUZoVl_fxMXcsxA5pRl69AvB4,12328
|
|
28
|
+
codegraph_nav/graph/flows.py,sha256=6JOTnPEiTpLXjbS0N03dNhRvjEnToeJFToqc6QIgXUg,10010
|
|
29
|
+
codegraph_nav/graph/query.py,sha256=dizw-L8rBmcATAOiw2g52Jioq_Hrg7CncMicxC4MvSc,12085
|
|
30
|
+
codegraph_nav/graph/schema.py,sha256=JTAWfnzr25aYWB8bTrsL0-h545VU58zn8N5-Hry8QPk,7409
|
|
31
|
+
codegraph_nav/graph/search.py,sha256=mbnSewviv5Bok5HjPWrPqoKWhteXkzUdAZu4fE9ZdOk,8457
|
|
32
|
+
codegraph_nav/graph/store.py,sha256=vasmxIqG6TtLjENZW1IQSrHWAYHmbk5L-EYjMCBQLCI,19310
|
|
33
|
+
codegraph_nav/mcp/__init__.py,sha256=YdUHhtoHH5Mh9TFG6kWNKdDp3juHDl46smy2V1rQ_WU,954
|
|
34
|
+
codegraph_nav/mcp/__main__.py,sha256=Yzwf8aYQ3vUqglATOpFV5tniNofH89TIq-5wqZtWmSk,103
|
|
35
|
+
codegraph_nav/mcp/server.py,sha256=3IHxbkcAYXKJuNMouqHi7m2-yNF8bknyJejSa0b8q-Y,81133
|
|
36
|
+
codegraph_nav-0.1.0.dist-info/licenses/LICENSE,sha256=XWLR9vFRSsH8LL47ie3_EI92ig7_8onT2F3WgPCh5nU,1071
|
|
37
|
+
codegraph_nav-0.1.0.dist-info/METADATA,sha256=9Bua0iy7G-77nwi_yAnpyz66GeVPfI5MCdYX2-4soQU,17436
|
|
38
|
+
codegraph_nav-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
|
|
39
|
+
codegraph_nav-0.1.0.dist-info/entry_points.txt,sha256=Kf0My7Kof34r2xLoEP2CptgrPGghN1OyfBUb3C_fbII,129
|
|
40
|
+
codegraph_nav-0.1.0.dist-info/top_level.txt,sha256=TtbZ0-btQfK2T1HdyClRBNJXY_OEf1IjsQq44APaS8E,14
|
|
41
|
+
codegraph_nav-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Efren Bautista
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
codegraph_nav
|