node-walk 0.1.1__tar.gz → 0.2.0__tar.gz

node_walk-0.2.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to **node-walk** will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+---
+
+## [0.2.0] - 2026-08-23
+### Added
+- **`node-walk serve` command**: Launches an embedded local HTTP server (`localhost:7777` by default) and auto-opens the browser to the interactive graph explorer. Accepts `--port`, `--host`, and `--no-open` flags.
+- **Graph Explorer UI** (`src/node_walk/web/`): A single-page browser application (no build step, no npm) that renders the full code graph using Cytoscape.js (CDN):
+  - Force-directed layout with manual drag support.
+  - Nodes coloured and shaped by `SymbolKind`; edges styled and coloured by `RelationshipType`.
+  - Click node → highlight it and direct neighbours + show detail panel (name, kind, file, lines, signature, docstring, source snippet).
+  - Double-click node → lazy 1-hop neighbour expansion via `/api/neighbors`.
+  - Right-click context menu: expand neighbours, focus subtree, hide node, reset focus.
+  - Debounced search bar backed by `/api/search` → centres and selects the top match.
+  - Filter panel (checkboxes) to show/hide nodes by `SymbolKind` and edges by `RelationshipType`; `CONTAINS` edges hidden by default.
+  - Tooltip on hover for nodes and edges.
+  - Fit-to-viewport and re-layout buttons.
+  - Status bar showing visible node/edge counts and selected symbol name.
+- **Web API** (`src/node_walk/web/server.py`): Zero-dependency HTTP server (Python `http.server`) exposing:
+  - `GET /api/graph[?kinds=…&rels=…]` — full graph for initial render, with optional kind/relationship filters.
+  - `GET /api/symbol/{id}` — symbol detail including source snippet, caller/callee counts.
+  - `GET /api/neighbors/{id}[?direction=out|in|both&rels=…]` — 1-hop neighbours for lazy canvas expansion.
+  - `GET /api/search?q=…` — fuzzy symbol search (reuses `QueryEngine.find_symbol`).
+  - `GET /api/stats` — graph statistics.
+- **API tests** (`tests/test_web_server.py`): Full test suite covering all five endpoints (schema validation, filter params, 404 handling, score ranges) plus a full smoke round-trip and static file serving tests.
+
+### Changed
+- **`pyproject.toml`**: Added `force-include` entries so `index.html`, `style.css`, and `app.js` are bundled in the installed wheel.
+- **`node-walk help`**: Added "Browser Explorer" section listing the `serve` command.
+
+
+## [0.1.1] - 2026-08-20
+
+### Added
+- **Dotted-Path Symbol Search**: Support searching for scoped symbols (e.g. `ModelAdapter.chat`, `UserService.create_user`) matching child symbols within parents without needing full module paths.
+- **Fuzzy / Typo Matching**: Added `difflib.SequenceMatcher` fallback across symbols to handle typos (e.g. `ModelAdpater.chat`, `creat_user`), returning match scores and `(fuzzy)` indicators.
+- **Graph Visualizations**: Added ASCII tree, Graphviz DOT (`.dot`), and Mermaid diagram formatters in `tree_formatter.py`.
+- **`graph` Command**: Added `node-walk graph <symbol>` for general BFS neighborhood exploration with customizable direction (`out`, `in`, `both`) and format (`tree`, `dot`, `mermaid`, `table`).
+- **Formatting Options**: Added `--format` / `-f` (`tree`, `dot`, `mermaid`, `table`) and `--output` / `-o` flags to `trace` and `blast-radius` commands.
+- **Automated Versioning in CI**: Updated GitHub Actions release workflow with dynamic version resolution (tag triggers or `patch`/`minor`/`major` dispatch inputs).
+
+### Changed
+- **Branding**: Renamed project and CLI binaries from `CodeGraph` to `node-walk`.
+- **Packaging**: Switched `pyproject.toml` to dynamic versioning via Hatchling reading from `src/node_walk/__init__.py`.
+- **CLI Resolution**: Auto-select top candidate when an unambiguous high-confidence match is found instead of prompting unnecessarily.
+- **Documentation**: Updated `README.md` to reflect all currently supported features, traversal modes, and CLI commands.
+
+---
+
+## [0.1.0] - 2026-08-20
+
+### Added
+- **Tree-sitter Python Analyzer**: High-speed AST analysis extracting files, classes, methods, functions, constants, variables, fields, docstrings, signatures, and call sites.
+- **Language-Independent Code IR**: Pydantic v2 data models for `Symbol`, `Relationship`, `FileInfo`, `SourceLocation`, and `AnalysisResult`.
+- **Typed Semantic Relationships**: Support for `CONTAINS`, `IMPORTS`, `CALLS`, `REFERENCES`, `EXTENDS`, `IMPLEMENTS`, and `OVERRIDES`.
+- **SQLite Storage Backend**: Local SQLite database with WAL mode, foreign keys, and 10 query indexes.
+- **Recursive CTE Query Engine**: In-database bounded graph traversals (`walk`, `trace`, `blast_radius`) using recursive SQL CTEs.
+- **Rich CLI**: Typer-based command-line interface with custom themed tables and syntax highlighting:
+  - `index`: Analyze and index a codebase.
+  - `find`: Search symbols by name or qualified name.
+  - `definition`: Show symbol definition and metadata.
+  - `source`: Extract and display the exact source code block of any symbol.
+  - `callers` & `callees`: Discover direct upstream and downstream call sites.
+  - `refs`: Locate symbol references.
+  - `implementations`: Find concrete classes extending or implementing interfaces/ABCs.
+  - `imports`: Inspect imported modules and symbols.
+  - `trace`: Follow outgoing dependency chains.
+  - `blast-radius`: Follow incoming dependent chains.
+  - `stats`: Display database statistics and symbol/relationship breakdowns.
+  - `export`: Export the complete semantic graph to JSON.
+  - `help`: Custom command cheat sheet.

