Ranker

ranker

Symbol importance ranking via PageRank.

Scores every symbol in a package by "importance" using a PageRank-like algorithm on the symbol reference graph. Symbols that are more imported, exported (__all__), or inherited rank higher.

Example

from axm_ast.core.ranker import rank_symbols scores = rank_symbols(pkg) sorted(scores, key=scores.get, reverse=True)[:5] ['Calculator', 'greet', 'resolve_path', ...]

pagerank(graph, damping=0.85, iterations=30)

Compute PageRank scores for a directed graph.

Pure-Python implementation without external dependencies. Edges go from source → target meaning source references target, so target receives the rank boost.

Internal-public: callable from sibling modules and tests, but not re-exported in the package root __all__ (kept out of the public SDK surface — rank_symbols is the documented high-level API).

Parameters:

Name	Type	Description	Default
graph	dict[str, set[str]]	Adjacency dict (node → set of nodes it points to).	required
damping	float	Damping factor (typically 0.85).	0.85
iterations	int	Number of power-iteration steps.	30

Returns:

Type	Description
dict[str, float]	Dict mapping node → importance score (sums to ~1.0).

Source code in packages/axm-ast/src/axm_ast/core/ranker.py

def pagerank(
    graph: dict[str, set[str]],
    damping: float = 0.85,
    iterations: int = 30,
) -> dict[str, float]:
    """Compute PageRank scores for a directed graph.

    Pure-Python implementation without external dependencies.
    Edges go from ``source → target`` meaning source *references* target,
    so target receives the rank boost.

    Internal-public: callable from sibling modules and tests, but not
    re-exported in the package root ``__all__`` (kept out of the public
    SDK surface — ``rank_symbols`` is the documented high-level API).

    Args:
        graph: Adjacency dict (node → set of nodes it points to).
        damping: Damping factor (typically 0.85).
        iterations: Number of power-iteration steps.

    Returns:
        Dict mapping node → importance score (sums to ~1.0).
    """
    nodes = list(graph.keys())
    n = len(nodes)
    if n == 0:
        return {}

    incoming, out_degree = _build_reverse_graph(graph, nodes)
    scores = _iterate_pagerank(nodes, incoming, out_degree, damping, iterations)
    return _normalize_scores(scores)

rank_symbols(pkg)

Rank all symbols in a package by importance.

Uses PageRank on the symbol reference graph to score each function and class. Higher scores mean the symbol is more referenced/exported.

Parameters:

Name	Type	Description	Default
pkg	PackageInfo	Analyzed package info.	required

Returns:

Type	Description
dict[str, float]	Dict mapping symbol name → importance score.

Example

scores = rank_symbols(pkg) top = sorted(scores, key=scores.get, reverse=True) top[0] 'Calculator'

Source code in packages/axm-ast/src/axm_ast/core/ranker.py

def rank_symbols(pkg: PackageInfo) -> dict[str, float]:
    """Rank all symbols in a package by importance.

    Uses PageRank on the symbol reference graph to score each
    function and class. Higher scores mean the symbol is more
    referenced/exported.

    Args:
        pkg: Analyzed package info.

    Returns:
        Dict mapping symbol name → importance score.

    Example:
        >>> scores = rank_symbols(pkg)
        >>> top = sorted(scores, key=scores.get, reverse=True)
        >>> top[0]
        'Calculator'
    """
    graph = _build_symbol_graph(pkg)
    all_scores = pagerank(graph)

    # Filter to only function/class symbols (not module nodes)
    symbol_names = _collect_all_symbols(pkg)
    result = {name: score for name, score in all_scores.items() if name in symbol_names}

    return result