How to Use Dead Code Detection Refactoring Tools in code-review-graph

The code-review-graph repository provides a unified refactor_tool interface that detects unused functions and classes by analyzing the code graph for symbols with no incoming references.

The code-review-graph open-source project ships with built-in dead code detection capabilities that help developers identify and eliminate unused functions, classes, and methods. By leveraging the repository's graph-based analysis engine, you can pinpoint dead code through both a command-line interface and a Python API. This guide explains how to use dead code detection refactoring tools in code-review-graph to clean up your codebase efficiently.

How Dead Code Detection Works

The detection engine operates in three phases: graph population, dead-code querying, and result formatting.

First, parse your repository to build a graph store containing nodes (symbols) and edges (references). This store powers the analysis engine implemented in code_review_graph/refactor.py.

Next, invoke the detection logic using either the generic refactor_tool function with mode="dead_code" or call find_dead_code directly. Both methods ultimately execute the algorithm at line 244 of code_review_graph/refactor.py.

Each dead-code entry returned contains the following fields:

• name – The symbol identifier
• file_path – Absolute location on disk
• relative_path – Location relative to the project root
• language – Detected programming language
• kind – Optional classification (e.g., Function, Class)

CLI Usage for Dead Code Detection

The fastest way to scan for unused code is through the command-line interface defined in code_review_graph/main.py (lines 690-727).

code-review-graph refactor dead_code \
    --kind Function \
    --path src/ \
    --root /repo \
    --json-limit 200

Key flags:

• --kind – Filter by node type (Function, Class, etc.)
• --path – Substring filter for file paths
• --root – Base directory for computing relative paths
• --json-limit – Maximum results in JSON output mode

This CLI command is exercised in the test suite at tests/test_cli_tool_commands.py (lines 78-84).

Python API Implementation

For programmatic access, import the underlying functions directly from the refactor module.

Using find_dead_code Directly

from code_review_graph.refactor import find_dead_code

# Assuming `store` is a GraphStore from the parsing step

dead = find_dead_code(
    store,
    kind="Function",          # optional: limit to functions

    file_pattern="src/",      # optional: path substring filter

    root="/repo",             # optional: project root for relative paths

)

for entry in dead:
    print(entry["name"], "→", entry["relative_path"])

Using the Generic refactor_tool

from code_review_graph.main import refactor_tool

response = refactor_tool(
    mode="dead_code",
    kind="Function",
    file_pattern="src/",
    root="/repo",
)

dead_symbols = response["result"]

Both approaches call the same find_dead_code implementation, ensuring consistent results whether you use the specialized function or the unified tool interface.

Advanced Filtering and Framework Awareness

The dead code detection system includes intelligent filters to reduce false positives.

Entry Point Exclusion – The engine automatically ignores symbols marked with if __name__ == "__main__" guards and recognized test entry points.

Framework Recognition – The analyzer understands framework-specific patterns, correctly preserving:

• Angular callbacks
• React hooks
• Django view functions
• Other lifecycle methods that appear unused but are invoked by frameworks

To target specific symbol types, pass the kind parameter (e.g., kind="Class") to isolate orphaned classes from unused functions.

Summary

• Unified Interface – Use refactor_tool with mode="dead_code" or call find_dead_code directly from code_review_graph/refactor.py.
• Flexible Access – Run scans via CLI (code-review-graph refactor dead_code) or Python API with identical filtering capabilities.
• Smart Detection – The engine excludes framework callbacks and entry points to minimize false positives.
• Rich Metadata – Results include absolute paths, relative paths, language detection, and symbol kinds for precise code cleanup.

Frequently Asked Questions

How does code-review-graph distinguish between dead code and framework callbacks?

The detection engine in code_review_graph/refactor.py maintains framework-specific rules that recognize patterns like React hooks, Angular lifecycle methods, and Django views. These symbols may have no incoming references in the source graph but are preserved because the engine knows external frameworks invoke them.

Can I filter dead code results by specific file directories?

Yes. Use the --path flag in the CLI or the file_pattern parameter in the Python API to limit results to paths containing specific substrings. For example, setting file_pattern="src/" returns only unused symbols located within the src directory tree.

What information does each dead code entry contain?

Every entry returned by find_dead_code includes the symbol's name, absolute file_path, relative_path (computed against the optional root), detected language, and optional kind classification (such as Function or Class). This metadata allows you to prioritize and track cleanup tasks effectively.

Where is the dead code detection logic implemented?

The core algorithm resides in code_review_graph/refactor.py at line 244, while the CLI wrapper and generic refactor_tool interface are defined in code_review_graph/main.py between lines 690-727. Integration tests validating the functionality exist in tests/test_cli_tool_commands.py.

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