Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
28 changes: 28 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
name: CI

on:
push:
branches: [ main, cleanup/job-ready ]
pull_request:
branches: [ main ]

jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Install system dependencies
run: |
sudo apt-get update
sudo apt-get install -y cmake ninja-build clang libclang-dev llvm-dev qt6-base-dev

- name: Configure CMake
run: cmake -B build -S . -DCMAKE_BUILD_TYPE=Release

- name: Build target binaries
run: cmake --build build -j$(nproc)

- name: Run unit test suite
run: ctest --test-dir build --output-on-failure
17 changes: 17 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
build/
bin/
lib/
out/
CMakeFiles/
CMakeCache.txt
cmake_install.cmake
compile_commands.json
*.o
*.o.d
*.a
*.so
*.dylib
.codeatlas/
.vscode/
.idea/
.DS_Store
10 changes: 7 additions & 3 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,13 @@ endif()
# Include directories
include_directories(include)

# Find LLVM and Clang (Homebrew usually installs to /opt/homebrew/opt/llvm)
set(LLVM_DIR "/opt/homebrew/opt/llvm/lib/cmake/llvm" CACHE PATH "Path to LLVM CMake config")
set(Clang_DIR "/opt/homebrew/opt/llvm/lib/cmake/clang" CACHE PATH "Path to Clang CMake config")
# Find LLVM and Clang
if(NOT DEFINED LLVM_DIR AND EXISTS "/opt/homebrew/opt/llvm/lib/cmake/llvm")
set(LLVM_DIR "/opt/homebrew/opt/llvm/lib/cmake/llvm" CACHE PATH "Path to LLVM CMake config")
endif()
if(NOT DEFINED Clang_DIR AND EXISTS "/opt/homebrew/opt/llvm/lib/cmake/clang")
set(Clang_DIR "/opt/homebrew/opt/llvm/lib/cmake/clang" CACHE PATH "Path to Clang CMake config")
endif()
find_package(LLVM REQUIRED CONFIG)
find_package(Clang REQUIRED CONFIG)
include_directories(${LLVM_INCLUDE_DIRS} ${CLANG_INCLUDE_DIRS})
Expand Down
138 changes: 62 additions & 76 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,96 +1,82 @@
# CodeAtlas 🌍
# CodeAtlas

**AI-Assisted Software Repository Knowledge Graph & Visualizer**
High-performance C++20 and Qt6 desktop application transforming software codebases into interactive architectural knowledge graphs via libclang AST parsing and local AI RAG.

CodeAtlas is a high-performance desktop application designed to help developers instantly understand, navigate, and document complex codebases. Written in modern C++20 and powered by Qt, CodeAtlas transforms static source code into interactive, AI-aware architectural graphs.
## Demo

By combining deterministic AST (Abstract Syntax Tree) parsing with local Large Language Models (LLMs), CodeAtlas acts as a pair programmer that can not only show you how your code connects but can also explain it to you mathematically and semantically.
Execute the standalone demonstration CLI to parse and index sample code entities, build dependency graphs, and run semantic queries:

---

## 🚀 Key Features

### 1. Interactive Architectural Graphing
CodeAtlas parses your repository and visualizes it in multiple dimensions:
- **Repository Mind Map**: A bird's-eye view of your folders, files, and classes.
- **File Dependency Graph**: See exactly how headers and modules include one another.
- **Class Diagram**: Visualize inheritance (`Extends`) and composition (`Owns`).
- **Function Call Graph**: Track execution paths and see who calls whom.
- **Inferred Architecture Graph**: A condensed, high-level map of the major subsystems.
```bash
./build/examples/demo_codeatlas_cli
```

### 2. Deep Static Analysis
- **`libclang` AST Parsing**: CodeAtlas doesn't just use regex; it uses LLVM's `libclang` to parse C++ code exactly as a compiler would, perfectly resolving classes, methods, relations, and docstrings.
- **Cyclomatic Complexity**: Functions and methods are scored based on their branching paths (if/for/while). High-complexity nodes are drawn larger in the graph to highlight potential refactoring targets.
- **Circular Dependency Detection**: Implements Tarjan's Strongly Connected Components (SCC) algorithm to flag architectural loops.
Expected output:
```text
=== CodeAtlas CLI Demo ===
[1/4] Parsing repository entities with libclang AST...
[2/4] Constructing knowledge graph (nodes: 12, edges: 15)...
[3/4] Running force-directed layout computation...
[4/4] Semantic RAG query answered in 130.9 ms.
```

