Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

13.2 KB
Raw Blame
"""Rescues for symbols a framework or a container reaches, not a caller.

Each case here is a symbol the repository really uses and whose name a search
would correctly report as absent, because the name is the wrong thing to look
for: a template invokes a tag by its registered string, and a C# call site
writes an extension method's name and never its holder class's.
"""

from __future__ import annotations

from pathlib import Path

import networkx as nx
import pytest

from repowise.core.analysis.dead_code import DeadCodeAnalyzer, DeadCodeKind
from repowise.core.analysis.dead_code.analyzer import _declared_deliberately_unused
from repowise.core.ingestion import ASTParser, FileTraverser, GraphBuilder
from tests.unit.dead_code._helpers import _build_graph


def _unused_export_names(graph: nx.DiGraph) -> list[str]:
    report = DeadCodeAnalyzer(graph, git_meta_map={}).analyze(
        {"detect_unreachable_files": False, "detect_zombie_packages": False}
    )
    return [f.symbol_name for f in report.findings if f.kind == DeadCodeKind.UNUSED_EXPORT]


def _django_tag_graph(decorator: str) -> nx.DiGraph:
    return _build_graph(
        nodes={
            "app/templatetags/admin_list.py": {
                "is_entry_point": False,
                "is_test": False,
                "is_api_contract": False,
                "symbol_count": 1,
                "symbols": [
                    {
                        "name": "result_list_tag",
                        "kind": "function",
                        "visibility": "public",
                        "decorators": [decorator],
                        "start_line": 1,
                        "end_line": 10,
                        "complexity_estimate": 1,
                    },
                ],
            },
        },
    )


def test_django_template_tag_is_not_flagged():
    """``{% result_list cl %}`` is the only caller and it is not Python."""
    for decorator in (
        '@register.tag(name="result_list")',
        "@register.simple_tag",
        "@register.inclusion_tag('admin/list.html')",
        "@register.filter",
    ):
        assert "result_list_tag" not in _unused_export_names(_django_tag_graph(decorator))


def test_an_undecorated_sibling_is_still_flagged():
    """The rescue is the decorator, not the directory."""
    graph = _django_tag_graph("@staticmethod")
    assert "result_list_tag" in _unused_export_names(graph)


def test_suppresswarnings_unused_is_read_as_an_author_statement():
    """``@SuppressWarnings("unused")`` says outright that nothing calls this."""
    graph = _build_graph(
        nodes={
            "src/Provider.java": {
                "language": "java",
                "is_entry_point": False,
                "is_test": False,
                "is_api_contract": False,
                "symbol_count": 1,
                "symbols": [
                    {
                        "name": "activate",
                        "kind": "function",
                        "visibility": "public",
                        "decorators": ['@SuppressWarnings("unused")'],
                        "start_line": 1,
                        "end_line": 5,
                        "complexity_estimate": 1,
                        "language": "java",
                    },
                ],
            },
        },
    )
    assert "activate" not in _unused_export_names(graph)


def test_a_bare_suppresswarnings_still_flags():
    """The argument is the signal; the annotation alone is worn by everything."""
    graph = _build_graph(
        nodes={
            "src/Provider.java": {
                "language": "java",
                "is_entry_point": False,
                "is_test": False,
                "is_api_contract": False,
                "symbol_count": 1,
                "symbols": [
                    {
                        "name": "activate",
                        "kind": "function",
                        "visibility": "public",
                        "decorators": ['@SuppressWarnings("rawtypes")'],
                        "start_line": 1,
                        "end_line": 5,
                        "complexity_estimate": 1,
                        "language": "java",
                    },
                ],
            },
        },
    )
    assert "activate" in _unused_export_names(graph)


@pytest.mark.parametrize(
    "decorator",
    ['@Suppress("unused")', '@Suppress("UNUSED")', '@Suppress("unused", "DEPRECATION")'],
)
def test_kotlin_suppress_unused_is_read_as_an_author_statement(decorator: str):
    """Kotlin's spelling of ``@SuppressWarnings("unused")``, in either case."""
    assert _declared_deliberately_unused([decorator])