{node_walk-0.1.1 → node_walk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: node-walk
-Version: 0.1.1
+Version: 0.2.0
 Summary: Semantic code intelligence — local-first graph of your codebase for humans and LLMs
 Author: CodeGraph Contributors
 License: MIT
@@ -38,8 +38,9 @@ Local-first · Lightweight · Fast indexing · SQLite backed · CLI & Visualizat
 - **Smart Symbol Search**: Find symbols by simple name (`chat`), qualified dotted path (`ModelAdapter.chat`), or fuzzy typo matching (`ModelAdpater.chat`).
 - **Exact Source Retrieval**: View definitions, signatures, and exact source ranges instantly.
 - **Relationship Navigation**: Find callers, callees, references, class implementations / ABCs, and imports.
-- **Graph Traversal & Visualization**: Trace outgoing call chains and incoming blast radiuses rendered directly in terminal (ASCII tree), exported to Graphviz (`.dot`), or generated as Mermaid diagrams.
-- **Lightweight & Self-Contained**: Pure Python + Tree-sitter + SQLite. Zero external database services or cloud dependencies.
+- **Graph Traversal & Visualization**: Trace outgoing call chains and incoming blast radiuses rendered in terminal (ASCII tree), exported to Graphviz (`.dot`), or generated as Mermaid diagrams.
+- **Browser Graph Explorer**: `node-walk serve` launches a local interactive Cytoscape.js graph — click nodes, expand neighbours, search symbols, filter by kind/relationship, and inspect source — all without leaving the browser.
+- **Lightweight & Self-Contained**: Pure Python + Tree-sitter + SQLite + stdlib `http.server`. Zero external database services, cloud dependencies, or build steps.
 
 ---
 
@@ -111,7 +112,25 @@ node-walk blast-radius UserService.create_user --format tree
 node-walk graph ModelAdapter --depth 3 --format tree
 ```
 
-### 5. Utilities
+### 5. Browser Graph Explorer
+```bash
+# Launch the interactive graph explorer in your browser
+node-walk serve                        # default: http://localhost:7777
+node-walk serve --port 8888            # custom port
+node-walk serve --no-open              # start server only, don't auto-open
+```
+
+The explorer visualises **all** symbols and relationships as a force-directed interactive graph:
+
+| Action | Result |
+|---|---|
+| Click node | Highlight node + direct neighbours; open detail panel |
+| Double-click node | Lazy-expand 1-hop neighbours from the server |
+| Right-click node | Context menu: expand, focus subtree, hide, reset |
+| Search bar | Debounced fuzzy search → centre + select result |
+| Filter panel | Toggle visibility by SymbolKind / RelationshipType |
+
+### 6. Utilities
 ```bash
 # Show database statistics (symbol kinds, relationship counts)
 node-walk stats
@@ -147,3 +166,9 @@ pytest tests/ -v
 ## Graph Storage & Lifecycle
 
 The generated graph is stored in `.node_walk/graph.db` inside your indexed repository. It is disposable and can be re-indexed at any time with `node-walk index .`.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](file:///c:/Users/nshri/Github/CodeGraph/CHANGELOG.md) for full release history and notes.

{node_walk-0.1.1 → node_walk-0.2.0}/README.md

@@ -14,8 +14,9 @@ Local-first · Lightweight · Fast indexing · SQLite backed · CLI & Visualizat
 - **Smart Symbol Search**: Find symbols by simple name (`chat`), qualified dotted path (`ModelAdapter.chat`), or fuzzy typo matching (`ModelAdpater.chat`).
 - **Exact Source Retrieval**: View definitions, signatures, and exact source ranges instantly.
 - **Relationship Navigation**: Find callers, callees, references, class implementations / ABCs, and imports.
-- **Graph Traversal & Visualization**: Trace outgoing call chains and incoming blast radiuses rendered directly in terminal (ASCII tree), exported to Graphviz (`.dot`), or generated as Mermaid diagrams.
-- **Lightweight & Self-Contained**: Pure Python + Tree-sitter + SQLite. Zero external database services or cloud dependencies.
+- **Graph Traversal & Visualization**: Trace outgoing call chains and incoming blast radiuses rendered in terminal (ASCII tree), exported to Graphviz (`.dot`), or generated as Mermaid diagrams.
+- **Browser Graph Explorer**: `node-walk serve` launches a local interactive Cytoscape.js graph — click nodes, expand neighbours, search symbols, filter by kind/relationship, and inspect source — all without leaving the browser.
+- **Lightweight & Self-Contained**: Pure Python + Tree-sitter + SQLite + stdlib `http.server`. Zero external database services, cloud dependencies, or build steps.
 
 ---
 
@@ -87,7 +88,25 @@ node-walk blast-radius UserService.create_user --format tree
 node-walk graph ModelAdapter --depth 3 --format tree
 ```
 
-### 5. Utilities
+### 5. Browser Graph Explorer
+```bash
+# Launch the interactive graph explorer in your browser
+node-walk serve                        # default: http://localhost:7777
+node-walk serve --port 8888            # custom port
+node-walk serve --no-open              # start server only, don't auto-open
+```
+
+The explorer visualises **all** symbols and relationships as a force-directed interactive graph:
+
+| Action | Result |
+|---|---|
+| Click node | Highlight node + direct neighbours; open detail panel |
+| Double-click node | Lazy-expand 1-hop neighbours from the server |
+| Right-click node | Context menu: expand, focus subtree, hide, reset |
+| Search bar | Debounced fuzzy search → centre + select result |
+| Filter panel | Toggle visibility by SymbolKind / RelationshipType |
+
+### 6. Utilities
 ```bash
 # Show database statistics (symbol kinds, relationship counts)
 node-walk stats
@@ -123,3 +142,9 @@ pytest tests/ -v
 ## Graph Storage & Lifecycle
 
 The generated graph is stored in `.node_walk/graph.db` inside your indexed repository. It is disposable and can be re-indexed at any time with `node-walk index .`.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](file:///c:/Users/nshri/Github/CodeGraph/CHANGELOG.md) for full release history and notes.

node_walk-0.2.0/plans/traversable-graph.md

@@ -0,0 +1,351 @@
+# Traversable Graph — Feature Plan
+
+**Interactive browser-based code graph visualization for node-walk.**
+
+Light-touch MVP first, iterate from user feedback.
+
+---
+
+## 1. Goal
+
+Let a developer **see and click through** their code graph in a browser — starting from any symbol, expanding neighbors on click, reading source on hover — rather than only navigating via terminal commands.
+
+The graph is **local-only**: a tiny embedded HTTP server reads the same `.node_walk/graph.db` that the CLI already produces. No cloud, no build step, no bundler.
+
+---
+
+## 2. What the MVP Does
+
+| Capability | Detail |
+|---|---|
+| **Launch from CLI** | `node-walk serve` starts a local HTTP server (default `localhost:7777`) and opens the browser. |
+| **Full graph overview** | On load, render all symbols + relationships from the indexed repo. Nodes are colored by `SymbolKind`, edges by `RelationshipType`. |
+| **Click to focus** | Click a node → highlight it and its direct neighbors, dim everything else. |
+| **Expand / collapse** | Double-click a node → run a 1-hop walk from that node and add newly discovered neighbors to the canvas (lazy expansion). |
+| **Node detail panel** | Select a node → side panel shows: qualified name, kind, file, line range, signature, docstring preview. |
+| **Search bar** | Type a symbol name → fuzzy match (reuses `find_symbol` logic server-side) → center the graph on the result. |
+| **Layout** | Force-directed layout (Cytoscape.js `cose`) with manual drag. |
+| **Edge labels** | Edges show relationship type (`CALLS`, `IMPORTS`, `EXTENDS`, etc.). |
+| **Filter panel** | Checkboxes to show/hide by SymbolKind and RelationshipType. |
+
+### What the MVP Does NOT Do
+
+- No live re-indexing (user must `node-walk index` first).
+- No edit-in-place or "go to file in editor" integration.
+- No multi-repo or remote graphs.
+- No persistence of layout state between sessions.
+
+---
+
+## 3. Architecture
+
+```
+┌────────────────────────────────┐
+│           Browser              │
+│  ┌──────────────────────────┐  │
+│  │  Single-Page HTML/JS/CSS │  │
+│  │  Cytoscape.js (CDN)      │  │
+│  └──────────┬───────────────┘  │
+│             │ fetch /api/*     │
+└─────────────┼──────────────────┘
+              │ HTTP (localhost)
+┌─────────────┼──────────────────┐
+│  node-walk serve               │
+│  ┌──────────┴───────────────┐  │
+│  │  Python HTTP server      │  │
+│  │  (aiohttp or stdlib)     │  │
+│  │  JSON API endpoints      │  │
+│  └──────────┬───────────────┘  │
+│             │                  │
+│  ┌──────────┴───────────────┐  │
+│  │  QueryEngine             │  │
+│  │  SQLiteGraphStore        │  │
+│  │  (.node_walk/graph.db)   │  │
+│  └──────────────────────────┘  │
+└────────────────────────────────┘
+```
+
+**Zero new Python dependencies for MVP.** The HTTP server uses Python's built-in `http.server` module. The frontend loads Cytoscape.js from CDN. All HTML/CSS/JS is served from a single bundled directory inside the package.
+
+---
+
+## 4. Backend — API Endpoints
+
+All endpoints return JSON. The server is a thin wrapper around `QueryEngine`.
+
+### `GET /api/graph`
+
+Returns the full graph (all symbols + relationships) for initial render.
+
+```json
+{
+  "nodes": [
+    {
+      "id": "uuid",
+      "name": "chat",
+      "qualified_name": "jarvis.model.base.ModelAdapter.chat",
+      "kind": "METHOD",
+      "file_path": "src/jarvis/model/base.py",
+      "start_line": 42,
+      "end_line": 58,
+      "signature": "(self, messages: list[ChatMessage]) -> str",
+      "docstring": "Send messages to the model and return response.",
+      "parent_id": "uuid-of-ModelAdapter"
+    }
+  ],
+  "edges": [
+    {
+      "id": "uuid",
+      "source": "source-symbol-uuid",
+      "target": "target-symbol-uuid",
+      "type": "CALLS",
+      "resolution": "resolved"
+    }
+  ],
+  "stats": {
+    "total_nodes": 127,
+    "total_edges": 304
+  }
+}
+```
+
+**Query params:**
+- `?kinds=CLASS,METHOD,FUNCTION` — filter node kinds (default: all)
+- `?rels=CALLS,IMPORTS,EXTENDS` — filter edge types (default: all)
+
+### `GET /api/symbol/{id}`
+
+Returns full detail for a single symbol (definition, source snippet).
+
+```json
+{
+  "symbol": { /* same shape as node above */ },
+  "source_lines": ["def chat(self, ...):", "    ..."],
+  "callers_count": 3,
+  "callees_count": 5,
+  "refs_count": 8
+}
+```
+
+### `GET /api/neighbors/{id}`
+
+Returns 1-hop neighbors of a symbol (for lazy expand on double-click).
+
+```json
+{
+  "nodes": [ /* new nodes not already on canvas */ ],
+  "edges": [ /* edges connecting to/from the expanded node */ ]
+}
+```
+
+**Query params:**
+- `?direction=out|in|both` (default: `both`)
+- `?rels=CALLS,IMPORTS` (default: all)
+
+### `GET /api/search?q=<query>`
+
+Fuzzy symbol search. Returns top matches with scores.
+
+```json
+{
+  "results": [
+    {
+      "id": "uuid",
+      "qualified_name": "pkg.ModelAdapter.chat",
+      "kind": "METHOD",
+      "score": 0.95
+    }
+  ]
+}
+```
+
+### `GET /api/stats`
+
+Returns graph statistics (reuses `QueryEngine.stats()`).
+
+---
+
+## 5. Frontend — Single-Page App
+
+### Technology
+
+| Component | Choice | Rationale |
+|---|---|---|
+| Graph rendering | **Cytoscape.js** (CDN) | Mature, performant, supports cola/cose layouts, built-in selection/expansion APIs. |
+| Styling | Vanilla CSS | Zero build step. Dark theme by default. |
+| HTTP | `fetch()` | No framework needed. |
+
+### Files
+
+All frontend files live under `src/node_walk/web/`:
+
+```
+src/node_walk/web/
+├── index.html       # Single-page shell
+├── style.css        # Dark theme, layout, panels
+└── app.js           # Cytoscape init, API calls, interaction handlers
+```
+
+### UI Layout
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│  ┌─────────────────────────────────────────┐  ┌───────────┐  │
+│  │           Search bar                    │  │  Filters  │  │
+│  └─────────────────────────────────────────┘  └───────────┘  │
+│  ┌─────────────────────────────────────────┐  ┌───────────┐  │
+│  │                                         │  │  Detail   │  │
+│  │                                         │  │  Panel    │  │
+│  │           Cytoscape Canvas              │  │           │  │
+│  │           (interactive graph)           │  │  - Name   │  │
+│  │                                         │  │  - Kind   │  │
+│  │                                         │  │  - File   │  │
+│  │                                         │  │  - Lines  │  │
+│  │                                         │  │  - Source  │  │
+│  └─────────────────────────────────────────┘  └───────────┘  │
+│  ┌─────────────────────────────────────────────────────────┐  │
+│  │  Status bar: node count · edge count · index path       │  │
+│  └─────────────────────────────────────────────────────────┘  │
+└───────────────────────────────────────────────────────────────┘
+```
+
+### Interactions
+
+| User Action | Behavior |
+|---|---|
+| **Click node** | Select → highlight it + direct neighbors. Show detail panel. |
+| **Double-click node** | Lazy expand: fetch `/api/neighbors/{id}`, add new nodes/edges, re-layout locally. |
+| **Right-click node** | Context menu: "Trace from here", "Blast radius", "Hide node", "Focus subtree". |
+| **Hover node** | Tooltip with qualified name + kind. |
+| **Hover edge** | Tooltip with relationship type. |
+| **Search** | Debounced keystroke → `GET /api/search?q=...` → highlight + center on top match. |
+| **Filter checkboxes** | Toggle visibility of SymbolKind / RelationshipType categories. |
+| **Drag node** | Manual positioning (disables auto-layout for that node). |
+| **Scroll** | Zoom in/out. |
+| **Fit button** | Reset viewport to fit all visible nodes. |
+
+### Node Styling (by SymbolKind)
+
+| Kind | Shape | Color |
+|---|---|---|
+| CLASS | Round rectangle | `#4FC3F7` (blue) |
+| INTERFACE | Diamond | `#7E57C2` (purple) |
+| FUNCTION | Ellipse | `#66BB6A` (green) |
+| METHOD | Ellipse | `#FFA726` (orange) |
+| MODULE / FILE | Rectangle | `#AB47BC` (violet) |
+| CONSTANT | Small rectangle | `#FFEE58` (yellow) |
+| VARIABLE / FIELD | Small ellipse | `#BDBDBD` (grey) |
+
+### Edge Styling (by RelationshipType)
+
+| Type | Style | Color |
+|---|---|---|
+| CALLS | Solid arrow | `#42A5F5` (blue) |
+| IMPORTS | Dashed arrow | `#AB47BC` (purple) |
+| EXTENDS | Bold arrow | `#66BB6A` (green) |
+| IMPLEMENTS | Dashed arrow | `#26A69A` (teal) |
+| REFERENCES | Dotted arrow | `#9E9E9E` (grey) |
+| CONTAINS | Dotted, thin | `#E0E0E0` (light grey) |
+
+---
+
+## 6. Implementation Plan
+
+### Phase 1: Backend API (server.py)
+
+**New file:** `src/node_walk/web/server.py`
+
+1. Create a `http.server.HTTPServer` subclass that:
+   - Serves static files from `src/node_walk/web/` for `/`, `/style.css`, `/app.js`.
+   - Routes `/api/*` requests to handler functions.
+   - Opens `SQLiteGraphStore` + `QueryEngine` on startup.
+2. Implement API handlers:
+   - `handle_graph()` → serialize all symbols + relationships to JSON.
+   - `handle_symbol(id)` → serialize symbol detail + source snippet.
+   - `handle_neighbors(id)` → 1-hop walk, serialize incremental nodes/edges.
+   - `handle_search(q)` → `find_symbol()`, serialize matches.
+   - `handle_stats()` → `stats()`, serialize.
+3. Add `serve` command to CLI (`main.py`):
+   ```python
+   @app.command()
+   def serve(
+       port: int = 7777,
+       no_open: bool = False,
+   ):
+       """Launch the interactive graph explorer in your browser."""
+   ```
+4. Auto-open `http://localhost:{port}` in the default browser via `webbrowser.open()`.
+
+### Phase 2: Frontend (index.html + style.css + app.js)
+
+**New files:** `src/node_walk/web/index.html`, `style.css`, `app.js`
+
+1. **index.html**: Minimal shell — imports Cytoscape.js from CDN, links `style.css` and `app.js`.
+2. **style.css**: Dark theme, layout grid (graph canvas + side panel), search bar, filter panel, status bar.
+3. **app.js**:
+   - On load: `fetch('/api/graph')` → feed nodes/edges to Cytoscape.
+   - Node click → fetch `/api/symbol/{id}` → populate detail panel.
+   - Node double-click → fetch `/api/neighbors/{id}` → add to graph, run local layout.
+   - Search input → debounced fetch `/api/search` → center + highlight.
+   - Filter checkboxes → toggle element visibility via `cy.elements().filter(...)`.
+
+### Phase 3: CLI Integration
+
+1. Add `serve` command to `main.py`.
+2. Include `src/node_walk/web/` in the package build (`pyproject.toml` package data).
+3. Update `README.md` and `CHANGELOG.md`.
+
+### Phase 4: Tests
+
+1. **Backend API tests** (`tests/test_web_server.py`):
+   - Spin up server in a thread, hit each endpoint, assert JSON schema.
+   - Test search endpoint with fuzzy queries.
+   - Test neighbors endpoint returns incremental data.
+2. **Smoke test**: Index a fixture repo, start server, verify `/api/graph` returns valid JSON with expected node/edge counts.
+
+---
+
+## 7. File Manifest
+
+| File | Status | Purpose |
+|---|---|---|
+| `src/node_walk/web/__init__.py` | NEW | Package marker |
+| `src/node_walk/web/server.py` | NEW | HTTP server + API handlers |
+| `src/node_walk/web/index.html` | NEW | Single-page HTML shell |
+| `src/node_walk/web/style.css` | NEW | Dark theme + layout |
+| `src/node_walk/web/app.js` | NEW | Cytoscape.js graph logic |
+| `src/node_walk/cli/main.py` | MODIFY | Add `serve` command |
+| `pyproject.toml` | MODIFY | Include `web/` in package data |
+| `tests/test_web_server.py` | NEW | API endpoint tests |
+| `README.md` | MODIFY | Document `serve` command |
+| `CHANGELOG.md` | MODIFY | Add traversable graph entry |
+
+---
+
+## 8. Post-MVP Improvements (Later)
+
+These are explicitly **not** in the MVP scope, but worth tracking:
+
+| Improvement | Description |
+|---|---|
+| **Compound nodes** | Nest methods inside class nodes (Cytoscape.js compound node support). |
+| **Trace overlay** | Click "Trace" → highlight the full call chain path with animated edges. |
+| **Blast radius heatmap** | Color nodes by blast-radius depth (red = close, blue = far). |
+| **"Open in editor" link** | `vscode://file/{path}:{line}` deep-links from the detail panel. |
+| **Layout persistence** | Save/restore node positions to `.node_walk/layout.json`. |
+| **Incremental re-index** | Watch file changes, re-index modified files, push updates to connected browser via WebSocket. |
+| **Performance: virtual rendering** | For repos with >5k symbols, use Cytoscape.js `webgl` renderer or cluster nodes by module. |
+| **Minimap** | Small overview panel for orientation on large graphs. |
+| **Dark/light toggle** | Theme switcher. |
+
+---
+
+## 9. Constraints & Decisions
+
+| Decision | Rationale |
+|---|---|
+| **stdlib `http.server`** over Flask/FastAPI | Zero new dependencies, consistent with "lightweight" philosophy. MVP doesn't need async, middleware, or routing frameworks. |
+| **Cytoscape.js from CDN** | No npm/bundler build step. Single HTML file can load it. Cytoscape is the most mature JS graph library with built-in layouts, selection, and expansion. |
+| **All frontend in 3 files** | Keeps it dead simple. No React, no Vite, no TypeScript. If the MVP proves valuable, we can graduate to a proper SPA later. |
+| **Full graph on initial load** | For repos up to ~2-3k symbols this is fine (Cytoscape handles 5k+ nodes). For larger repos, Phase 2 can add pagination or module-level clustering. |
+| **CONTAINS edges hidden by default** | They dominate the graph and add visual clutter. Users can toggle them on via the filter panel. |

{node_walk-0.1.1 → node_walk-0.2.0}/pyproject.toml

@@ -44,6 +44,15 @@ path = "src/node_walk/__init__.py"
 [tool.hatch.build.targets.wheel]
 packages = ["src/node_walk"]
 
+[tool.hatch.build.targets.wheel.shared-data]
+# Include all static web assets in the installed package
+"src/node_walk/web" = "node_walk/web"
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/node_walk/web/index.html" = "node_walk/web/index.html"
+"src/node_walk/web/style.css"  = "node_walk/web/style.css"
+"src/node_walk/web/app.js"     = "node_walk/web/app.js"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]

