Doc impact

doc_impact

Doc impact analysis — doc refs, undocumented symbols, stale signatures.

analyze_doc_impact(root, symbols)

Full doc impact analysis for a set of symbols.

Combines doc refs, undocumented detection, and stale signature detection.

Parameters:

Name	Type	Description	Default
root	Path	Project root directory.	required
symbols	list[str]	Symbol names to analyze.	required

Returns:

Type	Description
dict[str, Any]	Dict with doc_refs, undocumented, stale_signatures.

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

def analyze_doc_impact(
    root: Path,
    symbols: list[str],
) -> dict[str, Any]:
    """Full doc impact analysis for a set of symbols.

    Combines doc refs, undocumented detection, and stale
    signature detection.

    Args:
        root: Project root directory.
        symbols: Symbol names to analyze.

    Returns:
        Dict with ``doc_refs``, ``undocumented``, ``stale_signatures``.
    """
    refs = find_doc_refs(root, symbols)
    return {
        "doc_refs": refs,
        "undocumented": find_undocumented(refs),
        "stale_signatures": find_stale_signatures(root, symbols),
    }

find_doc_refs(root, symbols)

Find documentation references for given symbols.

Parameters:

Name	Type	Description	Default
root	Path	Project root directory.	required
symbols	list[str]	Symbol names to search for in docs.	required

Returns:

Type	Description
dict[str, list[dict[str, Any]]]	Dict mapping symbol name to list of references
dict[str, list[dict[str, Any]]]	(each with file and line keys).

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

def find_doc_refs(
    root: Path,
    symbols: list[str],
) -> dict[str, list[dict[str, Any]]]:
    """Find documentation references for given symbols.

    Args:
        root: Project root directory.
        symbols: Symbol names to search for in docs.

    Returns:
        Dict mapping symbol name to list of references
        (each with ``file`` and ``line`` keys).
    """
    doc_files = _collect_doc_files(root)
    refs: dict[str, list[dict[str, Any]]] = {s: [] for s in symbols}
    for sym in symbols:
        for doc_file in doc_files:
            hits = _search_symbol_in_file(doc_file, sym, root)
            refs[sym].extend(hits)
    return refs

find_stale_signatures(root, symbols)

Detect stale code signatures in documentation.

Compares def / class signatures in doc code blocks against actual AST signatures.

Parameters:

Name	Type	Description	Default
root	Path	Project root directory.	required
symbols	list[str]	Symbol names to check.	required

Returns:

Type	Description
list[dict[str, Any]]	List of dicts with symbol, file, doc_sig,
list[dict[str, Any]]	actual_sig, and line keys.

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

def find_stale_signatures(
    root: Path,
    symbols: list[str],
) -> list[dict[str, Any]]:
    """Detect stale code signatures in documentation.

    Compares ``def`` / ``class`` signatures in doc code blocks
    against actual AST signatures.

    Args:
        root: Project root directory.
        symbols: Symbol names to check.

    Returns:
        List of dicts with ``symbol``, ``file``, ``doc_sig``,
        ``actual_sig``, and ``line`` keys.
    """
    ast_sigs = _extract_ast_signatures(root)
    doc_files = _collect_doc_files(root)
    sym_set = set(symbols)
    stale: list[dict[str, Any]] = []
    for doc_file in doc_files:
        doc_sigs = _extract_doc_signatures(doc_file, sym_set, root)
        for entry in doc_sigs:
            sym_name = entry["symbol"]
            if sym_name in ast_sigs:
                actual = ast_sigs[sym_name]
                doc_sig = entry["doc_sig"]
                # Normalize for comparison: strip whitespace
                if doc_sig.strip() != actual.strip():
                    entry["actual_sig"] = actual
                    stale.append(entry)
    return stale

find_undocumented(doc_refs)

Return symbols that have no documentation references.

Parameters:

Name	Type	Description	Default
doc_refs	dict[str, list[dict[str, Any]]]	Output of find_doc_refs.	required

Returns:

Type	Description
list[str]	List of symbol names with empty references.

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

def find_undocumented(
    doc_refs: dict[str, list[dict[str, Any]]],
) -> list[str]:
    """Return symbols that have no documentation references.

    Args:
        doc_refs: Output of ``find_doc_refs``.

    Returns:
        List of symbol names with empty references.
    """
    return [sym for sym, refs in doc_refs.items() if not refs]