Home

Scope Performance Metrics (SPM)

SPM is a Dart CLI and Flutter package for measuring rebuild scopes. It finds State classes, consumer widgets, and state-management builder callbacks, then records static build-tree features for each scope as JSONL. It can also instrument State classes and collect runtime measurements from a profile-mode Flutter process.

The package installs an spm executable. Flutter code that SPM instruments uses the public package:spm/spm.dart API.

Package page: pub.dev/packages/spm

Commands in the workflow

Static analysis produces the manifest consumed by injection and profiling:

flowchart LR
    analyze([analyze]) --> results[results.jsonl]
    results --> inject([inject])
    inject --> source[instrumented source]
    source --> run([run])
    run --> profiler[profiler.jsonl]
    results -. "run injects and launches in one step" .-> run

    isolate([isolate]) --> widgets[standalone widgets]
    widgets --> map[diagnostics in map.jsonl]
    validate([validate]) --> gate[structural mutation gate]

Loading

Command	What it does
analyze	Finds rebuild scopes and emits static build-tree metrics as JSONL.
inject	Changes matching State classes to use SpmState, or removes those changes.
run	Injects, launches Flutter in profile mode, and collects profiler events.
isolate	Extracts rebuild scopes into smaller Dart files for targeted profiling.
validate	Rejects widget mutations that change more than widget-tree structure.

Choose a page

• Follow Getting Started for installation and a first run.
• Use the command pages when you need flags, defaults, or operational details.
• Read Extracted Features for the metrics emitted by analyze.
• Read Output Formats before consuming either JSONL stream.
• See Architecture for module boundaries and data flow.
• See Development and Contributing before changing the code.

Package facts

Language	Dart 3.9.2 or newer; Flutter 3.3 or newer
Architecture	Feature modules with data/, domain/, and presentation/ layers
Error handling	Either<Failure, T> in data and domain layers
Output	JSON Lines, one record per line
Public API	package:spm/spm.dart
CLI entry point	bin/spm.dart → lib/src/runner.dart