noodlbox

Refactoring

Plan safe renames, extractions, and restructuring

Plan and execute safe refactoring by understanding dependencies and impact.

Invoke with: /noodlbox:refactoring

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

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 Checklists

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?"

Find all references

"Find all callers of getUserById"

Uses: noodlbox_raw_cypher_query

Callers: AuthService.validateToken, ProfileController.getProfile, OrderService.getOrderOwner, UserController.show

Find the definitions

"Where is getUserById defined?"

Uses: noodlbox_raw_cypher_query

Definitions: UserService (src/users/service.ts), UserRepository (src/users/repository.ts)

Check for tests

"Find tests for getUserById"

Uses: noodlbox_query_with_context

Tests: user.service.spec.ts, user.repository.spec.ts

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)

Example: Split PaymentService

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

Understand current structure

"What methods does PaymentService have?"

Uses: noodlbox_query_with_context

Methods: processPayment, refundPayment, validateCard, calculateFees, sendReceipt, generateReport

Map internal dependencies

"What do PaymentService methods call internally?"

Uses: noodlbox_raw_cypher_query

  • processPayment → validateCard, calculateFees, sendReceipt
  • refundPayment → calculateFees

Map external callers

"Who calls PaymentService from outside?"

Uses: noodlbox_raw_cypher_query

  • CheckoutHandler → processPayment
  • WebhookHandler → processPayment
  • AdminController → refundPayment
  • ReportJob → generateReport

Suggest split

Based on dependencies:

  • PaymentProcessingService: processPayment, validateCard, calculateFees
  • PaymentNotificationService: sendReceipt
  • PaymentReportService: generateReport
  • PaymentRefundService: refundPayment, calculateFees (shared)

Risk Assessment

MetricLow RiskMedium RiskHigh Risk
Callers count< 55-20> 20
Cross-community callers01-2> 2
External API changeNoDeprecationBreaking
Shared stateNoneRead-onlyMutable

When to Use Something Else

NeedUse Instead
Quick change impactChange Planning
Explore unfamiliar codeExploring Codebases
Debug failing codeDebugging
Generate documentationGenerating Documentation

On this page