onboarding-complexity

Estimate developer onboarding time from repository structure. Analyzes language diversity, architecture complexity, documentation gaps, dependency count, and tribal knowledge concentration to predict time-to-productivity.

Installation

pip install onboarding-complexity

Quick Start

# Analyze a repository
onboarding-complexity analyze /path/to/repo

# Compare two repositories
onboarding-complexity compare /path/to/repo1 /path/to/repo2

# Output as JSON
onboarding-complexity analyze /path/to/repo --format json

# Adjust for experience level
onboarding-complexity analyze /path/to/repo --experience-level junior

Sample Output

📊 Onboarding Complexity Analysis

Repository: my-project
Analysis Date: 2026-02-16

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
METRICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Language Diversity:        5.2/10 (3 languages)
Architecture Complexity:   6.8/10 (depth: 5, services: 2)
Documentation Gap:         4.1/10 (README: good)
Dependency Complexity:     7.2/10 (156 total dependencies)
Knowledge Concentration:   6.5/10 (bus factor: 3)
Codebase Size:            5.9/10 (1,250 files, 45K LOC)

Overall Score:            5.9/10 (Moderate)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ONBOARDING TIME ESTIMATE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Mid-level Developer:       4-6 weeks
Junior Developer:          7-10 weeks
Senior Developer:          2-3 weeks

Recommendations:
  • Document architecture decisions in ARCHITECTURE.md
  • Increase inline code comments (current: 8%)
  • Create a CONTRIBUTING.md with setup instructions

How It Works

The onboarding-complexity analyzer examines six key dimensions of codebase complexity:

Language Diversity Score

Measures the variety of programming languages in the codebase. Multiple languages increase cognitive load for new developers.

• Single language: 1-2/10
• 2-3 languages: 4-6/10
• 4+ languages: 8-10/10

Architecture Complexity

Evaluates directory depth, number of services/modules, and configuration complexity.

• Simple flat structure: 1-2/10
• Typical monolith: 4-6/10
• Microservices/complex: 8-10/10

Documentation Gap

Analyzes README quality, API documentation, inline comments, and architecture documentation.

• Excellent docs: 1-2/10
• Some gaps: 4-6/10
• Minimal docs: 8-10/10

Dependency Complexity

Counts total dependencies, internal/custom packages, and framework count.

• <50 deps: 1-3/10
• 50-200 deps: 4-6/10
• 200+ deps: 7-10/10

Knowledge Concentration

Estimates "bus factor" - how many key contributors know critical systems.

• Well distributed: 1-2/10
• Some concentration: 4-6/10
• Highly concentrated: 8-10/10

Codebase Size

Total files, lines of code, and growth rate impact onboarding time.

• <10K LOC: 1-2/10
• 10K-100K LOC: 4-6/10
• 100K+ LOC: 8-10/10

Configuration

Create a .onboarding.yml in your repository root to customize analysis:

ignore_patterns:
  - node_modules
  - .git
  - vendor

documentation_paths:
  - README.md
  - docs/
  - ARCHITECTURE.md

language_weights:
  python: 1.0
  javascript: 1.0
  rust: 1.5
  go: 0.9

Attribution

Built by Glue — AI codebase intelligence for product teams. For real-time onboarding assistance including natural language codebase Q&A and auto-generated feature documentation, check out Glue.

License

MIT License - See LICENSE file for details