code-orient

🚀 AI-free Codebase Explainer - A CLI tool that analyzes repositories and generates comprehensive documentation including architecture overviews, dependency graphs, and onboarding guides.

✨ Features

• 📊 Architecture Overview - Identifies layers, patterns, and tech stack
• 🔗 Dependency Graph - Visualizes module and file dependencies with Mermaid diagrams
• 📚 Onboarding Guide - "Where to start" guide for new developers
• ⚠️ Risky Files Detection - Identifies god objects and complex files
• 🎨 Mermaid Diagrams - Generates visual dependency graphs
• 🔍 AST-based Analysis - Uses ts-morph for accurate TypeScript/JavaScript parsing
• 🚫 No AI Required - Deterministic analysis based on code structure

📦 Installation

Global Installation

pnpm add -g code-orient

Using pnpm dlx (No Installation)

pnpm dlx code-orient ./my-repo

Using npx

npx code-orient ./my-repo

🚀 Quick Start

# Analyze a repository
code-orient ./path-to-repo

# Specify custom output directory
code-orient ./path-to-repo -o ./docs

# Skip diagram generation (faster)
code-orient ./path-to-repo --no-diagrams

📋 Command Line Options

Usage: code-orient <repo-path> [options]

Options:
  -o, --output <dir>     Output directory for generated reports (default: "./code-orient-output")
  --no-diagrams          Skip generating diagrams
  -h, --help             Display help for command
  -V, --version          Display version number

📄 Generated Reports

The tool generates the following markdown files in the output directory:

File	Description
README.md	Overview and summary of the analysis
architecture.md	Architecture layers, patterns, and tech stack
dependency-graph.md	Module and file dependencies with Mermaid diagrams
onboarding-guide.md	Step-by-step guide for new developers
risky-files.md	Files that may need refactoring
dependency-graph.mmd	Mermaid diagram source file (if diagrams enabled)

🔧 How It Works

1. AST Parsing - Uses ts-morph to parse TypeScript/JavaScript files
2. Module Detection - Identifies modules based on directory structure
3. Dependency Analysis - Tracks imports/exports to build dependency graph
4. Complexity Metrics - Calculates cyclomatic complexity and identifies risky files
5. Pattern Recognition - Detects common architectural patterns (hooks, services, components)
6. Report Generation - Creates markdown reports with diagrams

📊 Example Output

Architecture Overview

## 🏗️ Architecture Layers

### Presentation Layer
UI components, views, and user-facing elements

### Service Layer
Business logic, API clients, and external service integrations

### Data Layer
Data models, entities, type definitions, and schemas

Dependency Graph

graph TD
  components --> services
  services --> models
  hooks --> components

Loading

Onboarding Guide

The tool generates a comprehensive guide including:

• Entry points to start reading
• Key modules to understand
• Learning path recommendations
• Code organization patterns
• Things to watch out for

🛠️ Development

Prerequisites

• Node.js 18+
• pnpm 8+

Setup

# Clone the repository
git clone <repo-url>
cd code-orient

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run locally
pnpm dev ./path-to-repo

# Or run the built version
pnpm start ./path-to-repo

Project Structure

code-orient/
├── src/
│   ├── cli.ts              # CLI entry point
│   ├── analyzer.ts          # Main codebase analyzer
│   ├── architecture.ts      # Architecture pattern detection
│   ├── complexity.ts        # Complexity and risk analysis
│   ├── report.ts            # Report generator
│   ├── types.ts             # TypeScript type definitions
│   └── reports/             # Individual report generators
│       ├── architecture.ts
│       ├── dependency.ts
│       ├── onboarding.ts
│       └── risky-files.ts
├── dist/                    # Compiled JavaScript output
└── package.json

🎯 Use Cases

• Onboarding New Developers - Quickly understand codebase structure
• Code Reviews - Identify risky files and architectural issues
• Documentation - Generate up-to-date architecture documentation
• Refactoring - Find god objects and complex files that need attention
• Dependency Analysis - Understand module dependencies and relationships

⚙️ Configuration

The tool automatically detects:

• TypeScript/JavaScript files (.ts, .tsx, .js, .jsx)
• Entry points (index.ts, main.ts, app.ts)
• Architecture layers (components, services, models, etc.)
• Tech stack (React, Node.js, Express, etc.)
• Common patterns (hooks, services, components)

🔍 What Gets Analyzed

• Files: All TypeScript and JavaScript files
• Exports: Named and default exports
• Imports: Relative and absolute imports
• Classes: Methods, properties, inheritance
• Functions: Parameters, async/await, exports
• Interfaces & Types: Type definitions
• Complexity: Cyclomatic complexity metrics

⚠️ Risky Files Detection

Files are flagged as risky if they have:

• High cyclomatic complexity (>50)
• Large file size (>500 lines)
• Too many dependencies (>20 imports)
• Too many exports (>15) - potential god object
• Multiple classes in one file (>5)
• Large classes/functions (>200/100 lines)

🌟 Why It's Cool

• ✅ Deterministic - No AI, just AST parsing and analysis
• ✅ Fast - Analyzes codebases quickly
• ✅ Accurate - Uses proper AST parsing, not regex
• ✅ Developer-focused - Solves real onboarding pain points
• ✅ Visual - Generates diagrams for better understanding
• ✅ Zero Configuration - Works out of the box
• ✅ Privacy-friendly - All analysis happens locally

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

MIT

🙏 Acknowledgments

Built with:

• ts-morph - TypeScript compiler wrapper
• commander - CLI framework
• chalk - Terminal string styling
• glob - File pattern matching