name: code-organization description: Fixes code organization issues including high complexity, large files, deep nesting, and barrel file problems. Use when functions are too complex, files too long, or directory structure is problematic.

Code Organization Fixes

Fixes for code structure and organization issues. Well-organized code is easier to understand, test, and maintain.

Quick Start

1. Identify the organization issue (complexity, file size, nesting, barrel)
2. Understand the current responsibilities
3. Apply appropriate extraction/restructuring
4. Verify with tests and imports

Priority Matrix

Workflows

High Cyclomatic Complexity (#8 - 46 occurrences)

Detection: complexity ESLint rule or manual review.

Pattern: Functions with many branches (if/else, switch, loops).

// PROBLEM - high cyclomatic complexity
function processOrder(order: Order): Result {
  let result: Result;
  if (order.type === 'standard') {
    if (order.priority === 'high') {
      if (order.items.length > 10) {
        result = processBulkHighPriority(order);
      } else {
        result = processHighPriority(order);
      }
    } else {
      result = processStandard(order);
    }
  } else if (order.type === 'subscription') {
    // ... more nesting
  }
  return result;
}

Fix Strategy 1: Strategy Pattern with early returns.

// SOLUTION - strategy pattern
interface OrderProcessor {
  canHandle(order: Order): boolean;
  process(order: Order): Result;
}

const processors: OrderProcessor[] = [
  new BulkHighPriorityProcessor(),
  new HighPriorityProcessor(),
  new StandardProcessor(),
  new SubscriptionProcessor(),
];

function processOrder(order: Order): Result {
  const processor = processors.find(p => p.canHandle(order));
  if (!processor) {
    throw new Error(`No processor for order type: ${order.type}`);
  }
  return processor.process(order);
}

Fix Strategy 2: Extract functions with guard clauses.

// SOLUTION - extracted functions with guards
function processOrder(order: Order): Result {
  if (order.type === 'subscription') {
    return processSubscription(order);
  }

  if (order.priority === 'high') {
    return processHighPriorityOrder(order);
  }

  return processStandardOrder(order);
}

function processHighPriorityOrder(order: Order): Result {
  if (order.items.length > 10) {
    return processBulkHighPriority(order);
  }
  return processHighPriority(order);
}

Complexity Reduction Techniques:

Large Files (#15 - 4 occurrences)

Detection: File exceeds 350 lines.

Pattern: Single file with multiple responsibilities.

// PROBLEM - monolithic file
src/
  orderService.ts  (500 lines: types + validation + processing + API)

Fix Strategy: Extract by responsibility.

// SOLUTION - separated concerns
src/
  orders/
    types.ts           (50 lines)
    validation.ts      (80 lines)
    processing.ts      (120 lines)
    api.ts             (100 lines)
    index.ts           (20 lines - barrel)

Extraction Guide:

File Size Guidelines:

• Ideal: 100-200 lines
• Acceptable: 200-350 lines
• Needs review: 350-500 lines
• Must split: 500+ lines

Deep Directory Nesting (#33 - 1 occurrence)

Detection: Path depth exceeds 5 levels.

Pattern: Over-categorized directory structure.

// PROBLEM - too deep
src/
  modules/
    orders/
      services/
        processing/
          handlers/
            webhook/
              stripe.ts  (6 levels)

Fix Strategy: Flatten with descriptive names.

// SOLUTION - flattened
src/
  orders/
    webhook-handlers/
      stripe.ts  (3 levels)

Flattening Rules:

1. Max 4 levels from src/
2. Use descriptive compound names instead of deep nesting
3. Group by feature, not by technical layer
4. Use barrel files to simplify imports

Feature-Based Structure:

src/
  features/
    authentication/
      components/
      hooks/
      api.ts
      types.ts
      index.ts
    orders/
      components/
      hooks/
      api.ts
      types.ts
      index.ts
  shared/
    components/
    utils/
    types/

Barrel File Issues (#31, #34)

Issue #31: Barrel file with 0% test coverage.

Fix: Add export verification test.

// __tests__/index.test.ts
import * as exports from '../index';

describe('barrel exports', () => {
  it('exports expected functions', () => {
    expect(exports.processOrder).toBeDefined();
    expect(exports.validateOrder).toBeDefined();
    expect(typeof exports.processOrder).toBe('function');
  });

  it('does not export internal utilities', () => {
    expect((exports as Record<string, unknown>)._internal).toBeUndefined();
  });
});

Issue #34: Long re-export lists.

Fix: Group exports with comments.

// BEFORE - long list
export { a } from './a';
export { b } from './b';
// ... 30 more

// SOLUTION - grouped
// Types
export type { User, Order, Product } from './types';

// Services
export { UserService } from './services/user';
export { OrderService } from './services/order';

// Utilities
export { formatDate, formatCurrency } from './utils/format';
export { validate } from './utils/validation';

Code Duplication (#25 - 10 occurrences)

Pattern: Same logic repeated in multiple places.

// PROBLEM - duplicated in each hook
// pre-commit.ts
const results = await runChecks(stagedFiles);
if (results.failed) {
  console.error(formatErrors(results.errors));
  process.exit(1);
}

// pre-push.ts (same logic)
const results = await runChecks(changedFiles);
if (results.failed) {
  console.error(formatErrors(results.errors));
  process.exit(1);
}

Fix Strategy: Extract shared function.

// SOLUTION - shared runner
// hooks/runner.ts
export interface HookContext {
  name: string;
  files: string[];
  checks: Check[];
}

export async function runHook(context: HookContext): Promise<void> {
  const results = await runChecks(context.files, context.checks);

  if (results.failed) {
    console.error(`${context.name} failed:`);
    console.error(formatErrors(results.errors));
    process.exit(1);
  }

  console.log(`${context.name} passed`);
}

// pre-commit.ts
await runHook({
  name: 'pre-commit',
  files: stagedFiles,
  checks: [lintCheck, typeCheck],
});

Overloaded Function Signatures (#26 - 2 occurrences)

Pattern: Function with multiple overloads doing different things.

// PROBLEM - overloaded signatures
function getUser(id: string): Promise<User>;
function getUser(email: string, byEmail: true): Promise<User>;
function getUser(identifier: string, byEmail?: boolean): Promise<User> {
  if (byEmail) {
    return getUserByEmail(identifier);
  }
  return getUserById(identifier);
}

Fix Strategy: Split into separate well-named functions.

// SOLUTION - separate functions
async function getUserById(id: string): Promise<User> {
  return database.users.findById(id);
}

async function getUserByEmail(email: string): Promise<User> {
  return database.users.findByEmail(email);
}

When overloads are justified:

• Truly polymorphic behavior on same data
• Third-party API compatibility
• Operator-like functions

Scripts

Analyze Code Organization

node scripts/analyze-organization.js /path/to/src

Find Large Files

node scripts/find-large-files.js /path/to/src --max-lines 350

Check Directory Depth

node scripts/check-depth.js /path/to/src --max-depth 5

Refactoring Checklist

Before extracting code:

• Identify clear responsibility boundary
• Check for shared state/side effects
• Plan new file/module structure
• Update imports in dependent files
• Add/update barrel exports
• Run tests after each extraction
• Update documentation if public API changes