mcp-vector-search 0.12.1__tar.gz → 0.12.3__tar.gz

mcp_vector_search-0.12.3/INVESTIGATION_EXPANSION_BUG.md

@@ -0,0 +1,229 @@
+# Investigation Report: Node Expansion Not Working
+
+## Summary
+User reports that directory/file nodes show expand/collapse icons ("+"/"-") but clicking them doesn't expand/collapse the hierarchy.
+
+## Code Analysis
+
+### 1. Click Handler Attachment ✓ CORRECT
+**Location**: `/Users/masa/Projects/mcp-vector-search/src/mcp_vector_search/visualization/index.html:481`
+
+```javascript
+.on("click", handleNodeClick)
+```
+
+The click handler IS correctly attached to each node group (`<g>` element).
+
+### 2. Pointer Events ✓ CORRECT
+**Locations**: Lines 123, 130, 542
+
+All text elements (labels, icons, expand indicators) have `pointer-events: none`, which correctly allows clicks to pass through to the parent `<g>` element where the handler is attached.
+
+### 3. hasChildren() Function ✓ CORRECT
+**Location**: Line 586-590
+
+```javascript
+function hasChildren(node) {
+    return allLinks.some(l => (l.source.id || l.source) === node.id);
+}
+```
+
+This correctly checks if a node is a parent (source) in any link. The `(l.source.id || l.source)` pattern handles both:
+- **Before D3 mutation**: `l.source` is a string (e.g., "dir_abc")
+- **After D3 mutation**: `l.source` is an object with `.id` property
+
+### 4. handleNodeClick() Function ✓ LOGIC CORRECT
+**Location**: Line 593-624
+
+The logic flow is correct:
+1. Show content pane (always)
+2. Check if node has children
+3. If yes, toggle collapse/expand state
+4. Call `renderGraph()` to update visualization
+
+### 5. expandNode() Function ✓ LOGIC CORRECT
+**Location**: Line 626-654
+
+Correctly:
+1. Removes node from `collapsedNodes`
+2. Finds children by filtering `allLinks` for links where source matches node ID
+3. Adds each child to `visibleNodes`
+4. Adds each child to `collapsedNodes` (children start collapsed)
+
+### 6. Data Structure ✓ VERIFIED
+**File**: `/Users/masa/Projects/mcp-vector-search/chunk-graph.json`
+
+```
+Total nodes: 7015
+Total links: 7006
+Directory nodes: 26
+Root directories: 5 (docs, examples, scripts, src, tests)
+```
+
+Sample link structure:
+```json
+{
+  "source": "dir_9f40c524",
+  "target": "dir_504f9a81",
+  "type": "dir_hierarchy"
+}
+```
+
+Example: `docs` directory has 22 child links, confirming hierarchy is correctly structured.
+
+## Debugging Added
+
+I've added comprehensive console logging to help diagnose the issue:
+
+### Initial State Logging (Line 445-450)
+Logs on page load:
+- Total nodes and links
+- Root nodes identified
+- Initial visible and collapsed node sets
+
+### Click Handler Logging (Line 594-623)
+Logs on every node click:
+- Node name, type, and ID
+- Whether node has children
+- Whether node is collapsed
+- Which action is taken (expand/collapse)
+
+### hasChildren() Logging (Line 587-590)
+Logs every time it's called:
+- Node name
+- Result (true/false)
+- Number of links checked
+
+### expandNode() Logging (Line 627-653)
+Logs during expansion:
+- Node being expanded
+- Number of child links found
+- Number of child nodes found
+- Each child being added to visibleNodes
+- Final visibleNodes size
+
+### renderGraph() Logging (Line 456-467)
+Logs on every render:
+- Size of visibleNodes and collapsedNodes sets
+- Number of nodes being rendered
+- Number of links being rendered
+
+## Testing Instructions
+
+1. **Open the visualization**:
+   ```bash
+   cd /Users/masa/Projects/mcp-vector-search/src/mcp_vector_search/visualization
+   open index.html
+   ```
+
+2. **Open Browser DevTools**:
+   - Press F12 or Cmd+Option+I (Mac)
+   - Go to the Console tab
+
+3. **Check Initial State**:
+   - You should see "=== INITIAL STATE ===" logged
+   - Verify root nodes are identified correctly
+   - Should show 5-9 root nodes
+
+4. **Click a Directory Node**:
+   - Click on "docs", "src", or another directory node
+   - Watch console for "=== NODE CLICKED ===" messages
+   - Check what happens:
+
+### Expected Behavior:
+```
+=== NODE CLICKED ===
+Node: docs Type: directory ID: dir_9f40c524
+hasChildren(docs): true Checking 7006 links for node ID: dir_9f40c524
+Node has children: true
+Node is collapsed: true
+Expanding node...
+expandNode(docs): Removing from collapsedNodes
+  Found 22 child links for node dir_9f40c524
+  Found 22 child nodes: [_archive, analysis, architecture, ...]
+    Adding child to visibleNodes: _archive (dir_504f9a81)
+    Adding child to visibleNodes: analysis (dir_abc123)
+    ...
+  visibleNodes now has 27 items
+=== renderGraph() called ===
+visibleNodes.size: 27
+Rendering 27 visible nodes
+Rendering XX visible links
+```
+
+### Possible Issues to Look For:
+
+#### Issue A: hasChildren() Returns False
+**Symptom**: Console shows `Node has children: false`
+**Cause**: Links not properly structured or node ID mismatch
+**Check**:
+- Are node IDs consistent between nodes and links?
+- Are links properly loaded?
+
+#### Issue B: No Children Found
+**Symptom**: Console shows `Found 0 child links`
+**Cause**: Link source/target ID mismatch or D3 mutation issue
+**Check**:
+- What is the format of `l.source` (string or object)?
+- Does `l.source` or `l.source.id` match the node ID?
+
+#### Issue C: Children Added But Not Rendered
+**Symptom**: Console shows children added to visibleNodes, but renderGraph() shows same count
+**Cause**: visibleNodes not being updated correctly
+**Check**:
+- Does `visibleNodes.size` increase after expansion?
+- Are the new nodes actually being rendered?
+
+#### Issue D: Click Handler Not Firing
+**Symptom**: No "=== NODE CLICKED ===" in console
+**Cause**: Event handler not attached or being blocked
+**Check**:
+- Are there any JavaScript errors on page load?
+- Try clicking different parts of the node (center, edge, icon area)
+
+## Potential Root Causes
+
+Based on the code analysis, here are the most likely issues:
+
+### 1. D3 Link Mutation Issue (MOST LIKELY)
+**Problem**: D3's `forceLink()` mutates link objects, replacing string IDs with object references.
+
+When `visibleLinks` is created by filtering `allLinks`, it creates a new array but **shares the same link objects**. When D3 mutates `visibleLinks`, it also mutates `allLinks`.
+
+**Impact**: After first render, all links in `allLinks` have object references instead of strings. The `hasChildren()` function should still work due to the `(l.source.id || l.source)` pattern, but there could be edge cases.
+
+**Test**: Check console to see if `hasChildren()` is returning the correct value after clicking.
+
+### 2. Event Propagation Issue
+**Problem**: Click events might be consumed by drag handler or other events.
+
+**Test**: Check if "=== NODE CLICKED ===" appears in console when clicking.
+
+### 3. Render Not Updating Visual State
+**Problem**: Even if expansion logic works, the visual update might fail.
+
+**Test**: Check if `renderGraph()` logs show increasing node counts after expansion.
+
+## Next Steps
+
+1. **Run the visualization with debugging**
+2. **Open browser console**
+3. **Click a directory node**
+4. **Copy all console output**
+5. **Analyze which of the above issues is occurring**
+
+## Files Modified
+
+- `/Users/masa/Projects/mcp-vector-search/src/mcp_vector_search/visualization/index.html`
+  - Added comprehensive console.log() debugging throughout
+  - No logic changes - only added logging
+
+## Conclusion
+
+The code logic appears correct. The issue is likely:
+
+1. **D3 link mutation** causing unexpected behavior in `hasChildren()` or `expandNode()`
+2. **Event handling** issue preventing clicks from being registered
+3. **Visual update** issue where expansion logic works but rendering doesn't update
+
+The added debugging will help pinpoint the exact issue. Please run the visualization and check the browser console output when clicking nodes.

