Skip to content

Dead code

dead_code

DeadCodeTool — detect unreferenced symbols in a package.

DeadCodeTool

Bases: AXMTool

Detect dead (unreferenced) code symbols in a Python package.

Registered as ast_dead_code via axm.tools entry point.

Source code in packages/axm-ast/src/axm_ast/tools/dead_code.py
Python
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
class DeadCodeTool(AXMTool):
    """Detect dead (unreferenced) code symbols in a Python package.

    Registered as ``ast_dead_code`` via axm.tools entry point.
    """

    @property
    def name(self) -> str:
        """Return tool name for registry lookup."""
        return "ast_dead_code"

    @safe_execute
    def execute(
        self,
        *,
        path: str = ".",
        include_tests: bool = False,
        **kwargs: object,
    ) -> ToolResult:
        """Find dead code in a Python package.

        Args:
            path: Path to package directory.
            include_tests: Include test fixtures in scan (default False).

        Returns:
            ToolResult with dead symbols list.
        """
        pkg_path = Path(path).resolve()
        if not pkg_path.is_dir():
            return ToolResult(success=False, error=f"Not a directory: {pkg_path}")

        from axm_ast.core.cache import get_package
        from axm_ast.core.dead_code import find_dead_code

        pkg = get_package(pkg_path)
        dead = find_dead_code(pkg, include_tests=include_tests)

        symbols: list[DeadSymbolEntry] = [
            {
                "name": d.name,
                "module_path": d.module_path,
                "line": d.line,
                "kind": d.kind,
            }
            for d in dead
        ]

        return ToolResult(
            success=True,
            data={"dead_symbols": symbols, "total": len(dead)},
            text=self._render_text(symbols, pkg_root=str(pkg_path)),
        )

    @staticmethod
    def _render_text(symbols: list[DeadSymbolEntry], *, pkg_root: str) -> str:
        """Render dead symbols as compact text for token-efficient MCP responses."""
        header = f"ast_dead_code | {len(symbols)} dead symbols"
        if not symbols:
            return header
        prefix = pkg_root.rstrip("/") + "/"
        lines = [header, ""]
        for s in symbols:
            mod = s["module_path"]
            if mod.startswith(prefix):
                mod = mod[len(prefix) :]
            kind = _KIND_SHORT.get(s["kind"], s["kind"])
            lines.append(f"{kind:5s} {s['name']}  {mod}:{s['line']}")
        return "\n".join(lines)
name property

Return tool name for registry lookup.

execute(*, path='.', include_tests=False, **kwargs)

Find dead code in a Python package.

Parameters:

Name Type Description Default
path str

Path to package directory.

 '.'
include_tests bool

Include test fixtures in scan (default False).

 False

Returns:

Type Description
ToolResult

ToolResult with dead symbols list.
Source code in packages/axm-ast/src/axm_ast/tools/dead_code.py
Python
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
@safe_execute
def execute(
    self,
    *,
    path: str = ".",
    include_tests: bool = False,
    **kwargs: object,
) -> ToolResult:
    """Find dead code in a Python package.

    Args:
        path: Path to package directory.
        include_tests: Include test fixtures in scan (default False).

    Returns:
        ToolResult with dead symbols list.
    """
    pkg_path = Path(path).resolve()
    if not pkg_path.is_dir():
        return ToolResult(success=False, error=f"Not a directory: {pkg_path}")

    from axm_ast.core.cache import get_package
    from axm_ast.core.dead_code import find_dead_code

    pkg = get_package(pkg_path)
    dead = find_dead_code(pkg, include_tests=include_tests)

    symbols: list[DeadSymbolEntry] = [
        {
            "name": d.name,
            "module_path": d.module_path,
            "line": d.line,
            "kind": d.kind,
        }
        for d in dead
    ]

    return ToolResult(
        success=True,
        data={"dead_symbols": symbols, "total": len(dead)},
        text=self._render_text(symbols, pkg_root=str(pkg_path)),
    )

DeadSymbolEntry

Bases: TypedDict

Serialized dead-symbol record for ast_dead_code output.

Source code in packages/axm-ast/src/axm_ast/tools/dead_code.py
Python
18
19
20
21
22
23
24
class DeadSymbolEntry(TypedDict):
    """Serialized dead-symbol record for ``ast_dead_code`` output."""

    name: str
    module_path: str
    line: int
    kind: str