Refactoring

Plan and execute safe refactoring by understanding dependencies and impact.

Quick Start

1. noodlbox_query_with_context  → Find the code to refactor
2. noodlbox_raw_cypher_query   → Map all dependencies
3. noodlbox_detect_impact      → Preview blast radius

Tool Reference

noodlbox_query_with_context

Find code related to the refactoring target.

noodlbox_query_with_context(
  repository: "current",
  q: "payment processing service",
  task_context: "planning to split PaymentService",
  current_goal: "find all payment-related code",
  search_intention: "map dependencies before refactor",
  limit: 10
)

noodlbox_raw_cypher_query

Map dependencies for safe refactoring.

-- Find all callers (what depends on this?)
MATCH (caller)-[:CALLS]->(target:CODE_SYMBOL {name: "PaymentService"})
RETURN caller.name, caller.file_path, caller.community_id
ORDER BY caller.community_id

-- Find all callees (what does this depend on?)
MATCH (source:CODE_SYMBOL {name: "PaymentService"})-[:CALLS]->(callee)
RETURN callee.name, callee.file_path
ORDER BY callee.name

-- Find symbols that would need updating after rename
MATCH (s:CODE_SYMBOL)
WHERE s.name CONTAINS "Payment"
RETURN s.name, s.kind, s.file_path
ORDER BY s.file_path

For more Cypher patterns, see shared/cypher-patterns.md.

noodlbox_detect_impact

Preview what would be affected by the refactor.

noodlbox_detect_impact(
  repository: "current",
  change_scope: "all",
  include_content: false,
  max_processes: 20
)

Workflow Checklist

Rename a Symbol

Rename Refactoring:
- [ ] Find all references to the symbol
- [ ] Check for string literals using the name
- [ ] Identify test files that reference it
- [ ] Check for external API surface changes
- [ ] Plan rename order (interfaces → implementations → usages)
- [ ] Verify no dynamic references (reflection, string keys)

Extract Module

Extract Module Refactoring:
- [ ] Identify code to extract
- [ ] Map all internal dependencies
- [ ] Map all external callers
- [ ] Define new module interface
- [ ] Plan extraction order
- [ ] Update imports across codebase

Split Service

Split Service Refactoring:
- [ ] Map current service responsibilities
- [ ] Group related methods by domain
- [ ] Identify shared state/dependencies
- [ ] Define new service boundaries
- [ ] Plan migration path
- [ ] Create facade for backwards compatibility (if needed)

Example: Rename getUserById to findUserById

Task: "I want to rename getUserById to findUserById. What needs to change?"

Step 1: Find all references
noodlbox_raw_cypher_query(
  repository: "current",
  cypher: "MATCH (caller)-[:CALLS]->(fn:CODE_SYMBOL {name: 'getUserById'}) RETURN caller.name, caller.file_path"
)

→ Results:
  AuthService.validateToken (src/auth/service.ts:45)
  ProfileController.getProfile (src/profile/controller.ts:23)
  OrderService.getOrderOwner (src/orders/service.ts:78)
  UserController.show (src/users/controller.ts:34)

Step 2: Find the definition
noodlbox_raw_cypher_query(
  repository: "current",
  cypher: "MATCH (fn:CODE_SYMBOL {name: 'getUserById'}) RETURN fn.file_path, fn.kind"
)

→ Results:
  UserService (src/users/service.ts) - Method
  UserRepository (src/users/repository.ts) - Method

Step 3: Check for tests
noodlbox_query_with_context(
  repository: "current",
  q: "getUserById test spec",
  task_context: "finding tests for getUserById",
  limit: 5
)

→ Results:
  user.service.spec.ts
  user.repository.spec.ts

Step 4: Create rename plan
Files to update:
1. src/users/service.ts (definition)
2. src/users/repository.ts (definition)
3. src/auth/service.ts (caller)
4. src/profile/controller.ts (caller)
5. src/orders/service.ts (caller)
6. src/users/controller.ts (caller)
7. src/users/service.spec.ts (test)
8. src/users/repository.spec.ts (test)

Checklist for this example:

- [x] Find all references (4 callers)
- [x] Find definitions (2 files)
- [x] Check for tests (2 test files)
- [ ] Check for string literals (grep for "getUserById")
- [ ] Check external API (not exposed)
- [x] Plan rename order

Example: Split PaymentService

Task: "Can I split PaymentService into separate services? Show dependencies."

Step 1: Understand current structure
noodlbox_query_with_context(
  repository: "current",
  q: "PaymentService methods responsibilities",
  task_context: "planning to split payment service",
  current_goal: "map all payment functionality",
  limit: 10
)

→ Results:
  PaymentService methods:
  ├── processPayment
  ├── refundPayment
  ├── validateCard
  ├── calculateFees
  ├── sendReceipt
  └── generateReport

Step 2: Map internal dependencies
noodlbox_raw_cypher_query(
  repository: "current",
  cypher: "MATCH (m)-[:CALLS]->(n) WHERE m.file_path CONTAINS 'payment' AND n.file_path CONTAINS 'payment' RETURN m.name, n.name"
)

→ Results:
  processPayment → validateCard
  processPayment → calculateFees
  refundPayment → calculateFees
  processPayment → sendReceipt

Step 3: Map external callers
noodlbox_raw_cypher_query(
  repository: "current",
  cypher: "MATCH (caller)-[:CALLS]->(fn:CODE_SYMBOL) WHERE fn.file_path CONTAINS 'payment/service' AND NOT caller.file_path CONTAINS 'payment' RETURN DISTINCT caller.name, fn.name, caller.file_path"
)

→ Results:
  CheckoutHandler → processPayment
  WebhookHandler → processPayment
  AdminController → refundPayment
  ReportJob → generateReport

Step 4: Suggest split
Based on dependencies:
- PaymentProcessingService: processPayment, validateCard, calculateFees
- PaymentNotificationService: sendReceipt
- PaymentReportService: generateReport
- PaymentRefundService: refundPayment, calculateFees (shared)

Refactoring Patterns

Risk Assessment

When to Use Something Else