dead-cst 0.1.0__py3-none-any.whl

dead_cst/__init__.py

@@ -0,0 +1,99 @@
+"""Dead code analysis for Python using LibCST.
+
+`dead-cst` builds a symbol-level reachability graph of a Python codebase and
+reports (or removes) anything not reachable from a configurable set of
+entrypoints.
+
+The public API has three layers:
+
+* :func:`build_symbol_graph` parses every ``.py`` file under each base in a
+  ``{base: [dep_paths]}`` map and returns a :class:`networkx.DiGraph` of
+  :class:`SymbolNode` instances. Edges encode "keeps alive" relationships.
+* Edge plugins (:class:`MainBlockPlugin`, :class:`ProjectScriptsPlugin`,
+  :class:`ExplicitEntrypointPlugin`, :class:`ModuleDundersPlugin`,
+  :class:`PytestPlugin`, :class:`UnittestPlugin`, :class:`FastAPIPlugin`,
+  :class:`FlaskPlugin`, :class:`TyperPlugin`, :class:`ClickPlugin`)
+  extend the graph with edges that pure CST analysis can't infer --
+  entry points, framework conventions, dynamic dispatch. Custom
+  plugins implement the :class:`EdgePlugin` protocol.
+* Path resolvers (:class:`VenvResolver`, :class:`PyprojectResolver`,
+  :class:`UvWorkspaceResolver`) discover the ``{base: [dep_paths]}`` map
+  itself from a project root, so callers don't have to hand-build it.
+
+After plugins run, :func:`find_reachable` walks successors from every node
+tagged with ``entrypoint=True`` and returns the live set;
+:func:`remove_code` rewrites source files in place to delete the rest via
+a LibCST codemod that preserves surrounding formatting.
+
+See the README for the CLI, the entrypoint and search-path specs, and the
+limitations of static analysis.
+"""
+
+from ._analyze import build_symbol_graph, count_nodes, find_reachable, order_paths
+from ._codemod import remove_code
+from ._plugins import (
+    AddEdge,
+    AddNode,
+    BUILTIN_PLUGINS,
+    ClickPlugin,
+    EdgePlugin,
+    ExplicitEntrypointPlugin,
+    FastAPIPlugin,
+    FlaskPlugin,
+    GraphOp,
+    InitSubclassPlugin,
+    MainBlockPlugin,
+    ModuleDundersPlugin,
+    PluginContext,
+    ProjectScriptsPlugin,
+    PytestPlugin,
+    RemoveEdge,
+    TyperPlugin,
+    UnittestPlugin,
+    load_plugin,
+)
+from ._resolvers import (
+    BUILTIN_RESOLVERS,
+    PathResolver,
+    PyprojectResolver,
+    UvWorkspaceResolver,
+    VenvResolver,
+    load_resolver,
+    merge_paths,
+)
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    "AddEdge",
+    "AddNode",
+    "BUILTIN_PLUGINS",
+    "BUILTIN_RESOLVERS",
+    "ClickPlugin",
+    "EdgePlugin",
+    "ExplicitEntrypointPlugin",
+    "FastAPIPlugin",
+    "FlaskPlugin",
+    "GraphOp",
+    "InitSubclassPlugin",
+    "MainBlockPlugin",
+    "ModuleDundersPlugin",
+    "PathResolver",
+    "PluginContext",
+    "ProjectScriptsPlugin",
+    "PyprojectResolver",
+    "PytestPlugin",
+    "RemoveEdge",
+    "TyperPlugin",
+    "UnittestPlugin",
+    "UvWorkspaceResolver",
+    "VenvResolver",
+    "build_symbol_graph",
+    "count_nodes",
+    "find_reachable",
+    "load_plugin",
+    "load_resolver",
+    "merge_paths",
+    "order_paths",
+    "remove_code",
+]