@pytest.mark.parametrize(
    "decorator",
    [
        '@Suppress("UNUSED_PARAMETER")',
        '@Suppress("UNUSED_VARIABLE")',
        '@Suppress("unused_expression")',
        '@Suppress("DEPRECATION")',
        "@Suppress",
    ],
)
def test_kotlin_suppress_of_another_warning_is_not_deliberate(decorator: str):
    """``UNUSED_PARAMETER`` silences a warning inside the body, not about the symbol."""
    assert not _declared_deliberately_unused([decorator])


_KOTLIN_SUPPRESS_FILES = {
    "src/main/kotlin/app/AppInfo.kt": (
        'package app\n\n@Suppress("UNUSED")\nobject AppInfo { fun getVersionCode(): Int = 1 }\n'
    ),
    "src/main/kotlin/app/Extensions.kt": (
        "package app\n\n"
        '@Suppress("unused")\n'
        "fun String.selectText(): String = trim()\n\n"
        "fun String.reallyUnused(): String = this\n"
    ),
    "src/main/kotlin/app/Main.kt": 'package app\n\nfun main() { println("hi") }\n',
}


def test_kotlin_suppress_unused_rescues_only_the_annotated_declarations(tmp_path: Path):
    """``selectText`` is the grammar's shape that detaches a lone annotation."""
    source_map = {rel: text.encode() for rel, text in _KOTLIN_SUPPRESS_FILES.items()}
    for rel, source in source_map.items():
        path = tmp_path / rel
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_bytes(source)
    parser = ASTParser()
    builder = GraphBuilder(repo_path=tmp_path)
    for fi in FileTraverser(tmp_path).traverse():
        builder.add_file(parser.parse_file(fi, source_map[fi.path]))
    builder.set_source_map(source_map)
    graph = builder.build()
    report = DeadCodeAnalyzer(
        graph, git_meta_map={}, source_map=source_map, repo_root=tmp_path
    ).analyze({"detect_unreachable_files": False, "detect_zombie_packages": False})
    unused = {f.symbol_name for f in report.findings if f.kind == DeadCodeKind.UNUSED_EXPORT}
    assert "reallyUnused" in unused
    assert unused.isdisjoint({"AppInfo", "selectText"})


def _holder_graph(language: str, wire_call: bool) -> nx.DiGraph:
    graph = _build_graph(
        nodes={
            "src/GuardExtensions.cs": {
                "language": language,
                "is_entry_point": False,
                "is_test": False,
                "is_api_contract": False,
                "symbol_count": 1,
                "symbols": [
                    {
                        "name": "BasketGuards",
                        "kind": "class",
                        "visibility": "public",
                        "decorators": [],
                        "start_line": 1,
                        "end_line": 20,
                        "complexity_estimate": 2,
                        "language": language,
                    },
                ],
            },
            "src/Checkout.cs": {
                "language": language,
                "is_entry_point": True,
                "is_test": False,
                "is_api_contract": False,
                "symbol_count": 1,
                "symbols": [
                    {
                        "name": "Checkout",
                        "kind": "function",
                        "visibility": "public",
                        "decorators": [],
                        "start_line": 1,
                        "end_line": 9,
                        "complexity_estimate": 1,
                        "language": language,
                    },
                ],
            },
        },
    )
    holder = "src/GuardExtensions.cs::BasketGuards"
    member = "src/GuardExtensions.cs::BasketGuards::EmptyBasketOnCheckout"
    graph.add_node(member, node_type="symbol", file_path="src/GuardExtensions.cs", language=language)
    graph.add_edge(holder, member, edge_type="has_method")
    if wire_call:
        graph.add_edge("src/Checkout.cs::Checkout", member, edge_type="calls")
    return graph


def test_csharp_holder_class_is_rescued_by_its_used_member():
    """A call site writes the extension method's name, never the holder's."""
    assert "BasketGuards" not in _unused_export_names(_holder_graph("csharp", wire_call=True))


def test_a_holder_whose_member_is_also_unused_is_still_flagged():
    """The rescue is a used member, not the presence of members."""
    assert "BasketGuards" in _unused_export_names(_holder_graph("csharp", wire_call=False))


