ghostrefs

Find code kept alive only by tests.

Features

• Finds production symbols whose only known consumers are tests
• Follows transitive dependencies, including test → helper → target
• Uses language server references to build a usage graph
• Explains findings with reference locations and test chains
• Supports custom production entry points and ignore patterns
• Written in Rust, currently supports Python via Pyright

Installation

Currently supports Python projects only, using pyright-langserver from your PATH.

With Python 3.10+ and a published wheel for your platform, install from PyPI:

npm install -g pyright
pip install ghostrefs

Wheels contain the compiled executable, so Rust is not needed to install them. Pyright requires Node.js and npm and is installed separately. If pip builds from a source distribution instead, Rust with Cargo is also required.

Alternatively, install from crates.io with Rust and Cargo:

npm install -g pyright
cargo install ghostrefs

Example

From a checkout of this repository, run against the included sample project:

ghostrefs --root . --source fixtures/python/project --tests fixtures/python/tests

TestOnly …/main.py:6:5 test_only_used_func (Function)
TestOnly …/main.py:14:7 TestOnlyUsedClass (Class)
TestOnly candidates: 2 (6 production symbols analyzed)

For your own project, set --root to the directory matching your Python imports. The --source and --tests paths are relative to that root.

Add --verbose to see why a symbol was flagged, or --graph to inspect the usage graph. Configure ignore patterns, production entry points, and Pyright settings in ghostrefs-lsp.json at the project root.

Findings are candidates for review: dynamic imports, reflection, and external consumers may be invisible to the language server.

Documentation

Start with Getting started, then explore the CLI reference, configuration, and analysis model.

See the development guide to build the searchable HTML documentation locally, and the publishing guide to build and release the PyPI distributions.