RepoAtlas

Interactive concept maps for TypeScript/JavaScript codebases.

RepoAtlas statically analyzes your repository and generates colorful, interactive graph visualizations — no AI, no LLMs, just pure static analysis.

Features

• Dependency Map — module import/export relationships
• Folder Structure Map — directory hierarchy as a tree graph
• Call Graph — function-to-function call relationships
• API Route Map — detect Express/Fastify/Next.js route handlers
• Circular dependency detection with red highlighting
• Dead code detection — exported symbols never imported
• Incremental caching — only re-parse changed files
• Interactive visualization — zoom, pan, search, filter, minimap
• Export to SVG

Installation

# Use without installing (recommended for one-off use)
npx repoatlas analyze .

# Install globally so the `repoatlas` command is available everywhere
npm install -g repoatlas

# Install as a dev dependency (use via npx or package.json scripts)
npm install --save-dev repoatlas

Note: If you install as a local dev dependency (--save-dev), the repoatlas command won't be available directly in your terminal. Use npx repoatlas instead, or add it to your package.json scripts:

{
  "scripts": {
    "analyze": "repoatlas analyze ."
  }
}

Then run npm run analyze.

Quick Start

# Analyze the current directory
repoatlas analyze .

# Analyze a specific path
repoatlas analyze ./packages/my-lib

# Output JSON only (no server)
repoatlas analyze . --json

# Force full re-analysis
repoatlas analyze . --no-cache

# Generate only specific maps
repoatlas analyze . --map dependency,api

Then open your browser at http://localhost:3001 to explore the visualization.

CLI Reference

repoatlas analyze [path] [options]

Arguments:
  path                    Directory to analyze (default: current directory)

Options:
  -o, --output <dir>      Output directory (default: .repoatlas)
  -p, --port <port>       Server port (default: 3001)
  --json                  Output graph.json only, skip server
  --no-cache              Force full re-analysis (ignore cache)
  --include <patterns...> Glob patterns to include
  --exclude <patterns...> Glob patterns to exclude
  --map <types>           Maps to generate, comma-separated:
                          dependency,folder,callgraph,api
                          (default: all)
  --export-svg            Open browser for SVG export
  -V, --version           Show version
  -h, --help              Show help

Examples

# Analyze only src/, exclude tests
repoatlas analyze . --include "src/**" --exclude "**/*.test.*"

# Use a custom port and output dir
repoatlas analyze . --port 4000 --output .cache/repoatlas

# Generate dependency and API maps only
repoatlas analyze . --map dependency,api

# CI mode: just dump the JSON
repoatlas analyze . --json --no-cache

Programmatic API

import { analyze, filterGraph } from 'repoatlas';
import type { RepoGraph, MapType } from 'repoatlas';

// Analyze a directory
const graph: RepoGraph = await analyze('./src', {
  maps: ['dependency', 'callgraph'],
  cache: true,
  exclude: ['**/*.test.*'],
});

// Access the full graph
console.log(`${graph.nodes.length} nodes`);
console.log(`${graph.edges.length} edges`);
console.log(`Circular deps:`, graph.metadata.circularDeps);
console.log(`Dead code:`, graph.metadata.deadCode);

// Get a filtered map view
const depMap = filterGraph(graph, 'dependency');
const importEdges = depMap.edges.filter(e => e.type === 'imports');

// Find all API route nodes
const routes = graph.nodes.filter(n => n.type === 'apiRoute');
routes.forEach(r => console.log(r.label, r.filePath));

analyze(targetDir, options?)

| Option | Type | Default | Description | |--------|------|---------|-------------| | maps | MapType[] | all | Which maps to generate | | cache | boolean | true | Use incremental cache | | noCache | boolean | false | Force full re-analysis | | include | string[] | ['**/*.{ts,tsx,js,jsx}'] | Glob patterns to include | | exclude | string[] | default excludes | Glob patterns to exclude | | output | string | '.repoatlas' | Cache output directory | | port | number | 3001 | Server port (CLI only) | | json | boolean | false | JSON only, no server |

filterGraph(graph, mapType)

Returns a filtered RepoGraph view for the given map type: 'dependency', 'folder', 'callgraph', or 'api'.

Config File

Create repoatlas.config.js in your project root:

// repoatlas.config.js
module.exports = {
  include: ['src/**'],
  exclude: ['**/*.test.*', '**/*.spec.*'],
  maps: ['dependency', 'folder', 'callgraph', 'api'],
  port: 3001,
  output: '.repoatlas',
  theme: {
    file: '#6b7280',
    function: '#3b82f6',
    class: '#8b5cf6',
    apiRoute: '#f97316',
    component: '#ec4899',
    folder: '#10b981',
    store: '#a855f7',
    database: '#ef4444',
  },
};

Node Types & Colors

| Type | Color | Description | |------|-------|-------------| | file | Gray #6b7280 | TypeScript/JavaScript source files | | function | Blue #3b82f6 | Named functions and arrow functions | | class | Purple #8b5cf6 | Class declarations | | apiRoute | Orange #f97316 | Express/Fastify/Next.js route handlers | | component | Pink #ec4899 | React/JSX components | | folder | Green #10b981 | Directories | | store | Purple #a855f7 | State stores (Redux, Zustand, etc.) | | database | Red #ef4444 | Database connections/models |

Visualization Features

