🔍 RepoTrace

An interactive, AST-powered codebase dependency graph and architecture explorer for TypeScript, JavaScript, Python, and Dart / Flutter repositories, built with ts-morph, React Flow, and Dagre.

Statically parses local repositories into an Abstract Syntax Tree (AST), resolves internal module imports/exports, maps architectural layers via Kahn's Topological Sort, and animates code execution flow step-by-step.

🚀 Getting Started

⚡ Instant Run via `npx` (No Clone or Install Needed!)

Inside any local TypeScript, JavaScript, Python, or Flutter/Dart project on your machine, simply run:

npx repotrace

RepoTrace will automatically:

Detect your current codebase directory.
Boot the dashboard on an isolated production port (default 4242).
Launch your default browser to http://localhost:4242 and render your codebase graph!

CLI Options:

# Analyze a specific project path
npx repotrace ./my-project

# Run on a custom port
npx repotrace --port 5050

# Run in headless/server mode (skip auto-opening browser)
npx repotrace --no-open

# View all CLI options
npx repotrace --help

💻 Local Development & Contributing

If you want to contribute to or hack on RepoTrace:

# 1. Clone repository
git clone https://github.com/your-username/repotrace.git
cd repotrace

# 2. Install dependencies
npm install

# 3. Start development servers (Vite :5173 + Express :3001)
npm run dev

🎥 Demo Video

Watch RepoTrace explore codebases, trace architectural execution flow, and cluster directories in real time:

▶️ Click here to watch the full demo on YouTube

📸 Interface Preview

🌐 High-Level Architecture Overview

Dagre-powered hierarchical tier layout color-coded by module category with circuit blueprint corridor routing:

🔍 Node Inspection & Flow Stepper

Inspect discovered symbols (components, hooks, functions, interfaces) with caller/dependency counts, or step through execution flow step-by-step using the bottom canvas player:

✨ Features