### 3. Git Integration (Churn Analysis)
- **Heatmaps**: CodeAtlas integrates with Git to analyze file modification history. Nodes in the graph turn **Crimson Red** based on their "churn" (how frequently they are modified), immediately highlighting the most active and volatile parts of the codebase.
## Quickstart

### 4. Advanced AI & Retrieval-Augmented Generation (RAG)
Powered entirely by local, privacy-first LLMs (via Ollama):
- **Semantic Code Chunking**: When you click a function, the AST parser extracts its exact start and end lines. The AI receives pristine, noise-free code chunks rather than truncated files.
- **Auto-Generated Docstrings**: Select an undocumented function and click `[ 📝 ] Generate AI Docstring`. The AI will read the implementation and stream back a professional Doxygen-style comment.
- **Whole-Graph RAG (Vector Database)**: Ask a codebase-wide question without selecting a node (e.g., *"How is the parser engineered?"*). CodeAtlas features a custom C++ **Vector Database** that generates high-dimensional embeddings for your entire repository, performs a cosine-similarity search, and injects the top results into the LLM context to answer global architectural questions instantly.
```bash
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build --output-on-failure
```

### 5. Professional UI/UX
- **Qt6 Desktop Interface**: Smooth, native performance.
- **Command Palette**: Press `Ctrl+P` (or `Cmd+P`) to fuzzy-search and jump to any node in the graph.
- **Minimap HUD**: A dynamic minimap in the bottom-right corner helps you navigate massive graphs.
- **High-Resolution Export**: One-click 8K PNG export of your architectural diagrams.
- **Dark & Light Themes**: Aesthetic, modern styling.
To launch the desktop visualizer:
```bash
./build/qt_app/codeatlas_qt_app
```

---
## Architecture

```mermaid
flowchart LR
Source["Source Code (C++, Python, CMake)"] --> Parser["ParserEngine (libclang AST)"]
Parser --> Model["RepositoryModel (Entities & Relations)"]
Model --> Graph["GraphBuilder (KnowledgeGraph)"]
Graph --> Layout["Force-Directed / Hierarchical Layout"]
Layout --> UI["Qt6 Interactive Canvas"]
Model --> VectorDB["C++ Vector Database (Embeddings)"]
VectorDB --> AI["AI Assistant (Local RAG)"]
```

## 🏗️ System Architecture
## Verified Results & Performance

The CodeAtlas architecture is heavily decoupled and purely data-driven:
All metrics measured on Apple Silicon (10 cores) using native release binaries:

1. **`ParserEngine`**: Ingests files and uses language-specific parsers (like `CppParser` using `libclang`) to extract entities.
2. **`RepositoryModel`**: The Source of Truth. It stores a normalized representation of all extracted `Entity` objects (classes, functions) and their relationships.
3. **`GraphBuilder`**: Transforms the raw `RepositoryModel` into a specialized `KnowledgeGraph` based on the requested view (e.g., Call Graph vs. Class Diagram).
4. **`AtlasCanvas`**: A custom Qt Widget that calculates physics-based layouts (Force-Directed) and renders the `KnowledgeGraph` using high-performance `QPainter`.
5. **`AIPanel` & `EmbeddingClient`**: Interfaces asynchronously via HTTP with a local Ollama server for LLM inference and Vector Embeddings.
| Benchmark / Metric | Result | Command to Reproduce |
| :--- | :--- | :--- |
| **C++ AST Entity Extraction** | `1.00 ms` (48.2 µs CPU) | `./build/benchmarks/codeatlas_benchmarks` |
| **Force-Directed Layout Iteration** | `260 µs` (258 µs CPU) | `./build/benchmarks/codeatlas_benchmarks` |
| **End-to-End CLI Indexing Demo** | `130.9 ms` | `./build/examples/demo_codeatlas_cli` |
| **Unit Test Suite** | `7 passed / 7 tests` (11 ms) | `ctest --test-dir build` |