{node_walk-0.1.1 → node_walk-0.2.0}/src/node_walk/__init__.py

@@ -1,3 +1,3 @@
 """node-walk — Semantic code intelligence for humans and LLMs."""
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"

{node_walk-0.1.1 → node_walk-0.2.0}/src/node_walk/cli/main.py

@@ -629,11 +629,46 @@ def show_help() -> None:
     table.add_row("stats", "Show database statistics (file, symbol, edge counts).")
     table.add_row("export", "Export the entire semantic graph as JSON.")
 
+    table.add_section()
+    table.add_row("[bold white]Browser Explorer[/bold white]", "")
+    table.add_row("serve", "Launch the interactive graph explorer in your browser.")
+
     console.print(table)
     console.print("\n[dim]To see options for any command, run: [bold]node-walk <command> --help[/bold][/dim]")
 
 
 
+@app.command()
+def serve(
+    port: Annotated[int, typer.Option("--port", "-p", help="Port to listen on.")] = 7777,
+    host: Annotated[str, typer.Option("--host", help="Host to bind to.")] = "localhost",
+    no_open: Annotated[bool, typer.Option("--no-open", help="Do not open the browser automatically.")] = False,
+) -> None:
+    """Launch the interactive graph explorer in your browser."""
+    db = _find_db()
+    if db is None:
+        err_console.print(
+            "[red]No .node_walk/graph.db found.[/red] "
+            "Run [bold]node-walk index <path>[/bold] first."
+        )
+        raise typer.Exit(1)
+
+    url = f"http://{host}:{port}"
+    console.print(
+        Panel(
+            f"[bold cyan]Graph explorer[/bold cyan] starting at [bold]{url}[/bold]\n"
+            f"[dim]DB:[/dim] {db}\n"
+            "[dim]Press Ctrl+C to stop.[/dim]",
+            title="node-walk serve",
+            border_style="cyan",
+        )
+    )
+
+    from node_walk.web.server import start_server
+
+    start_server(db, host=host, port=port, open_browser=not no_open, block=True)
+
+
 # ---------------------------------------------------------------------------
 # Entry point
 # ---------------------------------------------------------------------------

node_walk-0.2.0/src/node_walk/web/__init__.py

@@ -0,0 +1,3 @@
+"""
+node_walk.web — Embedded HTTP server for the traversable graph explorer.
+"""