From 5063cecf753cdd86d4c6b9879a82e032ae81196c Mon Sep 17 00:00:00 2001 From: yumakakuya Date: Mon, 18 May 2026 17:36:26 +0900 Subject: [PATCH] Update README positioning --- README.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 49 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 7082861..b799344 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,35 @@ # Distil. -Fast dead-code scanner for Java and Spring projects. +Find the code your Java project forgot about. -Distil. is a read-only CLI static analysis tool that reports likely dead code with confidence scores. It is designed to help humans and coding agents review cleanup candidates before making source changes. +Distil. is a read-only scanner for Java and Spring codebases that reports likely dead code, unwired features, and suspicious public APIs with no in-project callers. + +It does not delete code or prove that removal is safe. Instead, it gives developers and coding agents high-signal review candidates before they make source changes. + +Use Distil. when you want to: + +- Find dead code before it becomes maintenance debt. +- Spot public methods and constructors that no code path appears to call. +- Investigate features that look implemented but may not be wired into runtime behavior. +- Review cleanup candidates with confidence scores instead of guessing from text search. + +## Why Distil. + +Most codebases have more dead paths than teams realize. Some are safe cleanup candidates. Others are more interesting: half-connected features, stale diagnostics, forgotten API surfaces, or code that explains why a system behaves differently from the way the source appears to promise. + +Distil. is built for that review loop. It is not a deletion engine. It is a precision-first signal generator for humans and agents that need to understand where Java code has drifted away from actual use. + +## Real-World Signal + +Distil. has been tested on internal Java tools, including framework-heavy and agent-facing codebases. + +In one recent validation pass, Distil. scanned 117 Java files across two real projects and produced 32 review candidates. One small candidate set led directly to an unwired diagnostic path behind a real tool-visibility bug. + +That is the intended shape of the tool: low-noise findings that help reviewers find both cleanup opportunities and suspicious disconnected code paths. ## Current Status -Distil. is in pre-release development. Treat its findings as review candidates, not as automatic deletion instructions. +Distil. is in pre-release development. Treat findings as review candidates, not deletion instructions. | Area | Status | |------|--------| @@ -16,6 +39,8 @@ Distil. is in pre-release development. Treat its findings as review candidates, | Output formats | Terminal, JSON, SARIF | | Distribution | Source build only until release binaries are published | +Official release binaries are not yet published. For now, install from source. + ## What It Detects | Layer | Detects | @@ -27,6 +52,24 @@ Distil. is in pre-release development. Treat its findings as review candidates, Distil. prefers precision over recall. When confidence is too low, it should stay silent rather than produce noisy findings. +Example finding: + +```text +L3 95% src/main/java/com/example/TaskContextFilter.java:58 + com.example.TaskContextFilter#getCurrentContext() + Public method with zero project-wide calls. +``` + +The right next step is review, not blind deletion. This kind of signal may be a cleanup candidate, a missing integration point, or a diagnostic surface that should be wired into an error path. + +## Where It Helps + +- Cleanup reviews before a refactor. +- Agent-assisted coding reviews where you need compact, high-signal evidence. +- Spring application maintenance, where entry points and framework callbacks can make naive dead-code checks noisy. +- Debugging investigations where a method exists but no project code appears to call it. +- CI or release checks that should report suspicious code without mutating files. + ## Framework Awareness Distil. recognizes common Java framework patterns that often confuse simple dead-code scanners, including: @@ -46,7 +89,7 @@ Framework awareness reduces false positives, but it does not make deletion risk Distil. is detect-only. -It does not: +It never: - Delete files. - Edit source code. @@ -155,7 +198,8 @@ See [docs/user/configuration.md](docs/user/configuration.md) for details. ## Known Limitations - Findings are cleanup candidates, not proof that deletion is safe. -- Dynamic framework behavior, reflection, generated code, and custom dependency injection can hide live code. +- Public APIs may be used by external callers that are not visible inside the scanned repository. +- Reflection, dynamic dispatch, generated code, and custom dependency injection can hide live code. - Gradle parsing is based on common declaration patterns and may miss custom configurations or version catalogs. - Multi-module Maven support follows declared modules; unusual reactor setups may need manual review. - Java is the only supported language in the current release line.