Techdebt Finder

Tech Debt Finder

Identify duplicated code, inconsistent patterns, and refactoring opportunities.

When to Use

• "Find duplicate code"
• "What needs refactoring?"
• "Are there inconsistent patterns?"
• Code review prep
• Pre-refactor analysis

Detection Process

1. Scan - Grep for common debt indicators 2. Cluster - Group similar issues 3. Prioritize - Rank by frequency × impact 4. Report - Show findings with locations

Quick Patterns

Output Format

## Technical Debt Report

### High Priority (fix soon)
- [DUPLICATE] src/utils/format.ts:23 ↔ src/helpers/fmt.ts:45
  Similar: 87% | Impact: High (called 12 places)

### Medium Priority (plan for)
- [INCONSISTENT] Mixed naming: getUserData vs fetch_user
  Files: api.ts, service.ts, handler.ts

### Low Priority (track)
- [TODO] 23 TODO comments, oldest: 2023-01-15

References

• detection-patterns.md - Pattern matching rules
• prioritization.md - Scoring and ranking
• refactoring-strategies.md - Fix suggestions

Detection Patterns

Rules for identifying technical debt in codebases.

Code Duplication

Exact Duplicates

Find identical code blocks:

# Find functions with identical bodies (simplified)
grep -rn "function\|const.*=.*=>" --include="*.ts" | sort | uniq -d

Structural Similarity

Compare AST-like patterns:

Duplication Indicators

- Same function name in multiple files
- Identical import blocks
- Copy-pasted error handling
- Repeated validation logic
- Similar API call patterns

Inconsistency Detection

Naming Conventions

Pattern Variations

Find same concept, different implementation:

- Multiple date formatting approaches
- Different error handling styles
- Varied logging patterns
- Inconsistent null checks

Dead Code Detection

Unreferenced Exports

# Find exports not imported elsewhere
grep -rh "export.*function\|export.*const" --include="*.ts" | \
  while read exp; do
    name=$(echo "$exp" | grep -oP '(?<=function |const )\w+')
    count=$(grep -r "$name" --include="*.ts" | wc -l)
    [ "$count" -eq 1 ] && echo "Unused: $name"
  done

Indicators

• Functions with no callers
• Commented-out code blocks
• Unused imports
• Unreachable branches

Code Smell Markers

Comment-Based

Structural

Magic Values

Detection

# Find hardcoded numbers (excluding 0, 1, common ports)
grep -rn "[^0-9][2-9][0-9]\{2,\}[^0-9]" --include="*.ts" | \
  grep -v "const\|port\|status"

Common Offenders

• Timeouts (3000, 5000, 30000)
• Array indices beyond 0/1
• Status codes inline
• Retry counts
• Buffer sizes

File-Level Patterns

Large Files

# Files over 500 lines
find . -name "*.ts" -exec wc -l {} \; | awk '$1 > 500'

High Churn Files

# Most frequently modified (git)
git log --pretty=format: --name-only | sort | uniq -c | sort -rn | head -20

High churn + high complexity = refactor priority.

Prioritization

Scoring and ranking technical debt for action.

Priority Matrix

Impact Scoring

Change Risk

Coupling

Complexity

Frequency Scoring

Code Churn

# Commits touching file in last 6 months
git log --since="6 months ago" --oneline -- path/to/file | wc -l

Usage Frequency

Composite Score

Priority = (Impact × 2) + Frequency + Urgency Modifier

Urgency Modifiers:
  +5  Security vulnerability
  +3  Causes prod errors
  +2  Blocks feature work
  +1  Developer friction

Priority Buckets

Critical (Score 12+)

• Address in current sprint
• May warrant hotfix
• Examples: security issues, data corruption risks

High (Score 8-11)

• Plan for next sprint
• Track in backlog with deadline
• Examples: performance bottlenecks, major duplication

Medium (Score 4-7)

• Address opportunistically
• Bundle with related work
• Examples: naming inconsistencies, minor duplication

Low (Score 0-3)

• Track but don't prioritize
• Fix if touching area anyway
• Examples: old TODOs, style inconsistencies

Batch Grouping

Group related debt for efficient fixing:

Group by:
1. Same file/module
2. Same pattern type
3. Same fix approach
4. Same reviewer needed

Example Batch

Batch: "Standardize error handling"
Files: api.ts, service.ts, handler.ts
Pattern: Inconsistent try/catch
Effort: 2 hours
Impact: Medium (Score 6)
→ Fix together in single PR

Reporting Template

## Tech Debt Summary

**Total Items**: 47
**Critical**: 2 | **High**: 8 | **Medium**: 22 | **Low**: 15

### Top 5 Priority Items

