Metadata-Version: 2.4
Name: ghostrefs
Version: 0.0.4
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
License-File: LICENSE
Summary: Find code kept alive only by tests
Keywords: dead-code,static-analysis,python,testing,lsp
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/milssky/ghostrefs/releases
Project-URL: Documentation, https://github.com/milssky/ghostrefs/tree/master/docs
Project-URL: Issues, https://github.com/milssky/ghostrefs/issues
Project-URL: Repository, https://github.com/milssky/ghostrefs

<h1 align="center">ghostrefs</h1>

<p align="center">
  <em>Find code kept alive only by tests.</em>
</p>

## Features

- [x] Finds production symbols whose only known consumers are tests
- [x] Follows transitive dependencies, including `test → helper → target`
- [x] Uses language server references to build a usage graph
- [x] Explains findings with reference locations and test chains
- [x] Supports custom production entry points and ignore patterns
- [x] 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:

```bash
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](https://crates.io/crates/ghostrefs)
with Rust and Cargo:

```bash
npm install -g pyright
cargo install ghostrefs
```

## Example

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

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

```text
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](https://github.com/milssky/ghostrefs/blob/master/docs/index.rst),
then explore the [CLI reference](https://github.com/milssky/ghostrefs/blob/master/docs/pages/cli.rst),
[configuration](https://github.com/milssky/ghostrefs/blob/master/docs/pages/configuration.rst),
and [analysis model](https://github.com/milssky/ghostrefs/blob/master/docs/pages/analysis.rst).

See the [development guide](https://github.com/milssky/ghostrefs/blob/master/docs/pages/contributing.rst)
to build the searchable HTML documentation locally, and the
[publishing guide](https://github.com/milssky/ghostrefs/blob/master/docs/pages/publishing.rst)
to build and release the PyPI distributions.

