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
Python
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 toggles join 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,
        transitive_depth: int = 0,
        **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).
                Accepts ``func``, ``Class.method``, ``module.func`` and
                ``module.Class.method``. 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).
            transitive_depth: OPT-IN (default ``0``, off). When ``> 0``, the
                data adds ``transitive_test_file_paths``: the tests of the
                symbol AND of its in-package callers up to this many levels
                (a superset of ``test_file_paths``, which stays the direct
                references), plus ``transitive_callers`` (walked symbols) and
                ``transitive_truncated`` (visited-symbol budget hit). ``3`` is
                the measured sweet spot; at most ``10``. Off, data and text
                are the legacy output.
            **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()
        invalid = _invalid_request(project_path, transitive_depth)
        if invalid is not None:
            return ToolResult(success=False, error=invalid)

        raw_filter = kwargs.get("test_filter")
        opts = _impact_options(
            test_filter=raw_filter if isinstance(raw_filter, str) else None,
            include_module_importers=include_module_importers,
            precise_callers=precise_callers,
            transitive_depth=transitive_depth,
        )

        try:
            if symbols is not None:
                return self._execute_batch(
                    project_path, symbols, exclude_tests, detail, opts
                )
            if symbol is None:
                return ToolResult(success=False, error="symbol parameter is required")
            return self._execute_symbol(
                project_path, symbol, exclude_tests, detail, opts
            )
        except Exception as exc:  # noqa: BLE001
            return ToolResult(success=False, error=str(exc))

    def _execute_symbol(
        self,
        project_path: Path,
        symbol: str,
        exclude_tests: bool,
        detail: str | None,
        opts: _ImpactOptions | None = None,
    ) -> ToolResult:
        opts = opts or {}
        candidates = self._qualified_candidates(project_path, symbol)
        if len(candidates) > 1:
            return self._execute_batch(
                project_path,
                sorted(candidates),
                exclude_tests,
                detail,
                opts,
                definition_files=candidates,
            )
        return self._execute_single(project_path, symbol, exclude_tests, detail, opts)

    @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,
        opts: _ImpactOptions | None = None,
        *,
        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")
        options: _ImpactOptions = opts or {}
        results: list[ImpactResult] = [
            self._analyze_single(
                project_path, sym, exclude_tests=exclude_tests, **options
            )
            for sym in symbols
        ]
        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(
        self,
        project_path: Path,
        symbol: str,
        exclude_tests: bool,
        detail: str | None,
        opts: _ImpactOptions | None = None,
    ) -> 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 returns the full report.
        """
        options: _ImpactOptions = opts or {}
        if detail != "compact":
            return self._analyze_single_result(
                project_path, symbol, exclude_tests=exclude_tests, **options
            )
        result = self._analyze_single(
            project_path, symbol, exclude_tests=exclude_tests, **options
        )
        return ToolResult(
            success=True,
            data={},
            text=format_impact_compact(result),
        )

    def _analyze_single_result(
        self,
        project_path: Path,
        symbol: str,
        *,
        exclude_tests: bool = False,
        **opts: Unpack[_ImpactOptions],
    ) -> ToolResult:
        """Run single-symbol impact analysis and return a ToolResult."""
        result = self._analyze_single(
            project_path, symbol, exclude_tests=exclude_tests, **opts
        )
        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,
        )

    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,
        transitive_depth: int = 0,
    ) -> 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. Workspace analysis is tried
        first; a non-workspace path falls back to the single-package core.

        Returns:
            Impact dict with ``score`` key on success,
            or ``{"symbol": name, "error": msg}`` on failure.
        """
        opts = _impact_options(
            test_filter=test_filter,
            include_module_importers=include_module_importers,
            precise_callers=precise_callers,
            transitive_depth=transitive_depth,
        )
        try:
            try:
                impact = _analyze_workspace(project_path, symbol, exclude_tests, opts)
            except ValueError:
                from axm_ast.core.impact import analyze_impact

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

            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)}),
            )
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, transitive_depth=0, **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). Accepts func, Class.method, module.func and module.Class.method. 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
transitive_depth int

OPT-IN (default 0, off). When > 0, the data adds transitive_test_file_paths: the tests of the symbol AND of its in-package callers up to this many levels (a superset of test_file_paths, which stays the direct references), plus transitive_callers (walked symbols) and transitive_truncated (visited-symbol budget hit). 3 is the measured sweet spot; at most 10. Off, data and text are the legacy output.

0
**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
Python
@safe_execute
def execute(  # noqa: PLR0913 - opt-in toggles join 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,
    transitive_depth: int = 0,
    **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).
            Accepts ``func``, ``Class.method``, ``module.func`` and
            ``module.Class.method``. 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).
        transitive_depth: OPT-IN (default ``0``, off). When ``> 0``, the
            data adds ``transitive_test_file_paths``: the tests of the
            symbol AND of its in-package callers up to this many levels
            (a superset of ``test_file_paths``, which stays the direct
            references), plus ``transitive_callers`` (walked symbols) and
            ``transitive_truncated`` (visited-symbol budget hit). ``3`` is
            the measured sweet spot; at most ``10``. Off, data and text
            are the legacy output.
        **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()
    invalid = _invalid_request(project_path, transitive_depth)
    if invalid is not None:
        return ToolResult(success=False, error=invalid)

    raw_filter = kwargs.get("test_filter")
    opts = _impact_options(
        test_filter=raw_filter if isinstance(raw_filter, str) else None,
        include_module_importers=include_module_importers,
        precise_callers=precise_callers,
        transitive_depth=transitive_depth,
    )

    try:
        if symbols is not None:
            return self._execute_batch(
                project_path, symbols, exclude_tests, detail, opts
            )
        if symbol is None:
            return ToolResult(success=False, error="symbol parameter is required")
        return self._execute_symbol(
            project_path, symbol, exclude_tests, detail, opts
        )
    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
Python
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
Python
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)