StateScope renders XMI / UML2 .emx state-machine models as interactive
state diagrams, with a model-aware diff overlay and a no-checkout PR
review flow. It turns opaque XMI into a navigable, reviewable view —
right next to the rest of your code.
What's an .emx file? A standards-based XMI /
UML2 document that describes a state
machine. Common in regulated and embedded domains where a textual
spec isn't enough and a visual model is the source of truth.
Features
View
| Tab |
What it shows |
| Diagram |
UML state diagram. Initial-dot / final-double-circle notation. Sugiyama layered layout. Pan, zoom, fit. |
| Flow |
Per-FSM interaction view — storyboard or sequence — derived from the Config Model's parties, channels, and service participants. |
| Table |
Flat transition table — event, guard, action, target. Sortable, filterable. |
| Model |
Participants + Stereotypes view of the companion Config Model. Three-column layout, per-card filters, dead-config dimming. |
Click any state, transition, classification chip, or stereotype chip to
pin it in the property panel. Use ⌘F / Ctrl+F to search across
state names, events, actions, guards, and FSM names within the file.
Compare
- Compare with Branch / Ref… — pick any git ref. The base version is fetched without touching your working tree.
- Compare with File… — pick a second
.emx from disk.
- Auto-diff — open a file with uncommitted changes and the HEAD version loads side-by-side automatically.
- Flip direction — click the diff badge to swap base and current in place.
- Focus mode — show only changed nodes and their direct neighbours.
Modified-field detection works at three levels: structural (states,
transitions), property-level (stereotype, constraint body, guard
expression), and companion-model-level (classification description,
action pseudocode).
Review a PR — no checkout
Command Palette → StateScope: Review a PR…
- Pick the target branch (what the PR merges into).
- Pick the source branch (the PR).
- StateScope lists every
.emx the PR touches and paints A / M / D badges on them in the Explorer tree.
- Open any changed file — it renders the source-ref version with a
source → target diff overlay automatically applied.
A status-bar item shows the active review and your local working copy
stays untouched throughout. Click the status bar to end the review.
Companion-model intelligence
A .emx FSM typically references two companion files: a Config
Model (application-specific overlays) and a Generic Model (the
shipped data dictionary). When StateScope finds them, it enriches the
FSM with:
- Classification chips on states whose name matches a code entry.
- Action pseudocode in the property panel for transitions whose action resolves to a defined action body.
- Referenced-by lists — click a classification or action to see every FSM / state / transition that joins to it.
- Reference FSMs from the Generic Model in the FSM selector.
Discovery is automatic. Missing or unreachable companions degrade
gracefully — the FSM diagram still renders, just without the chips.
Diagnostics
Six opt-in checks publish to the Problems panel under the statescope
source. Each has its own severity setting:
| Setting |
Default |
Catches |
statescope.diagnostics.brokenHref |
error |
<importedPackage href="…"/> whose target can't be resolved. |
statescope.diagnostics.undefinedAction |
warning |
Transition action not defined in any companion. |
statescope.diagnostics.unreachableState |
warning |
States BFS can't reach from the seed set. |
statescope.diagnostics.deadConfig |
information |
Classification codes / actions in companions that no FSM references. |
statescope.diagnostics.missingDescription |
information |
Classification codes whose stereotype carries no description. |
statescope.diagnostics.undefinedClassification |
off |
State names that don't match any classification code. |
Configuration
| Setting |
Type |
Default |
Description |
statescope.actionSubtypeMap |
string |
"" |
Optional path to an action-subtype.json sidecar that maps action names to their physicalTransmissionType subtype. Relative paths resolve against the workspace root. Auto-discovery falls back to <emxFile>.action-subtype.json and .statescope/action-subtype.json at the workspace root. |
statescope.diagnostics.* |
enum |
per-rule |
See Diagnostics above. Values: error / warning / information / off. |
Commands
| Command ID |
Title |
statescope.open |
Open in StateScope |
statescope.compareWithRef |
Compare with Branch / Ref… |
statescope.compareWithFile |
Compare with File… |
statescope.clearCompare |
Clear Compare Overlay |
statescope.reviewPR |
Review a PR… |
statescope.endReview |
End PR Review |
statescope.openAtSourceRef |
Open at PR Source Ref |
Supported files
| Extension |
Format |
.emx |
XMI / UML2 state-machine model |
StateScope is a third-party viewer for an open standard. It has no
affiliation with any specific tool vendor.
Security
- CSP-locked webview. Per-load nonce on every script tag;
script-src 'nonce-…' only; no 'unsafe-eval'.
- No remote resources.
default-src 'none'; img-src and font-src restricted to webview.cspSource.
localResourceRoots scoped to media/ only.- Read-only editor. The custom editor is
CustomReadonlyEditorProvider; file contents are never written.
- Zero runtime npm dependencies. No
eval, no new Function, no innerHTML for untrusted content.
Suitable for regulated environments and air-gapped networks.
License
PolyForm Noncommercial 1.0.0 — free for personal, research,
educational, and other noncommercial use. Commercial use requires a
separate commercial license.
