refactoring

name	refactoring
description	Linter-driven refactoring patterns to reduce complexity and improve code quality in React/TypeScript. Use when ESLint fails with SonarJS complexity issues (cognitive, cyclomatic, expression) or when code feels hard to read/maintain. Applies component extraction, hook extraction, and simplification patterns.

Refactoring (React/TypeScript)

Linter-driven refactoring patterns to reduce complexity and improve React code quality.

When to Use

• ESLint fails with SonarJS complexity issues
• Code feels hard to read or maintain
• Components/functions are too long or deeply nested
• Automatically invoked by @linter-driven-development when linter fails

Critical Rule: Never Disable Linter Rules

IMPORTANT: When refactoring:

• DO NOT add eslint-disable, @ts-ignore, @ts-expect-error, or similar suppression comments
• ALWAYS fix the underlying issue through proper refactoring
• ONLY disable rules as an absolute last resort with explicit user approval
• When approved: Add a comment explaining WHY the rule is disabled
• Linter warnings indicate real code quality issues - fix them, don't hide them

Refactoring Signals

SonarJS Linter Failures

• sonarjs/cognitive-complexity (max: 15) → Simplify logic, extract functions/hooks
• sonarjs/cyclomatic-complexity (max: 10) → Reduce branches, early returns
• sonarjs/expression-complexity (max: 5) → Extract variables, simplify conditions
• sonarjs/max-lines-per-function (max: 200) → Extract components/hooks
• sonarjs/max-lines (max: 600) → Split file into multiple files
• sonarjs/nested-control-flow (max: 4) → Early returns, guard clauses

React-Specific Signals

• react/no-unstable-nested-components → Extract component definitions
• react/no-multi-comp → Split into separate files
• react-hooks/exhaustive-deps → Simplify dependencies, extract logic

Code Smells

• Components > 200 LOC
• Functions with > 4 levels of nesting
• Mixed abstraction levels (UI + business logic)
• Inline complex logic in JSX
• Deeply nested conditionals

Workflow

1. Interpret Linter Output

Run the lint check command from package.json and analyze failures:

src/components/LoginForm.tsx:45:1: Cognitive Complexity of 18 exceeds max of 15
src/components/UserList.tsx:120:5: Cyclomatic Complexity of 12 exceeds max of 10
src/components/DataTable.tsx:89:1: Function has 250 lines, max is 200

2. Diagnose Root Cause

For each failure, ask:

• Mixed abstractions? → Extract custom hooks, extract components
• Complex conditionals? → Early returns, guard clauses, extract conditions
• Primitive obsession? → Create Zod schemas or branded types
• Long component? → Split into smaller components
• Nested components? → Extract to separate components
• Complex JSX logic? → Extract to helper functions or hooks

3. Apply Refactoring Pattern

Choose appropriate pattern:

• Extract Custom Hook: Move logic out of component
• Extract Component: Break down large components
• Extract Helper Function: Simplify complex logic
• Early Returns/Guard Clauses: Reduce nesting
• Simplify Conditions: Extract to variables, use early returns
• Extract Validation: Move to Zod schemas or validation functions

4. Verify Improvement

• Re-run linter using detected lint check command from package.json
• Tests still pass using detected test command from package.json
• Code more readable?

Refactoring Patterns

Pattern 1: Extract Custom Hook (Business Logic)

Signal: Component mixing UI with complex logic

// ❌ Before - Complex logic in component (Cognitive Complexity: 18)
function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null)
  const [isLoading, setIsLoading] = useState(false)
  const [error, setError] = useState<Error | null>(null)

  useEffect(() => {
    const fetchUser = async () => {
      setIsLoading(true)
      setError(null)
      try {
        const response = await fetch(`/api/users/${userId}`)
        if (!response.ok) {
          throw new Error('Failed to fetch user')
        }
        const data = await response.json()
        setUser(data)
      } catch (err) {
        setError(err as Error)
      } finally {
        setIsLoading(false)
      }
    }
    ()
  }, [userId])

   (isLoading)  
   (error)  
   (!user)  

   (
    
  )
}


 () {
   [user, setUser] = useState< | >()
   [isLoading, setIsLoading] = ()
   [error, setError] = useState< | >()

  ( {
      =  () => {
      ()
      ()
       {
         response =  ()
         (!response.)   ()
        ( response.())
      }  (err) {
        (err  )
      }  {
        ()
      }
    }
    ()
  }, [userId])

   { user, isLoading, error }
}

 () {
   { user, isLoading, error } = (userId)

   (isLoading)  
   (error)  
   (!user)  

   (
    
  )
}