{mcp_vector_search-0.12.1 → mcp_vector_search-0.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-vector-search
-Version: 0.12.1
+Version: 0.12.3
 Summary: CLI-first semantic code search with MCP integration
 Project-URL: Homepage, https://github.com/bobmatnyc/mcp-vector-search
 Project-URL: Documentation, https://mcp-vector-search.readthedocs.io
@@ -490,6 +490,10 @@ uv sync
 # Install in development mode
 uv pip install -e .
 
+# Test CLI from source (recommended during development)
+./dev-mcp version        # Shows [DEV] indicator
+./dev-mcp search "test"  # No reinstall needed after code changes
+
 # Run tests
 uv run pytest
 
@@ -498,6 +502,8 @@ uv run ruff check
 uv run mypy src/
 ```
 
+For detailed development workflow and `dev-mcp` usage, see the [Development](#-development) section below.
+
 ### Adding Language Support
 
 1. Create a new parser in `src/mcp_vector_search/parsers/`
@@ -570,10 +576,64 @@ uv sync && uv pip install -e .
 # Run development tests
 ./scripts/dev-test.sh
 
-# Test CLI locally
+# Run CLI from source (recommended during development)
+./dev-mcp version        # Visual [DEV] indicator
+./dev-mcp status         # Any command works
+./dev-mcp search "auth"  # Immediate feedback on changes
+
+# Alternative: use uv run directly
 uv run mcp-vector-search version
 ```
 
+#### Using the `dev-mcp` Development Helper
+
+The `./dev-mcp` script provides a streamlined way to run the CLI from source code during development, eliminating the need for repeated installations.
+
+**Key Features:**
+- **Visual [DEV] Indicator**: Shows `[DEV]` prefix to distinguish from installed version
+- **No Reinstall Required**: Reflects code changes immediately
+- **Complete Argument Forwarding**: Works with all CLI commands and options
+- **Verbose Mode**: Debug output with `--verbose` flag
+- **Built-in Help**: Script usage with `--help`
+
+**Usage Examples:**
+```bash
+# Basic commands (note the [DEV] prefix in output)
+./dev-mcp version
+./dev-mcp status
+./dev-mcp index
+./dev-mcp search "authentication logic"
+
+# With CLI options
+./dev-mcp search "error handling" --limit 10
+./dev-mcp index --force
+
+# Script verbose mode (shows Python interpreter, paths)
+./dev-mcp --verbose search "database"
+
+# Script help (shows dev-mcp usage, not CLI help)
+./dev-mcp --help
+
+# CLI command help (forwards --help to the CLI)
+./dev-mcp search --help
+./dev-mcp index --help
+```
+
+**When to Use:**
+- **`./dev-mcp`** → Development workflow (runs from source code)
+- **`mcp-vector-search`** → Production usage (runs installed version via pipx/pip)
+
+**Benefits:**
+- **Instant Feedback**: Changes to source code are reflected immediately
+- **No Build Step**: Skip the reinstall cycle during active development
+- **Clear Context**: Visual `[DEV]` indicator prevents confusion about which version is running
+- **Error Handling**: Built-in checks for uv installation and project structure
+
+**Requirements:**
+- Must have `uv` installed (`pip install uv`)
+- Must run from project root directory
+- Requires `pyproject.toml` in current directory
+
 **Stage B: Local Deployment Testing**
 ```bash
 # Build and test clean deployment

mcp_vector_search-0.12.3/QA_REPORT_ContentPane.md

@@ -0,0 +1,338 @@
+# QA Report: Content Pane Display Issue - RESOLVED
+
+**Date:** 2025-10-30
+**Reporter:** User
+**QA Engineer:** Claude (QA Agent)
+**Severity:** HIGH (Feature Not Working)
+**Status:** FIXED ✓
+
+---
+
+## Issue Summary
+
+**User Report:**
+"Should see the data inspector for all node clicks. If it's a directory, a directory list. A file = full file listing, etc"
+
+**Problem:**
+The content pane (data inspector) was NOT appearing when clicking directory or file nodes. Only leaf nodes (nodes without children) showed the content pane.
+
+---
+
+## Root Cause Analysis
+
+### Investigation Process
+
+1. **Server Status Check:**
+   - Visualization server running on port 8090: ✓
+   - File path: `/Users/masa/Projects/mcp-vector-search/src/mcp_vector_search/visualization/index.html`
+
+2. **Code Analysis:**
+   - Examined click handler in deployed `index.html` (lines 482-497)
+   - Compared with template in `visualize.py` (lines 1106-1121)
+   - **Identified version mismatch:** Deployed file had outdated code
+
+3. **Data Analysis:**
+   - Verified `chunk-graph.json` structure
+   - Directory nodes: `has_content: False` (by design, will show listing)
+   - File nodes: `has_content: False` (will aggregate from chunks)
+   - Function/Class nodes: `has_content: True` ✓
+
+### Root Cause
+
+The deployed `/Users/masa/Projects/mcp-vector-search/src/mcp_vector_search/visualization/index.html` contained an **outdated version** of the visualization code.
+
+**Buggy Code (Deployed Version):**
+```javascript
+function handleNodeClick(event, d) {
+    event.stopPropagation();
+
+    // If node has children, toggle expansion
+    if (hasChildren(d)) {
+        // PROBLEM: Only expand/collapse, NO content pane shown
+        if (collapsedNodes.has(d.id)) {
+            expandNode(d);
+        } else {
+            collapseNode(d);
+        }
+        renderGraph();
+    } else {
+        // Leaf node - show code viewer
+        showCodeViewer(d);  // Only called for leaf nodes!
+    }
+}
+```
+
+**Issues with Buggy Code:**
+- ❌ Directory nodes (have children) → Only expand/collapse
+- ❌ File nodes (have children) → Only expand/collapse
+- ✅ Leaf nodes (no children) → Show content pane
+- ❌ Missing functions: `showContentPane()`, `showDirectoryContents()`, `showFileContents()`, etc.
+- ❌ Missing CSS: `#content-pane` styling
+- ❌ Missing HTML: `<div id="content-pane">` element
+- ❌ Using old element: `#code-viewer` instead of `#content-pane`
+
+---
+
+## Fix Applied
+
+### Solution
+
+Regenerated `index.html` from the correct template in `visualize.py` (lines 561-1464).
+
+**Fixed Code (Template Version):**
+```javascript
+function handleNodeClick(event, d) {
+    event.stopPropagation();
+
+    // Always show content pane when clicking any node
+    showContentPane(d);  // ✓ FIXED: Called for ALL nodes
+
+    // If node has children, also toggle expansion
+    if (hasChildren(d)) {
+        if (collapsedNodes.has(d.id)) {
+            expandNode(d);
+        } else {
+            collapseNode(d);
+        }
+        renderGraph();
+    }
+}
+```
+
+### Components Added/Fixed
+
+**Functions Added:**
+1. ✓ `showContentPane(node)` - Main content display router (line 668)
+2. ✓ `showDirectoryContents(node, container)` - Directory listing (line 717)
+3. ✓ `showFileContents(node, container)` - File content aggregation (line 780)
+4. ✓ `showImportDetails(node, container)` - Import statement display (line 813)
+5. ✓ `showCodeContent(node, container)` - Code/docstring display (line 842)
+6. ✓ `closeContentPane()` - Close handler (line 870)
+
+**CSS Added:**
+- ✓ `#content-pane` - Fixed position, right-side panel (line 153)
+- ✓ `#content-pane.visible` - Slide-in animation (line 168)
+- ✓ `.pane-header`, `.pane-title`, `.pane-meta` - Header styling
+- ✓ `.pane-content` - Content area styling
+- ✓ `.directory-list` - Directory listing styles
+- ✓ `.import-details` - Import statement styles
+
+**HTML Added:**
+```html
+<div id="content-pane">
+    <div class="pane-header">
+        <button class="collapse-btn" onclick="closeContentPane()">×</button>
+        <div class="pane-title" id="pane-title"></div>
+        <div class="pane-meta" id="pane-meta"></div>
+    </div>
+    <div class="pane-content" id="pane-content"></div>
+</div>
+```
+
+### Implementation
+
+```bash
+# Regenerated index.html from correct template
+python3 << 'EOF'
+import re
+
+with open('src/mcp_vector_search/cli/commands/visualize.py', 'r') as f:
+    content = f.read()
+
+match = re.search(r'html_content = """(.*?)"""', content, re.DOTALL)
+if match:
+    html = match.group(1)
+    with open('src/mcp_vector_search/visualization/index.html', 'w') as f:
+        f.write(html)
+EOF
+```
+
+**File Details:**
+- Location: `/Users/masa/Projects/mcp-vector-search/src/mcp_vector_search/visualization/index.html`
+- Size: 32,145 bytes (previously: 23,632 bytes)
+- Template source: `visualize.py` lines 561-1464
+
+---
+
+## Verification Results
+
+### Code Verification (Automated) ✓
+
+```
+✓ FIXED: handleNodeClick() now calls showContentPane(d) for all nodes
+✓ Found: function showContentPane
+✓ Found: function showDirectoryContents
+✓ Found: function showFileContents
+✓ Found: function showImportDetails
+✓ Found: function showCodeContent
+✓ Found: function closeContentPane
+✓ Found: #content-pane CSS styling
+✓ Found: <div id='content-pane'> HTML element
+✓ File size matches expected template size (32,145 bytes)
+```
+
+### Expected Behavior After Fix
+
+**Test Case 1: Directory Node Click (📁)**
+- ✓ Click directory node → Content pane slides in from right
+- ✓ Shows directory name in header
+- ✓ Displays directory listing (subdirectories, files, code chunks)
+- ✓ Shows summary: "Total: X items (Y directories, Z files, N code chunks)"
+- ✓ Node expands/collapses children (if any)
+
+**Test Case 2: File Node Click (📄)**
+- ✓ Click file node → Content pane slides in from right
+- ✓ Shows filename in header
+- ✓ Shows "Contains X code chunks"
+- ✓ Displays full file content (aggregated from chunks, sorted by line)
+- ✓ Node expands/collapses children (if any)
+
+**Test Case 3: Import Node Click (⇄, L1)**
+- ✓ Click import node → Content pane slides in from right
+- ✓ Shows import statement as title
+- ✓ Displays "Import Statement:" section with code
+- ✓ Shows file path, line numbers, language metadata
+
+**Test Case 4: Function/Class Node Click (ƒ, C)**
+- ✓ Click function/class node → Content pane slides in from right
+- ✓ Shows function/class name in header
+- ✓ Displays docstring (if present) in highlighted section
+- ✓ Shows full code content
+
+**Test Case 5: UI/UX Verification**
+- ✓ Content pane slides in smoothly (CSS animation)
+- ✓ Fixed to right edge, 600px width, full height
+- ✓ Close button (×) visible and functional
+- ✓ Content scrollable if overflow
+- ✓ Clicked node highlighted with yellow glow
+
+---
+
+## Manual Browser Testing Required
+
+**Server:** http://localhost:8090
+**Status:** Running on port 8090
+
+### Testing Instructions
+
+**IMPORTANT:** You may need to **hard refresh** the browser to clear cache:
+- **Chrome/Edge:** Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
+- **Firefox:** Ctrl+F5 (Windows/Linux) or Cmd+Shift+R (Mac)
+- **Safari:** Cmd+Option+R
+
+### Test Checklist
+
+1. **Directory Nodes:**
+   - [ ] Click a directory (📁) → Content pane appears
+   - [ ] Shows directory listing with folders/files/chunks
+   - [ ] Close button (×) works
+
+2. **File Nodes:**
+   - [ ] Click a file (📄) → Content pane appears
+   - [ ] Shows full file content or chunk listing
+   - [ ] Close button (×) works
+
+3. **Import Nodes:**
+   - [ ] Expand a file, click an L1 import (⇄) → Content pane appears
+   - [ ] Shows import statement and metadata
+   - [ ] Close button (×) works
+
+4. **Function/Class Nodes:**
+   - [ ] Expand a file, click a function (ƒ) or class (C) → Content pane appears
+   - [ ] Shows code and docstring (if present)
+   - [ ] Close button (×) works
+
+5. **Browser Console:**
+   - [ ] Open DevTools (F12)
+   - [ ] Check Console tab for errors
+   - [ ] Should see NO "undefined function" errors
+   - [ ] Should see NO JavaScript errors when clicking nodes
+
+6. **Visual Inspection:**
+   - [ ] Content pane slides in from right smoothly
+   - [ ] Pane is 600px wide, full height
+   - [ ] Clicked node has yellow highlight glow
+   - [ ] Content is readable and properly styled
+
+---
+
+## Success Criteria
+
+- [x] ✓ Click handler calls `showContentPane()` for ALL nodes
+- [x] ✓ All required display functions present
+- [x] ✓ CSS styling for `#content-pane` present
+- [x] ✓ HTML `<div id="content-pane">` element present
+- [x] ✓ File size matches template (32KB+)
+- [ ] ⏳ Manual browser testing confirms all node types display content
+- [ ] ⏳ No JavaScript errors in browser console
+
+**Status:** Code fix verified ✓ | Browser testing pending ⏳
+
+---
+
+## Technical Details
+
+### File Changes
+
+**Modified File:**
+- Path: `/Users/masa/Projects/mcp-vector-search/src/mcp_vector_search/visualization/index.html`
+- Change: Regenerated from template in `visualize.py`
+- Lines changed: Entire file (23,632 → 32,145 bytes)
+
+**Key Code Changes:**
+
+1. **Click Handler (Line 1106-1121):**
+   ```diff
+   - if (hasChildren(d)) {
+   -     expandNode/collapseNode(d);
+   - } else {
+   -     showCodeViewer(d);
+   - }
+   + showContentPane(d);  // Always show for ALL nodes
+   + if (hasChildren(d)) {
+   +     expandNode/collapseNode(d);
+   + }
+   ```
+
+2. **Content Display Functions Added:**
+   - `showContentPane()` - Router based on node type
+   - `showDirectoryContents()` - Lists directory children
+   - `showFileContents()` - Aggregates file chunks
+   - `showImportDetails()` - Displays import statements
+   - `showCodeContent()` - Shows code and docstrings
+
+3. **UI Element Changed:**
+   - Old: `#code-viewer` (simple code display)
+   - New: `#content-pane` (full-featured inspector)
+
+### Why This Happened
+
+The deployed `index.html` was out of sync with the template in `visualize.py`. The template contains the correct, feature-complete code, but it was never deployed to the actual visualization directory.
+
+**Prevention:**
+- Consider using a build step to ensure `index.html` is always generated from template
+- Add a version comment to HTML files to track template sync
+- Document the relationship between `visualize.py` template and deployed `index.html`
+
+---
+
+## Conclusion
+
+**Issue:** RESOLVED ✓
+**Fix Applied:** Regenerated index.html from correct template
+**Code Verification:** PASSED ✓
+**Browser Testing:** PENDING (manual verification required)
+
+The content pane should now appear for ALL node clicks (directories, files, imports, functions, classes) as requested by the user. Each node type displays appropriate content in the data inspector panel.
+
+**Next Steps:**
+1. Hard refresh browser (Cmd+Shift+R / Ctrl+Shift+R)
+2. Test each node type click
+3. Verify content pane appears and displays correct content
+4. Check browser console for errors
+5. Report any remaining issues
+
+---
+
+**QA Sign-off:** Claude (QA Agent)
+**Date:** 2025-10-30