gh-dhofheinz-open-plugins-plugins-10x-fullstack-engineer/commands/refactor/analyze.md

Code Quality Analysis Operation

Analyze code quality, identify code smells, calculate metrics, and prioritize refactoring opportunities.

Parameters

Received from $ARGUMENTS: All arguments after "analyze"

Expected format:

scope:"<path-or-description>" [metrics:"<metric1,metric2>"] [depth:"quick|standard|detailed"]

Parameter definitions:

• scope (REQUIRED): Path to analyze or description (e.g., "user-service/", "authentication module", "src/components/UserProfile.tsx")
• metrics (OPTIONAL): Comma-separated metrics to analyze (default: all)
  • complexity - Cyclomatic complexity
  • duplication - Code duplication detection
  • coverage - Test coverage analysis
  • dependencies - Dependency analysis and circular dependencies
  • types - Type coverage (TypeScript projects)
  • smells - Code smells detection
• depth (OPTIONAL): Analysis depth (default: standard)
  • quick - Fast scan, high-level metrics only
  • standard - Balanced analysis with key metrics
  • detailed - Comprehensive deep analysis with recommendations

Workflow

1. Pre-Analysis Verification

Before analyzing, verify:

# Check if scope exists
test -e <scope> || echo "Error: Scope path does not exist"

# Check if project has package.json
test -f package.json || echo "Warning: No package.json found"

# Verify analysis tools availability
command -v npx >/dev/null 2>&1 || echo "Warning: npm/npx not available"

2. Complexity Analysis

Measure cyclomatic complexity using ESLint:

# Run complexity analysis
npx eslint <scope> \
  --ext .js,.jsx,.ts,.tsx \
  --rule 'complexity: [error, { max: 10 }]' \
  --rule 'max-depth: [error, 3]' \
  --rule 'max-lines-per-function: [error, { max: 50 }]' \
  --rule 'max-params: [error, 4]' \
  --format json > complexity-report.json

# Or use script
./.scripts/analyze-complexity.sh <scope>

Identify:

• Functions with complexity > 10 (high risk)
• Functions with complexity 6-10 (moderate risk)
• Deep nesting (>3 levels)
• Long functions (>50 lines)
• Long parameter lists (>4 parameters)

Report format:

### Complexity Analysis

**Critical Issues** (Complexity > 10):
1. `UserService.validateAndCreateUser()` - Complexity: 18 (45 lines)
   - Location: src/services/UserService.ts:127
   - Impact: High - Used in 8 places
   - Recommendation: Extract validation logic into separate functions

2. `OrderProcessor.processPayment()` - Complexity: 15 (38 lines)
   - Location: src/services/OrderProcessor.ts:89
   - Impact: Medium - Payment critical path
   - Recommendation: Use strategy pattern for payment methods

**Moderate Issues** (Complexity 6-10):
- 12 functions identified
- Average complexity: 7.3
- Recommendation: Monitor, refactor opportunistically

3. Duplication Detection

Detect duplicate code using jsinspect:

# Find duplicated code blocks
npx jsinspect <scope> \
  --threshold 30 \
  --min-instances 2 \
  --ignore "node_modules|dist|build" \
  --reporter json > duplication-report.json

# Or use script
./.scripts/detect-duplication.sh <scope>

Identify:

• Exact duplicates (100% match)
• Near duplicates (>80% similar)
• Copy-paste patterns
• Repeated logic across files

Report format:

### Code Duplication

**Exact Duplicates** (100% match):
1. Validation logic (42 lines) - 5 instances
   - src/components/UserForm.tsx:45-87
   - src/components/ProfileForm.tsx:32-74
   - src/components/RegistrationForm.tsx:56-98
   - src/components/SettingsForm.tsx:23-65
   - src/components/AdminForm.tsx:89-131
   - **Recommendation**: Extract to shared validator utility
   - **Estimated savings**: 168 lines (4 duplicates × 42 lines)

**Near Duplicates** (>80% similar):
2. API error handling (18 lines) - 8 instances
   - Average similarity: 87%
   - **Recommendation**: Create centralized error handler
   - **Estimated savings**: 126 lines

**Total Duplication**:
- Duplicate lines: 542 / 8,234 (6.6%)
- Target: < 3%
- **Priority**: HIGH - Significant duplication found

4. Test Coverage Analysis

Calculate test coverage:

# Run tests with coverage
npm test -- --coverage --watchAll=false

# Generate coverage report
npx nyc report --reporter=json > coverage-report.json

# Or use script
./.scripts/verify-tests.sh <scope>

Identify:

• Files with < 70% coverage (inadequate)
• Files with 70-80% coverage (acceptable)
• Files with > 80% coverage (good)
• Untested code paths
• Missing edge case tests

Report format:

### Test Coverage

**Overall Coverage**:
- Statements: 78.5% (Target: 80%)
- Branches: 72.3% (Target: 75%)
- Functions: 81.2% (Target: 80%)
- Lines: 77.8% (Target: 80%)

**Critical Gaps** (< 70% coverage):
1. `src/services/PaymentService.ts` - 45% coverage
   - Missing: Error handling paths
   - Missing: Edge cases (negative amounts, invalid cards)
   - **Risk**: HIGH - Financial logic

2. `src/utils/validation.ts` - 62% coverage
   - Missing: Boundary conditions
   - Missing: Invalid input handling
   - **Risk**: MEDIUM - Used in 15 components

**Recommendation**: Add tests before refactoring these areas.

5. Dependency Analysis

Analyze module dependencies:

# Check for circular dependencies
npx madge --circular --extensions ts,tsx,js,jsx <scope>

# Generate dependency graph
npx madge --image deps.png <scope>

# Find orphaned files
npx madge --orphans <scope>

Identify:

• Circular dependencies (breaks modularity)
• Highly coupled modules
• God objects (too many dependencies)
• Orphaned files (unused)
• Deep dependency chains

Report format:

### Dependency Analysis

**Circular Dependencies** (CRITICAL):
1. UserService ↔ AuthService ↔ SessionService
   - **Impact**: Cannot test in isolation
   - **Recommendation**: Introduce interface/abstraction layer

2. OrderModel ↔ PaymentModel ↔ CustomerModel
   - **Impact**: Tight coupling, difficult to change
   - **Recommendation**: Use repository pattern

**High Coupling**:
- `UserService.ts` - 23 dependencies (Target: < 10)
- `AppConfig.ts` - 18 dependencies (Target: < 10)
- **Recommendation**: Split into smaller, focused modules

**Orphaned Files**: 5 files unused
- src/utils/old-validator.ts (can be deleted)
- src/helpers/deprecated.ts (can be deleted)

6. Type Coverage Analysis (TypeScript)

Analyze TypeScript type safety:

# Type check with strict mode
npx tsc --noEmit --strict

# Count 'any' usage
grep -r "any" <scope> --include="*.ts" --include="*.tsx" | wc -l

# Check for implicit any
npx tsc --noEmit --noImplicitAny

Identify:

• Usage of any type
• Implicit any declarations
• Missing return type annotations
• Weak type definitions
• Type assertion overuse

Report format:

### Type Safety Analysis (TypeScript)

**Type Coverage**:
- Files with types: 145 / 167 (87%)
- Any usage: 42 instances (Target: 0)
- Implicit any: 18 instances
- **Rating**: MODERATE - Room for improvement

**Critical Issues**:
1. `src/api/client.ts` - 12 'any' types
   - Functions without return types
   - Untyped API responses
   - **Recommendation**: Add proper interfaces for API contracts

2. `src/utils/helpers.ts` - 8 'any' types
   - Generic utility functions
   - **Recommendation**: Use generics instead of 'any'

**Opportunity**: Eliminate 'any' types for 23% improvement

7. Code Smells Detection

Identify common code smells:

Long Method (>50 lines):

• Difficult to understand
• Hard to test
• Often doing too much
• Fix: Extract smaller methods

Long Parameter List (>4 parameters):

• Difficult to use
• Hard to remember order
• Often indicates missing abstraction
• Fix: Introduce parameter object

Duplicate Code:

• Maintenance nightmare
• Bug multiplication
• Fix: Extract to shared function/component

Large Class (>300 lines):

• Too many responsibilities
• Hard to understand
• Difficult to test
• Fix: Split into smaller classes

Switch Statements (complex conditionals):

• Hard to extend
• Violates Open/Closed Principle
• Fix: Use polymorphism or strategy pattern

Report format:

### Code Smells Detected

**Long Methods**: 23 functions > 50 lines
- Worst: `OrderService.processOrder()` (247 lines)
- **Impact**: Extremely difficult to understand and maintain
- **Priority**: CRITICAL

**Long Parameter Lists**: 18 functions > 4 parameters
- Worst: `createUser(name, email, age, address, phone, role, settings)` (7 params)
- **Fix**: Use `CreateUserParams` object

**Large Classes**: 8 classes > 300 lines
- Worst: `UserService.ts` (842 lines)
- **Responsibilities**: Validation, CRUD, Auth, Notifications, Logging
- **Fix**: Split into focused services

