Home

State Performance Metrics (SPM)

SPM is a Flutter package with a Dart CLI. It locates every State class in a Flutter project, extracts rich build-tree metrics, optionally instruments those classes by swapping in an SpmState base class, and runs the app while collecting runtime data. Everything it produces is JSONL, ready for profiling or ML pipelines.

The profiler side integrates directly with Flutter (frame timings, BuildContext, widget-tree analysis). The CLI (analyze, inject, run, isolate, validate) is available as the spm executable after dart pub global activate spm, or through dart run spm:spm from a project that depends on the package.

---

The pipeline

SPM's commands form a pipeline. Static analysis produces a manifest, injection instruments the code, and run executes the app and collects runtime measurements.

flowchart LR
    analyze([analyze]) --> results[results.jsonl]
    results --> inject([inject])
    inject --> source[instrumented source]
    source --> run([run])
    run --> profiler[profiler.jsonl]
    results -. "run does inject + launch in one step" .-> run

    isolate([isolate]) --> widgets[standalone widgets<br/>for targeted benchmarking]
    validate([validate]) --> gate["static gate:<br/>clean structural variant of the base?"]

Loading

Commands are the rounded nodes; the rectangles are the JSONL and source artifacts that flow between them.

Command	Role
analyze	Static AST analysis. Finds State subclasses and extracts build-tree metrics as JSONL.
inject	Rewrites target State classes to extends SpmState<T>, or reverts them. Modes: inject / remove.
run	Injects, launches the app, connects to the Dart VM Service, and collects profiler events as JSONL.
isolate	Transplants rebuild scopes into standalone, compilable widgets for isolated profiling.
validate	A static gate: verifies a mutation differs from its base only in widget-tree structure.

---

Start here

• Getting Started walks through requirements, installation, and a first end-to-end run.
• Architecture covers the Clean Architecture layout, the features, error handling, and dependencies.
• Extracted Features defines every metric analyze records.
• Output Formats documents the JSONL schemas produced by analyze and run.
• Development lists the build, lint, and test commands, plus the repo's testing conventions.
• Contributing covers the workflow, the PR checklist, and how to extend each feature.

---

At a glance

Language	Dart (SDK ≥ 3.9), Flutter ≥ 3.3
Architecture	Clean Architecture, with data/ → domain/ → presentation/ per feature
Error handling	Either<Failure, T> (dartz) throughout the data and domain layers
Output	JSON Lines (JSONL), one record per line
Public API	package:spm/spm.dart exports SpmState for instrumented Flutter code
CLI entry point	bin/spm.dart → lib/src/runner.dart (SpmRunner)