Pattern 2: Extract Component (Break Down Large Components)

Signal: Component > 200 lines, doing too much

// ❌ Before - Large component (250 lines, Cognitive Complexity: 22)
function UserDashboard() {
  const [users, setUsers] = useState([])
  const [selectedUser, setSelectedUser] = useState(null)
  const [isEditing, setIsEditing] = useState(false)
  const [searchTerm, setSearchTerm] = useState('')

  // ... 200+ lines of logic and JSX

  return (
    <div>
      {/* Search bar */}
      <input value={searchTerm} onChange={e => setSearchTerm(e.target.value)} />

      {/* User list */}
      <ul>
        {users.filter(u => u.name.includes(searchTerm)).map(user => (
          <li key={user.id} onClick={() => setSelectedUser(user)}>
            {user.name} - {user.email}
            <button onClick={() => setIsEditing(true)}>Edit</button>
            <button onClick={() => deleteUser(user.id)}>Delete</button>
          </li>
        ))}
      </ul>

      {/* User detail */}
      {selectedUser && (
        
          {isEditing ? (
            ...
          ) : (
            ...
          )}
        
      )}
    
  )
}


 () {
   [selectedUser, setSelectedUser] = useState< | >()

   (
    
  )
}

 () {
   [searchTerm, setSearchTerm] = ()
  
   
}

 () {
   { users } = ()
   (
    
  )
}

 () {
   (
    
  )
}

Pattern 3: Early Returns / Guard Clauses (Reduce Nesting)

Signal: Deeply nested conditionals, cyclomatic complexity high

// ❌ Before - Deep nesting (Cyclomatic Complexity: 12, Nesting: 5)
function validateAndSubmit(data: FormData) {
  if (data) {
    if (data.email) {
      if (isValidEmail(data.email)) {
        if (data.password) {
          if (data.password.length >= 8) {
            if (data.terms) {
              return submitForm(data)
            } else {
              return { error: 'Must accept terms' }
            }
          } else {
            return { error: 'Password too short' }
          }
        } else {
          return { error: 'Password required' }
        }
      } else {
        return { error: 'Invalid email' }
      }
    } else {
      return { error: 'Email required' }
    }
  }
  return { error: 'No data' }
}

// ✅ After - Early returns (Cyclomatic Complexity: 7, Nesting: 1)
function validateAndSubmit(: ) {
   (!data)  { :  }
   (!data.)  { :  }
   (!(data.))  { :  }
   (!data.)  { :  }
   (data.. < )  { :  }
   (!data.)  { :  }

   (data)
}


  = z.({
  : z.().(),
  : z.().(),
  : z.().( val === , )
})

 () {
   result = .(data)
   (!result.) {
     { : result..[]. }
  }
   (result.)
}

Pattern 4: Extract Complex Conditions (Simplify Expression Complexity)

Signal: Complex boolean expressions, expression complexity > 5

// ❌ Before - Complex condition (Expression Complexity: 8)
if (
  user &&
  user.isActive &&
  !user.isBanned &&
  user.subscription &&
  user.subscription.status === 'active' &&
  user.subscription.expiresAt > Date.now() &&
  (user.roles.includes('admin') || user.roles.includes('moderator'))
) {
  // Allow access
}

// ✅ After - Extracted to helper functions
function hasActiveSubscription(user: User): boolean {
  return (
    user.subscription?.status === 'active' &&
    user.subscription.expiresAt > Date.now()
  )
}

function hasModeratorAccess(user: User): boolean {
  return user.roles.includes('admin') || user.roles.includes('moderator')
}

function canAccessFeature(: ):  {
   (
    user. &&
    !user. &&
    (user) &&
    (user)
  )
}

 (user && (user)) {
  
}


 isUserValid = user. && !user.
 hasSubscription = (user)
 isModerator = (user)

 (user && isUserValid && hasSubscription && isModerator) {
  
}

Pattern 5: Extract Unstable Nested Components

Signal: react/no-unstable-nested-components

// ❌ Before - Component defined inside component
function UserList() {
  const users = useUsers()

  // ❌ Recreated on every render
  const UserCard = ({ user }: { user: User }) => (
    <div>
      <h3>{user.name}</h3>
      <p>{user.email}</p>
    </div>
  )

  return (
    <div>
      {users.map(user => <UserCard key={user.id} user={user} />)}
    </div>
  )
}

