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

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"

    @safe_execute
    def execute(  # noqa: PLR0913 - opt-in module-importers toggle joins the existing option surface
        self,
        *,
        path: str = ".",
        symbol: str | None = None,
        symbols: list[str] | None = None,
        exclude_tests: bool = False,
        detail: str | None = None,
        include_module_importers: bool = False,
        precise_callers: bool = False,
        **kwargs: object,
    ) -> 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).
                An ambiguous bare name expands to one report per module-qualified
                candidate; use one of those qualified names to replay a targeted
                query.
            symbols: Optional list of symbol names for batch inspection.
            exclude_tests: If True, exclude test files from impact analysis.
            detail: Output detail level. Use ``"compact"`` for a markdown
                table summary instead of the full JSON dict.
            include_module_importers: OPT-IN (default ``False``). When ``True``,
                forward the core reverse-import toggle so the result data carries
                a ``module_level_importers`` field listing modules that only
                ``import pkg.m`` the edited symbol's *module* (or a re-export
                shim of it) without referencing the symbol itself -- dependents a
                symbol-level traversal misses. Off (the default) the ToolResult
                data and text are byte-for-byte the legacy output (AC2).
                Best-effort: inert in workspace mode (the core
                ``analyze_impact_workspace`` does not yet accept the toggle -- a
                documented residual, single-package analysis is unaffected) and
                silently empty when the import graph is unavailable.
            precise_callers: OPT-IN (default ``False``). When ``True``,
                discard callers proven to import a distinct homonymous symbol.
                Ambiguous, unresolvable, or unreadable imports remain included
                (fail-open).
            **kwargs: Extra options. ``test_filter`` (``"none"``,
                ``"all"``, ``"related"``) controls test caller filtering.

        Returns:
            ToolResult with impact analysis.

        Note:
            Seeding (Volet B): the analysis seeds from *symbol* verbatim -- the
            tool never derives or proxies the seed. If a caller (the
            BUILD-briefing) hands in a derived/proxy symbol, that mis-seed lives
            on the caller side; it is a documented residual, not fixable here
            without forcing an axm-ast change.
        """
        if not symbol and not symbols:
            return ToolResult(success=False, error="symbol parameter is required")

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

        raw_filter = kwargs.get("test_filter")
        test_filter: str | None = raw_filter if isinstance(raw_filter, str) else None
        tf: _TestFilterKwargs = (
            {"test_filter": test_filter} if test_filter is not None else {}
        )

        try:
            if symbols is not None:
                return self._execute_batch(
                    project_path,
                    symbols,
                    exclude_tests,
                    detail,
                    include_module_importers=include_module_importers,
                    precise_callers=precise_callers,
                    **tf,
                )

            if symbol is None:
                return ToolResult(success=False, error="symbol parameter is required")
            return self._execute_symbol(
                project_path,
                symbol,
                exclude_tests,
                detail,
                include_module_importers=include_module_importers,
                precise_callers=precise_callers,
                **tf,
            )
        except Exception as exc:  # noqa: BLE001
            return ToolResult(success=False, error=str(exc))

    def _execute_symbol(  # noqa: PLR0913 - mirrors the public option surface
        self,
        project_path: Path,
        symbol: str,
        exclude_tests: bool,
        detail: str | None,
        *,
        test_filter: str | None = None,
        include_module_importers: bool = False,
        precise_callers: bool = False,
    ) -> ToolResult:
        candidates = self._qualified_candidates(project_path, symbol)
        target_symbols = sorted(candidates) if len(candidates) > 1 else None
        if target_symbols is not None:
            return self._execute_batch(
                project_path,
                target_symbols,
                exclude_tests,
                detail,
                test_filter=test_filter,
                include_module_importers=include_module_importers,
                precise_callers=precise_callers,
                definition_files=candidates,
            )
        return self._execute_single(
            project_path,
            symbol,
            exclude_tests,
            detail,
            test_filter=test_filter,
            include_module_importers=include_module_importers,
            precise_callers=precise_callers,
        )

    @staticmethod
    def _qualified_candidates(project_path: Path, symbol: str) -> dict[str, str]:
        if "." in symbol:
            return {}
        try:
            pkg = get_package(project_path)
            candidates: dict[str, str] = {}
            for _, candidate in search_symbols(pkg, name=symbol):
                if candidate.name != symbol:
                    continue
                module = find_module_for_symbol(pkg, candidate)
                if module is None:
                    continue
                module_name = module.name or module_dotted_name(module.path, pkg.root)
                candidates[f"{module_name}.{symbol}"] = str(module.path)
            return candidates
        except Exception:  # noqa: BLE001 - ambiguity probing is best-effort
            return {}

    def _execute_batch(  # noqa: PLR0913 - opt-in toggles join the existing option surface
        self,
        project_path: Path,
        symbols: list[str],
        exclude_tests: bool,
        detail: str | None,
        *,
        test_filter: str | None = None,
        include_module_importers: bool = False,
        precise_callers: bool = False,
        definition_files: Mapping[str, str] | None = None,
    ) -> ToolResult:
        """Run batch impact analysis for multiple symbols.

        In compact mode, returns formatted markdown via ``ToolResult.text``
        with an empty ``data`` dict. In full mode, returns per-symbol dicts
        under ``data["symbols"]``.
        """
        if not isinstance(symbols, list):
            return ToolResult(success=False, error="symbols parameter must be a list")
        if not symbols:
            return ToolResult(success=False, error="symbols list must not be empty")
        results: list[ImpactResult] = []
        for sym in symbols:
            tf: _TestFilterKwargs = (
                {"test_filter": test_filter} if test_filter is not None else {}
            )
            if precise_callers:
                results.append(
                    self._analyze_single(
                        project_path,
                        sym,
                        exclude_tests=exclude_tests,
                        include_module_importers=include_module_importers,
                        precise_callers=True,
                        **tf,
                    )
                )
            else:
                results.append(
                    self._analyze_single(
                        project_path,
                        sym,
                        exclude_tests=exclude_tests,
                        include_module_importers=include_module_importers,
                        **tf,
                    )
                )
        if definition_files is not None:
            for result in results:
                candidate_file = definition_files.get(result.get("symbol", ""))
                definition = result.get("definition")
                if candidate_file is not None and definition is not None:
                    definition_data = cast("dict[str, object]", definition)
                    definition_data["file"] = candidate_file
        if detail == "compact":
            return ToolResult(
                success=True,
                data={},
                text=format_impact_compact(cast("list[Mapping[str, object]]", results)),
            )
        text = self._render_batch_text(results)
        return ToolResult(
            success=True,
            data={"symbols": cast("list[dict[str, object]]", results)},
            text=text,
        )

    @staticmethod
    def _render_batch_text(results: list[ImpactResult]) -> str | None:
        """Render batch text from results, returning *None* on failure."""
        try:
            if any("score" in r or "callers" in r for r in results):
                return render_impact_batch_text(results)
        except (KeyError, TypeError):
            pass
        return None

    def _execute_single(  # noqa: PLR0913 - opt-in toggles join the existing option surface
        self,
        project_path: Path,
        symbol: str,
        exclude_tests: bool,
        detail: str | None,
        *,
        test_filter: str | None = None,
        include_module_importers: bool = False,
        precise_callers: bool = False,
    ) -> ToolResult:
        """Run single-symbol impact analysis with optional compact output.

        In compact mode, returns formatted markdown via ``ToolResult.text``
        with an empty ``data`` dict. Otherwise delegates to
        ``_analyze_single_result``.
        """
        tf: _TestFilterKwargs = (
            {"test_filter": test_filter} if test_filter is not None else {}
        )
        if detail == "compact":
            if precise_callers:
                result = self._analyze_single(
                    project_path,
                    symbol,
                    exclude_tests=exclude_tests,
                    include_module_importers=include_module_importers,
                    precise_callers=True,
                    **tf,
                )
            else:
                result = self._analyze_single(
                    project_path,
                    symbol,
                    exclude_tests=exclude_tests,
                    include_module_importers=include_module_importers,
                    **tf,
                )
            return ToolResult(
                success=True,
                data={},
                text=format_impact_compact(result),
            )
        return self._analyze_single_result(
            project_path,
            symbol,
            exclude_tests=exclude_tests,
            include_module_importers=include_module_importers,
            precise_callers=precise_callers,
            **tf,
        )

    def _analyze_single(  # noqa: PLR0913 - opt-in toggles join the option surface
        self,
        project_path: Path,
        symbol: str,
        *,
        exclude_tests: bool = False,
        test_filter: str | None = None,
        include_module_importers: bool = False,
        precise_callers: bool = False,
    ) -> ImpactResult:
        """Run impact analysis for a single symbol.

        The analysis seeds from *symbol* exactly as received (Volet B): the
        real edit-target, never a derived proxy. ``include_module_importers``
        is forwarded to the single-package core path only -- the workspace path
        (``analyze_impact_workspace``) does not yet accept the toggle, so the
        opt-in is a best-effort no-op there (documented residual).

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

                # Residual: the workspace core does not accept the reverse-import
                # toggle yet, so it is intentionally not forwarded here.
                if precise_callers:
                    try:
                        workspace_analyzer = cast(
                            "_PreciseWorkspaceAnalyzer", analyze_impact_workspace
                        )
                        impact = workspace_analyzer(
                            project_path,
                            symbol,
                            exclude_tests=exclude_tests,
                            test_filter=test_filter,
                            precise_callers=True,
                        )
                    except TypeError as exc:
                        if "unexpected keyword argument 'precise_callers'" not in str(
                            exc
                        ):
                            raise
                        impact = analyze_impact_workspace(
                            project_path,
                            symbol,
                            exclude_tests=exclude_tests,
                            test_filter=test_filter,
                        )
                else:
                    impact = analyze_impact_workspace(
                        project_path,
                        symbol,
                        exclude_tests=exclude_tests,
                        test_filter=test_filter,
                    )
            except ValueError:
                from axm_ast.core.impact import analyze_impact

                if precise_callers:
                    impact = analyze_impact(
                        project_path,
                        symbol,
                        exclude_tests=exclude_tests,
                        test_filter=test_filter,
                        include_module_importers=include_module_importers,
                        precise_callers=True,
                    )
                else:
                    impact = analyze_impact(
                        project_path,
                        symbol,
                        exclude_tests=exclude_tests,
                        test_filter=test_filter,
                        include_module_importers=include_module_importers,
                    )

            if impact.get("definition") is None:
                return cast(
                    "ImpactResult",
                    {"symbol": symbol, "error": f"Symbol '{symbol}' not found"},
                )
            return impact
        except Exception as exc:  # noqa: BLE001 — final boundary
            return cast(
                "ImpactResult",
                log_and_fallback(logger, exc, {"symbol": symbol, "error": str(exc)}),
            )

    def _analyze_single_result(  # noqa: PLR0913 - opt-in toggles join the option surface
        self,
        project_path: Path,
        symbol: str,
        *,
        exclude_tests: bool = False,
        test_filter: str | None = None,
        include_module_importers: bool = False,
        precise_callers: bool = False,
    ) -> ToolResult:
        """Run single-symbol impact analysis and return a ToolResult."""
        tf: _TestFilterKwargs = (
            {"test_filter": test_filter} if test_filter is not None else {}
        )
        # Omit the toggle entirely when off so the default delegation stays
        # byte-for-byte identical to the legacy call (AC2); forward it verbatim
        # only when opted-in.
        if include_module_importers and precise_callers:
            result = self._analyze_single(
                project_path,
                symbol,
                exclude_tests=exclude_tests,
                include_module_importers=True,
                precise_callers=True,
                **tf,
            )
        elif include_module_importers:
            result = self._analyze_single(
                project_path,
                symbol,
                exclude_tests=exclude_tests,
                include_module_importers=True,
                **tf,
            )
        elif precise_callers:
            result = self._analyze_single(
                project_path,
                symbol,
                exclude_tests=exclude_tests,
                precise_callers=True,
                **tf,
            )
        else:
            result = self._analyze_single(
                project_path,
                symbol,
                exclude_tests=exclude_tests,
                **tf,
            )
        if "error" in result:
            err = result.get("error", "")
            return ToolResult(
                success=False,
                error=err if isinstance(err, str) else str(err),
            )
        try:
            text: str | None = render_impact_text(result)
        except (KeyError, TypeError):
            text = None
        return ToolResult(
            success=True,
            data=cast("dict[str, object]", result),
            text=text,
        )

