DEV Community: Lucas Menezes

Código morto em Flutter é mais do que um warning do analyzer

Lucas Menezes — Tue, 03 Nov 2026 23:07:00 +0000

Encontrar um warning unused_element é fácil. Decidir se um arquivo pode ser apagado com segurança não é.

Aplicações Flutter possuem várias formas legítimas de usar código sem uma referência direta óbvia: registries gerados, tabelas de rotas, injeção de dependências, imports condicionais, flavors, platform channels, annotations, helpers exclusivos de testes e exports públicos de packages. Uma busca que retorna zero referências é uma evidência útil, mas não é um veredito.

Essa diferença me levou a criar a flutter-dead-code-audit, uma Agent Skill open source para auditar declarações Dart sem uso e arquivos .dart potencialmente órfãos por meio de um fluxo que exige revisão antes da remoção.

▶️ Assista à demonstração curta

Repositório: github.com/LucasMenezeslc/flutter-dead-code-audit

O analyzer responde apenas parte da pergunta

O analyzer do Dart é excelente para encontrar problemas locais como:

imports sem uso;
campos e métodos privados sem uso;
branches inalcançáveis;
variáveis locais sem uso;
expressões redundantes.

Mas uma limpeza de repositório também precisa responder perguntas mais amplas:

O arquivo é alcançável por algum entrypoint suportado?
O símbolo chega ao consumidor por um barrel export?
Ele é registrado por injeção de dependências?
É carregado apenas em uma plataforma ou flavor?
Faz parte de uma API pública consumida fora do repositório?
É gerado ou pertence a um generator?
Foi mantido intencionalmente por compatibilidade ou rollback?

Uma ferramenta que ignora essas perguntas pode produzir um relatório convincente e ainda recomendar a remoção errada.

Estado write-only é um bom exemplo

Considere um campo que recebe valores em diferentes callbacks, mas nunca é lido:

bool _hasPlayed = false;

void onStarted() {
  _hasPlayed = true;
}

void onStopped() {
  _hasPlayed = false;
}

Mecanicamente, o campo é write-only. Remover apenas a declaração não basta; todas as atribuições também precisam ser removidas para o código continuar compilando.

Existe, porém, uma pergunta de produto mais importante: o campo foi abandonado ou faltou uma leitura que deveria controlar replay, analytics, persistência ou estado visual?

Portanto, a conclusão correta não é automaticamente “cleanup seguro”. Ela pode ser:

O campo é write-only no código atual, mas a intenção de produto ainda não foi resolvida.

Por isso o fluxo separa evidência mecânica de decisão humana.

Um fluxo orientado à revisão

A skill trabalha em quatro etapas:

1. Audit

O modo Audit é somente leitura. Os scripts combinam:

diagnósticos do analyzer em formato legível por máquina;
reachability determinística de imports, exports e arquivos part;
buscas de símbolos e strings em todo o repositório;
verificações de rotas, DI, codegen, plataformas, flavors, testes e APIs públicas.

O resultado é uma lista de candidatos, não uma lista automática de exclusão.

2. Review

Os candidatos são apresentados em grupos pequenos. Cada um recebe uma decisão:

remove — evidência e contexto sustentam a remoção;
retain — manter intencionalmente e registrar o motivo;
defer — ainda faltam evidências ou contexto do time.

Código mantido continua visível em relatórios futuros. Ele não é silenciosamente ignorado, evitando que a mesma investigação seja repetida alguns meses depois.

3. Cleanup

O Cleanup só pode alterar candidatos explicitamente aprovados como remove. As mudanças são aplicadas em lotes pequenos e seguidas por analyzer e testes.

4. Tests

Depois da limpeza, o relatório sugere verificações de comportamento com base na área afetada. A remoção de um campo de playback, por exemplo, deve gerar um checklist do fluxo de reprodução — não apenas um analyzer verde.

Correção estática é necessária, mas não prova que o comportamento suportado foi preservado.

Evidência em vez de confiança aparente

Um candidato de alta confiança normalmente precisa de pelo menos dois sinais independentes e de verificações de falso positivo concluídas.

A hierarquia de evidências utilizada é:

diagnóstico do analyzer ou compilador;
reachability por imports, exports e part;
buscas de símbolos e strings no repositório;
inspeção de registros em runtime e mecanismos do framework;
testes ou builds após uma remoção aprovada.

Quando os sinais entram em conflito, a confiança diminui. O fluxo não esconde o conflito atrás de uma média.

Relatórios feitos para decidir

Listas enormes são difíceis de revisar. Por isso, os resultados são agrupados em:

Ready for review — evidência forte e nenhum consumidor dinâmico plausível;
Review carefully — provável código morto em uma fronteira sensível;
Needs team context — a intenção não pode ser determinada pelo repositório;
Potential logic issue — pode revelar um bug em vez de cleanup;
Intentionally retained — mantido com motivo documentado;
Not dead / excluded — investigado e confirmado como ativo ou protegido.

Cada candidato preserva localização, evidências, verificações, confiança, risco, recomendação e comando de validação. A visão executiva permanece compacta, enquanto os detalhes ficam disponíveis quando necessários.

Instalação

Na raiz de um projeto Flutter ou Dart:

npx skills add LucasMenezeslc/flutter-dead-code-audit

Depois, comece com uma solicitação somente leitura:

Use $flutter-dead-code-audit em modo Audit neste projeto.
Não modifique arquivos. Gere um relatório e apresente o primeiro grupo para revisão.

Os scripts exigem Python 3.10 ou superior e utilizam apenas a biblioteca padrão. O Dart pode vir do PATH ou do FVM. A saída utiliza caminhos relativos para não expor o diretório absoluto do projeto nos relatórios.

Limites atuais

A skill ainda não audita:

código duplicado;
assets ou traduções sem uso;
dependências sem uso no pubspec.yaml;
performance ou segurança da aplicação.

Ela também não instala ferramentas no projeto, não altera regras do analyzer e não remove arquivos gerados diretamente durante uma auditoria.

Sugestões e contribuições são bem-vindas

O projeto usa licença MIT e está aberto a contribuições. O feedback mais útil é um exemplo Flutter ou Dart pequeno e reproduzível que revele um falso positivo, um falso negativo ou uma forma de uso dinâmico ainda não modelada.

Se você já encontrou código aparentemente morto escondido por rotas, injeção de dependências, codegen, imports condicionais, implementações de plataforma ou exports públicos, quero conhecer esse caso.

Repositório: flutter-dead-code-audit

Dead Code in Flutter Is More Than an Analyzer Warning

Lucas Menezes — Tue, 03 Nov 2026 23:07:00 +0000

Finding an unused_element warning is easy. Deciding whether a file is safe to delete is not.

Flutter applications have several legitimate ways to use code without an obvious direct reference: generated registries, route tables, dependency injection, conditional imports, flavors, platform channels, annotations, test-only helpers, and public package exports. A search that returns zero references is useful evidence, but it is not a verdict.

That distinction led me to build flutter-dead-code-audit, an open-source Agent Skill for auditing unused Dart declarations and potentially orphaned .dart files through a review-first workflow.

▶️ Watch the short demo

Repository: github.com/LucasMenezeslc/flutter-dead-code-audit

The analyzer answers only part of the question

The Dart analyzer is excellent at detecting local issues such as:

unused imports;
unused private fields and methods;
unreachable branches;
unused local variables;
redundant expressions.

But repository cleanup also involves broader questions:

Is this file reachable from a supported entrypoint?
Is the symbol referenced through a barrel export?
Is it registered by dependency injection?
Is it loaded only for one platform or flavor?
Is it a public API consumed outside the repository?
Is it generated or owned by a generator?
Is it intentionally retained for compatibility or rollback?

A tool that ignores these questions may produce a convincing report and still recommend the wrong deletion.

Write-only state is a good example

Consider a field that is assigned in several lifecycle callbacks but never read:

bool _hasPlayed = false;

void onStarted() {
  _hasPlayed = true;
}

void onStopped() {
  _hasPlayed = false;
}

Mechanically, the field is write-only. Removing the declaration alone is not enough; every assignment must also be removed for the code to compile.

However, there is a more important product question: was the field abandoned, or was a missing read supposed to control replay, analytics, persistence, or UI state?

The correct finding is therefore not automatically “safe cleanup.” It may be:

The field is write-only in the current code, but product intent is unresolved.

That is why the workflow separates mechanical evidence from human decisions.

A review-first workflow

The skill uses four stages:

1. Audit

Audit mode is read-only. The bundled scripts combine:

machine-readable Dart analyzer diagnostics;
deterministic import, export, and part reachability;
repository-wide symbol and string searches;
checks for routes, DI, code generation, platforms, flavors, tests, and public APIs.

The result is a list of candidates, not an automatic deletion list.

2. Review

Candidates are presented in small groups. Each receives one of three decisions:

remove — evidence and context support removal;
retain — keep intentionally and record the reason;
defer — more evidence or team context is required.

Retained code remains visible in later reports. It is not silently ignored, which prevents the same investigation from being repeated every few months.

3. Cleanup

Cleanup is allowed only for candidates explicitly approved as remove. Removals are applied in small batches, followed by analyzer and test verification.

4. Tests

After cleanup, the report suggests behavior-oriented checks based on the affected area. Removing a playback field, for example, should result in a playback test checklist rather than only a green static analyzer result.

Static correctness is necessary, but it does not prove that supported behavior survived.

Evidence instead of confidence theater

A high-confidence finding should normally have at least two independent signals and cleared false-positive checks.

The evidence hierarchy used by the skill is:

analyzer or compiler diagnostics;
import/export/part reachability;
repository-wide symbol and string searches;
runtime registration and framework-specific inspection;
tests or builds after an approved removal.

When signals conflict, confidence goes down. The workflow does not average the conflict away.

Reports designed for decisions

Large raw lists are difficult to review. The report therefore groups findings into:

Ready for review — strong evidence and no plausible dynamic consumer;
Review carefully — likely unused but located at a sensitive boundary;
Needs team context — intent cannot be established from the repository;
Potential logic issue — may reveal a bug rather than cleanup;
Intentionally retained — kept with a documented reason;
Not dead / excluded — investigated and shown to be live or protected.

Every candidate preserves its location, evidence, checks, confidence, risk, recommendation, and verification command. The executive view stays compact while detailed evidence remains available when needed.

Installation

From the root of a Flutter or Dart project:

npx skills add LucasMenezeslc/flutter-dead-code-audit

Then start with a read-only request:

Use $flutter-dead-code-audit in Audit mode on this project.
Do not modify files. Create a report and present the first review group.

The scripts require Python 3.10 or newer and use only the Python standard library. Dart can come from PATH or FVM. Script output uses relative paths so reports do not expose the absolute project directory.

Current boundaries

The skill does not currently audit:

duplicate code;
unused assets or localization resources;
unused dependencies in pubspec.yaml;
application performance or security.

It also does not install project tooling, rewrite analyzer rules, or hand-delete generated files during an audit.

Feedback is welcome

The project is MIT licensed and open to contributions. The most useful feedback is a small reproducible Flutter or Dart example that exposes a false positive, a false negative, or a dynamic usage pattern that is not yet modeled.

If you have encountered dead code hidden behind routing, dependency injection, code generation, conditional imports, platform implementations, or package exports, I would like to learn from that case.

Repository: flutter-dead-code-audit