• Map switcher — switch between all four map types
• Node click → sidebar showing dependencies, functions, metadata
• Search — filter nodes by name, highlights matches
• Type filters — show/hide node types with checkboxes
• Layout options — hierarchical, force-directed, circular, breadth-first
• Minimap — overview of the full graph
• Hover highlight — connected edges and neighbors highlighted
• Circular dep badges — red borders on nodes in cycles
• Dead code dimming — semi-transparent nodes for unused exports
• Export SVG — download current view as SVG

Output Files

After analysis, .repoatlas/ contains:

| File | Description | |------|-------------| | graph.json | Full graph with all nodes and edges | | dependency.json | Filtered dependency map | | folder.json | Filtered folder structure map | | callgraph.json | Filtered call graph | | api.json | Filtered API routes map | | file-index.json | File hash index for incremental caching | | dependency-cache.json | Per-file parsed data cache |

Supported Frameworks

Import detection: Any ES module import/export syntax

Route detection:

• Express: app.get(), app.post(), router.get(), etc.
• Fastify: fastify.get(), fastify.post(), etc.
• Next.js: pages/api/** (Pages Router), app/**/route.ts (App Router)

Error Handling

• Syntax errors: file is skipped with a warning, analysis continues
• Missing tsconfig.json: falls back to default compiler options
• Large files (>10k lines): parsed with a performance warning
• Port in use: clear error message, use --port to change

Requirements

• Node.js >= 18
• Works with TypeScript and JavaScript projects

Concept Maps Reference

A concept map represents a codebase as a graph of nodes (entities) and edges (relationships). RepoAtlas generates four distinct maps, each highlighting a different architectural dimension.

1. Dependency Map

What it shows: Which modules import which other modules.

| Node type | Description | |-----------|-------------| | file | TypeScript/JavaScript source file | | component | JSX/TSX file exporting a React component |

| Edge | Style | Description | |------|-------|-------------| | imports | Solid → | File A imports something from File B |

Import type metadata:

• named — import { foo, bar } from './module'
• default — import MyThing from './module'
• namespace — import * as utils from './utils'
• dynamic — await import('./lazy-module') (lazy-loaded)

Use cases: understand coupling, find god modules, plan refactors, detect circular dependencies.

src/app.ts ──imports──▶ src/router.ts ──imports──▶ src/handlers/users.ts
src/handlers/users.ts ──imports──▶ src/db/users.ts

# Circular dependency (flagged red):
src/a.ts ──imports──▶ src/b.ts ──imports──▶ src/a.ts  ← cycle!

2. Folder Structure Map

What it shows: The directory hierarchy with files nested inside their parent folders.

| Node type | Description | |-----------|-------------| | folder | Directory (green squares) | | file / component | Source file inside the folder |

| Edge | Style | Description | |------|-------|-------------| | contains | Dotted → | Folder contains file or subfolder |

Use cases: understand project layout, spot unbalanced structures, onboarding, plan reorganization.

src/ (folder)
├── api/ (folder)
│   ├── routes.ts
│   └── middleware.ts
├── components/ (folder)
│   ├── Button.tsx
│   └── Modal.tsx
└── utils.ts

3. Call Graph

What it shows: Which functions call which other functions, and where functions live in their files.

| Node type | Description | |-----------|-------------| | file / component | Source file (container) | | function | Named function or arrow function | | class | Class declaration |

| Edge | Style | Description | |------|-------|-------------| | contains | Dotted → | File/class contains a function/method | | calls | Dashed → | Function A calls Function B |

Use cases: trace execution paths, find unused functions, identify hotspots, understand class structure.

Note: RepoAtlas currently tracks intra-file calls. Cross-file call tracking requires full type resolution and is planned for a future release.

src/service.ts (file)
├── UserService (class)
│   ├── createUser ──calls──▶ validateEmail
│   ├── validateEmail
│   └── sendWelcomeEmail ──calls──▶ formatTemplate
└── formatTemplate

4. API Route Map

What it shows: Which files define API endpoints and what those endpoints are.

| Node type | Description | |-----------|-------------| | file / component | File containing route handlers | | apiRoute | Individual HTTP route (method + path) |

| Edge | Style | Description | |------|-------|-------------| | routes | Thick solid → | File defines this route | | imports | Solid → | Route file's dependencies |

Supported frameworks:

// Express / Fastify
app.get('/users', getUsersHandler);
router.post('/users', createUserHandler);

// Next.js Pages Router (inferred from path)
// pages/api/users.ts → GET /api/users

// Next.js App Router
// app/api/users/route.ts
export async function GET(req: Request) { ... }
export async function POST(req: Request) { ... }

Use cases: API inventory, security audits, coverage analysis, microservices migration, onboarding.

src/routes/
├── auth.ts ── POST /auth/login, POST /auth/logout, POST /auth/refresh
├── users.ts ── GET /users, POST /users, GET /users/:id, DELETE /users/:id
└── health.ts ── GET /health

Bonus: Circular Dependency Detection

RepoAtlas runs a DFS on the file-level dependency graph to find cycles. Results are:

• Listed in graph.metadata.circularDeps
• Shown with red borders on affected nodes in the UI
• Displayed as a warning banner when any cycles exist

Circular deps can cause initialization order bugs, bundler issues, and difficulty testing modules.

Bonus: Dead Code Detection

RepoAtlas compares exported symbols vs imported symbols across the whole repo. Symbols exported but never imported anywhere are flagged:

• Listed in graph.metadata.deadCode as filePath::symbolName
• Affected file nodes are dimmed (50% opacity) in the UI

Only files within the analyzed directory are considered. Always verify before deleting.

License

MIT