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

node_walk-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,158 @@
+name: Release & Publish
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to publish (e.g. 0.1.1, patch, minor, major) — leave blank to use current __init__.py version"
+        required: false
+        default: ""
+        type: string
+      target:
+        description: "Target repository to publish to"
+        required: true
+        default: "pypi"
+        type: choice
+        options:
+          - "pypi"
+          - "testpypi"
+      create_github_release:
+        description: "Create a GitHub Release with built distribution assets"
+        required: false
+        default: true
+        type: boolean
+      is_prerelease:
+        description: "Mark GitHub Release as pre-release"
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  build:
+    name: Build source and binary distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set release version
+        id: set_version
+        run: |
+          python - << 'EOF'
+          import os, re
+
+          tag = os.environ.get("GITHUB_REF_NAME", "")
+          input_ver = os.environ.get("INPUT_VERSION", "").strip()
+          init_path = "src/node_walk/__init__.py"
+
+          with open(init_path, "r", encoding="utf-8") as f:
+              content = f.read()
+
+          m = re.search(r'__version__\s*=\s*["\']([^"\']+)["\']', content)
+          current_ver = m.group(1) if m else "0.1.0"
+          
+          target_ver = current_ver
+
+          if input_ver:
+              if input_ver in ("patch", "minor", "major"):
+                  parts = [int(p) for p in re.findall(r'\d+', current_ver)]
+                  while len(parts) < 3:
+                      parts.append(0)
+                  if input_ver == "major":
+                      target_ver = f"{parts[0]+1}.0.0"
+                  elif input_ver == "minor":
+                      target_ver = f"{parts[0]}.{parts[1]+1}.0"
+                  elif input_ver == "patch":
+                      target_ver = f"{parts[0]}.{parts[1]}.{parts[2]+1}"
+              else:
+                  target_ver = input_ver.lstrip("v")
+          elif os.environ.get("GITHUB_REF_TYPE") == "tag" and tag.startswith("v"):
+              target_ver = tag.lstrip("v")
+
+          print(f"Setting package version to: {target_ver}")
+          new_content = re.sub(r'__version__\s*=\s*["\'][^"\']+["\']', f'__version__ = "{target_ver}"', content)
+          with open(init_path, "w", encoding="utf-8") as f:
+              f.write(new_content)
+
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as out:
+              out.write(f"version={target_ver}\n")
+          EOF
+        env:
+          INPUT_VERSION: ${{ inputs.version }}
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build hatchling
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish distribution
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: ${{ inputs.target || 'pypi' }}
+      url: ${{ (inputs.target == 'testpypi') && 'https://test.pypi.org/p/node-walk' || 'https://pypi.org/p/node-walk' }}
+    permissions:
+      id-token: write # Required for Trusted Publishing (OIDC)
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI / TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ (inputs.target == 'testpypi') && 'https://test.pypi.org/legacy/' || '' }}
+          skip-existing: true
+
+  github-release:
+    name: Create GitHub Release
+    needs: [build]
+    if: ${{ inputs.create_github_release != false }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Extract package version from distribution filename
+        id: get_version
+        run: |
+          FILE=$(ls dist/*.whl | head -n 1)
+          VERSION=$(basename "$FILE" | sed -E 's/.*-([0-9]+\.[0-9]+\.[0-9]+[a-zA-Z0-9._]*)-.*/\1/')
+          echo "version=v$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.get_version.outputs.version }}
+          files: dist/*
+          generate_release_notes: true
+          prerelease: ${{ inputs.is_prerelease || false }}

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.2.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: node-walk
+Version: 0.2.0
+Summary: Semantic code intelligence — local-first graph of your codebase for humans and LLMs
+Author: CodeGraph Contributors
+License: MIT
+License-File: LICENSE
+Keywords: code-analysis,developer-tools,llm,semantic-graph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tree-sitter-python>=0.23.0
+Requires-Dist: tree-sitter>=0.23.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# node-walk
+
+**Semantic code intelligence and graph navigation for Python codebases.**
+
+Local-first · Lightweight · Fast indexing · SQLite backed · CLI & Visualizations
+
+---
+
+## What is node-walk?
+
+`node-walk` parses your Python codebase into an Intermediate Representation (IR) graph stored locally in SQLite. It lets humans and LLMs query code relationships semantically instead of running repeated `grep` or text searches.
+
+### Key Capabilities
+- **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 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.
+
+---
+
+## Installation
+
+```bash
+git clone <repo-url> node-walk
+cd node-walk
+python -m venv .venv
+.venv\Scripts\activate     # Windows (.venv/bin/activate on Linux/macOS)
+pip install -e ".[dev]"
+```
+
+---
+
+## CLI Usage
+
+All CLI commands discover the graph database by searching for `.node_walk/graph.db` in the current directory or walking up parent directories.
+
+### 1. Index a repository
+```bash
+cd /path/to/your/project
+node-walk index .
+```
+
+### 2. Search & Inspect Symbols
+```bash
+# Search by name, dotted path, or fuzzy typo
+node-walk find UserService
+node-walk find ModelAdapter.chat
+node-walk find creat_user
+
+# View symbol definition metadata
+node-walk definition UserService.create_user
+
+# View the exact source code block
+node-walk source UserService.create_user
+```
+
+### 3. Explore Relationships
+```bash
+# Find callers of a function or method
+node-walk callers UserService.create_user
+
+# Find callees (what does this method call?)
+node-walk callees UserService.create_user
+
+# Find references/usages
+node-walk refs User
+
+# Find implementations / subclasses of an ABC or class
+node-walk implementations BaseRepository
+
+# Inspect imports
+node-walk imports services.py
+```
+
+### 4. Graph Traversals & Visualizations
+```bash
+# Trace outgoing dependencies (tree, table, dot, mermaid)
+node-walk trace UserService.create_user --depth 4 --format tree
+node-walk trace UserService.create_user --format dot -o trace.dot
+node-walk trace UserService.create_user --format mermaid
+
+# Assess blast radius (what calls/depends on this?)
+node-walk blast-radius UserService.create_user --format tree
+
+# General graph exploration around any symbol
+node-walk graph ModelAdapter --depth 3 --format tree
+```
+
+### 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
+
+# Export the entire graph to JSON
+node-walk export --output graph.json
+```
+
+---
+
+## Architecture
+
+```
+Source Files (.py) ──► Tree-sitter Parser ──► Code IR (Pydantic v2) ──► SQLite Graph ──► Query Engine ──► CLI / Visualizers
+```
+
+- **Analysis**: Tree-sitter for robust AST parsing and symbol/call-site extraction.
+- **Data Model**: Structured `Symbol`, `Relationship`, and `FileInfo` models.
+- **Storage**: SQLite with WAL mode and indexes on names, qualified names, and relationships.
+- **Traversals**: Recursive Common Table Expressions (CTEs) for fast BFS graph walks without loading graphs into memory.
+- **Visualization Formats**: ASCII Tree, Graphviz DOT, and Mermaid markdown diagrams.
+
+---
+
+## Running Tests
+
+```bash
+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/README.md

@@ -0,0 +1,150 @@
+# node-walk
+
+**Semantic code intelligence and graph navigation for Python codebases.**
+
+Local-first · Lightweight · Fast indexing · SQLite backed · CLI & Visualizations
+
+---
+
+## What is node-walk?
+
+`node-walk` parses your Python codebase into an Intermediate Representation (IR) graph stored locally in SQLite. It lets humans and LLMs query code relationships semantically instead of running repeated `grep` or text searches.
+
+### Key Capabilities
+- **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 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.
+
+---
+
+## Installation
+
+```bash
+git clone <repo-url> node-walk
+cd node-walk
+python -m venv .venv
+.venv\Scripts\activate     # Windows (.venv/bin/activate on Linux/macOS)
+pip install -e ".[dev]"
+```
+
+---
+
+## CLI Usage
+
+All CLI commands discover the graph database by searching for `.node_walk/graph.db` in the current directory or walking up parent directories.
+
+### 1. Index a repository
+```bash
+cd /path/to/your/project
+node-walk index .
+```
+
+### 2. Search & Inspect Symbols
+```bash
+# Search by name, dotted path, or fuzzy typo
+node-walk find UserService
+node-walk find ModelAdapter.chat
+node-walk find creat_user
+
+# View symbol definition metadata
+node-walk definition UserService.create_user
+
+# View the exact source code block
+node-walk source UserService.create_user
+```
+
+### 3. Explore Relationships
+```bash
+# Find callers of a function or method
+node-walk callers UserService.create_user
+
+# Find callees (what does this method call?)
+node-walk callees UserService.create_user
+
+# Find references/usages
+node-walk refs User
+
+# Find implementations / subclasses of an ABC or class
+node-walk implementations BaseRepository
+
+# Inspect imports
+node-walk imports services.py
+```
+
+### 4. Graph Traversals & Visualizations
+```bash
+# Trace outgoing dependencies (tree, table, dot, mermaid)
+node-walk trace UserService.create_user --depth 4 --format tree
+node-walk trace UserService.create_user --format dot -o trace.dot
+node-walk trace UserService.create_user --format mermaid
+
+# Assess blast radius (what calls/depends on this?)
+node-walk blast-radius UserService.create_user --format tree
+
+# General graph exploration around any symbol
+node-walk graph ModelAdapter --depth 3 --format tree
+```
+
+### 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
+
+# Export the entire graph to JSON
+node-walk export --output graph.json
+```
+
+---
+
+## Architecture
+
+```
+Source Files (.py) ──► Tree-sitter Parser ──► Code IR (Pydantic v2) ──► SQLite Graph ──► Query Engine ──► CLI / Visualizers
+```
+
+- **Analysis**: Tree-sitter for robust AST parsing and symbol/call-site extraction.
+- **Data Model**: Structured `Symbol`, `Relationship`, and `FileInfo` models.
+- **Storage**: SQLite with WAL mode and indexes on names, qualified names, and relationships.
+- **Traversals**: Recursive Common Table Expressions (CTEs) for fast BFS graph walks without loading graphs into memory.
+- **Visualization Formats**: ASCII Tree, Graphviz DOT, and Mermaid markdown diagrams.
+
+---
+
+## Running Tests
+
+```bash
+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.