Commands analyze

analyze: static analysis

The analyze command is the static-analysis engine of the SPM toolchain. It performs deep AST (Abstract Syntax Tree) inspection of Flutter projects to find every State subclass and extract rich performance-related metrics from their build methods.

These metrics are the foundation for identifying "heavy" widgets that may benefit from optimization, refactoring, or targeted profiling. Its output is also the manifest consumed by inject and run.

Usage

spm analyze --output results.jsonl /path/to/flutter/project
spm analyze -o results.jsonl /path/to/project1 /path/to/project2
spm analyze -v -o results.jsonl /path/to/project   # verbose

Options and flags

Flag / Option	Short	Description
--output <path>	-o	Required. Output JSONL file path.
--verbose	-v	Print per-instance progress to stderr.
<dir> [dir…]		One or more Flutter project roots to analyze.

On completion it prints a summary to stdout:

Scanned 142 files (3 skipped with compile errors); found 31 State subclasses; kept 31 rows.

How it works

1. Resolved AST analysis. SPM uses the analyzer package to resolve each Dart compilation unit. Files with error-level diagnostics are skipped and reported in the summary.
2. State-class discovery. StateClassVisitor identifies every Flutter State<T> subclass and locates its build method.
3. Build-tree extraction. TreeExtractor follows non-const custom widgets transitively, including the State build of custom StatefulWidget children and declarations in part files.
4. Metric collection. BuildMetricsVisitor records widgets, helper references, iterations, allocations, list strategy, and layout-dependent builders. Widget-returning helper bodies are resolved transitively, and the AST complexity extension computes build and helper decision points.
5. Normalization and streaming. Metrics are aggregated into an AnalysisResultModel and emitted as one JSONL row per discovered State subclass, followed internally by a summary event.

Output

One JSON object per line, one line per State subclass. See Output Formats for the full field reference and an example record, and Extracted Features for the precise definition of each metric.

Why run analysis?

• Inventory generation. Automatically find all stateful logic in a large codebase.
• Performance auditing. Surface "hotspots" by filtering for high widget counts or nesting depth.
• Refactoring guide. Locate components that lean on many helper methods; they are prime candidates for extraction into dedicated StatelessWidgets.
• Injection preparation. The output is the manifest that inject and run use to decide where to instrument profiling code.

Best practices

• Targeted scans. Running analyze on specific feature directories keeps result analysis more manageable than scanning an entire project at once.
• JSONL tooling. Process the output with jq or Python to generate reports and visualizations of your project's UI complexity.