feat: codegraphcontext analyze dead-code has no confidence scoring — it reports all unreferenced symbols equally, producing high false-positive rates on Python dunder methods, public API entry points, and test fixtures #1332

🐛 Problem Statement

The CLI command codegraphcontext analyze dead-code is documented as:

"Find dead or unused code"

Dead code detection works by querying the graph for nodes (functions,
classes, methods) that have zero incoming CALLS or IMPORTS edges.
However, not all zero-in-degree nodes are dead code. There are three
systematic false positive categories that the current implementation
cannot distinguish from genuine dead code:

Category 1 — Python Dunder/Magic Methods

__init__, __str__, __repr__, __eq__, __hash__, __enter__,
__exit__, etc. are never explicitly called in user code — Python's
runtime calls them implicitly. Since CGC builds its graph from explicit
call syntax in Tree-sitter ASTs (e.g., foo.bar()), dunder methods will
have zero incoming CALLS edges even when they are critical and heavily
used.

A user running codegraphcontext analyze dead-code on a well-written
Python project will see dozens of __init__ and __str__ methods
flagged as dead — noise that buries the genuine dead code.

Category 2 — Public API Entry Points

Library code exposes functions that are called by external consumers,
not by the library itself. A function like def connect(host, port)
in a database library has zero callers in the library's own codebase
but is the primary API surface. CGC indexes only the local repository,
so external callers are invisible — these functions are flagged as dead.

Category 3 — Test Fixtures and Pytest Hooks

conftest.py fixtures are called by pytest automatically. setUp,
tearDown, setUpClass, and setUpModule in unittest are invoked
by the test runner. These all have zero explicit callers in the graph
but are entirely necessary.

Current Behavior

$ codegraphcontext analyze dead-code
Dead code found:
  • __init__ (src/auth.py:12)       ← False positive: called implicitly
  • __str__ (src/user.py:45)        ← False positive: called by str()
  • connect (src/database.py:8)     ← False positive: public API
  • setUp (tests/test_auth.py:15)   ← False positive: test runner
  • process_payment (src/billing.py:67) ← REAL dead code ← buried

The real dead code is buried in dozens of false positives.

✅ Proposed Solution

Add confidence scoring to dead code results

# In src/codegraphcontext/analyzers/dead_code.py

from enum import Enum

class DeadCodeConfidence(Enum):
    HIGH = "high"       # Very likely dead — safe to remove
    MEDIUM = "medium"   # Possibly dead — review before removing
    LOW = "low"         # Probably not dead — likely false positive

# Patterns that indicate LOW confidence (likely false positives)
LOW_CONFIDENCE_PATTERNS = {
    # Python magic methods
    "dunder": lambda name: name.startswith("__") and name.endswith("__"),
    # Test framework hooks
    "test_hook": lambda name: name in {
        "setUp", "tearDown", "setUpClass", "tearDownClass",
        "setUpModule", "tearDownModule", "fixture"
    },
    # Common entry points
    "entry_point": lambda name: name in {
        "main", "run", "start", "serve", "execute", "handler",
        "lambda_handler", "on_event"
    },
    # Decorated functions (decorators often add implicit callers)
    # This requires checking for @property, @staticmethod, @classmethod,
    # @app.route, @pytest.fixture etc. in the AST
}

def classify_dead_code(symbol_name: str, file_path: str, has_decorator: bool) -> DeadCodeConfidence:
    if any(check(symbol_name) for check in LOW_CONFIDENCE_PATTERNS.values()):
        return DeadCodeConfidence.LOW
    if "test_" in file_path or file_path.endswith("conftest.py"):
        return DeadCodeConfidence.LOW
    if has_decorator:
        return DeadCodeConfidence.MEDIUM
    return DeadCodeConfidence.HIGH

Update CLI output with confidence levels

$ codegraphcontext analyze dead-code

🔴 HIGH confidence dead code (safe to remove):
  • process_payment (src/billing.py:67) — 0 callers, 0 importers

🟡 MEDIUM confidence (review before removing):
  • _internal_helper (src/utils.py:23) — decorated, no explicit callers

⚪ LOW confidence (likely false positives — shown with --show-all):
  • __init__, __str__, setUp, connect ... (hidden by default)

Summary: 1 high, 1 medium, 47 low confidence (use --show-all to see all)

Add CLI flags

# Show only high-confidence dead code (default — signal, no noise)
codegraphcontext analyze dead-code

# Show all results including low-confidence
codegraphcontext analyze dead-code --show-all

# Show only specific confidence level
codegraphcontext analyze dead-code --confidence high
codegraphcontext analyze dead-code --confidence medium

Files to Modify

📊 Impact

Dead code detection is one of CGC's flagship features ("Find dead or
unused code" is in the README's quick-start commands). A tool that
produces 95% false positives is worse than not having the feature —
users run it once, see noise, and never use it again. Confidence scoring
converts a noisy alarm into a precision tool, which is the difference
between a feature that gets used and one that gets ignored.

Suggested labels: bug, enhancement, intermediate

I would like to work on this. Could you assign it to me?