⚡ Circuit Blueprint Flow Engine: Clean orthogonal corridor routing (smoothstep) eliminates spaghetti crisscrossing wires. Hovering any card dynamically illuminates incoming callers in cyan (#06b6d4) and outgoing dependencies in purple (#a855f7).
🎯 Focus Neighborhood Mode: 1-click micro-blueprint isolation ([ Callers ] ──▶ [ Active File ] ──▶ [ Dependencies ]) that automatically fits to the screen with zero manual panning or scrolling needed.
📁 Folder View Layout & Directory Clustering: Seamlessly switch between dependency flow and glassmorphic directory boundary containers that group files inside their physical folders.
🔍 Real-Time Folder & File Search: Search files and physical folders simultaneously, spotlighting matching folder containers with glowing borders and camera centering.
⚡ Multi-Language AST Engine (TypeScript, JavaScript, Python, Dart/Flutter): Statically inspects and maps .ts, .tsx, .js, .jsx, .mjs, .cjs, .py, and .dart files. Resolves ES Modules, CommonJS (require()), Python imports, and Flutter package imports (package:<app>/... via pubspec.yaml). Honors path aliases (@/*, ~/*) and automatically ignores build caches, virtual environments (.venv, venv), Flutter platform runners (android/, ios/), and vendor packages (node_modules, .dart_tool).
🔍 Discovered Symbols & Functions: Extracts internal declarations from every file—React Components, Custom Hooks, Helper Functions, TypeScript Interfaces, Type Aliases, and Classes—badging public exports versus private declarations.
📂 Zero-Upload Directory Navigator & Direct Path Input: Select any repository on your computer without uploading or moving source files. Includes an in-app filesystem navigator with quick shortcuts, direct path input/paste, and automatic codebase detection (package.json/tsconfig.json).
📐 Automatic Dagre Layout: Computes optimal hierarchical coordinates supporting Top-to-Bottom (TB) and Left-to-Right (LR) orientations with smooth bezier connections.
🔄 Bidirectional Topological Sort:
- Execution Flow (Entrypoint → Leaves, default): Traces the runtime boot path starting at index.tsx down through containers, UI components, and leaf utilities.
- Build Order (Leaves → Entrypoint): Traces the compilation sequence starting at foundational primitives with zero dependencies up toward the entrypoint.
🛡️ Fault-Tolerant Cycle Breaking: Mathematically detects circular import loops ($A \rightarrow B \rightarrow C \rightarrow A$) using Kahn's algorithm and DFS back-edge detection. Bypasses the deadlock to ensure 100% of your codebase remains sorted and visible, while highlighting cyclic nodes in pulsing crimson red.
🎬 Interactive Canvas Flow Player: Floating player docked at the bottom of the canvas. Traverses the codebase step-by-step or with auto-play, smoothly illuminating each module in glowing amber as it resolves.
🎯 1-Hop Neighborhood Isolation: Clicking any file isolates its direct incoming callers (cyan) and outgoing dependencies (purple), dimming unrelated files to reduce visual noise.

🏗️ Architecture

The system decouples the Backend AST Engine (Data Producer) from the Frontend Canvas (Data Consumer):

flowchart TD
    subgraph Frontend ["Client (React 18 + Vite + React Flow + Dagre)"]
        UI[User inputs path or picks folder]
        TopBar[TopBar Toolbar]
        Canvas[React Flow Graph Canvas]
        Drawer[Topo Order Drawer]
        Player[Canvas Flow Player]
        DagreEngine[Dagre Layout Engine]
        TopoEngine[Kahn Topo Sort & Cycle Breaker]
    end

    subgraph Backend ["Server (Node.js + Express + ts-morph)"]
        API["Express API (:3001)"]
        Explorer["Directory Explorer (/api/explore)"]
        WinDialog["Windows Dialog (/api/browse-folder)"]
        Analyzer["CodebaseAnalyzer (server/analyzer.ts)"]
        TSMorph["ts-morph AST Engine"]
    end

    UI --> TopBar
    TopBar -->|POST /api/analyze| API
    TopBar -->|POST /api/browse-folder| WinDialog
    TopBar -->|GET /api/explore| Explorer
    API --> Analyzer
    Analyzer --> TSMorph
    TSMorph -->|AST Nodes & Symbols| Analyzer
    Analyzer -->|JSON: nodes, edges, symbols| API
    API -->|GraphPayload| Frontend
    Frontend --> DagreEngine
    Frontend --> TopoEngine
    DagreEngine --> Canvas
    TopoEngine --> Drawer
    TopoEngine --> Player
    Player -->|Sync active step| Canvas

📁 Repository Structure

repotrace/
├── server/                         # Backend AST & Discovery Engine
│   ├── analyzer.ts                 # CodebaseAnalyzer: ts-morph AST parser & symbol extractor
│   ├── index.ts                    # Express API server & routes (/api/analyze, /api/explore)
│   ├── mockData.ts                 # Fallback graph data for resilience
│   ├── test-analyzer.ts            # CLI test runner for AST extraction
│   └── test-topo.ts                # CLI test runner for Topo Sort & Cycle Breaking
│
├── src/                            # Frontend UI & Visualization Layer
│   ├── components/                 # UI Components
│   │   ├── CanvasFlowPlayer.tsx    # Bottom floating stepper & playback controls
│   │   ├── CycleAlertModal.tsx     # Circular dependency loop diagnosis dialog
│   │   ├── FileNode.tsx            # Custom React Flow card (badges, states, counters)
│   │   ├── FolderBrowserModal.tsx  # In-app visual directory picker & OS dialog trigger
│   │   ├── GraphCanvas.tsx         # React Flow canvas wrapper with minimap & controls
│   │   ├── Sidebar.tsx             # Selected node inspector (symbols, callers, deps)
│   │   ├── TopBar.tsx              # Top toolbar with search, presets, layout & topo triggers
│   │   └── TopoOrderDrawer.tsx     # Slide-out topological architectural tier guide
│   │
│   ├── utils/                      # Client Graph Utilities & Algorithms
│   │   ├── graphAnalysis.ts        # Category heuristics & 1-hop neighborhood math
│   │   ├── layout.ts               # Dagre layout coordinate math & edge styling
│   │   └── topoSort.ts             # Fault-tolerant Kahn's algorithm & cycle breaking
│   │
│   ├── types/                      # Domain Type Definitions
│   │   └── graph.ts                # RawNode, RawEdge, GraphPayload, FileSymbol, FileNodeData
│   │
│   ├── App.tsx                     # Root application coordinator
│   ├── main.tsx                    # React DOM entrypoint
│   └── index.css                   # Tailwind CSS utilities
│
├── example-repo/                   # Realistic 10-file React+TS sample chat app
├── progress.md                     # Roadmap tracking and completed milestones
├── walkthrough.md                  # In-depth technical architecture guide
└── package.json                    # Scripts and dependencies

🧪 Testing & Validation

Run AST Analyzer Test

Statically parses example-repo and logs discovered symbols, outgoing dependencies, and incoming callers to the terminal:

npm run test:analyzer

Run Topological Sort & Cycle Breaking Test

Runs Kahn's algorithm over example-repo (verifying 7 architectural tiers) and an intentionally cyclic test graph ($A \rightarrow B \rightarrow C \rightarrow A$), verifying fault-tolerant cycle breaking:

npm run test:topo

🌐 Language Extensibility

While the current AST analyzer uses ts-morph for TypeScript & JavaScript (.ts, .tsx, .js, .jsx), the frontend graph consumer is language-agnostic.

To support other languages (Python, Go, Rust, Java), implement an adapter in server/ that emits the standardized { nodes, edges } JSON structure:

Python: Use Python's built-in ast module or Tree-sitter.
Go: Use go/parser and go/ast.
Rust: Use syn or ra_ap_syntax.

The entire frontend canvas, Dagre layout, Topological Sort drawer, and Stepper player will work immediately without any client-side changes.

🤝 Contributing

Contributions make the open-source community an incredible place to learn, inspire, and create!

Read our Contributing Guide to get started with local setup, branch conventions, and testing workflows.
Check out open issues or submit ideas for new language adapters, symbol call-graphs, or canvas themes.
Please review and adhere to our Code of Conduct.

📄 License

This project is licensed under the MIT License.

FilesExpand file tree

README.md

Latest commit

History