Impact
impact
Change impact analysis — who is affected when you modify a symbol.
Composes callers, graph, and search into a single
"what breaks if I change X?" answer.
Example
from axm_ast.core.impact import analyze_impact result = analyze_impact(Path("src/axm_ast"), "analyze_package") print(result["score"]) 'HIGH'
CallerEntry
Bases: TypedDict
Caller record as serialized into the impact result dict.
Source code in packages/axm-ast/src/axm_ast/core/impact.py
DefinitionInfo
Bases: TypedDict
Resolved definition location for a symbol.
module, line and kind are always present; signature and
name are only set for function/class lookups; package is added
by workspace-level resolution.
Source code in packages/axm-ast/src/axm_ast/core/impact.py
ImpactReport
Bases: BaseModel
Input shape consumed by :func:score_impact.
Captures only the inputs to scoring — display-only fields produced by
:func:analyze_impact (symbol, definition, test_files …)
are intentionally excluded.
Source code in packages/axm-ast/src/axm_ast/core/impact.py
ImpactResult
Bases: TypedDict
Output shape of :func:analyze_impact / :func:analyze_impact_workspace.
total=False because workspace results omit cross_package_impact
and test_files_by_import, and add workspace instead.
Source code in packages/axm-ast/src/axm_ast/core/impact.py
ImpactWeights
Bases: BaseModel
Configurable weights and thresholds for :func:score_impact.
Defaults match the module-level constants. Per-package overrides are
loaded from [tool.axm-ast.impact] in pyproject.toml.
Source code in packages/axm-ast/src/axm_ast/core/impact.py
TypeRefEntry
analyze_impact(path, symbol, *, project_root=None, exclude_tests=False, test_filter=None, include_module_importers=False, precise_callers=False, transitive_depth=0)
Full impact analysis for a symbol.
Combines definition location, callers, re-exports, tests, and an impact score.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Path
|
Path to the package directory. |
required |
symbol
|
str
|
Name of the symbol to analyze. |
required |
project_root
|
Path | None
|
Project root (for test detection). |
None
|
exclude_tests
|
bool
|
If True, filter test callers and test type_refs from the output. The impact score is still computed on the full (unfiltered) caller set. |
False
|
test_filter
|
str | None
|
Filter mode for test callers. |
None
|
include_module_importers
|
bool
|
OPT-IN (default |
False
|
precise_callers
|
bool
|
OPT-IN (default |
False
|
transitive_depth
|
int
|
OPT-IN (default |
0
|
Returns:
| Type | Description |
|---|---|
ImpactResult
|
Complete impact analysis dict. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If transitive_depth is out of range, or a dotted symbol cannot be resolved unambiguously. |
Example
result = analyze_impact(Path("src/axm_ast"), "analyze_package") result["score"] 'HIGH'
Source code in packages/axm-ast/src/axm_ast/core/impact.py
| Python | |
|---|---|
1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 | |
analyze_impact_workspace(ws_path, symbol, *, exclude_tests=False, test_filter=None, transitive_depth=0)
Full impact analysis for a symbol across a workspace.
Searches all packages for definition, callers, re-exports, and test files. Module names include package prefix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ws_path
|
Path
|
Path to workspace root. |
required |
symbol
|
str
|
Name of the symbol to analyze. |
required |
exclude_tests
|
bool
|
If True, filter test callers from the output. Score is computed on the full caller set. |
False
|
test_filter
|
str | None
|
Filter mode for test callers. |
None
|
transitive_depth
|
int
|
OPT-IN (default |
0
|
Returns:
| Type | Description |
|---|---|
ImpactResult
|
Complete impact analysis dict (workspace-scoped). |
Example
result = analyze_impact_workspace(Path("/ws"), "ToolResult") result["score"] 'HIGH'
Source code in packages/axm-ast/src/axm_ast/core/impact.py
| Python | |
|---|---|
1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 | |
find_definition(pkg, symbol)
Locate where a symbol is defined.
Supports dotted paths like ClassName.method to find
methods within class bodies. For deeply nested paths like
Outer.Inner.method, resolution is best-effort.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pkg
|
PackageInfo
|
Analyzed package info. |
required |
symbol
|
str
|
Name of the function/class to find. May be
dotted (e.g. |
required |
Returns:
| Type | Description |
|---|---|
DefinitionInfo | None
|
Dict with module, line, kind — or None if not found. |
Source code in packages/axm-ast/src/axm_ast/core/impact.py
find_reexports(pkg, symbol)
Find modules that re-export a symbol via all or imports.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pkg
|
PackageInfo
|
Analyzed package info. |
required |
symbol
|
str
|
Name to search for in exports. |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
List of module names that re-export the symbol. |
Source code in packages/axm-ast/src/axm_ast/core/impact.py
find_type_refs(pkg, type_name)
Find functions that reference a type in their signatures.
Scans all function parameters, return types, and module-level variable annotations for occurrences of type_name using word-boundary matching.
Handles compound types: list[X], dict[str, X],
X | None, Optional[X], nested generics, and
string annotations ("X").
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pkg
|
PackageInfo
|
Analyzed package info. |
required |
type_name
|
str
|
Exact type name to search for (e.g. |
required |
Returns:
| Type | Description |
|---|---|
list[TypeRefEntry]
|
List of dicts with |
list[TypeRefEntry]
|
and |
Source code in packages/axm-ast/src/axm_ast/core/impact.py
map_tests(symbol, project_root)
Find test files that reference a given symbol.
Recursively scans the tests/ directory (including the AXM pyramid
sub-dirs tests/unit|integration|e2e/) for test_*.py files
containing the symbol name as a whole identifier (greet does not
match greeting). Name-only: :func:analyze_impact additionally
scopes a method to the tests that can reach its class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
symbol
|
str
|
Name to search for in test files. |
required |
project_root
|
Path
|
Root of the project. |
required |
Returns:
| Type | Description |
|---|---|
list[Path]
|
List of test file paths that reference the symbol. |
Source code in packages/axm-ast/src/axm_ast/core/impact.py
score_impact(report, weights=None)
Score impact as LOW, MEDIUM, or HIGH.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
report
|
ImpactReport | ImpactResult
|
|
required |
weights
|
ImpactWeights | None
|
Optional override; defaults to module-level weights. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
Impact level string. |