| Rank | Issue                   | Score | Location          | Est. Effort |
| ---- | ----------------------- | ----- | ----------------- | ----------- |
| 1    | SQL injection risk      | 15    | api/query.ts:45   | 1h          |
| 2    | 6x duplicate validation | 12    | src/validators/\* | 3h          |
| ...  | ...                     | ...   | ...               | ...         |

### Recommended Batches

1. **Error handling** (3 files, 2h) - Score 8
2. **Naming cleanup** (12 files, 1h) - Score 5

Refactoring Strategies

Fix patterns for common technical debt types.

Duplication Fixes

Extract Shared Function

Before:

// file1.ts
function processUserA(user) {
  validate(user);
  normalize(user.name);
  save(user);
}

// file2.ts
function processUserB(user) {
  validate(user);
  normalize(user.name);
  save(user);
}

After:

// shared/user-processing.ts
export function processUser(user) {
  validate(user);
  normalize(user.name);
  save(user);
}

Parameterize Variations

When duplicates differ slightly:

// Before: 3 similar functions
function fetchUsers() {
  return fetch("/users");
}
function fetchPosts() {
  return fetch("/posts");
}
function fetchComments() {
  return fetch("/comments");
}

// After: one parameterized
function fetchResource(type: "users" | "posts" | "comments") {
  return fetch(`/${type}`);
}

Template Method

For process variations:

abstract class DataProcessor {
  process(data) {
    this.validate(data); // shared
    this.transform(data); // varies
    this.save(data); // shared
  }

  abstract transform(data); // subclass implements
}

Inconsistency Fixes

Naming Standardization

1. Choose convention (document in style guide) 2. Find all variants: grep -rn "getUserData\|fetch_user\|loadUser" 3. Pick canonical name 4. Global rename (IDE or sed) 5. Update imports

Pattern Consolidation

// Before: mixed error handling
try {
} catch (e) {
  console.log(e);
}
try {
} catch (e) {
  throw new Error(e);
}
try {
} catch (e) {
  return null;
}

// After: consistent approach
try {
} catch (e) {
  logger.error(e);
  throw new AppError(e.message, { cause: e });
}

Dead Code Removal

Safe Deletion Process

1. Verify unused: Search all references 2. Check dynamic usage: Grep for string references 3. Review git history: Why was it added? 4. Delete in stages: Comment first, delete next sprint 5. Monitor: Watch for errors post-deploy

Unused Export Pattern

# Find export, count usages
export_name="unusedHelper"
usages=$(grep -r "$export_name" --include="*.ts" | wc -l)
# If usages == 1 (just the export), safe to remove

Long Function Fixes

Extract Method

// Before: 80-line function
function processOrder(order) {
  // 20 lines: validate
  // 30 lines: calculate
  // 30 lines: persist
}

// After: composed
function processOrder(order) {
  validateOrder(order);
  const totals = calculateTotals(order);
  persistOrder(order, totals);
}

Extract Class

When function has too many responsibilities:

// Before: function with 10 helpers
function handlePayment(payment) { ... }
function validateCard() { ... }
function checkFraud() { ... }
// ...

// After: cohesive class
class PaymentProcessor {
  handle(payment) { ... }
  private validateCard() { ... }
  private checkFraud() { ... }
}

Magic Number Fixes

// Before
if (retries > 3) { ... }
setTimeout(fn, 30000);

// After
const MAX_RETRIES = 3;
const TIMEOUT_MS = 30_000;

if (retries > MAX_RETRIES) { ... }
setTimeout(fn, TIMEOUT_MS);

Config Extraction

// config/limits.ts
export const LIMITS = {
  maxRetries: 3,
  timeoutMs: 30_000,
  maxFileSize: 10_485_760,
} as const;

Deep Nesting Fixes

Early Return

// Before
function process(x) {
  if (x) {
    if (x.valid) {
      if (x.ready) {
        return doWork(x);
      }
    }
  }
  return null;
}

// After
function process(x) {
  if (!x) return null;
  if (!x.valid) return null;
  if (!x.ready) return null;
  return doWork(x);
}

Extract Conditions

// Before
if (user.role === 'admin' && user.active && !user.suspended) { ... }

// After
const canAccess = user.role === 'admin' && user.active && !user.suspended;
if (canAccess) { ... }

// Or
function canAccess(user) {
  return user.role === 'admin' && user.active && !user.suspended;
}

Safe Refactoring Checklist

Before refactoring:

• [ ] Tests exist for affected code
• [ ] Understand all callers
• [ ] Check for reflection/dynamic usage
• [ ] Plan rollback strategy

During:

• [ ] Small commits (one change per commit)
• [ ] Run tests after each step
• [ ] Keep behavior identical (no features)

After:

• [ ] All tests pass
• [ ] Review for missed references
• [ ] Update documentation if needed
• [ ] Monitor prod for regressions