// ✅ After - Component extracted
function UserCard({ user }: { user: User }) {
  return (
    <div>
      <h3>{user.name}</h3>
      <p>{user.email}</p>
    </div>
  )
}

function UserList() {
  const users = useUsers()
   (
    
  )
}

Pattern 6: Simplify Hook Dependencies

Signal: react-hooks/exhaustive-deps warnings, complex useEffect

// ❌ Before - Complex dependencies
function SearchResults({ initialQuery, filters, sortBy }: Props) {
  const [results, setResults] = useState([])

  useEffect(() => {
    const fetchResults = async () => {
      const response = await api.search({
        query: initialQuery,
        filters: filters,
        sort: sortBy,
        page: 1
      })
      setResults(response.data)
    }
    fetchResults()
  }, [initialQuery, filters, sortBy, filters.category, filters.price]) // ❌ Duplicates, object deps
}

// ✅ After - Simplified with custom hook
function useSearchResults(query: string, filters: Filters, sortBy: string) {
  const [results, setResults] = useState([])

  // Stable object reference
  const searchParams = useMemo(
    () => ({ query, filters, sort: sortBy, page: 1 }),
    [query, filters, sortBy]
  )

  useEffect(() => {
    api.(searchParams).( (response.))
  }, [searchParams])

   results
}

 () {
   results = (initialQuery, filters, sortBy)
   
}

Pattern 7: Extract Form Validation Logic

Signal: Complex validation in components

// ❌ Before - Validation scattered in component
function LoginForm() {
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
  const [errors, setErrors] = useState({})

  const handleSubmit = () => {
    const newErrors = {}

    if (!email) {
      newErrors.email = 'Email required'
    } else if (!/\S+@\S+\.\S+/.test(email)) {
      newErrors.email = 'Invalid email'
    }

    if (!password) {
      newErrors.password = 'Password required'
    } else if (password.length < 8) {
      newErrors.password = 'Password too short'
    }

    if (Object.keys(newErrors).length > 0) {
      setErrors(newErrors)
      return
    }

    submitLogin(email, password)
  }

  // ...JSX
}

// ✅ After - Validation with Zod
import { z } from 'zod'

const LoginSchema = z.({
  : z.().(),
  : z.().(, )
})

 () {
   { values, errors, setValue, handleSubmit } = (
    ,
    { : , :  },
    submitLogin
  )

   (
    
  )
}

Refactoring Decision Tree

When linter fails, follow this decision tree:

Linter Failure
    ├─ Cognitive Complexity > 15
    │   ├─ Mixed abstractions? → Extract custom hooks
    │   ├─ Complex conditions? → Extract to helper functions
    │   └─ Deep nesting? → Early returns, guard clauses
    │
    ├─ Cyclomatic Complexity > 10
    │   ├─ Many branches? → Early returns
    │   ├─ Complex switch? → Use object mapping or extract functions
    │   └─ Multiple &&/|| chains? → Extract conditions to variables
    │
    ├─ Expression Complexity > 5
    │   ├─ Long boolean expressions? → Extract to variables
    │   └─ Nested ternaries? → Extract to function or if statements
    │
    ├─ Max Lines Per Function > 200
    │   ├─ Large component? → Extract smaller components
    │   ├─ Complex logic? → Extract custom hooks
    │   └─ Mixed concerns? → Separate UI from business logic
    │
    ├─ Nested Control Flow > 4
    │   └─ Deep nesting? → Early returns, guard clauses
    │
    └─ React-specific
        ├─ no-unstable-nested-components → Extract component definition
        ├─ no-multi-comp → Split into separate files
        └─ exhaustive-deps → Simplify dependencies, extract logic

Key Principles

See reference.md for detailed principles:

