The highest tagged major version is
README
¶
deadset
One command for dead code across Go and TypeScript, resolving the references that cross the language boundary.
What it does
Dead code is a declaration nothing reaches: a function nobody calls, an export nothing imports, a file no build includes, a dependency no import needs. Each language has its own analyzer for that question. deadset is the command you run when a repository holds more than one language, and it does four things:
- Detects which languages the repository contains, and runs only the analyzers for those. A repository with one language never needs the other language's toolchain.
- Runs each analyzer as a separate process.
deadsetcontains no parser and no type checker of its own; every finding comes from an analyzer. - Resolves the references that cross the language boundary. A Go type consumed only through the TypeScript client generated from it has no reference in Go and no declaration in TypeScript, so each analyzer alone would judge it wrong.
deadsetreads both reports, follows the declared edge between the two symbols, and reports the pair as dead only when both sides are. - Merges the reports into one and returns one exit code, so a CI step reads one result.
The analyzers are complete programs on their own. deadset-go analyzes a Go module and deadset-ts analyzes a TypeScript or JavaScript package, each from parsing to exit code. Running one directly produces the same findings as running it through deadset, so this command is never a required hop; it earns its place when there is a language boundary to resolve.
Every analyzer implements the same contract, published at deadset-spec: one vocabulary of issue kinds, one report schema, one suppression grammar, one exit-code table and one merge definition. Any analyzer that passes that repository's conformance corpus can be listed in deadset's provider list, including one written by someone else for a language neither first-party analyzer covers.
Status
Pre-release. This build implements contract version 3.0.0 and answers deadset version and deadset print-config, which prints the resolved configuration and where each value came from; every other command is reserved and exits with a usage message.
Quick start
go install github.com/cplieger/deadset/cmd/deadset@latest
deadset version
Go 1.27 or later is required to install from source. The binary is static and needs no C toolchain.
Security
deadset performs no network request during analysis. It executes only analyzers already installed on the local filesystem, at the path its provider list names, and exits with an error rather than fetching one that is missing. It is report-only: no command edits a source file, and any request for one is refused with exit code 2.
Dependencies
The binary uses the standard library only. The test suite requires deadset-spec, whose Contract files it checks the binary against. The analyzers it runs are separate programs with their own releases.
Contributing
Issues and pull requests are welcome. The general guidelines live in cplieger/.github.
Disclaimer
This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.
This project was built with AI-assisted tooling using Claude, GPT, and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.
License
GPL-3.0-or-later. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
deadset
command
Command deadset is the front door of the deadset dead-code toolkit.
|
Command deadset is the front door of the deadset dead-code toolkit. |
|
internal
|
|
|
config
Package config resolves the deadset configuration for the orchestrator.
|
Package config resolves the deadset configuration for the orchestrator. |
|
detect
Package detect decides which languages a target holds, from the names of its files alone.
|
Package detect decides which languages a target holds, from the names of its files alone. |
|
invoke
Package invoke runs an analyzer's analyze verb as a separate process and reads the report the analyzer writes to the file the invocation names.
|
Package invoke runs an analyzer's analyze verb as a separate process and reads the report the analyzer writes to the file the invocation names. |
|
merge
Package merge combines the reports analyzers wrote over one target into one merged report, by the algorithm contract/grammar/merge.md states.
|
Package merge combines the reports analyzers wrote over one target into one merged report, by the algorithm contract/grammar/merge.md states. |
|
report
Package report is the deadset report document as Go values: the envelope one analyzer writes over one analysis, the envelope a merge writes over several, and the finding both carry.
|
Package report is the deadset report document as Go values: the envelope one analyzer writes over one analysis, the envelope a merge writes over several, and the finding both carry. |
|
rundir
Package rundir lays out the run directory: the evidence for every exit code the orchestrator returns.
|
Package rundir lays out the run directory: the evidence for every exit code the orchestrator returns. |
|
summary
Package summary renders what a run prints about its merged report beside the report itself: the analyzers the merge read, one summary line over every language the run covered, and one workflow annotation per finding and per stale suppression.
|
Package summary renders what a run prints about its merged report beside the report itself: the analyzers the merge read, one summary line over every language the run covered, and one workflow annotation per finding and per stale suppression. |
|
verdict
Package verdict is the Contract's exit-code table: the code a run returns, read from the report the run produced or from the error that ended it before a report existed.
|
Package verdict is the Contract's exit-code table: the code a run returns, read from the report the run produced or from the error that ended it before a report existed. |