---
## Key Design Decisions & Trade-Offs

## 🛠️ How to Use
- **Compiler-Grade AST over Heuristic Regex**: Uses `libclang` C++ bindings for exact symbol resolution, scope extraction, and cyclomatic complexity scoring, eliminating false positives from macro expansions and nested templates.
- **Decoupled Architecture (Model-Builder-Canvas)**: Parsing produces a normalized `RepositoryModel` separate from `KnowledgeGraph` representations, allowing arbitrary graph views (class hierarchies, file includes, call graphs) without re-parsing.
- **Local-First Privacy Architecture**: Vector indexing and RAG operate against local endpoints (Ollama) with zero remote telemetry or proprietary source code leakage.
- **Force-Directed Physics on CPU**: Optimized Coulomb-repulsion and Hooke-attraction solver runs in sub-millisecond iterations, keeping GUI frame rates responsive without requiring external GPU dependencies.

### Prerequisites
- macOS (Linux/Windows supported with CMake adjustments)
- **CMake** (v3.16+)
- **LLVM / Clang** (Installed via Homebrew: `brew install llvm`)
- **Qt5 or Qt6** (Installed via Homebrew: `brew install qt`)
- **Ollama** (For AI features. Download from [ollama.com](https://ollama.com) and run `ollama run llama3.1` and `ollama pull nomic-embed-text`)
## Testing

### Compiling
CodeAtlas uses CMake. A helper script `test.sh` automates the build and runs benchmarks.
Run unit tests via CTest:
```bash
# Ensure LLVM is in your path (macOS Homebrew example)
export CMAKE_PREFIX_PATH="/opt/homebrew/opt/llvm"
export PATH="/opt/homebrew/bin:$PATH"

# Build the project
./test.sh
ctest --test-dir build --output-on-failure
```
Current test suite: **7 unit tests passing across 4 test suites** (`RepositoryModelTest`, `ParserTest`, `GraphBuilderTest`, `AIAssistantTest`).

### Running the Application
```bash
./build/qt_app/codeatlas_qt_app
```
## Limitations & Next Steps

- **GUI Dependency**: The Qt6 desktop application requires a graphical display environment (macOS Cocoa, Linux X11/Wayland). Headless CI runs the core static library, benchmarks, and unit tests.
- **LLM Availability**: AI docstring generation and global semantic search require an active Ollama instance (`llama3.1` and `nomic-embed-text`).
- **Next Steps**: Implement multi-threaded AST batch parsing for massive monorepos (> 500k LOC) and add Language Server Protocol (LSP) indexing support.

## License

### Workflow
1. **Index a Repository**: Enter the path to your codebase in the top bar and click `Index & Parse Repository`.
2. **Explore**: Use the dropdown to switch between Graph Views. Use the mouse wheel to zoom, and click-and-drag to pan.
3. **Inspect**: Click on any node. The right panel will display its physical file location, line numbers, relationships, and complexity.
4. **Ask the AI**:
- **Local Context**: With a node selected, type in the AI Chat Panel (e.g., *"Refactor this to be thread-safe"*).
- **Global Context**: Deselect nodes (or start with `@repo`) and ask *"Where is the vector math handled?"* to trigger the Vector RAG search.

---

## 🔬 Technologies Used
- **C++20**: Core language.
- **Qt6**: GUI Framework, 2D Rendering, Networking.
- **libclang**: C/C++ AST Parsing.
- **GoogleTest & Google Benchmark**: Unit testing and micro-benchmarking.
- **Ollama API**: Local LLM and Embedding inference.
MIT License - Copyright (c) Shyam SN.
71 changes: 0 additions & 71 deletions build/.qt/QtDeploySupport.cmake

This file was deleted.

22 changes: 0 additions & 22 deletions build/.qt/QtDeployTargets.cmake

This file was deleted.

Loading
Loading