name property

Return tool name for registry lookup.

execute(*, path='.', symbol=None, symbols=None, exclude_tests=False, detail=None, include_module_importers=False, precise_callers=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). An ambiguous bare name expands to one report per module-qualified candidate; use one of those qualified names to replay a targeted query.	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
detail	str | None	Output detail level. Use "compact" for a markdown table summary instead of the full JSON dict.	None
include_module_importers	bool	OPT-IN (default False). When True, forward the core reverse-import toggle so the result data carries a module_level_importers field listing modules that only import pkg.m the edited symbol's module (or a re-export shim of it) without referencing the symbol itself -- dependents a symbol-level traversal misses. Off (the default) the ToolResult data and text are byte-for-byte the legacy output (AC2). Best-effort: inert in workspace mode (the core analyze_impact_workspace does not yet accept the toggle -- a documented residual, single-package analysis is unaffected) and silently empty when the import graph is unavailable.	False
precise_callers	bool	OPT-IN (default False). When True, discard callers proven to import a distinct homonymous symbol. Ambiguous, unresolvable, or unreadable imports remain included (fail-open).	False
**kwargs	object	Extra options. test_filter ("none", "all", "related") controls test caller filtering.	{}

Returns:

Type	Description
ToolResult	ToolResult with impact analysis.

