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
 99
100
101
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}")

        try:
            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
            ]
        except Exception as exc:  # noqa: BLE001
            return ToolResult(success=False, error=str(exc))

        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
83
84
85
@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}")

    try:
        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
        ]
    except Exception as exc:  # noqa: BLE001
        return ToolResult(success=False, error=str(exc))

    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