🔍 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:

1. Detect your current codebase directory.
2. Boot the dashboard on an isolated production port (default 4242).
3. 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

📸 Interface Preview

🌐 High-Level Architecture Overview

Dagre-powered hierarchical tier layout color-coded by module category:

🔍 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

• ⚡ 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.