Refactor Check

Analyze whether a refactoring is safe BEFORE making changes. Produces a verdict with specific risks and mitigation steps.

Steps

1. Get the full dependency graph for the target:

• graph(action="update") to ensure graph is current
• query(action="query", pattern="callers_of", target="<name>") -- who calls this
• query(action="query", pattern="callees_of", target="<name>") -- what this calls
• query(action="query", pattern="imports_of", target="<name>") -- what this imports
• If it is a class: query(action="query", pattern="inheritors_of", target="<name>") and query(action="query", pattern="children_of", target="<name>")

1. Identify test coverage:

• query(action="query", pattern="tests_for", target="<name>") -- direct tests
• For each caller, also check tests_for to see if callers have integration tests covering this function indirectly
• Record: number of direct tests, number of callers with tests, number of callers without tests

1. Flag public API exposure:

• Check if the target is exported from a package __init__.py, index.ts, or similar
• Check if the target is referenced from outside its own module/package
• Check if the target appears in documentation or type stubs
• Public API = any function/class importable by external consumers

1. Estimate blast radius:

• query(action="impact", target="<name>") -- full impact analysis
• Count: total impacted files, total impacted functions, depth of dependency chain
• Identify any impacted files outside the immediate package/module

1. Produce verdict:

   ## Refactor Safety: <name>

   ### Target
   - **Location**: <file_path>:<line>
   - **Type**: function / class / method
   - **Public API**: Yes / No

   ### Dependency Summary
   - **Callers**: N functions depend on this
   - **Callees**: Calls M other functions
   - **Inheritance**: N subclasses (if class)

   ### Test Coverage
   - **Direct tests**: N tests
   - **Caller tests**: M/K callers have tests covering this path
   - **Coverage gaps**: <list uncovered callers>

   ### Blast Radius
   - **Impacted files**: N
   - **Impacted functions**: M
   - **Max depth**: K hops

   ### Verdict: SAFE / NEEDS MIGRATION / DANGEROUS

   **SAFE** -- Low blast radius (<5 files), good test coverage, no public API exposure.
   Make the change, run tests, done.

   **NEEDS MIGRATION** -- Public API or moderate blast radius (5-15 files).
   Recommended approach:
   1. Create new version alongside old
   2. Migrate callers incrementally
   3. Deprecate old version
   4. Remove after all callers migrated

   **DANGEROUS** -- High blast radius (>15 files), poor test coverage, or public API with external consumers.
   Specific risks:
   - <risk 1 with affected files>
   - <risk 2 with affected files>
   Mitigation: <steps to reduce risk before proceeding>

Verdict Criteria

When to Use

• Before renaming a function, class, or method
• Before changing a function signature (parameters, return type)
• Before moving code to a different module/package
• Before splitting a class or merging functions
• Before deleting code that might still be referenced