GitNexus/gitnexus/TODO.md

GitNexus V2 Strategic Roadmap: The "Semantic Understanding" Upgrade

Context for Models: This document contains a comprehensive analysis of a competitor tool ("Noodlbox") and a detailed roadmap for integrating its best features into GitNexus. GitNexus is a browser-native (WASM) code analysis tool using KuzuDB and Tree-sitter. This roadmap aims to elevate GitNexus from a "Code Graph" to a "Semantic Code Understanding" platform.

---

1. Competitive Analysis: GitNexus vs. Noodlbox

Core Architecture

Feature	GitNexus (Current)	Noodlbox (Competitor)	Advantage
Runtime	100% Browser (WASM). Zero setup. Privacy-first.	CLI + Local Server. Requires installation/daemon.	GitNexus (UX/Privacy)
Storage	KuzuDB (WASM). Graph + Vector.	LanceDB. Graph + Vector.	Tied (Both robust)
Extraction	Tree-sitter (WASM).	Tree-sitter.	Tied
Integration	Custom MCP Bridge (Browser ↔ Local).	Direct CLI MCP Server.	Noodlbox (Simpler setup)

Conceptual Model (The Gap)

Feature	GitNexus	Noodlbox	Analysis
Grouping	File-based (Folders).	Communities. Algorithmic clustering of related code.	Noodlbox. Reveals logical architecture vs physical.
Flows	Raw CALLS edges.	Processes. Named execution paths (Entry → End).	Noodlbox. "How it works" vs "What calls what".
Search	Hybrid (BM25 + Vec).	Context Search.	Tied, but Noodlbox returns Processes.
Impact	Node Blast Radius.	Git Diff Impact. Unstaged/Staged analysis.	Noodlbox. Much better DevEx.
UX	Raw IDs/Filenames.	Labels. Human-readable names ("Auth System").	Noodlbox. Cognitive load reduction.

---

2. Strategic Goal: "The Graph of Meaning"

We need to move GitNexus beyond just mapping files and functions to mapping concepts and flows. Shift: Files -> Communities, Functions -> Processes, Edges -> Flows.

---

3. Implementation Roadmap

🔥 PHASE 1: The Semantic Layer (High Priority)

Transform the raw KuzuDB graph into high-level concepts.

1.1 Communities (Code Clusters)

Concept: Use modularity optimization to group tightly coupled symbols into "Communities" (e.g., "Auth System", "Payment Processing") regardless of folder structure.

• Algorithm: Implement Leiden Algorithm (superior to Louvain for refined clusters) or Louvain in WASM (or pure JS if graph small enough).
• Trigger: Run post-ingestion.
• Schema Update:
  • New Node: Community { id, label, cohesionScore }
  • New Edge: MEMBER_OF (Symbol -> Community)
• Metrics: Calculate Cohesion Score (internal edges / total edges) to rate cluster quality (0-1).
• Key Symbols: Identify diverse "Entry Points" (called from outside) and "Central Hubs" (high internal degree).

1.2 Processes (Execution Flows)

Concept: Trace and name execution paths often hidden in call graphs.

• Detection Heuristic:
  1. Find Entry Points: Functions called by Frameworks (e.g., handleRequest) or with 0 internal callers.
  2. Trace forward CALLS edges (limit depth/branching).
  3. Group linear paths.
• Schema Update:
  • New Node: Process { id, label, process_type: 'intra'|'cross' }
  • New Edge: STEP_IN_PROCESS { step_number } (Symbol -> Process)
• Process Labeling: Heuristic naming (e.g., [EntryFn]_[Action]).

1.3 Git Diff Impact Detection

Concept: Analyze work-in-progress code, not just the committed graph.

• MCP Tool: detect_impact(scope: 'unstaged' | 'staged')
• Workflow:
  1. MCP Client reads git diff.
  2. Parse diff to find changed symbols (e.g., src/auth.ts: function login).
  3. Query Graph for potentially_affected (Downstream callers).
  4. Crucial: Map affected symbols to Processes and Communities.
  5. Output: "Changing login affects 'Checkout Flow' and 'User Onboarding Process'".

---

🟡 PHASE 2: Cognitive UX (Medium Priority)

Make the complex graph human-readable.

2.1 Smart Labeling

Concept: Replacing IDs with meaningful names.

• Generator: Simple LLM pass or rule-based heuristic.
  • Input: Top file paths in Community (e.g., src/auth/*, src/login/*).
  • Output: Label "Authentication".
• Storage: .gitnexus/labels.json.
• Usage: UI & MCP tools display "Auth System" instead of "Community #12".

2.2 Architecture Generation (generate_map)

Concept: Auto-generated documentation that stays up to date.

• MCP Tool: gitnexus_generate_architecture
• Output: ARCHITECTURE/ folder.
  • README.md: Mermaid Diagram of Communities + Cross-community data flow.
  • {process_name}.md: Sequence diagrams of key processes.
• Value: Instant "Onboarding Docs" for any repo.

2.3 Centrality & Importance

Concept: Not all nodes are equal.

• Algorithm: PageRank or Betweenness Centrality.
• Use Case: Search results ranking. When searching "Auth", show the AuthService class before a random utility function used by it.

---

🟢 PHASE 3: Agentic Workflows (Low Priority)

Standardized "Thinking Patterns" for the LLM.

3.1 "Skills" (Structured Prompts)

Define rigid workflows for the Agent to prevent "wandering":

• Exploration Skill: Read Map -> Pick Community -> List Key Processes -> Drill Down.
• Debugging Skill: Error Msg -> Search Context -> Trace Backwards (Callers) -> Check Recent Changes.
• Refactoring Skill: Select Symbol -> Blast Radius -> Dependencies (In/Out) -> Plan Split.

3.2 Hooks

• Session Hook: auto-inject database-schema and high-level codebase-map at chat start.
• Search Hook: Intercept grep in IDE to attach semantic context ("This match is part of 'Payment Process'").

---

4. Technical Specs & Schema Changes

Proposed KuzuDB Schema V2

// Nodes
interface Community {
  id: string; // "comm_1"
  label: string; // "Authentication"
  cohesion: number; // 0.85
}

interface Process {
  id: string; // "proc_login_flow"
  label: string; // "Login Flow"
  type: 'intra_community' | 'cross_community';
}

// Relationships
// MEMBER_OF: Symbol -> Community
// STEP_IN_PROCESS: Symbol -> Process (property: step_index)

Algorithm Reference

• Leiden Algorithm:
  • Input: Adjacency matrix of CALLS + EXTENDS edges.
  • Output: Partition assignment (NodeID -> CommunityID).
  • Constraint: Must run fast in JS/WASM.
• Reciprocal Rank Fusion (RRF):
  • Already used for Search. Can be refined to weight "Key Symbols" (Centrality) higher.

---

5. Summary of Work to Be Done

1. Ingestion: Add CommunityDetection and ProcessTracing post-processors.
2. Schema: Add Community and Process tables.
3. MCP: Add detect_impact tool accepting git diffs.
4. UI: Visualize Communities (colored clusters) and Processes (animated paths).
5. Docs: Implement generate_map to export findings to Markdown.