code-consolidation

Code Consolidation Mapper

Analyze codebases to identify responsibilities scattered across multiple files that should be consolidated into single sources of truth.

Purpose

Map fragmented code responsibilities and generate actionable consolidation plans. Detect:

• Duplicate type definitions
• Scattered utility functions
• Repeated configuration patterns
• Fragmented error hierarchies
• Inconsistent factory implementations

When to Use

• Before major refactoring efforts
• When onboarding to brownfield codebases
• During architecture reviews
• When code smells indicate duplication
• Planning consolidation sprints

Analysis Process

Phase 1: Pattern Detection

Scan for common duplication patterns using targeted searches:

# Type definitions scattered
grep -rn "export (type|interface) " --include="*.ts" | sort | uniq -d

# Similar function names in different files
grep -rn "export function \w+" --include="*.ts" | awk -F: '{print $3}' | sort | uniq -c | sort -rn

# Duplicate class definitions
grep -rn "class \w+Error" --include="*.ts" --include="*.py"

# Configuration objects with same structure
grep -rn "STATUS_CONFIG\|VARIANT_CONFIG" --include="*.ts"

# Factory patterns repeated
grep -rn "create.*Factory\|.*Factory\(" --include="*.ts"

Phase 2: Responsibility Mapping

For each detected pattern, classify by category:

Category	Detection Pattern	Consolidation Target
Types	Same interface in 2+ packages	packages/types/
Validators	Duplicate Zod schemas	packages/validators/
Errors	Scattered error classes	app/errors/ or lib/errors/
Config	Repeated status/variant configs	lib/{domain}-config-factory.ts
Utils	Similar functions across files	lib/utils/{domain}.ts
Constants	Duplicate magic values	lib/constants/{domain}.ts

Phase 3: Impact Analysis

For each consolidation opportunity, assess:

1. File Count: How many files contain the duplicate?
2. Line Count: Estimated lines of code affected
3. Import Depth: How many consumers import from scattered locations?
4. Breaking Risk: Will consolidation break existing APIs?

Phase 4: Prioritization Matrix

Score opportunities using:

Factor	Weight	Scoring
Files affected	30%	1-5 files (1pt), 6-10 (2pt), 11+ (3pt)
Maintenance burden	25%	Low (1pt), Medium (2pt), High (3pt)
Bug risk	25%	Low (1pt), Medium (2pt), High (3pt)
Effort required	20%	High (1pt), Medium (2pt), Low (3pt)

Priority = (Files × 0.30) + (Maintenance × 0.25) + (BugRisk × 0.25) + (Effort × 0.20)

Output Format

Generate consolidation map in markdown:

# Consolidation Map: [Project Name]

## Executive Summary
- **Duplication Categories Found:** X
- **Files Affected:** Y
- **Estimated Lines to Eliminate:** Z

## Priority Matrix

| Priority | Category | Files | Impact | Effort | Score |
|----------|----------|-------|--------|--------|-------|
| 🔴 High  | [name]   | X     | High   | Low    | 2.8   |
| 🟡 Med   | [name]   | X     | Med    | Med    | 2.1   |
| 🟢 Low   | [name]   | X     | Low    | High   | 1.4   |

## Detailed Findings

### 1. [Category Name] 🔴 High Priority

**Problem:** [Description]

**Duplicated Locations:**
- `path/to/file1.ts:line` - [what it exports]
- `path/to/file2.ts:line` - [what it exports]

**Consolidation Target:** `path/to/consolidated/location.ts`

**Migration Steps:**
1. Create consolidated module
2. Add backward-compatible re-exports
3. Update consumers incrementally
4. Remove deprecated locations

**Verification:**
```bash
# Check for remaining references
grep -rn "old_import" src/

## Consolidation Patterns

### Pattern: Factory Extraction

When multiple files define similar configuration objects:

**Before (scattered):**
```typescript
// file1/constants.ts
export const STATUS_CONFIG = { draft: {...}, published: {...} };
export function getStatusLabel(status) { return STATUS_CONFIG[status].label; }

// file2/constants.ts
export const STATUS_CONFIG = { active: {...}, archived: {...} };
export function getStatusLabel(status) { return STATUS_CONFIG[status].label; }

After (consolidated):

// lib/status-config-factory.ts
export function createStatusConfig<T extends string>(configs: Record<T, StatusDef>) { ... }
export function createStatusHelpers<T extends string>(configs: Record<T, StatusDef>) { ... }

// file1/constants.ts
import { createStatusConfig } from '@/lib/status-config-factory';
export const STATUS_CONFIG = createStatusConfig({ draft: {...}, published: {...} });

Pattern: Error Hierarchy

When error classes are scattered:

Before:

# service1.py
class Service1Error(Exception): pass
class ValidationError(Service1Error): pass

# service2.py
class Service2Error(Exception): pass
class ValidationError(Service2Error): pass  # Duplicate name!

After:

# errors/__init__.py
from .base import AppError
from .service import ServiceError, ValidationError

# errors/service.py
class ServiceError(AppError): pass
class ValidationError(ServiceError): pass

Pattern: Barrel Export Reorganization

When utilities sprawl across flat directories:

Before:

utils/
├── auth.ts
├── crypto.ts
├── email.ts
├── redis.ts
├── slug.ts
└── ... (40+ files)

After:

utils/
├── index.ts           # Barrel export with categories
├── auth/              # Or just organized exports in index.ts
│   └── index.ts       # export * from '../auth'; export * from '../crypto';
└── ...

Backward Compatibility

Always maintain backward compatibility during migration:

1. Re-export from old location:

// old/location.ts (deprecated)
export { Thing } from '@/new/location';

2. Add deprecation comments:

/**
 * @deprecated Import from '@/new/location' instead
 */
export { Thing } from '@/new/location';

3. Create alias for renamed exports:

// When renaming, keep old name as alias
export const OldName = NewName;

Verification Commands

After consolidation, verify no orphaned references:

# Find remaining imports from deprecated location
grep -rn "from ['\"].*deprecated/path" src/

# Type check
pnpm type-check

# Run tests
pnpm test

# Check for duplicate exports
grep -rn "export.*SameName" src/ | wc -l

Integration with TaskNotes

After generating consolidation map, create tasks:

# Create consolidation tasks
pnpm task:new "Consolidar [Category]" --sprint -t CHORE -p [priority]

Additional Resources

Reference Files

• references/detection-patterns.md - Detailed grep/ripgrep patterns for each language
• references/migration-strategies.md - Step-by-step migration guides

Scripts

• scripts/find-duplicates.sh - Automated duplicate detection
• scripts/generate-consolidation-report.sh - Report generator