**Switch Statements**: 12 complex conditionals
- `src/services/PaymentProcessor.ts` - Switch on payment method (5 cases, 180 lines)
- **Fix**: Use strategy pattern for payment methods

8. Generate Prioritized Report

Priority calculation based on:

• Severity: Critical > High > Medium > Low
• Impact: How many files/components affected
• Risk: Test coverage, complexity, usage frequency
• Effort: Estimated time to fix (hours)
• Value: Improvement in maintainability

Report format:

## Code Quality Analysis Report

### Executive Summary

**Scope Analyzed**: <scope>
**Analysis Date**: <date>
**Total Files**: <count>
**Total Lines**: <count>

**Overall Health Score**: 6.5 / 10 (Needs Improvement)

**Top Priorities**:
1. Eliminate critical code duplication (HIGH)
2. Refactor high-complexity functions (HIGH)
3. Improve test coverage for critical paths (HIGH)
4. Remove circular dependencies (MEDIUM)
5. Strengthen TypeScript type safety (MEDIUM)

---

### Metrics Summary

| Metric | Current | Target | Status |
|--------|---------|--------|--------|
| Cyclomatic Complexity (avg) | 8.3 | < 6 | ⚠️ Above target |
| Code Duplication | 6.6% | < 3% | ⚠️ Above target |
| Test Coverage | 78.5% | > 80% | ⚠️ Below target |
| Type Coverage | 87% | > 95% | ⚠️ Below target |
| Circular Dependencies | 3 | 0 | ❌ Critical |

---

### Priority 1: Critical Issues (Fix Immediately)

#### 1.1 Circular Dependencies
**Severity**: CRITICAL
**Impact**: Cannot test modules in isolation, tight coupling
**Files Affected**: 8

**Dependencies**:
- UserService ↔ AuthService ↔ SessionService
- OrderModel ↔ PaymentModel ↔ CustomerModel
- ComponentA ↔ ComponentB ↔ ComponentC

**Recommendation**: Introduce dependency injection and interface abstractions
**Estimated Effort**: 8 hours
**Value**: HIGH - Enables independent testing and deployment

#### 1.2 Extremely High Complexity Functions
**Severity**: CRITICAL
**Impact**: Very difficult to understand, test, maintain
**Functions**: 4

**Functions**:
1. `UserService.validateAndCreateUser()` - Complexity: 18
2. `OrderProcessor.processPayment()` - Complexity: 15
3. `ReportGenerator.generateQuarterly()` - Complexity: 14
4. `DataTransformer.transform()` - Complexity: 13

**Recommendation**: Extract smaller functions, use early returns
**Estimated Effort**: 6 hours
**Value**: HIGH - Dramatic readability improvement

---

### Priority 2: High Issues (Fix Soon)

#### 2.1 Significant Code Duplication
**Severity**: HIGH
**Impact**: Maintenance burden, bug multiplication

**Duplicate Code**:
- Validation logic: 5 exact copies (210 lines duplicated)
- Error handling: 8 similar copies (144 lines duplicated)
- Data formatting: 6 copies (96 lines duplicated)

**Recommendation**: Extract to shared utilities
**Estimated Effort**: 4 hours
**Value**: HIGH - 450 lines reduction, single source of truth

#### 2.2 Inadequate Test Coverage
**Severity**: HIGH
**Impact**: High risk of regressions during refactoring

**Critical Gaps**:
- `PaymentService.ts` - 45% coverage (Financial logic!)
- `AuthService.ts` - 58% coverage (Security logic!)
- `validation.ts` - 62% coverage (Used everywhere!)

**Recommendation**: Add comprehensive tests before ANY refactoring
**Estimated Effort**: 8 hours
**Value**: CRITICAL - Enables safe refactoring

---

### Priority 3: Medium Issues (Plan to Fix)

#### 3.1 TypeScript Type Safety
**Severity**: MEDIUM
**Impact**: Runtime errors, poor IDE support

**Issues**:
- 42 usages of 'any' type
- 18 implicit any declarations
- Missing return type annotations

**Recommendation**: Eliminate 'any', add proper types
**Estimated Effort**: 6 hours
**Value**: MEDIUM - Catch errors at compile time

#### 3.2 Long Methods and Large Classes
**Severity**: MEDIUM
**Impact**: Difficult to understand and maintain

**Issues**:
- 23 long methods (>50 lines)
- 8 large classes (>300 lines)
- Single Responsibility Principle violations

**Recommendation**: Extract methods and split classes
**Estimated Effort**: 12 hours
**Value**: MEDIUM - Improved maintainability

---

### Priority 4: Low Issues (Opportunistic)

- Rename unclear variables (quick wins)
- Add missing JSDoc comments
- Consolidate similar utility functions
- Remove unused imports and variables