Note

Seeding (Volet B): the analysis seeds from symbol verbatim -- the tool never derives or proxies the seed. If a caller (the BUILD-briefing) hands in a derived/proxy symbol, that mis-seed lives on the caller side; it is a documented residual, not fixable here without forcing an axm-ast change.

Source code in packages/axm-ast/src/axm_ast/tools/impact.py

@safe_execute
def execute(  # noqa: PLR0913 - opt-in module-importers toggle joins the existing option surface
    self,
    *,
    path: str = ".",
    symbol: str | None = None,
    symbols: list[str] | None = None,
    exclude_tests: bool = False,
    detail: str | None = None,
    include_module_importers: bool = False,
    precise_callers: bool = False,
    **kwargs: object,
) -> 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).
            An ambiguous bare name expands to one report per module-qualified
            candidate; use one of those qualified names to replay a targeted
            query.
        symbols: Optional list of symbol names for batch inspection.
        exclude_tests: If True, exclude test files from impact analysis.
        detail: Output detail level. Use ``"compact"`` for a markdown
            table summary instead of the full JSON dict.
        include_module_importers: OPT-IN (default ``False``). When ``True``,
            forward the core reverse-import toggle so the result data carries
            a ``module_level_importers`` field listing modules that only
            ``import pkg.m`` the edited symbol's *module* (or a re-export
            shim of it) without referencing the symbol itself -- dependents a
            symbol-level traversal misses. Off (the default) the ToolResult
            data and text are byte-for-byte the legacy output (AC2).
            Best-effort: inert in workspace mode (the core
            ``analyze_impact_workspace`` does not yet accept the toggle -- a
            documented residual, single-package analysis is unaffected) and
            silently empty when the import graph is unavailable.
        precise_callers: OPT-IN (default ``False``). When ``True``,
            discard callers proven to import a distinct homonymous symbol.
            Ambiguous, unresolvable, or unreadable imports remain included
            (fail-open).
        **kwargs: Extra options. ``test_filter`` (``"none"``,
            ``"all"``, ``"related"``) controls test caller filtering.

    Returns:
        ToolResult with impact analysis.

    Note:
        Seeding (Volet B): the analysis seeds from *symbol* verbatim -- the
        tool never derives or proxies the seed. If a caller (the
        BUILD-briefing) hands in a derived/proxy symbol, that mis-seed lives
        on the caller side; it is a documented residual, not fixable here
        without forcing an axm-ast change.
    """
    if not symbol and not symbols:
        return ToolResult(success=False, error="symbol parameter is required")

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

    raw_filter = kwargs.get("test_filter")
    test_filter: str | None = raw_filter if isinstance(raw_filter, str) else None
    tf: _TestFilterKwargs = (
        {"test_filter": test_filter} if test_filter is not None else {}
    )

    try:
        if symbols is not None:
            return self._execute_batch(
                project_path,
                symbols,
                exclude_tests,
                detail,
                include_module_importers=include_module_importers,
                precise_callers=precise_callers,
                **tf,
            )

        if symbol is None:
            return ToolResult(success=False, error="symbol parameter is required")
        return self._execute_symbol(
            project_path,
            symbol,
            exclude_tests,
            detail,
            include_module_importers=include_module_importers,
            precise_callers=precise_callers,
            **tf,
        )
    except Exception as exc:  # noqa: BLE001
        return ToolResult(success=False, error=str(exc))

format_impact_compact(impact)

Format impact analysis as a compact markdown table.

Accepts either a single impact dict or a list of per-symbol reports. When given a list, each symbol gets its own row with per-symbol callers.

Parameters:

Name	Type	Description	Default
impact	Mapping[str, object] | list[Mapping[str, object]]	Single impact dict or list of per-symbol impact dicts.	required

Returns:

Type	Description
str	Markdown string with symbol table, caller details, and test footer.

Source code in packages/axm-ast/src/axm_ast/tools/impact.py

def format_impact_compact(
    impact: Mapping[str, object] | list[Mapping[str, object]],
) -> str:
    """Format impact analysis as a compact markdown table.

    Accepts either a single impact dict or a list of per-symbol reports.
    When given a list, each symbol gets its own row with per-symbol callers.

    Args:
        impact: Single impact dict or list of per-symbol impact dicts.

    Returns:
        Markdown string with symbol table, caller details, and test footer.
    """
    if isinstance(impact, list):
        score = _max_score(impact)
        return format_impact_compact_multi(impact, score)

    # Single-report dict path
    score_raw = impact.get("score", "UNKNOWN")
    score = score_raw if isinstance(score_raw, str) else "UNKNOWN"
    return format_impact_compact_multi([impact], score)

format_impact_compact_multi(reports, score)

Format multiple impact reports as a compact table with per-symbol callers.

Each symbol gets its own row with its own Prod / Direct tests / Indirect tests columns. Each row displays the per-symbol score from the report.

Parameters:

Name	Type	Description	Default
reports	list[Mapping[str, object]]	Individual per-symbol impact dicts.	required
score	str	Kept for backward compatibility (not used for row display).	required

Returns:

Type	Description
str	Markdown table string.

Source code in packages/axm-ast/src/axm_ast/tools/impact.py

def format_impact_compact_multi(
    reports: list[Mapping[str, object]],
    score: str,
) -> str:
    """Format multiple impact reports as a compact table with per-symbol callers.

    Each symbol gets its own row with its own Prod / Direct tests / Indirect
    tests columns.  Each row displays the per-symbol score from the report.

    Args:
        reports: Individual per-symbol impact dicts.
        score: Kept for backward compatibility (not used for row display).

    Returns:
        Markdown table string.
    """
    lines: list[str] = [
        "| Symbol | Location | Score | Prod | Direct tests | Indirect tests |",
        "|---|---|---|---|---|---|",
    ]
    for report in reports:
        row_score_raw = report.get("score", "LOW")
        row_score = row_score_raw if isinstance(row_score_raw, str) else "LOW"
        lines.append(_format_symbol_row(report, row_score))

    # Aggregate test_files across all reports
    seen: set[str] = set()
    all_test_files: list[str] = []
    for report in reports:
        report_tfs = report.get("test_files", [])
        if not isinstance(report_tfs, list):
            continue
        for tf in report_tfs:
            if isinstance(tf, str) and tf not in seen:
                seen.add(tf)
                all_test_files.append(tf)
    lines.append("")
    lines.append(f"Tests: {_format_test_files_compact(all_test_files)}")
    return "\n".join(lines)

render_impact_batch_text(reports)

Render multiple impact reports as human-readable text.

Source code in packages/axm-ast/src/axm_ast/tools/impact_text.py

def render_impact_batch_text(reports: list[ImpactResult]) -> str:
    """Render multiple impact reports as human-readable text."""
    if not reports:
        return ""

    try:
        score_order = {"LOW": 0, "MEDIUM": 1, "HIGH": 2}
        best = "LOW"
        for r in reports:
            s = r.get("score", "LOW")
            if score_order.get(s, 0) > score_order.get(best, 0):
                best = s
        header = f"ast_impact | {len(reports)} symbols | max={best}"
        sections: list[str] = [header]
        for r in reports:
            symbol = r.get("symbol", "?")
            score = r.get("score", "UNKNOWN")
            section_header = f"## {symbol} | {score}"
            body = _render_impact_single(r)
            body_lines = body.split("\n")[1:]
            sections.append(section_header + "\n" + "\n".join(body_lines))
        return "\n\n".join(sections)
    except (KeyError, TypeError, AttributeError):
        return ""

render_impact_text(report)

Render a single impact report as human-readable text.

Source code in packages/axm-ast/src/axm_ast/tools/impact_text.py

def render_impact_text(report: ImpactResult) -> str:
    """Render a single impact report as human-readable text."""
    try:
        return _render_impact_single(report)
    except (KeyError, TypeError, AttributeError):
        symbol = report.get("symbol", "?") if isinstance(report, dict) else "?"
        return f"ast_impact | {symbol} | render error"