onboarding-complexity 1.0.0
Estimate developer onboarding time from repository structure
License: MIT
Requires Python: >=3.8

# onboarding-complexity

[![PyPI version](https://badge.fury.io/py/onboarding-complexity.svg)](https://badge.fury.io/py/onboarding-complexity)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

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

```bash
pip install onboarding-complexity
```

## Quick Start

```bash
# 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:

```yaml
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](https://glue.tools) — 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