---

### Recommended Refactoring Sequence

**Week 1**:
1. Add missing tests for critical paths (8 hrs)
2. Fix circular dependencies (8 hrs)

**Week 2**:
3. Eliminate critical code duplication (4 hrs)
4. Refactor highest complexity functions (6 hrs)

**Week 3**:
5. Strengthen TypeScript types (6 hrs)
6. Extract long methods (6 hrs)

**Week 4**:
7. Split large classes (6 hrs)
8. Address remaining medium priority issues

**Total Estimated Effort**: ~54 hours

---

### Code Examples

#### Example 1: High Complexity Function

**Before** (Complexity: 18):
```typescript
async validateAndCreateUser(userData: any) {
  if (!userData.email) {
    throw new Error("Email required");
  }

  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(userData.email)) {
    throw new Error("Invalid email");
  }

  if (!userData.password || userData.password.length < 8) {
    throw new Error("Password must be at least 8 characters");
  }

  const hasUpper = /[A-Z]/.test(userData.password);
  const hasLower = /[a-z]/.test(userData.password);
  const hasNumber = /[0-9]/.test(userData.password);

  if (!hasUpper || !hasLower || !hasNumber) {
    throw new Error("Password must contain uppercase, lowercase, and number");
  }

  const existing = await this.db.users.findOne({ email: userData.email });
  if (existing) {
    throw new Error("Email already registered");
  }

  const hashedPassword = await bcrypt.hash(userData.password, 10);

  const user = await this.db.users.create({
    email: userData.email,
    password: hashedPassword,
    name: userData.name,
    createdAt: new Date()
  });

  await this.emailService.sendWelcomeEmail(user.email);

  return user;
}

After (Complexity: 3):

async validateAndCreateUser(userData: CreateUserInput): Promise<User> {
  this.validateUserInput(userData);
  await this.checkEmailAvailability(userData.email);

  const hashedPassword = await this.hashPassword(userData.password);
  const user = await this.createUser({ ...userData, password: hashedPassword });

  await this.sendWelcomeEmail(user);

  return user;
}

private validateUserInput(userData: CreateUserInput): void {
  validateEmail(userData.email);
  validatePassword(userData.password);
}

private async checkEmailAvailability(email: string): Promise<void> {
  const existing = await this.db.users.findOne({ email });
  if (existing) {
    throw new UserAlreadyExistsError(email);
  }
}

private async hashPassword(password: string): Promise<string> {
  return bcrypt.hash(password, 10);
}

private async createUser(data: CreateUserData): Promise<User> {
  return this.db.users.create({
    ...data,
    createdAt: new Date()
  });
}

private async sendWelcomeEmail(user: User): Promise<void> {
  await this.emailService.sendWelcomeEmail(user.email);
}

Improvements:

• Complexity: 18 → 3 (83% reduction)
• Lines per function: 37 → 5 (86% reduction)
• Testability: Each function can be tested independently
• Readability: Clear intent, self-documenting code
• Type safety: Proper interfaces instead of 'any'

---

Next Steps

Based on this analysis, consider:

1. Immediate Actions:

   • Add tests for PaymentService, AuthService, validation.ts
   • Fix circular dependencies
   • Review and approve refactoring priorities

2. Use Refactoring Operations:

   • /refactor extract - For long methods
   • /refactor duplicate - For code duplication
   • /refactor patterns - For circular dependencies (DI pattern)
   • /refactor types - For TypeScript improvements

3. Continuous Monitoring:

   • Set up automated complexity checks in CI/CD
   • Track duplication metrics over time
   • Monitor test coverage trends
   • Review code quality in pull requests

---

Analysis Complete: Refactoring priorities identified and prioritized by impact and effort.

## Output Format

Provide a comprehensive analysis report with:
- Executive summary with health score
- Metrics table (current vs target)
- Prioritized issues (Critical → High → Medium → Low)
- Code examples showing before/after improvements
- Estimated effort and value for each issue
- Recommended refactoring sequence
- Next steps and monitoring recommendations

## Error Handling

**Scope not found**:

Error: Specified scope does not exist:

Please provide a valid path or description:

• Relative path: "src/components/"
• Absolute path: "/full/path/to/code"
• Module description: "user authentication module"

**No metrics requested**:

Using default metrics: complexity, duplication, coverage, dependencies

To specify metrics: metrics:"complexity,duplication"

**Analysis tools not available**:

Warning: Some analysis tools not available:

• eslint: Install with 'npm install -D eslint'
• jsinspect: Install with 'npm install -g jsinspect'

Proceeding with available tools...