Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
"""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)