How CRG Assists with Refactoring: Renaming Symbols and Dead Code Detection

Code-Review-Graph (CRG) provides a dedicated refactor toolset that automates renaming symbols across repositories and detects dead code by analyzing the knowledge graph for unused functions and classes.

Code-Review-Graph (CRG) transforms static code analysis into actionable refactoring workflows through its graph-based knowledge representation. The repository exposes a comprehensive refactoring API that enables developers to preview and apply structural changes safely. By querying the underlying knowledge graph, CRG identifies refactoring opportunities such as unused symbols and naming inconsistencies that span multiple files.

CRG Refactoring Architecture

The primary entry point for all refactoring operations is refactor_func in code_review_graph/tools/refactor_tools.py. This function validates the requested operation mode and delegates to specialized helpers within the codebase. The implementation constructs a store object representing the current graph state before routing to mode-specific logic.

CRG supports three distinct refactoring modes:

• rename: Generates previews of symbol renaming across the entire repository
• dead_code: Identifies functions, classes, and symbols with no incoming references
• suggest: Produces community-driven refactoring recommendations based on usage patterns

Renaming Symbols with Cross-Reference Safety

The rename functionality leverages rename_preview (lines 70-82 in refactor_tools.py) to build a complete list of required edits before any files are modified. This approach ensures that all references to the symbol—including imports, calls, and definitions—are identified through the knowledge graph.

To preview a rename operation:

from code_review_graph.tools.refactor_tools import refactor_func

preview = refactor_func(
    mode="rename",
    old_name="oldFunc",
    new_name="newFunc"
)

print(preview["summary"])

# → Rename preview: oldFunc -> newFunc, 3 edit(s). Use apply_refactor_tool(...)

The preview returns a unique refactor_id that tracks the proposed changes without modifying the working directory.

Detecting Dead Code Automatically

The dead code detection mode walks the knowledge graph to locate symbols with zero incoming references. The find_dead_code implementation (lines 92-100) accepts optional filters for node kind and file-path patterns, allowing targeted analysis of specific modules.

To identify unused functions within a specific directory:

dead = refactor_func(
    mode="dead_code",
    kind="function",
    file_pattern="utils/"
)

print(f"Dead symbols: {dead['total']}")

# → Dead symbols: 4

print(dead["dead_code"])

# → [{'name': 'unused_helper', 'path': 'src/utils/helpers.py', ...}, ...]

This graph-based approach catches unreachable code that traditional linters might miss, particularly across complex import chains.

Community-Driven Refactoring Suggestions

The suggest mode analyzes usage patterns across the knowledge graph to generate refactoring recommendations. The suggest_refactorings helper (lines 106-114) produces structured suggestion objects that can guide code modernization efforts.

suggestions = refactor_func(mode="suggest")
print(suggestions["summary"])

# → Generated 12 refactoring suggestion(s).

print(suggestions["suggestions"][0])

# → {'action': 'rename', 'old_name': 'fooBar', 'new_name': 'barFoo', ...}

Applying Refactoring Changes Safely

Once a preview is approved, apply_refactor_func (lines 33-56 in refactor_tools.py) executes the stored edits. This function supports dry-run mode, which returns diffs without writing to disk, enabling code review before permanent changes.

from code_review_graph.tools.refactor_tools import apply_refactor_func

result = apply_refactor_func(
    refactor_id=preview["refactor_id"],
    dry_run=False
)

print(result["summary"])

# → Applied 3 edit(s) across 2 file(s).

The underlying implementation in code_review_graph/refactor.py handles the actual file mutations, while code_review_graph/incremental.py manages repository root detection and graph store initialization. Post-operation hints are generated via code_review_graph/hints.py to guide subsequent steps.

Summary

• CRG provides a graph-based refactoring toolset through refactor_func and apply_refactor_func in code_review_graph/tools/refactor_tools.py
• Rename operations generate previews using rename_preview before safely applying changes across all references
• Dead code detection identifies unused symbols by querying for nodes without incoming edges, with optional filtering by kind and file pattern
• Refactoring suggestions leverage community patterns to recommend structural improvements
• Dry-run capabilities allow diff preview without modifying source files, ensuring safe code evolution

Frequently Asked Questions

What file contains the main CRG refactoring API?

The public refactoring API is implemented in code_review_graph/tools/refactor_tools.py, which exports refactor_func for discovering refactoring opportunities and apply_refactor_func for executing changes.

How does CRG identify dead code in a repository?

CRG queries the knowledge graph to find symbols with no incoming references using the find_dead_code function. This graph traversal detects unused functions, classes, and variables that are never imported or called, even across complex module boundaries.

Can I preview refactoring changes before applying them in CRG?

Yes. The refactor_func with mode "rename" generates a preview with a unique refactor_id. You can then call apply_refactor_func with dry_run=True to view diffs without modifying files, or set dry_run=False to apply the changes permanently.

Does CRG support filtering dead code detection to specific file paths?

Yes. The dead_code mode accepts optional kind and file_pattern parameters. For example, setting file_pattern="utils/" limits the search to the utils directory, while kind="function" restricts results to unused functions only.

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