refactor-safely

name	refactor-safely
description	Use when planning or executing a refactor — rename, extract, move, or delete code — to prevent breaking callers or missing affected files

Refactor Safely

Overview

Tundra spans 20+ Rust crates, a React SPA, proto definitions, and SQL migrations. A rename in one layer silently breaks another if you don't trace all references first. The graph finds them all.

Core principle: Preview before applying. Never rename across files without seeing the full impact list first.

When to Use

• Renaming a public type, function, or const used in multiple crates
• Extracting a module or splitting a large file
• Moving code between crates (e.g., domain type → shared)
• Deleting code you think is unused
• Restructuring panel components or route files

When NOT to Use

• Single-file rename with no public exports
• Internal-only change with no callers outside the file

The Process

Step 1: Get minimal context

get_minimal_context(task="refactor <what you're changing>")

Step 2: Understand the current shape

query_graph(node_id="<target>", pattern="children_of")   // what it contains
query_graph(node_id="<target>", pattern="callers_of")    // who depends on it
query_graph(node_id="<target>", pattern="imports_of")    // what it pulls in

Build the full dependency picture before touching anything.

Step 3: Find dead code (if removing)

refactor_tool(mode="dead_code")

Returns unreferenced functions/types. Verify with callers_of — graph dead code + zero callers = safe to delete.

Step 4: Get rename suggestions (if restructuring)

refactor_tool(mode="suggest")

Community-driven suggestions for what could be extracted or grouped differently.

Step 5: Preview renames before applying

refactor_tool(mode="rename", node_id="...", new_name="...")

Returns a refactor_id and full list of affected locations. Read the list completely. If unexpected files appear, investigate before proceeding.

Step 6: Check blast radius

get_impact_radius(node_id="<target>")

Shows callers two levels up. Callers you didn't expect = the refactor is larger than assumed.

Step 7: Apply (only after preview is clean)

apply_refactor_tool(refactor_id="...")

Step 8: Verify

detect_changes()

Confirms actual changes match expected scope. Then run cargo check --workspace and pnpm typecheck.

Tundra-Specific Considerations

What you're refactoring	What to check additionally
Public Rust type in tundra-shared	Both Rust callers AND TypeScript api-types.ts DTO
Route handler signature	lib.rs route registration, openapi.yaml spec
DB column name	All SQLx queries in tundrad-repo, any SELECT * statements
Panel component	All import sites + any lazy-loaded routes in routeTree.gen.ts
Enum variant	match exhaustiveness — Rust will catch missing arms, but check JS too if mirrored
Migration table/column	Cannot rename via migration — add new column, migrate data, drop old in sequence

Red Flags

• apply_refactor_tool touches a migration file → stop, migrations are append-only
• Blast radius includes tundrad-auth or tundrad-crypto → get a second review
• Dead code analysis says "unused" but it's a Tonic handler → gRPC services aren't locally called
• Panel component appears unused but is in a lazy route → router may load it dynamically