• Never Disable Rules: Fix issues through refactoring, never suppress with eslint-disable or @ts-ignore
• Single Responsibility: Each component/hook does one thing
• DRY (Don't Repeat Yourself): Extract repeated patterns to reusable utilities/constants
• Check Before Creating: Search for existing type guards, utilities, and constants before creating new ones
• Extract Early, Extract Often: Don't wait for linter to fail
• Composition Over Complexity: Combine simple pieces
• Guard Clauses: Exit early, reduce nesting
• Extract Helper Functions: Name complex logic
• Type Guards: Use utilities (isString, isNumber) instead of repeated typeof checks
• Custom Hooks: Reusable logic outside components
• Zod for Validation: Move validation out of components

After Refactoring

• Re-run linter using detected lint command - changed code must have no linting errors
• Run tests using detected test command
• Verify behavior unchanged
• Check if more readable
• Consider broader refactoring if patterns repeat

Success Criteria: Comments

No comments on functions, variables, or code lines - they should be self-explanatory through good naming.

Acceptable comments:

• File-level comments explaining a complex hook's purpose or architecture
• JSDoc for public API functions that will be consumed by other modules
• Comments explaining WHY (non-obvious business logic, intentional tradeoffs)

Not acceptable:

• Comments explaining WHAT code does (refactor to better names instead)
• Comments on variables or individual lines
• Comments that repeat the function/variable name

See examples.md for detailed examples.

Acceptance Criteria

CRITICAL: All criteria must be met before completing refactoring.

Mandatory Requirements (Must Pass)

1. No Linter Rule Disabling in Refactored Code

   • Refactored files contain NO new eslint-disable, eslint-disable-next-line, eslint-disable-line comments
   • Refactored files contain NO new @ts-ignore, @ts-expect-error, @ts-nocheck comments
   • Pre-existing disabling comments in unchanged files are acceptable (not in scope)
   • All linter issues resolved through proper refactoring patterns
   • If disabling seems necessary: Stop, reconsider approach, ask user for approval

2. All Linter Checks Pass Clean

   • ESLint: 0 errors, 0 warnings in refactored files
   • TypeScript: 0 errors
   • No new linter issues introduced by refactoring

3. Behavior Preserved

   • All existing tests still pass
   • No functionality removed or changed (unless explicitly requested)
   • Public API unchanged (unless explicitly requested)

4. Iterative Verification (Multiple Passes)

   • Run linter after each refactoring step
   • Run linter at least twice after final changes
   • Both runs pass clean with no new issues
   • If fix introduces new issue, address it before proceeding

Verification Workflow

IMPORTANT: Detect available scripts from the project's package.json before running checks.

# After each refactoring step:
Run lint check command from package.json (quick verification)

# After all refactoring complete:
# Iteration 1
Run all quality check commands detected from package.json:
- TypeScript check
- Linting check
- Tests

# Iteration 2 (verify stability)
Run the same quality check commands again

# Both must pass clean before refactoring is complete

Refactoring Completion Checklist

✅ REFACTORING ACCEPTANCE CRITERIA

Linter Compliance (MANDATORY):
[ ] No eslint-disable comments added
[ ] No @ts-ignore/@ts-expect-error added
[ ] All complexity issues fixed through refactoring patterns
[ ] Did NOT disable rules to "fix" issues
[ ] If any disabling approved: comment explains WHY

Quality Verification:
[ ] ESLint passes clean (0 errors/warnings)
[ ] TypeScript compiles (0 errors)
[ ] All tests pass
[ ] Ran verification twice consecutively

Code Quality:
[ ] No comments explaining WHAT (only WHY if needed)
[ ] Self-explanatory naming
[ ] Single responsibility per function/component
[ ] No repeated typeof checks (use type guards)

Refactoring complete: All boxes checked ✅

What Blocks Completion

The following will BLOCK refactoring completion:

• Any new linter disabling comment (without explicit user approval)
• Approved linter disabling without explanatory comment (why was it necessary)
• Complexity still above thresholds
• Any failing linter check in refactored files
• Single-run verification (must run twice)
• Tests failing after refactoring

Acceptable Exceptions (Require User Approval)

Only with explicit user consent:

• Keeping complexity slightly above threshold with justification
• Disabling a specific rule with documented reason
• Breaking behavior change (if explicitly requested)

When disabling a rule with approval, add a comment explaining WHY:

// ❌ Bad: Disabled without explanation
// eslint-disable-next-line sonarjs/cognitive-complexity
function complexLegacyParser() { ... }

// ✅ Good: Disabled with justification
// eslint-disable-next-line sonarjs/cognitive-complexity -- Legacy parser with complex state machine, refactoring planned in Q2
function complexLegacyParser() { ... }

Document any exceptions when reporting refactoring results.

Additional Resources

• reference.md - Complete refactoring patterns, storifying techniques, and decision trees
• examples.md - Real-world refactoring examples:
  • Avoid IIFE (use lookup objects or helper functions)
  • No empty blocks (use early returns, guard clauses)
  • Magic numbers (extract to named constants)
  • Comments philosophy (explain WHY, not WHAT)
  • Complex conditionals to early returns