Supported Refactoring Operations in tirth8205/code-review-graph: Rename, Dead Code Detection, and Suggestions

The refactor tool supports three operations: rename for symbol renaming across repositories, dead_code for detecting unused symbols, and suggest for AI-powered refactoring recommendations.

All three modes are dispatched through a unified refactor_tool interface in the tirth8205/code-review-graph repository. The tool validates input parameters, executes the appropriate refactoring operation, and returns structured responses with status, summary, and mode-specific payloads. Understanding these supported refactoring operations helps developers automate code quality improvements at scale.

Rename Operation: Cross-Repository Symbol Renaming

The rename mode generates preview edits for renaming any symbol—functions, classes, variables, or modules—across the entire codebase.

Required Parameters

• old_name — the current symbol identifier
• new_name — the desired replacement identifier

Implementation Details

In code_review_graph/tools/refactor_tools.py, the refactor_func dispatcher validates these parameters and calls rename_preview from code_review_graph/refactor.py. The preview computes all necessary file modifications without applying them immediately.

Rename Code Example

result = refactor_tool(
    mode="rename",
    old_name="OldClassName",
    new_name="NewClassName"
)

Response structure:

{
    "status": "ok",
    "summary": "Rename preview: OldClassName -> NewClassName, 3 edit(s). Use apply_refactor_tool(... ) to apply.",
    "edits": [...],           # List of file edits with diffs

    "refactor_id": "abcd1234",  # Unique identifier for apply step

    ...
}

Apply the previewed changes using apply_refactor_tool(refactor_id="abcd1234").

Dead Code Operation: Detect Unused Symbols

The dead_code mode identifies symbols that are defined but never referenced, helping eliminate maintenance burden from obsolete code.

Optional Filters

Parameter	Purpose	Example
kind	Limit search to specific node types	"function", "class", "variable"
file_pattern	Restrict to files matching substring	"utils" matches src/utils/helpers.py

Implementation Details

The find_dead_code function in refactor.py performs static analysis to track symbol definitions versus references. The optional filters reduce noise in large codebases by narrowing the search scope.

Dead Code Code Example

result = refactor_tool(
    mode="dead_code",
    kind="function",          # Optional: only functions

    file_pattern="utils"      # Optional: paths containing "utils"

)

Response structure:

{
    "status": "ok",
    "summary": "Found 5 dead code symbol(s).",
    "dead_code": [
        {
            "name": "unused_helper",
            "path": "src/utils/helpers.py",
            "line": 42,
            "kind": "function"
        },
        ...
    ],
    "total": 5,
    ...
}

Suggest Operation: AI-Powered Refactoring Recommendations

The suggest mode generates context-aware refactoring proposals based on community patterns and heuristics collected from the repository.

No Required Parameters

This mode requires only mode="suggest"—it analyzes the current codebase state automatically to surface improvement opportunities.

Implementation Details

The suggest_refactorings function in refactor.py applies pattern matching and statistical analysis to identify candidates for transformations like method extraction, variable inlining, or class decomposition.

Suggest Code Example

result = refactor_tool(mode="suggest")

Response structure:

{
    "status": "ok",
    "summary": "Generated 3 refactoring suggestion(s).",
    "suggestions": [
        {
            "type": "extract_method",
            "target": "src/module.py:calculate_total",
            "rationale": "Block exceeds 15 lines and duplicates logic"
        },
        {
            "type": "inline_variable",
            "target": "src/utils.py:temp_result",
            "rationale": "Used only once, obscures readability"
        },
        ...
    ],
    "total": 3,
    ...
}

Tool Architecture and Response Handling

All three refactoring operations share consistent response semantics in refactor_tools.py:

• status: Either "ok" or "error" for immediate validation feedback
• summary: Human-readable description of results
• Mode-specific payload: edits (rename), dead_code (dead code), or suggestions (suggest)

Error handling returns structured error objects with actionable guidance rather than exceptions, enabling robust integration into automated workflows.

Key Source Files

File	Responsibility
code_review_graph/tools/refactor_tools.py	refactor_func dispatcher, apply_refactor_func orchestration
code_review_graph/refactor.py	Core implementations: rename_preview, find_dead_code, suggest_refactorings, apply_refactor
tests/test_refactor.py	Comprehensive test coverage for all three modes and apply operations

Summary

• Three supported refactoring operations: rename (symbol renaming), dead_code (unused symbol detection), and suggest (pattern-based recommendations)
• Unified interface: Single refactor_tool function with mode parameter selects operation dynamically
• Consistent response format: All modes return status, summary, and specialized payload fields
• Preview-then-apply workflow: Rename operations generate refactor_id for separate apply_refactor_tool invocation
• Optional filtering: Dead code mode supports kind and file_pattern constraints for targeted analysis

Frequently Asked Questions

What is the difference between refactor_tool and apply_refactor_tool?

refactor_tool generates previews and analysis results without modifying files. apply_refactor_tool takes a refactor_id from a rename preview and executes the actual file changes. This two-phase design prevents accidental transformations and enables human review.

Can I combine multiple refactoring operations in one call?

No—each invocation of refactor_tool executes exactly one mode. Chain separate calls to perform sequential analysis. For example, run dead_code detection first, then suggest on remaining active code.

How does the dead_code mode determine if something is truly unused?

The find_dead_code function in refactor.py performs static reachability analysis. It flags symbols with no incoming references in the import graph. Dynamic usage through reflection or string-based imports may cause false positives—review suggestions before deletion.

What types of suggestions does the suggest mode generate?

Based on suggest_refactorings implementation, common suggestion types include extract_method for duplicated blocks, inline_variable for single-use assignments, and structural improvements derived from pattern matching against repository history.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}