Repository Analyzer

Purpose

Quickly understand unfamiliar codebases by automatically scanning structure, detecting technologies, mapping dependencies, and generating comprehensive documentation.

For SDAM users: Creates external documentation of codebase structure you can reference later. For ADHD users: Instant overview without manual exploration – saves hours of context-switching. For all users: Onboard to new projects in minutes instead of days.

Activation Triggers

• User says: “analyze repository”, “understand codebase”, “document project”
• Requests for: “what’s in this repo”, “how does this work”, “codebase overview”
• New project onboarding scenarios
• Technical debt assessment requests

Core Workflow

1. Scan Repository Structure

Step 1: Get directory structure

# Use filesystem tools to map structure
tree -L 3 -I 'node_modules|.git|dist|build'

Step 2: Count files by type

# Identify languages used
find . -type f -name "*.js" | wc -l
find . -type f -name "*.py" | wc -l
find . -type f -name "*.go" | wc -l
# etc...

Step 3: Measure codebase size

# Count lines of code
cloc . --exclude-dir=node_modules,.git,dist,build

2. Detect Technologies

Languages: JavaScript, TypeScript, Python, Go, Rust, Java, etc.

Frameworks:

• Frontend: React, Vue, Angular, Svelte
• Backend: Express, FastAPI, Django, Rails
• Mobile: React Native, Flutter
• Desktop: Electron, Tauri

Detection methods:

const detectFramework = async () => {
  // Check package.json
  const packageJson = await readFile('package.json');
  const dependencies = packageJson.dependencies || {};

  if ('react' in dependencies) return 'React';
  if ('vue' in dependencies) return 'Vue';
  if ('express' in dependencies) return 'Express';

  // Check requirements.txt
  const requirements = await readFile('requirements.txt');
  if (requirements.includes('fastapi')) return 'FastAPI';
  if (requirements.includes('django')) return 'Django';

  // Check go.mod
  const goMod = await readFile('go.mod');
  if (goMod.includes('gin-gonic')) return 'Gin';

  return 'Unknown';
};

3. Map Dependencies

For Node.js:

# Read package.json
cat package.json | jq '.dependencies'
cat package.json | jq '.devDependencies'

# Check for outdated packages
npm outdated

For Python:

# Read requirements.txt or pyproject.toml
cat requirements.txt

# Check for outdated packages
pip list --outdated

For Go:

# Read go.mod
cat go.mod

# Check for outdated modules
go list -u -m all

4. Identify Architecture Patterns

Common patterns to detect:

• MVC (Model-View-Controller): models/, views/, controllers/
• Layered: api/, services/, repositories/
• Feature-based: features/auth/, features/users/
• Domain-driven: domain/, application/, infrastructure/
• Microservices: Multiple services in services/ directory
• Monorepo: Workspaces or packages structure

Detection logic:

const detectArchitecture = (structure) => {
  if (structure.includes('models') && structure.includes('views') && structure.includes('controllers')) {
    return 'MVC Pattern';
  }
  if (structure.includes('features')) {
    return 'Feature-based Architecture';
  }
  if (structure.includes('domain') && structure.includes('application')) {
    return 'Domain-Driven Design';
  }
  if (structure.includes('services') && structure.includes('api-gateway')) {
    return 'Microservices Architecture';
  }
  return 'Custom Architecture';
};

5. Extract Technical Debt

Search for indicators:

# Find TODOs
grep -r "TODO" --include="*.js" --include="*.py" --include="*.go"

# Find FIXMEs
grep -r "FIXME" --include="*.js" --include="*.py" --include="*.go"

# Find HACKs
grep -r "HACK" --include="*.js" --include="*.py" --include="*.go"

# Find deprecated code
grep -r "@deprecated" --include="*.js" --include="*.ts"

Complexity analysis:

// Identify long functions (potential refactor targets)
const analyzeFunctions = () => {
  // Functions > 50 lines = high complexity
  // Functions > 100 lines = very high complexity
  // Cyclomatic complexity > 10 = needs refactoring
};

6. Generate Documentation

Output format:

# {Project Name} - Repository Analysis

**Generated:** {timestamp}
**Analyzed by:** Claude Code Repository Analyzer

---

## 📊 Overview

**Primary Language:** {language}
**Framework:** {framework}
**Architecture:** {architecture pattern}
**Total Files:** {count}
**Lines of Code:** {LOC}
**Last Updated:** {git log date}

---

## 📁 Directory Structure

project/ ├── src/ │ ├── components/ │ ├── services/ │ └── utils/ ├── tests/ └── docs/

---

## 🛠 Technologies

### Frontend
- React 18.2.0
- TypeScript 5.0
- Tailwind CSS 3.3

### Backend
- Node.js 18
- Express 4.18
- PostgreSQL 15

### DevOps
- Docker
- GitHub Actions
- Jest for testing

---

## 📦 Dependencies

### Production (12 packages)
- express: 4.18.2
- pg: 8.11.0
- jsonwebtoken: 9.0.0
- ...

### Development (8 packages)
- typescript: 5.0.4
- jest: 29.5.0
- eslint: 8.40.0
- ...

### ⚠️ Outdated (3 packages)
- express: 4.18.2 → 4.19.0 (minor update available)
- jest: 29.5.0 → 29.7.0 (patch updates available)

---

## 🏗 Architecture

**Pattern:** Layered Architecture

**Layers:**
1. **API Layer** (`src/api/`): REST endpoints, request validation
2. **Service Layer** (`src/services/`): Business logic
3. **Repository Layer** (`src/repositories/`): Database access
4. **Models** (`src/models/`): Data structures

**Data Flow:**

Client → API → Service → Repository → Database

---

## 🔍 Code Quality

**Metrics:**
- Average function length: 25 lines
- Cyclomatic complexity: 3.2 (low)
- Test coverage: 78%
- TypeScript strict mode: ✅ Enabled

**Strengths:**
- ✅ Well-structured codebase
- ✅ Good test coverage
- ✅ Type-safe with TypeScript

**Areas for Improvement:**
- ⚠️ 12 TODOs found (see Technical Debt section)
- ⚠️ 3 outdated dependencies
- ⚠️ Missing documentation in `/utils`

---

## 🐛 Technical Debt

### High Priority (3)
- **FIXME** in `src/services/auth.js:42`: JWT refresh token rotation not implemented
- **TODO** in `src/api/users.js:78`: Add rate limiting
- **HACK** in `src/utils/cache.js:23`: Using setTimeout instead of proper cache expiry

### Medium Priority (5)
- **TODO** in `src/components/Dashboard.jsx:15`: Optimize re-renders
- **TODO** in `tests/integration/api.test.js:100`: Add more edge cases
- ...

### Low Priority (4)
- **TODO** in `README.md:50`: Update installation instructions
- ...

---

## 🚀 Entry Points

**Main Application:**
- `src/index.js` - Server entry point
- `src/client/index.jsx` - Client entry point

**Development:**
- `npm run dev` - Start dev server
- `npm test` - Run tests
- `npm run build` - Production build

**Configuration:**
- `.env.example` - Environment variables
- `tsconfig.json` - TypeScript config
- `jest.config.js` - Test configuration

---

## 📋 Common Tasks

**Adding a new feature:**
1. Create component in `src/components/`
2. Add service logic in `src/services/`
3. Create API endpoint in `src/api/`
4. Write tests in `tests/`

**Database changes:**
1. Create migration in `migrations/`
2. Update models in `src/models/`
3. Run `npm run migrate`

---

## 🔗 Integration Points

**External Services:**
- PostgreSQL database (port 5432)
- Redis cache (port 6379)
- SendGrid API (email)
- Stripe API (payments)

