Refactor Check

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

Command surface: run the local CLI through the coding harness shell. Examples use the installed crg command; from a source checkout, prefix it with uv run. No MCP mapping is required.

Steps

1. Get the full dependency graph for the target:
   • crg graph build --base HEAD --repo-root "<path>" to index current working changes
   • crg query query --pattern callers_of --target "<name>" --repo-root "<path>" -- who calls this
   • use --pattern callees_of to see what this calls
   • use --pattern imports_of to see what this imports
   • If it is a class, also query --pattern inheritors_of and --pattern children_of
2. Identify test coverage:
   • crg query query --pattern tests_for --target "<name>" --repo-root "<path>" -- direct tests
   • For each caller, also query 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
3. 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
4. Estimate blast radius:
   • crg query impact --changed-files "<target-file>" --repo-root "<path>" -- file-level impact analysis around the target
   • Count: total impacted files, total impacted functions, depth of dependency chain
   • Identify any impacted files outside the immediate package/module

5. 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