dead_cst/_analyze.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Sequence
+
+import libcst as cst
+import networkx as nx
+from libcst.metadata import FullRepoManager
+
+from ._fqn import FixedFullyQualifiedNameProvider
+from ._plugins import (
+    EdgePlugin,
+    PluginContext,
+    apply_ops,
+)
+from ._resolve import resolve_edges, safe_resolve_module, temp_sys_path
+from ._resolvers import PathMap, exported_roots
+from ._symbols import SymbolNode, SymbolTrie
+from ._visitor import SymbolVisitor
+
+logger = logging.getLogger(__name__)
+
+
+def order_paths(paths: PathMap) -> list[Path]:
+    """Topologically sort base paths so dependencies are processed first.
+
+    ``paths`` maps each base directory to the list of other base directories
+    it imports from (added to ``sys.path`` while it is processed). The
+    returned order ensures that when a base is processed every base it
+    depends on has already contributed its symbols to the lookup tables, so
+    cross-package import resolution sees them.
+    """
+    path_order = nx.DiGraph()
+    for base, search_paths in paths.items():
+        path_order.add_node(base)
+        for sp in search_paths:
+            path_order.add_edge(sp, base)
+    return list(nx.topological_sort(path_order))
+
+
+def build_symbol_graph(
+    paths: PathMap,
+    *,
+    plugins: Sequence[EdgePlugin] = (),
+    project_root: Path | None = None,
+) -> nx.DiGraph:
+    """Build a directed reachability graph of every top-level symbol under ``paths``.
+
+    Each ``.py`` file under each base in ``paths`` is parsed with LibCST;
+    modules, classes, functions, top-level variables, and module-level imports
+    become :class:`SymbolNode` graph nodes. Edges encode "keeps alive"
+    relationships:
+
+    * a reference points at its referent,
+    * a declaration points at its containing module,
+    * a submodule points at its parent package, and
+    * synthetic ``unreachable`` nodes own edges into symbols referenced from
+      statically-dead suites (``if False:``, ``raise``-only branches, ...) so
+      those references don't keep the targets alive.
+
+    Third-party imports are surfaced as synthetic ``[external dist] <name>``
+    / ``[external file] <name>`` nodes so callers can audit the
+    project's dependency surface (see the ``dependencies`` CLI command).
+
+    Plugins run once per base in topological order, after that base's import
+    edges have been resolved. Each plugin invocation gets a per-base
+    :class:`PluginContext` whose parsed-module cache is primed with the
+    modules the analyzer just walked, so plugins never re-read or re-parse.
+
+    Parameters
+    ----------
+    paths:
+        Mapping from base directory to its first-party search-path
+        dependencies. For a single-package project, pass ``{root: []}``. For
+        a monorepo, list the dependencies so they're added to ``sys.path``
+        and resolved as first-party. ``order_paths`` orders the bases.
+    plugins:
+        Sequence of :class:`EdgePlugin` instances. Plugins emit
+        :class:`AddNode`, :class:`AddEdge`, and :class:`RemoveEdge` ops;
+        ``AddNode(..., entrypoint=True)`` seeds :func:`find_reachable`.
+    project_root:
+        Project root used by plugins for path-relative matching. If
+        omitted, inferred as the shortest path in ``paths``.
+
+    Returns
+    -------
+    networkx.DiGraph
+        Nodes are :class:`SymbolNode` instances; entrypoint seeds carry
+        ``graph.nodes[node]["entrypoint"] = True``.
+    """
+    symbol_graph = nx.DiGraph()
+    base_tries: dict[Path, SymbolTrie] = {}
+    export_tries: dict[Path, SymbolTrie] = {}
+    root = project_root or _infer_project_root(paths) if paths else Path.cwd()
+    for base in order_paths(paths):
+        logger.debug("Processing base path: %s", base)
+        search_paths = [base] + paths.get(base, [])
+        safe_resolve_module.cache_clear()
+        with temp_sys_path(search_paths):
+            base_tries[base] = current_trie = SymbolTrie()
+            export_trie = SymbolTrie()
+            export_roots = exported_roots(base)
+            import_edges = set()
+            files = list(sorted(base.rglob("*.py")))
+            mgr = FullRepoManager(
+                str(base), [str(f) for f in files], {FixedFullyQualifiedNameProvider}
+            )
+            # Stash the modules the visitor pass parses so plugins can reuse
+            # them via ``ctx.parse(path)`` without re-reading or re-parsing.
+            base_modules: dict[Path, cst.Module] | None = {} if plugins else None
+            for file in files:
+                wrapper = mgr.get_metadata_wrapper_for_path(str(file))
+                if base_modules is not None:
+                    base_modules[file] = wrapper.module
+                visitor = SymbolVisitor(file, search_paths)
+                wrapper.visit(visitor)
+                # A file's decls go into ``export_trie`` only when the file
+                # lives under one of ``base``'s exported dirs (or when the
+                # base has no export restriction). This is what hides
+                # ``tests/`` from dependents in the typical workspace
+                # layout: the member analyzes its own ``tests/`` (decls
+                # land in ``current_trie`` and the graph), but consumers'
+                # lookup tries never see them.
+                file_exported = export_roots is None or _under_any(file, export_roots)
+                curr = [visitor.trie]
+                while curr:
+                    node = curr.pop()
+                    if node.module is not None:
+                        symbol_graph.add_node(node.module)
+                        current_trie.add_declaration(node.module)
+                        if file_exported:
+                            export_trie.add_declaration(node.module)
+                    for decls in node.declarations.values():
+                        for decl in decls:
+                            symbol_graph.add_node(decl)
+                            symbol_graph.add_edge(decl, node.module)
+                            current_trie.add_declaration(decl)
+                            if file_exported:
+                                export_trie.add_declaration(decl)
+                    # Shadowed decls still belong to this module: emit them
+                    # so the graph stays well-formed (every decl has a
+                    # parent-module edge). They aren't re-added to
+                    # ``current_trie`` -- only live-at-exit decls should
+                    # win project-wide lookups.
+                    for decl in node.shadowed:
+                        symbol_graph.add_node(decl)
+                        symbol_graph.add_edge(decl, node.module)
+                    curr.extend(node.children.values())
+
+                for src, dst in visitor.internal_edges:
+                    symbol_graph.add_edge(src, dst)
+
+                # Synthetic ``unreachable`` nodes for statically-dead suites.
+                # They live in the graph as orphan sources -- nothing points
+                # at them, so reachability never visits them, but the edges
+                # they own surface which symbols are referenced from inside
+                # dead branches. Existing top-level decl edges are unchanged.
+                for unreachable in visitor.unreachable_nodes:
+                    symbol_graph.add_node(unreachable)
+                for src, dst in visitor.unreachable_internal_edges:
+                    symbol_graph.add_edge(src, dst)
+
+                import_edges |= visitor.import_edges | visitor.unreachable_import_edges
+
+            current_trie.add_module_hierarchy_edges(symbol_graph)
+            export_tries[base] = export_trie
+
+            # Per-consumer lookup trie: this base's full trie (everything
+            # in scope when resolving its own imports) plus each dep's
+            # *exported* trie (what the dep ships to consumers). Deps are
+            # processed earlier by topological order, so their export
+            # tries already exist.
+            symbol_lookup = SymbolTrie()
+            symbol_lookup.merge(current_trie)
+            for dep in paths.get(base, []):
+                symbol_lookup.merge(export_tries.get(dep, base_tries[dep]))
+
+            for src, dst in resolve_edges(import_edges, symbol_lookup, base):
+                symbol_graph.add_edge(src, dst)
+
+            # Plugin pass for this base, with the symbol lookup that was
+            # valid at this base's resolution time and the parsed modules
+            # we just walked. The context (and ``base_modules``) goes out
+            # of scope once we move to the next base, so the parsed CSTs
+            # for this base can be GC'd.
+            if plugins:
+                ctx = PluginContext(
+                    graph=symbol_graph,
+                    symbol_lookup=symbol_lookup,
+                    base=base,
+                    project_root=root,
+                )
+                if base_modules is not None:
+                    for path, module in base_modules.items():
+                        ctx.prime_module(path, module)
+                for plugin in plugins:
+                    if not isinstance(plugin, EdgePlugin):
+                        raise TypeError(f"Plugin {plugin!r} does not satisfy EdgePlugin protocol")
+                    # Materialize before applying so plugins can iterate
+                    # ctx.graph.nodes without tripping "dictionary changed
+                    # size during iteration".
+                    ops = list(plugin.contribute(ctx))
+                    apply_ops(symbol_graph, ops)
+
+    return symbol_graph
+
+
+def _under_any(file: Path, roots: list[Path]) -> bool:
+    """True iff ``file`` is equal to or nested under any of ``roots``."""
+    f = file.resolve()
+    for r in roots:
+        if f == r or f.is_relative_to(r):
+            return True
+    return False
+
+
+def _infer_project_root(paths: PathMap) -> Path:
+    bases = list(paths)
+    if not bases:
+        return Path.cwd()
+    return min(bases, key=lambda p: len(p.parts))
+
+
+def find_reachable(graph: nx.DiGraph) -> set[SymbolNode]:
+    """BFS forward from every node tagged as an entrypoint by a plugin.
+
+    Plugins mark seeds by setting ``graph.nodes[node]["entrypoint"] = True``
+    (see :func:`dead_cst._plugins.apply_ops`). There is no longer any
+    built-in matching against file paths or FQNs -- that lives in
+    :class:`ExplicitEntrypointPlugin`.
+    """
+    visited: set[SymbolNode] = set()
+    stack = [n for n, attrs in graph.nodes(data=True) if attrs.get("entrypoint")]
+    while stack:
+        node = stack.pop()
+        if node in visited:
+            continue
+        visited.add(node)
+        stack.extend(graph.successors(node))
+    return visited
+
+
+def count_nodes(graph: nx.DiGraph, prefix: Path | None) -> dict[str, int]:
+    """Count nodes in ``graph`` by ``SymbolNode.type``, optionally restricted by path.
+
+    If ``prefix`` is given, only nodes whose ``path`` is under ``prefix`` are
+    counted -- useful for per-base summaries when several packages are
+    analysed together. Includes the synthetic ``"synthetic"`` type contributed
+    by plugins and third-party-dep markers; the CLI suppresses that key when
+    rendering summaries.
+    """
+    counts = {}
+    for node in graph.nodes:
+        if prefix and not node.path.is_relative_to(prefix):
+            continue
+        counts[node.type] = counts.get(node.type, 0) + 1
+    return counts

