kevmoo/analytica.dart/dart-undead

Dart Undead (dart-undead)

Deterministic reachability and dead/unused declaration analysis for Dart and Flutter packages using pkg:undead.

1. When to Use This Skill

Use this skill when auditing codebase health, trimming dead weight from mature packages, identifying orphaned internal abstractions, or cleaning up standalone applications and CLI tools.

Unlike basic lexical lints (unused_element, unused_field) which only detect unused file-private (_) identifiers, undead builds a whole-package reachability graph from designated entrypoint roots down to all internal declarations.

Trigger Indicators

• Orphaned Internal Utilities: Functions, classes, or mixins under

lib/src/ unreachable from public API barrels or internal entrypoints.

• Dead Application Features: Unreachable views, controllers, or services in

standalone CLI tools or Flutter apps.

• Orphaned Test Fixtures: Dead Fake* or Mock* fixtures left behind after

features were refactored.

• Pre-Release API Pruning: Verifying whether newly introduced experimental

helpers are actually wired up before public release.

When NOT to Use

• Single-File Private Lints: Rely on standard dart analyze for simple

local variable or private parameter lints.

• Code Formatting or Lint Rules: Use standard dart format or dart fix.
• Non-Dart / Non-Flutter Projects: Tool exclusively operates on Dart ASTs.

2. Automated Execution & Scope Resolution

Execute the official package CLI directly in the terminal to retrieve reachability findings deterministically:

dart run undead@^0.1.2 [options] [target_path]

[!NOTE]

Pre-Flight Package Resolution Gate: package:analyzer requires

.dart_tool/package_config.json to resolve package:<name>/... imports. If

packages are unresolved, pass --pub-get to automatically run dart pub get

or flutter pub get. If encountering .dart_tool atomic rename errors in

sandboxed environments, pass --no-precompile (e.g.

dart run --no-precompile undead@^0.1.2).

Execution Modes

Mode 1: Library Package (Default / Open-World)