**API Endpoints:**
- `GET /api/users` - List users
- `POST /api/auth/login` - Authentication
- `GET /api/dashboard` - Dashboard data

---

## 📚 Additional Resources

- [Architecture Diagram](./docs/architecture.png)
- [API Documentation](./docs/api.md)
- [Development Guide](./docs/development.md)

---

**Next Steps:**
1. Address high-priority technical debt
2. Update outdated dependencies
3. Increase test coverage to 85%+
4. Document utility functions

See patterns.md for architecture pattern library and examples.md for analysis examples.

Advanced Analysis Features

Git History Analysis

# Find most changed files (hotspots)
git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -10

# Find largest contributors
git shortlog -sn

# Recent activity
git log --oneline --since="30 days ago" --no-merges

Code Complexity Metrics

# Using complexity tools
npx eslint src/ --format json | jq '.[] | select(.messages[].ruleId == "complexity")'

# Or manual analysis
# Functions > 50 lines = candidate for refactoring
# Files > 500 lines = candidate for splitting

Dependency Security

# Check for vulnerabilities
npm audit
pip-audit  # for Python
go mod tidy && go list -m all  # for Go

Integration with Other Skills

Context Manager

Save repository overview:

remember: Analyzed ProjectX repository
Type: CONTEXT
Tags: repository, architecture, nodejs, react
Content: ProjectX uses React + Express, layered architecture,
         12 high-priority TODOs, 78% test coverage

Error Debugger

If analysis finds common issues:

Invoke error-debugger for:
- Deprecated dependencies
- Security vulnerabilities
- Common antipatterns detected

Browser App Creator

Generate visualization:

Create dependency graph visualization
→ browser-app-creator generates interactive HTML chart

Quality Checklist

Before delivering documentation, verify:

• ✅ Directory structure mapped
• ✅ Languages and frameworks identified
• ✅ Dependencies listed
• ✅ Architecture pattern detected
• ✅ Technical debt catalogued
• ✅ Entry points documented
• ✅ Common tasks explained
• ✅ Markdown formatted properly

Output Delivery

Format: Markdown file saved to /home/toowired/.claude-artifacts/analysis-{project}-{timestamp}.md

Notify user:

✅ **{Project Name} Analysis** complete!

**Summary:**
- {LOC} lines of code across {file_count} files
- Primary stack: {stack}
- Architecture: {pattern}
- {todo_count} TODOs found

**Documentation saved to:** {filepath}

**Key findings:**
1. {finding_1}
2. {finding_2}
3. {finding_3}

**Recommended actions:**
- {action_1}
- {action_2}

Common Analysis Scenarios

New Project Onboarding

User joins unfamiliar project → analyzer provides complete overview in minutes

Technical Debt Assessment

User needs to evaluate legacy code → analyzer identifies all TODOs/FIXMEs/HACKs

Dependency Audit

User wants to check outdated packages → analyzer lists all outdated dependencies with versions

Architecture Documentation

User needs to document existing project → analyzer generates comprehensive architecture docs

Success Criteria

✅ Complete codebase structure mapped ✅ All technologies identified correctly ✅ Dependencies catalogued with versions ✅ Architecture pattern detected ✅ Technical debt surfaced ✅ Documentation generated in <2 minutes ✅ Markdown output saved to artifacts ✅ Actionable recommendations provided

Additional Resources

• Pattern Library – Common architecture patterns
• Analysis Examples – Real-world repository analyses

Quick Reference

Trigger Phrases

• “analyze repository”
• “understand codebase”
• “document project”
• “what’s in this repo”
• “codebase overview”
• “technical debt report”

Output Location

/home/toowired/.claude-artifacts/analysis-{project}-{timestamp}.md

Analysis Depth Options

• Quick (<1 min): Structure + languages only
• Standard (1-2 min): + dependencies + patterns
• Deep (3-5 min): + git history + complexity metrics + security audit