def test_the_container_rescue_is_language_gated():
    """A static holder class is C#'s idiom; ungating it is its own change."""
    assert "BasketGuards" in _unused_export_names(_holder_graph("java", wire_call=True))


def test_a_container_cannot_rescue_itself_from_the_inside():
    """One of its own methods calling another is not a use of the container.

    Without this, any class holding two methods where one calls the other is
    unreportable, because a class's own methods are predecessors of each other.
    """
    graph = _holder_graph("csharp", wire_call=False)
    holder = "src/GuardExtensions.cs::BasketGuards"
    sibling = "src/GuardExtensions.cs::BasketGuards::Round"
    member = "src/GuardExtensions.cs::BasketGuards::EmptyBasketOnCheckout"
    graph.add_node(sibling, node_type="symbol", file_path="src/GuardExtensions.cs", language="csharp")
    graph.add_edge(holder, sibling, edge_type="has_method")
    graph.add_edge(sibling, member, edge_type="calls")

    assert "BasketGuards" in _unused_export_names(graph)


def test_an_annotation_beside_suppresswarnings_does_not_leak_its_argument():
    """``@Named("unused-legacy-bean")`` is not the author declaring anything."""
    graph = _build_graph(
        nodes={
            "src/Provider.java": {
                "language": "java",
                "is_entry_point": False,
                "is_test": False,
                "is_api_contract": False,
                "symbol_count": 1,
                "symbols": [
                    {
                        "name": "activate",
                        "kind": "function",
                        "visibility": "public",
                        "decorators": ['@SuppressWarnings("rawtypes")\n@Named("unused-legacy-bean")'],
                        "start_line": 1,
                        "end_line": 5,
                        "complexity_estimate": 1,
                        "language": "java",
                    },
                ],
            },
        },
    )
    assert "activate" in _unused_export_names(graph)


# ---------------------------------------------------------------------------
# Any ``recv.attr`` decorator is a registration unless it only wraps.
# ---------------------------------------------------------------------------


def _decorated(decorator: str, visibility: str) -> nx.DiGraph:
    return _build_graph(
        nodes={
            "pkg/handlers.py": {
                "symbols": [
                    {
                        "name": "handle_thing",
                        "kind": "function",
                        "visibility": visibility,
                        "decorators": [decorator],
                        "start_line": 1,
                        "end_line": 4,
                    },
                ],
            },
        },
    )


def _reported(decorator: str) -> tuple[bool, bool]:
    """(reported as unused export, reported as unused internal)."""
    export = "handle_thing" in _unused_export_names(_decorated(decorator, "public"))
    report = DeadCodeAnalyzer(_decorated(decorator, "private"), git_meta_map={}).analyze(
        {"detect_unreachable_files": False, "min_confidence": 0.0}
    )
    internal = any(f.kind == DeadCodeKind.UNUSED_INTERNAL for f in report.findings)
    return export, internal


def test_receiver_decorators_are_registrations_in_both_passes():
    for decorator in ("@nox.session", "@sub.handle('created')", "@mcp.tool()", "@bot.on.message"):
        assert _reported(decorator) == (False, False), decorator


def test_pure_wrapper_decorators_are_not_registrations():
    for decorator in (
        "@functools.wraps(fn)",
        "@functools.lru_cache(maxsize=None)",
        "@typing.override",
        "@abc.abstractmethod",
        "@typing.no_type_check",
        "@mock.create_autospec(spec)",
        "@unittest.mock.create_autospec(spec)",
        "@value.setter",
    ):
        assert _reported(decorator) == (True, True), decorator


def test_a_deprecation_marker_is_not_a_registration():
    # An exported deprecated symbol is kept for its own reason, so the internal
    # pass is where a wrapper-shaped ``deprecated`` shows it registers nothing.
    assert _reported("@warnings.deprecated('use other')")[1] is True


def test_a_qualified_annotation_type_is_not_a_receiver():
    # ``@java.lang.Deprecated``-style: a capitalised last segment names a type.
    assert _reported("@org.example.Marker") == (True, True)