Preserves all non-src lib/** exports as public API roots. Analyzes whether internal declarations (lib/src/**) are reachable from exported barrels or tests:

# Markdown output for human review
dart run undead@^0.1.2
 
# Machine-readable JSON output for agent automation
dart run undead@^0.1.2 --format=json

Mode 2: Closed Application (--mode=closed-app)

Traces execution strictly from executable entrypoints (bin/**, lib/main.dart, lib/main_*.dart). Treats unreferenced public declarations as dead:

dart run undead@^0.1.2 --mode=closed-app

Mode 3: Example Code Handling (--example-mode)

Controls how code in example/ is treated during reachability analysis:

• demonstration (Default): example/ code is treated as a consumer root;

example files are never suggested for deletion.

• strict: Analyzes reachability within example/ itself.
• skip: Ignores example/ completely during analysis.

dart run undead@^0.1.2 --example-mode=demonstration

Common CLI Options Reference

3. Critical Safety Guardrails & Deletion Invariants

[!CAUTION]

Audit Before Deleting: Never delete declarations autonomously without

reviewing safety invariants and verifying against the test suite.

Invariant 1: Sealed Class Hierarchy Protection

Direct subtypes of live sealed classes (via extends, implements, with, or enum) must NEVER be deleted, even if unreferenced elsewhere. Deleting a sealed subtype breaks Dart 3 exhaustive pattern matching across all switch expressions.

Invariant 2: Co-Invoked Test Hazard Protection

When a test file invokes both live and dead declarations:

• Isolated Dead Tests: Test blocks referencing _only_ dead code can be

safely pruned alongside the dead target.

• Co-Invoked Test Hazard: When a single test function or widget test

exercises both live and dead code, do not delete the test. Refactor the test body to remove only the dead assertions.

Invariant 3: Framework Entrypoints & Pragmas

Ensure framework-specific roots are not falsely classified as dead:

• Build Runner: Builder factories and generator entrypoints in build.yaml.
• VM Entrypoints: Declarations annotated with @pragma('vm:entry-point').
• JS Interop: External JavaScript facades (@JS()). Pass

--ignore-external-bindings if pruning libraries with public interop headers.

Invariant 4: Custom Suppression Syntax

To suppress intentional dead code or API placeholders without deleting:

• Declaration Level: // undead:ignore (directly above the declaration; see

Placement Rules below).

• File Level: // undead:ignore_for_file (below the copyright header; see

Placement Rules below).

• _(Note: The standard // ignore: unreachable_from_main is strictly for the

built-in Dart analyzer lint rule; pkg:undead requires // undead:ignore)._

Placement Rules (violations fail dart analyze --fatal-infos or style review):

• File-level: Insert // undead:ignore_for_file below any copyright /

license header block and above the library directive or first import. Never place it on line 1 above the copyright notice.

• Declaration-level: Never insert // undead:ignore between an existing

// ignore: <lint> comment and its declaration. The analyzer only honors an // ignore: comment on the line immediately preceding the declaration, so detaching it produces unnecessary_ignore plus the original diagnostic (e.g. unreachable_from_main). Place // undead:ignore above the // ignore: line:

``dart // undead:ignore // ignore: unreachable_from_main Future<void> runTests(List<String> args) async { ... } ``

Invariant 5: Dynamic Invocation & Non-AST Reference Check

Static AST analysis (pkg:undead) only traces typed Dart import trees. It cannot see declarations referenced through runtime meta-programming:

• Dynamic isolate spawners (dart.runInIsolate, Isolate.spawnUri)
• Code-generation string templates ('''import "package:.../foo.dart";''')
• JS / WASM compilation targets and runtime asset bootstrap runners
• Build hooks and build.yaml references
• Framework extension hooks and plugin registries invoked by downstream runners

rather than by in-package call sites

Dynamic-Entrypoint Heuristics (Require Confirmation, Never Blind Delete):

Treat a zero-reference finding as a _suspected_ runtime entrypoint, not dead code, when it matches any of these patterns. Classify it as KEEP (protect with // undead:ignore) unless the user explicitly confirms removal:

• File names: *_run.dart, direct_run.dart, *_bootstrap.dart,

*_listener.dart, *_hook.dart, *_plugin.dart.

• Declaration names: register*, initialize*, bootstrap*, plugin*,

custom*, install*, configure* (e.g. registerReporter).

• Shape: public top-level functions whose only parameters are callbacks or

factories, accepting a string key (registerX(String name, Factory f)), or that spawn isolates / compile kernels / open ports.

• Context: packages consumed as frameworks (test runners, build systems,

plugin hosts) where downstream packages are the real callers.

The Pre-Deletion Check Protocol:

1. Before deleting any candidate file or top-level declaration in lib/src/,

perform a literal string search (grep_search "<filename_or_symbol>") across the repository.

1. If text matches exist outside the target file itself, **inspect and

understand the match context** before deleting:

• KEEP: The match is an active runtime string template, dynamic isolate

entrypoint, or compilation target. Protect it with // undead:ignore.

• PRUNE: The match is merely a doc comment, obsolete README reference, or

dead test fixture that should be deleted alongside the target.

Invariant 6: Monorepo & External Entrypoint Protection

In multi-package workspaces where internal implementation libraries export entrypoints consumed by sibling CLI wrappers or test runners:

• Include sibling packages and root integration test folders using

--extra-roots or enable --workspace-discovery.

• If an unexported function is an intended external entrypoint, protect it with

// undead:ignore (and // ignore: unreachable_from_main if analyzer lint is active, ordered per the Invariant 4 Placement Rules).

Invariant 7: Cohesive Subsystem Pruning

When pruning dead code, avoid partial or purely cosmetic deletions that leave larger unreferenced subsystems intact:

• Delete all verified unreferenced internal classes, functions, and files in

lib/src/ (e.g., unreferenced listener classes, unused event sinks, obsolete scaffold runners) in one cohesive pass.

• Remove orphaned imports, associated dead private helpers, and obsolete test

fixtures concurrently.

Invariant 8: Deletion Hygiene (Comments Travel With Declarations)

A deletion range must cover the entire declaration, including everything attached above it, so that nothing is left orphaned:

• Doc comments: Remove the full preceding /// block (and any /** */

block). An orphaned block at file head (before library / import directives) triggers dangling_library_doc_comments under dart analyze --fatal-infos, but an orphan stranded between surviving declarations produces no diagnostic at all and silently re-attaches to the next declaration — only a diff review catches it.

• Annotations and `// ignore:` comments: Remove @Deprecated(...),

@visibleForTesting, and any // ignore: <lint> lines that belonged to the deleted declaration; a leftover // ignore: triggers unnecessary_ignore.

• Ignore comments on surviving neighbors: When deleting one of several

adjacent declarations, do not leave two // ignore: lines stacked on the survivor (unnecessary_ignore / duplicate_ignore).

• Blank lines: Collapse the resulting double blank line so dart format

reports no changes.

4. The 2-Stage Triage & Confirmation Protocol