dead_cst/_branches.py

@@ -0,0 +1,203 @@
+"""Static evaluator for conditional truthiness.
+
+Determines, when possible, whether the truthiness of an expression is
+statically known. Used to identify dead branches of ``if`` / ``while``
+statements so callers can prune references that live inside them.
+
+Only handles a small whitelist of literal forms: the ``True`` /
+``False`` / ``None`` keywords, integer / string literals,
+empty-vs-non-empty collection literals, and ``not`` / ``and`` / ``or``
+over those. Anything involving a name lookup (other than the three
+keywords), attribute access, function call, comparison, or other
+dynamic operation returns ``None`` (unknown). Returning ``None`` is
+always the safe default: callers must treat the branch as live.
+
+This module also owns the convention for synthetic graph nodes that
+represent dead suites. The nodes have ``type="synthetic"`` (the
+existing escape hatch in :mod:`dead_cst._symbols`) and a fqname
+prefixed with :data:`UNREACHABLE_PREFIX` (``<unreachable>:``).
+``is_unreachable_node`` is the single source of truth for that
+convention; consumers should never check the prefix string themselves.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Sequence
+
+import libcst as cst
+from libcst.metadata import CodeRange
+
+from ._symbols import SymbolNode
+
+
+_KEYWORDS: dict[str, bool] = {
+    "True": True,
+    "False": False,
+    "None": False,
+}
+
+UNREACHABLE_PREFIX = "<unreachable>:"
+
+
+def evaluate_truthiness(node: cst.BaseExpression) -> bool | None:
+    """Best-effort static truthiness for ``node``.
+
+    Returns ``True`` / ``False`` if the value's truthiness is statically
+    determinable, ``None`` otherwise. Never raises.
+    """
+    if isinstance(node, cst.Name):
+        return _KEYWORDS.get(node.value)
+
+    if isinstance(node, cst.Integer):
+        try:
+            return int(node.value, 0) != 0
+        except ValueError:
+            return None
+
+    if isinstance(node, (cst.SimpleString, cst.ConcatenatedString)):
+        try:
+            value = node.evaluated_value
+        except Exception:
+            return None
+        if value is None:
+            return None
+        return bool(value)
+
+    if isinstance(node, (cst.Tuple, cst.List, cst.Set)):
+        for elt in node.elements:
+            if isinstance(elt, cst.StarredElement):
+                return None
+        return len(node.elements) > 0
+
+    if isinstance(node, cst.Dict):
+        for elt in node.elements:
+            if isinstance(elt, cst.StarredDictElement):
+                return None
+        return len(node.elements) > 0
+
+    if isinstance(node, cst.UnaryOperation) and isinstance(node.operator, cst.Not):
+        inner = evaluate_truthiness(node.expression)
+        return None if inner is None else not inner
+
+    if isinstance(node, cst.BooleanOperation):
+        left = evaluate_truthiness(node.left)
+        if isinstance(node.operator, cst.And):
+            if left is False:
+                return False
+            right = evaluate_truthiness(node.right)
+            if right is False:
+                return False
+            if left is True and right is True:
+                return True
+            return None
+        if isinstance(node.operator, cst.Or):
+            if left is True:
+                return True
+            right = evaluate_truthiness(node.right)
+            if right is True:
+                return True
+            if left is False and right is False:
+                return False
+            return None
+
+    return None
+
+
+def unreachable_suites(stmt: cst.BaseStatement) -> list[cst.BaseSuite]:
+    """Return every dead suite inside ``stmt``.
+
+    Supports ``cst.If`` (including ``elif`` / ``else`` chains) and
+    ``cst.While``. Returns ``[]`` for any other statement type or when
+    no branch can be shown to be unreachable.
+
+    Returns the suite nodes themselves so callers that need source
+    positions (e.g. the visitor) can read them off the node.
+    """
+    if isinstance(stmt, cst.If):
+        return _unreachable_in_if(stmt, branch_taken=False)
+    if isinstance(stmt, cst.While):
+        truth = evaluate_truthiness(stmt.test)
+        if truth is False:
+            return [stmt.body]
+        # ``while True:`` exits only via break / return / exception, so
+        # the ``else`` clause (which fires on normal exit) never runs.
+        if truth is True and stmt.orelse is not None:
+            return [stmt.orelse.body]
+        return []
+    return []
+
+
+def unreachable_bodies(stmt: cst.BaseStatement) -> list[Sequence[cst.CSTNode]]:
+    """Return the ``.body`` of every dead suite inside ``stmt``.
+
+    Thin wrapper over :func:`unreachable_suites` for callers that only
+    need the statement list, not the enclosing suite. Each entry is
+    typed as ``Sequence[cst.CSTNode]`` because libcst's
+    ``BaseSuite.body`` may be ``Sequence[BaseStatement]`` (an indented
+    block) or ``Sequence[BaseSmallStatement]`` (a one-line suite like
+    ``if False: x = 1``).
+    """
+    return [suite.body for suite in unreachable_suites(stmt)]
+
+
+def _unreachable_in_if(node: cst.If, branch_taken: bool) -> list[cst.BaseSuite]:
+    """Walk an ``if`` / ``elif`` / ``else`` chain collecting dead suites.
+
+    ``branch_taken`` is ``True`` when an earlier branch in the chain is
+    known to fire; everything from this point on is then unreachable.
+    """
+    dead: list[cst.BaseSuite] = []
+    truth = None if branch_taken else evaluate_truthiness(node.test)
+
+    if branch_taken or truth is False:
+        dead.append(node.body)
+
+    next_taken = branch_taken or truth is True
+
+    orelse = node.orelse
+    if orelse is None:
+        return dead
+    if isinstance(orelse, cst.Else):
+        if next_taken:
+            dead.append(orelse.body)
+        return dead
+    dead.extend(_unreachable_in_if(orelse, next_taken))
+    return dead
+
+
+def make_unreachable_fqname(module_fqname: str, position: CodeRange) -> str:
+    """Build the fqname for the synthetic node representing a dead suite.
+
+    The format is intentionally fixed: callers should use
+    :func:`is_unreachable_node` to identify these nodes rather than
+    string-matching on their fqnames.
+    """
+    return f"{UNREACHABLE_PREFIX}{module_fqname}:{position.start.line}:{position.start.column}"
+
+
+def make_unreachable_node(module_fqname: str, path: Path, position: CodeRange) -> SymbolNode:
+    """Build the synthetic ``SymbolNode`` for a dead suite.
+
+    Reuses ``type="synthetic"`` -- the existing escape hatch for graph
+    nodes that don't correspond to a top-level declaration -- and
+    distinguishes itself by carrying a real source ``position`` (rather
+    than the ``SYNTHETIC_POSITION`` sentinel used by entrypoint plugins)
+    plus the :data:`UNREACHABLE_PREFIX` fqname prefix.
+    """
+    return SymbolNode(
+        fqname=make_unreachable_fqname(module_fqname, position),
+        type="synthetic",
+        path=path,
+        position=position,
+    )
+
+
+def is_unreachable_node(sym: SymbolNode) -> bool:
+    """Predicate: ``True`` iff ``sym`` is a synthetic dead-suite node.
+
+    The only supported way to identify these nodes. Callers should not
+    string-match on the fqname directly; the prefix is an implementation
+    detail of this module.
+    """
+    return sym.type == "synthetic" and sym.fqname.startswith(UNREACHABLE_PREFIX)

dead_cst/_codemod.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import libcst as cst
+import networkx as nx
+from libcst.codemod import CodemodContext
+from libcst.codemod.visitors import RemoveImportsVisitor
+from libcst.metadata import CodeRange, FullRepoManager, PositionProvider, QualifiedNameSource
+
+from ._fqn import FixedFullyQualifiedNameProvider
+from ._symbols import SymbolNode
+
+
+class RemoveDeadSymbols(cst.CSTTransformer):
+    METADATA_DEPENDENCIES = (FixedFullyQualifiedNameProvider, PositionProvider)
+
+    def __init__(self, dead_decls: set[tuple[str, CodeRange]]):
+        # ``(fqname, position)`` pairs. The position disambiguates same-name
+        # decls so a shadowed dead binding does not drag its live sibling
+        # out with it (and vice versa).
+        self.dead_decls = dead_decls
+
+    def _should_remove(self, node: cst.CSTNode) -> bool:
+        fqnames = self.get_metadata(FixedFullyQualifiedNameProvider, node, default=[])
+        pos = self.get_metadata(PositionProvider, node, default=None)
+        return any(
+            (qn.name, pos) in self.dead_decls
+            for qn in fqnames
+            if qn.source == QualifiedNameSource.LOCAL
+        )
+
+    def leave_FunctionDef(self, original_node: cst.FunctionDef, updated_node: cst.FunctionDef):
+        if self._should_remove(original_node):
+            return cst.RemoveFromParent()
+        return updated_node
+
+    def leave_ClassDef(self, original_node: cst.ClassDef, updated_node: cst.ClassDef):
+        if self._should_remove(original_node):
+            return cst.RemoveFromParent()
+        return updated_node
+
+    def leave_Assign(self, original_node: cst.Assign, updated_node: cst.Assign):
+        new_targets = []
+        for orig_target, new_target in zip(original_node.targets, updated_node.targets):
+            if not self._should_remove(orig_target.target):
+                new_targets.append(new_target)
+
+        if not new_targets:
+            return cst.RemoveFromParent()
+
+        return updated_node.with_changes(targets=new_targets)
+
+    def leave_AnnAssign(self, original_node: cst.AnnAssign, updated_node: cst.AnnAssign):
+        if self._should_remove(original_node.target):
+            return cst.RemoveFromParent()
+        return updated_node
+
+
+def _import_remove_args(node: SymbolNode) -> tuple[str, str | None, str | None]:
+    """Convert an ``"import"``-typed node to ``RemoveImportsVisitor`` args.
+
+    Returns ``(module, obj, asname)`` matching the signature of
+    :meth:`RemoveImportsVisitor.remove_unused_import`. ``asname`` is set
+    only when the local bound name differs from the natural binding
+    (``obj`` for ``from X import obj``, the leftmost segment of
+    ``module`` for bare ``import X``).
+    """
+    assert node.imports is not None, f"Import node missing imports metadata: {node.fqname}"
+    module = str(node.imports.module)
+    obj = node.imports.decl
+    bound = node.fqname.rsplit(".", 1)[-1]
+    natural = obj if obj is not None else module.split(".", 1)[0]
+    asname = bound if bound != natural else None
+    return module, obj, asname
+
+
+def remove_code(G: nx.Graph, base: Path) -> None:
+    """Delete every symbol in ``G`` from the source files under ``base``.
+
+    Modules are removed by unlinking the file. Functions, classes, and
+    top-level variables are dropped by a LibCST transformer matching on
+    ``(fqname, position)`` so a shadowed dead binding does not drag its
+    live sibling out with it. Surviving statements, comments, and
+    formatting around the deletions are preserved.
+
+    Imports are handled in a second pass via libcst's
+    :class:`RemoveImportsVisitor`, which walks scopes itself and skips
+    anything still referenced (defensive -- the graph already classifies
+    these as dead, but the scope check is cheap insurance).
+
+    ``G`` is typically the unreachable subgraph of the graph from
+    :func:`build_symbol_graph`; only the nodes are inspected, edges are
+    ignored. Symbols whose path is not under ``base`` are skipped, so call
+    once per base when analysing several packages together. The
+    transformation is destructive -- back the files up first, or run on a
+    clean working tree.
+    """
+    by_file: dict[Path, list[SymbolNode]] = {}
+    for node in G.nodes:
+        if not node.path.is_relative_to(base):
+            continue
+        if not node.path.exists():
+            continue
+        match node.type:
+            case "function" | "class" | "variable" | "import":
+                by_file.setdefault(node.path, []).append(node)
+            case "module":
+                node.path.unlink()
+
+    mgr = FullRepoManager(str(base), [str(p) for p in by_file], {FixedFullyQualifiedNameProvider})
+    for path, nodes in sorted(by_file.items(), key=lambda x: x):
+        if not path.exists():
+            continue
+
+        # Pass 1: drop dead defs / classes / variables. Imports they
+        # used to reference become eligible for removal in pass 2.
+        wrapper = mgr.get_metadata_wrapper_for_path(str(path))
+        dead_decls = {(n.fqname, n.position) for n in nodes if n.type != "import"}
+        result = wrapper.visit(RemoveDeadSymbols(dead_decls))
+
+        # Pass 2: hand the dead-import set to libcst's stock import
+        # remover. It walks scopes itself, so it'll skip anything still
+        # referenced after pass 1 (defensive -- if the graph said
+        # something is dead, no live user remains).
+        dead_imports = [n for n in nodes if n.type == "import"]
+        if dead_imports:
+            ctx = CodemodContext()
+            for imp in dead_imports:
+                module, obj, asname = _import_remove_args(imp)
+                RemoveImportsVisitor.remove_unused_import(ctx, module, obj, asname)
+            result = RemoveImportsVisitor(ctx).transform_module(result)
+
+        with path.open("w") as f:
+            f.write(result.code)