kareki

English | 日本語

枯木 (kareki): dead wood in Japanese — the unused branches that need pruning.

A workspace-wide dead code finder for Dart and Flutter. Unlike dart analyze, which only flags private unused declarations inside a single package, kareki resolves cross-package references across Melos / pub workspaces to surface the dead code that actually accumulates in real projects: public APIs no one calls, files nobody imports, and pub dependencies that ride along unused.

Why kareki?

	What you get
🌲	Workspace-wide. Resolves references across every package in Melos / pub workspaces — not just one.
🔓	Public APIs too. Finds the public classes, methods, and fields dart analyze ignores.
🧬	Codegen-friendly. Built-in presets for freezed, json_serializable, riverpod, auto_route, go_router, drift, hive.
🧪	test_only_used. Catches lib/ code that only its own tests still use.
📉	Baseline. Adopt on legacy code without fixing everything first — CI fails only on new findings.
🩺	Doctor. kareki doctor flags stale ignore entries, dead excludes, and orphan suppression comments.
⚙️	CI-ready. JSON output, deterministic exit codes, portable baselines.

What it finds

Rule	Detects
unused_element	Public classes / functions / methods / getters / setters / fields / top-level variables / extensions / typedefs with no caller anywhere in the workspace.
unused_file	.dart files that are not import-ed, part-ed, or export-ed from any other file.
unused_pub_dependency	Packages declared in pubspec.yaml whose imports never appear in source.
test_only_used	Public declarations under lib/ that are only referenced from test code (*_test.dart, files under test/ or integration_test/). The implementation has no production consumer — typically its tests are the only thing keeping it alive.
unused_parameter	Parameters of a function, method, or named constructor that are never referenced in the body or initializers. Covers required and public-API parameters that Dart's built-in unused_element_parameter doesn't reach.
unused_parameter_optional	Optional parameters (named or positional optional) of a function, method, or constructor that are never passed at any call site in the workspace. The public / cross-package counterpart to Dart's built-in unused_element_parameter, which only inspects private optional parameters within a single library.

Install

# pubspec.yaml
dev_dependencies:
  kareki: ^0.1.0

dart pub get

Usage

Run from the workspace root:

dart run kareki

See doc/cli.md for all options.

Adopting on an existing codebase

Don't try to delete every finding before turning on CI. Snapshot what's there, commit it, fail only on new dead code from now on:

dart run kareki --baseline .kareki-baseline.json --write-baseline

See doc/baseline.md.

Keeping the config honest

Once you start excluding files or whitelisting dependencies, the list rots — packages move, files get renamed, the excludes still pass. kareki doctor finds dead entries in your own config:

dart run kareki doctor

See doc/doctor.md.

Documentation

• CLI reference — every option, every exit code
• Configuration — kareki-config.yaml, defaults, built-in presets, custom presets, suppression, full example
• Baseline — incremental adoption
• Doctor — config-rot detection
• How it works — analysis pipeline, entry-point seeding, supported versions

License

MIT. See LICENSE.