Skip to content

Impact

impact

ImpactTool — change impact analysis.

ImpactTool

Bases: AXMTool

Analyze blast radius of changing a symbol.

Registered as ast_impact via axm.tools entry point. Workspace-aware: if path is a uv workspace root, analyzes impact across all member packages.

Source code in packages/axm-ast/src/axm_ast/tools/impact.py 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
class ImpactTool(AXMTool):
    """Analyze blast radius of changing a symbol.

    Registered as ``ast_impact`` via axm.tools entry point.
    Workspace-aware: if path is a uv workspace root, analyzes
    impact across all member packages.
    """

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

    def execute(
        self,
        *,
        path: str = ".",
        symbol: str | None = None,
        symbols: list[str] | None = None,
        exclude_tests: bool = False,
        **kwargs: Any,
    ) -> ToolResult:
        """Analyze change impact for a symbol.

        Args:
            path: Path to package or workspace directory.
            symbol: Symbol name to analyze (required if symbols is not provided).
            symbols: Optional list of symbol names for batch inspection.
            exclude_tests: If True, exclude test files from impact analysis.

        Returns:
            ToolResult with impact analysis.
        """
        if not symbol and not symbols:
            return ToolResult(success=False, error="symbol parameter is required")

        try:
            project_path = Path(path).resolve()
            if not project_path.is_dir():
                return ToolResult(
                    success=False, error=f"Not a directory: {project_path}"
                )

            if symbols is not None:
                if not isinstance(symbols, list):
                    return ToolResult(
                        success=False, error="symbols parameter must be a list"
                    )
                results: list[dict[str, Any]] = []
                for sym in symbols:
                    results.append(
                        self._analyze_single(
                            project_path, sym, exclude_tests=exclude_tests
                        )
                    )
                return ToolResult(success=True, data={"symbols": results})

            assert symbol is not None  # already guarded above
            return self._analyze_single_result(
                project_path, symbol, exclude_tests=exclude_tests
            )
        except Exception as exc:
            return ToolResult(success=False, error=str(exc))

    def _analyze_single(
        self,
        project_path: Path,
        symbol: str,
        *,
        exclude_tests: bool = False,
    ) -> dict[str, Any]:
        """Run impact analysis for a single symbol.

        Returns:
            Impact dict with ``severity`` key on success,
            or ``{"symbol": name, "error": msg}`` on failure.
        """
        try:
            from axm_ast.core.workspace import detect_workspace

            ws = detect_workspace(project_path)
            if ws is not None:
                from axm_ast.core.impact import analyze_impact_workspace

                impact = analyze_impact_workspace(
                    project_path, symbol, exclude_tests=exclude_tests
                )
            else:
                from axm_ast.core.impact import analyze_impact

                impact = analyze_impact(
                    project_path, symbol, exclude_tests=exclude_tests
                )

            impact["severity"] = impact.get("score", "UNKNOWN")
            if impact.get("definition") is None:
                return {"symbol": symbol, "error": f"Symbol '{symbol}' not found"}
            return impact
        except Exception as exc:
            return {"symbol": symbol, "error": str(exc)}

    def _analyze_single_result(
        self,
        project_path: Path,
        symbol: str,
        *,
        exclude_tests: bool = False,
    ) -> ToolResult:
        """Run single-symbol impact analysis and return a ToolResult."""
        result = self._analyze_single(project_path, symbol, exclude_tests=exclude_tests)
        if "error" in result:
            return ToolResult(success=False, error=result["error"])
        return ToolResult(
            success=True,
            data=result,
            hint="Tip: Run affected tests, then ast_inspect on high-risk callers.",
        )
name property

Return tool name for registry lookup.

execute(*, path='.', symbol=None, symbols=None, exclude_tests=False, **kwargs)

Analyze change impact for a symbol.

Parameters:

Name Type Description Default
path str

Path to package or workspace directory.

 '.'
symbol str | None

Symbol name to analyze (required if symbols is not provided).

 None
symbols list[str] | None

Optional list of symbol names for batch inspection.

 None
exclude_tests bool

If True, exclude test files from impact analysis.

 False

Returns:

Type Description
ToolResult

ToolResult with impact analysis.
Source code in packages/axm-ast/src/axm_ast/tools/impact.py 
29
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
def execute(
    self,
    *,
    path: str = ".",
    symbol: str | None = None,
    symbols: list[str] | None = None,
    exclude_tests: bool = False,
    **kwargs: Any,
) -> ToolResult:
    """Analyze change impact for a symbol.

    Args:
        path: Path to package or workspace directory.
        symbol: Symbol name to analyze (required if symbols is not provided).
        symbols: Optional list of symbol names for batch inspection.
        exclude_tests: If True, exclude test files from impact analysis.

    Returns:
        ToolResult with impact analysis.
    """
    if not symbol and not symbols:
        return ToolResult(success=False, error="symbol parameter is required")

    try:
        project_path = Path(path).resolve()
        if not project_path.is_dir():
            return ToolResult(
                success=False, error=f"Not a directory: {project_path}"
            )

        if symbols is not None:
            if not isinstance(symbols, list):
                return ToolResult(
                    success=False, error="symbols parameter must be a list"
                )
            results: list[dict[str, Any]] = []
            for sym in symbols:
                results.append(
                    self._analyze_single(
                        project_path, sym, exclude_tests=exclude_tests
                    )
                )
            return ToolResult(success=True, data={"symbols": results})

        assert symbol is not None  # already guarded above
        return self._analyze_single_result(
            project_path, symbol, exclude_tests=exclude_tests
        )
    except Exception as exc:
        return ToolResult(success=False, error=str(exc))